Reflection API

Introduction

For an overview of the reflection workflow, read Reflection Guide first. It explains how reflection metadata, packed blobs, and fy_type_context fit together before the symbol-level reference below.

Reflection

The reflection subsystem extracts type metadata from C header files (via a libclang backend at development time) or from pre-serialised binary blobs (packed backend at deployment time), and uses that metadata to automatically map between YAML documents and C data structures at runtime.

Key types:

struct fy_reflection — a type registry loaded from a C header or a packed blob; owns all type information for a compilation unit
struct fy_type_info — descriptor for a single C type (struct, union, enum, typedef, pointer, array, …); covers the full C type system including bitfields, anonymous types, and qualifiers
struct fy_field_info — descriptor for a single struct/union field, including offset, size, bit-width, and YAML metadata annotations extracted from source comments
struct fy_enum_info — descriptor for a single enumeration constant

Metadata annotations: YAML-formatted comments in C source code guide the YAML <-> C mapping:

struct users {
    struct user *list;    // yaml: { counter: count }
    int count;
};

Backends:

Clang backend (requires --with-libclang / libclang installed): parses C headers at runtime; no pre-processing step needed
Packed backend: a self-contained binary blob pre-generated at build time via fy_reflection_export_packed(); zero runtime dependency on libclang, suitable for deployment
Null backend: stub with no type data, used for testing

This interface is experimental and subject to change before version 1.0.

YAML Metadata Annotations

Metadata annotations are YAML-formatted comments placed on C struct/union fields or on the type definitions themselves. They guide the meta-type system when mapping between YAML documents and C data structures.

Annotation syntax:

// yaml: { <key>: <value>, ... }

The comment must appear on the same line as (or on the line immediately before) the field or type definition. Multiple key/value pairs may appear in one annotation.

Example:

struct foo {
    char *key;
    int   value;
};

struct container {
    int        count;
    struct foo *items;   // yaml: { key: key, counter: count }
};

Annotations placed on the entry type (or supplied via entry_meta in struct fy_type_context_cfg) govern root-level behaviour.

Boolean annotations

All boolean keys default to false unless noted.

required (default: true): Field is mandatory; a parse error is raised if it is absent from the input YAML. Set to false to make a field optional.
omit-on-emit: Skip this field entirely during emission; it will not appear in the generated YAML output regardless of its value.
omit-if-empty: Omit the field during emission when its value is empty: a NULL or zero-length string, or a sequence/array with no elements.
omit-if-default: Omit the field during emission when its value equals the default annotation value. Must be used together with the default key.
omit-if-null: Omit the field during emission when its C value is a NULL pointer.
match-null: Accept YAML null as a valid input value for this type or field.
match-seq: Accept a YAML sequence node as valid input. Primarily used on union variant arms to express that the arm matches sequences.
match-map: Accept a YAML mapping node as valid input.
match-scalar: Accept a YAML scalar node as valid input.
match-always: Accept any YAML node type; used as a wildcard “catch-all” arm in union discriminator chains.
not-null-terminated: The string field is stored as raw bytes without a trailing NUL; length is tracked by the companion counter field. Mutually exclusive with normal C-string handling.
not-string: Treat the field as non-string data even though its C type is char *. Prevents the serdes engine from applying string-specific behaviour.
null-allowed: Permit NULL pointer values in this field during both parse and emit; without this flag a NULL from a non-optional field is treated as an error.
field-auto-select: On union types: automatically choose the active union arm by probing each arm’s match-* flags against the actual YAML node type, without requiring an explicit selector field.
flatten-field-first-anonymous: When flattening an anonymous sub-struct into the parent mapping, emit the first anonymous field before any named fields (i.e., keep it first).
skip-unknown: On struct types: silently ignore mapping keys that have no corresponding C field, instead of raising a parse error. Useful for forward-compatible schemas.
enum-or-seq: On enum types: allow the YAML input to be either a scalar (single enum value) or a sequence of scalars (set of values combined with OR).

String annotations

counter: <field-name>

Names the sibling field that holds the element count of a variable-length C array. The counter field must be an integer type. During parse the library writes the parsed length into that field; during emit it reads the count from it:

struct buf {
    uint8_t *data;    // yaml: { counter: len }
    size_t   len;
};

key: <field-name>

Names the field within each array element that becomes the YAML mapping key when the array is emitted as a YAML mapping (and parsed back from one). Requires counter to also be set:

struct entry {
    char *id;
    int   value;
};
struct table {
    struct entry *rows;   // yaml: { key: id, counter: count }
    int           count;
};

selector: <field-name>

On union types: names the field that acts as the discriminator. The field’s value is compared against each arm’s select annotation to choose the active arm.

name: <yaml-key>

Override the YAML key name used for this field. By default the C field name is used. Useful when the desired YAML key is a C reserved word or follows a different naming convention:

int type_id;   // yaml: { name: type }

remove-prefix: <prefix>

Strip the given prefix from all field names before using them as YAML keys. Applied to every field in the annotated struct:

struct s {     // yaml: { remove-prefix: s_ }
    int s_foo;
    int s_bar;
};

Emits as { foo: ..., bar: ... }.

flatten-field: <field-name>

Inline (flatten) the sub-struct named by the annotation into the parent YAML mapping. The sub-struct’s own fields appear as direct keys of the parent mapping instead of under a nested key.

“Any” annotations (accept arbitrary YAML values)

terminator: <value>

Alternative to counter for variable-length arrays: the array ends at the first element whose value equals terminator. The terminator element itself is not emitted. Common use is 0-terminated arrays:

