Grammar / Spec by Example

The Stage-0 grammar is intentionally small. It covers enough syntax to run examples and bootstrap more of Vela. Static types, package imports, traits, and the full dataframe surface are planned for the compiler.

1. Lexical shape

• Comments run from # to the end of the line.
• Indentation is significant.
• Newlines inside () and [] are suppressed.
• Literals include Int, Float, String, Bool, and f-strings.
• Operators include arithmetic, comparison, |>, =>, ?, field access, indexing, and broadcast dot forms.

2. Statement and expression forms

Current Stage-0 files use:

• immutable and mutable bindings,
• fn definitions,
• type declarations for tagged unions,
• if / elif / else,
• while and for,
• lambdas,
• pipelines,
• lists, records, calls, indexing, fields,
• match with patterns and guards.

3. Precedence examples

.sources/vela/docs/SPEC_BY_EXAMPLE.md verifies these outputs against the seed.

print(1 + 2 * 3)
print((1 + 2) * 3)
print(10 - 2 - 3)
print(100 / 5 / 2)
print(2 ^ 3 ^ 2)
print((-2) ^ 2)
print(-2 ^ 2)

7
9
5
10
512
4
-4

4. Runtime rules worth knowing

• Int / Int truncates toward zero.
• % returns a remainder with the sign of the left operand.
• and and or short-circuit and require Bool operands.
• Lists, records, and strings are not truthy.
• Negative list and string indexes are normalized by adding length.
• Records compare structurally and field order does not affect equality.
• Constructor pattern matching currently matches by tag and arity, not nominal type identity.

5. Pattern matching example

# Source: .sources/vela/docs/SPEC_BY_EXAMPLE.md
type Shape:
    Circle(r)
    Rect(w, h)
fn describe(s):
    match s:
        Circle(r) if r > 10 => "big circle"
        Circle(r) => f"circle {r}"
        Rect(w, h) if w == h => "square"
        Rect(w, h) => f"rect {w}x{h}"
        _ => "other"
print(describe(Circle(2)))
print(describe(Circle(20)))

6. The seed grammar is not the final language

The grammar source explicitly says the Stage-0 interpreter is a subset. Treat spec/GRAMMAR.md as the behavior implemented by the seed, and the design/* files as target compiler design unless a runnable example shows otherwise.