como 0.1.1 → 0.1.2

data/lib/como.rb

@@ -46,7 +46,7 @@
 # [author] Author of the program.
 # [year] Year (or any date) for the program.
 # [option table] Description of the command options.
-# 
+#
 # Each option table entry (row/sub-array) includes 4 fields and
 # specifies one option:
 #   [ type, name, mnemonic, doc ]
@@ -100,17 +100,17 @@
 # The following is displayed on the screen:
 #
 #  como_simple error: Option "-f" missing for "como_simple"...
-#  
+#
 #    Usage:
 #      como_simple -f <file> [-d]
-#  
+#
 #    -f          File argument.
 #    -d          Enable debugging.
-#  
-#  
+#
+#
 #    Copyright (c) 2013 by Programmer
-#  
-#  
+#
+#
 # Missing option error is displayed since "file" is a mandatory
 # option. The error message is followed by "usage" display (Usage
 # Help). Documentation string is taken from the option specification to
@@ -122,7 +122,7 @@
 # would display the same "usage" screen except without the error
 # line.
 #
-# === Subccommand example
+# === Subcommand example
 #
 # Subcmd example includes a program which has subcommands. Subcommands
 # can have their own command line switches and options.
@@ -131,36 +131,36 @@
 #
 #  require "como"
 #  include Como
-#  
+#
 #  Spec.program( "Programmer", "2013" ) do
-#  
+#
 #      subcmd( "como_subcmd", [
 #         [ :subcmd,      "add",       nil,  "Add file." ],
 #         [ :subcmd,      "rm",        nil,  "Remove file." ],
 #        ], )
-#  
+#
 #      subcmd( "add", [
 #         [ :switch,      "force",     "-fo", "Force operation." ],
 #         [ :opt_single,  "password",  "-p",  "User password." ],
 #         [ :opt_single,  "username",  "-u",  "Username." ],
 #         [ :single,      "file",      "-f",  "File." ],
 #        ] )
-#  
+#
 #      checkRule do
 #          one(
 #              '-fo',
 #              all( 'password', 'username' )
 #              )
 #      end
-#      
+#
 #      subcmd( "rm", [
 #         [ :single,  "file",      "-f",  "File." ],
 #        ] )
-#   
+#
 #  end
-#  
+#
 #  subcmd = Opt.main.givenSubcmd
-#  
+#
 #  case subcmd.name
 #  when 'add'; puts "  Adding file \"#{subcmd['file'].value}\"..."
 #  when 'rm';  puts "  Removing file \"#{subcmd['file'].value}\"..."
@@ -212,23 +212,23 @@
 #
 # Would result to:
 #  como_subcmd error: Option combination mismatch!
-#  
+#
 #    Subcommand "add" usage:
 #      como_subcmd add [-fo] [-p <password>] [-u <username>] -f <file>
-#  
+#
 #    -fo         Force operation.
 #    -p          User password.
 #    -u          Username.
 #    -f          File.
-#  
-#  
+#
+#
 #    Option Combinations:
 #      |--# One of:
 #      |     |--<-fo>
 #      |     |--# All of:
 #      |     |     |--<password>
 #      |     |     |--<username>
-#      
+#
 # Since the combination rule requires either "-fo" or both "password"
 # and "username" in a pair.
 #
@@ -241,9 +241,9 @@
 #
 #
 # == Option specification
-# 
+#
 # === Overview
-# 
+#
 # Option specification includes the minimum set of information
 # required for command line parsing. It is used to:
 # * Parse the command line.
@@ -272,7 +272,10 @@
 #            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 options.
+# [:exclusive] Option that does not coexist with other
+#              options. :exclusive can have arguments as with
+#              :opt_any, however :exclusive is documented like
+#              :switch.
 # [:silent] Option that does not coexist with other options and is not
 #           displayed as an option in Usage Help display. In effect a
 #           sub-option of :exclusive.
@@ -297,7 +300,7 @@
 #
 #
 # === Option specification method configuration
-# 
+#
 # Option behavior can be controlled with several configuration options.
 #
 # The configuration options are provided in a Hash. These are the
