Trait uucore::error::UError

source · [−]

pub trait UError: Error + Send {
    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

source

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!"),
        }
    }
}

source

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!"),
        }
    }
}