como 0.1.3 → 0.1.4

data/lib/como.rb

@@ -41,7 +41,7 @@
 #
 # First Como is required and Como module is included.
 #
-# "Spec.command" method takes 4 arguments:
+# {Spec.command} method takes 4 arguments:
 # [progname] Name of the program (or command).
 # [author] Author of the program.
 # [year] Year (or any date) for the program.
@@ -63,7 +63,7 @@
 # The option name also doubles as long option format, i.e. one could
 # use "--file <filename>" on the command line.
 #
-# Existence of optional options can be tested using the "given"
+# Existence of optional options can be tested using the {Opt#given}
 # method. For example
 #   Opt['debug'].given
 # would return "true" if "-d" was given on the command line.
@@ -165,12 +165,12 @@
 #  when 'rm';  puts "  Removing file \"#{subcmd['file'].value}\"..."
 #  end
 #
-# "Spec.program" method defines a program (command) with
+# {Spec.program} method defines a program (command) with
 # subcommands. The author and date are provided as parameters, and the
 # program and subcommand options are defined in block.
 #
-# The first "command" (or "subcmd") method call defines the main command
-# ("Opt.main") which represents the program. It has two "subcmd"
+# The first {Spec#command} (or {Spec#subcmd}) method call defines the main command
+# ({Opt.main}) which represents the program. It has two "subcmd"
 # options ("add" and "rm").
 #
 # The rest of the "subcmd" methods define subcommands for the parent
@@ -187,14 +187,14 @@
 # or alternatively
 #   Opt['como_subcmd']
 #
-# The subcommands can be referenced through "Opt.main" (etc.)
+# The subcommands can be referenced through {Opt.main} (etc.)
 #   Opt.main['add']
 #   Opt['como_subcmd']['add']
 #
-# or directly from "Opt" if subcommand names do not collide:
+# or directly from {Opt} if subcommand names do not collide:
 #   Opt['add']
 #
-# The given subcommand can be accessed with "givenSubcmd" method from
+# The given subcommand can be accessed with {Opt#givenSubcmd} method from
 # each parent command.
 #
 # === Subcommand example executions
@@ -262,7 +262,8 @@
 # [:single] Mandatory single argument option.
 # [:multi] Mandatory multiple argument option (one or many). Option
 #          values in array.
-# [:opt_single] Optional single argument option.
+# [:opt_single] Optional single argument option. Value is nil when
+#               option is not given.
 # [:opt_multi] Optional multiple argument option (one or many). Option
 #              values in array.
 # [:opt_any] Optional multiple argument option (also none
@@ -271,7 +272,7 @@
 #            String values can be left out, since only the document
 #            string is used. Default option is referred with
 #            ":default" or "nil".
-# [:exclusive] Option that does not coexist with other
+# [:exclusive] Option that does not co-exist with other
 #              options. :exclusive can have arguments as with
 #              :opt_any, however :exclusive is documented like
 #              :switch.
@@ -303,8 +304,8 @@
 # Option behavior can be controlled with several configuration options.
 #
 # The configuration options are provided in a Hash. These are the
-# passed as the last regular parameter for both "Spec.command" and
-# "Spec.program" methods. Setting the configuration at "Spec.program"
+# passed as the last regular parameter for both {Spec.command} and
+# {Spec.program} methods. Setting the configuration at {Spec.program}
 # will propagate the config options to all the subcommands as
 # well. Configuration can be given to each subcommand separately to
 # override the inherited config values. Subcommand settings are not
@@ -335,9 +336,9 @@
 # tested whether they are specified on the command line using:
 #   Opt['name'].given
 #
-# The "given" method takes optionally a block argument. When block
+# The {Opt#given} method takes optionally a block argument. When block
 # argument is used, the block is supplied with option value and the
-# block is executed if the option has been set (See: Opt#given).
+# block is executed if the option has been set (See: {Opt#given}).
 #
 # Provided value is returned by:
 #   Opt['name'].value
@@ -378,7 +379,7 @@
 # == Subcommand options
 #
 # The given subcommand for the parent command is return by
