ddn.data.sdl

SDL (Simple Declarative Language) Parser and Writer

This module provides complete SDL support including:

  • Parsing SDL documents into CDM structures
  • Preserving comments, formatting, and source locations
  • Serializing CDM documents back to SDL
  • Support for all 13 SDL literal types
  • Namespace support for tags and attributes
  • Anonymous tags and line continuation
  • Four comment styles (hash, double-slash, block, double-dash)

SDL is a tag-based configuration language with rich literal types including dates, timespans, and binary data.

Copyright

Copyright (c) 2024, DDN Project Authors

License

MIT

Examples

import ddn.data.sdl;

// Parse SDL configuration
auto doc = parseSdlCdm(`
   server "main" host="localhost" port=8080 {
       ssl enabled=true
   }
`);

// Access tag data
assert(doc.root.nodeName == "server");
assert(doc.root.tagValues[0].as!string == "main");
assert(doc.root.getAttribute("host").as!string == "localhost");

// Serialize back to SDL
string output = toSdl(doc);
enum SdlTokenKind
struct SdlCdmParser SdlError SdlLexer SdlPolicy SdlToken SdlWriteOptions
fn collectTrailingComment decodeBase64 encodeBase64 formatDate formatDateTime formatDuration formatTime indent isAttributeStart parseAnonymousTag parseAttribute parseBool parseChildrenBlock parseDate parseDateTime parseDocument parseDocumentCdm parseDocumentVar parseDouble parseLiteral parseLong parseNamedTag parseSdlCdm parseSdlCdmWithBuilder parseTag parseTimeSpan parseValuesAndAttributes toSdl writeComment writeInlineComment writeLiteral writeStringLiteral writeTag

Types 7

structSdlError

Error information for SDL parsing failures.

Fields
size_t line
size_t column
string message
string source
Methods
string toString() const @safeFormat error as human-readable string.
structSdlPolicy

Policy options for SDL parsing.

Fields
size_t maxDepth
structSdlWriteOptions

Options for SDL serialization.

Fields
bool prettyPrint
uint indentWidth
bool preserveRawText
enumSdlTokenKind : ubyte

SDL token kinds produced by the lexer.

UNKNOWNInvalid/unrecognised input
EOFEnd of input
LBRACE{
RBRACE}
SEMICOLON;
NEWLINEEnd of line (tag statement terminator)
EQUALS=
COLON: (namespace or in datetime literal)
LINE_COMMENT_HASH# ...
LINE_COMMENT_DSLASH// ...
LINE_COMMENT_DASH-- ...
BLOCK_COMMENT/ ... /
STRING"..." double-quoted string
BACKTICK`...` backtick/raw string
CHARACTER'x' single character
INTEGER123, 123L
FLOAT3.14, 3.14F, 3.14d, 123.44BD
BOOLEANtrue, false, on, off
DATE2005/12/05
DATETIME2005/12/05 14:12:23.345-ZONE
TIMESPAN12:14:42, 12:14:42.532
BINARY[base64...]
NULL_LITnull
IDENTIFIERmyName, my-name, com.example.foo
structSdlToken

A single SDL token produced by the lexer.

Fields
SdlTokenKind kind
string value
string rawText
size_t line
size_t column
size_t offset
private structSdlLexer

SDL lexer that tokenises input on demand.

Supports all SDL lexical constructs including:

  • Four comment styles (hash, double-slash, block, double-dash)
  • String literals (double-quoted and backtick)
  • Character literals
  • Numeric literals (integer, float, double, decimal)
  • Boolean literals (true, false, on, off)
  • Date, datetime, and timespan literals
  • Binary literals (base64 in [ ])
  • Null literal
  • Identifiers with namespace prefix
  • Line continuation (backslash-newline)
  • Semicolon tag separator
