Enum Error 

#[non_exhaustive]
pub enum Error<'t, 'v> {
    UnknownFlag {
        token: &'v [u8],
    },
    MissingFlagValue {
        flag: &'t Flag<'t>,
    },
    UnexpectedArg {
        token: &'v [u8],
    },
    ArgRequiresDoubleDash {
        arg: &'t Arg<'t>,
    },
    SubcommandConflict {
        subcommand: &'t Command<'t>,
    },
    TooDeep,
    MissingRequired {
        name: &'t str,
    },
    DuplicateFlag {
        name: &'t str,
    },
    InvalidChoice {
        name: &'t str,
        choices: &'t [&'t str],
    },
    VarTooFew {
        name: &'t str,
        min: usize,
        got: usize,
    },
    VarTooMany {
        name: &'t str,
        max: usize,
        got: usize,
    },
    ConflictingFlags {
        name: &'t str,
        other: &'t str,
    },
    InvalidValue(Box<InvalidValue<'t>>),
    MissingGroup {
        group: &'t str,
        members: &'t [&'t str],
    },
    MissingSubcommand,
    Help {
        cmd: &'t Command<'t>,
        long: bool,
    },
    MissingArgsHelp {
        cmd: &'t Command<'t>,
    },
    HelpAll {
        cmd: &'t Command<'t>,
    },
    Version {
        long: bool,
    },
}

A binding failure.

Carries the offending token so a caller can render a good message, but no message of its own: rendering belongs to a cold path, and building a string here would allocate on the way to reporting that nothing was allocated.

non_exhaustive, because an error enum grows: a caller matching on it needs a fallback arm so that recognizing a new failure is never a breaking change.

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.

UnknownFlag

A flag-like token matched no flag in scope. token is the whole token as typed, so a bundle containing an unrecognized letter reports -fz rather than the letter alone — which is also the unit in which it is rejected.

Fields

token: &'v [u8]

MissingFlagValue

A flag that needs a value did not get one, either because the command line ended or because the next token was flag-like.

Fields

flag: &'t Flag<'t>

UnexpectedArg

A word arrived with no argument left to hold it.

Fields

token: &'v [u8]

ArgRequiresDoubleDash

A word was offered to a double_dash = "required" argument before any -- had been seen.

Fields

arg: &'t Arg<'t>

SubcommandConflict

A subcommand was selected after this command had already bound an argument.

Fields

subcommand: &'t Command<'t>

TooDeep

The command tree is deeper than MAX_DEPTH.

MissingRequired

Something the command requires was never given.

Fields

name: &'t str

The flag or argument’s name, as the spec calls it.

DuplicateFlag

A flag that is not repeatable was given more than once.

Fields

name: &'t str

The flag’s name, as the spec calls it.

InvalidChoice

A value was given that is not among the declared choices.

Carries the choices rather than the offending value: rendering the value means owning it, and an error that allocates on a path this crate promises not to allocate on would be a poor trade for a better message. Diagnostics are a separate layer.

Fields

name: &'t str

choices: &'t [&'t str]

VarTooFew

Fewer values than var_min.

Fields

name: &'t str

min: usize

got: usize

VarTooMany

More values than var_max.

Fields

name: &'t str

max: usize

got: usize

ConflictingFlags

Two flags declared to conflict were both given.

Carries both names because either one alone reads as a puzzle: which flag is unwelcome depends entirely on what else is on the command line.

Fields

name: &'t str

The flag whose declaration names the conflict.

other: &'t str

The flag it cannot be given with, as the declaration spells it.

InvalidValue(Box<InvalidValue<'t>>)

A value was given that the field’s type could not be built from.

Boxed, and the only error here that owns anything. Everything else borrows the tables or argv, which is what keeps a successful parse allocation-free — and the box keeps Error the size it was, so the Result this rides in on the hot path does not grow. A value that will not convert has already failed, and a message worth reading is worth one allocation.

MissingGroup

A required group had none of its members given.

Carries the members as members rather than as a rendered sentence: the caller decides how to say it, and a completion asking what would satisfy this needs the list rather than the prose.

Fields

group: &'t str

The group’s declared name, which appears in the message so a command with several groups does not report the same sentence twice.

members: &'t [&'t str]

The flags that would satisfy it, as the declaration spells them.

MissingSubcommand

A subcommand was required, and none was given.

Help

--help or -h was given, and cmd is what it was asked about.

Not a failure, and returned as one anyway: a parse that stops to print help has not produced a value, and every caller already handles the “no value” shape. clap does the same thing for the same reason.

long distinguishes the two: -h prints the short form and --help the long one, as clap has them. The caller renders — this crate does not print, because a library that writes to stdout on its own is one an adopter cannot embed.

Fields

cmd: &'t Command<'t>

long: bool

MissingArgsHelp

arg_required_else_help found no command-line arguments for cmd.

Unlike an explicit help request, this is a usage failure: clap prints the short help to stderr and exits with status 2. Keeping the shape separate lets embedders preserve that terminal contract without guessing why Error::Help was returned.

Fields

cmd: &'t Command<'t>

HelpAll

Recursive long help was requested for cmd and every visible descendant.

Fields

cmd: &'t Command<'t>

Version

--version or -V was asked for. Not a failure either — the caller prints and leaves.

The version string lives in the spec rather than the parse tables. long lets the caller choose long_version for --version while -V retains the concise value.

Fields

long: bool

Trait Implementations

impl<'t, 'v> Clone for Error<'t, 'v>

fn clone(&self) -> Error<'t, 'v>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'t, 'v> Debug for Error<'t, 'v>

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

Formats the value using the given formatter.

impl<'t, 'v> Eq for Error<'t, 'v>

impl<'t, 'v> PartialEq for Error<'t, 'v>

fn eq(&self, other: &Error<'t, 'v>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<'t, 'v> StructuralPartialEq for Error<'t, 'v>