ela
Contents

ManualPackages

Tables

In the terminalela --spec tables

The loaders give data as the format has it, and nothing more. A table is made from data by choice: table.of gives the columns names and a type each, reads cells by name or by position, and sorts, filters and pages the whole data set, with the original kept. Sorting and filtering are the table's, so they work on every format: CSV rows, a JSON or YAML list, or any list a script holds.

rows = csv.decode(file.read("orders.csv"), sep = ";")t = table.of($rows, header = true, types = {"amount": Type.NUMBER, "paid": Type.BOOL}) proc biggest_first(a, b); return $a["amount"] > $b["amount"]open = table.filter(table.sort($t, by = biggest_first), where = {"paid": false}) for p in table.pages($open, size = 50)    echo "page ${$p.page + 1} of $p.pages"    for row in $p; echo "$row['region'] $row['amount']"end forfile.write("open.csv", csv.encode($open))

Making a table #

table.of(data, header = false, columns = null, types = null, layouts = null) takes table-shaped data and is not bent to fit any:

  • A list of maps, every map with the same keys, the first map's order naming the columns. JSON, YAML and TOML decode to these, TOML's rows being a key's [[...]]: table.of($doc["orders"]).
  • A list of lists, every list as long as the first. With header = true the first names the columns and is not a row; a header that names a column twice or not at all is an error.
  • A cell is text, a number, a bool or null.
  • A missing or an extra key, a short or a long row, and a list or a map in a cell are errors that name the row and the key or column. Anything else, a map at the top or a list of numbers, is an error that says what a table takes. Untidy data is the script's to tidy in plain ela first.
  • columns = ["region", "postcode", "amount"] names the columns of data that has none, or, beside header = true, renames a header's, as for a bank's export. A count that differs from the rows' is an error.
  • Every column is reached by its position from 0, named or not.

Column types #

  • A column holds one type. A CSV field is text until types says otherwise: types = {"amount": Type.NUMBER, "paid": Type.BOOL} names the columns to type, and only those, or [Type.STRING, Type.NUMBER] gives the types by position for a table without names. Guessing a column's type from its cells, Excel's way, which turned gene names into dates, is what ela never does: a postcode 01234 or a version 1.10 stays as it was written.
  • JSON's, YAML's and TOML's values come typed, so a column's type is its values', and a column of a number and text is an error that names the first cell that differs. csv.decode(text, typed = true) gives typed cells as well (Config formats).
  • types takes members of Type, the language's enum of value types (LANGUAGE.md, Type and type_of): Type.STRING (the default), Type.NUMBER (12 whole, 12.5 with a fraction), Type.BOOL (true, false) and Type.TIME. A column holds plain values, so Type.LIST, Type.MAP and the rest are an error that names these four.
  • A cell that does not convert stops table.of at its row and column, naming the column and the text. An empty cell in a typed column is null. A name in types that is not a column is an error.
  • A Type.TIME column holds instants, so dates sort and filter as time whatever the export wrote. layouts = {"when": "02/01/2006"} gives its layout in Go's form, as time.parse takes it; without one a cell is ISO 8601: 2001-02-13T09:30:00Z with its offset, 2001-02-13T09:30:00 in the local zone, or 2001-02-13, a date alone, as midnight in the local zone.
  • A time cell reads as seconds since 1970, as time.now() gives, so time.format and time.since take it. The column keeps each cell's text as it was written, which csv.encode writes back. A table sorts, filters and compares times, and does no calendar arithmetic: no months, weekdays or durations.

Reading a table #

  • $t.rows is the number of rows of a table or a view, and $t.columns the names in order, [] without names. They are read, never set.
  • $t[3] is row 3, from 0, and $t[-1] the last. A row is a map by the column names, or a list for a table without names; a cell is read by name or by position, $row["amount"] or $row[1].
  • for row in $t loops over a table's or a view's rows in its order, and for i, row in $t numbers them from 0.
  • table.rows($t) gives the rows as a plain list, for a change no table call covers; table.of makes a table of it again.
  • vars lists a table with its fields: t table{rows: 4, columns: ["region", "amount", "paid"]}.
  • A table is a value as every value is: assigning it copies it in meaning, so nothing changes behind a script's back. Two tables are equal when they have the same names and the same cells in the same order.

Sorting #

by_amount = table.sort($t, by = "amount", desc = true)by_region = table.sort($t, by = ["region", "amount"])     # the first key, then the nextby_name = table.sort($t, by = 0)                          # a column by positionnewest = table.sort($t, by = newest_first)                # a comparator proc, by name
  • table.sort(t, by, desc = false) gives a view of the table or view t in a new order: by is a column by name or position, a list of them, or a comparator proc.
  • The built-in order is the order list.sort keeps (LANGUAGE.md, Sorting a list): numbers by value, text by character code whatever the machine's LANG, false before true, and null last in either direction, as SQL's NULLS LAST. desc = true reverses it. list.sort, dir.list and dir.walk take fold = true for text with case and accents folded; table.sort keeps the character code.
  • Any other order takes a comparator: a proc (a, b), given two rows, that returns true when a goes before b, as Go's sort.Slice has it. A comparator that does not return a bool is an error at its call.
  • The sort is stable: rows that compare equal keep their order.
  • A sort gives a view and leaves the table as it was.

