Reference
Narra specification
Narra specification
This document defines the Narra language. Each section states the rules first, then shows an example. DECISIONS.md explains why each rule was chosen over the alternatives.
File extension: .nra. Compiler command: narrac.
Code samples leave out the imports of Array, Map, Range and Box functions (section 3): a sample that calls Arrays.push assumes import * as Arrays from "std/array".
1. Overview
- Narra uses TypeScript-style syntax with Rust-style semantics: static types, enums with fields, pattern matching, and no
null. - Narra compiles to native code, the same target as C, Rust and Go. The compiler emits C, and a C compiler builds the final binary.
- Narra code is a set of modules. One file is one module. There are no globals.
- Every name holds its own value: a change through one name never shows through another. Safe code has no pointers or references, only values.
- A function changes a caller's data only through a
mutableparameter, marked at the call:damage(mutable hero, 10). It changes the contents (fields and elements), never the caller's variable itself. - The compiler frees memory with reference counting that it inserts itself. There is no garbage collector.
- When a value has exactly one owner, an update writes to it in place instead of copying it.
import * as Float from "std/float"
export enum Shape {
Circle(radius: f64)
Rect(width: f64, height: f64)
}
export function area(s: Shape): f64 {
return match (s) {
Shape.Circle(r) => Float.PI * r * r
Shape.Rect(w, h) => w * h
}
}
test "rect area" {
assert(area(Shape.Rect(2.0, 3.0)) == 6.0)
}
2. Syntax
The syntax follows TypeScript where the meaning is the same. Where Narra means something different, it uses different syntax or reports a compile error. The table under "Differences from TypeScript" lists those cases. One difference has no diagnostic: assignment copies a value, so after const b = a, a change to a does not show in b (D81).
Statements and layout
-
Blocks use
{ }. -
No semicolons. A line break ends a statement when the line could end there. A line that ends with an operator,
,,(,[or{continues on the next line. A;is a compile error, except between the parentheses of afor (init; condition; step)loop (section 2, Control flow). -
narrac fmtdefines the one valid layout. CI is expected to runnarrac fmt --check. -
narrac fmtreads a[fmt]table ofnarra.toml(the nearest one above the file). Keys, with their defaults:printWidth = 100: the line width.tabWidth = 2: spaces per indent level.useTabs = false: indent with tabs.trailingComma = "all": a trailing comma in broken lists, or"none".
There are no other options.
-
Comments:
//to the end of the line,/* ... */for blocks,///before a declaration for documentation. -
A source line number or column at or past 1048576 (2^20) is a compile error (E1004).
Bindings
const x = exprbinds a name that cannot be reassigned.constfixes the name, not the contents (D81): the fields and elements of a localconststruct, array, map or other contents type (section 6, Mutable parameters) can be assigned, and theconstcan be passed asmutable.let x = exprbinds a name that can also be reassigned withx = expr. A closure passed straight to a non-escaping function parameter can capture it, by reference (section 2, Closures).- Every binding holds its own value.
const other = herocopieshero, so a later change to either one does not show in the other. The one exception is afor (mutable item of items)binding, which reaches an element ofitems(section 2, Control flow). - A plain parameter is read-only. Its fields and elements cannot be assigned, and it cannot be passed as
mutable(section 6). - Bindings that copy part of another value are read-only. A
matchorispattern binding (x is Some(v)), afor (const p of players)binding and a destructured binding (const { a, b } = s) hold a copy, so their fields and elements cannot be assigned and they cannot be passed asmutable.for (const p of players) { p.hp = 0 }is a compile error: writefor (mutable p of players)(section 2, Control flow), write through the array,players[index].hp = 0, or make a copy first withcopy(p)(D81, D94). Amutablemarker exists only in that loop (D85);x is Some(mutable y),const { mutable a } = sand a localmutable name = placedo not. - Top-level constants never change (D81). A top-level
constcannot be changed at any depth (section 10). - There are no globals. Assigning to an undeclared name is a compile error.
- Compound assignment (D76).
x += eand the forms-=*=/=%=&=|=^=<<=>>=meanx = x op ewith the target place evaluated once:items[next()] += 1callsnextonce. They are statements with no value, valid on every target=accepts (alet, a field or element of a changeable value, the contents of amutableparameter).x++andx--are statements for an integer of any width; the prefix++xis a compile error (E0964). The value must have the type of the target (E0962), and++on a non-integer is E0963. Wrapping, divisor proofs and shift count proofs are those of the binary operator:x /= dneeds a provend. The wrapping operators+%=,-%=and*%=do not exist. On astringtarget only+=exists and it joins strings (+alone is still an error). A Map index target (counts[key] += 1) is a compile error, since a missing key has no old value (readingcounts[key]gives anOption); writeMaps.update(mutable counts, key, 0, (count) => count + 1), which starts from the initial value when the key is missing (D92). - No shadowing inside a function. A name cannot be declared again while an earlier binding with that name is in scope.
- Unused names are errors. An unused local, parameter, import or private function is a compile error. Name it
_or start it with_to mark it as unused on purpose. - A
letthat is never reassigned is an error. Aletdeclared with a plain name that nothing writes after its declaration is a compile error (E1510); declare it withconst. A write isx = e, a compound assignment,x++, a write through a field or element (x.f = e,x[i] = e), passingmutable xand a closure that does any of these. The fix rewriteslettoconst. Aletthat is also never read is reported as unused instead. - Unreachable statements are errors. A statement that follows
return,break,continue, a call topanicorProcess.exit, anifwith anelsewhose branches all leave, amatchwhose arms all leave, or awhile (true)loop with nobreakis a compile error (E1500). Only the first dead statement is reported. - Destructuring:
const { host, port: serverPort } = configfor structs (section 4), andconst #[quotient, remainder] = Int.divmod(a, b)for tuples. - Array destructuring (D103). A destructuring must match every value, so on an
Array<T>onlyconst [...rest] = itemsworks: it binds a new Array with every element, a copy.const [a, b] = itemsandfor (const [a, b] of rows)over an Array are compile errors (E0715), since the length is not known; test it withmatchoris(section 4, Pattern matching). On aFixedArray<T, N>with a knownN, a pattern of exactlyNelements, or..._after at mostNelements, works inconst,let,for ... ofand nested in tuple and struct patterns:const [x, y, z] = point. Another length is E0723. In a generic body whereNis a constant parameter, only[..._]matches every value (E0723).
Functions
function name(a: int, b: int): int { ... }declares a function. A function is private to its module unless declared withexport function(section 3). A function cannot be declared inside another function (E0930): declare it at module level as a private function and pass the enclosing values as arguments. A nested declaration in TypeScript captures the enclosing locals, and a module-level copy could read a different name where a local shadows it (D74). To keep a helper that captures, bind an arrow function to aconst.- A function with no return type returns nothing.
- A function with a result must return on every path. A path ends at
return, a call topanicorProcess.exit, anif/elsewhose branches all end, amatchwhose arms all end, orwhile (true)/for (;;)with nobreakout of it. Any other path that reaches the closing brace is a compile error that names the path (E0969, E0970 for an arrow function with a block body). Generators have no result value and are exempt (D92). - Anonymous functions are arrow functions:
(x: int): int => x + 1, or(x: int): int => { ... }with a block.functionis only used for named declarations. function*declares a generator andasync functiondeclares an async function (section 8). Arrow functions can beasync:async () => { ... }, andasync { ... }is an async block.- An arrow function passed as an argument takes its types from the parameter it is passed to. The types can be left out:
Arrays.map(prices, (p) => p * 2). - Function types are written like arrow functions:
(item: T) => U. - Standard functions are values when their signature is fixed:
Int.toString,Str.lengthandFs.readTextcan be passed, stored and returned, andimport { toString } from "std/int"names one directly. Its effects follow it:Fs.readTexthasalloc, io, so a function type that takes it lists both. A standard function whose types depend on the call (Arrays.length,Maps.size), one with amutableparameter and one that takes a function (Arrays.map) are not values (E1013); write an arrow function,(items) => Arrays.length(items). - Parameters are constant. A parameter cannot be reassigned, and its contents cannot be changed unless it is declared
mutable(section 6). Amutableparameter still cannot be reassigned. - A call passes every argument that has no default. Passing fewer arguments, or more than the function declares, is a compile error.
- Arguments are evaluated left to right, in the order they are written. An argument that is a block expression, a
matchor a closure call can assign aletthat an earlier argument reads; the earlier argument keeps the value it had when it was evaluated. Aftershow(items, { items = ["z"]; return 0 }),showreceived the originalitems. - Named arguments. A call can name its arguments, written like struct literal fields:
move(x: 1, y: 2). Positional arguments come first, then named ones in any order:move(1, z: 3, y: 2). A positional argument after a named one is an error. Each parameter is passed exactly once, by position or by name.mutablefollows the colon:fill(buffer: mutable items, value: 0). Names work when the callee is a declared function or a trait function. A function value, an enum constructor, and a std function built into the compiler such asStr.slicetake positions only (D87). The arguments are evaluated in the order they are written and passed in the order of the parameters. A parameter's name is part of the function's interface: renaming it breaks the calls that use the name. - No currying and no partial application. To fix some arguments, write an arrow function.
- No method calls.
xs.push(v)is not valid. WriteArrays.push(mutable xs, v).value.field(args)is only valid whenfieldis a struct field that holds a function. - Parameter defaults (D115). A parameter of a declared function can have a default after
=:function render(node: Node, depth: int = 0, indent: string = " "). A call may leave it out:render(tree),render(tree, 2), orrender(tree, indent: "\t"), which names a later parameter to skipdepth.- Defaults are trailing: once a parameter has one, every later parameter has one (E1210).
- A default is a compile-time constant, by the rule of a struct field default (section 4): a literal, a unary operator on a constant, a constructor with constant arguments, or an array of constants (E1212). It cannot read another parameter, a local, a top-level constant or a function, and cannot call an
@constfunction. - A
mutableparameter has no default (E1211). Arrow function parameters and function types have none (E1213), nor have trait functions and theirimplementblocks (E1214) or the functions of anexternblock (E1215).name?: Tis a compile error (E1216); writename: Option<T> = None. - The compiler fills each left-out default into the call, in parameter order, after named arguments are matched, so the function is still one C function with a fixed parameter list. The default is built at each call that leaves it out. A call that leaves out an array default has the
alloceffect; no other default has an effect. Arequirespattern on the parameter is checked against the filled value. - A default whose type uses a type parameter must type-check for every type argument, as for a generic struct field (
fallback: Option<T> = None). A left-out argument gives no evidence for inference. - A function value takes every argument. The type of
renderas a value is(node: Node, depth: int, indent: string) => string, with no defaults, and a call through it passes all three. - A default is part of the function's interface, like a parameter name: changing it changes every call that leaves it out.
- No varargs. Pass an array.
- Tail calls to the same function are loops. A tail-position call from a function to itself compiles to a jump. The stack does not grow. This holds for every function. Other recursive calls use the stack, and stack overflow aborts the program.
- Recursion needs no keyword. The compiler finds recursive functions from the call graph of each module.
narrac query recursion MODULElists them.
function gcd(a: int, b: int): int {
if (b == 0) {
return a
}
return gcd(b, a % b) // tail call, compiled to a loop
}
Closures
- An arrow function that captures nothing compiles to a plain C function pointer.
- An arrow function that captures values stores them in an environment. Captured heap values have their reference count incremented, and captured structs are copied.
- A closure captures constants (
constbindings and non-mutable parameters) by value, except a localconstwhose contents it changes (next item). - A non-escaping closure captures
letvariables andmutableparameters by reference (D77). An arrow function written directly as the argument of a non-escaping function-type parameter may read and assign them, as in TypeScript:
let total = 0
each(numbers, (item) => { total = total + item })
Every let and mutable it uses is captured by reference, also when it only reads it. A local const whose fields or elements it assigns, or which it passes as mutable, directly or through a nested closure, is captured by reference too, by every closure between the change and the declaration, and is borrowed like a let it assigns (D81). A const that no closure in the chain changes stays a copy. A closure that is not of this kind cannot change a captured value. Every arrow function between the use and the declaration must be of this kind. A closure that is stored, returned, passed to an escaping parameter or through a function value, or that sits inside one of those, cannot capture a let or a mutable parameter (E0612, E0613).
- An escaping closure shares changing state through a
Cell(D90).const count = Cells.create(0)is captured by value like any constant, and every copy of the handle reads and writes the same slot:Cells.update(count, (value) => value + 1),Cells.get(count). Section 8 describesCell<T>. - A variable that such a closure assigns is borrowed for the call. In that call it cannot be passed as
mutable, read or assigned in another argument (includingitems.lengthorxs[0]), or captured by another closure argument (E0614). Two closures that only read the same variable are fine. A narrowing byisis not seen inside a closure that captures the variable, and a narrowing of a variable that a closure assigns ends at the statement of the call. - Function-type parameters cannot escape by default. Inside the called function, such a parameter can only be called. It cannot be stored, returned, captured by another closure, or sent to a thread.
- A non-escaping closure costs no allocation. Its environment is placed on the caller's stack, and nothing is reference counted or freed.
escapingmarks a function-type parameter that may be stored or outlive the call:function onClick(escaping handler: () => void). An escaping closure's environment is allocated on the heap.- Struct fields and array elements of function type always hold escaping closures.
Thread.startandAsync.thentake escaping parameters. Anasyncarrow function or block captures like an escaping closure wherever it is written (section 8).
Control flow
if (cond) { ... } else if (cond) { ... } else { ... }. The condition must have typebool. There is no truthiness:None,0and""are not conditions.while (cond) { ... }.for (const item of source) { ... }loops over an array, aRange, a generator, or the result ofMaps.keys,Maps.entriesorStr.chars(each an array).for (const #[i, item] of Arrays.entries(items))gives indexes from 0.for (mutable item of items)changes the elements in place (D85).itemreaches each element of the array, as amutableparameter would, soitem.hp = 0changesitems.for (const #[index, mutable item] of Arrays.entries(items))also gives the index, andArrays.values(items)may be written foritems.- The source is a local place of type
Array<T>: a localconstorlet, amutableparameter, or a field or element path of one. A call result, a plain parameter, a top-level constant, a map, a range and a generator are compile errors. Thas contents (section 6, Mutable parameters):for (mutable n of numbers)overArray<int>is a compile error; writenumbers[index] = ...in anArrays.entriesloop.- The binding follows the rules of a
mutableparameter: its fields and elements can be assigned and it can be passed asmutable, but it cannot be assigned whole or escape. - The source is borrowed for the whole body: the body cannot read, assign, pass or capture the source or any path that overlaps it (
players,players[0], andgamefor a sourcegame.players;game.roundis fine). - The array is made unique before the first iteration (a shared array is copied once), and the loop takes no reference to it.
- Not allowed in a
function*orasyncbody yet.
- The source is a local place of type
for (mutable player of players) {
player.hp = 0 // changes players
}
- What a loop reads.
for ... ofreads anArray<T>(each element), aRange(each number), or aGenerator<T>(each value it yields).Maps.keys,Maps.entriesandStr.charsreturn arrays, and aRangeis its own type, so none of them is aGenerator<T>: a parameter of typeGenerator<int>does not take an array or aRange, and a function that wants one writes afunction*that yields the items.Arrays.valuesandArrays.entriesare allowed only at the head of a loop (E0920), where they stand for the array itself. A generator (section 8) is an iterator you write: a function returns its own by returning a generator, andfor ... ofiterates over its own copy of it, so a generator held in a variable is not advanced. for await (const chunk of stream) { ... }reads anAsyncGenerator<T>in an async body, waiting for each value (section 8, Async generators).- Counting loops use
Range.Ranges.upTo(n)counts from 0 ton - 1.Ranges.between(start, end)counts fromstarttoend - 1.Ranges.stepped(start, end, step)takes a step: a positive step counts up while the value is belowend, a negative step counts down while it is aboveend, and a step of 0 gives an empty range. A step that is 0 at compile time (a literal, or a constant that folds to 0) is error E1270, since the range could never have a value.Ranges.steppedreturns aRange, so it never panics. The loop stops before the value would pass the largest or smallestint.
for (const i of Ranges.upTo(Arrays.length(items))) {
print(items[i])
}
breakandcontinuework as in TypeScript, including labels:outer: for (...) { ... break outer }.- C-style
for.for (init; condition; step) { ... }has TypeScript's meaning, andfor (;;)loops forever (D76).
for (let i = 0; i < limit; i = i + 1) {
total = total + i
}
initis aletdeclaration or empty. Its name is scoped to the loop.constis error E0960, because the step could not change it.conditionhas typebool, with no truthiness (error E0959), or is empty.stepis an assignment, a call or empty (error E0961 for anything else).continueruns the step, then the condition. Labels work as for the other loops.- The semicolons belong to the parentheses. A
;anywhere else is still an error. - The loop is a statement, not a value.
- There is no
do ... while, noswitchand nogoto. matchreplacesswitch(section 4).
Block expressions and if as a value
A block has two forms, told apart by position (D75). A block in statement position is a block statement. A block in value position is a block expression: after =, as a call argument, as an operand, as a return value, inside ${...}, or as an element of an array, tuple or struct literal.
const label = {
const name = lookup(code)
if (name == "") {
return "unknown"
}
return name
}
- The value comes from
return. Narra never returns implicitly, so the last expression of a block is not its value. returnstops at the nearest block expression, as at a function body. Areturnanywhere inside it, also in nested block statements, loops andmatcharms, ends the block expression and not the function. A block expression cannot return from the enclosing function.breakandcontinuecannot leave a block expression. Abreakorcontinueto a loop outside it is a compile error (E0932). Loops inside the block work as usual.- Every path must end in
return value(E0931), and every returned value has the same type. A barereturnis an error. A block expression with noreturnat all, such asconst o = { a }, is a compile error (E0933) that points to struct literals. - A
{that starts{},{ ...s, f: v }or{ name: value }in value position is still a struct literal whose type comes from context. The exception is{ name: forand{ name: while, wherename:labels a loop and the{starts a block expression. if (c) { ... } else { ... }in value position is an expression whose branches are block expressions, each ending inreturn. Theelsebranch is required, andelse ifchains are allowed. At the start of a statementifis still a statement.cond ? a : bis a conditional expression, as in TypeScript.condmust bebool(no truthiness),aandbhave the same type, and only the chosen branch runs. It binds looser than||and is right-associative:a ? b : c ? d : eisa ? b : (c ? d : e). A missing:is E0934. The line rule above applies: a line that starts with?or:is a new statement, so a conditional expression that spans lines is wrapped in parentheses, where line breaks are ignored, and the Prettier layout works inside them:const v = (cond/? a/: b)on three lines. Without the parentheses the compiler reports E0934 and says to wrap it. A conditional expression is not a constant (a top-levelconstcannot use one), its value must be used (as a statement it is E0934; write anif), and both branches need a value. It is a block expression holding anifwhose branches eachreturnone value, so a self call in a returned branch (return n < 0 ? f(n + 1) : n) is still a tail call.
const sign = if (n < 0) { return "negative" } else if (n == 0) { return "zero" } else { return "positive" }
- A self call in a
returninside a block expression is not a tail call of the function.
Literals
- Strings use double quotes:
"text". They have no interpolation. - Template strings use backticks:
`Hello ${name}`. Each${...}must hold an expression of typestring. Template strings can span several lines. They take the same escapes as strings:\n,\t,\r,\0,\\,\",\',\`,\$and\u{<hex>}. Any other\Xis a compile error, reported at the backslash.\${is a literal${, not an interpolation. - Tagged templates (D114):
tag`a${x}b`is the calltag(["a", "b"], [x]). The parts array always has one more item than the values; an empty part is"". The tag is a name or a dotted name (tag,Sql.query) on the same line as the backtick; after),]or a literal a template is E1200, and so are type arguments on a tag (tag<int>`x`). A tag is a function or function value of two parameters, neithermutable(E1201): the parts,Array<string>with the escapes above orTemplate.Rawfromstd/templatewith the source text as written, and the values,Array<T>for one typeT. Each hole is checked withTas its expected type, and a hole of another type is E1202; a generic tag takesTfrom the holes. The tag's effects count at the use site, plusallocfor the two arrays. Raw parts decode no escape and report none:\dis the two characters\andd, and\`and\${keep their backslash. A template at the start of a line, after a line that ends with a name, is E1203: a newline ends the statement, so it is not tagged as it would be in TypeScript.Template.rawis TypeScript'sString.raw; it is@const, soconst DIGITS = Template.raw`\d+`is computed while compiling (section 10).
import * as Arrays from "std/array"
import * as Ranges from "std/range"
import * as Str from "std/string"
import * as Template from "std/template"
@const
function quoted(parts: Array<string>, values: Array<string>): string {
let out = Str.builder()
for (const index of Ranges.between(0, Arrays.length(values))) {
Str.append(mutable out, `${parts[index]}"${values[index]}"`)
}
Str.append(mutable out, parts[Arrays.length(values)])
return Str.build(out)
}
const greeting = quoted`hello ${name}!` // hello "ada"! when name is "ada"
const pattern = Template.raw`\d+\.${digits}` // the text \d+\. then digits
- Characters use single quotes:
'a','\n','\u{1F600}'. A character literal has typechar.'abc'is a compile error. - Integers:
42,0xFF,0o755,0b1010._can separate digits:1_000_000. - Floats:
3.14,1.0e-9,1_000.5. - A literal must fit its type.
const x: u8 = 300is a compile error. trueandfalsehave typebool.- A number literal with no other type information is
intwhen written without a decimal point, andf64when written with one. - Arrays:
[1, 2, 3].[]needs its type from context, as inlet xs: Array<int> = []. Arrays have no literal form with a type argument. - Maps:
Map { "a": 1, "b": 2 }. A key that is not a literal is written[key]: value. The key and value types come from the entries or from context. An emptyMap {}needs its type from context. - Type arguments on a literal.
Map<string, int> {},Map<string, int> { "a": 1 }andPair<int, string> { a: 1, b: "x" }write the type arguments after the name. The literal then has that type without help from context, socount(Map<string, int> {})needs no annotation. The compiler checks the arity, that each argument is a type, the map key rules (no float keys,EquatableandHashabletogether) and every key, value and field against the written types. If an expected type also exists, the two must be the same type. A<after a capitalized name starts type arguments only when it is followed by a balanced<...>of type names, dotted names and tuple types and then{; in every other case it is the less-than operator, soa < bis unchanged. Function types are not accepted inside the arguments; use an annotation for those. There is no{K: V}type and no#{...}literal. - Tuples:
#[1, "a"]builds a tuple of type#[int, string]. It always makes a tuple, needs no expected type and has at least two elements.[1, 2]is always an array.
There are no macros, no operator overloading and no function overloading.
Operators
- Operators are built in. Programs cannot define operators or change their meaning.
- Both operands have the same type. There are no implicit conversions, so
1 + 2.0is a compile error.
| Operators | Operand types |
|---|---|
+ - * / % |
Any integer type or any float type. / on integers truncates toward zero and needs a proven divisor (below). + - * on integers wrap on overflow |
& | ^ << >> |
Integer types. ^ is xor. A shift needs a proven count (below) |
~ |
Integer types, bitwise not |
< <= > >= |
Numbers, char and string |
== != |
Types that implement Equatable, compared structurally (section 4) |
&& || ! |
bool |
- There is no string concatenation operator. Use a template string or
Str.concat(a, b). The statements += tjoins strings (section 2, Bindings). - Compound assignment (
+=and the others) andx++/x--are statements, not operators, and have no value (section 2, Bindings). - There is no length operator. Use
Arrays.length(items),Str.length(s)andMaps.size(m). - There is no power operator. Use
Float.pow(x, y)orInt.pow(x, y). - The vector types of
std/simdtake+,-,*,/and the bitwise operators lane by lane (section 4, "Vector types"). Int.floorDiv(a, b)rounds toward negative infinity. It andInt.divmod(a, b)(the tuple#[quotient, remainder], truncating like/and%) return anOption,Nonefor a zero divisor, so they need no proof.Int.compare(a, b)returns anOrdering.
Differences from TypeScript
Code that is valid TypeScript but means something different in Narra is a compile error with a fix, never a silently different meaning. The exception is value copies (the const b = a row): a copy followed by a change to one of the names compiles, because finding the change would need a whole-function check of every copy (D81).
| TypeScript | Narra |
|---|---|
const b = a gives two names for one object, and a change through one shows through the other |
const fixes the name, and its contents can change, as in TypeScript (D81). const b = a makes a copy: a change to a does not show in b |
== converts types, === compares strictly |
== compares structurally with no conversion. === is a compile error |
let can be captured by any closure |
let can be captured only by a closure passed to a non-escaping parameter; an escaping closure shares changing state through a Cell |
null, undefined |
Not present. Use Option<T> with None |
T[] is an array type |
Not present. Write Array<T> (D23) |
number |
Not present. Use int, i32, f64 and the other sized types |
enum holds named numbers or strings |
enum holds variants with fields, checked by match |
'text' is a string |
'a' is a char. Strings use "text" |
for (const k in obj) loops over keys |
Not present. Use for (const k of Maps.keys(m)) |
for (init; cond; step) accepts var, const, several declarations and any condition |
The same form, with init a single let or empty (const is E0960), condition a bool (E0959) and step an assignment or a call (E0961) |
import X from "m" imports a default export |
Not present. Use import * as X from "m" |
xs.push(v), s.length |
Not present. Use Arrays.push(mutable xs, v), Str.length(s) |
a + b joins strings |
Not present. Use a template string (s += t is allowed as a statement) |
tag`a${x}` calls tag(strings, ...values), strings.raw holds the source text, and any expression can be the tag |
tag(["a", ""], [x]): the values come in one Array<T>, the tag picks decoded or raw parts by its first parameter type (Array<string> or Template.Raw), and the tag is a name (D114) |
y = x++, ++x, a[i] = b += 1 |
Compound assignment and x++ are statements without a value; ++x is an error (E0964) |
class, this, new, interface |
Not present. Use struct, enum and trait |
try, catch, throw |
Not present. Use Result (section 5) |
Calling an async function without await starts it in the background |
It starts it too, and the call gives an Async<T> handle. A handle left unused is a compile error (E1103): write await f(), keep the handle, or let it run with Async.detach(f()) (section 8) |
const o = { a } builds an object |
Not present. { a } in value position is a block expression, which needs return (E0933). Write a struct literal: Point { x: 1 } |
Promise<T> |
Async<T> (section 8). The methods are functions: Async.then(handle, callback), Async.all(handles) |
async function* returns an object with a next() method, and for await also takes sync iterables and arrays of promises |
async function* returns an AsyncGenerator<T>, read with for await or Async.next(stream). for await takes only an AsyncGenerator<T> (E1123), and copies of a stream share one position (section 8). |
A function declared inside a function |
A compile error (E0930). Declare it at module level as a private function and pass the enclosing values as arguments |
3. Modules and imports
- One file is one module. Its path from the package root is its name:
src/app/text.nrais"app/text". - Names are private by default.
exportmakes a top-level declaration visible to other modules:export function,export const,export type,export struct,export enum,export trait. - Imports are explicit. A module sees only its own declarations, the names it imports, and the prelude.
- Prelude. The prelude holds the types and constructors
Option,Some,None,Result,Ok,Err,Array,Map,Range,Boxand the primitive types, and the functionsprint,assert,panicandcopy(section 6, Copies on shared values). Nothing else is in scope without an import. These four are the only global functions. - A type in the prelude does not bring its functions. The functions of
Array,Map,RangeandBoxlive instd/array,std/map,std/rangeandstd/box(D67).Arrays.push(mutable xs, v)needsimport * as Arrays from "std/array". Without the import the call is a compile error (E0908) whose fix adds the import line. A type the program declares namedBoxorMaphides the prelude one. - Std aliases are plural by convention. The std modules of the capitalized prelude types are imported as
Arrays,Maps,Boxes,Ranges,OptionsandResults(D72). Samples and fixes use these names. Any other alias that follows the rules below works too. - Standard modules.
std/arena,std/args,std/array,std/box,std/build,std/bytes,std/cell,std/char,std/cstring(section 9),std/env,std/f32,std/fixedarray(section 2),std/float,std/fs,std/hash,std/int,std/i8,std/i16,std/i32,std/u8,std/u16,std/u32,std/u64,std/io,std/iterator,std/json,std/map,std/math,std/option,std/path,std/process,std/ptr(section 9),std/random,std/range,std/regex,std/result,std/shape,std/simd(section 4),std/string,std/template(section 2, Literals),std/terminal,std/test,std/time,std/tomlandstd/unicode, and the async modulesstd/asyncandstd/net(section 8). std/pathand Windows.Path.join,dirname,basenameandextnamefollow Node'spath.posixon every system. A program built for Windows (--target Windows-X86_64) also reads\as a separator, and a leading drive such asC:is kept in front of the result and is not a segment:Path.join("C:\\a", "..\\b")isC:/b, andPath.join("C:/a", "..")isC:/.joinalways writes/, which the Windows file functions accept;dirnamereturns the text of the input up to the last separator, soPath.dirname("C:\\a\\b")isC:\a, andPath.dirname("C:a")isC:. UNC paths (\\\\server\\share) are not supported. On other systems\is an ordinary name character.std/fsopens every file in binary mode on Windows and stdin, stdout and stderr are binary too, so\nis never rewritten (printwrites\n, not\r\n), andstd/fscreates a directory without a mode there. Samples:testdata/windows_path.nra,testdata/windows_runtime.nra.std/process,std/testandstd/asyncon Windows. A program built forWindows-X86_64runs all three. Known gaps against the other systems:Process.runstarts the program withCreateProcessW, searchingPATHitself (never the current directory or the folder of the program) and trying the name (only when it ends in.exe,.com,.bator.cmd), then the name with.exeand.com; it does not start a shell, soechoanddirneedcmd /c. The arguments are joined into one command line with the quotingCommandLineToArgvWreverses, and they must be valid UTF-8. The exit code is the value the process ended with: a crash gives a number such as3221225477(0xC0000005), not 128 plus a signal. The child, and any process it left running, ends when the call returns or this process ends (a job object). A.bator.cmdprogram runs throughcmd.exe, which reads%,&,|and^in the arguments as its own syntax, so do not pass untrusted text to one. SIGTERM and SIGHUP do not exist, so nothing is forwarded; a console sends Ctrl-C to the child itself.narrac teststarts the test binary again for each test instead of forking, so a test sees a fresh process. A test that runs past the time limit (10 seconds, orNARRA_TEST_TIMEOUT) is ended with the processes it started. A test that crashes reportscrashed with status 0x...where the other systems report the signal.Test.panicsandTest.panicsWithrun the closure in the same process and catch the panic with a jump, asCo.resumedoes. They have no timeout, so a closure that never returns hangs the test until the test's own time limit; what the closure changed in globals stays changed; and only the first 255 bytes of the panic message are compared.std/asyncwaits for sockets withWSAPoll. Only sockets are waited on, as on the other systems. A refused connect shows as an error only on Windows 10 version 2004 or later; before thatWSAPollnever reports it. Winsock errors are mapped to the errno names the std code tests (EWOULDBLOCK,EINPROGRESS,ECONNREFUSED, ...), and an error with no name there shows asEIO.SO_REUSEADDRis not set, because on Windows it lets a second socket take a port in use. The build linksws2_32, andshell32for the argument list.Env.args()reads the arguments as UTF-8 from the wide command line. Theargsgiven to the entry function still come from the Cmainand use the ANSI code page, so a non-ASCII argument reads correctly only throughEnv.args().- Samples:
testdata/windows_process.nra,testdata/windows_async.nra.
- Narra parts of builtin modules. A builtin std module may have functions and constants written in Narra, in
std/src/ext__<name>.nra(module pathstd/ext/<name>). The compiler loads that module whenever a program importsstd/<name>, andAlias.nameandimport { name } from "std/<name>"find it after the builtins. So far:Float.PI;Int.compare,Int.divmod,Int.floorDiv;Str.find(text, needle), the same asStr.indexOf;Arrays.map(items, f)(the callback takes an effect variable),Arrays.slice(items, start, finish)(anOption:Nonewhen the range is outside the array; it copies) andArrays.withCapacity(count)(an empty array that has room forcountelements; the element type comes from the expected type). std/shapeandstd/json(D83).std/shapedeclaresexport enum Value { Null, Bool(value: bool), Int(value: int), Float(value: f64), Text(value: string), List(items: Array<Value>), Record(fields: Map<string, Value>) }, a dynamic tree for structured data.std/jsonhasparse(text: string): Result<Value, string> uses allocandstringify(value: Value): string uses alloc. Writeimport * as Json from "std/json"andimport { Value } from "std/shape".parsefollows RFC 8259: a number without fraction or exponent that fitsintisValue.Int, every other number isValue.Float; a duplicate key keeps its first place and takes the last value; escapes and surrogate pairs decode, a lone surrogate is an error; nesting deeper than 512 is an error. Errors read<line>:<column>: <reason>.stringifyis compact, writes non-ASCII as UTF-8 and a non-finiteFloatasnull, and a wholeFloatkeeps.0.std/math,std/time,std/randomandstd/hashare Narra source over the primitives ofstd/internal/math(the functions of C'smath.h),std/internal/clockandstd/internal/entropy.std/mathhas the constantsPIandE;absandabsFloat;min,maxandclampfor anyOrderedtype, so forintandf64;powandpowInt(powIntreturnsNonefor a negative exponent, overflow wraps like*; useInt.mulCheckedto detect it); andsqrt,floor,ceil,round(half away from zero),trunc,sin,cos,tan,atan2,expandlog, all onf64.clampreturnsNonewhenlow > high, andSome(value)otherwise.std/timehasInstantandDuration(both a count of nanoseconds).now()reads the monotonic clock,elapsed(since)reads it again,between(earlier, later)needs no clock,unixMillis()is the wall clock, and the asyncsleep(duration): Result<Duration, AsyncError>waits without blocking the loop (section 8).milliseconds,secondsandnanosecondsbuild aDuration,asMillisecondsandasNanosecondsread it. Reading a clock and sleeping have theioeffect (section 7).std/randomis SplitMix64: aRandomholds oneu64state, the same seed gives the same numbers on every run and platform, and a value is copied like any struct.seeded(seed)andfromSystem() uses io(seeded from/dev/urandom) make one;nextInt(mutable random, low, high)returnsSome(n)withnin[low, high)without modulo bias, andNonewhen the range is empty;nextFloatreturns anf64in[0, 1);nextBitsreturns 64 random bits;shuffle(mutable random, mutable items)is a Fisher-Yates shuffle. It is not for cryptography.std/hashhasHash.of(x), theHashablehash of any value (it may change between builds), andfnv1a(text), FNV-1a 64 over the UTF-8 bytes of a string as au64, which never changes.ofis a keyword, and is accepted as a function name and after., likefrom.
std/process(aliasProcess) is builtin:run(command: string, arguments: Array<string>): Result<#[int, string, string], string>andexit(code: int): void.exithas theioeffect and ends the process withcode(the operating system keeps the low 8 bits). It flushes pending standard output first, then leaves at once: live values are not released, so the leak check (NARRA_CHECK_LEAKS) reports nothing for them, and the code after the call does not run. Likepanic, a call toexitends a path, so a function that returns a value may end with it. Whilerunwaits, it forwards SIGTERM, SIGINT and SIGHUP to the child (the child stays in the caller's process group, so Ctrl-C still reaches it). The caller keeps running:runreturns and reports the child's end as exit code 128 plus the signal number, so a program that callsProcess.runin a loop must check for it.narrac run,narrac testandTest.panicsuse the same forwarding for the processes they start, so killing narrac does not orphan the program or a test.std/internal/is for the standard library. A std module written in Narra reaches the C primitives it needs through modules understd/internal/<name>. Only a module whose path starts withstd/may import them. Any other import is an error (E0474):std/internal/<name> is internal to the standard library. The error list of unknown modules does not name them.- Std modules for tools (D118). Seven modules:
std/iterator,std/arena,std/unicode,std/args,std/toml,std/regexandstd/terminal. Each is Narra source; onlystd/terminalhas runtime C (std/internal/terminal). None panics on bad input. std/iterator(aliasIterators, D118) is Narra source. Lazy operators are generator functions:map,filter,flatMap(its callback returns aGenerator),take,drop,takeWhile,dropWhile,enumerate(yields#[int, T]),zip(yields#[A, B]and ends with the shorter source) andconcat. Their callbacks areescaping, so a closure passed to one cannot capture alet(E0612).chunk(source, size)andwindow(source, size)returnOption<Generator<Array<T>> uses (E, alloc)>,Nonefor a size below 1; the last chunk may be shorter, and a source shorter than the window yields no window.takeanddroptreat a negative count as 0. Eager operators run the source to its end or to the first answer, with callbacks that are not escaping:reduce(source, combine, initial),toArray,forEach,some,every,find(anOption) andcount. One effect variable covers the source and the callbacks, soIterators.mapover a source withuses iois aGeneratorwithuses io, and a pure source and callback give a pure one.flatMap,zip,chunkandwindowaddalloc. The effect variable ofchunkandwindowsits inside theOptionof the result and is bound at the call too, so chunks of a source withuses ioruniowhen they are read. An operator takes its source by value: a loop or a resume inside it works on its own copy, so afterIterators.take(lines, 2)a loop overlinesstarts from the first item again and redoes its work.Co.resume(mutable lines)moveslinesitself.std/arena(aliasArenas, D118) is Narra source overArray.Arena<T>andHandle<T>are opaque structs (section 6, Cycles), so code outside the module cannot read a handle's fields. A handle is a slot index and a generation, and derivesEquatable,HashableandShow, so it works as a map key.create<T>()makes an empty arena (the element type comes from the expected type orArenas.create<Node>()).insert(mutable arena, value)returns aHandle<T>.get(arena, handle)returnsOption<T> from arena.set(mutable arena, handle, value)andupdate(mutable arena, handle, change)returnbool, false for a stale handle.remove(mutable arena, handle)returns the value as anOptionand drops it from the slot at once. A removed slot goes on a free list, and reusing it adds 1 to its generation, so an old handle getsNoneandfalse.containsandsizeread the arena.clear(mutable arena)keeps the slots and raises every generation.entries(arena)is aGenerator<#[Handle<T>, T]>in slot order. A handle from another arena is not detected: it reads whatever the same slot of this arena holds. Copying an arena copies its slots on the first write, like an array.std/unicode(aliasUnicode, D118) is Narra source, for Unicode 17.0. It hasgraphemes(text): Generator<string>(extended grapheme clusters of UAX #29, each a slice oftext),graphemeCount(text): int,toUpperCaseandtoLowerCase(full mappings with the unconditional rules of SpecialCasing and the final sigma rule),foldCase(full case folding, status C and F),displayWidth(text): int(terminal columns per cluster: the widest code point of the cluster, where East Asian Wide and Fullwidth and emoji presentation are 2, marks, format, control and default-ignorable code points 0, others 1, and U+FE0F after an emoji makes the cluster 2; it counts escape codes as text, so styled text goes throughTerminal.stripStylesfirst),normalize(text, form): stringandisNormalized(text, form): boolwithenum NormalForm { NFC, NFD, NFKC, NFKD }(UAX #15; text already in the form comes back as the same string, and Hangul syllables are computed, not tabled). Case mapping uses no locale. The tables are string constants instd/internal/unicode(std/src/internal__unicode.nra), written byscripts/unicode/generate.nrafrom the UCD files.std/args(aliasArgs, D118) is Narra source. ACommand { name, summary, flags, positionals, rest, commands }describes a command line;restisRest.None(the default),Rest.PositionalsorRest.Raw. AFlag { name, short, value, repeated, help }with an emptyvaluetakes no value; any other text names the value in the help (--output <path>).Args.parse(command, arguments)reads the argumentsrunreceives (the program name first) and returnsResult<Parsed, ArgsError>.- Syntax:
--name,--name=value,--name value,-x,-x value,-xvalue, bundled-abc, and--ends the flags. A lone-is a positional. A long name always takes two dashes. Flags belong to the command they are declared on and may come after its positionals. Every declared positional is required. A command with subcommands takes the first positional as the subcommand name. Extra positionals are an error withRest.None, are collected withRest.Positionals, and withRest.Raweverything after the declared positionals is kept as written. - Reading:
has(parsed, name),value(parsed, name)(the last one given),values(parsed, name),positional(parsed, name),rest(parsed)andcommandPath(parsed)(["narrac", "build"], starting at the root command's name). - Errors:
ArgsError.UnknownFlag(name, closest),MissingValue(flag),UnexpectedValue(flag),Repeated(flag),UnknownCommand(name, closest),MissingCommand(path),MissingPositional(name),ExtraPositional(text),Help(path)andBadSpec(reason).closestis the known name at most two edits away (names compared without dashes; a name under three bytes gets none), or"".UnknownFlagandMissingValuename the flag as typed (-oor--output).-hand--helpon any command returnHelp(path); the caller printsArgs.help(command, path)and exits 0.BadSpecreports a spec mistake (two flags or subcommands with one name, a subcommand flag with the long name of an enclosing command's flag, a short name that is not one character, positionals beside subcommands) on every parse.Args.formatError(error)writes the message line, with a hint for a close name (unknown flag --relase; did you mean --release?). Args.help(command, path)writes the usage line, the summary, the flags and the subcommands in aligned columns, with no wrapping.
- Syntax:
std/toml(aliasToml, D118) is Narra source: TOML 1.0 to and from theValueofstd/shape.Toml.parse(text)returnsResult<Value, TomlError>withstruct TomlError { line, column, reason };Toml.formatError(error)writes<line>:<column>: <reason>.stringify(value)returnsResult<string, string>,decode<T: Shape>(text)returnsResult<T, string>(a parse error asformatErrorwrites it, a shape error as a D84 path), andencode<T: Shape>(value)returnsResult<string, string>.- Mapping: a table is a
Recordin the order of the file, an array aList(mixed types allowed), an integer anInt(decimal,0x,0o,0b, underscores between digits; outside the 64-bit range is an error), a float aFloat(inf,nanand exponents too), a stringText(basic, literal and both multi-line forms, every escape of TOML 1.0), a booleanBool. An offset date-time, local date-time, local date or local time is checked (month, day of month with leap years, hours, minutes, seconds up to 60) and becomesTextholding its text as written. - Errors: a key set twice, a table defined twice or after dotted keys defined it, dotted keys into a table a header defined, an inline table extended, a static array appended to with
[[name]], a bare carriage return, a control character in a string or comment, and nesting deeper than 512. stringifywrites the plain keys of each table before its sub-tables, a non-emptyListof onlyRecords as[[name]]tables, otherRecords inside values as inline tables, and quotes keys that are not bare. A table with only sub-tables gets no header. It returnsErrforNull(<path>: TOML has no null) and for a root that is not aRecord, and does not keep comments or layout.
- Mapping: a table is a
std/regex(aliasRegexes, typeRegex, D118) is Narra source: a pattern parser and a Pike VM over the code points of the text, so a search takes time linear in the text times the pattern.Regexes.compile(pattern)returnsResult<Regex, RegexError>withstruct RegexError { position, reason },positionbeing the byte offset of the mistake in the pattern.Regexes.formatError(error)writes<position>: <reason>.Regexes.checked(pattern): Regexis an@constfunction that compiles the pattern while the compiler runs (section 10):const WORD = Regexes.checked("[a-z]+")puts the compiled program into the C, and a bad pattern stops the constant with E1053,bad pattern "(a" at 0: unclosed group. A call anywhere else (a function body or alazyvalue) and a use as a function value are E1360, socheckednever panics at run time; usecompilethere.- Syntax: JavaScript's without back references and lookaround. Literals and escapes (
\n,\t,\r,\v,\f,\0,\cX,\xHH,\uHHHH(a high and a low surrogate escape in a row are one code point),\u{...}, and a backslash before any punctuation),., classes ([a-z],[^...],[]matches nothing and[^]anything;\bin a class is a backspace),\d,\wand\sand their negations (\dand\wASCII,\sJavaScript's white space and line terminators), anchors^,$,\b,\B(ASCII word characters), groups(...),(?:...),(?<name>...), alternation, and*,+,?,{n},{n,},{n,m}with their lazy forms. A{that does not start a repeat is a literal. Flags are written as RE2 does:(?i),(?m)and(?s)(or several, with-to turn off) hold to the end of the enclosing group, and(?i:...)sets them for one group.(?i)folds ASCII letters only.(?m)makes^and$match at line terminators (\n,\r, U+2028, U+2029) and(?s)lets.match them, as JavaScript'smands. - Errors: an unclosed group or class, an unmatched
), a bad class range, nothing to repeat, a back reference (\1,\k<name>) or lookaround ((?=,(?!,(?<=,(?<!) with a reason that says the engine is linear-time, a repeat count above 1000, a program above 10,000 instructions, a program whose length times its slots (two per group, one per repeat) is above 1,000,000, a bad escape or group name, a group name used twice, and groups nested deeper than 1000. - Matching is leftmost-first with captures, as RE2: the first alternative and the greedy choice win. As in JavaScript, each pass of a repeat clears the groups inside it, and a pass beyond the lower count fails when it matches empty (
(|a)+onaamatchesaa).matches(regex, text): bool,find(regex, text)andfindFrom(regex, text, start)returnOption<Match>; a start inside a character moves to the next one, and one outside the text finds nothing.findAll(regex, text)is aGenerator<Match>(JavaScript'smatchAll) and moves past an empty match by one character.struct Match { start, end, text, groups, names }: offsets are byte offsets,groups[0]is the whole match.group(match, index)andnamedGroup(match, name)returnOption<string>,Nonefor a group that took no part in the match. replace(regex, text, replacement)replaces the first match andreplaceAllevery match found asfindAllfinds them; the replacement is plain text, so$1stays$1.replaceWith(regex, text, change)replaces every match with what a non-escaping callback returns for itsMatch.split(regex, text)cuts as JavaScript'ssplitwith a regex, without adding groups: an empty match next to the last cut or at the end does not cut, and an empty text gives[]when the regex matches it.- The test function is
matches, nottest:testis a keyword. Most Annex B forms that JavaScript accepts without theuflag are errors (\8,\a,[\w-z]); a lone]or}and a{that does not start a repeat stay literals.
- Syntax: JavaScript's without back references and lookaround. Literals and escapes (
std/terminal(aliasTerminal, D118) is Narra source overstd/internal/terminal.isTerminal(stream),columns(stream): Option<int>(Nonewhen the stream is not a terminal) anduseColor(stream)(which honorsNO_COLOR,FORCE_COLORandTERM=dumb) have theioeffect;StreamisStdin,StdoutorStderr. Style functions (bold,red,bgRed,style(text, Style)and the rest) always add the codes and nest;stripStylesremoves them.Styleholdsforegroundandbackgroundas aColor(defaultColor.Default, which adds no code) and the flagsbold,dim,italic,underline,inverseandstrikethrough.ColorhasDefault, the eight names, their bright forms,Ansi256(index: u8)andRgb(red, green, blue).- Paths are package rooted.
"app/text"for this package,"std/string"for the standard library,"pkgname/module"for a dependency. Relative paths are not allowed.
import * as Str from "std/string" // namespace import
import * as Arrays from "std/array" // plural alias for a prelude type's module
import { classify, Token } from "app/text" // named imports
import { map as mapArray } from "std/array" // a named import with a new name
There is no re-export statement. To expose an imported name, import it and export a new declaration:
import * as Text from "app/text"
export const classify = Text.classify // a function
export type Token = Text.Token // a type, with its constructors
Rules:
- Imports are static. They appear at the top of the file with a string literal path. They never run code and never load a module at runtime.
import(...)as an expression is a compile error. - An import alias may not equal a type name.
import * as Shapein a module that declares or imports a typeShape, orimport * as Array(a prelude type), is a compile error, as in TypeScript.Shape.Circlethen always names a constructor ofShape. The fix suggests the plural (Arrays). Two imports with the same alias are an error too. - Named imports can take a new name.
import { map as mapArray } from "std/array"makes the functionmapArrayin this module. The new name follows the rules of every other name in the module: it may not clash with a declaration, another import or a type name.import { Teacher }of an enum constructor is a compile error whose fix imports the enum instead. - No cycles. The import graph must be acyclic. The compiler reports the cycle as a list of modules.
- No re-export statement and no default exports.
export { x } from "m",export *andexport defaultare compile errors. An exported name is always declared in the exporting file. export type A = Bdeclares an alias. WhenBis an enum, its constructors are usable through the alias.export opaque structandexport distinct typeexport a type while hiding its contents (section 4).- No import side effects. Top-level declarations must be functions, types, traits or
constconstants. There is no top-levellet. - Constructors come with their enum and are always qualified. Importing
TokenmakesToken.Word(x)usable, in expressions and in patterns (D71). A bareWord(x)is a compile error whose fix writesToken.Word(x).Some,None,OkandErrare the exception: they are prelude names and stay bare. Constructors of different enums never clash, whatever their fields, and a user enum may have a constructor namedNone(Maybe.None); a bareNoneis always the prelude one. Two constructors with the same name in one enum are an error.
4. Types
Primitive types
| Type | Meaning |
|---|---|
i8 i16 i32 i64 |
Signed integers |
u8 u16 u32 u64 |
Unsigned integers |
int |
Alias for i64 |
f32 f64 |
Floats |
bool |
true or false |
char |
A Unicode scalar value |
string |
Immutable UTF-8 text |
bytes |
Immutable byte sequence |
Composite types
- Structs. Declared with
struct. The full rules are in "Structs" below. - Enums. Declared with
enum. Each constructor can carry named fields, and is written with its enum's name:Token.Word("hi"),Token.Space(section 3).
export enum Token {
Word(text: string)
Number(value: int)
Space
}
- Arrays.
Array<T>is a growable, contiguous array on the heap. Elements are stored directly: anArray<int>holds raw 8-byte integers. Indexes start at 0.items[i]is bounds checked and panics when out of range. - Fixed-size arrays.
FixedArray<T, N>holds exactlyNelements and is stored inline, like a struct. It needs no heap allocation.Nis an integer literal or a constant type parameter, and never negative (E0995). OneFixedArrayvalue takes at most 1 MiB (1048576 bytes), so a local fits well inside a thread's stack; a larger one is E0995, and anArrayholds more.[1.0, 2.0, 3.0, 4.0]builds one when the expected type is aFixedArray, and gives allNelements. A generic function can take the length as a parameter:function sum<const N: int>(values: FixedArray<f64, N>): f64. - Fixed-size array indexes are proven. Indexing a
FixedArraynever panics and has no runtime check. A constant index must be from 0 toN - 1, and any other index must be a name that a check proves to be in that range (E0994): aniforwhilecondition such asi >= 0 && i < N, the condition offor (let i = 0; i < N; i++)when nothing in the loop assignsi, orfor (const i of Ranges.upTo(N)). An assignment to the name ends the proof. In a generic body the proof is made in each instance, whereNis a constant.FixedArrays.get(values, i)(std/fixedarray) returns anOption<T>for any index, andFixedArrays.length(values)returnsN.for (const v of values)reads a copy of the elements. Equality, hashing, ordering andShowfollow the element type, as forArray.
import * as FixedArrays from "std/fixedarray"
function sum<const N: int>(values: FixedArray<f64, N>): f64 {
let total = 0.0
for (let i = 0; i < N; i++) {
total += values[i]
}
return total
}
function at(values: FixedArray<f64, 4>, index: int): f64 {
if (index >= 0 && index < 4) {
return values[index]
}
return 0.0
}
function last(values: FixedArray<f64, 4>): Option<f64> {
return FixedArrays.get(values, FixedArrays.length(values) - 1)
}
- Vector types.
std/simdprovides fixed-width vectors such asF32x4,F64x2andI32x8(D112). Their operators work lane by lane and compile to the target's vector instructions. "Vector types" below has the rules. - Maps.
Map<K, V>is a hash map.m[k]returnsOption<V>. - Maps keep insertion order. Iteration visits keys in the order they were first inserted. Removing a key and inserting it again moves it to the end.
- Float keys are not allowed.
Map<f64, V>and keys that contain floats are compile errors. - Tuples.
#[int, string]is a tuple type. It holds a fixed group of at least two values.#[1, "a"]builds one,const #[n, s] = t(orlet) destructures one, and#[0, name]matches one in a pattern.pair[0]reads one element, with that element's type. The index is a constant integer, a literal or a top-levelconst, inside the tuple's range, so the read has no runtime check and cannot panic; any other index is E1010, an index outside the range is E1011. Tuple elements are read-only:pair[0] = 2is E0226. The type is written like the literal, in every type position:Array<#[int, string]>,#[#[int, int], string]. A function that returns several values returns a tuple or a struct. - Functions.
(a: int, b: string) => bool. A function type may list its effects after the result:(path: string) => string uses io(section 7).
Vector types
- Twenty types.
std/simdhas ten lane types at two widths. 128 bits:I8x16,U8x16,I16x8,U16x8,I32x4,U32x4,I64x2,U64x2,F32x4,F64x2. 256 bits:I8x32,U8x32,I16x16,U16x16,I32x8,U32x8,I64x4,U64x4,F32x8,F64x4. The lanes ofI64x2areint. The names are visible in a module that importsstd/simd(import * as Simd from "std/simd"), whatever the alias. - Every type exists on every target and gives the same results there. A 256-bit type on a machine with 128-bit registers runs as two 128-bit operations.
- A vector is a plain value, like a number: assignment copies it, and it needs no heap. It is not a contents type, so it cannot be a
mutableparameter or the argument ofcopy(section 6). It can be an element ofArrayandFixedArray, a struct field, a type argument and the target of aPtr.==and!=compare whole vectors and give abool. Integer vectors can be map keys; float vectors cannot, like floats.Show.show(v)prints the lanes as it prints aFixedArray; a template does not take a vector, as it does not take aFixedArray. Vectors have no order:<,<=,>and>=are compile errors (E1250). - Building one. An array literal with an expected vector type gives every lane,
const unit: F32x4 = [1.0, 0.0, 0.0, 0.0]; another number of lanes is E1253.Simd.splat(value)fills every lane.Simd.fromFixed(values)turns aFixedArray<L, N>into the vector ofNlanes of typeL(E1255 when no vector type has that lane type and count), andSimd.toFixed(v)turns it back.Simd.splatandSimd.loadtake their vector type from the expected type or a type argument,Simd.splat<F32x4>(1.0); with neither, the call is E1254. - Operators work lane by lane.
+,-and*on every vector type, unary-on signed and float ones,/on float vectors, and&,|,^and~on integer vectors. Compound assignment follows (total += a * b). Integer lanes wrap on overflow, as integers do.%, integer/,<<and>>are compile errors that name the function to use (E1250). Both operands have the same vector type:v * 2.0is E1251, whose message endsmake a vector of the scalar with Simd.splat(...). - Lanes.
v[i]reads lanei. The index is proven as aFixedArrayindex is (E0994): a constant from 0 to the lane count minus 1, or a name a check proves to be in that range. A vector is a value, sov[i] = xis E1252;Simd.withLane(v, i, x)returns a copy with laneireplaced, with the same proof fori. - Comparisons give masks.
Simd.equal,Simd.notEqual,Simd.less,Simd.lessOrEqual,Simd.greaterandSimd.greaterOrEqualtake two vectors of one type and return its mask: the signed integer vector with the same lane width and count (F32x4givesI32x4,U8x16givesI8x16), with-1in each lane where the comparison holds and0elsewhere.Simd.select(mask, ifTrue, ifFalse)takes each bit fromifTruewhere the mask's bit is set and fromifFalseelsewhere.Simd.any(mask)andSimd.all(mask)return whether any lane, or every lane, is not 0. - Loads and stores.
Simd.load(items, start)reads the lanesstartonward of anArray<L>into a vector and returnsOption<V>,Nonewhen they are not all in range.Simd.store(mutable items, start, v)writes the lanes and returnstrue, or writes nothing and returnsfalsewhen they do not all fit. - Other functions.
Simd.shuffle(v, [3, 2, 1, 0])returns a vector whose lanekis lanelanes[k]ofv; the list gives one constant per lane, each a lane ofv(E1260).Simd.sum(v)adds the lanes, the high half to the low half until one lane is left, so a float sum is the same on every target.Simd.min(a, b)andSimd.max(a, b)work per lane.Simd.abs(v)takes signed and float vectors; the lowest integer stays itself.Simd.shiftLeft(v, count)andSimd.shiftRight(v, count)take integer vectors and anintcount, proven like a shift count against the lane width (E0980); a right shift is arithmetic on signed lanes and logical on unsigned ones. A function given a vector type it does not take is E1261. - No effects and no panics. No
std/simdfunction has an effect, allocates or panics.
Structs
A struct is a fixed set of named fields, stored inline like a C struct.
export struct ServerConfig {
host: string
port: int = 8080
tags: Array<string> = []
}
struct Entry<K, V> {
key: K
value: V
}
Fields and defaults
- Each field has a name and a type, one per line.
- A field can have a default value after
=. The default must be a compile-time constant (section 10). - In a generic struct a field whose type uses a type parameter can have a default (
items: Array<T> = [],value: Option<T> = None). The default is checked once in the declaration with the parameter open, so it must type-check for every type argument (count: T = 0is a type error), and it is built for each instance with that instance's types. - A field without a default must be given every time the struct is built.
Building a struct
TypeName { field: value, ... }builds a struct of that type. The fields can appear in any order.- When the expected type is already known, the type name can be left out:
{ field: value }. The type comes from an annotation, a parameter or a return type. - Fields with defaults can be left out. All other fields must be given.
- A field can be written as its name alone:
Point { x, y }meansPoint { x: x, y: y }(D119). The name is read as a variable, a parameter or a top-level constant in scope, so an unknown name is the usual unknown-name error. Shorthand andname: valuefields mix, and shorthand works after a spread, in enum constructor arguments and in a generic struct literal with or without type arguments. It needs a type name or a spread: a plain{ name }in value position is still a block expression (E0933).narrac fmtkeeps the form that was written. - Type arguments of a generic struct are inferred from the fields:
Entry { key: "a", value: 1 }isEntry<string, int>.
const config = ServerConfig { host: "localhost" } // port is 8080, tags is []
const loopback: ServerConfig = { host: "127.0.0.1", port: 3000 }
function makeEntry(key: string, value: int): Entry<string, int> {
return { key: key, value: value } // type taken from the return type
}
Reading and updating
s.fieldreads a field.{ ...s, field: value }returns a copy ofswith some fields changed. The spread must come first, there is only one, and the result has the same type ass. The original is unchanged.s.field = valuechanges a field in place.smust be a localconstorlet, amutableparameter, or a field or element of one (section 2, Bindings).- To change a caller's struct inside a function, declare the parameter
mutable(section 6).
const moved = { ...config, port: 9000 }
let current = copy(config)
current.port = 9001
current.tags[0] = "primary"
Destructuring
const { field1, field2 } = sbinds each field to a variable with the same name.const { field: name } = sbinds the field to a different name.- Fields that are not listed are ignored.
- The same patterns work in
match. A literal after:tests the field's value instead of binding it.
const { host, port: serverPort } = config
match (point) {
{ x: 0.0, y: 0.0 } => print("origin")
{ x: 0.0, y } => print(`on the y axis at ${Float.toString(y)}`)
{ x, y } => print(`${Float.toString(x)}, ${Float.toString(y)}`)
}
Storage
- A struct field, array element or variable holds the struct's fields directly. There is no heap allocation and no reference count for the struct itself.
- Copying a struct copies its fields. Fields stored on the heap, such as strings and arrays, have their reference count incremented.
==compares structs field by field. It is a compile error when a field holds a function.- A struct cannot contain itself. Use an array, an enum or
Box<T>for recursive data.
Boxes
Box<T>holds one value on the heap with a reference count.Boxes.new(value)creates one.b.valuereads the value.b.value = vreplaces it whenbis a localconstorletor amutableparameter, in place when the count is 1.- Use a box for recursive structs and for large structs that are copied often.
struct ListNode {
value: int
next: Option<Box<ListNode>> = None
}
const list = ListNode { value: 1, next: Some(Boxes.new(ListNode { value: 2 })) }
Opaque types
export opaque struct exports a struct's name but not its fields.
// module "app/range"
export opaque struct Range {
start: int
finish: int
}
export function create(start: int, finish: int): Result<Range, string> uses alloc {
if (start > finish) {
return Err("start is after finish")
}
return Ok(Range { start: start, finish: finish })
}
export function length(r: Range): int {
return r.finish - r.start
}
- Other modules can store, pass, copy and compare a
Rangewith==. They cannot build one with a literal, read or assign its fields, spread it, or destructure it. - The declaring module uses the struct like any other struct.
- Fields are all public or all private. There is no per-field visibility.
- Use an opaque struct when a type has a rule that every value must follow, such as
start <= finish.
Type aliases
type Name = T gives a type a second name. export type exports it.
type Tok = Token
type Pair<T> = #[T, T]
export type Token = Text.Token
- The alias is the same type.
TokandTokencan be used in place of each other, and when the target is an enum,Tok.Word(x)builds a value andTok.Word(text)works in a pattern. - Generic aliases take type parameters, and every use gives the arguments. A wrong number of arguments is a compile error. Constructors through a generic alias (
Opt.Some(3)fortype Opt<T> = Option<T>) are not available yet. - No recursion. An alias may not refer to itself, directly or through other aliases; recursive types need an enum.
- Diagnostics show a struct, enum or distinct type reached through an alias as
Tok (Token). - Nothing reaches the emitted C.
typeof
typeof name in a type position stands for the type of a value in scope: a const, let, a parameter, a top-level constant or a function (D96). Its use is to keep a type in step with a value, without writing the type twice.
export const table: Map<string, Array<int>> = Map {}
function fill(mutable target: typeof table, key: string) {
target[key] = [1]
}
For a function it is the full function type, with its effects and from:
export function handle(request: Request): Response uses io {
return Response { status: 200 }
}
export type Handler = typeof handle // (request: Request) => Response uses io
- Names only. A field path or an expression after
typeofis a parse error. A parameter can be named by the parameters after it in the same signature:(request: Request, other: typeof request). - A name that is not a value is E0982: a type, a module, a generic function, a function with effect variables, a
mutableparameter orrequireslines (none has a function type to write). - A
typeofthat refers to its own declaration is E0981, for exampleconst count: typeof count = 1orfunction f(handler: typeof f). - A constant without a written type has the type of its value, which is known once the constant has been checked:
typeofof it works in function bodies, but not in a declaration of the same module (a signature, a field, an alias), where it is E1003 and asks for the written type. A constant of another module is always checked first. - Nothing reaches the emitted C: the type is replaced by the type it stands for.
Distinct types
distinct type declares a new type with the same representation as an existing one.
export distinct type UserId = int
export distinct type OrderId = int
const user = UserId.from(42)
const raw: int = UserId.toInt(user)
loadUser(OrderId.from(7)) // compile error: OrderId is not UserId
- No implicit conversion. A
UserIdis not anint, and anOrderIdis not aUserId. T.fromandT.toIntare generated. For a distinct type over another type, the second function is named after it, such asT.toStringfor a distinctstring.- Arithmetic, bit operators and
<do not carry over.user + 1anduser < otherare compile errors. The declaring module defines any operations the type needs as functions.==,!=and map keys work when the base type supports them, through the automaticEquatableandHashable; they compare the base value, soimplement Equatableorimplement Hashablefor a distinct type is an error (E1014). - Trait lists. A distinct type lists traits after its base, as a struct does:
distinct type UserId = int implements Label derives Ordered, Show. A trait inimplementsneeds animplementblock in the same module or aderivesentry. A derived trait is the base type's: the derive is an error (E1012) when the base type does not implement the trait, andShow.show(UserId.from(7))is7.derives Shapeencodes the base value, also for anopaquedistinct type, soShape.fromValuebuilds its values outside the module. - No runtime cost. A distinct type compiles to the same C type as its base.
export opaque distinct typehidesfrom, so only the declaring module can create values. Other modules can still call the unwrap function.
Refinements
A distinct type may restrict its values with requires and a list of patterns joined by && (D116). The list follows the base and the trait lists and may start on the next line.
export distinct type Port = int derives Show requires >= 1 && <= 65535
export distinct type Method = string requires "GET" | "POST"
distinct type Bit = u8
requires < 8
const DEFAULT_PORT = Port.from(8080) // proven from the literal
function share(total: int, port: Port): int {
return total / Port.toInt(port) // 1 <= n <= 65535, so the divisor is proven
}
function parsePort(raw: int): Option<Port> {
if (raw >= 1 && raw <= 65535) {
return Some(Port.from(raw)) // proven by the check
}
return Port.check(raw) // tested at run time: None here
}
const port = Port.from(70000) // compile error: 70000 does not satisfy Port (<= 65535)
- The patterns are
ensurespatterns (section 13): comparisons< c,<= c,> c,>= cand!= cwith an integer constant that fits the base, literals, and or-patterns of these.&&joins patterns only at the top of the list. A malformed list is E1220. - The base is an integer type or
string. Astringtakes literal patterns only. Any other base, another distinct type included, is E1221. A pattern that does not fit the base (a comparison on astring, a bound that is not a constant or does not fit, a u64 bound from 2^63 up, a literal of another type, a wildcard, a name, a constructor, a struct, tuple or array pattern) is E1222. T.from(value)is proven at compile time, as a call to a function withrequires: the value must match every pattern, proven from a constant, a literal, or an integer name narrowed by a check or by the caller'srequires. Nothing is checked at run time. An unprovenfromis E1223, and the message names the patterns that failed:Port.from(8080)compiles,Port.from(raw)compiles insideif (raw >= 1 && raw <= 65535), andPort.from(70000)is E1223 (70000 does not satisfy Port (<= 65535)). A top-levelconstor a struct field default may hold afromcall, proven the same way.T.check(value): Option<T>tests at run time. It exists only on a refined type, allocates nothing, and isNonewhen a pattern does not match:if (Port.check(raw) is Some(port)).export opaque distinct typehides it withfrom.- Unwrapping gives the fact.
Port.toInt(port)has the bounds of the patterns, whereverportcomes from (a parameter, a field, an array element). It proves divisors, shift counts,FixedArrayindexes,requiresarguments andensuresreturns, andconst n = Port.toInt(port)starts with it. The fact is the hull of the patterns, as forensures:Portgives1 <= n <= 65535,!= 0gives a non-zero value, and astringrefinement gives no fact. The unwrapped value is a plain base value:Port.toInt(port) + 1is anintwith no fact. derives Shapedecodes the base, then checks the patterns. A value that fails is anErrwith the usual path:Json.decode<Config>(text)givesErr(".port: 70000 does not satisfy Port (>= 1 && <= 65535)"), and a string value is quoted. The other derived traits use the base, as for every distinct type.- No runtime cost outside
checkand decoding: a refined type compiles to its base C type, andfromis the base value.
Optional values
Option<T>is eitherSome(value)orNone. A plainTalways holds a value. There is nonullorundefined.if (x is Some(v)) { ... }bindsvinside the branch. Afterif (x is None) { return ... },xis known to beSomefor the rest of the block, andx.valuereads the value.std/optionhelpers.import * as Options from "std/option"addsOptions.map(x, f),Options.andThen(x, f)(freturns anOption),Options.withDefault(x, fallback),Options.orElse(x, f)(ftakes no argument and returns anOption),Options.isSome(x),Options.isNone(x)andOptions.okOr(x, error)(aResult).withDefaultreturnsfallbackwhenxisNone. The fallback is always evaluated; useorElsefor a lazy one. When a callback returnsNoneorErr(...)and the type of the call is not known from context, annotate the result (const y: Option<int> = Options.andThen(x, (v) => None)). There is nounwraporexpect: read the value after anistest, or give a fallback.- Callbacks. The function arguments of these helpers are non-escaping and take an effect variable, like
Arrays.mapin the effects section: a call uses the effects of its callback, so aniocallback needsuses ioon the caller. A capturing arrow function passed to a helper is allocated on the stack. - Helpers never return early. They are expressions. The main style for a path that stops stays
isandmatch. - Type syntax uses names, not symbols:
Option<T>,Array<T>,Map<K, V>,Result<T, E>. There is noT | nullorT?. Tuples are the one exception:#[A, B](see Tuples above).
Pattern matching
match checks a value against patterns. It must cover every case, or end with a _ arm.
match (token) {
Token.Word(text) => print(text)
Token.Number(n) if (n < 0) => print("negative")
Token.Number(n) => print(Int.toString(n))
Token.Space => print(" ")
}
const label = match (status) {
Status.Active => "active"
Status.Suspended(reason) => `suspended: ${reason}`
}
- Each arm is
pattern => expressionorpattern => { statements }. - Patterns can bind fields, test literals, and add an
if (...)guard. - Alternatives (D98). An arm may list patterns joined with
|:Token.Plus | Token.Minus => .... Alternatives nest inside a pattern:Some(1 | 2). Every alternative binds the same names with the same types (E0967 for different names, E0968 for different types), soShape.Circle(r) | Shape.Sphere(r) => rworks. A guard covers the whole list: when it fails for one matching alternative, the next alternative that matches is tried with its own bindings, and the arm is taken if any alternative matches with the guard true (as in Rust). A binding keeps the full type of the value: there is no narrowing to the listed constructors and no union type (D73). Exhaustiveness counts each alternative, and an alternative that the arms and alternatives before it already match is an error (E0974). Alternatives are only formatch; anistest and aconst,letorfor ... ofdestructuring take one pattern (E0974).narrac fmtwrites a list on one line when it fits, otherwise one alternative per line, each after the first starting with|. - Array patterns (D103).
[],[only],[a, b],[first, ..._]and[first, ...rest]match anArray<T>or aFixedArray<T, N>inmatcharms andistests. A pattern without...matches exactly its number of elements;...afterkelements matcheskelements or more....appears at most once, as the last element (E0722). Elements are any patterns, literals and alternatives included:[_, "hash", text, output],[_, "help" | "--help"],Some([head, ...tail]),#[[x], y]. Bound elements are read-only copies, like other pattern bindings....reston an Array binds a newArray<T>with the remaining elements (section 6, Copies on shared values);..._copies nothing. On a FixedArray a named rest is an error (E0724), since its type would needN - k: write..._and index the array. A FixedArray pattern of a length that cannot match is E0723; in a generic body overNthe length is tested in each instance. An array pattern on any other type (string,bytes,Map,Range, a generator, a struct) is E0726, and an array pattern inensuresis E0987. For exhaustiveness the lengths are the cases: withLthe largest element count of any arm, they are the lengths 0 toLand "more thanL", and a pattern with...afterkelements covers every length fromk. So[]with[_, _, _, ..._]leaves[_]and[_, _]missing, and the error lists them as patterns (E0714). A FixedArray with a knownNhas one length; one over a genericNneeds an arm that covers every length,[..._]or_.narrac fmtprints an array pattern like an array literal, one element per line when it does not fit, with no trailing comma after a rest. - Unreachable arms (E0983). An arm that the unguarded arms before it already match completely is an error: an arm after
_, a repeated constructor, a repeated literal, or a_after arms that cover every constructor. A guarded arm before the same pattern does not cover it. A guarded arm that is already covered is also an error.narrac apply-fixremoves the arm. matchas a value. In value position (after=, as an argument, an operand or areturnvalue),matchproduces a value. An arm writtenpattern => expressiongives the expression. An arm writtenpattern => { ... }is a block expression (see "Block expressions" in section 2): its value comes fromreturn v, areturninside it ends the arm and not the function,breakandcontinuecannot leave it, and every path must end inreturn. All arms have the same type. Amatchin statement position keeps block-statement arms, wherereturnleaves the function.matchon anOption<T>usesSome(v) =>andNone =>.
Generics
- Type parameters use angle brackets:
function first<T>(items: Array<T>): Option<T>andstruct Entry<K, V> { ... }. - A type parameter can require traits:
<T: Ordered>, or<T: Show & Ordered>for several (see "Traits" below). The type parameters of structs and enums take constraints too:struct Labeled<T: Show> { ... }. Field types and implement blocks see them. Every written use of the type with arguments must meet them, in a type, a struct literal or an enum constructor; a failure is a compile error. A type parameter of the enclosing declaration meets a constraint only when it declares the same trait:function first<T>(pair: Labeled<T>)is an error,function first<T: Show>(pair: Labeled<T>)is not. Constraints are not implied. - Arithmetic operators do not work on a type parameter. Pass a function or require a trait instead.
- Structural equality.
==compares values structurally. The compiler implementsEquatablefor every type that has no function inside it. Using==on a type that contains a function is a compile error. - Hashing.
Hash.of(x)needsHashable. The compiler implements it for every type that has no function or float inside it. - Generic code that uses
==declares<T: Equatable>. Code that hashes declares<T: Hashable>. - Type arguments in a call.
id<int>(1),Mod.pair<int, string>(a, b)andfirst<Array<int>>(xs)give the type arguments of a generic function. They fix the type parameters before the arguments are checked, so an argument that does not fit is an ordinary type mismatch. Write one type argument per type parameter or none; a different count is an error, and so are type arguments on a function that is not generic. A<after a name starts type arguments only when a balanced<...>of type names follows, closed by>directly followed by(. Every name in it that is not followed by.must be a type parameter of the enclosing declaration (so a lowercasetworks), a primitive type (int,f64,bool,char,string,void), or start with a capital letter. A name of two or more characters with no lowercase letter (MAX,LIMIT_2) is a constant, not a type, soa < b > (c)andboth(x < MAX, MIN > (y))are still comparisons. The remaining ambiguity is a value that is capitalized but not SCREAMING_CASE, as inf(x < Limit, Cap > (y)), which reads as a call with type arguments; parenthesize the second comparison,(Cap > y). Single capital letters (T,K,V) are types. An integer literal (3,-1) between the brackets is a constant type argument, whatever the name before<, as in TypeScript:both(a < 3, 4 > (c))is the calla<3, 4>(c), so write the comparison in parentheses,both((a < 3), 4 > (c)). Constructors (Some<int>(1)) and builtin functions take no type arguments; annotate the variable instead, as inconst x: Option<int> = None(). Function types are not accepted inside the arguments. - Constant type parameters.
const N: intin the type parameters of a function or a struct stands for an integer, not a type:function repeat<const N: int>(text: string): string,struct Vector<const N: int> { ... }. Its argument is an integer literal (repeat<3>("ab"),Vector<-1>) or a constant parameter in scope (Vector<N>). A call infers it from the argument types or the expected type like a type parameter (const plane: Vector<2> = zeros()); one that only the body uses must be written. A struct literal does not work it out from its fields:Schedule { hours: [1, 2, 3] }is an error unless an expected type gives it (const plan: Schedule<3> = Schedule { hours: [1, 2, 3] }), so writeSchedule<3> { hours: [1, 2, 3] }. A type argument never computes:Vector<N + 1>is a compile error, and so are a local, a top-level constant or a type where a constant belongs, and a constant where a type belongs (value: N). In the bodyNis anintvalue, known in each instance:total / Nneeds no check, and an instance withNequal to 0 is the usual divisor error, which names the instance and its call. A local or parameter named like a constant parameter is a shadowing error. A constant parameter does not satisfy arequirescondition yet: a call that passesNto a function withrequiresis E0985. Each value is its own instance, sorepeat<2>andrepeat<3>are two functions andVector<2>andVector<3>two types. The kind isintonly for now; the sized integer kinds (const N: u8) may come later. Enums and type aliases take no constant parameters. - Floats follow IEEE 754 in
==.NaN == NaNisfalse. A struct that containsNaNis not equal to itself.
export function contains<T: Equatable>(items: Array<T>, wanted: T): bool {
for (const item of Arrays.values(items)) {
if (item == wanted) {
return true
}
}
return false
}
struct Vector<const N: int> {
values: Array<f64>
}
function dimension<const N: int>(_vector: Vector<N>): int {
return N
}
function share<const N: int>(total: int): int {
return total / N
}
Traits
A trait is a named set of functions that a type implements. A type's traits are all listed where the type is declared.
export trait Label {
function label(value: Self): string
}
export struct Money implements Label, Ordered {
cents: int
}
implement Label for Money {
function label(value: Money): string {
return `${Int.toString(value.cents / 100)}.${Int.toString(value.cents % 100)}`
}
}
implement Ordered for Money {
function compare(a: Money, b: Money): Ordering {
return Int.compare(a.cents, b.cents)
}
}
const text = Label.label(price)
Declaring and implementing
trait Name { ... }declares a trait. Its body lists function signatures.Selfis the implementing type.- A trait has functions only. No fields, no default implementations, no associated types, and no traits that require other traits.
- Implementations live with the type. A struct, enum or distinct type lists its traits with
implements. Each listed trait needs animplement Trait for Type { ... }block in the same module, or aderivesentry. - Generic types. A generic struct or enum is implemented once for all its instances:
implement Show for Pair<T> { ... }names the type with the type parameters of its declaration, by the same names and in order. A concrete type (Pair<int>), a missing list, a wrong count or another name is a compile error, so there is no specialization. The block adds no constraints of its own: its functions see the constraints of the type's declaration, so a member that callsShow.showon a field of typeTneedsstruct Pair<T: Show>. The functions take no type parameters of their own. - No implementations anywhere else. A module cannot implement a trait for a type declared in another module. To add a trait to another module's type, wrap it in a
distinct typeor a struct. derivesasks the compiler to write the implementation:struct User derives Show, Ordered, Shape { ... }.
Calling
- Trait functions are called through the trait name:
Label.label(price). There is noprice.label()form. - In generic code,
<T: Show>allowsShow.show(value)for avalue: T. - A trait function may mention
Selfonly in its result, for examplefunction fromValue(value: Value): Result<Self, string>. A call names the type thatSelfstands for:Shape.fromValue<User>(value). Exactly one type argument is allowed. Without it, the call is an error unless the expected type fixesSelf. In a generic body<T: Shape>,Shape.fromValue<T>(value)is resolved when the body is instantiated.
Trait values
Dynamic<Trait>holds a value of any type that implements the trait.Dynamic.of(value)creates one when the expected type is known.Array<Dynamic<Drawable>>holds values of different types.Drawable.draw(item, mutable canvas)calls the implementation of each item's own type.- Which traits. Every function of the trait takes
Selfas its first parameter, once and not inside another type (Array<Self>does not count), and mentionsSelfnowhere else, the result included. Other parameters may bemutable(mutable canvas: Canvas). SoShow,Hashableand traits likeDrawablequalify, andEquatable,Ordered(twoSelfvalues) andShape(fromValuereturnsSelf) do not. - Layout.
Dynamic.of(value)makes one allocation: a reference-counted cell that holds a pointer to the table of the value's type for the trait, then the value. ADynamicis a pointer to that cell, so a copy is one retain and the value is never copied. The value is read-only: no field of it can be written through aDynamic, which is why the copies can share it:copy(item)copies nothing and is an error, as for astring. A trait function that takesmutable value: Selfcannot be called through aDynamic. - A call through a
Dynamicnames the trait as any trait call does, and its effects are the trait function's declared effects. ADynamichas no==, cannot be a map key and implements no trait, so it does not meet a bound such as<T: Show>: loop over anArray<Dynamic<Show>>and callShow.show(item)on each. In a generic body<T: Drawable>,Dynamic.of(value)withvalue: Tworks.Dynamicis a prelude name, likeBox: a type of the module namedDynamichides it.
Standard traits
| Trait | Purpose | Implemented |
|---|---|---|
Equatable |
== and != |
Automatically for types without functions |
Hashable |
Hash.of, map keys |
Automatically for types without functions or floats |
Ordered |
compare, sorting |
By derives or implement |
Show |
Text for logs, tests and errors | By derives or implement |
Shape |
Conversion to and from the Value tree of std/shape, for serialization |
By the compiler for prelude types, by derives or implement for a struct or enum |
Sendable |
Values that may cross threads (section 6) | Automatically for types without functions, Cell, Async, generators, async generators and the other types section 6 lists; never by implement |
- A type can replace the automatic
EquatableorHashablewith its ownimplementblock. - Primitive types,
string,Array<T>,Map<K, V>,Option<T>andResult<T, E>implement the standard traits when their contents do.
Serialization with Shape
Shape(D84) has two functions instd/shape:toValue(value: Self): ValueandfromValue(value: Value): Result<Self, string>. Formats read and writeValue, soShapedoes not know JSON.Json.encode(value)isJson.stringify(Shape.toValue(value)).Json.decode<User>(text)isJson.parse(text)followed byShape.fromValue<User>; a parse error is passed through.- The compiler provides
Shapeforbool,int,f64,char(as a one-characterText),string,Array<T>,Map<string, V>,Option<T>(NoneisNull) and tuples of two to four items (aList), when their contents implement it.Valueimplements it as itself. AMapwith other keys, a function type, a sized integer and a longer tuple do not: E0530 names the type that fails. A struct or enum derives it (derives Shape) or listsimplements Shapeand writes animplement Shape forblock. - Decoding is strict on types and ignores extra data:
intaccepts onlyValue.Int,f64acceptsIntandFloat. An error reads<path>: <reason>from the root, as in.users[2].age: expected int, found Text; at the root it is the reason alone. derives Shapewrites the implementation. A struct is aRecordwith one entry per field, in declaration order; a field of typeOption<T>holdingNoneis left out, asJSON.stringifyleaves outundefined. AnOptionfield whose default is notNone(hint: Option<int> = Some(5)) writesNoneasNullinstead, so that it does not decode as its default. Decoding a struct gives a missing field its default (age: int = 0) and a missingOptionfieldNone, and decodesNullin anOptionfield asNone; any other missing field is an error (.age: missing field). Unknown fields are ignored.- An enum is a
Recordwith a"type"entry naming the constructor, then one entry per field, as a TypeScript discriminated union:{"type":"Circle","radius":1.0},{"type":"Empty"}. A missing, non-text or unknowntypeis an error naming the enum. A constructor field namedtypewould clash, so derivingShapeon such an enum is E0532. - Every field type must implement
Shape(E0531 names the field and its type). A generic type derivesShapefor the instances whose type arguments implement it, asderives Showdoes. Recursive enums (D55) derive it too. - The derived
Shapeof anexport opaque structbuilds and reads its fields, so only the declaring module may use it; aShapecall or aT: Shapebound on it in another module is E0533.
Inference
- Types of variables are inferred.
const n = 1isint. - Function parameters and return types are written for every named function. Arrow functions passed as arguments are the exception. Their types come from the parameter they are passed to.
- Other modules type-check against exported signatures only. They never read function bodies.
Numbers
- Integer overflow wraps in every build (D92).
+,-,*and unary-wrap at the width of the type. The operators+%,-%,*%and their compound forms do not exist. - Checked arithmetic.
Int.addChecked(a, b),subCheckedandmulCheckedreturnNonewhen the result does not fit, and the same functions exist instd/i8tostd/u64(U8.addChecked(a, b)). - Integer division or remainder by zero panics in every build.
MIN / -1givesMINandMIN % -1gives 0. - Sized integers (D82).
i8,i16,i32,u8,u16,u32andu64are separate types of that width;i64is the same type asint. All of them implementEquatable,Hashable,OrderedandShow, and work as map keys, fields, tuple elements, enum fields and generic arguments.Array<u8>stores one byte per element. - Literals take the type the context expects (an annotation, a parameter, a field, an element, a return type, the other operand, a literal pattern), and
intwhen nothing is expected. A literal must fit its type:const x: u8 = 256andconst y: u8 = -1are E0294.-128is a validi8. - There is no implicit conversion. Arithmetic, comparison and bitwise operators need operands of the same type;
u8 + i32is E0295, and the message names the conversion functions. Unary-on an unsigned type is E0296. Shift counts have the type of the value shifted. - Divisors and shift counts are proven (D92). Integer
/,%,/=and%=compile only when the divisor is a non-zero constant (a literal, a negated literal, or a top-levelconstwhose value is one) or a local integer narrowed by a check in the same function:!= 0,> 0,< 0,>= 1,== 3and the like, joined by&&, or by||on the failing side, and negated by!. A||that holds (or an&&that fails) gives the hull of its sides when every side compares the same local with a constant: inif (d < 0 || d > 0)thethenbranch knowsdis non-zero; any other||gives nothing, and on a u64 a side with a bound from 2^63 up gives nothing. A check between two integer locals of the same type (if (index < count)) records a relation between them, which ends when either is assigned, and passes bounds one step: withindex < countandcount <= 63,indexis at most 62. Relations do not chain (a < bandb < csay nothing aboutaandc), and on a u64 an end from 2^63 up is not passed on. Anything else is E0979, and the message says what to add. A shift count (<<,>>,<<=,>>=) must be a constant from 0 to the bit width minus 1 (63 forint), or a local checked at both ends (n >= 0 && n < 64); an unsigned count needs only the upper bound. Anything else is E0980. Float division is unchanged. The emitted C and the runtime have no division or shift panic:MIN / -1isMIN,MIN % -1is 0. - What a check proves. A check narrows in the
thenbranch of anif(theelsebranch gets the opposite), in the body of awhile, in the right operand of&&(||gets the opposite), and after anifwhosethenbranch ends inreturn,break,continueor a panic. A narrowing ends at an assignment to the name (n = ...,n += 1,n++), at a call that passes the name asmutable, and at the start of a loop that does either; a new check narrows again. A name that an arrow function captures by reference is not narrowed inside the arrow function. Only a plain local name narrows: a field or an element (size.count,counts[i]) and any other expression (n + 1,Arrays.length(items)) do not, so copy the value into a local first and check the local. A constant is a literal, a negated literal, a top-levelconstwhose value is one, or aconstlocal that was set from one (const items = 7). - Overflow wraps at the type's own width:
u8200 + 100is 44 andi8-128 - 1is 127, in every build. - Conversions are explicit functions named after the target type, in one module per type (
I32.from(x),I32.tryFrom(x),I32.wrap(x); modulesstd/i8tostd/u64;std/intservesi64), andFloat.fromInt(x),Float.truncate(f).fromis for conversions where every value fits,tryFromreturns anOption,wrapkeeps the low bits. Each of the seven modules also hastoString(x)andparse(text, base), andstd/inthasfrom,tryFromandwrap.X.from(v)takes any integer type whose every value fitsX; another integer type is E0940 and a value that is not an integer is E0941.tryFromandwraptake any integer type.parseisInt.parsewith the range of the type in its error text. A literal argument is anint, soI32.from(5)is E0940; writeconst x: i32 = 5. f32is a 32-bit float (Cfloat) besidef64. A float literal takesf32when the context expects it andf64otherwise; an integer literal never becomes a float. A literal too large to be finite inf32is E0297.f32andf64do not mix in arithmetic or comparison (E0295).f32implementsEquatable,OrderedandShow(the shortest text that reads back as the samef32) but notHashable, so it is not a map key.F32.from(v)takes anf64(rounds to nearest) or any integer type,F32.truncate(v)gives anOption<int>(Nonefor NaN or a value outsideint),F32.toString(v)a string (modulestd/f32), andFloat.from(v)takes anf32(exact) or any integer type. Another argument type is E0941.- Float text.
Float.toString,F32.toString,Showand template holes print a float as the shortest digits that read back as the same value. Values from1e-7up to below1e21use plain notation and others an exponent (0.1,1.5e-7,1e+21,1.7976931348623157e+308). A whole number keeps.0(20.0,-0.0), so a float never prints like an integer. NaN printsnanand the infinitiesinfand-inf.
Strings
stringholds valid UTF-8. Functions that build a string from bytes returnResultand fail on invalid UTF-8.- Positions are byte offsets of type
ByteIndex, starting at 0.ByteIndexis declared asexport opaque distinct type ByteIndex = u64, so onlystd/stringcan create one. - Positions come from the string.
Str.indexOf,Str.findand iterators returnByteIndexvalues that always fall on a character boundary. - Slices share memory.
Str.sliceandArrays.slicereturn a view into the original buffer, with no copy. The view keeps the whole buffer alive. Usecopy(...)(section 6, Copies on shared values) to keep a small part of a large buffer without keeping the rest. - Slicing checks boundaries.
Str.slice(s, from, to)returns bytesfromup to but not includingto. It returnsNonewhen a position is not on a character boundary, is out of range, orfromis afterto, andSome(text)otherwise. Str.length(s)is the byte length asByteIndex.Str.charCount(s)counts characters and takes time proportional to the length.- Grapheme clusters, case mapping and display width are in
std/unicode(D118, section 3):Unicode.graphemeCount("e\u{301}")is 1 whereStr.charCountis 2.Unicode.normalize(text, NormalForm.NFC)gives one spelling of text that can be written with different code points.
Bytes
bytesis an immutable byte sequence with no UTF-8 guarantee. It has the representation ofstring, soBytes.fromString(text)shares the buffer, andBytes.toString(data)shares it too when the bytes are valid UTF-8. Otherwise it returnsErr("invalid UTF-8 at byte N"), with the offset of the first bad byte.std/bytes(aliasBytes):fromString(text): bytes,toString(data): Result<string, string>,length(data): int,at(data, index: int): Option<u8>,slice(data, start: int, end: int): Option<bytes>,concat(left, right): bytes,fromArray(items: Array<u8>): bytesandtoArray(data): Array<u8>.atandslicereturnNoneout of range.slicecopies the bytes.std/fshasreadBytes(path): Result<bytes, string>andwriteBytes(path, data: bytes): Result<int, string>, which work asreadTextandwriteTextwithout the UTF-8 check.bytesimplementsEquatable,Hashable,Ordered(bytewise, a prefix first, and<works as on strings) andShow, which writes hex pairs:bytes[68 69 0a]. It works as a map key. It is not a contents type, so amutableparameter cannot have it.
export struct Pair {
key: string
value: string
}
export function parsePair(line: string): Option<Pair> uses alloc {
const found = Str.indexOf(line, "=")
if (found is None) {
return None
}
const i = found.value
const key = Str.slice(line, 0, i)
if (key is None) {
return None
}
return Some(Pair {
key: Str.trim(key.value),
value: Str.trim(Str.sliceFrom(line, Str.nextChar(line, i))),
})
}
5. Errors
- Errors are return values. A function that can fail returns
Result<T, E>, with constructorsOk(value)andErr(error). - The caller checks the result. There is no
try, nocatch, nothrowand no operator that returns early. Every error path is a visibleiformatch. istests a pattern and narrows the type. Afterif (r is Err(e)) { return ... }, the compiler knowsrisOk.r.valuethen reads the value. The same narrowing works forOption<T>withNone.std/resulthelpers.import * as Results from "std/result"addsResults.map(r, f),Results.mapErr(r, f),Results.andThen(r, f)(freturns aResultwith the same error type),Results.withDefault(r, fallback), andResults.ok(r)andResults.err(r), which return theOkorErrvalue as anOption. They work on a value you already hold. They never return from the caller, so they do not replace the visibleiformatchon the error path; they transform a result or give it a fallback.- Ignoring a
Resultis a compile error. Discard one on purpose withconst _ = f(). - Panics abort the program.
panic("message"), failedassert, and out-of-bounds indexing all panic. A panic cannot be caught. - Std functions that cannot handle their input return
Option(D92). None of them panics. Each has one way to fail, soNonesays all there is to say.
| Function | Result | None when |
|---|---|---|
Str.slice(text, from, to) |
Option<string> |
a position is out of range or inside a character, or from is after to |
Str.split(text, separator) |
Option<Array<string>> |
the separator is empty |
Str.repeat(text, count) |
Option<string> |
count is negative |
Bytes.at(data, index) |
Option<u8> |
index is out of range |
Bytes.slice(data, start, end) |
Option<bytes> |
the range is out of bounds |
Float.truncate(value), F32.truncate(value) |
Option<int> |
value is NaN or outside int |
Arrays.filled(value, count) |
Option<Array<T>> |
count is negative |
Math.clamp(value, low, high) |
Option<T> |
low is greater than high |
Math.powInt(base, exponent) |
Option<int> |
exponent is negative |
Random.nextInt(mutable random, low, high) |
Option<int> |
low is not below high |
- Std panics that remain.
Str.sliceFrom,Str.charAtandStr.nextCharstill panic on a position that is out of range or inside a character, and array indexing keeps its panic. They are not yet converted. Maps.update(mutable map, key, initial, change). Setsmap[key]tochange(old), whereoldis the current value, orinitialwhen the key is missing.changeis a function from the value type to the value type.
export function readConfig(path: string): Result<Config, ConfigError> uses io, alloc {
const text = File.readText(path)
if (text is Err(e)) {
return Err(ConfigError.IoFailed(e))
}
const config = Config.parse(text.value)
if (config is Err(e)) {
return Err(e)
}
return Ok(config.value)
}
6. Memory model
Values and ownership
- Every value has one or more owners: variables, fields, array slots, closure captures.
- Boxed values (arrays, maps, strings, closures,
Box<T>and recursive enums) live on the heap with a reference count. Numbers,bool,char, structs and enums that do not contain themselves and are at most 32 bytes live inline. - A struct that holds boxed fields counts those fields, not itself. Copying the struct increments the count of each boxed field. An inline enum is the same: copying it increments the count of each boxed field of its variant.
- An enum is stored on the heap when a variant field contains the enum again through structs and enums held by value (an expression tree), or when its largest variant is over 32 bytes. Fields behind an
Array,Map,Boxor function do not count.Some(1),Ok(x)andErr(e)of a small type allocate nothing. Box<T>puts a value on the heap with a reference count. Use it for recursive structs and for large structs that are passed around often.- The compiler inserts reference count increments and decrements. It removes the ones it can prove unnecessary, as in Koka's Perceus.
- A value is freed when its count reaches zero. File handles, sockets and other resources close at the point their last owner drops them.
- Large frees can be spread out. When a large structure is freed, the runtime may release its memory in small batches during later allocations. Resources still close immediately. Only the return of memory to the allocator is delayed.
- Running out of memory aborts the program, the same as a panic.
In-place updates
items[i] = v,m[k] = v,Arrays.push(mutable items, v)andu.age = vchange a local variable,constorlet.{ ...u, age: v }returns a changed copy.- When the reference count of the old value is 1, the compiler writes into it instead of copying. This is called reuse.
- Code that keeps one owner gets in-place mutation with no copies.
let squares: Array<int> = []
if (Arrays.filled(0, 1000) is Some(zeros)) {
squares = copy(zeros)
}
for (const i of Ranges.upTo(1000)) {
squares[i] = i * i // the count is 1, so the write is in place
}
items[i] = vandu.age = vrequire the target to be a localconstorlet, amutableparameter, or a field or element of one. A plain parameter and a top-level constant cannot be changed. Pattern,for (const ...)and destructured bindings are read-only; afor (mutable item of items)binding can be changed and changesitems(section 2, Control flow).
Copies on shared values
When an update targets a value whose reference count is greater than 1, the value is copied first. The copy is correct, but it costs time proportional to the value's size, and the source does not show it. copy(x) makes the copy visible (D94):
copy(x)duplicates a value at any depth. At the call it is one reference count increment, so it costs nothing until a write. A later write toxor to the copy then copies only the objects on the written path, once each: afterconst other = copy(team),other.scores[1][0] = 30copies the outer array ofother.scoresand one row, not the other rows.copytakes one argument of a type that a write changes in place: a struct (all-scalar ones too),Array<T>,Map<K, V>,FixedArray<T, N>,Box<T>,StringBuilder,Generator<T>orCoroutine<In, Out>, a tuple holding one of them, a distinct type over one, or a type parameter. It also takes an enum whose payload can hold one of them, at any depth (Option<Array<int>>,Result<Team, string>, a recursive enum with a struct payload). An enum value itself is never changed in place, but a part taken out of its payload can be: the copy retains the payload. A part taken out of the copy still shares the original's part while the copy is held, so changing it takes acopy(...)of the part, which then copies only that part. Any other argument (numbers,bool,char,string,bytes, enums whose payloads hold only such values, function values) is a compile error whose fix removes the call, and so are a second argument andcopy(mutable x)(E0975).- A named rest copies (D103).
[first, ...rest]on anArray<T>buildsrestas a new Array of the remaining elements, each retained: likeArrays.slice, it costs time linear in the tail and one allocation each time the pattern matches. A recursive[first, ...rest] => sum(rest)is therefore quadratic in the length; walk an index instead when the array is long...._copies nothing. copyis a prelude function, not a keyword. A local or parameter may be namedcopy, as one may be namedpanic; inside its scope a callcopy(x)then calls the local. A top-level function namedcopyis never called: the prelude'scopyis found first.- The debug copy check. A debug build run with
NARRA_CHECK_COPIESset counts every copy on write of an array, map,Box,StringBuilderor generator, and at exit reports the ones that nocopy(...)explains, with exit code 103, like the leak check (D80):copy check: copies on write that no copy(...) explains: array 2. Eachcopy(x)gives the objects it shares one credit, a copy on write uses one credit of the object it copies and gives one to each object the two copies now share, and a credit ends when the object's count falls back to 1. So at most one hidden copy percopy(...)call goes unreported. The copy thatfor ... ofandyield*make of a generator they do not own (section 8) counts as explained. The credits a copy of a heap enum gives the parts of its payload end when the last holder of that copy is released, and all of them when the payload box is freed. All-scalar structs live inline and never copy on write; the compile-time shared-write rule covers them. Release builds have no credits and no hooks.
const scores = [[1, 2], [3, 4]]
let other = copy(scores)
other[1][0] = 30 // copies the outer array and one row; scores is unchanged
Arrays.push(mutable other, [5, 6])
A copy of an enum with a tracked payload:
const found: Option<Array<int>> = Some([1, 2])
const kept = copy(found)
if (kept is Some(items)) {
let list = copy(items)
list[0] = 9 // copies this array only; found and kept still hold [1, 2]
}
const slot = Slot.Filled(Row { cells: [3, 4] })
const other = copy(slot)
if (other is Slot.Filled(row)) {
let edited = copy(row)
edited.cells[0] = 5 // copies the cells of this row only
}
An enum whose payloads hold only scalars and strings has nothing to copy:
const count: Option<int> = Some(3)
const same = copy(count) // E0975: remove the call
Renames
A second name for a value that changes in place is a compile error (E0971, D124). const b = a, let b = a and b = a, where a is a bare name and its type is a struct, Array, Map, FixedArray, Box, StringBuilder or generator, would name one array or struct twice, and a write through one name would not show in the other. Use a, or copy(a) for a value of its own; narrac apply-fix writes the copy.
const prices = [100, 200]
const synonym = prices // E0971: synonym would be a second name for prices
A tuple counts when one of its elements does. A name of a number, bool, char, string, bytes, an enum, a tuple of those or a function value can be renamed, since none of them changes in place. Reading a field or an element (const items = bag.items), passing an argument and keeping a result are not renames; the rules below cover them. A top-level const ALIAS = TABLE and a destructuring declaration are not checked.
Shared writes
A write to a place is a compile error while another name that is still used shares that place, a place that contains it or a place inside it (E0978, D94). Without the rule the write would copy the value, and the source would not show it. Sharing starts where a value is read into a second name and ends when that name is no longer used:
let bag = Bag { items: [1, 2], count: 0 }
const items = bag.items
bag.items[0] = 9 // E0978: items still shares bag.items
const seen = items[0]
copy(...) around the value that started the sharing is the fix (const items = copy(bag.items)), and narrac apply-fix writes it. The write then copies nothing at the write:
let bag = Bag { items: [1, 2], count: 0 }
const items = copy(bag.items)
bag.items[0] = 9
const seen = items[0] + bag.items[0] // 1 + 9
- What writes. An assignment to a field or element,
Arrays.push(mutable items, v)and any othermutableargument. Passingmutable RwritesRand everything below it. A non-escaping closure that writes a capturedconstwrites it where the closure is passed. All-scalar structs are checked too, though they live inline and a write never copies them. - What shares. A
constorletinitialized from a field or an element, an assignment of one, a pattern, destructured orfor (const ...)binding, a struct, array, tuple or map holding the place, the result of a call whose callee hasfromfor that argument (above), and a function value made from an arrow function, which shares what it captured: calling it uses those values. A parameter, a top-level constant, aCelland a value read from an identity type count as used for the whole body, so a write to the value they share is an error at once.copy(x)shares nothing. Sharing runs in both directions and through chains: afterconst b = a.items; const c = [b], a write toa.items,borcis checked against the other two. - When it ends. Assigning a local or a field path (
bag = other,bag.items = []) ends its sharing; assigning an indexed place (rows[0] = x) does not. Liveness is checked inside one function body: the error names the later use. Aconstorletholds its value until its block ends, so a write after its last use is still an error when the write would copy an array, map,Box,StringBuilderor generator it holds; the error then names the end of the block (D104). A write that copies nothing is accepted after the last use: a field of a struct of numbers, or amutablecall on a struct that holds the shared value only inside an enum, whose payload is not a place. An enum built from a place holds that place's value like any other value: afterconst held = Some(bag.items),Arrays.push(mutable bag.items, 4)is an error untilheld's block ends. A destructuringconstorletholds its fields the same way. Aconstorletinitialized withcopy(...)holds its value the same way: a part taken out of it shares the original until its block ends. The bindings of anisor amatchon a value that is not a place (a call result, a constructor) hold it until theifblock or the arm ends, and so does afor (const ...)binding over such a value until the body ends; bindings of a place end at their last use, since the place keeps the value. While afor ... ofloop other thanfor (mutable ...)runs, its iterator holds the place it walks, so a write to that place in the body is an error; loop overcopy(items)or write after the loop. - Which index places are the same. Two different integer literal indexes name different places:
const first = rows[0]; rows[1][0] = 4is accepted. Every other index may name any element, so an identifier or other expression (rows[i]androws[j],rows[i]androws[0]) and a map key match every element and the other indexes. The same literal index is one place, and assigning it does not end its sharing (a known false positive:let row = grid[0]; grid[0] = [9]; row[0] = 5is reported whilegrid[0]is used later). - Known gap: a part of a temporary copy of a heap enum.
copy(x)shares nothing, solet row = takeLeftRow(copy(tree))is not paired withtree. The temporary copy ends with the statement and takes its credits back, so a later write torowcopiestree's part without acopy(...)that explains it. The debug copy check reports it. Takecopy(...)of the part instead. - Known gap: stores into a
mutableparameter. A function that assigns a value sharing one parameter into amutableparameter (into.items = other.items) leaves the caller's two arguments sharing after the call, and no rule sees it. Storecopy(other.items). The debug copy check reports the copy. - Known gap: shared elements. Elements that share one value are not tracked.
Arrays.filled([0, 0], 3)and[row, row]make an array whose elements share one inner array, so a write togrid[0][0]through a name that holds it is accepted and copies at run time. The debug copy check reports it. - Where it runs. Every command that checks a package (
build,run,test,emit,check,apply-fixand the language server), also when the package has other errors. A write that another error already points at is reported once.
let rows = [Row { cells: [1] }, Row { cells: [2] }]
const first = rows[0]
rows[1].cells[0] = 4 // accepted: rows[0] and rows[1] are different places
const seen = first.cells[0] + rows[1].cells[0]
Shared results
A function whose result shares a parameter says so with from <parameter> after the result type (D94). Nothing is inferred across functions: a call's result shares one of its arguments only when the callee's signature or function type has from, so a caller sees it in the signature.
function firstItem(items: Array<SortItem>): SortItem from items {
return items[0]
}
function lastItem<T>(items: Array<T>): T from items {
return items[Arrays.length(items) - 1]
}
- What shares. A returned value shares a parameter when it is the parameter, a field, element or narrowed payload of it, a local, pattern or
for ... ofbinding that took such a value, a struct, array, tuple, map or constructor holding one (a spread{ ...base }holds only the fields ofbaseit does not write), or the result of a call whosefromnames an argument that shares it. A local also takes the values assigned to it and the values passed beside it when it is amutableargument. A value whose type holds no struct, array, map,Box,StringBuilder, generator or type parameter (numbers,bool,char,string,bytes, enums without such payloads, function values) shares nothing.copy(x)is unshared. - The check (E0976). Returning a value that shares a parameter the marker does not name is an error. Without a marker the fix adds
from <parameter>; with a marker that names another parameter, the fix wraps the value incopy(...). Afromthat names no parameter is also E0976. - Generic results.
from itemscovers the whole parameter and everything reached through it, at any depth, whatever the type arguments are: a result of typeTtaken out ofitems: Array<T>sharesitems. WhenTis a scalar type the marker is allowed and changes nothing. - Arrow functions. An arrow function whose result shares one of its own parameters writes
fromafter its result type:(row: Row): Array<int> from row => row.cells. An arrow function that writes nofromtakes thefromof its expected function type, as it takes its parameter types, so(row) => row.cellsfits a(row: Row) => Array<int> from rowslot. When the expected type has nofrom, or the arrow function writes no result type, a result that shares a parameter is E0976 with a fix that wraps the value incopy(...).fromnames only a parameter, never a capture: an arrow function whose result shares a captured value is E0976, and the fix wraps the value incopy(...). - Function types.
fromis part of a function type, likeuses(section 7), and names one of the type's parameter names:(grid: Grid) => Array<int> from grid uses alloc.fromcomes beforeuses. A function with a fresh result fits a slot whose type hasfrom; a function withfromdoes not fit a slot without the samefrom(E0977), unless the result holds no tracked value. The fix adds the marker to the slot's type, naming the parametersourcewhen the type writes no name for it. A type printed by the compiler names the shared parametersource:(source: Grid) => Array<int> from source. - Trait functions. An implementation may leave out the
fromits trait function has, but may not add one the trait function lacks. - Generators are not checked: a generator's result is the generator.
struct Picker {
pick: (grid: Grid) => Array<int> from grid uses alloc
}
function firstRow(grid: Grid): Array<int> from grid {
return grid.rows[0]
}
function rowSizes(grid: Grid): Array<int> uses alloc {
return [Arrays.length(grid.rows)]
}
function listPickers(): Array<Picker> uses alloc {
// A fresh result fits the `from` slot too.
const second = (grid: Grid): Array<int> from grid => grid.rows[1]
return [Picker { pick: firstRow }, Picker { pick: rowSizes }, Picker { pick: second }]
}
Mutable parameters
A function changes a caller's data only through a mutable parameter. The keyword appears in the declaration and again at the call. A mutable parameter reaches the contents of the caller's value, its fields and elements, and never the caller's variable (D81).
function damage(mutable player: Player, amount: int) {
player.hp = player.hp - amount // ok: changes a field
player = { ...player, hp: 0 } // compile error: a mutable parameter cannot be replaced
}
const hero = Player { name: "Ana", hp: 100, position: Vec2 { x: 0.0, y: 0.0 } }
damage(mutable hero, 10) // hero.hp is now 90
function bump(mutable n: int) { // compile error: int has no contents to change
n = n + 1
}
- The parameter's type has contents. A
mutableparameter must have a contents type: a struct (anopaque structtoo),Array<T>,FixedArray<T, N>,Map<K, V>,Box<T>,StringBuilder,Generator<T>, orCoroutine<In, Out>. Any other type is a compile error at the parameter: numbers,bool,char,string,bytes, distinct types, enums (OptionandResultincluded), tuples, function types, the preludeRange,Sender,Receiver,SharedandAtomic. To give a new scalar or enum back to the caller, return it, or keep it in a field of a struct passed asmutable. - Generic parameters.
mutable value: Twith a bare type parameterTis a compile error, whatever its constraint: no trait guarantees a contents type. A generic instance of a contents type is fine:mutable items: Array<T>. In a trait,mutable value: Selfis allowed, everyimplementof the trait must be for a contents type, and aDynamic<Trait>cannot be passed to such a function. - The callee changes contents, never the parameter. Through a
mutableparameter the callee may assign fields and elements at any depth, call std functions that change contents (Arrays.push,Maps.set,Str.append,Co.resume), and pass the value or a part of it on asmutable. Assigning the parameter itself (player = other,count += 1) is a compile error. - The argument is a local place. It must be a local binding that holds a contents type, or a field or element path of one: a
const, alet, or amutableparameter. A literal, a call result, a plain parameter and a top-level constant are compile errors. Pattern,for (const ...)and destructured bindings are read-only copies and are compile errors too; afor (mutable item of items)binding can be passed (D85). Passing aconstasmutableadds nothing that direct code lacks, since its fields can be assigned directly (section 2, Bindings). - Access is exclusive during the call. A variable cannot be passed as
mutabletwice in one call. It cannot be passed asmutableand also read in another argument.swap(mutable a, mutable a)andmove(mutable p, p.x)are compile errors. - A
mutablevariable is not used elsewhere in the same expression. Within one statement's expression, a variable passed asmutablecannot also be read, assigned or passed again anywhere else, at any depth, including fields and elements of it.p.hp + heal(mutable p)andpair(p, heal(mutable p))are compile errors. Bind the call first:const healed = heal(mutable p), thenp.hp + healed. Twomutablecalls on different variables are fine, and so are the two sides of&&and||and different arms of amatch. These rules hold for every binding passed asmutable,constincluded. - A
mutableparameter cannot escape. It cannot be stored, returned, or captured by a closure that is not passed straight to a non-escaping parameter (D77). Copying its value withcopy(player)is allowed. - No copies. The compiler passes a pointer to the caller's value. Changes are written in place, with no copy and no reference count change for the value itself. A value shared with other owners is copied on its first change, as in any in-place update.
- Other parameters are values. A parameter without
mutableis a read-only copy: its fields cannot be assigned, and it cannot be passed asmutable. To build new data instead of changing the caller's data, return a new value. - Enums and tuples are replaced, not changed (D81). A struct inside an enum payload or a tuple is not a place: enum fields are fixed and tuples have no element assignment. A field that holds one is assigned whole:
state.current = Some(next). To change a struct held in anOption, read it withis, build the changed copy, and store it back. Amutablemarker in a pattern (x is Some(mutable y)) does not exist (D85).
| Goal | Form |
|---|---|
| Change the caller's data | damage(mutable hero, 10) |
| Build new data | const stronger = withBonus(hero, 5) |
| Give back a new number | count = bumped(count) |
Cycles
- Immutable values cannot form cycles, so reference counting frees everything without a cycle collector. Storing a value inside itself holds a second reference to it while the write runs, so the write copies first.
- A variable is never stored by reference: storing it stores a copy, and only a closure that cannot outlive the call captures a variable by reference, so no cycle forms.
- Cycles through identity types leak (D80). Identity types (
Shared<T>,Sender<T>,Receiver<T>,Async<T>andCell<T>; section 8) are handles to one object, so they can form a cycle. There is no cycle collector and no type rule against it. Memory safety holds, but the objects in the cycle are never freed and resources they hold never close. Every cycle passes through an identity object, so the debug leak check (NARRA_CHECK_LEAKS, section 13) reports it at exit, and a test that leaks fails. Two patterns leak:- A handle stored in its own payload:
Shared.update(state, ...)that storesSome(state)in the value ofstate, or aSendersent into its own channel. - A closure stored in a
Cellthat captures the sameCell.
- A handle stored in its own payload:
- Breaking a cycle. Clear the slot before the last outside handle is dropped (
Cells.set(cell, None)), or keep the graph instd/arenaand refer to its nodes with handles. - A later version may add a collector limited to identity objects. It would only free memory that this rule leaks, so no program changes meaning.
- Graphs use
Arena<T>andHandle<T>fromstd/arena(D118). A handle is an index plus a generation number.Arenas.get(arena, h)returnsNonewhen the slot was freed or reused. Handles can point anywhere in the arena, including in cycles, and the arena frees all its slots at once. A handle from a different arena is not detected.
Values across threads
- Only
Sendablevalues cross threads.Sendableis an automatic trait: the compiler implements it for every type that holds none of these, at any depth: a function type,Dynamic<Trait>,Ptr<T>,Cell<T>,Async<T>,Generator<T>,AsyncGenerator<T>,Coroutine<In, Out>,Scope,Thread<T>, and the sockets ofstd/net.Shared<T>,Sender<T>,Receiver<T>andAtomic<T>areSendable. A capture of a thread function, a thread result, and the type argument ofChannel.create,Shared.createandAtomic.createmust beSendable(E1190). Generic code declares<T: Sendable>.implement Sendableis a compile error (E1194). - A value captured by a thread function, sent through a channel or stored in a
Sharedis marked shared. Shared values use atomic reference counts. Unshared values use plain counts. Only a program that importsstd/thread(or a module built on it) has shared values; any other program uses plain counts throughout. - An in-place update on a shared value copies first, so threads never see each other's writes.
- Safe code has no shared mutable memory, so no data race is possible. Section 8 covers threads, channels and the few types that are shared on purpose.
7. Effects
An effect marks something a function can do beyond computing a value. The set is fixed:
| Effect | Meaning |
|---|---|
alloc |
May allocate heap memory |
io |
May perform input or output, read the clock, or read the environment |
unsafe |
Calls code that the compiler cannot check (section 9) |
Rules:
- Exported functions declare their effects after the return type:
function f(s: string): int uses alloc { ... }. - The compiler infers effects for private functions and arrow functions. A private function that writes a
useslist is checked against it, as an exported one is. - A function's effects include the effects of everything it calls. Calling an
iofunction from a function that does not declareiois a compile error. - Panics are not an effect. Any function can panic.
- The entry function (section 15) has every effect. It may be
async(section 8). asyncandfunction*are not effects. They mark the type of function a declaration is (section 8).- Function types carry effects (D86):
(v: int) => int uses io. A call through a function value has the effects of its type, and a function cannot be stored where the type lists fewer effects than it has. A function value's own type lists none, so a top-level constant that holds a function with effects writes its type:const step: (v: int) => int uses io = loud. - Generator types carry effects (D78), as function types do:
Generator<string> uses iois a generator whose body does I/O when it runs.Generator<T>alone is pure. The effects are charged where the body runs: afor ... ofover the generator, ayield*of it,Co.resumeandCo.send. Creating a generator charges onlyalloc, for its frame. - A generator value may be used where a generator type with more effects is expected, not fewer: passing a
Generator<T> uses iowhereGenerator<T>is expected is a compile error. - A
useslist inside a type (D117) takes one effect, or a comma list in parentheses:() => int uses io,() => int uses (io, alloc),Map<Generator<int> uses (io, alloc), int>. A,after the one effect ends the type, so it can be followed by another type argument, tuple element or parameter, or by a trailing comma. A function declaration's own list, after its result type, is a bare comma list without parentheses:function f(): int uses io, alloc. A comma after a result type's one effect is an error (E1240):function* lines(): Generator<string> uses io, alloc {must be writtenGenerator<string> uses (io, alloc). An effect name in a type position is an error (E1241). Types in messages and tools are printed in the same form, andnarrac fmtwritesuses (io)asuses io.
Effect variables
A function that calls a function it receives has that function's effects. An effect variable states this in a signature.
export function map<T, U, effect E>(items: Array<T>, f: (item: T) => U uses E): Array<U> uses alloc, E
- Effect variables are declared in the type parameter list with the
effectkeyword, and appear only afteruses. - They are bound by a parameter. An effect variable in the function's own
useslist must also appear in a parameter's function type or generator type:export function sum<effect E>(numbers: Generator<int> uses E): int uses E. - At each call, the variable takes the effects of the function or generator passed in.
map(names, Str.length)hasalloc.map(paths, File.readText)hasalloc, io. A generator result type that names the variable takes them too: withrelay<effect E>(g: Generator<int> uses E): Generator<int> uses (E, alloc),relay(lines(path))is aGenerator<int> uses (alloc, io). - A function used as a value keeps its variables (D91). After
const apply = twice,apply(loud, 1)has the effects ofloud, astwice(loud, 1)does, through a top-level or a local constant.
8. Generators and concurrency
Narra has three tools. Each covers one type of concurrent work:
| Work | Tool |
|---|---|
| Produce values one at a time, on demand | Generators |
| Run computations in parallel on several cores | Scoped threads and channels |
| Wait on many I/O operations at once | Async functions on an event loop |
| Produce values one at a time that need I/O | Async generators |
A panic on any thread or task aborts the whole program.
Generators
A generator is a function that can suspend itself with yield and be resumed later. The syntax is TypeScript's. The compiler turns each generator into a state machine, so no separate stack is allocated.
function* counter(limit: int): Generator<int> {
for (const i of Ranges.upTo(limit)) {
yield i
}
}
function* evens(limit: int): Generator<int> {
for (const n of counter(limit)) {
if (n % 2 == 0) {
yield n
}
}
}
function* both(): Generator<int> {
yield* counter(3)
yield* evens(10)
}
for (const n of both()) {
print(Int.toString(n))
}
function*declares a generator. Calling it returns aGenerator<Out>without running any of its body. A generator is a top-level function (D74), andexport function*exports it asexport functiondoes. There is no arrow form. The return type is required and must beGenerator<T>orCoroutine<In, Out>. Generic generators are allowed.yield valuesuspends the generator and producesvalue, which must have typeT.yieldis a statement, not an expression. It is valid only directly inside afunction*body or its nested statement blocks (if,while,for, labeled loops,matchstatement arms). It is not valid in an arrow function, a block expression, a conditional expression or amatchused as a value.yield* otherproduces every value of another generator in turn.othermust be aGenerator<T>with the sameT.returnin a generator takes no value. It ends the generator, as falling off the end of the body does.- A generator outlives the call that creates it. It cannot take a
mutableparameter, and its function-type parameters must beescaping. - Effects (section 7, D78). An exported generator writes the effects of its body on its return type:
export function* lines(path: string): Generator<string> uses (io, alloc). A private one gets them inferred into its type. A body that uses an effect its declared type omits is a compile error. - Calls of generator functions are not recursion. A generator that calls itself, directly or through another generator, creates a new value, so D37 and tail loops do not apply.
Coroutine<In, Out>(D79) is a generator that also receives a value on each resume. It is a separate type fromGenerator<T>: declare it withfunction*and the return typeCoroutine<In, Out>, as infunction* total(): Coroutine<int, int>. Inside it,const input = yield outputyieldsoutputand, when the coroutine is resumed, binds the value passed toCo.send. Theyieldwith a value is valid only in a coroutine, and only as the initializer of aconstorletthat names one variable and has no type annotation; a plainyield outputstatement is also valid and drops the input. The input of the first resume is dropped, as in TypeScript, because noyieldis waiting for it.yield*is not valid in a coroutine, andfor ... ofover a coroutine is a compile error (a loop has no input to send). A coroutine type carries effects like a generator type:Coroutine<string, int> uses io.Co.resumeandCo.sendfromstd/coroutine(import * as Co from "std/coroutine") run a generator or a coroutine to its nextyield, changinggin place:Co.resume(mutable g)for aGenerator<T>andCo.send(mutable g, input)for aCoroutine<In, Out>. No function is chosen by its argument count:Co.resumetakes one argument andCo.sendtwo, and a call with the other count is the usual wrong-argument-count error (D119). It returns aStep<Out>, an enum of the same module (import { Step } from "std/coroutine") with the constructorsStep.Yielded(value),Step.DoneandStep.Panicked(message), always qualified (D71).StepderivesShowandEquatable. A finished generator or coroutine answersStep.Doneto every later resume or send. The call charges the effects carried on the type ofg(D78), andallocfor theStep. A shared generator is copied before it resumes (the count above 1), as infor ... of.Panickedis only reported in test builds (narrac test): a panic inside the coroutine then ends the coroutine andCo.resumereturnsStep.Panicked(message)with the bare message; what the coroutine held at that moment is not freed. In other builds a panic aborts the program.- A generator is a value like any other. Resuming one by hand requires a
mutableargument.for ... ofiterates over its own copy.Generator<T>has no==, no hashing and noShow. - Only generator bodies become state machines. A
yieldcannot cross a normal function call, so other functions compile as plain C functions.
Threads
Threads run in a scope. Every thread started in a scope finishes before the scope returns.
import * as Thread from "std/thread"
import * as Ranges from "std/range"
function sumRange(start: int, end: int): int {
let total = 0
for (const number of Ranges.between(start, end)) {
total = total + number
}
return total
}
export function sumInTwoThreads(): int uses alloc {
return Thread.scope((scope) => {
const left = Thread.start(scope, () => sumRange(0, 500))
const right = Thread.start(scope, () => sumRange(500, 1000))
return Thread.join(left) + Thread.join(right)
})
}
Thread.scope(f)callsfwith aScope. It waits for every thread started in that scope, then returns the result off, or nothing whenfreturns nothing.Thread.start(scope, f)takesfas an escaping parameter and runs it on a new thread and returns aThread<T>.Thread.join(t)waits for it and returns its result. A secondjoingives the same value. Each thread has an 8 MiB stack, the size of the main thread's.fis a plain function: anasyncarrow or the name of anasyncfunction is a compile error that namesThread.startAsync(E1192).Thread.startAsync(scope, f)takesf: () => Async<T>, anasyncarrow written at the call or the name of a top-levelasyncfunction, and returns aThread<T>. The new thread runs the task offon its own event loop until it finishes, andjoingives the awaited value. This is how code on a thread sleeps or usesstd/net.- Effects.
Thread.startandThread.startAsynchave the effects offandalloc.Thread.scopeandThread.joinadd none: joining gives the same result every run. - A
Scopecannot escape. It can be passed to a function, but it cannot be stored in a field, element, tuple or constructor, returned, or captured by an escaping closure, a thread function included (E1191). Only code running insideThread.scopecan start threads in it. - Thread functions are an arrow function written at the call or the name of a top-level function (E1193), so the compiler sees what they capture. They capture only constant values, like every closure that can outlive its call, and each capture and the result must be
Sendable(section 6, E1190). ForThread.startAsyncthe awaited value must beSendable, not theAsynchandle.Parallel.maptakes only a plain function: anasyncone gives anAsync<U>, which is notSendable(E1190). - Tasks on a thread. Each thread has its own event loop. A thread function may start tasks; when it returns, or when the task that
Thread.startAsyncruns finishes, its thread cancels and drains what is left, as the program does at exit (Async functions below), beforejoingives the result. AnAsync<T>is notSendable, so a handle never reaches another thread's loop; work moves between loops through channels andShared. - A panic on any thread prints its message and ends the process with code 101.
Parallel.map(items, f)fromstd/parallelsplits an array into one part per core, runsfon each element on those threads and returns the results in order.ffollows the thread function rules.==,!=and map keys on aThread<T>or aScopeare a compile error (E1195).
Channels
import * as Thread from "std/thread"
import * as Channel from "std/channel"
import * as Int from "std/int"
import * as Ranges from "std/range"
export function printNumbers(): int uses io, alloc {
const #[sender, receiver] = Channel.create<int>(16) // holds up to 16 values
return Thread.scope((scope) => {
Thread.start(scope, () => {
for (const i of Ranges.upTo(100)) {
Channel.send(sender, i) // blocks while the channel is full
}
Channel.close(sender)
})
for (const value of Channel.values(receiver)) { // ends when the channel is closed and empty
print(Int.toString(value))
}
return 0
})
}
std/channel is a source module, and Channel.create<int>(16) is an ordinary call with a type argument (section 4).
Channel.create<T>(capacity)returns a#[Sender<T>, Receiver<T>].Tmust beSendable(E1190). A capacity below 1 is taken as 1.Channel.send(sender, value)blocks while the channel is full and returnstrue. It returnsfalseand drops the value once the channel is closed or every copy of the receiver is gone.Channel.receive(receiver)blocks until a value arrives and returnsSome(value), orNoneonce the channel is closed and empty.Channel.values(receiver)is aGenerator<T> uses ioover the same values; aforloop over it also needsalloc, because a generator's frame is allocated, so the caller writesuses io, alloc. Copies of aReceivershare the queue, so several threads can take values from one channel; each value goes to one of them.Channel.close(sender)closes the channel for every copy of the sender. Dropping the last copy also closes it.- Blocking calls have the
ioeffect. In async code they block the thread's event loop, as other blocking calls do. ==,!=and map keys on aSenderor aReceiverare a compile error (E1195).- A channel in a cycle stays open (D80). A
Sendersent through its own channel, or held in aSharedthat the channel's values reach, keeps the channel alive: it is never freed, and dropping the other copies of the sender does not close it, so a receiver that reads until the close waits forever. When senders travel through channels, close the channel withChannel.close(sender)instead of relying on the last drop; the close ends the receiver's wait, and a receiver that reads the channel empty drops the sender it held and breaks the cycle. ASender<Reply>sent inside a request (Sender<#[Request, Sender<Reply>]>) is fine: the reply channel does not hold the request channel.
Cell
Cell<T> (D90) is an identity type for state that changes and is shared on one thread, such as a counter two escaping closures use. It is Shared without the lock. It is a Narra source module: import * as Cells from "std/cell" for the functions and import { Cell } from "std/cell" for the type.
const count = Cells.create(0)
const next = (): int => {
Cells.update(count, (value) => value + 1)
return Cells.get(count)
}
const reset = (): int => {
Cells.set(count, 0)
return 0
}
Cells.create(value)allocates the slot (uses alloc).Cells.get(cell)returns a copy of the value.Cells.set(cell, value)replaces it and drops the old value at the call.Cells.update(cell, change)storeschange(value);changeis a function that returns the new value, because a scalar cannot be amutableparameter (D81). None of the last three has an effect: a write to aCellis not tracked.- Copying a
Cell, capturing it, or storing it in a struct copies the handle, so every copy sees every write.Cellis anopaque struct: its field is not reachable.==and!=on aCellare a compile error (E0965), and aCellis notHashable, so it cannot be aMapkey; compare the values withCells.get. - A
Cellcannot cross threads. It uses plain reference counts and is notSendable(section 6): aCell, or a value that holds one, captured by a thread function or sent through a channel is E1190, with a hint to useShared. - A closure stored in the
Cellit captures leaks (D80); clear it withCells.set(cell, None)first.
Shared state
A few types have identity: copying one copies a handle to the same object. They are the only way two threads can see the same changing data.
| Type | Use |
|---|---|
Sender<T>, Receiver<T> |
Channel ends |
Shared<T> |
A value guarded by a lock |
Atomic<T> |
An integer or bool with atomic operations |
const hits = Shared.create(0)
Shared.update(hits, (count) => count + 1)
const now = Shared.read(hits, (count) => count)
Shared<T>(std/shared) has the functions ofCellsandread:Shared.create(value)(uses alloc),Shared.get(shared)returns a copy,Shared.set(shared, value),Shared.update(shared, change)storeschange(value), andShared.read(shared, look)returnslook(value). As forCells.update,changereturns the new value, because a scalar cannot be amutableparameter (D81).Tmust beSendable(E1190). LikeCells.get,Shared.getshares the value it returns (from shared), andlookmay return a part of its value (from value); both results hold their own reference, taken before the lock is released.updatemoves the value out of theSharedwhilechangeruns.- The lock is held only while a call runs. Each function takes the lock, does its work (running the callback, if any) and releases it. There is no way to take the lock and forget to release it.
- The callback cannot be
async(E1410), so a task never suspends while holding a lock. Atomic<T>(std/atomic) holds aboolor an integer type up to 64 bits (E1411 for any otherT). It offersAtomic.create,Atomic.load,Atomic.store,Atomic.exchange,Atomic.add(integers only, E1412 onAtomic<bool>; it returns the old value and wraps like+) andAtomic.compareExchange(atomic, expected, replacement), which returnstruewhen it stored. Every operation is sequentially consistent.==,!=and map keys on aSharedor anAtomicare a compile error (E1195), as on aCell; compare the values instead.- Identity types can form cycles (D80, section 6 "Cycles"). A
Sharedwhose value holds a handle to the sameShared, directly or through other identity objects, is never freed.Async<T>(Async functions below) andCell<T>follow the same rule. The debug leak check reports the cycle; clear the slot before dropping the last outside handle, or usestd/arena. - Deadlocks are possible when callbacks nest locks in different orders. Nothing reports nested
Shared.updatecalls yet;narrac auditlists onlyunsafeblocks and@trustedfunctions (section 9). - A callback that reaches its own
Sharedstops the program (D111). A call ofShared.get,set,updateorreadon aSharedwhose lock its own thread holds, as inShared.read(cell, (v) => v + Shared.get(cell)), ends the program with exit code 101 and a message that names the call, as a panic does, instead of waiting forever.
Async functions
An async function runs as a task on the event loop of its thread. A task suspends at an await that has to wait, and the loop resumes it when the awaited task has finished, a timer has fired or I/O is ready. The syntax is TypeScript's (D93, D95, D109).
import * as Async from "std/async"
import * as Bytes from "std/bytes"
import * as Net from "std/net"
import { Connection } from "std/net"
async function echo(connection: Connection): int uses io, alloc {
let total = 0
while (true) {
const data = await Net.read(connection, 4096)
if (data is Err(_)) {
return total
}
if (Bytes.length(data.value) == 0) {
return total
}
const written = await Net.write(connection, data.value)
if (written is Err(_)) {
return total
}
total += written.value
}
}
export async function run(_args: Array<string>): int {
const listener = Net.listen("127.0.0.1", 8080)
if (listener is Err(_)) {
return 1
}
while (true) {
const accepted = await Net.accept(listener.value)
if (accepted is Err(_)) {
return 0
}
Async.detach(echo(accepted.value))
}
}
Tasks and handles:
async function f(...): Tdeclares an async function. Its type is(...) => Async<T>: a call starts the task and gives anAsync<T>handle. The body runs until it first has to wait, then the call returns.returnin the body gives aT.Async<T>is a handle to a result on its way, like a TypeScriptPromise. It is an identity type (section 6, "Cycles"): copies share one task, and the finished value is kept until the last handle is dropped.Asyncneeds no import, and a type namedAsyncthat the module declares hides it.==,!=and map keys on a handle are compile errors (E1106).asyncarrow functions andasync { ... }blocks make handles too.async (item) => { ... }has the type(item: T) => Async<R>, soArrays.map(items, async (item) => ...)gives anArray<Async<R>>.async { ... }is an expression of typeAsync<T>that starts at once; it follows the rules of a block expression (section 2), so its value comes fromreturn. Both capture like escaping closures wherever they are written: the task gets each captured value when it starts, and capturing aletor amutableparameter is a compile error (E1110). Share changing state through aCell. As for an arrow function, a block that returns a value sharing a captured one is E0976; return acopy(...)of it.await handlegives the value of anAsync<T>. It waits only when the task has not finished, and awaiting the same handle again gives the same value.awaiton another type is E1102.- Where
awaitis allowed. Anywhere in an async body (function, arrow or block), in any expression:if (await ready())andtotal(await first(), await second())work, and the operands run left to right as in TypeScript. Outside an async body, in afunction*body and in an arrow function that is notasyncit is E1100. - An unused
Async<T>is a compile error (E1103), like an uncheckedResult: a call withoutawaitas a statement, anasync { ... }alone, andconst _ = f(). Await the handle, keep it, pass it on, or let the task run withAsync.detach(handle). - Effects are charged where the handle is made. A call of an async function has the function's effects plus
allocfor the task, andawaithas none.Async<T>carries no effects. The type of an async arrow lists the effects of its body:(id: int) => Async<User> uses io. - Parameters. An async function or arrow takes no
mutableparameter (E1104), because the task outlives the call, and a function-type parameter of an async function must beescaping(E1111). Its parameters are kept in the task, and a value passed to a task is shared with it: while a local holds the handle, a write to the passed place is a shared write (E0978, section 6), andcopy(...)at the argument is the fix. The value an async function or arrow returns follows thefromrules of a plain function or arrow (section 6): a returned parameter needsfromafter the result type, andawait f(x)of a function withfrom x, called by name or through a function value, sharesxas a plain call does. The compiler does not yet followfromthrough a stored handle (const h = f(x), thenawait h), so a write to that value copies without an error, and the debug copy check reports it. for (mutable item of items)is a compile error in an async body (E1105).async function*declares an async generator (below).
The functions of std/async (import * as Async from "std/async"):
Async.then(handle, callback)runscallbackwith the value when the task finishes and returns nothing. The callback is an ordinary escaping function with noawait, and its effects are charged at the call. Callbacks run in the order they were registered; on a handle that has already finished the callback runs on the next loop turn, not inside thethencall, as in TypeScript. The runtime drops it after it runs or when the handle is cancelled.Async.detach(handle)lets the task run with nobody waiting.Async.peek(handle): Option<T>gives the value once the task has finished, andNonebefore that or after a cancel. It never waits.Async.cancel(handle)cancels the task (below).Async.all(handles): Async<Array<T>>gives every value, in order.Async.race(handles): Async<Option<T>>gives the first value to come, orNonefor an empty array. Neither cancels the handles it was given.Async<void>. A type parameter that is the value of anAsync<T>is inferred asvoidfrom anAsync<void>argument, and a callback parameter of typevoidtakes no argument, so thethencallback of anAsync<void>is() => void:Async.then(work(), () => print("done")).detach,thenandcanceltake anAsync<void>;peek,allandraceon one are E1150, becauseOption<void>andArray<void>are not types. A type parameter inferred as void anywhere else thanAsync<T>or a function-type parameter is E1150 too.await Async.idle()waits until the loop has nothing ready and no timer or I/O wait pending, counting tasks started while it waits. Several idle callers finish one at a time, oldest first. A task stuck in a cycle of awaits does not hold it.AsyncErroris the error of every suspending std function:AsyncError.Cancelled, orAsyncError.Failed(message)with the operating system's message.- No blocking wait. No function waits for a handle outside an async body. A function that is not
asyncstarts tasks and passes their handles on, detaches them, or registers athencallback. - No
Thenabletrait.awaitworks only onAsync<T>, so it never runs user code. A type that can be awaited offers a function that returns anAsync<T>.
The loop:
- One event loop per thread, with no loop value to pass around. The entry function runs as its first task (section 15). It may be
export async function run(args: Array<string>): int, whoseAsync<int>gives the exit code. - The program exits when the entry function finishes. Tasks still running then are cancelled and run until they return; a task left waiting on a task that can never finish is dropped. The wait a cancelled task is suspended in gives
Err(AsyncError.Cancelled), and the task runs up to its next suspending call; that call drops it, so its frame releases its locals and it does not resume.Async.idlecounts as a suspending call. A task cancelled before its first run is dropped at its first suspending call without seeingErr(AsyncError.Cancelled). A loop that never suspends (including one that reads an async generator that never awaits) is a plain infinite loop, as in synchronous code. To let tasks finish first, end the entry withawait Async.idle(). A detached task lives at most as long as the program. This differs fromAsync.cancelduring the run, where every later suspending call keeps returning the error. - A cycle of awaits stops the program. When no task is ready, no timer is set and no I/O is waiting, but the entry has not finished, the tasks wait on each other. The program stops with the message
async: every task waits on another taskand exit code 101, as for a panic. - Cancel is cooperative. After
Async.cancel(handle), the suspending std call that the task waits on or makes next returnsErr(AsyncError.Cancelled)without doing its work, and so does every later one. The body handles it like any error and returns aT, soawaiton a cancelled handle still gives aT. A cancelled handle'sthencallbacks do not run. A cancel passes down the await chain: when the cancelled task waits on a handle that no other task awaits, that task is cancelled too, and so on, so the innermost timer, I/O or idle wait givesErr(AsyncError.Cancelled). A handle that other tasks also await, that hasthencallbacks or that an unfinishedAsync.allorAsync.racewas given is not cancelled, a cancel of anAsync.allorAsync.racehandle stops there, and detached tasks and tasks the cancelled task started but does not await keep running. A task cancelled while it runs passes the cancel when it next waits in anawait. Cancelling a finished task does nothing. A cancel wakes a task waiting in its ownAsync.idle(), andidlein a cancelled task finishes at once. - One form per std function (D125). A std function is
asyncwhen the operating system can wait for it in the background (timers, sockets), and plain when it cannot (files, processes, standard input). No function has both forms. Each suspending function returnsResult<T, AsyncError>, so a body must look at the result (E0229) and sees a cancel.Time.sleepinstd/time:sleep(duration: Duration): Result<Duration, AsyncError>. Ok holds the time slept.std/net:listen(host, port): Result<Listener, AsyncError>andlocalPort(listener): int, which do not suspend, andaccept(listener),connect(host, port),read(connection, maxBytes): Result<bytes, AsyncError>(empty at the end of the stream) andwrite(connection, data): Result<int, AsyncError>.hostis a numeric address, and port 0 picks a free port. One task at a time may read a connection and one may write it; a second givesErr(AsyncError.Failed(...)).readgives at most 64 KiB per call.ListenerandConnectionare handles: copies share the socket, and it closes when the last copy is dropped (section 6).
- Blocking calls block the loop.
std/fs,Process.runand the other plain functions are allowed in async code, and no other task runs while they wait.await Async.idle()between them lets the other tasks run. - A task stays on the thread that runs its loop. An
Async<T>or aCellcannot be sent to another thread. Pass work between the loops of several threads with channels. - The loop waits with
kqueueon macOS andepollon Linux.
Async generators
An async generator produces values one at a time and may wait between them (D110). The syntax is TypeScript's async function* and for await.
import * as Bytes from "std/bytes"
import * as Net from "std/net"
import { Connection } from "std/net"
async function* sizes(connection: Connection): AsyncGenerator<int> uses (io, alloc) {
for await (const chunk of Net.chunks(connection, 4096)) {
if (chunk is Err(_)) {
return
}
yield Bytes.length(chunk.value)
}
}
async function total(connection: Connection): int uses io, alloc {
let sum = 0
for await (const size of sizes(connection)) {
sum += size
}
return sum
}
async function* f(...): AsyncGenerator<T>declares an async generator. The result must be writtenAsyncGenerator<T>(E1112); afunction*that is not async cannot declare it (E1113).AsyncGeneratortakes one type argument (E1114), needs no import, and a type namedAsyncGeneratorthat the module declares hides it. As for a generator, an exported one writes its effects on the result (AsyncGenerator<T> uses io), a private one has them inferred, it takes nomutableparameter (E1104), and its function-type parameters must beescaping(E1111). There is no arrow and no block form.- The call runs nothing. It makes the stream and stores the arguments, as a
function*call does, and chargesalloc. The body runs only while a reader waits for a value, so a stream nobody reads does no work. - The body is both an async body and a generator body.
awaitstands in any expression, as in an async function.yield valueis a statement, as in afunction*, andyield await f()works.returntakes no value (E0292).const input = yield valueis E1115: there is no async coroutine.yield* otherpasses on every value of anotherAsyncGenerator<T>with the sameT; any other operand, aGenerator<T>included, is E1116. Async.next(stream): Async<Option<T>>(std/async) asks for the next value. The handle givesSome(value)at the nextyieldandNoneonce the body has ended, and then for every later call. It is an ordinary handle:awaitit, race it against asleepfor a timeout, or keep it to read one value ahead. The call charges the effects of the stream's type andalloc. Requests are served in the order they were made, and the body runs until its nextyieldinline in the call when nothing makes it wait.for await (const x of stream)awaitsAsync.nextuntil it givesNone, binding each value. It is allowed in an async function, an async arrow, anasync { ... }block and an async generator, and elsewhere it is E1122. The source must be anAsyncGenerator<T>(E1123): loop over aGenerator<T>withfor ... of, and over anArray<Async<T>>withfor ... ofand anawaiton each handle.for ... ofover anAsyncGenerator<T>is E1124.for await (mutable x of stream)is E1105, and the head takesconst, notlet(E0030). Labels,break,continueand destructuring heads work as infor ... of, andensureson the generator gives the binding the same facts.- A stream is shared, not copied. Copies of an
AsyncGenerator<T>share one body and one position, as copies of anAsync<T>share one task, so two loops over one stream each get some of its values.==,!=and map keys on one are E1106. A value passed to a stream is shared with it as with a task: while a local holds the stream, a write to the passed place is E0978. - Stopping early.
break,returnor a labeledbreakout of afor awaitdrops the loop's reference to the stream, as dropping a copy read withAsync.nextdoes. When it was the last one, the body is dropped where it waits at itsyield, and what it holds there is released; aConnectioncloses when its last copy goes. Nothing else of the body runs. - Cancel. A cancel of a task that waits on a value of a stream, or of the
Async.nexthandle itself, passes to the stream when it is the only request waiting on it: the wait inside the body givesErr(AsyncError.Cancelled), as do its later suspending calls, and later requests giveNoneonce the body ends. A request nobody awaits still runs the body to its nextyield; that value is lost when the handle is dropped. Net.chunks(connection, maxBytes): AsyncGenerator<Result<bytes, AsyncError>>instd/netyieldsOk(chunk)for each read that is not empty, ends at the end of the stream, and on an error yields oneErrand ends. AmaxBytesof zero or less ends the stream at once.
9. Unsafe code and C interop
unsafe { ... }is a statement, and the only place a call with theunsafeeffect is allowed: the std/ptr functions that read, write, move or free a pointer, and any function whose effects includeunsafe. A call outside one is E0996.unsafeis a keyword only before{, so it stays an effect name. The block is not an expression (const x = unsafe { ... }is a syntax error); assign to aletdeclared before it. Areturninside the block returns from the enclosing function. Code insideunsafemay crash; it is the stated exception to D92.- The
unsafeeffect. A function that holds anunsafeblock has theunsafeeffect: an exported one writesuses unsafe(E0800), a private one is inferred, and every caller needs anunsafeblock of its own. A function value whose type listsuses unsafeis called the same way. - Generators and traits. Running a generator runs its body, so a
forloop oryield*over a generator whose body has theunsafeeffect needs anunsafeblock (E0996). A call through a trait has the effects the trait function declares, so an implementation may useunsafeonly when its trait function declaresuses unsafe(E0800); otherwise it wraps the unsafe code with@trusted, the one attribute allowed on an implement block member. @trustedon a function states that itsunsafeblocks were checked by hand. It stops the effect there: the function does not haveunsafe, so callers need no block and an exported one does not declare it.@trustedon a function with nounsafeblock, or on one that writesuses unsafe, is E0997.Ptr<T>is a raw pointer, a plain value with no reference count, compiled to the C pointerT*. The type is visible in a module that importsstd/ptr(import * as Ptr from "std/ptr"), and it is writtenPtr<T>whatever the alias: withimport * as P from "std/ptr"the functions areP.readand the type is stillPtr<int>;P.Ptr<int>is an error.Tis a number type,bool,char, anotherPtr, a vector type ofstd/simd, aFixedArrayof such values, or a struct whose fields are all such values (tuples count as structs, and a field may be aFixedArray). AFixedArrayof anything else, such asFixedArray<string, 2>, is E0998 with a message that names the element. Strings,bytes, arrays, maps, boxes, enums, function values, generators, opaque structs and type parameters are E0998, because a pointer to them would bypass reference counting.- Pointer values are ordinary data. A
Ptrcan be stored in a struct, an array or a tuple, copied, passed to and returned from any function,@trustedor not, and held across calls. Copying one copies the address. APtris notEquatable,Hashableor printable:==and!=on it are compile errors, it cannot be aMapkey, and a struct that holds one cannot derive those traits. Test for null withPtr.isNull. - std/ptr.
Ptr.alloc(count: int): Ptr<T>allocatescountzeroed elements (uses alloc);Ptr.free(pointer)frees whatPtr.allocreturned and does nothing for a null pointer;Ptr.read(pointer): TandPtr.write(pointer, value: T)read and write one element;Ptr.offset(pointer, count: int): Ptr<T>moves bycountelements.Ptr.cast(pointer: Ptr<T>): Ptr<U>reinterprets the address as a pointer to another element type, as a C cast does, with no check (const bytes: Ptr<u8> = Ptr.cast(words));Ptr.element(pointer: Ptr<FixedArray<T, N>>, index: int): Ptr<T>is the address of one item of a FixedArray.Ptr.elementproves its index like a FixedArray read does (E0994 for a constant outside 0 to N - 1 or an unproven index), and a pointer to anything else is E0998. These seven have theunsafeeffect.Ptr.null(): Ptr<T>andPtr.isNull(pointer): booltouch no memory and are safe.Ptr.alloc,Ptr.nullandPtr.casttake the result's element type from the expected type (const items: Ptr<int> = Ptr.alloc(4)). There is noPtr<void>, sincevoidis not a type that can be written;Ptr<u8>stands for C'svoid*. Nothing is checked at run time: a read past the allocation, a use afterPtr.freeor a double free is undefined behavior, and so is reading or writing through aPtr.castpointer whose element type does not match the stored data, except throughu8andi8, because programs are built with strict aliasing. Memory fromPtr.alloccounts toward the debug leak check (section 13) until it is freed.
import * as Ptr from "std/ptr"
@trusted
function sumSquares(count: int): int uses alloc {
let total = 0
unsafe {
const items: Ptr<int> = Ptr.alloc(count)
for (let i = 0; i < count; i++) {
Ptr.write(Ptr.offset(items, i), i * i)
}
for (let i = 0; i < count; i++) {
total += Ptr.read(Ptr.offset(items, i))
}
Ptr.free(items)
}
return total
}
extern { ... } from "library"declares C functions, like an import names a module. The block stands at the top level and holds one or more function signatures, each on its own line, with no type parameters, nousesand no body (E1000).fromnames the library ascctakes it after-l(letters, digits,_,.,+and-, not starting with-):"m"for libm,"z"for zlib;"c"is libc and needs no-l. A member may be writtenexport, and is then called from other modules like any exported function.
import * as Float from "std/float"
extern {
@extern("abs")
function absolute(value: i32): i32
} from "c"
extern {
function cbrt(value: f64): f64
} from "m"
@trusted
export function cubeRootOfMagnitude(value: i32): f64 {
let result = 0.0
unsafe {
result = cbrt(Float.from(absolute(value)))
}
return result
}
- Every member has the
unsafeeffect, so all the rules above apply: a call needs anunsafeblock (E0996) or a@trustedwrapper, a private function that calls one inside a block gets the effect, a generator whose body calls one needs a block where it runs, an implementation may call one only when its trait function declaresuses unsafe, and a function value of a member has the type(...) => T uses unsafe. A member's parameters are never "unused". - Types. Parameters and results are the number types,
boolandPtr<T>, and a member may return nothing (E1002). In C,intisint64_t, the sized integers areint8_ttouint64_t,f64isdouble,f32isfloat,boolisboolandPtr<T>isT*. So C'slongisinton both supported platforms, C'sintisi32,size_tisu64, andchar*,const char*andvoid*arePtr<u8>. Nothing checks that the Narra signature matches the C function: a wrong one is undefined behavior, which is why a call is unsafe. Amutableparameter is E1002. A C function that returnsintas a truth value (isalphaand the otherctype.hpredicates) is declared withi32, notbool: aboolresult reads only the low byte, and glibc returns values such as 1024. - Variadic C functions cannot be declared. There is no syntax for
..., and a fixed prototype for one (printf(format: Ptr<u8>, value: int): i32) is undefined behavior: variadic arguments are passed differently from fixed ones on some platforms (macOS arm64 puts them on the stack), so the C function reads garbage. Call them through a C-side wrapper with a fixed signature, which waits for C-callable functions and C sources in a package (node c-abi-export). - C names. A member links to the C function with its own name, or with the name
@extern("name")gives (the only attribute a member takes, written on the line before it). The C name must be a C identifier and must not be one the compiler writes (E1001):main, a name starting withnarra_orlstr_, a string literal name (Land digits), a name with a module hash (f_3fa9c1e7_show), or the generated name of a function or type of the program, alone, followed by_and more, or after a word and_(the reference counting and trait helpers, such asrelease_E_Option_e088c655andeq_S_Tuple2_…).@externon a function with a body is E1000 for now; C-callable Narra functions are step 2 below. - How a member's C prototype is written. The C code keeps calling the member by its generated, hashed name, and declares it once as
extern <result> <generated name>(<parameters>) __asm__("<symbol>"), with the C types above and the C name as the symbol (with the platform's symbol prefix,_on macOS). Because the C identifier is not the C name, the prototype never meets a declaration of the same function in the headers the runtime includes (string.h,stdlib.h,math.hand others): declaringstrlenwithPtr<u8>andu64whilestring.hdeclaressize_t strlen(const char*), orsqrttwice, compiles with no conflict, and both declarations name the same symbol. Only the prototypes of reached members are written. - Linking.
narrac buildandnarrac runpass-l<library>toccfor every library whose block has a member that reached code calls (tree shaking, section 11), after the C file and in declaration order;-lmis always passed. A block whose members are never reached, for example because they are called only in a branch a build condition drops, links nothing, so its library need not exist on that target.[link] searchinnarra.tomladds-L<directory>(section 15). - Memory from C. Memory a C function allocates goes back through the C library's own function (an extern
free), never throughPtr.free, which frees only whatPtr.allocreturned. - Not built yet (C interop step 2, node c-abi-export):
@layout(C),@layout(u8)and C-callable functions, written below under their earlier names. @repr(C)on a struct fixes its field order and padding to match C. Without it, the compiler may reorder fields to reduce padding.- C-compatible enums.
@repr(u8),@repr(i32)and the other integer types give an enum without fields explicit values.Red = 1in an enum without@repris a compile error whose fix adds@repr(i32)(D73).Enum.toIntandEnum.fromIntconvert, andfromIntreturnsOption.
@repr(u8)
export enum Color {
Red = 1
Green = 2
Blue = 4
}
- Callbacks from C. A function marked
@export(C, "name")gets a C-compatible symbol. Its parameters and result must be@repr(C)types, numbers orPtr<T>. - C strings.
std/cstringprovidesCString, a string with no zero byte, written withimport * as CStrings from "std/cstring"andimport { CString } from "std/cstring".CStrings.from(text): Option<CString>isNonewhen the text holds a zero byte.CStrings.pointer(value): Ptr<u8>is the address of its zero-terminated bytes for a C function that takesconst char*; it is valid while the CString is alive and must not be written through.CStrings.toString(value): stringgives the text back, andCStrings.read(pointer): Result<string, string>(uses alloc, unsafe) copies a zero-terminated string a C function returned, withErrfor invalid UTF-8. narrac audit [path]lists everyunsafeblock and@trustedfunction in a package, one line each, sorted by file, line and column:src/x.nra:12:3: unsafe block in function nameandsrc/x.nra:4:1: @trusted function name. A block in a test readsin test name, and a trait or implement block member is named with its trait or implementation:@trusted function measure in implement Measure for Cells,unsafe block in function measure in trait Measure. It reads the source only and exits 0; a package that does not load is an error.
10. Top-level declarations
constat the top level declares a compile-time constant. It cannot be changed at any depth or passed asmutable(D81); a localconstfixes only its name (section 2). Inside a function,constaccepts any expression. A top-level value must be one of these:- a literal or a constructor
- a struct or array of constants
- a named function or another constant
- a call to an
@constfunction, with constant arguments, also inside the constant parts of a value (const pair = #[square(2), square(3)])
@constfunctions are computed by the compiler when a top-level constant calls them (D105). The call is written at the constant, so nothing runs hidden; outside a constant an@constfunction is an ordinary function.- Only a function written with
@constmay be called from a constant. Its declaration is checked where it is written, even when no constant calls it, so an edit that breaks the rules fails in the module that made it. - Its effects are at most
alloc(E1051); an exported one declares at mostuses alloc. - Its parameters and result hold only numbers,
bool,char,string,bytes,Array,Map,FixedArray,Option,Result, tuples, and structs, enums and distinct types made of these. A function type,Cell,Ptr,Shared, a generator, a trait-constrained type parameter or an effect parameter is E1050, and so is a generator function. - Its body may call other
@constfunctions, constructors and the functions ofstd/string,std/array,std/map,std/int,std/float,std/range,std/char,std/option,std/result,std/regex,std/math,std/bytes,std/fixedarray,std/f32and the sized number modules (std/i8,std/i16,std/i32,std/u8,std/u16,std/u32,std/u64) that take no function, read top-level constants, and use loops,match,is, patterns,mutableparameters and locals. It may not call another function (E1052, which names the function), use an arrow function or call through a function value, or run a userimplementblock, through==, a map key or a call. The built-in and derived implementations run:==and map keys on numbers, strings and derived types. A sized number wraps, converts and fails checked arithmetic at compile time exactly as at run time.Math.sin,cos,tan,atan2,exp,logandpoware never allowed, because their results depend on the C library. - Limits, per constant: 10 million evaluation steps (E1054), 64 MiB of values (E1055), 1000 nested calls (E1056), a nesting depth of 5000 (E1056) and a value depth of 1000 (E1056). A step is one expression, statement or loop turn, plus one per 8 bytes or elements a std string, array or map call goes through. Values are counted where they are built: 8 bytes per number, element, field and entry, string lengths rounded up to 8, and 16 per array and map.
copy(...), and storing a value read from a place (const row = rows[0],Arrays.push(mutable rows, row), a field or element of a literal), count the outer level of the value again, as the copy its first write makes. A std call that would pass the memory limit (Arrays.filled,Arrays.withCapacity,Str.repeat,Str.join,Str.replace, string concatenation and templates) is stopped before it runs. A self-call in tail position runs as a loop and does not count toward the calls. The nesting depth counts the calls, blocks, loops and expressions under way in all open calls at once, so a body that nests deeply reaches it before 1000 calls (six nested additions per call allow about 600 calls); it keeps the compiler's own C stack safe. The value depth is how deeply arrays, structs, enums and maps nest in the result. - A float literal in an
@constbody is computed only when the compiler reads it exactly: at most 18 significant digits, and a power of ten that reduces to at most 22. Anf32literal whose value read asf64is rounded and lies halfway between twof32values is refused too, since rounding it again tof32could differ from C's reading. Both are E1052 at the constant. - A panic, a failed
assert, an index out of range and the std functions that would panic (Str.sliceFrom,Str.charAt,Str.nextChar,Str.byteAton a bad position) stop the computation with a compile error at the constant (E1053). Each error of a computation shows the chain of calls from the constant down as notes. - A constant that an
@constfunction reads while the constant itself is computed is E1057. - A scalar result (a number,
bool,char, a constructor without fields) is written at each use, as for any scalar constant. Any other result is built on first use by the constant's getter, from the value; an array of scalars is copied from static C data in one step.
- Only a function written with
- Modules have no initialization code. Program startup runs nothing before the entry function.
11. Code generation
- Output is C. One
.cfile per module, plus a small runtime: allocator, reference counting, panic handler and arenas. - Vector types from
std/simdcompile to C compiler vector extensions (D112). Each type the program uses is a typedef such astypedef float narra_f32x4 __attribute__((vector_size(16), aligned(8))). The alignment is 8 because heap blocks start at 8-byte boundaries; loads are unaligned, which costs nothing on x86-64 and arm64. Integer+,-and*go through the unsigned vector type, so they wrap. The build passes no-marchflag: x86-64 code uses SSE2 and arm64 code NEON. A C compiler without vector extensions (TCC) cannot build a program that importsstd/simd. - Debug builds use the same C compiler with checks on (AddressSanitizer, the leak check and the copy check).
- Release builds use Clang or GCC with
-O2. - No fused multiply-add. The C starts with
#pragma STDC FP_CONTRACT OFF, soa * b + con floats rounds twice at every optimization level, as the compiler computes it for an@constfunction (D105). Without it, clang contracts the expression on arm64, which changes the last bit of some results. - Generators and async functions compile to a struct and a resume function. The struct holds their live variables and a state number. The resume function switches on that number.
- Calling a
function*allocates the struct with a reference count of 1 and state 0, and stores its parameters. It runs nothing of the body. - Every local, loop counter, temporary and expression result of the body is a field of the struct, so no C local is alive across a
yield. Only scratch values used inside one expression stay C locals. yield vstoresvfor the caller, records the next state and returns. Ending the body orreturnreleases what is still held and sets the finished state; resuming a finished generator returns nothing again.- Dropping an unfinished generator releases what is live at its state and frees the struct. Resuming a shared generator first copies the struct and retains what is live in it, so
for ... ofandyield*work on their own copy. - Calling an async function allocates the struct with a task header and a field for the result, stores its parameters (an async arrow or block stores its captures) and runs the body until it first waits. The struct is the task and the handle:
Async<T>points to it, and copies of the handle share it, so it is never copied. awaiton a finished handle reads the result field. Otherwise the task joins the handle's waiters, records the next state and returns to the loop, which resumes it once the handle has finished.- A finished task has released its locals. The struct and the result are freed with the last handle. At exit the tasks still unfinished are dropped like an unfinished generator, so the leak check sees nothing of them.
- Calling a
mutableparameters compile to C pointer parameters.- Self-calls in tail position compile to loops in every function (section 2). Other recursion uses the C stack. Stack overflow aborts the program.
- Closures. A non-escaping closure's environment is a C struct on the caller's stack. An escaping closure's environment is a reference-counted heap object.
- Trait constraints compile to a hidden parameter that points to the implementation table.
- Constant parameters pass by pointer. A parameter larger than two machine words is passed as a pointer to the caller's value. Parameters are constant and access is exclusive (section 6), so this changes nothing a program can observe.
- Reads do not copy.
items[i].fieldands.inner.fieldread through a pointer. The element is not copied and its reference count is not touched. - Generic code is monomorphized. Every build, debug and release, compiles one copy of a generic function for each set of type arguments the program uses, across packages too (D119). Values are stored and passed in their normal form, never boxed, and
Array<int>holds raw integers.
12. Build model
- The compiler reads a module's
importdeclarations before anything else and builds the module graph from them. - Modules with no dependency between them compile in parallel.
- Builds are deterministic. The same inputs produce byte-identical C and binaries.
- Compile-time evaluation is limited to top-level
constdeclarations,@constfunctions and build conditions. A constant that calls an@constfunction is computed inside the compiler, by an evaluator over the checked program, within the limits of section 10;narrac check,build,emitand the language service all compute it, since a failed computation is a compile error. A result depends only on the source and the target: maps keep insertion order, integers wrap the same way, and floats round the same in the compiler and the program (section 11).
Build conditions
Code that differs by platform branches on constants from std/build. The compiler keeps only the matching branch.
import * as Build from "std/build"
import { Os } from "std/build"
import * as Env from "std/env"
import * as Options from "std/option"
export function configDir(): string uses io, alloc {
const home = Options.withDefault(Env.get("HOME"), "")
if (Build.os == Os.Windows) {
return Options.withDefault(Env.get("APPDATA"), home)
} else if (Build.os == Os.MacOS) {
return `${home}/Library/Application Support`
} else {
return `${home}/.config`
}
}
Build.os,Build.archandBuild.debugare compile-time constants.std/buildalso exports their types, the enumsOs(MacOS,Linux,Windows,Wasi) andArch(Arm64,X86_64,Wasm32).Build.debugisfalsein a-releasebuild andtrueotherwise.- The host is the target. The compiler takes
Build.osandBuild.archfrom the target the C compiler built the compiler itself for (itsBuild.hostTarget()), and only when the package importsstd/build. A compiler can run onMacOS-Arm64,MacOS-X86_64,Linux-X86_64,Linux-Arm64,Linux-X86_64-musl,Linux-Arm64-muslandWindows-X86_64;Wasi-Wasm32is a target only. The environment variableNARRA_HOST_TARGET, when set, names the target as<os>-<arch>in place of the host; it is the only input besides the host that sets the target. A host, or aNARRA_HOST_TARGET, with no supported target is a compile error at the module's import ofstd/build. Build.hostTarget()returnsOption<Target>, whereTargetis a struct ofos: Osandarch: Arch: the target the C compiler builds the program for, read from its predefined macros (__APPLE__,__linux__,__aarch64__,__x86_64__) when the program runs. It isNonefor any other combination. It does not rununame.narrac emitwrites the C of a debug build. The C of a release build comes fromnarrac build -release -emit-c file.c.- An
ifthat tests only these constants is resolved at compile time. The output contains no runtime check, only the matching branch, or nothing when no branch matches. The condition may combine the constants with==,!=,is(a variant without fields),!,&&and||, and eachelse ifof a chain is resolved on its own. A condition that mixes the constants with any other value, or amatchon them, is an ordinary runtime test. - Every branch is type-checked on every build. A Windows branch is checked when building for Linux, so branches for other platforms cannot break unnoticed. The effects of every branch count toward the function's effects, the dropped ones included, so a function has the same signature on every target.
@target(os = Os.MacOS)on its own line before a top-level function makes the function exist only on that target. It takesos =a variant ofOs,arch =a variant ofArch, or both (@target(os = Os.Linux, arch = Arch.Arm64)), each once; a part it does not name matches every value. The enum is written the way the module imports it:Os.MacOSafterimport { Os } from "std/build",Build.Os.MacOSthroughimport * as Build. Narra functions andextern { } fromblocks take@target; other declarations do not.
import * as Build from "std/build"
import { Os } from "std/build"
@target(os = Os.MacOS)
function macOpener(): string {
return "open"
}
@target(os = Os.Linux)
function linuxOpener(): string {
return "xdg-open"
}
export function opener(): string {
if (Build.os == Os.MacOS) {
return macOpener()
} else if (Build.os == Os.Linux) {
return linuxOpener()
}
return "start"
}
-
A use outside a branch that guarantees the target is a compile error. On each target, a call to a
@targetfunction, or its use as a function value, is an error where the function does not exist, unless that target does not compile the use. A target does not compile:- a branch that a build condition (above) drops on it, such as the then branch of
if (Build.os == Os.Windows)on Linux, or the rest of anelse ifchain after the branch it keeps; - the body of a
@targetfunction whose target it is not.
So a use is accepted on every target exactly when it sits inside a branch whose build condition holds only on targets where the function exists (
macOpener()insideif (Build.os == Os.MacOS)), or inside a@targetfunction with the same or a narrower target. An ordinaryif, amatchonBuild.os, an earlyreturnand a condition onBuild.debugalone guarantee nothing. - a branch that a build condition (above) drops on it, such as the then branch of
-
A
@targetfunction is type-checked on every target, like a dropped branch, and its effects count the same way. -
narrac checkchecks a debug build for the host;narrac check --all-targetschecks every supported target, each as a debug and as a release build, since a condition onBuild.debugcan keep a use in one of them only. It reports each diagnostic once, in source order; an E0991 lists every target it fails on, with(debug)or(release)after a target that fails in one build only. A use that is wrong only on another target shows only with--all-targets. -
The targets are one table of eight rows, named
<Os>-<Arch>or, for a Linux row that links musl,<Os>-<Arch>-musl:MacOS-Arm64,MacOS-X86_64,Linux-X86_64,Linux-Arm64,Linux-X86_64-musl,Linux-Arm64-musl,Windows-X86_64andWasi-Wasm32.Oshas the variantsMacOS,Linux,WindowsandWasi;ArchhasArm64,X86_64andWasm32.Build.osandBuild.archdo not tell musl from glibc. -
Wasi-Wasm32runs under a WASI preview 1 host such aswasmtime run -W exceptions=y. The build passes-mexception-handling -mllvm -wasm-enable-sjlj -mllvm -wasm-use-legacy-eh=falseand links-lsetjmp, because the panic handler usessetjmp; the runtime defines the__c_longjmpexception tag that the wasmsetjmplowering needs. Programs read their arguments fromargs_getand write/dev/stdoutand/dev/stderrto descriptors 1 and 2. The std items WASI cannot back are E0991 on this target, like a@targetfunction that does not exist there:Process.run, every function ofstd/thread,std/parallel,std/channel,std/sharedandstd/atomic, the functions ofstd/net, andTerminal.columns. A use inside anifthat dropsOs.Wasi(if (Build.os != Os.Wasi)) is accepted. Their signatures are the same on every target. The async loop on this target has timers and no descriptor waits: a turn with nothing ready sleeps until the nearest timer.narrac test --target Wasi-Wasm32is not supported:testrejects--targeton every row. -
narrac build --target <name>andnarrac check --target <name>use another target's row for the build conditions.buildalso passes-target <triple>to the C compiler, before its other flags, when the row is not the host's (the triple is thezig cc -targetform, for examplex86_64-linux-musl), soCCmust be a cross compiler such aszig cc. An unknown name is E1600 and lists the names;-sanitizewith a target other than the host is E1601.narrac targetsprints one line per row: the name and the triple. -
@targetbefore anextern { } fromblock declares its C functions, and links its library, only when building for its target. It applies to every member of the block, since a block names one library, and each member follows the rules of a@targetfunction above. Only the block takes the attribute; a member does not (E1000).
import { Os } from "std/build"
@target(os = Os.Windows)
extern {
function GetTickCount64(): u64
} from "kernel32"
- There are no per-platform file names and no preprocessor.
13. Tests and contracts
test "name" { ... }blocks sit next to the code.narrac testruns them. They are removed from non-test builds.std/testhas assertions for test blocks. Its functions can be called only inside atestblock, arrow functions inside it included; a call anywhere else is a compile error. The import itself may stay in a file that is also built as a program, because test blocks are not part of that build.Test.eq<T: Equatable & Show>(actual: T, expected: T)panics withexpected <expected>, got <actual>when the values differ.Test.ne(actual, other)panics withexpected a value other than <other>when they are equal. Both values are written withShow, and the panic names the call'sfile:line:col.Test.panics(f: () => void)callsfand panics unlessfpanics.Test.panicsWith(f, message: string)also needs the panic message to containmessage.Test.golden(name: string, actual: string)comparesactualwith the file<name>.goldenin the package'stestdata/directory (for a single file, in the file's own directory). It fails withgolden <name> differs at line N: expected "<line>", got "<line>", or when the file is missing. With the environment variableNARRA_UPDATE_GOLDEN=1it writes the file instead and passes.namemay contain/but no path segment equal to.., and it is not empty. The missing-file message names<name>.golden, not the directory. When the test binary runs alone, the directory istestdata/relative to the working directory, unless--golden-dir <dir>is given. It declaresio; test blocks may use any effect without declaring it.- A failed assertion is a panic that fails its test only.
narrac testruns each test in its own process, in source order, and goes on after a failure. It prints one line per test to standard output:ok - <name>, orFAIL - <name>: <message> (<file>:<line>:<col>). Output a test prints appears before its line. The last line isN passed, M failed. The exit code is 1 when a test failed, otherwise 0. A test that crashes or leaks memory in a debug build fails with the signal or exit code.narrac test -filter <text> fileruns only the tests whose name contains<text>.narrac test -time fileappends(N ms)to each test line. Without it no timing is printed.- A filter that matches no test prints
no tests match "<text>"and exits 1. A file with no tests at all prints0 passed, 0 failedand exits 0. - Every test has a time limit: 10 seconds, or
NARRA_TEST_TIMEOUT(a positive number of seconds). A test that runs past it fails withFAIL - <name>: timed out after N sand the run goes on. ATest.panicsclosure gets the same limit, or the time left on the test's limit minus one second (at least one second), whichever is smaller, so its own timeout message comes first. - With
NARRA_CHECK_LEAKSset (debug builds of the project's own tests), a test that leaks fails withleaked N allocations. - The test binary reads
--filter <text>,--timeand--golden-dir <dir>(one or two dashes) from its own arguments, so it can be run directly.narrac testpasses the golden directory itself, so the generated C holds no path. Other arguments are an error (exit 2), and so is an option without its value. Flags may also follow the file name. fruns in a child process, so nothing it changes or allocates reaches the test. Output it prints appears in order.Test.panicsandTest.panicsWiththerefore need a POSIX system (fork). A closure that runs past the timeout (10 seconds, orNARRA_TEST_TIMEOUT) fails.
import * as Test from "std/test"
test "parse" {
Test.eq(Int.parse("ff", 16), Ok(255))
Test.ne(Str.trim(" a "), " a ")
Test.panicsWith(() => divide(1, 0), "division by zero")
}
- Contracts.
requireslines between a function's signature and its body state what each caller must prove (D95). They are proven at compile time; nothing is checked at run time.
export function pick(index: int, count: int): int
requires index >= 0 && index < 64
requires count != 0
{
return index % count // count != 0 is known here
}
function pickChecked(n: int): int {
if (n >= 0 && n < 64) {
return pick(n, 8) // a name the `if` checked proves the condition
}
return pick(3, 8) // so do constants
}
- A condition is clauses joined by
&&(D102). A clause is one comparison, or comparisons joined by||; parentheses group a clause:requires (index >= 0 || index == -1) && count != 0. A comparison is==,!=,<,<=,>or>=between an integer parameter and an integer constant, with the parameter on either side, or between two integer parameters of the same type (a relation:requires low <= high). Constants are what division proofs accept (section 6): literals and top-levelconstvalues built from them. Any other condition is E0984: a float or other non-integer parameter, a field path, a call,!(the message gives the condition without it:!(x < 0 || x > 9)isx >= 0 && x <= 9), arithmetic around a parameter in a relation (low + 1 <= high, since+wraps), a parameter compared with itself, and&&inside||(split it into clauses). Floats and field paths are a later extension. - Each call proves every clause: one of its comparisons must be proven. A comparison with a constant is proven from the argument for that parameter: an integer constant, or a name narrowed by a check (
if,while, an early return), as for a divisor. A name with no check proves nothing, not even a bound at the end of the int range. A relation is proven from two constants (a u64 constant from 2^63 up is above every other), from intervals whose bounded ends settle the order (x <= ywhen the high end ofxis at most the low end ofy), from the same name passed twice, or from a relation the caller holds between the two names, from its own checks (if (low <= high)) or its ownrequires. A caller that checkedif (x < 0 || x > 10)knows only the hull of the sides (below), which proves neither side ofrequires x < 0 || x > 10. The caller's ownrequirescount, sorequires count > 0lets the body passcounton to another function withrequires count != 0. An unproven clause is E0985 at the argument of its first parameter, naming the whole clause. - In the body each clause is a known fact about its parameters, until a parameter is assigned: a body with
requires divisor != 0may divide bydivisor. A clause over one parameter gives it the hull of its sides, the smallest interval that holds each:requires x == 1 || x == 3gives1 <= x <= 3, andrequires d < 0 || d > 0gives a non-zerod. On a u64 a side with a bound from 2^63 up proves nothing, so the hull proves nothing either. A clause over two parameters gives nothing. A relation is a fact too: it proves calls with the same or a weaker relation (<proves<=and!=), and it passes bounds one step (section 4), sorequires low >= 0 && low <= high && high < 64makeslowa valid shift count. It proves nothing abouthigh - low, which can wrap. - A function with
requirescannot be used as a value (E0986), andtypeofof it is E0982: a function type carries no condition, so a call through the value could pass an unproven argument. Functions of animplementblock cannot haverequires(E0984), since a call through the trait proves nothing. ensureslines follow therequireslines. Each is a pattern every result must match, with no named subject. Everyreturnvalue is proven against each line; in a generator, everyyieldvalue, andyield*is E0988. A pattern holds one bound per place, with no&&: write two lines,ensures Some(>= 0) | Noneandensures Some(< 64) | None, and a caller learns both.
import * as Arrays from "std/array"
function findIndex(items: Array<int>, wanted: int): Option<int>
ensures Some(>= 0) | None
{
let index = 0
while (index < Arrays.length(items)) {
if (items[index] == wanted && index >= 0) {
return Some(index) // index >= 0 is known here
}
index++
}
return None
}
function slot(index: int): int
requires index >= 0
{
return index * 2
}
function firstSlot(items: Array<int>): int {
if (findIndex(items, 7) is Some(index)) {
return slot(index) // the caller knows index >= 0
}
return 0
}
- The patterns are the patterns of
match(section 5), alternatives included, plus comparison patterns< c,<= c,> c,>= cand!= c, which are allowed only inensures:ensures >= 0,ensures Ok(> 0) | Err(_),ensures #[>= 0, _],ensures { width: > 0 },ensures "GET" | "POST",ensures != 0. A comparison needs an integer place and a bound that is an integer constant fitting its type (E0987). The prover orders integers asint, so a u64 bound or literal pattern from 2^63 up is E0987 too, and so is a literal pattern9223372036854775807or-9223372036854775807: the ends of the int range stand for "no fact". Anensurespattern binds no names, and a function that returns nothing has noensures(E0987). - A value is proven when it is written to match: a constructor, tuple or struct literal written in place whose parts are proven (a struct field must be written, not taken from a spread or a default), a literal written the same, an integer constant, or an integer name narrowed by a check. Anything else is E0988, including a call:
return g(x)is not proven from g's ownensures; bind it first. - A caller learns the pattern as facts about integer names, the same facts a check gives:
const n = f()(andlet n = f()until it is assigned), the names bound byf() is P, bymatch (f())arms and by a destructuring off(), the same for aconst r = f()whose type has no contents that change in place, and the name offor (const n of g())for a generatorg. A name bound bySome(n)learns what every alternative that can beSomesays about its place.!= 0makes the name non-zero, so it can be a divisor;!= cfor anothercgives no fact.
14. Tooling for agents
Diagnostics
narrac check --json prints one JSON object per diagnostic:
{
"code": "E0412",
"severity": "error",
"message": "Function `load` uses `io` but its signature does not declare it",
"file": "src/app/config.nra",
"range": {"start": [12, 4], "end": [12, 22]},
"fixes": [
{"title": "Add `io` to the signature", "edits": [{"file": "src/app/config.nra", "range": {"start": [8, 40], "end": [8, 40]}, "text": ", io"}]}
]
}
- Error codes are stable.
narrac explain E0412prints the rule and an example fix. - Fixes are exact edits that an agent can apply without rewriting them.
- TypeScript habits get a fix. Each row of "Differences from TypeScript" (section 2) has a diagnostic, except the row on value copies (
const b = a), which compiles. Its fix rewrites the TypeScript form into the Narra form. For example,===is rewritten to==, andxs.push(v)toArrays.push(mutable xs, v).
Queries
| Command | Output |
|---|---|
narrac query type-of FILE:LINE:COL |
The type and effects at a position |
narrac query def NAME |
Where a name is defined |
narrac query refs NAME |
Every use of an exported name |
narrac query callers FUNCTION |
Every function that calls it |
narrac query interface MODULE |
The module's exported signatures |
narrac query recursion MODULE |
The module's recursive functions |
narrac query hovers FILE |
The hover text of every name in a file, and its diagnostics |
All query commands accept --json.
Language server
narrac lsp is a Language Server Protocol server on stdin and stdout. It works with any LSP client.
- Messages use the LSP framing: a
Content-Lengthheader, other headers ignored, then the JSON body. - Lifecycle:
initialize,initialized,shutdownandexit.exitends the server with code 0 aftershutdownand 1 before it. The end of the input withoutexitalso ends it with code 1. initializeanswers full text sync,documentFormattingProviderand apositionEncoding. The encoding is"utf-8"when the client offers it, else"utf-16".- A request before
initializegets error -32002, an unknown request -32601 and a message that cannot be read -32700. Unknown notifications are ignored. textDocument/didOpen,didChange(the full text) anddidClosekeep the editor's text, which replaces the file on disk. After each open or change the server checks the package that holds the file (the nearestnarra.toml; a file with none is checked alone). It then sendstextDocument/publishDiagnosticsfor every module of the package, with an empty list for a module that has no problem. A diagnostic's range starts and ends at its position. Itscodeis the diagnostic code.didClosechecks the package again from the files on disk and empties the list of the closed document.textDocument/formattingformats with the[fmt]table of the nearestnarra.toml. It returns one edit that replaces the whole document, an empty list when the document is already formatted, ornullwhen it does not parse.
Speed target
narrac check on an unchanged package with one edited file returns in under 100 ms.
15. Packages
- A package is a directory with a
narra.tomlmanifest and asrc/directory. - The package name is the import path prefix. Package
jsonexposessrc/parse.nraas"json/parse". - Dependencies are git repositories pinned to version tags. There is no central registry.
[package]
name = "app"
version = "0.1.0"
[dependencies]
json = { git = "https://github.com/example/narra-json", version = "1.2.0" }
[[binary]]
name = "app"
entry = "app/cli.run"
[link]
search = ["/opt/homebrew/lib"]
narrac build --target <name>builds for another target (section 12).narrac targetslists the names and their C compiler triples.- Entry points are set in
narra.toml. Each[[binary]]names the binary and its entry function as"module.function". A package with no[[binary]]is a library. - The entry function has the signature
export function run(args: Array<string>): int, orexport async function run(args: Array<string>): int. The result is the process exit code; for an async entry, the value of itsAsync<int>. It has every effect. Tasks still running when it finishes are cancelled (section 8). [link]has one key,search: directoriesccsearches for libraries (-L), relative to the package directory unless absolute. The libraries come from thefromof extern blocks (section 9); any other key in[link]is E1000.- Version selection is minimal version selection, as in Go. Each dependency resolves to the highest version that some package in the graph requires as its minimum. The result is the same on every machine and needs no solver.
- One version per package in a build. A major version change is a new package name, such as
json2. narra.lockrecords the commit hash and content hash of every dependency.narrac buildfails when a fetched dependency does not match its hash.[dependencies]holds one inline table per dependency:name = { git = "...", version = "1.2.0" }.gitis a URL or a local path;versionis the minimum version asMAJOR.MINOR.PATCH, and its tag isvplus the version.[package] versionhas the same form. The name is the import path prefix and follows the rules of a package name.narra.lockshape. A TOML file with a comment line, then one[[package]]table per dependency, sorted by name, with the keysname,git,version(the selected version),tag(the git tag the version was fetched from:v<version>, or<name>/v<version>in a repository that tags by package),commit(the full commit hash of the tag) andcontent(the git tree hash of that commit), in that order. The reader checks thatnameis a package name,gitis not empty,versionisMAJOR.MINOR.PATCHwith each part in the range ofint,tagis one of the two tags of the version, andcommitandcontentare 40 or 64 lowercase hex digits. A value may hold the escapes\n,\t,\r,\",\\and\uXXXX, and the writer escapes every control character. The tag is what lets a build use the cached checkout of exactly that tag again: a checkout of another tag of the same repository is never taken for it, and thenarra.tomlof a checkout must name the package that asked for it (E0453).- Manifest and lock errors: E0430 a dependency without
gitorversion; E0431 a version that is notMAJOR.MINOR.PATCH; E0432 an unknown or repeated key in a dependency; E0433 a dependency namedstdor like the package; E0434 two dependencies with one name; E0435 a dependency that is not a valid inline table, such as one with a trailing comma; E0436 an invalid dependency name; E0437 a malformednarra.lockline or a value that is not well formed; E0438 a lock entry with an unknown, missing or repeated key, or a tag that is not the tag of its version; E0439 two lock entries with one name. - The cache and the checkouts are trusted. The cache folder is
$NARRA_CACHE(a relative path is made absolute against the working directory), or$HOME/.cache/narra. A fetch records the commit hash and the tree hash of the tag beside the checkout (<checkout>.hash) and removes the history. A build compares the recorded tree hash withnarra.lock, and the language service compares it with thecontentof the lock. Neither re-hashes the files of a checkout, so a file changed in the cache after the fetch is built as it is. A symbolic link inside a checkout is followed. The folder names in the cache keep at most 64 bytes of the readable name of the URL or tag, followed by a hash of the whole name. Anyone who can write to the cache can change what a build compiles; keep it writable by the user who builds. A checkout is read-only; remove one withchmod -R u+wfirst. - A git dependency on a member of another repository.
json = { git = URL, version = "1.2.0" }finds the package namedjsonin the checkout: the root package, or else the member of the root's[workspace]with that name, and the sources load from that member'ssrc/. A repository whose root has[workspace]tags each member<name>/v<version>, for examplejson/v1.2.0. When a repository has any tag<name>/v<version>, only those tags give the versions of<name>; otherwise the tags arev<version>. A cached checkout of the plain tagv1.2.0is never taken forjson 1.2.0when the repository has member tags, so two machines lock the same commit. Inside a fetched checkout,core = { workspace = true }is a requirement on the same URL for the siblingcore, at the[package] versionin the sibling's manifest at that commit, so an author tagscoreat that version before taggingjson. The versions then follow the usual selection: if the app also asks forcore1.2.0,core1.2.0 is selected. Errors: E0486 the checkout has no package of that name; E0487 a sibling without aversion, or a sibling version with no tag. - A lock URL that changed. When
narra.lockrecords a package from one URL and the manifests now resolve it from another, the build printsnotice: <name> was locked from <old URL> and now resolves from <new URL>on stderr and rewrites the lock. It is not an error. - Building with dependencies. Every command that loads a package (
build,run,test,check,queryand the dump commands) on a package with[dependencies]or[overrides]resolves the manifests, compares the result withnarra.lock, fetches each selected tag into the cache, writes the lock when its text changes (before the sources load, so a later load error leaves the new lock), and loads the sources of every dependency insrc/as modules<name>/<path>of the same program. The package being built comes first in the node numbering. The C names of a dependency's modules hash the package name, a colon and the rest of the path (json:text), and those of the package being built hash the path without the package name, so the emitted C of a package with no dependencies is unchanged.narrac testruns the test blocks of the package being built only. A diagnostic in a dependency names the file as<name>/src/<path>. - Imports between packages. A package may import itself,
stdand the packages in its own[dependencies]. Importing a package that is in the build only because another package needs it is E0463. [exports]maps import paths to module files:"json/stream" = "src/streaming/reader.nra". A key is the package name (the bare name stands for one module, such as"json" = "src/index.nra") or starts with<name>/; a value is a path undersrc/that ends in.nra. Without the table, every module is exposed by its path. With it, another package may import only the keys; any other path is E0473, and the message lists the keys. The importer writes the key, and the compiler loads the module the value names. Modules of the package itself import each other by their real paths. Errors: E0470 a key that does not start with the package name; E0471 a value that is not a module file, or names a file the package does not have; E0472 two entries with one key (so the bare name cannot map twice).- std exposes every module except those under
std/internal/andstd/ext/. Another package that imports one of them gets E0474. std has nonarra.toml; the list is built into the compiler. - The language service (
narrac lsp) loads the same program fromnarra.lockand the cache. It never fetches and never writes the lock, and it publishes no diagnostics for dependency files. A lock with no entry for a dependency of the manifest is E0461; an entry whose checkout is not in the cache is E0460. In a workspace,narrac lspskips anarra.tomlthat has no[package]. Editing a member also checks every member that depends on it. A member's load errors are published only by that member. Go to definition reaches the files of members but not the files of git dependencies. - Workspaces. A
narra.tomlwith a[workspace]table makes its folder a workspace root.memberslists package folders relative to the root: a*stands for one whole path segment and matches every folder there with anarra.toml, and an entry that starts with!removes the folders it matches. Each member has a[package]table and a name no other member has; a member may not have its own[workspace](E0480 to E0482). A root that also has[package]is a member of its own workspace. A package whose folder is not listed is standalone.{ workspace = true }in[dependencies]names the member with that name; it takes no other key (E0483), it is not fetched and has no lock entry, and a name with no member is E0484. A git dependency with a member's name is E0450.[overrides]is allowed in the root manifest only (E0454). Onenarra.locksits at the workspace root and covers every member; anarra.lockinside a member is E0485. Each git package has one version across the members, so building one member selects the same versions as building all of them. - Commands in a workspace. The path given to
build,run,test,check,fmtandqueryselects the work. A member folder selects that member. The workspace root selects every member, in the order of themembersentries (the root package first; the matches of one*entry sorted by folder):buildmakes every binary of every member,run -bin NAMEruns the binary of the member that has it,testruns the tests of each member as one program per member and prints== NAME (DIRECTORY) ==before each when more than one runs (the exit code is 1 when any fails; with-filter, a member that has no matching test is skipped, and the command fails only when no member matched),checkchecks each member as its own program and merges the diagnostics sorted by file, line and column (a diagnostic that two members report for the same dependency is printed once),fmtformats the files under every member andqueryasks every member and prints the answers of those that have one, each location named from the member folder (with--json, one object: fordef,refs,callers,interfaceandrecursionits list holds the entries of every member's answer, and its other fields (name,module) are those of the first member that answered;type-ofnames a file, so one member answers, and the first answer is printed). A diagnostic of a member names its file from the member folder; a diagnostic in a dependency that is also a selected member is reported once, for that member. A path that is a file keeps its meaning. With a member folder,-dependentsadds every member that depends on it, directly or not, and-dependenciesadds every member it depends on.build,testandchecktake both flags, and the flags may follow the path. Two members with a binary of one name are E0488 forbuildat the root and forrun -binof that name. A flag with a path that is not a workspace member (a file, a folder outside the workspace, or the workspace root) is E0489. A cycle ofworkspace = truedependencies between members is E0490, found whenever a root or a flag selects members, that is forbuild,run,testandcheck.fmtandqueryskip the cycle check on purpose. [fmt]in a workspace.narrac fmttakes the[fmt]of the nearestnarra.tomlthat has a[fmt]table. A package without[fmt]that is a member of a workspace takes the[fmt]of the workspace root, then the defaults. Anarra.tomlwith neither[package]nor[fmt]is skipped, so a repository root that only declares a workspace gives the files below it no settings.- Build errors: E0460 a locked dependency that is not in the cache (language service); E0461
narra.lockhas no entry for a dependency (language service); E0462 a dependency with no.nrafile insrc/; E0463 an import of a package the importing package does not list. Resolution and fetch errors are E0440 to E0458.
16. Deferred
These are left out of the first version on purpose.
- Thread cancellation. A thread runs until it returns. Async tasks have a cooperative cancel (
Async.cancel, section 8), and a timeout isAsync.racewith asleep; a cancel design for threads is not decided. - A cycle collector for identity objects. Cycles through identity types leak and the leak check reports them (section 6, D80).
- Functors and module parameters. See
DECISIONS.md, D6. - A native debug backend. See
DECISIONS.md, D10. - A bytecode VM. Possible later for scripting and hot reload. The first target is native code only.
narrac move old new. A command that moves a file and rewrites every import of it. It is not built yet:narrac moveprints the usage line and exits 2.