The grammar determines what can be written. The rules below determine which programs are valid and how they run.

Types and inference #

  • Int: Signed 64-bit integer; overflow is a runtime error
  • Float: IEEE 754 binary64
  • Bool: Only true and false; there is no truthiness
  • String: Unicode text; concatenation with +, repetition with * Int
  • Bytes: Immutable byte string, one byte for each item (0..255); no literal (§6, “Bytes”)
  • Nil: A single data value, nil
  • Void: Completion without a usable value; no literal
  • List[T]: Homogeneous, immutable list; Int indexes from zero
  • Map[K, V]: Homogeneous, immutable map; the key K is Int, String or Bytes; keeps insertion order
  • Set[T]: Immutable set of distinct Int, String or Bytes values; keeps first-insertion order
  • Result[T]: ok(value), or error(...) holding an Error
  • Error: Builtin record of a failed Result: kind: String, message: String, code: Optional[Int], details: Map[String, String], cause: Optional[Error] and location: String
  • Optional[T]: some(value), or none for a value that is missing
  • JSON.Value: Opaque JSON value, used through the JSON module
  • Range: Immutable Int range: a..b includes b, a...b excludes it
  • Fn[A, ..., R]: Function value; the last type is its return, the others are its parameters
  • Task[R]: Opaque lightweight task with one result type
  • TaskRef: Opaque running task from Task.current, with no result type: it can be monitored, cancelled and identified, not awaited
  • Await[T]: Builtin enum of a timed Task.await: Await.Done(value) or Await.TimedOut; matched with case like a user enum
  • Logger.Level and Logger.Event: Builtin enum and record of std/logger (LogRegistry.Level and LogRegistry.Event, re-exported). Logger.Level is matched with case like a user enum; Logger.Event, which a log handler receives, is not JSON-decodable. Their variants and fields are on the Logger page
  • StructMember: Builtin record of Type.members: name: String and type: String, the field name and its type written as source
  • TaskExit: Builtin enum of how a task ended: TaskExit.Ok, TaskExit.Crashed and TaskExit.Cancelled
  • TaskDown: Builtin record that Task.monitor sends when a task ends: task_id: Int, reason: TaskExit, and the diagnostic of a crash, code: String, message: String, file: String, line: Int and column: Int; it is not JSON-decodable
  • Channel[T]: Opaque bounded queue of T values that tasks send into and receive from
  • Address[T]: Send-only reference to a Channel[T] (channel.address); it is data, not a handle. Address is not reserved: written with one type argument it is this builtin, so a program may still declare its own struct Address, but not a generic one (section 6c)
  • Enum[T, ...]: User-declared nominal sum type
  • Declared struct: Nominal type with typed, immutable fields

Parameters and function return types need annotations. Local variables may be inferred from the initializer, as in count = 3. An empty list, map or Set.new([]) needs an expected type, from an annotation, a parameter, a field or a return type: names: List[String] = []. A non-empty list has one element type. There is no implicit numeric conversion and no Any type. Nil is not a nullable wildcard: name: String = nil is invalid; use Optional[T].

Operators #

  • +, -, * and / take two operands of one numeric type; + also concatenates Strings, Bytes and two lists of one type (a new list), and s * n repeats a String n (an Int) times; a negative n, or a result over 256 MiB, is RUNTIME-INVALID-COUNT. Integer / truncates toward zero, and % takes integers only, with a = (a / b) * b + (a % b). Division by zero is RUNTIME-DIVISION-BY-ZERO, for Float too. An integer result outside Int is an error.
  • Ordering operators take two numbers of one type. == and != take two values of one type that has equality: a primitive type, Range (equal when start, end and kind match), Bytes (the same length and bytes), Address (equal when they name the same channel), and List, Map, Set, Optional, Result, structs and enums whose parts have equality. Lists are equal when they have the same length and equal items in order; maps when they have the same keys with equal values, and sets the same elements, in any order; Optionals, Results and enums when they have the same variant and equal payloads (error compares the message, and ok() == ok() for Result[Void]); structs when they have the same type and equal fields. A struct or enum that holds itself (children: List[Node]) has equality when no type of its group lacks it. Functions, tasks, channels, handles and JSON.Value have no equality, nor does any type that holds one, nor a type variable of a generic function: CHECK-TYPE-MISMATCH, whose message names the field or variant without equality. A Float follows IEEE 754 at any depth, so a list or struct that holds a NaN is not equal to itself. A list, map, set, Optional, Result, struct or enum on the left gives its type to the right side, so x == none and xs == [] check. .. and ... take two Int values.
  • and, or and not take only Bool. &&, || and ! are the same operators. A ! directly after a name belongs to it (read!); != is inequality.
  • There is no operator overloading. Expressions, arguments and constructor fields are evaluated left to right. Float comparisons follow IEEE 754: NaN is not equal to itself.

Variables and scope #

The first assignment introduces a variable in the current scope, and an annotation is allowed only there. Later assignments change its value, not its type. Each function and control block is a lexical scope. An assignment without annotation updates a visible variable of that name, or else introduces a local in the current block. A new name cannot shadow a visible one, so one name means one variable in a scope. Parameters and the for variable are initialized bindings; the for variable cannot be reassigned. Variables created in a block are not visible after its end.

_ is a discard wherever a name is bound: an assignment target (_ = f()), a for variable, a block or function parameter and a pattern slot. It binds nothing, so it can repeat and never conflicts with another name. Reading _ is CHECK-UNKNOWN-NAME, and _: Int = x is PARSE-UNEXPECTED-TOKEN.

A name that is never read is CHECK-UNUSED-VARIABLE, unless it starts with _ (_count): the opt-out for a name kept on purpose, and the name can still be read. The rule covers a variable introduced by an assignment, a for variable, a block parameter and a name in a case pattern; it never covers a function parameter, which is part of the signature that callers, &name callbacks and adapters depend on. A name is read when it is evaluated as an expression anywhere in its scope, in a nested block too. An assignment to the name itself is not a read of it: in x += 1, x = x + 1 and xs = xs.push(v) the x on the right does not count, so a counter that is only incremented, or a list that is only appended to, is unused. The rule is per variable, not per assignment: x = 1, x = 2, puts(x) is valid. The error is at the place where the name is introduced (the assignment statement, the for variable, the block parameter or the pattern name), the first in the source when several are unused, and it is found at the end of the function, after every other error of it. To drop a value, write _ = f(); to ignore a loop variable, a parameter or a payload, write for _ in 0...n, |_, i| or error(_). The query commands (type-at, refs, symbol) do not report it in the file they are asked about, since an editor writes a name before its first use; the files that file imports keep the rule.

