Enum knuffel::errors::DecodeError

#[non_exhaustive]
pub enum DecodeError<S: ErrorSpan> {
    TypeName {
        span: S,
        found: Option<TypeName>,
        expected: ExpectedType,
        rust_type: &'static str,
    },
    ScalarKind {
        span: S,
        expected: ExpectedKind,
        found: Kind,
    },
    Missing {
        span: S,
        message: String,
    },
    MissingNode {
        message: String,
    },
    Unexpected {
        span: S,
        kind: &'static str,
        message: String,
    },
    Conversion {
        span: S,
        source: Box<dyn Error + Send + Sync + 'static>,
    },
    Unsupported {
        span: S,
        message: Cow<'static, str>,
    },
    Custom(Box<dyn Error + Send + Sync + 'static>),
}

An error type that is returned by decoder traits and emitted to the context

These are elements of the

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

TypeName

Fields

span: S

Position of the type name

found: Option<TypeName>

Type name contained in the source code

expected: ExpectedType

Expected type name or type names

rust_type: &'static str

Rust type that is being decoded when error is encountered

Unexpected type name encountered

Type names are identifiers and strings in parenthesis before node names or values.

ScalarKind

Fields

span: S

Position of the unexpected scalar

expected: ExpectedKind

Scalar kind (or multiple) expected at this position

found: Kind

Kind of scalar that is found

Different scalar kind was encountered than expected

This is emitted when integer is used instead of string, and similar. It may also be encountered when null is used for non-optional field.

Missing

Fields

span: S

Position of the node name of which has missing element

message: String

Description of what’s missing

Some required element is missing

This is emitted on missing required attributes, properties, or children. (missing type names are emitted using DecodeError::TypeName)

MissingNode

Fields

message: String

Descriptino of what’s missing

Missing named node at top level

This is similar to Missing but is only emitted for nodes on the document level. This is separate error because there is no way to show span where missing node is expected (end of input is not very helpful).

Unexpected

Fields

span: S

Position of the unexpected element

kind: &'static str

Kind of element that was found

message: String

Description of the error

Unexpected entity encountered

This is emitted for entities (arguments, properties, children) that have to matching structure field to put into, and also for nodes that aren expected to be encountered twice.

Conversion

Fields

span: S

Position of the scalar that could not be converted

source: Box<dyn Error + Send + Sync + 'static>

Original error

Bad scalar conversion

This error is emitted when some scalar value of right kind cannot be converted to the Rust value. Including, but not limited to:

1. Integer value out of range
2. FromStr returned error for the value parse by #[knuffel(.., str)]

Unsupported

Fields

span: S

Position of the value that is unsupported

message: Cow<'static, str>

Description of why the value is not supported

Unsupported value

This is currently used to error out on (base64) values when base64 feature is not enabled.

Custom(Box<dyn Error + Send + Sync + 'static>)

Custom error that can be emitted during decoding

This is not used by the knuffel itself. Note most of the time it’s better to use DecodeError::Conversion as that will associate source code span to the error.

Implementations

impl<S: ErrorSpan> DecodeError<S>

pub fn conversion<T, E>(span: &Spanned<T, S>, err: E) -> Self where
    E: Into<Box<dyn Error + Send + Sync + 'static>>, 

Construct DecodeError::Conversion error

pub fn scalar_kind(expected: Kind, found: &Spanned<Literal, S>) -> Self

Construct DecodeError::ScalarKind error

pub fn missing(node: &SpannedNode<S>, message: impl Into<String>) -> Self

Construct DecodeError::Missing error

pub fn unexpected<T>(
    elem: &Spanned<T, S>,
    kind: &'static str,
    message: impl Into<String>
) -> Self

Construct DecodeError::Unexpected error

pub fn unsupported<T, M>(span: &Spanned<T, S>, message: M) -> Self where
    M: Into<Cow<'static, str>>, 

Construct DecodeError::Unsupported error

Trait Implementations

impl<S: Debug + ErrorSpan> Debug for DecodeError<S>

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

Formats the value using the given formatter.

impl<S: ErrorSpan> Diagnostic for DecodeError<S>

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

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

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

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 self) -> Option<Box<dyn Display + 'a, Global>>

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 self) -> Option<Box<dyn Display + 'a, Global>>

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 related(
    &'a self
) -> Option<Box<dyn Iterator<Item = &'a (dyn Diagnostic + 'a)> + 'a, Global>>

Additional related Diagnostics.

impl<S: ErrorSpan> Display for DecodeError<S>

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

Formats the value using the given formatter.

impl<S: ErrorSpan> Error for DecodeError<S> where
    Self: Debug + Display, 

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()

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

👎 Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting