arg-parser 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9b0c2c32a741e3751760248db85d2cc4e1a47288
-  data.tar.gz: cbd2b833b43077480b73e932bdf45168c52d8d04
+  metadata.gz: 0ff4e92f478416dc226d866f7763340e5bad9be7
+  data.tar.gz: d367fbaa43753a938f599ea0cf04181a3cabaadd
 SHA512:
-  metadata.gz: 571fb0dda1c9f9b9162fe126da1795c22db68e3ae2732b6b66db0fbe87466cd617f8fb7a413f44b30ad21e47aa2d22b563030e4133151509766a49ad4506bd33
-  data.tar.gz: 1dd67d98bedea2a677490e999fc9db92ee5c29ab1099740f4a0f828a33938ae4640220436140b247f72fdcc09c9361833df921a20b23f36fe389a515ff05877d
+  metadata.gz: 8c1994d8da4359cc9c19735975840835b156cd8d79afd255660e9285bcfec1bb18eb806230113da2103d129ac5abf725c38af4fd60ac052eeaa9ba4512ec4a85
+  data.tar.gz: 7dd2c412243ea6b4f15d0ea41fccec25ff173404817536e72aec01112e43ddc99ae52a16fd3748fcb908601bc2fbe75e4f3b875cd1c953b97d47869a5d1b0e3f

data/README.md

@@ -47,6 +47,12 @@ class MyClass
             # opts.flag, and opts.files
             # ...
         else
+            # False is returned if argument parsing was not completed
+            # This may be due to an error or because the help command
+            # was used (by specifying --help or /?). The #show_help?
+            # method returns true if help was requested, otherwise if
+            # a parse error was encountered, #show_usage? is true and
+            # parse errors are in #parse_errors
             show_help? ? show_help : show_usage
         end
     end
@@ -63,6 +69,27 @@ MyClass.new.run
 ArgParser provides a fairly broad range of functionality for argument parsing. Following is a non-exhaustive
 list of features:
 * Built-in usage and help display
+* Multiple different types of arguments can be defined:
+    - Command arguments indicate an argument that can be one of a limited selection of pre-defined
+      argument values. Each command argument must define its commands, as well as any command-specific
+      arguments.
+    - Positional arguments are arguments that are normally supplied without any key, and are matched
+      to an argument definition based on the order in which they are encountered. Positional arguments
+      can also be supplied using the key if preferred. Generally only a small number of positional
+      arguments would be defined for those parameters required on every run.
+    - Keyword arguments are arguments that must be specified by using a key to indicate which argument
+      the subsequent value is for.
+    - Flag arguments are boolean arguments that normally default to nil, but can be set to true just
+      by specifying the argument key. It is also possible to define flag arguments with a default value
+      of true; the argument can then be set to false by speciying the argument name with --no-<flag>
+      (or --not-<flag> or --non-<flag> when those are more understandable).
+    - Rest arguments use a single argument key to collect all remaining values from the command-line,
+      and return these as an array in the resulting argument results.
+* Parsed results are returned in an OpenStruct, with every defined argument having a value set (whether
+  or not it was encountered on the command-line). Use the `default: <value>` option to set default
+  values for non-specified arguments where you don't want nil returned in the parse results. Note that
+  in the case of command arguments with command-specific arguments, only the arguments from the selected
+  command appear in the results.
 * Mandatory vs Optional: All arguments your program accepts can be defined as optional or mandatory.
   By default, positional arguments are considered mandatory, and all others default to optional. To change
   the default, simply specify `required: true` or `required: false` when defining the argument.
@@ -72,6 +99,10 @@ list of features:
   parsed value in the results. However, arguments can also define a single letter or digit short-key form
   which can be used as an alternate means for indicating a value. To define a short key, simply pass
   `short_key: '<letter_or_digit>'` when defining an argument.
+* Requiring from a set of arguments: If you need to ensure that only one of several mutually exclusive
+  arguments is specified, use `require_one_of <arg1>, <arg2>, ..., <argN>`. If you need to ensure that
+  at least one argument is specified from a list of arguments, use
+  `require_any_of <arg1>, <arg2>, ..., <argN>`
 * Validation: Arguments can define validation requirements that must be satisfied. This can take several
   forms:
      - List of values: Pass an array containing the allowed values the argument can take.
@@ -90,3 +121,149 @@ list of features:
 * Pre-defined arguments: Arguments can be registered under a key, and then re-used across multiple
   definitions via the #predefined_arg DSL method. Common arguments would typically be defined in a
   shared file that was included into each job. See Argument.register and DSL.predefined_arg.
