class Phreak::Subparser

Direct Known Subclasses

Defined in:

subparser.cr

Constructors

Instance Method Summary

Constructor Detail

def self.new(parent : Subparser | Nil) #

[View source]

Instance Method Detail

def banner : String | Nil #

An optional banner to display in the autogenerated help menu.


[View source]
def banner=(banner : String | Nil) #

An optional banner to display in the autogenerated help menu.


[View source]
def 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.


[View source]
def command_section_width : Int8 #

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


[View source]
def command_section_width=(command_section_width : Int8) #

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


[View source]
def 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.


[View source]
def 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.


[View source]
def 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.


[View source]
def grab(&block : Subparser, String -> Nil) : Nil #

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.


[View source]
def help_indent : String #

The left indentation unit used in printing default help menus.


[View source]
def help_indent=(help_indent : String) #

The left indentation unit used in printing default help menus.


[View source]
def max_fuzzy_distance=(max_fuzzy_distance : Int32) #

Sets the maximum fuzzy finding distance allowed.


[View source]
def missing_args(&block : String -> ) #

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.


[View source]
def 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


[View source]
def unrecognized_args(&block : String -> ) #

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


[View source]