Grammar
This grammar is the one recognized by the parser in compiler/syntax/. It covers without error the 7 example files and the 33 code blocks of SPEC.md. The choices that resolve an ambiguity are listed below, followed by the decisions made during the first review.
Lexicon
Section titled “Lexicon”- Keywords.
fn val var type enum contract impl for while loop break continue return if else match is meta quote using ondispose defer errdefer arena unsafe async inout sink lazy fail catch true false import pub private where any shared yield subscript self Self inline actor await. - Contextual words. They are keywords only in their place, and names elsewhere:
inafter the pattern of afor(fn anonymous(in: Path)remains allowed),stepafter a range,testbefore a string at the start of a declaration, or aftermeta,poolbeforename =,taskbeforeval,threadbeforevar,onbefore a name at the start of a statement,detachbefore a name,asafter an imported name. - Keywords as names. After
.,?.,::orfn, and before:in an argument or a field, a keyword is a name:f.type,File.anonymous(in: dir),fn any(…). - Literals. Integers (
10_000,0xC2,0o644,0b1010), floats (0.25), strings with${…}, prefixed strings (sql"…"), whose text is raw:\keeps the character that follows it,regex"\d+", and$${writes a${; blocks over several lines,"""orsql"""ending their line and closed by"""alone on its own, whose indentation every line loses; byte stringsb"GET\r\n", where\xffwrites any byte; characters ('\n','\u{85}'), bytes (b'\n'). - Labels.
'lines, told apart from a character because it is not closed by'. - Tags. Text between backticks, then parsed as a sequence of
namespace(arguments). - Comments.
//to the end of the line;///for documentation. - Ellipsis.
...and…are accepted where the spec leaves an element blank.
Layout
Section titled “Layout”| Rule | Example |
|---|---|
| A line end terminates the statement | val a = 1 |
Between ( ) and [ ], line ends do not count; between { } they count, even inside a parenthesis |
arguments over several lines |
A line that starts with ., |>, &&, ||, ??, else, catch, ondispose or | (enum variant) continues the previous one |
.then(…), catch e => … |
After a binary operator, =, => or ,, the next line continues |
fn f(): T = then the body |
+ and - at the start of a line open a new statement |
-x |
; separates two statements on the same line |
{ a; b } |
| A brace glued to a name opens a record; preceded by a space, never | Pos{x: 0} versus if ok { |
x!=y reads x != y: propagation followed by a comparison is written x! == y |
Grammar
Section titled “Grammar”Fields, arguments and elements are separated by ,; in a block, a record or a match, a line end acts as a separator.
module = { item }item = { attr } { "pub" | "private" | "inline" | "async" | "meta" | "sync" | "local" | "arena" | "packed" } decl | binding (* keywords only before `type`: `sync`, a shared object, 8.3; `local`, a type whose values hold borrows; `arena`, an arena object (memory-model.md); `packed`, a bit field, 2; `@removable arena type`: an arena object that removes nodes *)attr = "@" Ident [ args ]decl = fn | type_decl | enum | contract | impl | import | test | extern | meta_itemsmeta_items = "meta" "if" cond "{" { item } "}" [ "else" ( meta_items | "{" { item } "}" ) ] (* at module level: the declarations of the chosen branch *)test = [ "meta" ] "test" Str block (* `meta test`: run at compile time *)extern = "extern" Str fn (* `extern "C" fn f(…): T`, without a body *)
fn = "fn" ( Ident | "${" stmts "}" ) [ generics ] params [ ret ] [ "where" bounds ] [ "=" expr | block ] (* `fn ${name}(…)` in a quote *)ret = ":" [ "yield" ] type [ "from" place , … ] | "!" [ union ] (* `: yield V from table`: a result lent, as long as table lives (memory-model.md) *)place = ( Ident | "self" ) { "." Ident }param = [ "mut" | "sink" | "lazy" | "using" | "meta" ] ( Ident | "self" ) [ ":" type ] [ "=" expr ] (* `xs: mut T`, `mut self`, a lambda's `mut st`: modified, never replaced *)type_decl = ( "type" | "actor" ) decl_name [ generics ] [ ":" type ] [ "where" bounds ] [ "=" type ] (* `: UInt16`: the integer of a `packed type`; `actor A = { … }`: an actor, 8.3 *)enum = "enum" decl_name [ generics ] [ "where" bounds ] "=" ( [ "|" ] variant { "|" variant } | Ident args | "${" stmts "}" ) (* `enum Few = Pick(Shape, ["Circle"])`: a computed enum; `enum ${name} = ${t}` in a quote: the variants of an enum the meta code built *)variant = Ident [ "(" [ Ident ":" ] type , … ")" ] { Tag }contract = "contract" decl_name [ generics ] ( "=" bound | [ ":" bound ] "{" { member } "}" ) (* `= A & B`: an alias; `: A`: an extended contract *)decl_name = Ident | "${" stmts "}" (* `type ${name} = …` in a quote: the name the meta code gives *)generics = "<" Ident [ ":" bound ] [ "=" type ] , … ">" (* `<E = Never>`: the value of an omitted argument, in a contract only *)bounds = Ident ":" bound , …bound = path [ "<" type , … ">" ] { "&" path [ "<" type , … ">" ] } (* Eq & Index<Int, T> *)impl = "impl" [ generics ] union [ "for" union ] [ "where" bounds ] "{" { member } "}" (* without `for`: the type's functions *)member = { attr } { "pub" | "private" | "inline" | "async" | "meta" } fn | "subscript" params ":" type block (* `pub fn`: visible outside the package; `private fn`: to the file alone *)import = "import" Ident { "." Ident } ( [ "as" Ident ] | "." "{" Ident [ "as" Ident ] , … "}" ) (* `pub import m.{A, B}`: names the module also presents; `@cimport("zlib.h", link: "z") import zlib`: a C header, under a name *)
type = union [ "!" [ union ] ]union = opt_type { "|" opt_type }opt_type = prim_type { "?" | "[" "]" | "[" expr "]" } (* Int?[]: array of optionals; UInt8[16], UInt8[2 * Size]: fixed size, computed at compile time *)prim_type = path [ "<" type , … ">" ] (* Map<K, V> *) | Ident args (* MapFields(Counts, Bool) *) | "(" [ [ Ident ":" ] type , … ] ")" [ "=>" type ] (* `(T)` groups: `(File ! IoError)[]` *) | "{" { [ "pub" ] [ "borrow" ] Ident ":" type [ "=" expr ] { Tag } | ".." } "}" (* `pub x`: a field visible outside the package; `= expr`: its default value; `borrow x`: a field of a `local type` *) | ( "mut" | "shared" [ "mut" ] ) opt_type (* qualifiers, of the type that follows, its suffixes included *) | "ref" prim_type (* `ref Node`, a node of an arena object; `ref Node[]`, an array of them *) | Str | [ "-" ] Int | Char | "true" | "false" (* a literal type, member of a union: "asc" | "desc", -1 | 0 | 1 *) | "any" ( opt_type | "(" bound ")" ) | "Self" | "${" stmts "}" (* `mut T`: also a parameter of a function type, `(mut T) => R`, and the place a subscript lends, `: mut V` *)
stmt = [ Label ":" ] ( for | while | loop ) | binding | "defer" expr | "errdefer" expr | "yield" expr | "meta" ( "val" … | meta_if | "for" … | fn ) | decl (* `pub meta val`, at module level: a presented constant *) | "on" cond block (* the pool of the tasks launched in the block *) | expr [ ( "=" | "+=" | "-=" | "*=" | "/=" | "%=" ) expr ]meta_if = "meta" "if" cond block [ "else" ( meta_if | block ) ]binding = "val" ( pattern | "${" stmts "}" ) [ ":" type ] [ "=" expr ] [ "else" block ] (* `val ${name} = …` in a quote: the name the meta code splices; at module level, `pub` allowed: a constant, a single name *) | "var" ( Ident | "(" pattern , … ")" ) [ ":" type ] [ "=" expr ] (* `var (a, b) = pair()` *) | "using" ( Ident | "(" pattern , … ")" ) [ ":" type ] "=" expr [ "ondispose" expr ] (* `using (a, b) = …`: each resource received, without `ondispose` *) | "pool" Ident "=" expr (* at module level, `pub` allowed *) | "task" "val" Ident [ ":" type ] [ "=" expr ] | "thread" "var" Ident [ ":" type ] [ "=" expr ]for = "for" pattern "in" cond block (* `for mut x in xs`: the pattern `mut x` designates each element in place *)while = "while" cond block
expr = lambda | catchlambda = [ "[" capture , … "]" ] ( Ident | params ) "=>" ( expr_or_assign | block )capture = ( "mut" | "var" | "take" ) Ident (* `[mut names]`: modifies its content; `[var total]`: the variable itself; `[take file]`: gives it up to the lambda *)catch = pipe { "catch" ( "{" { arm } "}" | arm ) { "!" } }pipe = coalesce { "|>" coalesce }coalesce = or [ "??" coalesce ]or = and { "||" and }and = cmp { "&&" cmp }cmp = range [ ( "==" | "!=" | "<" | "<=" | ">" | ">=" ) range | "is" pattern ]range = [ shift ] ( ".." | "..=" ) [ shift ] [ "step" shift ] | shiftshift = add { ( "<<" | ">>" ) add }add = mul { ( "+" | "-" ) mul }mul = unary { ( "*" | "/" | "%" ) unary }unary = ( "!" | "-" | "&" | "mut" ) unary | postfix (* `mut [1, 2]`: a value whose content is modifiable *)postfix = primary { args | "." name | "." Int | ".await" | ".${" stmts "}" | "?." name | "::" name | "[" expr "]" | "!" | "<" type , … ">" (* after a path or a `.name`, if followed by ( or .: `xs.map<String>(f)`, `json.decode<User>(body)` *) | record } (* brace glued to the path *)args = "(" [ [ name ":" ] ( expr | "?" ) , … ] ")"primary = literal | Ident | "self" | "Self" | "." name | "::" name | "(" [ [ name ":" ] expr , … ] ")" | "[" expr , … "]" | "[" expr ":" expr , … "]" | "[" ":" "]" | block | "if" cond block [ "else" ( if | block ) ] | "match" cond "{" { arm } "}" | "loop" block | "return" [ expr ] | "break" [ Label ] [ expr ] | "continue" [ Label ] | "fail" expr | "await" postfix | "detach" postfix (* `await f(x)` is `f(x).await`; the postfix stops before a `!`, `await f(x)!` being `(await f(x))!` *) | "any" args (* `any(a, b)` from weaver.task, which `any` before a contract does not read *) | "quote" block | "${" stmts "}" | "lazy" block | "arena" block | "unsafe" blockrecord = "{" { name [ ":" expr ] | ".." expr } "}"arm = pattern [ "if" pipe ] "=>" expr_or_assign
pattern = pattern1 { "|" pattern1 }pattern1 = "_" | "mut" Ident | "using" Ident | Ident | "${" stmts "}" | path [ "(" [ name ":" ] pattern , … ")" ] | path "{" ( name [ ":" pattern ] | ".." ) , … "}" (* record pattern; the brace is glued to the name *) | "(" pattern , … ")" | "." name | literal [ ( ".." | "..=" ) literal ] | "in" range (* `in 'a'..='z'`, `in vowels`: r.contains(x) *)cond is an expression where { preceded by a space opens the block that follows and cannot end a range (match s[n..] {).
Precedence
Section titled “Precedence”From weakest to strongest: lambda, catch, |>, ?? (right-associative), ||, &&, comparison and is (non-associative), range, shift, + -, * / %, prefixes ! - &, suffixes (call, member, ?., ::, index, !).
Choices made by the parser
Section titled “Choices made by the parser”- Type arguments in an expression.
Json.decode<User>(body):<…>is kept only if it reads as a list of types followed by(,.or[]. Otherwise<is a comparison (i < line.len()). T[]in an expression.Key[], followed by(or., is the typeArray<Key>:Key[](capacity: 8),Int[].filled(3, with: 0). Empty brackets cannot be an index.Int?[]is likewise an array of optionals,Int?[].filled(3, with: None):?alone does not exist in an expression, so?[]cannot be anything else.UInt8[16], for its part, reads as an index: the checker makes it the typeUInt8[16]when its head names a type, and not a variable or a constant,UInt8[16].filled(with: 0).>>. In a list of types,>>closes two lists:Deque<Task<File>>().- Body of a lambda or an arm. It is in statement position, so an assignment is allowed there:
'f' => opts.fold = true,hits.write(h => h[path] = 1). !followed by{. It is the function body, never a record type:fn f(): T ! {declares an inferred error.- Line that starts with
.. It continues the previous expression, as in Swift. After a loop or a declaration, which are not expressions,.equalopens a new statement; likewise a line that has its=>outside any parenthesis, the.no => …arm of amatch. - Exits.
fail,return,breakandcontinueare expressions (of typeNever):v ?? fail Usage(s),_ => return false. - Messages for removed forms.
x?,_.name,Name {…}with a space, the trailing closuref { … }andusing … elseeach produce a message that gives the current form. inin a pattern. It is a contextual word: at the start of a pattern and followed by an expression, it tests membership,in 1..10 => …; followed by=>,,,),|,{,=or a line end, it is a bound name,in => ….enum X = F(…). The parser first reads variants, andTags(Shape)is one, which the checker reads as the call of the meta fnTagswhen it exists. What does not read as variants,Pick(Shape, ["Circle"]), is the call.
Review decisions
Section titled “Review decisions”| Question | Decision | Spec |
|---|---|---|
? propagated errors and ?. chained optionals |
x! propagates the error out of the function; x?.y chains without leaving the expression; ? alone does not exist. The operators echo the types: T? and ?, T ! E and ! |
2, 8.1 |
| Four ways to write a closure, one of them ambiguous with records | A single form, parameters => body, passed inside the parentheses; no more trailing closure f { … } |
3.1 |
The implicit parameter _ |
Removed from expressions; replaced by the references ::isBlank, Char::isAsciiDigit and the partial call compare(?, ?), whose hole belongs to the call that directly contains it |
3.1 |
{ x } after a name: record or closure, decided by case |
Glued brace, as in Go: Config{cache} is a record. Case has no syntactic role, and a record becomes possible in a condition |
2 |
| Lone name in a named tuple | A tuple is either positional or named; as soon as one element has a name, a lone name means name: name |
2 |
${…} in a string inside a quote |
The string belongs to the generated code; a meta value is prepared outside the quote |
5.5 |
\d in regex"\d+" |
The text of a prefixed literal is raw: its meta fn receives the backslashes; b"…", part of the language, keeps the escapes |
5.4 |
using … catch versus using … else |
ondispose e => … for the closing error; catch and ondispose can open a line |
7.3 |
| What is visible without an import | The language’s types and their methods; every function is imported, print included (import weaver.io.print), as are the library’s collections (import weaver.collections.Map) |
9 |
Declaration of File.open(p), Counts.default() |
impl File { fn open(path: Path): ReadFile ! IoError }: without self, an associated function, File.open(p); with self, a method, f.read(…). A type’s functions come with it |
4 |
| Value returned by the last expression of a body | A block body returns with return; fn f(): T = expr remains the concise form; if, match and blocks keep their value |
3.1 |