Fields
const(char)[] input
size_t pos
size_t line
size_t column
Methods
SdlToken nextToken() @safeAdvance to the next token.
private void advance() pure nothrow @nogc @safeConsumes one byte, updating line/column tracking.
private void skipWhitespace() @safeSkips spaces and tabs, and transparently consumes line continuations; stops at newlines, which are emitted as NEWLINE tokens by nextToken.
private SdlToken readIdentifier() @safeReads an identifier or keyword, classifying boolean/null keywords.
private SdlToken readString() @safeReads a double-quoted string, decoding escapes and collapsing line continuations.
private SdlToken readBacktickString() @safeReads a raw backtick string (escapes disabled, newlines allowed).
private SdlToken readCharacter() @safeReads a character literal `'x'` (single content character or escape).
private SdlToken readNumber() @safeReads a numeric literal, dispatching to date/datetime/timespan readers when the shape calls for it and applying integer/float suffixes.
private SdlToken readDateOrDateTime(size_t startPos, size_t startLine, size_t startCol, size_t startOffset) @safeReads a date or datetime literal starting at the first '/'.
private SdlToken readTimeSpan(size_t startPos, size_t startLine, size_t startCol, size_t startOffset) @safeReads a timespan literal (hh:mm[:ss][.frac] or Nd:hh:mm:ss) starting at the first ':'.
private SdlToken readBinary() @safeReads a base64 binary literal delimited by brackets.
private SdlToken readLineComment(SdlTokenKind kind) @safeReads a line comment up to (not including) the newline.
private SdlToken readBlockComment() @safeReads a block comment delimited by slash-star pairs.
private bool isDigit(char c) const pure nothrow @nogc @safeChecks whether a byte is an ASCII digit.
private bool isIdentStart(char c) const pure nothrow @nogc @safeChecks whether a byte can start an identifier (ASCII letters, underscore, or any UTF-8 lead/continuation byte).
private bool isIdentContinue(char c) const pure nothrow @nogc @safeChecks whether a byte can continue an identifier.
Constructors
this(const(char)[] input)
private structSdlCdmParser(Builder = CdmBuilder)

Internal SDL CDM parser.

Consumes tokens from an SdlLexer and produces CdmNode trees. Handles all SDL grammar constructs including tags, values, attributes, namespaces, anonymous tags, and comments.

Fields
SdlLexer lexer
SdlPolicy policy
SdlError * err
string source
size_t depth
SdlToken current
CdmComment[] pendingComments
Builder builder
Methods
void advance() @safeAdvances to the next non-comment token, accumulating any comment tokens into pendingComments.
bool isCommentToken(SdlTokenKind kind) pure nothrow @nogc @safeChecks whether a token kind is one of the four comment kinds.
CdmComment makeComment(SdlToken tok) @safeConverts a comment token into a CdmComment with style and location.
CdmComment[] consumePendingComments() @safeDetaches and returns the accumulated comments.
bool fail(string msg) @safeRecords a parse failure into the error sink.
Constructors
this(const(char)[] input, SdlPolicy policy, SdlError * err, string source)Constructs a parser and reads the first token.

Functions 36

