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
//! [`Timebase`]'s wire faces: the OBJECT a client reads, the SCALAR one whole-value operand crosses
//! on, and the INPUT OBJECT the three filter facets are published as.
//!
//! The resolver naming rule is stated once in [`primitives`](crate::primitives) and the general shape of
//! these faces in [`time`](super::super), where all four types share them. What is stated HERE is
//! the one thing a timebase does that its siblings do not: it accepts a value on the way IN.
//!
//! ```text
//! type Timebase { input TimebaseFilter {
//! numerator: Int! eq: TimebaseOperand ─┐
//! denominator: Int! ne: TimebaseOperand │ VALUE
//! name: String in: [TimebaseOperand!] │
//! text: String! notIn: [TimebaseOperand!] ─┘
//! hz: Float startsWith: String ─┐
//! secondsPerTick: Float! endsWith: String │ RENDER
//! } contains: String ─┘
//! numerator: I32Filter ─┐ COMPONENT
//! scalar TimebaseOperand denominator: …Filter ─┘
//! }
//! ```
//!
//! # WIDE IN, STRICT OUT — and the two shapes are the whole of "wide"
//!
//! [`TimebaseOperand`] reads three spellings of one value and writes back one. A client may send
//! the STRUCTURE `{ numerator: 1001, denominator: 30000 }`, the TEXT `"1001/30000"`, or a roster
//! NAME `"NTSC_VIDEO"` — and what comes back out is always the canonical text, so a value read from
//! this schema and sent back to it is the same value by the shortest route.
//!
//! Everything else is refused, and the refusals are the point rather than the leftovers:
//!
//! - **A bare NUMBER is refused because it is ambiguous three ways.** `30000` could be the numerator
//! (`30000/1`), the denominator (`1/30000`) or a tick rate meant as its reciprocal — and the three
//! are three different timebases. A parser that picked one would be guessing at what a client
//! meant, and would guess silently.
//! - **A list is refused** where a whole-value operand is expected, because `in` is an explicit key.
//! That is the framework's own shorthand law rather than a rule invented here.
//! - **An object with any other key is refused**, both halves being required: `{ numerator: 1 }` is
//! not `1/1`, for the reason a bare number is not — the missing half is a value nobody wrote.
//!
//! The two STRING arms are told apart by the SLASH, which is total: no roster name contains one,
//! which `mediatime` states as the property its own two-armed parser relies on. So a text operand
//! reaches the rational parser and a name operand reaches the roster, and neither can shadow the
//! other. Case folding comes with the roster door rather than being added here — `mediatime`'s
//! `from_name` folds ASCII case, so `"ntsc_video"` names the same constant as `"NTSC_VIDEO"`.
//!
//! # `Timebase` publishes SIX fields where the wrapped struct has two
//!
//! The four beyond `numerator`/`denominator` are DERIVED, and the module docs one level up rule
//! derived fields out for the OTHER time types — a lossy `seconds` beside an exact `pts` only
//! invites a client to read the wrong one. A timebase is where that reasoning stops applying, and it
//! is worth saying why rather than treating the exception as an oversight:
//!
//! - **`name` and `text` are EXACT.** A roster name is a lookup on the value and the canonical text
//! is the pair itself, so neither loses anything a client would then have to reconstruct.
//! - **`hz` and `secondsPerTick` are lossy, and they are what a client asks a timebase for.** The
//! question "how fast is this stream counting" has no exact answer in a JSON number, and a client
//! computing it from the two integers computes exactly this — in whatever precision ITS language
//! affords, which is rarely better than a double and is sometimes worse. The exact form is right
//! there beside them, which is the condition the rule one level up actually states.
//!
//! Both derived numbers are NULLABLE where the value has no answer rather than reporting a
//! plausible one: `hz` is the reciprocal reading, and a `0/d` timebase has no reciprocal.
use NonZeroI32;
use crateToGraphqlOutput;
use ;
use mediatime as mt;
use ;
/// A timebase as a filter operand: the structure `{ numerator, denominator }`, the text
/// `"1001/30000"`, or a well-known name such as `"NTSC_VIDEO"`.
///
/// Written back as the canonical text, whichever of the three it arrived as.
// The GraphQL name is SPELLED rather than derived from the Rust one, as `SoundEventCode`'s is: a
// wire name is a schema commitment, and a Rust rename is not a schema change.
/// The STRUCTURED arm: both halves, required, and no other key.
///
/// Strict about extra keys because a filter operand is not a place to be forgiving — `{ numerator:
/// 1, denominato: 30000 }` is a typo that a lenient reader turns into a query for `1/1` that returns
/// the wrong rows rather than an error.
/// The two STRING arms, told apart by the slash.
///
/// The slash decides rather than a try-and-fall-back, and that is what keeps each arm's error its
/// own: `"1 / 90000"` hears that a timebase is spelled `num/den` — the rational parser's own
/// refusal, naming the rule it broke — where a fall-back would report that it is not a well-known
/// name, which is true and useless. No roster name contains a slash, so the split is total.
/// A read arm's answer as the scalar's: the value wrapped, or the sentence put in front of a client.
///
/// The two arms answer with a MESSAGE rather than with an `InputValueError` so that
/// [`is_valid`](ScalarType::is_valid) can call the same two functions `parse` does — an error type
/// carrying the operand would make the validator's call site have to name one, and the whole point
/// of sharing them is that a query which validates is a query which parses.
/// The OPERAND's own crossing — the row a COLLECTION face reads to learn what one element of a
/// `[Timebase]` looks like on the wire.
///
/// The OUTPUT row: a timebase is returned as ITSELF, by reference, through the object below.
///
/// The identity arm rather than a carrier, which is what the lifetime on `Output` exists to make
/// free: a type that already has a wire face is rendered through async-graphql's own blanket over
/// `&T`, and a clone per field of every response is exactly what a lifetime-free seat would have
/// cost.
/// A media timebase: the rational `numerator / denominator` seconds per tick that the stream itself
/// carries.
// The FILTER's wire face is not here, and that is the point: `TimebaseFilter` carries
// `#[ingraph(composed)]`, so its nine slots are read off the struct's own field list and the
// registration, the parse and the render are emitted from that one table. What this module still
// owns is the OPERAND's grammar — the three arms a client may write and the one canonical form that
// comes back.