Nested data
In the terminalela --spec nested-data
The readers give data as the format nests it: maps in lists in maps. The tree package reaches into it by a path, so a value three levels down is one call, and a list of records becomes the rows a table is made from.
body = $(curl -sS https://shop.example/api/orders)doc = json.decode($body)first = tree.get($doc, "orders.0.customer.name")rows = tree.pick($doc["orders"], {"id": "id", "name": "customer.name", "city": "customer.address.city", "phone": "customer.phone"}, fallback = {"city": "unknown", "phone": null})t = table.of($rows)
Keys and positions #
- A path is one string, its steps between dots:
"orders.0.customer.name". Everytreeproc takes the same paths. - A step is text. On a map it is a key, as written. On a list its digits are a position from 0, written without a sign or a leading zero. So
"orders.0"is a list's first item and"codes.404"a map's key"404": what the step meets decides, and only one reading fits each. - A key that holds a dot is reached with the list form, a list of steps, each text or a whole number from 0:
["servers", "web.example", "host"]. Every path argument takes it. A number in it is its digits, so["orders", 0]and["orders", "0"]are the same path. "", or[], is the whole data.- An empty step,
"a..b"or"a.", and a list step that is no key or position (-1,1.5,true) are mistakes, whichtrynever catches.
Reading #
tree.get(data, path)gives the value at the path, a copy, so changing it changes nothing indata. A path that leads nowhere is an error naming the step that failed and what is there: the map's keys, the list's length, or the plain value the path ran into.trycatches it.tree.get(data, path, fallback = value)gives the fallback instead, and fornullat the path too, asmap.getdoes for a key.tree.has(data, path)says whether the path reaches a value, not missing and notnull, ashasdoes for a key.nullon the way,"customer.address.city"with"address": null, leads nowhere: the path has nothing to step into.
tree.get($doc, "orders.0.customer.nme")# error: tree.get: no key "nme" at orders.0.customer; its keys are "name", "address", "phone"tree.get($doc, "orders.5.id")# error: tree.get: no position 5 at orders, a list of 3 items
Setting #
tree.set(data, path, value)gives a copy of the data with the value at the path, astable.setgives a new table;datastays as it was.- A key missing on the way, or one that holds
null, becomes an empty map, asmkdir -pmakes folders:tree.set({}, "meta.source.name", "shop")is{"meta": {"source": {"name": "shop"}}}. - A list's position past its end is an error:
tree.setchanges an item a list has, andlist.appendadds one. So is a step into text, a number, a bool or a table. Either leaves the data as it was. doc = tree.set($doc, path, value), the result written back to the variable it read, sets the value in place, asxs = list.append($xs, x)grows a list: only the steps of the path are walked, and nothing else is copied. A document built a key at a time costs each value once. Written to another variable, the result is a whole copy, since every variable holds a value of its own (LANGUAGE.md, Strict rules).
Rows for a table #
tree.pick(items, columns, fallback = {column: value})flattens each item of a list to one map:columnsmaps each column's name to its path, and the rows keep the columns in the order written.table.oftakes them as they are.- An item the path doesn't reach is an error naming the item, the path and the step, so a mistyped path is caught on the first item, unless
fallbacknames that column's value, which stands in fornulltoo. A key infallbackthat is no column is a mistake.
rows = tree.pick($doc["orders"], {"id": "id", "phone": "customer.phone"})# error: tree.pick: item 1 has no "customer.phone" for the column "phone" (fallback = {"phone": null} takes items without it): no key "phone" at customer; its keys are "name", "address"
The shape #
tree.paths(data)gives a list of every path in the data to a value that holds no other, each once in the order first met, a list's position written*:["page", "orders.*.id", "orders.*.customer.name", "orders.*.tags.*"]. An empty map or list ends a path as a value does.- A path with
*shows a shape and reaches no one value:tree.getandtree.picktake a number, and*in a path given to them is an error that says so. A path through a key that holds a dot, or an empty key, which text can't say, comes in the list form,["versions", "v1.2", "date"], its positions"*"as well; every other path is text. So every pathtree.pathsgives, its*made a number, goes back intotree.getas it is.
Merging maps #
conf = tree.merge(json.decode(file.read("defaults.json")), json.decode(file.read("site.json")))conf = tree.merge($defaults, $user, replace = true)
tree.merge(a, b, replace = false)gives a copy of mapawith mapb's keys merged in, astree.setgives a copy; neither map changes. A key onlybholds is added aftera's keys, inb's order.- A key both hold with a map in each is merged the same way, key by key, as deep as the maps go.
- Anything else under a key both hold is a value, text, a number, a bool,
nullor a list: two equal values are one, and two that differ are an error naming the key's full path and both values, whichtrycatches. A list is a value like any other, so two lists under one key clash unless they are equal;list.append($xs, ..$ys)joins lists, andtable.stacktables' rows. replace = trueletsb's value win wherever the two differ, as settings layer: a user's over the defaults. A map under a key both hold is still merged, sobchanges only the keys it names.aandbare maps; anything else is a mistake that says merge takes maps.
tree.merge({"db": {"host": "a", "port": 5432}}, {"db": {"port": 5433}})# error: tree.merge: db.port is 5432 in the first map and 5433 in the second; replace = true lets the second's win