class

Phreak::Subparser

Inherits Reference < Object

Constructors

new(parent : Subparser | Nil)
Source

Instance methods

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.

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.

Source
command_section_width

The minumum width (word, long flag, and spaces) of the command section of the default help menu.

Source
command_section_width=(command_section_width : Int8)

The minumum width (word, long flag, and spaces) of the command section of the default help menu.

Source
fallback_description_padding

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.

Source
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.

Source
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 or long_flag is fuzzy. These callbacks are not considered until all else has failed.

Source
grab

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.

Source
help_indent

The left indentation unit used in printing default help menus.

Source
help_indent=(help_indent : String)

The left indentation unit used in printing default help menus.

Source
max_fuzzy_distance=(max_fuzzy_distance : Int32)

Sets the maximum fuzzy finding distance allowed.

Source
missing_args

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.

Source
to_s(io : IO) : Nil

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

Source
unrecognized_args

Sets the handler block to yield to in the case of an unrecognized argument. Provides the argument to the callback.

Source