int *ids;   // yaml: { terminator: 0 }

default: <value>

Default value for the field. During parse, if the field is absent from the input and the field is not required, the default is used. During emit, omit-if-default compares the live value against this. The value is parsed as the field’s own C type:

int port;   // yaml: { default: 8080, omit-if-default: true }

select: <value>

The discriminator value that causes this union arm to be selected when the parent struct’s selector field matches. Works together with the selector string annotation on the enclosing union type:

union payload {       // yaml: { selector: kind }
    int    as_int;    // yaml: { select: 0 }
    char  *as_str;    // yaml: { select: 1 }
};

fill: <value>

Default fill value for uninitialised or sparse sequence elements. When the input sequence is shorter than expected, remaining elements are filled with this value rather than left as zero/NULL.

Meta-Type System

The meta-type system combines a raw C type (struct fy_type_info) with a YAML annotation document to produce a meta type: an object that knows both the C layout of a type and how to map it to/from YAML. Two fields with the same C type but different annotations are different meta types.

Key types:

struct fy_type_context — owns all meta types for one entry point; created from a struct fy_reflection * + an entry type name
struct fy_meta_type — one C type + annotation pair; describes how a type is serialised/deserialised
struct fy_meta_field — one field within a meta type (field_info + meta)

Lifecycle:

struct fy_type_context_cfg cfg = {
    .rfl        = rfl,
    .entry_type = "struct server_config",
};
struct fy_type_context *ctx = fy_type_context_create(&cfg);

// parse YAML into a C struct (allocates; caller must free via
// fy_type_context_free_data):
void *data = NULL;
fy_type_context_parse(ctx, fyp, &data);

// emit back to YAML:
fy_type_context_emit(ctx, emit, data, FYTCEF_SS | FYTCEF_DS |
                     FYTCEF_DE | FYTCEF_SE);

fy_type_context_free_data(ctx, data);
fy_type_context_destroy(ctx);

enum fy_type_kind

enum fy_type_kind: The types of the reflection plumbing

Definition

enum fy_type_kind {
    FYTK_INVALID,
    FYTK_VOID,
    FYTK_BOOL,
    FYTK_CHAR,
    FYTK_SCHAR,
    FYTK_UCHAR,
    FYTK_SHORT,
    FYTK_USHORT,
    FYTK_INT,
    FYTK_UINT,
    FYTK_LONG,
    FYTK_ULONG,
    FYTK_LONGLONG,
    FYTK_ULONGLONG,
    FYTK_INT128,
    FYTK_UINT128,
    FYTK_FLOAT,
    FYTK_DOUBLE,
    FYTK_LONGDOUBLE,
    FYTK_FLOAT16,
    FYTK_FLOAT128,
    FYTK_RECORD,
    FYTK_STRUCT,
    FYTK_UNION,
    FYTK_ENUM,
    FYTK_TYPEDEF,
    FYTK_PTR,
    FYTK_CONSTARRAY,
    FYTK_INCOMPLETEARRAY,
    FYTK_NULL,
    FYTK_FUNCTION
};

Constants

FYTK_INVALID: Invalid type
FYTK_VOID: The void type
FYTK_BOOL: The boolean type
FYTK_CHAR: The native char type
FYTK_SCHAR: The signed char type
FYTK_UCHAR: The unsigned char type
FYTK_SHORT: The signed short type
FYTK_USHORT: The unsigned short type
FYTK_INT: The int type
FYTK_UINT: The unsigned int type
FYTK_LONG: The long type
FYTK_ULONG: The unsigned long type
FYTK_LONGLONG: The long long type
FYTK_ULONGLONG: The unsigned long long type
FYTK_INT128: A signed int 128 bit type (may not be available on all arches)
FYTK_UINT128: An unsigned int 128 bit type (may not be available on all arches)
FYTK_FLOAT: The float type
FYTK_DOUBLE: The double type
FYTK_LONGDOUBLE: The long double type
FYTK_FLOAT16: A 16 bit float type (may not be available on all arches)
FYTK_FLOAT128: A 128 bit float type (may not be available on all arches)
FYTK_RECORD: A generic record type (not used for C)
FYTK_STRUCT: A struct type
FYTK_UNION: A union type
FYTK_ENUM: An enumeration type
FYTK_TYPEDEF: A typedef type
FYTK_PTR: A pointer type
FYTK_CONSTARRAY: A constant array type
FYTK_INCOMPLETEARRAY: An incomplete array type
FYTK_NULL: The null type
FYTK_FUNCTION: A function type

fy_type_kind_is_valid

bool fy_type_kind_is_valid(enum fy_type_kind type_kind)

Check type kind for validity

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind is valid.

Return

true if valid, false otherwise

fy_type_kind_is_primitive

bool fy_type_kind_is_primitive(enum fy_type_kind type_kind)

Check if it’s a primitive type kind

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind is for a primitive C type

Return

true if primitive, false otherwise

fy_type_kind_is_primary

bool fy_type_kind_is_primary(enum fy_type_kind type_kind)

Check if it’s a primary type kind

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind is for a primary C type A primary type is is a subset of primitive (without VOID and NULL)

Return

true if primitive, false otherwise

fy_type_kind_is_like_ptr

bool fy_type_kind_is_like_ptr(enum fy_type_kind type_kind)

Check if it’s pointer like type

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind matches a pointer like use, which is pointer, constant array or incomplete array.

Return

true if pointer like, false otherwise

fy_type_kind_is_record