+
+
+### Commands
+
+Often command-line utilities can perform several actions, and we want to define an argument that will
+be used to indicate to the program which action it should perform. This can be done very easily using
+positional arguments, and setting a list of allowed values in the argument validation, e.g.
+`positional_arg :command, 'The command to perform', validation: %w{list export import}`
+
+However, it is often the case that the different commands require different additional arguments
+to be specified, and this makes it necessary to make any argument not required by all commands into
+an optional argument. However, now the program has to ensure that it checks for those optional
+arguments that are required for the command to actually be present.
+
+In this circumstance, it is better to instead make use of command arguments. These are arguments
+that look like positional arguments that accept only a specific set of values, however, each command
+can then define its own set of additional arguments (of any type). During parsing, when a command
+argument is found, the argument definition is updated on-the-fly to include any additional arguments
+defined by the now-matched command. Additionally, the usage and help displays are also updated to
+reflect the arguments defined by the specified command.
+
+Defining command arguments is a little more complex, due to the need to associate command arguments
+with the commands.
+
+
+```ruby
+require 'arg-parser'
+
+class MyClass
+
+    include ArgParser::DSL
+
+    purpose <<-EOT
+        This is where you specify the purpose of your program. It will be displayed in the
+        generated help screen if you pass /? or --help on the command-line.
+    EOT
+
+    command_arg :command, 'The command to perform' do
+        # We often want the same arguments to appear in several but not all commands.
+        # Rather than re-defining them for each command, we can first define them, and
+        # then reference them in the commands that need them.
+        define_args do
+            positional_arg :source, 'The source to use'
+            positional_arg :target, 'The target to use'
+            positional_arg :local_dir, 'The path to a local directory',
+                default: 'extracts'
+        end
+
+        command :list, 'List available items for transfer' do
+            predefined_arg :source
+        end
+        command :export, 'Export items to a local directory' do
+            predefined_arg :source
+            predefined_arg :local_dir
+        end
+        command :import, 'Import items from a local directory' do
+            predefined_arg :local_dir
+            predefined_arg :target
+        end
+    end
+
+    positional_arg :user_id, 'The user id for connecting to the source/target'
+    positional_arg :password, 'The password for connecting to the source/target',
+        sensitive: true
+
+    ...
+
+    def run
+        if opts = parse_arguments
+            case opts.command
+            when 'list'
+                do_list(opts.source)
+            when 'export'
+                do_export(opts.source, opts.local_dir)
+            when 'import'
+                do_import(opts.local_dir, opts.target)
+            end
+        else
+            show_help? ? show_help : show_usage
+        end
+    end
+
+end
+
+MyClass.new.run
+```
+
+## Pre-defined Arguments
+
+We saw above in the case of commands that it can be useful to pre-define an argument with all its
+parameters once, and then reference that argument in multiple separate commands. This allows us
+to follow DRY principles when defining an argument, making maintenance simpler and reducing the
+possibility of mis-configuring one or more instances of the same argument.
+
+This principle does not only apply to arguments for use within a single utility or set of commands.
+Arguments can also be pre-defined in an argument scope, and then referenced in multiple utilities.
+Thus if there are common arguments needed in many utilities that share some common code, you can
+also define these common arguments in the shared code, and then include the pre-defined arguments
+into each utility that shares that functionality.
+
+
+```ruby
+require 'arg-parser'
+
+class MyLibrary
+
+    include ArgParser::DSL
+
+    LIBRARY_ARGS = define_args('Database Args') do
+        positional_arg :database, 'The name of the database to connect to',
+            on_parse: lambda{ |val, arg, hsh| # Lookup database connection details and return as hash }
+        positional_arg :user_id, 'The user id for connecting to the database'
+        positional_arg :password, 'The password for connecting to the database',
+            sensitive: true
+    end
+
+end
+
+
+class Utility
+
+    include 'arg-parser'
+
+    with_predefined_args MyLibrary::LIBRARY_ARGS do
+        predefined_arg :database
+        predefined_arg :user_id
+        predefined_arg :password
+    end
+
+    keyword_arg :log_level, 'Set the log level for database interactions'
+    
+    ...
+
+    
+    def run
+        if opts = parse_arguments
+            # Connect to database, set log level etc
+        else
+            show_help? ? show_help : show_usage
+        end
+    end
+
+end
+
+MyClass.new.run
+```

data/lib/arg-parser/argument.rb

@@ -5,7 +5,11 @@ module ArgParser
     OnParseHandlers = {
         :split_to_array => lambda{ |val, arg, hsh| val.split(',') }
     }
-    # Hash containing registered arguments available via #predefined_arg
+    # Hash containing globally registered predefined arguments available via
+    # #predefined_arg.
+    # Predefined arguments should normally be defined within an ArgumentScope,
+    # rather than globally. See DSL.define_args for pre-defining arguments on
+    # an including class, or use the argument creation methods on ArgumentScope,
     PredefinedArguments = { }
 
 
@@ -14,14 +18,12 @@ module ArgParser
     # @abstract
     class Argument
 
-        # The key used to identify this argument value in the  parsed command-
-        # line results Struct.
         # @return [Symbol] the key/method by which this argument can be retrieved
         #   from the parse result Struct.
         attr_reader :key
         # @return [String] the description for this argument, which will be shown
         #   in the usage display.
-        attr_reader :description
+        attr_accessor :description
         # @return [Symbol] a single letter or digit that can be used as a short
         #   alternative to the full key to identify an argument value in a command-
         #   line.
@@ -50,20 +52,19 @@ module ArgParser
         #   the group.
         attr_accessor :usage_break
 
-
         # Converts an argument key specification into a valid key, by stripping
         # leading dashes, converting remaining dashes to underscores, and lower-
         # casing all text. This is required to ensure the key name will be a
         # valid accessor name on the parse results.
         #
+        # @param label [String|Symbol] the value supplied for an argument key
         # @return [Symbol] the key by which an argument can be retrieved from
-        #   the arguments definition, and the parse results.
+        #   the arguments definition and the parse results.
         def self.to_key(label)
             k = label.to_s.gsub(/^-+/, '').gsub('-', '_')
             k.length > 1 ? k.downcase.intern : k.intern
         end
 
-
         # Register a common argument for use in multiple argument definitions. The
         # registered argument is a completely defined argument that can be added to
         # any argument definition via Definition#predefined_arg.
@@ -86,7 +87,6 @@ module ArgParser
             PredefinedArguments[key] = arg
         end
 
-
         # Return a copy of a pre-defined argument for use in an argument
         # definition.
         #
@@ -104,9 +104,22 @@ module ArgParser
             arg.clone
         end
 
+        # Set the short key (a single letter or digit) that may be used as an
+        # alternative when specifyin gthis argument.
+        #
+        # @param sk [String] The short key specification
+        def short_key=(sk)
+            if sk =~ /^-?([a-z0-9])$/i
+                @short_key = $1.intern
+            else
+                raise ArgumentError, "An argument short key must be a single digit or letter"
+            end
+        end
+
 
         private
 
