CYAML
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
cyaml.h File Reference

CYAML library public header. More...

#include <stdarg.h>
#include <stdint.h>
#include <stddef.h>
Include dependency graph for cyaml.h:

Go to the source code of this file.

Data Structures

struct  cyaml_strval
 
struct  cyaml_bitdef
 
struct  cyaml_schema_value
 
struct  cyaml_schema_field
 
struct  cyaml_config
 

Macros

#define CYAML_VALUE_INT(_flags, _type)
 
#define CYAML_FIELD_INT(_key, _flags, _structure, _member)
 
#define CYAML_FIELD_INT_PTR(_key, _flags, _structure, _member)
 
#define CYAML_VALUE_UINT(_flags, _type)
 
#define CYAML_FIELD_UINT(_key, _flags, _structure, _member)
 
#define CYAML_FIELD_UINT_PTR(_key, _flags, _structure, _member)
 
#define CYAML_VALUE_BOOL(_flags, _type)
 
#define CYAML_FIELD_BOOL(_key, _flags, _structure, _member)
 
#define CYAML_FIELD_BOOL_PTR(_key, _flags, _structure, _member)
 
#define CYAML_VALUE_ENUM(_flags, _type, _strings, _strings_count)
 
#define CYAML_FIELD_ENUM(_key, _flags, _structure, _member, _strings, _strings_count)
 
#define CYAML_FIELD_ENUM_PTR(_key, _flags, _structure, _member, _strings, _strings_count)
 
#define CYAML_VALUE_FLAGS(_flags, _type, _strings, _strings_count)
 
#define CYAML_FIELD_FLAGS(_key, _flags, _structure, _member, _strings, _strings_count)
 
#define CYAML_FIELD_FLAGS_PTR(_key, _flags, _structure, _member, _strings, _strings_count)
 
#define CYAML_VALUE_BITFIELD(_flags, _type, _bitvals, _bitvals_count)
 
#define CYAML_FIELD_BITFIELD(_key, _flags, _structure, _member, _bitvals, _bitvals_count)
 
#define CYAML_FIELD_BITFIELD_PTR(_key, _flags, _structure, _member, _bitvals, _bitvals_count)
 
#define CYAML_VALUE_FLOAT(_flags, _type)
 
#define CYAML_FIELD_FLOAT(_key, _flags, _structure, _member)
 
#define CYAML_FIELD_FLOAT_PTR(_key, _flags, _structure, _member)
 
#define CYAML_VALUE_STRING(_flags, _type, _min, _max)
 
#define CYAML_FIELD_STRING(_key, _flags, _structure, _member, _min)
 
#define CYAML_FIELD_STRING_PTR(_key, _flags, _structure, _member, _min, _max)
 
#define CYAML_VALUE_MAPPING(_flags, _type, _fields)
 
#define CYAML_FIELD_MAPPING(_key, _flags, _structure, _member, _fields)
 
#define CYAML_FIELD_MAPPING_PTR(_key, _flags, _structure, _member, _fields)
 
#define CYAML_VALUE_SEQUENCE(_flags, _type, _entry, _min, _max)
 
#define CYAML_FIELD_SEQUENCE(_key, _flags, _structure, _member, _entry, _min, _max)
 
#define CYAML_FIELD_SEQUENCE_COUNT(_key, _flags, _structure, _member, _count, _entry, _min, _max)
 
#define CYAML_VALUE_SEQUENCE_FIXED(_flags, _type, _entry, _count)
 
#define CYAML_FIELD_SEQUENCE_FIXED(_key, _flags, _structure, _member, _entry, _count)
 
#define CYAML_FIELD_IGNORE(_key, _flags)
 
#define CYAML_FIELD_END   { .key = NULL }
 
#define CYAML_UNLIMITED   0xffffffff
 
#define CYAML_ARRAY_LEN(_a)   ((sizeof(_a)) / (sizeof(_a[0])))
 

Typedefs

typedef enum cyaml_type cyaml_type_e
 
typedef enum cyaml_flag cyaml_flag_e
 
typedef struct cyaml_strval cyaml_strval_t
 
typedef struct cyaml_bitdef cyaml_bitdef_t
 
typedef struct cyaml_schema_value cyaml_schema_value_t
 
typedef struct cyaml_schema_field cyaml_schema_field_t
 
typedef enum cyaml_cfg_flags cyaml_cfg_flags_t
 
typedef enum cyaml_err cyaml_err_t
 
typedef void cyaml_data_t
 
typedef enum cyaml_log_e cyaml_log_t
 
typedef void(* cyaml_log_fn_t) (cyaml_log_t level, void *ctx, const char *fmt, va_list args)
 
typedef void *(* cyaml_mem_fn_t) (void *ctx, void *ptr, size_t size)
 
typedef struct cyaml_config cyaml_config_t
 

Enumerations

enum  cyaml_type {
  CYAML_INT , CYAML_UINT , CYAML_BOOL , CYAML_ENUM ,
  CYAML_FLAGS , CYAML_FLOAT , CYAML_STRING , CYAML_MAPPING ,
  CYAML_BITFIELD , CYAML_SEQUENCE , CYAML_SEQUENCE_FIXED , CYAML_IGNORE ,
  CYAML__TYPE_COUNT
}
 
enum  cyaml_flag {
  CYAML_FLAG_DEFAULT = 0 , CYAML_FLAG_OPTIONAL = (1 << 0) , CYAML_FLAG_POINTER = (1 << 1) , CYAML_FLAG_POINTER_NULL = (1 << 2) | CYAML_FLAG_POINTER ,
  CYAML_FLAG_POINTER_NULL_STR = (1 << 3) | CYAML_FLAG_POINTER_NULL , CYAML_FLAG_STRICT = (1 << 4) , CYAML_FLAG_BLOCK = (1 << 5) , CYAML_FLAG_FLOW = (1 << 6) ,
  CYAML_FLAG_CASE_SENSITIVE = (1 << 7) , CYAML_FLAG_CASE_INSENSITIVE = (1 << 8) , CYAML_FLAG_SCALAR_PLAIN = (1 << 9) , CYAML_FLAG_SCALAR_FOLDED = (1 << 10) ,
  CYAML_FLAG_SCALAR_LITERAL = (1 << 11) , CYAML_FLAG_SCALAR_QUOTE_SINGLE = (1 << 12) , CYAML_FLAG_SCALAR_QUOTE_DOUBLE = (1 << 13)
}
 
enum  cyaml_cfg_flags {
  CYAML_CFG_DEFAULT = 0 , CYAML_CFG_IGNORE_UNKNOWN_KEYS = (1 << 0) , CYAML_CFG_STYLE_BLOCK = (1 << 1) , CYAML_CFG_STYLE_FLOW = (1 << 2) ,
  CYAML_CFG_DOCUMENT_DELIM = (1 << 3) , CYAML_CFG_CASE_INSENSITIVE = (1 << 4) , CYAML_CFG_NO_ALIAS = (1 << 5) , CYAML_CFG_IGNORED_KEY_WARNING = (1 << 6)
}
 
