como 0.1.7 → 0.2.0

data/doc/top-level-namespace.html

@@ -103,7 +103,7 @@
 </div>
 
     <div id="footer">
-  Generated on Tue Jun 21 19:41:08 2016 by
+  Generated on Fri Jul 15 20:24:22 2016 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.7.6 (ruby-2.3.1).
 </div>

data/lib/como.rb

@@ -274,11 +274,9 @@
 #            ":default" or "nil".
 # [:exclusive] Option that does not co-exist 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.
+#              :opt_any.
+# [:silent] Switch option that is not displayed as an option in Usage
+#           Help display.
 #
 # Options use typically all the 4 option fields:
 #   [ type, name, mnemonic, doc ]
@@ -299,6 +297,43 @@
 #   [ :silent, "terminator", "-", "The terminator." ],
 #
 #
+# == Option type primitives
+#
+# Como converts option types into option type primitives. Option types
+# are not completely orthogonal, but primitives are.
+#
+# Primitives:
+#
+# [:none] No arguments (i.e. switch).
+# [:one] One argument.
+# [:many] More than one argument.
+# [:opt] Optional argument(s).
+# [:default] Default option.
+# [:mutex] Mutually exclusive option.
+# [:hidden] Hidden option (no usage doc).
+#
+# Types to primitives mapping:
+#
+# [:switch] :none, :opt
+# [:single] :one
+# [:multi] :one, :many
+# [:opt_single] :one, :opt
+# [:opt_multi] :one, :many, :opt
+# [:opt_any] :none, :one, :many, :opt
+# [:default] :none, :one, :many, :opt, :default
+# [:exclusive] :none, :one, :many, :opt, :mutex
+# [:silent] :none, :opt, :hidden
+#
+# Primitives can be used in place of types if exotic options are
+# needed. Instead of a single Symbol an Array of primitives are given
+# for option type. Order of primitives is not significant.
+#
+# For example:
+#   [ [ :none, :hidden, :opt ], "terminator", "-", "The terminator." ],
+#
+# Como does not check the primitive combinations, thus care and
+# consideration should be applied.
+#
 # == Option specification method configuration
 #
 # Option behavior can be controlled with several configuration options.
@@ -471,7 +506,6 @@
 
 module Como
 
-
     # IO stream options for Como classes.
     class ComoCommon
 
@@ -732,18 +766,15 @@ module Como
 
             else
 
-                case opt_or_sub[0]
-
-                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] )
+                types = Spec.mapTypeToPrims( opt_or_sub[0] )
 
-                when :default
+                if types.index( :default )
                     Opt.defaultOpt( opt_or_sub[3] )
-
                 else
-                    raise "Unknown option type: \"#{opt_or_sub[0]}\"..."
-
+                    Opt.full( opt_or_sub[1],
+                              opt_or_sub[2],
+                              Spec.mapTypeToPrims( opt_or_sub[0] ),
+                              opt_or_sub[3] )
                 end
 
             end
@@ -751,6 +782,65 @@ module Como
         end
 
 
+        # Option type primitives.
+        TYPE_PRIMS = [
+            # No arguments (i.e. switch).
+            :none,
+            # One argument.
+            :one,
+            # More than one argument.
+            :many,
+            # Optional argument(s).
+            :opt,
+            # Default option.
+            :default,
+            # Mutually exclusive option.
+            :mutex,
+            # Hidden option (no usage doc).
+            :hidden
+        ]
+
+
+        # Convert option types (type definitions) to option type
+        # primitives.
+        def Spec.mapTypeToPrims( type )
+
+            prims = nil
+
+            if type.kind_of? Symbol
+                case type
+                when :switch;     prims = [ :none, :opt ]
+                when :single;     prims = [ :one ]
+                when :multi;      prims = [ :one, :many ]
+                when :opt_single; prims = [ :one, :opt ]
+                when :opt_multi;  prims = [ :one, :many, :opt ]
+                when :opt_any;    prims = [ :none, :one, :many, :opt ]
+                when :default;    prims = [ :none, :one, :many, :default, :opt ]
+                when :exclusive;  prims = [ :none, :one, :many, :opt, :mutex ]
+                when :silent;     prims = [ :none, :opt, :hidden ]
+                else 
+                    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
+
         # Command line options source.
         @@argv = ARGV
 
