Struct Error 

pub struct Error { /* private fields */ }

A single error from parsing or converting a TOML document.

Errors arise from two phases:

• Parsing: syntax errors such as unterminated strings, duplicate keys, or unexpected characters. parse returns the first such error as Err(Error).

• Conversion: type mismatches, missing fields, unknown keys, and other constraint violations detected by FromToml. These accumulate so that a single pass surfaces as many problems as possible.

parse_recoverable combines both phases, continuing past syntax errors and collecting them alongside conversion errors into a single Document::errors list.

Extracting information

Method	Returns
kind()	The ErrorKind variant for this error
span()	Source Span (byte offsets), 0..0 when no location applies
path()	Optional TomlPath to the offending value
message(source)	Human-readable diagnostic message
primary_label()	Optional (Span, String) label for the error site
secondary_label()	Optional (Span, String) for related locations

The message, primary_label, and secondary_label methods provide building blocks for rich diagnostics, mapping onto the label model used by codespan-reporting and annotate-snippets.

Integration with error reporting libraries

codespan-reporting example

use codespan_reporting::diagnostic::{Diagnostic, Label};

fn error_to_diagnostic(
    error: &toml_spanner::Error,
    source: &str,
) -> Diagnostic<()> {
    let mut labels = Vec::new();
    if let Some((span, text)) = error.secondary_label() {
        labels.push(Label::secondary((), span).with_message(text));
    }
    if let Some((span, label)) = error.primary_label() {
        let l = Label::primary((), span);
        labels.push(if label.is_empty() {
            l
        } else {
            l.with_message(label)
        });
    }
    Diagnostic::error()
        .with_code(error.kind().kind_name())
        .with_message(error.message_with_path(source))
        .with_labels(labels)
}

annotate-snippets example

use annotate_snippets::{AnnotationKind, Group, Level, Snippet};

fn error_to_snippet<'s>(
    error: &toml_spanner::Error,
    source: &'s str,
    path: &'s str,
) -> Group<'s> {
    let message = error.message_with_path(source);
    let mut snippet = Snippet::source(source).path(path).fold(true);
    if let Some((span, text)) = error.secondary_label() {
        snippet = snippet.annotation(
            AnnotationKind::Context.span(span.range()).label(text),
        );
    }
    if let Some((span, label)) = error.primary_label() {
        let ann = AnnotationKind::Primary.span(span.range());
        snippet = snippet.annotation(if label.is_empty() {
            ann
        } else {
            ann.label(label)
        });
    }
    Level::ERROR.primary_title(message).element(snippet)
}

Multiple error accumulation

During FromToml conversion, errors are pushed into a shared Context rather than causing an immediate abort. The sentinel type Failed signals that a branch failed without carrying error details itself. When Document::to or from_str finishes, all accumulated errors are returned in FromTomlError::errors.

parse_recoverable extends this to the parsing phase, collecting syntax errors into the same list so valid portions of the document remain available for inspection.

Implementations

impl Error

pub fn span(&self) -> Span

Returns the source span where this error occurred.

A span of 0..0 (Span::is_empty) means the error has no specific source location, as with ErrorKind::FileTooLarge.

pub fn kind(&self) -> ErrorKind<'_>

Returns the error kind.

pub fn path<'a>(&'a self) -> Option<&'a TomlPath<'a>>

Returns the TOML path where this error occurred, if available.

pub fn custom(message: impl ToString, span: Span) -> Error

Creates an error with a custom message at the given source span.

impl Error

pub fn message(&self, source: &str) -> String

Returns the diagnostic message for this error, without the TOML path.

Some error kinds extract names from source for richer messages.

pub fn message_with_path(&self, source: &str) -> String

Returns the diagnostic message for this error, with the TOML path appended.

Some error kinds extract names from source for richer messages.

pub fn primary_label(&self) -> Option<(Span, String)>

Returns the primary label span and text for this error, if any.

pub fn secondary_label(&self) -> Option<(Span, String)>

Returns the secondary label span and text, if any.

Some errors reference a related location (for example, the first definition of a duplicate key).

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

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<(ErrorKind<'static>, Span)> for Error

fn from((kind, span): (ErrorKind<'static>, Span)) -> Self

Converts to this type from the input type.

impl From<Error> for FromTomlError

Available on crate feature from-toml only.

fn from(error: Error) -> Self

Converts to this type from the input type.