@@ -318,14 +321,14 @@
 # [:subcheck] Automatically check that a subcommand is provided
 #             (default: true).
 # [:check_missing] Check for missing arguments (default: true).
+# [:check_invalid] Error for unknown options (default: true).
 # [:tab] Tab stop column for option documentation (default: 12).
 # [:help_exit] Exit program if help displayed (default: true).
-# [:error_exit] Exit program if error in options (default: true).
 #
 #
 #
 # == Option referencing
-# 
+#
 # === Existence and values
 #
 # Opt class includes the parsed option values. All options can be
@@ -394,7 +397,7 @@
 # RuleCheck DSL. This is needed since sometimes options have to be
 # used in combination to make sense for the program. Also options
 # might be mutually exclusive.
-#  
+#
 # The following rules can be used (in combination):
 # [all] All options in the list.
 # [one] One and only one from the list.
@@ -421,7 +424,7 @@ module Como
 
     # IO stream options for Como classes.
     class ComoCommon
-        
+
         # Default value for display output.
         @@io = STDOUT
 
@@ -467,7 +470,7 @@ module Como
         #                      (changes @@config defaults).
         def Spec.command( prog, author, year, defs, config = {} )
             Spec.defineCheck( prog, author, year, defs, config )
-            Spec.usage if Opt['help'].given
+            # Spec.usage if Opt['help'].given
         end
 
         # Alias to Spec.command.
@@ -507,7 +510,7 @@ module Como
             unless Opt.main
 
                 main = MainOpt.new( @author, @year,
-                                        cmd, nil, :subcmd, nil )
+                    cmd, nil, :subcmd, nil )
                 Opt.setMain( main )
                 subcmd = main
 
@@ -549,7 +552,7 @@ module Como
             table.each_index do |idx|
 
                 i = table[ idx ]
-                
+
                 Spec.ArgCheck( i.class == Array, "Option table entry is not an Array" )
 
                 if i[0] == :default && i.length == 2
@@ -563,10 +566,11 @@ module Como
                     table[ idx ] = [ i[0], i[1], nil, i[2] ]
                 end
 
-                Spec.ArgCheck( table[ idx ].length == 4, "Option table entry length not 4" )
+                Spec.ArgCheck( table[ idx ].length == 4,
+                    "Option table entry length not 4" )
             end
 
-            
+
             table.each do |e|
 
                 if e[0] == :subcmd
@@ -579,16 +583,8 @@ module Como
 
                     case e[0]
 
-                    when :switch
-                        option = Opt.switch( e[1], e[2], e[3] )
-
-                    when :exclusive
-                        option = Opt.exclusive( e[1], e[2], e[3] )
-
-                    when :silent
-                        option = Opt.exclusive( e[1], e[2], e[3], true )
-
-                    when :single, :multi, :opt_single, :opt_multi, :opt_any
+                    when :switch, :exclusive, :silent, :single, :multi,
+                        :opt_single, :opt_multi, :opt_any
                         option = Opt.full( e[1], e[2], e[0], e[3] )
 
                     when :default
@@ -597,13 +593,13 @@ module Como
                     else
                         raise "Unknown option type: \"#{e[0]}\"..."
                     end
-                    
+
                     options[ option.name ] = option
 
                 end
-                    
+
             end
-            
+
             [ options.values, subcmds.values ]
         end
 
@@ -726,15 +722,15 @@ module Como
 
         # Set of default configs for printout.
         @@config = {
-            :autohelp      => true,  
-            :rulehelp      => false, 
-            :header        => nil,   
-            :footer        => nil,   
-            :subcheck      => true,  
-            :check_missing => true,  
-            :tab           => 12,    
-            :help_exit     => true,  
-            :error_exit    => true,  
+            :autohelp      => true,
+            :rulehelp      => false,
+            :header        => nil,
+            :footer        => nil,
+            :subcheck      => true,
+            :check_missing => true,
+            :check_invalid => true,
+            :tab           => 12,
+            :help_exit     => true,
         }
 
 
@@ -755,12 +751,12 @@ module Como
             @@opts.push opt
         end
 
-        
+
         # Set current subcmd.
         def Opt.setSubcmd( opt )
             @@subcmd = opt
         end
