Reference
Reference
Grammar
Every keyword and where it may appear, the shapes of declarations, statements and expressions, operators and precedence, and the literals.
This page is a map of what the parser accepts: each keyword, each statement, and where it may be written. The other chapters say what each form means; this page says where it goes.
How to read the shapes on this page:
- A
textblock shows the shape of a form, not a program to copy. …stands for more of the same, and|separates alternatives.- A word in lower case that is not a keyword, such as
expr,Typeorname, stands for something you write there. - Render block means a block that holds elements and the statements that declare state: a page, a component, the
app, a test, and every element's children. Imperative block means a block of statements that run: an action, a handler, an effect, a timer or a hook.
Names
The case of a name says what it is:
| Kind of name | Case | Examples |
|---|---|---|
| Declarations and statements | lower case |
|
| Elements, and the names declarations introduce | capitalised |
|
| Everything else | camelCase |
|
A keyword has its meaning only where a statement starts. Everywhere else it is an ordinary word, so every keyword works as a map key ({ action: "approve", type: "a" }), a field name and an enum case.
A name the language already gives a meaning cannot be a program's own: the words a statement is written with (state, action, let, if, show, match, style, on, and the rest), the built-in functions, and the values env, params, locale, dir, now, viewport, query, hash, theme, network and update. Declared as a state, a prop, a parameter, a loop item, a lambda's parameter or a const, one is an E118. The names a handler brings (event, e, value, key) and the browser's globals are yours to use. A program's own names may be written in any script, Arabic included.
Keywords
Each keyword, and where it starts a statement:
| Keyword | Where | Starts |
|---|---|---|
|
|
top of a file | a declaration |
|
|
an |
an endpoint |
|
|
an |
what every request passes through; what a group's writes make stale; how its reads page |
|
|
after an error enum's case |
the status the case stands for: |
|
|
render block, store | a value that can change |
|
|
page, component, store | a value kept across visits |
|
|
render block, store | a value worked out from others |
|
|
render block, store | code that runs when what it reads changes, and its clean-up |
|
|
render block, store | a named imperative block |
|
|
render block | access to a store |
|
|
render block, store | a request whose state the page shows |
|
|
render block | the rules a state must pass |
|
|
render block, store | a connection the scope holds open |
|
|
render block | a repeating or a one-off timer |
|
|
top of a page, a component or |
a listener on the document or the window |
|
|
page | tags for the document's head |
|
|
render or imperative block | a branch |
|
|
render or imperative block |
a loop; |
|
|
render block | a block hidden, not removed, when its condition fails |
|
|
render or imperative block, or a value |
one arm, by a read's case, an enum's case or a result's |
|
|
render block | a timed group of enter animations |
|
|
component, before its elements | a slot, an event it fires, a part |
|
|
component | where the caller's block goes |
|
|
element block | styles, transitions, handlers |
|
|
imperative block | a local, and leaving with a value |
|
|
imperative block | catching what a script throws |
|
|
a value, in an imperative block | a result's value, or its error passed up from the action |
|
|
imperative block, or a value | waiting for a promise |
|
|
imperative block of a component | firing one of its events |
|
|
test | a step a test checks or performs |
Declarations
These forms are written at the top of a file, and nowhere else:
page Name(path: "/", title: …, description: …, image: …, image_alt: …, type: …,
noindex: …, lang: "…", translates: Page, layout: Component(…),
guard: expr, redirect: "/…", paths: expr, param: Type, …) { render block }
component Name(_ positional: Type, prop: Type = default, …) { component body }
store Name(scope: .app | .session | .route, eager: Bool) { store body }
app { render block }
theme Name { token: value … }
type Name { field: Type = default, … } type Name = Other { … } type Name = Type
enum Name { case, case(part: Type, …), … }
enum NameError { case(problem: Type) on 404, case(problem: Type?) on 4XX, http(error: HttpError) }
api Name(base: expr, …) { settings middleware [ … ] endpoints invalidations { … } pagination { … } }
api Name.group { endpoints }
api Name from "spec.json" (base: expr)
middleware name(req, next) { action body }
fake Name for Service.group { endpoint(params) { result } … }
fake Name for Service.group from examples { endpoint(params) { result } … }
const NAME: Type = expr
data name: Type = "file.json"
image name = "picture.jpg"
animation Name { from { css } 50% { css } to { css } }
test "name"(data: { … }, fakes: [Fake, …]) { render block and test steps }
example Component "what it shows"(fakes: [Fake, …]) { render block }
An error enum is an enum whose cases name statuses with on: one status (on 422) or a class (on 4XX, every status of it no other case names), and exactly one http(error: HttpError) case for the rest (N12).
A /// comment before a declaration, a prop, a field, an event, an endpoint, or a state, persist, derived or action of a page, a component or a store is its documentation.
A store's body holds state, persist, derived, effect, action, resource and the connections (socket, stream, channel, peer, worker).
Types
A type is written wherever a : Type or a -> Type goes:
| Type | Written |
|---|---|
| A built-in |
|
| A declared one |
|
| A list |
|
| A dictionary |
|
| May be null |
|
| A function |
|
| A result |
|
| Nothing, but it may fail |
|
| A refined type |
|
type Name = Type gives a type another name. Any and Map are not types (T23, T24): JSON whose shape is open is Json.
Services
An api body holds settings, middleware, endpoints, and the invalidations { } and pagination { } of its groups. A group, api Name.group { }, holds endpoints only; it sends what its service sends.
api Name(base: expr) {
timeout: 10.seconds retry: .backoff(…) credentials: .sameOrigin
middleware [requestId, bearer(Session.token), timed]
get name(param: Type = default, other: Type? in header "X-Name" | in query "q" | in cookie) at "path/{param}" -> Type!
pages .number(param: page) | .cursor(param: after, next: p => …, items: p => …) | .link
get name(…) at "…" -> [Type]! streamed
post name(body: Type) at "…" -> Type ! NameError
idempotent
invalidates [read, read(param)]
delete name(id: String) at "…/{id}" -> !
invalidations { group.write(id) invalidates [group.read, group.byId(id)] }
pagination { group.read pages .cursor(…) }
}
Every endpoint has at "path", every {name} in it is one of its parameters (N01), and its answer is -> T!, -> T ! E, -> ! or -> ! E. An endpoint may also say cache: and as: after its answer.
Render blocks
A page, a component, the app, a test and every element's children hold these statements:
| Statement | Form |
|---|---|
| state |
|
| persisted state |
|
| derived |
|
| effect |
|
| action |
|
| store |
|
| resource |
|
| validation |
|
| connection |
|
| timer |
|
| key |
|
| page event |
|
| head |
|
| conditional |
|
| loop |
|
| visibility |
|
| choice |
|
| orchestration |
|
| set-up |
|
| element |
|
| slot use |
|
A connection's options may also be written inside its block, one name: value to a line.
Component bodies
A component's body is a render block, and before its elements it may declare:
slot the default slot, placed with `children`
slot name a named slot
slot name(value: Type, …) a scoped slot
event name(param: Type, …) an event it fires with `emit`
part Name(props) { render block } a part, called as `Component.Name`
Element blocks
An element's block holds these, in this order, each optional:
Name(…).flags {
style { declarations }
transition { property: duration easing … }
on event(e) { imperative } `on input(debounce: 300.ms)`, `on scroll(e, throttle: 100.ms)`
slotName(params) { render block } a slot fill, on a component call
children
}
Imperative blocks
Actions, handlers, effects, timers and hooks hold these statements:
| Statement | Form |
|---|---|
| assignment |
|
| local |
|
| call |
|
| emit |
|
| return |
|
| conditional |
|
| choice |
|
| loop |
|
| error handling |
|
| a result's value |
|
| waiting |
|
A pattern in a match arm or an if let is a case (.ok(v)), a case inside a case (.err(.http(.status(503, _)))), _, or a literal.
let, return and emit written in a render block are an error that says to move them into a handler, an action or an effect.
Style blocks and themes
A style block holds CSS declarations, one to a line:
style {
property: raw css value to the end of the line, a `;`, or two spaces and the next declaration
property: {expr}px $token a live value, a design token
--custom-property: value
&:hover { declarations } nested rules, as CSS nesting writes them
@media (…) { declarations } and `@md { }` for a breakpoint, `@container (…) { }`
}
A theme's body is the same declarations, without nesting.
Test steps
A test holds render statements and these steps, run in the order written:
| Step | Form |
|---|---|
| check |
|
| focus |
|
| requests |
|
| click |
|
| type |
|
| key |
|
test "name"(fakes: [Fake]) answers the endpoints of a fake's group in place of the network; data: { … } seeds the body's state.
example Component "what it shows" { … } is one way to use a component, drawn by wf docs: a render block with no steps, checked as a page's body and left out of every build.
Expressions
The operators, from weakest to strongest binding:
| Level | Operators |
|---|---|
| 1 |
|
| 2 |
|
| 3 |
|
| 4 |
|
| 5 |
|
| 6 |
|
| 7 |
|
| 8 |
|
| 9 |
unary |
| 10 |
calls |
So 1..n + 1 is 1..(n + 1), and a ?? b || c is a ?? (b || c). Operators of one level group from the left: a - b - c is (a - b) - c.
These forms are expressions too:
if c { a } else { b }, which isnullwhen there is noelseandcfails;if let x = v { a } else { b };match v { .case { a } else { b } };- lambdas
x => expr,(a, b) => exprand() => expr; - spreads
...xin a list, a map or a call's arguments.
A call's named arguments (due.plus(days: 3)) are gathered into one map, passed last. Expressions explains each form.
Literals
| Kind | Written |
|---|---|
| String |
|
| Number |
|
| Bool, null |
|
| List, map |
|
| Regex |
|
| Date, time |
|
| Duration |
|
| Money |
|
| Colour |
|
| Enum case |
|
| Design token |
|
Comments
// to the end of the line, /* across lines */, and /// documentation.
Layout
A .wf file writes blocks in braces. A .wfx file writes them by indentation: a line indented deeper than the one before opens a block, and a dedent closes it. Braces written by hand still work inside a line (Language basics). Statements need no separator, on one line either: the parser finds where one ends. Two on one line read best apart by a ; or two spaces (count = 0; log(count)).