Procs
In the terminalela --spec procs
A proc is declared with proc, its parameters in brackets, and its lines up to end proc.
Types and names are optional: the simple form has none.
| Form | Gives | Example |
|---|---|---|
proc name(a, b), lines, end proc | a proc; return hands values back | proc deploy(target) |
proc name(a); line | a proc on one line | proc paid(r); return $r["paid"] |
proc name(a: string, n: number = 3) | typed parameters, checked at each call; a default | proc deploy(target: string, retries = 3) |
proc name(paths: ..string) | a variadic parameter, the last arguments as a list | proc sync(paths: ..string) |
proc name(a) -> type | one result, typed | proc port_of(addr: string) -> number |
proc name(a) -> (x: type, y: type) | several results, or one named, each typed | proc split_host(addr: string) -> (host: string, port: number) |
proc deploy(target) rsync -a build/ "$target:/srv/app"end proc
- Keyword
proc, as in Odin, in the simple formproc name(args). - Named parameters replace Bash's
$1,$2. Each has a name of its own:proc f(a, a = 5)is an error. returnhands values back to the caller. Multiple values are allowed, separated by commas, as in Go and Odin. Everyreturnin a proc gives the same number of values, so a caller knows how many names to give before the call runs. A call given another number of names is an error that says what to write,pair() gives 2 values: name both, or write _ for one you don't need, and names the results where the proc declares them.exit codeends the whole script with that exit status, andfail "message"ends it with a message on stderr and exit 1 (fail).- A proc may call itself, and procs each other, as deep as the stack holds the calls: about 7,000 calls of a short proc on Linux's usual 8 MB stack, more under a larger
ulimit -sand fewer where each call runs loops or a built-in between, never more than 100,000; in a web page, 400. A call past that is an error that names the proc, never a crash:recursion deeper than 7245 calls in down: does it call itself without a case that stops?
proc load_config() config = toml.decode(file.read("app.toml")) return $config["host"], $config["port"]end proc host, port = load_config()
- A short proc goes on one line, its body after a
;, as a one-lineifdoes:proc newest_first(a, b); return $a["when"] > $b["when"]. It suits a comparator or a filter handed to a built-in; a proc of several lines keeps its body below, closed byend proc. - Procs are only called with brackets:
deploy("staging"). A bare word is always an external command or a built-in, so a proc can never shadow a real command. - Variadic parameters use Odin syntax:
proc run_ls(paths: ..string)collects extra arguments into a list. - A spread,
..$xsas a call's last argument by position, passes a list's items one by one to a variadic parameter, as Odin's does:run_ls("/srv", ..$dirs). A proc without one refuses it, and so does--lint. A built-in's arguments by name may follow it, as Odin'sfmt.println(..args, sep = ""):table.stack(..$pages, fill = true). A script's own proc takes its variadic parameter last, so nothing follows a spread into it. - A list passed to a command spreads into one argument per item; strings are never split.
ls -la $paths.echoalone prints the list's form instead (echo prints any value).
Typed parameters and typed, named results #
A proc may give its parameters types, and declare its results after ->, in Odin's form. Both
are optional, and a proc without them runs as it is. Each buys three things:
ela --lintcatches a wrong call or a wrong use of a result when the script is read, before any line runs.- An error points at the line and names the parameter or the result, so the fix is at hand.
- An agent reads the signature, in
procs,which, an editor's hover or an imported library, and knows what to pass and what comes back without reading the body.
One proc in the three forms, and what each catches:
proc split_host(addr) parts = str.split($addr, ":") return $parts[0], int($parts[1])end proc
The simple form. split_host(8080) fails inside the proc, at str.split. --lint counts what
its returns give, so x = split_host($a) is reported before the run, but not what kind of
value each is.
proc split_host(addr: string) parts = str.split($addr, ":") return $parts[0], int($parts[1])end proc
A typed parameter: split_host(8080) is an error at the call, split_host: addr must be string, got number, and --lint gives it before the run wherever the script shows the argument's type: a
literal, null, $env.NAME, an enum's member, a struct literal, a variable or constant that is
always text, or a call to a proc that declares its result, split_host(port_of($a)) with
port_of declared -> number. A built-in that gives text, a number, a bool, a list or a map
shows it too: len, str.upper. A variable assigned elsewhere is known only when it runs. Some built-ins
type their parameters too, as ela --builtins shows: text.pad(text: string, width: number, ...). A call to one is checked the same way, and a literal it refuses, text.pad(42, 8), stops
the script before line 1.
proc split_host(addr: string) -> (host: string, port: number) parts = str.split($addr, ":") return $parts[0], int($parts[1])end proc host, port = split_host("models.example:8080")
Typed, named results: return $parts[0], $parts[1] is an error at that return, proc split_host: the result port must be number, got string, and return $parts[0] is one before the
script runs. --lint reads the types too: with proc port_of(addr: string) -> number,
if port_of($a) is reported before the run, a condition must be true or false, got number.
- One result without a name is
-> string. Several, or one named, go in brackets:-> (host: string, port: number). Every result is named, or none is:-> (string, number). - A type is one a parameter takes, and ends in
?wherenullmay come back:-> number?. - Every
returnlists its values, one for each result. There is no barereturnthat hands back the named results: the names document the values, and areturnthat gives another number of values is an error at thatreturn, before the script runs where the count is known. A value of the wrong type is an error at itsreturnwhen it runs, and so is a proc that ends without one. procsandwhichshow the signature with its results:split_host(addr: string) -> (host: string, port: number).
What a proc sees #
A proc sees its parameters, the variables it sets itself, the constants, the environment ($env.NAME) and the declarations: procs, structs, enums and imports. It never sees the script's variables, so a proc reads the same wherever it is called from, and a name inside it can't clash with one the script sets. What it needs comes in as a parameter, and what it changes goes back with return.
proc ls_remote(url: string, branch: string) with time.each = "30s"; out, err = try $(git ls-remote $url "refs/heads/$branch") for line in str.split($out, "\n") # its own line, whatever the script calls line ... end for return $out, $errend proc url = "https://git.example/app"branch = "main"line, err = ls_remote($url, $branch)
Reading a script variable inside a proc is an error that says to pass it as a parameter.
Named and optional arguments #
As in Odin, a parameter may have a default, and a call may give an argument by its parameter's name:
proc deploy(target: string, dry_run: bool = false, retries: number = 3) echo "deploying to $target, $retries tries"end proc deploy("staging") # dry_run false, retries 3deploy("staging", retries = 5)deploy(target = "prod", dry_run = true)
- A default is written after the type, or after the name when the parameter is untyped:
retries = 3. Parameters with a default come after those without. - A parameter left out takes its default, evaluated at that call, in the proc's own scope with the parameters before it already bound. So a default can use them, and a default list or map is a new one at every call: a call that changes it never changes the next call's.
proc add(item, items: list = []) return list.append($items, $item)end proc a = add(1) # [1]b = add(2) # [2], not [1, 2] proc backup(src: string, dest = "${src}.bak") cp $src $destend proc
- Arguments by position come first; named ones follow, in any order:
deploy(retries = 5, target = "prod"). A parameter takes one argument, by position or by name. - A variadic parameter comes last, takes no default and is never named: names and defaults stop at it, as in Odin. Its values are the last arguments, by position, so a call that gives it any gives every argument before them by position too.
- A built-in may have parameters after its variadic one, given by name only:
table.stack($a, $b, fill = true),table.stack(..$pages, fill = true).
proc sync(dest: string, mode = "-a", paths: ..string) rsync $mode $paths $destend proc sync("backup.example:/srv") # mode -a, no pathssync("backup.example:/srv", mode = "-av")sync("backup.example:/srv", "-a", "src", "docs")
- Built-in and package procs take names too, the names
ela --builtinslists:str.split($line, sep = ","),ela.spec(topic = "pipes"). So do an imported file's procs, whose defaults are evaluated in that file, where its own procs and declarations are seen.