class Como::Spec

User interface for Como.

Constants

MAP_TYPE_PRIMS
TYPE_PRIMS

Option type primitives.

Public Class Methods

check( opt = nil, &rule ) click to toggle source

Alias for Spec.checkRule.

# File lib/como.rb, line 910
def Spec.check( opt = nil, &rule ) Spec.checkRule( opt = nil, &rule ) end
checkAlso( opt, error, &check ) click to toggle source

Additional option check.

@param opt [String] Option name. @param error [String] Error string for false return values (from check). @param check [Proc] Checker proc run for the option. Either @return false or generate an exception when errors found.

# File lib/como.rb, line 937
def Spec.checkAlso( opt, error, &check )
    Opt.main.checkAlso( opt, error, &check )
end
checkRule( opt = nil, &rule ) click to toggle source

Check option combination rules.

@param opt [String] Opt name to which rules are set. If not

given, Opt.current is used.

@param rule [Proc] Rules to check.

# File lib/como.rb, line 898
def Spec.checkRule( opt = nil, &rule )
    if opt
        opt = Opt[ opt ]
    else
        opt = Opt.current
    end
    opt.setRuleCheck( &rule )
    opt.checkRule
end
command( prog, author, year, defs = [], config = {} ) click to toggle source

The primary entry point to Como. Defines the command switches and parses the command line. Performs “usage” display if “help” was selected.

@param prog [String] Program (i.e. command) name. @param author [String] Author of the program. @param year [String] Year (or dates) for program. @param defs [Array<Array>] Option definitions. @param config [Hash] Option definition's behavioral config

(changes @@config defaults).
# File lib/como.rb, line 599
def Spec.command( prog, author, year, defs = [], config = {} )
    Spec.defineCommand( prog, author, year, defs, config )
    Spec.execute
end
defineCheckHelp( prog, author, year, defs, config = {} ) click to toggle source

Alias for {Spec.command}.

NOTE: This method is deprecated and will be removed in future releases.

# File lib/como.rb, line 660
def Spec.defineCheckHelp( prog, author, year, defs, config = {} )
    Spec.command( prog, author, year, defs, config )
end
defineCommand( prog, author, year, defs, config = {} ) click to toggle source

Define options specification for command. User should perform {Spec.execute} separately.

@param prog [String] Program (i.e. command) name. @param author [String] Author of the program. @param year [String] Year (or dates) for program. @param defs [Array<Array>] Option definitions. @param config [Hash] Option definition's behavioral config

(changes @@config defaults).
# File lib/como.rb, line 639
def Spec.defineCommand( prog, author, year, defs, config = {} )

    preHookArgs = {
        :prog => prog,
        :author => author,
        :year => year,
        :defs => defs,
        :config => config,
    }

    ComoCommon.runHook( :preHook, preHookArgs )

    spec = Spec.new( author, year )
    spec.subcmd( prog, defs, config )
end
defineProgram( author, year, config = nil, &defs ) click to toggle source

Define options specification for program. User should perform {Spec.execute} separately.

@param author [String] Program author. @param year [String] Year (or dates) for program. @yield [] Subcmd definitions.

# File lib/como.rb, line 611
def Spec.defineProgram( author, year, config = nil, &defs )
    preHookArgs = {
        :author => author,
        :year => year,
        :config => config,
        :defs => defs,
    }

    ComoCommon.runHook( :preHook, preHookArgs )

    if config
        Opt.configOverlay( config )
    end

    spec = Spec.new( author, year )
    spec.instance_eval( &defs )
end
execute() click to toggle source

Perform command line options checking.

# File lib/como.rb, line 666
def Spec.execute
    Opt.main.check( ArgsParseState.new( @@argv ) )
    ComoCommon.runHook( :postHook, Opt.main )
end
mapTypeToPrims( type ) click to toggle source

Convert option types (type definitions) to option type primitives.

# File lib/como.rb, line 839
def Spec.mapTypeToPrims( type )

    prims = nil

    if type.kind_of? Symbol
        prims = MAP_TYPE_PRIMS[ type ]
        unless prims
            raise "Unknown option type: \"#{type}\"..."
        end

    elsif type.kind_of? Array
        prims = []

        # Check that type primivives are valid before taking
        # them into use.
        type.each do |t|
            if TYPE_PRIMS.index( t )
                prims.push t
            else
                raise "Unknown option type primitive: \"#{t}\"..."
            end
        end
    else
        raise "Invalid option type definition: \"#{type}\"..."
    end

    prims
end
new( author, year ) click to toggle source

Create Spec object that can handle subcmd definitions.

@param author [String] Program author. @param year [String] Year (or dates) for program.

# File lib/como.rb, line 676
def initialize( author, year )
    @author = author
    @year = year

    Spec.ArgCheck( author.class == String, "Author name is not a String" )
    Spec.ArgCheck( year.class == String, "Year is not a String" )
end
program( author, year, config = nil, &defs ) click to toggle source

Create specification for program with subcmds.

@param author [String] Program author. @param year [String] Year (or dates) for program. @yield [] Subcmd definitions.

