322 lines
8.2 KiB
Markdown
322 lines
8.2 KiB
Markdown
# tomlc17 API Reference
|
|
|
|
## Overview
|
|
|
|
```c
|
|
#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`
|
|
|
|
```c
|
|
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.
|
|
|
|
```c
|
|
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.
|
|
|
|
```c
|
|
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()`](#toml_set_option).
|
|
|
|
```c
|
|
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`
|
|
|
|
```c
|
|
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`
|
|
|
|
```c
|
|
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`
|
|
|
|
```c
|
|
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`
|
|
|
|
```c
|
|
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`
|
|
|
|
```c
|
|
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`
|
|
|
|
```c
|
|
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`
|
|
|
|
```c
|
|
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`
|
|
|
|
```c
|
|
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`
|
|
|
|
```c
|
|
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`
|
|
|
|
```c
|
|
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`
|
|
|
|
```c
|
|
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`
|
|
|
|
```c
|
|
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:**
|
|
|
|
```c
|
|
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`
|
|
|
|
```c
|
|
toml_datum_t toml_table_find(toml_datum_t table, const char *key);
|
|
```
|
|
|
|
Alias for `toml_get()`. Use `toml_get()` instead.
|