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,
impl<F> Error<F>where
F: ErrorFormatter,
Sourcepub fn raw(kind: ErrorKind, message: impl Display) -> Error<F>
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?
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 }
Sourcepub fn format(self, cmd: &mut Command) -> Error<F>
pub fn format(self, cmd: &mut Command) -> Error<F>
Format the existing message with the Command’s context
Sourcepub fn new(kind: ErrorKind) -> Error<F>
pub fn new(kind: ErrorKind) -> Error<F>
Create an error with a pre-defined message
See also
§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();
Sourcepub fn with_cmd(self, cmd: &Command) -> Error<F>
pub fn with_cmd(self, cmd: &Command) -> Error<F>
Apply Command
’s formatting to the error
Generally, this is used with Error::new
Sourcepub fn apply<EF>(self) -> Error<EF>where
EF: ErrorFormatter,
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());
Sourcepub fn context(&self) -> impl Iterator<Item = (ContextKind, &ContextValue)>
pub fn context(&self) -> impl Iterator<Item = (ContextKind, &ContextValue)>
Additional information to further qualify the error
Sourcepub fn get(&self, kind: ContextKind) -> Option<&ContextValue>
pub fn get(&self, kind: ContextKind) -> Option<&ContextValue>
Lookup a piece of context
Sourcepub fn insert(
&mut self,
kind: ContextKind,
value: ContextValue,
) -> Option<ContextValue>
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.
Sourcepub fn remove(&mut self, kind: ContextKind) -> Option<ContextValue>
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.
Sourcepub fn use_stderr(&self) -> bool
pub fn use_stderr(&self) -> bool
Should the message be written to stdout
or not?
Sourcepub fn exit_code(&self) -> i32
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
.
Sourcepub fn exit(&self) -> !
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?
More examples
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}
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}
Sourcepub fn print(&self) -> Result<(), Error>
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
},
};