Syntax
This is a descriptive grammar. { X } means zero or more repetitions, [ X ]
means optional, and | expresses alternatives. Terminals appear in quotes;
uppercase names are lexical tokens.
File and declarations #
program = [ NL ], [ module_doc ], { declaration },
[ private_line, { declaration } ], EOF ;
private_line = "private", NL ;
module_doc = DOC, NL, NL ;
declaration = import_decl | reexport_decl | extern_decl
| [ DOC, NL ], ( constant_decl | function_decl | struct_decl | enum_decl
| alias_decl ) ;
constant_decl = CONST_NAME, [ ":", type ], "=", expression, NL ;
import_decl = "import", ( TYPE_NAME | name_list ), "from", STRING, NL ;
name_list = "{", import_name, { ",", import_name }, [ "," ], "}" ;
import_name = ( NAME | TYPE_NAME ), [ "as", ( NAME | TYPE_NAME ) ] ;
reexport_decl = "export", TYPE_NAME, ".", ( NAME | TYPE_NAME ), NL ;
function_decl = "def", NAME, [ type_parameters ], "(", [ parameters ], ")",
"->", type, ( NL, block, "end" | "=", expression ), NL ;
parameters = parameter, { ",", parameter }, [ "," ] ;
parameter = NAME, ":", type, [ "=", expression ] ;
extern_decl = "extern", STRING, NL, { extern_member }, "end", NL
| "extern", "module", STRING, NL, { module_member }, "end",
NL ;
extern_member = [ DOC, NL ],
( extern_function | resource_decl | callback_decl
| c_struct_decl ) ;
extern_function = [ "compute" ], "def", NAME, "(", [ c_parameters ], ")",
"->", ( c_type | TYPE_NAME | "Void" ), [ "=", STRING ], NL ;
c_parameters = c_parameter, { ",", c_parameter },
[ ",", "...", { ",", c_parameter } ], [ "," ] ;
resource_decl = "resource", TYPE_NAME, ",", "free", ":",
( NAME | TYPE_NAME | "C", ".", "Function" ), NL ;
callback_decl = "callback", TYPE_NAME, "(", [ c_parameters ], ")",
"->", ( c_type | "Void" ), NL ;
c_parameter = [ "out" ], NAME, ":",
( c_type | "C", ".", ( "Bytes" | "Function" ) | TYPE_NAME ) ;
c_type = "C", ".", ( "Int32" | "Int64" | "Double" | "Float" | "Bool"
| "String" | "Pointer" ) ;
c_struct_decl = "struct", TYPE_NAME, NL, c_field, { c_field }, "end", NL ;
c_field = [ DOC, NL ], NAME, ":", ( c_field_type | TYPE_NAME ),
[ "=", expression ], NL ;
c_field_type = "C", ".", ( "Int32" | "Int64" | "Double" | "Float" | "Bool"
| "Pointer" ) ;
module_member = [ DOC, NL ], [ "compute" ], "def", NAME,
"(", [ parameters ], ")", "->", type, NL ;
struct_decl = "struct", TYPE_NAME, [ type_parameters ], NL,
{ field_decl }, [ "private", NL, { field_decl } ], "end",
NL ;
field_decl = [ DOC, NL ], NAME, ":", type, [ "=", expression ], NL ;
enum_decl = "enum", TYPE_NAME, [ type_parameters ], NL,
variant_decl, { variant_decl }, "end", NL ;
alias_decl = "type", TYPE_NAME, [ type_parameters ], "=", type, NL ;
type_parameters = "[", TYPE_NAME, { ",", TYPE_NAME }, "]" ;
variant_decl = [ DOC, NL ], TYPE_NAME, [ "(", type, { ",", type }, ")" ], NL ;
qualified_type = TYPE_NAME, [ ".", TYPE_NAME ] ;
type = qualified_type, [ "[", type, { ",", type }, "]" ] ;A one-line def, def name(params) -> Type = expression, is the def with
expression as its body, and the form agentica fmt writes for such a def when
it fits on its line and holds no comment: it checks and runs the same way,
generics, defaults and a ## doc included. The expression starts on
the line of = (PARSE-UNEXPECTED-TOKEN at the end of the line otherwise)
and goes on to other lines only as any expression does: inside parentheses or a
block, or on a next line that starts with .name. A case or an if after =
is PARSE-UNEXPECTED-TOKEN: they are statements. A Void function returns no
value, so -> Void = is PARSE-UNEXPECTED-TOKEN at the =, with a help to
write the def with a body; this includes main. The return type is required
(def f(x: Int) = x is PARSE-UNEXPECTED-TOKEN at the =). Like constants,
one-line defs may follow each other with no blank line (below). In an extern
block, = "name" after the signature is the C name of the function instead
(below), not a value.
A parameter may end with a default value, NAME: type = expression. The parser
takes any expression after =, so that the checker can say why a default is not
allowed; the rules are in section 6, “Default parameter values”. A block
parameter (do |x|) takes no default. A field of a struct may end with a
default the same way (retries: Int = 3), with the same rules; section 6,
“Structs and lists”, says what a constructor does with it.
A struct body may have one private line: the word alone on its line, with a
blank line before it unless it is the first line of the body and a blank line
after it unless it is the last. The fields after it are private (section 6,
“Private fields”). A missing blank line is PARSE-MISSING-BLANK-LINE and a
second private is PARSE-SECOND-PRIVATE. private is a plain name, so a
field may be called private (private: Int). A C struct of an extern block
has no private line.
An extern block declares functions of a native library (section 6d, “Native
code”). The library is a plain string: a name without / or an absolute path
(PARSE-EXTERN-LIBRARY at the string). Each line is the signature of one C
function: no body, no default (PARSE-EXTERN-DEFAULT at the parameter), C types
only (PARSE-EXTERN-TYPE at the type), at most 64 parameters
(PARSE-EXTERN-ARITY at the 65th) and a def name without ? or !, even
with a C name (PARSE-EXTERN-NAME at the name). Anything else in the block, a
body or a library given as a heredoc is PARSE-UNEXPECTED-TOKEN. A ## doc
goes on a def inside the block. Each function is a def for the rest of the
language: it is public or private as the block is (above or after private,
section 5b; export before a member is PARSE-UNEXPECTED-TOKEN, and a block
with both kinds of function is written as two blocks), it takes the place of a
def in the declaration order (except in a block that declares a resource,
below), the whole block needs the blank line of a declaration, and the checker
sees each C type as the Agentica type that section 6d gives it. compute def
declares a function that runs off the scheduler while the task waits (section
6d). extern is contextual: it is a keyword only at the start of a top-level
declaration, and compute only before def in an extern block. C.UInt64 and
C.ULong are PARSE-EXTERN-TYPE (section 6d).
resource Name, free: c_name in an extern block declares a resource: a type for
the C pointers that the block’s functions return, freed by the C function
c_name of the same library (section 6d). c_name is any C identifier, also
one that starts with a capital letter (PQfinish, SSL_free): only the dotted
C.Function after the colon is a type, so a bare name is always a C name,
whatever types the program declares. resource Name, free_ref: c_name names a
C function that takes a reference to the pointer instead (void c_name(T **),
as duckdb_close; ref as in Ruby’s Fiddle::Pointer#ref), checked as a
free: name. A resource has one free word: a second one is PARSE-EXTERN-FREE
at it, and free_ref: C.Function is PARSE-EXTERN-FUNCTION. It is a type for
the rest of the language: it is public above private, and it takes the place
of a type in the declaration order. So does every def of a block that
declares a resource or a struct, public or not: such a block is one
declaration among the types, and its functions do not count as functions for the
order (a block with neither keeps the rule of the def). A def of the block
may use it in its signature after the line that declares it (PARSE-EXTERN-TYPE
before): a parameter takes the resource, and a result of the resource is
Result[Name] for the checker. A def of the block whose C name is the free
function is PARSE-EXTERN-FREE at that name; the check is per block, so another
block of the same library may still declare it. C.Pointer is the type of a C
pointer anywhere in a program; C.Bytes is a parameter only, a Bytes for the
checker. resource is a keyword only at the start of a member of an extern
block.
out NAME: type in an extern function is an out parameter: C gets a pointer to
a slot and writes the value there (section 6d). The caller does not pass it.
A function with out parameters returns its record, a struct that the parser
declares next to it, named after the function in CamelCase (sqlite3_open gives
Sqlite3Open): a field result with the C result (none for Void), then one
field per out parameter, in order, named after it. The record is public with
its function and has no place in the declaration order. An out parameter is
an integer type, C.Double, C.Float, C.Bool, C.Pointer or a resource of
the block, whose field is the resource itself, not a Result;
anything else is PARSE-EXTERN-OUT at the type. An out parameter named
result of a function with a C result, an in and an out parameter of one name
(at the later), and a function name with no letter for the record’s name, are
PARSE-EXTERN-OUT at that name; out before a parameter outside an extern
block is PARSE-EXTERN-OUT at the word. A type of the record’s name elsewhere
in the file, and two out parameters of one name, are CHECK-REDEFINED-NAME.
out is a keyword only before a parameter name.
The C name of an extern function is its def name, or the string after the
result (-> C.Int32 = "fcntl"), so one C function can be declared in several
shapes (PARSE-EXTERN-SYMBOL at a string that is not a plain name). ... among
the parameters declares a variadic C function: the parameters after it are its
variadic arguments, each with the C type the call passes. The rules and the
codes of a bad one (PARSE-EXTERN-VARIADIC*) are in the
Types and resources page.
A C.Function parameter is the address of a C function, a C.Pointer for the
checker. As the first parameter it makes the def a call through a function
pointer: the call runs the function at that address with the other parameters,
and the def has no C name (= "..." is PARSE-EXTERN-FUNCTION at the
string). resource Name, free: C.Function declares a resource whose values each
have their own free function: a def that makes one (its result or an out
parameter) takes the address of that function as its last parameter, a
C.Function, after any out parameters. The free rule wins: a sole C.Function
parameter of a def that returns such a resource is its free function, so def thing_new(free: C.Function) -> Thing calls thing_new by name; a call through
a pointer that makes one takes two C.Function parameters. The parameter names
are free (fn and free are a convention). Neither address goes to C. A
C.Function anywhere else, a def that makes such a resource without that
parameter, and a def that makes two are PARSE-EXTERN-FUNCTION at the type,
and so is a free: type other than C.Function. A C.Function result is
PARSE-EXTERN-TYPE, an out one PARSE-EXTERN-OUT and a variadic one
PARSE-EXTERN-VARIADIC-TYPE; a variadic part needs a C parameter before the
... besides the C.Function ones (PARSE-EXTERN-VARIADIC-FIXED).
callback Name(params) -> result in an extern block declares the type of a C
function pointer that C calls (section 6d). It takes the C types of a def
that cross by value: an integer type, C.Double, C.Float, C.Bool,
C.String (a parameter only) or C.Pointer, and returns one of them but
C.String, or Void; any other type is PARSE-EXTERN-TYPE at the type. It
has no default (PARSE-EXTERN-DEFAULT), no out parameter (PARSE-EXTERN-OUT
at the parameter), no ... (PARSE-EXTERN-VARIADIC) and at most 64
parameters (PARSE-EXTERN-ARITY); a parameter name used twice is
CHECK-REDEFINED-NAME at the second. For the rest of the language it is a
resource: a type, with the place of a type in the declaration order (a block
that declares one goes with the types). A def of the block
below it takes it as a parameter, also in the variadic part, and so is
Optional[Name], which C gets as NULL for none; a callback result, or an
Optional of anything else, is PARSE-EXTERN-TYPE and an out one
PARSE-EXTERN-OUT. callback is a
keyword only at the start of a member of an extern block, before a type name.
struct Name ... end in an extern block declares a C struct that the block’s
functions take and return by value (section 6d). Its fields come in the order of
the C header, each an integer type, C.Double, C.Float, C.Bool,
C.Pointer or a struct declared above in the block; any other type, C.String,
C.Bytes, C.Function and a resource included, is PARSE-EXTERN-TYPE at the
type (a char * field is a C.Pointer). A struct with no field is
PARSE-EXTERN-TYPE at its name, and one with more than 1024 fields or 16
levels, nested structs counted, PARSE-EXTERN-ARITY there. For the rest of the
language it is an ordinary struct whose fields have the Agentica types (Int,
Float, Bool, C.Pointer, the nested struct), with field defaults, .with.
Like a resource, a def of the block may use it after its
declaration (PARSE-EXTERN-TYPE before), as a parameter or a result; an out
struct is PARSE-EXTERN-OUT and a variadic one PARSE-EXTERN-VARIADIC-TYPE.
extern module "NAME" declares the functions of a native module, C code
written against the VM’s C API (section 6d). NAME follows the library rule
above, [native.NAME] of a package included. Each member is a def or
compute def with no body, named as the module’s table names it (? and !
allowed), with Agentica types; the checker says which cross
(CHECK-NATIVE-TYPE, section 6d). A member may also be resource Name, a
resource of the module’s resource table, which frees it. A callback or
struct line, an out parameter, a ... and a C name after = are
PARSE-EXTERN-MODULE at the word, the parameter, the ... or the =, and so
is a comma after a resource’s name (the module frees it, so it has no free:);
a C. type anywhere in a type is PARSE-EXTERN-TYPE at it; a default is
PARSE-EXTERN-DEFAULT and a 65th parameter PARSE-EXTERN-ARITY. For the rest
of the language each function is a def, as in an extern block, and each
member, a resource too, takes the place of a def in the declaration order.
module is a word only between extern and the string.
An import is one of two forms. import Util from "util" gives the file the
alias Util. import {area, Square as Sq} from "shapes" brings exported names
into the file, each with an optional new name after as, and the list may span
lines, may end with a comma, and may not be empty. from and as are not
reserved words: the parser reads them by their text at those two places, so a
parameter or a function called from or as still works, and {as} imports a
function called as. One line does one thing: import Util, {area} from "util"
is PARSE-UNEXPECTED-TOKEN at the comma. Writing the path first is
PARSE-UNEXPECTED-TOKEN at the string, with the help
write import Alias from "path". What each form means is in section 5b.
A function, struct, enum or type alias declaration needs a
blank line before the next declaration; a line with only a comment counts, but a
doc line does not, because it belongs to the declaration after it: the blank
line goes before the doc block. Otherwise PARSE-MISSING-BLANK-LINE is reported
at the next declaration, or at the first line of its doc block. Imports may
follow each other directly, but an import after a declaration also needs the
blank line. A constant follows the imports, and another constant, with no blank
line, also when the next constant has a doc block; the blank line is
still needed between a constant and a struct, enum, type alias or def, and
before an import. In the same way a one-line def may follow a one-line def with
no blank line, also when the next one has a doc block; after a
one-line def the blank line is still needed before any other declaration, and
before a one-line def after any other declaration but an import, a constant or
a def with a body included. Other text after a declaration’s end is
PARSE-TOP-LEVEL-STATEMENT.
Declarations follow a fixed order in every file, the root program, imported
files and embedded std/ modules alike: the module doc and the imports first,
then the public part (the constants and re-exports, then the struct, enum,
type alias and module block declarations, then the functions), then
private and the private part (constants, then types and blocks, then
functions) when the file or module block has one (section 5b). An extern block
that declares a resource or a struct goes with the types, as a whole. type is
contextual in an alias declaration and remains an ordinary name elsewhere. The
order is a style rule only: a function may still call a function, use a struct
declared later or read a constant in the same group. The first declaration that
comes after a declaration of a later group is CHECK-DECL-ORDER, reported at
the start of that declaration (at import when it is one), with help that says
where it goes. The module linker checks it for each file before linking, so a
file with a parse error reports PARSE- first and a file that imports another
reports its own order first.
A constant is NAME = expression or NAME: Type = expression at the top level,
public when it is above private (section 5b). NAME is a TYPE_NAME
token whose text is UPPER_SNAKE_CASE: capital letters, digits and _,
starting with a capital letter, at least two characters. Any other name (Limit = 1, X = 1) is PARSE-CONSTANT-NAME at the name, with the closest constant
name as help when there is one. The built-in all-capitals names (IO, JSON,
TCP, TLS) are reserved type names and cannot be constants. The type is
optional: NAME = expression takes the type of the expression, and NAME: Type = expression checks it against Type and gives [], {} and Set.new([])
the type they need, as for a local. The value is one expression that starts on
the line of the =; it may span lines inside brackets or a do ... end block.
What the expression may contain and how a constant is read are in section 6.
A doc block (a DOC token, section 4) documents what comes on the next line: a
def, struct, enum, type alias or constant declaration, a field inside a struct, or a variant inside an enum. The first
doc block of a file is the module doc when only blank lines and ordinary #
comment lines come before it and a blank line follows it; a # comment line
right after it does not count as that blank line. A file has at most one module
doc. Any other doc block is PARSE-DETACHED-DOC, reported at its first line: a
block followed by a blank line (other than the module doc), by a # comment
line, by an import, or by the end of the file, a block inside a function body,
and a block inside (...), [...] or {...}. Docs are optional and have no
effect when the program runs.
## Adds two numbers.
def add(a: Int, b: Int) -> Int = a + bStruct, enum, type alias and function declarations appear only at the top level.
A type alias is transparent (section 6, “Enums and pattern matching”). The
parser accepts type applications such as
List[Int]. The checker allows them only for supported builtins, declared
structs and enums that take type parameters, and generic aliases. Structs,
enums, aliases and functions are the declarations that take type parameters. A
struct with type parameters is in section 6, “Generic structs”, and a function
in “Generic functions”. A call writes no type arguments: first_or[Int](xs, 0)
is PARSE-UNEXPECTED-TOKEN at the (, because first_or[Int] reads as an
index. A def in an extern block takes no type parameters.
A generic alias, type Matrix[T] = List[List[T]], is pure substitution:
Matrix[Int] means exactly List[List[Int]]. The parameters follow the enum
rules (type names, no repeats, no reserved names:
CHECK-REDEFINED-NAME). A use gives exactly one argument per parameter, and
a bare Matrix is not a partial application; a wrong count is
CHECK-UNKNOWN-TYPE at the use, as for enums, and a non-generic alias takes
none. A parameter may go unused. The arguments are never inferred. An alias
may use other aliases, generic or not (type Grid = Matrix[Float]), and a
cycle, also through the arguments, is CHECK-TYPE-ALIAS-CYCLE. A parameter
may be a Map key or Set element in the target; the key rule is judged on
the expanded type at each use (CHECK-MAP-KEY-TYPE, at the argument). A bad
key or a Void item written in the target itself (type B[T] = Map[Float, T])
is reported at the declaration. The target is read where the alias is declared:
only its own parameters are in scope, so a name in it is never taken for a type
parameter of the use. An enum type parameter that hides a type the alias names
(struct Item, type Items = List[Item], enum E[Item] V(Items) end) is
CHECK-UNKNOWN-TYPE at the use. The argument of an unused parameter is still
checked. A public generic alias is used through an import (S.Matrix[Int],
or import {Matrix} from "m"). Like any alias it is neither a constructor nor a
pattern.
Statements and blocks #
block = { statement } ;
statement = simple_statement, NL
| if_statement
| case_statement
| while_statement
| for_statement ;
simple_statement = binding | compound_binding | return_statement | loop_control | expression
| guard ;
binding = NAME, [ ":", type ], "=", value ;
compound_binding = NAME, ( "+=" | "-=" | "*=" | "/=" | "%=" ), value ;
return_statement = "return", [ value ] ;
value = expression | case_expression ;
loop_control = "break" | "next" ;
guard = ( return_statement | loop_control ), "if", expression ;
if_statement = "if", expression, NL, block,
{ "elsif", expression, NL, block },
[ "else", NL, block ], "end", NL ;
while_statement = "while", expression, [ "do" ], NL, block, "end", NL ;
for_statement = "for", NAME, "in", expression, [ "do" ], NL,
block, "end", NL ;
case_statement = case_expression, NL ;
case_expression = "case", expression, [ "do" ], NL,
match_arm, { match_arm }, "end" ;
match_arm = pattern, { ",", pattern }, [ "if", expression ], "->",
( NL, block | simple_statement, NL, block ) ;
pattern = "_" | literal | "-", INTEGER | "-", FLOAT
| variant_pattern ;
variant_pattern = qualified_variant, [ "(", pattern_slots, ")" ]
| ( "ok" | "error" | "some" ), "(", pattern_slots, ")"
| "none" ;
qualified_variant = TYPE_NAME, ".", TYPE_NAME, [ ".", TYPE_NAME ] ;
pattern_slots = pattern_slot, { ",", pattern_slot } ;
pattern_slot = NAME | "_" | literal | "-", INTEGER | "-", FLOAT
| variant_pattern ;Assignments, if, while and for are statements, not expressions. A case
is a statement too; it gives a value only where the grammar above says value
(the right side of an assignment, after return) and as the last line of a
block, and is PARSE-UNEXPECTED-TOKEN anywhere else (puts(case ...),
1 + case ...). x += e (also -=, *=, /=, %=) means x = x op e, with
the same checks as the long form.
break leaves the innermost while or for; next skips to its next
iteration. Both are CHECK-LOOP-CONTROL outside a loop of the same function or
block: a block cannot break or skip its caller’s loop. Inside a block, return
leaves the block. There is no continue, and no assignment to fields or
indexes.
A guard, return x if c, return if c, break if c or next if c, is the
if c with that one statement and end written out: it checks and runs the
same way. Its if is on the line where the statement starts, so a case value
or a block that spans lines cannot take one, and nothing follows the condition
(no elsif, else or second if); each is PARSE-UNEXPECTED-TOKEN. The
condition reads as an if condition: a method call with a block needs no
parentheses, and a function called by its plain name keeps them.
A guard is a simple statement, so it can be the one-line body of a case arm
(1 -> return x if c) or of a one-line do block.
No other statement takes a modifier (puts(x) if c, x = 1 if c), and there
is no unless: both are PARSE-UNEXPECTED-TOKEN.
A statement that follows a terminator in the same block is
CHECK-UNREACHABLE-CODE, at the first such statement; remove it or move it
before the terminator. The terminators are return, break and next; an if
with an else whose every branch ends in a terminator; and a case whose every
arm does (any mix). The check does not look into loops or calls: System.exit,
a ! function such as unwrap!, while true without a break and try are
not terminators. A branch is its own block: if c with a return and no else
is not a terminator, but a statement after that return inside the branch is
dead.
Expressions and precedence #
expression = or_expr, [ ( ".." | "..." ), or_expr ] ;
or_expr = and_expr, { ( "or" | "||" ), and_expr } ;
and_expr = equality_expr, { ( "and" | "&&" ), equality_expr } ;
equality_expr = comparison_expr,
[ ( "==" | "!=" ), comparison_expr ] ;
comparison_expr = pipe_expr,
[ ( "<" | "<=" | ">" | ">=" ), pipe_expr ] ;
pipe_expr = additive_expr, { "|>", pipe_target } ;
pipe_target = [ "try" ], call_with_parentheses ;
additive_expr = multiplicative_expr,
{ ( "+" | "-" ), multiplicative_expr } ;
multiplicative_expr = unary_expr,
{ ( "*" | "/" | "%" ), unary_expr } ;
unary_expr = ( "-" | "not" | "!" | "try" ), unary_expr | postfix_expr ;
postfix_expr = primary, { ".", NAME
| ".", "with", "(", named_arguments, ")"
| ".", NAME, "(", [ call_arguments ], ")"
| "[", expression, "]"
| block | brace_block } ;
block = "do", [ "|", block_param, { ",", block_param }, "|" ],
block_body, "end" ;
brace_block = "{", [ "|", block_param, { ",", block_param }, "|" ],
lambda_body, "}" ;
block_param = NAME, [ ":", type ] ;
block_body = NL, { statement } | simple_statement ;
lambda = "->", [ "(", block_param, { ",", block_param }, ")" ],
"{", lambda_body, "}" ;
lambda_body = NL, { statement } | simple_statement ;
primary = literal
| "&", ( NAME | TYPE_NAME, ".", [ TYPE_NAME, "." ], NAME )
| NAME, [ "(", [ call_arguments ], ")" ]
| TYPE_NAME, ".", TYPE_NAME, ".", TYPE_NAME, [ "(", [ arguments ], ")" ]
| TYPE_NAME, ".", TYPE_NAME, "(", [ arguments ], ")"
| qualified_type, "(", [ named_arguments ], ")"
| qualified_type
| list_literal
| map_literal
| lambda
| "(", expression, ")" ;
arguments = expression, { ",", expression }, [ "," ] ;
call_arguments = arguments | named_arguments
| expression, { ",", expression }, ",", named_arguments ;
named_arguments = named_argument, { ",", named_argument }, [ "," ] ;
named_argument = NAME, ":", expression ;
list_literal = "[", [ arguments ], "]" ;
map_literal = "{", [ map_entry, { ",", map_entry }, [ "," ] ], "}" ;
map_entry = expression, ":", expression ;
literal = INTEGER | FLOAT | STRING | "true" | "false" | "nil" ;Calls are to named functions, or to function values through .call(...); there
are no user methods. A struct field of type Fn is called by its name:
store.put(a, b) means store.put.call(a, b). call is not a reserved word:
it means a function-value call only right after a . and before (.
Parentheses are required for every call. They may be dropped only for builtin
methods, and for module functions without arguments, builtin or reached through
an import alias: s.length, IO.gets!, while !IO.eof? do, Util.reset. So
f = Util.helper calls helper; write &Util.helper for the function value.
&name references a declared top-level function without captures, and
&Time.now_ms or &Int.to_s a builtin (06-semantics.md, “Function values”).
A call without arguments drops its () before a block: xs.each do |x| ... end,
run do ... end for a function run, and xs.map { |x| x * 2 }. A bare name
without a block is never a call. run() do ... end still parses, and
agentica fmt drops the (). A { ... } block follows only a call written
without (, and its body is a lambda’s: one line or several, up to the };
xs.map() { ... } and xs.map(1) { ... } are PARSE-UNEXPECTED-TOKEN, since
a call with parentheses takes a do block. The () stays after |>
(PARSE-PIPE-TARGET without it), for lambda, proc and loop, and for a
function called by its plain name in an if, elsif, guard or case arm guard
condition: there ready do is PARSE-UNEXPECTED-TOKEN (the do reads as a
mistake for the end of the line), and no call takes a { ... } block. Inside
parentheses, brackets, a map literal or #{...}, a condition or a while,
for or case head takes any block: if (xs.any? { |x| x > 0 }).
A lambda, ->(x) { x + 1 }, is a block written as a value; inside a call’s
parentheses, in the place of the block, it is that block:
xs.map(->(x) { x * 2 }). One without parameters has no parentheses
(-> { 42 }), and its body is always in braces.
->() { ... }, ->x { ... }, ->(x) do ... end, lambda { ... },
lambda do ... end, proc do ... end and fn(x: Int) ... are
PARSE-UNEXPECTED-TOKEN, with a help that shows the lambda.
A bare Enum.Variant of an enum in the same file is that nullary variant, and
M.Enum.Variant through an import alias is one too.
A struct update value.with(name: expr, ...) is the one postfix form with named
arguments, and it needs at least one. with is not a reserved word: it has this
meaning only after a . and before (, so value.with without parentheses
still reads a field named with, and Alias.with(...) (an import alias before
the dot) is a call of the module’s function with. user.with() and a
positional value such as user.with(31) are PARSE-UNEXPECTED-TOKEN, with help
that shows the form: value.with(age: 31). Like a call, the update is a link of
a chain (a.with(x: 1).with(y: 2)), and a do block cannot follow it.
A method chain may span lines (§4). Nothing chains after the end of a
do ... end block: a .name, .call(...), .with(...), [index] or |>
right after that end, on its line or as a leading .name on the next, is
CHECK-CHAIN-AFTER-END, from the end to the name, index or call that
follows. Parentheses around the call do not change it: (xs.map do |x| f(x) end).size is the same chain, and agentica fmt prints it without them. Pass a
lambda and pipe, xs |> map(->(x) { f(x) }) |> join(", "), write a one-line
block in braces, xs.map { |x| f(x) }.join(", "), or bind the result to a
name first. A chain after a block in braces or after a lambda is
fine, and so is a binary operator after end (xs.map do |x| x end + ys).
x |> f(a, b) means f(x, a, b): the left value becomes the first argument of
the call on the right. The right side is a call with parentheses, name(args)
or Alias.name(args) (a user function, an imported function or a builtin),
optionally preceded by try: x |> try f(a) is try f(x, a). A trailing block
works: xs |> each_pair() do |a, b| ... end. Anything else on the right (a bare
name, a field, an index, a method chain such as f(1).g, a literal) is
PARSE-PIPE-TARGET at the right side; wrap the expression in parentheses and
use . on the result, as in (x |> f()).unwrap!. A bare name that is no
function of the file, no function it imports by name and no builtin function
is a method of the left value: xs |> map(->(x) { x * 2 }) is
xs.map(->(x) { x * 2 }), and xs |> sum() is xs.sum; a name that is no
method of the value either, a struct field (an Fn field too) included, is
CHECK-UNKNOWN-NAME at the right side. A function of the program with the
same name as a method wins. A builtin written
with its type, x |> String.strip(), is CHECK-PIPE-METHOD at the right side,
with the method form as help. The styles mix: s.strip |> try parse() |> try validate(). |> binds lower than + and
- and higher than the comparisons, and groups from left to right: a + 1 |> f() is f(a + 1), x |> f() == y is f(x) == y, and x |> f() |> g() is
g(f(x)). try and unary operators bind tighter: try x |> f() is f(try x).
The call keeps its normal order of evaluation (the left value first, then the
other arguments) and its normal diagnostics: the piped argument’s span is the
left expression’s span. A chain over several lines goes in parentheses, one step
per line.
a..b and a...b have the lowest precedence and do not chain: 1..2..3 is
PARSE-UNEXPECTED-TOKEN at the second operator, and 0...n + 1 is 0...(n + 1). A method on a range needs parentheses: (1..5).to_a. 1..5 lexes as two
integers. A line that ends in .. or ... does not continue on the next line.
and and or short-circuit. Operators group from left to right, except that
comparisons and equality do not chain: a < b < c is invalid. From high to low,
the precedence is: named call, field, index and grouping; unary -, not, !
and try; *, /, %; +, -; |>; comparisons; equality; and; or;
ranges. not binds tighter than comparisons, so to negate one, write `not (age
= 18)`.
Nesting is limited to 1,000 levels (PARSE-TOO-DEEP, at the token that passes
the limit). Each statement, expression, prefix operator (-, not, !, try)
and type counts one level inside the one around it. So does each operator of a
chain (a + b + c, x |> f() |> g()) and each .name, [index] or do block
after a primary (a.b.c): what follows the k-th operator or suffix of a chain
(its right operand, its arguments, its block) starts k levels deeper than the
chain. Real programs stay far below it; it keeps the parser inside the VM call
limit of 10,000. The checker has its own limit on the depth of the tree: more
than 1,000 levels of expressions and statements, one level for each, is
CHECK-TOO-DEEP at the node that passes the limit. It also stops an alias
expansion after 1,000 type references with the same code, so repeated aliases
cannot grow exponentially. A chain of operators is as deep as it is long, and
the parser counts the right operand of the first operator of a chain as one more
level only, so a nested chain passes the parser and stops in the checker.