Loading...
Searching...
No Matches
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)

## 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 | ) |

Value:
((sizeof(_a)) / (sizeof(_a[0])))

Helper macro for counting array elements.

Note
  Don't use this macro on pointers.

Parameters

  [in] | _a | A 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
@ 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The member in _structure for this mapping value.
  [in] | _bitvals | Array of bit field value data for the bit field.
  [in] | _bitvals_count | Number 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The member in _structure for this mapping value.
  [in] | _bitvals | Array of bit field value data for the bit field.
  [in] | _bitvals_count | Number 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The member in _structure for this mapping value.
  [in] | _strings | Array of string data for enumeration values.
  [in] | _strings_count | Number 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The member in _structure for this mapping value.
  [in] | _strings | Array of string data for enumeration values.
  [in] | _strings_count | Number 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The member in _structure for this mapping value.
  [in] | _strings | Array of string data for flag values.
  [in] | _strings_count | Number 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The member in _structure for this mapping value.
  [in] | _strings | Array of string data for flag values.
  [in] | _strings_count | Number 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The 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
@ CYAML_IGNORE
Definition cyaml.h:125

Mapping schema helper macro for keys with CYAML_IGNORE type.

Parameters

  [in] | _key | String defining the YAML mapping key to ignore.
  [in] | _flags | Any 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the containing mapping.
  [in] | _member | The member in _structure for this mapping value.
  [in] | _fields | Pointer 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the containing mapping.
  [in] | _member | The member in _structure for this mapping value.
  [in] | _fields | Pointer 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The member in _structure for this mapping value.
  [in] | _entry | Pointer to schema for the entries in sequence.
  [in] | _min | Minimum number of sequence entries required.
  [in] | _max | Maximum 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The member in _structure for this mapping value.
  [in] | _count | The member in _structure for this sequence's entry count.
  [in] | _entry | Pointer to schema for the entries in sequence.
  [in] | _min | Minimum number of sequence entries required.
  [in] | _max | Maximum 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The member in _structure for this mapping value.
  [in] | _entry | Pointer to schema for the entries in sequence.
  [in] | _count | Number 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The member in _structure for this mapping value.
  [in] | _min | Minimum 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The member in _structure for this mapping value.
  [in] | _min | Minimum string length in bytes. Excludes '\0'.
  [in] | _max | Maximum 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The 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] | _key | String defining the YAML mapping key for this value.
  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _structure | The structure corresponding to the mapping.
  [in] | _member | The 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
@ CYAML_BITFIELD
Definition cyaml.h:89
cyaml_flag
cyaml_flag
Definition cyaml.h:138

Value schema helper macro for values with CYAML_BITFIELD type.

Parameters

  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _type | The C type for this value.
  [in] | _bitvals | Array of bit field value data for the bit field.
  [in] | _bitvals_count | Number 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
@ CYAML_BOOL
Definition cyaml.h:56

Value schema helper macro for values with CYAML_BOOL type.

Parameters

  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _type | The 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
@ CYAML_ENUM
Definition cyaml.h:62

Value schema helper macro for values with CYAML_ENUM type.

Parameters

  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _type | The C type for this value.
  [in] | _strings | Array of string data for enumeration values.
  [in] | _strings_count | Number 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
@ CYAML_FLAGS
Definition cyaml.h:72

Value schema helper macro for values with CYAML_FLAGS type.

Parameters

  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _type | The C type for this value.
  [in] | _strings | Array of string data for flag values.
  [in] | _strings_count | Number 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
@ CYAML_FLOAT
Definition cyaml.h:73

Value schema helper macro for values with CYAML_FLOAT type.

Parameters

  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _type | The 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
@ CYAML_INT
Definition cyaml.h:54

Value schema helper macro for values with CYAML_INT type.

Parameters

  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _type | The 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
@ CYAML_MAPPING
Definition cyaml.h:79

Value schema helper macro for values with CYAML_MAPPING type.

