snafu

Fixed

• The whatever macro no longer triggers the semicolon_in_expressions_from_macros lint.

Fixed

• Error types that use Self in fields or trait bounds are now supported.

Added

• WhateverLocal is an alternate to Whatever that does not implement or require Send or Sync.

• Errors that do not use context selectors (e.g. opaque errors, #[snafu(context(false))] errors, or #[snafu(transparent)] errors) may now be constructed using a generic value when they are annotated with the #[snafu(source(from(generic)))] attribute.

• When using the unstable-provider-api feature flag, Report will check if each error provides a Location. When it does, the Location will be appended to the error message.

Fixed

• Opaque errors which use const generics with default values are now supported.

Changed

• Rust 1.65 is now the minimum supported Rust version. This is a breaking change.

• Rust 1.81 is now the default supported Rust version. This is a breaking change.

• Whatever implements Send and Sync, allowing it to be sent between threads. This requires that wrapped errors also implement Send and Sync. This is a breaking change.

• snafu::Location has been replaced with a type alias to the standard library's Location (specifically a reference to that type: &'static core::panic::Location<'static>). This improves interoperability and access to features. This is a breaking change.

• Opaque errors default to allowing construction from any value that implements Into for the wrapped type. The previous behavior can be restored with #[snafu(source(from(exact)))]. This is a breaking change.

• The internal implementation of #[snafu] attribute parsing has been rewritten. This should largely be unnoticeable, but some error messages and spans have been improved, and memory usage may be slightly reduced.

Removed

• The deprecated Error::description and Error::cause methods are no longer generated.

• The rust_1_61, rust_1_65, and unstable-core-error feature flags have been removed.

• When using the unstable-provider-api feature flag, the source error is no longer provided by default. This impacts regular and opaque errors, as well as Whatever and WhateverLocal.

• When using the unstable-provider-api feature flag, provided values may no longer be chained or have chaining priority assigned.

Fixed

• Allow the unstable-provider-api feature to be used in a no_std environment, both with and without the alloc feature flag enabled.

Fixed

• Gate TryFuture::whatever_context, TryFuture::with_whatever_context, TryStream::whatever_context, and TryStream::with_whatever_context behind the alloc feature flag. This allows SNAFU's future and stream combinators to be used in a no_std environment.

• Only implement GenerateImplicitData and AsBacktrace for Arc wrappers when the target platform has access to atomics and Arc.

Added

• GenerateImplicitData and AsBacktrace are now implemented for Box<T>, Rc<T>, and Arc<T> when T implements the same trait. This allows you to use types like Arc<Backtrace> as a backtrace field.

Added

• A new alloc feature flag has been added as a subset of the existing std feature flag. This allows SNAFU to be used in environments that have access to an allocator but not the standard library.

• Context selectors may now be explicitly named. This allows flexibility in edge cases, but also is understood by rust-analyzer to help with renaming context selectors.

Fixed

• Added #[allow(dead_code)] to the context selector's fail method. This works around an issue with the dead_code lint in rare usages involving declarative macros and explicit visibility qualifiers.

Changed

• Add top-level documentation on reporting errors using #[snafu::report].

• Show the cfg options that control features on docs.rs.

Added

• Implement the core::error::Error trait instead of std::error::Error when the rust_1_81 feature flag is enabled. This supersedes the unstable-core-error feature flag.

Fixed

• Use the fully-qualified path to Location in the location!() macro.

Changed

• Report now prints an "Error: " prefix when returned directly from main or tests.

• Support heck version 0.5 in addition to 0.4.

Fixed

• Adding a custom Whatever variant to a generic error enum is now supported.

• The #[report] macro works better on functions that require more complicated type inference for their return types.

Added

• Error types that use constant generics are now supported.

Added

• snafu(transparent) allows creating compound error types that act as if they were not present, delegating thier Display and Error implementations to the source error. This is useful when aggregating smaller errors that already completely explain the failure.

• ResultExt::boxed and ResultExt::boxed_local are available to convert an error value into an owned trait object. This is useful when an error type is a generic controlled by the caller.

Changed

• Rust 1.56 is now the minimum supported Rust version. This is a breaking change.

• Rust 1.65 is now the default supported Rust version. This is a breaking change.

• The item type of the ChainCompat iterator is now &'a (dyn Error + 'b) to allow downcasting the error trait object to a concrete type. This is a breaking change.

• Error fields marked location are no longer automatically implicitly created. This is a breaking change.

• Adding #[snafu] attributes to the field of a tuple struct are now errors. This is a breaking change.

• The SNAFU copy of the Error trait now marks the description and cause methods as deprecated, following the standard library's example. This trait is only active when using SNAFU in a no_std environment and no functional difference is intended.

Removed

• The default Display implementation no longer includes the error text of the source error. This is a breaking change.

