pub struct Error<F: ErrorFormatter = DefaultFormatter> { /* private fields */ }
Expand description
Command Line Argument Parser Error
See Command::error
to create an error.
Implementations
sourceimpl<F: ErrorFormatter> Error<F>
impl<F: ErrorFormatter> Error<F>
sourcepub fn raw(kind: ErrorKind, message: impl Display) -> Self
pub fn raw(kind: ErrorKind, message: impl Display) -> Self
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 26-29)
≺ ≻
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
fn from_arg_matches(matches: &ArgMatches) -> Result<Self, Error> {
match matches.subcommand() {
Some(("add", args)) => Ok(Self::Add(AddArgs::from_arg_matches(args)?)),
Some(("remove", args)) => Ok(Self::Remove(RemoveArgs::from_arg_matches(args)?)),
Some((_, _)) => Err(Error::raw(
ErrorKind::InvalidSubcommand,
"Valid subcommands are `add` and `remove`",
)),
None => Err(Error::raw(
ErrorKind::MissingSubcommand,
"Valid subcommands are `add` and `remove`",
)),
}
}
fn update_from_arg_matches(&mut self, matches: &ArgMatches) -> Result<(), Error> {
match matches.subcommand() {
Some(("add", args)) => *self = Self::Add(AddArgs::from_arg_matches(args)?),
Some(("remove", args)) => *self = Self::Remove(RemoveArgs::from_arg_matches(args)?),
Some((_, _)) => {
return Err(Error::raw(
ErrorKind::InvalidSubcommand,
"Valid subcommands are `add` and `remove`",
))
}
None => (),
};
Ok(())
}
sourcepub fn format(self, cmd: &mut Command) -> Self
pub fn format(self, cmd: &mut Command) -> Self
Format the existing message with the Command’s context
sourcepub fn apply<EF: ErrorFormatter>(self) -> Error<EF>
pub fn apply<EF: ErrorFormatter>(self) -> Error<EF>
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)>
Available on crate feature error-context
only.
pub fn context(&self) -> impl Iterator<Item = (ContextKind, &ContextValue)>
error-context
only.Additional information to further qualify the error
sourcepub fn get(&self, kind: ContextKind) -> Option<&ContextValue>
Available on crate feature error-context
only.
pub fn get(&self, kind: ContextKind) -> Option<&ContextValue>
error-context
only.Lookup a piece of context
sourcepub fn use_stderr(&self) -> bool
pub fn use_stderr(&self) -> bool
Should the message be written to stdout
or not?
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
examples/derive_ref/augment_args.rs (line 24)
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
fn main() {
let cli = Command::new("CLI").arg(arg!(-b - -built).action(clap::ArgAction::SetTrue));
// Augment built args with derived args
let cli = DerivedArgs::augment_args(cli);
let matches = cli.get_matches();
println!("Value of built: {:?}", matches.get_flag("built"));
println!(
"Value of derived via ArgMatches: {:?}",
matches.get_flag("derived")
);
// Since DerivedArgs implements FromArgMatches, we can extract it from the unstructured ArgMatches.
// This is the main benefit of using derived arguments.
let derived_matches = DerivedArgs::from_arg_matches(&matches)
.map_err(|err| err.exit())
.unwrap();
println!("Value of derived: {:#?}", derived_matches);
}
examples/tutorial_derive/04_04_custom.rs (line 50)
≺ ≻
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91
fn main() {
let cli = Cli::parse();
// Let's assume the old version 1.2.3
let mut major = 1;
let mut minor = 2;
let mut patch = 3;
// See if --set-ver was used to set the version manually
let version = if let Some(ver) = cli.set_ver.as_deref() {
if cli.major || cli.minor || cli.patch {
let mut cmd = Cli::command();
cmd.error(
ErrorKind::ArgumentConflict,
"Can't do relative and absolute version change",
)
.exit();
}
ver.to_string()
} else {
// Increment the one requested (in a real program, we'd reset the lower numbers)
let (maj, min, pat) = (cli.major, cli.minor, cli.patch);
match (maj, min, pat) {
(true, false, false) => major += 1,
(false, true, false) => minor += 1,
(false, false, true) => patch += 1,
_ => {
let mut cmd = Cli::command();
cmd.error(
ErrorKind::ArgumentConflict,
"Can only modify one version field",
)
.exit();
}
};
format!("{}.{}.{}", major, minor, patch)
};
println!("Version: {}", version);
// Check for usage of -c
if let Some(config) = cli.config.as_deref() {
let input = cli
.input_file
.as_deref()
// 'or' is preferred to 'or_else' here since `Option::as_deref` is 'const'
.or(cli.spec_in.as_deref())
.unwrap_or_else(|| {
let mut cmd = Cli::command();
cmd.error(
ErrorKind::MissingRequiredArgument,
"INPUT_FILE or --spec-in is required when using --config",
)
.exit()
});
println!("Doing work using input {} and config {}", input, config);
}
}
examples/tutorial_builder/04_04_custom.rs (line 38)
≺ ≻
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
fn main() {
// Create application like normal
let mut cmd = command!() // requires `cargo` feature
// Add the version arguments
.arg(arg!(--"set-ver" <VER> "set version manually"))
.arg(arg!(--major "auto inc major").action(ArgAction::SetTrue))
.arg(arg!(--minor "auto inc minor").action(ArgAction::SetTrue))
.arg(arg!(--patch "auto inc patch").action(ArgAction::SetTrue))
// Arguments can also be added to a group individually, these two arguments
// are part of the "input" group which is not required
.arg(arg!([INPUT_FILE] "some regular input").value_parser(value_parser!(PathBuf)))
.arg(
arg!(--"spec-in" <SPEC_IN> "some special input argument")
.value_parser(value_parser!(PathBuf)),
)
// Now let's assume we have a -c [config] argument which requires one of
// (but **not** both) the "input" arguments
.arg(arg!(config: -c <CONFIG>).value_parser(value_parser!(PathBuf)));
let matches = cmd.get_matches_mut();
// Let's assume the old version 1.2.3
let mut major = 1;
let mut minor = 2;
let mut patch = 3;
// See if --set-ver was used to set the version manually
let version = if let Some(ver) = matches.get_one::<String>("set-ver") {
if matches.get_flag("major") || matches.get_flag("minor") || matches.get_flag("patch") {
cmd.error(
ErrorKind::ArgumentConflict,
"Can't do relative and absolute version change",
)
.exit();
}
ver.to_string()
} else {
// Increment the one requested (in a real program, we'd reset the lower numbers)
let (maj, min, pat) = (
matches.get_flag("major"),
matches.get_flag("minor"),
matches.get_flag("patch"),
);
match (maj, min, pat) {
(true, false, false) => major += 1,
(false, true, false) => minor += 1,
(false, false, true) => patch += 1,
_ => {
cmd.error(
ErrorKind::ArgumentConflict,
"Can only modify one version field",
)
.exit();
}
};
format!("{}.{}.{}", major, minor, patch)
};
println!("Version: {}", version);
// Check for usage of -c
if matches.contains_id("config") {
let input = matches
.get_one::<PathBuf>("INPUT_FILE")
.or_else(|| matches.get_one::<PathBuf>("spec-in"))
.unwrap_or_else(|| {
cmd.error(
ErrorKind::MissingRequiredArgument,
"INPUT_FILE or --spec-in is required when using --config",
)
.exit()
})
.display();
println!(
"Doing work using input {} and config {}",
input,
matches.get_one::<PathBuf>("config").unwrap().display()
);
}
}
sourcepub fn print(&self) -> Result<()>
pub fn print(&self) -> Result<()>
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
},
};
Trait Implementations
sourceimpl<F: ErrorFormatter> Debug for Error<F>
impl<F: ErrorFormatter> Debug for Error<F>
sourceimpl<F: ErrorFormatter> Display for Error<F>
impl<F: ErrorFormatter> Display for Error<F>
sourceimpl<F: ErrorFormatter> Error for Error<F>
impl<F: ErrorFormatter> Error for Error<F>
sourcefn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
The lower-level source of this error, if any. Read more
1.0.0 · sourcefn description(&self) -> &str
fn description(&self) -> &str
👎Deprecated since 1.42.0: use the Display impl or to_string()
sourceimpl<F: ErrorFormatter> From<Error> for Error<F>
impl<F: ErrorFormatter> From<Error> for Error<F>
Auto Trait Implementations
impl<F = RichFormatter> !RefUnwindSafe for Error<F>
impl<F> Send for Error<F>where
F: Send,
impl<F> Sync for Error<F>where
F: Sync,
impl<F> Unpin for Error<F>where
F: Unpin,
impl<F = RichFormatter> !UnwindSafe for Error<F>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more