enum  cyaml_err {
  CYAML_OK , CYAML_ERR_OOM , CYAML_ERR_ALIAS , CYAML_ERR_FILE_OPEN ,
  CYAML_ERR_INVALID_KEY , CYAML_ERR_INVALID_VALUE , CYAML_ERR_INVALID_ALIAS , CYAML_ERR_INTERNAL_ERROR ,
  CYAML_ERR_UNEXPECTED_EVENT , CYAML_ERR_STRING_LENGTH_MIN , CYAML_ERR_STRING_LENGTH_MAX , CYAML_ERR_INVALID_DATA_SIZE ,
  CYAML_ERR_TOP_LEVEL_NON_PTR , CYAML_ERR_BAD_TYPE_IN_SCHEMA , CYAML_ERR_BAD_MIN_MAX_SCHEMA , CYAML_ERR_BAD_PARAM_SEQ_COUNT ,
  CYAML_ERR_BAD_PARAM_NULL_DATA , CYAML_ERR_BAD_BITVAL_IN_SCHEMA , CYAML_ERR_SEQUENCE_ENTRIES_MIN , CYAML_ERR_SEQUENCE_ENTRIES_MAX ,
  CYAML_ERR_SEQUENCE_FIXED_COUNT , CYAML_ERR_SEQUENCE_IN_SEQUENCE , CYAML_ERR_MAPPING_FIELD_MISSING , CYAML_ERR_BAD_CONFIG_NULL_MEMFN ,
  CYAML_ERR_BAD_PARAM_NULL_CONFIG , CYAML_ERR_BAD_PARAM_NULL_SCHEMA , CYAML_ERR_LIBYAML_EMITTER_INIT , CYAML_ERR_LIBYAML_PARSER_INIT ,
  CYAML_ERR_LIBYAML_EVENT_INIT , CYAML_ERR_LIBYAML_EMITTER , CYAML_ERR_LIBYAML_PARSER , CYAML_ERR__COUNT
}
 
enum  cyaml_log_e {
  CYAML_LOG_DEBUG , CYAML_LOG_INFO , CYAML_LOG_NOTICE , CYAML_LOG_WARNING ,
  CYAML_LOG_ERROR
}
 

Functions

void cyaml_log (cyaml_log_t level, void *ctx, const char *fmt, va_list args)
 
void * cyaml_mem (void *ctx, void *ptr, size_t size)
 
cyaml_err_t cyaml_load_file (const char *path, const cyaml_config_t *config, const cyaml_schema_value_t *schema, cyaml_data_t **data_out, unsigned *seq_count_out)
 
cyaml_err_t cyaml_load_data (const uint8_t *input, size_t input_len, const cyaml_config_t *config, const cyaml_schema_value_t *schema, cyaml_data_t **data_out, unsigned *seq_count_out)
 
cyaml_err_t cyaml_save_file (const char *path, const cyaml_config_t *config, const cyaml_schema_value_t *schema, const cyaml_data_t *data, unsigned seq_count)
 
cyaml_err_t cyaml_save_data (char **output, size_t *len, const cyaml_config_t *config, const cyaml_schema_value_t *schema, const cyaml_data_t *data, unsigned seq_count)
 
cyaml_err_t cyaml_free (const cyaml_config_t *config, const cyaml_schema_value_t *schema, cyaml_data_t *data, unsigned seq_count)
 
const char * cyaml_strerror (cyaml_err_t err)
 

Variables

const char * cyaml_version_str
 
const uint32_t cyaml_version
 

Detailed Description

CYAML library public header.

CYAML is a C library for parsing and serialising structured YAML documents.

Macro Definition Documentation

◆ CYAML_ARRAY_LEN

#define CYAML_ARRAY_LEN (   _a)    ((sizeof(_a)) / (sizeof(_a[0])))

Helper macro for counting array elements.

Note
Don't use this macro on pointers.
Parameters
[in]_aA C array.
Returns
Array element count.

◆ CYAML_FIELD_BITFIELD

#define CYAML_FIELD_BITFIELD (   _key,
  _flags,
  _structure,
  _member,
  _bitvals,
  _bitvals_count 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_BITFIELD(((_flags) & (~CYAML_FLAG_POINTER)), \
(((_structure *)NULL)->_member), \
_bitvals, _bitvals_count), \
}, \
}
@ CYAML_FLAG_POINTER
Definition cyaml.h:148

Mapping schema helper macro for keys with CYAML_BITFIELD type.

Use this for bit field types contained in structs.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.
[in]_bitvalsArray of bit field value data for the bit field.
[in]_bitvals_countNumber of entries in _bitvals.

◆ CYAML_FIELD_BITFIELD_PTR

#define CYAML_FIELD_BITFIELD_PTR (   _key,
  _flags,
  _structure,
  _member,
  _bitvals,
  _bitvals_count 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_BITFIELD(((_flags) | CYAML_FLAG_POINTER), \
(*(((_structure *)NULL)->_member)), \
_bitvals, _bitvals_count), \
}, \
}

Mapping schema helper macro for keys with CYAML_BITFIELD type.

Use this for pointers to bit field types.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.
[in]_bitvalsArray of bit field value data for the bit field.
[in]_bitvals_countNumber of entries in _bitvals.

◆ CYAML_FIELD_BOOL

#define CYAML_FIELD_BOOL (   _key,
  _flags,
  _structure,
  _member 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_BOOL(((_flags) & (~CYAML_FLAG_POINTER)), \
(((_structure *)NULL)->_member)), \
}, \
}

Mapping schema helper macro for keys with CYAML_BOOL type.

Use this for boolean types contained in structs.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.

◆ CYAML_FIELD_BOOL_PTR

#define CYAML_FIELD_BOOL_PTR (   _key,
  _flags,
  _structure,
  _member 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_BOOL(((_flags) | CYAML_FLAG_POINTER), \
(*(((_structure *)NULL)->_member))), \
}, \
}

Mapping schema helper macro for keys with CYAML_BOOL type.

Use this for pointers to boolean types.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.

◆ CYAML_FIELD_END

#define CYAML_FIELD_END   { .key = NULL }

Mapping schema helper macro for terminating an array of mapping fields.

CYAML mapping schemas are formed from an array of cyaml_schema_field entries, and an entry with a NULL key indicates the end of the array.

◆ CYAML_FIELD_ENUM

#define CYAML_FIELD_ENUM (   _key,
  _flags,
  _structure,
  _member,
  _strings,
  _strings_count 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_ENUM(((_flags) & (~CYAML_FLAG_POINTER)), \
(((_structure *)NULL)->_member), \
_strings, _strings_count), \
}, \
}

Mapping schema helper macro for keys with CYAML_ENUM type.

Use this for enumerated types contained in structs.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.
[in]_stringsArray of string data for enumeration values.
[in]_strings_countNumber of entries in _strings.

◆ CYAML_FIELD_ENUM_PTR

#define CYAML_FIELD_ENUM_PTR (   _key,
  _flags,
  _structure,
  _member,
  _strings,
  _strings_count 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_ENUM(((_flags) | CYAML_FLAG_POINTER), \
(*(((_structure *)NULL)->_member)), \
_strings, _strings_count), \
}, \
}

