Add support for source forwarding in Error derive

[MegaBluejay]

Resolves #428
Related to #110, #200

Synopsis

Adds support for #[error(forward)] attribute, which forwards the .source() implementation to a field.

Solution

Use existing forward fields in State for parsing the attributes, and keep the source-inferring logic the same as without forwarding.

Backtrace forwarding

The current behaviour is that if the field annotated/inferred to be the source is annotated with #[error(backtrace)], a forwarded provide() is generated.

This was in the example usage, but not documented in the list above, so I added it.

Checklist

• Documentation is updated (if required)
  • Document new behaviour
  • Add an explanation of advised usage as previously suggested?
• Add errors on usage of #[error(forward)] when no source field was specified/inferred
• Tests are added/updated (if required)
• CHANGELOG entry is added (if required)

[MegaBluejay]

@tyranron I implemented this with the existing parsing since it was an easy change.

Would it be preferable to refactor the derive first, similarly to #286?

[tyranron]

@MegaBluejay no, let's postpone refactoring here as a minor priority task.

[JelteF]

copy paste error?

Suggested change

	4. The source field is annotated with `#[error(backtrace)]`. Then it would
	4. The source field is annotated with `#[error(forward)]`. Then it would

[MegaBluejay]

No that's correct, provide is forwarded only when the source is annotated with #[error(backtrace)].

That behaviour is unchanged in this PR.

The reasoning for keeping a separate attribute is to make source forwarding work on stable, since there's no good way of generating feature-gated code.

I also think this is somewhat unintuitive, but I haven't come up with a better idea.

Perhaps it could make sense to disallow #[error(backtrace)] on the source field if there's no #[error(forward)]?

[JelteF]

I'm having a hard time understanding the usecase for such forwarding. Could you share a concrete example for when this is useful?

[MegaBluejay]

Could you share a concrete example for when this is useful?

The main use case I can see is transparent error variants

Something like

#[derive(Debug, Display, Error)
enum Error {
    ...
    #[error(forward)]
    #[display("{_0}")]
    #[debug("{_0:?}")]
    Other(anyhow::Error),
}

Where there's no new information added by the wrapper, so adding it to the source stack is unnecessary.

[tyranron]

@MegaBluejay yes, I start thinking that maybe transparent is better here than forward. Let's postpone it for a little while... I'll write up some design thoughts during the following week. And, of course, will describe the motivation more clearly.

[JonahPlusPlus]

Example use case:
I want to have a composite error type, and forwarding the source would simplify deriving Display and Error.

e.g.

#[derive(Debug, Display, Error)]
#[display("`{rust_name}` should work but {kind}")]
struct Error {
  rust_name: &'static str,
  #[error(forward)]
  kind: ErrorKind
}

#[derive(Debug, Display, Error)]
enum ErrorKind {
  #[display("foo was encountered")]
  Foo,
  #[display("bar errored")]
  Bar {
    #[error(source)]
    external: ExternalError
  }
}

We have data common to all variants, so moving it into a struct makes sense. But we also have source information only relevant to specific variants, so we need some way to use the source in the enum and we don't want to treat the ErrorKind as it's own source, since the enum doesn't represent an "abstraction barrier" by itself. So forwarding the error makes the most sense here.

Note that this pattern isn't available in thiserror, since #[error(transparent)] also delegates the Display impl.