+        # Private to prevent instantiation of this abstract class
         def initialize(key, desc, opts = {}, &block)
             @key = self.class.to_key(key)
             @description = desc
@@ -125,12 +138,100 @@ module ArgParser
             end
             @usage_break = opts[:usage_break]
             if sk = opts[:short_key]
-                if sk =~ /^-?([a-z0-9])$/i
-                    @short_key = $1.intern
+                self.short_key=(sk)
+            end
+        end
+
+    end
+
+
+    # An argument type that defines a command. Each command placeholder can have
+    # one or more command arguments (i.e. allowed values). Depending on the command,
+    # different additional arguments may then be specified in the command's
+    # ArgumentSet.
+    class CommandArgument < Argument
+
+        # @return [Array<Symbol] List of valid commands that may be specified.
+        attr_accessor :commands
+
+
+        # Create an instance of a CommandArgument, a positional argument that
+        # indicates a particular command to be invoked.
+        #
+        # @param key [String|Symbol] The value under which the specified command
+        #   can be retrieved following parsing (e.g. :command)
+        # @param desc [String] A description for the command argument.
+        # @param opts [Hash] An options hash. See Argument#initialize for supported
+        #   option values.
+        def initialize(key, desc, opts = {})
+            super(key, desc, opts)
+            @commands = {}
+            @required = opts.fetch(:required, !opts.has_key?(:default))
+            @usage_value = opts.fetch(:usage_value, key.to_s.gsub('_', '-').upcase)
+        end
+
+        # Adds a specific command verb/value to this command argument
+        def <<(cmd_instance)
+            raise ArgumentError, "must be a CommandInstance object" unless cmd_instance.is_a?(CommandInstance)
+            @commands[cmd_instance.command_value] = cmd_instance
+        end
+
+        # Return the CommandInstance for a particular command value
+        #
+        # @param cmd_val [String|Symbol] A command token identifying the command
+        # @return [CommandInstance] The CommandInstance for the specified command
+        def [](cmd_val)
+            k = Argument.to_key(cmd_val)
+            @commands[k]
+        end
+
+        def to_s
+            @usage_value
+        end
+
+        def to_use
+            required? ? usage_value : "[#{usage_value}]"
+        end
+
+    end
+
+
+    # Represents a specific command value for a CommandArgument, along with any
+    # additional arguments specific to this command.
+    class CommandInstance < Argument
+
+        # @return the constant value that identifies this CommandInstance
+        attr_reader :command_value
+        # Return the CommandArgument to which this CommandInstance relates
+        attr_reader :command_arg
+        # Return an ArgumentScope for any additional arguments this command takes 
+        attr_reader :argument_scope
+
+
+        def initialize(cmd_val, desc, cmd_arg, arg_scope, opts = {})
+            if cmd_arg.on_parse
+                if cmd_inst_op = opts[:on_parse]
+                    # Command and command instance both defined on_parse handlers
+                    opts[:on_parse] = lambda do |val, arg, hsh|
+                        cmd_arg.on_parse(val, arg, hsh)
+                        cmd_inst_op.on_parse(val, arg, hsh)
+                    end
                 else
-                    raise ArgumentError, "An argument short key must be a single digit or letter"
+                    opts[:on_parse] = cmd_arg.on_parse
                 end
             end
+            super(cmd_arg.key, desc, opts)
+            @command_value = cmd_val
+            @command_arg = cmd_arg
+            @argument_scope = arg_scope
+        end
+
+        def to_s
+            @command_value
+        end
+
+        def to_use
+            @command_value
         end
 
     end
@@ -320,6 +421,7 @@ module ArgParser
         #   String to some other type.
         def initialize(key, desc, opts = {}, &block)
             super
+            @usage_value = opts[:usage_value]
         end
 
         def required
@@ -332,7 +434,11 @@ module ArgParser
 
         def to_use
             sk = short_key ? "-#{short_key}, " : ''
-            "#{sk}#{self.to_s}"
+            if @usage_value
+                "#{sk}#{@usage_value[0..1] == '--' ? '' : '--'}#{@usage_value}"
+            else
+                "#{sk}#{self.to_s}"
+            end
         end
 
     end
@@ -366,6 +472,7 @@ module ArgParser
         def initialize(key, desc, opts = {}, &block)
             super
             @min_values = opts.fetch(:min_values, opts.fetch(:required, true) ? 1 : 0)
+            @default = [@default] if @default.is_a?(String)
         end
 
         def required

data/lib/arg-parser/definition.rb

@@ -5,25 +5,76 @@ module ArgParser
     class NoSuchArgumentError < RuntimeError; end
 
 
-    # Represents the collection of possible command-line arguments for a script.
-    class Definition
+    # Represents a scope within which an argument is defined/alid.
+    # Scopes may be nested, and argument requests will search the scope chain to
+    # find a matching argument.
+    class ArgumentScope
 
-        # @return [String] A title for the script, displayed at the top of the
-        #   usage and help outputs.
-        attr_accessor :title
-        # @return [String] A short description of the purpose of the script, for
-        #   display when showing the usage help.
-        attr_accessor :purpose
+        attr_reader :name, :parent
+        attr_accessor :predefined_args
 
 
-        # Create a new Definition, which is a collection of valid Arguments to
-        # be used when parsing a command-line.
-        def initialize
+        def initialize(name, parent = nil)
+            @name = name
+            @parent = parent
+            @parent.add_child(self) if @parent
+            @children = []
             @arguments = {}
             @short_keys = {}
