#[mutation_error]Expand description
Dress an application’s own failure type to RENDER — a declared exchange’s error, given a code and a sentence.
#[ingraph::mutation_error]
pub enum WatchError {
#[ingraph(code = "NOT_A_DIRECTORY", error = "`{0}` is not a directory")]
NotADirectory(PathBuf),
#[ingraph(code = "ALREADY_WATCHED", error = "{root} is already watched, as watch {id}")]
AlreadyWatched { root: String, id: u64 },
}§A CONVENIENCE AND NOT A SEAM
A hand-written error is exactly as legal. Nothing in this framework asks a failure type for more
than a Display — that is all error(type = "…")’s rendering spends, and
all the assembled face’s error sum spends — so an error that implements it by hand, or through
somebody else’s derive, is a first-class declared failure. What this word buys is the CODE
DISCIPLINE, which nothing checks for a hand-written one.
§Attributes, per VARIANT, and neither is optional
code = "SCREAMING_SNAKE_CASE"— what a client MATCHES ON, and the head of everything this variant renders as.error = "…"— what a person READS. A format string over the variant’s own fields:{0}and{}by position,{name}by name,{{for a literal brace.
§What it emits
| item | content |
|---|---|
| the author’s enum, echoed | unchanged but for the markers this macro consumed |
impl Display | "CODE: message", one arm per variant, from one literal apiece |
impl core::error::Error | the defaulted source, this macro having no way to know which field is a cause |
<Error>::code | the word this variant is recognised by |
The declaration is otherwise untouched: its arms, its payloads, its derives, its visibility.
§THE ENUM OWES A Debug, and it is the author’s to write
core::error::Error has Debug as a supertrait, so a declaration wears #[derive(Debug)] —
or an impl of its own. Nothing here emits one, and the omission is the point: a Debug this
macro wrote would collide with the derive most error types already carry (E0119), and choosing
between them by scanning attributes would make the emission depend on which way an author
happened to spell it. What an author sees if they forget is rustc naming Debug under
required by a bound in Error, at the enum.
A field the template RENDERS owes a Display; one it never names owes
nothing at all, being bound as _.
§THE CODE HEADS THE MESSAGE, so a declaration does not head it again
An exchange declaring error(type = "…", code = "…") puts its own heading in front of whatever
the value renders as. An error minted here already carries one, so such an exchange writes
error(type = "…") and NO code word — two headings on one message is two vocabularies with
nothing telling a reader which is which.
§Refusals
| written | refused because |
|---|---|
a variant with no code | the code is what a client matches on, and a variant without one is a refusal it cannot tell from its neighbour |
a variant with no error | a code with no message under it says nothing to a person |
code = "notScreaming" | a code is a machine-read constant, in GraphQL’s own convention for one |
two variants under one code | a vocabulary is a contract only while it is injective |
a code that is one of the framework’s own | a client matching it is asking about a refusal this framework raises |
{name} naming no field, or {7} past the last one | the template reads the variant’s own fields |
| a struct or a union | an error’s VARIANTS are the ways it can fail |
| a generic parameter | the expansion writes ONE Display over ONE type |
| any argument on the attribute itself | every word is written on a variant |