joetjen.net
EN DE
Datenformat

Das Textformat

Wie ein .dxn-Dokument aufgebaut ist: ein Wert, eine optionale Kopfzeile, Trenner ohne Bedeutung, Kommentare, Bezeichner und die Präfixe, mit denen alles jenseits einfacher Skalare und Listen beginnt.

Format 1.0

Dokumente und Kopfzeile

Ein Dokument ist genau ein Wert — meist eine Map, aber auch 42 oder [1 2 3] sind vollständige Dokumente. Vor dem Wert darf die Kopfzeile @dxn mit einer Versionszeichenkette stehen. Sie ist optional und nur einmal erlaubt, und nur vor dem Wert. Die Version dient der Information: Ein Leser muss jedes 1.x akzeptieren und darf eine andere Hauptversion ablehnen.

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

Leerraum und Kommas

Leerzeichen, Tabulatoren, Zeilenumbrüche und Kommas sind allesamt Trenner, und keiner trägt Bedeutung — auch kein abschließendes oder doppeltes Komma. Diese Zeilen sind dieselbe Map, und die Liste darunter verliert nur Satzzeichen:

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

Kommentare

Ein # beginnt einen Kommentar bis zum Zeilenende; ein Leerzeichen danach ist nicht nötig. Blockkommentare gibt es nicht. Kommentare gehören nicht zum Wert: Ein dekodierter Wert hat keine, und die Binärform hat keinen Platz für sie.

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

Ein Werkzeug, das eine von Hand gepflegte Datei bearbeitet, braucht sie aber. Dextrin.Document in dextrin hält ein Dokument samt Kommentaren, Leerzeilen und Kommas, gibt es Byte für Byte zurück und kann es bearbeiten oder neu setzen, ohne einen Kommentar zu verlieren. mix dextrin.format nutzt es. Die oberste Sammlung wird umbrochen, ein Eintrag pro Zeile; eine verschachtelte bleibt auf einer Zeile, wenn diese in die Breite passt, standardmäßig 80:

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"]
}

Bezeichner

Symbole, Keywords, Struct-Namen und Tag-Namen folgen einer Regel. Ein Segment beginnt mit einem Buchstaben (Unicode XID_Start) oder _ und setzt sich mit Buchstaben, Ziffern (XID_Continue), -, ? und ! fort. Ein Bezeichner besteht aus einem oder mehreren Segmenten, verbunden durch ., mit höchstens einem / zwischen Namensraum und Namen. retry-after, valid?, Point, my-app/money und acme.billing/invoice sind also Bezeichner, a/b/c und a..b nicht.

Reserviert sind nil, true, false, NaN und Infinity. Keines dieser fünf Zeichen darf einen nackten Bezeichner einleiten:

ZeichenLeitet ein
#einen Kommentar
@ein Tag, eine Menge @{…} oder das Verwerfen @_
%eine Map %{…} oder ein Struct %Name{…}
?ein Zeichen
:ein Keyword

Tags

Ein Tag ist @, ein Bezeichner und der eine Wert, auf den es sich bezieht: @uuid "…", @ordered %{…}. Eingebaut sind @ordered, @sorted-set und @array für Sammlungen; @date, @time, @datetime, @local-datetime und @duration für Datum und Uhrzeit; @uuid, @objectid, @ip, @uri, @bytes, @bits und @regex; dazu @dxn für die Kopfzeile. Jeder andere Name ist ein eigenes Tag — siehe eigene Tags.

Leerraum zwischen einem Tag und seinem Wert hat keine Bedeutung. @array[, die Klammer direkt am Tag, ist die bevorzugte Schreibweise und die, die jeder Schreiber erzeugt; jedes andere Tag wird mit einem Leerzeichen vor seinem Wert geschrieben. Nur @regex nimmt einen Kopf in Klammern, seine Flags; ein Kopf an jedem anderen Tag ist ein Syntaxfehler.

[@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

Einen Wert verwerfen

@_ liest den folgenden Wert und verwirft ihn. Anders als ein Kommentar muss der verworfene Wert gültiges DXN sein; ein fehlerhafter ist ein Parse-Fehler, statt still übergangen zu werden. So lässt sich ein einzelnes Listenelement oder ein Wert schnell abschalten.

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