joetjen.net
EN DE
Data format

The text format

How a .dxn document is put together: one value, an optional header, separators that do not matter, comments, identifiers, and the prefixes that introduce everything beyond plain scalars and lists.

Format 1.0

Documents and the header

A document is exactly one value — usually a map, but 42 or [1 2 3] are complete documents too. Before the value may stand the header @dxn and a version string. It is optional, and allowed once, before the value only. The version is informational: a reader must accept any 1.x and may refuse another major version.

# settings for the importer
@dxn "1.0"
%{ batch: 500 }

Whitespace and commas

Spaces, tabs, line breaks and commas are all separators, and none of them carries meaning — not even a trailing or doubled comma. These lines are the same map, and the list below loses nothing but punctuation:

%{x: 1, y: 2}
%{x: 1 y: 2}
%{
  x: 1
  y: 2
}
[1,,, 2,]
[1 2]

Comments

A # starts a comment that runs to the end of the line; no space is needed after it. There are no block comments. Comments are not part of the value: a decoded value has none, and the binary form has no place for them.

%{
  retries: 3   # per request
  #disabled is still just a comment
}
%{retries:3}

A tool that edits a hand-written file needs them, though. dextrin’s Dextrin.Document keeps a document with its comments, blank lines and commas, renders it back byte for byte, and can edit or lay it out without losing a comment. mix dextrin.format uses it. The top-level collection breaks, one entry per line; a nested one stays on one line when that line fits the width, 80 by default:

mix dextrin.format
# importer settings
%{batch: 500, # rows per insert
  retries: 3, hosts: ["db1"
  "db2"]}
# importer settings
%{
  batch: 500  # rows per insert
  retries: 3
  hosts: ["db1" "db2"]
}

Identifiers

Symbols, keywords, struct names and tag names share one rule. A segment starts with a letter (Unicode XID_Start) or _ and continues with letters, digits (XID_Continue), -, ? and !. An identifier is one or more segments joined by ., with at most one / between a namespace and a name. So retry-after, valid?, Point, my-app/money and acme.billing/invoice are all identifiers; a/b/c and a..b are not.

Reserved: nil, true, false, NaN and Infinity. None of these five characters may begin a bare identifier:

CharacterStarts
#a comment
@a tag, a set @{…} or the discard @_
%a map %{…} or a struct %Name{…}
?a character
:a keyword

Tags

A tag is @, an identifier, and the one value it applies to: @uuid "…", @ordered %{…}. The built-in tags are @ordered, @sorted-set and @array for collections; @date, @time, @datetime, @local-datetime and @duration for dates and times; @uuid, @objectid, @ip, @uri, @bytes, @bits and @regex; plus @dxn for the header. Any other name is a custom tag — see custom tags.

Whitespace between a tag and its value means nothing. @array[, the bracket against the tag, is the preferred spelling and the one every writer produces; every other tag is written with one space before its value. Only @regex takes a header in parentheses, its flags; a header on any other tag is a syntax error.

[@array[1 2] @array [1 2]]
[@array[1 2] @array[1 2]]
@uuid(i) "9b74c989-1e2a-4b17-9b1f-2a6a4a2b6f10"
syntax: @uuid takes no (...) header; only @regex(flags) does

Discarding a value

@_ reads the value after it and drops it. Unlike a comment, the discarded value must still be valid DXN, so a broken one is a parse error rather than silently skipped. It is the quick way to switch off one element of a list or one value in a file.

[1 @_ "skip me" 2 3]
[1 2 3]