xref: /aosp_15_r20/external/rust/android-crates-io/crates/darling_core/src/error/mod.rs

//! 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;
    }
}