stdx_tml.h

home

STDX - A lightweight hierarchical data language optimized for fast parsing and tree traversal.
Part of the STDX General Purpose C Library by marciovmf
License: MIT
https://github.com/marciovmf/stdx

Overview

TML (Tree Markup Language) is a minimal indentation-based hierarchical data format designed for:

Human readability
Deterministic parsing
Compact immutable runtime representation
Single-allocation arena-style loading
Fast traversal without dynamic allocations

TML borrows some readability ideas from YAML while intentionally avoiding many of its parsing ambiguities and complexity.

The parser operates in two passes:

Validation + memory counting
Final parse into a single contiguous allocation

The final document is intended primarily for reading/traversal.

How to compile

To compile the implementation define X_IMPL_TML in one source file before including this header.

To customize how this module allocates memory, define X_ARRAY_ALLOC / X_ARRAY_REALLOC / X_ARRAY_FREE before including this header.

Implementation details

Nodes are stored sequentially in document order.
Entries (key:value pairs) are stored sequentially.
Strings are stored in a contiguous string buffer.
Arrays are stored in contiguous typed buffers.
The loaded document is immutable after parsing.

Direct children are linked using:

firstchild + nextsibling

because child nodes are not necessarily contiguous in memory due to depth-first document ordering.

Syntax

COMMENTS

Comments start with '#': # this is a comment

Comments are ignored until the end of the line.

Indentation

Indentation defines hierarchy. The first indented line defines the indentation unit. Valid values are 2 or 4 spaces.

Tabs are invalid for indentation.

Nodes

Nodes are declared using:

  identifier:

Example:

  player:
  transform:

Valid identifiers follow standard C variable naming rules:

  valid_name:
  _another_name:

Invalid:

  0_invalid: # identifier can't start with number

Nodes are hierarchical containers. Nodes are NOT values.

Entries (KEY/VALUE pairs)

Entries use:

  key: value

Example:

  enabled: true
  health: 100
  speed: 3.5

Entries are never anonymous.

Anonymous Nodes

Anonymous child nodes are declared with '-':

  objects:
    - name: "tree"
      enabled: true

Anonymous nodes still have stable child indices inside their parent scope. The first key:value pair must appear on the same line as '-'.

Strings

Strings use double quotes: name: "Player" Strings support escape sequences: n r t " \

Example:

  text: "Hello\nWorld"

Strings may span multiple lines. A string only ends at the matching closing quote.

Example:

  text: "This is a
multiline string."

Indentation inside multiline strings is preserved exactly. Comments inside strings are treated as literal text. Internally strings are stored as views (ptr + size) but are also NUL-terminated for easy interoperability with C APIs.

Arrays

Arrays are homogeneous lists of values declared using comma-separated values:

  values: 1, 2, 3

The type of the array is determined by the type of the first element. Supported array types are i64, f64 and string

Valid:

  values: 1, 2, 3
  points: 1.0, 2.0, 3.0
  names: "a", "b", "c"

Invalid:

  values: 1, 2.0, 3 # arrays do not support mixed types!

Array elements may span multiple lines. If a line ends with ',' the next line is considered part of the same array. Indentation is ignored while continuing multiline arrays. Example:

  vertices:
    1.0, 2.0, 3.0,
    4.0, 5.0, 6.0,
    7.0, 8.0, 9.0

Dot-paths

Every node or entry can be uniquely addressed using a dot path. Example: scene.objects.1.position

Path segments may refer to: named child nodes, child node indices or entry names

Child indices are stable and include BOTH named and anonymous nodes.

Example:

  root:
    foo:
    bar:
    - enabled: true

Child indices:

foo -> 0 bar -> 1 anonymous node -> 2

Basic Usage

Parsing a document:

  TMLParseResult result;

  result = tml_parse(source);

  if (!result.ok)
  {
    printf("Parse error at %u:%u : %s\n",
      result.line,
      result.column,
      result.error);
  }

Accessing nodes:

  TMLNode const* root;
  root = tml_root_node_at(result.document, 0);

Accessing entries:

  i64 health;

  if (tml_node_get_i64(result.document, root, "health", &health))
  {
    printf("%lld\n", (long long)health);
  }

Accessing paths:

  f64 speed;

  if (tml_path_get_f64(
    result.document,
    "player.movement.speed",
    &speed))
  {
    ...
  }

