pub struct Error<F: ErrorFormatter = DefaultFormatter> { /* private fields */ }
Expand description
Command Line Argument Parser Error
See Command::error
to create an error.
Implementations§
source§impl<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?
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 new(kind: ErrorKind) -> Self
pub fn new(kind: ErrorKind) -> Self
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) -> Self
pub fn with_cmd(self, cmd: &Command) -> Self
Apply Command
’s formatting to the error
Generally, this is used with Error::new
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)>
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
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
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);
}
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);
}
}
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
},
};