@@ -1004,7 +1094,7 @@ module Como
 
         # Create default option spec, no switch.
         def Opt.defaultOpt( doc = "No doc." )
-            new( "<default>", "<default>", :default, doc, [] )
+            new( "<default>", "<default>", [ :default, :none, :one, :many, :opt ], doc, [] )
         end
 
 
@@ -1074,7 +1164,7 @@ module Como
         # Long option string.
         attr_accessor :longOpt
 
-        # Option type.
+        # Option type as array of primitives (or :subcmd).
         attr_accessor :type
 
         # Option value.
@@ -1102,16 +1192,8 @@ module Como
         # Create Opt object.
         # @param name [String] Option name.
         # @param opt [String] Switch.
-        # @param type [Symbol] Option type. One of:
-        #        * :switch
-        #        * :single
-        #        * :multi
-        #        * :opt_single
-        #        * :opt_multi
-        #        * :opt_any
-        #        * :default
-        #        * :exclusive
-        #        * :silent
+        # @param type [Array<Symbol>, Symbol] Option type in
+        #   primitives (or :subcmd).
         # @param doc [String] Option documentation.
         # @param value [Object] Default value.
         def initialize( name, opt, type, doc, value = nil )
@@ -1120,10 +1202,13 @@ module Como
             @shortOpt = opt
             @longOpt = "--#{name}"
             @type = type
+
             @value = value
 
-            if hasMany && value == nil
-                @value = []
+            if @type != :subcmd
+                if prim?( :many ) && value == nil
+                    @value = []
+                end
             end
 
             @doc = doc
@@ -1241,7 +1326,7 @@ module Como
 
             while args.get
 
-                #puts "Opt.parse (#{@name}): #{args.get}"
+                # puts "Opt.parse (#{@name}): #{args.get}"
 
                 if args.isOptTerm
 
@@ -1273,12 +1358,12 @@ module Como
                             end
                         end
 
-                    elsif o && o.hasArg
+                    elsif o && ( o.prim?( :one ) || o.prim?( :many ) )
 
                         args.next
 
                         if ( !args.get || args.isOpt ) &&