-            @require_set = Hash.new{ |h,k| h[k] = [] }
-            @title = $0.respond_to?(:titleize) ? $0.titleize : $0
-            yield self if block_given?
+            @predefined_args = nil
+        end
+
+
+        # Adds a Scope as a child of this scope.
+        def add_child(arg_scope)
+            raise ArgumentError, "#{arg_scope} must be an ArgumentScope instance" unless arg_scope.is_a?(ArgumentScope)
+            raise ArgumentError, "#{arg_scope} parent not set to this ArgumentScope" if arg_scope.parent != self
+            @children << arg_scope
+        end
+
+
+        # Checks if a key has been used in this scope, any ancestor scopes, or
+        # any descendant scopes.
+        #
+        # @param key [String] The key under which an argument is to be registered
+        # @return [Argument|nil] The Argument that already uses the key, or nil
+        #   if the key is not used.
+        def key_used?(key)
+            self.walk_ancestors do |anc|
+                arg = anc.has_key?(key)
+                return arg if arg
+            end
+            self.walk_children do |child|
+                arg = child.has_key?(key)
+                return arg if arg
+            end
+            nil
+        end
+
+
+        # Yields each key/argument pair for this ArgumentScope
+        def walk_arguments(&blk)
+            @arguments.each(&blk)
+        end
+
+
+        # Yields each ancestor of this scope, optionally including this scope.
+        def walk_ancestors(inc_self = true, &blk)
+            scope = inc_self ? self : self.parent
+            while scope do
+                yield scope
+                scope = scope.parent
+            end
+        end
+            
+
+        # Recursively walks and yields each descendant scopes of this scope.
+        def walk_children(inc_self = false, &blk)
+            yield self if inc_self
+            @children.each do |child|
+                yield child
+                child.walk_children(&blk)
+            end
         end
 
 
@@ -50,26 +101,35 @@ module ArgParser
         #   line definition.
         def <<(arg)
             case arg
-            when PositionalArgument, KeywordArgument, FlagArgument, RestArgument
-                if @arguments[arg.key]
-                    raise ArgumentError, "An argument with key '#{arg.key}' has already been defined"
+            when CommandArgument, PositionalArgument, KeywordArgument, FlagArgument, RestArgument
+                if used = self.key_used?(arg.key)
+                    raise ArgumentError, "An argument with key '#{arg.key}' has already been defined: #{used}"
                 end
-                if arg.short_key && @short_keys[arg.short_key]
-                    raise ArgumentError, "The short key '#{arg.short_key}' has already been registered by the '#{
-                        @short_keys[arg.short_key]}' argument"
+                if arg.short_key && used = self.key_used?(arg.short_key)
+                    raise ArgumentError, "The short key '#{arg.short_key}' has already been registered: #{used}"
                 end
-                if arg.is_a?(RestArgument) && rest_args
+                if arg.is_a?(RestArgument) && rest_args?
                     raise ArgumentError, "Only one rest argument can be defined"
                 end
                 @arguments[arg.key] = arg
                 @short_keys[arg.short_key] = arg if arg.short_key
             else
-                raise ArgumentError, "arg must be an instance of PositionalArgument, KeywordArgument, " +
-                    "FlagArgument or RestArgument"
+                raise ArgumentError, "arg must be an instance of CommandArgument, PositionalArgument, " +
+                    "KeywordArgument, FlagArgument or RestArgument"
             end
         end
 
 
+        # Add a command argument to the set of arguments in this command-line
+        # argument definition.
+        # @see CommandArgument#initialize
+        def command_arg(key, desc, opts = {}, &block)
+            cmd_arg = ArgParser::CommandArgument.new(key, desc, opts)
+            CommandBlock.new(self, cmd_arg, &block)
+            self << cmd_arg
+        end
+
+
         # Add a positional argument to the set of arguments in this command-line
         # argument definition.
         # @see PositionalArgument#initialize
@@ -123,108 +183,23 @@ module ArgParser
         #   returned in the command-line parse results if no other value is
         #   specified.
         def predefined_arg(lookup_key, opts = {})
-            arg = Argument.lookup(lookup_key)
-            arg.description = opts[:description] if opts[:description]
-            arg.useage_break = opts[:usage_break] if opts.has_key?(:usage_break)
+            #arg = Argument.lookup(lookup_key)
+            arg = nil
+            self.walk_ancestors do |scope|
+                arg = scope.predefined_args && scope.predefined_args.has_key?(lookup_key)
+                break if arg
+            end
+            raise ArgumentError, "No predefined argument with key '#{lookup_key}' found" unless arg
+            arg.short_key = opts[:short_key] if opts.has_key?(:short_key)
+            arg.description = opts[:description] if opts.has_key?(:description)
+            arg.usage_break = opts[:usage_break] if opts.has_key?(:usage_break)
             arg.required = opts[:required] if opts.has_key?(:required)
             arg.default = opts[:default] if opts.has_key?(:default)
+            arg.on_parse = opts[:on_parse] if opts.has_key?(:on_parse)
             self << arg
         end
 
 
