arg-parser 0.1

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013, Adam Gardiner
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,80 @@
+# ArgParser
+
+ArgParser is a small library for parsing command-line arguments (or indeed any string or Array of text).
+It provides a simple DSL for defining the possible arguments, which may be one of the following:
+* Positional arguments, where values are specified without any keyword, and their meaning is based on the
+  order in which they appear in the command-line.
+* Keyword arguments, which are identified by a long- or short-key preceding the value.
+* Flag arguments, which are essentially boolean keyword arguments. The presence of the key implies a true
+  value.
+* A Rest argument, which is an argument definition that takes 0 or more trailing positional arguments.
+
+## Usage
+
+ArgParser is supplied as a gem, and has no dependencies. To use it, simply:
+```
+gem install arg-parser
+```
+
+ArgParser provides a DSL module that can be included into any class to provide argument parsing.
+
+```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
+
+    positional_arg :my_positional_arg, 'This is a positional arg'
+    keyword_arg :my_keyword_arg, 'This is a keyword arg'
+    flag_arg :flag, 'This is a flag argument'
+    rest_arg :files, 'This is where we specify that remaining args will be collected in an array'
+
+
+    def run
+        if opts = parse_arguments
+            # Do something with opts.my_positional_arg, opts.my_keyword_arg,
+            # opts.flag, and opts.files
+            # ...
+        else
+            show_help? ? show_help : show_usage
+        end
+    end
+
+end
+
+
+MyClass.new.run
+
+```
+
+## Functionality
+
+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
+* 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.
+* Short-keys and long-keys: Arguments are defined with a long_key name which will be used to access the
+  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.
+* 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.
+       `validation: %w{one two three}`
+     - Regular expression: Pass a regular expression that the argument value must satisfy.
+       `validation: /.*\.rb$/`
+     - Proc: Pass a proc that will be called to validate the supplied argument value. If the proc returns
+       a non-falsey value, the argument is accepted, otherwise it is rejected.
+       `validation: lambda{ |val, arg, hsh| val.upcase == 'TRUE' }`
+* On-parse handler: A proc can be passed that will be called when the argument value is encountered
+  during parsing. The return value of the proc will be used as the argument result.
+  `on_parse: lambda{ |val, arg, hsh| val.split(',') }`
+

data/lib/arg-parser.rb

@@ -0,0 +1,5 @@
+require 'arg-parser/argument'
+require 'arg-parser/definition'
+require 'arg-parser/parser'
+require 'arg-parser/dsl'
+

data/lib/arg-parser/argument.rb

