Class: Cri::OptionParser

Inherits:
Object
  • Object
show all
Defined in:
lib/cri/option_parser.rb

Overview

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, :multiple => true },
  { :short => 'p', :long => 'port', :argument => :required, :multiple => false },
]

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'
  }
}

Defined Under Namespace

Classes: IllegalOptionError, OptionRequiresAnArgumentError

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (OptionParser) initialize(arguments_and_options, definitions)

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

Parameters:

  • arguments_and_options (Array<String>)

    An array containing the commandline arguments (will probably be ARGS for a root command)

  • definitions (Array<Hash>)

    An array of option definitions



114
115
116
117
118
119
120
121
122
123
# File 'lib/cri/option_parser.rb', line 114

def initialize(arguments_and_options, definitions)
  @unprocessed_arguments_and_options = arguments_and_options.dup
  @definitions = definitions

  @options       = {}
  @raw_arguments = []

  @running = false
  @no_more_options = false
end

Instance Attribute Details

- (#option_added, #argument_added) delegate

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)

Returns:

  • (#option_added, #argument_added)

    The delegate



74
75
76
# File 'lib/cri/option_parser.rb', line 74

def delegate
  @delegate
end

- (Hash) options (readonly)

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.

Returns:

  • (Hash)

    The already parsed options.



83
84
85
# File 'lib/cri/option_parser.rb', line 83

def options
  @options
end

- (Array) raw_arguments (readonly)

Returns The arguments that have already been parsed, including the -- separator.

Returns:

  • (Array)

    The arguments that have already been parsed, including the -- separator.



87
88
89
# File 'lib/cri/option_parser.rb', line 87

def raw_arguments
  @raw_arguments
end

- (Array) unprocessed_arguments_and_options (readonly)

The options and arguments that have not yet been processed. If the parser wasn’t stopped (using #stop), this list will be empty.

Returns:

  • (Array)

    The not yet parsed options and arguments.



93
94
95
# File 'lib/cri/option_parser.rb', line 93

def unprocessed_arguments_and_options
  @unprocessed_arguments_and_options
end

Class Method Details

+ (Cri::OptionParser) parse(arguments_and_options, definitions)

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

Parameters:

  • arguments_and_options (Array<String>)

    An array containing the commandline arguments (will probably be ARGS for a root command)

  • definitions (Array<Hash>)

    An array of option definitions

Returns:



104
105
106
# File 'lib/cri/option_parser.rb', line 104

def self.parse(arguments_and_options, definitions)
  new(arguments_and_options, definitions).run
end

Instance Method Details

- (Array) arguments

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.

Returns:

  • (Array)

    The already parsed arguments.



132
133
134
# File 'lib/cri/option_parser.rb', line 132

def arguments
  ArgumentArray.new(@raw_arguments).freeze
end

- (Cri::OptionParser) run

Parses the commandline arguments into options and arguments.

During parsing, two errors can be raised:

Returns:

Raises:

  • IllegalOptionError if an unrecognised option was encountered, i.e. an option that is not present in the list of option definitions

  • OptionRequiresAnArgumentError if an option was found that did not have a value, even though this value was required.



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
# File 'lib/cri/option_parser.rb', line 160

def run
  @running = true

  while running?
    # Get next item
    e = @unprocessed_arguments_and_options.shift
    break if e.nil?

    if e == '--'
      handle_dashdash(e)
    elsif e =~ /^--./ && !@no_more_options
      handle_dashdash_option(e)
    elsif e =~ /^-./ && !@no_more_options
      handle_dash_option(e)
    else
      add_argument(e)
    end
  end
  self
ensure
  @running = false
end

- (Boolean) running?

Returns true if the parser is running, false otherwise.

Returns:

  • (Boolean)

    true if the parser is running, false otherwise.



137
138
139
# File 'lib/cri/option_parser.rb', line 137

def running?
  @running
end

- (void) stop

This method returns an undefined value.

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



145
146
147
# File 'lib/cri/option_parser.rb', line 145

def stop
  @running = false
end