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.
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:
# 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:
| Character | Starts |
|---|---|
# | 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]