gleplot 6.0.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.
@@ -0,0 +1,756 @@
1
+ """Structural parser for GLE source: text -> document tree -> text.
2
+
3
+ The prime directive is **byte-exact round-tripping**: for any input ``text``,
4
+ ``emit(parse_gle_source(text))`` must reproduce ``text`` byte-for-byte when no
5
+ node has been modified. To guarantee this, every physical line is stored with
6
+ its raw text and its original line ending, and :func:`emit` simply concatenates
7
+ the raw text of every node's lines unless a node has been explicitly replaced.
8
+
9
+ The parser layers a *structural view* on top of the flat line list so a later
10
+ semantic mapper can walk graph blocks and their statements without losing the
11
+ verbatim source. Structure problems (unbalanced ``begin``/``end`` blocks, etc.)
12
+ never raise -- they are recorded as :class:`ParseWarning` and the offending
13
+ lines fall back to plain statements.
14
+
15
+ Document model (see classes below):
16
+
17
+ GleDocument
18
+ .lines : list[SourceLine] -- every physical line, in order
19
+ .nodes : list[Node] -- ordered top-level structural view
20
+ .warnings : list[ParseWarning]
21
+
22
+ Node = Statement | GraphBlock | OpaqueBlock | BlankOrComment
23
+
24
+ Structural nodes reference the ``SourceLine`` objects they were built from, so
25
+ raw preservation and the structural walk share the same underlying storage.
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ from dataclasses import dataclass, field
31
+ from typing import List, Optional, Tuple, Union
32
+
33
+ from .lexer import Token, TokenType, tokenize_line
34
+
35
+ __all__ = [
36
+ "SourceLine",
37
+ "Statement",
38
+ "GraphBlock",
39
+ "OpaqueBlock",
40
+ "BlankOrComment",
41
+ "Node",
42
+ "ParseWarning",
43
+ "GleDocument",
44
+ "parse_gle_source",
45
+ "emit",
46
+ "split_statements",
47
+ ]
48
+
49
+
50
+ # --------------------------------------------------------------------------- #
51
+ # Line-level storage
52
+ # --------------------------------------------------------------------------- #
53
+
54
+
55
+ @dataclass
56
+ class SourceLine:
57
+ """One physical line of source, stored verbatim for round-tripping.
58
+
59
+ Attributes
60
+ ----------
61
+ line_no:
62
+ 1-based index of the line in the original source.
63
+ text:
64
+ The line content *without* its terminator (see ``ending``).
65
+ ending:
66
+ The exact line terminator that followed this line in the source --
67
+ ``"\\n"``, ``"\\r\\n"``, ``"\\r"``, or ``""`` for a final line with no
68
+ trailing newline. ``text + ending`` reproduces the original slice.
69
+ """
70
+
71
+ line_no: int
72
+ text: str
73
+ ending: str = "\n"
74
+
75
+ @property
76
+ def raw(self) -> str:
77
+ """The exact original bytes of this line including its terminator."""
78
+ return self.text + self.ending
79
+
80
+
81
+ # --------------------------------------------------------------------------- #
82
+ # Statement (possibly one of several on a ``;``-separated line)
83
+ # --------------------------------------------------------------------------- #
84
+
85
+
86
+ @dataclass
87
+ class Statement:
88
+ """A single GLE statement.
89
+
90
+ A statement corresponds to one ``;``-separated chunk of a physical line.
91
+ Most lines have exactly one statement (``sub_index == 0``); a line like
92
+ ``set hei 0.5; amove 1 1`` yields two statements sharing the same
93
+ ``source_line`` but with ``sub_index`` 0 and 1.
94
+
95
+ Attributes
96
+ ----------
97
+ tokens:
98
+ Lexer tokens for this statement's segment.
99
+ raw:
100
+ The verbatim source text of this statement's segment (excluding the
101
+ ``;`` separator and line ending). Used only for inspection; emission
102
+ of *unmodified* documents always goes through the owning
103
+ ``SourceLine`` to preserve exact bytes including separators.
104
+ line_no:
105
+ 1-based physical line number.
106
+ sub_index:
107
+ 0-based index of this statement within its physical line.
108
+ source_line:
109
+ Back-reference to the owning :class:`SourceLine`.
110
+ replacement:
111
+ If set (via :meth:`GleDocument.replace_statement`), the new text that
112
+ should be emitted in place of this statement. ``None`` means emit the
113
+ original bytes.
114
+ """
115
+
116
+ tokens: List[Token]
117
+ raw: str
118
+ line_no: int
119
+ sub_index: int = 0
120
+ source_line: Optional[SourceLine] = None
121
+ replacement: Optional[str] = None
122
+
123
+ @property
124
+ def keyword(self) -> Optional[str]:
125
+ """Lower-cased first WORD token, or ``None`` for an empty statement.
126
+
127
+ This is the primary handle the semantic mapper uses to dispatch on a
128
+ statement (``"amove"``, ``"data"``, ``"set"``, ...). Case is folded
129
+ for matching; original case is preserved in ``tokens``.
130
+ """
131
+ for tok in self.tokens:
132
+ if tok.type is TokenType.COMMENT:
133
+ continue
134
+ if tok.type is TokenType.WORD:
135
+ return tok.value.lower()
136
+ # First meaningful token is not a word (number/op/string) -> the
137
+ # statement has no keyword to dispatch on.
138
+ return None
139
+ return None
140
+
141
+ @property
142
+ def is_blank(self) -> bool:
143
+ """True if the statement carries no meaningful (non-comment) tokens."""
144
+ return all(t.type is TokenType.COMMENT for t in self.tokens)
145
+
146
+
147
+ # --------------------------------------------------------------------------- #
148
+ # Block nodes
149
+ # --------------------------------------------------------------------------- #
150
+
151
+
152
+ @dataclass
153
+ class GraphBlock:
154
+ """A ``begin graph`` ... ``end graph`` block, descended into.
155
+
156
+ Attributes
157
+ ----------
158
+ begin:
159
+ The ``begin graph`` statement.
160
+ end:
161
+ The ``end graph`` statement, or ``None`` if the block was left open at
162
+ end of file (a recorded warning accompanies this).
163
+ body:
164
+ Ordered structural nodes between ``begin`` and ``end``. Contains
165
+ :class:`Statement`, :class:`BlankOrComment`, and any nested
166
+ :class:`OpaqueBlock` nodes.
167
+ """
168
+
169
+ begin: Statement
170
+ end: Optional[Statement]
171
+ body: List["Node"] = field(default_factory=list)
172
+
173
+ @property
174
+ def line_no(self) -> int:
175
+ return self.begin.line_no
176
+
177
+
178
+ @dataclass
179
+ class OpaqueBlock:
180
+ """A non-graph ``begin X`` ... ``end X`` block passed through wholesale.
181
+
182
+ Block types such as ``text``, ``tex``, ``object``, ``key``, ``path``,
183
+ ``translate``, ``rotate``, ``scale``, ``origin``, ``clip``, ``table``,
184
+ ``name``, ``box``, ``length`` are not interpreted structurally -- their
185
+ inner lines are kept as raw :class:`SourceLine` objects and re-emitted
186
+ verbatim. The semantic mapper generally skips these.
187
+
188
+ Attributes
189
+ ----------
190
+ block_type:
191
+ Lower-cased block name (``"text"``, ``"object"``, ...).
192
+ begin:
193
+ The opening ``begin <type>`` statement.
194
+ end:
195
+ The closing ``end <type>`` statement, or ``None`` if unclosed.
196
+ inner_lines:
197
+ The raw source lines strictly between begin and end.
198
+ """
199
+
200
+ block_type: str
201
+ begin: Statement
202
+ end: Optional[Statement]
203
+ inner_lines: List[SourceLine] = field(default_factory=list)
204
+
205
+ @property
206
+ def line_no(self) -> int:
207
+ return self.begin.line_no
208
+
209
+
210
+ @dataclass
211
+ class BlankOrComment:
212
+ """A physical line that is blank or comment-only.
213
+
214
+ Kept as its own node type so structure walkers can trivially skip these
215
+ while emission still reproduces them verbatim.
216
+ """
217
+
218
+ statement: Statement
219
+
220
+ @property
221
+ def line_no(self) -> int:
222
+ return self.statement.line_no
223
+
224
+
225
+ Node = Union[Statement, GraphBlock, OpaqueBlock, BlankOrComment]
226
+
227
+
228
+ # --------------------------------------------------------------------------- #
229
+ # Warnings
230
+ # --------------------------------------------------------------------------- #
231
+
232
+
233
+ @dataclass
234
+ class ParseWarning:
235
+ """A recoverable structure problem noted during parsing.
236
+
237
+ Never fatal. ``line_no`` points at the offending line; ``message`` is a
238
+ short human-readable description.
239
+ """
240
+
241
+ line_no: int
242
+ message: str
243
+
244
+ def __str__(self) -> str: # pragma: no cover - convenience only
245
+ return f"line {self.line_no}: {self.message}"
246
+
247
+
248
+ # --------------------------------------------------------------------------- #
249
+ # Document
250
+ # --------------------------------------------------------------------------- #
251
+
252
+ # Non-graph block types that are captured opaquely. This is a permissive set:
253
+ # any ``begin <word>`` that is not ``graph`` is treated opaquely regardless of
254
+ # whether it appears here, but the set documents the known GLE block keywords.
255
+ KNOWN_OPAQUE_BLOCKS = frozenset(
256
+ {
257
+ "text",
258
+ "tex",
259
+ "object",
260
+ "key",
261
+ "path",
262
+ "translate",
263
+ "rotate",
264
+ "scale",
265
+ "origin",
266
+ "clip",
267
+ "table",
268
+ "name",
269
+ "box",
270
+ "length",
271
+ }
272
+ )
273
+
274
+
275
+ @dataclass
276
+ class GleDocument:
277
+ """Parsed GLE document with verbatim line storage and a structural view.
278
+
279
+ Use :func:`parse_gle_source` to build one and :func:`emit` (or the
280
+ :meth:`emit` method) to serialise. See module docstring for the model.
281
+ """
282
+
283
+ lines: List[SourceLine]
284
+ nodes: List[Node]
285
+ warnings: List[ParseWarning] = field(default_factory=list)
286
+
287
+ # -- serialisation -------------------------------------------------------
288
+
289
+ def emit(self) -> str:
290
+ """Serialise the document back to text.
291
+
292
+ Byte-identical to the parsed input when no statement was replaced.
293
+ Replaced statements are rendered from their ``replacement`` text; all
294
+ other content comes straight from the stored raw line bytes.
295
+ """
296
+ return _emit_lines(self.lines)
297
+
298
+ # -- structural navigation ----------------------------------------------
299
+
300
+ @property
301
+ def graphs(self) -> List[GraphBlock]:
302
+ """All top-level graph blocks, in document order.
303
+
304
+ (Graph blocks nested inside opaque blocks are not exposed here; GLE
305
+ does not nest graphs in practice.)
306
+ """
307
+ return [n for n in self.nodes if isinstance(n, GraphBlock)]
308
+
309
+ def statements(self) -> List[Statement]:
310
+ """Flatten to every :class:`Statement` in the document, in order.
311
+
312
+ Includes preamble/interlude statements, graph-block body statements,
313
+ and the begin/end statements of graph blocks. Opaque block inner lines
314
+ are *not* included (they are raw-only). Blank/comment lines are
315
+ included via their wrapped statement so callers can see them.
316
+ """
317
+ out: List[Statement] = []
318
+ for node in self.nodes:
319
+ out.extend(_iter_statements(node))
320
+ return out
321
+
322
+ # -- modification API (sketch for the semantic layer) --------------------
323
+
324
+ def replace_statement(self, statement: Statement, new_text: str) -> None:
325
+ """Replace a single statement's emitted text.
326
+
327
+ Minimal support intended to be driven by the semantic mapper. The
328
+ statement's ``replacement`` is set and its owning :class:`SourceLine`
329
+ is rewritten by re-rendering all statements on that physical line
330
+ (so a multi-statement line rejoins with ``;`` separators preserved
331
+ from the original where possible).
332
+
333
+ Notes
334
+ -----
335
+ Emission of a modified line reconstructs it from the line's statement
336
+ segments; leading indentation and inter-statement separators from the
337
+ original line are preserved for statements that were *not* replaced.
338
+ Byte-exactness is only guaranteed for statements left untouched; a
339
+ replaced statement is emitted exactly as ``new_text`` (the caller owns
340
+ its formatting).
341
+ """
342
+ statement.replacement = new_text
343
+ src = statement.source_line
344
+ if src is None:
345
+ return
346
+ src.text = _render_line_text(src, self)
347
+
348
+
349
+ # --------------------------------------------------------------------------- #
350
+ # Statement splitting (quote-aware, respects comments)
351
+ # --------------------------------------------------------------------------- #
352
+
353
+
354
+ def split_statements(text: str) -> List[Tuple[str, int]]:
355
+ """Split a physical line into ``;``-separated statement segments.
356
+
357
+ Splitting is quote-aware (``;`` inside a double- or single-quoted string
358
+ does not split) and comment-aware (a ``!`` comment runs to end of line, so
359
+ a ``;`` inside a comment does not split).
360
+
361
+ Returns a list of ``(segment_text, start_offset)`` pairs. The segments,
362
+ when rejoined with ``;`` at the recorded offsets, reproduce the line. A
363
+ line with no top-level ``;`` returns a single segment covering the whole
364
+ line.
365
+ """
366
+ segments: List[Tuple[str, int]] = []
367
+ n = len(text)
368
+ seg_start = 0
369
+ i = 0
370
+ in_string: Optional[str] = None
371
+ in_comment = False
372
+
373
+ while i < n:
374
+ c = text[i]
375
+ if in_comment:
376
+ i += 1
377
+ continue
378
+ if in_string is not None:
379
+ # A doubled quote is GLE's embedded quote, not the closer.
380
+ if c == in_string and i + 1 < n and text[i + 1] == in_string:
381
+ i += 2
382
+ continue
383
+ if c == in_string:
384
+ in_string = None
385
+ i += 1
386
+ continue
387
+ # Not in string/comment.
388
+ if c == '"' or c == "'":
389
+ in_string = c
390
+ i += 1
391
+ continue
392
+ if c == "!":
393
+ in_comment = True
394
+ i += 1
395
+ continue
396
+ if c == ";":
397
+ segments.append((text[seg_start:i], seg_start))
398
+ i += 1
399
+ seg_start = i
400
+ continue
401
+ i += 1
402
+
403
+ segments.append((text[seg_start:n], seg_start))
404
+ return segments
405
+
406
+
407
+ # --------------------------------------------------------------------------- #
408
+ # Parsing
409
+ # --------------------------------------------------------------------------- #
410
+
411
+
412
+ def parse_gle_source(text: str) -> GleDocument:
413
+ """Parse GLE source text into a :class:`GleDocument`.
414
+
415
+ Never raises on structural problems. See module docstring for the model
416
+ and guarantees.
417
+ """
418
+ lines = _split_physical_lines(text)
419
+ warnings: List[ParseWarning] = []
420
+
421
+ # First pass: build a Statement (or several) per physical line, and wrap
422
+ # blank/comment-only lines. This flat list is what the structural pass
423
+ # consumes.
424
+ per_line: List[List[Statement]] = []
425
+ for src in lines:
426
+ stmts = _statements_for_line(src)
427
+ per_line.append(stmts)
428
+
429
+ # Second pass: structural grouping into nodes with begin/end pairing.
430
+ nodes = _build_structure(lines, per_line, warnings)
431
+
432
+ return GleDocument(lines=lines, nodes=nodes, warnings=warnings)
433
+
434
+
435
+ def _split_physical_lines(text: str) -> List[SourceLine]:
436
+ """Split source into :class:`SourceLine` objects preserving line endings.
437
+
438
+ Handles ``\\n``, ``\\r\\n`` and lone ``\\r``. A trailing newline does *not*
439
+ create a spurious empty final line; a file with no trailing newline keeps
440
+ its last line's ``ending == ""``. An empty input yields no lines.
441
+ """
442
+ if text == "":
443
+ return []
444
+
445
+ lines: List[SourceLine] = []
446
+ n = len(text)
447
+ i = 0
448
+ line_no = 1
449
+ start = 0
450
+ while i < n:
451
+ c = text[i]
452
+ if c == "\r":
453
+ if i + 1 < n and text[i + 1] == "\n":
454
+ lines.append(SourceLine(line_no, text[start:i], "\r\n"))
455
+ i += 2
456
+ else:
457
+ lines.append(SourceLine(line_no, text[start:i], "\r"))
458
+ i += 1
459
+ line_no += 1
460
+ start = i
461
+ elif c == "\n":
462
+ lines.append(SourceLine(line_no, text[start:i], "\n"))
463
+ i += 1
464
+ line_no += 1
465
+ start = i
466
+ else:
467
+ i += 1
468
+
469
+ if start < n:
470
+ # Final line with no trailing terminator.
471
+ lines.append(SourceLine(line_no, text[start:n], ""))
472
+ return lines
473
+
474
+
475
+ def _statements_for_line(src: SourceLine) -> List[Statement]:
476
+ """Produce the statement(s) for one physical line."""
477
+ segments = split_statements(src.text)
478
+ stmts: List[Statement] = []
479
+ for sub_index, (seg_text, _offset) in enumerate(segments):
480
+ tokens = tokenize_line(seg_text)
481
+ stmts.append(
482
+ Statement(
483
+ tokens=tokens,
484
+ raw=seg_text,
485
+ line_no=src.line_no,
486
+ sub_index=sub_index,
487
+ source_line=src,
488
+ )
489
+ )
490
+ return stmts
491
+
492
+
493
+ def _begin_target(stmt: Statement) -> Optional[str]:
494
+ """If ``stmt`` is a ``begin <word>``, return the lower-cased target word."""
495
+ words = [t for t in stmt.tokens if t.type is TokenType.WORD]
496
+ if len(words) >= 2 and words[0].value.lower() == "begin":
497
+ return words[1].value.lower()
498
+ if len(words) == 1 and words[0].value.lower() == "begin":
499
+ # ``begin`` with no target -- malformed; caller records a warning.
500
+ return ""
501
+ return None
502
+
503
+
504
+ def _is_end(stmt: Statement, target: Optional[str] = None) -> bool:
505
+ """True if ``stmt`` is ``end`` (optionally ``end <target>``)."""
506
+ words = [t for t in stmt.tokens if t.type is TokenType.WORD]
507
+ if not words or words[0].value.lower() != "end":
508
+ return False
509
+ if target is None:
510
+ return True
511
+ if len(words) >= 2:
512
+ return words[1].value.lower() == target
513
+ # Bare ``end`` closes whatever block is open.
514
+ return True
515
+
516
+
517
+ def _build_structure(
518
+ lines: List[SourceLine],
519
+ per_line: List[List[Statement]],
520
+ warnings: List[ParseWarning],
521
+ ) -> List[Node]:
522
+ """Group flat statements into the ordered top-level node list.
523
+
524
+ Handles begin/end pairing for graph blocks (structural) and other block
525
+ types (opaque). Multi-statement lines are handled per-statement, but a
526
+ ``begin``/``end`` is only recognised when it is the sole statement on its
527
+ line -- GLE never mixes block delimiters with other statements on a line,
528
+ and treating a mid-line ``begin`` as a block opener would badly mangle
529
+ round-tripping, so mixed lines pass through as plain statements.
530
+ """
531
+ nodes: List[Node] = []
532
+ open_statements: List[str] = []
533
+ n_lines = len(per_line)
534
+ idx = 0
535
+ while idx < n_lines:
536
+ stmts = per_line[idx]
537
+
538
+ # Multi-statement line, or single non-delimiter line.
539
+ if len(stmts) == 1:
540
+ stmt = stmts[0]
541
+ target = _begin_target(stmt)
542
+ if target is not None and target != "":
543
+ consumed, node = _consume_block(
544
+ lines, per_line, idx, target, stmt, warnings
545
+ )
546
+ nodes.append(node)
547
+ idx = consumed
548
+ continue
549
+ if target == "":
550
+ warnings.append(
551
+ ParseWarning(
552
+ stmt.line_no, "'begin' with no block type; treated as statement"
553
+ )
554
+ )
555
+ nodes.append(_wrap_single(stmt))
556
+ idx += 1
557
+ continue
558
+ words = [t.value.lower() for t in stmt.tokens if t.type is TokenType.WORD]
559
+ # A 'sub' and a multi-line 'if ... then' are closed by 'end sub'
560
+ # and 'end if', not by the end of a 'begin' block.
561
+ if words[0:1] == ["sub"] or (words[0:1] == ["if"] and words[-1] == "then"):
562
+ open_statements.append(words[0])
563
+ elif words[0:1] == ["end"]:
564
+ if (
565
+ words[1:2] in (["sub"], ["if"])
566
+ and open_statements[-1:] == words[1:2]
567
+ ):
568
+ open_statements.pop()
569
+ else:
570
+ # A stray 'end' with no matching open block at this level.
571
+ warnings.append(
572
+ ParseWarning(
573
+ stmt.line_no,
574
+ "'end' without matching 'begin'; treated as statement",
575
+ )
576
+ )
577
+ nodes.append(_wrap_single(stmt))
578
+ idx += 1
579
+ else:
580
+ # Multi-statement line: emit each statement as its own node. Block
581
+ # delimiters mixed into such lines are not treated structurally.
582
+ for stmt in stmts:
583
+ nodes.append(_wrap_single(stmt))
584
+ idx += 1
585
+
586
+ return nodes
587
+
588
+
589
+ def _wrap_single(stmt: Statement) -> Node:
590
+ """Wrap a lone statement as the appropriate leaf node."""
591
+ if stmt.is_blank:
592
+ return BlankOrComment(stmt)
593
+ return stmt
594
+
595
+
596
+ def _consume_block(
597
+ lines: List[SourceLine],
598
+ per_line: List[List[Statement]],
599
+ begin_idx: int,
600
+ target: str,
601
+ begin_stmt: Statement,
602
+ warnings: List[ParseWarning],
603
+ ) -> Tuple[int, Node]:
604
+ """Consume a begin..end block starting at ``begin_idx``.
605
+
606
+ Returns ``(next_index, node)``. For ``target == "graph"`` produces a
607
+ :class:`GraphBlock` with a structured body; for anything else an
608
+ :class:`OpaqueBlock` with raw inner lines. Unbalanced blocks are recovered:
609
+ an unclosed block extends to end of file with a recorded warning.
610
+ """
611
+ n_lines = len(per_line)
612
+
613
+ if target == "graph":
614
+ body: List[Node] = []
615
+ j = begin_idx + 1
616
+ while j < n_lines:
617
+ stmts = per_line[j]
618
+ if len(stmts) == 1:
619
+ s = stmts[0]
620
+ inner_target = _begin_target(s)
621
+ if inner_target is not None and inner_target != "":
622
+ consumed, inner_node = _consume_block(
623
+ lines, per_line, j, inner_target, s, warnings
624
+ )
625
+ body.append(inner_node)
626
+ j = consumed
627
+ continue
628
+ if _is_end(s, "graph") or _is_end_bare(s):
629
+ return j + 1, GraphBlock(begin=begin_stmt, end=s, body=body)
630
+ body.append(_wrap_single(s))
631
+ j += 1
632
+ else:
633
+ for s in stmts:
634
+ body.append(_wrap_single(s))
635
+ j += 1
636
+ # Ran off the end without an 'end graph'.
637
+ warnings.append(
638
+ ParseWarning(
639
+ begin_stmt.line_no, "'begin graph' not closed before end of file"
640
+ )
641
+ )
642
+ return n_lines, GraphBlock(begin=begin_stmt, end=None, body=body)
643
+
644
+ # Opaque block: gather raw inner lines until the matching (or bare) end.
645
+ # Nested begin/end pairs stay raw lines (we do not descend). The stack
646
+ # is the open block names, outermost first. ``end <name>`` pops only
647
+ # when <name> is the innermost open block; a bare ``end`` pops that
648
+ # innermost block whatever it is called. A line that merely starts with
649
+ # ``end`` (``end of caption``) is prose and does not change the stack,
650
+ # so it cannot close this block or the one nested inside it.
651
+ inner: List[SourceLine] = []
652
+ stack = [target]
653
+ j = begin_idx + 1
654
+ while j < n_lines:
655
+ stmts = per_line[j]
656
+ if len(stmts) == 1:
657
+ s = stmts[0]
658
+ begun = _begin_target(s)
659
+ if begun is not None:
660
+ stack.append(begun)
661
+ elif _is_end(s, stack[-1]):
662
+ stack.pop()
663
+ if not stack:
664
+ return j + 1, OpaqueBlock(
665
+ block_type=target,
666
+ begin=begin_stmt,
667
+ end=s,
668
+ inner_lines=inner,
669
+ )
670
+ inner.append(lines[j])
671
+ j += 1
672
+
673
+ warnings.append(
674
+ ParseWarning(
675
+ begin_stmt.line_no,
676
+ f"'begin {target}' not closed before end of file",
677
+ )
678
+ )
679
+ return n_lines, OpaqueBlock(
680
+ block_type=target, begin=begin_stmt, end=None, inner_lines=inner
681
+ )
682
+
683
+
684
+ def _is_end_bare(stmt: Statement) -> bool:
685
+ """True if ``stmt`` is a bare ``end`` with no explicit target word."""
686
+ words = [t for t in stmt.tokens if t.type is TokenType.WORD]
687
+ return len(words) == 1 and words[0].value.lower() == "end"
688
+
689
+
690
+ # --------------------------------------------------------------------------- #
691
+ # Emission helpers
692
+ # --------------------------------------------------------------------------- #
693
+
694
+
695
+ def _iter_statements(node: Node) -> List[Statement]:
696
+ """Yield the statements reachable from a node (see ``statements``)."""
697
+ if isinstance(node, Statement):
698
+ return [node]
699
+ if isinstance(node, BlankOrComment):
700
+ return [node.statement]
701
+ if isinstance(node, GraphBlock):
702
+ out = [node.begin]
703
+ for child in node.body:
704
+ out.extend(_iter_statements(child))
705
+ if node.end is not None:
706
+ out.append(node.end)
707
+ return out
708
+ if isinstance(node, OpaqueBlock):
709
+ out = [node.begin]
710
+ if node.end is not None:
711
+ out.append(node.end)
712
+ return out
713
+ return []
714
+
715
+
716
+ def _emit_lines(lines: List[SourceLine]) -> str:
717
+ """Concatenate the raw bytes of every source line."""
718
+ return "".join(src.raw for src in lines)
719
+
720
+
721
+ def _render_line_text(src: SourceLine, doc: GleDocument) -> str:
722
+ """Re-render a physical line's text from its (possibly replaced) statements.
723
+
724
+ Preserves the original leading whitespace and the inter-statement text
725
+ (``;`` plus any surrounding spaces) for statements left untouched, and
726
+ substitutes ``replacement`` text for replaced ones.
727
+ """
728
+ stmts = [s for s in doc.statements() if s.source_line is src]
729
+ stmts.sort(key=lambda s: s.sub_index)
730
+ if not stmts:
731
+ return src.text
732
+ if len(stmts) == 1:
733
+ s = stmts[0]
734
+ if s.replacement is not None:
735
+ # Preserve leading indentation of the original segment.
736
+ leading = src.text[: len(src.text) - len(src.text.lstrip())]
737
+ return leading + s.replacement.lstrip()
738
+ return src.text
739
+
740
+ # Multi-statement: rebuild using original segment offsets so separators
741
+ # survive. We recompute segment boundaries from the original text.
742
+ segments = split_statements(src.text)
743
+ pieces: List[str] = []
744
+ for i, (seg_text, _offset) in enumerate(segments):
745
+ stmt = next((s for s in stmts if s.sub_index == i), None)
746
+ if stmt is not None and stmt.replacement is not None:
747
+ leading = seg_text[: len(seg_text) - len(seg_text.lstrip())]
748
+ pieces.append(leading + stmt.replacement.lstrip())
749
+ else:
750
+ pieces.append(seg_text)
751
+ return ";".join(pieces)
752
+
753
+
754
+ def emit(document: GleDocument) -> str:
755
+ """Serialise ``document`` back to source text (module-level convenience)."""
756
+ return document.emit()