-        
+
 
         # Current subcmd processed.
         def Opt.current
@@ -844,33 +840,24 @@ module Como
             new( name, nil, :subcmd, doc, false )
         end
 
-        # Create switch option spec.
-        def Opt.switch( name, opt, doc = "No doc." )
-            new( name, opt, :switch, doc, false )
-        end
-
-        # Create exclusive option spec.
-        def Opt.exclusive( name, opt, doc = "No doc.", silent = false )
-            o = new( name, opt, :exclusive, doc, false )
-            o.silent = silent
-            o
-        end
-
         # Create default option spec, no switch.
         def Opt.defaultOpt( doc = "No doc." )
-            new( "<default>", "<args>", :default, doc, [] )
+            new( "<default>", "<default>", :default, doc, [] )
         end
 
+
         # Options iterator for all options.
         def Opt.each( &blk )
             Opt.main.each &blk
         end
 
+
         # Options iterator for given options.
         def Opt.each_given( &blk )
             Opt.main.each_given( &blk )
         end
 
+
         # Overlay Opt default configuration options.
         def Opt.configOverlay( config )
             @@config.merge!( config )
@@ -889,7 +876,7 @@ module Como
         attr_accessor :name
 
         # Short option string.
-        attr_accessor :opt
+        attr_accessor :shortOpt
 
         # Long option string.
         attr_accessor :longOpt
@@ -906,9 +893,6 @@ module Como
         # Is option specified?
         attr_writer :given
 
-        # Is option hidden (usage).
-        attr_accessor :silent
-
         # List of suboptions.
         attr_reader :subopt
 
@@ -941,12 +925,11 @@ module Como
         def initialize( name, opt, type, doc, value = nil )
             @parent = nil
             @name = name
-            @opt = opt
+            @shortOpt = opt
             @longOpt = "--#{name}"
             @type = type
             @value = value
             @doc = doc
-            @silent = false
             # Whether option was set or not.
             @given = false
             @subopt = nil
@@ -961,7 +944,7 @@ module Como
 
         # Set subcommand suboptions.
         #
-        # @param opts [Array<Opt>] 
+        # @param opts [Array<Opt>]
         def setSubopt( opts, subs )
             opts.each do |i|
                 i.parent = self
@@ -1005,7 +988,7 @@ module Como
 
                 # Parse and check for invalid arguments.
                 begin
-                    top = top.parse( argsState, top.config[ :check_missing ] )
+                    top = top.parse( argsState, top.config[ :check_invalid ] )
                 end while( top )
 
                 # Check for any missing valid arguments.
@@ -1013,17 +996,14 @@ module Como
 
             rescue Opt::MissingArgument, Opt::InvalidOption => err
 
-                @@io.puts
-
                 error( err.to_s )
 
                 # Display subcmd specific usage info.
                 err.data.usage
 
-                exit( 1 ) if Opt.main.config[ :error_exit ]
-
+                exit( 1 )
             end
-            
+
             # Revert back to top after hierarchy travelsal.
             usageIfHelp
 
@@ -1061,13 +1041,13 @@ module Como
                         if checkInvalids
                             raise \
                             InvalidOption.new( "Unknown option \"#{args.get}\"...",
-                                               self )
+                                self )
                         else
                             o = findOpt( nil )
                             if !o
                                 raise \
                                 InvalidOption.new(
-                                   "No default option specified for \"#{args.get}\"...",
+                                    "No default option specified to allow \"#{args.get}\"...",
                                    self )
                             else
                                 # Default option.
@@ -1081,16 +1061,16 @@ module Como
                         args.next
 
                         if ( !args.get || args.isOpt ) &&
-                                o.type != :opt_any
+                                o.type != :opt_any && o.type != :exclusive
 
                             raise MissingArgument.new(
-                                      "No argument given for \"#{o.opt}\"...",
-                                      self )
+                                "No argument given for \"#{o.opt}\"...",
+                                self )
 
                         else
 
                             if o.hasMany
-                                
+
                                 # Get all argument for multi-option.
                                 o.value = [] if !o.given
                                 while args.get && !args.isOpt
