Module upgrading 

Available on crate feature guide only.

Upgrading from previous releases

• Version 0.8 → 0.9
• Version 0.7 → 0.8
• Version 0.6 → 0.7
• Version 0.5 → 0.6
• Version 0.4 → 0.5
• Version 0.3 → 0.4
• Version 0.2 → 0.3
• Version 0.1 → 0.2

Version 0.8 → 0.9

Whatever vs WhateverLocal

Previously, Whatever did not implement the Send or Sync traits, which caused some friction when using it in multithreaded environments, including in many popular asynchronous executors.

Whatever now implements Send and Sync, which in turn requires that any wrapped errors also implement those traits. If you were relying on the absence of those traits, the sibling type WhateverLocal has been introduced and can be used as a drop-in replacement.

snafu::Location

Previously, Location was a type defined by SNAFU. With this release, Location becomes a type alias to a reference to core::panic::Location.

If you were accessing a field of Location such as line or column, you will need to call the method of the same name instead.

If you were constructing a Location via Location::new with the current source location, consider using the location! macro or core::panic::Location::caller. Even better, mark the field as implicit and let SNAFU automatically capture the location data for you.

If you were constructing a Location with something other than the current source location, there is no direct replacement; if you still need that capability, you will need to create your own type.

Opaque errors may be built from generic types by default

Opaque errors now implement From for any type that can be converted into the wrapped error type. For example:

#[derive(Debug, Snafu)]
struct SomeOpaqueError(InnerError);

// The `Snafu` macro generates code equivalent to this:
impl From<E> for SomeOpaqueError
where
    E: Into<InnerError>,

This blanket From implementation will conflict with any existing implementation of From on the opaque error type. In some cases, the existing From implementation can be replaced with the generated implementation, but in other cases you may need to disable the transformation using #[snafu(source(from(exact)))].

Building errors from generic types

If you used source transformation for an error type with the non-idiomatic name exact or generic, that will now be treated as a keyword for the macro. You’ll need to refer to it using the raw identifier syntax as r#exact or r#generic.

The Provider API

Previously, the source error was provided by default. If you were relying on this, you can add an explicit #[snafu(provide)] to the source error field, but it is more idiomatic to use Error::source combined with downcasting instead.

Previously, errors could “chain” provided values from a wrapped error. Instead, walk the sources of the iterator yourself and check for the value you need. This aligns with how you would iterate through the sources to get the error to display and allows the caller to decide if the shallowest or deepest provided value should take precedence.

Version 0.7 → 0.8

Fields named location are no longer automatically implicitly generated

Previously, fields named location would be implicitly generated. However, this proved to be confusing and usually not what users wanted. If you have #[snafu(implicit(false))] on a field named location, that can be removed. If you are using this functionality, you will need to add #[snafu(implicit)] on those fields.

Before

#[derive(Debug, Snafu)]
struct ErrorWithGeneratedLocation {
    location: snafu::Location,
}

#[derive(Debug, Snafu)]
struct ErrorWithNonGeneratedLocation {
    #[snafu(implicit(false))]
    location: usize,
}

After

#[derive(Debug, Snafu)]
struct ErrorWithGeneratedLocation {
    #[snafu(implicit)]
    location: snafu::Location,
}

#[derive(Debug, Snafu)]
struct ErrorWithNonGeneratedLocation {
    location: usize,
}

The default implementation of Display no longer includes the source

To better follow the Error Handling Project Group’s suggested guideline, the generated implementation of Display no longer includes the underlying source’s Display. High quality error types already define their own Display format strings via snafu(display(...)), so this should not impact many users.

To combine all Display messages in the entire error chain, you can use higher-level tools like report or Report or lower-level tools like CleanedErrorText.

If you wish to ignore the suggested guideline, you will need to add a Display implementation that explicitly includes the source text.

Before

#[derive(Debug, Snafu)]
struct ErrorWithDefaultDisplay {
    source: std::io::Error,
}

