toml.h File Reference

A TOML parser for C17. More...

#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <das3/defs.h>

Include dependency graph for toml.h:

Go to the source code of this file.

Data Structures
struct	dastoml_datum_t
	Represents a single piece of TOML data. More...
struct	dastoml_result_t
	Result of a TOML parsing operation. More...
struct	dastoml_option_t
	Global options for the TOML parser. More...

Macros
#define	DASTOML_FLAG_INLINED    1
	Bit values for dastoml_datum_t::flag.
#define	DASTOML_FLAG_STDEXPR   2
	table created by a [table] header
#define	DASTOML_FLAG_EXPLICIT   4
	table explicitly defined

Enumerations
enum	dastoml_type_t {   DASTOML_UNKNOWN = 0 , DASTOML_STRING , DASTOML_INT64 , DASTOML_FP64 ,   DASTOML_BOOLEAN , DASTOML_DATE , DASTOML_TIME , DASTOML_DATETIME ,   DASTOML_DATETIMETZ , DASTOML_ARRAY , DASTOML_TABLE }
	Enumeration of TOML data types. More...

Functions
DASTOML_EXTERN DAS_API dastoml_result_t	dastoml_parse (const char *src, int len)
	Parse a TOML document from a string.
DASTOML_EXTERN DAS_API dastoml_result_t	dastoml_parse_named (const char *src, int len, const char *name)
	Parse a TOML document, tagging every datum with a source name.
DASTOML_EXTERN DAS_API dastoml_result_t	dastoml_parse_file (FILE *fp)
	Parse a TOML document from a file pointer.
DASTOML_EXTERN DAS_API dastoml_result_t	dastoml_parse_file_named (FILE *fp, const char *name)
	Parse a TOML document from a file pointer, tagging datums with a name.
DASTOML_EXTERN DAS_API dastoml_result_t	dastoml_parse_file_ex (const char *fname)
	Parse a TOML document from a file path.
DASTOML_EXTERN DAS_API void	dastoml_free (dastoml_result_t result)
	Release resources allocated for a TOML result.
DASTOML_EXTERN DAS_API dastoml_datum_t	dastoml_get (dastoml_datum_t table, const char *key)
	Find a value for a specific key in a TOML table.
DASTOML_EXTERN DAS_API dastoml_datum_t	dastoml_seek (dastoml_datum_t table, const char *multipart_key)
	Locate a value using a multipart-key (e.g., "a.b.c").
DASTOML_EXTERN DAS_API dastoml_result_t	dastoml_merge (const dastoml_result_t *r1, const dastoml_result_t *r2)
	Merge two TOML results.
DASTOML_EXTERN DAS_API bool	dastoml_equiv (const dastoml_result_t *r1, const dastoml_result_t *r2)
	Compare two TOML results for equality.
DASTOML_EXTERN DAS_API dastoml_option_t	dastoml_default_option (void)
	Get the default parser options.
DASTOML_EXTERN DAS_API void	dastoml_set_option (dastoml_option_t opt)
	Set the global parser options.

Detailed Description

A TOML parser for C17.

This library provides a simple and efficient way to parse TOML documents in C. It supports standard TOML features and provides an easy-to-use API for traversing the parsed data.

Macro Definition Documentation

DASTOML_FLAG_INLINED

#define DASTOML_FLAG_INLINED    1

Bit values for dastoml_datum_t::flag.

These record how a datum appeared in the source document. They are set by the parser and are informational for API users. appeared in inline form, e.g. {x = 1} or [1, 2]

Enumeration Type Documentation

dastoml_type_t

enum dastoml_type_t

Enumeration of TOML data types.

Enumerator
DASTOML_UNKNOWN	Unknown or invalid type.
DASTOML_STRING	String type.
DASTOML_INT64	64-bit integer type
DASTOML_FP64	64-bit floating point type
DASTOML_BOOLEAN	Boolean type.
DASTOML_DATE	Local date type.
DASTOML_TIME	Local time type.
DASTOML_DATETIME	Local datetime type.
DASTOML_DATETIMETZ	Offset datetime type.
DASTOML_ARRAY	Array type.
DASTOML_TABLE	Table type.

Function Documentation

dastoml_parse()

DASTOML_EXTERN DAS_API dastoml_result_t dastoml_parse	(	const char *	src,
		int	len
	)

Parse a TOML document from a string.

Parameters

src	A string containing the TOML document.
len	The length of the string. src need not be NUL-terminated; only the first len bytes are read.

Returns

