1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
//! The FLAGS VOCABULARY — a bit set a column holds, and what this crate needs to know about one.
//!
//! A flags type is the ENUM kind'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, so its whole question is membership and its wire form is a value. A flags column holds a
//! SUBSET of them, so its questions are the set-theoretic ones and its wire form has more than one
//! reading to publish — which is the whole of why [the output face is an
//! object](crate::graphql::FlagsView) where a vocabulary's is a scalar.
//!
//! # The bit table is `bitflags`' and never a second one
//!
//! [`FlagsValue`] sits on [`bitflags::Flags`], and everything a bit set can be asked — the declared
//! bits with their words, `bits`, `from_bits`, `contains`, `intersects`, the four set operators and
//! `complement` — is read off that trait rather than restated here. The reason is the one
//! `enumeration`'s reverse maps give: two tables over one vocabulary are two things that can come
//! to disagree, and the disagreement is invisible because each is correct in isolation.
//!
//! What this trait adds is the two facts `bitflags` has no reason to carry — the name a SCHEMA
//! publishes the type under, and the wire FIELD each bit takes — and nothing else.
//!
//! # Undeclared bits are refused at BOTH doors, and that is load-bearing
//!
//! `bitflags` is deliberately permissive about bits outside the declared set: `from_bits_retain`
//! keeps them, `parser::from_str` retains them, and `to_writer` renders them as a trailing hex
//! token. This crate is not. An operand carrying an undeclared bit is refused at the wire with the
//! bit and the legal mask both named, and a stored value carrying one refuses the ROW rather than
//! decoding to something the declaration cannot spell — which is the same posture a vocabulary
//! takes when the stored discriminant names no variant.
//!
//! Two filter words are exact BECAUSE of that strictness rather than in spite of it.
//! `bitflags::Flags::is_all` asks whether every declared bit is set and tolerates extra ones, and
//! `contains(all())` says the same; with no value that came through a DOOR able to carry an extra
//! bit, both are `bits == ALL`, which is an EQUALITY and therefore lowers through the integer family
//! with no bitwise word of its own. [`FlagsFilter`](crate::FlagsFilter)'s `isAll` sugar is written
//! on that identity, and it is why the sugar needs four hard words and not five.
//!
//! *A door* rather than *the system*, and the difference is one declaration wide: a MIRRORED flags
//! set — `#[ingraph::flags(u32, remote = "…")]` — crosses to its upstream by `from_bits_retain`, so
//! a bit that declaration never restated survives the crossing rather than being truncated away.
//! Such a value reaches no sugar: the fold lives at the WIRE PARSE, where the operand arrived
//! through a door, and every other door refuses one on the way in exactly as before.
use ;
use Utf8Bytes;
use crateToGraphqlOutput;
/// What a `#[ingraph::flags(…)]` declaration IS, as every layer of this crate reads one.
///
/// # The supertrait carries the vocabulary; this trait carries the wire
///
/// [`bitflags::Flags`] is where the bits live — `FLAGS` is the declared table, one
/// [`Flag`](bitflags::Flag) per bit with its word and its value, in declaration order — and every
/// question this crate asks of a flags value goes through it. A hand-written implementer therefore
/// writes a `bitflags!` type and two constants, and nothing here asks it to restate a bit twice.
///
/// # The four bounds on `Bits`, each spent
///
/// - [`ParseHex`] and [`WriteHex`] are the STRICT TEXT FORM's — `bitflags::parser`'s own grammar is
/// what `text` renders and what the operand's text door parses, and both functions ask for one of
/// the pair. Taking the grammar rather than inventing one is what makes a value this crate writes
/// a value that crate reads.
/// - [`ToGraphqlOutput`] is the `bits` field's. A width publishes under its own scalar — `u32` as
/// `U32` — so the number a client reads out of a flags object is the same form it would read out
/// of a plain `u32` column, rather than a second numeric spelling minted for this face.
/// - `Send` and `Sync` are the OBJECT FACE's: `bits` resolves through a value of this type held
/// across an await, and async-graphql's own `OutputType` asks for both of the form it renders.
///
/// The bounds sit on the SUPERTRAIT's associated type rather than on this trait's own body so that
/// every one of them is available wherever `F: FlagsValue` is written, without a `where` clause
/// repeated at each use.
///
/// # `Copy`, `Send` and `Sync`
///
/// A flags value is a register. `Copy` is what lets the object face hand a derived value —
/// `complement`, `union(other)` — to a nested selection without borrowing anything, and the two
/// auto traits are what an `async fn resolve` holding one across an await needs. Every type
/// `bitflags!` mints satisfies all three; a declaration that declines one gets `E0277` naming this
/// trait at the type, which is the same posture `#[derive(ingraph::Enum)]` takes towards
/// async-graphql's `EnumType: Copy` bound.
/// One declared bit: the word it is spelled with, the field it is asked for by, and its value.
///
/// The join of [`Flags::FLAGS`] and [`FlagsValue::FIELDS`], built where a caller needs both halves
/// at once — which is every wire face, since a schema publishes the field and an answer carries the
/// word.
/// Every declared bit of `F`, in DECLARATION order.
///
/// A ZIP and not an index, for [`FlagsValue::FIELDS`]' reason: the two lists are built together but
/// live in two traits, and truncating is the failure a hand-written implementer can survive.
///
/// UNNAMED bits are skipped. `bitflags` lets a declaration write `const _ = !0;` to widen the known
/// mask without minting a name, and such an entry has an empty word — there is no field for it and
/// nothing for a client to ask, so it contributes to [`all`] through `Flags::all` and to nothing
/// here. No emission of this crate's writes one.
/// The whole declared mask — every bit this vocabulary has a name for.
///
/// [`Flags::all`], under a name that says what it is at the call sites that spend it: it is the
/// operand `isAll` compares against, the mask a refusal quotes back, and the set `complement` is
/// taken within.
/// The value with no bit set.
/// One flags value in the STRICT TEXT FORM — `bitflags`' own grammar, which is this vocabulary's
/// exemplar in both directions.
///
/// `DEFAULT | FORCED` for two bits, the empty string for none. The words are the declared ones in
/// declaration order and the separator is ` | `, which is what [`bitflags::parser::to_writer`]
/// writes and what [`bitflags::parser::from_str`] reads — so a text this function renders is a text
/// the operand door accepts, and the round trip is the vendored crate's property rather than an
/// agreement between two functions here.
///
/// # [`Utf8Bytes`] and the allocation it does not always make
///
/// A single-bit value is the common case — a per-flag answer, a mask quoted back in a refusal — and
/// its whole text is one declared word, which is `&'static str`. That case takes
/// [`Utf8Bytes::from_static`], which inlines a short word and borrows a long one and allocates in
/// neither. Only a value with two or more bits assembles, and it assembles once.
/// The text form, assembled.
///
/// [`bitflags::parser::to_writer`] cannot fail against a [`String`] — its refusal is
/// [`core::fmt::Error`], which `String`'s `Write` never returns — so the result is discarded rather
/// than propagated into a signature no caller could act on.
/// The WORDS of the bits set in `value`, in declaration order.
///
/// Every word is a declared `&'static str`, so the list allocates its spine and not one character —
/// which is the whole reason the text seat is [`Utf8Bytes`] rather than [`String`].
///
/// Undeclared bits contribute NOTHING here, where [`text`] renders them as a hex token. The
/// asymmetry is deliberate and it is `bitflags`' own: a name list is a list of names, and a bit with
/// no name has none. Nothing in this crate can hand either function a value carrying one — both
/// doors refuse it — so the difference is visible only to a hand-written implementer that reached
/// past them.
/// One flags value read from the declared bits' WORDS — the operand's list form.
///
/// # Errors
///
/// [`UnknownFlag`] naming the first word that is not one of this vocabulary's, with the legal set
/// beside it. First rather than all, because the list form is written by hand and a reader fixes
/// one word at a time; the message carries the whole vocabulary, so the second mistake is visible
/// from the first message.
/// One flags value read from the STRICT TEXT FORM.
///
/// # Errors
///
/// [`UnknownFlag`] for a word this vocabulary does not have, and [`ill_formed`] for a text the
/// grammar does not accept at all. `bitflags`' own parser is what reads it — the grammar is that
/// crate's, so a text form this crate renders is one it reads back — and what this function adds is
/// the refusal of an UNDECLARED BIT, which that parser retains and this vocabulary does not allow:
/// a `0x…` token naming a bit outside the declared mask is a bit no answer could ever spell.
/// One flags value read from a raw BIT PATTERN — the operand's integer form, and the form a stored
/// column decodes through.
///
/// # Errors
///
/// [`UnknownFlag`] carrying the undeclared bits, rendered as a hex token beside the legal mask.
/// The strictness both doors share: a value that reached here through a RETAINING constructor,
/// checked for bits this vocabulary never declared.
/// The refusal for a text the grammar does not accept — quoted whole, because what is wrong with it
/// is its shape rather than one token.
/// What a word, a token or a bit outside a vocabulary is refused with.
///
/// It carries the OFFENDING SPELLING and not the vocabulary, because the vocabulary is a property
/// of the type the caller was parsing INTO and every caller of these functions knows it — so the
/// sentence a client reads is assembled where both halves are in hand, which is
/// [`FlagsInput`](crate::graphql::FlagsInput)'s parse, and this type carries no copy of a table it
/// would then have to keep in step.
/// The legal set, as a refusal lists it: every declared word, then the whole mask in the text form.
///
/// Written once and spent by every door, so a client refused at the list form and a client refused
/// at the text form are told the same thing about the same vocabulary.