Expand description
The LEAF ERROR’s model — an application’s own failure type, dressed to render under its code. THE LEAF ERROR’s midwife: an application’s own failure type, dressed to render.
#[ingraph::mutation_error]
pub enum WatchError {
#[ingraph(code = "NOT_A_DIRECTORY", error = "`{0}` is not a directory")]
NotADirectory(PathBuf),
}emits Display, core::error::Error and one reading — code() — and NOTHING ELSE. The enum
stays the author’s: its arms, its payloads, its derives and its visibility are echoed untouched.
§IT IS A CONVENIENCE AND NOT A SEAM, which is the ruling and not a hedge
A hand-written error is exactly as legal here as a generated one. Nothing in this framework asks
a failure type for anything but a Display — error(type = "…")’s own rendering, and the
assembled face’s error sum, both spend that and no more — so a type that implements Display by
hand, or through somebody else’s derive, is a first-class declared failure. What this macro buys
is the CODE DISCIPLINE below, which a hand-written error simply does not get checked for.
§ONE CODE PER VARIANT, and the code IS the head of the sentence
Every variant writes a code, and the rendering is CODE: message. That is the one-code-head
law, and it is why the code is mandatory rather than optional: a leaf error’s whole job at the
wire is to be recognised, and a variant with no word is a refusal a client cannot tell from its
neighbour.
It is also why a declaration that heads such an error a SECOND time is a mistake. A declared
error(type = "…", code = "…") puts its own heading in front of whatever the value renders as,
so an error minted here — which already carries one — is declared WITHOUT the code word. Two
headings on one message is two vocabularies with nothing telling a reader which is which.
§THE CODE SPACE IS OPEN, and the framework’s own words are RESERVED
An application mints whatever SCREAMING_SNAKE_CASE words it likes: this framework cannot
enumerate everybody’s failures and does not try. What it does hold is its OWN vocabulary — the
ErrorCode table, one word per typed refusal that can reach
the wire — and a declaration that mints one of those words is refused. A client matching on
UNREACHABLE_SOURCE would otherwise be told the change was made and not applied by an
application error that meant something else entirely.
RESERVED is that table’s words, carried here because a proc macro cannot depend on the crate
it generates code for. The two lists are pinned EQUAL by ingraph’s own graphql::code fixture
— the file a round that adds a word already has to touch, which is what makes the pin catch that
round rather than merely catch a rename.
§WHAT THE DECLARATION OWES
A Debug, because core::error::Error has it as a supertrait — and nothing here emits one,
because a Debug this emission wrote would collide with the derive most error types already
carry. A Display on every field a template RENDERS; nothing at all on a
field it never names, which is bound as _.
§THE TEMPLATE is a format string over the variant’s own fields
{0} and {} name a tuple variant’s fields by position; {name} names a struct variant’s by
name. What is emitted is ONE write_str-or-write! per arm with the head folded in at
expansion time, and every argument passed EXPLICITLY by name — implicit capture is the
declaring crate’s edition to have, and an expansion does not get to assume one.
Structs§
- Binding
- ONE field a template referred to.
- Error
Model - A validated leaf-error declaration, ready to emit.
- Rendering
- A variant’s message, as the emission spends it.
- Variant
Model - ONE variant of a leaf error: what it is called, what it is recognised by, and what it says.
Enums§
- Binding
At - Where a bound field sits in its variant.
- Error
Road - WHICH ROAD an error was minted for — the word an author wrote, carried for the sentence.
- Variant
Shape - A variant’s fields, as a pattern has to spell them.
Constants§
- RESERVED
- The FRAMEWORK’s own wire vocabulary, as words.