Add a prelude module

[nik-rev]

This adds a prelude module with:

• bail!
• ensure!
• report! (rename pending from eyre! in Rename the eyre! macro to report! #271)
• OptionExt
• ResultExt
• Report
• Result

Allowing users to write:

use eyre::prelude::*;

Notably this should not include Result, as taking over the bare Result identifier without explicitly importing it would be surprising.

I think that eyre::Result should be in the prelude because it is just so very, very common to import it. There are 17,200 instances of use eyre::Result compared to 1,100 instances of use eyre::bail.

Essentially the value of having eyre::Result in the prelude is greater than all the other eyre items combined.

Yes, it's true that we are shadowing the implicit Result type defined in the standard library's prelude. However, we are shadowing it with a type alias, where the type alias still refers to the same standard library's Result type, just with a few generics specified to have default values.

Closes #63

[LeoniePhiline]

I agree that if there is a prelude, then Result must be in it.

The default <_, E = Report> does not cause any friction in the rare cases of returning other kinds of errors.

The friction of needing to import Result despite using the prelude would be a recurring UX hurdle.

[deckstose]

What about extending this to color-eyre as well? This would make using eyre types with color-eyre as the main dependency a bit smoother and I don't see any downsides.

[nik-rev]

What about extending this to color-eyre as well? This would make using eyre types with color-eyre as the main dependency a bit smoother and I don't see any downsides.

Which types from color-eyre would you like to see in the prelude?

In my opinion, color-eyre doesn't need a prelude, because you only really use the types in the main.rs file to install the hook. On the other hands, it's not uncommon to import the same 6 items from eyre in dozens, even hundreds of files.

[deckstose]

On the other hands, it's not uncommon to import the same 6 items from eyre in dozens, even hundreds of files.

Exactly. If I'm using color-eyre I'm definitely using eyre as well, and it's a bit annoying that I need to import the most important things from color_eyre::eyre::. I'd go for mirroring the API from eyre in color-eyre. A bit off-topic here, maybe I need to create a separate issue for that.

[nik-rev]

and it's a bit annoying that I need to import the most important things from color_eyre::eyre::

Are you saying that you feel like this path is too long:

use color_eyre::eyre::prelude::*;

You can add the eyre crate as a dependency, then you don't have to use the re-export:

use eyre::prelude::*;

Considering that color_eyre has just a pub use eyre, if there is a eyre::prelude, then that automatically means there will be a color_eyre::eyre::prelude

[LeoniePhiline]

As a heavy user of color_eyre, I fully agree with @deckstose in that color_eyre::prelude::* should contain a full re-export of eyre::prelude::*.

color-eyre already re-exports Result and Report but not other eyre types, traits or macros – the inconsistency is jarring:

Using rust-analyzer‘s auto-imports, you usually end up with something like use color_eyre::{eyre::{bail, eyre, OptionExt, WrapErr}, Report, Result, Section, SectionExt};.
This two-tiered separation of imports does not seem useful at all, nor intuitive, especially with the re-exports which only go half way.

I believe that making users write use color_eyre::eyre::… is a leaky abstraction and a UX bug.

You can add the eyre crate as a dependency, then you don't have to use the re-export

That’s merely a hack, and it quickly introduces issues with mismatched versions.
This is also the reason why many crates forward feature flags to their dependencies, avoiding the need for the user to declare these transitive dependencies as direct dependencies, just to configure feature flags.

color-eyre ultimately is a wrapper of eyre, and it should not cause any need to be hoisted to a root dependency.

Facing a 1.0 release, it might even be most useful to consider merging the two. color-eyre may have started as a color-enabled reports renderer, but the span trace integration ends up being one of its core features for practical use. Colors, backtrace and spantrace support could just as well be crate features of eyre 1.0, cleaning up lots of confusion regarding the web of crates and their responsibilities.

[yaahc]

That’s merely a hack, and it quickly introduces issues with mismatched versions.

To back this up, this issue is the reason eyre is re-exported from color-eyre in the first place, to provide an unambiguous path for the appropriate version of eyre that is compatible with color-eyre.

And just to confirm that I'm understanding what you're saying correctly @LeoniePhiline by:

I believe that making users write use color_eyre::eyre::… is a leaky abstraction and a UX bug.

You mean that accessing eyre paths should be done via the prelude instead? Would this imply removing the re-export of eyre? If so, what would be the expected method for users to access an eyre API that isn't exposed via the prelude?

[deckstose]

@LeoniePhiline I couldn't have phrased it better, thanks :) I agree with everything you said.

You mean that accessing eyre paths should be done via the prelude instead? Would this imply removing the re-export of eyre? If so, what would be the expected method for users to access an eyre API that isn't exposed via the prelude?

Ideally, you would interact with color-eyre as if it was eyre. The API should be the same + what color-eyre provides on top.

Should I open a new issue for making eyre's and color-eyre's API the same? I commented here since I thought a prelude is basically 90% of that.

[LeoniePhiline]

To back this up, this issue is the reason eyre is re-exported from color-eyre in the first place, to provide an unambiguous path for the appropriate version of eyre that is compatible with color-eyre.

I noticed that both color-eyre and color-spantrace use tracing-error, which is also required by the user to set up the subscriber – but the dependency is not re-exported.

1. Only color-spantrace should depend on tracing-error, and re-export it for color-eyre.

2. color-eyre should again re-export it for users to set up tracing-subscriber with tracing_error::ErrorLayer.

[pksunkara]

To back this up, this issue is the reason eyre is re-exported from color-eyre in the first place, to provide an unambiguous path for the appropriate version of eyre that is compatible with color-eyre.

I noticed that both color-eyre and color-spantrace use tracing-error, which is also required by the user to set up the subscriber – but the dependency is not re-exported.

1. Only color-spantrace should depend on tracing-error, and re-export it for color-eyre.

2. color-eyre should again re-export it for users to set up tracing-subscriber with tracing_error::ErrorLayer.

Please feel free create a PR for this specific change.