: Boson::OptionParser [RDoc Documentation]

This class concisely defines commandline options that when parsed produce a Hash of option keys and values. Additional points:

Setting option values should follow conventions in *nix environments. See examples below.
By default, there are 5 option types, each which produce different objects for option values.
The default option types can produce objects for one or more of the following Ruby classes: String, Integer, Float, Array, Hash, FalseClass, TrueClass.
Users can define their own option types which create objects for any Ruby class. See Options.
Each option type can have attributes to enable more features (see OptionParser.new).
When options are parsed by parse(), an IndifferentAccessHash hash is returned.
Options are also called switches, parameters, flags etc.
Option parsing stops when it comes across a ’—’.

Default option types:

:boolean

This option has no passed value. To toogle a boolean, prepend with ’—no-’. Multiple booleans can be joined together.

'--debug'    -> {:debug=>true}
'--no-debug' -> {:debug=>false}
'--no-d'     -> {:debug=>false}
'-d -f -t' same as '-dft'

:string

Sets values by separating name from value with space or ’=’.

'--color red' -> {:color=>'red'}
'--color=red' -> {:color=>'red'}
'--color "gotta love spaces"' -> {:color=>'gotta love spaces'}

:numeric

Sets values as :string does or by appending number right after aliased name. Shortened form can be appended to joined booleans.

'-n3'  -> {:num=>3}
'-dn3' -> {:debug=>true, :num=>3}

:array

Sets values as :string does. Multiple values are split by a configurable character Default is ’,’ (see OptionParser.new). Passing ’*’ refers to all known :values.

'--fields 1,2,3' -> {:fields=>['1','2','3']}
'--fields *'     -> {:fields=>['1','2','3']}

:hash

Sets values as :string does. Key-value pairs are split by ’:’ and pairs are split by a configurable character (default ’,’). Multiple keys can be joined to one value. Passing ’*’ as a key refers to all known :keys.

'--fields a:b,c:d' -> {:fields=>{'a'=>'b', 'c'=>'d'} }
'--fields a,b:d'   -> {:fields=>{'a'=>'d', 'b'=>'d'} }
'--fields *:d'     -> {:fields=>{'a'=>'d', 'b'=>'d', 'c'=>'d'} }

This is a modified version of Yehuda Katz’s Thor::Options class which is a modified version of Daniel Berger’s Getopt::Long class (licensed under Ruby’s license).

Methods

public instance

aliases
current_attributes
dasherize
default_usage
formatted_usage
names
non_opts
option_attributes
option_type
parse
print_usage_table
to_s
types
undasherize

Classes and Modules

Class Boson::OptionParser::Error

Constants

 /(\d*\.\d+|\d+)/
 /^(--\w+[-\w+]*)$/
 /^(-[a-zA-Z])$/i
 /^(--\w+[-\w+]*|-[a-zA-Z])=(.*)$/i
 /^-([a-zA-Z]{2,})$/i
 /^(-[a-zA-Z])#{NUMERIC}$/i
 %w{-- -}

Attributes

 leading_non_opts
 opt_aliases
 trailing_non_opts

Public class methods

new (opts)

Takes a hash of options. Each option, a key-value pair, must provide the option’s name and type. Names longer than one character are accessed with ’—’ while one character names are accessed with ’-’. Names can be symbols, strings or even dasherized strings:

Boson::OptionParser.new :debug=>:boolean, 'level'=>:numeric,
  '--fields'=>:array

Options can have default values and implicit types simply by changing the option type for the default value:

Boson::OptionParser.new :debug=>true, 'level'=>3.1, :fields=>%w{f1 f2}

By default every option name longer than one character is given an alias, the first character from its name. For example, the —fields option has -f as its alias. You can override the default alias by providing your own option aliases as an array in the option’s key.

Boson::OptionParser.new [:debug, :damnit, :D]=>true

Note that aliases are accessed the same way as option names. For the above, —debug, —damnit and -D all refer to the same option.

Options can have additional attributes by passing a hash to the option value instead of a type or default:

Boson::OptionParser.new :fields=>{:type=>:array, :values=>%w{f1 f2 f3},
 :enum=>false}

These attributes are available when an option is parsed via current_attributes(). Here are the available option attributes for the default option types:

:type: This or :default is required. Available types are :string, :boolean, :array, :numeric, :hash.
:default: This or :type is required. This is the default value an option has when not passed.
:bool_default: This is the value an option has when passed as a boolean. However, by enabling this an option can only have explicit values with ’=’ i.e. ’—index=alias’ and no ’—index alias’. If this value is a string, it is parsed as any option value would be. Otherwise, the value is passed directly without parsing.
:required: Boolean indicating if option is required. Option parses raises error if value not given. Default is false.
:alias: Alternative way to define option aliases with an option name or an array of them. Useful in yaml files. Setting to false will prevent creating an automatic alias.
:values: An array of values an option can have. Available for :array and :string options. Values here can be aliased by typing a unique string it starts with or underscore aliasing (see Util.underscore_search). For example, for values foo, odd and obnoxiously_long, f refers to foo, od to odd and o_l to obnoxiously_long.
:enum: Boolean indicating if an option enforces values in :values or :keys. Default is true. For :array, :hash and :string options.
:split: For :array and :hash options. A string or regular expression on which an array value splits to produce an array of values. Default is ’,’.
:keys: :hash option only. An array of values a hash option’s keys can have. Keys can be aliased just like :values.
:default_keys: For :hash option only. Default keys to assume when only a value is given. Multiple keys can be joined by the :split character. Defaults to first key of :keys if :keys given.
:regexp: For :array option with a :values attribute. Boolean indicating that each option value does a regular expression search of :values. If there are values that match, they replace the original option value. If none, then the original option value is used.

Class Boson::OptionParser