Expand description
The FLAGS face: what a #[ingraph::flags(u32)] declaration expands into.
A flags set is the VOCABULARY’s sister and not a new universe. Both are a closed set of names a
declaration writes down; what differs is the arity of an answer — an enum column holds one of the
names and a flags column holds a subset. So the two share a shape at every layer, and where this
module departs from enumeration it is because that arity forced it.
§The declaration is an ENUM and the expansion is a STRUCT, and that is a REWRITE
#[ingraph::flags(u32)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum TrackDisposition {
/// The default track for its kind.
Default = 0x1,
Forced = 0x2,
HearingImpaired = 0x4,
}becomes a bitflags! struct with TrackDisposition::DEFAULT, ::FORCED and
::HEARING_IMPAIRED on it. Three things are being asserted there and each was chosen against an
alternative:
- An ATTRIBUTE and not a derive. A derive may only APPEND, and the flags type is MINTED by
bitflags!rather than written by the author — so nothing but an attribute can be the door. That is the same rewrite criterion the tree already applies elsewhere. - The manifest is an
enum, because a declaration face is a set of NAMES with values and Rust has exactly one item that spells that. A struct body cannot holdNAME = 0x1, and a unit struct with the bits in the attribute would put the vocabulary somewhere a doc comment cannot reach. Writing the vocabulary as an enum is also what makes the two kinds READ as sisters: the word above the declaration is the whole difference between one of these and a set of these. - The bits are the DISCRIMINANTS, explicit and never inferred. A flags value is somebody’s stored integer, so an automatic numbering would mean that reordering the declaration rewrites every row — and reordering a list of names is the most ordinary edit there is. Auto-numbering is therefore refused rather than defaulted, which is the one place this kind is STRICTER than the vocabulary it mirrors.
The manifest’s own lints never fire, because the manifest does not survive: an attribute macro
replaces the item, so Default and HearingImpaired are read as bit NAMES here and are gone
before rustc has an enum to have an opinion about.
§#[ingraph::flags(…)] GOES ABOVE THE DERIVES, and the order is load-bearing
#[ingraph::flags(u32)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum TrackDisposition { … }rustc expands the TOPMOST attribute on an item first, and derive takes its turn in that same
order. A derive written above this word therefore expands against the MANIFEST — the enum that is
about to stop existing — and lands a Debug impl matching on TrackDisposition::Default, a
variant the expansion replaced with a const. The error a reader gets says no associated
function or constant named Default found for struct, which is true and unhelpful.
Written above, this word expands first, and the derives it forwards land on the type
bitflags! mints. It is the ordinary hazard of every rewriting attribute and it cannot be
detected here: by the time this door runs, a derive that already expanded is gone from the
item’s attributes and is indistinguishable from one nobody wrote.
§One word, three casings, one table
HearingImpaired in the manifest gives the const HEARING_IMPAIRED, the wire word
HEARING_IMPAIRED, and the GraphQL field hearingImpaired. The const and the word are the SAME
string — which is what lets the strict text form be bitflags::parser::to_writer itself rather
than a renderer written here that could come to disagree with it — and the field is that word
under the one casing GraphQL’s own convention asks for. #[ingraph(rename = "…")] moves the
word, and the field follows it, because they are two readings of one declaration rather than two
declarations.
§Storage is the BACKING INTEGER, always
There is no text/integer fork here and no per-face block, where a vocabulary has both. A
flags column is stored as its bit pattern because the mask questions are ARITHMETIC on that
pattern: hasAll is (col & m) = m, which a text column cannot answer at all. So the only face
with words is the wire, one rename covers it, and the whole namespace apparatus a vocabulary
needs is absent rather than defaulted.
The width is the DECLARATION’s — flags(u32) is a u32 column — through the same house carrier
table a vocabulary’s #[repr(…)] goes through, so a Postgres column widens to BIGINT exactly
as an enum’s u32 discriminant does.
§The set of rows
| impl | who demands it | gated |
|---|---|---|
FlagsValue | every wire face — it carries the SDL name and the bit table | no |
FlagsFilterMarker | the column’s FILTER — FlagsMarker<T> resolves through it | no |
DefaultMarker, DefaultVecMarker | the INFERENCE, so a column needs no word to be read | no |
CursorValue | the KEYSET cursor, which every persisted column is audited for | no |
ColumnKind, Assemble | the column’s width and how a row reads one back | the family |
sqlx::Type/Decode/Encode, Carrier | the storage binding and the lowering’s operand | per backend |
ToGraphqlOutput, ToGraphqlInput | the two wire SEATS | the binding |
The wire face itself is NOT here, and that is the biggest saving over the vocabulary kind: an
enum’s InputType/OutputType are emitted per declaration because a GraphQL enum’s values are
its own, where a flags type’s whole face is generic over FlagsValue in ingraph and reads the
bit table at runtime. So a declaration emits two crossing rows and the framework does the rest.
Structs§
- FlagBit
- One declared bit.
- Flags
Model - One flags declaration, validated.
Enums§
- BitWidth
- The widths a flags set may be declared at.