bool fy_type_kind_is_record(enum fy_type_kind type_kind)

Check if it’s a record like type

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind contains other types in a record like structure, like a struct or union.

Return

true if record, false otherwise

fy_type_kind_is_numeric

bool fy_type_kind_is_numeric(enum fy_type_kind type_kind)

Check if it’s a numeric type

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind points to a number, either boolean, integer or float

Return

true if numeric, false otherwise

fy_type_kind_is_integer

bool fy_type_kind_is_integer(enum fy_type_kind type_kind)

Check if it’s a numeric integer type

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind points to an integer

Return

true if integer, false otherwise

fy_type_kind_is_float

bool fy_type_kind_is_float(enum fy_type_kind type_kind)

Check if it’s a numeric float type

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind points to a float

Return

true if float, false otherwise

fy_type_kind_is_signed

bool fy_type_kind_is_signed(enum fy_type_kind type_kind)

Check if an integer kind is signed

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind is a signed integer.

Return

true if a signed integer, false otherwise

fy_type_kind_is_unsigned

bool fy_type_kind_is_unsigned(enum fy_type_kind type_kind)

Check if an integer kind is unsigned

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind is an unsigned integer

Return

true if an unsigned integer, false otherwise

fy_type_kind_is_enum_constant_decl

bool fy_type_kind_is_enum_constant_decl(enum fy_type_kind type_kind)

Check if it’s a type that can be an enum

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind points to something that is a valid enum constant declaration. For normal cases it’s >= int but for weird packed cases can be something smaller.

Return

true if it is a type than can be an enum constant declaration, false otherwise

fy_type_kind_has_fields

bool fy_type_kind_has_fields(enum fy_type_kind type_kind)

Check if the type has fields

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind has fields, either if it’s a record or an enumeration type.

Return

true if it has fields, false otherwise

fy_type_kind_has_direct_fields

bool fy_type_kind_has_direct_fields(enum fy_type_kind type_kind)

Check if the type has directly addressable fields

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind is a struct or union — types whose fields can be addressed by offset without going through a dependent type. This is a strict subset of fy_type_kind_has_fields(), excluding enums.

Return

true if it has direct fields (struct or union), false otherwise

fy_type_kind_has_prefix

bool fy_type_kind_has_prefix(enum fy_type_kind type_kind)

Check if the type requires a prefix

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind requires a prefix when displayed, ie. like struct union or enum types.

Return

true if it has prefix, false otherwise

fy_type_info_prefixless_name

const char *fy_type_info_prefixless_name(const struct fy_type_info *ti)

Get the name of a type without its keyword prefix

Parameters:

ti (const struct fy_type_info*) – The type info

Description

Return the type’s name with any leading keyword prefix removed. For example, "struct foo" becomes "foo" and "enum bar" becomes "bar". For types that carry no prefix (e.g. "int") the returned pointer is the same as ti->name.

Return

A pointer into ti->name past the prefix, or NULL on error. The lifetime of the returned pointer matches that of ti.

fy_type_kind_is_dependent

bool fy_type_kind_is_dependent(enum fy_type_kind type_kind)

Check if the type is dependent on another

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind is dependent on another, i.e. a typedef. An enum is also dependent because the underlying type matches the range of the enum values.

Return

true if it is dependent, false otherwise

fy_type_kind_is_direct_dependent

bool fy_type_kind_is_direct_dependent(enum fy_type_kind type_kind)

Check if the type is directly dependent on another

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind has a single, directly referenced dependent type (i.e. the dependent_type field of struct fy_type_info is meaningful). This covers typedefs, pointers, and arrays, but not enums — enums have a dependent type that represents their underlying integer range, but their constants are named independently rather than being a direct alias.

Return

true if directly dependent (typedef, ptr, constarray, incompletearray), false otherwise

fy_type_kind_is_named

bool fy_type_kind_is_named(enum fy_type_kind type_kind)

Check if the type is named

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind is named, i.e. has a name that uniquely identifies it.

Return

true if it is named, false otherwise

fy_type_kind_has_element_count

bool fy_type_kind_has_element_count(enum fy_type_kind type_kind)

Check if the type carries a fixed element count

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check whether the type kind is a constant-size array, i.e. one whose element count is known at compile time and stored in fy_type_info::count. Incomplete arrays ([]) have an unknown size at declaration and return false.

Return

true if the type is a FYTK_CONSTARRAY, false otherwise

fy_type_kind_signess

int fy_type_kind_signess(enum fy_type_kind type_kind)

Find out the type’s sign

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Check how the type deals with signs.

Return

-1 signed, 1 unsigned, 0 not relevant for this type

struct fy_type_kind_info

struct fy_type_kind_info: Information about types

Definition

struct fy_type_kind_info {
    enum fy_type_kind kind;
    const char *name;
    const char *enum_name;
    size_t size;
    size_t align;
}

Members

kind: The type’s kind id
name: The name of the type (i.e. int, struct)
enum_name: The name of the type_kind enum (for code generation)
size: The size of the type
align: The alignment of the type

Description

This structure contains information about each type kind we defined.

fy_type_kind_info_get

const struct fy_type_kind_info *fy_type_kind_info_get(enum fy_type_kind type_kind)

Get the type info of a type from it’s id

Parameters:

type_kind (enum fy_type_kind) – The type_kind

Description

Retrieve the type info structure from a type kind id.

Return

The info structure that corresponds to the id, or NULL if invalid argument

fy_type_kind_size

size_t fy_type_kind_size(enum fy_type_kind type_kind)