# File lib/como.rb, line 583
def Spec.program( author, year, config = nil, &defs )
    Spec.defineProgram( author, year, config, &defs )
    Spec.execute
end
setArgv( newArgv ) click to toggle source

Set command line options source, i.e. @@argv (default: ARGV).

# File lib/como.rb, line 872
def Spec.setArgv( newArgv )
    @@argv = newArgv
end
setUsageFooter( str ) click to toggle source

Set optional footer for “usage”.

# File lib/como.rb, line 888
def Spec.setUsageFooter( str )
    Opt.main.setUsageFooter( str )
end
setUsageHeader( str ) click to toggle source

Set optional header for “usage”.

# File lib/como.rb, line 882
def Spec.setUsageHeader( str )
    Opt.main.setUsageHeader( str )
end
specify( subcmd, table ) click to toggle source

Check/fix options specs and create option objects for the whole table.

@param subcmd [Opt] Subcommand target. @param table [Array<Array>] Option definition table for subcommand.

# File lib/como.rb, line 732
def Spec.specify( subcmd, table )

    options = {}
    subcmds = {}

    # Type checks for valid user input.
    Spec.ArgCheck( table.class == Array, "Option table is not an Array" )

    table.each do |e|
        os = Spec.specifyOptOrSub( e )
        case os.type
        when :subcmd; subcmds[ os.name ] = os
        else options[ os.name ] = os
        end
    end

    subcmd.setOptionSubcmd( options.values, subcmds.values )
    subcmd
end
specifyOptOrSub( opt_or_sub ) click to toggle source

Check/fix options specs and create option objects for the whole table.

@param opt_or_sub [Array<Array>] Option definition table.

# File lib/como.rb, line 758
def Spec.specifyOptOrSub( opt_or_sub )

    # Fix the table entries if needed.

    Spec.ArgCheck( opt_or_sub.class == Array, "Option table entry is not an Array" )

    if opt_or_sub[0] == :default && opt_or_sub.length == 2

        # Add 2 dummy entries for :default type if needed.
        opt_or_sub = [ opt_or_sub[0], nil, nil, opt_or_sub[1] ]

    elsif opt_or_sub[0] == :subcmd && opt_or_sub.length == 3

        # Add 1 dummy entry for :subcmd type if needed.
        opt_or_sub = [ opt_or_sub[0], opt_or_sub[1], nil, opt_or_sub[2] ]

    end

    Spec.ArgCheck( opt_or_sub.length == 4,
        "Option table entry length not 4" )

    if opt_or_sub[0] == :subcmd

        Opt.subcmd( opt_or_sub[1], opt_or_sub[3] )

    else

        types = Spec.mapTypeToPrims( opt_or_sub[0] )

        if types.index( :default )
            Opt.defaultOpt( opt_or_sub[3] )
        else
            Opt.full( opt_or_sub[1],
                      opt_or_sub[2],
                      Spec.mapTypeToPrims( opt_or_sub[0] ),
                      opt_or_sub[3] )
        end

    end

end
usage() click to toggle source

Display program usage (and optionally exit).

# File lib/como.rb, line 877
def Spec.usage
    Opt.main.usage
end

Private Class Methods

ArgCheck( cond, str ) click to toggle source

Argument checking assertion.

# File lib/como.rb, line 945
def Spec.ArgCheck( cond, str )
    raise( ArgumentError, str ) unless cond
end

Public Instance Methods

check( opt = nil, &rule )

Alias for checkRule

Alias for: checkRule
checkRule( opt = nil, &rule ) click to toggle source

Check option combination rules.

@param opt [String] Opt name to which rules are set. If not

given, Opt.current is used.

@param rule [Proc] Rules to check.

# File lib/como.rb, line 917
def checkRule( opt = nil, &rule )
    if opt
        opt = Opt[ opt ]
    else
        opt = Opt.current
    end
    opt.setRuleCheck( &rule )
end
Also aliased as: check
command( cmd, defs = [], config = {} )

Alias to subcmd to highlight the main command.

Alias for: subcmd
subcmd( cmd, defs = [], config = {} ) click to toggle source

Define subcommand options.

@param cmd [String] Subcmd name. @param defs [Array<Array>] Option definition table. @param config [] Configuration options.

# File lib/como.rb, line 690
def subcmd( cmd, defs = [], config = {} )

    unless Opt.main

        main = MainOpt.new( @author, @year,
            cmd, nil, :subcmd, nil )
        Opt.setMain( main )
        subcmd = main

    else

        subcmd = Opt.findOpt( cmd )

        Opt.setSubcmd( subcmd )

        Spec.ArgCheck( false, "Subcommand \"#{cmd}\" not defined." ) unless subcmd

    end

    # Overlay user config on top of default.
    subcmd.applyConfig( config )

    if subcmd.config[ :autohelp ]
        # Automatically add the help option and make it also mutex.
        spec = MAP_TYPE_PRIMS[ :silent ] + [ :mutex ]
        defs.insert( 0, [ spec, "help", "-h", "Display usage info." ] )
    end

    Spec.specify( subcmd, defs )

end
Also aliased as: command