• The backtraces and unstable-backtraces-impl-std feature flags have been removed. This is a breaking change. The Backtrace type is now the standard library's Backtrace type when it is available.

Added

• The CleanedErrorText iterator can be used to remove redundant parts from the messages that many errors duplicate from their underlying sources. This is the same behavior as Report, but can be used in contexts other than console output, such as when reporting an error in structured output like HTML or JSON.

Fixed

• The documentation for the compatability feature flags now mentions rust_1_39 and shows the correct default state of rust_1_61.

Changed

• Report and the #[report] macro now remove redundant parts from the messages that many errors duplicate from their underlying sources.

Fixed

• The macro no longer generates invalid code when implicitly-generated types (such as backtraces) were used in conjunction with #[snafu(source(from))] and the type before transformation does not implement std::error::Error.

Added

• Report can be returned from main or test functions to provide a user-friendly display of errors.

• A cheat sheet for the most common #[snafu(...)] attribute usages has been added to the Snafu macro's documentation.

• Optional support for using the standard library's std::backtrace::Backtrace type via the backtraces-impl-std feature flag.

• Optional support for implementing the Provider API using the std::error::Error::provide method via the unstable-provider-api feature flag.

• Optional support for implementing the core::error::Error trait instead of std::error::Error via the unstable-core-error feature flag.

• GenerateImplicitData has a new method generate_with_source.

Changed

• ErrorCompat::iter_chain and ChainCompat are now available in no_std environments.

• ChainCompat now implements Clone.

• The Debug implementation for Location no longer shows some irrelevant internal details.

Added

• The macro ensure_whatever provides the functionality of the ensure macro for stringly-typed errors.

Changed

• No longer require the futures feature flag to support the shim implementations of standard library errors that have existed since Rust 1.34.

• Documentation improved to demonstrate that custom Whatever errors can optionally be made Send and Sync.

Many breaking changes in this release can be automatically addressed with the snafu-upgrade-assistant.

Added

• A crate prelude containing common macros and traits can be imported via use snafu::prelude::*.

• A ready-to-use error type Whatever is available to quickly start reporting errors with little hassle.

• "Stringly typed" error cases can be added to existing error types, allowing you to construct errors without defining them first.

• Formatting shorthand syntax for error type data fields is now supported: #[snafu(display("Hello {name}"))].

• #[snafu(module)] can be specified on an error type. This will create a module for the error type and all associated context selectors will be placed in that module.

• snafu::Location can be added to an error type to provide lightweight tracking of the source location where the error was created.

• #[snafu(implicit)] can be specified on context selector data fields to automatically generate it via snafu::GenerateImplicitData when the error is created.

• ErrorCompat::iter_chain provides an iterator over the list of causal errors.

Changed

• Generated context selectors now have the suffix Snafu. This is a breaking change.

• ResultExt::with_context, TryFutureExt::with_context, and TryStreamExt::with_context now pass the error into the closure. This is a breaking change.

• The GenerateBacktrace trait has been split into GenerateImplicitData and AsBacktrace. This is a breaking change.

• Rust 1.34 is now the minimum supported Rust version. This is a breaking change.

Removed