-        # Individual arguments are optional, but exactly one of +keys+ arguments
-        # is required.
-        def require_one_of(*keys)
-            @require_set[:one] << keys.map{ |k| self[k] }
-        end
-
-
-        # Individual arguments are optional, but at least one of +keys+ arguments
-        # is required.
-        def require_any_of(*keys)
-            @require_set[:any] << keys.map{ |k| self[k] }
-        end
-
-
-        # True if at least one argument is required out of multiple optional args.
-        def requires_some?
-            @require_set.size > 0
-        end
-
-
-        # @return [Parser] a Parser instance that can be used to parse this
-        #   command-line Definition.
-        def parser
-            @parser ||= Parser.new(self)
-        end
-
-
-        # Parse the +args+ array of arguments using this command-line definition.
-        #
-        # @param args [Array, String] an array of arguments, or a String representing
-        #   the command-line that is to be parsed.
-        # @return [OpenStruct, false] if successful, an OpenStruct object with all
-        # arguments defined as accessors, and the parsed or default values for each
-        # argument as values. If unsuccessful, returns false indicating a parse
-        # failure.
-        # @see Parser#parse, Parser#errors, Parser#show_usage, Parser#show_help
-        def parse(args = ARGV)
-            parser.parse(args)
-        end
-
-
-        # Return an array of parse errors.
-        # @see Parser#errors
-        def errors
-            parser.errors
-        end
-
-
-        # Whether user indicated they would like help on usage.
-        # @see Parser#show_usage
-        def show_usage?
-            parser.show_usage?
-        end
-
-
-        # Whether user indicated they would like help on supported arguments.
-        # @see Parser#show_help
-        def show_help?
-            parser.show_help?
-        end
-
-
-        # Validates the supplied +args+ Hash object, verifying that any argument
-        # set requirements have been satisfied. Returns an array of error
-        # messages for each set requirement that is not satisfied.
-        #
-        # @param args [Hash] a Hash containing the keys and values identified
-        #   by the parser.
-        # @return [Array] a list of errors for any argument requirements that
-        #   have not been satisfied.
-        def validate_requirements(args)
-            errors = []
-            @require_set.each do |req, sets|
-                sets.each do |set|
-                    count = set.count{ |arg| args.has_key?(arg.key) && args[arg.key] }
-                    case req
-                    when :one
-                        if count == 0
-                            errors << "No argument has been specified for one of: #{set.join(', ')}"
-                        elsif count > 1
-                            errors << "Only one argument can been specified from: #{set.join(', ')}"
-                        end
-                    when :any
-                        if count == 0
-                            errors << "At least one of the arguments must be specified from: #{set.join(', ')}"
-                        end
-                    end
-                end
-            end
-            errors
-        end
-
-
         # @return [Array] all argument keys that have been defined.
         def keys
             @arguments.keys
@@ -243,9 +218,23 @@ module ArgParser
         end
 
 
+        # @return [Array] all command arguments that have been defined
+        def command_args
+            @arguments.values.select{ |arg| CommandArgument === arg }
+        end
+
+
+        # @return True if a command arg has been defined
+        def command_args?
+            command_args.size > 0
+        end
+
+
         # @return [Array] all positional arguments that have been defined
         def positional_args
-            @arguments.values.select{ |arg| PositionalArgument === arg }
+            @arguments.values.select{ |arg| CommandArgument === arg ||
+                                            CommandInstance === arg ||
+                                            PositionalArgument === arg }
         end
 
 
@@ -258,7 +247,10 @@ module ArgParser
         # @return [Array] the non-positional (i.e. keyword and flag)
         #    arguments that have been defined.
         def non_positional_args
-            @arguments.values.reject{ |arg| PositionalArgument === arg || RestArgument === arg }
+            @arguments.values.reject{ |arg| CommandArgument === arg || 
+                                            CommandInstance === arg ||
+                                            PositionalArgument === arg ||
+                                            RestArgument === arg }
         end
 
 
@@ -317,13 +309,232 @@ module ArgParser
             @arguments.size
         end
 
