tomlc17 API Reference

Overview

#include "tomlc17.h"

The typical usage pattern:

1. Call toml_parse(), toml_parse_file(), or toml_parse_file_ex() to parse a document.
2. Check result.ok. On failure, result.errmsg contains a description.
3. Navigate the document tree using toml_get() or toml_seek().
4. Call toml_free() when done.

Important: toml_free() must be called on every result returned by a parse or merge function, even if result.ok is false.

All strings and data returned from the API are owned by the toml_result_t and remain valid until toml_free() is called on that result.

---

Types

toml_type_t

typedef enum {
  TOML_UNKNOWN = 0,
  TOML_STRING,
  TOML_INT64,
  TOML_FP64,
  TOML_BOOLEAN,
  TOML_DATE,
  TOML_TIME,
  TOML_DATETIME,
  TOML_DATETIMETZ,
  TOML_ARRAY,
  TOML_TABLE,
} toml_type_t;

The type tag carried by every toml_datum_t. A datum with type == TOML_UNKNOWN means "not found" or "invalid".

---

toml_datum_t

A node in the parsed document tree.

struct toml_datum_t {
  toml_type_t type;
  uint32_t    flag;   // internal
  int         lineno; // 1-based source line, 0 when synthesized
  int         colno;  // 1-based source column, 0 when synthesized
  const char *source; // source name (e.g. filename), NULL when not provided
  union {
    const char *s;           // TOML_STRING: shorthand for str.ptr
    struct {
      const char *ptr;       // NUL-terminated string
      int len;               // length excluding the NUL terminator
    } str;                   // TOML_STRING
    int64_t int64;           // TOML_INT64
    double  fp64;            // TOML_FP64
    bool    boolean;         // TOML_BOOLEAN
    struct {
      int16_t year, month, day;
      int16_t hour, minute, second;
      int32_t usec;          // microseconds
      int16_t tz;            // timezone offset in minutes
    } ts;                    // TOML_DATE, TOML_TIME, TOML_DATETIME, TOML_DATETIMETZ
    struct {
      int32_t       size;    // number of elements
      toml_datum_t *elem;    // elem[0..size-1]
    } arr;                   // TOML_ARRAY
    struct {
      int32_t        size;   // number of key/value pairs
      const char   **key;    // key[0..size-1]  (NUL-terminated strings)
      int           *len;    // len[0..size-1]  (key lengths)
      toml_datum_t  *value;  // value[0..size-1]
    } tab;                   // TOML_TABLE
  } u;
};

Fields:

• type: The type of this datum (see toml_type_t).
• flag: Internal use only. Do not read or modify.
• lineno: 1-based line number in the source document where this value appeared. Set to 0 for synthesized values.
• colno: 1-based column number in the source document where this value appeared. Set to 0 for synthesized values.
• source: Name of the document this value came from (e.g. the filename), or NULL if no name was supplied. Copied into the result and preserved across toml_merge, so merged documents retain each entry's origin.
• u: Union containing the actual value based on the type.

Accessing values by type:

type	field(s) to read
TOML_STRING	u.s or u.str.ptr / u.str.len
TOML_INT64	u.int64
TOML_FP64	u.fp64
TOML_BOOLEAN	u.boolean
TOML_DATE	u.ts.year, .month, .day
TOML_TIME	u.ts.hour, .minute, .second, .usec
TOML_DATETIME	all u.ts fields except .tz
TOML_DATETIMETZ	all u.ts fields
TOML_ARRAY	u.arr.size, u.arr.elem[]
TOML_TABLE	u.tab.size, u.tab.key[], u.tab.value[]

---

toml_result_t

Returned by every parse function.

struct toml_result_t {
  bool         ok;          // true on success
  toml_datum_t toptab;      // the top-level table; valid when ok == true
  char         errmsg[200]; // error description; valid when ok == false
  void        *__internal;  // internal use only; do not access
};

---

toml_option_t

Global options. See toml_set_option().

struct toml_option_t {
  bool check_utf8;                          // validate UTF-8; default: false
  void *(*mem_realloc)(void *ptr, size_t); // default: realloc()
  void (*mem_free)(void *ptr);             // default: free()
};

---

Parsing

toml_parse

toml_result_t toml_parse(const char *src, int len);

Parse a TOML document from a NUL-terminated string. len is the length of src excluding the NUL terminator. The result must be released with toml_free().

---

toml_parse_file

toml_result_t toml_parse_file(FILE *fp);

Parse a TOML document from an open file handle. The caller is responsible for calling fclose(fp). The result must be released with toml_free().

---

toml_parse_file_ex

toml_result_t toml_parse_file_ex(const char *fname);

Parse a TOML document from a file path. Opens and closes the file internally. Every parsed datum's source is set to fname. The result must be released with toml_free().

---

toml_parse_named

toml_result_t toml_parse_named(const char *src, int len, const char *name);

Like toml_parse, but tags every parsed datum's source with name (copied into the result; pass NULL for no name). The name survives toml_merge.

---

toml_parse_file_named

toml_result_t toml_parse_file_named(FILE *fp, const char *name);

Like toml_parse_file, but tags datums with name. toml_parse_file_ex automatically uses the file path as the name.

---

Releasing

toml_free

void toml_free(toml_result_t result);

Release all memory associated with a toml_result_t. Must be called on every result returned by a parse or merge function, regardless of whether parsing succeeded. All pointers obtained from this result become invalid after this call.

---

Querying

toml_get

toml_datum_t toml_get(toml_datum_t table, const char *key);

Look up a single key in a table. Returns a datum with type == TOML_UNKNOWN if the key is not found or if table is not a TOML_TABLE.

---

toml_seek

toml_datum_t toml_seek(toml_datum_t table, const char *multipart_key);

Look up a dot-separated key path starting from table. For example, "server.host" is equivalent to calling toml_get twice.

Constraints:

• Keys must not contain escape characters.
• The total length of multipart_key must not exceed 255 bytes.

Returns a datum with type == TOML_UNKNOWN if any component is not found.

---

Merging and Comparing

toml_merge

toml_result_t toml_merge(const toml_result_t *r1, const toml_result_t *r2);

Produce a new result that is r1 overridden by r2. Merge rules:

• Key in r2 not in r1 → added to result.
• Key in r2 with a different type than r1 → overrides r1.
• Key is an array of tables → r2's entries are appended to r1's.
• Key is a table → r2's sub-keys are recursively merged into r1's.
• Otherwise → r2 overrides r1.

All three results (r1, r2, and the returned result) must each be freed with toml_free() independently.

---

toml_equiv

bool toml_equiv(const toml_result_t *r1, const toml_result_t *r2);

Return true if the two results represent identical documents. Table key order and array element order are both significant.

---

Options

toml_default_option

toml_option_t toml_default_option(void);

Return the current default options. Use this to obtain a baseline before modifying individual fields.

---

toml_set_option

void toml_set_option(toml_option_t opt);

Replace the global options. This affects all subsequent parse calls. Not thread-safe; call once during program initialization.

Example — custom allocator:

toml_option_t opt = toml_default_option();
opt.mem_realloc = my_realloc;
opt.mem_free    = my_free;
toml_set_option(opt);

---

Deprecated

toml_table_find

toml_datum_t toml_table_find(toml_datum_t table, const char *key);

Alias for toml_get(). Use toml_get() instead.