nkparser 0.1.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.
- nkparser/__init__.py +68 -0
- nkparser/__main__.py +8 -0
- nkparser/builder.py +231 -0
- nkparser/cli.py +419 -0
- nkparser/errors.py +37 -0
- nkparser/lexer.py +299 -0
- nkparser/models.py +526 -0
- nkparser/parser.py +462 -0
- nkparser/py.typed +0 -0
- nkparser/query.py +135 -0
- nkparser/serializer.py +72 -0
- nkparser/tokens.py +33 -0
- nkparser/validator.py +140 -0
- nkparser/visualization.py +245 -0
- nkparser-0.1.0.dist-info/METADATA +104 -0
- nkparser-0.1.0.dist-info/RECORD +18 -0
- nkparser-0.1.0.dist-info/WHEEL +4 -0
- nkparser-0.1.0.dist-info/entry_points.txt +2 -0
nkparser/parser.py
ADDED
|
@@ -0,0 +1,462 @@
|
|
|
1
|
+
"""Recursive-descent parser for Nuke .nk token streams.
|
|
2
|
+
|
|
3
|
+
Converts a flat list of Tokens produced by the Lexer into an intermediate
|
|
4
|
+
representation (raw AST) consisting of RawNode, RawSetOp, RawPushOp, and
|
|
5
|
+
RawAddLayer dataclasses. The builder module converts this raw AST into the
|
|
6
|
+
final Script/Node object model.
|
|
7
|
+
|
|
8
|
+
Design notes:
|
|
9
|
+
- The grammar is LL(2): any ambiguity is resolved by at most one look-ahead token.
|
|
10
|
+
- Error recovery uses per-node checkpoints: when parsing a node body fails, the
|
|
11
|
+
parser skips forward to the next top-level closing '}' and resumes, emitting
|
|
12
|
+
a ParseError diagnostic for the broken node.
|
|
13
|
+
- Groups (Group { ... end_group }) are handled recursively via _parse_group().
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import re
|
|
19
|
+
from dataclasses import field, dataclass
|
|
20
|
+
|
|
21
|
+
from .errors import ParseError
|
|
22
|
+
from .tokens import Token, TokenKind
|
|
23
|
+
|
|
24
|
+
# ---------------------------------------------------------------------------
|
|
25
|
+
# Raw AST node types (internal, not part of the public API)
|
|
26
|
+
# ---------------------------------------------------------------------------
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
@dataclass
|
|
30
|
+
class RawKnob:
|
|
31
|
+
name: str
|
|
32
|
+
raw_value: str # verbatim value text as it appears after the knob name
|
|
33
|
+
source_line: int
|
|
34
|
+
raw_line: str # the full original line(s) including leading space
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
@dataclass
|
|
38
|
+
class RawNode:
|
|
39
|
+
node_class: str
|
|
40
|
+
knobs: list[RawKnob] = field(default_factory=list)
|
|
41
|
+
children: list["RawStatement"] = field(default_factory=list) # for groups
|
|
42
|
+
is_group: bool = False
|
|
43
|
+
is_unclosed: bool = False # set if group end_group was missing
|
|
44
|
+
source_line: int = 0
|
|
45
|
+
source_end_line: int = 0
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
@dataclass
|
|
49
|
+
class RawSetOp:
|
|
50
|
+
name: str # variable name without $
|
|
51
|
+
stack_index: int
|
|
52
|
+
source_line: int
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
@dataclass
|
|
56
|
+
class RawPushOp:
|
|
57
|
+
ref: str # variable name without $
|
|
58
|
+
source_line: int
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
@dataclass
|
|
62
|
+
class RawAddLayer:
|
|
63
|
+
declaration: str # raw content inside {}
|
|
64
|
+
source_line: int
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
RawStatement = RawNode | RawSetOp | RawPushOp | RawAddLayer
|
|
68
|
+
|
|
69
|
+
# Pattern to extract stack index from "[stack N]"
|
|
70
|
+
_STACK_RE = re.compile(r"\[stack\s+(\d+)\]")
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
# ---------------------------------------------------------------------------
|
|
74
|
+
# Parser
|
|
75
|
+
# ---------------------------------------------------------------------------
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
class Parser:
|
|
79
|
+
"""Parse a token list into (header_dict, list[RawStatement]).
|
|
80
|
+
|
|
81
|
+
Usage::
|
|
82
|
+
|
|
83
|
+
tokens = Lexer(source).tokenize()
|
|
84
|
+
parser = Parser(tokens)
|
|
85
|
+
header, statements = parser.parse()
|
|
86
|
+
"""
|
|
87
|
+
|
|
88
|
+
def __init__(self, tokens: list[Token]) -> None:
|
|
89
|
+
# Filter out COMMENT tokens; keep NEWLINEs for line-number tracking
|
|
90
|
+
self._tokens = [t for t in tokens if t.kind != TokenKind.COMMENT]
|
|
91
|
+
self._pos = 0
|
|
92
|
+
self.errors: list[ParseError] = []
|
|
93
|
+
|
|
94
|
+
# ------------------------------------------------------------------
|
|
95
|
+
# Public entry point
|
|
96
|
+
# ------------------------------------------------------------------
|
|
97
|
+
|
|
98
|
+
def parse(self) -> tuple[dict[str, str], list[RawStatement]]:
|
|
99
|
+
"""Return (header, statements) for the script."""
|
|
100
|
+
header = self._parse_header()
|
|
101
|
+
statements: list[RawStatement] = []
|
|
102
|
+
while not self._at_eof():
|
|
103
|
+
self._skip_newlines()
|
|
104
|
+
if self._at_eof():
|
|
105
|
+
break
|
|
106
|
+
stmt = self._parse_statement()
|
|
107
|
+
if stmt is not None:
|
|
108
|
+
statements.append(stmt)
|
|
109
|
+
return header, statements
|
|
110
|
+
|
|
111
|
+
# ------------------------------------------------------------------
|
|
112
|
+
# Header
|
|
113
|
+
# ------------------------------------------------------------------
|
|
114
|
+
|
|
115
|
+
def _parse_header(self) -> dict[str, str]:
|
|
116
|
+
header: dict[str, str] = {}
|
|
117
|
+
self._skip_newlines()
|
|
118
|
+
|
|
119
|
+
# Shebang
|
|
120
|
+
if self._peek().kind == TokenKind.SHEBANG:
|
|
121
|
+
header["shebang"] = self._consume().value
|
|
122
|
+
self._skip_newlines()
|
|
123
|
+
|
|
124
|
+
# version 15.0 v2
|
|
125
|
+
if self._peek().kind == TokenKind.WORD and self._peek().value == "version":
|
|
126
|
+
self._consume() # "version"
|
|
127
|
+
parts: list[str] = []
|
|
128
|
+
while not self._at_newline_or_eof():
|
|
129
|
+
parts.append(self._consume().value)
|
|
130
|
+
header["version"] = " ".join(parts)
|
|
131
|
+
self._skip_newlines()
|
|
132
|
+
|
|
133
|
+
# define_window_layout_xml { ... }
|
|
134
|
+
if (
|
|
135
|
+
self._peek().kind == TokenKind.WORD
|
|
136
|
+
and self._peek().value == "define_window_layout_xml"
|
|
137
|
+
):
|
|
138
|
+
self._consume() # keyword
|
|
139
|
+
self._skip_newlines()
|
|
140
|
+
if self._peek().kind == TokenKind.BRACE_BLOCK:
|
|
141
|
+
tok = self._consume()
|
|
142
|
+
# Strip surrounding { }
|
|
143
|
+
inner = tok.value[1:-1]
|
|
144
|
+
header["window_layout_xml"] = inner
|
|
145
|
+
self._skip_newlines()
|
|
146
|
+
|
|
147
|
+
return header
|
|
148
|
+
|
|
149
|
+
# ------------------------------------------------------------------
|
|
150
|
+
# Statement dispatcher
|
|
151
|
+
# ------------------------------------------------------------------
|
|
152
|
+
|
|
153
|
+
def _parse_statement(self) -> RawStatement | None:
|
|
154
|
+
self._skip_newlines()
|
|
155
|
+
if self._at_eof():
|
|
156
|
+
return None
|
|
157
|
+
|
|
158
|
+
tok = self._peek()
|
|
159
|
+
if tok.kind != TokenKind.WORD:
|
|
160
|
+
# Unexpected token; skip it
|
|
161
|
+
self.errors.append(
|
|
162
|
+
ParseError(
|
|
163
|
+
f"expected node class or keyword, got {tok.kind.name} {tok.value!r}",
|
|
164
|
+
tok.line,
|
|
165
|
+
tok.col,
|
|
166
|
+
)
|
|
167
|
+
)
|
|
168
|
+
self._consume()
|
|
169
|
+
return None
|
|
170
|
+
|
|
171
|
+
word = tok.value
|
|
172
|
+
|
|
173
|
+
if word == "set":
|
|
174
|
+
return self._parse_set()
|
|
175
|
+
if word == "push":
|
|
176
|
+
return self._parse_push()
|
|
177
|
+
if word == "add_layer":
|
|
178
|
+
return self._parse_add_layer()
|
|
179
|
+
|
|
180
|
+
# Anything else should be a node class followed by {
|
|
181
|
+
return self._parse_node()
|
|
182
|
+
|
|
183
|
+
# ------------------------------------------------------------------
|
|
184
|
+
# Stack operations
|
|
185
|
+
# ------------------------------------------------------------------
|
|
186
|
+
|
|
187
|
+
def _parse_set(self) -> RawSetOp | None:
|
|
188
|
+
tok = self._consume() # "set"
|
|
189
|
+
line = tok.line
|
|
190
|
+
if self._peek().kind != TokenKind.WORD:
|
|
191
|
+
self.errors.append(ParseError(
|
|
192
|
+
"expected variable name after 'set'", line, tok.col))
|
|
193
|
+
return None
|
|
194
|
+
name = self._consume().value # variable name
|
|
195
|
+
if self._peek().kind != TokenKind.BRACKET_EXPR:
|
|
196
|
+
self.errors.append(ParseError(
|
|
197
|
+
"expected [stack N] after variable name", line, tok.col))
|
|
198
|
+
return None
|
|
199
|
+
bracket = self._consume()
|
|
200
|
+
m = _STACK_RE.match(bracket.value)
|
|
201
|
+
if not m:
|
|
202
|
+
self.errors.append(
|
|
203
|
+
ParseError(
|
|
204
|
+
f"malformed stack expression: {bracket.value!r}", line, bracket.col)
|
|
205
|
+
)
|
|
206
|
+
return None
|
|
207
|
+
return RawSetOp(name=name, stack_index=int(m.group(1)), source_line=line)
|
|
208
|
+
|
|
209
|
+
def _parse_push(self) -> RawPushOp | None:
|
|
210
|
+
tok = self._consume() # "push"
|
|
211
|
+
line = tok.line
|
|
212
|
+
if self._peek().kind != TokenKind.WORD:
|
|
213
|
+
self.errors.append(ParseError(
|
|
214
|
+
"expected $variable after 'push'", line, tok.col))
|
|
215
|
+
return None
|
|
216
|
+
ref_tok = self._consume()
|
|
217
|
+
ref = ref_tok.value.lstrip("$")
|
|
218
|
+
return RawPushOp(ref=ref, source_line=line)
|
|
219
|
+
|
|
220
|
+
def _parse_add_layer(self) -> RawAddLayer | None:
|
|
221
|
+
tok = self._consume() # "add_layer"
|
|
222
|
+
line = tok.line
|
|
223
|
+
if self._peek().kind != TokenKind.BRACE_BLOCK:
|
|
224
|
+
self.errors.append(ParseError(
|
|
225
|
+
"expected {...} after 'add_layer'", line, tok.col))
|
|
226
|
+
return None
|
|
227
|
+
block = self._consume()
|
|
228
|
+
# Strip { and } and return inner content
|
|
229
|
+
return RawAddLayer(declaration=block.value[1:-1].strip(), source_line=line)
|
|
230
|
+
|
|
231
|
+
# ------------------------------------------------------------------
|
|
232
|
+
# Node parsing
|
|
233
|
+
# ------------------------------------------------------------------
|
|
234
|
+
|
|
235
|
+
def _parse_node(self) -> RawNode | None:
|
|
236
|
+
class_tok = self._consume()
|
|
237
|
+
node_class = class_tok.value
|
|
238
|
+
line = class_tok.line
|
|
239
|
+
is_group = node_class == "Group"
|
|
240
|
+
|
|
241
|
+
self._skip_newlines()
|
|
242
|
+
if self._peek().kind != TokenKind.BRACE_BLOCK and not (
|
|
243
|
+
self._peek().kind == TokenKind.WORD and self._peek().value == "{"
|
|
244
|
+
):
|
|
245
|
+
# The brace block may be a BRACE_BLOCK token (most common) or the
|
|
246
|
+
# lexer may have split it into separate WORD/NEWLINE tokens if
|
|
247
|
+
# the node body spans lines — but our lexer always emits BRACE_BLOCK
|
|
248
|
+
# for { tokens. However in the outer grammar the lexer produces
|
|
249
|
+
# BRACE_BLOCKs only when { is encountered; node bodies ARE brace
|
|
250
|
+
# blocks, so this path is always BRACE_BLOCK.
|
|
251
|
+
if self._peek().kind != TokenKind.BRACE_BLOCK:
|
|
252
|
+
self.errors.append(
|
|
253
|
+
ParseError(
|
|
254
|
+
f"expected '{{' after node class {node_class!r}",
|
|
255
|
+
line,
|
|
256
|
+
class_tok.col,
|
|
257
|
+
)
|
|
258
|
+
)
|
|
259
|
+
return None
|
|
260
|
+
|
|
261
|
+
body_tok = self._consume() # BRACE_BLOCK token for the node body
|
|
262
|
+
end_line = body_tok.end_line
|
|
263
|
+
|
|
264
|
+
# Parse the brace block's inner text for knob lines.
|
|
265
|
+
# Groups additionally contain child statements between their knobs and end_group.
|
|
266
|
+
if is_group:
|
|
267
|
+
knobs, children, is_unclosed = self._parse_group_body(
|
|
268
|
+
body_tok.value[1:-1], line)
|
|
269
|
+
return RawNode(
|
|
270
|
+
node_class=node_class,
|
|
271
|
+
knobs=knobs,
|
|
272
|
+
children=children,
|
|
273
|
+
is_group=True,
|
|
274
|
+
is_unclosed=is_unclosed,
|
|
275
|
+
source_line=line,
|
|
276
|
+
source_end_line=end_line,
|
|
277
|
+
)
|
|
278
|
+
else:
|
|
279
|
+
knobs = self._parse_node_body(body_tok.value[1:-1], line)
|
|
280
|
+
return RawNode(
|
|
281
|
+
node_class=node_class,
|
|
282
|
+
knobs=knobs,
|
|
283
|
+
source_line=line,
|
|
284
|
+
source_end_line=end_line,
|
|
285
|
+
)
|
|
286
|
+
|
|
287
|
+
# ------------------------------------------------------------------
|
|
288
|
+
# Node body parsing (knob lines inside a brace block)
|
|
289
|
+
# ------------------------------------------------------------------
|
|
290
|
+
|
|
291
|
+
def _parse_node_body(self, body_text: str, base_line: int) -> list[RawKnob]:
|
|
292
|
+
"""Parse the interior text of a node {} block into RawKnob list."""
|
|
293
|
+
knobs: list[RawKnob] = []
|
|
294
|
+
lines = body_text.split("\n")
|
|
295
|
+
i = 0
|
|
296
|
+
current_line = base_line + \
|
|
297
|
+
1 # body starts one line after the opening {
|
|
298
|
+
|
|
299
|
+
while i < len(lines):
|
|
300
|
+
raw_line = lines[i]
|
|
301
|
+
stripped = raw_line.strip()
|
|
302
|
+
i += 1
|
|
303
|
+
current_line += 1
|
|
304
|
+
|
|
305
|
+
if not stripped:
|
|
306
|
+
continue
|
|
307
|
+
|
|
308
|
+
# A knob line is: <name> <value>
|
|
309
|
+
# Value may be a brace block that spans multiple lines — but since
|
|
310
|
+
# the lexer already collected the full brace block into a single
|
|
311
|
+
# BRACE_BLOCK token, within the node body text the braces are
|
|
312
|
+
# already balanced inline.
|
|
313
|
+
parts = stripped.split(None, 1)
|
|
314
|
+
if len(parts) == 0:
|
|
315
|
+
continue
|
|
316
|
+
knob_name = parts[0]
|
|
317
|
+
raw_value = parts[1] if len(parts) > 1 else ""
|
|
318
|
+
knobs.append(
|
|
319
|
+
RawKnob(
|
|
320
|
+
name=knob_name,
|
|
321
|
+
raw_value=raw_value,
|
|
322
|
+
source_line=current_line - 1,
|
|
323
|
+
raw_line=raw_line,
|
|
324
|
+
)
|
|
325
|
+
)
|
|
326
|
+
|
|
327
|
+
return knobs
|
|
328
|
+
|
|
329
|
+
def _parse_group_body(
|
|
330
|
+
self, body_text: str, base_line: int
|
|
331
|
+
) -> tuple[list[RawKnob], list[RawStatement], bool]:
|
|
332
|
+
"""Parse the interior of a Group { ... end_group } block.
|
|
333
|
+
|
|
334
|
+
Returns (knobs, children, is_unclosed).
|
|
335
|
+
"""
|
|
336
|
+
# Re-tokenise the inner body so we can use the same parser logic.
|
|
337
|
+
from .lexer import \
|
|
338
|
+
Lexer # local import to avoid circular at module load
|
|
339
|
+
|
|
340
|
+
inner_lexer = Lexer(body_text)
|
|
341
|
+
inner_tokens = inner_lexer.tokenize()
|
|
342
|
+
# Adjust line numbers by base_line offset
|
|
343
|
+
adjusted: list[Token] = []
|
|
344
|
+
for t in inner_tokens:
|
|
345
|
+
adjusted.append(
|
|
346
|
+
Token(
|
|
347
|
+
kind=t.kind,
|
|
348
|
+
value=t.value,
|
|
349
|
+
line=t.line + base_line,
|
|
350
|
+
col=t.col,
|
|
351
|
+
end_line=t.end_line + base_line,
|
|
352
|
+
end_col=t.end_col,
|
|
353
|
+
)
|
|
354
|
+
)
|
|
355
|
+
|
|
356
|
+
inner_parser = Parser(adjusted)
|
|
357
|
+
knobs: list[RawKnob] = []
|
|
358
|
+
children: list[RawStatement] = []
|
|
359
|
+
is_unclosed = True
|
|
360
|
+
|
|
361
|
+
inner_parser._skip_newlines()
|
|
362
|
+
|
|
363
|
+
# First, parse leading knob lines (before any child nodes / end_group)
|
|
364
|
+
# Knobs appear before child nodes in Group bodies.
|
|
365
|
+
while not inner_parser._at_eof():
|
|
366
|
+
inner_parser._skip_newlines()
|
|
367
|
+
if inner_parser._at_eof():
|
|
368
|
+
break
|
|
369
|
+
tok = inner_parser._peek()
|
|
370
|
+
if tok.kind != TokenKind.WORD:
|
|
371
|
+
break
|
|
372
|
+
if tok.value == "end_group":
|
|
373
|
+
inner_parser._consume()
|
|
374
|
+
is_unclosed = False
|
|
375
|
+
break
|
|
376
|
+
|
|
377
|
+
# Peek ahead: if next meaningful token after word is BRACE_BLOCK,
|
|
378
|
+
# this is a child node; otherwise it's a knob line.
|
|
379
|
+
next_idx = inner_parser._pos + 1
|
|
380
|
+
while next_idx < len(inner_parser._tokens) and inner_parser._tokens[next_idx].kind in (
|
|
381
|
+
TokenKind.NEWLINE,
|
|
382
|
+
):
|
|
383
|
+
next_idx += 1
|
|
384
|
+
next_tok = (
|
|
385
|
+
inner_parser._tokens[next_idx]
|
|
386
|
+
if next_idx < len(inner_parser._tokens)
|
|
387
|
+
else inner_parser._tokens[-1]
|
|
388
|
+
)
|
|
389
|
+
|
|
390
|
+
if next_tok.kind == TokenKind.BRACE_BLOCK and tok.value not in (
|
|
391
|
+
"set",
|
|
392
|
+
"push",
|
|
393
|
+
"add_layer",
|
|
394
|
+
):
|
|
395
|
+
# Child node or nested group
|
|
396
|
+
stmt = inner_parser._parse_statement()
|
|
397
|
+
if stmt is not None:
|
|
398
|
+
children.append(stmt)
|
|
399
|
+
elif tok.value in ("set", "push", "add_layer"):
|
|
400
|
+
stmt = inner_parser._parse_statement()
|
|
401
|
+
if stmt is not None:
|
|
402
|
+
children.append(stmt)
|
|
403
|
+
else:
|
|
404
|
+
# Knob line — consume the rest of the logical line
|
|
405
|
+
knob_tok = inner_parser._consume()
|
|
406
|
+
parts = knob_tok.value.split(
|
|
407
|
+
None, 1) # shouldn't really happen
|
|
408
|
+
knob_name = parts[0]
|
|
409
|
+
raw_value = ""
|
|
410
|
+
|
|
411
|
+
# Value tokens follow on same logical line
|
|
412
|
+
val_parts: list[str] = []
|
|
413
|
+
while not inner_parser._at_newline_or_eof():
|
|
414
|
+
val_parts.append(inner_parser._consume().value)
|
|
415
|
+
raw_value = " ".join(val_parts)
|
|
416
|
+
|
|
417
|
+
knobs.append(
|
|
418
|
+
RawKnob(
|
|
419
|
+
name=knob_name,
|
|
420
|
+
raw_value=raw_value,
|
|
421
|
+
source_line=knob_tok.line,
|
|
422
|
+
raw_line=f" {knob_name} {raw_value}",
|
|
423
|
+
)
|
|
424
|
+
)
|
|
425
|
+
|
|
426
|
+
self.errors.extend(inner_parser.errors)
|
|
427
|
+
return knobs, children, is_unclosed
|
|
428
|
+
|
|
429
|
+
# ------------------------------------------------------------------
|
|
430
|
+
# Token stream helpers
|
|
431
|
+
# ------------------------------------------------------------------
|
|
432
|
+
|
|
433
|
+
def _peek(self, offset: int = 0) -> Token:
|
|
434
|
+
idx = self._pos + offset
|
|
435
|
+
if idx < len(self._tokens):
|
|
436
|
+
return self._tokens[idx]
|
|
437
|
+
# Return a sentinel EOF token
|
|
438
|
+
last = self._tokens[-1] if self._tokens else Token(
|
|
439
|
+
TokenKind.EOF, "", 1, 1, 1, 1)
|
|
440
|
+
return Token(TokenKind.EOF, "", last.line, last.col, last.line, last.col)
|
|
441
|
+
|
|
442
|
+
def _consume(self, expected_kind: TokenKind | None = None) -> Token:
|
|
443
|
+
tok = self._peek()
|
|
444
|
+
if expected_kind is not None and tok.kind != expected_kind:
|
|
445
|
+
raise ParseError(
|
|
446
|
+
f"expected {expected_kind.name}, got {tok.kind.name} {tok.value!r}",
|
|
447
|
+
tok.line,
|
|
448
|
+
tok.col,
|
|
449
|
+
)
|
|
450
|
+
self._pos += 1
|
|
451
|
+
return tok
|
|
452
|
+
|
|
453
|
+
def _at_eof(self) -> bool:
|
|
454
|
+
return self._peek().kind == TokenKind.EOF
|
|
455
|
+
|
|
456
|
+
def _at_newline_or_eof(self) -> bool:
|
|
457
|
+
k = self._peek().kind
|
|
458
|
+
return k in (TokenKind.NEWLINE, TokenKind.EOF)
|
|
459
|
+
|
|
460
|
+
def _skip_newlines(self) -> None:
|
|
461
|
+
while self._peek().kind == TokenKind.NEWLINE:
|
|
462
|
+
self._pos += 1
|
nkparser/py.typed
ADDED
|
File without changes
|
nkparser/query.py
ADDED
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
"""Fluent traversal and query API for Script node graphs.
|
|
2
|
+
|
|
3
|
+
Usage::
|
|
4
|
+
|
|
5
|
+
script = Script.from_file("comp.nk")
|
|
6
|
+
|
|
7
|
+
# Find all Read nodes
|
|
8
|
+
reads = script.query().of_class("Read").all()
|
|
9
|
+
|
|
10
|
+
# Find nodes whose name starts with "Merge"
|
|
11
|
+
merges = script.query().named("^Merge").all()
|
|
12
|
+
|
|
13
|
+
# Find all upstream nodes from a given node
|
|
14
|
+
node = script.find("Grade1")
|
|
15
|
+
upstream = script.query().upstream(node, script).all()
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import re
|
|
21
|
+
from typing import Callable, Iterator, Optional
|
|
22
|
+
from collections import deque
|
|
23
|
+
|
|
24
|
+
from .models import Node, Script
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class NodeQuery:
|
|
28
|
+
"""Immutable, chainable query builder over a sequence of Nodes."""
|
|
29
|
+
|
|
30
|
+
def __init__(self, nodes: Iterator[Node] | list[Node]) -> None:
|
|
31
|
+
self._nodes: list[Node] = list(nodes)
|
|
32
|
+
|
|
33
|
+
# ------------------------------------------------------------------
|
|
34
|
+
# Filters
|
|
35
|
+
# ------------------------------------------------------------------
|
|
36
|
+
|
|
37
|
+
def of_class(self, *classes: str) -> "NodeQuery":
|
|
38
|
+
"""Keep only nodes whose node_class is in *classes*."""
|
|
39
|
+
class_set = set(classes)
|
|
40
|
+
return NodeQuery(n for n in self._nodes if n.node_class in class_set)
|
|
41
|
+
|
|
42
|
+
def named(self, pattern: str) -> "NodeQuery":
|
|
43
|
+
"""Keep nodes whose name knob matches the regex *pattern*."""
|
|
44
|
+
rx = re.compile(pattern)
|
|
45
|
+
return NodeQuery(n for n in self._nodes if rx.search(n.name))
|
|
46
|
+
|
|
47
|
+
def with_knob(self, name: str, value_pattern: Optional[str] = None) -> "NodeQuery":
|
|
48
|
+
"""Keep nodes that have a knob with the given name.
|
|
49
|
+
|
|
50
|
+
If *value_pattern* is given, also filter by that regex against the
|
|
51
|
+
knob's raw value.
|
|
52
|
+
"""
|
|
53
|
+
rx = re.compile(value_pattern) if value_pattern else None
|
|
54
|
+
results: list[Node] = []
|
|
55
|
+
for node in self._nodes:
|
|
56
|
+
k = node.knob(name)
|
|
57
|
+
if k is None:
|
|
58
|
+
continue
|
|
59
|
+
if rx is not None and not rx.search(k.value.raw):
|
|
60
|
+
continue
|
|
61
|
+
results.append(node)
|
|
62
|
+
return NodeQuery(results)
|
|
63
|
+
|
|
64
|
+
def where(self, predicate: Callable[[Node], bool]) -> "NodeQuery":
|
|
65
|
+
"""Keep nodes that satisfy *predicate*."""
|
|
66
|
+
return NodeQuery(n for n in self._nodes if predicate(n))
|
|
67
|
+
|
|
68
|
+
# ------------------------------------------------------------------
|
|
69
|
+
# Graph traversal
|
|
70
|
+
# ------------------------------------------------------------------
|
|
71
|
+
|
|
72
|
+
def inputs_of(self, node: Node) -> "NodeQuery":
|
|
73
|
+
"""Return direct input nodes of *node* (excludes None/missing inputs)."""
|
|
74
|
+
return NodeQuery(n for n in node.inputs if n is not None)
|
|
75
|
+
|
|
76
|
+
def outputs_of(self, node: Node, script: Script) -> "NodeQuery":
|
|
77
|
+
"""Return all nodes in *script* that have *node* as a direct input."""
|
|
78
|
+
return NodeQuery(n for n in script.all_nodes() if node in n.inputs)
|
|
79
|
+
|
|
80
|
+
def upstream(self, node: Node, script: Script) -> "NodeQuery": # noqa: ARG002
|
|
81
|
+
"""BFS all nodes upstream from (and including) *node*."""
|
|
82
|
+
visited: set[int] = set()
|
|
83
|
+
queue: deque[Node] = deque([node])
|
|
84
|
+
result: list[Node] = []
|
|
85
|
+
while queue:
|
|
86
|
+
current = queue.popleft()
|
|
87
|
+
if id(current) in visited:
|
|
88
|
+
continue
|
|
89
|
+
visited.add(id(current))
|
|
90
|
+
result.append(current)
|
|
91
|
+
for inp in current.inputs:
|
|
92
|
+
if inp is not None and id(inp) not in visited:
|
|
93
|
+
queue.append(inp)
|
|
94
|
+
return NodeQuery(result)
|
|
95
|
+
|
|
96
|
+
def downstream(self, node: Node, script: Script) -> "NodeQuery":
|
|
97
|
+
"""BFS all nodes downstream from (and including) *node*."""
|
|
98
|
+
visited: set[int] = set()
|
|
99
|
+
queue: deque[Node] = deque([node])
|
|
100
|
+
result: list[Node] = []
|
|
101
|
+
while queue:
|
|
102
|
+
current = queue.popleft()
|
|
103
|
+
if id(current) in visited:
|
|
104
|
+
continue
|
|
105
|
+
visited.add(id(current))
|
|
106
|
+
result.append(current)
|
|
107
|
+
for n in script.all_nodes():
|
|
108
|
+
if current in n.inputs and id(n) not in visited:
|
|
109
|
+
queue.append(n)
|
|
110
|
+
return NodeQuery(result)
|
|
111
|
+
|
|
112
|
+
# ------------------------------------------------------------------
|
|
113
|
+
# Terminal operations
|
|
114
|
+
# ------------------------------------------------------------------
|
|
115
|
+
|
|
116
|
+
def first(self) -> Optional[Node]:
|
|
117
|
+
return self._nodes[0] if self._nodes else None
|
|
118
|
+
|
|
119
|
+
def last(self) -> Optional[Node]:
|
|
120
|
+
return self._nodes[-1] if self._nodes else None
|
|
121
|
+
|
|
122
|
+
def all(self) -> list[Node]:
|
|
123
|
+
return list(self._nodes)
|
|
124
|
+
|
|
125
|
+
def count(self) -> int:
|
|
126
|
+
return len(self._nodes)
|
|
127
|
+
|
|
128
|
+
def __iter__(self) -> Iterator[Node]:
|
|
129
|
+
return iter(self._nodes)
|
|
130
|
+
|
|
131
|
+
def __len__(self) -> int:
|
|
132
|
+
return len(self._nodes)
|
|
133
|
+
|
|
134
|
+
def __repr__(self) -> str:
|
|
135
|
+
return f"NodeQuery({len(self._nodes)} nodes)"
|
nkparser/serializer.py
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
"""Round-trip serializer: converts a Script back to valid .nk text.
|
|
2
|
+
|
|
3
|
+
Fidelity strategy
|
|
4
|
+
-----------------
|
|
5
|
+
Each Knob stores ``raw_line`` — the verbatim line(s) from the original source.
|
|
6
|
+
The serializer replays ``raw_line`` for every unmodified knob, achieving
|
|
7
|
+
byte-level fidelity for untouched knobs.
|
|
8
|
+
|
|
9
|
+
For knobs that have been mutated (``Knob._dirty == True``), the serializer
|
|
10
|
+
re-renders from the model using ``" {name} {value.raw}"``.
|
|
11
|
+
|
|
12
|
+
The ``Script._ordered_statements`` list records every top-level statement
|
|
13
|
+
(Node, RawSetOp, RawPushOp, RawAddLayer) in original document order,
|
|
14
|
+
which is essential for preserving the exact interleaving of set/push
|
|
15
|
+
operations between nodes.
|
|
16
|
+
|
|
17
|
+
Known limitations
|
|
18
|
+
-----------------
|
|
19
|
+
- The exact whitespace inside brace blocks (indentation of multi-line knob
|
|
20
|
+
values) is preserved verbatim via ``raw_line``.
|
|
21
|
+
- The ``define_window_layout_xml`` block's internal XML whitespace is
|
|
22
|
+
preserved if the original source text was captured in
|
|
23
|
+
``Script.window_layout_xml``.
|
|
24
|
+
- Trailing newlines: the serializer always ends with a single trailing newline.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
from __future__ import annotations
|
|
28
|
+
|
|
29
|
+
from .models import Node, Script, GroupNode
|
|
30
|
+
from .parser import RawSetOp, RawPushOp, RawAddLayer
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class Serializer:
|
|
34
|
+
def __init__(self, script: Script) -> None:
|
|
35
|
+
self._script = script
|
|
36
|
+
|
|
37
|
+
def serialize(self) -> str:
|
|
38
|
+
parts: list[str] = []
|
|
39
|
+
|
|
40
|
+
# Header
|
|
41
|
+
if self._script.shebang:
|
|
42
|
+
parts.append(self._script.shebang)
|
|
43
|
+
if self._script.nuke_version:
|
|
44
|
+
parts.append(f"version {self._script.nuke_version}")
|
|
45
|
+
if self._script.window_layout_xml is not None:
|
|
46
|
+
parts.append(
|
|
47
|
+
f"define_window_layout_xml {{{self._script.window_layout_xml}}}")
|
|
48
|
+
|
|
49
|
+
# Body — replay ordered statements to preserve set/push interleaving
|
|
50
|
+
for stmt in self._script._ordered_statements:
|
|
51
|
+
if isinstance(stmt, Node):
|
|
52
|
+
parts.append(self._serialize_node(stmt))
|
|
53
|
+
elif isinstance(stmt, RawSetOp):
|
|
54
|
+
parts.append(f"set {stmt.name} [stack {stmt.stack_index}]")
|
|
55
|
+
elif isinstance(stmt, RawPushOp):
|
|
56
|
+
parts.append(f"push ${stmt.ref}")
|
|
57
|
+
elif isinstance(stmt, RawAddLayer):
|
|
58
|
+
parts.append(f"add_layer {{{stmt.declaration}}}")
|
|
59
|
+
|
|
60
|
+
return "\n".join(parts) + "\n"
|
|
61
|
+
|
|
62
|
+
@staticmethod
|
|
63
|
+
def _serialize_node(node: Node) -> str:
|
|
64
|
+
lines: list[str] = [f"{node.node_class} {{"]
|
|
65
|
+
for knob in node.knobs:
|
|
66
|
+
lines.append(knob.raw_line)
|
|
67
|
+
if isinstance(node, GroupNode):
|
|
68
|
+
for child in node.children:
|
|
69
|
+
lines.append(Serializer._serialize_node(child))
|
|
70
|
+
lines.append("end_group")
|
|
71
|
+
lines.append("}")
|
|
72
|
+
return "\n".join(lines)
|
nkparser/tokens.py
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"""Token types and Token dataclass for the nkparser lexer."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from enum import Enum, auto
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class TokenKind(Enum):
|
|
10
|
+
WORD = auto() # bare identifier, number, or unquoted value fragment
|
|
11
|
+
STRING = auto() # "..." — quotes included in .value
|
|
12
|
+
BRACE_BLOCK = auto() # {...} balanced block — braces included in .value
|
|
13
|
+
BRACKET_EXPR = auto() # [...] — brackets included in .value
|
|
14
|
+
SHEBANG = auto() # #! ... rest of line (line 1 only)
|
|
15
|
+
COMMENT = auto() # # ... rest of line
|
|
16
|
+
NEWLINE = auto()
|
|
17
|
+
EOF = auto()
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@dataclass(slots=True)
|
|
21
|
+
class Token:
|
|
22
|
+
kind: TokenKind
|
|
23
|
+
value: str # raw text as it appears in source (including delimiters)
|
|
24
|
+
line: int # 1-based start line
|
|
25
|
+
col: int # 1-based start column
|
|
26
|
+
end_line: int # 1-based end line
|
|
27
|
+
end_col: int # 1-based end column
|
|
28
|
+
|
|
29
|
+
def __repr__(self) -> str:
|
|
30
|
+
preview = self.value[:40].replace("\n", "\\n")
|
|
31
|
+
if len(self.value) > 40:
|
|
32
|
+
preview += "..."
|
|
33
|
+
return f"Token({self.kind.name}, {preview!r}, {self.line}:{self.col})"
|