Accessing arrays:

  TMLF64Slice vertices;

  if (tml_path_get_f64_array(
    result.document,
    "mesh.vertices",
    &vertices))
  {
    for (u32 i = 0; i < vertices.count; ++i)
    {
      printf("%f\n", vertices.data[i]);
    }
  }

Releasing memory:

  tml_document_free(result.document);

Macro

X_TML_VERSION_MAJOR

#define X_TML_VERSION_MAJOR 1

Macro

X_TML_VERSION_MINOR

#define X_TML_VERSION_MINOR 0

Macro

X_TML_VERSION_PATCH

#define X_TML_VERSION_PATCH 0

Macro

X_TML_VERSION

#define X_TML_VERSION(X_TML_VERSION_MAJOR *10000+X_TML_VERSION_MINOR *100+X_TML_VERSION_PATCH)

Typedef

f64

typedef double f64;

Struct

TMLString

typedef struct TMLString{
  char const *data;
  u32 size;
}TMLString;

Enum

TMLValueType

typedef enum TMLValueType{
  TML_VALUE_BOOL,
  TML_VALUE_I64,
  TML_VALUE_F64,
  TML_VALUE_STRING,
  TML_VALUE_ARRAY_I64,
  TML_VALUE_ARRAY_F64,
  TML_VALUE_ARRAY_STRING
}TMLValueType;

Struct

TMLArray

typedef struct TMLArray{
  u32 first;
  u32 count;
}TMLArray;

Struct

TMLI64Slice

typedef struct TMLI64Slice{
  i64 const *data;
  u32 count;
}TMLI64Slice;

Struct

TMLF64Slice

typedef struct TMLF64Slice{
  f64 const *data;
  u32 count;
}TMLF64Slice;

Struct

TMLStringSlice

typedef struct TMLStringSlice{
  TMLString const *data;
  u32 count;
}TMLStringSlice;

Struct

TMLEntry

typedef struct TMLEntry{
  TMLString name;
  TMLValueType type;
  u32 parent;
  u32 next_entry;
  union{u8 boolean;i64 integer;f64 number;TMLString string;TMLArray array;};
}TMLEntry;

Struct

TMLNode

typedef struct TMLNode{
  TMLString name;
  u32 parent;
  u32 next_sibling;
  u32 first_child;
  u32 last_child;
  u32 child_count;
  u32 first_entry;
  u32 last_entry;
  u32 entry_count;
}TMLNode;

Struct

TMLDocument

typedef struct TMLDocument{
  void *memory;
  u64 memory_size;
  TMLNode *nodes;
  TMLEntry *entries;
  char *string_data;
  i64 *array_i64;
  f64 *array_f64;
  TMLString *array_string;
  u32 node_count;
  u32 entry_count;
  u32 string_size;
  u32 array_i64_count;
  u32 array_f64_count;
  u32 array_string_count;
  u32 first_root_node;
  u32 last_root_node;
  u32 root_node_count;
}TMLDocument;

Struct

TMLParseResult

typedef struct TMLParseResult{
  int ok;
  char error[256];
  u32 line;
  u32 column;
  TMLDocument *document;
}TMLParseResult;

Function

tml_document_free

Release all memory associated with a parsed TML document.

X_TML_API void tml_document_free(TMLDocument *doc);

Parameters

TMLDocument *doc: Pointer to the document returned by tml_parse(). The document and all associated internal memory become invalid after this call.

Function

tml_parse

Parse a TML document from a UTF-8 source string.

X_TML_API TMLParseResult tml_parse(char const *source);

Parameters

char const *source: Null-terminated source text.

Returns

Parse result structure. On success: - result.ok is non-zero - result.document contains the parsed immutable document On failure: - result.ok is 0 - result.error contains a human-readable error message - result.line and result.column identify the error location The returned document must be released with: tml_document_free()

Function

tml_node_at

Retrieve a node by global node index.