@@ -1105,8 +1085,8 @@ module Como
                                 if o.given
                                     raise \
                                     InvalidOption.new(
-                                       "Too many arguments for option (\"#{o.name}\")...",
-                                       self )
+                                        "Too many arguments for option (\"#{o.name}\")...",
+                                        self )
                                 else
                                     o.value = args.toValue
                                 end
@@ -1120,9 +1100,8 @@ module Como
 
                         if !o
                             raise InvalidOption.new( "No valid options specified...",
-                                                     self )
+                                self )
                         else
-                            o.value = !o.value if !o.given
                             o.given = true
                             args.next
                         end
@@ -1142,8 +1121,8 @@ module Como
                         if !o
                             raise \
                             InvalidOption.new(
-                                     "No default option specified for \"#{args.get}\"...",
-                                                  self )
+                                "No default option specified to allow \"#{args.get}\"...",
+                                self )
                         else
                             # Default option.
                             o.given = true
@@ -1152,11 +1131,12 @@ module Como
                         end
 
                     else
-                        
+
+                        # Subcmd.
                         o.given = true
                         args.next
                         return o
-                        
+
                     end
 
                 end
@@ -1171,12 +1151,14 @@ module Como
         # is generated if argument is missing.
         def checkMissing
 
+            return unless config[ :check_missing ]
+
             # Full cmd name.
             cmd = ( getParents.map do |i| i.name end ).join( ' ' )
 
             # Check for any exclusive args first.
             @subopt.each do |o|
-                if o.type == :exclusive && o.given
+                if o.isExclusive && o.given
                     return
                 end
             end
@@ -1188,8 +1170,8 @@ module Como
                 if o.isRequired
                     unless o.given
                         raise MissingArgument.new(
-                                 "Option \"#{o.opt}\" missing for \"#{cmd}\"...",
-                                 self )
+                            "Option \"#{o.opt}\" missing for \"#{cmd}\"...",
+                            self )
                     end
                 end
             end
@@ -1215,9 +1197,9 @@ module Como
 
             # If no subcmds are given, issue error.
             raise MissingArgument.new(
-                                      "Subcommand required for \"#{cmd}\"...",
-                                      self ) if subcmdMissing
-            
+                "Subcommand required for \"#{cmd}\"...",
+                self ) if subcmdMissing
+
         end
 
 
@@ -1275,6 +1257,12 @@ module Como
         end
 
 
+        # Option's opt id. Short if exists otherwise long.
+        def opt
+            @shortOpt ? @shortOpt : @longOpt
+        end
+
+
         # All subcommand options, options and subcommands.
         def suball
             @subopt + @subcmd
@@ -1424,7 +1412,7 @@ module Como
         # Option requires argument?
         def hasArg
             case @type
-            when :single, :multi, :opt_single, :opt_multi, :opt_any; true
+            when :single, :multi, :opt_single, :opt_multi, :opt_any, :exclusive; true
             else false
             end
         end
@@ -1433,7 +1421,7 @@ module Como
         # Option requires many arguments?
         def hasMany
             case @type
-            when :multi, :opt_multi, :opt_any; true
+            when :multi, :opt_multi, :opt_any, :exclusive; true
             else false
             end
         end
@@ -1450,7 +1438,17 @@ module Como
 
         # Test if option is silent.
         def silent?
-            @silent
+            @type == :silent
+        end
+
+
+        # Test if option is exclusive. In addition :exclusive also
+        # :silent is exclusive.
+        def isExclusive
+            case @type
+            when :exclusive, :silent; true
+            else false
+            end
         end
 
 
@@ -1487,7 +1485,7 @@ module Como
         #                           display. Default to rulehelp config
         #                           if nil.
         def usage( doExit = nil, ruleHelp = nil )
-            
+
             doExit = @config[ :help_exit ] if doExit == nil
             ruleHelp = @config[ :rulehelp ] if ruleHelp == nil
 
@@ -1515,7 +1513,7 @@ module Como
         # Usage printout for command.
         def usageCommand
             str = ""
-            str += "
+            str += "\
   Subcommand \"#{@name}\" usage:
     #{fullCommand} #{cmdline.join(" ")}
 
