ela
Contents

ManualPackages

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". Every tree proc 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, which try never catches.

Reading #

  • tree.get(data, path) gives the value at the path, a copy, so changing it changes nothing in data. 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. try catches it.
  • tree.get(data, path, fallback = value) gives the fallback instead, and for null at the path too, as map.get does for a key.
  • tree.has(data, path) says whether the path reaches a value, not missing and not null, as has does for a key.
  • null on 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, as table.set gives a new table; data stays as it was.
  • A key missing on the way, or one that holds null, becomes an empty map, as mkdir -p makes folders: tree.set({}, "meta.source.name", "shop") is {"meta": {"source": {"name": "shop"}}}.
  • A list's position past its end is an error: tree.set changes an item a list has, and list.append adds 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, as xs = 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: columns maps each column's name to its path, and the rows keep the columns in the order written. table.of takes 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 fallback names that column's value, which stands in for null too. A key in fallback that 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.get and tree.pick take 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 path tree.paths gives, its * made a number, goes back into tree.get as 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 map a with map b's keys merged in, as tree.set gives a copy; neither map changes. A key only b holds is added after a's keys, in b'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, null or a list: two equal values are one, and two that differ are an error naming the key's full path and both values, which try catches. 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, and table.stack tables' rows.
  • replace = true lets b'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, so b changes only the keys it names.
  • a and b are 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