Functions
Define a function #
def defines a function. Every parameter and the result need a type. A function whose body is one value is written on one line, after =; a longer body goes on the lines between the signature and end (see return and One-line functions below).
def greet(name: String) -> String = "Hello, #{name}!"
def main() -> Void
puts(greet("Ana"))
endHello, Ana!Calls always use parentheses, also with no arguments: main(), puts("hi"). Arguments are given by position or by name, and trailing parameters can have default values (see below).
return #
The value of a function is its last expression. When the last statement is an if with an else, or a case, the value is the last expression of the branch or arm that runs. return leaves the function early, often as a guard:
def max(a: Int, b: Int) -> Int
return a if a > b
b
end
def sign(n: Int) -> String
if n > 0
"plus"
elsif n < 0
"minus"
else
"zero"
end
end
def main() -> Void
puts(max(3, 9))
puts(sign(-2))
end9
minusEvery path must give a value. An if without else, a loop or an assignment at the end gives none, and neither does a call of a Void function such as puts, so this is a checker error:
def sign(n: Int) -> String
if n > 0
"plus"
end
end
def main() -> Void
puts(sign(2))
enderror[CHECK-MISSING-RETURN]A Void function gives no value: its last expression is a statement like any other.
One-line functions #
A function whose body is one value can be written on one line, with = after the result type. It is the same as a def whose body is that value.
def double(n: Int) -> Int = n * 2
def label(name: String, count: Int = 1) -> String = "#{count} #{name}"
def main() -> Void
puts(double(4))
puts(label("apple"))
end8
1 appleThe value starts on the line of =; it can go on to more lines as any expression can: inside parentheses or a block, or on a next line that starts with .name. The result type is still required. A Void function has no value to give, so it cannot use this form, and neither can case or if, which are statements. One-line functions may follow each other with no empty line between them, as constants can; next to any other declaration the empty line is still needed, except right after an import, as for every declaration. agentica fmt chooses between the two forms (Format). In an extern block, = "name" after a signature is the C name of the function instead (see Native code).
Void functions #
A function that gives nothing returns Void. It ends at its last line, or at a bare return.
def report(count: Int) -> Void
if count == 0
puts("nothing")
return
end
puts("#{count} items")
end
def main() -> Void
report(0)
report(3)
endnothing
3 itemsOrder and recursion #
Functions can be called before they are defined, and can call themselves.
def main() -> Void
puts(factorial(5))
end
def factorial(n: Int) -> Int
return 1 if n <= 1
n * factorial(n - 1)
end120A call that is the whole value of a return, or the last expression that gives the function’s value, reuses the caller’s frame. Other calls count toward the limit of 10000 nested calls; a call of a builtin uses no frame. The nesting limits of the source (PARSE-TOO-DEEP, CHECK-TOO-DEEP) are in the language reference.
Many results #
A function returns one value. To give back several, return a struct.
struct MinMax
min: Int
max: Int
end
def min_max(xs: List[Int]) -> MinMax
sorted = xs.sort
MinMax(min: sorted[0], max: sorted[sorted.size - 1])
end
def main() -> Void
result = min_max([4, 1, 9, 3])
puts("#{result.min} to #{result.max}")
end1 to 9Function values #
&name is a function as a value. Its type is Fn[...]: the parameter types, then the result type. Call it with .call(...). A builtin with one form is a value too: &Time.now_ms is Fn[Int], and a method takes its receiver first, so [1, 2].map(&Int.to_s) is ["1", "2"]. A builtin with several forms or a rule of its own, such as &List.map, needs a block.
def double(n: Int) -> Int = n * 2
def apply(f: Fn[Int, Int], value: Int) -> Int = f.call(value)
def main() -> Void
f: Fn[Int, Int] = &double
puts(f.call(21))
puts(apply(&double, 5))
puts([1, 2, 3].map(&double))
end42
10
[2, 4, 6]Fn[Void] is a function with no parameters that gives nothing. Function values can live in lists, maps and struct fields.
A function in a struct field is called with the name of the field, like a method: counter.next(1) is counter.next.call(1). counter.next without parentheses still reads the function. Only a field of type Fn can be called this way; any other name is CHECK-UNKNOWN-METHOD, as structs have no methods. A field named to_s or inspect that holds a function wins over the method of that name.
struct Counter
next: Fn[Int, Int]
end
def succ(n: Int) -> Int = n + 1
def main() -> Void
counter = Counter(next: &succ)
puts(counter.next(counter.next(1)))
end3Blocks are the short way to write a function value at the place where you use it.
Chain calls with |> #
x |> f(a) means f(x, a): the left value becomes the first argument.
def parse(text: String) -> Result[Int] = text.to_i
def validate(n: Int) -> Result[Int]
return error("negative") if n < 0
ok(n)
end
def add(a: Int, b: Int) -> Int = a + b
def load(text: String) -> Result[Int]
(
text.strip
|> try parse()
|> validate()
)
end
def main() -> Void
puts(1 |> add(2) |> add(3))
puts(load(" 7 ").inspect)
puts(load("-3").inspect)
total = (
10
|> add(1)
|> add(100)
)
puts(total)
end6
ok(7)
error("negative")
111- The right side must be a call with parentheses. A multi-line chain goes in parentheses, as
totalabove. - It may start with
try:x |> try f()meanstry f(x). - A step may name a method of the value, which is then called on it:
xs |> map(->(x) { x * 2 }) |> sum()isxs.map(->(x) { x * 2 }).sum. A function of the program with the same name as a method wins. - A builtin with a method form is written by the method name, not with its type:
s |> strip()ors.strip, nots |> String.strip()(CHECK-PIPE-METHOD).
def main() -> Void
s = " hi "
puts(s |> String.strip())
enderror[CHECK-PIPE-METHOD]Default parameter values #
A parameter can end with = value. A call may leave it out.
- A default is a constant: a number, a string without
#{...},true,false,nil,none,[],{}or a variant without a payload such asLevel.Info. A struct built with no arguments,options: Options = Options(), is a default too when every field ofOptionshas one. The name of a constant is a default too when its value is one of these, as inlimit: Int = LIMITorLimits.LIMIT(the value is used in place of the name, also for a caller in another module). Anything else,some(1)or a constant such asSUM = 1 + 2too, isCHECK-DEFAULT-VALUE. Each call gets its own[],{}or struct. - Parameters with a default go last (
CHECK-DEFAULT-ORDER). The exception is a lastFnparameter, which a block fills. - Arguments fill the parameters from the left. A wrong count is
CHECK-ARITY, such asexpects 1 to 2 arguments.
def join(words: List[String], sep: String = ", ") -> String = words.join(sep)
def each_line(path: String, timeout_ms: Int = 1000, f: Fn[String, Void]) -> Void
f.call("#{path} after #{timeout_ms} ms")
end
def show(line: String) -> Void
puts(line)
end
def main() -> Void
puts(join(["a", "b"]))
puts(join(["a", "b"], "-"))
each_line("a.txt") do |line| puts(line) end
each_line("b.txt", 50, &show)
enda, b
a-b
a.txt after 1000 ms
b.txt after 50 msA default can name a constant, so one value serves many functions:
LIMIT = 2
def first(words: List[String], count: Int = LIMIT) -> List[String] = words.take(count)
def main() -> Void
puts(first(["a", "b", "c"]))
puts(first(["a", "b", "c"], 3))
end["a", "b"]
["a", "b", "c"]def next_id() -> Int = 1
def label(id: Int = next_id()) -> String = "item #{id}"
def main() -> Void
puts(label())
enderror[CHECK-DEFAULT-VALUE]Named arguments #
Any argument can be given by the name of its parameter, name: value. A call can then set one default and keep the ones before it:
def check(name: String, runs: Int = 100, seed: Int = 0, verbose: Bool = false) -> String
"#{name}: #{runs} runs, seed #{seed}, verbose #{verbose}"
end
def main() -> Void
puts(check("sort", verbose: true))
puts(check("sort", 200, seed: 7))
puts(check(seed: 1, name: "map"))
puts(["a", "b"].join(separator: "-"))
endsort: 100 runs, seed 0, verbose true
sort: 200 runs, seed 7, verbose false
map: 100 runs, seed 1, verbose false
a-b- Positional arguments come first; a positional argument after a named one is
PARSE-UNEXPECTED-TOKEN. Named ones come in any order and run in the order they are written. - A name that is no parameter is
CHECK-UNKNOWN-ARGUMENT, a parameter given twice (by name, or by position and by name) isCHECK-REPEATED-ARGUMENT, and a parameter with no default and no argument isCHECK-MISSING-ARGUMENT. - A trailing block fills the
Fnparameter:each_line("a.txt", timeout_ms: 50) do |line| ... end,xs.reduce(initial: 0) do |acc, x| ... end. When other arguments are named, a function value for that parameter is passed as a block or by name (f: &show), not by position. - Builtins and
std/functions take names too. A function value does not: itsFntype has no names, sof.call(1)stays positional.
def label(id: Int, prefix: String = "item") -> String = "#{prefix} #{id}"
def main() -> Void
puts(label(1, prefx: "row"))
enderror[CHECK-UNKNOWN-ARGUMENT]Type parameters #
A function can take type parameters after its name, so one definition works on any type. The call gives no type arguments: the checker finds them from the arguments.
def first_or[T](xs: List[T], fallback: T) -> T
return fallback if xs.length == 0
xs[0]
end
def max_by[T](xs: List[T], key: Fn[T, Int]) -> Optional[T]
return none if xs.length == 0
best = xs[0]
best_key = key.call(best)
for x in xs
k = key.call(x)
if k > best_key
best = x
best_key = k
end
end
some(best)
end
def main() -> Void
puts(first_or(["ana", "ben"], "none"))
puts(first_or([], 0))
longest = max_by(["pear", "fig", "banana"]) do |w| w.length end
puts(longest.unwrap_or("none"))
endana
0
bananaIn first_or(["ana", "ben"], "none") the type T is String, from the first argument. In first_or([], 0) the empty list says nothing, so T is Int from the 0, and the list is checked last. The result type of the call can also fix T, as in xs: List[Int] = empty_of() for def empty_of[T]() -> List[T]. The block comes last: its parameter types come from T (or, when T is still open, from their uses in the block), and its result fixes the type parameters that only the result of the Fn mentions. A parameter still open is CHECK-ENUM-TYPE-INFERENCE. A parameter whose type has T takes a default as any other, such as rest: List[T] = [] or extra: Optional[T] = none; a call must still show T through another argument or its expected type.
def empty_of[T]() -> List[T] = []
def main() -> Void
xs = empty_of()
enderror[CHECK-ENUM-TYPE-INFERENCE]Inside the body, T can be any type, so the body can only store it, return it and pass it on. Comparing, adding, printing or reading a field of a T value is an error, such as CHECK-TYPE-MISMATCH for ==. To act on the items, take a function, as max_by does with key. JSON.encode and JSON.from are the exception: they work on a T value, and each call checks that the type it gives T can be written as JSON (JSON).
def same[T](a: T, b: T) -> Bool = a == b
def main() -> Void
puts(same(1, 1))
enderror[CHECK-TYPE-MISMATCH]A type parameter is a type name that no struct, enum or alias of the file has (CHECK-REDEFINED-NAME). &first_or is a function value only where the Fn type fixes each type parameter, as in f: Fn[List[Int], Int, Int] = &first_or. A generic function can be exported and imported like any other.
No overloading #
A name has one definition: no overloading and no methods on your own types. Use a default value instead of a second version.