Enum Error 

#[non_exhaustive]
pub enum Error<'a> {
    MissingArgument(&'static str),
    UnknownOption {
        option: Opt<'a>,
        suggestion: Option<&'static str>,
    },
    UnexpectedArgument(&'a str),
    UnexpectedValue(Opt<'a>),
    MissingOptionValue(&'static str),
    ArgumentConflict {
        name: &'static str,
        other: &'static str,
    },
    MissingRequiredArgument {
        name: &'static str,
        required_by: &'static str,
    },
    MissingOneOf(&'static [&'static str]),
    MissingSubcommand(&'static [&'static str]),
    UnknownSubcommand {
        name: &'a str,
        suggestion: Option<&'static str>,
    },
    InvalidArguments,
    InvalidValue {
        name: &'static str,
        value: &'a str,
    },
    InvalidPossibleValue {
        name: &'static str,
        value: &'a str,
        possible_values: &'static [&'static str],
    },
    ValueOutOfRange {
        name: &'static str,
        value: &'a str,
        range: &'static str,
    },
    TooManyValues {
        name: &'static str,
        value: &'a str,
        max: usize,
    },
    TooFewValues {
        name: &'static str,
        min: usize,
        actual: usize,
    },
    InvalidUtf8 {
        name: Option<&'static str>,
        value: &'a [u8],
    },
    Help(&'static str),
    Version(&'static str),
}

Errors that can occur when parsing CLI arguments with GetArgs.

The lifetime 'a is the lifetime of the parsed arguments: variants describing what the user typed borrow it from the command line instead of copying it, so no allocation is needed.

Names of the struct’s own arguments (&'static str) are written as in the generated help: <INPUT> for a positional argument, --output <OUTPUT> for an option taking a value (-o <OUTPUT> when it has no long name).

The enum is #[non_exhaustive]: new variants can be added in a minor release, so a match on it needs a wildcard arm.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

MissingArgument(&'static str)

A required positional argument or named option was not provided on the command line.

The string is the argument name, e.g. "<INPUT>" or "--output <OUTPUT>".

UnknownOption

An option that the struct does not define was given, e.g. --bogus or -z.

Fields

option: Opt<'a>

The unknown option, as written by the user.

suggestion: Option<&'static str>

The closest long option name (without --) when an unknown long option looks like a typo of a known one, e.g. Some("verbose") for --verbos.

UnexpectedArgument(&'a str)

A positional argument was given but the struct expects no more of them.

The string is the extra argument, as written by the user.

UnexpectedValue(Opt<'a>)

A value was attached to an option that does not take one, e.g. --verbose=yes for a flag.

The option is the one written by the user.

MissingOptionValue(&'static str)

An option taking a value was given without one, e.g. --output at the end of the command line.

The string is the option name, e.g. "--output <OUTPUT>".

ArgumentConflict

Two arguments that cannot be used together were both given, because of conflicts_with or because they belong to the same group.

Fields

name: &'static str

The argument declaring the conflict (or the first member of the group), e.g. "--quiet".

other: &'static str

The other argument, e.g. "--verbose".

MissingRequiredArgument

An argument was given without another argument it requires.

Fields

name: &'static str

The missing argument, e.g. "--output <OUTPUT>".

required_by: &'static str

The given argument that requires it, e.g. "--compress".

MissingOneOf(&'static [&'static str])

None of a set of arguments was given although one of them is required, because of required_unless_present or a required group.

The slice lists the arguments, e.g. ["--config <CONFIG>", "--stdin"].

MissingSubcommand(&'static [&'static str])

A required subcommand was not given.

The slice lists the visible subcommands, e.g. ["add", "remove"]. It is only returned for a #[command(subcommand)] field that is not an Option.

UnknownSubcommand

A positional argument was given where a subcommand was expected, and it is not the name or an alias of any subcommand.

Fields

name: &'a str

The unknown subcommand, as written by the user.

suggestion: Option<&'static str>

The closest visible subcommand name or alias when the unknown one looks like a typo of it, e.g. Some("remove") for remov.

InvalidArguments

The underlying getargs parser reported an error that this crate does not recognise.

getargs may add error kinds in a compatible release; they are reported as this variant instead of panicking. It is never returned with the getargs 0.5 releases known to this crate.

InvalidValue

A value could not be parsed into the target field type, e.g. abc for a u32 field.

This is also returned when a default_value string does not parse.

Fields

name: &'static str

The argument name, e.g. "--port <PORT>" or "<COUNT>".

value: &'a str

The value that failed to parse.

InvalidPossibleValue

A value is not one of the argument’s possible_values, e.g. turbo for possible_values = ["fast", "slow"].

This is also returned when a default_value string is not one of them.

Fields

name: &'static str

The argument name, e.g. "--mode <MODE>".

value: &'a str

The value that was given.

possible_values: &'static [&'static str]

The accepted values, in declaration order, e.g. ["fast", "slow"].

ValueOutOfRange

A value parsed into the field type but is outside the argument’s value_parser range, e.g. 0 for value_parser = 1..=64.

This is also returned when a default_value string is outside the range.

Fields

name: &'static str

The argument name, e.g. "--jobs <JOBS>".

value: &'a str

The value that was given.

range: &'static str

The range as written in the attribute, e.g. "1..=64".

TooManyValues

More values were given to a repeated argument than its collection can hold, or than its num_args range accepts, e.g. a third -I for a Values<&str, 2> field.

This is also returned when an environment variable or a default splits into too many values.

Fields

name: &'static str

The argument name, e.g. "--include <INCLUDE>" or "<FILES>...".

value: &'a str

The first value that did not fit.

max: usize

The maximum number of values.

TooFewValues

A positional argument collecting several values received fewer than the minimum of its num_args range, but at least one. Error::MissingArgument is returned when it received none.

Fields

name: &'static str

The argument name, e.g. "<FILES>...".

min: usize

The minimum number of values.

actual: usize

The number of values given.

InvalidUtf8

An argument that is not valid UTF-8 was given where text is required, when parsing raw bytes with from_bytes, parse_bytes or from_args_os.

It is returned for a value of a &str field or of a field parsed from a string, and for an argument that matches no field, such as an option name, a subcommand name or an extra positional argument, since those are reported as text by the other variants.

Fields

name: Option<&'static str>

The argument name, e.g. "--name <NAME>", or None for an argument that matches no field.

value: &'a [u8]

The raw bytes of the argument, displayed with Lossy.

Help(&'static str)

Help was requested with -h or --help.

This is not a parse failure: the string is the generated help text, the struct’s HELP constant for -h and its LONG_HELP constant for --help. After a subcommand, it is the help of that subcommand instead. Applications should print it to standard output and exit successfully. It is never returned when help is disabled with #[command(disable_help_flag)].

Version(&'static str)

The version was requested with -V or --version.

This is not a parse failure: the string is the version line, the command name followed by the version (the struct’s VERSION_TEXT constant). Applications should print it to standard output and exit successfully. It is only returned when #[command(version)] is set.

Implementations

impl Error<'_>

pub fn is_help(&self) -> bool

Returns true if this is Error::Help, i.e. the user asked for help rather than passing invalid arguments.

pub fn is_version(&self) -> bool

Returns true if this is Error::Version, i.e. the user asked for the version rather than passing invalid arguments.

Trait Implementations

impl<'a> Clone for Error<'a>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Copy for Error<'a>

impl<'a> Debug for Error<'a>

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

Formats the value using the given formatter.

impl Display for Error<'_>

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

Formats the value using the given formatter.

impl<'a> Eq for Error<'a>

impl Error for Error<'_>

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl<'a> PartialEq for Error<'a>

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<'a> StructuralPartialEq for Error<'a>