CYAML Internals
|
Save client's data structure to YAML, using schema. More...
#include <inttypes.h>
#include <stdbool.h>
#include <assert.h>
#include <limits.h>
#include <yaml.h>
#include "mem.h"
#include "data.h"
#include "util.h"
Data Structures | |
struct | cyaml_state |
struct | cyaml_ctx |
struct | cyaml_buffer_ctx |
Typedefs | |
typedef struct cyaml_state | cyaml_state_t |
typedef struct cyaml_ctx | cyaml_ctx_t |
typedef struct cyaml_buffer_ctx | cyaml_buffer_ctx_t |
Enumerations | |
enum | cyaml_emit_style { CYAML_EMIT_STYLE_DEFAULT , CYAML_EMIT_STYLE_BLOCK , CYAML_EMIT_STYLE_FLOW } |
Save client's data structure to YAML, using schema.
This uses libyaml
to emit YAML documents, it uses the client-provided schema to access the client data, and validates it before emitting the YAML.
typedef struct cyaml_buffer_ctx cyaml_buffer_ctx_t |
CYAML save buffer context.
typedef struct cyaml_ctx cyaml_ctx_t |
Internal YAML saving context.
typedef struct cyaml_state cyaml_state_t |
A CYAML save state machine stack entry.
enum cyaml_emit_style |
The style to use when emitting mappings and sequences.
|
static |
Dump a backtrace to the log.
[in] | ctx | The CYAML saving context. |
|
static |
Write handler for libyaml.
The write handler is called when the emitter needs to flush the accumulated characters to the output. The handler should write size bytes of the buffer to the output.
[in] | data | A pointer to cyaml buffer context struture. |
[in] | buffer | The buffer with bytes to be written. |
[in] | size | The number of bytes to be written. |
|
static |
Find address of actual value.
If the value has the pointer flag, the pointer is read, otherwise the address is returned unchanged.
[in] | config | The CYAML client configuration object. |
[in] | schema | CYAML schema for the expected value. |
[in] | data_in | The address to read from. |
|
static |
Emit a mapping of bitfield values.
[in] | ctx | The CYAML saving context. |
[in] | schema | The schema for the value to be written. |
[in] | number | The value of the bitfield data. |
|
inlinestatic |
Helper to discern whether to emit document delimiting marks.
These are "---" for document start, and "..." for document end.
[in] | ctx | The CYAML saving context. |
|
static |
Helper to simplify emitting libyaml events.
This is a slightly peculiar function, but it is intended to reduce the boilerplate required to emit events.
Intended usage is something like:
[in] | ctx | The CYAML saving context. |
[in] | valid | Whether the event pointer is valid. Typically this will be the value returned by the libyaml call that initialised the event. As such, if valid is non-zero, the helper will try to emit the event, otherwise, it will return CYAML_ERR_LIBYAML_EVENT_INIT. |
[in] | event | The event to try to emit, if valid. |
|
static |
Emit a sequence of flag values.
[in] | ctx | The CYAML saving context. |
[in] | schema | The schema for the value to be written. |
[in] | number | The value of the flag data. |
|
static |
Helper to emit YAML scalar events, using libyaml.
[in] | ctx | The CYAML saving context. |
[in] | schema | The schema for the value to emit. |
[in] | value | The value to emit as a null-terminated C string. |
[in] | tag | YAML tag to use for output. |
|
static |
Get string representation for double precision floating point values.
[in] | value | The value to convert. |
|
inlinestatic |
Get the style to use for mappings/sequences from value flags and config.
As described in the API, schema flags take priority over config flags, and block has precedence over flow, if both flags are set at the same level.
[in] | ctx | The CYAML saving context. |
[in] | schema | The CYAML schema for the value expected in state. |
|
inlinestatic |
Get the style to use for mappings from value flags and config.
[in] | ctx | The CYAML saving context. |
[in] | schema | The CYAML schema for the value expected in state. |
|
inlinestatic |
Get the style to use for sequences from value flags and config.
[in] | ctx | The CYAML saving context. |
[in] | schema | The CYAML schema for the value expected in state. |
|
static |
Get string representation for single precision floating point values.
[in] | value | The value to convert. |
|
static |
Convert signed integer to string.
[in] | value | The integer to convert. |
|
static |
Convert unsigned integer to string.
[in] | value | The integer to convert. |
[in] | hex | Whether to render the number as hexadecimal. |
|
static |
The main YAML saving function.
The public interfaces are wrappers around this.
[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. |
[in] | emitter | An initialised libyaml emitter object with its output set. |
|
static |
Ensure that the CYAML save context has space for a new stack entry.
[in] | ctx | The CYAML saving context. |
|
static |
Pop the current entry on the CYAML save context's stack.
This frees any resources owned by the stack entry.
[in] | ctx | The CYAML saving context. |
[in] | emit | Whether end events should be emitted. |
|
static |
Emit a YAML end event for the state being popped from the stack.
This frees any resources owned by the stack entry.
[in] | ctx | The CYAML saving context. |
[in] | state | The CYAML save state we're popping from the stack. |
|
static |
Push a new entry onto the CYAML save context's stack.
[in] | ctx | The CYAML saving context. |
[in] | state | The CYAML save state we're pushing a stack entry for. |
[in] | schema | The CYAML schema for the value expected in state. |
[in] | data | Pointer to where value's data should be read from. |
|
static |
Emit a YAML start event for the state being pushed to the stack.
[in] | ctx | The CYAML saving context. |
[in] | state | The CYAML save state we're pushing a stack entry for. |
[in] | schema | The CYAML schema for the value expected in state. |
|
inlinestatic |
Check that common save params from client are valid.
[in] | config | The client's CYAML library config. |
[in] | schema | The schema describing the content of data. |
[in] | data | Points to client's data. |
[in] | seq_count | Top level sequence count. |
|
static |
Write a value of type CYAML_BITFIELD.
[in] | ctx | The CYAML saving context. |
[in] | schema | The schema for the value to be written. |
[in] | data | The place to read the value from in the client data. |
|
static |
Write a value of type CYAML_BOOL.
[in] | ctx | The CYAML saving context. |
[in] | schema | The schema for the value to be written. |
[in] | data | The place to read the value from in the client data. |
|
static |
YAML saving handler for the CYAML_STATE_IN_DOC state.
[in] | ctx | The CYAML saving context. |
|
static |
Write a value of type CYAML_ENUM.
[in] | ctx | The CYAML saving context. |
[in] | schema | The schema for the value to be written. |
[in] | data | The place to read the value from in the client data. |
|
static |
Write a value of type CYAML_FLAGS.
[in] | ctx | The CYAML saving context. |
[in] | schema | The schema for the value to be written. |
[in] | data | The place to read the value from in the client data. |
|
static |
Write a value of type CYAML_FLOAT.
The data_size
of the schema entry must be the size of a known floating point C type.
long double
type was causing problems, so it isn't currently supported.[in] | ctx | The CYAML saving context. |
[in] | schema | The schema for the value to be written. |
[in] | data | The place to read the value from in the client data. |
|
static |
|
static |
YAML saving handler for the CYAML_STATE_IN_MAP_KEY and CYAML_STATE_IN_MAP_VALUE states.
[in] | ctx | The CYAML saving context. |
|
static |
Write a scalar value.
[in] | ctx | The CYAML saving context. |
[in] | schema | The schema for the value to be written. |
[in] | data | The place to read the value from in the client data. |
|
static |
YAML saving handler for the CYAML_STATE_IN_SEQUENCE state.
[in] | ctx | The CYAML saving context. |
|
static |
YAML saving handler for the CYAML_STATE_START state.
[in] | ctx | The CYAML saving context. |
|
static |
YAML saving handler for the CYAML_STATE_IN_STREAM state.
[in] | ctx | The CYAML saving context. |
|
static |
Write a value of type CYAML_STRING.
[in] | ctx | The CYAML saving context. |
[in] | schema | The schema for the value to be written. |
[in] | data | The place to read the value from in the client data. |
|
static |
Write a value of type CYAML_UINT.
[in] | ctx | The CYAML saving context. |
[in] | schema | The schema for the value to be written. |
[in] | data | The place to read the value from in the client data. |
|
static |
Emit the YAML events required for a CYAML value.
[in] | ctx | The CYAML saving context. |
[in] | schema | CYAML schema for the expected value. |
[in] | data | The place to read the value from in the client data. |
[in] | seq_count | Entry count for sequence values. Unused for non-sequence values. |
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 | ||
) |
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. |
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 | ||
) |
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. |
|
static |
Pad a signed value that's smaller than 64-bit to an int64_t.
This sets all the bits in the padded region.
[in] | raw | Contains a signed value of size bytes. |
[in] | size | Number of bytes used in raw. |