joetjen.net
EN DE
Datenformat

Werte

DXN hat 31 Datentypen in vier Gruppen: Skalare, Sammlungen, Zeitwerte und erweiterte Typen. Jeder hat genau eine Textschreibweise und eine Binärkodierung.

Format 1.0

Auf einen Blick

TypText
nil, booleannil true false
Ganzzahl, Gleitkomma-17 3.14 5e-3 NaN -Infinity
Dezimalzahl, Bruch19.99M 22/7
Zeichenkette, Zeichen"text\n" ?a ?s
Symbol, KeywordPoint ns/name :ok name:
Liste, Tupel, Array[1 2] {:ok 200} @array[1 2]
Map, geordnete Map%{a: 1} %{"k" => 1} @ordered %{…}
Menge, sortierte Menge@{1 2} @sorted-set @{3 1 2}
struct%Point{x: 1 y: 2} %Point[1 2] %Point(2){x: 1 y: 2}
Datum, Zeit@date "2024-01-01" @time "12:30:00.5"
Zeitpunkt, lokale Uhrzeit@datetime "2024-01-01T12:30:00Z" @local-datetime "2024-01-01T12:30:00"
Dauer@duration "P1Y2M10D"
UUID, ObjectId, IP@uuid "…" @objectid "507f1f77bcf86cd799439011" @ip "192.0.2.1"
URI, Bytes, Bits, Regex@uri "…" @bytes "SGVsbG8=" @bits {"oA==" 3} @regex(i) "^a+$"
eigenes Tag@my-app/money 500

Zahlen

Vier Arten, jede genau in dem, was sie ist:

  • Ganzzahl — ein optionales - und Ziffern, mit beliebiger Genauigkeit. Es gibt kein +, kein Hex und keine Zifferntrenner.
  • Gleitkommazahl — ein IEEE-754-Double, mit Nachkommastellen, Exponent oder beidem. NaN, Infinity und -Infinity sind Literale; NaN hat kein Vorzeichen.
  • Dezimalzahl — Ziffern mit nachgestelltem M, exakte Festkommazahl. 19.99M bleibt 19,99, im Text wie binär, und 1.50M behält seine zweite Nachkommastelle.
  • Bruch — Zähler/Nenner, gespeichert wie geschrieben: 22/7 und 44/14 sind verschiedene Werte. Ein Nenner von null ist ein Fehler.
[42 -17 12345678901234567890123 3.14 1e3 NaN -Infinity 19.99M -1/3]

Zeichenketten und Zeichen

Zeichenketten sind UTF-8 in doppelten Anführungszeichen und dürfen über Zeilen reichen. Die Escapes sind \", \\, \n, \t, \r, \0, \a, \b, \f, \v und \x{…} mit beliebig vielen Hex-Ziffern für einen Codepoint. Eine Form mit einfachen Anführungszeichen und Interpolation gibt es nicht.

Ein Zeichen ist ? mit einem Codepoint — ein eigener Wert, keine Zeichenkette aus einem Buchstaben. ?s ist das Leerzeichen, und Escapes funktionieren auch nach ?.

["tab\there, smile \x{1F600}" ?a ?s ?\n ?é]

Symbole und Keywords

Ein nackter Bezeichner ist ein Symbol: ein Name, der auf etwas verweist — einen Typ, einen Handler, ein Schema — und nie ausgewertet wird. Ein Keyword ist ein Name als Wert, etwa ein Status oder Modus: :ok, oder :"mit Leerzeichen", wenn es kein einfacher Bezeichner ist. In einer Map ist name: vor einem Wert ein Keyword-Schlüssel.

%{
  handler: billing/invoice-created   # a symbol
  status:  :ok                       # a keyword
  label:   :"needs review"
}

:nil, :true und :false sind Keywords wie alle anderen, nicht nil und die Wahrheitswerte. Ihre Namen sind reserviert, daher werden sie in Anführungszeichen zurückgeschrieben:

[:nil :true :false]
[:"nil" :"true" :"false"]

Sammlungen

FormTypBedeutung
[…]Listeeine geordnete Folge, die wachsen darf
{…}Tupeleine feste Gruppe — ein Paar, ein Ergebnis, ein Datensatz
@array[…]arrayeine Folge fester Größe mit Indexzugriff
%{…}mapSchlüssel auf Werte, ohne festgelegte Reihenfolge
@ordered %{…}geordnete Mapeine Map, deren Reihenfolge zu ihrer Identität gehört
@{…}Mengeverschiedene Werte, ungeordnet
@sorted-set @{…}sortierte Mengeeine stets sortierte Menge

