flux-sim-engine 0.2.0__py3-none-any.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.
- flux_engine/__init__.py +22 -0
- flux_engine/_links.py +55 -0
- flux_engine/_vendor/__init__.py +5 -0
- flux_engine/_vendor/flux_spec/NOTICE +19 -0
- flux_engine/_vendor/flux_spec/VENDOR-NOTES.md +104 -0
- flux_engine/_vendor/flux_spec/__init__.py +9 -0
- flux_engine/_vendor/flux_spec/bundle.py +410 -0
- flux_engine/_vendor/flux_spec/enforce.py +316 -0
- flux_engine/_vendor/flux_spec/schema/flux-enforcement-0.5.0.json +121 -0
- flux_engine/_vendor/flux_spec/schema/flux-manifest-0.5.0.json +153 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.2.0.json +465 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.3.0.json +876 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.4.0.json +1601 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.4.1.json +1668 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.5.0.json +1669 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-latest.json +1669 -0
- flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.4.0.json +795 -0
- flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.4.1.json +852 -0
- flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.5.0.json +852 -0
- flux_engine/_vendor/flux_spec/validate.py +537 -0
- flux_engine/_vendor/flux_spec/vectors/enforcement-vectors.json +935 -0
- flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.3.json +5234 -0
- flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.4.json +5437 -0
- flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.5.json +5498 -0
- flux_engine/_vocabulary.py +141 -0
- flux_engine/accuracy/__init__.py +5 -0
- flux_engine/accuracy/_scoring/__init__.py +24 -0
- flux_engine/accuracy/accuracy_record.py +96 -0
- flux_engine/accuracy/policy.py +158 -0
- flux_engine/accuracy/records.py +264 -0
- flux_engine/accuracy/store.py +169 -0
- flux_engine/api/__init__.py +163 -0
- flux_engine/api/accuracy.py +209 -0
- flux_engine/api/agentic.py +134 -0
- flux_engine/api/calibration.py +125 -0
- flux_engine/api/claims.py +93 -0
- flux_engine/api/digests.py +73 -0
- flux_engine/api/emit.py +78 -0
- flux_engine/api/expressions.py +72 -0
- flux_engine/api/fidelity.py +110 -0
- flux_engine/api/lineage.py +78 -0
- flux_engine/api/stages.py +242 -0
- flux_engine/api/verdict.py +108 -0
- flux_engine/calibrate/__init__.py +5 -0
- flux_engine/calibrate/declared.py +253 -0
- flux_engine/calibrate/provenance.py +113 -0
- flux_engine/cli/__init__.py +2146 -0
- flux_engine/cli/__main__.py +17 -0
- flux_engine/cli/_documents.py +226 -0
- flux_engine/cli/_hints.py +118 -0
- flux_engine/cli/_init.py +152 -0
- flux_engine/cli/_progress.py +124 -0
- flux_engine/concordance/__init__.py +127 -0
- flux_engine/concordance/boundary/__init__.py +78 -0
- flux_engine/concordance/boundary/merkle.py +287 -0
- flux_engine/concordance/boundary/slice.py +429 -0
- flux_engine/concordance/boundary/statistic.py +561 -0
- flux_engine/concordance/boundary/store.py +334 -0
- flux_engine/concordance/boundary/vault.py +357 -0
- flux_engine/concordance/compiler.py +542 -0
- flux_engine/concordance/errors.py +189 -0
- flux_engine/concordance/gate.py +525 -0
- flux_engine/concordance/predicate.py +1217 -0
- flux_engine/concordance/record.py +554 -0
- flux_engine/concordance/verifier.py +583 -0
- flux_engine/core/__init__.py +5 -0
- flux_engine/core/artifact.py +99 -0
- flux_engine/core/canonical.py +369 -0
- flux_engine/core/clock.py +437 -0
- flux_engine/core/digest.py +288 -0
- flux_engine/core/errors.py +277 -0
- flux_engine/core/fixedpoint.py +929 -0
- flux_engine/core/lrm.py +158 -0
- flux_engine/core/rng.py +736 -0
- flux_engine/core/seedtree.py +891 -0
- flux_engine/core/trace.py +423 -0
- flux_engine/describe.py +207 -0
- flux_engine/engine.py +257 -0
- flux_engine/evidence/__init__.py +5 -0
- flux_engine/evidence/pack.py +411 -0
- flux_engine/evidence/report.py +243 -0
- flux_engine/expr/__init__.py +133 -0
- flux_engine/expr/ast.py +312 -0
- flux_engine/expr/attrs.py +386 -0
- flux_engine/expr/check.py +278 -0
- flux_engine/expr/compile.py +322 -0
- flux_engine/expr/errors.py +256 -0
- flux_engine/expr/lexer.py +297 -0
- flux_engine/expr/parser.py +313 -0
- flux_engine/expr/types.py +177 -0
- flux_engine/generator/__init__.py +97 -0
- flux_engine/generator/families.py +325 -0
- flux_engine/generator/paths.py +227 -0
- flux_engine/generator/rows.py +918 -0
- flux_engine/generator/statistics.py +524 -0
- flux_engine/governance/__init__.py +87 -0
- flux_engine/governance/audit.py +307 -0
- flux_engine/governance/gate.py +334 -0
- flux_engine/governance/skills.py +220 -0
- flux_engine/governance/sovereignty.py +251 -0
- flux_engine/lineage/__init__.py +5 -0
- flux_engine/lineage/emitter.py +398 -0
- flux_engine/py.typed +0 -0
- flux_engine/runtime/__init__.py +153 -0
- flux_engine/runtime/campaign.py +407 -0
- flux_engine/runtime/cast.py +283 -0
- flux_engine/runtime/detector.py +222 -0
- flux_engine/runtime/errors.py +58 -0
- flux_engine/runtime/experiment.py +311 -0
- flux_engine/runtime/journey.py +383 -0
- flux_engine/runtime/jurisdiction.py +72 -0
- flux_engine/runtime/payloads.py +124 -0
- flux_engine/runtime/signals.py +334 -0
- flux_engine/runtime/temperature.py +156 -0
- flux_engine/seam/__init__.py +5 -0
- flux_engine/seam/attest.py +290 -0
- flux_engine/seam/conform.py +448 -0
- flux_engine/seam/contract.py +605 -0
- flux_engine/seam/emit.py +488 -0
- flux_engine/seam/mapping.py +299 -0
- flux_engine/seam/resolve.py +1087 -0
- flux_engine/seam/sinks.py +157 -0
- flux_engine/spec/__init__.py +134 -0
- flux_engine/spec/bundle.py +25 -0
- flux_engine/spec/enforce.py +31 -0
- flux_engine/spec/validate.py +28 -0
- flux_engine/stages/__init__.py +30 -0
- flux_engine/stages/apply.py +447 -0
- flux_engine/stages/errors.py +315 -0
- flux_engine/stages/layout.py +292 -0
- flux_engine/stages/pipeline.py +600 -0
- flux_engine/stages/plan.py +241 -0
- flux_engine/stages/replay.py +83 -0
- flux_engine/stages/run.py +208 -0
- flux_engine/stages/ship.py +934 -0
- flux_engine/stages/validate.py +93 -0
- flux_engine/stages/verify.py +1129 -0
- flux_engine/starter/__init__.py +161 -0
- flux_engine/starter/bundle/detector.flux.yml +15 -0
- flux_engine/starter/bundle/journey.flux.yml +23 -0
- flux_engine/starter/bundle/module.flux.yml +16 -0
- flux_engine/starter/bundle/payment-recovery.fluid.yml +30 -0
- flux_engine/starter/bundle/persona.flux.yml +26 -0
- flux_engine/starter/bundle/signal.flux.yml +13 -0
- flux_engine/starter/bundle/simulation.flux.yml +29 -0
- flux_engine/starter/bundle/taxonomy.flux.yml +17 -0
- flux_engine/starter/bundle/treatment.flux.yml +13 -0
- flux_engine/starter/bundle/world.flux.yml +20 -0
- flux_engine/verticals/__init__.py +85 -0
- flux_engine/verticals/telco.py +89 -0
- flux_engine/world/__init__.py +89 -0
- flux_engine/world/derived.py +195 -0
- flux_engine/world/errors.py +41 -0
- flux_engine/world/families.py +260 -0
- flux_engine/world/population.py +602 -0
- flux_engine/world/tracing.py +66 -0
- flux_engine/world/values.py +121 -0
- flux_sim_engine-0.2.0.dist-info/METADATA +108 -0
- flux_sim_engine-0.2.0.dist-info/RECORD +165 -0
- flux_sim_engine-0.2.0.dist-info/WHEEL +5 -0
- flux_sim_engine-0.2.0.dist-info/entry_points.txt +2 -0
- flux_sim_engine-0.2.0.dist-info/licenses/LICENSE +202 -0
- flux_sim_engine-0.2.0.dist-info/licenses/NOTICE +10 -0
- flux_sim_engine-0.2.0.dist-info/licenses/flux_engine/_vendor/flux_spec/NOTICE +19 -0
- flux_sim_engine-0.2.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,297 @@
|
|
|
1
|
+
# Copyright 2026 Agentics Transformation Limited
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
4
|
+
|
|
5
|
+
"""Hand-written tokenizer for ``flux-expr/1`` (EXPR-SPEC §1, §4).
|
|
6
|
+
|
|
7
|
+
The grammar is closed: "anything not derivable is a parse error
|
|
8
|
+
(``FLX-6001``), never an extension point". This module is therefore written
|
|
9
|
+
to reject rather than to recover -- there is no error node, no skipped
|
|
10
|
+
character and no lookahead beyond one character.
|
|
11
|
+
|
|
12
|
+
Three rules resolved here that the EBNF leaves open, each in the restrictive
|
|
13
|
+
direction the closed-grammar policy calls for:
|
|
14
|
+
|
|
15
|
+
* **NFC first.** The source is normalised to NFC before a single character is
|
|
16
|
+
read, so the composed and decomposed spellings of an identifier name the
|
|
17
|
+
same path (EXPR-SPEC §5, "NFC/NFD identifier equivalence"). Every offset a
|
|
18
|
+
token or an error reports indexes the *normalised* text.
|
|
19
|
+
* **Backslash.** ``string = "'" , { char - "'" | "\\'" } , "'"`` does not say
|
|
20
|
+
what a bare backslash means. Resolved: a backslash is legal only as the
|
|
21
|
+
two-character escape ``\\'``; any other backslash is ``FLX-6001``. A string
|
|
22
|
+
value therefore never contains a backslash, which is what makes
|
|
23
|
+
``unparse`` total and a fixed point.
|
|
24
|
+
* **Control characters.** A character below U+0020 (a newline included) is
|
|
25
|
+
``FLX-6001`` anywhere in the source, including inside a string literal:
|
|
26
|
+
EXPR-SPEC §1 lists space and tab as the whole of the whitespace set, and a
|
|
27
|
+
canonical form that can carry a raw newline is not a single line of
|
|
28
|
+
``plan.json``.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
from __future__ import annotations
|
|
32
|
+
|
|
33
|
+
from dataclasses import dataclass
|
|
34
|
+
from decimal import Decimal
|
|
35
|
+
from enum import Enum
|
|
36
|
+
from typing import List, Tuple
|
|
37
|
+
|
|
38
|
+
from flux_engine.expr.errors import ParseError, ReservedWordError
|
|
39
|
+
from flux_engine.expr.types import nfc
|
|
40
|
+
|
|
41
|
+
__all__ = ["Token", "TokenKind", "RESERVED_WORDS", "tokenize"]
|
|
42
|
+
|
|
43
|
+
#: Words held for ``flux-expr/2``. EXPR-SPEC §1: "``matches`` is a **reserved
|
|
44
|
+
#: word** that parses to ``FLX-6002`` naming flux-expr/2". Reserved in every
|
|
45
|
+
#: position -- as a bare name, as a path segment and as a method name -- so
|
|
46
|
+
#: that the word cannot acquire a meaning by accident in flux-expr/1.
|
|
47
|
+
RESERVED_WORDS: frozenset = frozenset({"matches"})
|
|
48
|
+
|
|
49
|
+
#: EXPR-SPEC §1: "Whitespace: space, tab."
|
|
50
|
+
_WHITESPACE = " \t"
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class TokenKind(str, Enum):
|
|
54
|
+
"""Every token flux-expr/1 has. Closed."""
|
|
55
|
+
|
|
56
|
+
IDENT = "ident"
|
|
57
|
+
NUMBER = "number"
|
|
58
|
+
STRING = "string"
|
|
59
|
+
TRUE = "true"
|
|
60
|
+
FALSE = "false"
|
|
61
|
+
NULL = "null"
|
|
62
|
+
IN = "in"
|
|
63
|
+
LPAREN = "("
|
|
64
|
+
RPAREN = ")"
|
|
65
|
+
LBRACKET = "["
|
|
66
|
+
RBRACKET = "]"
|
|
67
|
+
COMMA = ","
|
|
68
|
+
DOT = "."
|
|
69
|
+
BANG = "!"
|
|
70
|
+
AND = "&&"
|
|
71
|
+
OR = "||"
|
|
72
|
+
EQ = "=="
|
|
73
|
+
NE = "!="
|
|
74
|
+
LT = "<"
|
|
75
|
+
LE = "<="
|
|
76
|
+
GT = ">"
|
|
77
|
+
GE = ">="
|
|
78
|
+
EOF = "<end of expression>"
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
#: ``ident``s that are keywords rather than names. ``matches`` is handled
|
|
82
|
+
#: separately because it raises rather than producing a token.
|
|
83
|
+
_KEYWORDS = {
|
|
84
|
+
"true": TokenKind.TRUE,
|
|
85
|
+
"false": TokenKind.FALSE,
|
|
86
|
+
"null": TokenKind.NULL,
|
|
87
|
+
"in": TokenKind.IN,
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
#: Operators that are exactly one character and have no two-character form.
|
|
91
|
+
_SINGLES = {
|
|
92
|
+
"(": TokenKind.LPAREN,
|
|
93
|
+
")": TokenKind.RPAREN,
|
|
94
|
+
"[": TokenKind.LBRACKET,
|
|
95
|
+
"]": TokenKind.RBRACKET,
|
|
96
|
+
",": TokenKind.COMMA,
|
|
97
|
+
".": TokenKind.DOT,
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
#: Comparison operator kinds, consumed by the parser as ``cmp_op``.
|
|
101
|
+
COMPARISON_KINDS = (
|
|
102
|
+
TokenKind.EQ,
|
|
103
|
+
TokenKind.NE,
|
|
104
|
+
TokenKind.LT,
|
|
105
|
+
TokenKind.LE,
|
|
106
|
+
TokenKind.GT,
|
|
107
|
+
TokenKind.GE,
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
@dataclass(frozen=True)
|
|
112
|
+
class Token:
|
|
113
|
+
"""One token: its kind, the exact text consumed, and its start offset.
|
|
114
|
+
|
|
115
|
+
``value`` carries the decoded payload for the three literal kinds -- a
|
|
116
|
+
``Decimal`` for ``NUMBER`` (never a ``float``; KERNEL-SPEC §2.1), the
|
|
117
|
+
unescaped NFC string for ``STRING``, the identifier for ``IDENT`` -- and
|
|
118
|
+
is the empty string for every operator.
|
|
119
|
+
"""
|
|
120
|
+
|
|
121
|
+
kind: TokenKind
|
|
122
|
+
text: str
|
|
123
|
+
position: int
|
|
124
|
+
value: object = ""
|
|
125
|
+
|
|
126
|
+
def __str__(self) -> str:
|
|
127
|
+
return self.text or self.kind.value
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def _is_ident_start(char: str) -> bool:
|
|
131
|
+
"""``ident = ( letter | "_" ) , ...`` -- ``letter`` is any Unicode letter."""
|
|
132
|
+
return char == "_" or char.isalpha()
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def _is_ident_part(char: str) -> bool:
|
|
136
|
+
"""``... , { letter | digit | "_" }``."""
|
|
137
|
+
return char == "_" or char.isalpha() or char.isdecimal()
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def _read_string(source: str, start: int) -> Tuple[str, int]:
|
|
141
|
+
"""Read a single-quoted string starting at the quote; return (value, end)."""
|
|
142
|
+
index = start + 1
|
|
143
|
+
chars: List[str] = []
|
|
144
|
+
while index < len(source):
|
|
145
|
+
char = source[index]
|
|
146
|
+
if char == "'":
|
|
147
|
+
return "".join(chars), index + 1
|
|
148
|
+
if char == "\\":
|
|
149
|
+
if index + 1 < len(source) and source[index + 1] == "'":
|
|
150
|
+
chars.append("'")
|
|
151
|
+
index += 2
|
|
152
|
+
continue
|
|
153
|
+
raise ParseError(
|
|
154
|
+
"a backslash is only legal as the escape \\' inside a string",
|
|
155
|
+
position=index,
|
|
156
|
+
)
|
|
157
|
+
if char < " ":
|
|
158
|
+
raise ParseError(
|
|
159
|
+
f"control character U+{ord(char):04X} is not legal in a string literal",
|
|
160
|
+
position=index,
|
|
161
|
+
)
|
|
162
|
+
chars.append(char)
|
|
163
|
+
index += 1
|
|
164
|
+
raise ParseError("unterminated string literal", position=start)
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def _read_number(source: str, start: int) -> Tuple[Decimal, int]:
|
|
168
|
+
"""Read ``[ "-" ] , digit , { digit } , [ "." , digit , { digit } ]``.
|
|
169
|
+
|
|
170
|
+
Parsed as ``Decimal`` with the literal's declared scale preserved
|
|
171
|
+
(``0.50`` stays ``0.50``) -- EXPR-SPEC §2: "Numeric literals are parsed as
|
|
172
|
+
``Decimal``, never ``float``."
|
|
173
|
+
"""
|
|
174
|
+
index = start
|
|
175
|
+
if source[index] == "-":
|
|
176
|
+
index += 1
|
|
177
|
+
digits_start = index
|
|
178
|
+
while index < len(source) and source[index].isdecimal():
|
|
179
|
+
index += 1
|
|
180
|
+
if index == digits_start:
|
|
181
|
+
raise ParseError(
|
|
182
|
+
"a '-' must be followed by a digit; there is no arithmetic", position=start
|
|
183
|
+
)
|
|
184
|
+
if index < len(source) and source[index] == ".":
|
|
185
|
+
fraction_start = index + 1
|
|
186
|
+
index = fraction_start
|
|
187
|
+
while index < len(source) and source[index].isdecimal():
|
|
188
|
+
index += 1
|
|
189
|
+
if index == fraction_start:
|
|
190
|
+
raise ParseError("a decimal point must be followed by a digit", position=start)
|
|
191
|
+
text = source[start:index]
|
|
192
|
+
# ``isdecimal`` accepts non-ASCII decimal digits, which ``Decimal`` would
|
|
193
|
+
# then accept too; the grammar's ``digit`` is ASCII, so reject the rest
|
|
194
|
+
# rather than silently admitting U+0660 and friends.
|
|
195
|
+
if any(char not in "-.0123456789" for char in text):
|
|
196
|
+
raise ParseError("a number is written with ASCII digits", position=start)
|
|
197
|
+
return Decimal(text), index
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def tokenize(source: str) -> Tuple[Token, ...]:
|
|
201
|
+
"""Tokenize *source*, ending with a single ``EOF`` token.
|
|
202
|
+
|
|
203
|
+
Raises :class:`~flux_engine.expr.errors.ParseError` (``FLX-6001``) for any
|
|
204
|
+
character or character sequence the grammar cannot derive, and
|
|
205
|
+
:class:`~flux_engine.expr.errors.ReservedWordError` (``FLX-6002``) for a
|
|
206
|
+
word held for ``flux-expr/2``.
|
|
207
|
+
"""
|
|
208
|
+
text = nfc(source)
|
|
209
|
+
tokens: List[Token] = []
|
|
210
|
+
index = 0
|
|
211
|
+
length = len(text)
|
|
212
|
+
while index < length:
|
|
213
|
+
char = text[index]
|
|
214
|
+
if char in _WHITESPACE:
|
|
215
|
+
index += 1
|
|
216
|
+
continue
|
|
217
|
+
if char < " " or char == "\x7f":
|
|
218
|
+
raise ParseError(
|
|
219
|
+
f"control character U+{ord(char):04X} is not whitespace in flux-expr/1",
|
|
220
|
+
position=index,
|
|
221
|
+
)
|
|
222
|
+
if _is_ident_start(char):
|
|
223
|
+
start = index
|
|
224
|
+
index += 1
|
|
225
|
+
while index < length and _is_ident_part(text[index]):
|
|
226
|
+
index += 1
|
|
227
|
+
word = text[start:index]
|
|
228
|
+
if word in RESERVED_WORDS:
|
|
229
|
+
raise ReservedWordError(
|
|
230
|
+
f"'{word}' is reserved for flux-expr/2 and has no meaning in flux-expr/1",
|
|
231
|
+
position=start,
|
|
232
|
+
)
|
|
233
|
+
keyword = _KEYWORDS.get(word)
|
|
234
|
+
if keyword is not None:
|
|
235
|
+
tokens.append(Token(keyword, word, start))
|
|
236
|
+
else:
|
|
237
|
+
tokens.append(Token(TokenKind.IDENT, word, start, word))
|
|
238
|
+
continue
|
|
239
|
+
if char.isdecimal() or char == "-":
|
|
240
|
+
value, end = _read_number(text, index)
|
|
241
|
+
tokens.append(Token(TokenKind.NUMBER, text[index:end], index, value))
|
|
242
|
+
index = end
|
|
243
|
+
continue
|
|
244
|
+
if char == "'":
|
|
245
|
+
value_str, end = _read_string(text, index)
|
|
246
|
+
tokens.append(Token(TokenKind.STRING, text[index:end], index, value_str))
|
|
247
|
+
index = end
|
|
248
|
+
continue
|
|
249
|
+
if char in _SINGLES:
|
|
250
|
+
tokens.append(Token(_SINGLES[char], char, index))
|
|
251
|
+
index += 1
|
|
252
|
+
continue
|
|
253
|
+
nxt = text[index + 1] if index + 1 < length else ""
|
|
254
|
+
if char == "&":
|
|
255
|
+
if nxt != "&":
|
|
256
|
+
raise ParseError("'&' is not an operator; conjunction is '&&'", position=index)
|
|
257
|
+
tokens.append(Token(TokenKind.AND, "&&", index))
|
|
258
|
+
index += 2
|
|
259
|
+
continue
|
|
260
|
+
if char == "|":
|
|
261
|
+
if nxt != "|":
|
|
262
|
+
raise ParseError("'|' is not an operator; disjunction is '||'", position=index)
|
|
263
|
+
tokens.append(Token(TokenKind.OR, "||", index))
|
|
264
|
+
index += 2
|
|
265
|
+
continue
|
|
266
|
+
if char == "=":
|
|
267
|
+
if nxt != "=":
|
|
268
|
+
raise ParseError("'=' is not an operator; equality is '=='", position=index)
|
|
269
|
+
tokens.append(Token(TokenKind.EQ, "==", index))
|
|
270
|
+
index += 2
|
|
271
|
+
continue
|
|
272
|
+
if char == "!":
|
|
273
|
+
if nxt == "=":
|
|
274
|
+
tokens.append(Token(TokenKind.NE, "!=", index))
|
|
275
|
+
index += 2
|
|
276
|
+
else:
|
|
277
|
+
tokens.append(Token(TokenKind.BANG, "!", index))
|
|
278
|
+
index += 1
|
|
279
|
+
continue
|
|
280
|
+
if char == "<":
|
|
281
|
+
kind, size = (TokenKind.LE, 2) if nxt == "=" else (TokenKind.LT, 1)
|
|
282
|
+
tokens.append(Token(kind, text[index : index + size], index))
|
|
283
|
+
index += size
|
|
284
|
+
continue
|
|
285
|
+
if char == ">":
|
|
286
|
+
kind, size = (TokenKind.GE, 2) if nxt == "=" else (TokenKind.GT, 1)
|
|
287
|
+
tokens.append(Token(kind, text[index : index + size], index))
|
|
288
|
+
index += size
|
|
289
|
+
continue
|
|
290
|
+
if char == '"':
|
|
291
|
+
raise ParseError(
|
|
292
|
+
"flux-expr/1 has no double-quoted strings; use single quotes",
|
|
293
|
+
position=index,
|
|
294
|
+
)
|
|
295
|
+
raise ParseError(f"unexpected character {char!r}", position=index)
|
|
296
|
+
tokens.append(Token(TokenKind.EOF, "", length))
|
|
297
|
+
return tuple(tokens)
|
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
# Copyright 2026 Agentics Transformation Limited
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
4
|
+
|
|
5
|
+
"""Pratt parser for ``flux-expr/1`` (EXPR-SPEC §1, §4).
|
|
6
|
+
|
|
7
|
+
The EBNF is reproduced here because the code is written against it clause by
|
|
8
|
+
clause::
|
|
9
|
+
|
|
10
|
+
expr = or_expr ;
|
|
11
|
+
or_expr = and_expr , { "||" , and_expr } ;
|
|
12
|
+
and_expr = not_expr , { "&&" , not_expr } ;
|
|
13
|
+
not_expr = [ "!" ] , primary ;
|
|
14
|
+
primary = "(" , expr , ")" | comparison | membership | method | bool_lit ;
|
|
15
|
+
comparison = operand , cmp_op , operand ;
|
|
16
|
+
membership = operand , "in" , list_lit | operand , "in" , path ;
|
|
17
|
+
method = path , "." , method_name , "(" , [ literal , { "," , literal } ] , ")" ;
|
|
18
|
+
operand = path | literal ;
|
|
19
|
+
|
|
20
|
+
The binary operators ``||`` and ``&&`` are driven by the binding-power table
|
|
21
|
+
:data:`_BINDING_POWER` in one loop (the Pratt shape EXPR-SPEC §4 names);
|
|
22
|
+
``!`` is the single prefix operator; everything tighter is a *primary*, which
|
|
23
|
+
this module parses with one token of lookahead.
|
|
24
|
+
|
|
25
|
+
Two consequences of taking the EBNF literally are worth stating, because both
|
|
26
|
+
are commonly assumed otherwise:
|
|
27
|
+
|
|
28
|
+
* **A bare path is not an expression.** ``primary`` offers ``bool_lit`` but
|
|
29
|
+
not ``operand``, so a boolean attribute is written ``flag == true``, and
|
|
30
|
+
``products`` on its own is ``FLX-6001``.
|
|
31
|
+
* **``!`` applies to a primary, not to an operand.** ``!a > 1`` therefore
|
|
32
|
+
derives as ``!(a > 1)``: ``not_expr = [ "!" ] , primary`` and ``primary``
|
|
33
|
+
includes ``comparison``. The precedence line in EXPR-SPEC §1 lists ``!`` as
|
|
34
|
+
tighter than comparison, but the grammar gives ``!`` nothing tighter to
|
|
35
|
+
apply to, so the ordering is unobservable and the EBNF decides. ``!!x`` is
|
|
36
|
+
not derivable and is ``FLX-6001``.
|
|
37
|
+
* **A method is not an operand.** ``a == b.has('x')`` is ``FLX-6001``; the
|
|
38
|
+
method production stands alone as a primary.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
from __future__ import annotations
|
|
42
|
+
|
|
43
|
+
from decimal import Decimal
|
|
44
|
+
from typing import Dict, List, Sequence, Tuple, Union
|
|
45
|
+
|
|
46
|
+
from flux_engine.expr.ast import (
|
|
47
|
+
METHOD_NAMES,
|
|
48
|
+
And,
|
|
49
|
+
BoolLit,
|
|
50
|
+
Compare,
|
|
51
|
+
Expr,
|
|
52
|
+
In,
|
|
53
|
+
ListLit,
|
|
54
|
+
Literal,
|
|
55
|
+
Method,
|
|
56
|
+
Not,
|
|
57
|
+
NullLit,
|
|
58
|
+
NumberLit,
|
|
59
|
+
Operand,
|
|
60
|
+
Or,
|
|
61
|
+
Path,
|
|
62
|
+
StringLit,
|
|
63
|
+
)
|
|
64
|
+
from flux_engine.expr.errors import ParseError
|
|
65
|
+
from flux_engine.expr.lexer import COMPARISON_KINDS, Token, TokenKind, tokenize
|
|
66
|
+
|
|
67
|
+
__all__ = ["parse", "parse_tokens"]
|
|
68
|
+
|
|
69
|
+
#: Left binding power of the two infix boolean operators. ``&&`` binds
|
|
70
|
+
#: tighter than ``||``; both are left-associative, which the parse loop gets
|
|
71
|
+
#: by recursing at ``bp + 1``.
|
|
72
|
+
_BINDING_POWER: Dict[TokenKind, int] = {
|
|
73
|
+
TokenKind.OR: 1,
|
|
74
|
+
TokenKind.AND: 2,
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
#: Token kinds that can begin an ``operand``.
|
|
78
|
+
_OPERAND_STARTS = (
|
|
79
|
+
TokenKind.IDENT,
|
|
80
|
+
TokenKind.STRING,
|
|
81
|
+
TokenKind.NUMBER,
|
|
82
|
+
TokenKind.TRUE,
|
|
83
|
+
TokenKind.FALSE,
|
|
84
|
+
TokenKind.NULL,
|
|
85
|
+
)
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
class _Parser:
|
|
89
|
+
"""One parse. Holds the token stream and the cursor; never backtracks."""
|
|
90
|
+
|
|
91
|
+
def __init__(self, tokens: Sequence[Token]) -> None:
|
|
92
|
+
self._tokens = tokens
|
|
93
|
+
self._index = 0
|
|
94
|
+
|
|
95
|
+
# --- cursor -----------------------------------------------------------
|
|
96
|
+
|
|
97
|
+
def at_end(self) -> bool:
|
|
98
|
+
"""True when the whole token stream has been consumed."""
|
|
99
|
+
return self._peek().kind is TokenKind.EOF
|
|
100
|
+
|
|
101
|
+
def trailing(self) -> Token:
|
|
102
|
+
"""The token the parse stopped at (``EOF`` on a complete parse)."""
|
|
103
|
+
return self._peek()
|
|
104
|
+
|
|
105
|
+
def _peek(self, offset: int = 0) -> Token:
|
|
106
|
+
index = min(self._index + offset, len(self._tokens) - 1)
|
|
107
|
+
return self._tokens[index]
|
|
108
|
+
|
|
109
|
+
def _advance(self) -> Token:
|
|
110
|
+
token = self._tokens[self._index]
|
|
111
|
+
if token.kind is not TokenKind.EOF:
|
|
112
|
+
self._index += 1
|
|
113
|
+
return token
|
|
114
|
+
|
|
115
|
+
def _expect(self, kind: TokenKind, what: str) -> Token:
|
|
116
|
+
token = self._peek()
|
|
117
|
+
if token.kind is not kind:
|
|
118
|
+
raise ParseError(f"expected {what}, found {token}", position=token.position)
|
|
119
|
+
return self._advance()
|
|
120
|
+
|
|
121
|
+
# --- expr / or_expr / and_expr ----------------------------------------
|
|
122
|
+
|
|
123
|
+
def parse_expr(self, min_bp: int = 1) -> Expr:
|
|
124
|
+
"""``expr = or_expr`` -- the Pratt loop over ``||`` and ``&&``."""
|
|
125
|
+
node: Expr = self.parse_not()
|
|
126
|
+
while True:
|
|
127
|
+
token = self._peek()
|
|
128
|
+
bp = _BINDING_POWER.get(token.kind)
|
|
129
|
+
if bp is None or bp < min_bp:
|
|
130
|
+
return node
|
|
131
|
+
self._advance()
|
|
132
|
+
right = self.parse_expr(bp + 1)
|
|
133
|
+
node = Or(node, right) if token.kind is TokenKind.OR else And(node, right)
|
|
134
|
+
|
|
135
|
+
# --- not_expr ---------------------------------------------------------
|
|
136
|
+
|
|
137
|
+
def parse_not(self) -> Expr:
|
|
138
|
+
"""``not_expr = [ "!" ] , primary``. One ``!`` only; ``!!`` is FLX-6001."""
|
|
139
|
+
if self._peek().kind is TokenKind.BANG:
|
|
140
|
+
self._advance()
|
|
141
|
+
if self._peek().kind is TokenKind.BANG:
|
|
142
|
+
raise ParseError(
|
|
143
|
+
"'!' applies to one primary; '!!' is not derivable",
|
|
144
|
+
position=self._peek().position,
|
|
145
|
+
)
|
|
146
|
+
return Not(self.parse_primary())
|
|
147
|
+
return self.parse_primary()
|
|
148
|
+
|
|
149
|
+
# --- primary ----------------------------------------------------------
|
|
150
|
+
|
|
151
|
+
def parse_primary(self) -> Expr:
|
|
152
|
+
"""``primary = "(" expr ")" | comparison | membership | method | bool_lit``."""
|
|
153
|
+
token = self._peek()
|
|
154
|
+
if token.kind is TokenKind.LPAREN:
|
|
155
|
+
self._advance()
|
|
156
|
+
inner = self.parse_expr()
|
|
157
|
+
self._expect(TokenKind.RPAREN, "')'")
|
|
158
|
+
return inner
|
|
159
|
+
if token.kind not in _OPERAND_STARTS:
|
|
160
|
+
raise ParseError(f"expected a predicate, found {token}", position=token.position)
|
|
161
|
+
|
|
162
|
+
left = self._parse_operand_or_method(allow_method=True)
|
|
163
|
+
after = self._peek()
|
|
164
|
+
|
|
165
|
+
if after.kind in COMPARISON_KINDS:
|
|
166
|
+
if isinstance(left, Method):
|
|
167
|
+
raise ParseError(
|
|
168
|
+
"a method call is not an operand of a comparison",
|
|
169
|
+
position=after.position,
|
|
170
|
+
)
|
|
171
|
+
self._advance()
|
|
172
|
+
right = self._parse_operand_or_method(allow_method=False)
|
|
173
|
+
assert not isinstance(right, Method) # allow_method=False
|
|
174
|
+
return Compare(after.text, left, right)
|
|
175
|
+
|
|
176
|
+
if after.kind is TokenKind.IN:
|
|
177
|
+
if isinstance(left, Method):
|
|
178
|
+
raise ParseError(
|
|
179
|
+
"a method call is not an operand of 'in'",
|
|
180
|
+
position=after.position,
|
|
181
|
+
)
|
|
182
|
+
self._advance()
|
|
183
|
+
return In(left, self._parse_membership_right())
|
|
184
|
+
|
|
185
|
+
if isinstance(left, Method):
|
|
186
|
+
return left
|
|
187
|
+
if isinstance(left, BoolLit):
|
|
188
|
+
return left
|
|
189
|
+
raise ParseError(
|
|
190
|
+
"a bare operand is not a predicate; primary is a comparison, a "
|
|
191
|
+
"membership test, a method call, a boolean literal or a "
|
|
192
|
+
"parenthesised expression",
|
|
193
|
+
position=after.position,
|
|
194
|
+
)
|
|
195
|
+
|
|
196
|
+
# --- operand / path / method ------------------------------------------
|
|
197
|
+
|
|
198
|
+
def _parse_operand_or_method(self, *, allow_method: bool) -> Union[Operand, Method]:
|
|
199
|
+
"""``operand = path | literal``, or -- when *allow_method* -- a ``method``."""
|
|
200
|
+
token = self._peek()
|
|
201
|
+
if token.kind is TokenKind.IDENT:
|
|
202
|
+
return self._parse_path_or_method(allow_method=allow_method)
|
|
203
|
+
return self._parse_literal()
|
|
204
|
+
|
|
205
|
+
def _parse_literal(self) -> Literal:
|
|
206
|
+
"""``literal = string | number | bool_lit | null_lit``."""
|
|
207
|
+
token = self._peek()
|
|
208
|
+
if token.kind is TokenKind.STRING:
|
|
209
|
+
self._advance()
|
|
210
|
+
return StringLit(str(token.value))
|
|
211
|
+
if token.kind is TokenKind.NUMBER:
|
|
212
|
+
self._advance()
|
|
213
|
+
value = token.value
|
|
214
|
+
assert isinstance(value, Decimal) # the lexer decodes NUMBER to Decimal
|
|
215
|
+
return NumberLit(value)
|
|
216
|
+
if token.kind in (TokenKind.TRUE, TokenKind.FALSE):
|
|
217
|
+
self._advance()
|
|
218
|
+
return BoolLit(token.kind is TokenKind.TRUE)
|
|
219
|
+
if token.kind is TokenKind.NULL:
|
|
220
|
+
self._advance()
|
|
221
|
+
return NullLit()
|
|
222
|
+
raise ParseError(f"expected a literal, found {token}", position=token.position)
|
|
223
|
+
|
|
224
|
+
def _parse_path_or_method(self, *, allow_method: bool) -> Union[Path, Method]:
|
|
225
|
+
"""Read ``path`` and, on the method lookahead, the whole ``method``.
|
|
226
|
+
|
|
227
|
+
``path`` and ``method`` share their prefix, so the dotted segments are
|
|
228
|
+
consumed greedily until a segment is both a declared ``method_name``
|
|
229
|
+
and immediately followed by ``(`` -- the one-token lookahead that
|
|
230
|
+
separates ``products.has`` (a path) from ``products.has('tv')`` (a
|
|
231
|
+
method call).
|
|
232
|
+
"""
|
|
233
|
+
parts: List[str] = [str(self._expect(TokenKind.IDENT, "an identifier").value)]
|
|
234
|
+
while self._peek().kind is TokenKind.DOT:
|
|
235
|
+
segment = self._peek(1)
|
|
236
|
+
if segment.kind is not TokenKind.IDENT:
|
|
237
|
+
raise ParseError(
|
|
238
|
+
f"expected an identifier after '.', found {segment}",
|
|
239
|
+
position=segment.position,
|
|
240
|
+
)
|
|
241
|
+
is_call = segment.text in METHOD_NAMES and self._peek(2).kind is TokenKind.LPAREN
|
|
242
|
+
if is_call:
|
|
243
|
+
if not allow_method:
|
|
244
|
+
raise ParseError(
|
|
245
|
+
"a method call is not an operand here",
|
|
246
|
+
position=segment.position,
|
|
247
|
+
)
|
|
248
|
+
self._advance() # '.'
|
|
249
|
+
self._advance() # method_name
|
|
250
|
+
args = self._parse_arguments()
|
|
251
|
+
return Method(Path(tuple(parts)), segment.text, args)
|
|
252
|
+
self._advance() # '.'
|
|
253
|
+
self._advance() # segment
|
|
254
|
+
parts.append(str(segment.value))
|
|
255
|
+
return Path(tuple(parts))
|
|
256
|
+
|
|
257
|
+
def _parse_arguments(self) -> Tuple[Literal, ...]:
|
|
258
|
+
"""``"(" , [ literal , { "," , literal } ] , ")"`` -- literals only."""
|
|
259
|
+
self._expect(TokenKind.LPAREN, "'('")
|
|
260
|
+
args: List[Literal] = []
|
|
261
|
+
if self._peek().kind is not TokenKind.RPAREN:
|
|
262
|
+
args.append(self._parse_literal())
|
|
263
|
+
while self._peek().kind is TokenKind.COMMA:
|
|
264
|
+
self._advance()
|
|
265
|
+
args.append(self._parse_literal())
|
|
266
|
+
self._expect(TokenKind.RPAREN, "')'")
|
|
267
|
+
return tuple(args)
|
|
268
|
+
|
|
269
|
+
def _parse_membership_right(self) -> Union[ListLit, Path]:
|
|
270
|
+
"""The right side of ``in``: a list literal or a path (``set<string>``)."""
|
|
271
|
+
token = self._peek()
|
|
272
|
+
if token.kind is TokenKind.LBRACKET:
|
|
273
|
+
self._advance()
|
|
274
|
+
items: List[Literal] = []
|
|
275
|
+
if self._peek().kind is not TokenKind.RBRACKET:
|
|
276
|
+
items.append(self._parse_literal())
|
|
277
|
+
while self._peek().kind is TokenKind.COMMA:
|
|
278
|
+
self._advance()
|
|
279
|
+
items.append(self._parse_literal())
|
|
280
|
+
self._expect(TokenKind.RBRACKET, "']'")
|
|
281
|
+
return ListLit(tuple(items))
|
|
282
|
+
if token.kind is TokenKind.IDENT:
|
|
283
|
+
right = self._parse_path_or_method(allow_method=False)
|
|
284
|
+
assert isinstance(right, Path) # allow_method=False
|
|
285
|
+
return right
|
|
286
|
+
raise ParseError(
|
|
287
|
+
f"the right side of 'in' is a list literal or a path, found {token}",
|
|
288
|
+
position=token.position,
|
|
289
|
+
)
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def parse_tokens(tokens: Sequence[Token]) -> Expr:
|
|
293
|
+
"""Parse an already-tokenized expression; the stream must end at ``EOF``."""
|
|
294
|
+
parser = _Parser(tokens)
|
|
295
|
+
node = parser.parse_expr()
|
|
296
|
+
if not parser.at_end():
|
|
297
|
+
rest = parser.trailing()
|
|
298
|
+
raise ParseError(f"unexpected {rest} after the expression", position=rest.position)
|
|
299
|
+
return node
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
def parse(source: str) -> Expr:
|
|
303
|
+
"""Tokenize and parse *source* into a frozen AST.
|
|
304
|
+
|
|
305
|
+
Raises ``FLX-6001`` for anything the closed grammar cannot derive and
|
|
306
|
+
``FLX-6002`` for a word reserved for ``flux-expr/2``. No type checking
|
|
307
|
+
happens here -- that is :func:`flux_engine.expr.check.check`, which needs
|
|
308
|
+
the attribute model.
|
|
309
|
+
"""
|
|
310
|
+
tokens = tokenize(source)
|
|
311
|
+
if len(tokens) == 1:
|
|
312
|
+
raise ParseError("an expression is not empty", position=0)
|
|
313
|
+
return parse_tokens(tokens)
|