Module constants #

A constant (section 5) is a value fixed for the whole run. It is read by its name, as an expression, so everything that works on a value works on it: LEVELS.get(kind, 0), KEYWORDS.include?(word), CLASSES[code], CONFIG.port, "#{LIMIT}". A local variable, a parameter or a block parameter is never an all-capitals name, so a constant cannot be shadowed, and nothing assigns to one: LIMIT = 2 or LIMIT += 1 inside a function is PARSE-INVALID-ASSIGNMENT-TARGET. A constant is not a pattern: case patterns are literals and variants, and a constant name where a pattern goes is PARSE-UNEXPECTED-TOKEN with the help a constant is not a pattern; compare with if. A constant of a struct type can be updated like any struct value: CONFIG.with(port: 81) gives a copy and the constant stays as it was.

The initializer is a constant expression, and its rules are checked after the whole program is read, in the order the constants depend on each other (a constant may read one declared later in its file). It may contain literals, string interpolation, list, map and Set.new literals, ranges, construction of structs, enum variants and ok/error values, operators, field access and indexing, reads of other constants, regex literals, and calls of builtins whose catalog row has no effects, with block literals passed to them (the body of such a block may use assignments, if, case, for, break, next and return). It may not contain a call of a function declared with def, a function value (&name), a block that is not an argument of a builtin, a while loop, or a call of a builtin with effects (stdout, stdin, filesystem, network, subprocess, clock, random, concurrency and the rest): each is CHECK-CONSTANT-EXPRESSION, located at that form. Every expression inside the initializer, not only the result, has a data type: numbers, String, Bool, Nil, Bytes, List, Map, Set, Range, Result, Optional and JSON of data types, and structs and enums whose fields and payloads are data; a function, Channel, task, handle or ATS table type (and Void) is CHECK-CONSTANT-TYPE, located at the expression, and so is a type that holds an Address (an address names a channel of the running program, and no channel exists before main). Channel.new has no effects, but it makes a value with identity and state, which is why the type rule exists.

One initializer is exempt from the type rule: a whole initializer ATS.new(), a constant table (NAMES: ATS[String, Address[Msg]] = ATS.new()). The annotation gives its type (without one it is CHECK-EXPECTED-TYPE), and ATS[K, V] keeps its own rules (CHECK-ATS-VALUE). A table is already shared and atomic and has no owner, so the constant only gives it a name: there is one table per declaration per run, shared by every task and every file that imports it. A table anywhere else in an initializer ([ATS.new()], a struct field, another constant’s table) stays CHECK-CONSTANT-TYPE.

A scalar literal constant is part of the bytecode. Every other constant is built once, in dependency order, before main starts, and only if a function that main can reach reads it (directly, or through another constant): a constant that nothing reads never runs. An initializer that fails (BAD = [1][5], an index out of range) stops the program before main prints anything, with a stack trace that names the constant.

Constants that read each other in a loop, directly or through others, are CHECK-CONSTANT-CYCLE, located at the read that closes the cycle, with the help the cycle is A -> B -> A. The checker follows the reads of an initializer in the order of their start offsets in the source, constants in the order of the linked declarations, which also gives the order the constants are set up in. An unknown name in capitals is CHECK-UNKNOWN-NAME, with a did you mean help over the constants the file can read: its own, declared above or below, and the ones it imports by name, by the name written. The nesting limit (CHECK-TOO-DEEP) counts initializers too.

Decided against. Literals only, with no evaluation: it cannot express the compiler’s own tables (Set.new(...) is a call, the character classes are a fold, the builtin rows are struct constructors). Compile-time evaluation: it would put the semantics of every allowed builtin in the compiler and the VM both. Lazy initialization on first read: an initializer error would surface in the middle of a run, a read would need a branch, and tasks could race on the first read. Calls of user functions in an initializer. An Elixir-style @name attribute or a const keyword, since the capitals already mark a constant. A constant in a case pattern: patterns are literals and variants. Folding literal arithmetic. One line holding both import forms.

Regex literals #

A regex literal (lexical form in §4) has the type Regex.Regex of std/regex, and its value is Regex.compile of the body, after (?i), (?s) or (?is) for the flags i, m or both. So /a.b/im has the source (?is)a.b. The file must import std/regex, in any form (an alias, another alias, or a name list); without one the literal is CHECK-REGEX-IMPORT, at the literal. The checker compiles the pattern with std/regex, so a literal never fails at run time: a pattern it refuses is CHECK-INVALID-REGEX, at the character of the body that the error names, or at the whole literal when the place is past the body.

A literal in a function or block body is built once, before main, as a constant is, and only if a function that main can reach holds it: a loop does not compile it again. A literal in a constant initializer is built with that constant. ^ and $ are text anchors, not line anchors as in Ruby; /(?m)^a/ gives line anchors. There is no =~ and no $1: use Regex.match?, Regex.match and the groups of the match.

Void completion #

Void has no literal and no usable payload. It is allowed as a function’s return type, as the last type of Fn, and as the completion type of Result or Task. Bare Void variables, parameters, fields, list elements and map values are CHECK-VOID-TYPE. Wrappers such as List[Result[Void]] are valid.

A Void call may be a statement, or be returned from a Void function. Assigning, passing, constructing, operating on or inspecting a Void result is CHECK-VOID-VALUE, and so is Result.unwrap! on Result[Void], Task.await on Task[Void], or a successful try on Result[Void]. ok() infers Result[Void], and ok(nil) is Result[Nil]. Result.unwrap_or cannot operate on Result[Void]. The timed Task.await(task, timeout_ms) on a Task[Void] is not a Void value: it gives Await[Void], which is matched as Await.Done(_) or Await.TimedOut.

Functions and entry point #

  • Functions can be called before their declaration, and can be recursive. There is no overloading. A parameter may have a default value, and an argument may be given by name (below).
  • A function with a non-Void return type must give a value on every reachable path. A loop does not guarantee one.
  • The value of such a function is its last expression, unless a return leaves before it. When the last statement is an if with an else, or a case, the rule applies to the last statement of each branch and each arm, at any depth. An if without else, a loop, a binding or a try statement at the end gives no value: CHECK-MISSING-RETURN at the function. A last expression of type Void (a call) gives none either: CHECK-MISSING-RETURN at that expression. A last value of another type is CHECK-TYPE-MISMATCH there.
  • The rule reads the result type as written. In a Void function, and in one whose result is an alias of Void, the last expression is a statement whose value is dropped: CHECK-UNUSED-VALUE and CHECK-UNUSED-RESULT apply to it. Blocks give their last expression already (below).
  • return without a value completes a Void function. A Nil function ends with nil.
  • An executable declares exactly one main() -> Void with no parameters and no type parameters. A run and agentica compile report CHECK-MAIN without it; agentica check does not need a main, but one that is declared must have this signature. Under agentica test a *_test.agc file with no main gets one that runs its test_* functions (06c-tasks-and-tests.md).