Mapping schema helper macro for keys with CYAML_ENUM type.

Use this for pointers to enumerated types.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.
[in]_stringsArray of string data for enumeration values.
[in]_strings_countNumber of entries in _strings.

◆ CYAML_FIELD_FLAGS

#define CYAML_FIELD_FLAGS (   _key,
  _flags,
  _structure,
  _member,
  _strings,
  _strings_count 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_FLAGS(((_flags) & (~CYAML_FLAG_POINTER)), \
(((_structure *)NULL)->_member), \
_strings, _strings_count), \
}, \
}

Mapping schema helper macro for keys with CYAML_FLAGS type.

Use this for flag types contained in structs.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.
[in]_stringsArray of string data for flag values.
[in]_strings_countNumber of entries in _strings.

◆ CYAML_FIELD_FLAGS_PTR

#define CYAML_FIELD_FLAGS_PTR (   _key,
  _flags,
  _structure,
  _member,
  _strings,
  _strings_count 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_FLAGS(((_flags) | CYAML_FLAG_POINTER), \
(*(((_structure *)NULL)->_member)), \
_strings, _strings_count), \
}, \
}

Mapping schema helper macro for keys with CYAML_FLAGS type.

Use this for pointers to flag types.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.
[in]_stringsArray of string data for flag values.
[in]_strings_countNumber of entries in _strings.

◆ CYAML_FIELD_FLOAT

#define CYAML_FIELD_FLOAT (   _key,
  _flags,
  _structure,
  _member 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_FLOAT(((_flags) & (~CYAML_FLAG_POINTER)), \
(((_structure *)NULL)->_member)), \
}, \
}

Mapping schema helper macro for keys with CYAML_FLOAT type.

Use this for floating point types contained in structs.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.

◆ CYAML_FIELD_FLOAT_PTR

#define CYAML_FIELD_FLOAT_PTR (   _key,
  _flags,
  _structure,
  _member 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_FLOAT(((_flags) | CYAML_FLAG_POINTER), \
(*(((_structure *)NULL)->_member))), \
}, \
}

Mapping schema helper macro for keys with CYAML_FLOAT type.

Use this for pointers to floating point types.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.

◆ CYAML_FIELD_IGNORE

#define CYAML_FIELD_IGNORE (   _key,
  _flags 
)
Value:
{ \
.key = _key, \
.value = { \
.type = CYAML_IGNORE, \
.flags = (_flags), \
}, \
}
@ CYAML_IGNORE
Definition cyaml.h:125

Mapping schema helper macro for keys with CYAML_IGNORE type.

Parameters
[in]_keyString defining the YAML mapping key to ignore.
[in]_flagsAny behavioural flags relevant to this key.

◆ CYAML_FIELD_INT

#define CYAML_FIELD_INT (   _key,
  _flags,
  _structure,
  _member 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_INT(((_flags) & (~CYAML_FLAG_POINTER)), \
(((_structure *)NULL)->_member)), \
}, \
}

Mapping schema helper macro for keys with CYAML_INT type.

Use this for integers contained in structs.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.

◆ CYAML_FIELD_INT_PTR

#define CYAML_FIELD_INT_PTR (   _key,
  _flags,
  _structure,
  _member 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_INT(((_flags) | CYAML_FLAG_POINTER), \
(*(((_structure *)NULL)->_member))), \
}, \
}

Mapping schema helper macro for keys with CYAML_INT type.

Use this for pointers to integers.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.

◆ CYAML_FIELD_MAPPING

#define CYAML_FIELD_MAPPING (   _key,
  _flags,
  _structure,
  _member,
  _fields 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_MAPPING(((_flags) & (~CYAML_FLAG_POINTER)), \
(((_structure *)NULL)->_member), _fields), \
}, \
}

Mapping schema helper macro for keys with CYAML_MAPPING type.

Use this for structures contained within other structures.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the containing mapping.
[in]_memberThe member in _structure for this mapping value.
[in]_fieldsPointer to mapping fields schema array.

◆ CYAML_FIELD_MAPPING_PTR

#define CYAML_FIELD_MAPPING_PTR (   _key,
  _flags,
  _structure,
  _member,
  _fields 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_MAPPING(((_flags) | CYAML_FLAG_POINTER), \
(*(((_structure *)NULL)->_member)), _fields), \
}, \
}

Mapping schema helper macro for keys with CYAML_MAPPING type.

Use this for pointers to structures.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the containing mapping.
[in]_memberThe member in _structure for this mapping value.
[in]_fieldsPointer to mapping fields schema array.

◆ CYAML_FIELD_SEQUENCE

#define CYAML_FIELD_SEQUENCE (   _key,
  _flags,
  _structure,
  _member,
  _entry,
  _min,
  _max 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.count_offset = offsetof(_structure, _member ## _count), \
.count_size = sizeof(((_structure *)NULL)->_member ## _count), \
.value = { \
CYAML_VALUE_SEQUENCE((_flags), \
(*(((_structure *)NULL)->_member)), \
_entry, _min, _max), \
}, \
}

Mapping schema helper macro for keys with CYAML_SEQUENCE type.

To use this, there must be a member in {_structure} called "{_member}_count", for storing the number of entries in the sequence.

For example, for the following structure:

struct my_structure {
unsigned *my_sequence;
unsigned my_sequence_count;
};

Pass the following as parameters:

Parameter Value
_structure struct my_structure
_member my_sequence

If you want to call the structure member for storing the sequence entry count something else, then use CYAML_FIELD_SEQUENCE_COUNT instead.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.
[in]_entryPointer to schema for the entries in sequence.
[in]_minMinimum number of sequence entries required.
[in]_maxMaximum number of sequence entries required.

◆ CYAML_FIELD_SEQUENCE_COUNT

#define CYAML_FIELD_SEQUENCE_COUNT (   _key,
  _flags,
  _structure,
  _member,
  _count,
  _entry,
  _min,
  _max 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.count_offset = offsetof(_structure, _count), \
.count_size = sizeof(((_structure *)NULL)->_count), \
.value = { \
CYAML_VALUE_SEQUENCE((_flags), \
(*(((_structure *)NULL)->_member)), \
_entry, _min, _max), \
}, \
}

Mapping schema helper macro for keys with CYAML_SEQUENCE type.

Compared to .CYAML_FIELD_SEQUENCE, this macro takes an extra _count parameter, allowing the structure member name for the sequence entry count to be provided explicitly.

For example, for the following structure:

struct my_structure {
unsigned *things;
unsigned n_things;
};

Pass the following as parameters:

Parameter Value
_structure struct my_structure
_member things
_count n_things
Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.
[in]_countThe member in _structure for this sequence's entry count.
[in]_entryPointer to schema for the entries in sequence.
[in]_minMinimum number of sequence entries required.
[in]_maxMaximum number of sequence entries required.

◆ CYAML_FIELD_SEQUENCE_FIXED

#define CYAML_FIELD_SEQUENCE_FIXED (   _key,
  _flags,
  _structure,
  _member,
  _entry,
  _count 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_SEQUENCE_FIXED((_flags), \
(*(((_structure *)NULL)->_member)), \
_entry, _count), \
}, \
}