private fnbool parseDocument(Builder)(ref SdlCdmParser!Builder p) @safeParse a complete SDL document via the builder.
private fnbool parseDocumentCdm(ref SdlCdmParser!CdmBuilder p) @safeCdmBuilder document parsing: uses anonymous tag wrapper for multiple tags.
private fnbool parseDocumentVar(ref SdlCdmParser!VarBuilder p) @safeVarBuilder document parsing: top-level tags become object members.
private fnbool parseTag(Builder)(ref SdlCdmParser!Builder p, CdmComment[] leadingComments) @safeParse a single SDL tag via the builder.
private fnbool parseNamedTag(Builder)(ref SdlCdmParser!Builder p, CdmComment[] leadingComments, CdmLocation loc) @safeParse a named tag with optional namespace via the builder.
private fnbool parseAnonymousTag(Builder)(ref SdlCdmParser!Builder p, CdmComment[] leadingComments, CdmLocation loc) @safeParse an anonymous tag (no name, at least one value; all values on the same logical line belong to the same tag).
private fnbool parseValuesAndAttributes(Builder)(ref SdlCdmParser!Builder p) @safeParse values and attributes for a named tag via the builder.
private fnbool parseAttribute(Builder)(ref SdlCdmParser!Builder p) @safeParse an attribute via the builder: [namespace ':'] name '=' value
private fnbool parseChildrenBlock(Builder)(ref SdlCdmParser!Builder p) @safeParse a children block: '{' (comment | tag)* '}' via the builder.
private fnbool isAttributeStart(Builder)(ref SdlCdmParser!Builder p) @safeCheck if the current position starts an attribute ([namespace ':'] name '=' literal).
private fnbool parseLiteral(Builder)(ref SdlCdmParser!Builder p) @safeParse any SDL literal via the builder.
private fnvoid collectTrailingComment(Builder)(ref SdlCdmParser!Builder p, size_t endLine) @safeCollect a trailing comment that sits on the same line the tag statement ended on (after the last value or after the closing brace).
private fnlong parseLong(const(char)[] raw) pure @safeParse an SDL integer literal to long.
private fndouble parseDouble(const(char)[] raw) pure @safeParse an SDL float/double/decimal literal to double.
private fnbool parseBool(const(char)[] raw) pure nothrow @nogc @safeParse an SDL boolean literal.
private fnDate parseDate(const(char)[] raw) pure @safeParse an SDL date literal (yyyy/mm/dd) to std.datetime.date.Date.
private fnDateTime parseDateTime(const(char)[] raw) pure @safeParse an SDL datetime literal to std.datetime.date.DateTime.
private fnDuration parseTimeSpan(const(char)[] raw) pure @safeParse an SDL timespan literal to core.time.Duration.
private fnimmutable(ubyte)[] decodeBase64(const(char)[] base64) @safeDecode a base64 string to immutable ubyte[].
fnauto parseSdlCdm(Builder = CdmBuilder)(const(char)[] input, string source = "") @safeParse SDL text into a CDM document.
fnauto parseSdlCdm(Builder = CdmBuilder)(File file) @safeParse SDL from an open file handle.
fnbool parseSdlCdm(out CdmDocument doc, const(char)[] input, out SdlError err, string source = "", SdlPolicy policy = SdlPolicy.init) @trustedNon-throwing parse variant.
private fnbool parseSdlCdmWithBuilder(Builder)(ref Builder.Result result, const(char)[] input, ref SdlError err, string source = "", SdlPolicy policy = SdlPolicy.init) @trustedInternal templated parse function shared by all builders.
fnstring toSdl(const ref CdmDocument doc, SdlWriteOptions opts = SdlWriteOptions.init) @safeSerialize a CDM document to SDL text.
fnvoid toSdl(Out)(const ref CdmDocument doc, ref Out output, SdlWriteOptions opts = SdlWriteOptions.init) @safeOutput range variant of toSdl().
private fnvoid writeTag(Out)(ref Out buf, const ref CdmNode node, uint depth, const ref SdlWriteOptions opts) @safeWrite a tag node as SDL text.
private fnvoid writeLiteral(Out)(ref Out buf, const ref CdmNode node, const ref SdlWriteOptions opts) @safeWrite a literal value node as SDL text.
private fnvoid writeStringLiteral(Out)(ref Out buf, const(char)[] s, CdmFormat.QuoteStyle style) @safeWrite a string literal with appropriate quoting.
private fnvoid writeComment(Out)(ref Out buf, const ref CdmComment c, uint depth, const ref SdlWriteOptions opts) @safeWrite a comment with proper SDL formatting.
private fnvoid writeInlineComment(Out)(ref Out buf, const ref CdmComment c) @safeWrite an inline (trailing) comment.
private fnvoid indent(Out)(ref Out buf, uint depth, const ref SdlWriteOptions opts) pure @safeWrite indentation spaces.
private fnstring formatDate(Date d) pure @safeFormat a Date as SDL date literal (yyyy/mm/dd).
private fnstring formatTime(TimeOfDay t) pure @safeFormat a TimeOfDay as SDL time literal (hh:mm:ss).
private fnstring formatDateTime(DateTime dt) pure @safeFormat a DateTime as SDL datetime literal (yyyy/mm/dd hh:mm:ss).
private fnstring formatDuration(Duration d) pure @safeFormat a Duration as SDL timespan literal.
private fnstring encodeBase64(const(ubyte)[] data) @safeEncode ubyte[] as base64 string.