+    end
+
+
+    # Used to define arguments specific to a CommandInstance
+    class CommandBlock
+
+        def initialize(arg_scope, cmd_arg, &block)
+            @parent = arg_scope
+            @command_arg = cmd_arg
+            self.instance_eval(&block)
+        end
+
+
+        def define_args(&block)
+            pre_def_arg_scope = ArgumentScope.new("Predefined args for #{@command_arg}")
+            pre_def_arg_scope.instance_eval(&block)
+            @parent.predefined_args = pre_def_arg_scope
+        end
+
+
+        def command(key, desc, opts = {}, &block)
+            cmd_arg_scope = ArgumentScope.new("Arguments for #{key} command", @parent)
+            cmd_arg_scope.instance_eval(&block) if block_given?
+            cmd_inst = CommandInstance.new(key, desc, @command_arg, cmd_arg_scope, opts)
+            @command_arg << cmd_inst
+        end
+
+    end
+
+
+    # Represents the collection of possible command-line arguments for a script.
+    class Definition < ArgumentScope
+
+        # @return [String] A title for the script, displayed at the top of the
+        #   usage and help outputs.
+        attr_accessor :title
+        # @return [String] A short description of the purpose of the script, for
+        #   display when showing the usage help.
+        attr_accessor :purpose
+        # @return [String] A copyright notice, displayed in the usage and help
+        #   outputs.
+        attr_accessor :copyright
+
+
+        # Create a new Definition, which is a collection of valid Arguments to
+        # be used when parsing a command-line.
+        def initialize(name = 'ArgParser::Definition')
+            super(name)
+            @require_set = []
+            @title = $0.respond_to?(:titleize) ? $0.titleize : $0
+            yield self if block_given?
+        end
+
+
+        # Collapses an ArgumentScope into this Definition, representing the
+        # collapsed argument possibilities once a command has been identitfied
+        # for a CommandArgument. Think of the original Definition as being a
+        # superposition of possible argument definitions, with one possible
+        # state for each CommandInstance of each commad. Once the actual
+        # CommandInstance is known, we are collapsing the superposition of
+        # possible definitions to a lower dimensionality; only one possible
+        # definition remains once all CommandArgument objects are replaced by
+        # CommandInstances.
+        #
+        # @param cmd_inst [CommandInstance] The instance of a command that has
+        #   been specified.
+        # @return [Definition] A new Definition with a set of arguments combined
+        #   from this Definition and the selected ArgumentScope for a specific
+        #   command instance.
+        def collapse(cmd_inst)
+            new_def = self.clone
+            child = cmd_inst.argument_scope
+            new_args = {}
+            new_short_keys = {}
+            @arguments.each do |key, arg|
+                if arg == cmd_inst.command_arg
+                    new_args[key] = cmd_inst
+                    child.walk_arguments do |key, arg|
+                        new_args[key] = arg
+                        new_short_keys[arg.short_key] = arg if arg.short_key
+                    end
+                else
+                    new_args[key] = arg
+                    new_short_keys[arg.short_key] = arg if arg.short_key
+                end
+            end
+            new_children = @children.reject{ |c| c == cmd_inst.argument_scope } &
+                child.instance_variable_get(:@children)
+            new_def.instance_variable_set(:@arguments, new_args)
+            new_def.instance_variable_set(:@short_keys, new_short_keys)
+            new_def.instance_variable_set(:@children, new_children)
+            new_def
+        end
+
+
+        # Lookup a pre-defined argument (created earlier via Argument#register),
+        # and add it to this arguments definition.
+        #
+        # @see Argument#register
+        #
+        # @param lookup_key [String, Symbol] The key under which the pre-defined
+        #   argument was registered.
+        # @param desc [String] An optional override for the argument description
+        #   for this use of the pre-defined argument.
+        # @param opts [Hash] An options hash for those select properties that
+        #   can be overridden on a pre-defined argument.
+        # @option opts [String] :description The argument description for this
+        #   use of the pre-defined argument.
+        # @option opts [String] :usage_break The usage break for this use of
+        #   the pre-defined argument.
+        # @option opts [Boolean] :required Whether this argument is a required
+        #   (i.e. mandatory) argument.
+        # @option opts [String] :default The default value for the argument,
+        #   returned in the command-line parse results if no other value is
+        #   specified.
+        def predefined_arg(lookup_key, opts = {})
+            # TODO: walk ancestor chain looking at pre-defined arg scopes
+            arg = (self.predefined_args && self.predefined_args.key_used?(lookup_key)) ||
+                Argument.lookup(lookup_key)
+            arg.short_key = opts[:short_key] if opts.has_key?(:short_key)
+            arg.description = opts[:description] if opts.has_key?(:description)
+            arg.usage_break = opts[:usage_break] if opts.has_key?(:usage_break)
+            arg.required = opts[:required] if opts.has_key?(:required)
+            arg.default = opts[:default] if opts.has_key?(:default)
+            arg.on_parse = opts[:on_parse] if opts.has_key?(:on_parse)
+            self << arg
+        end
+
+
+        # Individual arguments are optional, but exactly one of +keys+ arguments
+        # is required.
+        def require_one_of(*keys)
+            @require_set << [:one, keys.map{ |k| self[k] }]
+        end
+
+
+        # Individual arguments are optional, but at least one of +keys+ arguments
+        # is required.
+        def require_any_of(*keys)
+            @require_set << [:any, keys.map{ |k| self[k] }]
+        end
+
+
+        # True if at least one argument is required out of multiple optional args.
+        def requires_some?
+            @require_set.size > 0
+        end
+
+
+        # @return [Parser] a Parser instance that can be used to parse this
+        #   command-line Definition.
+        def parser
+            @parser ||= Parser.new(self)
+        end
+
+
+        # Parse the +args+ array of arguments using this command-line definition.
+        #
+        # @param args [Array, String] an array of arguments, or a String representing
+        #   the command-line that is to be parsed.
+        # @return [OpenStruct, false] if successful, an OpenStruct object with all
+        # arguments defined as accessors, and the parsed or default values for each
+        # argument as values. If unsuccessful, returns false indicating a parse
+        # failure.
+        # @see Parser#parse, Parser#errors, Parser#show_usage, Parser#show_help
+        def parse(args = ARGV)
+            parser.parse(args)
+        end
+
+
+        # Return an array of parse errors.
+        # @see Parser#errors
+        def errors
+            parser.errors
+        end
+
+
+        # Whether user indicated they would like help on usage.
+        # @see Parser#show_usage
+        def show_usage?
+            parser.show_usage?
+        end
+
+
+        # Whether user indicated they would like help on supported arguments.
+        # @see Parser#show_help
+        def show_help?
+            parser.show_help?
+        end
+
+
+        # Validates the supplied +args+ Hash object, verifying that any argument
+        # set requirements have been satisfied. Returns an array of error
+        # messages for each set requirement that is not satisfied.
+        #
+        # @param args [Hash] a Hash containing the keys and values identified
+        #   by the parser.
+        # @return [Array] a list of errors for any argument requirements that
+        #   have not been satisfied.
+        def validate_requirements(args)
+            errors = []
+            @require_set.each do |req, set|
+                count = set.count{ |arg| args.has_key?(arg.key) && args[arg.key] }
+                case req
+                when :one
+                    if count == 0
+                        errors << "No argument has been specified for one of: #{set.join(', ')}"
+                    elsif count > 1
+                        errors << "Only one argument can been specified from: #{set.join(', ')}"
+                    end
+                when :any
+                    if count == 0
+                        errors << "At least one of the arguments must be specified from: #{set.join(', ')}"
+                    end
+                end
+            end
+            errors
+        end
+
 
         # Generates a usage display string
         def show_usage(out = STDERR, width = 80)
             lines = ['']
-            pos_args = positional_args
-            opt_args = size - pos_args.size
-            usage_args = pos_args.map(&:to_use)
+            usage_args = []
+            usage_args.concat(positional_args.map(&:to_use))
+            opt_args = size - usage_args.size
             usage_args << (requires_some? ? 'OPTIONS' : '[OPTIONS]') if opt_args > 0
             usage_args << rest_args.to_use if rest_args?
             lines.concat(wrap_text("USAGE: #{RUBY_ENGINE} #{$0} #{usage_args.join(' ')}", width))
@@ -348,6 +559,9 @@ module ArgParser
             if purpose
                 lines.concat(wrap_text(purpose, width))
                 lines << ''
+            end
+            if copyright
+                lines.concat(wrap_text("Copyright (c) #{copyright}", width))
                 lines << ''
             end
 