Mapping schema helper macro for keys with CYAML_SEQUENCE_FIXED type.

Note that since this is a fixed size sequence, it must not be used with an excessive entry count. For example, passing CYAML_UNLIMITED as the count to a CYAML_SEQUENCE_FIXED with the CYAML_FLAG_POINTER flag would cause an enormous allocation, which would fail on many systems.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.
[in]_entryPointer to schema for the entries in sequence.
[in]_countNumber of sequence entries required.

◆ CYAML_FIELD_STRING

#define CYAML_FIELD_STRING (   _key,
  _flags,
  _structure,
  _member,
  _min 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_STRING(((_flags) & (~CYAML_FLAG_POINTER)), \
(((_structure *)NULL)->_member), _min, \
sizeof(((_structure *)NULL)->_member) - 1), \
}, \
}

Mapping schema helper macro for keys with CYAML_STRING type.

Use this for fields with C array type, e.g. char str[N];. This fills the maximum string length (N-1) out automatically.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.
[in]_minMinimum string length in bytes. Excludes '\0'.

◆ CYAML_FIELD_STRING_PTR

#define CYAML_FIELD_STRING_PTR (   _key,
  _flags,
  _structure,
  _member,
  _min,
  _max 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_STRING(((_flags) | CYAML_FLAG_POINTER), \
(((_structure *)NULL)->_member), \
_min, _max), \
}, \
}

Mapping schema helper macro for keys with CYAML_STRING type.

Use this for fields with C pointer type, e.g. char *str;. This creates a separate allocation for the string data, and fills in the pointer.

Use 0 for _min and CYAML_UNLIMITED for _max for unconstrained string lengths.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.
[in]_minMinimum string length in bytes. Excludes '\0'.
[in]_maxMaximum string length in bytes. Excludes '\0'.

◆ CYAML_FIELD_UINT

#define CYAML_FIELD_UINT (   _key,
  _flags,
  _structure,
  _member 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_UINT(((_flags) & (~CYAML_FLAG_POINTER)), \
(((_structure *)NULL)->_member)), \
}, \
}

Mapping schema helper macro for keys with CYAML_UINT type.

Use this for unsigned integers contained in structs.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.

◆ CYAML_FIELD_UINT_PTR

#define CYAML_FIELD_UINT_PTR (   _key,
  _flags,
  _structure,
  _member 
)
Value:
{ \
.key = _key, \
.data_offset = offsetof(_structure, _member), \
.value = { \
CYAML_VALUE_UINT(((_flags) | CYAML_FLAG_POINTER), \
(*(((_structure *)NULL)->_member))), \
}, \
}

Mapping schema helper macro for keys with CYAML_UINT type.

Use this for pointers to unsigned integers.

Parameters
[in]_keyString defining the YAML mapping key for this value.
[in]_flagsAny behavioural flags relevant to this value.
[in]_structureThe structure corresponding to the mapping.
[in]_memberThe member in _structure for this mapping value.

◆ CYAML_UNLIMITED

#define CYAML_UNLIMITED   0xffffffff

Identifies that a CYAML_SEQUENCE has unconstrained maximum entry count.

◆ CYAML_VALUE_BITFIELD

#define CYAML_VALUE_BITFIELD (   _flags,
  _type,
  _bitvals,
  _bitvals_count 
)
Value:
.type = CYAML_BITFIELD, \
.flags = (enum cyaml_flag)(_flags), \
.data_size = sizeof(_type), \
.bitfield = { \
.bitdefs = _bitvals, \
.count = _bitvals_count, \
}
@ CYAML_BITFIELD
Definition cyaml.h:89
cyaml_flag
Definition cyaml.h:138

Value schema helper macro for values with CYAML_BITFIELD type.

Parameters
[in]_flagsAny behavioural flags relevant to this value.
[in]_typeThe C type for this value.
[in]_bitvalsArray of bit field value data for the bit field.
[in]_bitvals_countNumber of entries in _bitvals.

◆ CYAML_VALUE_BOOL

#define CYAML_VALUE_BOOL (   _flags,
  _type 
)
Value:
.type = CYAML_BOOL, \
.flags = (enum cyaml_flag)(_flags), \
.data_size = sizeof(_type)
@ CYAML_BOOL
Definition cyaml.h:56

Value schema helper macro for values with CYAML_BOOL type.

Parameters
[in]_flagsAny behavioural flags relevant to this value.
[in]_typeThe C type for this value.

◆ CYAML_VALUE_ENUM

#define CYAML_VALUE_ENUM (   _flags,
  _type,
  _strings,
  _strings_count 
)
Value:
.type = CYAML_ENUM, \
.flags = (enum cyaml_flag)(_flags), \
.data_size = sizeof(_type), \
.enumeration = { \
.strings = _strings, \
.count = _strings_count, \
}
@ CYAML_ENUM
Definition cyaml.h:62

Value schema helper macro for values with CYAML_ENUM type.

Parameters
[in]_flagsAny behavioural flags relevant to this value.
[in]_typeThe C type for this value.
[in]_stringsArray of string data for enumeration values.
[in]_strings_countNumber of entries in _strings.

◆ CYAML_VALUE_FLAGS

#define CYAML_VALUE_FLAGS (   _flags,
  _type,
  _strings,
  _strings_count 
)
Value:
.type = CYAML_FLAGS, \
.flags = (enum cyaml_flag)(_flags), \
.data_size = sizeof(_type), \
.enumeration = { \
.strings = _strings, \
.count = _strings_count, \
}
@ CYAML_FLAGS
Definition cyaml.h:72

Value schema helper macro for values with CYAML_FLAGS type.

Parameters
[in]_flagsAny behavioural flags relevant to this value.
[in]_typeThe C type for this value.
[in]_stringsArray of string data for flag values.
[in]_strings_countNumber of entries in _strings.

◆ CYAML_VALUE_FLOAT

#define CYAML_VALUE_FLOAT (   _flags,
  _type 
)
Value:
.type = CYAML_FLOAT, \
.flags = (enum cyaml_flag)(_flags), \
.data_size = sizeof(_type)
@ CYAML_FLOAT
Definition cyaml.h:73

Value schema helper macro for values with CYAML_FLOAT type.

Parameters
[in]_flagsAny behavioural flags relevant to this value.
[in]_typeThe C type for this value.

◆ CYAML_VALUE_INT

#define CYAML_VALUE_INT (   _flags,
  _type 
)
Value:
.type = CYAML_INT, \
.flags = (enum cyaml_flag)(_flags), \
.data_size = sizeof(_type)
@ CYAML_INT
Definition cyaml.h:54

Value schema helper macro for values with CYAML_INT type.

Parameters
[in]_flagsAny behavioural flags relevant to this value.
[in]_typeThe C type for this value.

◆ CYAML_VALUE_MAPPING

#define CYAML_VALUE_MAPPING (   _flags,
  _type,
  _fields 
)
Value:
.type = CYAML_MAPPING, \
.flags = (enum cyaml_flag)(_flags), \
.data_size = sizeof(_type), \
.mapping = { \
.fields = _fields, \
}
@ CYAML_MAPPING
Definition cyaml.h:79

