0
# Abstract Syntax Tree
1

2
Complete AST system with 50+ node classes representing all Python language constructs. The AST provides programmatic access to parsed RapydScript code for analysis, transformation, and code generation.
3

4
## Capabilities
5

6
### Base AST Classes
7

8
Foundation classes that all AST nodes inherit from.
9

10
```javascript { .api }
11
/**
12
 * Root base class for all AST nodes
13
 */
14
class AST {
15
  constructor(props?: object);
16
  
17
  /** Clone this node with optional property overrides */
18
  clone(props?: object): AST;
19
  
20
  /** Apply a transformation function to this node and its children */
21
  transform(transformer: TreeTransformer): AST;
22
  
23
  /** Walk through this node and its children with a visitor function */
24
  walk(visitor: TreeWalker): void;
25
  
26
  /** Get a string representation of this node */
27
  toString(): string;
28
}
29

30
/**
31
 * Token from lexical analysis
32
 */
33
class AST_Token extends AST {
34
  type: string;
35
  value: string;
36
  line: number;
37
  col: number;
38
  pos: number;
39
  endline: number;
40
  endcol: number;
41
  endpos: number;
42
  nlb: boolean;
43
  comments_before: AST_Token[];
44
  comments_after: AST_Token[];
45
}
46

47
/**
48
 * Base class for syntax tree nodes
49
 */
50
class AST_Node extends AST {
51
  start: AST_Token;
52
  end: AST_Token;
53
  
54
  /** Print this node to an output stream */
55
  print(stream: OutputStream, force_parens?: boolean): void;
56
}
57
```
58

59
### Statement Classes
60

61
AST nodes representing executable statements.
62

63
```javascript { .api }
64
/**
65
 * Base class for all statements
66
 */
67
class AST_Statement extends AST_Node {}
68

69
/**
70
 * Block of statements  
71
 */
72
class AST_Block extends AST_Statement {
73
  body: AST_Statement[];
74
}
75

76
/**
77
 * Top-level program or module
78
 */
79
class AST_Toplevel extends AST_Block {
80
  /** Print this toplevel to an output stream */
81
  print(output: OutputStream): void;
82
}
83

84
/**
85
 * Single statement
86
 */
87
class AST_SimpleStatement extends AST_Statement {}
88

89
/**
90
 * Conditional statement (if/elif/else)
91
 */
92
class AST_If extends AST_Statement {
93
  condition: AST_Node;
94
  body: AST_Statement;
95
  alternative: AST_Statement | null;
96
}
97

98
/**
99
 * While loop
100
 */
101
class AST_While extends AST_Statement {
102
  condition: AST_Node;
103
  body: AST_Statement;
104
}
105

106
/**
107
 * Do-while loop
108
 */
109
class AST_Do extends AST_Statement {
110
  body: AST_Statement;
111
  condition: AST_Node;
112
}
113

114
/**
115
 * Python-style for loop (for item in iterable)
116
 */
117
class AST_ForIn extends AST_Statement {
118
  init: AST_Node;
119
  object: AST_Node;
120
  body: AST_Statement;
121
}
122

123
/**
124
 * JavaScript-style for loop
125
 */
126
class AST_ForJS extends AST_Statement {
127
  init: AST_Node | null;
128
  condition: AST_Node | null;
129
  step: AST_Node | null;
130
  body: AST_Statement;
131
}
132

133
/**
134
 * Try block
135
 */
136
class AST_Try extends AST_Statement {
137
  body: AST_Statement;
138
  bcatch: AST_Catch | null;
139
  bfinally: AST_Finally | null;
140
}
141

142
/**
143
 * Catch clause (JavaScript-style)
144
 */
145
class AST_Catch extends AST_Block {
146
  argname: AST_Symbol;
147
}
148

149
/**
150
 * Except clause (Python-style)
151
 */
152
class AST_Except extends AST_Block {
153
  errors: AST_Node[];
154
  argname: AST_Symbol | null;
155
}
156

157
/**
158
 * Finally block
159
 */
160
class AST_Finally extends AST_Block {}
161

162
/**
163
 * Function definition
164
 */
165
class AST_Function extends AST_Statement {
166
  name: AST_Symbol;
167
  argnames: AST_Symbol[];
168
  defaults: AST_Node[];
169
  is_generator: boolean;
170
  body: AST_Statement;
171
}
172

173
/**
174
 * Class definition
175
 */
176
class AST_Class extends AST_Statement {
177
  name: AST_Symbol;
178
  parent: AST_Node | null;
179
  body: AST_Statement;
180
}
181

182
/**
183
 * Class method definition
184
 */
185
class AST_Method extends AST_Function {
186
  static: boolean;
187
}
188

189
/**
190
 * Return statement
191
 */
192
class AST_Return extends AST_Statement {
193
  value: AST_Node | null;
194
}
195

196
/**
197
 * Yield expression (for generators)
198
 */
199
class AST_Yield extends AST_Statement {
200
  value: AST_Node | null;
201
  is_yield_from: boolean;
202
}
203

204
/**
205
 * Break statement
206
 */
207
class AST_Break extends AST_Statement {}
208

209
/**
210
 * Continue statement
211
 */
212
class AST_Continue extends AST_Statement {}
213
```
214