Ein Map-Eintrag ist entweder name: wert für Keyword-Schlüssel oder schlüssel => wert für die übrigen Schlüsseltypen. Beide Stile lassen sich mischen. Eine einfache Map verspricht keine Reihenfolge, auch wenn ihre Einträge nacheinander stehen; wo die Reihenfolge zählt, sagt @ordered das ausdrücklich.

%{
  name: "api"
  "Content-Type" => "application/json"
  404 => :not-found
  @date "2024-12-24" => "closed"
}
@sorted-set @{3 1 2}
@sorted-set @{1 2 3}

Map-Schlüssel

Ein Map-Schlüssel muss eine Zeichenkette, ein Keyword, eine Ganzzahl, eine UUID, eine ObjectId, ein Datum, Bytes, ein Symbol oder ein Zeichen sein. Jeder andere Schlüssel ist ein Fehler, key/not-allowed, ob er aus Text oder Binärform gelesen oder gerade geschrieben wird. Zwei Schlüssel sind genau dann derselbe, wenn ihre kanonischen Formen gleich sind: gleicher Typ, gleicher Wert. 1 und "1" sind also verschiedene Schlüssel, ebenso :x und "x". Ein Schlüssel, der zweimal vorkommt, behält seinen letzten Wert.

%{a: 1, a: 2}
%{a:2}
%{1.5 => :x}
key/not-allowed: 1.5 cannot be a map key: a key is a string, keyword, integer, uuid, objectid, date, bytes, symbol or char

Die neun sind die Typen, deren Identität in jeder Sprache exakt und offensichtlich ist. Gleitkommazahlen, Dezimalzahlen und Brüche fallen heraus, weil 1 und 1.0, 0.0 und -0.0, 1.0M und 1.00M, 2/4 und 1/2 verschiedene DXN-Werte sind, die manche Sprachen als einen halten. Zeiten, Zeitpunkte, lokale Uhrzeiten, Dauern und URIs fallen heraus wegen Genauigkeit, Offsets, P1D gegenüber PT24H und URI-Normalisierung. nil und Wahrheitswerte kollidieren in manchen Sprachen mit anderen Schlüsseln — in PHP nil mit "" und true mit 1. Auch IP-Adressen, Bits, Regexes, eigene Tags und Sammlungen sind ausgeschlossen.

Structs

Ein Struct ist ein benannter Datensatz, geschrieben mit Schlüsseln — Feldnamen im Text, in beliebiger Reihenfolge — oder nach Position, mit den Werten in der Reihenfolge, die das Schema festlegt. Mit seinem Schema gelesen, ergeben beide Formen denselben Wert. Eine Zahl in Klammern nach dem Namen ist die Version des Schemas, mit der das Struct geschrieben wurde; siehe Schema-Versionen.

%Point{y: 2, x: 1}
%Point[1, 2]
%Point(2){x: 1, y: 2}

Ein Struct darf mehr Felder tragen, als sein Schema deklariert. In der Form mit Schlüsseln sind sie einfach weitere Einträge. In der positionellen Form folgen sie den Elementen als Einträge: Ein Element ist ein Wert, dem kein => folgt, alle Elemente stehen vorn, und ein Element nach einem Eintrag ist ein Syntaxfehler. In einem Struct benennen name:, :name => und "name" => dasselbe Feld; ein Eintrag mit einem anderen Schlüssel, etwa 3 => :x, ist immer ein zusätzliches Feld.

%User(3)["a" "a@x" nickname: "b", 3 => :x]
%User(3)["a","a@x",nickname:"b",3=>:x]

Ein Struct lässt sich ohne Schema lesen: Ein Leser, der Point nicht kennt, liefert einen undurchsichtigen Wert mit dem Namen, der Version und den Feldern, wie sie geschrieben stehen. Mit einem Schema kann er die Felder prüfen, zwischen beiden Formen umwandeln und den Feldern ihre Typen geben.

Datum und Uhrzeit

FormTypBedeutung
@date "2024-01-01"Datumein Kalenderdatum
@time "12:30:00.5"Zeiteine Uhrzeit, bis auf Nanosekunden
@datetime "2024-01-01T12:30:00Z"datetimeein Zeitpunkt mit seinem Offset: Z für UTC oder ±HH:MM
@local-datetime "2024-01-01T12:30:00"local-datetimeDatum und Uhrzeit ohne Offset — kein Zeitpunkt
@duration "P1Y2M10DT2H30M"Dauereine Dauer nach ISO 8601