After

#[derive(Debug, Snafu)]
#[snafu(display("ErrorWithDefaultDisplay: {source}"))]
struct ErrorWithDefaultDisplay {
    source: std::io::Error,
}

Minimum supported version of Rust is now 1.56

If you are writing a library, you will need to increase your minimum supported version of Rust to 1.56 or better. If you are writing an application, you should be able to upgrade your installed compiler by the same mechanism that you installed it.

Version 0.6 → 0.7

Upgrading should be a tedious but straightforward process. To assist upgrading your code, you can use the snafu-upgrade-assistant, which attempts to automatically update breaking changes.

Context selector names have changed

Previously, context selector names for enum errors exactly matched their corresponding enum variant names. This caused a large amount of confusion for people new to SNAFU. It was also inconsistent with context selector names for struct errors.

Now, context selectors for both enum and struct errors use the Snafu suffix. Any existing Error suffix is removed before Snafu is added.

Before

#[derive(Debug, Snafu)]
struct StructError;

#[derive(Debug, Snafu)]
enum EnumError {
    VariantError,
}

ensure!(false, StructContext);
ensure!(false, VariantError);

After

#[derive(Debug, Snafu)]
struct StructError;

#[derive(Debug, Snafu)]
enum EnumError {
    VariantError,
}

ensure!(false, StructSnafu);
ensure!(false, VariantSnafu);

with_context takes an argument

ResultExt::with_context, TryFutureExt::with_context, and TryStreamExt::with_context now pass the error into the closure.

Before

some_result.with_context(|| ContextSelector);

After

some_result.with_context(|_| ContextSelector);

String attribute parsing is no longer supported

Previously, SNAFU allowed an alternate attribute specification format to support versions of Rust before 1.34. Since the minimum version has been increased, this format is no longer required. Use the parenthesized format instead:

Before

#[snafu(display = r#"("a format string with arguments: {}", info)"#)]

After

#[snafu(display("a format string with arguments: {}", info))]

Minimum supported version of Rust is now 1.34

If you are writing a library, you will need to increase your minimum supported version of Rust to 1.34 or better. If you are writing an application, you should be able to upgrade your installed compiler by the same mechanism that you installed it.

Version 0.5 → 0.6

Minimum supported version of Rust is now 1.31

If you are writing a library, you will need to increase your minimum supported version of Rust to 1.31 or better. If you are writing an application, you should be able to upgrade your installed compiler by the same mechanism that you installed it.

Backtraces

The Backtrace type is now always available, so it is encouraged to make liberal use of it in your errors. If you are writing an application that displays backtraces, make sure to enable the backtrace feature flag so that backtraces are populated when they are created.

Implementations of Backtrace::default and Backtrace::new have been removed and replaced with GenerateBacktrace::generate.

The backtrace-crate feature flag has been renamed to backtraces-impl-backtrace-crate. The backtrace returned by ErrorCompat::backtrace is now the backtrace::Backtrace type when this flag is enabled, so the implementation of AsRef has been removed.

Futures

Support for the standard library features has been stabilized, so the feature flag has been renamed from unstable-futures to futures.

Version 0.4 → 0.5

backtrace(delegate) replaced with backtrace

Previously, if you wanted to delegate backtrace creation to another error, you would specify #[snafu(backtrace(delegate))] on the source field that references the other error.

Now, you specify the simpler #[snafu(backtrace)]. Since source fields must be error types, and backtrace fields must be Backtrace types, this is unambiguous and simplifies the API.

Before

#[derive(Debug, Snafu)]
enum Error {
    MyVariant {
        #[snafu(backtrace(delegate))]
        source: OtherError,
    },
}

After

#[derive(Debug, Snafu)]
enum Error {
    MyVariant {
        #[snafu(backtrace)]
        source: OtherError,
    },
}

source(from) implies source

Previously, if you had wanted to treat a field that wasn’t named “source” as a source field, and you wanted to transform the field from another type, you had to specify both #[snafu(source)] and #[snafu(source(from(...)))].

