Skip to main content

Module flags

Module flags 

Source
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 hold NAME = 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

implwho demands itgated
FlagsValueevery wire face — it carries the SDL name and the bit tableno
FlagsFilterMarkerthe column’s FILTER — FlagsMarker<T> resolves through itno
DefaultMarker, DefaultVecMarkerthe INFERENCE, so a column needs no word to be readno
CursorValuethe KEYSET cursor, which every persisted column is audited forno
ColumnKind, Assemblethe column’s width and how a row reads one backthe family
sqlx::Type/Decode/Encode, Carrierthe storage binding and the lowering’s operandper backend
ToGraphqlOutput, ToGraphqlInputthe two wire SEATSthe 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.
FlagsModel
One flags declaration, validated.

Enums§

BitWidth
The widths a flags set may be declared at.