CYAML Internals
|
CYAML library public header. More...
#include <stdarg.h>
#include <stdint.h>
#include <stddef.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 |
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 |
CYAML library public header.
CYAML is a C library for parsing and serialising structured YAML documents.
#define CYAML_ARRAY_LEN | ( | _a | ) | ((sizeof(_a)) / (sizeof(_a[0]))) |
Helper macro for counting array elements.
[in] | _a | A C array. |
#define CYAML_FIELD_BITFIELD | ( | _key, | |
_flags, | |||
_structure, | |||
_member, | |||
_bitvals, | |||
_bitvals_count | |||
) |
Mapping schema helper macro for keys with CYAML_BITFIELD type.
Use this for bit field types contained in structs.
[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. |
#define CYAML_FIELD_BITFIELD_PTR | ( | _key, | |
_flags, | |||
_structure, | |||
_member, | |||
_bitvals, | |||
_bitvals_count | |||
) |
Mapping schema helper macro for keys with CYAML_BITFIELD type.
Use this for pointers to bit field types.
[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. |
#define CYAML_FIELD_BOOL | ( | _key, | |
_flags, | |||
_structure, | |||
_member | |||
) |
Mapping schema helper macro for keys with CYAML_BOOL type.
Use this for boolean types contained in structs.
[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. |
#define CYAML_FIELD_BOOL_PTR | ( | _key, | |
_flags, | |||
_structure, | |||
_member | |||
) |
Mapping schema helper macro for keys with CYAML_BOOL type.
Use this for pointers to boolean types.
[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. |
#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.
#define CYAML_FIELD_ENUM | ( | _key, | |
_flags, | |||
_structure, | |||
_member, | |||
_strings, | |||
_strings_count | |||
) |
Mapping schema helper macro for keys with CYAML_ENUM type.
Use this for enumerated types contained in structs.
[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. |
#define CYAML_FIELD_ENUM_PTR | ( | _key, | |
_flags, | |||
_structure, | |||
_member, | |||
_strings, | |||
_strings_count | |||
) |
Mapping schema helper macro for keys with CYAML_ENUM type.
Use this for pointers to enumerated types.
[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. |
#define CYAML_FIELD_FLAGS | ( | _key, | |
_flags, | |||
_structure, | |||
_member, | |||
_strings, | |||
_strings_count | |||
) |
Mapping schema helper macro for keys with CYAML_FLAGS type.
Use this for flag types contained in structs.
[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. |
#define CYAML_FIELD_FLAGS_PTR | ( | _key, | |
_flags, | |||
_structure, | |||
_member, | |||
_strings, | |||
_strings_count | |||
) |
Mapping schema helper macro for keys with CYAML_FLAGS type.
Use this for pointers to flag types.
[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. |
#define CYAML_FIELD_FLOAT | ( | _key, | |
_flags, | |||
_structure, | |||
_member | |||
) |
Mapping schema helper macro for keys with CYAML_FLOAT type.
Use this for floating point types contained in structs.
[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. |
#define CYAML_FIELD_FLOAT_PTR | ( | _key, | |
_flags, | |||
_structure, | |||
_member | |||
) |
Mapping schema helper macro for keys with CYAML_FLOAT type.
Use this for pointers to floating point types.
[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. |
#define CYAML_FIELD_IGNORE | ( | _key, | |
_flags | |||
) |
Mapping schema helper macro for keys with CYAML_IGNORE type.
[in] | _key | String defining the YAML mapping key to ignore. |
[in] | _flags | Any behavioural flags relevant to this key. |
#define CYAML_FIELD_INT | ( | _key, | |
_flags, | |||
_structure, | |||
_member | |||
) |
Mapping schema helper macro for keys with CYAML_INT type.
Use this for integers contained in structs.
[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. |
#define CYAML_FIELD_INT_PTR | ( | _key, | |
_flags, | |||
_structure, | |||
_member | |||
) |
Mapping schema helper macro for keys with CYAML_INT type.
Use this for pointers to integers.
[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. |
#define CYAML_FIELD_MAPPING | ( | _key, | |
_flags, | |||
_structure, | |||
_member, | |||
_fields | |||
) |
Mapping schema helper macro for keys with CYAML_MAPPING type.
Use this for structures contained within other structures.
[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. |
#define CYAML_FIELD_MAPPING_PTR | ( | _key, | |
_flags, | |||
_structure, | |||
_member, | |||
_fields | |||
) |
Mapping schema helper macro for keys with CYAML_MAPPING type.
Use this for pointers to structures.
[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. |
#define CYAML_FIELD_SEQUENCE | ( | _key, | |
_flags, | |||
_structure, | |||
_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:
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.
[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. |
#define CYAML_FIELD_SEQUENCE_COUNT | ( | _key, | |
_flags, | |||
_structure, | |||
_member, | |||
_count, | |||
_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:
Pass the following as parameters:
Parameter | Value |
---|---|
_structure | struct my_structure |
_member | things |
_count | n_things |
[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. |
#define CYAML_FIELD_SEQUENCE_FIXED | ( | _key, | |
_flags, | |||
_structure, | |||
_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.
[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. |
#define CYAML_FIELD_STRING | ( | _key, | |
_flags, | |||
_structure, | |||
_member, | |||
_min | |||
) |
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.
[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'. |
#define CYAML_FIELD_STRING_PTR | ( | _key, | |
_flags, | |||
_structure, | |||
_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.
[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'. |
#define CYAML_FIELD_UINT | ( | _key, | |
_flags, | |||
_structure, | |||
_member | |||
) |
Mapping schema helper macro for keys with CYAML_UINT type.
Use this for unsigned integers contained in structs.
[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. |
#define CYAML_FIELD_UINT_PTR | ( | _key, | |
_flags, | |||
_structure, | |||
_member | |||
) |
Mapping schema helper macro for keys with CYAML_UINT type.
Use this for pointers to unsigned integers.
[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. |
#define CYAML_UNLIMITED 0xffffffff |
Identifies that a CYAML_SEQUENCE has unconstrained maximum entry count.
#define CYAML_VALUE_BITFIELD | ( | _flags, | |
_type, | |||
_bitvals, | |||
_bitvals_count | |||
) |
Value schema helper macro for values with CYAML_BITFIELD type.
[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. |
#define CYAML_VALUE_BOOL | ( | _flags, | |
_type | |||
) |
Value schema helper macro for values with CYAML_BOOL type.
[in] | _flags | Any behavioural flags relevant to this value. |
[in] | _type | The C type for this value. |
#define CYAML_VALUE_ENUM | ( | _flags, | |
_type, | |||
_strings, | |||
_strings_count | |||
) |
Value schema helper macro for values with CYAML_ENUM type.
[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. |
#define CYAML_VALUE_FLAGS | ( | _flags, | |
_type, | |||
_strings, | |||
_strings_count | |||
) |
Value schema helper macro for values with CYAML_FLAGS type.
[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. |
#define CYAML_VALUE_FLOAT | ( | _flags, | |
_type | |||
) |
Value schema helper macro for values with CYAML_FLOAT type.
[in] | _flags | Any behavioural flags relevant to this value. |
[in] | _type | The C type for this value. |
#define CYAML_VALUE_INT | ( | _flags, | |
_type | |||
) |
Value schema helper macro for values with CYAML_INT type.
[in] | _flags | Any behavioural flags relevant to this value. |
[in] | _type | The C type for this value. |
#define CYAML_VALUE_MAPPING | ( | _flags, | |
_type, | |||
_fields | |||
) |
Value schema helper macro for values with CYAML_MAPPING type.
[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. |
#define CYAML_VALUE_SEQUENCE | ( | _flags, | |
_type, | |||
_entry, | |||
_min, | |||
_max | |||
) |
Value schema helper macro for values with CYAML_SEQUENCE type.
[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. |
#define CYAML_VALUE_SEQUENCE_FIXED | ( | _flags, | |
_type, | |||
_entry, | |||
_count | |||
) |
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.
[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. |
#define CYAML_VALUE_STRING | ( | _flags, | |
_type, | |||
_min, | |||
_max | |||
) |
Value schema helper macro for values with CYAML_STRING type.
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.
[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'. |
#define CYAML_VALUE_UINT | ( | _flags, | |
_type | |||
) |
Value schema helper macro for values with CYAML_UINT type.
[in] | _flags | Any behavioural flags relevant to this value. |
[in] | _type | The C type for this value. |
typedef struct cyaml_bitdef cyaml_bitdef_t |
Bitfield value info.
Used for CYAML_BITFIELD type.
typedef enum cyaml_cfg_flags cyaml_cfg_flags_t |
CYAML behavioural configuration flags for clients
These may be bitwise-ORed together.
typedef struct cyaml_config cyaml_config_t |
Client CYAML configuration data.
typedef void cyaml_data_t |
Data loaded or saved by CYAML has this type. CYAML schemas are used to describe the data contained.
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.
typedef enum cyaml_flag cyaml_flag_e |
CYAML value flags.
These may be bitwise-ORed together.
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.
[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. |
typedef enum cyaml_log_e cyaml_log_t |
CYAML logging levels.
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.
[in] | ctx | Client's private allocation context. |
[in] | ptr | Existing allocation to resize, or NULL. |
[in] | size | The new size for the allocation. |
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. 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.
typedef struct cyaml_schema_value cyaml_schema_value_t |
Schema definition for a value.
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.
typedef struct cyaml_strval cyaml_strval_t |
Mapping between a string and a signed value.
Used for CYAML_ENUM and CYAML_FLAGS types.
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.
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).
|
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).
|
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. |
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. |
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 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 This extends CYAML_FLAG_POINTER_NULL, but in addition to treating empty values as NULL, any of the following are also treated as 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 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_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.
|
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.
|
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.
|
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.
|
CYAML_FLAG_SCALAR_PLAIN | When saving, emit scalar value with plain style (no quotes).
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. |
enum cyaml_log_e |
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:
|
CYAML_SEQUENCE_FIXED | Value is a fixed length sequence. It is similar to CYAML_SEQUENCE, however:
|
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. |
|
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.
[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. |
|
extern |
Load a YAML document from a data buffer.
NULL
in the data_out
parameter.[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. |
|
extern |
Load a YAML document from a file at the given path.
NULL
in the data_out
parameter.[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. |
|
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.
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.[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. |
|
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.
[in] | ctx | Allocation context, unused. |
[in] | ptr | Existing allocation to resize, or NULL. |
[in] | size | The new size for the allocation. |
size == 0
this frees ptr
. 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.
|
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:
[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. |
|
extern |
Save a YAML document to a file at the given path.
[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. |
|
extern |
Convert a cyaml error code to a human-readable string.
[in] | err | Error code code to convert. |
|
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. |
|
extern |
CYAML library version string.