Struct parmacl::Parser

pub struct Parser<O: Default = DefaultTagType, P: Default = DefaultTagType> { /* private fields */ }

A Parser is used to parse a command line (or environmental arguments). It has:

• properties which define the style of the command line to be parsed,
• a matchers list which specifies the kind of arguments in the command line,
• parse functions which parse a command line (or environmental arguments) and return a vector of the parsed arguments.

To use the parser, configure it with the style of the command line, add matchers to cover all possible arguments that a command line can have and then use a parse function to parse a command line (or environmental arguments).

The style of a command line can configured with the following:

• Parameters and option values can be quoted (quote_chars)
• Allow quote characters to be embedded in quoted parameters and option values using double quotes (embed_quote_char_with_double)
• Whether parameters are case sensitive (params_case_sensitive)
• The characters which announce an option (option_announcer_chars)
• Whether option codes with more than one character require 2 announcer characters (multi_char_option_code_requires_double_announcer)
• Whether option codes are case sensitive (option_codes_case_sensitive)
• Whether option codes can be empty strings (option_code_can_be_empty)
• The characters which announce an option value (option_value_announcer_chars)
• Whether option values are case sensitive (option_values_case_sensitive)
• Optionally define a character which will escape characters with special purpose (escape_char)
• Specify which which special purpose characters can be escaped (escapeable_logical_chars)
• Specify which literal characters can be escaped (escapeable_chars)
• Whether the first argument is the binary name (first_arg_is_binary)
• The characters which will terminate the parsing of the line early (parse_terminate_chars)

The new constructor will create a Parser with base defaults that are a good starting point for parsing a command line. The with_env_args_defaults constructor has base defaults for parsing environmental arguments. These defaults can also be applied with the set_line_defaults and set_env_args_defaults functions.

The following functions can be used to manage the matcher list: matchers, push_new_matcher push_new_option_matcher, push_new_param_matcher, push_matcher, delete_matcher_at, clear_matchers and find_matcher.

There are 3 functions for parsing a command line or environmental variables:

• parse_line - Parses a command line
• parse_env_args - Parses an environmental variables specified in a std::env::args iterator
• parse_env - Parses the application’s environmental variables

If parsing was successful, these 3 functions will return a vector of parsed arguments. Otherwise they will return an ParseError struct detailing the type of parse error and its location in the line.

Implementations

impl<O: Default, P: Default> Parser<O, P>

pub fn new() -> Self

Create a new Parser object with Line parsing defaults. The O and P generic parameters specify the types that can be used to tag matchers with a value which easily enables Option and Parameter arguments to be identified.

pub fn with_line_defaults() -> Self

Create a new Parser object with Line parsing defaults. The O and P generic parameters specify the types that can be used to tag matchers with a value which easily enables Option and Parameter arguments to be identified.

pub fn with_env_args_defaults() -> Self

Create a new Parser object with Environment Arguments parsing defaults. The O and P generic parameters specify the types that can be used to tag matchers with a value which easily enables Option and Parameter arguments to be identified.

impl<O: Default, P: Default> Parser<O, P>

pub fn quote_chars(&self) -> &[char]

Get the array of characters any of which can be used as a quote character. A quote character is used to enclose all text in a parameter or an option value.

Whitespace characters (normally spaces) are used to delimit arguments in a command line. If a parameter or an option value contain whitespace characters, place a quote character at either end of the parameter or value text. If the parameter or option value already contain one or more quote characters, then these can be embedded using either Double quote characters or Escaping

If text starts with a quote character, you also need to embed it with either quoting or escaping or enclose it with a different quote character. You can also use quoting to enclose text which begins with a option announcer but is not an option. See Matcher::option_has_value for alternative ways of handling text beginning with the option announcer character.

Line Default: ['"'] (Array with one double quote character)
Env args Default: [] (Empty array)

pub fn set_quote_chars(&mut self, value: &[char]) -> &mut Self

Get the array of characters any of which can be used as a quote character. See Parser::quote_chars for more details.

pub fn option_announcer_chars(&self) -> &[char]

Get the array of characters any of which can be used to signify the start of an option argument in the command line.

A command line argument which begins with one of the characters in this array will be parsed as a option.

Note that the Parser can be configured to allow option values to begin with an option announcer character in some circumstances. See Matcher.option_value_can_start_with_option_announcer for more details.