Now, #[snafu(source(from(...)))] implies #[snafu(source)] – it automatically treats the field as a source field regardless of its name, so you can remove the #[snafu(source)] attribute.

Before

#[derive(Debug, Snafu)]
enum Error {
    CauseIsAnError {
        #[snafu(source)]
        #[snafu(source(from(Error, Box::new)))]
        cause: Box<Error>,
    },
}

After

#[derive(Debug, Snafu)]
enum Error {
    CauseIsAnError {
        #[snafu(source(from(Error, Box::new)))]
        cause: Box<Error>,
    },
}

New errors for attribute misuse and duplication

Previously, SNAFU would ignore #[snafu(...)] attributes that were used in invalid locations. If attributes were duplicated, either the first or last would apply (depending on the attribute) and the rest would be ignored.

One example is specifying #[snafu(source(from(...)))] on an enum variant instead of the source field in that variant:

#[derive(Debug, Snafu)]
enum Error {
    // This used to be ignored, and will now cause an error:
    #[snafu(source(from(Error, Box::new)))]
    MyVariant {
        source: Box<Error>,
    },
}

Now, compiler errors will be emitted that point to any misused or duplicated attributes.

Version 0.3 → 0.4

Context vs. IntoError

The Context type and related From implementations have been removed in favor of the IntoError trait. If you were making use of this for custom conversions, you will need to update your trait bounds:

Before

fn example<C, E>(context: C) -> MyType<E>
where
    snafu::Context<SomeError, C>: Into<E>;

After

fn example<C, E>(context: C) -> MyType<E>
where
    C: snafu::IntoError<E, Source = SomeError>,
    E: std::error::Error + snafu::ErrorCompat;

Borrow<std::error::Error>

SNAFU no longer generates Borrow<std::error::Error> implementations for SNAFU error types (sorry for the whiplash if you were affected by this when upgrading to 0.3).

Version 0.2 → 0.3

Minimal changes should be required: if you previously implemented Borrow<std::error::Error> for a SNAFU error type, you should remove that implementation and allow SNAFU to implement it for you.

Version 0.1 → 0.2

Support for the snafu::display attribute was removed as this type of attribute was never intended to be supported. Since this required a SemVer-incompatible version, the attribute format has also been updated and normalized.

1. Attributes have been renamed

   • snafu_display and snafu::display became snafu(display).
   • snafu_visibility became snafu(visibility)
   • snafu_backtrace became snafu(backtrace)

2. Support for snafu_display with individually-quoted format arguments was removed. Migrate to either the “clean” or “all one string” styles, depending on what version of Rust you are targeting.

Before

#[derive(Debug, Snafu)]
enum DisplayUpdate {
    #[snafu::display("Format and {}", argument)]
    CleanStyle { argument: i32 },

    #[snafu_display("Format and {}", "argument")]
    QuotedArgumentStyle { argument: i32 },

    #[snafu_display = r#"("Format and {}", argument)"#]
    AllOneStringStyle { argument: i32 },
}

#[derive(Debug, Snafu)]
enum VisibilityUpdate {
    #[snafu_visibility(pub(crate))]
    CleanStyle,

    #[snafu_visibility = "pub(crate)"]
    AllOneStringStyle,
}

After

#[derive(Debug, Snafu)]
enum DisplayUpdate {
    #[snafu(display("Format and {}", argument))]
    CleanStyle { argument: i32 },

    #[snafu(display = r#"("Format and {}", argument)"#)]
    QuotedArgumentStyle { argument: i32 },

    #[snafu(display = r#"("Format and {}", argument)"#)]
    AllOneStringStyle { argument: i32 },
}

#[derive(Debug, Snafu)]
enum VisibilityUpdate {
    #[snafu(visibility(pub(crate)))]
    CleanStyle,

    #[snafu(visibility = "pub(crate)")]
    AllOneStringStyle,
}