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
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
//! The four CONDITIONAL-EXPANSION gates: [`if_sqlite!`](crate::if_sqlite),
//! [`if_postgres!`](crate::if_postgres), [`if_mysql!`](crate::if_mysql) and
//! [`if_mongo!`](crate::if_mongo).
//!
//! This module is private and the four are PUBLIC, which is not a contradiction: `#[macro_export]`
//! puts a `macro_rules!` at the crate ROOT whatever module it was written in, so where a gate lives
//! and where it is published are different questions — the shape `field` and `name` already have.
//! Each gate states its own contract, and the reasons behind all four are the crate note's [four
//! gates](crate#the-four-gates) section, because what you are reading RENDERS NOWHERE: a private
//! module's note is not published, so nothing a consumer needs may be written only here.
//!
//! # One public macro over a private pair, and why not the pair alone
//!
//! Each public gate is UNGATED and delegates to a twin selected by this crate's `#[cfg]`: under the
//! feature the twin expands its tokens verbatim, and without it the twin expands to nothing.
//!
//! The pair could carry the public name directly, and what that costs is documentation rather than
//! expansion. A `#[cfg]`ed pair is two items, so each build documents the twin it compiled — the
//! contract and its example would be written twice per backend and checked in one feature lane each,
//! which is how a public doc drifts from the build a reader is in. One ungated definition is written
//! once, and its example is a compilation in EVERY lane, including the lanes where the gate is shut.
//!
//! The twins keep the long, collision-proof names the crate root carries for machinery, and nothing
//! outside this file names one.
/// Expand the tokens where `ingraph` was built with SQLite, and to nothing where it was not.
///
/// The gate a declaration's emitted SQLite impls ride, spent by hand. A per-backend half the derive
/// cannot write — a composite comparison, a conversion only the declaring crate knows — is written
/// beside the emission and rides the same gate, because a `#[cfg]` written where that half lives asks
/// a different question: see the crate note's [four gates](crate#the-four-gates).
///
/// The tokens are slurped rather than parsed, so they may name types this build does not have.
///
/// # Examples
///
/// ```
/// // `comparison::sql::sqlite` is a module `ingraph` has only where SQLite is compiled in, and a
/// // shut gate discards these tokens before anything in them has to resolve — so this is one
/// // compilation in every build, carrying no `#[cfg]` of its own.
/// ingraph::if_sqlite! {
/// use ingraph::comparison::sql::sqlite::ScalarComparison;
///
/// let column = ScalarComparison::<i64>::new();
/// assert!(column.is_empty());
/// }
/// ```
/// Expand the tokens where `ingraph` was built with PostgreSQL, and to nothing where it was not.
///
/// The gate a declaration's emitted PostgreSQL impls ride, spent by hand. A per-backend half the
/// derive cannot write — a composite comparison, a conversion only the declaring crate knows — is
/// written beside the emission and rides the same gate, because a `#[cfg]` written where that half
/// lives asks a different question: see the crate note's [four gates](crate#the-four-gates).
///
/// The tokens are slurped rather than parsed, so they may name types this build does not have.
///
/// # Examples
///
/// ```
/// // `comparison::sql::postgres` is a module `ingraph` has only where PostgreSQL is compiled in,
/// // and a shut gate discards these tokens before anything in them has to resolve — so this is one
/// // compilation in every build, carrying no `#[cfg]` of its own.
/// ingraph::if_postgres! {
/// use ingraph::comparison::sql::postgres::ScalarComparison;
///
/// let column = ScalarComparison::<i64>::new();
/// assert!(column.is_empty());
/// }
/// ```
/// Expand the tokens where `ingraph` was built with MySQL, and to nothing where it was not.
///
/// The gate a declaration's emitted MySQL impls ride, spent by hand. A per-backend half the derive
/// cannot write — a composite comparison, a conversion only the declaring crate knows — is written
/// beside the emission and rides the same gate, because a `#[cfg]` written where that half lives asks
/// a different question: see the crate note's [four gates](crate#the-four-gates).
///
/// The tokens are slurped rather than parsed, so they may name types this build does not have.
///
/// # Examples
///
/// ```
/// // `comparison::sql::mysql` is a module `ingraph` has only where MySQL is compiled in, and a shut
/// // gate discards these tokens before anything in them has to resolve — so this is one compilation
/// // in every build, carrying no `#[cfg]` of its own.
/// ingraph::if_mysql! {
/// use ingraph::comparison::sql::mysql::ScalarComparison;
///
/// let column = ScalarComparison::<i64>::new();
/// assert!(column.is_empty());
/// }
/// ```
/// Expand the tokens where `ingraph` was built with MongoDB, and to nothing where it was not.
///
/// The gate a declaration's emitted MongoDB impls ride, spent by hand. A per-backend half the derive
/// cannot write — a composite comparison, a conversion only the declaring crate knows — is written
/// beside the emission and rides the same gate, because a `#[cfg]` written where that half lives asks
/// a different question: see the crate note's [four gates](crate#the-four-gates).
///
/// The tokens are slurped rather than parsed, so they may name types this build does not have.
///
/// # Examples
///
/// ```
/// // `comparison::mongo` is a module `ingraph` has only where MongoDB is compiled in, and a shut
/// // gate discards these tokens before anything in them has to resolve — so this is one compilation
/// // in every build, carrying no `#[cfg]` of its own.
/// ingraph::if_mongo! {
/// use ingraph::comparison::mongo::MongoScalarComparison;
///
/// let column = MongoScalarComparison::<i64>::new();
/// assert!(column.is_empty());
/// }
/// ```
/// SQLite is compiled in, so the tokens are expanded verbatim.
/// The empty twin: SQLite is not compiled in, so the tokens are discarded unparsed.
/// PostgreSQL is compiled in, so the tokens are expanded verbatim.
/// The empty twin: PostgreSQL is not compiled in.
/// MySQL is compiled in, so the tokens are expanded verbatim.
/// The empty twin: MySQL is not compiled in.
/// MongoDB is compiled in, so the tokens are expanded verbatim.
/// The empty twin: MongoDB is not compiled in.
/// Expand `$item` where `ingraph` was built with the SQL family at all, and to nothing where it was
/// not.
///
/// The one gate whose subject is a FAMILY rather than a backend, and it is not a fifth backend
/// slipped into the list: `sqlx` is the family ROOT — the feature that owns `dep:sqlx`, which every
/// dialect feature names rather than the dependency — so this asks *does this build have sqlx*,
/// exactly as [`if_sqlite`] asks *does it have that driver*.
///
/// What needs it is an emitted item whose SIGNATURE names the family and not a dialect: a graph
/// root's `init` is generic over the database and still spells `sqlx::Acquire` and the schema
/// lane's own types, so it exists per family rather than per backend. A declaration's per-backend
/// impls keep the four gates above.
/// The empty twin: the SQL family is not compiled in.
/// Expand `$item` where `ingraph` was built WITHOUT the SQL family —
/// [`if_sqlx`](crate::__ingraph_if_sqlx)'s complement, and the THIRD gate to need one.
///
/// The serde pair's reason at a different grain. There the fact was *an attribute cannot be added by
/// a macro that expands to nothing*; here it is the same sentence about a METHOD: a derived index's
/// query unit is ONE `#[Object]` impl — a second would be `E0119` on `ObjectType` before any schema
/// exists — and the attribute reads the impl block whole, so a gate written around one of its
/// methods would be a `macro_rules!` invocation the attribute expands before, and never a field. The
/// block is therefore written twice, once inside each half, and exactly one survives.
///
/// What differs between the two copies is the HYDRATED roads: they name
/// [`SqlDoor`](crate::SqlDoor) and [`SqlPooledGather`](crate::SqlPooledGather), which a build with
/// no sqlx does not have, where the keys roads beside them name no store at all. So the shut half is
/// exactly the unit a build without the family already had, and the family's arrival adds fields
/// rather than moving any.
/// The empty twin: the SQL family IS compiled in, so the family-less unit is the one discarded.
/// Expand `$item` where `ingraph` was built with serde, and to nothing where it was not.
///
/// The one gate with a COMPLEMENT, and what needs the pair is a DERIVE. An emitted options spine
/// exists in every build — a programmatic deployment builds one by hand, and the launch entry names
/// the type whatever a build compiled — but only some builds can derive `Deserialize` on it. An
/// attribute cannot be added by a macro that expands to nothing, so the declaration is written
/// twice, once inside each half, and exactly one half survives.
/// The empty twin: serde is not compiled in.
/// Expand `$item` where `ingraph` was built WITHOUT serde — [`if_serde`](crate::__ingraph_if_serde)'s
/// complement, and see it for why the pair exists.
/// The empty twin: serde IS compiled in, so the serde-less declaration is the one discarded.
/// Expand `$item` where `ingraph` was built with OBSERVATION, and to nothing where it was not.
///
/// The SECOND gate with a complement, and it has one for the serde pair's exact reason: what rides
/// this gate is a whole function whose body is wrapped in a span, and the same function has to exist
/// unwrapped in a build that compiles no `tracing`. A macro expanding to nothing cannot subtract a
/// wrapper any more than it can add an attribute, so the entry is written twice — once in each half
/// — and exactly one survives.
///
/// It is the gate the `tracing(level = …)` word's whole EMISSION rides: the level const on a node's
/// [`Declared`](crate::Declared) impl, and the span an emitted query entry opens. The WORD itself
/// rides nothing — it parses, refuses and reaches the model in every build — which is the split that
/// keeps turning observation on a line in ONE manifest rather than an edit to a declaration.
/// The empty twin: observation is not compiled in.
/// Expand `$item` where `ingraph` was built WITHOUT observation —
/// [`if_tracing`](crate::__ingraph_if_tracing)'s complement, and see it for why the pair exists.
/// The empty twin: observation IS compiled in, so the uninstrumented entry is the one discarded.
/// Expand `$item` where `ingraph` was built with the GraphQL BINDING, and to nothing where it was
/// not.
///
/// The gate a declaration's emitted WIRE FACE rides, and not a sixth backend either: the four above
/// ask *does this build have that database*, the family gate asks *does it have sqlx*, and this one
/// asks the same question of the one feature that supplies a schema — the `InputType` pair every
/// registered filter needs, and the attribute an output object's accessor face carries.
///
/// A `#[cfg(feature = "async-graphql")]` written inside an expansion cannot stand in for it, and
/// that is the whole reason the gate shape exists: such a `#[cfg]` asks whether the DECLARING crate
/// has a feature by that name, which is a different manifest and usually no feature at all.
/// The empty twin: the GraphQL binding is not compiled in.
/// Expand `$item` where `ingraph` was built with the TANTIVY ENGINE, and to nothing where it was
/// not.
///
/// The THIRD gate with a complement, and the first whose subject is an ENGINE. What rides it is
/// everything a resource's `tantivy` KIND WORD emits: the declaration re-written to carry the
/// engine the macro mints, the `AsyncResource` impl that opens it, and the base and two blocking
/// faces that delegate to it. Every one of those names a type — `TantivyStore`, `TantivyFulltext`
/// — that a build without the feature does not have.
///
/// A `#[cfg(feature = "tantivy")]` written inside the expansion cannot stand in for it, for the
/// reason [`if_async_graphql`](crate::__ingraph_if_async_graphql) states: such a `#[cfg]` asks
/// whether the DECLARING crate has a feature by that name, which is a different manifest and
/// usually no feature at all.
/// The empty twin: the Tantivy engine is not compiled in.
/// Expand `$item` where `ingraph` was built WITHOUT the Tantivy engine —
/// [`if_tantivy`](crate::__ingraph_if_tantivy)'s complement, and the reason it needs one is not the
/// serde pair's.
///
/// There the two halves were two spellings of one item. Here the shut half carries the AUTHOR'S OWN
/// declaration back — a kind word re-writes the host to hold an engine, and a build with no engine
/// must still see the type it was written as — beside a `compile_error!` naming the feature. Without
/// it the shut gate would swallow the whole emission and leave the reader a missing-`AsyncResource`
/// refusal to work backwards from, when what they are missing is one word in one manifest.
/// The empty twin: the Tantivy engine IS compiled in, so the engine-less host is the one discarded.
// The four re-exports are what give the crate-root macros a MODULE path, and the shelf mirrors
// modules — which is how an emission reaches them under `__private::gate` like every other framework
// name, and why what a declaration's expansion writes is independent of what a person writes.
pub use crate::;
// The two NON-BACKEND gates take that module path and no public face: `__private::gate::if_sqlx` is
// what an emitted graph root writes and `__private::gate::if_async_graphql` is what an emitted
// wire face writes, and there is no `if_sqlx!` or `if_async_graphql!` beside the four above.
//
// The FAMILY gate has a complement now, for the reason its own note carries: a derived index's query
// unit is written twice so that the hydrated roads exist exactly where the SQL family does.
pub use crate::;
// The serde PAIR takes the same treatment, and for the same reason: `__private::gate::if_serde` and
// its complement are what an emitted options spine writes, and neither has a public face — what a
// person writes about serde is a feature in a manifest.
pub use crate::;
// The OBSERVATION pair, same treatment and same reason: `__private::gate::if_tracing` is what an
// emitted `Declared` impl and an emitted query entry write, its complement carries the uninstrumented
// entry beside it, and neither has a public face — what a person writes about observation is the
// `tracing(level = …)` word, which parses whether or not this gate is open.
pub use crate::;
// The ENGINE pair, same treatment: `__private::gate::if_tantivy` is what a resource declaration's
// `tantivy` kind word emits its whole expansion inside, its complement carries the author's own host
// back beside a `compile_error!`, and neither has a public face — what a person writes about an
// engine is the kind WORD, which parses whether or not this gate is open.
pub use crate::;