Revision control
Copy as Markdown
Other Tools
//! The `darling::Error` type, the multiple error `Accumulator`, and their internals.
//!
//! Error handling is one of the core values of `darling`; creating great errors is hard and
//! never the reason that a proc-macro author started writing their crate. As a result, the
//! `Error` type in `darling` tries to make adding span information, suggestions, and other
//! help content easy when manually implementing `darling` traits, and automatic when deriving
//! them.
use proc_macro2::{Span, TokenStream};
use std::error::Error as StdError;
use std::fmt;
use std::iter::{self, Iterator};
use std::string::ToString;
use std::vec;
use syn::spanned::Spanned;
use syn::{Expr, Lit, LitStr, Path};
#[cfg(feature = "diagnostics")]
mod child;
mod kind;
use crate::util::path_to_string;
use self::kind::{ErrorKind, ErrorUnknownField};
/// An alias of `Result` specific to attribute parsing.
pub type Result<T> = ::std::result::Result<T, Error>;
/// 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`](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.
#[derive(Debug, Clone)]
pub struct Error {
kind: ErrorKind,
locations: Vec<String>,
/// The span to highlight in the emitted diagnostic.
span: Option<Span>,
/// Additional diagnostic messages to show with the error.
#[cfg(feature = "diagnostics")]
children: Vec<child::ChildDiagnostic>,
}
/// Error creation functions
impl Error {
pub(in crate::error) fn new(kind: ErrorKind) -> Self {
Error {
kind,
locations: Vec::new(),
span: None,
#[cfg(feature = "diagnostics")]
children: vec![],
}
}
/// Creates a new error with a custom message.
pub fn custom<T: fmt::Display>(msg: T) -> Self {
Error::new(ErrorKind::Custom(msg.to_string()))
}
/// Creates a new error for a field that appears twice in the input.
pub fn duplicate_field(name: &str) -> Self {
Error::new(ErrorKind::DuplicateField(name.into()))
}
/// 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 duplicate_field_path(path: &Path) -> Self {
Error::duplicate_field(&path_to_string(path))
}
/// Creates a new error for a non-optional field that does not appear in the input.
pub fn missing_field(name: &str) -> Self {
Error::new(ErrorKind::MissingField(name.into()))
}
/// 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(name: &str) -> Self {
Error::new(ErrorKind::UnknownField(name.into()))
}
/// 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_path(path: &Path) -> Self {
Error::unknown_field(&path_to_string(path))
}
/// 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_with_alts<'a, T, I>(field: &str, alternates: I) -> Self
where
T: AsRef<str> + 'a,
I: IntoIterator<Item = &'a T>,
{
Error::new(ErrorUnknownField::with_alts(field, alternates).into())
}
/// 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) -> Self
where
T: AsRef<str> + 'a,
I: IntoIterator<Item = &'a T>,
{
Error::new(ErrorUnknownField::with_alts(&path_to_string(field), alternates).into())
}
/// Creates a new error for a struct or variant that does not adhere to the supported shape.
pub fn unsupported_shape(shape: &str) -> Self {
Error::new(ErrorKind::UnsupportedShape {
observed: shape.into(),
expected: None,
})
}
pub fn unsupported_shape_with_expected<T: fmt::Display>(shape: &str, expected: &T) -> Self {
Error::new(ErrorKind::UnsupportedShape {
observed: shape.into(),
expected: Some(expected.to_string()),
})
}
pub fn unsupported_format(format: &str) -> Self {
Error::new(ErrorKind::UnexpectedFormat(format.into()))
}
/// Creates a new error for a field which has an unexpected literal type.
pub fn unexpected_type(ty: &str) -> Self {
Error::new(ErrorKind::UnexpectedType(ty.into()))
}
pub fn unexpected_expr_type(expr: &Expr) -> Self {
Error::unexpected_type(match *expr {
Expr::Array(_) => "array",
Expr::Assign(_) => "assign",
Expr::Async(_) => "async",
Expr::Await(_) => "await",
Expr::Binary(_) => "binary",
Expr::Block(_) => "block",
Expr::Break(_) => "break",
Expr::Call(_) => "call",
Expr::Cast(_) => "cast",
Expr::Closure(_) => "closure",
Expr::Const(_) => "const",
Expr::Continue(_) => "continue",
Expr::Field(_) => "field",
Expr::ForLoop(_) => "for_loop",
Expr::Group(_) => "group",
Expr::If(_) => "if",
Expr::Index(_) => "index",
Expr::Infer(_) => "infer",
Expr::Let(_) => "let",
Expr::Lit(_) => "lit",
Expr::Loop(_) => "loop",
Expr::Macro(_) => "macro",
Expr::Match(_) => "match",
Expr::MethodCall(_) => "method_call",
Expr::Paren(_) => "paren",
Expr::Path(_) => "path",
Expr::Range(_) => "range",
Expr::Reference(_) => "reference",
Expr::Repeat(_) => "repeat",
Expr::Return(_) => "return",
Expr::Struct(_) => "struct",
Expr::Try(_) => "try",
Expr::TryBlock(_) => "try_block",
Expr::Tuple(_) => "tuple",
Expr::Unary(_) => "unary",
Expr::Unsafe(_) => "unsafe",
Expr::Verbatim(_) => "verbatim",
Expr::While(_) => "while",
Expr::Yield(_) => "yield",
// non-exhaustive enum
_ => "unknown",
})
.with_span(expr)
}
/// 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.
///
/// ```rust
/// # // pretend darling_core is darling so the doc example looks correct.
/// # extern crate darling_core as darling;
/// # extern crate syn;
///
/// 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))
/// }
/// }
/// }
///
/// # fn main() {}
/// ```
pub fn unexpected_lit_type(lit: &Lit) -> Self {
Error::unexpected_type(match *lit {
Lit::Str(_) => "string",
Lit::ByteStr(_) => "byte string",
Lit::Byte(_) => "byte",
Lit::Char(_) => "char",
Lit::Int(_) => "int",
Lit::Float(_) => "float",
Lit::Bool(_) => "bool",
Lit::Verbatim(_) => "verbatim",
// non-exhaustive enum
_ => "unknown",
})
.with_span(lit)
}
/// Creates a new error for a value which doesn't match a set of expected literals.
pub fn unknown_value(value: &str) -> Self {
Error::new(ErrorKind::UnknownValue(value.into()))
}
/// Creates a new error for a list which did not get enough items to proceed.
pub fn too_few_items(min: usize) -> Self {
Error::new(ErrorKind::TooFewItems(min))
}
/// 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 too_many_items(max: usize) -> Self {
Error::new(ErrorKind::TooManyItems(max))
}
/// Bundle a set of multiple errors into a single `Error` instance.
///
/// Usually it will be more convenient to use an [`error::Accumulator`](Accumulator).
///
/// # Panics
/// This function will panic if `errors.is_empty() == true`.
pub fn multiple(mut errors: Vec<Error>) -> Self {
match errors.len() {
1 => errors
.pop()
.expect("Error array of length 1 has a first item"),
0 => panic!("Can't deal with 0 errors"),
_ => Error::new(ErrorKind::Multiple(errors)),
}
}
/// Creates an error collector, for aggregating multiple errors
///
/// See [`Accumulator`] for details.
pub fn accumulator() -> Accumulator {
Default::default()
}
}
impl Error {
/// Create a new error about a literal string that doesn't match a set of known
/// or permissible values. This function can be made public if the API proves useful
/// beyond impls for `syn` types.
pub(crate) fn unknown_lit_str_value(value: &LitStr) -> Self {
Error::unknown_value(&value.value()).with_span(value)
}
}
/// Error instance methods
#[allow(clippy::len_without_is_empty)] // Error can never be empty
impl Error {
/// Check if this error is associated with a span in the token stream.
pub fn has_span(&self) -> bool {
self.span.is_some()
}
/// 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 with_span<T: Spanned>(mut self, node: &T) -> Self {
if !self.has_span() {
self.span = Some(node.span());
}
self
}
/// Get a span for the error.
///
/// # Return Value
/// This function will return [`Span::call_site()`](proc_macro2::Span) 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 span(&self) -> Span {
self.span.unwrap_or_else(Span::call_site)
}
/// Get the span for `self`, if one has been set.
pub fn explicit_span(&self) -> Option<Span> {
self.span
}
/// 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 flatten(self) -> Self {
Error::multiple(self.into_vec())
}
fn into_vec(self) -> Vec<Self> {
if let ErrorKind::Multiple(errors) = self.kind {
let locations = self.locations;
#[cfg(feature = "diagnostics")]
let children = self.children;
errors
.into_iter()
.flat_map(|error| {
// This is mutated if the diagnostics feature is enabled
#[allow(unused_mut)]
let mut error = error.prepend_at(locations.clone());
// Any child diagnostics in `self` are cloned down to all the distinct
// errors contained in `self`.
#[cfg(feature = "diagnostics")]
error.children.extend(children.iter().cloned());
error.into_vec()
})
.collect()
} else {
vec![self]
}
}
/// Adds a location to the error, such as a field or variant.
/// Locations must be added in reverse order of specificity.
pub fn at<T: fmt::Display>(mut self, location: T) -> Self {
self.locations.insert(0, location.to_string());
self
}
/// 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 at_path(self, path: &Path) -> Self {
self.at(path_to_string(path))
}
/// 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 len(&self) -> usize {
self.kind.len()
}
/// 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 add_sibling_alts_for_unknown_field<'a, T, I>(mut self, alternates: I) -> Self
where
T: AsRef<str> + 'a,
I: IntoIterator<Item = &'a T>,
{
// The error may have bubbled up before this method was called,
// and in those cases adding alternates would be incorrect.
if !self.locations.is_empty() {
return self;
}
if let ErrorKind::UnknownField(unknown_field) = &mut self.kind {
unknown_field.add_alts(alternates);
} else if let ErrorKind::Multiple(errors) = self.kind {
let alternates = alternates.into_iter().collect::<Vec<_>>();
self.kind = ErrorKind::Multiple(
errors
.into_iter()
.map(|err| {
err.add_sibling_alts_for_unknown_field(
// This clone seems like it shouldn't be necessary.
// Attempting to borrow alternates here leads to the following compiler error:
//
// error: reached the recursion limit while instantiating `darling::Error::add_sibling_alts_for_unknown_field::<'_, &&&&..., ...>`
alternates.clone(),
)
})
.collect(),
)
}
self
}
/// Adds a location chain to the head of the error's existing locations.
fn prepend_at(mut self, mut locations: Vec<String>) -> Self {
if !locations.is_empty() {
locations.extend(self.locations);
self.locations = locations;
}
self
}
/// Gets the location slice.
#[cfg(test)]
pub(crate) fn location(&self) -> Vec<&str> {
self.locations.iter().map(|i| i.as_str()).collect()
}
/// 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
/// ```rust,ignore
/// // in your proc-macro function
/// let opts = match MyOptions::from_derive_input(&ast) {
/// Ok(val) => val,
/// Err(err) => {
/// return err.write_errors();
/// }
/// }
/// ```
pub fn write_errors(self) -> TokenStream {
#[cfg(feature = "diagnostics")]
{
self.emit();
TokenStream::default()
}
#[cfg(not(feature = "diagnostics"))]
{
syn::Error::from(self).into_compile_error()
}
}
#[cfg(feature = "diagnostics")]
fn single_to_diagnostic(self) -> ::proc_macro::Diagnostic {
use proc_macro::{Diagnostic, Level};
// Delegate to dedicated error formatters when applicable.
//
// If span information is available, don't include the error property path
// since it's redundant and not consistent with native compiler diagnostics.
let diagnostic = match self.kind {
ErrorKind::UnknownField(euf) => euf.into_diagnostic(self.span),
_ => match self.span {
Some(span) => span.unwrap().error(self.kind.to_string()),
None => Diagnostic::new(Level::Error, self.to_string()),
},
};
self.children
.into_iter()
.fold(diagnostic, |out, child| child.append_to(out))
}
/// Transform this error and its children into a list of compiler diagnostics
/// and emit them. If the `Error` has associated span information, the diagnostics
/// will identify the correct location in source code automatically.
///
/// # Stability
/// This is only available on `nightly` until the compiler `proc_macro_diagnostic`
/// feature stabilizes. Until then, it may break at any time.
#[cfg(feature = "diagnostics")]
pub fn emit(self) {
for error in self.flatten() {
error.single_to_diagnostic().emit()
}
}
/// Transform the error into a compiler diagnostic and - if the diagnostic points to
/// a specific code location - add a spanned help child diagnostic that points to the
/// parent derived trait.
///
/// This is experimental and therefore not exposed outside the crate.
#[cfg(feature = "diagnostics")]
#[allow(dead_code)]
fn emit_with_macro_help_span(self) {
use proc_macro::Diagnostic;
for error in self.flatten() {
let needs_help = error.has_span();
let diagnostic = error.single_to_diagnostic();
Diagnostic::emit(if needs_help {
diagnostic.span_help(
Span::call_site().unwrap(),
"Encountered as part of this derive-mode-macro",
)
} else {
diagnostic
})
}
}
}
#[cfg(feature = "diagnostics")]
macro_rules! add_child {
($unspanned:ident, $spanned:ident, $level:ident) => {
#[doc = concat!("Add a child ", stringify!($unspanned), " message to this error.")]
#[doc = "# Example"]
#[doc = "```rust"]
#[doc = "# use darling_core::Error;"]
#[doc = concat!(r#"Error::custom("Example")."#, stringify!($unspanned), r#"("message content");"#)]
#[doc = "```"]
pub fn $unspanned<T: fmt::Display>(mut self, message: T) -> Self {
self.children.push(child::ChildDiagnostic::new(
child::Level::$level,
None,
message.to_string(),
));
self
}
#[doc = concat!("Add a child ", stringify!($unspanned), " message to this error with its own span.")]
#[doc = "# Example"]
#[doc = "```rust"]
#[doc = "# use darling_core::Error;"]
#[doc = "# let item_to_span = proc_macro2::Span::call_site();"]
#[doc = concat!(r#"Error::custom("Example")."#, stringify!($spanned), r#"(&item_to_span, "message content");"#)]
#[doc = "```"]
pub fn $spanned<S: Spanned, T: fmt::Display>(mut self, span: &S, message: T) -> Self {
self.children.push(child::ChildDiagnostic::new(
child::Level::$level,
Some(span.span()),
message.to_string(),
));
self
}
};
}
/// Add child diagnostics to the error.
///
/// # Example
///
/// ## Code
///
/// ```rust
/// # use darling_core::Error;
/// # let struct_ident = proc_macro2::Span::call_site();
/// Error::custom("this is a demo")
/// .with_span(&struct_ident)
/// .note("we wrote this")
/// .help("try doing this instead");
/// ```
/// ## Output
///
/// ```text
/// error: this is a demo
/// --> my_project/my_file.rs:3:5
/// |
/// 13 | FooBar { value: String },
/// | ^^^^^^
/// |
/// = note: we wrote this
/// = help: try doing this instead
/// ```
#[cfg(feature = "diagnostics")]
impl Error {
add_child!(error, span_error, Error);
add_child!(warning, span_warning, Warning);
add_child!(note, span_note, Note);
add_child!(help, span_help, Help);
}
impl StdError for Error {
fn description(&self) -> &str {
self.kind.description()
}
fn cause(&self) -> Option<&dyn StdError> {
None
}
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}", self.kind)?;
if !self.locations.is_empty() {
write!(f, " at {}", self.locations.join("/"))?;
}
Ok(())
}
}
impl From<syn::Error> for Error {
fn from(e: syn::Error) -> Self {
// This impl assumes there is nothing but the message and span that needs to be preserved
// from the passed-in error. If this changes at some point, a new ErrorKind should be made
// to hold the syn::Error, and this impl should preserve it unmodified while setting its own
// span to be a copy of the passed-in error.
Self {
span: Some(e.span()),
..Self::custom(e)
}
}
}
impl From<Error> for syn::Error {
fn from(e: Error) -> Self {
if e.len() == 1 {
if let Some(span) = e.explicit_span() {
// Don't include the location path if the error has an explicit span,
// since it will be redundant and isn't consistent with how rustc
// exposes errors.
syn::Error::new(span, e.kind)
} else {
// If the error's span is going to be the macro call site, include
// the location information to try and help the user pinpoint the issue.
syn::Error::new(e.span(), e)
}
} else {
let mut syn_errors = e.flatten().into_iter().map(syn::Error::from);
let mut error = syn_errors
.next()
.expect("darling::Error can never be empty");
for next_error in syn_errors {
error.combine(next_error);
}
error
}
}
}
// Don't want to publicly commit to Error supporting equality yet, but
// not having it makes testing very difficult. Note that spans are not
// considered for equality since that would break testing in most cases.
#[cfg(test)]
impl PartialEq for Error {
fn eq(&self, other: &Self) -> bool {
self.kind == other.kind && self.locations == other.locations
}
}
#[cfg(test)]
impl Eq for Error {}
impl IntoIterator for Error {
type Item = Error;
type IntoIter = IntoIter;
fn into_iter(self) -> IntoIter {
if let ErrorKind::Multiple(errors) = self.kind {
IntoIter {
inner: IntoIterEnum::Multiple(errors.into_iter()),
}
} else {
IntoIter {
inner: IntoIterEnum::Single(iter::once(self)),
}
}
}
}
enum IntoIterEnum {
Single(iter::Once<Error>),
Multiple(vec::IntoIter<Error>),
}
impl Iterator for IntoIterEnum {
type Item = Error;
fn next(&mut self) -> Option<Self::Item> {
match *self {
IntoIterEnum::Single(ref mut content) => content.next(),
IntoIterEnum::Multiple(ref mut content) => content.next(),
}
}
}
/// An iterator that moves out of an `Error`.
pub struct IntoIter {
inner: IntoIterEnum,
}
impl Iterator for IntoIter {
type Item = Error;
fn next(&mut self) -> Option<Error> {
self.inner.next()
}
}
/// Accumulator for errors, for helping call [`Error::multiple`].
///
/// See the docs for [`darling::Error`](Error) for more discussion of error handling with darling.
///
/// # Panics
///
/// `Accumulator` panics on drop unless [`finish`](Self::finish), [`finish_with`](Self::finish_with),
/// or [`into_inner`](Self::into_inner) has been called, **even if it contains no errors**.
/// If you want to discard an `Accumulator` that you know to be empty, use `accumulator.finish().unwrap()`.
///
/// # Example
///
/// ```
/// # extern crate darling_core as darling;
/// # struct Thing;
/// # struct Output;
/// # impl Thing { fn validate(self) -> darling::Result<Output> { Ok(Output) } }
/// fn validate_things(inputs: Vec<Thing>) -> darling::Result<Vec<Output>> {
/// let mut errors = darling::Error::accumulator();
///
/// let outputs = inputs
/// .into_iter()
/// .filter_map(|thing| errors.handle_in(|| thing.validate()))
/// .collect::<Vec<_>>();
///
/// errors.finish()?;
/// Ok(outputs)
/// }
/// ```
#[derive(Debug)]
#[must_use = "Accumulator will panic on drop if not defused."]
pub struct Accumulator(Option<Vec<Error>>);
impl Accumulator {
/// Runs a closure, returning the successful value as `Some`, or collecting the error
///
/// The closure's return type is `darling::Result`, so inside it one can use `?`.
pub fn handle_in<T, F: FnOnce() -> Result<T>>(&mut self, f: F) -> Option<T> {
self.handle(f())
}
/// Handles a possible error.
///
/// Returns a successful value as `Some`, or collects the error and returns `None`.
pub fn handle<T>(&mut self, result: Result<T>) -> Option<T> {
match result {
Ok(y) => Some(y),
Err(e) => {
self.push(e);
None
}
}
}
/// Stop accumulating errors, producing `Ok` if there are no errors or producing
/// an error with all those encountered by the accumulator.
pub fn finish(self) -> Result<()> {
self.finish_with(())
}
/// Bundles the collected errors if there were any, or returns the success value
///
/// Call this at the end of your input processing.
///
/// If there were no errors recorded, returns `Ok(success)`.
/// Otherwise calls [`Error::multiple`] and returns the result as an `Err`.
pub fn finish_with<T>(self, success: T) -> Result<T> {
let errors = self.into_inner();
if errors.is_empty() {
Ok(success)
} else {
Err(Error::multiple(errors))
}
}
fn errors(&mut self) -> &mut Vec<Error> {
match &mut self.0 {
Some(errors) => errors,
None => panic!("darling internal error: Accumulator accessed after defuse"),
}
}
/// Returns the accumulated errors as a `Vec`.
///
/// This function defuses the drop bomb.
#[must_use = "Accumulated errors should be handled or propagated to the caller"]
pub fn into_inner(mut self) -> Vec<Error> {
match self.0.take() {
Some(errors) => errors,
None => panic!("darling internal error: Accumulator accessed after defuse"),
}
}
/// Add one error to the collection.
pub fn push(&mut self, error: Error) {
self.errors().push(error)
}
/// Finish the current accumulation, and if there are no errors create a new `Self` so processing may continue.
///
/// This is shorthand for:
///
/// ```rust,ignore
/// errors.finish()?;
/// errors = Error::accumulator();
/// ```
///
/// # Drop Behavior
/// This function returns a new [`Accumulator`] in the success case.
/// This new accumulator is "armed" and will detonate if dropped without being finished.
///
/// # Example
///
/// ```
/// # extern crate darling_core as darling;
/// # struct Thing;
/// # struct Output;
/// # impl Thing { fn validate(&self) -> darling::Result<Output> { Ok(Output) } }
/// fn validate(lorem_inputs: &[Thing], ipsum_inputs: &[Thing])
/// -> darling::Result<(Vec<Output>, Vec<Output>)> {
/// let mut errors = darling::Error::accumulator();
///
/// let lorems = lorem_inputs.iter().filter_map(|l| {
/// errors.handle(l.validate())
/// }).collect();
///
/// errors = errors.checkpoint()?;
///
/// let ipsums = ipsum_inputs.iter().filter_map(|l| {
/// errors.handle(l.validate())
/// }).collect();
///
/// errors.finish_with((lorems, ipsums))
/// }
/// # validate(&[], &[]).unwrap();
/// ```
pub fn checkpoint(self) -> Result<Accumulator> {
// The doc comment says on success we "return the Accumulator for future use".
// Actually, we have consumed it by feeding it to finish so we make a fresh one.
// This is OK since by definition of the success path, it was empty on entry.
self.finish()?;
Ok(Self::default())
}
}
impl Default for Accumulator {
fn default() -> Self {
Accumulator(Some(vec![]))
}
}
impl Extend<Error> for Accumulator {
fn extend<I>(&mut self, iter: I)
where
I: IntoIterator<Item = Error>,
{
self.errors().extend(iter)
}
}
impl Drop for Accumulator {
fn drop(&mut self) {
// don't try to panic if we are currently unwinding a panic
// otherwise we end up with an unhelful "thread panicked while panicking. aborting." message
if !std::thread::panicking() {
if let Some(errors) = &mut self.0 {
match errors.len() {
0 => panic!("darling::error::Accumulator dropped without being finished"),
error_count => panic!("darling::error::Accumulator dropped without being finished. {} errors were lost.", error_count)
}
}
}
}
}
#[cfg(test)]
mod tests {
use super::Error;
#[test]
fn flatten_noop() {
let err = Error::duplicate_field("hello").at("world");
assert_eq!(err.clone().flatten(), err);
}
#[test]
fn flatten_simple() {
let err = Error::multiple(vec![
Error::unknown_field("hello").at("world"),
Error::missing_field("hell_no").at("world"),
])
.at("foo")
.flatten();
assert!(err.location().is_empty());
let mut err_iter = err.into_iter();
let first = err_iter.next();
assert!(first.is_some());
assert_eq!(first.unwrap().location(), vec!["foo", "world"]);
let second = err_iter.next();
assert!(second.is_some());
assert_eq!(second.unwrap().location(), vec!["foo", "world"]);
assert!(err_iter.next().is_none());
}
#[test]
fn len_single() {
let err = Error::duplicate_field("hello");
assert_eq!(1, err.len());
}
#[test]
fn len_multiple() {
let err = Error::multiple(vec![
Error::duplicate_field("hello"),
Error::missing_field("hell_no"),
]);
assert_eq!(2, err.len());
}
#[test]
fn len_nested() {
let err = Error::multiple(vec![
Error::duplicate_field("hello"),
Error::multiple(vec![
Error::duplicate_field("hi"),
Error::missing_field("bye"),
Error::multiple(vec![Error::duplicate_field("whatsup")]),
]),
]);
assert_eq!(4, err.len());
}
#[test]
fn accum_ok() {
let errs = Error::accumulator();
assert_eq!("test", errs.finish_with("test").unwrap());
}
#[test]
fn accum_errr() {
let mut errs = Error::accumulator();
errs.push(Error::custom("foo!"));
errs.finish().unwrap_err();
}
#[test]
fn accum_into_inner() {
let mut errs = Error::accumulator();
errs.push(Error::custom("foo!"));
let errs: Vec<_> = errs.into_inner();
assert_eq!(errs.len(), 1);
}
#[test]
#[should_panic(expected = "Accumulator dropped")]
fn accum_drop_panic() {
let _errs = Error::accumulator();
}
#[test]
#[should_panic(expected = "2 errors")]
fn accum_drop_panic_with_error_count() {
let mut errors = Error::accumulator();
errors.push(Error::custom("first"));
errors.push(Error::custom("second"));
}
#[test]
fn accum_checkpoint_error() {
let mut errs = Error::accumulator();
errs.push(Error::custom("foo!"));
errs.checkpoint().unwrap_err();
}
#[test]
#[should_panic(expected = "Accumulator dropped")]
fn accum_checkpoint_drop_panic() {
let mut errs = Error::accumulator();
errs = errs.checkpoint().unwrap();
let _ = errs;
}
}