0
# Parsing & AST System
1

2
Comprehensive parsing system that converts Stylus source into a structured Abstract Syntax Tree (AST), with 40+ node types representing all language constructs from basic values to complex control flow.
3

4
## Capabilities
5

6
### Parser Class
7

8
Main parser for converting Stylus source code into AST nodes.
9

10
```javascript { .api }
11
/**
12
 * Parser for Stylus source code
13
 * @param {string} str - Stylus source code to parse
14
 * @param {ParserOptions} options - Parser configuration options
15
 */
16
class Parser {
17
  constructor(str, options);
18
  
19
  /**
20
   * Parse source code to AST
21
   * @returns {Node} Root AST node
22
   */
23
  parse();
24
  
25
  /**
26
   * Peek at next token without consuming it
27
   * @returns {Token} Next token
28
   */
29
  peek();
30
  
31
  /**
32
   * Advance to next token
33
   * @returns {Token} Current token
34
   */
35
  advance();
36
  
37
  /**
38
   * Accept token of specified type
39
   * @param {string} type - Token type to accept
40
   * @returns {Token|undefined} Token if accepted, undefined otherwise
41
   */
42
  accept(type);
43
  
44
  /**
45
   * Expect token of specified type (throws if not found)
46
   * @param {string} type - Token type expected
47
   * @returns {Token} Expected token
48
   */
49
  expect(type);
50
}
51
```
52

53
### Base Node Class
54

55
All AST nodes inherit from this base class providing common functionality.
56

57
```javascript { .api }
58
/**
59
 * Base class for all AST nodes
60
 */
61
class Node {
62
  constructor();
63
  
64
  /** Line number in source file */
65
  lineno: number;
66
  /** Column number in source file */
67
  column: number;
68
  /** Source filename */
69
  filename: string;
70
  
71
  /**
72
   * Convert node to JSON representation
73
   * @returns {object} JSON representation
74
   */
75
  toJSON();
76
  
77
  /**
78
   * Evaluate the node
79
   * @returns {Node} Evaluated result
80
   */
81
  eval();
82
  
83
  /**
84
   * Clone the node
85
   * @returns {Node} Cloned node
86
   */
87
  clone();
88
  
89
  /**
90
   * String representation of node
91
   * @returns {string} String representation
92
   */
93
  toString();
94
}
95
```
96

97
### Core Structure Nodes
98

99
Main structural nodes for organizing stylesheet content.
100

101
```javascript { .api }
102
/**
103
 * Root node - top-level container for entire stylesheet
104
 */
105
class Root extends Node {
106
  constructor();
107
  nodes: Node[];
108
}
109

110
/**
111
 * CSS property declaration
112
 */
113
class Property extends Node {
114
  constructor(segments, expr);
115
  segments: Node[];
116
  expr: Expression;
117
}
118

119
/**
120
 * Statement block containing rules and properties
121
 */
122
class Block extends Node {
123
  constructor(parent, node);
124
  nodes: Node[];
125
  parent: Block;
126
  scope: boolean;
127
}
128

129
/**
130
 * CSS selector
131
 */
132
class Selector extends Node {
133
  constructor(segments);
134
  segments: Node[];
135
  optional: boolean;
136
}
137

138
/**
139
 * Group of selectors sharing the same block
140
 */
141
class Group extends Node {
142
  constructor();
143
  nodes: Selector[];
144
  extends: Node[];
145
  block: Block;
146
}
147
```
148

149
### Value Nodes
150

151
Nodes representing different types of values and literals.
152

153
```javascript { .api }
154
/**
155
 * Identifier or variable reference
156
 */
157
class Ident extends Node {
158
  constructor(name, val, mixin);
159
  name: string;
160
  val: Node;
161
  mixin: boolean;
162
}
163

164
/**
165
 * String literal value
166
 */
167
class String extends Node {
168
  constructor(val, quote);
169
  val: string;
170
  quote: string;
171
}
172

173
/**
174
 * Numeric value with optional unit
175
 */
176
class Unit extends Node {
177
  constructor(val, type);
178
  val: number;
179
  type: string;
180
}
181

182
/**
183
 * RGBA color value
184
 */
185
class RGBA extends Node {
186
  constructor(r, g, b, a);
187
  r: number;
188
  g: number;
189
  b: number;
190
  a: number;
191
}
192

193
/**
194
 * HSLA color value
195
 */
196
class HSLA extends Node {
197
  constructor(h, s, l, a);
198
  h: number;
199
  s: number;
200
  l: number;
201
  a: number;
202
}
203

204
/**
205
 * Boolean value
206
 */
207
class Boolean extends Node {
208
  constructor(val);
209
  val: boolean;
210
}
211

212
/**
213
 * Null value
214
 */
215
class Null extends Node {
216
  constructor();
217
}
218

219
/**
220
 * Object/hash value
221
 */
222
class Object extends Node {
223
  constructor();
224
  vals: object;
225
}
226
```
227

228
### Expression Nodes
229

230
Nodes for expressions and operations.
231

232
```javascript { .api }
233
/**
234
 * Expression container
235
 */
236
class Expression extends Node {
237
  constructor(isList);
238
  nodes: Node[];
239
  isList: boolean;
240
}
241

242
/**
243
 * Member access expression (obj.prop)
244
 */
245
class Member extends Node {
246
  constructor(left, right);
247
  left: Node;
248
  right: Node;
249
}
250

251
/**
252
 * Binary operation (+, -, *, /, etc.)
253
 */
254
class BinOp extends Node {
255
  constructor(op, left, right);
256
  op: string;
257
  left: Node;
258
  right: Node;
259
}
260

261
/**
262
 * Unary operation (!, -, +, etc.)
263
 */
264
class UnaryOp extends Node {
265
  constructor(op, expr);
266
  op: string;
267
  expr: Node;
268
}
269

270
/**
271
 * Ternary conditional expression (cond ? true : false)
272
 */
273
class Ternary extends Node {
274
  constructor(cond, trueExpr, falseExpr);
275
  cond: Node;
276
  trueExpr: Node;
277
  falseExpr: Node;
278
}
279
```
280