@@ -355,14 +569,15 @@ module ArgParser
             lines << '-----'
             pos_args = positional_args
             opt_args = size - pos_args.size
-            usage_args = pos_args.map(&:to_use)
+            usage_args = []
+            usage_args.concat(pos_args.map(&:to_use))
             usage_args << (requires_some? ? 'OPTIONS' : '[OPTIONS]') if opt_args > 0
             usage_args << rest_args.to_use if rest_args?
             lines.concat(wrap_text("  #{RUBY_ENGINE} #{$0} #{usage_args.join(' ')}", width))
             lines << ''
 
             if positional_args?
-                max = positional_args.map{ |a| a.to_s.length }.max
+                max = positional_args.map{ |arg| arg.to_s.length }.max
                 pos_args = positional_args
                 pos_args << rest_args if rest_args?
                 pos_args.each do |arg|
@@ -371,25 +586,48 @@ module ArgParser
                         lines << arg.usage_break
                     end
                     desc = arg.description
-                    desc << "\n[Default: #{arg.default}]" unless arg.default.nil?
+                    desc += "\n[Default: #{arg.default}]" unless arg.default.nil?
                     wrap_text(desc, width - max - 6).each_with_index do |line, i|
                         lines << "  %-#{max}s    %s" % [[arg.to_s][i], line]
                     end
                 end
                 lines << ''
             end
+            if command_args?
+                max = command_args.reduce(0) do |max, cmd_arg|
+                    m = cmd_arg.commands.map{ |_, arg| arg.to_s.length }.max
+                    m > max ? m : max
+                end
+                command_args.each do |cmd_arg|
+                    lines << ''
+                    lines << "#{cmd_arg.to_use}S"
+                    lines << '--------'
+                    cmd_arg.commands.each do |_, arg|
+                        if arg.usage_break
+                            lines << ''
+                            lines << arg.usage_break
+                        end
+                        desc = arg.description
+                        wrap_text(desc, width - max - 6).each_with_index do |line, i|
+                            lines << "  %-#{max}s    %s" % [[arg.to_s][i], line]
+                        end
+                    end
+                    lines << ''
+                end
+            end
+
             if non_positional_args?
                 lines << ''
                 lines << 'OPTIONS'
                 lines << '-------'
-                max = non_positional_args.map{ |a| a.to_use.length }.max
+                max = non_positional_args.map{ |arg| arg.to_use.length }.max
                 non_positional_args.each do |arg|
                     if arg.usage_break
                         lines << ''
                         lines << arg.usage_break
                     end
                     desc = arg.description
-                    desc << "\n[Default: #{arg.default}]" unless arg.default.nil?
+                    desc += "\n[Default: #{arg.default}]" unless arg.default.nil?
                     wrap_text(desc, width - max - 6).each_with_index do |line, i|
                         lines << "  %-#{max}s    %s" % [[arg.to_use][i], line]
                     end
@@ -461,5 +699,6 @@ module ArgParser
 
     end
 
+
 end
 

data/lib/arg-parser/dsl.rb

@@ -41,6 +41,7 @@ module ArgParser
                 @args_def ||= ArgParser::Definition.new
             end
 
+
             # Returns true if any arguments have been defined
             def args_defined?
                 @args_def && @args_def.args.size > 0
@@ -64,6 +65,20 @@ module ArgParser
                 args_def.purpose = desc
             end
 
+            # Sets the copyright notice to be displayed on the help screen or on
+            # startup.
+            def copyright(txt)
+                args_def.copyright = txt
+            end
+
+            # Define a new command argument.
+            # @see CommandArgument#initialize
+            def command_arg(key, desc, opts = {}, &block)
+                opts.merge!(@arg_opts){ |k, e, n| e || n } if @arg_opts
+                @arg_opts = nil
+                args_def.command_arg(key, desc, opts, &block)
+            end
+
             # Define a new positional argument.
             # @see PositionalArgument#initialize
             def positional_arg(key, desc, opts = {}, &block)
@@ -96,6 +111,26 @@ module ArgParser
                 args_def.rest_arg(key, desc, opts, &block)
             end
 
+
+            # Define a set of pre-defined arguments for later use
+            def define_args(label = nil, &block)
+                pre_def_arg_scope = ArgumentScope.new(label || "Predefined args")
+                pre_def_arg_scope.instance_eval(&block)
+                pre_def_arg_scope
+            end
+
+            # Set the ArgumentScope to use for looking up pre-defined arguments
+            def with_predefined_args(scope, &blk)
+                if block_given?
+                    pre_defs = args_def.predefined_args
+                    args_def.predefined_args = scope
+                    yield
+                    args_def.predefined_args = pre_defs
+                else
+                    args_def.predefined_args = scope
+                end
+            end
+
             # Use a pre-defined argument.
             # @see Definition#predefined_arg
             def predefined_arg(lookup_key, desc = nil, opts = {})

data/lib/arg-parser/parser.rb

@@ -40,11 +40,27 @@ module ArgParser
         end
 
 
-        # Parse the specified Array[String] of +tokens+, or ARGV if +tokens+ is
-        # nil. Returns false if unable to parse successfully, or an OpenStruct
-        # with accessors for every defined argument. Arguments whose values are
-        # not specified will contain the agument default value, or nil if no
-        # default is specified.
+        # Parse the specified Array<String> of +tokens+, or ARGV if +tokens+ is
+        # nil. If the parse is successful, an OpenStruct object is returned with
+        # values for all defined arguments as members of the OpenStruct.
+        # If parsing is not succssful, it may be due to parse errors or because
+        # a help flag was encountered. The +show_usage+ or +show_help+ flags
+        # will be set (the former in the case of parse errors, and the latter if
+        # help was requested), as well as the +errors+ property if there were parse
+        # errors.
+        #
+        # @note After parse has been called, the argument Definition used by the
+        # parser may have been replaced if a command argument value was specified.
+        # This new definition can be used to show context-specific help or usage
+        # details.
+        #
+        # @param tokens [Array<String>] The tokens to be parsed using the
+        #   argument definition set for this parser. If not specified, defaults
+        #   to ARGV.
+        # @return [False|OpenStruct] false if unable to parse successfully, or
+        # an OpenStruct with accessors for every defined argument if the parse
+        # was successful. Arguments whose values are not specified will contain
+        # the agument default value, or nil if no default is specified.
         def parse(tokens = ARGV)
             @show_usage = nil
             @show_help = nil
