pub trait UError: Error + Send {
// Provided methods
fn code(&self) -> i32 { ... }
fn usage(&self) -> bool { ... }
}Expand description
Custom errors defined by the utils and uucore.
All errors should implement std::error::Error, std::fmt::Display and
std::fmt::Debug and have an additional code method that specifies the
exit code of the program if the error is returned from uumain.
An example of a custom error from ls:
use uucore::{
display::Quotable,
error::{UError, UResult}
};
use std::{
error::Error,
fmt::{Display, Debug},
path::PathBuf
};
#[derive(Debug)]
enum LsError {
InvalidLineWidth(String),
NoMetadata(PathBuf),
}
impl UError for LsError {
fn code(&self) -> i32 {
match self {
LsError::InvalidLineWidth(_) => 2,
LsError::NoMetadata(_) => 1,
}
}
}
impl Error for LsError {}
impl Display for LsError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
LsError::InvalidLineWidth(s) => write!(f, "invalid line width: {}", s.quote()),
LsError::NoMetadata(p) => write!(f, "could not open file: {}", p.quote()),
}
}
}The main routine would look like this:
#[uucore::main]
pub fn uumain(args: impl uucore::Args) -> UResult<()> {
// Perform computations here ...
return Err(LsError::InvalidLineWidth(String::from("test")).into())
}The call to into() is required to convert the LsError to
Box<dyn UError>. The implementation for From is provided automatically.
A crate like quick_error might
also be used, but will still require an impl for the code method.
Provided Methods§
sourcefn code(&self) -> i32
fn code(&self) -> i32
Error code of a custom error.
Set a return value for each variant of an enum-type to associate an error code (which is returned to the system shell) with an error variant.
Example
use uucore::{
display::Quotable,
error::UError
};
use std::{
error::Error,
fmt::{Display, Debug},
path::PathBuf
};
#[derive(Debug)]
enum MyError {
Foo(String),
Bar(PathBuf),
Bing(),
}
impl UError for MyError {
fn code(&self) -> i32 {
match self {
MyError::Foo(_) => 2,
// All other errors yield the same error code, there's no
// need to list them explicitly.
_ => 1,
}
}
}
impl Error for MyError {}
impl Display for MyError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
use MyError as ME;
match self {
ME::Foo(s) => write!(f, "Unknown Foo: {}", s.quote()),
ME::Bar(p) => write!(f, "Couldn't find Bar: {}", p.quote()),
ME::Bing() => write!(f, "Exterminate!"),
}
}
}sourcefn usage(&self) -> bool
fn usage(&self) -> bool
Print usage help to a custom error.
Return true or false to control whether a short usage help is printed
below the error message. The usage help is in the format: “Try {name} --help for more information.” and printed only if true is returned.
Example
use uucore::{
display::Quotable,
error::UError
};
use std::{
error::Error,
fmt::{Display, Debug},
path::PathBuf
};
#[derive(Debug)]
enum MyError {
Foo(String),
Bar(PathBuf),
Bing(),
}
impl UError for MyError {
fn usage(&self) -> bool {
match self {
// This will have a short usage help appended
MyError::Bar(_) => true,
// These matches won't have a short usage help appended
_ => false,
}
}
}
impl Error for MyError {}
impl Display for MyError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
use MyError as ME;
match self {
ME::Foo(s) => write!(f, "Unknown Foo: {}", s.quote()),
ME::Bar(p) => write!(f, "Couldn't find Bar: {}", p.quote()),
ME::Bing() => write!(f, "Exterminate!"),
}
}
}