Value schema helper macro for values with CYAML_MAPPING type.

Parameters
[in]_flagsAny behavioural flags relevant to this value.
[in]_typeThe C type of structure corresponding to mapping.
[in]_fieldsPointer to mapping fields schema array.

◆ CYAML_VALUE_SEQUENCE

#define CYAML_VALUE_SEQUENCE (   _flags,
  _type,
  _entry,
  _min,
  _max 
)
Value:
.type = CYAML_SEQUENCE, \
.flags = (enum cyaml_flag)(_flags), \
.data_size = sizeof(_type), \
.sequence = { \
.entry = _entry, \
.min = _min, \
.max = _max, \
}
@ CYAML_SEQUENCE
Definition cyaml.h:101

Value schema helper macro for values with CYAML_SEQUENCE type.

Parameters
[in]_flagsAny behavioural flags relevant to this value.
[in]_typeThe C type of sequence entries.
[in]_entryPointer to schema for the entries in sequence.
[in]_minMinimum number of sequence entries required.
[in]_maxMaximum number of sequence entries required.

◆ CYAML_VALUE_SEQUENCE_FIXED

#define CYAML_VALUE_SEQUENCE_FIXED (   _flags,
  _type,
  _entry,
  _count 
)
Value:
.flags = (enum cyaml_flag)(_flags), \
.data_size = sizeof(_type), \
.sequence = { \
.entry = _entry, \
.min = _count, \
.max = _count, \
}
@ CYAML_SEQUENCE_FIXED
Definition cyaml.h:119

Value schema helper macro for values with CYAML_SEQUENCE_FIXED type.

Note that since this is a fixed size sequence, it must not be used with an excessive entry count. For example, passing CYAML_UNLIMITED as the count to a CYAML_SEQUENCE_FIXED with the CYAML_FLAG_POINTER flag would cause an enormous allocation, which would fail on many systems.

Parameters
[in]_flagsAny behavioural flags relevant to this value.
[in]_typeThe C type of sequence entries.
[in]_entryPointer to schema for the entries in sequence.
[in]_countNumber of sequence entries required.

◆ CYAML_VALUE_STRING

#define CYAML_VALUE_STRING (   _flags,
  _type,
  _min,
  _max 
)
Value:
.type = CYAML_STRING, \
.flags = (enum cyaml_flag)(_flags), \
.data_size = sizeof(_type), \
.string = { \
.min = _min, \
.max = _max, \
}
@ CYAML_STRING
Definition cyaml.h:74

Value schema helper macro for values with CYAML_STRING type.

Note
If the string is an array (char str[N];) then the CYAML_FLAG_POINTER flag must not be set, and the max length must be no more than N-1.

If the string is a pointer (char *str;), then the CYAML_FLAG_POINTER flag must be set.

Parameters
[in]_flagsAny behavioural flags relevant to this value.
[in]_typeThe C type for this value.
[in]_minMinimum string length in bytes. Excludes trailing '\0'.
[in]_maxThe C type for this value. Excludes trailing '\0'.

◆ CYAML_VALUE_UINT

#define CYAML_VALUE_UINT (   _flags,
  _type 
)
Value:
.type = CYAML_UINT, \
.flags = (enum cyaml_flag)(_flags), \
.data_size = sizeof(_type)
@ CYAML_UINT
Definition cyaml.h:55

Value schema helper macro for values with CYAML_UINT type.

Parameters
[in]_flagsAny behavioural flags relevant to this value.
[in]_typeThe C type for this value.

Typedef Documentation

◆ cyaml_bitdef_t

typedef struct cyaml_bitdef cyaml_bitdef_t

Bitfield value info.

Used for CYAML_BITFIELD type.

◆ cyaml_cfg_flags_t

CYAML behavioural configuration flags for clients

These may be bitwise-ORed together.

◆ cyaml_config_t

typedef struct cyaml_config cyaml_config_t

Client CYAML configuration data.

Todo:
Should provide facility for client to provide its own custom allocation functions.

◆ cyaml_data_t

typedef void cyaml_data_t

Data loaded or saved by CYAML has this type. CYAML schemas are used to describe the data contained.

◆ cyaml_err_t

typedef enum cyaml_err cyaml_err_t

CYAML function return codes indicating success or reason for failure.

Use cyaml_strerror() to convert an error code to a human-readable string.

◆ cyaml_flag_e

typedef enum cyaml_flag cyaml_flag_e

CYAML value flags.

These may be bitwise-ORed together.

◆ cyaml_log_fn_t

typedef void(* cyaml_log_fn_t) (cyaml_log_t level, void *ctx, const char *fmt, va_list args)

CYAML logging function prototype.

Clients may implement this to manage logging from CYAML themselves. Otherwise, consider using the standard logging function, cyaml_log.

Parameters
[in]levelLog level of message to log.
[in]ctxClient's private logging context.
[in]fmtFormat string for message to log.
[in]argsAdditional arguments used by fmt.

◆ cyaml_log_t

typedef enum cyaml_log_e cyaml_log_t

CYAML logging levels.

◆ cyaml_mem_fn_t

typedef void *(* cyaml_mem_fn_t) (void *ctx, void *ptr, size_t size)

CYAML memory allocation / freeing function.

Clients may implement this to handle memory allocation / freeing.

Parameters
[in]ctxClient's private allocation context.
[in]ptrExisting allocation to resize, or NULL.
[in]sizeThe new size for the allocation.
Note
setting 0 must be treated as free().
Returns
If size == 0, returns NULL. If size > 0, returns NULL on failure, and any existing allocation is left untouched, or return non-NULL as the new allocation on success, and the original pointer becomes invalid.

◆ cyaml_schema_field_t

Schema definition entry for mapping fields.

YAML mappings are key:value pairs. CYAML only supports scalar mapping keys, i.e. the keys must be strings. Each mapping field schema contains a cyaml_schema_value to define field's value.

The schema for mappings is composed of an array of entries of this data structure. It specifies the name of the key, and the type of the value. It also specifies the offset into the data at which value data should be placed. The array is terminated by an entry with a NULL key.

◆ cyaml_schema_value_t

Schema definition for a value.

Note
There are convenience macros for each of the types to assist in building a CYAML schema data structure for your YAML documents.

This is the fundamental building block of CYAML schemas. The load, save and free functions take parameters of this type to explain what the top-level type of the YAML document should be.

Values of type CYAML_SEQUENCE and CYAML_SEQUENCE_FIXED contain a reference to another cyaml_schema_value representing the type of the entries of the sequence. For example, if you want a sequence of integers, you'd have a cyaml_schema_value for the for the sequence value type, and another for the integer value type.

Values of type CYAML_MAPPING contain an array of cyaml_schema_field entries, defining the YAML keys allowed by the mapping. Each field contains a cyaml_schema_value representing the schema for the value.

◆ cyaml_strval_t

typedef struct cyaml_strval cyaml_strval_t

Mapping between a string and a signed value.

Used for CYAML_ENUM and CYAML_FLAGS types.

◆ cyaml_type_e

typedef enum cyaml_type cyaml_type_e

CYAML value types.