-                                o.type != :opt_any && o.type != :exclusive
+                           !o.prim?( :none )
 
                             raise MissingArgument.new(
                                 "No argument given for \"#{o.opt}\"...",
@@ -1286,7 +1371,7 @@ module Como
 
                         else
 
-                            if o.hasMany
+                            if o.prim?( :many )
 
                                 # Get all argument for multi-option.
                                 o.value = [] if !o.given
@@ -1375,7 +1460,7 @@ module Como
 
             # Check for any exclusive args first.
             @subopt.each do |o|
-                if o.isExclusive && o.given
+                if o.prim?( :mutex ) && o.given
                     return
                 end
             end
@@ -1384,7 +1469,7 @@ module Como
             # Check for required arguments for this level before
             # subcmds.
             @subopt.each do |o|
-                if o.isRequired
+                if !o.prim?( :opt )
                     unless o.given
                         raise MissingArgument.new(
                             "Option \"#{o.opt}\" missing for \"#{cmd}\"...",
@@ -1523,7 +1608,7 @@ module Como
         # Example usage: fileName = Opt["file"].apply( "no_name.txt" )
         def apply( default = nil )
             if given
-                if @type == :switch
+                if prim?( :none )
                     true
                 else
                     value
@@ -1595,7 +1680,7 @@ module Como
         def argByName( str )
             if str == nil || str == :default
                 @subopt.each do |o|
-                    if o.type == :default
+                    if o.prim?( :default )
                         return o
                     end
                 end
@@ -1615,7 +1700,7 @@ module Como
         def argById( str )
             if str == nil || str == :default
                 @subopt.each do |o|
-                    if o.type == :default
+                    if o.prim?( :default )
                         return o
                     end
                 end
@@ -1631,54 +1716,19 @@ module Como
         end
 
 
-        # Option requires argument?
-        def hasArg
-            case @type
-            when :single, :multi, :opt_single, :opt_multi, :opt_any, :exclusive; true
-            else false
-            end
-        end
-
-
-        # Option requires many arguments?
-        def hasMany
-            case @type
-            when :multi, :opt_multi, :opt_any, :exclusive, :default; true
-            else false
-            end
-        end
-
-
-        # Is mandatory argument?
-        def isRequired
-            case @type
-            when :single, :multi; true
-            else false
-            end
-        end
-
-
-        # Test if option is silent.
-        def 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
+        # Check for primitive.
+        def prim?( prim )
+            @type.index( prim )
         end
 
 
         # Test if option is of switch type.
-        def isSwitch
-            case @type
-            when :switch, :exclusive, :default; true
-            else false
+        def hasSwitchStyleDoc
+            if ( prim?( :none ) && !prim?( :many ) ) ||
+               prim?( :default )
+                true
+            else
+                false
             end
         end
 
@@ -1772,17 +1822,18 @@ module Como
 
             @subopt.each do |o|
 
-                next if o.silent?
+                next if o.prim?( :hidden )
 
                 prural = nil
-                case o.type
-                when :multi, :opt_multi; prural = "+"
-                when :opt_any; prural = "*"
-                else prural = ""
+                if o.prim?( :none ) && o.prim?( :many )
+                    prural = "*"
+                elsif o.prim?( :one ) && o.prim?( :many )
+                    prural = "+"
+                else
+                    prural = ""
                 end
 
-
-                if !( o.isSwitch )
+                if !( o.hasSwitchStyleDoc )
                     name = " <#{o.name}>#{prural}"
                 else
                     name = ""
@@ -1794,7 +1845,7 @@ module Como
                     opt = o.shortOpt
                 end
 
-                if o.isRequired
+                if !o.prim?( :opt )
                     opts.push "#{opt}#{name}"
                 else
                     opts.push "[#{opt}#{name}]"
@@ -1822,7 +1873,7 @@ module Como
             str += "  Options:\n" if hasSubcmd && hasVisibleOptions
 
             @subopt.each do |o|
-                next if o.silent?
+                next if o.prim?( :hidden )
                 str += suboptDocFormat( o.opt, o.doc )
             end
 
@@ -1839,7 +1890,7 @@ module Como
         # Find option object by option str.
         def findOpt( str )
             if str == nil
-                suball.detect { |i| i.type == :default }
+                suball.detect { |i| i.prim?( :default ) }
             elsif str[0..1] == "--"
                 suball.detect { |i| i.longOpt == str }
             elsif str[0..0] != "-"
@@ -1969,7 +2020,7 @@ module Como
         # Test if option is of subcmd type.
         def hasVisibleOptions
             # Count non-silent options.
-            ( @subopt.select do |i| !i.silent? end ).length > 0
+            ( @subopt.select do |i| !i.prim?( :hidden ) end ).length > 0
         end
 
 

data/lib/version.rb

@@ -1,5 +1,5 @@
 module Como
-    VERSION = "0.1.7"
+    VERSION = "0.2.0"
     def Como.version
         Como::VERSION
     end

data/test/como_type_prim

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+
+require "../lib/como"
+include Como
+
+Spec.command( "como_type_prim", "Como Tester", "2013",
+  [
+    [ [ :none, :opt, :mutex ], "doc", nil, "Documentation for option\n\twith too much description\n\tfor one line." ],
+    [ [ :one ], "file", "-f", "File argument." ],
+    [ :switch, "debug", nil, "Enable debugging." ],
+    [ [ :one, :opt ], "mode", "-m", "Mode." ],
+    [ [ :one, :many, :opt ], "params", nil, "Parameters." ],
+    [ [ :none, :one, :many, :opt ], "types", "-t", "Types." ],
+    [ [ :none, :opt, :hidden ], "terminator", "-", "The terminator." ],
+    [ [ :one, :many ], "dir", "-d", "Directory argument(s)." ],
+    [ :default, "Leftovers." ],
+  ] )
+
+
+Opt.each do |o|
+    puts "Given \"#{o.name}\": #{o.given}"
+    puts "Value \"#{o.name}\": #{o.value}" if o.given && o.value
+end
+
+if Opt.external
+    puts "External: #{Opt.external}"
+end

data/test/golden/compatible.txt

@@ -2,7 +2,7 @@
 
 como_compatible error: Option "-f" missing for "como_compatible"...
 
-  como_compatible [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_compatible [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc       Documentation.
   -f          File argument.
@@ -32,7 +32,7 @@ Given "<default>": false
 
 como_compatible error: No argument given for "-f"...
 
-  como_compatible [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_compatible [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc       Documentation.
   -f          File argument.
@@ -63,7 +63,7 @@ Given "<default>": false
 
 como_compatible error: No argument given for "-f"...
 
-  como_compatible [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_compatible [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc       Documentation.
   -f          File argument.
@@ -81,7 +81,7 @@ como_compatible error: No argument given for "-f"...
 
 como_compatible error: Option "-d" missing for "como_compatible"...
 
-  como_compatible [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_compatible [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc       Documentation.
   -f          File argument.
@@ -99,7 +99,7 @@ como_compatible error: Option "-d" missing for "como_compatible"...
 
 como_compatible error: No argument given for "-d"...
 
-  como_compatible [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_compatible [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc       Documentation.
   -f          File argument.
@@ -334,7 +334,7 @@ External: ["external", "arguments"]
 
 como_compatible error: Option "-d" missing for "como_compatible"...
 
-  como_compatible [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_compatible [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc       Documentation.
   -f          File argument.
@@ -352,7 +352,7 @@ como_compatible error: Option "-d" missing for "como_compatible"...
 
 como_compatible error: Option "-d" missing for "como_compatible"...
 
-  como_compatible [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_compatible [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc       Documentation.
   -f          File argument.
@@ -370,7 +370,7 @@ como_compatible error: Option "-d" missing for "como_compatible"...
 
 como_compatible error: Unknown option "-q"...
 
-  como_compatible [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_compatible [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc       Documentation.
   -f          File argument.
@@ -388,7 +388,7 @@ como_compatible error: Unknown option "-q"...
 
 como_compatible error: No argument given for "-d"...
 
-  como_compatible [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_compatible [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc       Documentation.
   -f          File argument.
@@ -417,7 +417,7 @@ Value "dir": ["dir"]
 Given "<default>": false
 ---- CMD: como_compatible -f foo -d dir -h
 
-  como_compatible [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_compatible [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc       Documentation.
   -f          File argument.
@@ -433,7 +433,7 @@ Given "<default>": false
 
 ---- CMD: como_compatible -h -f foo -d dir
 
-  como_compatible [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_compatible [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc       Documentation.
   -f          File argument.

data/test/golden/config.txt

@@ -27,7 +27,7 @@ como_config error: No argument given for "-f"...
 
 Additional heading info.
 
-  como_config [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_config [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc     Documentation.
   -f        File argument.
@@ -62,7 +62,7 @@ como_config error: No argument given for "-f"...
 
 Additional heading info.
 
-  como_config [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_config [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc     Documentation.
   -f        File argument.
@@ -96,7 +96,7 @@ como_config error: No argument given for "-d"...
 
 Additional heading info.
 
-  como_config [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_config [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc     Documentation.
   -f        File argument.
@@ -155,7 +155,7 @@ Given "<default>": false
 
 Additional heading info.
 
-  como_config [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_config [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc     Documentation.
   -f        File argument.
@@ -185,7 +185,7 @@ Given "<default>": false
 
 Additional heading info.
 
-  como_config [--doc] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
+  como_config [--doc <doc>*] -f <file> [--debug] [-m <mode>] [--params <params>+] [-t <types>*] -d <dir>+ [<default>]
 
   --doc     Documentation.
   -f        File argument.