Weft grammar
This document defines the normative grammar of the .weft language. The parser (weft_ui_parser::parse) implements this grammar. For semantic rules (scope, types, and dependencies), see Semantic constraints.
Lexical rules
Section titled “Lexical rules”- Source files are encoded in UTF-8. Newlines, like other whitespace, are insignificant except as token separators.
- Comments:
// line commentand/* block comment */. Block comments do not nest. - Identifiers:
[A-Za-z_][A-Za-z0-9_]*. - Reserved keywords:
ifelseforintruefalsenull. - Contextual keywords (ordinary identifiers elsewhere, such as the
modelparameter in Demo):import(followed by a string) andmodel/event/component(followed by an identifier) begin declarations only at the top level;state(followed by an identifier) begins a state declaration only in a component body;keyappears only in aforheader.
- Integers:
[0-9]+, within the range ofi64. Floating-point numbers:[0-9]+ "." [0-9]+ ([eE] [+-]? [0-9]+)?or[0-9]+ [eE] [+-]? [0-9]+. - Strings:
"...", with escapes\n\r\t\0\\\"\$\u{XXXX}.${ expression }interpolates an expression, which may itself contain strings. Strings cannot span multiple lines. - Symbols:
( ) { } [ ] , : ; . ?. ? ?? = += -= == != < <= > >= + - * / % ! && || ->
Grammar
Section titled “Grammar”EBNF notation: X? means optional, X* means zero or more occurrences, X+ means one or more occurrences, and "tok" denotes a token.
File = Import* Item* EOF ;Import = "import" STRING ; (* no interpolation *)Item = Model | Event | Component ;
Model = "model" IDENT "{" FieldList? "}" ;Event = "event" IDENT ( "(" FieldList? ")" )? ;FieldList = Field ( "," Field )* ","? ;Field = IDENT ":" Type ;
Component = "component" IDENT "(" ParamList? ")" "{" StateDecl* Node* "}" ;ParamList = Param ( "," Param )* ","? ;Param = IDENT ":" Type ( "=" Expr )? ;StateDecl = "state" IDENT ( ":" Type )? "=" Expr ;
Type = IDENT TypeSuffix* ;TypeSuffix = "[" "]" | "?" ;
Block = "{" Node* "}" ;Node = ElementNode | IfNode | ForNode ;ElementNode = Path ( "(" ArgList? ")" )? Block? ;Path = IDENT ( "." IDENT )* ;IfNode = "if" "(" Expr ")" Block ( "else" ( IfNode | Block ) )? ;ForNode = "for" "(" IDENT "in" Expr ( ";" "key" "=" Expr )? ")" Block ;
ArgList = Arg ( "," Arg )* ","? ;Arg = ( IDENT "=" )? Expr ; (* named arguments must follow positional arguments *)
Expr = IfExpr | Binary ;IfExpr = "if" "(" Expr ")" Expr "else" Expr ;Binary = Unary ( BinOp Unary )* ; (* grouped according to the precedence below *)Unary = ( "!" | "-" ) Unary | Postfix ;Postfix = Primary ( "." IDENT | "?." IDENT | "(" ArgList? ")" )* ;Primary = INT | FLOAT | STRING | "true" | "false" | "null" | IDENT | "(" Expr ")" | Lambda ;Lambda = "{" ( IDENT "->" )? ( Assign ";"? )* "}" ;Assign = IDENT ( "=" | "+=" | "-=" ) Expr ;Binary operator precedence (lowest to highest; all operators are left-associative):
| Precedence | Operators |
|---|---|
| 1 | ?? |
| 2 | || |
| 3 | && |
| 4 | == != |
| 5 | < <= > >= |
| 6 | + - |
| 7 | * / % |
Notes:
statedeclarations are allowed only at the top level of a component body, before all nodes.- Nodes require no separators. An opening
(or{immediately afterNamebelongs to that node, even if the{is on the next line. - In node position,
ifrenders conditionally and its branches are blocks of nodes. In expression position,ifrequires anelseand its branches are expressions. - Calls are allowed only after identifiers or member accesses:
Remove(todo.id),name.trim(). - A lambda may only be used directly as the value of an event argument.
- A
forheader can omitkeysyntactically. Semantic analysis reports its absence to provide a more precise diagnostic.
Error recovery
Section titled “Error recovery”The parser continues after an error to report as many errors as possible:
- Top level: Skip to the next
import/model/event/component. - Node blocks: Skip unrecognized tokens, skipping over matched delimiters as a unit, until the next token that can start a node or
}. - Argument and field lists: Skip to the next
,or closing delimiter. - Report only the first error at a given location.
Every AST node carries a source span (file and byte offsets). Diagnostics are located as file:line:column and include a source excerpt.
Semantic constraints
Section titled “Semantic constraints”Scope and imports
Section titled “Scope and imports”- Each file can see its own declarations and those of files it directly imports with
import. Imports are not transitive. - Within the import closure,
model,event, andcomponentdeclarations share one namespace. Duplicate names and names that collide with built-in elements are errors. - Host-side event registration methods are derived from event names (
onFooBar/on_foo_bar). Two event names that differ only in case and underscores (such asFooBarandfoo_bar) are therefore also an error. - Import cycles and missing files are errors.
- Name lookup within a component proceeds in this order: lambda parameters →
forvariables →state→ component parameters. Names may not shadow existing names within a component.
- Primitive types are
IntFloatBoolString. Other types are compound typesT[]andT?andmodelnames. - A component parameter can also be
Children(a slot, at most one per component). The caller fills it with a trailing block, and the component body uses the parameter name as a node. - Assignment compatibility: identical types;
Int→Float;null→T?;T→T?. - Arithmetic:
Int op Int → Int(integer division); the result isFloatif either operand isFloat.String + String → String. - Comparisons
< <= > >=apply only to numbers or strings.== !=apply only to scalar types and their nullable forms. a ?? brequiresa: T?.a?.frequires a nullable receiver and produces a nullable result. Using?.on a non-nullable value emits a warning.- String interpolation accepts only
IntFloatBoolString. - A
modelcannot refer directly to itself except through an array or a nullable type.
Built-in members
Section titled “Built-in members”| Receiver | Members |
|---|---|
String |
length: Int isEmpty: Bool trim() uppercase() lowercase() contains(String): Bool |
T[] |
length: Int isEmpty: Bool contains(T): Bool (T is scalar) |
Int Bool |
toString(): String |
Float |
toString(): String toFixed(Int): String |
length / isEmpty are properties; the rest are methods.
Event arguments
Section titled “Event arguments”Element event arguments have payload types (onClick has no payload; Input.onChange carries a String). Accepted values:
Event: Use the event name as a function. Its parameter count must match the payload count (0 or 1). The payload, if any, supplies the sole parameter.Event(args): Construct the event instance directly. Arguments are bound at render time, and the payload is ignored.{ stmts }/{ v -> stmts }: An inline lambda. It can assign only tostate;vreceives the payload.onMount/onUnmountaccept only events, not lambdas.
- An
ifcondition must beBool. - A
formust have akeyof typeIntorString. The value being iterated must be an array. - Custom components cannot be instantiated recursively except through an
if/for.
Built-in elements and layout
Section titled “Built-in elements and layout”All platforms support the same set of built-in elements and properties (finalized in P2). Only layout semantics are guaranteed to be consistent; appearance follows each platform’s native style.
| Element | Properties (positional arguments in bold) | Events | Children |
|---|---|---|---|
Column |
padding gap width height: Int, background: Color |
— | Yes |
Row |
Same as Column |
— | Yes |
Text |
value: String, color: Color, size: Int, bold: Bool |
— | No |
Button |
disabled: Bool |
onClick |
Yes |
Input |
value: String, placeholder: String, disabled: Bool |
onChange(String) |
No |
Checkbox |
checked: Bool, disabled: Bool |
onChange(Bool) |
No |
Image |
src: String, width height: Int |
— | No |
All elements also have onMount / onUnmount.
- Lengths:
Int, measured in logical pixels: pt on iOS / macOS, dp on Android, DIP on Windows, and CSS px on the web. Mini programs usepx, notrpx. Column/Row: Children are laid out in order from the start of the main axis (vertical forColumn, horizontal forRow). They align to the start of the cross axis, without stretching or automatically filling the available space. As in CSS,gapis the space between adjacent children, andpaddingis the same inset on all four sides. When platform defaults differ, the backend sets the alignment explicitly, for examplealign-items:flex-starton the web and in mini programs, andVStack(alignment: .leading)in SwiftUI.width/height: Fixed dimensions. If omitted, the content determines the size.- Colors: A
Colorproperty accepts#RGB,#RRGGBB, or#RRGGBBAA(case-insensitive hexadecimal) and is treated asStringduring type checking. Literals are validated at compile time: invalid literals are errors, and valid ones are parsed into RGBA and stored in the view layout. The platform parses dynamic values at runtime, treating invalid values as transparent and emitting a warning in development builds. Image:srcis an image URL. On platforms without a built-in control for remote images, the core downloads the image.
Dependency analysis
Section titled “Dependency analysis”- A dependency consists of a root and a field path. The root is a component parameter,
state, or aforvariable, as inmodel.user.name,expanded, ortodo.name. The path traverses only non-nullablemodelfields and stops at an array, a nullable type, a primitive type, or a built-in member such aslength. - Dirty bits: Component parameters and
stateare expanded to leaves by the rules above, with one bit per leaf. Eachforalso has a separate set of per-item dirty bits expanded according to the element type. A dependency covers every leaf for which it is a prefix. For example, passingmodel.userto a child component depends on every bit undermodel.user. - Binding sites: Element properties, component arguments,
ifconditions (the union of the conditions across theif / else ifchain), theforlist and key, and event constructions with arguments (arguments are bound at render time). Values with no dependencies are static and do not generate bindings. Lambdas are evaluated when triggered and do not generate bindings either.