-# "givenSubcmd". Commonly the program creator should just check
+# {Opt#givenSubcmd}. Commonly the program creator should just check
 # directly which subcommand has been selected and check for any
 # subcommand options set. For example:
 #   if Opt['como_subcmd']['add'].given
@@ -387,7 +388,7 @@
 # == Program external options
 #
 # If the user gives the "--" option (double-dash), the arguments after
-# that option are returned as an Array with "Opt.external".
+# that option are returned as an Array with {Opt.external}.
 #
 #
 #
@@ -415,8 +416,8 @@
 #
 # = Customization
 #
-# A user specific customization file can be referenced through the
-# "COMO" environment variable. If environment variable "COMO" is
+# A Como user specific customization file can be referenced through
+# the "COMO" environment variable. If environment variable "COMO" is
 # defined, the referenced file is read in as Ruby file as a last phase
 # when Como is loaded from the program (require). Proposed naming
 # convention for the customization is:
@@ -426,9 +427,9 @@
 # User can define a pre and a post action hook in the file.
 #
 # The pre-hook can be used for example to change the Como config
-# defaults. It is run before the body of "Spec.command" or
-# "Spec.program" is executed. It is passed all the parameters that has
-# been passed to "Spec.command" or "Spec.program", only collected into
+# defaults. It is run before the body of {Spec.command} or
+# {Spec.program} is executed. It is passed all the parameters that has
+# been passed to {Spec.command} or {Spec.program}, only collected into
 # a Hash. The Hash keys are method parameter names as symbols.
 #
 # Example:
@@ -449,7 +450,16 @@
 #  end
 #
 # There is no predefined use cases for post-hook. Post-hook is passed
-# the Opt.main as parameter.
+# the {Opt.main} as parameter.
+#
+# {Spec.program} and {Spec.command} both process and check options in
+# one pass. Como user can separate the definition and checking
+# phase. Definition phase is performed by executing
+# {Spec.defineProgram} or {Spec.defineCommand}. After definition phase
+# the user can for example programmatically add new subcommands or
+# options, in addition to existing options. When the subcommands and
+# options are complete, {Spec.execute} should be called to perform
+# options checking.
 #
 # If the provided customization facilities are not satisfactory,
 # changes can be implemented simply by overloading the existing
@@ -481,10 +491,18 @@ module Como
             @@io
         end
 
+        # Set hook content.
+        #
+        # @param name [String] Hook name.
+        # @yield code Hook code.
         def ComoCommon.setHook( name, &code )
             @@hook[ name ] = code
         end
 
+        # Run hook.
+        #
+        # @param name [String] Hook name.
+        # @yield code Hook arguments.
         def ComoCommon.runHook( name, args )
             @@hook[ name ].yield( args ) if @@hook[ name ]
         end
@@ -507,13 +525,41 @@ module Como
     # User interface for Como.
     class Spec < ComoCommon
 
+
         # Create specification for program with subcmds.
         #
         # @param author [String] Program author.
         # @param year [String] Year (or dates) for program.
         # @yield [] Subcmd definitions.
         def Spec.program( author, year, config = nil, &defs )