X_TML_API TMLNode const * tml_node_at(
 TMLDocument const *doc,
 u32 index
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
u32 index: Zero-based global node index.

Returns

Pointer to the node, or NULL if the index is invalid. Nodes are stored sequentially in document order.

Function

tml_entry_at

Retrieve an entry by global entry index.

X_TML_API TMLEntry const * tml_entry_at(
 TMLDocument const *doc,
 u32 index
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
u32 index: Zero-based global entry index.

Returns

Pointer to the entry, or NULL if the index is invalid. Entries are stored sequentially in document order.

Function

tml_root_node_at

Retrieve a root node by index.

X_TML_API TMLNode const * tml_root_node_at(
 TMLDocument const *doc,
 u32 index
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
u32 index: Zero-based root node index.

Returns

Pointer to the root node, or NULL if the index is invalid.

Function

tml_node_child_at

Retrieve a direct child node by index.

X_TML_API TMLNode const * tml_node_child_at(
 TMLDocument const *doc,
 TMLNode const *node,
 u32 index
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
TMLNode const *node: Pointer to the parent node.
u32 index: Zero-based child node index.

Returns

Pointer to the child node, or NULL if the index is invalid. Child indices are stable and include both named and anonymous nodes.

Function

tml_node_entry_at

Retrieve a direct entry from a node by index.

X_TML_API TMLEntry const * tml_node_entry_at(
 TMLDocument const *doc,
 TMLNode const *node,
 u32 index
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
TMLNode const *node: Pointer to the parent node.
u32 index: Zero-based entry index.

Returns

Pointer to the entry, or NULL if the index is invalid.

Function

tml_node_find_child

Find a direct child node by name.

X_TML_API TMLNode const * tml_node_find_child(
 TMLDocument const *doc,
 TMLNode const *node,
 char const *name
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
TMLNode const *node: Pointer to the parent node.
char const *name: Child node name.

Returns

Pointer to the matching child node, or NULL if no child matches.

Function

tml_node_find_entry

Find a direct entry by name.

X_TML_API TMLEntry const * tml_node_find_entry(
 TMLDocument const *doc,
 TMLNode const *node,
 char const *name
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
TMLNode const *node: Pointer to the parent node.
char const *name: Entry name.

Returns

Pointer to the matching entry, or NULL if no entry matches.

Function

tml_entry_get_bool

Retrieve a boolean value from an entry.

X_TML_API int tml_entry_get_bool(
 TMLEntry const *entry,
 u8 *out_value
);

Parameters

TMLEntry const *entry: Pointer to the entry.
u8 *out_value: Output boolean value.

Returns

Non-zero on success, 0 if the entry is NULL or not a boolean.

Function

tml_entry_get_i64

Retrieve a signed 64-bit integer value from an entry.

X_TML_API int tml_entry_get_i64(
 TMLEntry const *entry,
 i64 *out_value
);

Parameters

TMLEntry const *entry: Pointer to the entry.
i64 *out_value: Output integer value.

Returns

Non-zero on success, 0 if the entry is NULL or not an integer.

Function

tml_entry_get_f64

Retrieve a double-precision floating point value from an entry.

X_TML_API int tml_entry_get_f64(
 TMLEntry const *entry,
 f64 *out_value
);

Parameters

TMLEntry const *entry: Pointer to the entry.
f64 *out_value: Output floating point value.

Returns

Non-zero on success, 0 if the entry is NULL or not a float.

Function

tml_entry_get_string

Retrieve a string value from an entry.

X_TML_API int tml_entry_get_string(
 TMLEntry const *entry,
 TMLString *out_value
);

Parameters

TMLEntry const *entry: Pointer to the entry.
TMLString *out_value: Output string view.

Returns

Non-zero on success, 0 if the entry is NULL or not a string.

Function

tml_entry_get_i64_array

Retrieve an i64 array slice from an entry.

X_TML_API int tml_entry_get_i64_array(
 TMLDocument const *doc,
 TMLEntry const *entry,
 TMLI64Slice *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
TMLEntry const *entry: Pointer to the entry.
TMLI64Slice *out_value: Output array slice.

Returns

Non-zero on success, 0 if the entry is NULL or not an i64 array.

Function

tml_entry_get_f64_array

Retrieve an f64 array slice from an entry.

X_TML_API int tml_entry_get_f64_array(
 TMLDocument const *doc,
 TMLEntry const *entry,
 TMLF64Slice *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
TMLEntry const *entry: Pointer to the entry.
TMLF64Slice *out_value: Output array slice.

Returns

Non-zero on success, 0 if the entry is NULL or not an f64 array.

Function

tml_entry_get_string_array

Retrieve a string array slice from an entry.

X_TML_API int tml_entry_get_string_array(
 TMLDocument const *doc,
 TMLEntry const *entry,
 TMLStringSlice *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
TMLEntry const *entry: Pointer to the entry.
TMLStringSlice *out_value: Output array slice.

Returns

Non-zero on success, 0 if the entry is NULL or not a string array.

Function

tml_node_get_bool

Retrieve a boolean entry value from a node by name.

X_TML_API int tml_node_get_bool(
 TMLDocument const *doc,
 TMLNode const *node,
 char const *name,
 u8 *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
TMLNode const *node: Pointer to the parent node.
char const *name: Name of the entry.
u8 *out_value: Output boolean value.

Returns

Non-zero on success, 0 if the entry does not exist or is not a boolean.

Function

tml_node_get_i64

Retrieve a signed 64-bit integer entry value from a node by name.

X_TML_API int tml_node_get_i64(
 TMLDocument const *doc,
 TMLNode const *node,
 char const *name,
 i64 *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
TMLNode const *node: Pointer to the parent node.
char const *name: Name of the entry.
i64 *out_value: Output integer value.

Returns

Non-zero on success, 0 if the entry does not exist or is not an integer.

Function

tml_node_get_f64

Retrieve a double-precision floating point entry value from a node by name.

X_TML_API int tml_node_get_f64(
 TMLDocument const *doc,
 TMLNode const *node,
 char const *name,
 f64 *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
TMLNode const *node: Pointer to the parent node.
char const *name: Name of the entry.
f64 *out_value: Output floating point value.

Returns

Non-zero on success, 0 if the entry does not exist or is not a float.

Function

tml_node_get_string

Retrieve a string entry value from a node by name.

X_TML_API int tml_node_get_string(
 TMLDocument const *doc,
 TMLNode const *node,
 char const *name,
 TMLString *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
TMLNode const *node: Pointer to the parent node.
char const *name: Name of the entry.
TMLString *out_value: Output string view.

Returns

Non-zero on success, 0 if the entry does not exist or is not a string.

Function

tml_node_get_i64_array

Retrieve an i64 array entry from a node by name.

X_TML_API int tml_node_get_i64_array(
 TMLDocument const *doc,
 TMLNode const *node,
 char const *name,
 TMLI64Slice *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
TMLNode const *node: Pointer to the parent node.
char const *name: Name of the entry.
TMLI64Slice *out_value: Output array slice.

Returns

Non-zero on success, 0 if the entry does not exist or is not an i64 array.

Function

tml_node_get_f64_array

Retrieve an f64 array entry from a node by name.

X_TML_API int tml_node_get_f64_array(
 TMLDocument const *doc,
 TMLNode const *node,
 char const *name,
 TMLF64Slice *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
TMLNode const *node: Pointer to the parent node.
char const *name: Name of the entry.
TMLF64Slice *out_value: Output array slice.

Returns

Non-zero on success, 0 if the entry does not exist or is not an f64 array.

Function

tml_node_get_string_array

Retrieve a string array entry from a node by name.

X_TML_API int tml_node_get_string_array(
 TMLDocument const *doc,
 TMLNode const *node,
 char const *name,
 TMLStringSlice *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
TMLNode const *node: Pointer to the parent node.
char const *name: Name of the entry.
TMLStringSlice *out_value: Output array slice.

Returns

Non-zero on success, 0 if the entry does not exist or is not a string array.

Function

tml_path_find_node

Find a node using a dot path.

X_TML_API TMLNode const * tml_path_find_node(
 TMLDocument const *doc,
 char const *path
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
char const *path: Dot-separated node path.

Returns

Pointer to the matching node, or NULL if the path does not resolve. Path segments may refer to: - named child nodes - child node indices Example: scene.objects.1

Function

tml_path_find_entry

Find an entry using a dot path.

X_TML_API TMLEntry const * tml_path_find_entry(
 TMLDocument const *doc,
 char const *path
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
char const *path: Dot-separated entry path.

Returns

Pointer to the matching entry, or NULL if the path does not resolve. The final path segment must refer to an entry name. Example: scene.objects.1.position

Function

tml_path_get_bool

Retrieve a boolean value using a dot path.

X_TML_API int tml_path_get_bool(
 TMLDocument const *doc,
 char const *path,
 u8 *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
char const *path: Dot-separated entry path.
u8 *out_value: Output boolean value.

Returns

Non-zero on success, 0 if the path does not resolve or the value is not a boolean.

Function

tml_path_get_i64

Retrieve a signed 64-bit integer value using a dot path.

X_TML_API int tml_path_get_i64(
 TMLDocument const *doc,
 char const *path,
 i64 *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
char const *path: Dot-separated entry path.
i64 *out_value: Output integer value.

Returns

Non-zero on success, 0 if the path does not resolve or the value is not an integer.

Function

tml_path_get_f64

Retrieve a double-precision floating point value using a dot path.

X_TML_API int tml_path_get_f64(
 TMLDocument const *doc,
 char const *path,
 f64 *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
char const *path: Dot-separated entry path.
f64 *out_value: Output floating point value.

Returns

Non-zero on success, 0 if the path does not resolve or the value is not a float.

Function

tml_path_get_string

Retrieve a string value using a dot path.

X_TML_API int tml_path_get_string(
 TMLDocument const *doc,
 char const *path,
 TMLString *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
char const *path: Dot-separated entry path.
TMLString *out_value: Output string view.

Returns

Non-zero on success, 0 if the path does not resolve or the value is not a string.

Function

tml_path_get_i64_array

Retrieve an i64 array using a dot path.

X_TML_API int tml_path_get_i64_array(
 TMLDocument const *doc,
 char const *path,
 TMLI64Slice *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
char const *path: Dot-separated entry path.
TMLI64Slice *out_value: Output array slice.

Returns

Non-zero on success, 0 if the path does not resolve or the value is not an i64 array.

Function

tml_path_get_f64_array

Retrieve an f64 array using a dot path.

X_TML_API int tml_path_get_f64_array(
 TMLDocument const *doc,
 char const *path,
 TMLF64Slice *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
char const *path: Dot-separated entry path.
TMLF64Slice *out_value: Output array slice.

Returns

Non-zero on success, 0 if the path does not resolve or the value is not an f64 array.

Function

tml_path_get_string_array

Retrieve a string array using a dot path.

X_TML_API int tml_path_get_string_array(
 TMLDocument const *doc,
 char const *path,
 TMLStringSlice *out_value
);

Parameters

TMLDocument const *doc: Pointer to the parsed document.
char const *path: Dot-separated entry path.
TMLStringSlice *out_value: Output array slice.

Returns

Non-zero on success, 0 if the path does not resolve or the value is not a string array.

Macro

X_TML_ALLOC

Internal macro for allocating memory. To override how this header allocates memory, define this macro with a different implementation before including this header.

#define X_TML_ALLOC(sz) calloc(1, sz)

Parameters

sz: The size of memory to alloc.

Macro

X_TML_FREE

Internal macro for freeing memory. To override how this header frees memory, define this macro with a different implementation before including this header.

#define X_TML_FREE(p) free(p)

Parameters

p: The address of memory region to free.

Macro

TML_INVALID_INDEX

#define TML_INVALID_INDEX((uint32_t)0xFFFFFFFFu)

Struct

TMLStats

typedef struct TMLStats{
  u32 node_count;
  u32 entry_count;
  u32 string_size;
  u32 array_i64_count;
  u32 array_f64_count;
  u32 array_string_count;
}TMLStats;

Enum

TMLParseMode

typedef enum TMLParseMode{
  TML_PARSE_COUNT,
  TML_PARSE_WRITE
}TMLParseMode;

Struct

TMLScope

typedef struct TMLScope{
  u32 node;
  u32 indent;
}TMLScope;

Struct

TMLParser

typedef struct TMLParser{
  char const *source;
  char const *cursor;
  char const *line_start;
  u32 line;
  u32 indent_unit;
  TMLParseMode mode;
  TMLStats stats;
  TMLDocument *doc;
  u32 node_cursor;
  u32 entry_cursor;
  u32 string_cursor;
  u32 array_i64_cursor;
  u32 array_f64_cursor;
  u32 array_string_cursor;
  TMLScope scopes[256];
  u32 scope_count;
  char error[256];
  u32 error_line;
  u32 error_column;
}TMLParser;

Enum

TMLScalarKind

typedef enum TMLScalarKind{
  TML_SCALAR_BOOL,
  TML_SCALAR_I64,
  TML_SCALAR_F64,
  TML_SCALAR_STRING
}TMLScalarKind;

Struct

TMLScalar

typedef struct TMLScalar{
  TMLScalarKind kind;
  union{u8 boolean;i64 integer;f64 number;TMLString string;};
}TMLScalar;