Repository navigation
Expand file tree
/
Copy pathparser.py
More file actions
1593 lines (1441 loc) · 67.6 KB
/
Copy pathparser.py
File metadata and controls
1593 lines (1441 loc) · 67.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
"""Planes parser — turns tokens into AST."""
import json
import os
from dataclasses import fields as dc_fields
from dataclasses import is_dataclass
from lexer import *
from lexer import _VOCAB, GrammarDataError
from planes_num import Number
# Builtins are ordinary functions, not keywords. The parser only needs their
# names so a bare `count of xs` is read as a call rather than a variable; it
# does not need to know what they do. A user may define a function with the
# same name, and theirs is the one that runs. Source of truth is
# grammar/vocabulary.json, loaded by lexer.py as _VOCAB.
BUILTIN_NAMES = {b["name"] for b in _VOCAB["builtins"]}
class PlanesAmbiguity(PlanesSyntaxError):
"""Two or more readings of the same source, and nothing says which.
Not a malformed program — a program the name table cannot resolve.
The remedy is different (rename or parenthesise, not fix a typo), so
the class is distinct even though the base is shared: every existing
`except PlanesSyntaxError` still catches it. Parse-time only — this
never interacts with `or fail as`, which is a runtime mechanism.
"""
pass
_AMBER_TEMPLATES = None
def _load_amber_templates():
"""grammar/messages/amber.json — amber's refusal text, as data (§69.5
ruling D5). No amber message text lives inline in this file."""
global _AMBER_TEMPLATES
if _AMBER_TEMPLATES is not None:
return _AMBER_TEMPLATES
path = os.path.join(os.path.dirname(os.path.abspath(__file__)),
"grammar", "messages", "amber.json")
# Written out at each raise, not hoisted (C2, A.1) — see _load_vocabulary.
try:
with open(path, encoding="utf-8") as f:
doc = json.load(f)
except OSError as e:
raise GrammarDataError(
"grammar-data-missing",
f"{path} could not be read ({e.strerror or e})",
"reinstall planes, or regenerate with "
"python3 grammar_gen.py") from e
except json.JSONDecodeError as e:
raise GrammarDataError(
"grammar-data-missing", f"{path} is not valid JSON ({e})",
"reinstall planes, or regenerate with "
"python3 grammar_gen.py") from e
_AMBER_TEMPLATES = {t["id"]: t for t in doc["templates"]}
return _AMBER_TEMPLATES
def render_amber(template_id, line, readings, **slots):
"""Render one of amber's refusal messages from grammar/messages/amber.json.
`readings` is a list of (source, gloss) pairs, one per candidate
reading — lettered A, B, C, ... in order. `slots` fills every other
`{...}` placeholder the template uses.
"""
t = _load_amber_templates()[template_id]
lines = [t["headline"].format(line=line, **slots), ""]
for i, (source, gloss) in enumerate(readings):
letter = chr(ord("A") + i)
lines.append(t["readings"].format(letter=letter, source=source, gloss=gloss))
lines.append("")
lines.append(t["reason"].format(line=line, **slots))
lines.append(t["fix"].format(line=line, **slots))
return "\n".join(lines)
class Parser:
known_funcs: dict = {}
def __init__(self, tokens):
self.toks = tokens
self.i = 0
# A multi-line bracket literal raises the indentation on its
# continuation lines, so the tokenizer (which is oblivious to bracket
# nesting) emits a BEGIN inside the brackets whose matching END lands
# AFTER the closing bracket, at the enclosing block level. skip_bracket_ws
# consumes the BEGIN but the END leaks; parse_block would mistake it
# for the block's own close and drop every statement after the literal.
# This counts the leaked ENDs owed so skip_blank can absorb them
# before the block sees them. Zero for any program without a
# bracket literal that wraps across an indent.
self.pending_ends = 0
# ---- token helpers
def peek(self, k=0):
return self.toks[min(self.i + k, len(self.toks) - 1)]
def next(self):
t = self.toks[self.i]
self.i += 1
return t
def at(self, kind, value=None):
t = self.peek()
return t.kind == kind and (value is None or t.value == value)
def accept(self, kind, value=None):
return self.next() if self.at(kind, value) else None
def expect(self, kind, value=None, fix=None):
"""The generic token expectation, with the two ways it can name a fix.
`errors name the fix` is a language-level commitment (unbound v1.1
§22), and a bare token mismatch honours the letter of it and not the
substance: `expected }, found ':'` is true and tells nobody what to
write. Two answers, both added S8 after the corpus surfaced the
messages that had none:
* a reserved word where a NAME was wanted gets its own message,
because that is never a punctuation slip — it is the 45-name
reserved surface (32 keywords + 13 builtins) being hit. The
builtin half already errored naming the collision
(check_binding_name); this is the keyword half, in the same voice.
* every other site may pass `fix=`, a clause naming what to write
instead, in the same `\\n ...` continuation shape every other
message in this file uses.
"""
t = self.accept(kind, value)
if t is None:
g = self.peek()
found = g.value or "end of line"
if kind == "NAME" and g.value in KEYWORDS:
raise PlanesSyntaxError(
f"line {g.line}: '{found}' is a keyword, so it cannot be "
f"used as a name\n"
f" keyword names are reserved like builtins; pick "
f"another name")
# Two literal raises, not one message assembled in a variable:
# grammar_gen.py reads the catalogue off these call sites, and a
# message built up piecewise is one it has to record as
# unassembled — which would hide the fix clause from the very
# check that counts them.
if fix:
raise PlanesSyntaxError(
f"line {g.line}: expected {value or kind.lower()}, "
f"found '{found}'\n {fix}")
raise PlanesSyntaxError(
f"line {g.line}: expected {value or kind.lower()}, "
f"found '{found}'",
no_fix="this is the generic token gate, reached from every "
"form in the grammar; it knows which token was due and "
"not what the author meant by writing another, so a "
"call site that can say more passes `fix=` and a call "
"site that cannot says nothing rather than guessing")
return t
def check_binding_name(self, name, line, what):
"""A builtin name is reserved: it cannot be bound as an ordinary
variable. `<name> of x` (and the other builtin forms) is a grammar
shape, so a builtin name cannot also stand for a plain value — the
collision grammar/parser.planes hit when it used `rest` as a local
(S2). Builtins spend from the same 45-name budget as keywords
(32 + 13); the error names the collision here rather than letting it
become a confusing downstream failure. A function definition is the
one exception — `to count of x:` shadows the builtin deliberately
(the names mandate) — so this guards binding positions only, never a
funcdef or foreign NAME."""
if name in BUILTIN_NAMES:
raise PlanesSyntaxError(
f"line {line}: '{name}' is a builtin, so it cannot be {what}\n"
f" builtin names are reserved like keywords; pick another "
f"name (a function definition may still shadow it with "
f"`to {name} ...:`)")
def skip_blank(self):
# Common path first, unchanged and hot: skip blank separators. Then,
# only when a multi-line bracket literal has left an END owed (rare —
# `pending_ends` is 0 for any program without one), absorb it before
# it can be mistaken for a block close (see __init__/skip_bracket_ws).
while self.accept("EOL") or self.accept("OP", ";"):
pass
while self.pending_ends > 0 and self.at("END"):
self.accept("END")
self.pending_ends -= 1
while self.accept("EOL") or self.accept("OP", ";"):
pass
def skip_bracket_ws(self):
"""Blank tokens inside `[...]` / `{...}`.
The tokenizer tracks indentation per physical line, oblivious to
bracket nesting — a literal spanning indented lines picks up BEGIN
and END tokens that mean nothing here (brackets already carry the
structure). Consume them along with EOL/`;` so a literal can wrap
across lines the way a person writing one down would.
A BEGIN consumed here has no matching END inside the brackets — that
END lands one dedent later, outside the literal, where it would close
the enclosing block early. Record each such unmatched BEGIN in
`pending_ends` so skip_blank absorbs the leaked END instead."""
while True:
if self.accept("EOL") or self.accept("OP", ";"):
continue
if self.accept("BEGIN"):
self.pending_ends += 1
continue
if self.accept("END"):
# an END inside the brackets balances a BEGIN we already
# counted (a fully-nested indent) — cancel it, don't owe it.
if self.pending_ends > 0:
self.pending_ends -= 1
continue
break
# ---- structure
def parse_program(self):
stmts = []
self.skip_blank()
while not self.at("EOF"):
if self.accept("END"):
self.skip_blank()
continue
stmts.append(self.parse_statement())
self.skip_blank()
return stmts
def parse_block(self):
"""Indented block after ':' — or a single inline statement."""
if self.accept("EOL"):
self.expect("BEGIN")
stmts = []
self.skip_blank()
while not self.at("END") and not self.at("EOF"):
stmts.append(self.parse_statement())
self.skip_blank()
self.accept("END")
return stmts
return [self.parse_statement()]
# ---- statements
def parse_statement(self):
if self.accept("USE"):
module = self.expect("NAME").value
renames = []
with_tok = self.accept("WITH")
while with_tok:
# `use cache with load record as load cached`
# Names are multi-word, so read consecutive NAME tokens on
# both sides of `as`. `as` and `with` are reserved words, so
# neither can be part of either name. Only `old` is checked
# for amber (§69.5 site 4): it is a lookup against the used
# module's exported names, so a shorter exported prefix is
# a real second reading. `new` is not a lookup — it is the
# alias being introduced right here — and names_in_graph
# already registers it as a known name for the rest of this
# file, so checking it the same way would flag every rename
# whose alias happens to start with the name it replaces.
old = self.read_multiword_name()
self.check_rename_name_ambiguity(old, with_tok)
self.expect("AS")
new = self.read_multiword_name()
renames.append((old, new))
with_tok = self.accept("WITH")
return Use(module, tuple(renames))
if self.at("FOREIGN"):
return self.parse_foreign()
if self.at("RULE"):
return self.parse_because(self.parse_rule())
if self.at("NAME", "note") and self.peek(1).kind == "OP" and self.peek(1).value == ":":
return self.parse_note()
if self.at("TO") and self.peek(1).kind == "NAME":
return self.parse_funcdef()
if self.accept("GIVE"):
return Give(self.parse_expr())
show_tok = self.accept("SHOW")
if show_tok:
return Show(self.parse_expr(), show_tok.line)
if self.accept("WHY"):
return Why(self.parse_expr())
write_tok = self.accept("WRITE")
if write_tok:
value = self.parse_or()
self.expect("TO")
dest = self.parse_or()
return self.trailing_or_fail(WriteTo(value, dest, write_tok.line))
if self.accept("IF"):
cond = self.parse_expr()
self.expect("OP", ":")
then = self.parse_block()
els = []
save = self.i
self.skip_blank()
if self.accept("ELSE"):
self.expect("OP", ":")
els = self.parse_block()
else:
self.i = save
return If(cond, then, els)
if self.accept("WHEN"):
return self.parse_when()
if self.at("FOR"):
return self.parse_foreach(as_expr=False)
if self.accept("LET"):
tok = self.expect("NAME")
self.check_binding_name(tok.value, tok.line, "bound by `let`")
self.expect("OP", "=")
return self.parse_because(Assign(tok.value, self.parse_expr(), is_let=True))
if self.at("NAME") and self.peek(1).kind == "OP" and self.peek(1).value == "=":
tok = self.next()
self.check_binding_name(tok.value, tok.line, "assigned to")
self.next()
return self.parse_because(Assign(tok.value, self.parse_expr()))
fail_tok = self.accept("FAIL")
if fail_tok:
message = self.parse_expr()
self.expect("AS")
tag = self.expect("NAME").value
return Fail(message, tag, fail_tok.line)
return self.parse_expr()
def parse_foreign(self):
"""`foreign sort of xs from "builtins.sorted" doing nothing`
The `doing` clause is a claim, not a derived fact. Omitting it means
unknown, not pure — a foreign function whose effects nobody stated
must not disappear from the surface.
"""
foreign_tok = self.expect("FOREIGN")
parts = [self.expect("NAME").value]
while self.at("NAME"):
parts.append(self.next().value)
name = " ".join(parts)
params = []
if self.accept("OF"):
params.append(self.read_param())
while self.accept("OP", ","):
params.append(self.read_param())
self.expect("FROM")
target = self.expect("STRING").value[1:-1]
effects, declared = (), False
if self.accept("DOING"):
declared = True
claims = [self.read_claim(params)]
while self.accept("OP", ","):
claims.append(self.read_claim(params))
effects = tuple(c for c in claims if c[0] != "nothing")
return Foreign(name, params, target, effects, declared, foreign_tok.line)
def read_claim(self, params):
"""One entry in a `doing` clause: an effect kind and, optionally,
where it goes.
doing ask "https://api.example.com" a fixed destination
doing ask url whatever the caller passes
doing ask not stated
The middle form is the valuable one: naming a parameter means a call
site with a known argument resolves to the real destination, so an
effect surface can name a host across a foreign boundary.
"""
kind = self.read_effect_word()
if kind == "nothing":
return ("nothing", None)
if self.at("STRING"):
return (kind, ("literal", self.next().value[1:-1]))
if self.at("NAME") and self.peek().value in params:
return (kind, ("param", self.next().value))
if self.at("NAME"):
g = self.peek()
raise PlanesSyntaxError(
f"line {g.line}: '{g.value}' is not a parameter of this "
f"function, so it cannot be where '{kind}' goes\n"
f" parameters: {', '.join(params) or 'none'}")
return (kind, None)
def read_effect_word(self, after="'doing'", allow_nothing=True):
"""An effect name, after `doing` in a foreign claim or after `may
not` in a rule.
Effect names double as ordinary words, so most arrive as NAME. A few
(`read`, `write`, `show`, `ask`) may be builtins or reserved words;
accept whatever token carries the text.
§160: the membership check lives HERE, so an unknown effect name is
refused in every position that reads one. It used to live in
`parse_rule`, after the call — and `read_claim` made no such check, so
`foreign f of x from "m.f" doing frobnicate` parsed and silently
widened a vocabulary closed at seven, while the same word in a rule was
refused. A closed vocabulary that is only closed in one of the two
places that name it is not closed.
`allow_nothing` is an explicit parameter rather than an inference from
`after`: `nothing` is valid after `doing` (a foreign that performs
none) and not in a rule, and reading that off the message string would
tie the grammar to the wording of a message.
One message, not two. `parse_rule` used to raise its own, saying the
same thing in different words in three implementations — and the one
kept here is the more informative of the pair, because it names where
`nothing` is allowed as well as the eight kinds.
"""
t = self.peek()
word = (t.value or "nothing"
if t.kind in ("NAME", "NOTHING", "SHOW", "WRITE") else None)
known = word is not None and (
word in EFFECT_KINDS or (allow_nothing and word == "nothing"))
if not known:
found = word if word is not None else (t.value or "end of line")
raise PlanesSyntaxError(
f"line {t.line}: expected an effect name after {after}, "
f"found '{found}'\n"
f" valid kinds: {', '.join(sorted(EFFECT_KINDS))} — and "
f"'nothing' after 'doing', for a foreign that performs none")
self.next()
return word
def parse_rule(self):
"""`rule [name] subject may not kind` (forbid) or
`rule [name] subject may kind` (permit), each optionally with
`to "target"`, a `supersedes [other-name]` clause (which may itself
carry a fingerprint, `@xxxxxx`, of the rule it overrides — the
parser only checks the fingerprint's own shape; whether one was
written at all is refused where supersedes resolves, in rules.py,
since the parser has no other rule to compare against), and a
`contradicts [other-name]` clause declaring that this rule and the
named one must never both apply (B3, Track 0 #5). Fixed order:
supersedes first, then contradicts.
A rule is a constraint the checker reads, never an action the
program takes (unbound v2.0 §33) — nothing here executes anything.
"""
rule_tok = self.expect("RULE")
if not self.at("OP", "["):
g = self.peek()
raise PlanesSyntaxError(
f"line {g.line}: a rule needs a bracketed name, "
f"found '{g.value or 'end of line'}'\n"
f" try: rule [name-here] subject may not effect-kind")
self.next()
if not self.at("NAME"):
g = self.peek()
raise PlanesSyntaxError(
f"line {g.line}: a rule's bracketed name must be a word, "
f"found '{g.value or 'end of line'}'\n"
f" try: rule [name-here] subject may not effect-kind")
name = self.next().value
self.expect("OP", "]")
subject = self.expect("NAME").value
if not self.at("NAME", "may"):
g = self.peek()
raise PlanesSyntaxError(
f"line {g.line}: expected 'may not' or 'may' after a "
f"rule's subject, found '{g.value or 'end of line'}'\n"
f" try: rule [{name}] {subject} may not effect-kind "
f"(forbid)\n"
f" or: rule [{name}] {subject} may effect-kind "
f"(permit)")
self.next()
# `not` present -> forbid; absent -> permit. Neither `may` nor
# `not` is reserved for this — `not` was already NOT from logical
# negation, and `may` is read positionally, right here, only.
assertion = "forbid" if self.accept("NOT") else "permit"
verb = "may not" if assertion == "forbid" else "may"
form = f"rule [{name}] {subject} {verb} effect-kind"
# §160: the membership check moved into read_effect_word, which is the
# only place that reads an effect name, so a rule and a `doing` clause
# are now refused by the same check and the same message. `nothing` is
# a foreign's way of claiming no effect and means nothing in a rule.
kind = self.read_effect_word(after=f"'{verb}'", allow_nothing=False)
target = None
if self.accept("TO"):
target = self.expect("STRING").value[1:-1]
supersedes = None
supersedes_fingerprint = None
if self.at("NAME", "supersedes"):
self.next()
if not self.at("OP", "["):
g = self.peek()
raise PlanesSyntaxError(
f"line {g.line}: 'supersedes' needs a bracketed rule "
f"name, found '{g.value or 'end of line'}'\n"
f" try: {form} supersedes [other-rule-name]")
self.next()
if not self.at("NAME"):
g = self.peek()
raise PlanesSyntaxError(
f"line {g.line}: 'supersedes' needs a bracketed rule "
f"name, found '{g.value or 'end of line'}'\n"
f" try: {form} supersedes [other-rule-name]")
supersedes = self.next().value
self.expect("OP", "]")
if self.at("FINGERPRINT"):
supersedes_fingerprint = self.next().value[1:]
elif self.at("OP", "@"):
at_tok = self.next()
bad = self.peek()
raise PlanesSyntaxError(
f"line {at_tok.line}: a fingerprint must be exactly "
f"six hex characters after '@', found "
f"'{bad.value or 'end of line'}'\n"
f" try: {form} supersedes [{supersedes}] @abcdef")
# B3 (Track 0 #5): `contradicts [other-name]` — no fingerprint. It
# declares an incompatibility with the OTHER rule itself, not a
# claim about its current text, so unlike supersedes there is
# nothing here for a later edit to invalidate. Fixed order: this
# clause is only read after supersedes above.
contradicts = None
if self.at("NAME", "contradicts"):
self.next()
if not self.at("OP", "["):
g = self.peek()
raise PlanesSyntaxError(
f"line {g.line}: 'contradicts' needs a bracketed rule "
f"name, found '{g.value or 'end of line'}'\n"
f" try: {form} contradicts [other-rule-name]")
self.next()
if not self.at("NAME"):
g = self.peek()
raise PlanesSyntaxError(
f"line {g.line}: 'contradicts' needs a bracketed rule "
f"name, found '{g.value or 'end of line'}'\n"
f" try: {form} contradicts [other-rule-name]")
contradicts = self.next().value
self.expect("OP", "]")
return Rule(name, subject, kind, target, rule_tok.line, supersedes,
assertion, supersedes_fingerprint, contradicts=contradicts)
def parse_funcdef(self):
self.expect("TO")
parts = [self.expect("NAME").value]
while self.at("NAME"):
parts.append(self.next().value)
name = " ".join(parts)
params = []
if self.accept("OF"):
params.append(self.read_param())
while self.accept("OP", ","):
params.append(self.read_param())
self.expect("OP", ":")
return FuncDef(name, params, self.parse_block())
def read_param(self):
"""One parameter name — a binding position, so a builtin name is
rejected (a function may be named after a builtin, but its
parameters name ordinary values and cannot be)."""
tok = self.expect("NAME")
self.check_binding_name(tok.value, tok.line, "a parameter")
return tok.value
def read_tag(self):
"""An `or fail as tag` tag — a binding position when a handler
follows, since `tag` then binds the error record (a `fail … as tag`
statement's tag is a plain label, not a binding, and is not checked)."""
tok = self.expect("NAME")
self.check_binding_name(tok.value, tok.line, "an `or fail` tag")
return tok.value
def parse_foreach(self, as_expr):
self.expect("FOR")
self.expect("EACH")
var_tok = self.expect("NAME")
self.check_binding_name(var_tok.value, var_tok.line, "a `for each` loop variable")
var = var_tok.value
self.expect("IN")
source = self.parse_or()
# header may wrap: `for each s in stories` \n ` where ...: s`
wrapped = False
if self.at("EOL") and self.peek(1).kind == "BEGIN" \
and self.peek(2).kind in ("WHERE", "OP"):
self.next()
self.next()
wrapped = True
where = None
if self.accept("WHERE"):
where = self.parse_or()
self.expect("OP", ":")
if wrapped:
body = [self.parse_expr()]
self.skip_blank()
self.accept("END")
return ForEach(var, source, where, body, is_expr=True)
if as_expr:
if self.accept("EOL"):
self.expect("BEGIN")
body = [self.parse_expr()]
self.skip_blank()
self.accept("END")
else:
body = [self.parse_expr()]
return ForEach(var, source, where, body, is_expr=True)
return ForEach(var, source, where, self.parse_block(), is_expr=False)
def trailing_or_fail(self, node):
"""`or fail as tag` — same line, or indented continuation.
`as tag` may be followed by `:` and a block (indented, or a single
inline statement, same as `if`/`to`/`for each`) — the handler that
runs on failure, with `tag` bound to the error record. Without it,
the tag only renames the re-raised failure, as before.
"""
save = self.i
if self.at("OR") and self.peek(1).kind == "FAIL":
self.next()
self.next()
self.expect("AS")
tag = self.read_tag()
handler = None
if self.at("OP", ":"):
self.next()
handler = self.parse_block()
return OrFail(node, tag, handler)
if self.at("EOL") and self.peek(1).kind == "BEGIN" \
and self.peek(2).kind == "OR" and self.peek(3).kind == "FAIL":
self.next()
self.next()
self.next()
self.next()
self.expect("AS")
tag = self.read_tag()
handler = None
if self.at("OP", ":"):
self.next()
handler = self.parse_block()
self.skip_blank()
self.accept("END")
return OrFail(node, tag, handler)
self.i = save
return node
def parse_because(self, attach):
"""A trailing `because "..."` on an Assign or Rule — same line, or
an indented continuation (matching `trailing_or_fail`'s wrapped
form). `because` is read positionally, right here, only — like
`may` and `is` — so it stays free as an ordinary name everywhere
else (test_names.py's reserved-word ceiling).
"""
save = self.i
if self.at("NAME", "because"):
self.next()
return self.finish_because(attach)
if self.at("EOL") and self.peek(1).kind == "BEGIN" \
and self.peek(2).kind == "NAME" and self.peek(2).value == "because":
self.next()
self.next()
self.next()
node = self.finish_because(attach)
self.skip_blank()
self.accept("END")
return node
self.i = save
return attach
def finish_because(self, attach):
g = self.peek()
if not self.at("STRING"):
raise PlanesSyntaxError(
f"line {g.line}: 'because' needs a quoted reason\n"
f' try: cap = 200 because "the reason"')
text = self.next().value[1:-1]
attach.annotation = Because(text, g.line)
return attach
def parse_note(self):
"""`note:` followed by an indented block of `from "..."` and
`derives-from [rule-name]` entries — or a single inline entry.
Never executes; the interpreter raises if one reaches it.
"""
note_tok = self.next() # 'note'
self.expect("OP", ":")
entries = []
if self.accept("EOL"):
self.expect("BEGIN")
self.skip_blank()
while not self.at("END") and not self.at("EOF"):
entries.append(self.parse_note_entry())
self.skip_blank()
self.accept("END")
else:
entries.append(self.parse_note_entry())
return Note(entries, note_tok.line)
def parse_note_entry(self):
if self.at("FROM"):
self.next()
if not self.at("STRING"):
g = self.peek()
raise PlanesSyntaxError(
f"line {g.line}: 'from' in a note needs a quoted source\n"
f' try: from "the source"')
return ("from", self.next().value[1:-1])
if self.at("NAME", "derives-from"):
self.next()
if not self.at("OP", "["):
g = self.peek()
raise PlanesSyntaxError(
f"line {g.line}: 'derives-from' needs a bracketed rule "
f"name, found '{g.value or 'end of line'}'\n"
f" try: derives-from [rule-name]")
self.next()
if not self.at("NAME"):
g = self.peek()
raise PlanesSyntaxError(
f"line {g.line}: 'derives-from' needs a bracketed rule "
f"name, found '{g.value or 'end of line'}'\n"
f" try: derives-from [rule-name]")
name = self.next().value
self.expect("OP", "]")
return ("derives-from", name)
g = self.peek()
raise PlanesSyntaxError(
f"line {g.line}: unrecognised entry in a note, "
f"found '{g.value or 'end of line'}'\n"
f' try: from "source" or derives-from [rule-name]')
# ---- expressions
def parse_expr(self):
return self.trailing_or_fail(self.trailing_with(self.parse_or()))
# Field names a with-clause or when-pattern entry may use — the same
# keyword-as-field-name exception parse_record_field grants, since
# both are naming a record field, not opening a new construct. Source
# of truth is grammar/vocabulary.json's field_name_token_kinds.
FIELD_NAME_KINDS = tuple(_VOCAB["field_name_token_kinds"])
def at_field_start(self, ahead=0):
t = self.peek(ahead)
nxt = self.peek(ahead + 1)
return (t.kind in self.FIELD_NAME_KINDS
and nxt.kind == "OP" and nxt.value == ":")
def trailing_with(self, node):
"""`<expr> with name: expr, name: expr, ...` — record update
(v5.0 §72), never braced (that is RecordLit). Distinct from the
module-rename `with` (`use x with a as b`), which parse_statement's
Use branch parses entirely on its own and never reaches here.
Chains: `p with a: 1 with b: 2` is two nested RecordUpdate nodes,
left to right — "compose like any other expression" (§72).
"""
while self.at("WITH") and self.at_field_start(1):
self.next()
fields = [self.parse_with_field()]
while self.accept("OP", ","):
if not self.at_field_start(0):
self.i -= 1 # this comma belongs to an outer
# context (a call's argument list, a
# list literal, ...), not another field
break
fields.append(self.parse_with_field())
node = RecordUpdate(node, fields)
return node
def parse_with_field(self):
"""`name: expr` inside a with-clause. Not parse_record_field: that
one reads its value through parse_expr, which would re-enter
trailing_with and let a *following* with-clause attach to this
field's value instead of to the RecordUpdate as a whole —
`p with a: 1 with b: 2` must chain onto `p with a: 1`, not parse
as `p with a: (1 with b: 2)`. Everything parse_expr does except
the with-chain itself, since that part is precisely what must not
recurse here.
"""
self.skip_bracket_ws()
t = self.peek()
if t.kind in self.FIELD_NAME_KINDS:
key = self.next().value
else:
raise PlanesSyntaxError(
f"line {t.line}: expected a field name, "
f"found '{t.value or 'end of line'}'\n"
f" try: with name: value")
self.expect("OP", ":")
return (key, self.trailing_or_fail(self.parse_or()))
def parse_or(self):
left = self.parse_and()
while self.at("OR") and self.peek(1).kind != "FAIL":
self.next()
left = BinOp("or", left, self.parse_and())
return left
def parse_and(self):
left = self.parse_not()
while self.accept("AND"):
left = BinOp("and", left, self.parse_not())
return left
def parse_not(self):
if self.accept("NOT"):
return Not(self.parse_not())
return self.parse_comparison()
def parse_comparison(self):
left = self.parse_plus()
while (self.at("OP") and self.peek().value in
("<", ">", "<=", ">=", "==", "!=")) or self.at("IN") \
or (self.at("NAME", "is") and self.peek(1).kind == "NOTHING"):
# `is` is read positionally, right here, only — like `may` in
# parse_rule — so a program that never writes `is nothing`
# still has `is` free as an ordinary name (test_names.py's
# reserved-word ceiling). Requiring NOTHING to follow (rather
# than accepting bare `is` unconditionally) is what lets
# `when subject is { ... }` use the same word positionally,
# one level up in parse_when, without this loop swallowing it
# first and demanding a NOTHING that was never coming.
if self.accept("NAME", "is"):
self.expect("NOTHING")
left = IsNothing(left)
continue
if self.accept("IN"):
left = BinOp("in", left, self.parse_plus())
else:
left = BinOp(self.next().value, left, self.parse_plus())
return left
def parse_plus(self):
"""`base plus item` (v5.0 §72) — a named binary connective, bound
below arithmetic so `xs plus a + b` reads as `xs plus (a + b)`."""
left = self.parse_additive()
while self.at("PLUS"):
self.next()
left = ListPlus(left, self.parse_additive())
return left
def parse_additive(self):
left = self.parse_multiplicative()
while self.at("OP") and self.peek().value in ("+", "-"):
left = BinOp(self.next().value, left, self.parse_multiplicative())
return left
def parse_multiplicative(self):
left = self.parse_unary()
while self.at("OP") and self.peek().value in ("*", "/"):
left = BinOp(self.next().value, left, self.parse_unary())
return left
def parse_unary(self):
if self.at("OP", "-"):
self.next()
return BinOp("-", Num(0), self.parse_unary())
return self.parse_postfix()
def parse_postfix(self):
node = self.parse_primary()
while self.at("OP", ".") and (self.peek(1).kind == "NAME"
or self.peek(1).value in KEYWORDS):
# A field name is not a position where a reserved word can be
# structural — records nest arbitrarily (v2.0 §35) and a field
# may be named `first`, `to`, or any other ordinary word that
# happens to double as a keyword elsewhere.
self.next()
node = Field(node, self.next().value)
if self.at("OP", "["):
# Planes has no index or slice syntax. Without this check,
# `s[1]` does not raise at all: parse_primary returns Var("s")
# for the name, the statement ends there, and the leftover
# `[1]` tokens are read as an unrelated second statement — a
# list literal, evaluated and silently discarded. `c = s[1]`
# then binds `c` to the whole string, not a character, with
# nothing to say so (found by direct AST inspection,
# PROBE_LEXER.md §2). This does not add indexing; it turns a
# silent misparse into a syntax error naming what exists
# instead (`first n of x`).
g = self.peek()
raise PlanesSyntaxError(
f"line {g.line}: '[' has no meaning here — Planes has no "
f"index or slice syntax\n"
f" try: first n of x — takes the first n code points or "
f"items; there is no way to take one position or a range")
return node
def read_multiword_name(self):
"""Read a multi-word name: every consecutive NAME token, stopping
at the first non-NAME.
Names are several NAME tokens, so a clause like `load record as
load cached` needs a rule for where one name ends. This works only
because both of this method's callers' terminators (`as`, `with`)
are reserved words and therefore never arrive as NAME — there is
no lookahead for a specific stop word here, despite what an
earlier version of this docstring (and an unused `*stops`
parameter) implied.
"""
parts = []
while self.at("NAME"):
parts.append(self.next().value)
if not parts:
g = self.peek()
raise PlanesSyntaxError(
f"line {g.line}: expected a name, "
f"found '{g.value or 'end of line'}'\n"
f" a name here is one or more plain words — the old or the "
f"new spelling in a `use ... with <old> as <new>` rename; a "
f"quoted string, a number, or a punctuation mark cannot stand "
f"for one")
return " ".join(parts)
def check_rename_name_ambiguity(self, name, tok):
"""Amber site 4 (§69.5). `name` (the `old` half of a rename — a
lookup against the used module's exported names, via parse()'s
`known`) was just consumed whole by read_multiword_name, with no
table consulted. Check every prefix of it against known_funcs —
two or more matching prefixes means the greedy full consumption
was not the only viable reading.
"""
parts = name.split(" ")
hits = [k for k in range(1, len(parts) + 1)
if " ".join(parts[:k]) in Parser.known_funcs]
if len(hits) < 2:
return
readings = []
for k in hits:
prefix = " ".join(parts[:k])
rest = " ".join(parts[k:])
gloss = (f"`{prefix}` alone" if not rest
else f"`{prefix}`, leaving `{rest}` unaccounted for")
readings.append((prefix if not rest else f"{prefix} | {rest}", gloss))
msg = render_amber("amber.rename_clause", tok.line, readings, source=name)
raise PlanesAmbiguity(msg)
# ---- amber (§69.5): message construction helpers, never consuming
def _peek_text(self, start, end):
"""Token values from offset `start` (inclusive) to `end`
(exclusive), space-joined — a best-effort source reconstruction
for an amber message, not a claim about original spacing."""
return " ".join(self.peek(k).value or self.peek(k).kind for k in range(start, end))
def _peek_trailer(self, offset, limit=4):
"""Up to `limit` tokens starting at `offset`, for an amber
message. Stops at a statement boundary so the trailer reads as a
fragment, not a runaway scan."""
end = offset
for i in range(limit):
tok = self.peek(offset + i)
if tok.kind in ("EOL", "EOF", "END", "BEGIN"):
break
end = offset + i + 1
if tok.kind == "OP" and tok.value in (":", ";"):
break
return self._peek_text(offset, end)
def _matching_close_paren_offset(self, open_offset):
"""Offset of the token just after the `)` matching the `(` at
`open_offset`. Never consumes — paren_is_arglist does the same
scan for its own decision; this is the read-only twin used only
to build an amber message."""
depth, k = 0, open_offset
while True:
tok = self.peek(k)
if tok.kind == "OP" and tok.value == "(":
depth += 1
elif tok.kind == "OP" and tok.value == ")":
depth -= 1
if depth == 0:
return k + 1
k += 1
def raise_amber_multiword(self, t, name, bare_hit, ext_hits):
readings = []
labels = []
if bare_hit:
trailer = self._peek_trailer(0)
source = name if not trailer else f"{name} then {trailer}"
readings.append((source, f"the value `{name}`, then whatever parses next on its own"))
labels.append(f"`{name}`")
for k, probe in ext_hits:
trailer = self._peek_trailer(k)
source = probe if not trailer else f"{probe} {trailer}"
readings.append((source, f"one call to `{probe}`"))
labels.append(f"`{probe}`")