Struct LabeledError

pub struct LabeledError {
    pub msg: String,
    pub labels: Vec<ErrorLabel>,
    pub code: Option<String>,
    pub url: Option<String>,
    pub help: Option<String>,
    pub inner: Vec<LabeledError>,
}

A very generic type of error used for interfacing with external code, such as scripts and plugins.

This generally covers most of the interface of miette::Diagnostic, but with types that are well-defined for our protocol.

Fields

msg: String

The main message for the error.

labels: Vec<ErrorLabel>

Labeled spans attached to the error, demonstrating to the user where the problem is.

code: Option<String>

A unique machine- and search-friendly error code to associate to the error. (e.g. nu::shell::missing_config_value)

url: Option<String>

A link to documentation about the error, used in conjunction with code

help: Option<String>

Additional help for the error, usually a hint about what the user might try

inner: Vec<LabeledError>

Errors that are related to or caused this error

Implementations

impl LabeledError

pub fn new(msg: impl Into<String>) -> LabeledError

Create a new plain LabeledError with the given message.

This is usually used builder-style with methods like .with_label() to build an error.

Example

let error = LabeledError::new("Something bad happened");
assert_eq!("Something bad happened", error.to_string());

pub fn with_label(self, text: impl Into<String>, span: Span) -> Self

Add a labeled span to the error to demonstrate to the user where the problem is.

Example

let error = LabeledError::new("An error")
    .with_label("happened here", span);
assert_eq!("happened here", &error.labels[0].text);
assert_eq!(span, error.labels[0].span);

pub fn with_code(self, code: impl Into<String>) -> Self

Add a unique machine- and search-friendly error code to associate to the error. (e.g. nu::shell::missing_config_value)

Example

let error = LabeledError::new("An error")
    .with_code("my_product::error");
assert_eq!(Some("my_product::error"), error.code.as_deref());

pub fn with_url(self, url: impl Into<String>) -> Self

Add a link to documentation about the error, used in conjunction with code.

Example

let error = LabeledError::new("An error")
    .with_url("https://example.org/");
assert_eq!(Some("https://example.org/"), error.url.as_deref());

pub fn with_help(self, help: impl Into<String>) -> Self

Add additional help for the error, usually a hint about what the user might try.

Example

let error = LabeledError::new("An error")
    .with_help("did you try turning it off and back on again?");
assert_eq!(Some("did you try turning it off and back on again?"), error.help.as_deref());

pub fn with_inner(self, inner: impl Into<LabeledError>) -> Self

Add an error that is related to or caused this error.

Example

let error = LabeledError::new("An error")
    .with_inner(LabeledError::new("out of coolant"));
assert_eq!(LabeledError::new("out of coolant"), error.inner[0]);

pub fn render_error_to_string( diag: impl Diagnostic, fancy_errors: bool, ) -> String

pub fn from_diagnostic(diag: &(impl Diagnostic + ?Sized)) -> LabeledError

Create a LabeledError from a type that implements miette::Diagnostic.

Example

ShellError implements miette::Diagnostic:

let error = LabeledError::from_diagnostic(&ShellError::IOError { msg: "error".into() });
assert!(error.to_string().contains("I/O error"));

Trait Implementations

impl Clone for LabeledError

fn clone(&self) -> LabeledError

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LabeledError

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for LabeledError

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Diagnostic for LabeledError

fn code<'a>(&'a self) -> Option<Box<dyn Display + 'a>>

Unique diagnostic code that can be used to look up more information about this Diagnostic. Ideally also globally unique, and documented in the toplevel crate’s documentation for easy searching. Rust path format (foo::bar::baz) is recommended, but more classic codes like E0123 or enums will work just fine.

fn severity(&self) -> Option<Severity>

Diagnostic severity. This may be used by ReportHandlers to change the display format of this diagnostic.

fn help<'a>(&'a self) -> Option<Box<dyn Display + 'a>>

Additional help text related to this Diagnostic. Do you have any advice for the poor soul who’s just run into this issue?

fn url<'a>(&'a self) -> Option<Box<dyn Display + 'a>>

URL to visit for a more detailed explanation/help about this Diagnostic.

fn source_code(&self) -> Option<&dyn SourceCode>

Source code to apply this Diagnostic’s Diagnostic::labels to.

fn labels(&self) -> Option<Box<dyn Iterator<Item = LabeledSpan> + '_>>

Labels to apply to this Diagnostic’s Diagnostic::source_code

fn related<'a>( &'a self, ) -> Option<Box<dyn Iterator<Item = &'a dyn Diagnostic> + 'a>>

Additional related Diagnostics.

fn diagnostic_source(&self) -> Option<&dyn Diagnostic>

The cause of the error.

impl Display for LabeledError

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

Formats the value using the given formatter.

impl Error for LabeledError

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

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

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

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

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

Provides type-based access to context intended for error reports.

impl From<LabeledError> for ShellError

fn from(error: LabeledError) -> Self

Converts to this type from the input type.

impl From<ShellError> for LabeledError

fn from(err: ShellError) -> Self

Converts to this type from the input type.

impl PartialEq for LabeledError

fn eq(&self, other: &LabeledError) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for LabeledError

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for LabeledError

impl StructuralPartialEq for LabeledError