Struct user_error::UserFacingError

pub struct UserFacingError { /* fields omitted */ }

The eponymous struct. You can create a new one from using user_error::UserFacingError::new() however I recommend you use your own error types and have them implement UFE instead of using UserFacingError directly. This is more of an example type, or a way to construct a pretty messages without implementing your own error type.

Implementations

impl UserFacingError

pub fn new<S: Into<String>>(summary: S) -> UserFacingError

This is how users create a new User Facing Error. The value passed to new() will be used as an error summary. Error summaries are displayed first, prefixed by 'Error: '.

Example

let err = UserFacingError::new("File failed to open");

pub fn update<S: Into<String>>(&mut self, summary: S)

Replace the error summary.

Example

let mut err = UserFacingError::new("File failed to open");
err.update("Failed Task");

pub fn push<S: Into<String>>(&mut self, new_summary: S)

Replace the error summary and add the previous error summary to the list of reasons

Example

let mut err = UserFacingError::new("File failed to open");
err.push("Failed Task");

pub fn reason<S: Into<String>>(self, reason: S) -> UserFacingError

Add a reason to the UserFacingError. Reasons are displayed in a bulleted list below the summary, in the reverse order they were added.

Example

let err = UserFacingError::new("File failed to open")
                            .reason("File not found")
                            .reason("Directory cannot be entered");

pub fn clear_reasons(&mut self)

Clears all reasons from a UserFacingError.

Example

let mut err = UserFacingError::new("File failed to open")
                            .reason("File not found")
                            .reason("Directory cannot be entered");
err.clear_reasons();

pub fn help<S: Into<String>>(self, helptext: S) -> UserFacingError

Add help text to the error. Help text is displayed last, in a muted fashion.

Example

let err = UserFacingError::new("File failed to open")
                            .reason("File not found")
                            .help("Check if the file exists.");

pub fn clear_helptext(&mut self)

Clears all the help text from a UserFacingError.

Example

let mut err = UserFacingError::new("File failed to open")
                            .reason("File not found")
                            .reason("Directory cannot be entered")
                            .help("Check if the file exists.");
err.clear_helptext();

Trait Implementations

impl Debug for UserFacingError

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Display for UserFacingError

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Error for UserFacingError

fn source(&self) -> Option<&(dyn Error + 'static)>

The lower-level source of this error, if any.

fn backtrace(&self) -> Option<&Backtrace>

🔬 This is a nightly-only experimental API. (backtrace)

Returns a stack backtrace, if available, of where this error occurred.

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

if let Err(e) = "xc".parse::<u32>() { // Print e itself, no need for description(). eprintln!("Error: {}", e); }

fn cause(&self) -> Option<&dyn Error>

👎 Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

impl<'_> From<&'_ (dyn Error + '_)> for UserFacingError

Allows you to create UserFacingErrors From std Errors. You should really just implement UFE for your error type, but if you wanted to convert before quitting so you could add help text of something you can use this.

fn from(error: &dyn Error) -> UserFacingError

Performs the conversion.

impl From<Box<dyn Error + 'static>> for UserFacingError

Allows you to create UserFacingErrors From std Errors. You should really just implement UFE for your error type, but if you wanted to convert before quitting so you could add help text of something you can use this.

fn from(error: Box<dyn Error>) -> UserFacingError

Performs the conversion.

impl From<Error> for UserFacingError

Allows you to create UserFacingErrors From std::io::Error for convenience You should really just implement UFE for your error type, but if you wanted to convert before quitting so you could add help text of something you can use this.

fn from(error: Error) -> UserFacingError

Performs the conversion.

impl<T: Debug> From<Result<T, Box<dyn Error + 'static>>> for UserFacingError

Allows you to create UserFacingErrors From std Errors wrapped in a Result You should really just implement UFE for your error type, but if you wanted to convert before quitting so you could add help text of something you can use this.

fn from(error: Result<T, Box<dyn Error>>) -> UserFacingError

Performs the conversion.

impl UFE for UserFacingError

fn summary(&self) -> String

Returns a summary of the error. This will be printed in red, prefixed by "Error: ", at the top of the error message.

fn reasons(&self) -> Option<Vec<String>>

Returns a vector of Strings that will be listed as bullet points below the summary. By default, lists any errors returned by .source() recursively.

fn helptext(&self) -> Option<String>

Returns help text that is listed below the reasons in a muted fashion. Useful for additional details, or suggested next steps.

fn print(&self)

Prints the formatted error. # Example use user_error::{UserFacingError, UFE}; UserFacingError::new("File failed to open") .reason("File not found") .help("Try: touch file.txt") .print();

fn print_and_exit(&self)

Convenience function that pretty prints the error and exits the program. # Example should_panic use user_error::{UserFacingError, UFE}; UserFacingError::new("File failed to open") .reason("File not found") .help("Try: touch file.txt") .print_and_exit();

fn into_ufe(&self) -> UserFacingError

Consumes the UFE and returns a UserFacingError. Useful if you want access to additional functions to edit the error message before exiting the program. # Example ``` use user_error::{UserFacingError, UFE}; use std::fmt::{self, Display}; use std::error::Error;