281
### Control Flow Nodes
282

283
Nodes for conditional statements and loops.
284

285
```javascript { .api }
286
/**
287
 * Conditional if statement
288
 */
289
class If extends Node {
290
  constructor(cond, negate);
291
  cond: Node;
292
  block: Block;
293
  elses: Node[];
294
  negate: boolean;
295
}
296

297
/**
298
 * Each loop statement
299
 */
300
class Each extends Node {
301
  constructor(val, key, expr);
302
  val: string;
303
  key: string;
304
  expr: Node;
305
  block: Block;
306
}
307

308
/**
309
 * Return statement
310
 */
311
class Return extends Node {
312
  constructor(expr);
313
  expr: Node;
314
}
315
```
316

317
### Function Nodes
318

319
Nodes for function definitions and calls.
320

321
```javascript { .api }
322
/**
323
 * Function definition
324
 */
325
class Function extends Node {
326
  constructor(name, params, body);
327
  name: string;
328
  params: Params;
329
  body: Block;
330
}
331

332
/**
333
 * Function call
334
 */
335
class Call extends Node {
336
  constructor(name, args);
337
  name: string;
338
  args: Arguments;
339
}
340

341
/**
342
 * Function parameters
343
 */
344
class Params extends Node {
345
  constructor();
346
  nodes: Node[];
347
}
348

349
/**
350
 * Function arguments
351
 */
352
class Arguments extends Node {
353
  constructor();
354
  nodes: Node[];
355
}
356
```
357

358
### Import and Media Nodes
359

360
Nodes for imports and media queries.
361

362
```javascript { .api }
363
/**
364
 * @import directive
365
 */
366
class Import extends Node {
367
  constructor(path, once);
368
  path: Node;
369
  once: boolean;
370
}
371

372
/**
373
 * @media rule
374
 */
375
class Media extends Node {
376
  constructor();
377
  val: QueryList;
378
  block: Block;
379
}
380

381
/**
382
 * Media query list
383
 */
384
class QueryList extends Node {
385
  constructor();
386
  nodes: Query[];
387
}
388

389
/**
390
 * Single media query
391
 */
392
class Query extends Node {
393
  constructor();
394
  type: string;
395
  nodes: Feature[];
396
}
397

398
/**
399
 * Media feature
400
 */
401
class Feature extends Node {
402
  constructor(segments);
403
  segments: Node[];
404
  name: string;
405
  expr: Node;
406
}
407
```
408

409
### Advanced Nodes
410

411
Specialized nodes for advanced Stylus features.
412

413
```javascript { .api }
414
/**
415
 * @extend directive
416
 */
417
class Extend extends Node {
418
  constructor(selectors);
419
  selectors: Selector[];
420
}
421

422
/**
423
 * At-rule (@font-face, @page, etc.)
424
 */
425
class Atrule extends Node {
426
  constructor(type);
427
  type: string;
428
  segments: Node[];
429
  block: Block;
430
}
431

432
/**
433
 * @keyframes rule
434
 */
435
class Keyframes extends Atrule {
436
  constructor(segs, prefix);
437
  segments: Node[];
438
  prefix: string;
439
  block: Block;
440
}
441

442
/**
443
 * @supports rule
444
 */
445
class Supports extends Node {
446
  constructor(condition);
447
  condition: Node;
448
  block: Block;
449
}
450

451
/**
452
 * @charset directive
453
 */
454
class Charset extends Node {
455
  constructor(val);
456
  val: string;
457
}
458

459
/**
460
 * @namespace directive
461
 */
462
class Namespace extends Node {
463
  constructor(val, prefix);
464
  val: string;
465
  prefix: string;
466
}
467

468
/**
469
 * @block directive
470
 */
471
class Atblock extends Node {
472
  constructor();
473
  block: Block;
474
  nodes: Node[];
475
}
476

477
/**
478
 * CSS comment
479
 */
480
class Comment extends Node {
481
  constructor(str, suppress, inline);
482
  str: string;
483
  suppress: boolean;
484
  inline: boolean;
485
}
486

487
/**
488
 * Literal CSS output
489
 */
490
class Literal extends Node {
491
  constructor(str);
492
  str: string;
493
  css: string;
494
}
495
```
496

497
## Usage Examples
498

499
```javascript
500
const stylus = require('stylus');
501

502
// Parse Stylus source to AST
503
const parser = new stylus.Parser('body\n  color red');
504
const ast = parser.parse();
505

506
console.log(ast.toJSON()); // JSON representation
507

508
// Work with specific node types
509
const { nodes } = stylus;
510

511
// Create nodes programmatically  
512
const colorProp = new nodes.Property(
513
  [new nodes.Ident('color')],
514
  new nodes.Expression().push(new nodes.Ident('red'))
515
);
516

517
// Clone nodes
518
const clonedProp = colorProp.clone();
519

520
// Node type checking
521
if (ast instanceof nodes.Root) {
522
  console.log('Root node');
523
}
524
```
525

526
## Types
527

528
```javascript { .api }
529
// Parser options
530
interface ParserOptions {
531
  /** Source filename for error reporting */
532
  filename?: string;
533
  /** Enable parser caching */
534
  cache?: boolean;
535
  /** Parse in compressed mode */
536
  compress?: boolean;
537
}
538
```