Struct parmacl::Matcher

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

Contains a set of filters which can be used to match one or more arguments in a command line. An argument must meet all filter conditions in a matcher for a match to occur.

The following filters are supported:

• Index of an argument: arg_indices
• Type of argument: arg_type
• Index of a parameter argument: param_indices
• Parameter text: value_text
• Index of an option argument: option_indices
• Option code: option_codes
• Whether an option has a value: option_has_value
• Whether an option value can start with an option announcer character: option_value_can_start_with_option_announcer
• Option value text: value_text

Before parsing a command line, the Parser instance should be assigned one or more Matcher instance. When a command line is parsed, all arguments must be matched by a matcher. If zero matchers are assigned to a Parser, then all arguments will be matched.

It is possible for an argument to be matched by more than one matcher. For each argument, the parser will attempt to match a matcher in the order of Parser.matchers. If a one matcher is more specific than another, insert it into this vector before the other.

Each argument produced by the Parser’s parse functions (parse_line, parse_env, parse_env_args), will include a reference to the matcher which matched it. The properties of a matcher can be used by the application when processing an argument. The Matcher.option_tag and Matcher.param_tag can be assigned enums to assist with this processing. These enums can be used in match arms to easily identify arguments.

Implementations

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

pub fn new(name: &str) -> Self

Create a new matcher with the specified name.

pub fn new_option(name: &str) -> Self

Create a new matcher with the specified name which matches option arguments.

pub fn new_param(name: &str) -> Self

Create a new matcher with the specified name which matches parameter arguments.

pub fn name(&self) -> &str

Get the name of a matcher.

This is used for display and help purposes. It is not used as a match filter.

pub fn set_name(&mut self, value: &str) -> &mut Self

Set the name of a matcher.

pub fn index(&self) -> usize

Get the index of the matcher within the Parser’s matchers vector.

pub fn help(&self) -> &Option<String>

Get the help text associated with a matcher

pub fn set_help(&mut self, value: Option<String>) -> &mut Self

Set the help text associated with a matcher as an Option

pub fn some_help(&mut self, value: &str) -> &mut Self

Set the help text associated with a matcher

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

Clear the help text associated with a matcher

pub fn option_tag(&self) -> &O

A value that can be used to identify option arguments matched by a matcher. Is of the type specified by the Parser’s O generic parameter. Normally O is an enum type which can be used in match statements which process the array of Arg variants returned by a parse function.

pub fn set_option_tag(&mut self, value: O) -> &mut Self

Set the option tag value. See option_tag.

pub fn param_tag(&self) -> &P

A value that can be used to identify parameter arguments matched by a matcher. Is of the type specified by the Parser’s P generic parameter. Normally P is an enum type which can be used in match statements which process the array of Arg variants returned by a parse function.

pub fn set_param_tag(&mut self, value: P) -> &mut Self

Set the parameter tag value. See param_tag.

pub fn arg_indices(&self) -> &Option<Vec<usize>>

Match Filter: If None, all arguments accepted. Otherwise accepts an argument whose index is included in the vector.

pub fn arg_indices_as_slice(&self) -> &[usize]

Match Filter: Get the arg_indices as a slice.

pub fn set_arg_indices(&mut self, value: Option<Vec<usize>>) -> &mut Self

Match Filter: Set arg_indices.

pub fn some_arg_indices(&mut self, value: &[usize]) -> &mut Self

Match Filter: Set arg_indices from an array of usize.

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

Match Filter: Set arg_indices to None so that it accepts all arguments.

pub fn arg_type(&self) -> &Option<MatchArgTypeId>

Match Filter: If None, accepts all arguments. Otherwise accepts arguments of the type specified.

pub fn set_arg_type(&mut self, value: Option<MatchArgTypeId>) -> &mut Self

Match Filter: Set arg_type.

pub fn some_arg_type(&mut self, value: MatchArgTypeId) -> &mut Self

Match Filter: Set the arg_type to a type value.

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

Match Filter: Set arg_type to None so that it accepts all arguments.

pub fn param_indices(&self) -> &Option<Vec<usize>>

Match Filter: If None, all arguments accepted. Otherwise accepts a parameter argument whose index is included in the vector.

pub fn param_indices_as_slice(&self) -> &[usize]

Match Filter: Get the param_indices as a slice.

pub fn set_param_indices(&mut self, value: Option<Vec<usize>>) -> &mut Self

Match Filter: Set param_indices.

pub fn some_param_indices(&mut self, value: &[usize]) -> &mut Self

Match Filter: Set param_indices from an array of usize.

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

Match Filter: Set param_indices to None so that it accepts all arguments.

pub fn option_indices(&self) -> &Option<Vec<usize>>

Match Filter: If None, all arguments accepted. Otherwise accepts an option argument whose index is included in the vector.

pub fn option_indices_as_slice(&self) -> &[usize]

Match Filter: Get the option_indices as a slice.

pub fn set_option_indices(&mut self, value: Option<Vec<usize>>) -> &mut Self

Match Filter: Set option_indices.

pub fn some_option_indices(&mut self, value: &[usize]) -> &mut Self

Match Filter: Set option_indices from an array of usize.

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

Match Filter: Set option_indices to None so that it accepts all arguments.

pub fn option_codes(&self) -> &Option<Vec<RegexOrText>>

Match Filter: If None, all arguments accepted. Otherwise accepts an option argument whose code is matched by any of the RegexOrText in the vector.

pub fn option_codes_as_slice(&self) -> &[RegexOrText]

Match Filter: Get the option_codes RegexOrTexts as a slice.

pub fn set_option_codes(&mut self, value: Option<Vec<RegexOrText>>) -> &mut Self

Match Filter: Set option_codes.

pub fn some_option_codes(&mut self, value: &[RegexOrText]) -> &mut Self

Match Filter: Set option_codes from an array of RegexOrText.

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

Match Filter: Set option_codes to None so that it accepts all arguments.

pub fn option_has_value(&self) -> &OptionHasValue

Match Filter: Accepts an option argument with or without an option value according to the OptionHasValue variant. (Default: Never)

pub fn set_option_has_value(&mut self, value: OptionHasValue) -> &mut Self

Match Filter: Set option_has_value.

pub fn option_value_can_start_with_option_announcer(&self) -> bool

Match Filter: Specifies whether an option argument with a value which starts with an option announcer character is accepted.

Option values beginning with an option announcer character can be both confusing and convenient. If they can start with option announcers, they may easily be confused with being a separate option. However they can be convenient, for example, if the option value specifies numbers that can be negative (assuming ‘-’ is the option announcer). Whether to allow option values to begin with an option announcer will depend on the context.

To start an option value with an option announcer when this is not allowed, the value should either be enclosed in quotes or the announcer should be escaped.

Currently starting an option value with an option announcer when option_has_value is IfPossible is not supported.

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

Match Filter: Set option_value_can_start_with_option_announcer.

pub fn value_text(&self) -> &Option<RegexOrText>

Match Filter: If None, all arguments accepted. Otherwise, if argument is a parameter, then the argument will be accepted if the parameter’s text is matched by the RegexOrText. If the argument is an option and has a value, then the argument is accepted if the option value text is matched by the RegexOrText. In all other cases, the argument is accepted.

pub fn set_value_text(&mut self, value: Option<RegexOrText>) -> &Self

Match Filter: Set value_text.

pub fn some_value_text(&mut self, value: RegexOrText) -> &Self

Match Filter: Set value_text to a RegexOrText.

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

Match Filter: Set value_text to None so that it accepts all arguments.

Trait Implementations

impl<O: Debug + Default, P: Debug + Default> Debug for Matcher<O, P>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.