@@ -1526,7 +1524,7 @@ module Como
         end
 
         # Usage info for Opt:s.
-        def usageNormal
+        def usageNormalOld
             str = ""
 
             if @config[ :header ]
@@ -1538,7 +1536,28 @@ module Como
             str += usageCommand
 
             if @config[ :footer ]
-                str += @config[ :footer ] 
+                str += @config[ :footer ]
+                str += "\n"
+            end
+
+            str
+        end
+
+        # Usage info for Opt:s.
+        def usageNormal
+            str = ""
+
+            if @config[ :header ]
+                str += @config[ :header ]
+            else
+                str += "\n"
+            end
+
+            str += usageCommand
+
+            if @config[ :footer ]
+                str += @config[ :footer ]
+            else
                 str += "\n"
             end
 
@@ -1568,19 +1587,19 @@ module Como
                     name = ""
                 end
 
-                if o.opt == nil
+                if o.shortOpt == nil
                     opt = o.longOpt
                 else
-                    opt = o.opt
+                    opt = o.shortOpt
                 end
-                
+
                 if o.isRequired
                     opts.push "#{opt}#{name}"
                 else
                     opts.push "[#{opt}#{name}]"
                 end
             end
-            
+
 
             if hasSubcmd
                 opts.push "<<subcommand>>"
@@ -1597,11 +1616,11 @@ module Como
             str = ""
             # format = Proc.new do |s,d| ( "  %-#{@config[ :tab ]}s%s\n" % [ s, d ] ) end
 
-            str += suboptDocFormat( "Options:", "" ) if hasSubcmd && hasVisibleOptions
+            str += "  Options:\n" if hasSubcmd && hasVisibleOptions
 
             @subopt.each do |o|
                 next if o.silent?
-                str += suboptDocFormat( o.opt ? o.opt : o.longOpt, o.doc )
+                str += suboptDocFormat( o.opt, o.doc )
             end
 
             str += "\n" + suboptDocFormat( "Subcommands:", "" ) if hasSubcmd
@@ -1626,14 +1645,14 @@ module Como
                 suball.detect { |i| i.opt == str }
             end
         end
-                
+
 
         # Como error printout.
         def error( str )
-            @@io.puts "#{Opt.progname} error: #{str}"
+            STDERR.puts "\n#{Opt.progname} error: #{str}"
         end
 
-        
+
 
 
         # ------------------------------------------------------------
@@ -1705,7 +1724,7 @@ module Como
 
             parts = doc.split( "\n" )
             lines = [ ( "  %-#{@config[ :tab ]}s%s\n" % [ switch, parts[0] ] ) ]
-            
+
             if parts[1]
                 parts[1..-1].each do |p|
 
@@ -1714,7 +1733,7 @@ module Como
                     else
                         lines.push p
                     end
-                    
+
                 end
             end
 
@@ -1731,10 +1750,10 @@ module Como
 
         # Program external arguments:
         attr_accessor :external
-        
+
         # Program author and year (date).
         attr_reader :author, :year
-        
+
 
         def initialize( author, year,
                         name, opt, type, doc, value = nil )
@@ -1744,7 +1763,7 @@ module Como
             super( name, opt, type, doc, value = nil )
 
         end
-                
+
 
         # Full command name.
         def fullCommand
@@ -1753,7 +1772,7 @@ module Como
 
 
         # Usage printout for command.
-        def usageCommand
+        def usageCommandOld
             str = "
   Usage:
     #{fullCommand} #{cmdline.join(" ")}
@@ -1765,6 +1784,20 @@ module Como
 
   Copyright (c) #{Opt.year} by #{Opt.author}
 
+"
+        end
+
+        # Usage printout for command.
+        def usageCommand
+            str = "\
+  #{fullCommand} #{cmdline.join(" ")}
+
+"
+            str += suboptDoc
+
+            str += "
+
+  Copyright (c) #{Opt.year} by #{Opt.author}
 "
         end
 
@@ -1888,7 +1921,7 @@ module Como
         # Incremental options in order i.e. have to have previous
         # to have later.
         def incr( *args )
-            
+
             # Opts given consecutive.
             consecutiveCnt = 0