Optimist::Parser
Inherits Reference < Object
Constructors
Initializes the parser, and instance-evaluates any block given.
Instance methods
Adds text to the help display. Can be interspersed with calls to #opt to build a multi-section help page.
Create default text banner in a string so we can override it in the SubcommandParser class.
Marks two (or more!) options as requiring each other. Only handles undirected (i.e., mutual) dependencies. Directed dependencies are better modeled with Optimist::die.
The per-parser version of Optimist::die (see that for documentation).
Instead of displaying "Try --help for help." on an error display the usage (via educate)
A flag that determines whether or not to raise an error if the parser is passed one or more options that were not registered ahead of time. If 'true', then the parser will simply ignore options that it does not recognize.
A flag that determines whether or not to raise an error if the parser is passed one or more options that were not registered ahead of time. If 'true', then the parser will simply ignore options that it does not recognize.
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+. Use :none: to not have a short value. [+: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 Optimist::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, Optimist 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.
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+. Use :none: to not have a short value. [+: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 Optimist::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, Optimist 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.
Parses the commandline. Typically called by Optimist::options, but you can call it directly if you need more control.
throws CommandlineError, HelpNeeded, and VersionNeeded exceptions.
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 Optimist invocation would then be used to parse subcommand options, after shifting the subcommand off of ARGV.
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.
Provide a list of given subcommands. List will be empty if subcmd was never given.
Adds a synopsis (command summary description) right below the usage line, or as the first line if usage isn't specified.
Sets the usage string. If set the message will be printed as the first line in the help (educate) output and ending in two new lines.
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>".