Syntax v2 specification

Status: normative for core / reactive / backend. Layout-UI section is provisional. Plan: SYNTAX_V2_PLAN.md · Golden corpus: examples/v2/ Decisions: all nine open items in the plan's §8 are resolved as recommended — recorded in §1.

This spec is the mapping contract for the v2 front-end. Phase 2 is complete when every form below lowers to the v1 form in the same row and the golden corpus produces byte-identical stdout to its v1 twins.

Coverage is verified mechanically, not by eye:

python3 scripts/syntax_v2_spec_check.py

That script fails if any live conversational phrase is missing from this document. Because this is a solo project with no second reviewer, the gates are the review — every claim in this spec is either machine-checked or explicitly marked provisional.

1. Resolved decisions

Lexical rules

• Case sensitive. v1 accepted any casing (startsCI); v2 keywords are lowercase. Identifiers keep their v1 spelling, so httpReply stays httpReply.
• Statement terminator: newline. No semicolons required; ; permitted as a separator.
• Comments: // line, /* */ block.
• Strings: "..." with \n \t \" \\ escapes. Triple-quoted """...""" blocks are retained verbatim for embedded CSS/HTML (see §8).
• Reserved words are the lowercase keywords in this document. signal, derived, effect, watch, bind are reserved.

2. Core statements

2.1 let vs var requires mutation analysis

v1 has no immutability distinction — MY NAME IS declares everything, and any binding can later be reassigned with SET. v2 splits this into let and var, so the mapping is not mechanical. A one-to-one MY NAME IS → let rule produces code that will not compile.

The rule the migrator must implement, per binding, within its scope:

Emit var if the name is ever the target of SET, CHANGE, INCREASE, or DECREASE. Otherwise emit let.

Concretely, from examples/build/backend_api.luke:

MY NAME IS answered AS FLAG SET TO FALSE   // later: SET answered TO TRUEMY NAME IS path SET TO ASK httpPath WITH req   // never reassigned

var answered: bool = false   // mutated -> varlet path = httpPath(req)     // never mutated -> let

This is the first place a naive migrator breaks, and it is not detectable by the stdout equivalence harness alone — bad output here fails to compile, which is the good case. The dangerous case is the reverse: emitting var everywhere would compile fine and silently discard the immutability guarantee that motivated decision 3. Prefer let and let the compiler complain.

Types

AS as a type-annotation particle becomes :. AS in SLOT INPUT AS CHECKBOX becomes a named argument (see §6).

Operators

The AND split is the headline fix. v1 overloads one token for concatenation and conjunction; v2 separates + from &&. A v1→v2 migrator must resolve this by operand type: str operands lower to +, bool operands to &&.

Precedence (loosest to tightest): || · && · == != < > <= >= · + - · * / % · unary ! - · call/index/field. Parentheses group.

Associativity and parenthesisation

Verified against the v1 compiler rather than assumed:

• v1 arithmetic is left-associative (10 SUBTRACT 3 SUBTRACT 2 = 5, 12 DIVIDED BY 3 DIVIDED BY 2 = 2).
• v1 concatenation (AND) is right-associative.

The lowerer therefore always parenthesises binary operands. That makes grouping explicit and immunises non-associative operators (-, /) against any v1 associativity assumption. The visible consequence is that a + b + c on strings produces a differently-shaped — but semantically identical — tree than hand-written v1, so the equivalence harness treats a generated-C difference on concatenation as expected, not a failure.

Not yet lowered

3. Collections

4. Structs (was BLUEPRINT)

BORN / BORNED are v1 WHEN BORN block enders; v2 uses }.

5. Reactive — declarative, by decision

Spelling changes; kind does not. These stay first-class statements, not library calls.

6. Layout and UI — provisional

Not normative. The frontend track is parked (TaskList.md §7) and backend is the beachhead. These mappings are a placeholder so frontend_widgets can exist in the golden corpus; settling them must not block backend publish. Phase 4 revisits.

The shape: declarative blocks with braces and named arguments.

7. Modules

std/ and luke/ remain import namespace prefixes, unchanged.

8. Backend — declarative forms retained

Embedded foreign content

Triple-quoted blocks (WEAR STYLE """…""", FILL … WITH """…""") contain CSS/HTML, not Luke. The lexer treats them as opaque and the migrator copies them byte for byte. This is why part of the plan's Raw tail needs no structuring — see SYNTAX_V2_PLAN.md §2.2.

9. Dropped in v2

The 44 dead phrases (present in codegen, unused in the corpus) are not ported. Notable deliberate removals beyond those:

Collapsing aliases is a real simplification: v1's 216 phrases include many synonyms that exist only because the surface was English.

10. Worked example

v1 — examples/build/backend_api.luke (excerpt):

import std/serverimport std/sqlitefn handle(req: Request) {  let db = dbOpen("/tmp/luke_backend_api.db")  let method = httpMethod(req)  let path = httpPath(req)  var params: map = {}  if method == "GET" {    if httpMatch(path, "/user/:id", params) {      let id = params["id"]      var binds: list = []      binds.push(id)      let name = dbQueryBind(db, "SELECT name FROM users WHERE id = ?", binds)      httpReply(req, 200, "text/plain", name)    }  }  dbClose(db)}

v2 — examples/v2/backend_api.lk:

import std/serverimport std/sqlitefn handle(req: Request) {  let db = dbOpen("/tmp/luke_backend_api.db")  let method = httpMethod(req)  let path = httpPath(req)  var params: map = {}  if method == "GET" {    if httpMatch(path, "/user/:id", params) {      let id = params["id"]      var binds: list = []      binds.push(id)      let name = dbQueryBind(db, "SELECT name FROM users WHERE id = ?", binds)      httpReply(req, 200, "text/plain", name)    }  }  dbClose(db)}

Same program, same line count. The win is not brevity — it is that every construct is one a backend developer already recognises, and that ASK … WITH, MY NAME IS … SET TO, and GET … FROM stop being things you have to learn before writing a route handler.

11. What the front-end must guarantee

1. Lower to v1 text, not to C. Codegen is untouched (plan §3).
2. Emit // @luke-file "app.lk" N markers so diagnostics, #line maps, gdb, and LSP all report .lk positions. This is a Phase 2 gate, not a follow-up.
3. Preserve evaluation order and stdout exactly. The acceptance test is byte-identical stdout against the v1 twin, for every file in examples/v2/.
4. Reject, never guess. An unmappable construct is a compile error citing this spec, not a silent passthrough.

Implementation status

Shipped in vm/src/luke2_lex.cpp, luke2_parse.cpp, luke2_lower.cpp, luke2_migrate.cpp; .lk paths and luke MIGRATE are dispatched from main.cpp. build_c.cpp is unmodified.

Phase 3a (structuring the remaining Raw tail) is required before MIGRATE_CORPUS=all can be the CI gate; today that probe is informational (~38/118 pass on examples/build).

cd vm && make && make test-syntax-v2

Type information comes from v2 annotations, literals, in-file fn signatures, and — for stdlib calls — the GIVES BACK clauses read straight out of the v1 vm/stdlib/*.luke sources. No hand-maintained return-type table, so it cannot drift from the stdlib.