ela
Contents

ManualLanguage

Core built-ins

In the terminalela --spec core-built-ins

Built-inDoes
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.sum takes one list, typed xs: list: a call given anything else is refused before line 1 where the script writes the argument, list.sum(5), and by ela --lint where 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)) is 499999500000), with a fraction once an item has one (list.sum([1, 2, 3.5]) is 6.5), and an error past 64 bits, as + is.
  • list.sum([]) is 0, the total of nothing. min([]) and max([]) are errors: an empty list has no smallest number, so check len($xs) > 0 first.
  • 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 of min and max counted from 1. Text that holds a number is converted with int() or float() 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.