class Como::Spec
User interface for Como
.
Constants
- MAP_TYPE_PRIMS
- TYPE_PRIMS
Option type primitives.
Public Class Methods
Alias for Spec.checkRule
.
# File lib/como.rb, line 910 def Spec.check( opt = nil, &rule ) Spec.checkRule( opt = nil, &rule ) end
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
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
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
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
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
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
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
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
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
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
Set command line options source, i.e. @@argv (default: ARGV).
# File lib/como.rb, line 872 def Spec.setArgv( newArgv ) @@argv = newArgv end
Set optional header for “usage”.
# File lib/como.rb, line 882 def Spec.setUsageHeader( str ) Opt.main.setUsageHeader( str ) end
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
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
Display program usage (and optionally exit).
# File lib/como.rb, line 877 def Spec.usage Opt.main.usage end
Private Class Methods
Argument checking assertion.
# File lib/como.rb, line 945 def Spec.ArgCheck( cond, str ) raise( ArgumentError, str ) unless cond end
Public Instance Methods
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
Alias to subcmd to highlight the main command.
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