Class Cri::OptionParser
In: lib/cri/option_parser.rb
Parent: Object

Cri::OptionParser is used for parsing commandline options.

Option definitions are hashes with the keys `:short`, `:long` and `:argument` (optionally `:description` but this is not used by the option parser, only by the help generator). `:short` is the short, one-character option, without the `-` prefix. `:long` is the long, multi-character option, without the `—` prefix. `:argument` can be :required (if an argument should be provided to the option), :optional (if an argument may be provided) or :forbidden (if an argument should not be provided).

A sample array of definition hashes could look like this:

    [
      { :short => 'a', :long => 'all',  :argument => :forbidden },
      { :short => 'p', :long => 'port', :argument => :required  },
    ]

For example, the following commandline options (which should not be passed as a string, but as an array of strings):

    foo -xyz -a hiss -s -m please --level 50 --father=ani -n luke squeak

with the following option definitions:

    [
      { :short => 'x', :long => 'xxx',    :argument => :forbidden },
      { :short => 'y', :long => 'yyy',    :argument => :forbidden },
      { :short => 'z', :long => 'zzz',    :argument => :forbidden },
      { :short => 'a', :long => 'all',    :argument => :forbidden },
      { :short => 's', :long => 'stuff',  :argument => :optional  },
      { :short => 'm', :long => 'more',   :argument => :optional  },
      { :short => 'l', :long => 'level',  :argument => :required  },
      { :short => 'f', :long => 'father', :argument => :required  },
      { :short => 'n', :long => 'name',   :argument => :required  }
    ]

will be translated into:

    {
      :arguments => [ 'foo', 'hiss', 'squeak' ],
      :options => {
        :xxx    => true,
        :yyy    => true,
        :zzz    => true,
        :all    => true,
        :stuff  => true,
        :more   => 'please',
        :level  => '50',
        :father => 'ani',
        :name   => 'luke'
      }
    }

Methods

arguments   new   parse   run   running?   stop  

Classes and Modules

Class Cri::OptionParser::IllegalOptionError
Class Cri::OptionParser::OptionRequiresAnArgumentError

Attributes

delegate  [RW]  The delegate to which events will be sent. The following methods will be send to the delegate:
  • `option_added(key, value, cmd)`
  • `argument_added(argument, cmd)`

@return [option_added, argument_added] The delegate

options  [R]  The options that have already been parsed.

If the parser was stopped before it finished, this will not contain all options and `unprocessed_arguments_and_options` will contain what is left to be processed.

@return [Hash] The already parsed options.

raw_arguments  [R]  @return [Array] The arguments that have already been parsed, including
  the -- separator.
unprocessed_arguments_and_options  [R]  The options and arguments that have not yet been processed. If the parser wasn’t stopped (using {stop}), this list will be empty.

@return [Array] The not yet parsed options and arguments.

Public Class methods

Creates a new parser with the given options/arguments and definitions.

@param [Array<String>] arguments_and_options An array containing the

  commandline arguments (will probably be `ARGS` for a root command)

@param [Array<Hash>] definitions An array of option definitions

Parses the commandline arguments. See the instance `parse` method for details.

@param [Array<String>] arguments_and_options An array containing the

  commandline arguments (will probably be `ARGS` for a root command)

@param [Array<Hash>] definitions An array of option definitions

@return [Cri::OptionParser] The option parser self

Public Instance methods

Returns the arguments that have already been parsed.

If the parser was stopped before it finished, this will not contain all options and `unprocessed_arguments_and_options` will contain what is left to be processed.

@return [Array] The already parsed arguments.

Parses the commandline arguments into options and arguments.

During parsing, two errors can be raised:

@raise IllegalOptionError if an unrecognised option was encountered,

  i.e. an option that is not present in the list of option definitions

@raise OptionRequiresAnArgumentError if an option was found that did not

  have a value, even though this value was required.

@return [Cri::OptionParser] The option parser self

@return [Boolean] true if the parser is running, false otherwise.

Stops the parser. The parser will finish its current parse cycle but will not start parsing new options and/or arguments.

@return [void]

[Validate]