+            Spec.defineProgram( author, year, config, &defs )
+            Spec.execute
+        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).
+        def Spec.command( prog, author, year, defs = [], config = {} )
+            Spec.defineCommand( prog, author, year, defs, config )
+            Spec.execute
+        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.
+        def Spec.defineProgram( author, year, config = nil, &defs )
             preHookArgs = {
                 :author => author,
                 :year => year,
@@ -526,17 +572,14 @@ module Como
             if config
                 Opt.configOverlay( config )
             end
+
             spec = Spec.new( author, year )
             spec.instance_eval( &defs )
-            Opt.main.check( ArgsParseState.new( @@argv ) )
-
-            ComoCommon.runHook( :postHook, Opt.main )
         end
 
 
-        # The primary entry point to Como. Defines the command
-        # switches and parses the command line. Performs "usage"
-        # display if "help" was selected.
+        # 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.
@@ -544,7 +587,7 @@ module Como
         # @param defs [Array<Array>] Option definitions.
         # @param config [Hash] Option definition's behavioral config
         #                      (changes @@config defaults).
-        def Spec.command( prog, author, year, defs, config = {} )
+        def Spec.defineCommand( prog, author, year, defs, config = {} )
 
             preHookArgs = {
                 :prog => prog,
@@ -556,24 +599,24 @@ module Como
 
             ComoCommon.runHook( :preHook, preHookArgs )
 
-            Spec.defineCheck( prog, author, year, defs, config )
-
-            ComoCommon.runHook( :postHook, Opt.main )
+            spec = Spec.new( author, year )
+            spec.subcmd( prog, defs, config )
         end
 
 
-        # Alias to Spec.command.
+        # Alias for {Spec.command}.
+        #
+        # NOTE: This method is deprecated and will be removed in
+        # future releases.
         def Spec.defineCheckHelp( prog, author, year, defs, config = {} )
             Spec.command( prog, author, year, defs, config )
         end
 
 
-        # Same as "defineCheckHelp" except without automatic "help"
-        # option processing.
-        def Spec.defineCheck( prog, author, year, defs, config = {} )
-            spec = Spec.new( author, year )
-            spec.subcmd( prog, defs, config )
+        # Perform command line options checking.
+        def Spec.execute
             Opt.main.check( ArgsParseState.new( @@argv ) )
+            ComoCommon.runHook( :postHook, Opt.main )
         end
 
 
@@ -595,7 +638,7 @@ module Como
         # @param cmd [String] Subcmd name.
         # @param defs [Array<Array>] Option definition table.
         # @param config [] Configuration options.
-        def subcmd( cmd, defs, config = {} )
+        def subcmd( cmd, defs = [], config = {} )
 
             unless Opt.main
 
@@ -622,8 +665,7 @@ module Como
                 defs.insert( 0, [ :silent, "help", "-h", "Display usage info." ] )
             end
 
-            subcmd.setSubopt( *Spec.specify( defs ) )
-            subcmd
+            Spec.specify( subcmd, defs )
 
         end
 
@@ -632,10 +674,12 @@ module Como
         alias command subcmd
 
 
-        # Specify and check options spec.
+        # Check/fix options specs and create option objects for the
+        # whole table.
         #
-        # @param table [Array<Array>] Option definition table.
-        def Spec.specify( table )
+        # @param subcmd [Opt] Subcommand target.
+        # @param table [Array<Array>] Option definition table for subcommand.
+        def Spec.specify( subcmd, table )
 
             options = {}
             subcmds = {}
@@ -643,58 +687,67 @@ module Como
             # Type checks for valid user input.
             Spec.ArgCheck( table.class == Array, "Option table is not an Array" )
 
-            table.each_index do |idx|
+            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
 
-                i = table[ idx ]
 
-                Spec.ArgCheck( i.class == Array, "Option table entry is not an Array" )
 
-                if i[0] == :default && i.length == 2
+        # Check/fix options specs and create option objects for the
+        # whole table.
+        #
+        # @param opt_or_sub [Array<Array>] Option definition table.
+        def Spec.specifyOptOrSub( opt_or_sub )
 
-                    # Add 2 dummy entries for :default type if needed.
-                    table[ idx ] = [ i[0], nil, nil, i[1] ]
+            # Fix the table entries if needed.
 
-                elsif i[0] == :subcmd && i.length == 3
+            Spec.ArgCheck( opt_or_sub.class == Array, "Option table entry is not an Array" )
 
-                    # Add 1 dummy entry for :subcmd type if needed.
-                    table[ idx ] = [ i[0], i[1], nil, i[2] ]
-                end
+            if opt_or_sub[0] == :default && opt_or_sub.length == 2
 
-                Spec.ArgCheck( table[ idx ].length == 4,
-                    "Option table entry length not 4" )
-            end
+                # 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
 
-            table.each do |e|
+                # 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] ]
 
-                if e[0] == :subcmd
+            end
 
-                    subcmds[ e[1] ] = Opt.subcmd( e[1], e[3] )
+            Spec.ArgCheck( opt_or_sub.length == 4,
+                "Option table entry length not 4" )
 
-                else
+            if opt_or_sub[0] == :subcmd
 
-                    option = nil
+                Opt.subcmd( opt_or_sub[1], opt_or_sub[3] )
 
-                    case e[0]
+            else
 
-                    when :switch, :exclusive, :silent, :single, :multi,
-                        :opt_single, :opt_multi, :opt_any
-                        option = Opt.full( e[1], e[2], e[0], e[3] )
+                case opt_or_sub[0]
 
-                    when :default
-                        option = Opt.defaultOpt( e[3] )
+                when :switch, :exclusive, :silent, :single, :multi,
+                    :opt_single, :opt_multi, :opt_any
+                    Opt.full( opt_or_sub[1], opt_or_sub[2], opt_or_sub[0], opt_or_sub[3] )
 
-                    else
-                        raise "Unknown option type: \"#{e[0]}\"..."
-                    end
+                when :default
+                    Opt.defaultOpt( opt_or_sub[3] )
 
-                    options[ option.name ] = option
+                else
+                    raise "Unknown option type: \"#{opt_or_sub[0]}\"..."
 
                 end
 
             end
 
-            [ options.values, subcmds.values ]
         end
 
 
@@ -762,6 +815,7 @@ module Como
 
 
         # 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
@@ -773,6 +827,7 @@ module Como
 
         private
 
+        # Argument checking assertion.
         def Spec.ArgCheck( cond, str )
             raise( ArgumentError, str ) unless cond
         end
@@ -790,9 +845,13 @@ module Como
     class Opt < ComoCommon
 
 
-        # Create exception with capability to pass arbitrary data
+        # Create exception with capability to pass arbitrary data.
         class ErrorWithData < StandardError
+
+            # Exception data.
             attr_reader :data
+
+            # Create error exception.
             def initialize( message = nil, data = nil )
                 super( message )
                 @data = data
@@ -1023,10 +1082,10 @@ module Como
         attr_reader :rules
 
 
-        # Create Opt object:
-        # [name] Option name string.
-        # [opt] Switch string.
-        # [type] Option type. One of:
+        # Create Opt object.
+        # @param name [String] Option name.
+        # @param opt [String] Switch.
+        # @param type [Symbol] Option type. One of:
         #        * :switch
         #        * :single
         #        * :multi
@@ -1036,9 +1095,8 @@ module Como
         #        * :default
         #        * :exclusive
         #        * :silent
-        # [doc] Option documentation.
-        # [value] Default value.
-
+        # @param doc [String] Option documentation.
+        # @param value [Object] Default value.
         def initialize( name, opt, type, doc, value = nil )
             @parent = nil
             @name = name
@@ -1046,11 +1104,16 @@ module Como
             @longOpt = "--#{name}"
             @type = type
             @value = value
+
+            if hasMany && value == nil
+                @value = []
+            end
+
             @doc = doc
             # Whether option was set or not.
             @given = false
-            @subopt = nil
-            @subcmd = nil
+            @subopt = []
+            @subcmd = []
             @rules = nil
 
             @config = @@config.dup
@@ -1059,20 +1122,35 @@ module Como
         end
 
 
-        # Set subcommand suboptions.
+        # Set command (subcommand) suboptions and subcmds.
         #
         # @param opts [Array<Opt>]
-        def setSubopt( opts, subs )
+        def setOptionSubcmd( opts, subs )
             opts.each do |i|
-                i.parent = self
+                addOption( i )
             end
 
             subs.each do |i|
-                i.parent = self
+                addSubcmd( i )
             end
+        end
 
-            @subopt = opts
-            @subcmd = subs
+
+        # Add subcommand option.
+        #
+        # @param opt [Option] Option to add.
+        def addOption( opt )
+            opt.parent = self
+            @subopt.push opt
+        end
+
+
+        # Add subcommand subcmd.
+        #
+        # @param cmd [Option] Subcmd to add.
+        def addSubcmd( cmd )
+            cmd.parent = self
+            @subcmd.push cmd
         end
 
 
@@ -1101,8 +1179,7 @@ module Como
             # Start at top.
             top = self
 
-            begin
-
+            parse = Proc.new do
                 # Parse and check for invalid arguments.
                 begin
                     top = top.parse( argsState, top.config[ :check_invalid ] )
@@ -1110,10 +1187,10 @@ module Como
 
                 # Check for any missing valid arguments.
                 checkMissing
+            end
 
-            rescue Opt::MissingArgument, Opt::InvalidOption => err
-
-                error( err.to_s )
+            error = Proc.new do |err|
+                errornl( err.to_s )
 
                 # Display subcmd specific usage info.
                 err.data.usage
@@ -1121,6 +1198,12 @@ module Como
                 exit( 1 )
             end
 
+            begin
+                parse.call
+            rescue Opt::MissingArgument, Opt::InvalidOption => err
+                error.call( err )
+            end
+
             # Revert back to top after hierarchy travelsal.
             usageIfHelp
 
@@ -1332,7 +1415,7 @@ module Como
 
             rescue Opt::MissingArgument, Opt::InvalidOption => err
                 @@io.puts
-                error( err.to_s )
+                errornl( err.to_s )
 
                 usage( nil, true )
 
@@ -1341,6 +1424,7 @@ module Como
 
 
         # 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
@@ -1352,7 +1436,7 @@ module Como
                 end
             rescue Opt::MissingArgument, Opt::InvalidOption => err
                 @@io.puts
-                error( err.to_s )
+                errornl( err.to_s )
                 err.data.usage
                 exit( 1 )
             end
@@ -1422,7 +1506,11 @@ module Como
         # Example usage: fileName = Opt["file"].apply( "no_name.txt" )
         def apply( default = nil )
             if given
-                value
+                if @type == :switch
+                    true
+                else
+                    value
+                end
             else
                 default
             end
@@ -1538,7 +1626,7 @@ module Como
         # Option requires many arguments?
         def hasMany
             case @type
-            when :multi, :opt_multi, :opt_any, :exclusive; true
+            when :multi, :opt_multi, :opt_any, :exclusive, :default; true
             else false
             end
         end
@@ -1619,7 +1707,7 @@ module Como
 
         # Display program usage (and optionally exit).
         def usageIfHelp
-            if self['help'].given
+            if self.argByName( 'help' ) && self['help'].given
                 usage
             elsif hasSubcmd && givenSubcmd
                 givenSubcmd.usageIfHelp
@@ -1746,11 +1834,24 @@ module Como
 
 
         # Como error printout.
-        def error( str )
-            STDERR.puts "\n#{Opt.progname} error: #{str}"
+        def error( str, nl = false )
+            nl = nl ? "\n" : ""
+            STDERR.puts( "#{nl}#{Opt.progname} error: #{str}" )
+        end
+
+
+        # Como error printout with pre-newline.
+        def errornl( str )
+            error( str, true )
         end
 
 
+        # Como error printout with immediate exit.
+        def fatal( str )
+            error( str )
+            exit( false )
+        end
+
 
 
         # ------------------------------------------------------------
@@ -1853,8 +1954,12 @@ module Como
         attr_reader :author, :year
 
 
+        # Create program main option.
         def initialize( author, year,
-                        name, opt, type, doc, value = nil )
+                name, opt,
+                type, doc,
+                value = nil )
+
             @author = author
             @year = year
             @external = nil
@@ -1892,6 +1997,8 @@ module Como
     # Command argument parsing state.
     class ArgsParseState
 
+        # Create parse state.
+        #
         # @param list [Array<String>] List of Command Line Arguments
         #                             (default: ARGV).
         def initialize( list )
@@ -1973,11 +2080,17 @@ module Como
     #  end
     class RuleCheck
 
+        # Perform rule checking options.
+        #
+        # @param opt [Object] Options to check.
+        # @yield rule Checking conditions.
         def RuleCheck.check( opt, &rule )
             rc = RuleCheck.new( opt )
             rc.instance_eval( &rule )
         end
 
+
+        # Build Rule checker.
         def initialize( opt, &rule )
             @opt = opt
         end
@@ -2096,11 +2209,13 @@ module Como
             rd.evalAndDisplay( &rule )
         end
 
+        # Create rule displayer.
         def initialize( prefixStr )
             # Prefix string for lines. Rules add/rm from it.
             @prefixStr = prefixStr
         end
 
+        # Display method.
         def evalAndDisplay( &rule )
             printRule( instance_eval( &rule ) )
         end