ela
Contents

ManualLanguage

Lists and maps

In the terminalela --spec lists-and-maps

  • Literals look like JSON, so parsed JSON, TOML and YAML look the same as written data.
  • Maps keep insertion order, so a loaded config prints and saves back in file order.
  • A list's procs are in the list package and a map's in the map package, as text's are in str: list.append, list.sort, list.sum, list.head and list.tail; map.keys, map.values and map.get (PACKAGES.md, Lists and maps). len(x) and has(container, x) work on any of them, at the top level.
  • A call to append(…), sort(…), sum(…), keys(…), values(…) or get(…) stops before line 1 and names the package's proc, as print points to echo: no proc named 'append'; ela's list procs are in list.: list.append(xs, item).
  • A value has no methods. A call written as one, xs.append(x) or $s.split(":"), stops before line 1 and names the package's proc, the value first: xs.append(…) is no call: ela has no methods; a value's procs are in its package and take it first: xs = list.append($xs, item).
  • xs = list.append($xs, x) adds x to the list xs holds, in place, as xs[i] = v changes it: a list built in a loop costs each item once, never a copy of the list a round. ys = list.append($xs, x) is a new list, and xs stays as it was.
  • A list a map or a struct holds grows in place the same way, where the line puts it back where it read it: m[$k] = list.append($m[$k], x), m[$k] = list.append(map.get($m, $k, []), x) and s.ids = list.append($s.ids, x), the key a literal or a variable written alike on both sides. A key that holds no list yet gets the new list, as the line says.
  • list.append($xs, x) alone on a line is an error, since it changes nothing: write xs = list.append($xs, x) (Results are kept).
  • Two lists are joined by spreading one into list.append: all = list.append($xs, ..$ys), which grows xs in place when it is xs = list.append($xs, ..$ys). + on two lists is an error that says so, as + joins no strings either.
  • Data nested several levels deep, as JSON and YAML give it, is reached by a path with the tree package: tree.get($doc, "orders.0.customer.name"), doc = tree.set($doc, "meta.source", "shop") in place, and tree.pick for rows a table takes (PACKAGES.md, Nested data).
  • == compares two lists or two maps item by item. Items of different types are not equal, so [1, 2] == ["a", "b"] is false and has([1, "b"], "b") is true; only two plain values of different types, as "5" == 5, are an error.

Map keys are always accessed with brackets, as in Go. The dot is reserved for struct fields.

files = ["a.txt", "b.txt"]config = {"host": "models.example", "port": 8080} echo $files[0]echo $config["host"]config["port"] = 9090 for item in $files    echo "$item"end for for index, item in $files    echo "$index: $item"end for for key, value in $config    echo "$key = $value"end for for index, key in map.keys($config)    value = $config[$key]    echo "$index: $key = $value"end for

Sorting a list #

list.sort(list, by = null, desc = false, fold = false) gives a new list in order, the order table.sort keeps: numbers by value, text by character code, the same on every machine (B before a, ä after z), false before true, and null last either way. desc = true turns it round. Items that compare the same keep their order.

A list of lists, maps or structs, or one that mixes numbers, text and bools, takes a comparator: a proc passed by name that returns true when a goes before b, as table.sort takes one (PACKAGES.md, Sorting).

names = list.sort(map.keys($hosts))newest = list.sort($sizes, desc = true) proc by_name(a, b); return $a["name"] < $b["name"]hosts = list.sort($hosts, by = by_name)

fold = true sorts text as people read it, still the same on every machine rather than by LANG: case and accents folded, a beside A and ä beside a. Text the fold makes equal goes by character code, A before a before Ä before ä, so no two names tie. dir.list(path, fold = true) and dir.walk(path, fold = true) sort a folder's names the same way (PACKAGES.md, Paths and directories).

  • A Latin letter with an accent folds to its plain letter, from Unicode's own data: é is e, ø is o, ł is l, and ı and İ are i. ß is ss, æ is ae and œ is oe, so Straße sorts beside Strasse.
  • A letter with no plain letter to stand beside (þ, ð, ŋ), and Greek and Cyrillic, keep their own place after z, case folded.
  • Numbers, bools and null sort as they do without it, and a comparator gives its own order, so fold goes without by.
for name in dir.list("/home/ada/Code/play/amber", fold = true)    echo $nameend for
amber-jsonAmber-Notesämber-zetaodin-gtk4

Without fold the same call prints Amber-Notes, amber-json, odin-gtk4, ämber-zeta.

Indexes and slices #

A list and a string are read by position, from 0, a string by character as len counts it. A negative position counts back from the end: -1 is the last. [a:b] is a slice, from a up to b and without it; either may be left out.

lines = str.split($(git log --oneline -5), "\n")newest = $lines[0]oldest = $lines[-1]rest = $lines[1:]before_last = $lines[:-1]short = $head[0:8]tail = list.tail($lines, 10)
  • A position past either end is an error that names the range, -5 to 4 for five items, in an index and in a slice alike, where a slice's bound may also be 5, the end itself. A slice whose start comes after its end is an error.
  • Up to n items or characters, all of it when there are fewer, is list.head($xs, n) and list.tail($xs, n), str.head($s, n) and str.tail($s, n): the last 10 lines of a log of 4 lines are its 4 (PACKAGES.md, First and last items).
  • A string's character is a string of one character. A string can't be changed in place; a list's item can: xs[0] = "a".
  • A long string is counted once and read on from where the last read stopped, so a loop over $s[$i] walks it once, whatever its characters: 200,000 characters of a 1 MB file in 60 ms. A string whose characters are each one byte is read at the byte.
  • A slice is a new list or string, as every value is a copy.