These are the fundamental data types that apply to "values" in CYAML.

CYAML "values" are represented in by cyaml_schema_value.

Enumeration Type Documentation

◆ cyaml_cfg_flags

CYAML behavioural configuration flags for clients

These may be bitwise-ORed together.

Enumerator
CYAML_CFG_DEFAULT 

This indicates CYAML's default behaviour.

CYAML_CFG_IGNORE_UNKNOWN_KEYS 

When set, unknown mapping keys are ignored when loading YAML. Without this flag set, CYAML's default behaviour is to return with the error CYAML_ERR_INVALID_KEY.

CYAML_CFG_STYLE_BLOCK 

When saving, emit mapping / sequence values in block style.

This setting can be overridden for specific values using schema value flags (cyaml_flag).

Note
This only applies to values of type CYAML_MAPPING, CYAML_SEQUENCE, or CYAML_SEQUENCE_FIXED.
If both CYAML_CFG_STYLE_BLOCK and CYAML_CFG_STYLE_FLOW are set, then block style takes precedence.
CYAML_CFG_STYLE_FLOW 

When saving, emit mapping / sequence values in flow style.

This setting can be overridden for specific values using schema value flags (cyaml_flag).

Note
This only applies to values of type CYAML_MAPPING, CYAML_SEQUENCE, or CYAML_SEQUENCE_FIXED.
If both CYAML_CFG_STYLE_BLOCK and CYAML_CFG_STYLE_FLOW are set, then block style takes precedence.
CYAML_CFG_DOCUMENT_DELIM 

When saving, emit "---" at document start and "..." at document end.

If this flag isn't set, these document delimiting marks will not be emitted.

CYAML_CFG_CASE_INSENSITIVE 

When comparing strings, compare without case sensitivity.

By default, strings are compared with case sensitivity.

CYAML_CFG_NO_ALIAS 

When loading, don't allow YAML aliases in the document.

If this option is enabled, anchors will be ignored, and the error code CYAML_ERR_ALIAS will be returned if an alias is encountered.

Setting this removes the overhead of recording anchors, so it may be worth setting if aliases are not required, and memory is constrained.

CYAML_CFG_IGNORED_KEY_WARNING 

Log any ignored mapping keys at CYAML_LOG_WARNING level.

◆ cyaml_err

enum cyaml_err

CYAML function return codes indicating success or reason for failure.

Use cyaml_strerror() to convert an error code to a human-readable string.

Enumerator
CYAML_OK 

Success.

CYAML_ERR_OOM 

Memory allocation failed.

CYAML_ERR_ALIAS 

See CYAML_CFG_NO_ALIAS.

CYAML_ERR_FILE_OPEN 

Failed to open file.

CYAML_ERR_INVALID_KEY 

Mapping key rejected by schema.

CYAML_ERR_INVALID_VALUE 

Value rejected by schema.

CYAML_ERR_INVALID_ALIAS 

No anchor found for alias.

CYAML_ERR_INTERNAL_ERROR 

Internal error in LibCYAML.

CYAML_ERR_UNEXPECTED_EVENT 

YAML event rejected by schema.

CYAML_ERR_STRING_LENGTH_MIN 

String length too short.

CYAML_ERR_STRING_LENGTH_MAX 

String length too long.

CYAML_ERR_INVALID_DATA_SIZE 

Value's data size unsupported.

CYAML_ERR_TOP_LEVEL_NON_PTR 

Top level type must be pointer.

CYAML_ERR_BAD_TYPE_IN_SCHEMA 

Schema contains invalid type.

CYAML_ERR_BAD_MIN_MAX_SCHEMA 

Schema minimum exceeds maximum.

CYAML_ERR_BAD_PARAM_SEQ_COUNT 

Bad seq_count param for schema.

CYAML_ERR_BAD_PARAM_NULL_DATA 

Client gave NULL data argument.

CYAML_ERR_BAD_BITVAL_IN_SCHEMA 

Bit value beyond bit field size.

CYAML_ERR_SEQUENCE_ENTRIES_MIN 

Too few sequence entries.

CYAML_ERR_SEQUENCE_ENTRIES_MAX 

Too many sequence entries.

CYAML_ERR_SEQUENCE_FIXED_COUNT 

Mismatch between min and max.

CYAML_ERR_SEQUENCE_IN_SEQUENCE 

Non-fixed sequence in sequence.

CYAML_ERR_MAPPING_FIELD_MISSING 

Required mapping field missing.

CYAML_ERR_BAD_CONFIG_NULL_MEMFN 

Client gave NULL mem function.

CYAML_ERR_BAD_PARAM_NULL_CONFIG 

Client gave NULL config arg.

CYAML_ERR_BAD_PARAM_NULL_SCHEMA 

Client gave NULL schema arg.

CYAML_ERR_LIBYAML_EMITTER_INIT 

Failed to initialise libyaml.

CYAML_ERR_LIBYAML_PARSER_INIT 

Failed to initialise libyaml.

CYAML_ERR_LIBYAML_EVENT_INIT 

Failed to initialise libyaml.

CYAML_ERR_LIBYAML_EMITTER 

Error inside libyaml emitter.

CYAML_ERR_LIBYAML_PARSER 

Error inside libyaml parser.

CYAML_ERR__COUNT 

Count of CYAML return codes. This is not a valid return code itself.

◆ cyaml_flag

enum cyaml_flag

CYAML value flags.

These may be bitwise-ORed together.

Enumerator
CYAML_FLAG_DEFAULT 

Default value flags (none set).

CYAML_FLAG_OPTIONAL 

Mapping field is optional.

CYAML_FLAG_POINTER 

Value is a pointer to its type.

With this there must be a non-NULL value. Consider using CYAML_FLAG_POINTER_NULL or CYAML_FLAG_POINTER_NULL_STR if you want to allow NULL values.

CYAML_FLAG_POINTER_NULL 

Permit NULL values for CYAML_FLAG_POINTER types.

An empty value in the YAML is loaded as a NULL pointer, and NULL pointers are saved in YAML as empty values.

Note, when you set CYAML_FLAG_POINTER_NULL, then CYAML_FLAG_POINTER is set automatically.

CYAML_FLAG_POINTER_NULL_STR 

Permit storage of NULL values as special NULL strings in YAML.

This extends CYAML_FLAG_POINTER_NULL, but in addition to treating empty values as NULL, any of the following are also treated as NULL:

  • null,
  • Null,
  • NULL,
  • ~,

Note that as a side effect, loading a CYAML_STRING field with one of these values will not store the literal string, it will store NULL.

When saving, a NULL value will be recorded in the YAML as null.

Note, when you set CYAML_FLAG_POINTER_NULL_STR, then both CYAML_FLAG_POINTER and CYAML_FLAG_POINTER_NULL are set automatically.

CYAML_FLAG_STRICT 

Make value handling strict.

For CYAML_ENUM and CYAML_FLAGS types, in strict mode the YAML must contain a matching string. Without strict, numerical values are also permitted.

  • For CYAML_ENUM, the value becomes the value of the enum. The numerical value is treated as signed.
  • For CYAML_FLAGS, the values are bitwise ORed together. The numerical values are treated as unsigned.

