Struct rags_rs::Parser

pub struct Parser { /* fields omitted */ }

Parser holds the state required for parsing. The methods provided here define how arguments should be treated as well as where they are constructed.

Arguments used for help (-h/--help) are already registered, and the boolean for this can be accessed via Parser::wants_help.

Memory usage of this structure is bounded by the arguments passed as well as a bitset mapping which args have been matched. Rust does not provide an O(1) access to the args iterator, thus we store it. This also keeps implementation consistent when using Parser::from_strings

This structure can be dropped after handling of args/help are complete.

Methods

impl Parser

pub fn from_strings(input: Vec<String>) -> Parser

Creates a new parser for the arg strings given.

pub fn from_args() -> Parser

Collects the arguments given on the command line and defers to Parser::from_strings.

pub fn unused(&self) -> Vec<Unused>

Unused returns all unmatched args. The Unused struct contains the necessary information to call out unrecognized args or typos in passed arguments.

If there is an unused character in a run of shortcodes (e.g. -abcd, with b unused) the argument within the Unused struct will be prefixed with a dash.

pub fn app_name<'a>(&'a mut self, name: &'static str) -> &'a mut Parser

Sets the name of the application to be printed in the help dialog. Printed on the first line of the dialog.

pub fn app_desc<'a>(&'a mut self, desc: &'static str) -> &'a mut Parser

Sets the description of the application to be printed in the help dialog. Printed on the first line of the dialog.

pub fn app_long_desc<'a>(&'a mut self, desc: &'static str) -> &'a mut Parser

Sets the long-form description of the application to be printed in the help dialog. Printed after the base application info and usage lines.

pub fn app_version<'a>(&'a mut self, vers: &'static str) -> &'a mut Parser

Sets the version of the application to be printed in the help dialog. Printed on the first line of the dialog.

pub fn wants_help(&self) -> bool

Returns whether the help argument was given and help should be printed. The help dialog can be printed using Parser::print_help.

pub fn print_help(&self)

Prints the help information. If subcommands are provided, the help for the leaf subcommand is printed.

pub fn done(&mut self) -> Result<&mut Parser, Error>

Closes a context opened by calling Parser::group or Parser::subcommand.

pub fn arg<'a, T: FromStr + ToString>(
    &'a mut self,
    short: char,
    long: &'static str,
    desc: &'static str,
    into: &mut T,
    label: Option<&'static str>,
    required: bool
) -> Result<&'a mut Parser, Error> where
    <T as FromStr>::Err: Display, 

Registers a long and short code which are expected to be followed by a value. The associated value can be separated by either a space or an equal sign (e.g. --foo=7 or --foo 7).

The type you wish to be parse the arg value into must implement From<String> for construction as well as ToString for printing defaults in the help dialog.

You may provide a label to display next to the argument in the help dialog (e.g. -f, --file FILE where the label here is FILE).

Arguments may additionally be marked as required. If the argument is not provided when marked as required, this method will return an error which will propogate up the call stack without parsing further args (fail fast).

pub fn short_arg<'a, T: FromStr + ToString>(
    &'a mut self,
    short: char,
    desc: &'static str,
    into: &mut T,
    label: Option<&'static str>,
    required: bool
) -> Result<&'a mut Parser, Error> where
    <T as FromStr>::Err: Display, 

Convenience method for declaring a Parser::arg without a long code.

pub fn long_arg<'a, T: FromStr + ToString>(
    &'a mut self,
    long: &'static str,
    desc: &'static str,
    into: &mut T,
    label: Option<&'static str>,
    required: bool
) -> Result<&'a mut Parser, Error> where
    <T as FromStr>::Err: Display, 

Convenience method for declaring a Parser::arg without a short code.

pub fn flag<'a>(
    &'a mut self,
    short: char,
    long: &'static str,
    desc: &'static str,
    into: &mut bool,
    invert: bool
) -> Result<&'a mut Parser, Error>

Flag defines an argument that takes no value, but instead sets a boolean. Typically when a flag is given the backing bool is set to true, however, the invert argument here allows "negative-flags" which instead turn an option off.

pub fn short_flag<'a>(
    &'a mut self,
    short: char,
    desc: &'static str,
    into: &mut bool,
    invert: bool
) -> Result<&'a mut Parser, Error>

Convenience method for declaring a Parser::flag without a long code.

pub fn long_flag<'a>(
    &'a mut self,
    long: &'static str,
    desc: &'static str,
    into: &'a mut bool,
    invert: bool
) -> Result<&'a mut Parser, Error>

Convenience method for declaring a Parser::flag without a short code.

pub fn count<'a, T: AddAssign + ToString + Clone>(
    &'a mut self,
    short: char,
    long: &'static str,
    desc: &'static str,
    into: &mut T,
    step: T
) -> Result<&'a mut Parser, Error>

Count (inc|dec)rements a backing numeric type every time the argument is provided. The classic case is increasing verbosity (e.g. -v is 1, -vvvv is 4).

