Rename the eyre! macro to report!

[nik-rev]

Considering eyre plans to release 1.0 some time soon (#269), it's a good time to clean up the API - to make the API leaner, help prevent choice overload, and make the macro names make more sense..

Having 2 macros that do the same thing leads to unnecessary churn in which name to use. That's why we should remove the format_err! macro.

On the other hand, eyre! macro is not a good name - a better name is report!, because a Report is created.

Renaming ok_or_eyre to ok_or_report (#272) will mean we are consistent with the naming of ok_or_report method, and have more of a parallel between static error creation in the None case of an option, and dynamic error creation:

opt.ok_or_report("failed reading file")

opt.ok_or_else(|| report!("failed reading file: {path}"))

[pksunkara]

I actually like the usage Err(eyre!("cmd exited with non-zero status code")) where as report in that doesn't seem intuitive

[pksunkara]

Please make a separate PR to remove the format_err macro.

[nik-rev]

Please make a separate PR to remove the format_err macro.

#274

[nik-rev]

I actually like the usage Err(eyre!("cmd exited with non-zero status code")) where as report in that doesn't seem intuitive

Because this macro expands to the Report type, I'd say calling it report! makes the most sense. eyre! doesn't have any meaning to it, it's the name of the crate

[pksunkara]

FWIW, It follows the pattern of anyhow! macro too from anyhow crate.

[nik-rev]

FWIW, It follows the pattern of anyhow! macro too from anyhow crate.

What I like about bail! and ensure! is that these macros have generic names. These 2 macros are both in anyhow and eyre. But eyre developers needed to choose a different name for the anyhow! macro because, well, the crate is not anyhow

But if anyhow called the error-creating macro report! from the get-go, no such renaming would need to happen - because the name of the macro is not bound directly to the name of the crate. There's really nothing eyre-specific about the report! macro. It is a concept that can exist in different crates, whilst using the same name. Just like bail! and ensure!

If a type-erased error type such as Report makes itself into the standard library someday, or there is some sort of a successor crate to eyre like eyre is to anyhow, then having a more generic name for the macro will allow the standard library/future successor to re-use the name, just like people migrating from anyhow to eyre can re-use the macros bail! and ensure! without additional migration effort from users.

[LeoniePhiline]

While I like eyre!, the reasoning makes sense to me.

Maybe 1.0 is a good time to let go of fun whimsy of the early days in favor of an obvious, self explanatory API.

One counterpoint may be that most users never see Report, since it is hidden in the Result<T> type alias.

For the sake of an obvious api, eyre! could then be named error!. I’d not like that, since tracing::error! commonly occupies that place in my name spaces.

In the end, report! may be the best idea. I’m not strongly in favor of renaming eyre!, but if it is to be renamed, then to that.

[nik-rev]

One counterpoint may be that most users never see Report, since it is hidden in the Result type alias.

It's actually used quite a lot. The eyre::Report appears in 9,200 files from a quick GitHub search

For reference, eyre::bail appears in 10,200 files, eyre::ensure appears in 1,500 files, and eyre::Result appears in 84,200 files

[yaahc]

I don't have a strong feeling either way on the rename. I like the idea of a report macro and also don't mind keeping eyre as is. I would however object to renaming it to error. I'm assuming @nik-rev that you'd object to having both options given the removal of format_err.

[nik-rev]

I'm assuming @nik-rev that you'd object to having both options given the removal of format_err

Yeah, in my opinion - having 2 macros that do the same thing adds unnecessary choices to the user. It's easy to imagine multiple contributors to a codebase each with their own preference, causing an extra inconsistency