For CYAML_FLOAT types, in strict mode floating point values that would cause overflow or underflow are not permitted.

CYAML_FLAG_BLOCK 

When saving, emit mapping / sequence value in block style.

This can be used to override, for this value, any default style set in the cyaml_cfg_flags CYAML behavioural configuration flags.

Note
This is ignored unless the value's type is CYAML_MAPPING, CYAML_SEQUENCE, or CYAML_SEQUENCE_FIXED.
If both CYAML_FLAG_BLOCK and CYAML_FLAG_FLOW are set, then block style takes precedence.
If neither block nor flow style set either here, or in the cyaml_cfg_flags CYAML behavioural configuration flags, then libyaml's default behaviour is used.
CYAML_FLAG_FLOW 

When saving, emit mapping / sequence value in flow style.

This can be used to override, for this value, any default style set in the cyaml_cfg_flags CYAML behavioural configuration flags.

Note
This is ignored unless the value's type is CYAML_MAPPING, CYAML_SEQUENCE, or CYAML_SEQUENCE_FIXED.
If both CYAML_FLAG_BLOCK and CYAML_FLAG_FLOW are set, then block style takes precedence.
If neither block nor flow style set either here, or in the cyaml_cfg_flags CYAML behavioural configuration flags, then libyaml's default behaviour is used.
CYAML_FLAG_CASE_SENSITIVE 

When comparing strings for this value, compare with case sensitivity.

By default, strings are compared with case sensitivity. If CYAML_CFG_CASE_INSENSITIVE is set, this can override the configured behaviour for this specific value.

Note
If both CYAML_FLAG_CASE_SENSITIVE and CYAML_FLAG_CASE_INSENSITIVE are set, then case insensitive takes precedence.
This applies to values of types CYAML_MAPPING, CYAML_ENUM, and CYAML_FLAGS. For mappings, it applies to matching of the mappings' keys. For enums and flags it applies to the comparison of cyaml_strval strings.
CYAML_FLAG_CASE_INSENSITIVE 

When comparing strings for this value, compare with case sensitivity.

By default, strings are compared with case sensitivity. If CYAML_CFG_CASE_INSENSITIVE is set, this can override the configured behaviour for this specific value.

Note
If both CYAML_FLAG_CASE_SENSITIVE and CYAML_FLAG_CASE_INSENSITIVE are set, then case insensitive takes precedence.
This applies to values of types CYAML_MAPPING, CYAML_ENUM, and CYAML_FLAGS. For mappings, it applies to matching of the mappings' keys. For enums and flags it applies to the comparison of cyaml_strval strings.
CYAML_FLAG_SCALAR_PLAIN 

When saving, emit scalar value with plain style (no quotes).

Note
This is ignored if the value is non-scaler.
In cases where conflicting scalar style flags are set, the the one with the highest precedence is used. From lowest to highest precedence: CYAML_FLAG_SCALAR_PLAIN, CYAML_FLAG_SCALAR_FOLDED, CYAML_FLAG_SCALAR_LITERAL, CYAML_FLAG_SCALAR_QUOTE_SINGLE, CYAML_FLAG_SCALAR_QUOTE_DOUBLE,

If none of these are set, libyaml's default behaviour is used.

CYAML_FLAG_SCALAR_FOLDED 

When saving, emit scalar value with folded style:

string: >
This string
really has no line breaks!

See the notes for CYAML_FLAG_SCALAR_PLAIN for applicability and precedence.

CYAML_FLAG_SCALAR_LITERAL 

When saving, emit scalar value with literal style:

string: |
This is a
multi-line string!

See the notes for CYAML_FLAG_SCALAR_PLAIN for applicability and precedence.

CYAML_FLAG_SCALAR_QUOTE_SINGLE 