@@ -0,0 +1,332 @@
+# Namespace for classes defined by ArgParser, the command-line argument parser.
+module ArgParser
+
+    # Hash containing registered handlers for :on_parse options
+    OnParseHandlers = {
+        :split_to_array => lambda{ |val, arg, hsh| val.split(',') }
+    }
+
+
+    # Abstract base class of all command-line argument types.
+    #
+    # @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
+        # @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.
+        attr_reader :short_key
+        # @return [Boolean] whether this argument is a required (i.e. mandatory)
+        #   argument. Mandatory arguments that do not get specified result in a
+        #   ParseException.
+        attr_accessor :required
+        alias_method :required?, :required
+        # @return [String] the default value for the argument, returned in the
+        #   command-line parse results if no other value is specified.
+        attr_accessor :default
+        # An optional on_parse callback handler. The supplied block/Proc will be
+        # called after this argument has been parsed, with three arguments:
+        #   @param [String] The value from the command-line that was entered for
+        #     this argument.
+        #   @param [Argument] The Argument sub-class object that represents the
+        #     argument that was parsed.
+        #   @param [Hash] The results Hash containing the argument keys and their
+        #     values parsed so far.
+        # @return [Proc] the user supplied block to be called when the argument
+        #   has been parsed.
+        attr_accessor :on_parse
+        # @return [String] a label to use for a new section of options in the
+        #   argument usage display. Should be specified on the first argument in
+        #   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.
+        #
+        # @return [Symbol] the key by which an argument can be retrieved from
+        #   the arguments definition, and the parse results.
+        def self.to_key(label)
+            label.to_s.gsub(/^-+/, '').gsub('-', '_').downcase.intern
+        end
+
+
+        private
+
+        def initialize(key, desc, opts = {}, &block)
+            @key = self.class.to_key(key)
+            @description = desc
+            @default = opts[:default]
+            @on_parse = block || opts[:on_parse]
+            if @on_parse.is_a?(Symbol)
+                op = opts[:on_parse]
+                @on_parse = case
+                when OnParseHandlers.has_key?(op)
+                    OnParseHandlers[op]
+                when "".respond_to?(op)
+                    lambda{ |val, arg, hsh| val.send(op) }
+                else
+                    raise ArgumentError, "No on_parse handler registered for #{op.inspect}"
+                end
+            end
+            @usage_break = opts[:usage_break]
+            if sk = opts[:short_key]
+                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
+        end
+
+    end
+
+
+    # Abstract base class of arguments that take a value (i.e. positional and
+    # keyword arguments).
+    #
+    # @abstract
+    class ValueArgument < Argument
+
+        # @return [Boolean] Flag indicating that the value for this argument is
+        #   a sensitive value (e.g. a password) that should not be displayed.
+        attr_accessor :sensitive
+        alias_method :sensitive?, :sensitive
+        # @return [Array, Regexp, Proc] An optional validation that will be
+        #   applied to the argument value for this argument, to determine if it
+        #   is valid. The validation can take the following forms:
+        #     @param [Array] If an Array is specified, the supplied value will be
+        #       checked to verify it is one of the allowed values specified in the
+        #       Array.
+        #     @param [Regexp] If a Regexp object is supplied, the argument value
+        #       will be tested against the Regexp to verify it is valid.
+        #     @param [Proc] The most flexible option; the supplied value, this
+        #       ValueArgument sub-class object, and the parse results (thus far)
+        #       will be passed to the Proc for validation. The Proc must return a
+        #       non-falsey value for the argument to be accepted.
+        attr_accessor :validation
+        # @return [String] A label that will be used in the usage string printed
+        #   for this ValueArgument. If not specified, defaults to the upper-case
+        #   value of the argument key. For example, if the argument key is :foo_bar,
+        #   the default usage value for this argument would be FOO-BAR, as in:
+        #     Usage:
+        #       my-prog.rb FOO-BAR
+        attr_accessor :usage_value
+
+
+        private
+
+        def initialize(key, desc, opts = {}, &block)
+            super
+            @sensitive = opts[:sensitive]
+            @validation = opts[:validation]
+            @usage_value = opts.fetch(:usage_value, key.to_s.gsub('_', '-').upcase)
+        end
+
+    end
+
+
+    # An argument that is set by position on the command-line. PositionalArguments
+    # do not require a --key to be specified before the argument value; they are
+    # typically used when there are a small number of mandatory arguments.
+    #
+    # Positional arguments still have a key that is used to identify the parsed
+    # argument value in the results Struct. As such, it is not an error for a
+    # positional argument to be specified with its key - its just not mandatory
+    # for the key to be provided.
+    class PositionalArgument < ValueArgument
+
+        # Creates a new positional argument, which is an argument value that may
+        # be specified without a keyword, in which case it is matched to the
+        # available positional arguments by its position on the command-line.
+        #
+        # @param [Symbol] key The name that will be used for the accessor used
+        #   to return this argument value in the parse results.
+        # @param [String] desc A description for this argument. Appears in the
+        #   help output that is generated when the user specifies the --help or
+        #   /? flags on the command-line.
+        # @param [Hash] opts Contains any options that are desired for this
+        #   argument.
+        # @yield [val, arg, hsh] If supplied, the block passed will be invoked
+        #   after this argument value has been parsed from the command-line.
+        #   Blocks are usually used when the value to be returned needs to be
+        #   converted from a String to some other type.
+        # @yieldparam val [String] the String value read from the command-line
+        #   for this argument
+        # @yieldparam arg [PositionalArgument] this argument definition
+        # @yieldparam hsh [Hash] a Hash containing the argument values parsed
+        #   so far.
+        # @yieldreturn [Object] the return value from the block will be used as
+        #   the argument value  parsed from the command-line for this argument.
+        def initialize(key, desc, opts = {}, &block)
+            super
+            @required = opts.fetch(:required, !opts.has_key?(:default))
+        end
+
+        # @return [String] the word that will appear in the help display for
+        #   this argument.
+        def to_s
+            usage_value
+        end
+
+        # @return [String] the string for this argument position in a command-line
+        #   usage display.
+        def to_use
+            required? ? usage_value : "[#{usage_value}]"
+        end
+
+    end
+
+
+    # An argument that is specified via a keyword prefix; typically used
+    # for optional arguments, although Keyword arguments can also be used for
+    # mandatory arguments where there is no natural ordering of arguments.
+    class KeywordArgument < ValueArgument
+
+        # Whether the keyword argument must be specified with a non-missing
+        # value.
+        # @return [Boolean] true if the keyword can be specified without a value.
+        attr_accessor :value_optional
+        alias_method :value_optional?, :value_optional
+
+
+        # Creates a KeywordArgument, which is an argument that must be specified
+        # on a command-line using either a long form key (i.e. --key), or
+        # optionally, a short-form key (i.e. -k) should one be defined for this
+        # argument.
+        # @param key [Symbol] the key that will be used to identify this argument
+        #   value in the parse results.
+        # @param desc [String] the description of this argument, displayed in the
+        #   generated help screen.
+        # @param opts [Hash] a hash of options that govern the behaviour of this
+        #   argument.
+        # @option opts [Boolean] :required whether the keyword argument is a required
+        #   argument that must appear in the command-line. Defaults to false.
+        # @option opts [Boolean] :value_optional whether the keyword argument can be
+        #   specified without a value. For example, a keyword argument might
+        #   be used both as a flag, and to override a default value. Specifying
+        #   the argument without a value would signify that the option is set,
+        #   but the default value for the option should be used. Defaults to
+        #   false (keyword argument cannot be specified without a value).
+        def initialize(key, desc, opts = {}, &block)
+            super
+            @required = opts.fetch(:required, false)
+            @value_optional = opts.fetch(:value_optional, false)
+        end
+
+        def to_s
+            "--#{key}".gsub('_', '-')
+        end
+
+        def to_use
+            sk = short_key ? "-#{short_key}, " : ''
+            uv = value_optional ? "[#{usage_value}]" : usage_value
+            "#{sk}#{self.to_s} #{uv}"
+        end
+
+    end
+
+
+    # A boolean argument that is set if its key is encountered on the command-line.
+    # Flag arguments normally default to false, and become true if the argument
+    # key is specified. However, it is also possible to define a flag argument
+    # that defaults to true, in which case the option can be disabled by pre-
+    # pending the argument key with a 'no-' prefix, e.g. --no-export can be
+    # specified to disable the normally enabled --export flag.
+    class FlagArgument < Argument
+
+        # Creates a new flag argument, which is an argument with a boolean value.
+        #
+        # @param [Symbol] key The name that will be used for the accessor used
+        #   to return this argument value in the parse results.
+        # @param [String] desc A description for this argument. Appears in the
+        #   help output that is generated when the user specifies the --help or
+        #   /? flags on the command-line.
+        # @param [Hash] opts Contains any options that are desired for this
+        #   argument.
+        # @param [Block] block If supplied, the block passed will be invoked
+        #   after this argument value has been parsed from the command-line.
+        #   The block will be called with three arguments: this argument
+        #   definition, the String value read from the command-line for this
+        #   argument, and a Hash containing the argument values parsed so far.
+        #   The return value from the block will be used as the argument value
+        #   parsed from the command-line for this argument. Blocks are usually
+        #   used when the value to be returned needs to be converted from a
+        #   String to some other type.
+        def initialize(key, desc, opts = {}, &block)
+            super
+        end
+
+        def required
+            false
+        end
+
+        def to_s
+            "--#{self.default ? 'no-' : ''}#{key}".gsub('_', '-')
+        end
+
+        def to_use
+            sk = short_key ? "-#{short_key}, " : ''
+            "#{sk}#{self.to_s}"
+        end
+
+    end
+
+
+    # A command-line argument that takes 0 to N values from the command-line.
+    class RestArgument < ValueArgument
+
+        # Creates a new rest argument, which is an argument that consumes all
+        # remaining positional argument values.
+        #
+        # @param [Symbol] key The name that will be used for the accessor used
+        #   to return this argument value in the parse results.
+        # @param [String] desc A description for this argument. Appears in the
+        #   help output that is generated when the user specifies the --help or
+        #   /? flags on the command-line.
+        # @param [Hash] opts Contains any options that are desired for this
+        #   argument.
+        # @param [Block] block If supplied, the block passed will be invoked
+        #   after this argument value has been parsed from the command-line.
+        #   The block will be called with three arguments: this argument
+        #   definition, the String value read from the command-line for this
+        #   argument, and a Hash containing the argument values parsed so far.
+        #   The return value from the block will be used as the argument value
+        #   parsed from the command-line for this argument. Blocks are usually
+        #   used when the value to be returned needs to be converted from a
+        #   String to some other type.
+        def initialize(key, desc, opts = {}, &block)
+            super
+            @min_values = opts.fetch(:min_values, opts.fetch(:required, true) ? 1 : 0)
+        end
+
+        def required
+          @min_values > 0
+        end
+
+        # @return [String] the word that will appear in the help display for
+        #   this argument.
+        def to_s
+            usage_value
+        end
+
+        # @return [String] The string for this argument position in a command-line.
+        #  usage display.
+        def to_use
+            required? ? "#{usage_value} [...]" : "[#{usage_value} [...]]"
+        end
+
+    end
+
+end
+

