Class Trollop::Parser
In: lib/trollop.rb
Parent: Object

The commandline parser. In typical usage, the methods in this class will be handled internally by Trollop::options. In this case, only the opt, banner and version, depends, and conflicts methods will typically be called.

If it‘s necessary to instantiate this class (for more complicated argument-parsing situations), be sure to call parse to actually produce the output hash.

Methods

banner   conflicts   depends   educate   new   opt   parse   stop_on   stop_on_unknown   text   version  

Constants

FLAG_TYPES = [:flag, :bool, :boolean]   The set of values that indicate a flag option when passed as the +:type+ parameter of opt.
SINGLE_ARG_TYPES = [:int, :integer, :string, :double, :float, :io, :date]   The set of values that indicate a single-parameter (normal) option when passed as the +:type+ parameter of opt.

A value of io corresponds to a readable IO resource, including a filename, URI, or the strings ‘stdin’ or ’-’.

MULTI_ARG_TYPES = [:ints, :integers, :strings, :doubles, :floats, :ios, :dates]   The set of values that indicate a multiple-parameter option (i.e., that takes multiple space-separated values on the commandline) when passed as the +:type+ parameter of opt.
TYPES = FLAG_TYPES + SINGLE_ARG_TYPES + MULTI_ARG_TYPES   The complete set of legal values for the +:type+ parameter of opt.

Attributes

leftovers  [R]  The values from the commandline that were not interpreted by parse.
specs  [R]  The complete configuration hashes for each option. (Mainly useful for testing.)

Public Class methods

new(*a, &b)

Initializes the parser, and instance-evaluates any block given.

Public Instance methods

banner(s;)

Adds text to the help display. Can be interspersed with calls to opt to build a multi-section help page.

conflicts(*syms)

Marks two (or more!) options as conflicting.

depends(*syms)

Marks two (or more!) options as requiring each other. Only handles undirected (i.e., mutual) dependencies. Directed dependencies are better modeled with Trollop::die.

educate(stream=$stdout)

Print the help message to stream.

opt(name, desc="", opts={})

Define an option. name is the option name, a unique identifier for the option that you will use internally, which should be a symbol or a string. desc is a string description which will be displayed in help messages.

Takes the following optional arguments:

+:long+
Specify the long form of the argument, i.e. the form with two dashes. If unspecified, will be automatically derived based on the argument name by turning the name option into a string, and replacing any _‘s by -’s.
+:short+
Specify the short form of the argument, i.e. the form with one dash. If unspecified, will be automatically derived from name.
+:type+
Require that the argument take a parameter or parameters of type type. For a single parameter, the value can be a member of SINGLE_ARG_TYPES, or a corresponding Ruby class (e.g. Integer for +:int+). For multiple-argument parameters, the value can be any member of MULTI_ARG_TYPES constant. If unset, the default argument type is +:flag+, meaning that the argument does not take a parameter. The specification of +:type+ is not necessary if a +:default+ is given.
+:default+
Set the default value for an argument. Without a default value, the hash returned by parse (and thus Trollop::options) will have a nil value for this key unless the argument is given on the commandline. The argument type is derived automatically from the class of the default value given, so specifying a +:type+ is not necessary if a +:default+ is given. (But see below for an important caveat when +:multi+: is specified too.) If the argument is a flag, and the default is set to true, then if it is specified on the the commandline the value will be false.
+:required+
If set to true, the argument must be provided on the commandline.
+:multi+
If set to true, allows multiple occurrences of the option on the commandline. Otherwise, only a single instance of the option is allowed. (Note that this is different from taking multiple parameters. See below.)

Note that there are two types of argument multiplicity: an argument can take multiple values, e.g. "—arg 1 2 3". An argument can also be allowed to occur multiple times, e.g. "—arg 1 —arg 2".

Arguments that take multiple values should have a +:type+ parameter drawn from MULTI_ARG_TYPES (e.g. +:strings+), or a +:default:+ value of an array of the correct type (e.g. [String]). The value of this argument will be an array of the parameters on the commandline.

Arguments that can occur multiple times should be marked with +:multi+ => true. The value of this argument will also be an array. In contrast with regular non-multi options, if not specified on the commandline, the default value will be [], not nil.

These two attributes can be combined (e.g. +:type+ => +:strings+, +:multi+ => true), in which case the value of the argument will be an array of arrays.

There‘s one ambiguous case to be aware of: when +:multi+: is true and a +:default+ is set to an array (of something), it‘s ambiguous whether this is a multi-value argument as well as a multi-occurrence argument. In thise case, Trollop assumes that it‘s not a multi-value argument. If you want a multi-value, multi-occurrence argument with a default value, you must specify +:type+ as well.

parse(cmdline=ARGV)

Parses the commandline. Typically called by Trollop::options.

stop_on(*words)

Defines a set of words which cause parsing to terminate when encountered, such that any options to the left of the word are parsed as usual, and options to the right of the word are left intact.

A typical use case would be for subcommand support, where these would be set to the list of subcommands. A subsequent Trollop invocation would then be used to parse subcommand options, after shifting the subcommand off of ARGV.

stop_on_unknown()

Similar to stop_on, but stops on any unknown word when encountered (unless it is a parameter for an argument). This is useful for cases where you don‘t know the set of subcommands ahead of time, i.e., without first parsing the global options.

text(s;)

Alias for banner

version(s=nil;)

Sets the version string. If set, the user can request the version on the commandline. Should probably be of the form "<program name> <version number>".

[Validate]