When saving, emit scalar value with single quotes (‘’`).

See the notes for CYAML_FLAG_SCALAR_PLAIN for applicability and precedence.

CYAML_FLAG_SCALAR_QUOTE_DOUBLE 

When saving, emit scalar value with double quotes (").

See the notes for CYAML_FLAG_SCALAR_PLAIN for applicability and precedence.

◆ cyaml_log_e

CYAML logging levels.

Enumerator
CYAML_LOG_DEBUG 

Debug level logging.

CYAML_LOG_INFO 

Info level logging.

CYAML_LOG_NOTICE 

Notice level logging.

CYAML_LOG_WARNING 

Warning level logging.

CYAML_LOG_ERROR 

Error level logging.

◆ cyaml_type

enum cyaml_type

CYAML value types.

These are the fundamental data types that apply to "values" in CYAML.

CYAML "values" are represented in by cyaml_schema_value.

Enumerator
CYAML_INT 

Value is a signed integer.

CYAML_UINT 

Value is an unsigned signed integer.

CYAML_BOOL 

Value is a boolean.

CYAML_ENUM 

Value is an enum. Values of this type require a string / value mapping array in the schema entry, to define the list of valid enum values.

CYAML_FLAGS 

Value is a flags bit field. Values of this type require a string / value list in the schema entry, to define the list of valid flag values. Each bit is a boolean flag. To store values of various bit sizes, use a CYAML_BITFIELD instead.

In the YAML, a CYAML_FLAGS value must be presented as a sequence of strings.

CYAML_FLOAT 

Value is floating point.

CYAML_STRING 

Value is a string.

CYAML_MAPPING 

Value is a mapping. Values of this type require mapping schema array in the schema entry.

CYAML_BITFIELD 

Value is a bit field. Values of this type require an array of value definitions in the schema entry. If the bit field is used to store only single-bit flags, it may be better to use CYAML_FLAGS instead.

In the YAML, a CYAML_FLAGS value must be presented as a mapping of bit field entry names to their numerical values.

CYAML_SEQUENCE 

Value is a sequence. Values of this type must be the direct children of a mapping. They require:

  • A schema describing the type of the sequence entries.
  • Offset to the array entry count member in the mapping structure.
  • Size in bytes of the count member in the mapping structure.
  • The minimum and maximum number of sequence count entries. Set max to CYAML_UNLIMITED to make array count unconstrained.
CYAML_SEQUENCE_FIXED 

Value is a fixed length sequence. It is similar to CYAML_SEQUENCE, however:

  • Values of this type do not need to be direct children of a mapping.
  • The minimum and maximum entry count must be the same. If not CYAML_ERR_SEQUENCE_FIXED_COUNT will be returned.
  • Unlike with CYAML_SEQUENCE, where the min and max are limits, here they are the actual entry count.
  • Since values of this type represent a constant size array, the given entry count must not be CYAML_UNLIMITED, because that would cause it to attempt a massive allocation, which on most systems would fail.
  • The offset and size of the count structure member is unused. Because the count is a schema-defined constant, it does not need to be recorded.
CYAML_IGNORE 

Value of this type is completely ignored. This is most useful for ignoring particular keys in a mapping, when the LivCYAML client has not set a configuration of CYAML_CFG_IGNORE_UNKNOWN_KEYS.

CYAML__TYPE_COUNT 

Count of the valid CYAML types. This value is not a valid type itself.

Function Documentation

◆ cyaml_free()

cyaml_err_t cyaml_free ( const cyaml_config_t config,
const cyaml_schema_value_t schema,
cyaml_data_t data,
unsigned  seq_count 
)
extern

Free data returned by a CYAML load function.

This is a convenience function, which is here purely to minimise the amount of code required in clients. Clients would be better off writing their own free function for the specific data once loaded.

Note
This is a recursive operation, freeing all nested data.
Parameters
[in]configThe client's CYAML library config.
[in]schemaThe schema describing the content of data. Must match the schema given to the CYAML load function used to load the data.
[in]dataThe data structure to free.
[in]seq_countIf top level type is sequence, this should be the entry count, otherwise it is ignored.
Returns
CYAML_OK on success, or appropriate error code otherwise.

◆ cyaml_load_data()

cyaml_err_t cyaml_load_data ( const uint8_t *  input,
size_t  input_len,
const cyaml_config_t config,
const cyaml_schema_value_t schema,
cyaml_data_t **  data_out,
unsigned *  seq_count_out 
)
extern

Load a YAML document from a data buffer.

Note
In the event of the top-level mapping having only optional fields, and the YAML not setting any of them, this function can return CYAML_OK, and NULL in the data_out parameter.
Parameters
[in]inputBuffer to load YAML data from.
[in]input_lenLength of input in bytes.
[in]configClient's CYAML configuration structure.
[in]schemaCYAML schema for the YAML to be loaded.
[out]data_outReturns the caller-owned loaded data on success. Untouched on failure.
[out]seq_count_outOn success, returns the sequence entry count. Untouched on failure. Must be non-NULL if top-level schema type is CYAML_SEQUENCE, otherwise, must be NULL.
Returns
CYAML_OK on success, or appropriate error code otherwise.

◆ cyaml_load_file()

cyaml_err_t cyaml_load_file ( const char *  path,
const cyaml_config_t config,
const cyaml_schema_value_t schema,
cyaml_data_t **  data_out,
unsigned *  seq_count_out 
)
extern

Load a YAML document from a file at the given path.

Note
In the event of the top-level mapping having only optional fields, and the YAML not setting any of them, this function can return CYAML_OK, and NULL in the data_out parameter.
Parameters
[in]pathPath to YAML file to load.
[in]configClient's CYAML configuration structure.
[in]schemaCYAML schema for the YAML to be loaded.
[out]data_outReturns the caller-owned loaded data on success. Untouched on failure.
[out]seq_count_outOn success, returns the sequence entry count. Untouched on failure. Must be non-NULL if top-level schema type is CYAML_SEQUENCE, otherwise, must be NULL.
Returns
CYAML_OK on success, or appropriate error code otherwise.

◆ cyaml_log()

void cyaml_log ( cyaml_log_t  level,
void *  ctx,
const char *  fmt,
va_list  args 
)
extern

Standard CYAML logging function.

This logs to stderr. It clients want to log elsewhere they must implement their own logging function, and pass it to CYAML in the cyaml_config_t structure.

Note
This default logging function composes single log messages from multiple separate fprintfs to stderr. If the client application writes to stderr from multiple threads, individual cyaml_log messages may get broken up by the client applications logging. To avoid this, clients should implement their own cyaml_log_fn_t and pass it in via cyaml_config_t.
Parameters
[in]levelLog level of message to log.
[in]ctxLogging context, unused.
[in]fmtFormat string for message to log.
[in]argsAdditional arguments used by fmt.

◆ cyaml_mem()

void * cyaml_mem ( void *  ctx,
void *  ptr,
size_t  size 
)
extern

CYAML default memory allocation / freeing function.

This is used when clients don't supply their own. It is exposed to enable clients to use the same allocator as libcyaml used internally to allocate/free memory when they have not provided their own allocation function.

Parameters
[in]ctxAllocation context, unused.
[in]ptrExisting allocation to resize, or NULL.
[in]sizeThe new size for the allocation.
Note
When size == 0 this frees ptr.
Returns
If size == 0, returns NULL. If size > 0, returns NULL on failure, and any existing allocation is left untouched, or return non-NULL as the new allocation on success, and the original pointer becomes invalid.

◆ cyaml_save_data()

cyaml_err_t cyaml_save_data ( char **  output,
size_t *  len,
const cyaml_config_t config,
const cyaml_schema_value_t schema,
const cyaml_data_t data,
unsigned  seq_count 
)
extern

Save a YAML document into a string in memory.

This allocates a buffer containing the serialised YAML data.

To free the returned YAML string, clients should use the cyaml_mem_fn_t function set in the cyaml_config_t passed to this function. For example:

char *yaml;
size_t len;
err = cyaml_save_file(&yaml, &len, &config, &client_schema, client_data, 0);
if (err == CYAML_OK) {
// Use `yaml`:
printf("%*s\n", len, yaml);
// Free `yaml`:
config.mem_fn(config.mem_ctx, yaml, 0);
}
cyaml_err_t cyaml_save_file(const char *path, const cyaml_config_t *config, const cyaml_schema_value_t *schema, const cyaml_data_t *data, unsigned seq_count)
@ CYAML_OK
Definition cyaml.h:586
Note
The returned YAML string does not have a trailing '\0'.
Parameters
[out]outputReturns the caller-owned serialised YAML data on success, untouched on failure. Clients should use the cyaml_mem_fn_t function set in the cyaml_config_t to free the data.
[out]lenReturns the length of the data in output on success, untouched on failure.
[in]configClient's CYAML configuration structure.
[in]schemaCYAML schema for the YAML to be saved.
[in]dataThe caller-owned data to be saved.
[in]seq_countIf top level type is sequence, this should be the entry count, otherwise it is ignored.
Returns
CYAML_OK on success, or appropriate error code otherwise.

◆ cyaml_save_file()

cyaml_err_t cyaml_save_file ( const char *  path,
const cyaml_config_t config,
const cyaml_schema_value_t schema,
const cyaml_data_t data,
unsigned  seq_count 
)
extern

Save a YAML document to a file at the given path.

Parameters
[in]pathPath to YAML file to write.
[in]configClient's CYAML configuration structure.
[in]schemaCYAML schema for the YAML to be saved.
[in]dataThe caller-owned data to be saved.
[in]seq_countIf top level type is sequence, this should be the entry count, otherwise it is ignored.
Returns
CYAML_OK on success, or appropriate error code otherwise.

◆ cyaml_strerror()

const char * cyaml_strerror ( cyaml_err_t  err)
extern

Convert a cyaml error code to a human-readable string.

Parameters
[in]errError code code to convert.
Returns
String representing err. The string is '\0' terminated, and owned by libcyaml.

Variable Documentation

◆ cyaml_version

const uint32_t cyaml_version
extern

CYAML library version number suitable for comparisons.

Version number binary composition is 0bRUUUUUUUJJJJJJJJNNNNNNNNPPPPPPPP.

Character Meaning
R Release flag. If set, it's a release.
U Unused / reserved.
J Major component of version.
N Minor component of version.
P Patch component of version.

◆ cyaml_version_str

const char* cyaml_version_str
extern

CYAML library version string.