Synta — Language Reference

This is a compact, technical specification for the three artifacts Synta supports: bracketed trees (constituency notation), .synta (flat, line-oriented), and .syt (styling language executed at render time). The reference is precise rather than tutorial-style; examples are included for every construct.

Summary

• Bracketed trees: nested bracket representation of constituency structure. Supports per-node subscripts, numeric indices, parentheses for multiword terminals, and inline arrow hints.
• .synta: one-line-per-thing serialisation that maps terminals and constituents to explicit line numbers and supports explicit arrows.
• .syt: an indentation-aware styling language with assignments, control-flow, comprehensions, and built-in helpers that mutate the renderer scene before drawing.

1. Bracketed notation (grammar & semantics)

1.1 Grammar (informal)

Tree    := Node | Term
Node    := '[' Label (Child)* ']'
Term    := Token | '(' Phrase ')'
Label   := IDENT ('_' SUB)? ('{' INDEX '}')? ('->' INDEX)?
Token   := IDENT ('_' SUB)? ('{' INDEX '}')? ('->' INDEX)?
Phrase  := any characters except unbalanced parentheses (can contain spaces)

1.2 Features

• Preterminals: an internal node whose single child is a terminal will be treated as a POS + word pair and rendered compactly.
• Multi-word terminals: use parentheses to include spaces, e.g. (New York).
• Subtext: append _sub to a label or token to render an additional subline for that object.
• Numeric indices: append {n} to label or token; indices are used by arrows and preserved across conversion to .synta.
• Arrow hints: append ->m to indicate an outgoing arrow to index m. These hints are kept during conversion.

1.3 Examples

[S [NP{1} This] [VP [V is] [NP [D a] [N_wug{2}]]]]

// multiword terminal
[NP (New York)_LOC{4}]

// arrow hint
[S [NP{1} He->2] [VP ...]]

1.4 Notes & limitations

• Parentheses may be nested but must be balanced; no escape sequences are supported inside parentheses.
• Whitespace between tokens is insignificant for structure but used to split unparenthesized multiword tokens in terminals.

2. .synta — flat, line-oriented format

2.1 Line types

• Terminal: * POS token — star, POS label, token (parentheses allowed for multi-word token).
• Composition: i|j|... Label — child line numbers separated by |, then parent label.
• Arrow: from->to {optional label} — arrow between two line numbers; label inside braces is optional.

2.2 Formal rules

• Lines are implicitly numbered 1..N in file order (first non-empty line is 1).
• When authored manually, arrow references should point to earlier lines; the parser will report an error if a reference points to the same or later line.
• Terminal lines MUST begin with * and contain at least POS and token; tokens may be parenthesized to allow spaces.

2.3 Example

* D This
* V is
* D a
* N wug
3|4 NP
2|5 VP
1|6 S
1->3 {trace}

2.4 Conversion considerations

• Conversion from bracketed notation deterministically assigns line numbers by traversing terminals and constituents; indices from bracketed input are kept where possible.
• Arrow labels in bracketed form are not preserved verbatim unless explicitly provided in .synta arrow lines.

3. .syt — styling language (complete reference)

Purpose: run arbitrary styling code against the renderer scene before the canvas draw pass. The language is indentation-sensitive and intentionally small but expressive.

3.1 Lexical tokens

• NEWLINE, INDENT, DEDENT — produced by significant indentation.
• IDENT — identifiers (letters, digits, underscores; not starting with digit).
• KW — keywords: If, Elif, Else, While, For, each, Repeat, times, Func, return, break, continue, pass, and, or, not, in, has, where, true, false, null.
• STRING — double-quoted strings with common escapes \n, \t, \".
• NUMBER — integer or floating numeric literals.
• OP — operators and punctuation: =, +=, -=, *=, /=, %=, **, +, -, *, /, %, (, ), [, ], {, }, ., :, ,, comparison ops, etc.

3.2 Statements

• Assignment: target = expr or compound operators (+=, etc.). Targets are identifiers, property access (a.b), or index (a[0]).
• Expression statement: evaluate expression for side effects (e.g., function calls).
• If/Elif/Else: standard conditional with block introduced by :.
• While, For each (For each x in iterable:), and Repeat n times.
• Func definition and return semantics (lexical closures supported).
• Break/Continue/Pass supported.

3.3 Expressions (summary)

Supports precedence-aware expressions: unary (-, not), binary (+, -, *, /, %, **), comparisons (==, !=, <, <=, >, >=), logical and/or, membership in/not in, and has for property checks.

3.4 Comprehensions

List comprehensions using the syntax [var in Collection where predicate] produce a filtered list.

3.5 Built-in runtime objects

On execution the interpreter receives a scene object with these properties (names are case-sensitive):

• All: array containing every object (nodes, lines, arrows) present in the scene.
• Nodes: array of node objects (internal and terminal nodes).
• Terms: array of terminal objects.
• Lines: array of parent→child edge objects.
• Arrows: array of arrow objects.
• Tree: object with global tree settings: Alignment ("level" or "bottom"), MinVerticalSpacing, MaxVerticalSpacing, MinHorizontalSpacing, MaxHorizontalSpacing.

3.6 Object shapes (common fields)

Fields commonly present on scene objects (not exhaustive):

Node/Term object:
  Type: 'Node' | 'Term'
  Id: string
  Visible: boolean
  Parent: reference | null
  Children: array
  Text: string
  TextSize: number
  Font: string
  Color: css | [r,g,b]
  X, Y, _x, _y: numeric positions

Line object:
  Type:'Line', Id: string, Parent: node, Child: node, Width, Color, Style

Arrow object:
  Type:'Arrow', Id: string, From: node, To: node, Width, Color, Style, Label, Visible

3.7 Property semantics

• Assigning a property to an array broadcasts the assignment to every element that has that property (e.g., Lines.Width = 2 updates every element of Lines).
• Protecting built-ins: the interpreter prevents overwriting protected global names (All, Nodes, Lines, Terms, Arrows, Tree).

3.8 Built-in helper functions

len(x)       // length of list or string
type(x)      // returns 'list','null','number','string', etc.
range(a,b)   // integer ranges
min/max/abs
int/float/str/bool
rgb(r,g,b)   // returns [r,g,b] tuple used by renderer

3.9 Error model

Runtime errors (undefined variables, invalid indices, type errors, invalid assignments) are raised as exceptions. The UI surfaces interpreter errors in the errors panel.

4. Common SYT patterns & examples

4.1 Color nodes by label

for each n in Nodes:
    if n.label == "NP":
        n.Color = rgb(10,180,120)
    elif n.label == "VP":
        n.Color = rgb(10,120,180)

4.2 Hide unlabeled arrows

for each a in Arrows:
    if not a.Label:
        a.Visible = false

4.3 Increase spacing

Tree.MinHorizontalSpacing = 160
Tree.MinVerticalSpacing = 240

5. Export, conversion & validation

• The renderer draws the scene to a single canvas. PNG export uses the canvas content only; DOM elements (gutters, editors) are not included.
• Before exporting, click Render to re-run the .syt script so style mutations are applied to the scene.
• The built-in Test Export runs an automated in-browser check for both bracketed and .synta render paths; it validates that exported PNG blobs are produced.