Find out the type kind’s size

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Return the size of the type kind

Return

The size of the type kind or 0 on error

fy_type_kind_align

size_t fy_type_kind_align(enum fy_type_kind type_kind)

Find out the type kind’s align

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Return the align of the type kind

Return

The align of the type kind or 0 on error

fy_type_kind_name

const char *fy_type_kind_name(enum fy_type_kind type_kind)

Find out the type kind’s name

Parameters:

type_kind (enum fy_type_kind) – The type_kind to check

Description

Return the name of the type kind

Return

The name of the type kind or NULL on error

enum fy_field_info_flags

enum fy_field_info_flags: Flags for a field entry

Definition

enum fy_field_info_flags {
    FYFIF_BITFIELD,
    FYFIF_ENUM_UNSIGNED
};

Constants

FYFIF_BITFIELD: Set if the field is a bitfield and not a regular field
FYFIF_ENUM_UNSIGNED: Set if the enum value is unsigned

enum fy_type_info_flags

enum fy_type_info_flags: Flags for a a type info entry

Definition

enum fy_type_info_flags {
    FYTIF_CONST,
    FYTIF_VOLATILE,
    FYTIF_RESTRICT,
    FYTIF_ELABORATED,
    FYTIF_ANONYMOUS,
    FYTIF_ANONYMOUS_RECORD_DECL,
    FYTIF_ANONYMOUS_GLOBAL,
    FYTIF_ANONYMOUS_DEP,
    FYTIF_INCOMPLETE,
    FYTIF_UNRESOLVED,
    FYTIF_MAIN_FILE,
    FYTIF_SYSTEM_HEADER
};

Constants

FYTIF_CONST: Const qualifier for this type enabled
FYTIF_VOLATILE: Volatile qualifier for this type enabled
FYTIF_RESTRICT: Restrict qualified for this type enabled
FYTIF_ELABORATED: Type is a named type with a qualifier
FYTIF_ANONYMOUS: The type is anonymous, ie. declared in place.
FYTIF_ANONYMOUS_RECORD_DECL: The type is anonymous, and is a record
FYTIF_ANONYMOUS_GLOBAL: The type is a global anonymous type
FYTIF_ANONYMOUS_DEP: The dependent type is anonymous
FYTIF_INCOMPLETE: Incomplete type
FYTIF_UNRESOLVED: This type is unresolved (cannot be serialized as is)
FYTIF_MAIN_FILE: The type was declared in the main file of an import
FYTIF_SYSTEM_HEADER: The type was declared in a system header

fy_type_info_get_kind

enum fy_type_kind fy_type_info_get_kind(const struct fy_type_info *ti)

Get the type kind

Parameters:

ti (const struct fy_type_info*) – The type info

Return

The kind of this type (e.g. FYTK_STRUCT, FYTK_INT, …)

fy_type_info_get_flags

enum fy_type_info_flags fy_type_info_get_flags(const struct fy_type_info *ti)

Get the type info flags

Parameters:

ti (const struct fy_type_info*) – The type info

Return

Bitfield of enum fy_type_info_flags for this type

fy_type_info_get_name

const char *fy_type_info_get_name(const struct fy_type_info *ti)

Get the fully qualified name of the type

Parameters:

ti (const struct fy_type_info*) – The type info

Description

ti (const struct fy_type_info*) – The type info

Description

For pointers, typedefs, enums (underlying integer type), and arrays (element type) returns the referenced type. NULL for all others.

Return

The dependent type, or NULL if not applicable

fy_type_info_get_count

size_t fy_type_info_get_count(const struct fy_type_info *ti)

Get the field count or array element count

Parameters:

ti (const struct fy_type_info*) – The type info

Description

For struct/union/enum types this is the number of fields/constants. For FYTK_CONSTARRAY this is the fixed element count. Zero for all other types.

Return

The count

fy_type_info_get_field_at

const struct fy_field_info *fy_type_info_get_field_at(const struct fy_type_info *ti, size_t idx)

Get a field of a type by index

Parameters:

ti (const struct fy_type_info*) – The type info
idx (size_t) – Field index (0-based)

Description

fi (const struct fy_field_info*) – The field info

Description

Valid only when !(fy_field_info_get_flags(fi) & FYFIF_BITFIELD).

Return

Byte offset from the start of the enclosing struct/union

fy_field_info_get_bit_offset

size_t fy_field_info_get_bit_offset(const struct fy_field_info *fi)

Get the bit offset of a bitfield

Parameters:

fi (const struct fy_field_info*) – The field info

Description

Valid only when fy_field_info_get_flags(fi) & FYFIF_BITFIELD.

Return

Bit offset from the start of the enclosing struct/union

fy_field_info_get_bit_width

size_t fy_field_info_get_bit_width(const struct fy_field_info *fi)

Get the width of a bitfield in bits

Parameters:

fi (const struct fy_field_info*) – The field info

Description

Valid only when fy_field_info_get_flags(fi) & FYFIF_BITFIELD.

Return

Width of the bitfield in bits

fy_field_info_get_enum_value

intmax_t fy_field_info_get_enum_value(const struct fy_field_info *fi)

Get the signed value of an enum constant

Parameters:

fi (const struct fy_field_info*) – The field info

Description

Valid only for fields of an enum type info.

Return

The signed enum constant value

fy_field_info_get_unsigned_enum_value

uintmax_t fy_field_info_get_unsigned_enum_value(const struct fy_field_info *fi)

Get the unsigned value of an enum constant

Parameters:

fi (const struct fy_field_info*) – The field info

Description

backend_name (const char*) – The name of the backend
backend_cfg (const void*) – The configuration of the backend
num_imports (int) – The number of imports
import_cfgs (const void*) – The array of import configs.
diag (struct fy_diag*) – The diagnostic object

Description

Create a reflection by the imports of the given backend.

Return

The reflection pointer, or NULL if an error occured.

fy_reflection_from_import

struct fy_reflection *fy_reflection_from_import(const char *backend_name, const void *backend_cfg, const void *import_cfg, struct fy_diag *diag)

Create a reflection from an import

Parameters:

backend_name (const char*) – The name of the backend
backend_cfg (const void*) – The configuration of the backend
import_cfg (const void*) – The import configuration
diag (struct fy_diag*) – The diagnostic object

Description

Create a reflection by a single import of the given backend.

Return

The reflection pointer, or NULL if an error occured.

fy_reflection_from_c_files

struct fy_reflection *fy_reflection_from_c_files(int filec, const char *const filev, int argc, const char *const argv, bool display_diagnostics, bool include_comments, struct fy_diag *diag)

Create a reflection from C files

Parameters:

filec (int) – Number of files
filev (const char *const) – An array of files
argc (int) – Number of arguments to pass to libclang
argv (const char *const) – Arguments to pass to libclang
display_diagnostics (bool) – Display diagnostics (useful in case of errors)
include_comments (bool) – Include comments in the type database
diag (struct fy_diag*) – The diagnostic object to use (or NULL for default)

Description

Create a reflection from C source files

Return

The reflection pointer, or NULL if an error occured.

fy_reflection_from_c_file

struct fy_reflection *fy_reflection_from_c_file(const char *file, int argc, const char *const argv, bool display_diagnostics, bool include_comments, struct fy_diag *diag)

Create a reflection from a single C file

Parameters:

file (const char*) – The C file
argc (int) – Number of arguments to pass to libclang
argv (const char *const) – Arguments to pass to libclang
display_diagnostics (bool) – Display diagnostics (useful in case of errors)
include_comments (bool) – Include comments in the type database
diag (struct fy_diag*) – The diagnostic object to use (or NULL for default)

Description

Create a reflection from a single C source file

Return

The reflection pointer, or NULL if an error occured.

fy_reflection_from_c_file_with_cflags

struct fy_reflection *fy_reflection_from_c_file_with_cflags(const char *file, const char *cflags, bool display_diagnostics, bool include_comments, struct fy_diag *diag)

Create a reflection from a single C file with CFLAGS

Parameters:

file (const char*) – The C file
cflags (const char*) – The C flags
display_diagnostics (bool) – Display diagnostics (useful in case of errors)
include_comments (bool) – Include comments in the type database
diag (struct fy_diag*) – The diagnostic object to use (or NULL for default)

Description

Create a reflection from a single C source file, using a simpler CFLAGS api

Return

The reflection pointer, or NULL if an error occured.

fy_reflection_from_packed_blob

struct fy_reflection *fy_reflection_from_packed_blob(const void *blob, size_t blob_size, struct fy_diag *diag)

Create a reflection from a packed blob

Parameters:

blob (const void*) – A pointer to the binary blob
blob_size (size_t) – The size of the blob
diag (struct fy_diag*) – The diagnostic object to use (or NULL for default)

Description

Create a reflection from a packed blob.

Return

The reflection pointer, or NULL if an error occured.

fy_reflection_to_packed_blob

void *fy_reflection_to_packed_blob(struct fy_reflection *rfl, size_t *blob_sizep, bool include_comments, bool include_location)

Create blob from a reflection

Parameters:

rfl (struct fy_reflection*) – The reflection
blob_sizep (size_t*) – Pointer to a variable to store the generated blobs size
include_comments (bool) – Include comments in the blob
include_location (bool) – Include the location information in the blob

Description

Create a packed blob from the given reflection

Return

A pointer to the blob, or NULL in case of an error

fy_reflection_from_packed_blob_file

struct fy_reflection *fy_reflection_from_packed_blob_file(const char *blob_file, struct fy_diag *diag)

Create a reflection from a packed blob file

Parameters:

blob_file (const char*) – The name of the blob file
diag (struct fy_diag*) – The diagnostic object to use (or NULL for default)

Description

Create a reflection from the given packed blob file

Return

The reflection pointer, or NULL if an error occured.

fy_reflection_to_packed_blob_file

int fy_reflection_to_packed_blob_file(struct fy_reflection *rfl, const char *blob_file)

Create a packed blob file from reflection

Parameters:

rfl (struct fy_reflection*) – The reflection
blob_file (const char*) – The name of the blob file

Description

Create a packed blob file from the given reflection

Return

0 on success, -1 on error

fy_reflection_from_null

struct fy_reflection *fy_reflection_from_null(struct fy_diag *diag)

Create a reflection for C basic types only

Parameters:

diag (struct fy_diag*) – The diagnostic object to use (or NULL for default)

Description

Create a reflection using only C basic types

Return

The reflection pointer, or NULL if an error occured.

fy_reflection_set_userdata

void fy_reflection_set_userdata(struct fy_reflection *rfl, void *userdata)

Set the userdata of a reflection

Parameters:

rfl (struct fy_reflection*) – The reflection
userdata (void*) – A void pointer that can be used to retreive the data

Description

Set the user data associated with the reflection

fy_reflection_get_userdata

void *fy_reflection_get_userdata(struct fy_reflection *rfl)

Get the userdata associated with a reflection