Filtering #

proc paid(r); return $r["paid"]proc large(r); return $r["amount"] != null and $r["amount"] > 100 settled = table.filter($by_amount, keep = paid)north = table.filter($by_amount, where = {"region": "North", "paid": false})large_north = table.filter($north, keep = large)
  • table.filter(t, keep = null, where = null) gives a view of the rows of t that pass.
  • keep is a proc (row) that returns true to keep the row.
  • where = {"paid": true, "region": "North"} keeps the rows whose cells equal every value given, the columns joined by and. A value is compared as its column's type, so {"amount": 12} on a number column matches 12 and 12.0, and null matches an empty cell. A column the table does not have, or a value of another type, is an error. Anything more than equality, a range or an or, is a keep proc; given both, a row is kept when it passes both.
  • A filter keeps the order of the view it filters, so a filter on a sorted view never sorts again, and changing a filter is cheap. Filtering a filtered view narrows it further; going back to the sorted view resets the filter.

Paging #

for p in table.pages($open)    echo "page ${$p.page + 1} of $p.pages, $p.rows of $p.total rows"    for row in $p; echo $row["region"]end for last = table.page($open, -1, size = 20)
  • table.pages($v, size = 50) gives every page, a list of page views in order, so a loop walks pages as it walks rows; an empty table or view gives [].
  • size is the rows a page holds, 50 unless given, by name or by position: table.pages($v, 20). It is a whole number from 1.
  • table.page($v, n, size = 50) goes straight to one page. Pages count from 0, as every position in ela does, and -1 is the last; a page past the end is an error that names the range. A person's "page 1 of 14" is ${$p.page + 1}, the same +1 a row number needs.
  • A page is a view with page (from 0), pages and total beside rows. Pages share the rows of the view they page: a page costs a row number a row, never a copy.

Edits give a new table #

  • A table and its views are read-only. A cell is read, never set in place: t[3]["amount"] = 0 is an error that says to write t = table.set($t, 3, "amount", 0).
  • table.set($t, row, column, value) gives a new table in which only the changed column is copied and every other column is shared; the old table and its views are unchanged. table.add($t, row) adds a row at the end, a map by the column names or a list by position, and table.drop($t, row) leaves one out, both giving a new table the same way.
  • An edit takes a table, never a view: it changes the table a view came from, and the view is made again after.
  • A value must fit its column: a number in a number column, and so on, or null.

Stacking tables #

orders = table.stack(json.table($r1["body"], at = "orders"), json.table($r2["body"], at = "orders")) pages = []for n in range(5)    body = $(curl -sS "https://shop.example/api/orders?page=$n")    pages = list.append($pages, json.table($body, at = "orders"))end fororders = table.stack(..$pages)
  • table.stack(tables..., fill = false) gives a new table of the tables' rows one after the other, as SQL's UNION ALL: no row is dropped or merged. It takes any number of tables, and a list of them through a spread, table.stack(..$pages), as list.append takes a list's items; fill follows the spread by name, table.stack(..$pages, fill = true).
  • The columns match by name, in any order, and the new table keeps the first table's order. A column one table lacks or another adds is an error naming the table by its position, from 0, and the column. Tables without names match by position, and each has as many columns as the first.
  • A column holds one type, so a column of numbers in one table and of text in another is an error naming both types: types = on table.of or the reader gives them one. A whole number column and one with fractions are both numbers. A column all null in a table, or with no rows, takes the type the others give.
  • fill = true keeps every column of every table, the new ones after the first table's in the order met, a cell a table lacks null; a column of two types is still an error.
  • A view stacks as its rows in its order, sorted, filtered or paged; the result is always a table, never a view, so a page's page, pages and total are not carried.
  • One table gives that table, since a table is never changed; no table, table.stack(..$none) with an empty list, gives the empty table table.of([]) gives, and that table adds nothing to a stack. A table with names and one without don't stack.
  • A time column keeps each cell's instant and the text it was written in, whatever layout each table read it in; the new column takes the first table's layout.
  • Each column is built once, at its full size, the tables' cells copied straight from their columns, with no row made on the way.

Writing a table #

  • csv.encode($v) takes a table or a view and writes its names as the header when it has names, then its rows in their order: text in double quotes, numbers and bools bare, an empty cell for null, and a time cell as its text. csv.decode(text, typed = true) gives the types back.
  • json.encode and yaml.encode write a table as a list of maps, or of lists without names.

How a table is kept #

  • Each column is one typed array, numbers as numbers and bools as bits, never rows of maps. A column's type is decided once, at table.of, so a number column compares as numbers with no conversion a cell.
  • Text is kept once a column: a value repeated in it, a region or a status, is stored once.
  • A view is an array of row numbers over the same columns, and a sort is kept in its view.
  • A row is made when it is read, $v[3] or for row in $v; the table never holds one.
  • A table lives outside the memory of the line or loop that made it, so it is never copied by a loop or at the prompt. Its memory is given back when ela ends, not when the last variable that holds it lets it go: a script that makes tables in a long loop keeps every one of them.