The step argument to this method defines what should be added to the target value every time the arg is seen. You may provide negative numbers to decrement.

Floating point numeric types are supported, but are atypical.

pub fn short_count<'a, T: AddAssign + ToString + Clone>(
    &'a mut self,
    short: char,
    desc: &'static str,
    into: &mut T,
    step: T
) -> Result<&'a mut Parser, Error>

Convenience method for declaring a Parser::count without a long code.

pub fn long_count<'a, T: AddAssign + ToString + Clone>(
    &'a mut self,
    long: &'static str,
    desc: &'static str,
    into: &mut T,
    step: T
) -> Result<&'a mut Parser, Error>

Convenience method for declaring a Parser::count without a short code.

pub fn list<'a, T: FromStr + ToString>(
    &'a mut self,
    short: char,
    long: &'static str,
    desc: &'static str,
    into: &mut Vec<T>,
    label: Option<&'static str>,
    required: bool
) -> Result<&'a mut Parser, Error> where
    <T as FromStr>::Err: Display, 

List collects values from args and appends them to a vector of the target type.

Follows the same parsing semantics as Parser::arg, but appends to a collection rather a single value. Just as with an arg, the target type must implement From<String> as well as ToString. Likewise, the label and required arguments to this method work the same.

pub fn short_list<'a, T: FromStr + ToString>(
    &'a mut self,
    short: char,
    desc: &'static str,
    into: &mut Vec<T>,
    label: Option<&'static str>,
    required: bool
) -> Result<&'a mut Parser, Error> where
    <T as FromStr>::Err: Display, 

Convenience method for declaring a Parser::list without a long code.

pub fn long_list<'a, T: FromStr + ToString>(
    &'a mut self,
    long: &'static str,
    desc: &'static str,
    into: &mut Vec<T>,
    label: Option<&'static str>,
    required: bool
) -> Result<&'a mut Parser, Error> where
    <T as FromStr>::Err: Display, 

Convenience method for declaring a Parser::list without a short code.

pub fn subcommand<'a, T: FromStr + ToString>(
    &'a mut self,
    name: &'static str,
    desc: &'static str,
    into: &mut Vec<T>,
    long_desc: Option<&'static str>
) -> Result<&'a mut Parser, Error> where
    <T as FromStr>::Err: Display, 

Subcommands provide information about what the application should do as well as giving scope to arguments. This method creates a new context (zero cost) for which arguments can be defined. By creating a new context we allow for subcommands to share argument codes with differing meanings. You must close this context/scope using Parser::done.

When a subcommand is matched it is appended to a vector. The application is expected to iterate that vector to determine the correct internal function(s) to call.

An optional long description specific to this command can be provided. The application's long description is not printed in the help dialog when a subcommand is matched.

Because subcommands are indistinguishable from positional arguments, all definitions for positional arguments should be done after defining all subcommands.

pub fn group<'a>(
    &'a mut self,
    name: &'static str,
    desc: &'static str
) -> Result<&'a mut Parser, Error>

Group can be used to group various arguments into a named section within the help dialog. When a help argument is not provided, this is a no-op.

This method opens a new scope/context which must be closed using Parser::done. However, no masking of arguments occurs in this created scope. The only effect a group has is on the printing of args.

pub fn positional<'a, T: ToString + FromStr>(
    &'a mut self,
    name: &'static str,
    desc: &'static str,
    into: &mut T,
    required: bool
) -> Result<&'a mut Parser, Error> where
    <T as FromStr>::Err: Display, 

Creates a named positional argument. Positionals are taken on an in-order basis meaning when multiple positionals are defined, the values are constructed in the order they are provided by the user. This method does not parse anything after the arg-stop setinel (--); see Parser::positional_list.

You may define as many named positionals as required, but if you simply wish to capture all positionals, see Parser::positional_list.

Because positionals are indistinguishable from subcommands, all positionals should be defined after all subcommands. You can, however, safely define positionals within a leaf subcommand scope.

Just as in the base Parser::arg case, the target type must implement both From<String> and ToString.

pub fn positional_list<'a, T: ToString + FromStr>(
    &'a mut self,
    name: &'static str,
    desc: &'static str,
    into: &mut Vec<T>,
    required: bool
) -> Result<&'a mut Parser, Error> where
    <T as FromStr>::Err: Display, 

Gathers all unused arguments which are assumed to be positionals. Unused here does not include short code runs. Unrecognized arguments will also be returned here as there is mass complexity in determining the difference. For instance, -9 is a valid short code flag but also has meaning as a positional.

All arguments provided after the arg-stop setinel (--) will be gathered here. For example, in my_app list --foo=7 -- list --help the trailing list --help will not be parsed as arguments by this parser but instead will be considered positionals.

Just as Parser::list is a vector of Parser::arg, this method is a vector of Parser::positional sharing a single name for the set.

This method may only be called once, or an error will be returned.