Struct Error

pub struct Error { /* private fields */ }

An error encountered during attribute parsing.

Given that most errors darling encounters represent code bugs in dependent crates, the internal structure of the error is deliberately opaque.

Usage

Proc-macro expansion happens very infrequently compared to runtime tasks such as deserialization, and it happens in the context of an expensive compilation taks. For that reason, darling prefers not to fail on the first error it encounters, instead doing as much work as it can, accumulating errors into a single report.

As a result, darling::Error is more of guaranteed-non-empty error collection than a single problem. These errors also have some notion of hierarchy, stemming from the hierarchical nature of darling’s input.

These characteristics make for great experiences when using darling-powered crates, provided crates using darling adhere to some best practices:

1. Do not attempt to simplify a darling::Error into some other error type, such as syn::Error. To surface compile errors, instead use darling::Error::write_errors. This preserves all span information, suggestions, etc. Wrapping a darling::Error in a custom error enum works as-expected and does not force any loss of fidelity.
2. Do not use early return (e.g. the ? operator) for custom validations. Instead, create an error::Accumulator to collect errors as they are encountered. Then use Accumulator::finish to return your validated result; it will give Ok if and only if no errors were encountered. This can create very complex custom validation functions; in those cases, split independent “validation chains” out into their own functions to keep the main validator manageable.
3. Use darling::Error::custom to create additional errors as-needed, then call with_span to ensure those errors appear in the right place. Use darling::util::SpannedValue to keep span information around on parsed fields so that custom diagnostics can point to the correct parts of the input AST.

Implementations

impl Error

Error creation functions

pub fn custom<T>(msg: T) -> Error

where T: Display,

Creates a new error with a custom message.

pub fn duplicate_field(name: &str) -> Error

Creates a new error for a field that appears twice in the input.

pub fn duplicate_field_path(path: &Path) -> Error

Creates a new error for a field that appears twice in the input. Helper to avoid repeating the syn::Path to String conversion.

pub fn missing_field(name: &str) -> Error

Creates a new error for a non-optional field that does not appear in the input.

pub fn unknown_field(name: &str) -> Error

Creates a new error for a field name that appears in the input but does not correspond to a known field.

pub fn unknown_field_path(path: &Path) -> Error

Creates a new error for a field name that appears in the input but does not correspond to a known field. Helper to avoid repeating the syn::Path to String conversion.

pub fn unknown_field_with_alts<'a, T, I>(field: &str, alternates: I) -> Error

where T: AsRef<str> + 'a, I: IntoIterator<Item = &'a T>,

Creates a new error for a field name that appears in the input but does not correspond to a known attribute. The second argument is the list of known attributes; if a similar name is found that will be shown in the emitted error message.

pub fn unknown_field_path_with_alts<'a, T, I>( field: &Path, alternates: I, ) -> Error

where T: AsRef<str> + 'a, I: IntoIterator<Item = &'a T>,

Creates a new error for a field name that appears in the input but does not correspond to a known attribute. The second argument is the list of known attributes; if a similar name is found that will be shown in the emitted error message.

pub fn unsupported_shape(shape: &str) -> Error

Creates a new error for a struct or variant that does not adhere to the supported shape.

pub fn unsupported_shape_with_expected<T>(shape: &str, expected: &T) -> Error

where T: Display,

pub fn unsupported_format(format: &str) -> Error

pub fn unexpected_type(ty: &str) -> Error

Creates a new error for a field which has an unexpected literal type.

pub fn unexpected_expr_type(expr: &Expr) -> Error

pub fn unexpected_lit_type(lit: &Lit) -> Error

Creates a new error for a field which has an unexpected literal type. This will automatically extract the literal type name from the passed-in Lit and set the span to encompass only the literal value.

Usage

This is most frequently used in overrides of the FromMeta::from_value method.

use darling::{FromMeta, Error, Result};
use syn::{Lit, LitStr};

pub struct Foo(String);

impl FromMeta for Foo {
    fn from_value(value: &Lit) -> Result<Self> {
        if let Lit::Str(ref lit_str) = *value {
            Ok(Foo(lit_str.value()))
        } else {
            Err(Error::unexpected_lit_type(value))
        }
    }
}