Jedes Datum und jede Uhrzeit ist eine ISO-8601-Zeichenkette unter ihrem Tag, und eine Zeichenkette, die nicht die Form hat, die ihr Tag nennt, ist ein Syntaxfehler. Eine Zeit nimmt bis zu neun Nachkommastellen. Ein Zeitpunkt behält den Offset, mit dem er geschrieben wurde; Z ist +00:00, und -00:00, „Offset unbekannt“, wird abgelehnt — ein Wert ohne Offset ist ein local-datetime.

@datetime "2024-01-01T12:30:00+00:00"
@datetime "2024-01-01T12:30:00Z"

Eine Dauer hält Jahre, Monate, Wochen, Tage, Stunden, Minuten und Sekunden als eigene Felder, weil ein Monat oder ein Jahr keine feste Länge hat und sich nicht in eine Sekundenzahl falten lässt.

Kennungen, Adressen, Bytes und Regexes

  • @uuid "…" nimmt 8-4-4-4-12 Hex-Ziffern, in beliebiger Schreibung; geschrieben wird es in Kleinbuchstaben.
  • @objectid "…" ist die 12 Byte lange ObjectId von BSON, geschrieben als 24 Hex-Ziffern.
  • @ip "…" ist eine IPv4- oder IPv6-Adresse oder ein Präfix mit seiner Länge. Ein Präfix, dessen Host-Bits nicht null sind, 10.0.0.1/8, ist ein Syntaxfehler.
  • @uri "…" ist eine URI nach RFC 3986, genau so gespeichert, wie sie geschrieben ist.
  • @bytes "…" sind rohe Binärdaten, im Text als Base64, in .dxnb als reine Bytes.
  • @bits {"…" n} ist eine Folge von n Bits, die keine ganzen Bytes ergibt: Base64-Daten und die Anzahl, die Bits ab dem höchsten Bit des ersten Bytes.
  • @regex "muster" ist ein regulärer Ausdruck in PCRE-Syntax mit den Flags i m s u x f r — ohne Groß-/Kleinschreibung, mehrzeilig, dotall, Unicode, erweitert, erste Zeile, nicht gierig — in einem Kopf, @regex(im) "…".
%{
  id:     @uuid "9b74c989-1e2a-4b17-9b1f-2a6a4a2b6f10"
  doc:    @objectid "507f1f77bcf86cd799439011"
  host:   @ip "192.0.2.1"
  net:    @ip "2001:db8::/32"
  home:   @uri "https://example.com/path"
  avatar: @bytes "SGVsbG8="
  flags:  @bits {"oA==" 3}
  handle: @regex(i) "^[a-z0-9_]{3,20}$"
}

Bits und Bytes sind ein Wertebereich: Eine Bitfolge, deren Anzahl ein Vielfaches von acht ist, sind Bytes und wird auch so geschrieben.

@bits {"AQID" 24}
@bytes "AQID"

Ein Regex-Muster ist eine gewöhnliche Zeichenkette, ein Backslash darin wird also verdoppelt. Die Inline-Modifikatoren von PCRE gehören zum Muster und brauchen keinen Kopf: Die beiden Regexes unten passen auf denselben Text und sind verschiedene Werte, weil ihre Muster verschieden sind. Ein Muster, das PCRE nicht kompiliert, ist ein Syntaxfehler. node-dextrin kann nicht jedes Muster unterscheiden, weil die Engine von JavaScript kein PCRE ist, und liest jedes Muster.

[@regex(im) "^\\d+$" @regex "(?im)^\\d+$"]
@regex "a("
syntax: invalid regex "a(": {~c"missing closing parenthesis", 2}

Eigene Tags

Jeder Tag-Name, der nicht eingebaut ist, ist ein eigenes Tag: ein Wert, verpackt in einen von der Anwendung festgelegten Namen. Ein Leser mit einem Decoder für den Namen macht daraus seinen eigenen Typ; ein Leser ohne behält ihn als undurchsichtigen Wert mit Tag und gibt ihn weiter. Ein Namensraum im Namen verhindert Kollisionen mit fremden Tags.

@my-app/money {1999 :eur}

Eigene Tags passen zu einem einzelnen verpackten Wert. Alles mit echten Feldern ist als Struct besser aufgehoben, das ein Schema prüfen kann.