ela
Contents

ManualPackages

Config formats

In the terminalela --spec config-formats

  • json, toml, yaml and csv each provide decode(text) and encode(data), as in Go.

  • Decoding produces lists and maps; encoding produces a string. Each also provides table(text, …), which makes a table straight from the text (Tables from JSON, YAML, TOML and CSV).

  • Maps keep the file's order, so a config read, changed and written back keeps its order.

  • Decoded text is data: a reference in it, such as "$API_KEY" or "keyring:prusalink", is not resolved and decodes as the text it is. A script that wants what one names reads $env.NAME or keyring.lookup(name) itself.

  • A fault in the text is an error that gives its line and column there, after the script's own place: deploy.ela:4:7: error: yaml.decode: line 2, column 1: the key "image" is already in this mapping; keep one of the two. A value ela can't hold, such as a whole number past 64 bits or TOML's inf, gives the place where the value starts, not its key's. try catches both.

  • null decodes as null, in a map, a list or as the whole document, so a file read and written back keeps it: compose's volumes: {db-data: } keeps db-data.

  • json.encode and yaml.encode write a map's or a list's null as null (YAML writes a map's as an empty value, db-data:), and leave out a struct's null field.

  • TOML has no null and says it by leaving the key out: toml.encode leaves out a map's null member and a struct's null field, and a null in a list or as the whole document is an error.

  • A whole number is whole; one too large for a 64-bit integer is an error, not a float that has lost digits.

  • A JSON number with a point or an exponent is a float, a double, which holds about 1.8e308 at most: one past it, 1e999, is an error, the number is too large for a double, not infinity. A fault inside an array or object names where it is, after the line and column: json.decode('[{"a": 1e999}]') stops with json.decode: line 1, column 8: in [0].a: the number is too large for a double, at the first item's key a. A number a double can't hold is text to the program that wrote it, "1e999".

  • encode indents with two spaces. A struct encodes as an object of its fields that are not null, an enum value as its name.

  • TOML: tables keep the file's order too. A date-time decodes to its text (2001-02-03T04:05:06Z), since ela has no date type, and encodes back as a string; inf and nan are errors. A TOML document is a map or a struct at the top.

config = toml.decode(file.read("app.toml"))config["port"] = 9090file.write("app.toml", toml.encode($config))

YAML, through amber-yaml on libyaml, is for the files other tools own: Kubernetes manifests, compose files, CI files.

  • yaml.decode(text) reads one document, and a second after --- is an error. yaml.decode_all(text) reads a stream as a list of its documents, as kubectl apply -f takes several manifests from one file, and yaml.encode_all(documents) writes a list back as one, --- between them.
  • A plain value is read by YAML 1.2's core schema: true, 12, 0x1F, 1.5, null, ~ and nothing at all are what they say, and yes, no, on, off and 2001-02-03 are text, as is anything quoted. A key is text as written, so a CI file's on: is the key "on".
  • An anchor and its alias (&base, *base) decode as copies of the value, and a merge key, <<: *base, adds the keys of the map it names that its own map does not set. encode writes the copies, never an anchor or an alias.
  • Comments are not kept: libyaml drops them before ela sees the text, so a file read and written back loses them. A script that must keep a person's comments edits the text.
  • Errors, each at its line and column: a key given twice, a tag outside the core schema (!!binary), a number with a leading zero such as the file mode 0644 (write 0o644, or quote it for text), a tab in the indentation, .inf and .nan.
  • encode writes block style, a list's - lined up under its key, and a string in double quotes where some YAML reader would take it for something else: "yes", "on", "0644", "2001-02-03", a key as well as a value. A string over several lines is a literal block, |. The text ends with a newline.
compose = yaml.decode(file.read("compose.yaml"))compose["services"]["web"]["image"] = "registry.example/web:1.4"file.write("compose.yaml", yaml.encode($compose)) docs = yaml.decode_all(file.read("web.yaml"))for i, d in $docs    if $d["kind"] == "Deployment"        docs[$i]["spec"]["replicas"] = 3    end ifend forfile.write("web.yaml", yaml.encode_all($docs))

CSV is for what spreadsheets and reports give and take.

  • csv.decode(text) reads RFC 4180: a field in double quotes holds the separator, a line break, and a " written twice. It gives the rows as a list of lists of fields, the header row, when the file has one, first among them; sep = ";" reads the separator Excel writes in many countries, or any other one character. An empty line is skipped.
  • Every field is text: CSV has no types, and a postcode 01234, an id or a version 1.10 would change if ela guessed a number.
  • typed = true reads the types from the quoting, the convention csv.encode writes (Python's QUOTE_NONNUMERIC): a field in double quotes is text, a bare field a number or a bool as ela writes them (12, -1.5, true), and an empty bare field null. A bare field that is neither, such as 01234 or AB12, is an error at its line and column. It is a switch a script turns on, never assumed: Excel leaves text and postcodes bare, and one file is not told from another by looking.
  • A byte order mark at the start, which Excel writes, is left out.
  • Errors, each at its line and column: a " inside a field that does not start with one, text after a quoted field's closing ", a quoted field with no closing ", and a row with more or fewer fields than the first.
  • csv.encode(rows, columns = null, sep = ",") writes the typed convention: text always in double quotes, numbers and bools bare, null as an empty field, so csv.decode(text, typed = true) gives the types back and Excel and every other program read it as ordinary CSV. A row is a map, a struct or a list; columns = ["name", "size"] picks and orders the keys or fields, the first row's when left out, and rows that are lists have no header unless columns gives one; sep = ";" writes another separator, as csv.decode reads one. A field is text, a number or a bool; null is an empty field.
rows = csv.decode(file.read("sales.csv"), sep = ";")total = 0for row in $rows[1:]; total = $total + int($row[2])file.write("totals.csv", csv.encode([{"rows": len($rows) - 1, "total": $total}]))