Type Alias Error

pub type Error = Error;

Command Line Argument Parser Error

See Command::error to create an error.

Aliased Type

struct Error { /* private fields */ }

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 8 bytes

Implementations

impl<F> Error<F>

where F: ErrorFormatter,

pub fn raw(kind: ErrorKind, message: impl Display) -> Error<F>

Create an unformatted error

This is for you need to pass the error up to a place that has access to the Command at which point you can call Error::format.

Prefer Command::error for generating errors.

pub fn format(self, cmd: &mut Command) -> Error<F>

Format the existing message with the Command’s context

pub fn new(kind: ErrorKind) -> Error<F>

Create an error with a pre-defined message

See also

• Error::insert
• Error::with_cmd

Example

let cmd = clap::Command::new("prog");

let mut err = clap::Error::new(ErrorKind::ValueValidation)
    .with_cmd(&cmd);
err.insert(ContextKind::InvalidArg, ContextValue::String("--foo".to_owned()));
err.insert(ContextKind::InvalidValue, ContextValue::String("bar".to_owned()));

err.print();

pub fn with_cmd(self, cmd: &Command) -> Error<F>

Apply Command’s formatting to the error

Generally, this is used with Error::new

pub fn apply<EF>(self) -> Error<EF>

where EF: ErrorFormatter,

Apply an alternative formatter to the error

Example

let cmd = Command::new("foo")
    .arg(Arg::new("input").required(true));
let matches = cmd
    .try_get_matches_from(["foo", "input.txt"])
    .map_err(|e| e.apply::<KindFormatter>())
    .unwrap_or_else(|e| e.exit());

pub fn kind(&self) -> ErrorKind

Type of error for programmatic processing

pub fn context(&self) -> impl Iterator<Item = (ContextKind, &ContextValue)>

Additional information to further qualify the error

pub fn get(&self, kind: ContextKind) -> Option<&ContextValue>

Lookup a piece of context

pub fn insert( &mut self, kind: ContextKind, value: ContextValue, ) -> Option<ContextValue>

Insert a piece of context

If this ContextKind is already present, its value is replaced and the old value is returned.

pub fn remove(&mut self, kind: ContextKind) -> Option<ContextValue>

Remove a piece of context, return the old value if any

The context is currently implemented in a vector, so remove takes linear time.

pub fn use_stderr(&self) -> bool

Should the message be written to stdout or not?

pub fn exit_code(&self) -> i32

Returns the exit code that .exit will exit the process with.

When the error’s kind would print to stderr this returns 2, else it returns 0.

pub fn exit(&self) -> !

Prints the error and exits.

Depending on the error kind, this either prints to stderr and exits with a status of 2 or prints to stdout and exits with a status of 0.

pub fn print(&self) -> Result<(), Error>

Prints formatted and colored error to stdout or stderr according to its error kind

Example

use clap::Command;

match Command::new("Command").try_get_matches() {
    Ok(matches) => {
        // do_something
    },
    Err(err) => {
        err.print().expect("Error writing Error");
        // do_something
    },
};

pub fn render(&self) -> StyledStr

Render the error message to a StyledStr.

Example

use clap::Command;

match Command::new("Command").try_get_matches() {
    Ok(matches) => {
        // do_something
    },
    Err(err) => {
        let err = err.render();
        println!("{err}");
        // do_something
    },
};

Trait Implementations

impl<F> Debug for Error<F>

where F: ErrorFormatter,

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

Formats the value using the given formatter.

impl<F> Display for Error<F>

where F: ErrorFormatter,

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

Formats the value using the given formatter.

impl<F> Error for Error<F>

where F: ErrorFormatter,

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<F> From<Error> for Error<F>

where F: ErrorFormatter,

fn from(e: Error) -> Error<F>

Converts to this type from the input type.

impl<F> From<Error> for Error<F>

where F: ErrorFormatter,

fn from(e: Error) -> Error<F>

Converts to this type from the input type.