215
### Expression Classes
216

217
AST nodes representing expressions and values.
218

219
```javascript { .api }
220
/**
221
 * Base class for expressions
222
 */
223
class AST_Expression extends AST_Node {}
224

225
/**
226
 * Function call
227
 */
228
class AST_Call extends AST_Expression {
229
  expression: AST_Node;
230
  args: AST_Node[];
231
  kwargs: AST_Node[];
232
}
233

234
/**
235
 * Binary operation (+, -, *, etc.)
236
 */
237
class AST_Binary extends AST_Expression {
238
  operator: string;
239
  left: AST_Node;
240
  right: AST_Node;
241
}
242

243
/**
244
 * Unary operation (-, not, etc.)
245
 */
246
class AST_Unary extends AST_Expression {
247
  operator: string;
248
  expression: AST_Node;
249
}
250

251
/**
252
 * Ternary conditional operator (a if condition else b)
253
 */
254
class AST_Conditional extends AST_Expression {
255
  condition: AST_Node;
256
  consequent: AST_Node;
257
  alternative: AST_Node;
258
}
259

260
/**
261
 * Array literal [1, 2, 3]
262
 */
263
class AST_Array extends AST_Expression {
264
  elements: AST_Node[];
265
}
266

267
/**
268
 * Object literal {key: value}
269
 */
270
class AST_Object extends AST_Expression {
271
  properties: AST_ObjectKeyVal[];
272
}
273

274
/**
275
 * Object property (key: value pair)
276
 */
277
class AST_ObjectKeyVal extends AST_Node {
278
  key: AST_Node;
279
  value: AST_Node;
280
}
281

282
/**
283
 * Set literal {1, 2, 3}
284
 */
285
class AST_Set extends AST_Expression {
286
  elements: AST_Node[];
287
}
288

289
/**
290
 * Property access (obj.prop)
291
 */
292
class AST_Dot extends AST_Expression {
293
  expression: AST_Node;
294
  property: string;
295
}
296

297
/**
298
 * Subscript access (obj[key])
299
 */
300
class AST_Sub extends AST_Expression {
301
  expression: AST_Node;
302
  property: AST_Node;
303
}
304

305
/**
306
 * Variable reference or identifier
307
 */
308
class AST_Symbol extends AST_Expression {
309
  name: string;
310
  scope: Scope;
311
  thedef: SymbolDef;
312
}
313

314
/**
315
 * String literal
316
 */
317
class AST_String extends AST_Expression {
318
  value: string;
319
  quote: string;
320
}
321

322
/**
323
 * Number literal
324
 */
325
class AST_Number extends AST_Expression {
326
  value: number;
327
}
328

329
/**
330
 * Boolean literal (True/False)
331
 */
332
class AST_Boolean extends AST_Expression {
333
  value: boolean;
334
}
335

336
/**
337
 * Null literal (None)
338
 */
339
class AST_Null extends AST_Expression {}
340

341
/**
342
 * Undefined literal
343
 */
344
class AST_Undefined extends AST_Expression {}
345
```
346

347
### Comprehension Classes
348

349
AST nodes for Python-style comprehensions.
350

