gecode-iris 0.1.0__cp310-abi3-win_amd64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1434 @@
1
+ """Build reader specs from Python code, with typed handles.
2
+
3
+ A :class:`SpecBuilder` is the root scope of a spec. Each statement is a method
4
+ call, a block is a ``with`` statement, and every definition returns a handle
5
+ that later statements use in expressions and that ``data[handle]`` reads from
6
+ the data with the type it promises.
7
+
8
+ A handle's type parameter is the value ``data[handle]`` gives: ``int`` for an
9
+ integer, ``list[int]`` for an array or for an integer read in a repeat, and
10
+ ``int | None`` for an entry that may be absent. Scopes carry their depth in
11
+ their class, ``Scope0`` to ``Scope3``, and their presence in their parameter:
12
+ ``Required`` when their statements always execute and ``None`` when they may
13
+ not. Inside more than three repeats, ``ScopeN`` gives ``DynField`` handles.
14
+
15
+ Python operators build Iris expressions, except for division, remainder and
16
+ power, which are :func:`div`, :func:`rem` and :func:`pow`, and the logical
17
+ operators, which are ``&``, ``|`` and ``~``. Line patterns are t-strings on
18
+ Python 3.14 and later, and tuples of text and parts on every version.
19
+
20
+ A mistake that a builder can find raises :class:`BuildError` at the call that
21
+ made it, or from ``build()``, and names the caller's file and line. Errors
22
+ while reading a built spec name the call site of their statement in
23
+ :attr:`gecode_iris.Error.call_site`.
24
+ """
25
+
26
+ import builtins
27
+ import sys
28
+ from collections.abc import Callable
29
+ from typing import Any, Generic, Literal, NoReturn, Protocol, TypeAlias, TypeVar, overload
30
+
31
+ from gecode_iris import CallSite as CallSite
32
+ from gecode_iris import Error, Spec, Value
33
+ from gecode_iris.build import gecode as gecode
34
+
35
+ _T_co = TypeVar("_T_co", covariant=True)
36
+ _N_co = TypeVar("_N_co", covariant=True)
37
+ _S_co = TypeVar("_S_co", covariant=True)
38
+ _R_co = TypeVar("_R_co", covariant=True)
39
+ _O_co = TypeVar("_O_co", covariant=True)
40
+ _I_co = TypeVar("_I_co", covariant=True)
41
+ _U = TypeVar("_U")
42
+ _I = TypeVar("_I")
43
+ _F = TypeVar("_F", bound=Field[Any])
44
+ _C = TypeVar("_C", bound=Callable[..., Any])
45
+
46
+ Required: TypeAlias = NoReturn
47
+ """The presence of a scope whose statements always execute: ``T | Required``
48
+ is ``T``."""
49
+
50
+ Maybe: TypeAlias = None
51
+ """The presence of a scope whose statements may not execute."""
52
+
53
+ BuildErrorKind: TypeAlias = Literal[
54
+ "scope", "provenance", "redefinition", "unprintable", "binding", "spec"
55
+ ]
56
+
57
+ # Expressions
58
+
59
+ _Int: TypeAlias = int | IntExpr | DynExpr
60
+ _Numeric: TypeAlias = int | float | IntExpr | FloatExpr | NumExpr | DynExpr
61
+ _Operand: TypeAlias = int | float | str | Expr
62
+ _Condition: TypeAlias = int | Expr
63
+
64
+ class _Domain(Protocol[_I_co]):
65
+ """What a comprehension ranges over; its body gets ``_I_co``."""
66
+
67
+ def _iris_item(self, node: Any, /) -> _I_co: ...
68
+
69
+ class Expr:
70
+ """An Iris expression. Operators build larger expressions; ``bool()`` is an
71
+ error, so that a comparison is never taken for a Python condition."""
72
+
73
+ def __bool__(self) -> NoReturn: ...
74
+ def __hash__(self) -> int: ...
75
+ def dynamic(self) -> DynExpr:
76
+ """This expression with no static type, accepted anywhere."""
77
+
78
+ class IntExpr(Expr):
79
+ """An integer expression."""
80
+
81
+ def __add__(self, other: _Int) -> IntExpr: ...
82
+ def __radd__(self, other: int) -> IntExpr: ...
83
+ def __sub__(self, other: _Int) -> IntExpr: ...
84
+ def __rsub__(self, other: int) -> IntExpr: ...
85
+ def __mul__(self, other: _Int) -> IntExpr: ...
86
+ def __rmul__(self, other: int) -> IntExpr: ...
87
+ def __and__(self, other: _Int) -> IntExpr: ...
88
+ def __rand__(self, other: int) -> IntExpr: ...
89
+ def __or__(self, other: _Int) -> IntExpr: ...
90
+ def __ror__(self, other: int) -> IntExpr: ...
91
+ def __lt__(self, other: _Numeric) -> IntExpr: ...
92
+ def __le__(self, other: _Numeric) -> IntExpr: ...
93
+ def __gt__(self, other: _Numeric) -> IntExpr: ...
94
+ def __ge__(self, other: _Numeric) -> IntExpr: ...
95
+ def __eq__(self, other: _Numeric) -> IntExpr: ... # type: ignore[override] # ty: ignore[invalid-method-override]
96
+ def __ne__(self, other: _Numeric) -> IntExpr: ... # type: ignore[override] # ty: ignore[invalid-method-override]
97
+ def __neg__(self) -> IntExpr: ...
98
+ def __invert__(self) -> IntExpr: ...
99
+ def _iris_item(self, node: Any, /) -> IntLookup: ...
100
+
101
+ class FloatExpr(Expr):
102
+ """A float expression."""
103
+
104
+ def __lt__(self, other: _Numeric) -> IntExpr: ...
105
+ def __le__(self, other: _Numeric) -> IntExpr: ...
106
+ def __gt__(self, other: _Numeric) -> IntExpr: ...
107
+ def __ge__(self, other: _Numeric) -> IntExpr: ...
108
+ def __eq__(self, other: _Numeric) -> IntExpr: ... # type: ignore[override] # ty: ignore[invalid-method-override]
109
+ def __ne__(self, other: _Numeric) -> IntExpr: ... # type: ignore[override] # ty: ignore[invalid-method-override]
110
+ def __neg__(self) -> FloatExpr: ...
111
+ def _iris_item(self, node: Any, /) -> FloatLookup: ...
112
+
113
+ class NumExpr(Expr):
114
+ """A ``num`` expression: an int or a float, decided by the data."""
115
+
116
+ def __lt__(self, other: _Numeric) -> IntExpr: ...
117
+ def __le__(self, other: _Numeric) -> IntExpr: ...
118
+ def __gt__(self, other: _Numeric) -> IntExpr: ...
119
+ def __ge__(self, other: _Numeric) -> IntExpr: ...
120
+ def __eq__(self, other: _Numeric) -> IntExpr: ... # type: ignore[override] # ty: ignore[invalid-method-override]
121
+ def __ne__(self, other: _Numeric) -> IntExpr: ... # type: ignore[override] # ty: ignore[invalid-method-override]
122
+ def __neg__(self) -> NumExpr: ...
123
+ def _iris_item(self, node: Any, /) -> NumLookup: ...
124
+
125
+ class StrExpr(Expr):
126
+ """A string expression."""
127
+
128
+ def __eq__(self, other: str | StrExpr | DynExpr) -> IntExpr: ... # type: ignore[override] # ty: ignore[invalid-method-override]
129
+ def __ne__(self, other: str | StrExpr | DynExpr) -> IntExpr: ... # type: ignore[override] # ty: ignore[invalid-method-override]
130
+ def _iris_item(self, node: Any, /) -> StrLookup: ...
131
+
132
+ class _Fields:
133
+ """``field``: a member of the record an expression selects."""
134
+
135
+ @overload
136
+ def field(self, handle: IntField[Any]) -> IntLookup: ...
137
+ @overload
138
+ def field(self, handle: FloatField[Any]) -> FloatLookup: ...
139
+ @overload
140
+ def field(self, handle: NumField[Any]) -> NumLookup: ...
141
+ @overload
142
+ def field(self, handle: StrField[Any]) -> StrLookup: ...
143
+ @overload
144
+ def field(self, handle: DynField) -> DynExpr: ...
145
+
146
+ class DynExpr(_Fields, Expr):
147
+ """An expression with no static type, which every operator accepts."""
148
+
149
+ def __add__(self, other: _Int) -> IntExpr: ...
150
+ def __radd__(self, other: int) -> IntExpr: ...
151
+ def __sub__(self, other: _Int) -> IntExpr: ...
152
+ def __rsub__(self, other: int) -> IntExpr: ...
153
+ def __mul__(self, other: _Int) -> IntExpr: ...
154
+ def __rmul__(self, other: int) -> IntExpr: ...
155
+ def __and__(self, other: _Int) -> IntExpr: ...
156
+ def __rand__(self, other: int) -> IntExpr: ...
157
+ def __or__(self, other: _Int) -> IntExpr: ...
158
+ def __ror__(self, other: int) -> IntExpr: ...
159
+ def __lt__(self, other: _Numeric) -> IntExpr: ...
160
+ def __le__(self, other: _Numeric) -> IntExpr: ...
161
+ def __gt__(self, other: _Numeric) -> IntExpr: ...
162
+ def __ge__(self, other: _Numeric) -> IntExpr: ...
163
+ def __eq__(self, other: _Operand) -> IntExpr: ... # type: ignore[override] # ty: ignore[invalid-method-override]
164
+ def __ne__(self, other: _Operand) -> IntExpr: ... # type: ignore[override] # ty: ignore[invalid-method-override]
165
+ def __neg__(self) -> DynExpr: ...
166
+ def __invert__(self) -> IntExpr: ...
167
+ def __getitem__(self, index: _Int) -> DynExpr: ...
168
+ def _iris_item(self, node: Any, /) -> DynExpr: ...
169
+
170
+ class IntLookup(_Fields, IntExpr):
171
+ """An integer lookup, such as an index or a field: it may be an array."""
172
+
173
+ def __getitem__(self, index: _Int) -> IntLookup: ...
174
+
175
+ class FloatLookup(_Fields, FloatExpr):
176
+ """A float lookup, which may be an array."""
177
+
178
+ def __getitem__(self, index: _Int) -> FloatLookup: ...
179
+
180
+ class NumLookup(_Fields, NumExpr):
181
+ """A ``num`` lookup, which may be an array."""
182
+
183
+ def __getitem__(self, index: _Int) -> NumLookup: ...
184
+
185
+ class StrLookup(_Fields, StrExpr):
186
+ """A string lookup, which may be an array."""
187
+
188
+ def __getitem__(self, index: _Int) -> StrLookup: ...
189
+
190
+ class Field(Expr, Generic[_T_co]):
191
+ """A typed handle: the name of an entry. ``data[handle]`` reads its value,
192
+ of type ``_T_co``.
193
+
194
+ In the builder a handle is an expression; after reading it is a key.
195
+ """
196
+
197
+ @property
198
+ def name(self) -> str:
199
+ """The entry name."""
200
+
201
+ def _iris_key(self) -> tuple[str, str | None, int | None, bool]: ...
202
+
203
+ class IntField(IntLookup, Field[_T_co]):
204
+ """A handle of an integer entry."""
205
+
206
+ class FloatField(FloatLookup, Field[_T_co]):
207
+ """A handle of a float entry."""
208
+
209
+ class NumField(NumLookup, Field[_T_co]):
210
+ """A handle of a ``num`` entry."""
211
+
212
+ class StrField(StrLookup, Field[_T_co]):
213
+ """A handle of a string entry."""
214
+
215
+ class DynField(DynExpr, Field[Value | None]):
216
+ """A handle whose value type or depth is open."""
217
+
218
+ def declared(name: str, kind: type[_F]) -> _F:
219
+ """A handle for the entry ``name`` of a text spec, of the handle type
220
+ ``kind``, such as ``ib.IntField[list[int]]`` or ``ib.DynField``.
221
+
222
+ ``iris gen --lang python SPEC`` prints one per entry. The handle reads data
223
+ as a builder's handle does, but no builder accepts it, since it comes from
224
+ none."""
225
+
226
+ @overload
227
+ def lit(value: int) -> IntExpr: ... # pyright: ignore[reportOverlappingOverload]
228
+ @overload
229
+ def lit(value: float) -> FloatExpr: ...
230
+ @overload
231
+ def lit(value: str) -> StrExpr: ...
232
+ def div(left: _Int, right: _Int) -> IntExpr:
233
+ """``left / right``, Iris integer division."""
234
+
235
+ def rem(left: _Int, right: _Int) -> IntExpr:
236
+ """``left % right``, the Iris remainder."""
237
+
238
+ def pow(base: _Int, exponent: _Int) -> IntExpr:
239
+ """``base ^ exponent``."""
240
+
241
+ # Records and comprehensions
242
+
243
+ class Record:
244
+ """The records of a repeat. ``record[field]`` is the field of the current
245
+ record, ``record.list`` all the records, and a comprehension over a record
246
+ gives its body one record at a time."""
247
+
248
+ @overload
249
+ def __getitem__(self, handle: IntField[Any]) -> IntLookup: ...
250
+ @overload
251
+ def __getitem__(self, handle: FloatField[Any]) -> FloatLookup: ...
252
+ @overload
253
+ def __getitem__(self, handle: NumField[Any]) -> NumLookup: ...
254
+ @overload
255
+ def __getitem__(self, handle: StrField[Any]) -> StrLookup: ...
256
+ @overload
257
+ def __getitem__(self, handle: DynField) -> DynExpr: ...
258
+ @property
259
+ def list(self) -> RecordList:
260
+ """All the records of this repeat, printed as its ``as`` name."""
261
+
262
+ def records(self, inner: Record) -> RecordList:
263
+ """The records of the nested repeat ``inner`` in the current record."""
264
+
265
+ def _iris_item(self, node: Any, /) -> RecordExpr: ...
266
+
267
+ class RecordList:
268
+ """A list of records: all the records of a repeat, or a nested list.
269
+ ``records[i]`` selects one."""
270
+
271
+ def __getitem__(self, index: _Int) -> RecordExpr: ...
272
+ def _iris_item(self, node: Any, /) -> RecordExpr: ...
273
+
274
+ class RecordExpr:
275
+ """One record: selected by index, or a comprehension's variable.
276
+ ``record[field]`` looks up one of its fields."""
277
+
278
+ @overload
279
+ def __getitem__(self, handle: IntField[Any]) -> IntLookup: ...
280
+ @overload
281
+ def __getitem__(self, handle: FloatField[Any]) -> FloatLookup: ...
282
+ @overload
283
+ def __getitem__(self, handle: NumField[Any]) -> NumLookup: ...
284
+ @overload
285
+ def __getitem__(self, handle: StrField[Any]) -> StrLookup: ...
286
+ @overload
287
+ def __getitem__(self, handle: DynField) -> DynExpr: ...
288
+ def at(self, index: _Int) -> RecordExpr:
289
+ """``self[index]``, for a record that is itself a list."""
290
+
291
+ def records(self, inner: Record) -> RecordList:
292
+ """The records of the nested repeat ``inner`` in this record."""
293
+
294
+ class _Over(Generic[_I_co]):
295
+ def _iris_item(self, node: Any, /) -> _I_co: ...
296
+
297
+ def over(domain: _Domain[_I], name: str | None = None) -> _Over[_I]:
298
+ """``domain``, with its comprehension variable printed as ``name``."""
299
+
300
+ def all(domain: _Domain[_I], body: Callable[[_I], _Condition]) -> IntExpr:
301
+ """``all(x in domain: body)``."""
302
+
303
+ def any(domain: _Domain[_I], body: Callable[[_I], _Condition]) -> IntExpr:
304
+ """``any(x in domain: body)``."""
305
+
306
+ @overload
307
+ def sum(domain: _Domain[_I], body: Callable[[_I], _Condition], /) -> IntExpr:
308
+ """``sum(x in domain: body)``."""
309
+
310
+ @overload
311
+ def sum(*arguments: float | Expr) -> IntExpr:
312
+ """``sum(a, b, ...)``."""
313
+
314
+ def count(domain: _Domain[_I], body: Callable[[_I], _Condition] | None = None) -> IntExpr:
315
+ """``count(domain)``, or ``count(x in domain: body)`` given a function."""
316
+
317
+ def size(domain: _Domain[Any]) -> IntExpr:
318
+ """``size(domain)``."""
319
+
320
+ def min(*arguments: float | Expr) -> IntExpr:
321
+ """``min(a, b, ...)``."""
322
+
323
+ def max(*arguments: float | Expr) -> IntExpr:
324
+ """``max(a, b, ...)``."""
325
+
326
+ def distinct(*arguments: float | Expr) -> IntExpr:
327
+ """``distinct(a, b, ...)``."""
328
+
329
+ def defined(name: Expr | Record | RecordList | RecordExpr) -> IntExpr:
330
+ """``defined(name)``: a handle, record, record list or comprehension
331
+ variable. ``defined(record)`` tests the record list."""
332
+
333
+ # Types
334
+
335
+ class Type(Generic[_U]):
336
+ """A reading type, whose parameter is the value it reads, with a list for
337
+ each dimension."""
338
+
339
+ class IntType(Type[_U]):
340
+ """A type that reads integers."""
341
+
342
+ def dim(self, size: _Int) -> IntType[list[_U]]:
343
+ """Add a dimension: ``x[size]: type``."""
344
+
345
+ @overload
346
+ def dims(self, size: _Int, /) -> IntType[list[_U]]: ...
347
+ @overload
348
+ def dims(self, first: _Int, second: _Int, /) -> IntType[list[list[_U]]]: ...
349
+ @overload
350
+ def dims(self, first: _Int, second: _Int, third: _Int, /) -> IntType[list[list[list[_U]]]]: ...
351
+ @overload
352
+ def dims(self, *sizes: _Int) -> IntType[Any]: ...
353
+ def layout(self, layout: _Operand) -> IntType[_U]:
354
+ """``layout expression``: a matrix layout name such as ``"LOWER_COL"``."""
355
+
356
+ def offset(self, offset: _Int) -> IntType[_U]:
357
+ """``offset expression``."""
358
+
359
+ def until(self, end: _Operand | Eol) -> ListReading[IntType[_U]]:
360
+ """A list of this type ending at ``end``: a sentinel, or ``ib.eol``."""
361
+
362
+ class FloatType(Type[_U]):
363
+ """A type that reads floats."""
364
+
365
+ def dim(self, size: _Int) -> FloatType[list[_U]]:
366
+ """Add a dimension: ``x[size]: type``."""
367
+
368
+ @overload
369
+ def dims(self, size: _Int, /) -> FloatType[list[_U]]: ...
370
+ @overload
371
+ def dims(self, first: _Int, second: _Int, /) -> FloatType[list[list[_U]]]: ...
372
+ @overload
373
+ def dims(
374
+ self, first: _Int, second: _Int, third: _Int, /
375
+ ) -> FloatType[list[list[list[_U]]]]: ...
376
+ @overload
377
+ def dims(self, *sizes: _Int) -> FloatType[Any]: ...
378
+ def layout(self, layout: _Operand) -> FloatType[_U]:
379
+ """``layout expression``: a matrix layout name such as ``"LOWER_COL"``."""
380
+
381
+ def offset(self, offset: _Int) -> FloatType[_U]:
382
+ """``offset expression``."""
383
+
384
+ def until(self, end: _Operand | Eol) -> ListReading[FloatType[_U]]:
385
+ """A list of this type ending at ``end``: a sentinel, or ``ib.eol``."""
386
+
387
+ class NumType(Type[_U]):
388
+ """A type that reads ints or floats, decided by the data."""
389
+
390
+ def dim(self, size: _Int) -> NumType[list[_U]]:
391
+ """Add a dimension: ``x[size]: type``."""
392
+
393
+ @overload
394
+ def dims(self, size: _Int, /) -> NumType[list[_U]]: ...
395
+ @overload
396
+ def dims(self, first: _Int, second: _Int, /) -> NumType[list[list[_U]]]: ...
397
+ @overload
398
+ def dims(self, first: _Int, second: _Int, third: _Int, /) -> NumType[list[list[list[_U]]]]: ...
399
+ @overload
400
+ def dims(self, *sizes: _Int) -> NumType[Any]: ...
401
+ def layout(self, layout: _Operand) -> NumType[_U]:
402
+ """``layout expression``: a matrix layout name such as ``"LOWER_COL"``."""
403
+
404
+ def offset(self, offset: _Int) -> NumType[_U]:
405
+ """``offset expression``."""
406
+
407
+ def until(self, end: _Operand | Eol) -> ListReading[NumType[_U]]:
408
+ """A list of this type ending at ``end``: a sentinel, or ``ib.eol``."""
409
+
410
+ class StrType(Type[_U]):
411
+ """A type that reads strings."""
412
+
413
+ def dim(self, size: _Int) -> StrType[list[_U]]:
414
+ """Add a dimension: ``x[size]: type``."""
415
+
416
+ @overload
417
+ def dims(self, size: _Int, /) -> StrType[list[_U]]: ...
418
+ @overload
419
+ def dims(self, first: _Int, second: _Int, /) -> StrType[list[list[_U]]]: ...
420
+ @overload
421
+ def dims(self, first: _Int, second: _Int, third: _Int, /) -> StrType[list[list[list[_U]]]]: ...
422
+ @overload
423
+ def dims(self, *sizes: _Int) -> StrType[Any]: ...
424
+ def layout(self, layout: _Operand) -> StrType[_U]:
425
+ """``layout expression``: a matrix layout name such as ``"LOWER_COL"``."""
426
+
427
+ def offset(self, offset: _Int) -> StrType[_U]:
428
+ """``offset expression``."""
429
+
430
+ def until(self, end: _Operand | Eol) -> ListReading[StrType[_U]]:
431
+ """A list of this type ending at ``end``: a sentinel, or ``ib.eol``."""
432
+
433
+ class Alphabet(IntType[int]):
434
+ """``alphabet "symbols"``: reads each symbol as its index. ``blank``,
435
+ ``strip`` and ``base`` add options in call order."""
436
+
437
+ def blank(self, characters: str) -> Alphabet:
438
+ """``blank "characters"``."""
439
+
440
+ def strip(self, characters: str) -> Alphabet:
441
+ """``strip "characters"``."""
442
+
443
+ def base(self, value: int) -> Alphabet:
444
+ """``base value``."""
445
+
446
+ def alphabet(
447
+ symbols: str,
448
+ *,
449
+ blank: str | None = None,
450
+ strip: str | None = None,
451
+ base: int | None = None,
452
+ ) -> Alphabet:
453
+ """``alphabet "symbols"``, with the options given, in this order."""
454
+
455
+ class ListReading(Generic[_U]):
456
+ """The type and end of a ``list`` statement; the parameter is the type."""
457
+
458
+ def offset(self, offset: _Int) -> ListReading[_U]:
459
+ """``offset expression``, after the list's end."""
460
+
461
+ class Eol:
462
+ """The end-of-line marker of a list."""
463
+
464
+ eol: Eol
465
+ """``until eol``: a list that ends with its line."""
466
+ int_: IntType[int]
467
+ """``int``."""
468
+ float_: FloatType[float]
469
+ """``float``."""
470
+ num: NumType[int | float]
471
+ """``num``: an int or a float, decided by the data."""
472
+ word: StrType[str]
473
+ """``word``: one token."""
474
+ rest: StrType[str]
475
+ """``rest``: the rest of the line."""
476
+
477
+ def int_range(
478
+ lo: _Int | None = None, hi: _Int | None = None, *, below: _Int | None = None
479
+ ) -> IntType[int]:
480
+ """``lo..hi``, both included, or ``lo..<below``. Either end may be left
481
+ out, but not both."""
482
+
483
+ def at_least(lo: _Int) -> IntType[int]:
484
+ """``lo..``, the integers from ``lo`` up."""
485
+
486
+ # Patterns
487
+
488
+ class Part:
489
+ """A part of a pattern other than text or a capture handle."""
490
+
491
+ class Discard:
492
+ """The discard ``_``: a target that reads without storing, and ``{_}`` in
493
+ a pattern."""
494
+
495
+ def discard() -> Discard:
496
+ """``_``: read a value without storing it, or ``{_}`` in a pattern."""
497
+
498
+ def bind(handle: Field[Any], ty: Type[Any] | None = None) -> Part:
499
+ """``{x:type}``, binding a forward or redefined handle; without a type,
500
+ ``{x}``, which reads a word."""
501
+
502
+ def ref(handle: Field[Any]) -> Part:
503
+ """``{$x}``, matching the current value of ``x``."""
504
+
505
+ def validate(ty: Type[Any]) -> Part:
506
+ """``{:type}``, which checks the text without storing it."""
507
+
508
+ def blank() -> Part:
509
+ """``{}``, which matches a word without storing it."""
510
+
511
+ def discard_as(ty: Type[Any]) -> Part:
512
+ """``{_:type}``, a discarded capture with a type."""
513
+
514
+ rest_of_line: Part
515
+ """The trailing ``...`` of a pattern."""
516
+
517
+ _PatternPart: TypeAlias = str | Field[Any] | Part | Discard
518
+
519
+ if sys.version_info >= (3, 14):
520
+ from string.templatelib import Template
521
+
522
+ _Pattern: TypeAlias = str | tuple[_PatternPart, ...] | Template
523
+ else:
524
+ _Pattern: TypeAlias = str | tuple[_PatternPart, ...]
525
+
526
+ # Errors and call sites
527
+
528
+ class BuildError(Exception):
529
+ """Why a reader spec could not be built.
530
+
531
+ ``kind`` names the builder check that failed, or is ``"spec"`` when the
532
+ emitted text failed to parse; then ``error`` is the language error, which
533
+ is also the ``__cause__``. ``str(error)`` shows the language code and
534
+ message, the line of emitted text, and the call site.
535
+ """
536
+
537
+ kind: BuildErrorKind
538
+ """The check that failed: ``scope``, ``provenance``, ``redefinition``,
539
+ ``unprintable``, ``binding``, or ``spec`` for a language error."""
540
+ message: str
541
+ """The message of a builder check, without the call site. For a ``spec``
542
+ error it is the language diagnostic, with its location and excerpt, less
543
+ the call site line."""
544
+ call_site: CallSite | None
545
+ """The host code of the statement that failed."""
546
+ text: str | None
547
+ """The emitted text, when the language rejected it."""
548
+ error: Error | None
549
+ """The language error, when the emitted text was rejected."""
550
+
551
+ def __init__(
552
+ self,
553
+ kind: BuildErrorKind,
554
+ message: str,
555
+ call_site: CallSite | None,
556
+ text: str | None = None,
557
+ error: Error | None = None,
558
+ ) -> None: ...
559
+ @classmethod
560
+ def from_error(cls, error: Error, text: str) -> BuildError:
561
+ """The error for emitted text that the language rejected."""
562
+
563
+ @property
564
+ def emitted_line(self) -> str | None:
565
+ """The line of emitted text that the language error points at."""
566
+
567
+ def track_caller(function: _C) -> _C:
568
+ """Make a helper function report its caller's line as the call site of
569
+ the statements it writes, as builder methods do."""
570
+
571
+ # Scopes and blocks
572
+
573
+ class Block(Generic[_S_co]):
574
+ """The guard of a block statement: ``with`` gives the block's scope. A
575
+ guard that is never entered writes an empty block."""
576
+
577
+ def __enter__(self) -> _S_co: ...
578
+ def __exit__(self, *exception: object) -> None: ...
579
+
580
+ class SectionsGuard(Block[Arms[_R_co, _O_co]], Generic[_R_co, _O_co]):
581
+ """The guard of ``sections``: clauses chain, and ``with`` gives the arms."""
582
+
583
+ def until(
584
+ self, *terminators: str, store: str | Field[Any] | Discard | None = None
585
+ ) -> SectionsGuard[_R_co, _O_co]:
586
+ """``until "text"...``, with ``store x`` keeping the terminator; to read
587
+ it, pass a handle from ``forward``."""
588
+
589
+ def skip_other(self) -> SectionsGuard[_R_co, _O_co]:
590
+ """``skip other``."""
591
+
592
+ class Arms(Generic[_R_co, _O_co]):
593
+ """The block of a ``sections`` statement, which holds only arms: ``_R_co``
594
+ is the scope of a required arm and ``_O_co`` of an optional one."""
595
+
596
+ @overload
597
+ def arm(
598
+ self, pattern: _Pattern, *, optional: Literal[False] = False, last: bool = False
599
+ ) -> ArmGuard[_R_co]: ...
600
+ @overload
601
+ def arm(self, pattern: _Pattern, *, optional: bool, last: bool = False) -> ArmGuard[_O_co]: ...
602
+
603
+ class ArmGuard(Generic[_S_co]):
604
+ """The guard of an arm: ``with`` gives the arm's block."""
605
+
606
+ def __enter__(self) -> _S_co: ...
607
+ def __exit__(self, *exception: object) -> None: ...
608
+
609
+ class Scope(Generic[_N_co]):
610
+ """An open block, with the statements whose types do not depend on its
611
+ depth. A scope accepts statements only while it is the innermost open
612
+ block."""
613
+
614
+ def set(self, handle: Field[Any], value: _Operand) -> None:
615
+ """``let x = value`` through a handle, keeping its type.
616
+
617
+ The value must have the handle's value type and, where both are known,
618
+ its depth. To change either, use ``let`` with the handle as the target,
619
+ which returns a ``DynField``.
620
+ """
621
+
622
+ def check(self, condition: _Condition, message: str | None = None) -> None:
623
+ """``check condition``, with an optional message for when it fails."""
624
+
625
+ def expect(self, *words: str) -> None:
626
+ """``expect "text"...``."""
627
+
628
+ def line(self, pattern: _Pattern) -> None:
629
+ """``line "pattern"``."""
630
+
631
+ def find(self, pattern: _Pattern) -> None:
632
+ """``find "pattern"``."""
633
+
634
+ def skip_line(self) -> None:
635
+ """``skip line``."""
636
+
637
+ def skip_lines(self, count: _Int) -> None:
638
+ """``skip count lines``."""
639
+
640
+ def index(self, position: _Int) -> None:
641
+ """``index position``."""
642
+
643
+ @overload
644
+ def define_type(self, name: str, ty: IntType[_U]) -> IntType[_U]: ...
645
+ @overload
646
+ def define_type(self, name: str, ty: FloatType[_U]) -> FloatType[_U]: ...
647
+ @overload
648
+ def define_type(self, name: str, ty: NumType[_U]) -> NumType[_U]: ...
649
+ @overload
650
+ def define_type(self, name: str, ty: StrType[_U]) -> StrType[_U]: ...
651
+ def forward(self, name: str, kind: type[_F]) -> _F:
652
+ """A handle for a name that a later statement defines, of the handle
653
+ type ``kind``, such as ``ib.IntField[list[int]]`` or ``ib.DynField``."""
654
+
655
+ def undefined(self, name: str) -> DynField:
656
+ """A handle for a name deliberately left undefined."""
657
+
658
+ def forward_record(self, each: str, list: str) -> Record:
659
+ """The record of a repeat that comes later in the text, printed with
660
+ the names given here. Bind it with ``record_as``."""
661
+
662
+ class _Nested(Scope[_N_co]):
663
+ @property
664
+ def record(self) -> Record:
665
+ """The record of the nearest repeat."""
666
+
667
+ def each_name(self, name: str) -> None:
668
+ """Print this repeat's ``each`` name as ``name``, which may be ``_``."""
669
+
670
+ def as_name(self, name: str) -> None:
671
+ """Print this repeat's ``as`` name as ``name``, which may be ``_``."""
672
+
673
+ def record_as(self, record: Record) -> None:
674
+ """Bind this repeat to a record from ``forward_record``."""
675
+
676
+ class Scope0(Scope[_N_co]):
677
+ """A scope outside every repeat. ``_N`` is ``Required`` when its
678
+ statements always execute and ``None`` when they may not."""
679
+
680
+ @overload
681
+ def read(self, target: str, ty: IntType[_U]) -> IntField[_U | _N_co]: ...
682
+ @overload
683
+ def read(self, target: str, ty: FloatType[_U]) -> FloatField[_U | _N_co]: ...
684
+ @overload
685
+ def read(self, target: str, ty: NumType[_U]) -> NumField[_U | _N_co]: ...
686
+ @overload
687
+ def read(self, target: str, ty: StrType[_U]) -> StrField[_U | _N_co]: ...
688
+ @overload
689
+ def read(self, target: Field[Any], ty: Type[Any]) -> DynField: ...
690
+ @overload
691
+ def read(self, target: Discard, ty: Type[Any]) -> None: ...
692
+ @overload
693
+ def else_read_if(self, target: str, ty: IntType[_U]) -> IntField[_U | None]: ...
694
+ @overload
695
+ def else_read_if(self, target: str, ty: FloatType[_U]) -> FloatField[_U | None]: ...
696
+ @overload
697
+ def else_read_if(self, target: str, ty: NumType[_U]) -> NumField[_U | None]: ...
698
+ @overload
699
+ def else_read_if(self, target: str, ty: StrType[_U]) -> StrField[_U | None]: ...
700
+ @overload
701
+ def else_read_if(self, target: Field[Any], ty: Type[Any]) -> DynField: ...
702
+ @overload
703
+ def list(
704
+ self, target: str, reading: ListReading[IntType[_U]]
705
+ ) -> IntField[builtins.list[_U] | _N_co]: ...
706
+ @overload
707
+ def list(
708
+ self, target: str, reading: ListReading[FloatType[_U]]
709
+ ) -> FloatField[builtins.list[_U] | _N_co]: ...
710
+ @overload
711
+ def list(
712
+ self, target: str, reading: ListReading[NumType[_U]]
713
+ ) -> NumField[builtins.list[_U] | _N_co]: ...
714
+ @overload
715
+ def list(
716
+ self, target: str, reading: ListReading[StrType[_U]]
717
+ ) -> StrField[builtins.list[_U] | _N_co]: ...
718
+ @overload
719
+ def list(self, target: Field[Any], reading: ListReading[Any]) -> DynField: ...
720
+ @overload
721
+ def list(self, target: Discard, reading: ListReading[Any]) -> None: ...
722
+ @overload
723
+ def let(self, target: str, value: IntField[_U]) -> IntField[_U | _N_co]: ...
724
+ @overload
725
+ def let(self, target: str, value: IntLookup) -> IntField[Value | _N_co]: ...
726
+ @overload
727
+ def let(self, target: str, value: int | IntExpr) -> IntField[int | _N_co]: ...
728
+ @overload
729
+ def let(self, target: str, value: FloatField[_U]) -> FloatField[_U | _N_co]: ...
730
+ @overload
731
+ def let(self, target: str, value: FloatLookup) -> FloatField[Value | _N_co]: ...
732
+ @overload
733
+ def let(self, target: str, value: float | FloatExpr) -> FloatField[float | _N_co]: ...
734
+ @overload
735
+ def let(self, target: str, value: NumField[_U]) -> NumField[_U | _N_co]: ...
736
+ @overload
737
+ def let(self, target: str, value: NumLookup) -> NumField[Value | _N_co]: ...
738
+ @overload
739
+ def let(self, target: str, value: NumExpr) -> NumField[int | float | _N_co]: ...
740
+ @overload
741
+ def let(self, target: str, value: StrField[_U]) -> StrField[_U | _N_co]: ...
742
+ @overload
743
+ def let(self, target: str, value: StrLookup) -> StrField[Value | _N_co]: ...
744
+ @overload
745
+ def let(self, target: str, value: str | StrExpr) -> StrField[str | _N_co]: ...
746
+ @overload
747
+ def let(self, target: str, value: DynExpr) -> DynField: ...
748
+ @overload
749
+ def let(self, target: Field[Any], value: _Operand) -> DynField: ...
750
+ @overload
751
+ def param(self, target: str | Field[Any]) -> DynField: ...
752
+ @overload
753
+ def param(self, target: str, default: IntLookup) -> IntField[Value | _N_co]: ...
754
+ @overload
755
+ def param(self, target: str, default: int | IntExpr) -> IntField[int | _N_co]: ...
756
+ @overload
757
+ def param(self, target: str, default: FloatLookup) -> FloatField[Value | _N_co]: ...
758
+ @overload
759
+ def param(self, target: str, default: float | FloatExpr) -> FloatField[float | _N_co]: ...
760
+ @overload
761
+ def param(self, target: str, default: NumLookup) -> NumField[Value | _N_co]: ...
762
+ @overload
763
+ def param(self, target: str, default: NumExpr) -> NumField[int | float | _N_co]: ...
764
+ @overload
765
+ def param(self, target: str, default: StrLookup) -> StrField[Value | _N_co]: ...
766
+ @overload
767
+ def param(self, target: str, default: str | StrExpr) -> StrField[str | _N_co]: ...
768
+ @overload
769
+ def param(self, target: str, default: DynExpr) -> DynField: ...
770
+ @overload
771
+ def param(self, target: Field[Any], default: _Operand) -> DynField: ...
772
+ @overload
773
+ def capture(self, name: str, ty: None = None) -> StrField[str | _N_co]: ...
774
+ @overload
775
+ def capture(self, name: str, ty: IntType[_U]) -> IntField[_U | _N_co]: ...
776
+ @overload
777
+ def capture(self, name: str, ty: FloatType[_U]) -> FloatField[_U | _N_co]: ...
778
+ @overload
779
+ def capture(self, name: str, ty: NumType[_U]) -> NumField[_U | _N_co]: ...
780
+ @overload
781
+ def capture(self, name: str, ty: StrType[_U]) -> StrField[_U | _N_co]: ...
782
+ @overload
783
+ def optional_capture(self, name: str, ty: None = None) -> StrField[str | None]: ...
784
+ @overload
785
+ def optional_capture(self, name: str, ty: IntType[_U]) -> IntField[_U | None]: ...
786
+ @overload
787
+ def optional_capture(self, name: str, ty: FloatType[_U]) -> FloatField[_U | None]: ...
788
+ @overload
789
+ def optional_capture(self, name: str, ty: NumType[_U]) -> NumField[_U | None]: ...
790
+ @overload
791
+ def optional_capture(self, name: str, ty: StrType[_U]) -> StrField[_U | None]: ...
792
+ def repeat(self, count: _Int) -> Block[Scope1[_N_co]]: ...
793
+ def repeat_until_eof(self) -> Block[Scope1[_N_co]]: ...
794
+ def repeat_until(
795
+ self, *terminators: str, store: str | Field[Any] | Discard | None = None
796
+ ) -> Block[Scope1[_N_co]]: ...
797
+ def sections(
798
+ self,
799
+ *,
800
+ until: str | tuple[str, ...] = (),
801
+ skip_other: bool = False,
802
+ store: str | Field[Any] | Discard | None = None,
803
+ ) -> SectionsGuard[Scope0[_N_co], Scope0[None]]: ...
804
+ def if_(self, condition: _Condition) -> Block[Scope0[None]]: ...
805
+ def else_if(self, condition: _Condition) -> Block[Scope0[None]]: ...
806
+ def else_(self) -> Block[Scope0[None]]: ...
807
+
808
+ class Scope1(_Nested[_N_co]):
809
+ """A scope inside one repeat: its definitions are lists."""
810
+
811
+ @overload
812
+ def read(self, target: str, ty: IntType[_U]) -> IntField[builtins.list[_U] | _N_co]: ...
813
+ @overload
814
+ def read(self, target: str, ty: FloatType[_U]) -> FloatField[builtins.list[_U] | _N_co]: ...
815
+ @overload
816
+ def read(self, target: str, ty: NumType[_U]) -> NumField[builtins.list[_U] | _N_co]: ...
817
+ @overload
818
+ def read(self, target: str, ty: StrType[_U]) -> StrField[builtins.list[_U] | _N_co]: ...
819
+ @overload
820
+ def read(self, target: Field[Any], ty: Type[Any]) -> DynField: ...
821
+ @overload
822
+ def read(self, target: Discard, ty: Type[Any]) -> None: ...
823
+ @overload
824
+ def else_read_if(self, target: str, ty: IntType[_U]) -> IntField[builtins.list[_U] | None]: ...
825
+ @overload
826
+ def else_read_if(
827
+ self, target: str, ty: FloatType[_U]
828
+ ) -> FloatField[builtins.list[_U] | None]: ...
829
+ @overload
830
+ def else_read_if(self, target: str, ty: NumType[_U]) -> NumField[builtins.list[_U] | None]: ...
831
+ @overload
832
+ def else_read_if(self, target: str, ty: StrType[_U]) -> StrField[builtins.list[_U] | None]: ...
833
+ @overload
834
+ def else_read_if(self, target: Field[Any], ty: Type[Any]) -> DynField: ...
835
+ @overload
836
+ def list(
837
+ self, target: str, reading: ListReading[IntType[_U]]
838
+ ) -> IntField[builtins.list[builtins.list[_U]] | _N_co]: ...
839
+ @overload
840
+ def list(
841
+ self, target: str, reading: ListReading[FloatType[_U]]
842
+ ) -> FloatField[builtins.list[builtins.list[_U]] | _N_co]: ...
843
+ @overload
844
+ def list(
845
+ self, target: str, reading: ListReading[NumType[_U]]
846
+ ) -> NumField[builtins.list[builtins.list[_U]] | _N_co]: ...
847
+ @overload
848
+ def list(
849
+ self, target: str, reading: ListReading[StrType[_U]]
850
+ ) -> StrField[builtins.list[builtins.list[_U]] | _N_co]: ...
851
+ @overload
852
+ def list(self, target: Field[Any], reading: ListReading[Any]) -> DynField: ...
853
+ @overload
854
+ def list(self, target: Discard, reading: ListReading[Any]) -> None: ...
855
+ @overload
856
+ def let(self, target: str, value: IntLookup) -> IntField[Value | _N_co]: ...
857
+ @overload
858
+ def let(self, target: str, value: int | IntExpr) -> IntField[builtins.list[int] | _N_co]: ...
859
+ @overload
860
+ def let(self, target: str, value: FloatLookup) -> FloatField[Value | _N_co]: ...
861
+ @overload
862
+ def let(
863
+ self, target: str, value: float | FloatExpr
864
+ ) -> FloatField[builtins.list[float] | _N_co]: ...
865
+ @overload
866
+ def let(self, target: str, value: NumLookup) -> NumField[Value | _N_co]: ...
867
+ @overload
868
+ def let(self, target: str, value: NumExpr) -> NumField[builtins.list[int | float] | _N_co]: ...
869
+ @overload
870
+ def let(self, target: str, value: StrLookup) -> StrField[Value | _N_co]: ...
871
+ @overload
872
+ def let(self, target: str, value: str | StrExpr) -> StrField[builtins.list[str] | _N_co]: ...
873
+ @overload
874
+ def let(self, target: str, value: DynExpr) -> DynField: ...
875
+ @overload
876
+ def let(self, target: Field[Any], value: _Operand) -> DynField: ...
877
+ @overload
878
+ def param(self, target: str | Field[Any]) -> DynField: ...
879
+ @overload
880
+ def param(self, target: str, default: IntLookup) -> IntField[Value | _N_co]: ...
881
+ @overload
882
+ def param(
883
+ self, target: str, default: int | IntExpr
884
+ ) -> IntField[builtins.list[int] | _N_co]: ...
885
+ @overload
886
+ def param(self, target: str, default: FloatLookup) -> FloatField[Value | _N_co]: ...
887
+ @overload
888
+ def param(
889
+ self, target: str, default: float | FloatExpr
890
+ ) -> FloatField[builtins.list[float] | _N_co]: ...
891
+ @overload
892
+ def param(self, target: str, default: NumLookup) -> NumField[Value | _N_co]: ...
893
+ @overload
894
+ def param(
895
+ self, target: str, default: NumExpr
896
+ ) -> NumField[builtins.list[int | float] | _N_co]: ...
897
+ @overload
898
+ def param(self, target: str, default: StrLookup) -> StrField[Value | _N_co]: ...
899
+ @overload
900
+ def param(
901
+ self, target: str, default: str | StrExpr
902
+ ) -> StrField[builtins.list[str] | _N_co]: ...
903
+ @overload
904
+ def param(self, target: str, default: DynExpr) -> DynField: ...
905
+ @overload
906
+ def param(self, target: Field[Any], default: _Operand) -> DynField: ...
907
+ @overload
908
+ def capture(self, name: str, ty: None = None) -> StrField[builtins.list[str] | _N_co]: ...
909
+ @overload
910
+ def capture(self, name: str, ty: IntType[_U]) -> IntField[builtins.list[_U] | _N_co]: ...
911
+ @overload
912
+ def capture(self, name: str, ty: FloatType[_U]) -> FloatField[builtins.list[_U] | _N_co]: ...
913
+ @overload
914
+ def capture(self, name: str, ty: NumType[_U]) -> NumField[builtins.list[_U] | _N_co]: ...
915
+ @overload
916
+ def capture(self, name: str, ty: StrType[_U]) -> StrField[builtins.list[_U] | _N_co]: ...
917
+ @overload
918
+ def optional_capture(
919
+ self, name: str, ty: None = None
920
+ ) -> StrField[builtins.list[str] | None]: ...
921
+ @overload
922
+ def optional_capture(
923
+ self, name: str, ty: IntType[_U]
924
+ ) -> IntField[builtins.list[_U] | None]: ...
925
+ @overload
926
+ def optional_capture(
927
+ self, name: str, ty: FloatType[_U]
928
+ ) -> FloatField[builtins.list[_U] | None]: ...
929
+ @overload
930
+ def optional_capture(
931
+ self, name: str, ty: NumType[_U]
932
+ ) -> NumField[builtins.list[_U] | None]: ...
933
+ @overload
934
+ def optional_capture(
935
+ self, name: str, ty: StrType[_U]
936
+ ) -> StrField[builtins.list[_U] | None]: ...
937
+ def repeat(self, count: _Int) -> Block[Scope2[_N_co]]: ...
938
+ def repeat_until_eof(self) -> Block[Scope2[_N_co]]: ...
939
+ def repeat_until(
940
+ self, *terminators: str, store: str | Field[Any] | Discard | None = None
941
+ ) -> Block[Scope2[_N_co]]: ...
942
+ def sections(
943
+ self,
944
+ *,
945
+ until: str | tuple[str, ...] = (),
946
+ skip_other: bool = False,
947
+ store: str | Field[Any] | Discard | None = None,
948
+ ) -> SectionsGuard[Scope1[_N_co], Scope1[None]]: ...
949
+ def if_(self, condition: _Condition) -> Block[Scope1[None]]: ...
950
+ def else_if(self, condition: _Condition) -> Block[Scope1[None]]: ...
951
+ def else_(self) -> Block[Scope1[None]]: ...
952
+
953
+ class Scope2(_Nested[_N_co]):
954
+ """A scope inside two repeats."""
955
+
956
+ @overload
957
+ def read(
958
+ self, target: str, ty: IntType[_U]
959
+ ) -> IntField[builtins.list[builtins.list[_U]] | _N_co]: ...
960
+ @overload
961
+ def read(
962
+ self, target: str, ty: FloatType[_U]
963
+ ) -> FloatField[builtins.list[builtins.list[_U]] | _N_co]: ...
964
+ @overload
965
+ def read(
966
+ self, target: str, ty: NumType[_U]
967
+ ) -> NumField[builtins.list[builtins.list[_U]] | _N_co]: ...
968
+ @overload
969
+ def read(
970
+ self, target: str, ty: StrType[_U]
971
+ ) -> StrField[builtins.list[builtins.list[_U]] | _N_co]: ...
972
+ @overload
973
+ def read(self, target: Field[Any], ty: Type[Any]) -> DynField: ...
974
+ @overload
975
+ def read(self, target: Discard, ty: Type[Any]) -> None: ...
976
+ @overload
977
+ def else_read_if(
978
+ self, target: str, ty: IntType[_U]
979
+ ) -> IntField[builtins.list[builtins.list[_U]] | None]: ...
980
+ @overload
981
+ def else_read_if(
982
+ self, target: str, ty: FloatType[_U]
983
+ ) -> FloatField[builtins.list[builtins.list[_U]] | None]: ...
984
+ @overload
985
+ def else_read_if(
986
+ self, target: str, ty: NumType[_U]
987
+ ) -> NumField[builtins.list[builtins.list[_U]] | None]: ...
988
+ @overload
989
+ def else_read_if(
990
+ self, target: str, ty: StrType[_U]
991
+ ) -> StrField[builtins.list[builtins.list[_U]] | None]: ...
992
+ @overload
993
+ def else_read_if(self, target: Field[Any], ty: Type[Any]) -> DynField: ...
994
+ @overload
995
+ def list(
996
+ self, target: str, reading: ListReading[IntType[_U]]
997
+ ) -> IntField[builtins.list[builtins.list[builtins.list[_U]]] | _N_co]: ...
998
+ @overload
999
+ def list(
1000
+ self, target: str, reading: ListReading[FloatType[_U]]
1001
+ ) -> FloatField[builtins.list[builtins.list[builtins.list[_U]]] | _N_co]: ...
1002
+ @overload
1003
+ def list(
1004
+ self, target: str, reading: ListReading[NumType[_U]]
1005
+ ) -> NumField[builtins.list[builtins.list[builtins.list[_U]]] | _N_co]: ...
1006
+ @overload
1007
+ def list(
1008
+ self, target: str, reading: ListReading[StrType[_U]]
1009
+ ) -> StrField[builtins.list[builtins.list[builtins.list[_U]]] | _N_co]: ...
1010
+ @overload
1011
+ def list(self, target: Field[Any], reading: ListReading[Any]) -> DynField: ...
1012
+ @overload
1013
+ def list(self, target: Discard, reading: ListReading[Any]) -> None: ...
1014
+ @overload
1015
+ def let(self, target: str, value: IntLookup) -> IntField[Value | _N_co]: ...
1016
+ @overload
1017
+ def let(
1018
+ self, target: str, value: int | IntExpr
1019
+ ) -> IntField[builtins.list[builtins.list[int]] | _N_co]: ...
1020
+ @overload
1021
+ def let(self, target: str, value: FloatLookup) -> FloatField[Value | _N_co]: ...
1022
+ @overload
1023
+ def let(
1024
+ self, target: str, value: float | FloatExpr
1025
+ ) -> FloatField[builtins.list[builtins.list[float]] | _N_co]: ...
1026
+ @overload
1027
+ def let(self, target: str, value: NumLookup) -> NumField[Value | _N_co]: ...
1028
+ @overload
1029
+ def let(
1030
+ self, target: str, value: NumExpr
1031
+ ) -> NumField[builtins.list[builtins.list[int | float]] | _N_co]: ...
1032
+ @overload
1033
+ def let(self, target: str, value: StrLookup) -> StrField[Value | _N_co]: ...
1034
+ @overload
1035
+ def let(
1036
+ self, target: str, value: str | StrExpr
1037
+ ) -> StrField[builtins.list[builtins.list[str]] | _N_co]: ...
1038
+ @overload
1039
+ def let(self, target: str, value: DynExpr) -> DynField: ...
1040
+ @overload
1041
+ def let(self, target: Field[Any], value: _Operand) -> DynField: ...
1042
+ @overload
1043
+ def param(self, target: str | Field[Any]) -> DynField: ...
1044
+ @overload
1045
+ def param(self, target: str, default: IntLookup) -> IntField[Value | _N_co]: ...
1046
+ @overload
1047
+ def param(
1048
+ self, target: str, default: int | IntExpr
1049
+ ) -> IntField[builtins.list[builtins.list[int]] | _N_co]: ...
1050
+ @overload
1051
+ def param(self, target: str, default: FloatLookup) -> FloatField[Value | _N_co]: ...
1052
+ @overload
1053
+ def param(
1054
+ self, target: str, default: float | FloatExpr
1055
+ ) -> FloatField[builtins.list[builtins.list[float]] | _N_co]: ...
1056
+ @overload
1057
+ def param(self, target: str, default: NumLookup) -> NumField[Value | _N_co]: ...
1058
+ @overload
1059
+ def param(
1060
+ self, target: str, default: NumExpr
1061
+ ) -> NumField[builtins.list[builtins.list[int | float]] | _N_co]: ...
1062
+ @overload
1063
+ def param(self, target: str, default: StrLookup) -> StrField[Value | _N_co]: ...
1064
+ @overload
1065
+ def param(
1066
+ self, target: str, default: str | StrExpr
1067
+ ) -> StrField[builtins.list[builtins.list[str]] | _N_co]: ...
1068
+ @overload
1069
+ def param(self, target: str, default: DynExpr) -> DynField: ...
1070
+ @overload
1071
+ def param(self, target: Field[Any], default: _Operand) -> DynField: ...
1072
+ @overload
1073
+ def capture(
1074
+ self, name: str, ty: None = None
1075
+ ) -> StrField[builtins.list[builtins.list[str]] | _N_co]: ...
1076
+ @overload
1077
+ def capture(
1078
+ self, name: str, ty: IntType[_U]
1079
+ ) -> IntField[builtins.list[builtins.list[_U]] | _N_co]: ...
1080
+ @overload
1081
+ def capture(
1082
+ self, name: str, ty: FloatType[_U]
1083
+ ) -> FloatField[builtins.list[builtins.list[_U]] | _N_co]: ...
1084
+ @overload
1085
+ def capture(
1086
+ self, name: str, ty: NumType[_U]
1087
+ ) -> NumField[builtins.list[builtins.list[_U]] | _N_co]: ...
1088
+ @overload
1089
+ def capture(
1090
+ self, name: str, ty: StrType[_U]
1091
+ ) -> StrField[builtins.list[builtins.list[_U]] | _N_co]: ...
1092
+ @overload
1093
+ def optional_capture(
1094
+ self, name: str, ty: None = None
1095
+ ) -> StrField[builtins.list[builtins.list[str]] | None]: ...
1096
+ @overload
1097
+ def optional_capture(
1098
+ self, name: str, ty: IntType[_U]
1099
+ ) -> IntField[builtins.list[builtins.list[_U]] | None]: ...
1100
+ @overload
1101
+ def optional_capture(
1102
+ self, name: str, ty: FloatType[_U]
1103
+ ) -> FloatField[builtins.list[builtins.list[_U]] | None]: ...
1104
+ @overload
1105
+ def optional_capture(
1106
+ self, name: str, ty: NumType[_U]
1107
+ ) -> NumField[builtins.list[builtins.list[_U]] | None]: ...
1108
+ @overload
1109
+ def optional_capture(
1110
+ self, name: str, ty: StrType[_U]
1111
+ ) -> StrField[builtins.list[builtins.list[_U]] | None]: ...
1112
+ def repeat(self, count: _Int) -> Block[Scope3[_N_co]]: ...
1113
+ def repeat_until_eof(self) -> Block[Scope3[_N_co]]: ...
1114
+ def repeat_until(
1115
+ self, *terminators: str, store: str | Field[Any] | Discard | None = None
1116
+ ) -> Block[Scope3[_N_co]]: ...
1117
+ def sections(
1118
+ self,
1119
+ *,
1120
+ until: str | tuple[str, ...] = (),
1121
+ skip_other: bool = False,
1122
+ store: str | Field[Any] | Discard | None = None,
1123
+ ) -> SectionsGuard[Scope2[_N_co], Scope2[None]]: ...
1124
+ def if_(self, condition: _Condition) -> Block[Scope2[None]]: ...
1125
+ def else_if(self, condition: _Condition) -> Block[Scope2[None]]: ...
1126
+ def else_(self) -> Block[Scope2[None]]: ...
1127
+
1128
+ class Scope3(_Nested[_N_co]):
1129
+ """A scope inside three repeats, the deepest with typed handles."""
1130
+
1131
+ @overload
1132
+ def read(
1133
+ self, target: str, ty: IntType[_U]
1134
+ ) -> IntField[builtins.list[builtins.list[builtins.list[_U]]] | _N_co]: ...
1135
+ @overload
1136
+ def read(
1137
+ self, target: str, ty: FloatType[_U]
1138
+ ) -> FloatField[builtins.list[builtins.list[builtins.list[_U]]] | _N_co]: ...
1139
+ @overload
1140
+ def read(
1141
+ self, target: str, ty: NumType[_U]
1142
+ ) -> NumField[builtins.list[builtins.list[builtins.list[_U]]] | _N_co]: ...
1143
+ @overload
1144
+ def read(
1145
+ self, target: str, ty: StrType[_U]
1146
+ ) -> StrField[builtins.list[builtins.list[builtins.list[_U]]] | _N_co]: ...
1147
+ @overload
1148
+ def read(self, target: Field[Any], ty: Type[Any]) -> DynField: ...
1149
+ @overload
1150
+ def read(self, target: Discard, ty: Type[Any]) -> None: ...
1151
+ @overload
1152
+ def else_read_if(
1153
+ self, target: str, ty: IntType[_U]
1154
+ ) -> IntField[builtins.list[builtins.list[builtins.list[_U]]] | None]: ...
1155
+ @overload
1156
+ def else_read_if(
1157
+ self, target: str, ty: FloatType[_U]
1158
+ ) -> FloatField[builtins.list[builtins.list[builtins.list[_U]]] | None]: ...
1159
+ @overload
1160
+ def else_read_if(
1161
+ self, target: str, ty: NumType[_U]
1162
+ ) -> NumField[builtins.list[builtins.list[builtins.list[_U]]] | None]: ...
1163
+ @overload
1164
+ def else_read_if(
1165
+ self, target: str, ty: StrType[_U]
1166
+ ) -> StrField[builtins.list[builtins.list[builtins.list[_U]]] | None]: ...
1167
+ @overload
1168
+ def else_read_if(self, target: Field[Any], ty: Type[Any]) -> DynField: ...
1169
+ @overload
1170
+ def list(
1171
+ self, target: str, reading: ListReading[IntType[_U]]
1172
+ ) -> IntField[builtins.list[builtins.list[builtins.list[builtins.list[_U]]]] | _N_co]: ...
1173
+ @overload
1174
+ def list(
1175
+ self, target: str, reading: ListReading[FloatType[_U]]
1176
+ ) -> FloatField[builtins.list[builtins.list[builtins.list[builtins.list[_U]]]] | _N_co]: ...
1177
+ @overload
1178
+ def list(
1179
+ self, target: str, reading: ListReading[NumType[_U]]
1180
+ ) -> NumField[builtins.list[builtins.list[builtins.list[builtins.list[_U]]]] | _N_co]: ...
1181
+ @overload
1182
+ def list(
1183
+ self, target: str, reading: ListReading[StrType[_U]]
1184
+ ) -> StrField[builtins.list[builtins.list[builtins.list[builtins.list[_U]]]] | _N_co]: ...
1185
+ @overload
1186
+ def list(self, target: Field[Any], reading: ListReading[Any]) -> DynField: ...
1187
+ @overload
1188
+ def list(self, target: Discard, reading: ListReading[Any]) -> None: ...
1189
+ @overload
1190
+ def let(self, target: str, value: IntLookup) -> IntField[Value | _N_co]: ...
1191
+ @overload
1192
+ def let(
1193
+ self, target: str, value: int | IntExpr
1194
+ ) -> IntField[builtins.list[builtins.list[builtins.list[int]]] | _N_co]: ...
1195
+ @overload
1196
+ def let(self, target: str, value: FloatLookup) -> FloatField[Value | _N_co]: ...
1197
+ @overload
1198
+ def let(
1199
+ self, target: str, value: float | FloatExpr
1200
+ ) -> FloatField[builtins.list[builtins.list[builtins.list[float]]] | _N_co]: ...
1201
+ @overload
1202
+ def let(self, target: str, value: NumLookup) -> NumField[Value | _N_co]: ...
1203
+ @overload
1204
+ def let(
1205
+ self, target: str, value: NumExpr
1206
+ ) -> NumField[builtins.list[builtins.list[builtins.list[int | float]]] | _N_co]: ...
1207
+ @overload
1208
+ def let(self, target: str, value: StrLookup) -> StrField[Value | _N_co]: ...
1209
+ @overload
1210
+ def let(
1211
+ self, target: str, value: str | StrExpr
1212
+ ) -> StrField[builtins.list[builtins.list[builtins.list[str]]] | _N_co]: ...
1213
+ @overload
1214
+ def let(self, target: str, value: DynExpr) -> DynField: ...
1215
+ @overload
1216
+ def let(self, target: Field[Any], value: _Operand) -> DynField: ...
1217
+ @overload
1218
+ def param(self, target: str | Field[Any]) -> DynField: ...
1219
+ @overload
1220
+ def param(self, target: str, default: IntLookup) -> IntField[Value | _N_co]: ...
1221
+ @overload
1222
+ def param(
1223
+ self, target: str, default: int | IntExpr
1224
+ ) -> IntField[builtins.list[builtins.list[builtins.list[int]]] | _N_co]: ...
1225
+ @overload
1226
+ def param(self, target: str, default: FloatLookup) -> FloatField[Value | _N_co]: ...
1227
+ @overload
1228
+ def param(
1229
+ self, target: str, default: float | FloatExpr
1230
+ ) -> FloatField[builtins.list[builtins.list[builtins.list[float]]] | _N_co]: ...
1231
+ @overload
1232
+ def param(self, target: str, default: NumLookup) -> NumField[Value | _N_co]: ...
1233
+ @overload
1234
+ def param(
1235
+ self, target: str, default: NumExpr
1236
+ ) -> NumField[builtins.list[builtins.list[builtins.list[int | float]]] | _N_co]: ...
1237
+ @overload
1238
+ def param(self, target: str, default: StrLookup) -> StrField[Value | _N_co]: ...
1239
+ @overload
1240
+ def param(
1241
+ self, target: str, default: str | StrExpr
1242
+ ) -> StrField[builtins.list[builtins.list[builtins.list[str]]] | _N_co]: ...
1243
+ @overload
1244
+ def param(self, target: str, default: DynExpr) -> DynField: ...
1245
+ @overload
1246
+ def param(self, target: Field[Any], default: _Operand) -> DynField: ...
1247
+ @overload
1248
+ def capture(
1249
+ self, name: str, ty: None = None
1250
+ ) -> StrField[builtins.list[builtins.list[builtins.list[str]]] | _N_co]: ...
1251
+ @overload
1252
+ def capture(
1253
+ self, name: str, ty: IntType[_U]
1254
+ ) -> IntField[builtins.list[builtins.list[builtins.list[_U]]] | _N_co]: ...
1255
+ @overload
1256
+ def capture(
1257
+ self, name: str, ty: FloatType[_U]
1258
+ ) -> FloatField[builtins.list[builtins.list[builtins.list[_U]]] | _N_co]: ...
1259
+ @overload
1260
+ def capture(
1261
+ self, name: str, ty: NumType[_U]
1262
+ ) -> NumField[builtins.list[builtins.list[builtins.list[_U]]] | _N_co]: ...
1263
+ @overload
1264
+ def capture(
1265
+ self, name: str, ty: StrType[_U]
1266
+ ) -> StrField[builtins.list[builtins.list[builtins.list[_U]]] | _N_co]: ...
1267
+ @overload
1268
+ def optional_capture(
1269
+ self, name: str, ty: None = None
1270
+ ) -> StrField[builtins.list[builtins.list[builtins.list[str]]] | None]: ...
1271
+ @overload
1272
+ def optional_capture(
1273
+ self, name: str, ty: IntType[_U]
1274
+ ) -> IntField[builtins.list[builtins.list[builtins.list[_U]]] | None]: ...
1275
+ @overload
1276
+ def optional_capture(
1277
+ self, name: str, ty: FloatType[_U]
1278
+ ) -> FloatField[builtins.list[builtins.list[builtins.list[_U]]] | None]: ...
1279
+ @overload
1280
+ def optional_capture(
1281
+ self, name: str, ty: NumType[_U]
1282
+ ) -> NumField[builtins.list[builtins.list[builtins.list[_U]]] | None]: ...
1283
+ @overload
1284
+ def optional_capture(
1285
+ self, name: str, ty: StrType[_U]
1286
+ ) -> StrField[builtins.list[builtins.list[builtins.list[_U]]] | None]: ...
1287
+ def repeat(self, count: _Int) -> Block[ScopeN[_N_co]]: ...
1288
+ def repeat_until_eof(self) -> Block[ScopeN[_N_co]]: ...
1289
+ def repeat_until(
1290
+ self, *terminators: str, store: str | Field[Any] | Discard | None = None
1291
+ ) -> Block[ScopeN[_N_co]]: ...
1292
+ def sections(
1293
+ self,
1294
+ *,
1295
+ until: str | tuple[str, ...] = (),
1296
+ skip_other: bool = False,
1297
+ store: str | Field[Any] | Discard | None = None,
1298
+ ) -> SectionsGuard[Scope3[_N_co], Scope3[None]]: ...
1299
+ def if_(self, condition: _Condition) -> Block[Scope3[None]]: ...
1300
+ def else_if(self, condition: _Condition) -> Block[Scope3[None]]: ...
1301
+ def else_(self) -> Block[Scope3[None]]: ...
1302
+
1303
+ class ScopeN(_Nested[_N_co]):
1304
+ """A scope inside more repeats than handles can type: its definitions
1305
+ give ``DynField``, and dimensions still nest."""
1306
+
1307
+ @overload
1308
+ def read(self, target: str, ty: IntType[_U]) -> DynField: ...
1309
+ @overload
1310
+ def read(self, target: str, ty: FloatType[_U]) -> DynField: ...
1311
+ @overload
1312
+ def read(self, target: str, ty: NumType[_U]) -> DynField: ...
1313
+ @overload
1314
+ def read(self, target: str, ty: StrType[_U]) -> DynField: ...
1315
+ @overload
1316
+ def read(self, target: Field[Any], ty: Type[Any]) -> DynField: ...
1317
+ @overload
1318
+ def read(self, target: Discard, ty: Type[Any]) -> None: ...
1319
+ @overload
1320
+ def else_read_if(self, target: str, ty: IntType[_U]) -> DynField: ...
1321
+ @overload
1322
+ def else_read_if(self, target: str, ty: FloatType[_U]) -> DynField: ...
1323
+ @overload
1324
+ def else_read_if(self, target: str, ty: NumType[_U]) -> DynField: ...
1325
+ @overload
1326
+ def else_read_if(self, target: str, ty: StrType[_U]) -> DynField: ...
1327
+ @overload
1328
+ def else_read_if(self, target: Field[Any], ty: Type[Any]) -> DynField: ...
1329
+ @overload
1330
+ def list(self, target: str, reading: ListReading[IntType[_U]]) -> DynField: ...
1331
+ @overload
1332
+ def list(self, target: str, reading: ListReading[FloatType[_U]]) -> DynField: ...
1333
+ @overload
1334
+ def list(self, target: str, reading: ListReading[NumType[_U]]) -> DynField: ...
1335
+ @overload
1336
+ def list(self, target: str, reading: ListReading[StrType[_U]]) -> DynField: ...
1337
+ @overload
1338
+ def list(self, target: Field[Any], reading: ListReading[Any]) -> DynField: ...
1339
+ @overload
1340
+ def list(self, target: Discard, reading: ListReading[Any]) -> None: ...
1341
+ @overload
1342
+ def let(self, target: str, value: int | IntExpr) -> DynField: ...
1343
+ @overload
1344
+ def let(self, target: str, value: float | FloatExpr) -> DynField: ...
1345
+ @overload
1346
+ def let(self, target: str, value: NumExpr) -> DynField: ...
1347
+ @overload
1348
+ def let(self, target: str, value: str | StrExpr) -> DynField: ...
1349
+ @overload
1350
+ def let(self, target: str, value: DynExpr) -> DynField: ...
1351
+ @overload
1352
+ def let(self, target: Field[Any], value: _Operand) -> DynField: ...
1353
+ @overload
1354
+ def param(self, target: str | Field[Any]) -> DynField: ...
1355
+ @overload
1356
+ def param(self, target: str, default: int | IntExpr) -> DynField: ...
1357
+ @overload
1358
+ def param(self, target: str, default: float | FloatExpr) -> DynField: ...
1359
+ @overload
1360
+ def param(self, target: str, default: NumExpr) -> DynField: ...
1361
+ @overload
1362
+ def param(self, target: str, default: str | StrExpr) -> DynField: ...
1363
+ @overload
1364
+ def param(self, target: str, default: DynExpr) -> DynField: ...
1365
+ @overload
1366
+ def param(self, target: Field[Any], default: _Operand) -> DynField: ...
1367
+ @overload
1368
+ def capture(self, name: str, ty: None = None) -> DynField: ...
1369
+ @overload
1370
+ def capture(self, name: str, ty: IntType[_U]) -> DynField: ...
1371
+ @overload
1372
+ def capture(self, name: str, ty: FloatType[_U]) -> DynField: ...
1373
+ @overload
1374
+ def capture(self, name: str, ty: NumType[_U]) -> DynField: ...
1375
+ @overload
1376
+ def capture(self, name: str, ty: StrType[_U]) -> DynField: ...
1377
+ @overload
1378
+ def optional_capture(self, name: str, ty: None = None) -> DynField: ...
1379
+ @overload
1380
+ def optional_capture(self, name: str, ty: IntType[_U]) -> DynField: ...
1381
+ @overload
1382
+ def optional_capture(self, name: str, ty: FloatType[_U]) -> DynField: ...
1383
+ @overload
1384
+ def optional_capture(self, name: str, ty: NumType[_U]) -> DynField: ...
1385
+ @overload
1386
+ def optional_capture(self, name: str, ty: StrType[_U]) -> DynField: ...
1387
+ def repeat(self, count: _Int) -> Block[ScopeN[_N_co]]: ...
1388
+ def repeat_until_eof(self) -> Block[ScopeN[_N_co]]: ...
1389
+ def repeat_until(
1390
+ self, *terminators: str, store: str | Field[Any] | Discard | None = None
1391
+ ) -> Block[ScopeN[_N_co]]: ...
1392
+ def sections(
1393
+ self,
1394
+ *,
1395
+ until: str | tuple[str, ...] = (),
1396
+ skip_other: bool = False,
1397
+ store: str | Field[Any] | Discard | None = None,
1398
+ ) -> SectionsGuard[ScopeN[_N_co], ScopeN[None]]: ...
1399
+ def if_(self, condition: _Condition) -> Block[ScopeN[None]]: ...
1400
+ def else_if(self, condition: _Condition) -> Block[ScopeN[None]]: ...
1401
+ def else_(self) -> Block[ScopeN[None]]: ...
1402
+
1403
+ class SpecBuilder(Scope0[Required]):
1404
+ """Builds a reader spec. It is the root scope, with the settings and
1405
+ statements that only the top level allows."""
1406
+
1407
+ def __init__(self, format: str | None = None) -> None: ...
1408
+ def format(self, name: str) -> None:
1409
+ """``format name``, a name of this format."""
1410
+
1411
+ def comment(self, *markers: str) -> None:
1412
+ """``comment "text"...``."""
1413
+
1414
+ def stop(self, *markers: str) -> None:
1415
+ """``stop "text"...``."""
1416
+
1417
+ def tokens(self, characters: str) -> None:
1418
+ """``tokens "characters"``."""
1419
+
1420
+ def separators(self, characters: str) -> None:
1421
+ """``separators "characters"``."""
1422
+
1423
+ def ignore_trailing(self) -> None:
1424
+ """``ignore trailing``."""
1425
+
1426
+ def instances(self) -> Block[Scope0[Required]]:
1427
+ """``instances { ... }``."""
1428
+
1429
+ def source(self) -> str:
1430
+ """The text this builder emits, without parsing it."""
1431
+
1432
+ def build(self) -> Spec:
1433
+ """Print the text and parse it. The spec is an ordinary one, whose
1434
+ errors while reading name the call site of their statement."""