Trait getargs::Argument

source · [−]
pub trait Argument: Copy + Eq + Debug {
    type ShortOpt: Copy + Eq + Debug;

    fn ends_opts(self) -> bool;
    fn parse_long_opt(self) -> Option<(Self, Option<Self>)>;
    fn parse_short_cluster(self) -> Option<Self>;
    fn consume_short_opt(self) -> (Self::ShortOpt, Option<Self>);
    fn consume_short_val(self) -> Self;
}
Expand description

The argument trait for types that can be parsed by Options.

This trait is implemented for both &str and &[u8], and allows them to be understood by getargs enough to parse them - getargs is entirely generic over the type of its arguments.

Adding #[inline] to implementations of this trait can improve performance by up to 50% in release mode. This is because Options is so blazingly fast (nanoseconds) that the overhead of function calls becomes quite significant. rustc should be able to apply this optimization automatically, but doesn’t for some reason.

This trait should not need to be implemented unless you are using arguments that cannot be coerced into &str or &[u8] for whatever reason. If they can be in any way, you should use an Iterator::map instead of implementing Argument.

Implementing Argument requires Copy, Eq, and Debug because it simplifies #[derive]s on getargs’ side and codifies the inexpensive, zero-copy expectations of argument types. This should be a borrow like &str, not an owned struct like String.

Required Associated Types

The short-flag type. For &str, this is char. For &[u8], this is u8.

Required Methods

Returns true if this argument signals that no additional options should be parsed. If this method returns true, then Options::next_opt will not attempt to parse it as one (parse_long_opt and parse_short_cluster will not be called).

This method should only return true if Self is equal to the string "--" (or equivalent in your datatype). It should not return true if Self merely starts with "--", as that signals a long option.

Attempts to parse this argument as a long option. Returns the result of the parsing operation, with the leading -- stripped.

A long option is defined as an argument that follows the pattern --flag or --flag=VALUE, where VALUE may be empty.

Example
assert_eq!("--flag".parse_long_opt(), Some(("flag", None)));
assert_eq!("--flag=value".parse_long_opt(), Some(("flag", Some("value"))));
assert_eq!("--flag=".parse_long_opt(), Some(("flag", Some(""))));
assert_eq!("-a".parse_long_opt(), None);

Attempts to parse this argument as a “short option cluster”. Returns the short option cluster if present.

A “short option cluster” is defined as any Self such that either at least one ShortOpt can be extracted from it using consume_short_opt, or it can be converted to a value for a preceding short option using consume_short_val.

A short option cluster is signaled by the presence of a leading - in an argument, and does not include the leading -. The returned “short option cluster” must be valid for at least one consume_short_opt or consume_short_val.

This method does not need to guard against -- long options. parse_long_opt will be called first by Options::next_opt.

Example
assert_eq!("-abc".parse_short_cluster(), Some("abc"));
assert_eq!("-a".parse_short_cluster(), Some("a"));
assert_eq!("-".parse_short_cluster(), None);

Attempts to consume one short option from a “short option cluster”, as defined by parse_short_cluster. Returns the short option that was consumed and the rest of the cluster (if non-empty).

The returned cluster is subject to the same requirements as the return value of parse_short_cluster; namely, its validity for consume_short_opt or consume_short_val.

Example
assert_eq!("abc".consume_short_opt(), ('a', Some("bc")));
assert_eq!("a".consume_short_opt(), ('a', None));

Consumes the value of a short option from a “short option cluster”, as defined by parse_short_cluster. Returns the value that was consumed.

Implementations on Foreign Types

Implementors