351
```javascript { .api }
352
/**
353
 * Base class for comprehensions
354
 */
355
class AST_Comprehension extends AST_Expression {
356
  statement: AST_Node;
357
  condition: AST_Node | null;
358
}
359

360
/**
361
 * List comprehension [x for x in items]
362
 */
363
class AST_ListComprehension extends AST_Comprehension {}
364

365
/**
366
 * Set comprehension {x for x in items}
367
 */
368
class AST_SetComprehension extends AST_Comprehension {}
369

370
/**
371
 * Dictionary comprehension {k:v for k,v in items}
372
 */
373
class AST_DictComprehension extends AST_Comprehension {}
374

375
/**
376
 * Generator expression (x for x in items)
377
 */
378
class AST_GeneratorComprehension extends AST_Comprehension {}
379

380
/**
381
 * Decorator (@decorator syntax)
382
 */
383
class AST_Decorator extends AST_Node {
384
  decorator: AST_Node;
385
  args: AST_Node[];
386
}
387

388
/**
389
 * Assert statement
390
 */
391
class AST_Assert extends AST_Statement {
392
  condition: AST_Node;
393
  message: AST_Node | null;
394
}
395

396
/**
397
 * Import statement
398
 */
399
class AST_Import extends AST_Statement {
400
  module: AST_Node;
401
  names: AST_Node[];
402
  alias: string | null;
403
}
404

405
/**
406
 * Slice expression (a[1:5])
407
 */
408
class AST_Slice extends AST_Expression {
409
  expression: AST_Node;
410
  start: AST_Node | null;
411
  end: AST_Node | null;
412
  step: AST_Node | null;
413
}
414

415
/**
416
 * Existential operator (?)
417
 */
418
class AST_Existential extends AST_Expression {
419
  expression: AST_Node;
420
}
421
```
422

423
### AST Transformation and Traversal
424

425
Utilities for programmatically analyzing and modifying AST nodes.
426

427
```javascript { .api }
428
/**
429
 * Tree transformer for modifying AST nodes
430
 */
431
interface TreeTransformer {
432
  (node: AST_Node, descend: () => AST_Node): AST_Node;
433
}
434

435
/**
436
 * Tree walker for visiting AST nodes
437
 */
438
interface TreeWalker {
439
  (node: AST_Node, descend: () => void): void;
440
}
441

442
/**
443
 * Symbol definition in scope
444
 */
445
class SymbolDef {
446
  name: string;
447
  orig: AST_Symbol[];
448
  scope: Scope;
449
  references: AST_Symbol[];
450
  global: boolean;
451
  mangled_name: string;
452
}
453

454
/**
455
 * Lexical scope
456
 */
457
class Scope {
458
  names: {[name: string]: SymbolDef};
459
  mangled_names: {[name: string]: boolean};
460
  parent_scope: Scope | null;
461
  enclosed: SymbolDef[];
462
  cname: number;
463
}
464
```
465

466
### Usage Examples
467

468
**Basic AST Manipulation:**
469

470
```javascript
471
const { create_compiler } = require("rapydscript-ng");
472
const RapydScript = create_compiler();
473

474
// Parse code into AST
475
const ast = RapydScript.parse(`
476
def factorial(n):
477
    if n <= 1:
478
        return 1
479
    return n * factorial(n - 1)
480
`);
481

482
// Walk through AST nodes
483
ast.walk(function(node) {
484
  if (node instanceof RapydScript.AST_Function) {
485
    console.log("Found function:", node.name.name);
486
  }
487
});
488
```
489

490
**AST Transformation:**
491

492
```javascript
493
// Transform all string literals to uppercase
494
const transformed = ast.transform(function(node, descend) {
495
  if (node instanceof RapydScript.AST_String) {
496
    return new RapydScript.AST_String({
497
      value: node.value.toUpperCase(),
498
      quote: node.quote,
499
      start: node.start,
500
      end: node.end
501
    });
502
  }
503
  return descend();
504
});
505
```
506

507
**Finding Specific Nodes:**
508

509
```javascript
510
const functions = [];
511
ast.walk(function(node) {
512
  if (node instanceof RapydScript.AST_Function) {
513
    functions.push({
514
      name: node.name.name,
515
      args: node.argnames.map(arg => arg.name),
516
      line: node.start.line
517
    });
518
  }
519
});
520
```
521

522
**Creating AST Nodes:**
523

524
```javascript
525
// Create a new function call node
526
const call = new RapydScript.AST_Call({
527
  expression: new RapydScript.AST_Symbol({name: "print"}),
528
  args: [
529
    new RapydScript.AST_String({value: "Hello, World!", quote: '"'})
530
  ]
531
});
532

533
// Generate JavaScript from the node
534
const output = new RapydScript.OutputStream({ beautify: true });
535
call.print(output);
536
console.log(output.get()); // print("Hello, World!");
537
```