• String attribute parsing (#[snafu(foo = "...")]) is no longer supported. This is a breaking change.

• The deprecated eager_context and with_eager_context methods have been removed. This is a breaking change.

Fixed

• ensure! now uses a fully-qualified path to avoid a name clash when the path core is ambiguous.

Added

• #[derive(Snafu)] is now supported on unit structs and structs with fields.
• ensure! now supports trailing commas.

Fixed

• The error text for a misuse of #[snafu(context)] was corrected.
• More usages of Option in the generated code are now fully qualified.

Fixed

• The code generated by the Snafu macro no longer conflicts with a local module called core or snafu.

Added

• Demonstration error types are now present in the guide.
• The user's guide is now an optional feature flag. To preserve compatibility, it is enabled by default, but most users can disable it.
• It is now possible to import the snafu crate under a different name using #[snafu(crate_root)].

Added

• Context selectors without an underlying cause now have a build method in addition to the existing fail method. build creates the error but does not wrap it in a Result.

• This version was a failed publish; please use 0.6.6 instead.

• This version was a failed publish; please use 0.6.6 instead.

Fixed

• License files are now included with the snafu-derive package.

Added

• Automatically-generated code no longer triggers the single_use_lifetimes lint.

Added

• It is now possible to create errors that have no context using #[snafu(context(false))]. This allows using the question mark operator without calling .context(...).

Fixed

• Reduced the possibility for a name collision when implementing Display when a formatted value was called f.

Added

• Optional support for using the unstable std::backtrace::Backtrace type and implementing std::error::Error::backtrace via the unstable-backtraces-impl-std feature flag.
• Error variants can now use Option<Backtrace> for the backtrace field. Backtrace will always have the backtrace collected, while Option<Backtrace> requires that an environment variable be set.
• Basic support for no-std environments.
• The ensure! macro now allows creating opaque errors.
• Context selectors have basic documentation generated. This allows using #[deny(missing_docs)].

Changed

• Rust 1.31 is now the minimum supported Rust version. This is a breaking change.
• The Backtrace type is now always available, but does nothing by default. It is recommended that the end application enables backtrace functionality. This is a breaking change.
• Support for std::future::Future has been stabilized, which means the feature flag has been renamed from unstable-futures to futures. This is a breaking change.
• The backtrace-crate feature flag has been renamed to backtraces-impl-backtrace-crate. Enabling this flag now replaces snafu::Backtrace with backtrace::Backtrace. The AsRef implementation has been removed. This is a breaking change.
• A new trait for constructing backtraces is used instead of Default so the Backtrace type no longer implements Default or has any inherent methods. This is a breaking change.

Added

• Compiler errors are generated when SNAFU attributes are used in incorrect locations. This is a breaking change.
• Compiler errors are generated when SNAFU attributes are duplicated. This is a breaking change.

Changed

• #[snafu(source(from)) implies #[snafu(source)] (which implies #[snafu(source(true))]); #[snafu(source)] and #[snafu(source(true))] can be removed in these cases.

Fixed

• Multiple attributes can be specified inside of a single #[snafu(...)].

Removed

• #[snafu(backtrace(delegate))] on source fields is replaced by #[snafu(backtrace)]. This is a breaking change.

Fixed

• Ignore #[doc] attributes that do not correspond to documentation comments. This allows #[doc(hidden)] to be used again.

Changed

• Implement Future and Stream instead of TryFuture and TryStream for the combinators for the standard library's futures. This allows the Context future combinator to be directly used with .await and for the Context stream combinator to be used without calling .into_stream.

Added

• Add optional conversion of &snafu::Backtrace into &backtrace::Backtrace.

Fixed

• Support default generic parameters on error types.

Added

• Documentation comment summaries are used as the default Display text.

Fixed

• Quieted warnings from usages of bare trait objects.
• The From trait is fully-qualified to avoid name clashes.

Changed

• More errors are reported per compilation attempt.

Fixed

• A feature flag name was rejected by crates.io and needed to be updated; this release has no substantial changes beyond 0.4.0.

Fixed

• Underlying error causes of Box<dyn std::error::Error + Send + Sync> are now supported.

Deprecated

• Borrow is no longer required to be implemented for underlying error causes. In the next release containing breaking changes, the automatic implementation of Borrow<dyn std::error::Error> for SNAFU types will be removed.

Added

• Borrow<std::error::Error> is now automatically implemented for SNAFU types. This is a breaking change as it may conflict with an existing user implementation of the same trait. It is expected that the number of affected users is very small.

• #[snafu(source)] can be used to identify the field that corresponds to the underlying error if it is not called source. It can also be used to disable automatically using a field called source for the underlying error.

• #[snafu(backtrace)] can be used to identify the field that corresponds to the backtrace if it is not called backtrace. It can also be used to disable automatically using a field called backtrace for the backtrace.

• #[snafu(source(from(...type..., ...expression...)))] can be used to perform transformations on the underlying error before it is stored. This allows boxing of large errors to avoid bloated return types or recursive errors.

• The user guide has a basic comparison to Failure and migration paths for common Failure patterns.

Changed

• The default Display implementation includes the underlying error message.

Fixed

• User-provided where clauses on error types are now copied to SNAFU-created impl blocks.
• User-provided inline trait bounds (<T: SomeTrait>) are no longer included in SNAFU-generated type names.

Fixed

• Error enums with variants named Some or None no longer cause name conflicts in the generated code.

Added

• Deriving Snafu on a newtype struct now creates an opaque error type, suitable for conservative public APIs.

Removed

• snafu::display and snafu_display have been replaced with snafu(display)
• snafu_visibility has been replaced with snafu(visibility)

Added

• Backtraces can now be delegated to an underlying error via #[snafu(backtrace(delegate))].

Added

• Error enums with generic lifetimes and types are now supported.

Changed

• The trait bounds applied to the fail method have been moved from the implementation block to the function itself.

Fixed

• Visibility is now applied to context selector fields.

Added

• #[snafu_visibility] can be used to configure the visibility of context selectors.

Added

• The OptionExt extension trait is now available for converting Options into Results while adding context.

Changed

• Errors from the macro are more detailed and point to reasonable sections of code.

Added

• The ensure macro is now available.

Added

• Ability to automatically capture backtraces.

Changed

• Version requirements for dependencies loosened to allow compiling with more crate versions.

Added

• Support for Rust 1.18

Added

• Context selectors without an underlying source now have a fail method.

• ResultExt now has the eager_context and with_eager_context methods to eagerly convert a source Result into a final Result type, skipping the intermediate Result<_, Context<_>> type.

Initial version