A dastoml_result_t structure. Must be freed with dastoml_free().

dastoml_parse_named()

DASTOML_EXTERN DAS_API dastoml_result_t dastoml_parse_named	(	const char *	src,
		int	len,
		const char *	name
	)

Parse a TOML document, tagging every datum with a source name.

Parameters

src	A string containing the TOML document.
len	The length of the string. src need not be NUL-terminated; only the first len bytes are read.
name	A source name (e.g. filename) copied into the result, or NULL. Every parsed datum's source is set to this name (or NULL).

Returns

A dastoml_result_t structure. Must be freed with dastoml_free().

dastoml_parse_file()

DASTOML_EXTERN DAS_API dastoml_result_t dastoml_parse_file

(

FILE *

fp

)

Parse a TOML document from a file pointer.

Parameters

fp	A pointer to the open file. The caller is responsible for closing it.

Returns

A dastoml_result_t structure. Must be freed with dastoml_free().

Files of 1GB or larger are rejected with a "file is too big" error.

IMPORTANT: you are still responsible to fclose(fp).

dastoml_parse_file_named()

DASTOML_EXTERN DAS_API dastoml_result_t dastoml_parse_file_named	(	FILE *	fp,
		const char *	name
	)

Parse a TOML document from a file pointer, tagging datums with a name.

Parameters

fp	A pointer to the open file. The caller is responsible for closing it.
name	A source name copied into the result, or NULL.

Returns

A dastoml_result_t structure. Must be freed with dastoml_free().

Files of 1GB or larger are rejected with a "file is too big" error.

IMPORTANT: you are still responsible to fclose(fp).

dastoml_parse_file_ex()

DASTOML_EXTERN DAS_API dastoml_result_t dastoml_parse_file_ex

(

const char *

fname

)

Parse a TOML document from a file path.

Parameters

fname

The path to the TOML file.

Returns

A dastoml_result_t structure. Must be freed with dastoml_free().

Files of 1GB or larger are rejected with a "file is too big" error.

dastoml_free()

DASTOML_EXTERN DAS_API void dastoml_free

(

dastoml_result_t

result

)

Release resources allocated for a TOML result.

Parameters

result

The TOML result to free.

dastoml_get()

DASTOML_EXTERN DAS_API dastoml_datum_t dastoml_get	(	dastoml_datum_t	table,
		const char *	key
	)

Find a value for a specific key in a TOML table.

Parameters

table	The TOML table to search in.
key	The key to look for.

Returns

The value associated with the key, or a datum with type DASTOML_UNKNOWN if not found.

dastoml_seek()

DASTOML_EXTERN DAS_API dastoml_datum_t dastoml_seek	(	dastoml_datum_t	table,
		const char *	multipart_key
	)

Locate a value using a multipart-key (e.g., "a.b.c").

Parameters

table	The TOML table to start the search from.
multipart_key	A dot-separated key string. No escape characters allowed. Maximum length is 255 bytes.

Returns

The value found, or a datum with type DASTOML_UNKNOWN if not found.

dastoml_merge()

DASTOML_EXTERN DAS_API dastoml_result_t dastoml_merge	(	const dastoml_result_t *	r1,
		const dastoml_result_t *	r2
	)

Merge two TOML results.

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

Parameters

r1	The base TOML result.
r2	The TOML result containing overrides.

Returns

A new dastoml_result_t representing the merged document.

LOGIC: ret = copy of r1 for each item x in r2: if x is not in ret: set x in ret elif x in ret is NOT of the same type: override elif x in ret is an array of tables: append r2.x to ret.x elif x in ret is a table: merge r2.x to ret.x else: override

dastoml_equiv()

DASTOML_EXTERN DAS_API bool dastoml_equiv	(	const dastoml_result_t *	r1,
		const dastoml_result_t *	r2
	)

Compare two TOML results for equality.

Tables compare as unordered maps (keys matched by name); array element order is significant.

Parameters

r1	The first TOML result.
r2	The second TOML result.

Returns

True if they are equivalent, false otherwise.

dastoml_default_option()

DASTOML_EXTERN DAS_API dastoml_option_t dastoml_default_option

(

void

)

Get the default parser options.

Use this to obtain and initialize a dastoml_option_t structure before customizing it.

Returns

A dastoml_option_t with default values.

dastoml_set_option()

DASTOML_EXTERN DAS_API void dastoml_set_option

(

dastoml_option_t

opt

)

Set the global parser options.

Call this only if you need to override the default behavior.

Parameters

opt	The options to set.