@@ -73,8 +89,13 @@ module ArgParser
         # Evaluate the list of values in +tokens+, and classify them as either
         # keyword/value pairs, or positional arguments. Ideally this would be
         # done without any reference to the defined arguments, but unfortunately
-        # a keyword arg cannot be distinguished from a flag arg followed by a
-        # positional arg without the context of what arguments are expected.
+        # there are a couple of issues that require context to be able to handle
+        # properly:
+        # - a keyword arg cannot be distinguished from a flag arg followed by a
+        #   positional arg without the context of what arguments are expected.
+        # - command arguments will normally have their own set of additional
+        #   arguments that must be added once we know which command has been
+        #   entered.
         def classify_tokens(tokens)
             if tokens.is_a?(String)
                 require 'csv'
@@ -86,37 +107,68 @@ module ArgParser
             rest_vals = []
 
             arg = nil
+            pos_args = @definition.positional_args
             tokens.each_with_index do |token, i|
+                if token.downcase == 'help' && i == 0
+                    # Accept 'help' as the first token
+                    @show_help = true
+                    next
+                end
                 case token
                 when '/?', '-?', '--help'
                     @show_help = true
                 when /^[-\/]([a-z0-9]+)$/i
+                    # One or more short keys
                     $1.to_s.each_char do |sk|
                         kw_vals[arg] = nil if arg
                         arg = @definition[sk]
                         if FlagArgument === arg
                             kw_vals[arg] = true
                             arg = nil
+                        elsif PositionalArgument == arg
+                            pos_args.delete(arg)
                         end
                     end
-                when /^--(no-)?(.+)/i
+                when /^--(no[nt]?-)?(.+)/i
+                    # Long key
                     kw_vals[arg] = nil if arg
                     arg = @definition[$2]
                     if FlagArgument === arg || (KeywordArgument === arg && $1)
                         kw_vals[arg] = $1 ? false : true
                         arg = nil
+                    elsif PositionalArgument === arg
+                        pos_args.delete(arg)
                     end
                 when '--'
                     # All subsequent values are rest args
                     kw_vals[arg] = nil if arg
+                    unless rest_vals.empty?
+                        self.errors << "Too many positional arguments supplied before -- token"
+                    end
                     rest_vals = tokens[(i + 1)..-1]
                     break
                 else
                     if arg
                         kw_vals[arg] = token
+                    elsif pos_args.size > 0
+                        arg = pos_args.shift
+                        if CommandArgument === arg
+                            if cmd_inst = arg[token]
+                                # Merge command's arg set with the current definition
+                                @definition = @definition.collapse(cmd_inst)
+                                # Insert command positional arguments
+                                pos_args.insert(0, *cmd_inst.argument_scope.positional_args)
+                                pos_vals << cmd_inst.command_value
+                            else
+                                self.errors << "'#{token}' is not a valid value for #{arg}; valid values are: #{
+                                    arg.commands.keys.join(', ')}"
+                            end
+                            arg = nil   # Commands can't be sensitive
+                        else
+                            pos_vals << token
+                        end
                     else
-                        pos_vals << token
-                        arg = @definition.positional_args[i]
+                        rest_vals << token
                     end
                     tokens[i] = '******' if arg && arg.sensitive?
                     arg = nil
@@ -154,11 +206,14 @@ module ArgParser
             end
 
             # Process rest values
-            if rest_arg = @definition.rest_args
-                result[rest_arg.key] = process_arg_val(rest_arg, rest_vals, result)
-            elsif rest_vals.size > 0
-                self.errors << "#{rest_vals.size} rest #{rest_vals.size == 1 ? 'value' : 'values'} #{
-                    rest_vals.size == 1 ? 'was' : 'were'} supplied, but no rest argument is defined"
+            if rest_vals.size > 0
+                if rest_arg = @definition.rest_args
+                    result[rest_arg.key] = process_arg_val(rest_arg, rest_vals, result)
+                else
+                    self.errors << "#{rest_vals.size} rest #{rest_vals.size == 1 ? 'value' : 'values'} #{
+                        rest_vals.size == 1 ? 'was' : 'were'} supplied (#{rest_vals.join(', ')
+                        }), but no rest argument is defined"
+                end
             end
 
             # Default unspecified arguments

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arg-parser
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.1
 platform: ruby
 authors:
 - Adam Gardiner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-13 00:00:00.000000000 Z
+date: 2019-07-04 00:00:00.000000000 Z
 dependencies: []
 description: |2
           ArgParser is a simple, yet powerful command-line argument parser, with
@@ -19,13 +19,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- README.md
 - LICENSE
+- README.md
+- lib/arg-parser.rb
 - lib/arg-parser/argument.rb
 - lib/arg-parser/definition.rb
 - lib/arg-parser/dsl.rb
 - lib/arg-parser/parser.rb
-- lib/arg-parser.rb
 - lib/arg_parser.rb
 homepage: https://github.com/agardiner/arg-parser
 licenses: []
@@ -36,17 +36,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14.1
+rubygems_version: 2.5.2.3
 signing_key: 
 specification_version: 4
 summary: ArgParser is a simple, yet powerful, command-line argument (option) parser