Parameters

  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _type | The C type of structure corresponding to mapping.
  [in] | _fields | Pointer 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
@ CYAML_SEQUENCE
Definition cyaml.h:101

Value schema helper macro for values with CYAML_SEQUENCE type.

Parameters

  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _type | The C type of sequence entries.
  [in] | _entry | Pointer to schema for the entries in sequence.
  [in] | _min | Minimum number of sequence entries required.
  [in] | _max | Maximum number of sequence entries required.

## CYAML_VALUE_SEQUENCE_FIXED

#define CYAML_VALUE_SEQUENCE_FIXED | ( |  | _flags,
|  |  | _type,
|  |  | _entry,
|  |  | _count )

Value:
.type = CYAML_SEQUENCE_FIXED, \
.flags = (enum cyaml_flag)(_flags), \
.data_size = sizeof(_type), \
.sequence = { \
.entry = _entry, \
.min = _count, \
.max = _count, \
}
CYAML_SEQUENCE_FIXED
@ 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] | _flags | Any behavioural flags relevant to this value.
  [in] | _type | The C type of sequence entries.
  [in] | _entry | Pointer to schema for the entries in sequence.
  [in] | _count | Number 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
@ 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] | _flags | Any behavioural flags relevant to this value.
  [in] | _type | The C type for this value.
  [in] | _min | Minimum string length in bytes. Excludes trailing '\0'.
  [in] | _max | The 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
@ CYAML_UINT
Definition cyaml.h:55

Value schema helper macro for values with CYAML_UINT type.

Parameters

  [in] | _flags | Any behavioural flags relevant to this value.
  [in] | _type | The 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

typedef enum cyaml_cfg_flags 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] | level | Log level of message to log.
  [in] | ctx | Client's private logging context.
  [in] | fmt | Format string for message to log.
  [in] | args | Additional 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] | ctx | Client's private allocation context.
  [in] | ptr | Existing allocation to resize, or NULL.
  [in] | size | The 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

typedef struct cyaml_schema_field 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

typedef struct cyaml_schema_value 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

enum 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

enum 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] | config | The client's CYAML library config.
  [in] | schema | The schema describing the content of data. Must match the schema given to the CYAML load function used to load the data.
  [in] | data | The data structure to free.
  [in] | seq_count | If 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] | input | Buffer to load YAML data from.
  [in] | input_len | Length of input in bytes.
  [in] | config | Client's CYAML configuration structure.
  [in] | schema | CYAML schema for the YAML to be loaded.
  [out] | data_out | Returns the caller-owned loaded data on success. Untouched on failure.
  [out] | seq_count_out | On 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] | path | Path to YAML file to load.
  [in] | config | Client's CYAML configuration structure.
  [in] | schema | CYAML schema for the YAML to be loaded.
  [out] | data_out | Returns the caller-owned loaded data on success. Untouched on failure.
  [out] | seq_count_out | On 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] | level | Log level of message to log.
  [in] | ctx | Logging context, unused.
  [in] | fmt | Format string for message to log.
  [in] | args | Additional 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] | ctx | Allocation context, unused.
  [in] | ptr | Existing allocation to resize, or NULL.
  [in] | size | The 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_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)
CYAML_OK
@ CYAML_OK
Definition cyaml.h:586

Note
  The returned YAML string does not have a trailing '\0'.

Parameters

  [out] | output | Returns 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] | len | Returns the length of the data in output on success, untouched on failure.
  [in] | config | Client's CYAML configuration structure.
  [in] | schema | CYAML schema for the YAML to be saved.
  [in] | data | The caller-owned data to be saved.
  [in] | seq_count | If 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] | path | Path to YAML file to write.
  [in] | config | Client's CYAML configuration structure.
  [in] | schema | CYAML schema for the YAML to be saved.
  [in] | data | The caller-owned data to be saved.
  [in] | seq_count | If 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] | err | Error 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.