class Phreak::Subparser
- Phreak::Subparser
- Reference
- Object
Direct Known Subclasses
Defined in:
subparser.crConstructors
Instance Method Summary
-
#banner : String | Nil
An optional banner to display in the autogenerated help menu.
-
#banner=(banner : String | Nil)
An optional banner to display in the autogenerated help menu.
-
#bind(word : String | Nil = nil, long_flag : String | Nil = nil, short_flag : Char | Nil = nil, description : String | Nil = nil, &block : Subparser, String -> Nil) : Nil
Binds a keyword or keywords to a callback.
-
#command_section_width : Int8
The minumum width (word, long flag, and spaces) of the command section of the default help menu.
-
#command_section_width=(command_section_width : Int8)
The minumum width (word, long flag, and spaces) of the command section of the default help menu.
-
#fallback_description_padding : String
If the command section exceeds the width defined above, the fallback padding will be added to ensure there is at least some separation between command and description.
-
#fallback_description_padding=(fallback_description_padding : String)
If the command section exceeds the width defined above, the fallback padding will be added to ensure there is at least some separation between command and description.
-
#fuzzy_bind(word : String | Nil = nil, long_flag : String | Nil = nil, description : String | Nil = nil, &block : Subparser, String -> Nil) : Nil
Identical to bind, except the match for
word
orlong_flag
is fuzzy. -
#grab(&block : Subparser, String -> Nil) : Nil
Creates a wildcard binding.
-
#help_indent : String
The left indentation unit used in printing default help menus.
-
#help_indent=(help_indent : String)
The left indentation unit used in printing default help menus.
-
#max_fuzzy_distance=(max_fuzzy_distance : Int32)
Sets the maximum fuzzy finding distance allowed.
-
#missing_args(&block : String -> )
Binds a block to a callback in the case that there are not enough arguments to continue parsing.
-
#to_s(io : IO) : Nil
Prints all command names and descriptions defined on this subparser to the given io.
-
#unrecognized_args(&block : String -> )
Sets the handler block to yield to in the case of an unrecognized argument.
Constructor Detail
Instance Method Detail
Binds a keyword or keywords to a callback.
Accepts any of these optional keyword types:
- word : A word. For example, "version" would translate to
cli version
on the command line. - long_flag : A flag that is preceded by a double dash.
- short_flag : A character prefixed with a single dash. These can be stacked - to give an example,
cli -Syu
on the command line will run the bound event for 'S', 'y', and 'u' on the root parser.
NOTE:
Do not include prefix dashes in long_flag or short_flag -
They are inferred by Phreak. So, if you provide long_flag: "--version"
,
the cli will repond to ----version
, with two dashes automatically added by
Phreak. The same goes for short flags - if the desired flag is "-v", short_flag
should be set to 'v', not "-v".
Another possible source of unexpected behaviour is short flag stacking. If two short flags in a stack
both require a parameter, Phreak will not throw an error by design. Instead, the event handlers for each
flag will be called in order left to right, and the parameters will be consumed first come first serve.
For example, if flag -a
and -b
both take a parameter,
cli -a PARAM1 - b PARAM2
is equivalent to
cli -ab PARAM1 PARAM2
because a
consumes PARAM1, then returned, which then let b
consume PARAM2. If the user is aware of this
functionality, it can be very convinient. However, if they are not, it can lead to confusing side effects
that they might not be aware of.
&block will be invoked whenever one of the keywords is detected in the parse loop.
The arguments provided are the RootParser
which called the block, as well the keyword
that triggered the event. The block may return either a new Subparser, generated from RootParser.fork,
or nil. If a Subparser is returned, the next keyword will be parsed using that Subparser. This allows
for a stronger command structure.
The minumum width (word, long flag, and spaces) of the command section of the default help menu.
The minumum width (word, long flag, and spaces) of the command section of the default help menu.
If the command section exceeds the width defined above, the fallback padding will be added to ensure there is at least some separation between command and description.
If the command section exceeds the width defined above, the fallback padding will be added to ensure there is at least some separation between command and description.
Identical to bind, except the match for word
or long_flag
is fuzzy. These callbacks are
not considered until all else has failed.
Creates a wildcard binding. This is more or less equivalent to calling next_token on the
root RootParser
, however you don't have to worry about catching an IndexError. Nothing will
stop you from calling grab multiple times, but a subparser will only keep track of the
final bound callback.
The left indentation unit used in printing default help menus.
Sets the maximum fuzzy finding distance allowed.
Binds a block to a callback in the case that there are not enough arguments to continue parsing. Note that this will only be called if Phreak runs out of arguments. If your code invokes next_token on the root without assuring a token exists, an InsufficientArgumentsException will be raised, but missing_args will not be called.
Prints all command names and descriptions defined on this subparser to
the given io. Can be configured by changing the following properties on
Subparser:
#banner
#help_indent
description_pad
command_min_width
Sets the handler block to yield to in the case of an unrecognized argument. Provides the argument to the callback.