data/lib/arg-parser/definition.rb

@@ -0,0 +1,422 @@
+module ArgParser
+
+    # Exeption thrown when an attempt is made to access an argument that is not
+    # defined.
+    class NoSuchArgumentError < RuntimeError; end
+
+
+    # Represents the collection of possible command-line arguments for a script.
+    class Definition
+
+        # @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
+
+
+        # Create a new Definition, which is a collection of valid Arguments to
+        # be used when parsing a command-line.
+        def initialize
+            @arguments = {}
+            @short_keys = {}
+            @require_set = Hash.new{ |h,k| h[k] = [] }
+            @title = $0.respond_to?(:titleize) ? $0.titleize : $0
+            yield self if block_given?
+        end
+
+
+        # @return [Argument] the argument for the given key if it exists, or nil
+        #   if it does not.
+        def has_key?(key)
+            k = Argument.to_key(key)
+            arg = @arguments[k] || @short_keys[k]
+        end
+
+
+        # @return [Argument] the argument with the specified key
+        # @raise [ArgumentError] if no argument has been defined with the
+        #   specified key.
+        def [](key)
+            arg = has_key?(key)
+            arg or raise NoSuchArgumentError, "No argument defined for key '#{Argument.to_key(key)}'"
+        end
+
+
+        # Adds the specified argument to the command-line definition.
+        #
+        # @param arg [Argument] An Argument sub-class to be added to the command-
+        #   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"
+                end
+                if arg.short_key && @short_keys[arg.short_key]
+                    raise ArgumentError, "An argument with short key '#{arg.short_key}' has already been defined"
+                end
+                if 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"
+            end
+        end
+
+
+        # Add a positional argument to the set of arguments in this command-line
+        # argument definition.
+        # @see PositionalArgument#initialize
+        def positional_arg(key, desc, opts = {}, &block)
+            self << ArgParser::PositionalArgument.new(key, desc, opts, &block)
+        end
+
+
+        # Add a keyword argument to the set of arguments in this command-line
+        # argument definition.
+        # @see KeywordArgument#initialize
+        def keyword_arg(key, desc, opts = {}, &block)
+            self << ArgParser::KeywordArgument.new(key, desc, opts, &block)
+        end
+
+
+        # Add a flag argument to the set of arguments in this command-line
+        # argument definition.
+        # @see FlagArgument#initialize
+        def flag_arg(key, desc, opts = {}, &block)
+            self << ArgParser::FlagArgument.new(key, desc, opts, &block)
+        end
+
+
+        # Add a rest argument to the set of arguments in this command-line
+        # argument definition.
+        # @see RestArgument#initialize
+        def rest_arg(key, desc, opts = {}, &block)
+            self << ArgParser::RestArgument.new(key, desc, opts, &block)
+        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) }
+                    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 arguments that have been defined.
+        def args
+            @arguments.values
+        end
+
+
+        # @return [Array] all positional arguments that have been defined
+        def positional_args
+            @arguments.values.select{ |arg| PositionalArgument === arg }
+        end
+
+
+        # @return True if any positional arguments have been defined.
+        def positional_args?
+            positional_args.size > 0
+        end
+
+
+        # @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 }
+        end
+
+
+        # @return True if any non-positional arguments have been defined.
+        def non_positional_args?
+            non_positional_args.size > 0
+        end
+
+
+        # @return [Array] the keyword arguments that have been defined.
+        def keyword_args
+            @arguments.values.select{ |arg| KeywordArgument === arg }
+        end
+
+
+        # @return True if any keyword arguments have been defined.
+        def keyword_args?
+            keyword_args.size > 0
+        end
+
+
+        # @return [Array] the flag arguments that have been defined
+        def flag_args
+            @arguments.values.select{ |arg| FlagArgument === arg }
+        end
+
+
+        # @return True if any flag arguments have been defined.
+        def flag_args?
+            flag_args.size > 0
+        end
+
+
+        # @return [RestArgument] the RestArgument defined for this command-line,
+        #   or nil if no RestArgument is defined.
+        def rest_args
+            @arguments.values.find{ |arg| RestArgument === arg }
+        end
+
+
+        # @return True if a RestArgument has been defined.
+        def rest_args?
+            !!rest_args
+        end
+
+
+        # @return [Array] all the positional, keyword, and rest arguments
+        #   that have been defined.
+        def value_args
+            @arguments.values.select{ |arg| ValueArgument === arg }
+        end
+
+
+        # @return [Integer] the number of arguments that have been defined.
+        def size
+            @arguments.size
+        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 << (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))
+            lines << ''
+            lines << 'Specify the /? or --help option for more detailed help'
+            lines << ''
+            lines.each{ |line| out.puts line } if out
+            lines
+        end
+
+
+        # Generates a more detailed help screen.
+        # @param out [IO] an IO object on which the help information will be
+        #   output. Pass +nil+ if no output to any device is desired.
+        # @param width [Integer] the width at which to wrap text.
+        # @return [Array] An array of lines of text, containing the help text.
+        def show_help(out = STDOUT, width = 80)
+            lines = ['', '']
+            lines << title
+            lines << title.gsub(/./, '=')
+            lines << ''
+            if purpose
+                lines.concat(wrap_text(purpose, width))
+                lines << ''
+                lines << ''
+            end
+
+            lines << 'USAGE'
+            lines << '-----'
+            pos_args = positional_args
+            opt_args = size - pos_args.size
+            usage_args = 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
+                pos_args = positional_args
+                pos_args << rest_args if rest_args?
+                pos_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?
+                    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 non_positional_args?
+                lines << ''
+                lines << 'OPTIONS'
+                lines << '-------'
+                max = non_positional_args.map{ |a| a.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?
+                    wrap_text(desc, width - max - 6).each_with_index do |line, i|
+                        lines << "  %-#{max}s    %s" % [[arg.to_use][i], line]
+                    end
+                end
+            end
+            lines << ''
+
+            lines.each{ |line| line.length < width ? out.puts(line) : out.print(line) } if out
+            lines
+        end
+
+
+        # Utility method for wrapping lines of +text+ at +width+ characters.
+        #
+        # @param text [String] a string of text that is to be wrapped to a
+        #   maximum width.
+        # @param width [Integer] the maximum length of each line of text.
+        # @return [Array] an Array of lines of text, each no longer than +width+
+        #   characters.
+        def wrap_text(text, width)
+            if width > 0 && (text.length > width || text.index("\n"))
+                lines = []
+                start, nl_pos, ws_pos, wb_pos, end_pos = 0, 0, 0, 0, text.rindex(/[^\s]/)
+                while start < end_pos
+                    last_start = start
+                    nl_pos = text.index("\n", start)
+                    ws_pos = text.rindex(/ +/, start + width)
+                    wb_pos = text.rindex(/[\-,.;#)}\]\/\\]/, start + width - 1)
+                    ### Debug code ###
+                    #STDERR.puts self
+                    #ind = ' ' * end_pos
+                    #ind[start] = '('
+                    #ind[start+width < end_pos ? start+width : end_pos] = ']'
+                    #ind[nl_pos] = 'n' if nl_pos
+                    #ind[wb_pos] = 'b' if wb_pos
+                    #ind[ws_pos] = 's' if ws_pos
+                    #STDERR.puts ind
+                    ### End debug code ###
+                    if nl_pos && nl_pos <= start + width
+                        lines << text[start...nl_pos].strip
+                        start = nl_pos + 1
+                    elsif end_pos < start + width
+                        lines << text[start..end_pos]
+                        start = end_pos
+                    elsif ws_pos && ws_pos > start && ((wb_pos.nil? || ws_pos > wb_pos) ||
+                          (wb_pos && wb_pos > 5 && wb_pos - 5 < ws_pos))
+                        lines << text[start...ws_pos]
+                        start = text.index(/[^\s]/, ws_pos + 1)
+                    elsif wb_pos && wb_pos > start
+                        lines << text[start..wb_pos]
+                        start = wb_pos + 1
+                    else
+                        lines << text[start...(start+width)]
+                        start += width
+                    end
+                    if start <= last_start
+                        # Detect an infinite loop, and just return the original text
+                        STDERR.puts "Inifinite loop detected at #{__FILE__}:#{__LINE__}"
+                        STDERR.puts "  width: #{width}, start: #{start}, nl_pos: #{nl_pos}, " +
+                                    "ws_pos: #{ws_pos}, wb_pos: #{wb_pos}"
+                        return [text]
+                    end
+                end
+                lines
+            else
+                [text]
+            end
+        end
+
+    end
+
+end
+

data/lib/arg-parser/dsl.rb

@@ -0,0 +1,151 @@
+module ArgParser
+
+    # Namespace for DSL methods that can be imported into a class for defining
+    # command-line argument handling.
+    #
+    # @example
+    #   class MyClass
+    #       include ArgParser::DSL
+    #
+    #       # These class methods are added by the DSL, and allow us to define
+    #       # the command-line arguments we want our class to handle.
+    #       positional_arg :command, 'The name of the sub-command to run',
+    #           validation: ['process', 'list'] do |arg, val, hsh|
+    #               # On parse, return the argument value as a symbol
+    #               val.intern
+    #           end
+    #       rest_arg :files, 'The file(s) to process'
+    #
+    #       def run
+    #           # Parse the command-line arguments, and call the appropriate command
+    #           args = parse_arguments
+    #           send(args.command, *args.files)
+    #       end
+    #
+    #       def process(*files)
+    #           ...
+    #       end
+    #
+    #       def list(*files)
+    #           ...
+    #       end
+    #   end
+    module DSL
+
+        # Class methods added when DSL module is included into a class.
+        module ClassMethods
+
+            # Accessor to return a Definition object holding the command-line
+            # argument definitions.
+            def args_def
+                @args_def ||= ArgParser::Definition.new
+            end
+
+            # Returns true if any arguments have been defined
+            def args_defined?
+                @args_def && @args_def.args.size > 0
+            end
+
+            # Sets the title that will appear in the Usage output generated from
+            # the Definition.
+            def title(val)
+                args_def.title = val
+            end
+
+            # Sets the descriptive text that describes the purpose of the job
+            # represented by this class.
+            def purpose(desc)
+                args_def.purpose = desc
+            end
+
+            # Define a new positional argument.
+            # @see PositionalArgument#initialize
+            def positional_arg(key, desc, opts = {}, &block)
+                args_def.positional_arg(key, desc, opts, &block)
+            end
+
+            # Define a new positional argument.
+            # @see KeywordArgument#initialize
+            def keyword_arg(key, desc, opts = {}, &block)
+                args_def.keyword_arg(key, desc, opts, &block)
+            end
+
+            # Define a new flag argument.
+            # @see FlagArgument#initialize
+            def flag_arg(key, desc, opts = {}, &block)
+                args_def.flag_arg(key, desc, opts, &block)
+            end
+
+            # Define a rest argument.
+            # @see RestArgument#initialize
+            def rest_arg(key, desc, opts = {}, &block)
+                args_def.rest_arg(key, desc, opts, &block)
+            end
+
+            # Make exactly one of the specified arguments mandatory.
+            # @see Definition#require_one_of
+            def require_one_of(*keys)
+                args_def.require_one_of(*keys)
+            end
+
+            # Make one or more of the specified arguments mandatory.
+            # @see Definition#require_any_of
+            def require_any_of(*keys)
+                args_def.require_any_of(*keys)
+            end
+
+        end
+
+        # Hook used to extend the including class with class methods defined in
+        # the DSL ClassMethods module.
+        def self.included(base)
+            base.extend(ClassMethods)
+        end
+
+        # @return [Definition] The arguments Definition object defined on this
+        #   class.
+        def args_def
+            self.class.args_def
+        end
+
+        # Defines a +parse_arguments+ instance method to be added to classes that
+        # include this module. Uses the +args_def+ argument definition stored on
+        # on the class to define the arguments to parse.
+        def parse_arguments(args = ARGV)
+          args_def.parse(args)
+        end
+
+
+        # Defines a +parse_errors+ instance method to be added to classes that
+        # include this module.
+        def parse_errors
+            args_def.errors
+        end
+
+
+        # Whether usage information should be displayed.
+        def show_usage?
+            args_def.show_usage?
+        end
+
+
+        # Whether help should be displayed.
+        def show_help?
+            args_def.show_usage?
+        end
+
+
+        # Outputs brief usgae details.
+        def show_usage(*args)
+            args_def.show_usage(*args)
+        end
+
+
+        # Outputs detailed help about available arguments.
+        def show_help(*args)
+            args_def.show_help(*args)
+        end
+
+    end
+
+end

data/lib/arg-parser/parser.rb

@@ -0,0 +1,237 @@
+module ArgParser
+
+    # Parser for parsing a command-line
+    class Parser
+
+        # @return [Definition] The supported Arguments to be used when parsing
+        #   the command-line.
+        attr_reader :definition
+        # @return [Array] An Array of error message Strings generated during
+        #   parsing.
+        attr_reader :errors
+        # @return [Boolean] Flag set during parsing if the usage display should
+        #   be shown. Set if there are any parse errors encountered.
+        def show_usage?
+            @show_usage
+        end
+        # @return [Boolean] Flag set during parsing if the user has requested
+        #   the help display to be shown (via --help or /?).
+        def show_help?
+            @show_help
+        end
+
+
+        # Instantiates a new command-line parser, with the specified command-
+        # line definition. A Parser instance delegates unknown methods to the
+        # Definition, so its possible to work only with a Parser instance to
+        # both define and parse a command-line.
+        #
+        # @param [Definition] definition A Definition object that defines the
+        #   possible arguments that may appear in a command-line. If no definition
+        #   is supplied, an empty definition is created.
+        def initialize(definition = nil)
+            @definition = definition || Definition.new
+            @errors = []
+        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.
+        def parse(tokens = ARGV)
+            @show_usage = nil
+            @show_help = nil
+            @errors = []
+            begin
+                pos_vals, kw_vals, rest_vals = classify_tokens(tokens)
+                args = process_args(pos_vals, kw_vals, rest_vals) unless @show_help
+            rescue NoSuchArgumentError => ex
+                self.errors << ex.message
+                @show_usage = true
+            end
+            (@show_usage || @show_help) ? false : args
+        end
+
+
+        # Delegate unknown methods to the associated argument Definition object.
+        def method_missing(mthd, *args)
+            if @definition.respond_to?(mthd)
+                @definition.send(mthd, *args)
+            else
+                super
+            end
+        end
+
+
+        # 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.
+        def classify_tokens(tokens)
+            if tokens.is_a?(String)
+                require 'csv'
+                tokens = CSV.parse(tokens, col_sep: ' ').first
+            end
+            tokens = [] unless tokens
+            pos_vals = []
+            kw_vals = {}
+            rest_vals = []
+
+            arg = nil
+            tokens.each_with_index do |token, i|
+                case token
+                when '/?', '-?', '--help'
+                    @show_help = true
+                when /^-([a-z0-9]+)/i
+                    $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
+                        end
+                    end
+                when /^(?:--|\/)(no-)?(.+)/i
+                    kw_vals[arg] = nil if arg
+                    arg = @definition[$2]
+                    if FlagArgument === arg || (KeywordArgument === arg && $1)
+                        kw_vals[arg] = $1 ? false : true
+                        arg = nil
+                    end
+                when '--'
+                    # All subsequent values are rest args
+                    kw_vals[arg] = nil if arg
+                    rest_vals = tokens[(i + 1)..-1]
+                    break
+                else
+                    if arg
+                        kw_vals[arg] = token
+                    else
+                        pos_vals << token
+                        arg = @definition.positional_args[i]
+                    end
+                    tokens[i] = '******' if arg && arg.sensitive?
+                    arg = nil
+                end
+            end
+            kw_vals[arg] = nil if arg
+            [pos_vals, kw_vals, rest_vals]
+        end
+
+
+        # Process arguments using the supplied +pos_vals+ Array of positional
+        # argument values, and the +kw_vals+ Hash of keyword/value.
+        def process_args(pos_vals, kw_vals, rest_vals)
+            result = {}
+
+            # Process positional arguments
+            pos_args = @definition.positional_args
+            pos_args.each_with_index do |arg, i|
+                break if i >= pos_vals.length
+                result[arg.key] = process_arg_val(arg, pos_vals[i], result)
+            end
+            if pos_vals.size > pos_args.size
+                if @definition.rest_args?
+                    rest_vals = pos_vals[pos_args.size..-1] + rest_vals
+                else
+                    self.errors << "#{pos_vals.size} positional #{pos_vals.size == 1 ? 'argument' : 'arguments'} #{
+                        pos_vals.size == 1 ? 'was' : 'were'} supplied, but only #{pos_args.size} #{
+                        pos_args.size == 1 ? 'is' : 'are'} defined"
+                end
+            end
+
+            # Process key-word based arguments
+            kw_vals.each do |arg, val|
+                result[arg.key] = process_arg_val(arg, val, result)
+            end
+
+            # Process rest values
+            if arg = @definition.rest_args
+                result[arg.key] = process_arg_val(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"
+            end
+
+            # Default unspecified arguments
+            @definition.args.select{ |arg| !result.has_key?(arg.key) }.each do |arg|
+                result[arg.key] = process_arg_val(arg, arg.default, result, true)
+            end
+
+            # Validate if any set requirements have been satisfied
+            self.errors.concat(@definition.validate_requirements(result))
+            if self.errors.size > 0
+                @show_usage = true
+            else
+                props = result.keys
+                @definition.args.each{ |arg| props << arg.key unless result.has_key?(arg.key) }
+                args = Struct.new(*props)
+                args.new(*result.values)
+            end
+        end
+
+
+        protected
+
+
+        # Process a single argument value
+        def process_arg_val(arg, val, hsh, is_default = false)
+            if is_default && arg.required? && (val.nil? || val.empty?)
+                self.errors << "No value was specified for required argument '#{arg}'"
+                return
+            end
+            if !is_default && val.nil? && KeywordArgument === arg && !arg.value_optional?
+                self.errors << "No value was specified for keyword argument '#{arg}'"
+                return
+            end
+
+            # Argument value validation
+            if ValueArgument === arg && arg.validation && val
+                valid = case arg.validation
+                when Regexp
+                    [val].flatten.each do |v|
+                        add_value_error(arg, val) unless v =~ arg.validation
+                    end
+                when Array
+                    [val].flatten.each do |v|
+                        add_value_error(arg, val) unless arg.validation.include?(v)
+                    end
+                when Proc
+                    begin
+                        arg.validation.call(val, arg, hsh)
+                    rescue StandardError => ex
+                        self.errors << "An error occurred in the validation handler for argument '#{arg}': #{ex}"
+                        return
+                    end
+                else
+                    raise "Unknown validation type: #{arg.validation.class.name}"
+                end
+            end
+
+            # TODO: Argument value coercion
+
+            # Call any registered on_parse handler
+            begin
+                val = arg.on_parse.call(val, arg, hsh) if val && arg.on_parse
+            rescue StandardError => ex
+                self.errors << "An error occurred in the on_parse handler for argument '#{arg}': #{ex}"
+                return
+            end
+
+            # Return result
+            val
+        end
+
+
+        # Add an error for an invalid value
+        def add_value_error(arg, val)
+            self.errors << "The value '#{val}' is not valid for argument '#{arg}'"
+        end
+
+    end
+
+end
+

data/lib/arg_parser.rb

@@ -0,0 +1,2 @@
+require 'arg-parser'
+

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: arg-parser
+version: !ruby/object:Gem::Version
+  version: '0.1'
+  prerelease: 
+platform: ruby
+authors:
+- Adam Gardiner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-21 00:00:00.000000000 Z
+dependencies: []
+description: ! "        ArgParser is a simple, yet powerful command-line argument
+  parser, with\n        support for positional, keyword, flag and rest arguments,
+  any of which\n        may be optional or mandatory.\n"
+email: adam.b.gardiner@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- LICENSE
+- 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: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.21
+signing_key: 
+specification_version: 3
+summary: ArgParser is a simple, yet powerful, command-line argument (option) parser
+test_files: []