Config formats
In the terminalela --spec config-formats
json,toml,yamlandcsveach providedecode(text)andencode(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.NAMEorkeyring.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'sinf, gives the place where the value starts, not its key's.trycatches both.nulldecodes asnull, in a map, a list or as the whole document, so a file read and written back keeps it: compose'svolumes: {db-data: }keepsdb-data.json.encodeandyaml.encodewrite a map's or a list'snullasnull(YAML writes a map's as an empty value,db-data:), and leave out a struct'snullfield.TOML has no null and says it by leaving the key out:
toml.encodeleaves out a map'snullmember and a struct'snullfield, and anullin 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.8e308at 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 withjson.decode: line 1, column 8: in [0].a: the number is too large for a double, at the first item's keya. A number a double can't hold is text to the program that wrote it,"1e999".encodeindents with two spaces. A struct encodes as an object of its fields that are notnull, 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;infandnanare 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, askubectl apply -ftakes several manifests from one file, andyaml.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, andyes,no,on,offand2001-02-03are text, as is anything quoted. A key is text as written, so a CI file'son: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 mode0644(write0o644, or quote it for text), a tab in the indentation,.infand.nan. encodewrites 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 version1.10would change if ela guessed a number. typed = truereads the types from the quoting, the conventioncsv.encodewrites (Python'sQUOTE_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 fieldnull. A bare field that is neither, such as01234orAB12, 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,nullas an empty field, socsv.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 unlesscolumnsgives one;sep = ";"writes another separator, ascsv.decodereads one. A field is text, a number or a bool;nullis 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}]))