pub fn unknown_value(value: &str) -> Error

Creates a new error for a value which doesn’t match a set of expected literals.

pub fn too_few_items(min: usize) -> Error

Creates a new error for a list which did not get enough items to proceed.

pub fn too_many_items(max: usize) -> Error

Creates a new error when a list got more items than it supports. The max argument is the largest number of items the receiver could accept.

pub fn multiple(errors: Vec<Error>) -> Error

Bundle a set of multiple errors into a single Error instance.

Usually it will be more convenient to use an error::Accumulator.

Panics

This function will panic if errors.is_empty() == true.

pub fn accumulator() -> Accumulator

Creates an error collector, for aggregating multiple errors

See Accumulator for details.

impl Error

Error instance methods

pub fn has_span(&self) -> bool

Check if this error is associated with a span in the token stream.

pub fn with_span<T>(self, node: &T) -> Error

where T: Spanned,

Tie a span to the error if none is already present. This is used in darling::FromMeta and other traits to attach errors to the most specific possible location in the input source code.

All darling-built impls, either from the crate or from the proc macro, will call this when appropriate during parsing, so it should not be necessary to call this unless you have overridden:

• FromMeta::from_meta
• FromMeta::from_nested_meta
• FromMeta::from_value

pub fn span(&self) -> Span

Get a span for the error.

Return Value

This function will return Span::call_site() if Self::has_span is false. To get the span only if one has been explicitly set for self, instead use Error::explicit_span.

pub fn explicit_span(&self) -> Option<Span>

Get the span for self, if one has been set.

pub fn flatten(self) -> Error

Recursively converts a tree of errors to a flattened list.

Child Diagnostics

If the diagnostics feature is enabled, any child diagnostics on self will be cloned down to all the errors within self.

pub fn at<T>(self, location: T) -> Error

where T: Display,

Adds a location to the error, such as a field or variant. Locations must be added in reverse order of specificity.

pub fn at_path(self, path: &Path) -> Error

Adds a location to the error, such as a field or variant. Locations must be added in reverse order of specificity. This is a helper function to avoid repeating path to string logic.

pub fn len(&self) -> usize

Gets the number of individual errors in this error.

This function never returns 0, as it’s impossible to construct a multi-error from an empty Vec.

pub fn add_sibling_alts_for_unknown_field<'a, T, I>( self, alternates: I, ) -> Error

where T: AsRef<str> + 'a, I: IntoIterator<Item = &'a T>,

Consider additional field names as “did you mean” suggestions for unknown field errors if and only if the caller appears to be operating at error’s origin (meaning no calls to Self::at have yet taken place).

Usage

flatten fields in derived trait implementations rely on this method to offer correct “did you mean” suggestions in errors.

Because the flatten field receives all unknown fields, if a user mistypes a field name that is present on the outer struct but not the flattened struct, they would get an incomplete or inferior suggestion unless this method was invoked.

pub fn write_errors(self) -> TokenStream

Write this error and any children as compile errors into a TokenStream to be returned by the proc-macro.

The behavior of this method will be slightly different if the diagnostics feature is enabled: In that case, the diagnostics will be emitted immediately by this call, and an empty TokenStream will be returned.

Return these tokens unmodified to avoid disturbing the attached span information.

Usage

// in your proc-macro function
let opts = match MyOptions::from_derive_input(&ast) {
    Ok(val) => val,
    Err(err) => {
        return err.write_errors();
    }
}

Trait Implementations

impl Clone for Error

fn clone(&self) -> Error

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

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 source(&self) -> Option<&(dyn Error + 'static)>

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

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 Extend<Error> for Accumulator

fn extend<I>(&mut self, iter: I)

where I: IntoIterator<Item = Error>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

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

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

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

Reserves capacity in a collection for the given number of additional elements.

impl From<Error> for Error

fn from(e: Error) -> Error

Converts to this type from the input type.

impl From<Error> for Error

fn from(e: Error) -> Error

Converts to this type from the input type.

impl IntoIterator for Error

type Item = Error

The type of the elements being iterated over.

type IntoIter = IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> IntoIter

Creates an iterator from a value.