Default: ['-'] (Array with one dash character)

pub fn set_option_announcer_chars(&mut self, value: &[char]) -> &mut Self

Set the array of characters any of which can be used to signify the start of an option argument in the command line. See Parser::option_announcer_chars for more details.

pub fn option_codes_case_sensitive(&self) -> bool

Specifies whether option codes are matched with case sensitivity.

Note that a RegexOrText object can override this setting for individual arguments

Default: false

pub fn set_option_codes_case_sensitive(&mut self, value: bool) -> &mut Self

Sets option_codes_case_sensitive

pub fn option_code_can_be_empty(&self) -> bool

Specifies whether option codes can be a string of length zero.

Having empty option codes means that a standalone option announcer char is an option argument in its own right. This could be confusing however it is possible.

Default: false

pub fn set_option_code_can_be_empty(&mut self, value: bool) -> &mut Self

Sets option_code_can_be_empty

pub fn multi_char_option_code_requires_double_announcer(&self) -> bool

Specifies whether option codes with more than one character must be announced with 2 successive option announcer characters.

This convention is common but not necessary.

Default: false

pub fn set_multi_char_option_code_requires_double_announcer(
    &mut self,
    value: bool
) -> &mut Self

Sets multi_char_option_code_requires_double_announcer

pub fn option_value_announcer_chars(&self) -> &[char]

Get the array of characters any of which can be used end an option code and announce its option value.

If an option argument does not end with this character, then it is a switch/flag only and does not include a value. If it does contain this character, then the characters prior to this character are the option code and the characters after it, are the option value.

Note that if a whitespace character is used as a option value announcer, there is some ambiguity as to whether that character is announcing the value for that option or being a delimiter for the next argument. This ambiguity is resolved by a matcher’s Matcher.option_has_value property.

Default: [' '] (Array with one space character)

pub fn set_option_value_announcer_chars(&mut self, value: &[char]) -> &mut Self

Set the array of characters any of which can be used end an option code and announce its option value. See Parser::option_value_announcer_chars for more details.

pub fn option_values_case_sensitive(&self) -> bool

Specifies whether option values are matched with case sensitivity.

Note that a RegexOrText object can override this setting for individual arguments.

Default: false

pub fn set_option_values_case_sensitive(&mut self, value: bool) -> &mut Self

Sets option_values_case_sensitive

pub fn params_case_sensitive(&self) -> bool

Specifies whether parameters are matched with case sensitivity.

Note that a RegexOrText object can override this setting for individual arguments.

Default: false

pub fn set_params_case_sensitive(&mut self, value: bool) -> &mut Self

Sets params_case_sensitive

pub fn embed_quote_char_with_double(&self) -> bool

Specifies whether quote characters can be embedded in a quoted parameter or option value by using double quotes.

If true, two successive quote characters in quoted text will be treated as one embedded quote character within the text.

Line Default: true
Env args Default: false

pub fn set_embed_quote_char_with_double(&mut self, value: bool) -> &mut Self

Set embed_quote_char_with_double

pub fn escape_char(&self) -> &Option<char>

The escape character within a parameter or option value, signifies that the subsequent character should be treated as a literal character and not have a special purpose.

Some characters have special purposes in the command line. For example, a quote character normally specifies the start or end of the parameter/option value. To embed it within this quoted value, a user can place an escape character before it. The quote character will then be treated as a literal character and not as the character used to quote a string.

Only characters specified by escapeable_logical_chars or escapeable_chars can be escaped. A parsing error will be returned if the command line attempts to escape any other character.

Note that if escaping is enabled, it is recommended that the Escape logical character itself also be escaped. That allows a user to include the escape character as a literal in a parameter or option value.

Default: None (no escaping of characters)

pub fn set_escape_char(&mut self, value: Option<char>) -> &mut Self

Set escape_char.

pub fn some_escape_char(&mut self, value: char) -> &mut Self

Set escape_char.

pub fn none_escape_char(&mut self) -> &mut Self

Set escape_char to None which disables character escaping.

pub fn escapeable_logical_chars(&self) -> &[EscapeableLogicalChar]

The array of logical characters which the command line can escape.

Default: [EscapeableLogicalChar::Escape, EscapeableLogicalChar::Quote]

pub fn set_escapeable_logical_chars(
    &mut self,
    value: &[EscapeableLogicalChar]
) -> &mut Self

Set escapeable_logical_chars

pub fn escapeable_chars(&self) -> &[char]

The array of literal characters which the command line can escape.

Normally, a character which is not a special purpose character does not need to be escaped. Accordingly, this property would generally be left as an empty array.

Default: []

pub fn set_escapeable_chars(&mut self, value: &[char]) -> &mut Self

Set escapeable_chars

pub fn first_arg_is_binary(&self) -> bool

Whether the first argument should be interpretted as the binary’s name.

Operating systems and shells traditionally insert the name or path of a binary as the first parameter of a command line (or environmental arguments) passed to an application. When this property is true, the parser will treat the first parameter accordingly.

However if an application internal command is parsed then the first parameter will most likely not be the binary name. This property can be set to false so the first parameter is treated like all other parameters.

Note that for security purposes, if the operating system inserts the first argument, it should not be relied upon to be the binary path. It is possible for arbitrary text to be passed as the first parameter.

pub fn set_first_arg_is_binary(&mut self, value: bool) -> &mut Self

Set first_arg_is_binary

pub fn parse_terminate_chars(&self) -> &[char]

Get the array of characters which terminate the parsing of arguments in the command line.

If any of the characters in this array are encountered outside a quoted value, then that character and all remaining characters in the command line are ignored. This can be used to ignore standard input/output redirection and the end of a command line.

Default: [] (Empty array)

pub fn set_parse_terminate_chars(&mut self, value: &[char]) -> &mut Self

Set parse_terminate_chars

impl<O: Default, P: Default> Parser<O, P>

pub fn set_line_defaults(&mut self)

Set Parser properties to their default values for parsing a command line.

pub fn set_env_args_defaults(&mut self)

Set Parser properties to their default values for parsing environmental arguments.

pub fn matchers(&self) -> &Matchers<O, P>

The array of matchers registered with the Parser.

pub fn push_new_matcher(&mut self, name: &str) -> &mut Matcher<O, P>

Create and return a new matcher which has been added to the end of the Parser’s list of matchers.

pub fn push_new_option_matcher(&mut self, name: &str) -> &mut Matcher<O, P>

Create and return a new matcher for option arguments. The matcher has been added to the end of the Parser’s list of matchers.

pub fn push_new_param_matcher(&mut self, name: &str) -> &mut Matcher<O, P>

Create and return a new matcher for parameter arguments. The matcher has been added to the end of the Parser’s list of matchers.

pub fn push_matcher(&mut self, matcher: Matcher<O, P>) -> &mut Matcher<O, P>

Add a supplied matcher to the end of the Parser’s list of matchers. The Parser will take ownership of this matcher.

pub fn delete_matcher(&mut self, name: &str) -> bool

Delete the first matcher in the list whose name equals the value of the name parameter.

Returns true if a matcher was deleted otherwise returns false.

pub fn delete_matcher_at(&mut self, index: usize)

Delete the matcher at the position in the list specified by the index parameter.

pub fn clear_matchers(&mut self)

Delete all matchers from the Parser’s list of matchers.

pub fn find_matcher(&self, name: &str) -> Option<&Matcher<O, P>>

Find and return the first matcher in the list whose name equals the value of the name parameter.

Returns a reference to the matcher in an option if found. Otherwise return None.

pub fn parse_env(&self) -> Result<Args<'_, O, P>, ParseError>

Parse this applications environmental arguments.

If successful, returns a success result holding an array of the parsed arguments. Otherwise return an error result containing a ParseError struct which holds the error details.

pub fn parse_env_args(
    &self,
    env_args: Args
) -> Result<Args<'_, O, P>, ParseError>

Parse the environmental arguments passed in the env_args parameter.

If successful, returns a success result holding an array of the parsed arguments. Otherwise return an error result containing a ParseError struct which holds the error details.

pub fn parse_line(&self, line: &str) -> Result<Args<'_, O, P>, ParseError>

Parse a command line.

If successful, returns a success result holding an array of the parsed arguments. Otherwise return an error result containing a ParseError struct which holds the error details.

Trait Implementations

impl<O: Default, P: Default> Default for Parser<O, P>

fn default() -> Self

Returns the “default value” for a type.