Parameters:

rfl (struct fy_reflection*) – The reflection

Description

Retrieve the user data associated with the given type via a previous call to fy_reflection_set_userdata().

Return

The userdata associated with the reflection, or NULL on error

fy_type_info_iterate

const struct fy_type_info *fy_type_info_iterate(struct fy_reflection *rfl, void **prevp)

Iterate over the types of the reflection

Parameters:

rfl (struct fy_reflection*) – The reflection
prevp (void**) – The previous type sequence iterator

Description

This method iterates over all the types of a reflection. The start of the iteration is signalled by a NULL in *prevp.

Return

The next type in sequence or NULL at the end of the type sequence.

fy_type_info_with_qualifiers

const struct fy_type_info *fy_type_info_with_qualifiers(const struct fy_type_info *ti, enum fy_type_info_flags qual_flags)

Get type info with specified qualifiers

Parameters:

ti (const struct fy_type_info*) – The type info
qual_flags (enum fy_type_info_flags) – The qualifier flags to apply

Description

Return a type info with the specified qualifier flags applied. This allows you to get const, volatile, or other qualified versions of a type.

Return

The type info with qualifiers applied, or NULL on error

fy_type_info_unqualified

const struct fy_type_info *fy_type_info_unqualified(const struct fy_type_info *ti)

Get unqualified type info

Parameters:

ti (const struct fy_type_info*) – The type info

Description

Return the unqualified version of a type (removing const, volatile, etc.)

Return

The unqualified type info, or NULL on error

fy_type_info_to_reflection

struct fy_reflection *fy_type_info_to_reflection(const struct fy_type_info *ti)

Get the reflection a type belongs to

Parameters:

ti (const struct fy_type_info*) – The type info

Description

Return the reflection this type belongs to

Return

The reflection this type belongs to, or NULL if bad ti argument

fy_type_info_generate_name

char *fy_type_info_generate_name(const struct fy_type_info *ti, const char *field)

Generate a name for a type

Parameters:

ti (const struct fy_type_info*) – The type info
field (const char*) – The field if using the call to generate a field definition or NULL if not.

Description

Generate a name from the type by traversing the type definitions down to their dependent primitive types.

Return

A malloc()‘ed pointer to the name, or NULL in case of an error. This pointer must be free()‘d when the caller is done with it.

fy_field_info_generate_name

char *fy_field_info_generate_name(const struct fy_field_info *fi)

Generate a name for a field

Parameters:

fi (const struct fy_field_info*) – The field info

Description

Generate a name for a field by combining the field’s name with its type. Similar to fy_type_info_generate_name() but specifically for fields.

Return

A malloc()‘ed pointer to the name, or NULL in case of an error. This pointer must be free()‘d when the caller is done with it.

fy_type_info_lookup

const struct fy_type_info *fy_type_info_lookup(struct fy_reflection *rfl, const char *name)

Lookup for a type by a definition

Parameters:

rfl (struct fy_reflection*) – The reflection
name (const char*) – The name of type (i.e. “struct foo”)

Description

ti (const struct fy_type_info*) – The type info

Description

Check the mark of a type

Return

true if the type is marked, false otherwise

fy_type_info_eponymous_offset

size_t fy_type_info_eponymous_offset(const struct fy_type_info *ti)

Offset of an anonymous type from the closest eponymous parent type.

Parameters:

ti (const struct fy_type_info*) – The anonymous type

Description

For anonymous types, get the offset from the start of the enclosing eponymous type. For example:

struct baz {
  int foo;
  struct { // <- anonymous
    int bar; // <- offset from baz
  } bar;
};

Return

The offset from the closest eponymous parent type or 0 if not anonymous

fy_type_info_get_comment

const char *fy_type_info_get_comment(const struct fy_type_info *ti)

Get the comment for a type

Parameters:

ti (const struct fy_type_info*) – The type info

Description

Retrieve the ‘cooked’ comment for a type. The cooking consists of (trying) to remove comment formatting. For example:

// this is a comment
//   which requires cooking

Would be cooked as:

this is a comment
  which requires cooking

Return

The cooked comment, or NULL

fy_field_info_get_comment

const char *fy_field_info_get_comment(const struct fy_field_info *fi)

Get the comment for a field

Parameters:

fi (const struct fy_field_info*) – The field info

Description

Retrieve the ‘cooked’ comment for a field. The cooking consists of (trying) to remove comment formatting. For example:

// this is a comment
//   which requires cooking

Would be cooked as:

this is a comment
  which requires cooking

Return

The cooked comment, or NULL

fy_type_info_get_yaml_annotation

struct fy_document *fy_type_info_get_yaml_annotation(const struct fy_type_info *ti)

Get the yaml annotation of this type

Parameters:

ti (const struct fy_type_info*) – The type info

Description

Retrieve a document containing the yaml keyword annotations of this type

Return

The yaml annotation document or NULL

fy_type_info_get_yaml_comment

const char *fy_type_info_get_yaml_comment(const struct fy_type_info *ti)

Get the yaml annotation of this type as string

Parameters:

ti (const struct fy_type_info*) – The type info

Description

Retrieve a document containing the yaml keyword annotations of this type as a string

Return

The yaml comment or NULL

fy_type_info_get_id

int fy_type_info_get_id(const struct fy_type_info *ti)

Get the unique ID of a type

Parameters:

ti (const struct fy_type_info*) – The type info

Description

Retrieve the unique identifier for this type within its reflection context. Each type in a reflection has a distinct ID.

Return

The type ID if >= 0, -1 on error

