Internal documentation — Work in progress
This page has not been confirmed as accurate or approved for publication. Current documentation version: 0.1.0-internal.1.
Examples
Tokenizer demonstration
examples/tokenizer_demo.sagan is the representative source fixture. It
covers modules and imports, interfaces and classes, function forms, mutating
method names, typed declarations, numeric separators and scientific notation,
vectors and coordinates, dictionaries, raw and multiline strings, nested
interpolation, exception keywords, increment, and an emoji identifier.
The file has been checked as tokenizer input. It is not executable because no parser or later compiler stages exist.
Parser and visual AST demonstration
examples/parser_demo.sagan exercises the parser features implemented so far,
including precedence, right-associative exponentiation and assignment, the
conditional expression, indexing, ordinary and safe member access, function and
method calls, mutating method names, and deep postfix chains.
It also includes ordinary, raw, multiline, and interpolated strings, including
interpolations containing member access and arithmetic expressions.
The collection section demonstrates arrays, dictionaries with expression keys,
vectors, coordinates, spreads, trailing commas, and multiline formatting.
Its control-flow section adds nested blocks, declarations, ordinary assignment,
expression statements, an if/else if/else chain, all three loop forms,
break, continue, both return forms, and match/case with a fallback inside
a typed, block-bodied function. It also demonstrates multiple unless handlers,
scream, and finally cleanup around a protected hope block.
The first command prints the tree and confirms the intentional errors in
examples/parser_error.sagan, examples/postfix_error.sagan, and
examples/string_error.sagan, examples/collection_error.sagan,
examples/block_error.sagan, examples/control_flow_error.sagan, and
examples/match_error.sagan, and examples/exception_error.sagan. The second
opens a self-contained page showing the input source beside a colored tree. The
page supports button and mouse-wheel zoom plus drag-to-pan navigation. Use
bash scripts/ast_demo.sh --no-open to generate build/ast-demo.html without
launching a browser.
The string error fixture demonstrates the focused diagnostic for an empty
${} interpolation. The collection fixture demonstrates the minimum
two-element vector rule.
The block fixture demonstrates the focused diagnostic for a missing closing
brace. The control-flow fixture demonstrates the diagnostic for break outside
a loop. The match fixture demonstrates that case else must be the last branch.
The exception fixture demonstrates that scream requires a value.
Intentional lexical error
examples/tokenizer_error.sagan contains:
The tokenizer rejects it because the exponent has no digits.
When adding examples, say whether they are tokenizer fixtures, intended syntax, or eventually executable programs. Never imply execution solely from successful tokenization.