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 = truethe 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, besideheader = 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
typessays 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 postcode01234or a version1.10stays 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). typestakes members ofType, the language's enum of value types (LANGUAGE.md, Type and type_of):Type.STRING(the default),Type.NUMBER(12whole,12.5with a fraction),Type.BOOL(true,false) andType.TIME. A column holds plain values, soType.LIST,Type.MAPand the rest are an error that names these four.- A cell that does not convert stops
table.ofat its row and column, naming the column and the text. An empty cell in a typed column isnull. A name intypesthat is not a column is an error. - A
Type.TIMEcolumn 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, astime.parsetakes it; without one a cell is ISO 8601:2001-02-13T09:30:00Zwith its offset,2001-02-13T09:30:00in the local zone, or2001-02-13, a date alone, as midnight in the local zone. - A time cell reads as seconds since 1970, as
time.now()gives, sotime.formatandtime.sincetake it. The column keeps each cell's text as it was written, whichcsv.encodewrites back. A table sorts, filters and compares times, and does no calendar arithmetic: no months, weekdays or durations.
Reading a table #
$t.rowsis the number of rows of a table or a view, and$t.columnsthe 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 $tloops over a table's or a view's rows in its order, andfor i, row in $tnumbers them from 0.table.rows($t)gives the rows as a plain list, for a change no table call covers;table.ofmakes a table of it again.varslists 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 viewtin a new order:byis a column by name or position, a list of them, or a comparator proc.- The built-in order is the order
list.sortkeeps (LANGUAGE.md, Sorting a list): numbers by value, text by character code whatever the machine'sLANG,falsebeforetrue, andnulllast in either direction, as SQL'sNULLS LAST.desc = truereverses it.list.sort,dir.listanddir.walktakefold = truefor text with case and accents folded;table.sortkeeps the character code. - Any other order takes a comparator: a proc
(a, b), given two rows, that returnstruewhenagoes beforeb, as Go'ssort.Slicehas 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 oftthat pass.keepis a proc(row)that returnstrueto 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 matches12and12.0, andnullmatches 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 akeepproc; 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[].sizeis 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-1is 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),pagesandtotalbesiderows. 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"] = 0is an error that says to writet = 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, andtable.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'sUNION ALL: no row is dropped or merged. It takes any number of tables, and a list of them through a spread,table.stack(..$pages), aslist.appendtakes a list's items;fillfollows 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 =ontable.ofor the reader gives them one. A whole number column and one with fractions are both numbers. A column allnullin a table, or with no rows, takes the type the others give. fill = truekeeps every column of every table, the new ones after the first table's in the order met, a cell a table lacksnull; 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,pagesandtotalare 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 tabletable.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 fornull, and a time cell as its text.csv.decode(text, typed = true)gives the types back.json.encodeandyaml.encodewrite 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]orfor 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.