Core built-ins
In the terminalela --spec core-built-ins
| Built-in | Does |
|---|---|
len(x) | Characters in a string, items in a list or map |
type_of(x) | The Type of any value: Type.STRING, Type.LIST, Type.NULL and the rest; never an error (Type and type_of) |
int(x) / float(x) | Explicit conversion; int truncates towards zero |
has(container, x) | A map's key x or a struct's field x has a value (false when missing or null), or a list contains x |
range(a, [b], [step]) | The whole numbers from a up to b, not b itself, as a list: range(3) is [0, 1, 2] (Control flow) |
min(x, more...) / max(x, more...) | The smallest or largest of the numbers; one list of numbers gives its smallest or largest item (Totals, smallest and largest) |
secret_file(text) | A /dev/fd/N path whose pipe holds the text, for the next command that names it (PACKAGES.md, Secrets in commands) |
pid(x) | A process for kill: pid(4242) by its id, pid("firefox") the one process of that name (kill) |
job(x) | A job of the session: job(1) by its number, job("vim") the one job whose command is that (kill) |
progress(count, total, label = "") | A progress line at a terminal (Progress and spinners) |
The top level holds the procs that work on any value or on numbers. A proc for one kind of value is in that kind's package: a list's in list, a map's in map, text's in str (PACKAGES.md).
ela --builtins lists these with every package proc and shell built-in, from the interpreter's own table, each with its parameters' names, which a call may give them by: has(container = $m, x = "k").
Totals, smallest and largest #
list.sum adds up one list of numbers; min and max give the smallest and the largest, of several numbers or of one list:
n = list.sum(range(1000000)) # 499999500000total = list.sum($sizes)biggest = max($sizes)least = min($a, $b, 0)
list.sumtakes one list, typedxs: list: a call given anything else is refused before line 1 where the script writes the argument,list.sum(5), and byela --lintwhere the script shows its type. Two numbers add with+:$a + $b.- The total is what
+gives item by item: whole while every item is whole, to the last digit (list.sum(range(1000000))is499999500000), with a fraction once an item has one (list.sum([1, 2, 3.5])is6.5), and an error past 64 bits, as+is. list.sum([])is0, the total of nothing.min([])andmax([])are errors: an empty list has no smallest number, so checklen($xs) > 0first.- Every item is a number. Text, a boolean,
null, a list or a map is an error that names it and its place, never made a number: an item counted from 0, as$xs[1]reads it, or an argument ofminandmaxcounted from 1. Text that holds a number is converted withint()orfloat()first.
total = list.sum([3, "7"])
total.ela:1:17: error: list.sum takes numbers; item 1 is the text "7": convert it with int() or float()
list.sum([3, true]) stops with list.sum takes numbers; item 1 is the boolean true, and max(1, "2") with max takes numbers; argument 2 is the text "2": convert it with int() or float().
Results are kept #
A built-in that only gives a value is never a line on its own: its result is assigned or used. list.append, list.sort, map.keys and map.values, len, the str and path procs, json.decode and the rest give a new value and change nothing, so a line that calls one and drops what it gives does nothing. It is an error before any line runs, so ela --check reports it too:
keep = []for l in $lines if not str.has_prefix($l, "#") list.append($keep, $l) end ifend forfile.write("notes.txt", str.join($keep, "\n"))
notes.ela:4:9: error: list.append gives a new list: write keep = list.append($keep, …)
keep = list.append($keep, $l) adds the line to keep. The message says what the built-in gives and the line to write, with the variable from the call when the result replaces it: str.upper($name) on its own is str.upper gives new text: write name = str.upper($name).
The rule covers every built-in that gives a value, except the prompts of the ask package and secret_file, which do something besides. Built-ins that do something and give nothing, file.write, dir.create, time.sleep, progress, env.remove and the like, stand alone, as does a call of any proc. At the interactive prompt a call alone on the line typed is no error, and the prompt prints its value (SHELL.md, A value at the prompt); inside a block typed there, it is.