# ZuzuScript Syntax Inventory

This inventory is the starting point for `tree-sitter-zuzu`. It is based on the
user guide, the existing VS Code and Pulsar TextMate grammars, examples,
language tests, and runtime parser entry points.

## File Types

- `.zzs`: script files.
- `.zzm`: module files.
- Extensionless executable scripts with a first line matching `zuzu` in the
  shebang. The grammar represents the first-line shebang as `shebang`.

## Comments and Documentation

- `//` line comments.
- `/* ... */` block comments.
- POD blocks beginning with an `=` command and ending at `=cut`.
- POD-only files without `=cut`, handled by the external scanner as POD to end
  of file.

## Declarations

- Imports: `from module/path import Name;`
- Optional imports: `from module/path try import Name;`
- Conditional imports: `from module/path import Name if condition;`
- Variable declarations: `let name := value;`, `const name := value;`
- Destructuring declarations: `let { key, key: local, String name } := value;`
- Functions: `function name ( params ) { ... }`
- Methods: `method name ( params ) { ... }`
- Classes: `class Name extends Parent with Trait { ... }`
- Compact class declarations: `class Name;`, `class Name with Trait;`, and
  `class Name extends Parent but Trait;`
- Traits: `trait Name { ... }`
- Field declarations in class bodies.

## Statements

- Blocks.
- `if`/`else` and `unless` postfix conditions.
- `while` without `else`.
- `for` with optional `else`.
- `switch`, `case`, and `default`.
- `try`/`catch`.
- `return`, `throw`, `next`, `continue`, and `last`.
- Built-in output/debug statements: `say`, `print`, `warn`, `assert`, `debug`.
- Expression statements.

## Expressions

The grammar encodes the operator precedence from the user guide, including:

- postfix call/member/index/slice/dict access and postfix `++`/`--`;
- prefix unary, prefix `++`/`--`, floor, and ceiling;
- exponentiation;
- multiplicative, additive, concatenation, collection, shift, bitwise, and
  comparison tiers;
- equality and `default`;
- logical operators, including value-preserving `?` forms;
- ternary and Elvis;
- chain operators;
- assignment operators.

## Literals

- Numbers: decimal, hex, octal, binary, and exponent notation.
- Strings: double quoted, single quoted, triple double, triple single.
- Template strings: backtick and triple backtick, with `${ ... }`
  interpolation parsed as normal ZuzuScript expressions.
- Regexp literals.
- Booleans: `true`, `false`, `⊤`, `⊥`.
- Null: `null`.
- Empty set: `∅`.
- Lists, dicts, PairLists, bags, and sets.

## Current Baseline

- `npm test` passes the generated parser corpus and highlight assertions.
- `npm run parse:smoke` passes internal smoke fixtures plus sibling
  `languagetests` and `stdlib/modules` when they are available.
- `languagetests` parse smoke: 125/125 files without `ERROR` or `MISSING`
  nodes.
- `stdlib/modules` parse smoke: 86/86 files without `ERROR` or `MISSING`
  nodes.

## Known Follow-ups

- Expand focused corpus tests from `languagetests`, `stdlib/modules`, examples,
  and the user guide.
- Confirm all runtime parser differences discovered during grammar testing.
- Decide the Pulsar Tree-sitter migration strategy after a current Pulsar spike.
