nub 0.0.55 → 0.0.56

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6492bcf60374552fe23049d74396793bccae8f0e11ed9521d58feb19bc592da
-  data.tar.gz: 1113ee70f0fdef09151c7551c840dec18142af299efc7938050f49e3579e714b
+  metadata.gz: 6840a65c5b757eb9cf92cdbfd1548577f2a0abf4b91470477cb133a048259372
+  data.tar.gz: 3c5dd5de7ce42a2a2ba91b4ac2d5aa6cf773cda0320723bdd13f79ddbd918de8
 SHA512:
-  metadata.gz: ab873f93ede81f44697af52730f61035503a0290769f132f22118567096c1910b94a4adcd4c77b657bb68167dc6303a52bda1f6ab06b1d23be1e5f5bf1b4cc28
-  data.tar.gz: 39fe7de14e98f37b1f2d224691c801aed3c27ff44731595bc0c72a76255a2e3f847b86e6f29a7e0632c75f028860fc61bf602ce4b58de9f8f09c54e3f81885bb
+  metadata.gz: 20051bea8cd2af4aa22c09683673e3a99c6deb0b3e166c6e18175c7e87d96035ce3497b38337de3956274879ad52a47cb172bd80eee7f3be7b2030278c4ddb84
+  data.tar.gz: eddef00f72ad07ab8b384317113633d5256d489221f8411128e0db86dbee7da51c514264b93c8c3d749f0ae391d9d2f4d93396fd5806988c254118f44bc14f12

data/README.md

