Struct Error

Source

pub struct Error<F = RichFormatter>where
    F: ErrorFormatter,
{ /* private fields */ }

Expand description

Command Line Argument Parser Error

See Command::error to create an error.

Implementations§

Source §

impl<F> Error<F>
where F: ErrorFormatter,

Source

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.

Examples found in repository ?

examples/derive_ref/hand_subcommand.rs (lines 27-30)

23    fn from_arg_matches(matches: &ArgMatches) -> Result<Self, Error> {
24        match matches.subcommand() {
25            Some(("add", args)) => Ok(Self::Add(AddArgs::from_arg_matches(args)?)),
26            Some(("remove", args)) => Ok(Self::Remove(RemoveArgs::from_arg_matches(args)?)),
27            Some((_, _)) => Err(Error::raw(
28                ErrorKind::InvalidSubcommand,
29                "Valid subcommands are `add` and `remove`",
30            )),
31            None => Err(Error::raw(
32                ErrorKind::MissingSubcommand,
33                "Valid subcommands are `add` and `remove`",
34            )),
35        }
36    }
37    fn update_from_arg_matches(&mut self, matches: &ArgMatches) -> Result<(), Error> {
38        match matches.subcommand() {
39            Some(("add", args)) => *self = Self::Add(AddArgs::from_arg_matches(args)?),
40            Some(("remove", args)) => *self = Self::Remove(RemoveArgs::from_arg_matches(args)?),
41            Some((_, _)) => {
42                return Err(Error::raw(
43                    ErrorKind::InvalidSubcommand,
44                    "Valid subcommands are `add` and `remove`",
45                ))
46            }
47            None => (),
48        };
49        Ok(())
50    }

Source

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

Format the existing message with the Command’s context

Source

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

Create an error with a pre-defined message

§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();

Source

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

Apply Command’s formatting to the error

Generally, this is used with Error::new

Source

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());

Source

pub fn kind(&self) -> ErrorKind

Type of error for programmatic processing

Source

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

Additional information to further qualify the error

Source

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

Lookup a piece of context

Source

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.

Source

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.

Source

pub fn use_stderr(&self) -> bool

Should the message be written to stdout or not?

Source

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.

Source

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.

Examples found in repository ?

examples/derive_ref/augment_subcommands.rs (line 18)

11fn main() {
12    let cli = Command::new("Built CLI");
13    // Augment with derived subcommands
14    let cli = Subcommands::augment_subcommands(cli);
15
16    let matches = cli.get_matches();
17    let derived_subcommands = Subcommands::from_arg_matches(&matches)
18        .map_err(|err| err.exit())
19        .unwrap();
20    println!("Derived subcommands: {derived_subcommands:#?}");
21}

More examples

Hide additional examples

examples/derive_ref/augment_args.rs (line 24)

9fn main() {
10    let cli = Command::new("CLI").arg(arg!(-b - -built).action(clap::ArgAction::SetTrue));
11    // Augment built args with derived args
12    let cli = DerivedArgs::augment_args(cli);
13
14    let matches = cli.get_matches();
15    println!("Value of built: {:?}", matches.get_flag("built"));
16    println!(
17        "Value of derived via ArgMatches: {:?}",
18        matches.get_flag("derived")
19    );
20
21    // Since DerivedArgs implements FromArgMatches, we can extract it from the unstructured ArgMatches.
22    // This is the main benefit of using derived arguments.
23    let derived_matches = DerivedArgs::from_arg_matches(&matches)
24        .map_err(|err| err.exit())
25        .unwrap();
26    println!("Value of derived: {derived_matches:#?}");
27}

examples/tutorial_derive/04_04_custom.rs (line 50)

34fn main() {
35    let cli = Cli::parse();
36
37    // Let's assume the old version 1.2.3
38    let mut major = 1;
39    let mut minor = 2;
40    let mut patch = 3;
41
42    // See if --set-ver was used to set the version manually
43    let version = if let Some(ver) = cli.set_ver.as_deref() {
44        if cli.major || cli.minor || cli.patch {
45            let mut cmd = Cli::command();
46            cmd.error(
47                ErrorKind::ArgumentConflict,
48                "Can't do relative and absolute version change",
49            )
50            .exit();
51        }
52        ver.to_string()
53    } else {
54        // Increment the one requested (in a real program, we'd reset the lower numbers)
55        let (maj, min, pat) = (cli.major, cli.minor, cli.patch);
56        match (maj, min, pat) {
57            (true, false, false) => major += 1,
58            (false, true, false) => minor += 1,
59            (false, false, true) => patch += 1,
60            _ => {
61                let mut cmd = Cli::command();
62                cmd.error(
63                    ErrorKind::ArgumentConflict,
64                    "Can only modify one version field",
65                )
66                .exit();
67            }
68        };
69        format!("{major}.{minor}.{patch}")
70    };
71
72    println!("Version: {version}");
73
74    // Check for usage of -c
75    if let Some(config) = cli.config.as_deref() {
76        let input = cli
77            .input_file
78            .as_deref()
79            // 'or' is preferred to 'or_else' here since `Option::as_deref` is 'const'
80            .or(cli.spec_in.as_deref())
81            .unwrap_or_else(|| {
82                let mut cmd = Cli::command();
83                cmd.error(
84                    ErrorKind::MissingRequiredArgument,
85                    "INPUT_FILE or --spec-in is required when using --config",
86                )
87                .exit()
88            });
89        println!("Doing work using input {input} and config {config}");
90    }
91}

Source

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
    },
};

Source

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
    },
};