fy_field_info_get_yaml_annotation

struct fy_document *fy_field_info_get_yaml_annotation(const struct fy_field_info *fi)

Get the yaml annotation document for this field

Parameters:

fi (const struct fy_field_info*) – The field info

Description

Retrieve a document containing the yaml keyword annotations of this field

Return

The yaml annotation document, or NULL

fy_field_info_get_yaml_comment

const char *fy_field_info_get_yaml_comment(const struct fy_field_info *fi)

Get the YAML comment for this field

Parameters:

fi (const struct fy_field_info*) – The field info

Description

Retrieve the YAML comment associated with this field from its annotations.

Return

The YAML comment string, or NULL if no comment exists

fy_reflection_dump

void fy_reflection_dump(struct fy_reflection *rfl, bool marked_only, bool no_location)

Dump the internal type database to stderr

Parameters:

rfl (struct fy_reflection*) – The reflection to dump
marked_only (bool) – If true, dump only types that have been marked (see fy_type_info_mark()); if false, dump all types
no_location (bool) – If true, omit source file/line location information from the output

Description

Print a human-readable description of every type (or only the marked types) in the reflection’s registry to stderr. Primarily a debugging aid.

enum fy_c_generation_flags

enum fy_c_generation_flags: Flags controlling C code generation output format

Definition

enum fy_c_generation_flags {
    FYCGF_INDENT_TAB,
    FYCGF_INDENT_SPACES_2,
    FYCGF_INDENT_SPACES_4,
    FYCGF_INDENT_SPACES_8,
    FYCGF_COMMENT_NONE,
    FYCGF_COMMENT_RAW,
    FYCGF_COMMENT_YAML
};

Constants

FYCGF_INDENT_TAB: Use a hard tab character for each indentation level
FYCGF_INDENT_SPACES_2: Use two spaces per indentation level
FYCGF_INDENT_SPACES_4: Use four spaces per indentation level
FYCGF_INDENT_SPACES_8: Use eight spaces per indentation level
FYCGF_COMMENT_NONE: Omit all comments from the generated output
FYCGF_COMMENT_RAW: Emit the original raw source comment verbatim
FYCGF_COMMENT_YAML: Emit only the yaml: annotation portion of the comment, formatted as a single-line // comment

Description

Pass a bitwise OR of one indentation choice and one comment choice to fy_reflection_generate_c() or fy_reflection_generate_c_string(). The default combination is FYCGF_INDENT_TAB | FYCGF_COMMENT_NONE.

fy_reflection_generate_c

int fy_reflection_generate_c(struct fy_reflection *rfl, enum fy_c_generation_flags flags, FILE *fp)

Generate C code from reflection type information

Parameters:

rfl (struct fy_reflection*) – The reflection
flags (enum fy_c_generation_flags) – Generation flags controlling output format (indentation, comments)
fp (FILE*) – The file pointer to write to

Description

Generate C code (struct definitions, typedefs, etc.) from the reflection’s type database and write it to a file pointer. This can be used to recreate C header files from reflection metadata. The output format is controlled by the flags parameter which specifies indentation style and comment format.

Return

0 on success, -1 on error

fy_reflection_generate_c_string

char *fy_reflection_generate_c_string(struct fy_reflection *rfl, enum fy_c_generation_flags flags)

Generate C code from reflection as a string

Parameters:

rfl (struct fy_reflection*) – The reflection
flags (enum fy_c_generation_flags) – Generation flags controlling output format (indentation, comments)

Description

Generate C code (struct definitions, typedefs, etc.) from the reflection’s type database and return it as an allocated string. This is similar to fy_reflection_generate_c() but returns the result as a string instead of writing to a file. The output format is controlled by the flags parameter.

Return

A malloc()‘ed pointer to the generated C code, or NULL on error. This pointer must be free()‘d when the caller is done with it.

fy_field_info_index

int fy_field_info_index(const struct fy_field_info *fi)

Get the index of a field of a type

Parameters:

fi (const struct fy_field_info*) – The pointer to the field info

Description

Retrieve the 0-based index of a field info. The first structure member is 0, the second 1 etc.

Return

The index of the field if >= 0, -1 on error

fy_type_info_lookup_field

const struct fy_field_info *fy_type_info_lookup_field(const struct fy_type_info *ti, const char *name)

Lookup a field of a type by name

Parameters:

ti (const struct fy_type_info*) – The pointer to the type info
name (const char*) – The name of the field

Description

Lookup the field with the given name on the given type.

Return

A pointer to the field info if field was found, NULL otherwise

fy_type_info_lookup_field_by_enum_value

const struct fy_field_info *fy_type_info_lookup_field_by_enum_value(const struct fy_type_info *ti, intmax_t val)

Lookup an enum field of a type by value

Parameters:

ti (const struct fy_type_info*) – The pointer to the type info
val (intmax_t) – The value of the enumeration

Description

Lookup the field with the enum value on the given type.

Return

A pointer to the field info if field was found, NULL otherwise

fy_type_info_lookup_field_by_unsigned_enum_value

const struct fy_field_info *fy_type_info_lookup_field_by_unsigned_enum_value(const struct fy_type_info *ti, uintmax_t val)

Lookup an enum field of a type by unsigned 0value

Parameters:

ti (const struct fy_type_info*) – The pointer to the type info
val (uintmax_t) – The value of the enumeration

Description

Lookup the field with the enum value on the given type.

Return

A pointer to the field info if field was found, NULL otherwise

enum fy_type_context_cfg_flags