@@ -10,53 +10,95 @@ Collection of ruby utils I've used in several of my projects and wanted re-usabl
 ### Table of Contents
 * [Deploy](#deploy)
 * [Commander](#commander)
-    * [Commands](#commands)
-    * [Options](#options)
-    * [Help](#help)
+  * [Commands](#commands)
+    * [Command Parameters ](#command-paramaters)
+    * [Chained Commands](#chained-commands)
+  * [Options](#options)
+    * [Positional Options](#positional-options)
+    * [Value Types](#value-types)
+    * [Allowed Values](#allowed-values)
+    * [Global Options](#global-options)
+  * [Configuration](#configuration)
+  * [Help](#help)
+    * [Examples](#examples)
+    * [Indicators](#indicators)
 * [Config](#config)
 * [Ruby Gem Creation](#ruby-gem-creation)
-    * [Package Layout](#package-layout)
-    * [Build Gem](#build-gem)
-    * [Install Gem](#install-gem)
-    * [Push Gem](#push-gem)
+  * [Package Layout](#package-layout)
+  * [Build Gem](#build-gem)
+  * [Install Gem](#install-gem)
+  * [Push Gem](#push-gem)
 * [Integrate with Travis-CI](#integrate-with-travis-ci)
-    * [Install Travis Client](#install-travis-client)
-    * [Deploy Ruby Gem on Tag](#deploy-ruby-gem-on-tag)
+  * [Install Travis Client](#install-travis-client)
+  * [Deploy Ruby Gem on Tag](#deploy-ruby-gem-on-tag)
  
 ## Deploy <a name="deploy"></a>
 Run: `bundle install --system`
 
 ## Commander <a name="commander"></a>
-Commander was created mainly because all available options parsers seemed complicated and overweight
-and partly because I enjoyed understanding every bit going into it. Commander offers ***git*** like
-command syntax that is becoming so popular. Personally I like the syntax as it feels cleaner and
-faster to type.
+Commander was created mainly because all available options parsers seemed overly complicated and
+overweight and partly because I enjoyed understanding every bit going into it. Commander offers
+***git*** like command syntax that is becoming so popular.
 
 There are two kinds of paramaters that commander deals with ***commands*** and ***options***.
-Commands are specific named parameters that may or may not have options specific to it. Commands
-have their own help to display their usage and available options.
 
 ### Commands <a name="commands"></a>
-Commands are defined via configuration as key words that trigger different branches of functionality
-for the application. Each command may have zero or more options that modify how this behaveior is
-invoked. Whenever more than one command is used in the command line expression the expression is
-interpreted as being a ***chained command expression***. Chained command expressions are executed
-left to right, such that you can execute the ***clean*** command then the ***build*** command or
-more in a single command line expression. Each command in a chained command expression may have its
-own specific options (those coming after the command but before the next command) or if options are
-omitted the required options from the next command will be used. The chained command options syntax
-allows one to have a cleaner multi-command line expression with reusable options. Options are said
-to apply in a chained command syntax when they are of the same type and position in the positional
-case or same type and name in the named case.
+Commands are specific named parameters that may or may not have options specific to it. Commands
+have their own help to display their usage and available options. Commands are used to trigger
+different branches of functionality in an application.
+
+#### Command Parameters <a name="command-parameters"></a>
+Each command may have zero or more command parameters. Command parameters may be either a
+sub-command, which follow the same rules in a recursive fashion as any command, or an option.
+Command options modify how the command behaves.
 
+#### Chained Commands <a name="chained-commands"></a>
+The chained command expressions allow a cleaner multi-command type expression with reusable options.
+
+Whenever more than one command is used in the command line expression the expression is interpreted
+as being a ***chained command expression*** a.k.a ***chained commands***. Chained commands are
+executed left to right, such that you can execute the first command then the second command or more
+in a single command line expression. Each command in a chained command expression may have its own
+specific options (those coming after the command but before the next command) or if options are
+omitted the options from the next command will be used in the order they are given to satisfy the
+options of the command before. Only options of the same type and position will be used.
+
+### Options <a name="options"></a>
+Options are additional parameters that are given that modify the behavior of a command. There are
+two kinds of options available for use, ***positional*** and ***named***.
+
+#### Positional Options <a name="positional-options"></a>
+Positional options are identified by the absence of preceding dash/dashes and are interpreted
+according to the order in which they were found. Positional options always pass a value into the
+application. Positional options are named internally with the command name concatted with a zero
+based int representing its order ***e.g. clean0*** where *clean* is the command name and *0* is the
+positional options order given during configuration. Positional options are given sequentially so
+you can't skip one and specify the second, it must be one then two etc...
+
+#### Named Options
+Named options have a name that is prefixed with a dash (short hand) or two dashes (long hand) e.g.
+***-h*** or ***--help*** and may be a value passed in or simply a boolean flag. **Long Hand** form
+is always required for named options, short hand may or may not be given. An incoming
+**value/values** are indicated by the hint configuration e.g. ***-s|--skip=COMPONENTS*** indicates
+there is an incoming value/values to be expected because of the hint ***COMPONENTS***.
+
+#### Value Types <a name="value-types"></a>
+Option values require a ***type*** so that Commander can interpret how to use them. The supported
+value types are ***true, false, Integer, String, Array***. Positional options default to
+type String while named options default to false. The named option flag default of false can be
+changed to default to true by setting the ***type:true*** configuration param.
+
+#### Allowed Values <a name="allowed-values"></a>
+Commander will check the values given against an allowed list if so desired. This is done via the 
+***allowed*** configuration parameter.
+
+#### Global Options <a name="global-options"></a>
 ***Global*** options are options that are added with the ***add_global*** function and will show up
 set in the command results using the ***:global*** symbol. Global positional options must be given
 before any other commands but global named options may appear anywhere in the command line
 expression.
 
-***Shared*** options are options that are added with the command ***add_shared*** function. They
-should be added before any commands are added. They are added to each command as an explicit option.
-
+### Configuration <a name="configuration"></a>
 ***Commander.new*** must be run from the app's executable file for it to pick up the app's filename
 properly.
 
@@ -98,24 +140,6 @@ Example command line expressions:
 ./app clean all build all
 ```
 
-### Options <a name="options"></a>
-There are two kinds of options available for use, ***positional*** and ***named***. Positional
-options are identified by the absence of preceding dash/dashes and interpreted according to the
-order and number in which they were found. Positional options are a value being passed into the
-application.  Named options have a name that is prefixed with a dash (short hand) or two dashes
-(long hand) e.g.  ***-h*** or ***--help*** and may simply be a flag or pass in a value. Option
-values require a ***type*** so that Commander can interpret how to use them. The supported value
-types are ***Flag, Integer, String, Array***. Values may be checked or not checked via the
-***allowed*** config param. Positional options default to type String while named options default to
-type Flag.  Positional options are named internally with the command concatted with a an int for
-order ***e.g.  clean0*** zero based. Positional options are given sequentially so you can't
-skip one and specify the second, it must be one then two etc...
-
-**Long Hand** form is always required for named options, short hand may or may not be given.
-
-**Values** are indicated by the hint given e.g. ***-s|--skip=COMPONENTS*** indicates there is an
-incoming value/values to be expected because of the hint ***COMPONENTS***.
-
 Example ruby configuration:
 ```ruby
 # Creates a new instance of commander with app settings as given
@@ -155,10 +179,15 @@ Example command line expressions:
 ### Help <a name="help"></a>
 Help for your appliation and commands is automatically supported with the ***-h*** and ***--help***
 flags and is generated from the app ***name***, ***version***, ***examples***, ***commands***,
-***descriptions*** and ***options*** given in Commander's configuration. Examples is just a free
-form string that is displayed before usage so user's have an idea of how to put together the
-commands and options. Allowed checks are added to the end of option descriptions in parenthesis.
-Type and required indicators are added after allowed check descriptions.
+***descriptions*** and ***options*** given in Commander's configuration.
+
+#### Examples <a name="examples"></a>
+Examples is just a free form string that is displayed before usage so user's have an idea of how to
+put together the commands and options.
+
+#### Indicators <a name="indicators"></a>
+Allowed checks, types, and required flags specified in the configuration are known as indicators in
+the help context and are added to the end of the option descriptions.
 
 Example ruby configuration:
 ```ruby
@@ -235,9 +264,6 @@ Usage: ./builder build [options]
     -h|--help                           Print command/options help
 ```
 
-**Required**
-Options can be required using the ***required:true*** options param
-
 ## Config <a name="config"></a>
 Config is a simple YAML wrapper with some extra features. Since it implements the ***Singleton***
 pattern you can easily use it through out your app without carrying around instances everywhere.

data/lib/nub/commander.rb

@@ -18,8 +18,8 @@
 #LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 #OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 #SOFTWARE.
-
 require 'colorize'
+require 'ostruct'
 require_relative 'log'
 require_relative 'sys'
 require_relative 'string'
@@ -34,26 +34,26 @@ class Option
   attr_reader(:type)
   attr_accessor(:allowed)
   attr_accessor(:required)
-  attr_accessor(:shared)
 
   # Create a new option instance
   # @param key [String] option short hand, long hand and hint e.g. -s|--skip=COMPONENTS
   # @param desc [String] the option's description
   # @param type [Type] the option's type
   # @param required [Bool] require the option if true else optional
-  # @param allowed [Array] array of allowed string values
-  def initialize(key, desc, type:nil, required:false, allowed:[])
+  # @param allowed [Hash] hash of allowed strings to descriptions maps
+  def initialize(key, desc, type:nil, required:false, allowed:{})
     @hint = nil
     @long = nil
     @short = nil
     @desc = desc
-    @shared = false
-    @allowed = allowed || []
+    @allowed = allowed || {}
     @required = required || false
+    Log.die("allowed should be a hash of values to descriptions") if allowed.class != Hash
+    Log.die("required should be a boolean value") if ![TrueClass, FalseClass].include?(required.class)
 
     # Parse the key into its components (short hand, long hand, and hint)
     #https://bneijt.nl/pr/ruby-regular-expressions/
-    # Valid forms to look for with chars [a-zA-Z0-9-_=|] 
+    # Valid forms to look for with chars [a-zA-Z0-9-_=|]
     # --help, --help=HINT, -h|--help, -h|--help=HINT
     Log.die("invalid option key #{key}") if key && (key.count('=') > 1 or key.count('|') > 1 or !key[/[^\w\-=|]/].nil? or
       key[/(^--[a-zA-Z0-9\-_]+$)|(^--[a-zA-Z\-_]+=\w+$)|(^-[a-zA-Z]\|--[a-zA-Z0-9\-_]+$)|(^-[a-zA-Z]\|--[a-zA-Z0-9\-_]+=\w+$)/].nil?)
@@ -64,22 +64,72 @@ class Option
       @long = key[/(--[\w\-]+)(=.+)*$/, 1]
     end
 
-    # Validate and set type
-    Log.die("invalid option type #{type}") if ![String, Integer, Array, nil].any?{|x| type == x}
+    # Convert true/false to TrueClass/FalseClass
+    type = TrueClass if type.class == TrueClass
+    type = FalseClass if type.class == FalseClass
+
+    # Validate and set type, allow Flag defaults to be true or false
+    Log.die("invalid option type #{type}") if ![String, Integer, Array, TrueClass, FalseClass, nil].any?{|x| type == x}
     Log.die("option type must be set") if @hint && !type
     @type = String if !key && !type
     @type = FalseClass if key and !type
     @type = type if type
 
     # Validate hint is given for non flags
-    Log.die("option hint must be set") if @key && !@hint && @type != FalseClass
+    Log.die("option hint must be set") if @key && !@hint && @type != FalseClass && @type != TrueClass
 
     # Validate allowed
     if @allowed.any?
-      allowed_type = @allowed.first.class
-      Log.die("mixed allowed types") if @allowed.any?{|x| x.class != allowed_type}
+      allowed_type = @allowed.first.first.class
+      Log.die("mixed allowed types") if @allowed.any?{|k,v| k.class != allowed_type}
     end
   end
+
+  # Get a symbol representing the command
+  # @returns symbol
+  def to_sym
+    return @long[2..-1].gsub("-", "_").to_sym
+  end
+
+  # Return a human readable string of this object
+  # @param level [Integer] level to indent
+  def to_s(level:0)
+    return "#{" " * level * 2}Option => key:#{@key}, desc:'#{@desc}', type:#{@type}, allowed:#{@allowed}, required:#{@required}"
+  end
+end
+
+class Command
+  attr_reader(:name)
+  attr_reader(:desc)
+  attr_accessor(:nodes)
+  attr_accessor(:help)
+
+  # Create a new command
+  # @param name [String] command name used on command line
+  # @param desc [String] the command's description
+  # @param nodes [String] the command's description
+  def initialize(name, desc, nodes:[])
+    @name = name
+    @desc = desc
+    @nodes = nodes
+    @help = ""
+  end
+
+  # Get a symbol representing the command
+  # @returns symbol
+  def to_sym
+    return @name.gsub('-', '_').to_sym
+  end
+
+  # Return a human readable string of this object
+  # @param level [Integer] level to indent
+  def to_s(level:0)
+    str = "#{" " * level * 2}Command => name:#{@name}, desc:'#{@desc}'"
+    @nodes.each{|x|
+      str += "\n#{x.to_s(level: level + 1)}"
+    }
+    return str
+  end
 end
 
 # An implementation of git like command syntax for ruby applications:
@@ -89,13 +139,15 @@ class Commander
   attr_reader(:banner)
   attr_accessor(:cmds)
 
-  Command = Struct.new(:name, :desc, :opts, :help)
-
   # Initialize the commands for your application
   # @param app [String] application name e.g. reduce
   # @param version [String] version of the application e.g. 1.0.0
   # @param examples [String] optional examples to list after the title before usage
   def initialize(app:nil, version:nil, examples:nil)
+    @k = OpenStruct.new({
+      global: 'global'
+    })
+
     @app = app
     @app_default = Sys.caller_filename
     @version = version
@@ -107,18 +159,15 @@ class Commander
     @long_regex = /(--[\w\-]+)(=.+)*$/
     @value_regex = /.*=(.*)$/
 
-    # Incoming user set commands/options
+    # Command line expression results
     # {command_name => {}}
     @cmds = {}
 
     # Configuration - ordered list of commands
     @config = []
 
-    # List of options that will be added to all commands
-    @shared = []
-
     # Configure default global options
-    add_global(Option.new('-h|--help', 'Print command/options help'))
+    add_global('-h|--help', 'Print command/options help')
   end
 
   # Hash like accessor for checking if a command or option is set
@@ -134,44 +183,41 @@ class Commander
   # Add a command to the command list
   # @param cmd [String] name of the command
   # @param desc [String] description of the command
-  # @param opts [List] list of command options
-  def add(cmd, desc, options:[])
-    Log.die("'global' is a reserved command name") if cmd == 'global'
-    Log.die("'shared' is a reserved command name") if cmd == 'shared'
+  # @param nodes [List] list of command nodes (i.e. options or commands)
+  def add(cmd, desc, nodes:[])
+    Log.die("'#{@k.global}' is a reserved command name") if cmd == @k.global
     Log.die("'#{cmd}' already exists") if @config.any?{|x| x.name == cmd}
-    Log.die("'help' is a reserved option name") if options.any?{|x| !x.key.nil? && x.key.include?('help')}
-
-    # Add shared options
-    @shared.each{|x| options.unshift(x)}
+    Log.die("'help' is a reserved option name") if nodes.any?{|x| x.class == Option && !x.key.nil? && x.key.include?('help')}
+    Log.die("command names must be pure lowercase letters or hypen") if cmd =~ /[^a-z-]/
+
+    # Validate sub command key words
+    validate_subcmd = ->(subcmd){
+      subcmd.nodes = [] if !subcmd.nodes
+      Log.die("'#{@k.global}' is a reserved command name") if subcmd.name == @k.global
+      Log.die("'help' is a reserved option name") if subcmd.nodes.any?{|x| x.class == Option && !x.key.nil? && x.key.include?('help')}
+      Log.die("command names must be pure lowercase letters or hypen") if subcmd.name =~ /[^a-z-]/
+      subcmd.nodes.select{|x| x.class != Option}.each{|x| validate_subcmd.(x)}
+    }
+    nodes.select{|x| x.class != Option}.each{|x| validate_subcmd.(x)}
 
-    cmd = add_cmd(cmd, desc, options)
-    @config << cmd
+    @config << add_cmd(cmd, desc, nodes)
   end
 
   # Add global options (any option coming before all commands)
-  # @param option/s [Array/Option] array or single option/s
-  def add_global(options)
-    options = [options] if options.class == Option
+  # @param key [String] option short hand, long hand and hint e.g. -s|--skip=COMPONENTS
+  # @param desc [String] the option's description
+  # @param type [Type] the option's type
+  # @param required [Bool] require the option if true else optional
+  # @param allowed [Hash] hash of allowed values to description map
+  def add_global(key, desc, type:nil, required:false, allowed:{})
+    options = [Option.new(key, desc, type:type, required:required, allowed:allowed)]
 
     # Aggregate global options
-    if (global = @config.find{|x| x.name == 'global'})
-      global.opts.each{|x| options << x}
-      @config.reject!{|x| x.name == 'global'}
+    if (global = @config.find{|x| x.name == @k.global})
+      global.nodes.each{|x| options << x}
+      @config.reject!{|x| x.name == @k.global}
     end
-    @config << add_cmd('global', 'Global options:', options)
-  end
-
-  # Add shared option (options that are added to all commands)
-  # @param option/s [Array/Option] array or single option/s
-  def add_shared(options)
-    options = [options] if options.class == Option
-    options.each{|x|
-      Log.die("duplicate shared option '#{x.desc}' given") if @shared
-        .any?{|y| y.key == x.key && y.desc == x.desc && y.type == x.type}
-      x.shared = true
-      x.required = true
-      @shared << x
-    }
+    @config << add_cmd(@k.global, 'Global options:', options)
   end
 
   # Returns banner string
@@ -185,6 +231,8 @@ class Commander
   # Return the app's help string
   # @return [String] the app's help string
   def help
+
+    # Global help
     help = @app.nil? ? "" : "#{banner}\n"
     if !@examples.nil? && !@examples.empty?
       newline = @examples.strip_color[-1] != "\n" ? "\n" : ""
@@ -192,9 +240,9 @@ class Commander
     end
     app = @app || @app_default
     help += "Usage: ./#{app} [commands] [options]\n"
-    help += @config.find{|x| x.name == 'global'}.help
+    help += @config.find{|x| x.name == @k.global}.help
     help += "COMMANDS:\n"
-    @config.select{|x| x.name != 'global'}.each{|x| help += "    #{x.name.ljust(@just)}#{x.desc}\n" }
+    @config.select{|x| x.name != @k.global}.each{|x| help += "    #{x.name.ljust(@just)}#{x.desc}\n" }
     help += "\nsee './#{app} COMMAND --help' for specific command help\n"
 
     return help
@@ -202,94 +250,22 @@ class Commander
 
   # Construct the command line parser and parse
   def parse!
-    cmd_names = @config.map{|x| x.name }
+
+    # Clear out the previous run every time, in case run more than once
+    @cmds = {}
 
     # Set help if nothing was given
     ARGV.clear and ARGV << '-h' if ARGV.empty?
-    
-    # Process command options
-    #---------------------------------------------------------------------------
-    order_globals!
-    expand_chained_options!
-    loop {
-      break if ARGV.first.nil?
-
-      if !(cmd = @config.find{|x| x.name == ARGV.first}).nil?
-        @cmds[ARGV.shift.to_sym] = {}             # Create command results entry
-        cmd_names.reject!{|x| x == cmd.name}      # Remove command from possible commands
-
-        # Collect command options from args to compare against
-        opts = ARGV.take_while{|x| !cmd_names.include?(x) }
-        ARGV.shift(opts.size)
- 
-        # Handle help upfront before anything else
-        if opts.any?{|x| m = match_named(x, cmd); m.hit? && m.sym == :help }
-          !puts(help) and exit if cmd.name == 'global'
-          !puts(cmd.help) and exit
-        end
 
-        # Check that all required options were given
-        cmd_pos_opts = cmd.opts.select{|x| x.key.nil? }
-        cmd_named_opts = cmd.opts.select{|x| !x.key.nil? }
-
-        !puts("Error: positional option required!".colorize(:red)) && !puts(cmd.help) and
-          exit if opts.select{|x| !x.start_with?('-')}.size < cmd_pos_opts.select{|x| x.required}.size
-
-        named_opts = opts.select{|x| x.start_with?('-')}
-        cmd_named_opts.select{|x| x.required}.each{|x|
-          !puts("Error: required option #{x.key} not given!".colorize(:red)) && !puts(cmd.help) and
-            exit if !named_opts.find{|y| y.start_with?(x.short) || y.start_with?(x.long)}
-        }
-
-        # Process command options
-        pos = -1
-        loop {
-          break if opts.first.nil?
-          opt = opts.shift
-          cmd_opt = nil
-          value = nil
-          sym = nil
-
-          # Validate/set named options
-          # --------------------------------------------------------------------
-          # e.g. -s, --skip, --skip=VALUE
-          if (match = match_named(opt, cmd)).hit?
-            sym = match.sym
-            cmd_opt = match.opt
-            value = match.value
-            value = match.flag? || opts.shift if !value
-
-          # Validate/set positional options
-          # --------------------------------------------------------------------
-          else
-            pos += 1
-            value = opt
-            cmd_opt = cmd_pos_opts.shift
-            !puts("Error: invalid positional option '#{opt}'!".colorize(:red)) && !puts(cmd.help) and
-              exit if cmd_opt.nil? || cmd_names.include?(value)
-            sym = "#{cmd.name}#{pos}".to_sym
-          end
-
-          # Convert value to appropriate type and validate against allowed
-          # --------------------------------------------------------------------
-          value = convert_value(value, cmd, cmd_opt)
-
-          # Set option with value
-          # --------------------------------------------------------------------
-          !puts("Error: unknown named option '#{opt}' given!".colorize(:red)) && !puts(cmd.help) and exit if !sym
-          @cmds[cmd.name.to_sym][sym] = value
-          if cmd_opt.shared
-            sym = "shared#{pos}".to_sym if cmd_opt.key.nil?
-            @cmds[:shared] = {} if !@cmds.key?(:shared)
-            @cmds[:shared][sym] = value
-          end
-        }
-      end
-    }
+    # Parse commands recursively
+    move_globals_to_front!
+    expand_chained_options!
+    while (cmd = @config.find{|x| x.name == ARGV.first})
+      ARGV.shift && parse_commands(cmd, nil, @config.select{|x| x.name != cmd.name}, ARGV, @cmds)
+    end
 
-    # Ensure specials (global, shared) are always set
+    # Ensure specials (global) are always set
     @cmds[:global] = {} if !@cmds[:global]
-    @cmds[:shared] = {} if !@cmds[:shared]
 
     # Ensure all options were consumed
     Log.die("invalid options #{ARGV}") if ARGV.any?
@@ -307,15 +283,132 @@ class Commander
       return !!sym
     end
     def flag?
-      return opt.type == FalseClass
+      return opt.type == FalseClass || opt.type == TrueClass
+    end
+  end
+
+  # Parse the given args recursively
+  # @param cmd [Command] command to work with
+  # @param parent [Command] command to work with
+  # @param others [Array] sibling cmds to cmd
+  # @param args [Array] array of arguments
+  # @param results [Hash] of cmd results
+  def parse_commands(cmd, parent, others, args, results)
+    results[cmd.to_sym] = {}                            # Create command results entry
+    cmd_names = others.map{|x| x.name}                  # Get other command names as markers
+    subcmds = cmd.nodes.select{|x| x.class == Command}  # Get sub-commands for this command
+
+    # Collect all params until the next sibling command
+    #---------------------------------------------------------------------------
+    params = args.take_while{|x| !cmd_names.include?(x)}
+    args.shift(params.size)
+
+    # Strip off this command's preceeding options
+    opts = subcmds.any? ? params.take_while{|x| !subcmds.any?{|y| x == y.name}} : params
+    otherparams = params[opts.size..-1]
+
+    #---------------------------------------------------------------------------
+    # Handle sub-commands recursively first
+    #---------------------------------------------------------------------------
+    while subcmds.any? && (subcmd = subcmds.find{|x| x.name == otherparams.first})
+      otherparams.shift                             # Consume sub-cmd from opts
+      subcmds.reject!{|x| x.name == subcmd.name}    # Drop sub-command from further use
+      parse_commands(subcmd, cmd, subcmds, otherparams, results[cmd.to_sym])
+    end
+
+    # Account for any left over options
+    otherparams.reverse.each{|x| opts.unshift(x)}
+
+    #---------------------------------------------------------------------------
+    # Base case: dealing with options for a given command.
+    # Only consume options for this command and bubble up unused to parent
+    #---------------------------------------------------------------------------
+
+    # Handle help upfront before anything else
+    #---------------------------------------------------------------------------
+    if opts.any?{|x| m = match_named(x, cmd); m.hit? && m.sym == :help }
+      !puts(help) and exit if cmd.name == @k.global
+      !puts(cmd.help) and exit
+    end
+
+    # Parse/consume named options first
+    #---------------------------------------------------------------------------
+
+    # Check that all required named options were given
+    cmd.nodes.select{|x| x.class == Option && !x.key.nil? && x.required}.each{|x|
+      !puts("Error: required option #{x.key} not given!".colorize(:red)) && !puts(cmd.help) and
+        exit if !match_named(x, opts).hit?
+    }
+
+    # Consume and set all named options
+    i = 0 
+    while i < opts.size
+      if (match = match_named(opts[i], cmd)).hit?
+        value = match.flag? || match.value  # Inline or Flag value
+
+        # Separate value
+        separate = false
+        if !value && i + 1 < opts.size
+          separate = true
+          value = opts[i + 1]
+        elsif !value
+          !puts("Error: named option '#{opts[i]}' value not found!".colorize(:red)) and
+            !puts(cmd.help) and exit
+        end
+
+        # Set result and consume options
+        results[cmd.to_sym][match.sym] = convert_value(value, cmd, match.opt)
+        opts.delete_at(i)                   # Consume option
+        opts.delete_at(i) if separate       # Consume separate value
+      else
+        i += 1
+      end
+    end
+
+    # Parse/consume positional options next
+    #---------------------------------------------------------------------------
+    cmd_pos_opts = cmd.nodes.select{|x| x.class == Option && x.key.nil?}
+
+    # Check that all required positionals were given
+    !puts("Error: positional option required!".colorize(:red)) && !puts(cmd.help) and
+      exit if opts.select{|x| !x.start_with?('-')}.size < cmd_pos_opts.select{|x| x.required}.size
+
+    # Consume and set all positional options
+    i = 0
+    pos = -1
+    while i < opts.size && cmd_pos_opts.any?
+      if !opts[i].start_with?('-')
+        pos += 1
+        cmd_opt = cmd_pos_opts.shift
+        !puts("Error: invalid positional option '#{opts[i]}'!".colorize(:red)) and 
+          !puts(cmd.help) and exit if cmd_opt.nil?
+
+        # Set result and consume options
+        results[cmd.to_sym]["#{cmd.to_sym}#{pos}".to_sym] = convert_value(opts[i], cmd, cmd_opt)
+        opts.delete_at(i)                   # Consume option
+      else
+        i += 1
+      end
+    end
+
+    # Add any unconsumed options back to parent to ensure everything is accounted for
+    if parent
+      opts.reverse.each{|x| args.unshift(x)}
+    else
+      opts.each{|x|
+        !puts("Error: invalid positional option '#{x}'!".colorize(:red)) and 
+          !puts(cmd.help) and exit if !x.start_with?('-')
+        !puts("Error: invalid named option '#{x}'!".colorize(:red)) and
+          !puts(cmd.help) and exit if x.start_with?('-')
+      }
     end
   end
 
   # Parses the command line, moving all global options to the begining
   # and inserting the global command
-  def order_globals!
-    if !(global_cmd = @config.find{|x| x.name == 'global'}).nil?
-      ARGV.delete('global')
+  def move_globals_to_front!
+    if !(global_cmd = @config.find{|x| x.name == @k.global}).nil?
+      ARGV.delete(@k.global)
 
       # Collect positional and named options from begining
       globals = ARGV.take_while{|x| !@config.any?{|y| y.name == x}}
@@ -324,7 +417,7 @@ class Commander
       # Collect named options throughout
       i = -1
       cmd = nil
-      while (i += 1) < ARGV.size do
+      while (i += 1) < ARGV.size
 
         # Set command and skip command and matching options
         if !(_cmd = @config.find{|x| x.name == ARGV[i]}).nil?
@@ -342,7 +435,7 @@ class Commander
 
       # Re-insert options in correct order at end with command
       globals.reverse.each{|x| ARGV.unshift(x)}
-      ARGV.unshift('global')
+      ARGV.unshift(@k.global)
     end
   end
 
@@ -352,66 +445,118 @@ class Commander
   def expand_chained_options!
     args = ARGV[0..-1]
     results = {}
-    cmd_names = @config.map{|x| x.name }
-    
+    cmd_order = []
+    cmd_names = @config.map{|x| x.name}
+
     chained = []
-    while args.any? do
+    while args.any?
       if !(cmd = @config.find{|x| x.name == args.first}).nil?
-        results[args.shift] = []                            # Add the command to the results
-        cmd_names.reject!{|x| x == cmd.name}                # Remove command from possible commands
-        cmd_required = cmd.opts.select{|x| x.required}
+        cmd_order << args.shift                   # Maintain oder of given commands
+        results[cmd.name] = []                    # Add the command to the results
+        cmd_names.reject!{|x| x == cmd.name}      # Remove command from possible commands
 
         # Collect command options from args to compare against
         opts = args.take_while{|x| !cmd_names.include?(x)}
         args.shift(opts.size)
 
         # Globals are not to be considered for chaining
-        results[cmd.name].concat(opts) and next if cmd.name == 'global'
+        results[cmd.name].concat(opts) and next if cmd.name == @k.global
 
-        # Chained case is when no options are given but some are required
-        if opts.size == 0 && cmd.opts.any?{|x| x.required}
+        # Chained case is when no options are given but the command has options
+        cmd_options = cmd.nodes.select{|x| x.class == Option}
+        if opts.size == 0 && cmd_options.any?
           chained << cmd
         else
           # Add cmd with options
           results[cmd.name].concat(opts)
 
-          # Check chained cmds against current cmd
-          chained.each{|x|
-            other_required = x.opts.select{|x| x.required}
-            !puts("Error: chained commands must satisfy required options!".colorize(:red)) && !puts(x.help) and
-              exit if cmd_required.size < other_required.size
-            other_required.each_with_index{|y,i|
-              !puts("Error: chained command options are not type consistent!".colorize(:red)) && !puts(x.help) and
-                exit if y.type != cmd_required[i].type || y.key != cmd_required[i].key
-            }
-            results[x.name].concat(opts.take(other_required.size))
+          # Add applicable options to chained as well
+          chained.each{|other|
+            _opts = opts[0..-1]
+            named_results = []
+            positional_results = []
+
+            # Add all matching named options
+            #-------------------------------------------------------------------
+            i = 0 
+            while i < _opts.size
+              if (match = match_named(_opts[i], other)).hit?
+                named_results << _opts[i];
+                _opts.delete_at(i)
+
+                # Get the next option to as the value was separate
+                if i < _opts.size && !(match.flag? || match.value)
+                  named_results << _opts[i]
+                  _opts.delete_at(i)
+                end
+              else
+                i += 1
+              end
+            end
+
+            # Add all matching positional options
+            #-------------------------------------------------------------------
+            i = 0
+            other_positional = other.nodes.select{|x| x.class == Option && x.key.nil?}
+            while i < _opts.size
+              if !_opts[i].start_with?('-') && other_positional.any?
+                positional_results << _opts[i]
+                other_positional.shift
+                _opts.delete_at(i)
+              else
+                i += 1
+              end
+            end
+
+            positional_results.each{|x| results[other.name] << x}
+            named_results.each{|x| results[other.name] << x}
           }
         end
       end
     end
 
     # Set results as new ARGV command line expression
-    ARGV.clear and results.each{|k, v| ARGV << k; ARGV.concat(v)}
+    ARGV.clear and cmd_order.each{|x| ARGV << x; ARGV.concat(results[x]) }
   end
 
   # Match the given command line arg with a configured named option
-  # @param opt [String] the command line argument given
-  # @param cmd [Command] configured command to match against
+  # or match configured named option against a list of command line args
+  # @param arg [String/Option] the command line argument or configured Option
+  # @param other [Command/Array] configured command or command line args
   # @return [OptionMatch]] struct with some helper functions
-  def match_named(opt, cmd)
-    match = OptionMatch.new(opt)
-    cmd_named_opts = cmd.opts.select{|x| !x.key.nil? }
-
-    if opt.start_with?('-')
-      short = opt[@short_regex, 1]
-      long = opt[@long_regex, 1]
-      match.value = opt[@value_regex, 1]
-
-      # Set symbol converting dashes to underscores for named options
-      if (cmd_opt = cmd_named_opts.find{|x| x.short == short || x.long == long})
-        match.opt = cmd_opt
-        match.sym = cmd_opt.long[2..-1].gsub("-", "_").to_sym
+  def match_named(arg, other)
+    match = OptionMatch.new
+
+    # Match command line arg against command options
+    if arg.class == String && other.class == Command
+      match.arg = arg
+      options = other.nodes.select{|x| x.class == Option && !x.key.nil? }
+
+      if arg.start_with?('-')
+        short = arg[@short_regex, 1]
+        long = arg[@long_regex, 1]
+        match.value = arg[@value_regex, 1]
+
+        # Set symbol converting dashes to underscores for named options
+        if (match.opt = options.find{|x| x.short == short || x.long == long})
+          match.sym = match.opt.to_sym
+        end
       end
+
+    # Match command option against command line args
+    elsif arg.class == Option && other.class == Array
+      match.arg = arg.key
+
+      other.select{|x| x.start_with?('-')}.any?{|x|
+        short = x[@short_regex, 1]
+        long = x[@long_regex, 1]
+        value = x[@value_regex, 1]
+        if short == arg.short || long == arg.long
+          match.opt = arg
+          match.value = value
+          match.sym = match.opt.to_sym
+        end
+      }
     end
 
     return match
@@ -427,20 +572,20 @@ class Commander
       if opt.type == String
         if opt.allowed.any?
           !puts("Error: invalid string value '#{value}'!".colorize(:red)) && !puts(cmd.help) and
-            exit if !opt.allowed.include?(value)
+            exit if !opt.allowed.key?(value) && !opt.allowed.key?(value.to_sym)
         end
       elsif opt.type == Integer
         value = value.to_i
         if opt.allowed.any?
           !puts("Error: invalid integer value '#{value}'!".colorize(:red)) && !puts(cmd.help) and
-            exit if !opt.allowed.include?(value)
+            exit if !opt.allowed.key?(value)
         end
       elsif opt.type == Array
         value = value.split(',')
         if opt.allowed.any?
           value.each{|x|
             !puts("Error: invalid array value '#{x}'!".colorize(:red)) && !puts(cmd.help) and
-              exit if !opt.allowed.include?(x)
+              exit if !opt.allowed.key?(x) && !opt.allowed.key?(x.to_sym)
           }
         end
       end
@@ -450,37 +595,61 @@ class Commander
   end
 
   # Add a command to the command list
-  # @param cmd [String] name of the command
+  # @param name [String] name of the command
   # @param desc [String] description of the command
-  # @param opts [List] list of command options
+  # @param nodes [Array] list of command nodes (i.e. options or commands)
+  # @param hierarchy [Array] list of commands
   # @return [Command] new command
-  def add_cmd(cmd, desc, options)
-    Log.die("command names must be pure lowercase letters") if cmd =~ /[^a-z]/
+  def add_cmd(name, desc, nodes, hierarchy:[])
+    hierarchy << name
+    cmd = Command.new(name, desc)
+    subcmds = nodes.select{|x| x.class == Command}.sort{|x,y| x.name <=> y.name}
 
     # Build help for command
+    #---------------------------------------------------------------------------
+    cmd.help = "#{desc}\n"
     app = @app || @app_default
-    help = "#{desc}\n"
-    help += "\nUsage: ./#{app} #{cmd} [options]\n" if cmd != 'global'
-    help = "#{banner}\n#{help}" if @app && cmd != 'global'
+    cmd_prompt = subcmds.any? ? "[commands] " : ""
+    cmd.help += "\nUsage: ./#{app} #{hierarchy * ' '} #{cmd_prompt}[options]\n" if name != @k.global
+    cmd.help = "#{banner}\n#{cmd.help}" if @app && name != @k.global
 
-    # Add help option if not global command
-    options << @config.find{|x| x.name == 'global'}.opts.find{|x| x.long == '--help'} if cmd != 'global'
+    # Add help for each sub-command before options
+    cmd.help += "COMMANDS:\n" if subcmds.any?
+    subcmds.each{|x| cmd.help += "    #{x.name.ljust(@just)}#{x.desc}\n" }
+
+    # Insert standard help option for command (re-using one from global, all identical)
+    nodes << @config.find{|x| x.name == @k.global}.nodes.find{|x| x.long == '--help'} if name != @k.global
 
     # Add positional options first
-    sorted_options = options.select{|x| x.key.nil?}
-    sorted_options += options.select{|x| !x.key.nil?}.sort{|x,y| x.key <=> y.key}
+    sorted_options = nodes.select{|x| x.class == Option && x.key.nil?}
+    sorted_options += nodes.select{|x| x.class == Option && !x.key.nil?}.sort{|x,y| x.key <=> y.key}
+    cmd.help += "OPTIONS:\n" if subcmds.any? && sorted_options.any?
     positional_index = -1
-    sorted_options.each{|x| 
+    sorted_options.each{|x|
       required = x.required ? ", Required" : ""
-      allowed = x.allowed.empty? ? "" : " (#{x.allowed * ','})"
       positional_index += 1 if x.key.nil?
-      key = x.key.nil? ? "#{cmd}#{positional_index}" : x.key
-      type = x.type == FalseClass ? "Flag" : x.type
-      help += "    #{key.ljust(@just)}#{x.desc}#{allowed}: #{type}#{required}\n"
+      key = x.key.nil? ? "#{name}#{positional_index}" : x.key
+      if x.type == FalseClass || x.type == TrueClass
+        type = "Flag(#{x.type.to_s[/(.*)Class/, 1].downcase})"
+      elsif x.type == Array
+        type = "#{x.type}(String)"
+      else
+        type = x.type
+      end
+      cmd.help += "    #{key.ljust(@just)}#{x.desc}: #{type}#{required}\n"
+      x.allowed.sort{|x,y| x <=> y}.each{|x| cmd.help += "    #{''.ljust(@just)}  #{x.first}: #{x.last}\n" }
     }
 
-    # Create the command in the command config
-    return Command.new(cmd, desc, sorted_options, help)
+    # Add hint as to how to get specific sub command help
+    cmd.help += "\nsee './#{app} #{name} COMMAND --help' for specific command help\n" if subcmds.any?
+
+    # Configure help for each sub command
+    subcmds.each{|x| cmd.nodes << add_cmd(x.name, x.desc, x.nodes, hierarchy:hierarchy)}
+
+    # Add options after any sub-commands
+    cmd.nodes += sorted_options
+
+    return cmd
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nub
 version: !ruby/object:Gem::Version
-  version: 0.0.55
+  version: 0.0.56
 platform: ruby
 authors:
 - Patrick Crummett
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-02 00:00:00.000000000 Z
+date: 2018-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colorize