Default parameter values #

def join(xs: List[String], sep: String = ", ") -> String = xs.join(sep)

join(["a", "b"])        # a, b
join(["a", "b"], "-")   # a-b

A parameter written NAME: type = expression has a default value, which a call may leave out. After a parameter with a default, every parameter has a default, except a last parameter of type Fn[...], which stays without one so that a block can still fill it. Any other parameter without a default after one with a default is CHECK-DEFAULT-ORDER, located at that parameter.

A default is a constant: an Int, Float or String literal (a minus sign is allowed before a number, and a string has no #{...}), true, false, nil, none, [], {}, or a nullary enum variant (Level.Info, TaskExit.Ok for a builtin enum, or Models.Level.Info through an import alias). A parameter may also default to a struct built with no arguments, options: Options = Options(): each field takes its own default, and a field without one is CHECK-MISSING-FIELD at the default. A default may also name a module constant (limit: Int = LIMIT): one of the same file, an imported one through its alias (Limits.LIMIT) or one imported by name, as long as the value of the constant is itself one of these forms (not a call, an operation, another constant, a non-empty list or map; a struct with no arguments only for a parameter). The name is the value written in its place, so the default is the same at every call and a caller in another module that leaves the argument out gets it without importing the constant. Anything else (a call such as some(1), any other name, &name, a struct with arguments, a variant with a payload, a non-empty list or map, an interpolated string, an operation) is CHECK-DEFAULT-VALUE, located at the expression, with a help that says to make the parameter required. A default cannot read another parameter.

The type of a default is checked against the type of its parameter like an initializer: [] and {} take the parameter type as their expected type, and a mismatch is CHECK-TYPE-MISMATCH at the default. A default is built at each call, so no call shares a value with another.

Named arguments #

def check(gen: Gen, runs: Int = 100, seed: Int = 0, verbose: Bool = false) -> Report

check(gen, verbose: true)        # runs and seed keep their defaults
check(gen, 200, verbose: true)   # positional first, then named

A call may give any argument as name: value, where name is a parameter of the function: definitions do not change, so every function of the program, of std/ and every builtin takes names. The positional arguments come first and fill the parameters from the left; a positional argument after a named one is PARSE-UNEXPECTED-TOKEN at that argument. Each named argument fills the parameter of its name, in any order, and a parameter left out takes its default. A trailing block fills a last Fn parameter that follows defaults, as in a positional call, and otherwise the first parameter no other argument fills: xs.reduce(initial: 0) do |acc, x| ... end. The positional arguments still fill from the left, so with named arguments a function value for that last Fn is passed as a block or by name (f: &show), not by position. The arguments run in the order they are written, not in the order of the parameters.

A name that is no parameter is CHECK-UNKNOWN-ARGUMENT, and a parameter given twice (two names, or a name and a position) is CHECK-REPEATED-ARGUMENT, both at the named argument. A parameter without a default that no argument fills is CHECK-MISSING-ARGUMENT at the call. A parameter named _ has no name.

Names are not part of an Fn type: a function value is called with positional arguments only. f.call(x: 1) is PARSE-UNEXPECTED-TOKEN, and a named argument to an Fn field of a struct (s.run(x: 1)) is CHECK-UNKNOWN-ARGUMENT. Struct construction, .with(...) and the named arguments of error(...) keep their own rules. The call is a positional call once checked: names cost nothing at run time.

A call to a function with N parameters without a default and M in all takes N to M arguments; any other count is CHECK-ARITY. Arguments fill the parameters from the left. When the last parameter is an Fn without a default, the block (or else the last argument) always goes to it, and the other arguments fill the parameters before it from the left. With def each_line(path: String, timeout_ms: Int = 1000, f: Fn[String, Void]) -> Void, both each_line("a.txt") do |line| ... end and each_line("a.txt", 50, &show) are calls, and each_line("a.txt", 50) gives 50 to f, so it is CHECK-TYPE-MISMATCH, not CHECK-ARITY.

A call through an import alias leaves out defaults too (Util.join(xs)), and an alias call written without parentheses fills all its defaults: x = Util.connect is valid when every parameter of connect has a default. A function value takes every argument: &join has type Fn[List[String], String, String], and .call needs both arguments. Defaults are part of an exported signature. A default is resolved in the module that declares the function, so Models.Level.Info means the same for a caller that does not import that file.

A builtin can have defaults by the same rules, in its catalog row: Zlib.crc32(data, seed = 0) takes 1 or 2 arguments, in call, method and pipe form alike. A builtin default may also be an empty Bytes, shown as "".bytes (auth_data of OpenSSL.Cipher.aes_256_gcm_encrypt). The call site fills the arguments left out, so the VM always gets a full call; CHECK-ARITY names the range (expects 1 to 2 argument(s)). A builtin has no function value (&Zlib.crc32 is CHECK-UNKNOWN-NAME). A Lazy method row can have defaults too: lz.deflate(level = 6, raw = false). agentica help shows the default (seed: Int = 0).

Enums and pattern matching #

Enums are nominal sum types and may declare type parameters. Variants are qualified by their enum, and payloads are positional. A nullary variant is written Command.Show or Command.Show(), and a method reads on it (Command.Show.to_s). Constructor type parameters come from the payloads and the expected type; unresolved or conflicting ones are errors.

A type alias is transparent: type Grid = List[List[Float]] means the same type as List[List[Float]] in annotations, arguments, returns and builtin type arguments. An alias adds no runtime representation or conversion. It can name a builtin, struct, enum or function type, or another alias; a cycle is CHECK-TYPE-ALIAS-CYCLE. An alias is not a constructor or enum: construct or match using the underlying struct or enum name.

Generic aliases (type Matrix[T] = List[List[T]]) are in section 5.

case value ... end is a statement. An arm may put one simple statement on the arrow line (1 -> puts("one")), and more lines of the same arm may follow. A pattern is a primitive literal, _, ok(...) or error(...), or a qualified variant with one slot per payload position. A slot is a name (a binding), _, a literal (a negative number too), or another variant pattern, ok(...) or error(...), to any depth (the parser’s nesting limit applies, one level for each nested variant). Bindings are local to the arm, and a name may appear once in an arm (CHECK-SHADOWED-NAME otherwise, at the variant pattern that holds the second one). A nested literal has the type of its payload position (CHECK-PATTERN-TYPE), and a nested variant must belong to the enum of its position. A name alone is not a top-level pattern. Payloads are positional: there are no struct or list patterns.

An arm may carry a guard, pattern if condition -> .... The condition is a Bool expression (CHECK-TYPE-MISMATCH otherwise) that sees the bindings of its own arm. The arm runs when the pattern matches and the condition is true; otherwise the case goes on with the next arm. The parser looks for the guard of an arm up to the first -> of its line, so a guard stays on the line of its pattern.

An arm may list several patterns on its line, separated by commas: "ex", "px" -> ttl(value). The arm runs when one of them matches, tried left to right, and its guard applies to all of them. Such an arm binds no names (CHECK-CASE-ARM-BINDING, at the patterns): write _ in the slots, or one arm per pattern. Each pattern counts on its own for exhaustiveness and reachability, so a pattern that an earlier arm or an earlier pattern of the same arm already covers is CHECK-UNREACHABLE-CASE-ARM at that pattern.

Enum values need every variant, unless there is a catch-all _. Result[T] matches as Result.Ok(value) and Result.Err(message), or as ok and error; Result.Ok(_) discards the payload. Optional[T] matches as some(value) and none. The builtin Await[T] of a timed Task.await matches as Await.Done(value) and Await.TimedOut, with the same rules. Every other case, including one on Bool or Nil, needs _. A catch-all is the last arm when it has no guard, and duplicate or unreachable arms are rejected. The codes are CHECK-ENUM-TYPE-INFERENCE, CHECK-PATTERN-TYPE, CHECK-NON-EXHAUSTIVE-CASE and CHECK-UNREACHABLE-CASE-ARM.

A case gives a value in three places, and is a statement everywhere else:

  • the right side of an assignment, text = case r ... end, also with an annotation (x: T = case ...) or += and the like;
  • after return, return case s ... end;
  • the last line of a block, items.map do |item| case item ... end end.

Each arm of such a case ends with an expression, which is the value of the arm; lines may come before it (CHECK-CASE-ARM-VALUE when an arm ends with another statement, such as return, next, break or a nested case, or has no body). All arms have one type, which is the annotation of the assignment or the type the context expects when it has one, else the type of the first arm: CHECK-TYPE-MISMATCH, at the last expression of the arm that differs. So write x: Result[Int] = case ... when the first arm is error(...), [] or none. The case must be exhaustive by the rules above.

On the last line of a block the case stays a statement when the block’s result is Void (the block of each) or when an arm ends with another statement. When the block’s result is not known from its context (the block of Task.spawn), a case whose arms are Void or of one other type, with at least one Void, is a statement and the block gives no value; otherwise it gives the value. Arms of two different non-Void types are CHECK-TYPE-MISMATCH, even when another arm is Void.

Exhaustiveness and reachability are conservative, and no deeper analysis is done. An arm covers its variant only when it has no guard and every slot is a name or _. An arm with a guard, a literal slot or a nested variant covers nothing: it is a test that may fail. So a guarded _ if c -> does not make a case exhaustive, and a case that matches only Shape.Boxed(some(n)) (a variant with an Optional payload) needs a Shape.Boxed(_) arm (or _) after it, as ok(Reading.Value(n)) needs ok(_) and some(0) needs some(n) or _. An arm is unreachable (CHECK-UNREACHABLE-CASE-ARM) only when an earlier arm without a guard already covers its variant with names and _, or follows an unguarded catch-all. The same pattern may come again after a guarded or refutable arm, guarded or not.

The example declares a user generic enum, to show the rules; a value that may be missing is the builtin Optional[T] (see “Optional values”).

enum Option[T]
  Some(T)
  None
end

def display(option: Option[Int]) -> Void
  case option
    Option.Some(item) -> puts(item.to_s)
    Option.None -> puts("empty")
  end
end

def label(option: Option[Int]) -> String
  case option
    Option.Some(0) -> return "zero"
    Option.Some(n) if n < 0 -> return "negative"
    Option.Some(_) -> return "positive"
    Option.None -> return "empty"
  end
end

Structs and lists #

A struct constructor gives each field at most once, by name, in any order. A field written NAME: type = expression has a default value, which a constructor may leave out; the field then gets the default. A field without a default must be given (CHECK-MISSING-FIELD, located at the constructor), and a name that is not a field is CHECK-UNKNOWN-FIELD. A field that is given twice is CHECK-DUPLICATE-FIELD.

A field default follows the rules of a parameter default (see “Default parameter values”): it is a constant of the same forms, or the name of a constant with such a value, except a struct built with no arguments (CHECK-DEFAULT-VALUE: its own defaults could build the struct again at each construction, without end), anything else is CHECK-DEFAULT-VALUE at the expression, and its type is checked against the field type ([] and {} take the field type, a mismatch is CHECK-TYPE-MISMATCH). There is no order rule: a constructor names its fields, so any field may have a default. A default is checked where the struct is declared, even when no constructor leaves the field out. It is built at each construction that leaves the field out, so no two values share one, and it is resolved in the module that declares the struct, so a constructor in another module can leave the field out without importing what the default names. value.with(...) is not affected. A builtin record takes the defaults that the catalog gives its fields: every field of HTTP.ClientOptions and HTTP.ServerOptions has one, the other records have none.

value.with(name: expr, ...) is a copy of a struct with some fields changed; the original is unchanged. The receiver must be a struct (any other type is CHECK-UNKNOWN-METHOD, with help that with copies structs), each name must be a field of it (CHECK-UNKNOWN-FIELD), given at most once (CHECK-DUPLICATE-FIELD), with a value of the field’s type (CHECK-TYPE-MISMATCH; [] and {} take the field type). A bare value.with(...) whose result is dropped is CHECK-UNUSED-VALUE. The receiver is evaluated first, then the values from left to right, and all values see the receiver as it was before the update: p.with(a: p.b, b: p.a) swaps the two fields. The result has the receiver’s type, so updates chain and nest: a.with(address: a.address.with(city: "Lima")). Changing some fields of an existing value is what with is for; a constructor with every field is how to build a new one. An update builds a value, so it follows the rules of construction: a value of a struct that another module keeps private cannot be updated by an importer (CHECK-IMPORT-NAME, as for constructing it), and the importer needs the struct’s own module among its imports, by an alias or by names (a module imported by names counts with all its exported structs, not only the ones it names). A field named with is allowed when its type is not a function type: a field of type Fn[...] named with (or of a type parameter, see “Generic structs”) is CHECK-REDEFINED-NAME, because value.with(...) is always the update; value.with without parentheses reads a data field of that name.

Type.members lists the fields of a struct type, in declaration order, as a List[StructMember]. StructMember is a builtin record, reserved like TaskDown, with two String fields: name, the field name, and type, its type written as source (Int, List[String], Map[String, Int], Result[Int], Address, Shape[String]). The text is the checker’s printed form: an alias is expanded (type Id = Int gives Int) and a struct or enum from another module is written by its own name, without the import alias, so A.Point and B.Point both give Point. Type is a struct you declare, one you import by name or through an alias (Models.User.members), or a builtin record such as File.Info. It is written without parentheses and not piped: User.members() and x |> User.members() are CHECK-UNKNOWN-NAME, and Models.User.members() is CHECK-TYPE-MISMATCH. There is no form on a value: user.members is the field of that name, so a struct may have a field called members. The list needs no runtime support beyond the instructions that build it, but each evaluation builds it again, so hoist Type.members out of a hot loop. Any other type name is an error: an enum or a resource is CHECK-UNKNOWN-METHOD, an alias is CHECK-UNKNOWN-TYPE (name the struct itself), and a name that is no declared type, or a builtin type such as Int, is CHECK-UNKNOWN-NAME.

Private fields #

The fields after the private line of a struct body are private to the module that declares the struct: its file, or the module block it is declared in (code of the file outside the block is outside). The module blocks of a file see the private names of the file, so they are inside for a struct declared at the top of the file. A re-export (export Alias.Type) does not change that module. Outside it, naming a private field is CHECK-PRIVATE-FIELD at the field name: reading it (conn.socket), calling an Fn field, giving it in a constructor or setting it with with. A struct with a private field is built only in its module, even when every private field has a default: a constructor elsewhere that leaves them out is CHECK-PRIVATE-FIELD at the struct name. Type.members, Type.codec, JSON.encode, JSON.from, JSON.decode and JSON.schema of a type that holds such a struct (in a field, an item or an enum payload) are CHECK-PRIVATE-FIELD outside its module, and so is a call that hands one to a generic function that encodes it; in its module they cover every field. Outside the module the value can still be passed, stored, sent over a Channel, compared and updated in its public fields with with. == compares every field, and inspect, to_s and interpolation show every field. agentica doc, outline and help list the public fields, then a line that says the struct has private fields.

A list index runs from zero to length minus one; a negative or out-of-range index is RUNTIME-INDEX-OUT-OF-RANGE. for iterates a List in order, a Set in first-insertion order, a Range, or a Bytes byte by byte. The core has no slices and no string indexing.

Generic structs #

A struct declares type parameters after its name, as an enum does: struct Box[T] ... end, struct Pair[A, B] ... end. The parameter names follow the enum rules: type names that are not repeated and not reserved (CHECK-REDEFINED-NAME). A field may use a parameter anywhere a type goes (value: T, items: List[T], get: Fn[String, Result[T]], next: Option[Box[T]]), and a struct may mention itself (kids: List[Tree[T]]). A parameter may be a Map key or a Set element nowhere in the declaration (CHECK-MAP-KEY-TYPE, CHECK-SET-ELEMENT-TYPE, as for enums). A field named with whose type is a parameter is CHECK-REDEFINED-NAME at the field, since the parameter could be an Fn and value.with(...) is always the update.

struct Storage[T]
  get: Fn[String, Result[T]]
  put: Fn[String, T, Result[Void]]
end

struct Box[T]
  value: T
  items: List[T] = []
end

b = Box(value: 41)                     # Box[Int]
e: Box[List[String]] = Box(value: [])  # T from the annotation

A type is written with one argument for each parameter: Box[Int], Pair[String, List[Int]]. A bare Box and a wrong number of arguments are CHECK-UNKNOWN-TYPE at the type, and an argument is checked as an enum argument is (Void is CHECK-VOID-TYPE). An imported struct is written M.Box[Int], or Box[Int] after import {Box} from "m"; a parameter name in its fields keeps its own meaning in the importing file.

A construction takes the arguments from the values, from left to right as they are written, and from the expected type (an annotation, a parameter, a field or a return type): Box(value: 41) is Box[Int]. A value of the wrong type for an argument already known is CHECK-TYPE-MISMATCH at the value (Pair(a: 1, b: "x") for struct Pair[T] with two T fields). An empty list or map cannot say what an argument is, so it needs the expected type: without one it is CHECK-ENUM-TYPE-INFERENCE at the value, and so is a parameter that no given value fixes (a parameter no field uses, or a field left out by its default), at the construction. The code keeps its enum name.

Every rule applies after substitution. b.value is Int for a Box[Int]; b.with(value: 7) has the type of b and checks the new value against Int. A generic instance has to_s, inspect and Test.eq when its arguments are data types, so Box[Int] prints and Box[Fn[Int, Int]] does not (CHECK-TYPE-MISMATCH). Type.members is on the bare name (Box.members) and writes the field types as declared, so value: T gives T.

JSON.encode and JSON.from accept a generic instance whose fields are encodable after substitution (Box[List[Int]]), and give CHECK-NOT-ENCODABLE when one is not (Box[Fn[Int, Int]]). JSON.decode, JSON.schema and .codec take a generic struct instance whose fields are decodable after substitution, as the target (Box[Int], Lib.Box[Int] or an alias) or in a field; the schema describes each instance under its name with the arguments (Box[Int]). An instance whose arguments nest more than 32 levels (a struct whose field passes itself a bigger argument, next: Optional[W[List[T]]]) and a generic enum instance are CHECK-NOT-DECODABLE; a bare generic struct as the target is CHECK-UNKNOWN-TYPE. A type argument counts after substitution for JSON.Field too (rules in 06b-builtins.md, “Optional and nullable fields”). A C struct of an extern block takes no type parameters (PARSE-UNEXPECTED-TOKEN at the [).

Generic functions #

A function declares type parameters after its name: def first_or[T](xs: List[T], fallback: T) -> T. The names follow the enum rules, with one more: a name that a struct, enum or alias of the file already has (declared there or imported by name) would hide that type, so it is CHECK-REDEFINED-NAME at the parameter, as are a repeated name and a reserved one (Int, List). def f[] is PARSE-UNEXPECTED-TOKEN. main with type parameters is CHECK-MAIN. A type parameter that no parameter type and no result type mentions cannot be inferred: CHECK-ENUM-TYPE-INFERENCE at its name. A parameter whose type mentions a type parameter takes a default as any other: none, [] and {} fit Optional[T], List[T] and Map[String, T], and x: T = 1 is CHECK-TYPE-MISMATCH at the default. A call that leaves out every argument that shows a type parameter cannot infer it (CHECK-ENUM-TYPE-INFERENCE at the call).

def first_or[T](xs: List[T], fallback: T) -> T
  return fallback if xs.length == 0

  return xs[0]
end

def max_by[T](xs: List[T], key: Fn[T, Int]) -> Optional[T]
  # ...
end

puts(first_or(["ana", "ben"], "none"))  # T is String
puts(first_or([], 0))                   # T is Int, from 0; [] is checked last

Inference. A call gives no type arguments. The checker finds them in four steps; a call has its own type variables, so the T of the callee and the T of the caller do not mix:

  1. The arguments that have a type of their own, from left to right. Each one binds the type parameters of its parameter type; a value of another type than one already bound is CHECK-TYPE-MISMATCH (first_or([1], "x")).
  2. The expected type of the call (an annotation, a parameter, a field or a return type) is matched with the result type, for the parameters still open. The arguments win over it. A parameter that only the result mentions, as in def empty_of[T]() -> List[T], comes from here.
  3. The arguments that need an expected type are checked against their parameter type as far as it is known, and bind nothing: [], {}, Set.new([]), error(...), a variant of a generic enum without a payload, a list or map literal that holds one of them, and &f of a generic function. As the argument of a builtin method, &f gets its type only where the method fixes the whole Fn type: the callback of filter, any?, all? and each, and the predicate of find, partition and take_while. Elsewhere, as in map, bind it first: f: Fn[Int, Bool] = &name.
  4. The lambdas among the other arguments, from left to right, then the block, the last argument. Their parameter types come from the Fn parameter; one that is still open comes from an annotation (do |x: Int|, ->(x: Int)) or from its uses in the body (see Blocks), which binds it, else CHECK-BLOCK-TYPE. The result binds the open parameters of the Fn result (R in Result[R]); a result that does not fit is CHECK-TYPE-MISMATCH. A step 3 argument whose parameter type is still open waits for the block. A step 3 argument binds nothing: with def apply[A, B](x: A, f: Fn[A, B]), the call apply(3, &id) leaves B open.

A type parameter still open after step 4 is CHECK-ENUM-TYPE-INFERENCE at the call. The call has the result type with the arguments put in. Recursion, mutual recursion and a generic function that calls another work; a recursive call may use other type arguments, because the checker builds no copy per type. A type argument may be Void where Void is valid after substitution (a result, the last type of an Fn, the completion of a Result or a Task: ok() binds R to Void in Result[R]); a parameter or a list item that becomes Void is CHECK-VOID-TYPE at the call. try f(x), with f returning Result[T], gives T. A call is no constant expression (CHECK-CONSTANT-EXPRESSION).

Inside the body. A type parameter stands only for itself, and the body is checked once, whatever the types of the calls. A T value can be stored, returned, put in a List, a Result, a Map value, a struct or an enum payload, captured by a block, and passed to anything that takes that type. A T annotation is valid in the body (x: T, do |y: T|). These are errors, as they are for an Fn:

  • ==, !=, arithmetic and ordering: CHECK-TYPE-MISMATCH.
  • puts, interpolation and the other printing forms: CHECK-TYPE-MISMATCH; x.to_s and x.inspect are CHECK-UNKNOWN-METHOD, like any method of T.
  • a field or a method (x.name, x.with(...)): CHECK-UNKNOWN-METHOD; x.call(...): CHECK-TYPE-MISMATCH.
  • a literal or variant arm in case x: CHECK-PATTERN-TYPE.
  • JSON.decode(text, T): CHECK-NOT-DECODABLE, since decoding needs the type at run time. Take a Codec[T] parameter instead (docs/grammar/06b-builtins.md, JSON).
  • T as a Map key or a Set element: CHECK-MAP-KEY-TYPE and CHECK-SET-ELEMENT-TYPE, wherever it is written; a call with Int does not help.

JSON.encode(x) and JSON.from(x) are allowed when the type of x holds type parameters (T, List[T], Map[String, T], Box[T], Optional[T]) and some types for them would make it encodable; otherwise (Task[T], an Fn) they are CHECK-NOT-ENCODABLE in the body. The check of the types moves to each call: when a call (or a reference &f) binds the type parameters, the bound types must be encodable, else CHECK-NOT-ENCODABLE at the argument that binds them (at the call, or the reference, when no argument does). A generic function that passes its own T to such a function takes on the same requirement, wherever the two are declared.

Behaviour comes from Fn parameters, as in max_by: there are no traits or constraints on a type parameter. The data-type and effect rules are judged on the substituted types at each call: with fns: List[Fn[Int, Int]], puts(first_or(fns, &id)) is CHECK-TYPE-MISMATCH, because T is that Fn.

References. &first_or is a value only where the expected Fn type fixes each type parameter: f: Fn[List[Int], Int, Int] = &first_or is valid, and f = &first_or is CHECK-ENUM-TYPE-INFERENCE at the reference. A type parameter of the enclosing function counts as fixed.

Modules. An exported generic function is called as any function (M.first_or(xs, 0), or first_or(xs, 0) after import {first_or} from "m"). Linking keeps the type parameters local, in the signature and the body: a bare T does not get the module prefix. Type parameters exist only in the checker: the VM sees one body for any type argument, and structs by field names and order. Not in the language: constraints on type parameters, type arguments written at a call, generic extern functions and generic Map keys.

Ranges #

a..b includes b; a...b excludes it, as in Ruby. A Range is a small immutable value (start, end and kind); it never holds a list. Its functions are in the Range page.

  • for x in range yields each Int in order. An end before the start is empty, and there is no reverse iteration. Iterating up to the largest Int does not overflow. The range is evaluated once.
  • Int.times, upto and downto return Void. A negative literal receiver needs parentheses: (-5).times do ... end; -5.times do ... end is -(5.times ...), a CHECK-VOID-VALUE.
  • Ranges are not JSON-encodable and cannot be Map keys. Ranges of String or Float, and step, are not supported.

Bytes #

Bytes is an immutable string of bytes, one byte for each item, read as an Int in 0..255. It holds data that is not text. There is no literal: write "PK".bytes, OpenSSL.Digest.hexdecode(text) or Bytes.from_list([80, 75]). The methods, the encodings, the costs and the errors are in the Bytes page. The language fixes:

  • for byte in b visits the bytes in order.
  • == and != compare length and bytes. They are not constant time: compare a MAC or a token with OpenSSL.HMAC.secure_compare. A Bytes never equals a String with the same bytes (CHECK-TYPE-MISMATCH). There is no ordering (<).
  • A Bytes is a Map key, an ATS key or a Set item, and a field, a list item or a map value. It is not JSON-encodable or decodable (CHECK-NOT-ENCODABLE, CHECK-NOT-DECODABLE).
  • Bytes is a reserved type name (CHECK-REDEFINED-NAME). String has no index (CHECK-NOT-INDEXABLE); s.bytes[i] reads a byte.

Maps #

Map[K, V] has exactly two type arguments: K is Int, String or Bytes, and V is any type.

stock: Map[String, Int] = {"apple": 3, "pear": 0}
apples = stock["apple"]
more = Map.put(stock, "kiwi", 7)
  • A literal uses braces and key: value pairs. An empty {} needs an expected type, like []: CHECK-EMPTY-MAP-TYPE (CHECK-EMPTY-LIST-TYPE is for []).
  • m[key] returns the value; the key must have type K. A missing key is a runtime error (RUNTIME-KEY-NOT-FOUND).
  • A repeated key in a literal keeps the last value at the first position. Map.put on an existing key keeps its position.
  • Maps are immutable: there is no m[key] = value, and Map.put returns a new map. There is no for over a map; iterate Map.keys, which is in insertion order.

Sets #

Set[T] has one type argument, Int, String or Bytes, like a Map key: any other element type is CHECK-SET-ELEMENT-TYPE. A set holds each value once and keeps the order of first insertion. Its functions are in the Set page.

seen: Set[String] = Set.new([])
seen = seen.add("a").add("b").add("a")
puts(seen)
  • Set.new([]) needs an expected type, like [] and {}: CHECK-EMPTY-SET-TYPE.
  • Sets are immutable: Set.add and Set.delete return a new set.
  • for x in set visits the elements in order. The set is read once before the loop, so assigning the variable in the body does not change the loop.
  • == and Test.eq compare two sets in any order; there is no index (CHECK-NOT-INDEXABLE). A set is not JSON-encodable (CHECK-NOT-ENCODABLE) and cannot be a Map key, but it may be a field, a list item or a map value.

Result and propagation #

  • ok(value), ok() and error(message) build Results. Result.Ok(x), Result.Ok() and Result.Err(m) are the same calls.
  • A failed Result holds an Error. error(message) with a String builds one: kind "error", no code, no details, no cause, and the location of the call. error(e) with an Error holds e unchanged. Any other argument is CHECK-TYPE-MISMATCH. The pattern error(e) binds an Error, so a literal in its slot (error("timeout")) is CHECK-PATTERN-TYPE; test e.message in a guard.
  • error(message, kind:, code:, details:, cause:): after a String message come named arguments, in any order, each optional: kind: String, code: Int, details: Map[String, String] and cause: Error. code and cause are stored as some(...), and the same holds for Result.Err(...). A positional argument after a named one is PARSE-UNEXPECTED-TOKEN. An unknown name (location too) is CHECK-UNKNOWN-FIELD; message or a repeated name is CHECK-DUPLICATE-FIELD; a named argument after an Error is CHECK-ARITY; code: some(19) is CHECK-TYPE-MISMATCH.
  • A kind is a dotted name: parts of a-z, 0-9 and _, each starting with a letter, joined by single dots (db, db.constraint, io.not_found). A text literal given as kind: (of error(...) or Result.Err(...)) or to is_a? / kind_of? that is not one is CHECK-ERROR-KIND. Nothing else is checked: not a computed kind, and not e.with(kind: ...). e.is_a?(family) is true when the kind is family or starts with family and a dot (db takes db.constraint, not dbx); kind_of? is the same method, and is? is CHECK-UNKNOWN-METHOD with a help that shows is_a?.
  • Error(...) is CHECK-ERROR-CONSTRUCTOR: only error(...) builds an Error, and e.with(...) changes one.
  • location is path:line:col of the error(...) call, or for an error that a builtin makes, of the builtin call that the innermost frame outside the prelude makes. The path is the source name the compiled file stores. It is "" when no such frame is found within 16 prelude or native frames. error(e), try and e.with(...) keep it.
  • == on two Errors compares every field but location. to_s and interpolation give the message; inspect gives the error(...) call (06b-builtins.md).
  • Result[T] is builtin, not a user enum. It can nest and hold any payload. It has no fields or indexing; == compares it when T has equality.
  • ok(1) infers Result[Int]. An expected Result[T] checks the payload against T, including empty lists and maps. error("bad") needs an expected Result type from an annotation, a binding, a parameter, a field, a return or a typed container element; otherwise it is CHECK-RESULT-TYPE. A block whose result type is not known (map, Native.memory_pointer, Task.map) takes it from its other ok(...) returns, so return error("bad") before the last ok(x) checks; a block with only error(...) still needs the annotation. Container inference uses the first element, so [ok(1), error("bad")] infers and the reverse order needs an annotation.
  • The functions are in the Result page. Result.unwrap! on an error halts with RUNTIME-UNWRAP-ERROR at the call. Result.ok? and Result.message (the message field) need a known Result type. ok(false) and ok(nil) are successes. An error value never prints a diagnostic or changes the exit code. Non-bang String conversions return an error for bad text or overflow; other runtime failures are never turned into Results.
  • try has unary precedence. It evaluates one Result[T] operand once: on success it gives T; on error it returns the error from the current function. Only a function that returns Result[...] may use it (CHECK-TRY-CONTEXT otherwise). An expected type T gives the operand Result[T]; the return type alone does not. A success still needs an explicit return ok(...).
  • A Result[T] that is dropped, as an expression statement or as the last statement of a Void block, is CHECK-UNUSED-RESULT at the expression. It does not matter who made it (a user function, a builtin with or without effects, Task.await, .call) or what T is (Result[Void] too). It is checked before CHECK-UNUSED-VALUE, so a pure builtin that gives a Result, such as s.to_i, is this error. Handle the Result with try, a case, .unwrap!, or drop it on purpose with _ = f(). IO.inspect(r) gives back what it printed, so it is exempt. A dropped Task[Result[T]] (Task.spawn(&save)) is not a Result and stays valid.
def read_age(text: String) -> Result[Int]
  age = try text.to_i
  return ok(age)
end

Optional values #

  • some(value) and none build Optionals. Optional[T] is builtin, not a user enum. It is allowed wherever a type is (variables, parameters, returns, fields, list and map items, type arguments) and can nest; Optional[Void] is CHECK-VOID-TYPE.
  • some(1) infers Optional[Int]. none needs an expected Optional type, as error(...) needs a Result type (CHECK-OPTIONAL-TYPE otherwise), and a block of unknown result type takes it from its some(...) values.
  • The functions are in the Optional page. o.unwrap! on none halts with RUNTIME-UNWRAP-NONE at the receiver.
  • An Optional prints as some(1) or none. none may be the default of a parameter or field (port: Optional[Int] = none).
  • In JSON, none is null and some(x) is x; decode reads null or a missing key as none (06b-builtins.md, “Optional values in JSON”).

Function values #

f: Fn[Int, Int] = &double refers to a declared function with exactly those types, and f.call(21) invokes it. Function values can travel through lists, maps, parameters, returns and fields. A bare function name is not a value. Functions have no equality, fields, indexing or JSON encoding; IO.inspect prints <Fn>.

A builtin is a function value too: &Time.now_ms is Fn[Int], and a method written on its type, &Int.to_s, takes the receiver first (Fn[Int, String]). It takes every parameter, those with a default included (&Zlib.crc32 is Fn[Bytes, Int, Result[Int]]). Only a builtin with one form, no rule of its own and no type parameter can be one, written as Ruby writes it (&List.join, not &String.join); any other (&File.open, &List.map, &puts, a function of a family member such as &OpenSSL.Digest.sha256) is CHECK-UNKNOWN-NAME with a help: pass a block that calls it.

A field of type Fn is called through the struct, without .call: store.put(a, b) is store.put.call(a, b). The arguments are checked against the parameters of the field’s type (CHECK-ARITY, CHECK-TYPE-MISMATCH), the value is the result of the function, and store.put without parentheses still reads the function. Structs have no methods, so the name of an Fn field cannot clash with one, except to_s and inspect: an Fn field of that name wins, as the field does when it is read. A field named with cannot hold a function, so x.with(...) is always the struct update. Calling a field of any other type, or a name that is no field, is CHECK-UNKNOWN-METHOD.

Blocks and closures #

A block is a function written at the call site, as the last argument of a call:

doubled = xs.map do |x|
  x * 2
end
total = xs.reduce(0) do |sum, x| sum + x end
  • Where. do |a, b| ... end comes right after the ) of a call, or after a method or function name without arguments, which drops the empty () (xs.each do, start do, Util.start do). { |a, b| ... } comes only after such a name (xs.map { |x| x * 2 }). The called function’s last parameter must be a Fn; otherwise CHECK-BLOCK-TARGET, for user functions and builtins alike. do || ... end and { || ... } are rejected.
  • Headers. case, while and for headers may end with an optional do, which is never a block; a block in such a header needs parentheses.
  • Parameter types come from the expected Fn or the builtin’s rule (xs.map gives x the element type), or from annotations such as do |x: Int|. With neither, the uses of the parameter in the body give its type when they leave exactly one. A use names a set of types: an argument of a typed parameter (a function, a builtin with one form, a variant payload, a struct field, y: T = x) its type; x.name every receiver kind or struct that has name, builtin records included (none when a generic one does, when nothing has it, or for to_s and inspect); an operator with a literal the literal’s type (x * 2 Int or String, % and ranges Int); and, or and ! Bool. Other uses name none. With no set, several types left (x * 2) or none (x + 1 and x.upcase), CHECK-BLOCK-TYPE at the parameter, with the annotation in its help. The body is then checked as if annotated. A wrong number of parameters is CHECK-ARITY.
  • Result. return leaves the block, not the function. Without return, the last expression statement is the value. For map and sort_by the result type comes from the body, where every return and the last expression must agree (CHECK-TYPE-MISMATCH). A non-Void block must return on every path (CHECK-MISSING-RETURN).
  • try in a block returns the error from the block, so the block’s result must be a Result (CHECK-TRY-CONTEXT otherwise). The result type must come from the call, so try is not available in map and sort_by blocks. The block of Task.map gives a Result[R] with R not known from the call, and try works in it, since the outer type is always Result. In a block of a Lazy method (a step, Lazy.produce or a terminal) try works whatever the block’s result type: a failed try ends the pipeline, and the terminal returns its error (docs/grammar/06b-builtins.md, Lazy[T]). A block nested in that block follows the rule above.
  • Capture by value. A block sees the variables visible where it is written, with their values at creation; later outer assignments do not change it. Assigning to an outer variable inside a block is CHECK-CAPTURED-ASSIGNMENT; use reduce or a for loop. Block parameters and new variables cannot reuse a visible name (CHECK-SHADOWED-NAME).
  • Values. A block has type Fn[A, ..., R] and works wherever a function value does, including as a BDD step. It shares the caller’s step budget and call-depth limit. Blocks have no equality or JSON form.

Lambdas #

A lambda, ->(x) { ... }, is a block written as a value: a function value that can go wherever a value does, the place of a call’s block included.

c = 3
add_c: Fn[Int, Int, Int] = ->(a, b) { a + b + c }
answer = -> { 42 }
half: Fn[String, Result[Int]] = ->(s) {
  n = try s.to_i
  ok(n / 2)
}
  • The rules of a block hold: parameter types from the expected Fn (an annotated variable, a parameter, a field, a list or map item, a return type) or from annotations (->(x: Int) { ... }) or from their uses in the body (->(x) { x + 1 } takes an Int), else CHECK-BLOCK-TYPE; the result from the expected Fn or else from the body; try only with a known Result result (CHECK-TRY-CONTEXT); capture by value; return leaves the lambda. A lambda where a type other than Fn is expected is CHECK-TYPE-MISMATCH.
  • A lambda has no name, so it cannot call itself: the variable it is assigned to does not exist inside it (CHECK-UNKNOWN-NAME); recursion uses def.
  • In the place of a block. A lambda written as the last argument of a call whose last parameter is an Fn is that call’s block: xs.map(->(x) { x * 2 }) means xs.map do |x| x * 2 end, with the parameter types from the expected Fn, and a lambda literal picks the block form of a builtin that has one (File.open). A lambda kept in a variable is passed as a value: xs.map(double) checks when its type fits the Fn parameter. A do ... end block still follows the call and never goes inside its parentheses. A parameter of a generic type takes no block, so some(->(x: Int) { x }) and fs.push(->(x: Int) { x }) pass the lambda as a value.
  • In a generic call, a lambda that is not the last argument is checked after the arguments that have a type of their own, from left to right, as the block is (step 4 of “Generic functions”).
  • A lambda dropped as a statement is CHECK-UNUSED-VALUE.