enum fy_type_context_cfg_flags: Optional creation flags for fy_type_context_create()

Definition

enum fy_type_context_cfg_flags {
    FYTCCF_DUMP_REFLECTION,
    FYTCCF_DUMP_TYPE_SYSTEM,
    FYTCCF_DEBUG,
    FYTCCF_STRICT_ANNOTATIONS
};

Constants

FYTCCF_DUMP_REFLECTION: Dump raw reflection structures during context creation
FYTCCF_DUMP_TYPE_SYSTEM: Dump the meta-type tree after it is built
FYTCCF_DEBUG: Enable verbose debug logging during type tree construction
FYTCCF_STRICT_ANNOTATIONS: Treat unknown annotation keys as errors instead of notices. Use this in build/CI pipelines to catch annotation typos early.

struct fy_type_context_cfg

struct fy_type_context_cfg: Configuration for fy_type_context_create()

Definition

struct fy_type_context_cfg {
    struct fy_reflection *rfl;
    const char *entry_type;
    const char *entry_meta;
    struct fy_diag *diag;
    unsigned int flags;
}

Members

rfl: Reflection object (must be non-NULL)
entry_type: Name of the entry C type, e.g. “struct server_config”
entry_meta: Optional YAML annotation string overriding the type’s own annotation; pass NULL to use the annotation from the C source
diag: Optional diagnostic object; NULL = use a default stderr diagnoser
flags: Bitwise OR of enum fy_type_context_cfg_flags (0 = defaults)

enum fy_type_context_emit_flags

enum fy_type_context_emit_flags: Flags controlling stream/document delimiters

Definition

enum fy_type_context_emit_flags {
    FYTCEF_SS,
    FYTCEF_DS,
    FYTCEF_DE,
    FYTCEF_SE
};

Constants

FYTCEF_SS: Emit a STREAM-START event before the document
FYTCEF_DS: Emit a DOCUMENT-START event
FYTCEF_DE: Emit a DOCUMENT-END event
FYTCEF_SE: Emit a STREAM-END event after the document

fy_type_context_create

struct fy_type_context *fy_type_context_create(const struct fy_type_context_cfg *cfg)

Create a type context from a reflection object

Parameters:

cfg (const struct fy_type_context_cfg*) – Configuration (must be non-NULL; cfg->rfl and cfg->entry_type required)

Description

Builds the meta-type tree for the given entry type, resolving all annotations and specialisations. Returns NULL on error.

Return

A new context object, or NULL on failure.

fy_type_context_destroy

void fy_type_context_destroy(struct fy_type_context *ctx)

Destroy a type context

Parameters:

ctx (struct fy_type_context*) – Context to destroy (may be NULL)

Description

Frees all meta types and fields owned by this context.

fy_type_context_parse

int fy_type_context_parse(struct fy_type_context *ctx, struct fy_parser *fyp, void **datap)

Parse a YAML stream into a C data structure

Parameters:

ctx (struct fy_type_context*) – Type context
fyp (struct fy_parser*) – Parser positioned at the start of input
datap (void**) – Output pointer; set to the parsed C struct on success

Description

Reads one document from fyp and populates a newly allocated C struct whose type is the context’s entry type. The caller is responsible for freeing the returned data with fy_type_context_free_data().

The parser must be positioned just before or at a STREAM-START / DOCUMENT-START event.

Return

0 on success, negative on error.

fy_type_context_emit

int fy_type_context_emit(struct fy_type_context *ctx, struct fy_emitter *emit, const void *data, unsigned int flags)

Emit a C data structure as YAML

Parameters:

ctx (struct fy_type_context*) – Type context
emit (struct fy_emitter*) – Emitter
data (const void*) – Pointer to the C struct to serialise
flags (unsigned int) – Combination of FYTCEF_SS / FYTCEF_DS / FYTCEF_DE / FYTCEF_SE

Description

Serialises data (which must be a pointer to a C struct of the entry type) using the emitter emit. Stream/document boundary events are controlled by flags (bitwise OR of enum fy_type_context_emit_flags).

Return

0 on success, negative on error.

fy_type_context_free_data

void fy_type_context_free_data(struct fy_type_context *ctx, void *data)

Free C data allocated by fy_type_context_parse()

Parameters:

ctx (struct fy_type_context*) – Type context that produced data
data (void*) – Data pointer returned by fy_type_context_parse()

Description

Runs destructors for pointer fields and releases the top-level allocation.

fy_type_context_get_root

const struct fy_meta_type *fy_type_context_get_root(const struct fy_type_context *ctx)

Return the root meta type of a context

Parameters:

ctx (const struct fy_type_context*) – Type context

Description

rfl (struct fy_reflection*) – Reflection object to filter (must be non-NULL)
type_include (const char*) – Regex for type names to keep; NULL = keep all
type_exclude (const char*) – Regex for type names to drop; NULL = drop none

Description

Marks types whose name matches type_include (if non-NULL) and does not match type_exclude (if non-NULL), then prunes all unmarked types. Both patterns are POSIX extended regular expressions.

Return

0 on success, -1 on regex compilation error.

fy_reflection_equal

bool fy_reflection_equal(struct fy_reflection *rfl_a, struct fy_reflection *rfl_b)

Test whether two reflection objects are equivalent

Parameters:

rfl_a (struct fy_reflection*) – First reflection object
rfl_b (struct fy_reflection*) – Second reflection object

Description

Iterates both reflection objects in order and compares each type_info structurally. Useful for verifying packed round-trips.

Return

true if the objects are equivalent, false otherwise.