capi

The C target, capi, generates the C API of the header, into <output>/capi:

lib<prefix>.h

The C API: the declarations of the header, and of the pretty-printers. It is generated from the IR, not copied from the header, and may use what C allows and the C subset does not. A packed record keeps its __attribute__((packed)), which the C++ layer, including it, shares.

<prefix>_pp.c

The pretty-printers. Every struct and union with fields gets <name>_fpr(), printing to a stream, and <name>_pr(), printing to stdout, as YAML, the default, or as JSON on one line. The flags are those of enum <prefix>_pr: <PREFIX>_PR_DEF, <PREFIX>_PR_YAML, <PREFIX>_PR_TERSE and <PREFIX>_PR_JSON. A printer prints JSON when the bit of <PREFIX>_PR_JSON is set, and YAML otherwise; terse output is not generated, so <PREFIX>_PR_TERSE prints YAML. Every enum gets <name>_str(), the name of a value. A field of bits, see The C Subset, is printed as a mapping on one line of its value, val, and of each of its parts, by bit, in hexadecimal in YAML, code: {val: 0x8a05, type: 0x5, dnr: 0x1}, and in decimal in JSON. The printers of the other targets print the same.

<prefix>_check.c

The check, not part of the API: it asserts at compile time that every record with fields has the size, alignment and field offsets recorded in the IR, then prints a zeroed instance of each, as YAML or JSON.

<prefix>_signatures.c

The check of the signatures, not part of the API: it includes the headers the IR was parsed from, not the generated C API, and asserts at compile time that each function has the type the IR gives it. Every target declares the functions from the IR, and C++, Go and the .pxd call them through lib<prefix>.h, so a signature the IR got wrong fails here rather than at run time.

The check is built with $CC, by default cc, as C11 with all warnings as errors, and run; yace then parses what it printed, as YAML and as JSON. The layout is asserted only on the platform it was recorded on, the abi of the IR’s meta.

The check of the signatures is compiled, as GNU C11, with the include directories, which hold the headers when they were given by path, or by -I. Where a header is not found, yace warns that the signatures are not checked, and fails nothing. The check of the signatures does not say whether a library was built from these headers; that is for a tool comparing the library’s ABI with them, such as abidiff.

capi_pp

The capi_pp target generates the pretty-printers alone, into <output>/capi_pp. The option form chooses how they are compiled: library, the default, for an API to compile into its own library, or header, for a program to include. The library form writes:

lib<prefix>_pp.h

The declarations of the pretty-printers and of enum <prefix>_pr. It includes the headers the IR was parsed from, after the standard headers and the prelude the parser includes ahead of them, rather than the generated C API.

<prefix>_pp.c

The pretty-printers, as the C target generates them, including lib<prefix>_pp.h.

<prefix>_check.c

The check, as the C target’s, over the headers the IR was parsed from.

The check is compiled, as GNU C11 with all warnings as errors, with the include directories, and fails where a header is not found in them. The headers must not declare printers of their own, as the rule printer-name says; they would conflict with the generated ones.

The header form, --target-option capi_pp.form=header, writes no <prefix>_pp.c. lib<prefix>_pp.h then defines every printer and every _str() function as static inline, and the helpers they call as static, so a file that calls no printer gets no code of them, and a file that calls one printer gets that printer and the helpers it calls. GCC compiles the helpers into every file that includes the header when it does not optimize, at -O0. The helpers are under the include guard YACE_PP_HELPERS, so a file can include the printer headers of several runs of yace, as long as each run has a prefix of its own.

Example

yace output/foo.yaml --emit capi --output output
output/capi
├── cc.log
├── check.json
├── check.yaml
├── foo_check
├── foo_check.c
├── foo_pp.c
├── foo_signatures.c
├── libfoo.h
└── signatures.log

1 directory, 9 files

C API

../../../../output/capi/libfoo.h
/**
 * libfoo: An example library described in the C subset of yace
 *
 * Copyright (C) Simon A. F. Lund <os@safl.dk>
 * SPDX-License-Identifier: GPL-2.0-only
 *
 * @file libfoo.h
 *
 * Generated by yace from foo.h; do not edit.
 */
#ifndef LIBFOO_H
#define LIBFOO_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <sys/types.h>

/**
 * Name of the library
 */
#define FOO_NAME "foo"

/**
 * A hexadecimal constant
 */
#define FOO_MAGIC 0xacdc

/**
 * Major version
 */
#define FOO_VERSION_MAJOR 1

/**
 * Minor version
 */
#define FOO_VERSION_MINOR 2

/**
 * Patch version
 */
#define FOO_VERSION_PATCH 3

/**
 * Points a handle holds at most
 */
#define FOO_POINTS_MAX 8

/**
 * A constant, by name
 */
#define FOO_DEFAULT_SHAPE_SIDES 8

/**
 * A count is submitted and not yet completed; bit 0 of 'code'
 */
#define FOO_STATUS_CODE_PENDING 0x1

/**
 * Points held; bits 11:4 of 'code'
 */
#define FOO_STATUS_CODE_POINTS 0xff0

/**
 * The handle holds FOO_POINTS_MAX points; bit 15 of 'code'
 */
#define FOO_STATUS_CODE_FULL 0x8000

/**
 * Kinds of figure
 */
enum foo_shape {
	FOO_SHAPE_NONE = -1,   ///< No figure
	FOO_SHAPE_POINT = 0,   ///< A single point
	FOO_SHAPE_LINE = 1,    ///< Two points
	FOO_SHAPE_POLYGON = 2, ///< Three points or more
};

/**
 * Options of a figure, combined as bits
 */
enum foo_option {
	FOO_OPTION_CLOSED = 1, ///< The last corner connects to the first
	FOO_OPTION_FILLED = 2, ///< The inside is filled
};

/**
 * A collection of points, opened with foo_open() and closed with foo_close()
 */
struct foo_handle;
struct foo_point;
struct foo_visitor;
struct foo_scalars;
struct foo_figure;
union foo_value;
struct foo_wire;
struct foo_status;

/**
 * Called back with each point visited
 *
 * @param arg The argument given along with the callback
 * @param point The point visited
 * @return 0 to go on, anything else to stop
 */
typedef int (*foo_visit_cb)(void *arg, const struct foo_point *point);

/**
 * Called back when a count submitted completes
 *
 * @param arg The argument given along with the callback
 * @param count The number of points when it completed
 */
typedef void (*foo_done_cb)(void *arg, size_t count);

/**
 * Called back with each point added to a handle watched
 *
 * @param arg The argument given along with the callback
 * @param point The point added
 */
typedef void (*foo_added_cb)(void *arg, const struct foo_point *point);

/**
 * A point on the plane
 */
struct foo_point {
	int32_t x; ///< Horizontal position
	int32_t y; ///< Vertical position
};

/**
 * A callback and its argument
 */
struct foo_visitor {
	foo_visit_cb visit; ///< Called for each point
	void *arg;          ///< Given to 'visit'
};

/**
 * A value of every kind of scalar
 */
struct foo_scalars {
	bool flag;              ///< bool
	char letter;            ///< char
	signed char schar;      ///< signed char
	unsigned char uchar;    ///< unsigned char
	short s;                ///< short
	unsigned short us;      ///< unsigned short
	int i;                  ///< int
	unsigned int ui;        ///< unsigned int
	long l;                 ///< long
	unsigned long ul;       ///< unsigned long
	long long ll;           ///< long long
	unsigned long long ull; ///< unsigned long long
	float f;                ///< float
	double d;               ///< double
	int8_t i8;              ///< int8_t
	int16_t i16;            ///< int16_t
	int32_t i32;            ///< int32_t
	int64_t i64;            ///< int64_t
	uint8_t u8;             ///< uint8_t
	uint16_t u16;           ///< uint16_t
	uint32_t u32;           ///< uint32_t
	uint64_t u64;           ///< uint64_t
	intptr_t iptr;          ///< intptr_t
	uintptr_t uptr;         ///< uintptr_t
	size_t size;            ///< size_t
	ssize_t ssize;          ///< ssize_t
	ptrdiff_t diff;         ///< ptrdiff_t
};

/**
 * A figure: its kind, where it is, and its corners
 */
struct foo_figure {
	uint32_t shape;              ///< One of enum foo_shape
	uint32_t options;            ///< Bits of enum foo_option
	struct foo_point origin;     ///< Where the figure is
	struct foo_point corners[4]; ///< The corners, relative to 'origin'
	uint8_t ncorners;            ///< How many of 'corners' are used
	char name[16];               ///< Name of the figure
	int16_t grid[2][3];          ///< A two-dimensional array
	const char *label;           ///< A string, NULL when there is none
	float scale;                 ///< Scale of the figure
	double area;                 ///< Area of the figure
};

/**
 * A 32-bit value, read as signed, as unsigned, or as the 'x' of a point
 */
union foo_value {
	int32_t i;              ///< Signed
	uint32_t u;             ///< Unsigned
	struct foo_point point; ///< A point, its 'x' sharing the bits of 'i'
};

/**
 * A record laid out without padding, as a wire format is: no field after the
 * first is aligned
 */
struct __attribute__((packed)) foo_wire {
	uint8_t kind;        ///< One of enum foo_shape
	uint32_t length;     ///< At offset 1
	struct foo_point at; ///< A point, at offset 5
	uint16_t pair[2];    ///< An array, at offset 13
};

/**
 * The status of a handle, its code a field of bits
 */
struct foo_status {
	uint16_t code; ///< Status code, see FOO_STATUS_CODE_*
	uint16_t max;  ///< Points the handle holds at most
};

/**
 * The version of the library
 *
 * @return The version, as "MAJOR.MINOR.PATCH"
 */
const char *
foo_version(void);

/**
 * Why the call that failed last on the calling thread failed
 *
 * A function that returns a negative errno keeps a message saying what the
 * errno does not, such as the name of the handle that is full. The meta names
 * this function as 'errmsg', so that the error of a binding holds the message.
 *
 * @return The message, owned by the library and valid until the next call fails
 *   on the calling thread; "" when no call has failed
 */
const char *
foo_errmsg(void);

/**
 * Open a handle holding no points
 *
 * @param[in] name Name of the handle, copied
 * @param[out] handle Set to the handle opened
 * @return 0 on success, -EINVAL when 'name' or 'handle' is NULL, -ENOMEM when
 *   memory ran out
 * @errno
 */
int
foo_open(const char *name, struct foo_handle **handle);

/**
 * Close a handle
 *
 * @param handle The handle to close, NULL is ignored
 * @nullable handle
 * @destroys handle
 */
void
foo_close(struct foo_handle *handle);

/**
 * The name the handle was opened with
 *
 * @param handle The handle
 * @return The name, owned by the handle
 */
const char *
foo_name(const struct foo_handle *handle);

/**
 * Add a point to the handle
 *
 * @param handle The handle
 * @param[in] point The point to add, copied
 * @return 0 on success, -ENOSPC when the handle holds FOO_POINTS_MAX points
 * @errno
 */
int
foo_point_add(struct foo_handle *handle, const struct foo_point *point);

/**
 * Add points to the handle, as many as it has room for
 *
 * @param handle The handle
 * @arrparam[in] points The points to add, copied
 * @param points_len The number of points
 * @return The number of points added, -ENOSPC when there was room for none
 * @errno
 */
ssize_t
foo_point_add_many(struct foo_handle *handle, const struct foo_point *points, size_t points_len);

/**
 * The number of points held
 *
 * @param handle The handle
 * @return The number of points
 */
size_t
foo_point_count(const struct foo_handle *handle);

/**
 * A point held by the handle
 *
 * @param handle The handle
 * @param idx Index of the point
 * @return The point, NULL when 'idx' is past the last one
 * @nullable return
 */
const struct foo_point *
foo_point_get(const struct foo_handle *handle, size_t idx);

/**
 * Copy the points held, as many as fit
 *
 * @param handle The handle
 * @arrparam[out] points Where to copy the points to
 * @param points_len The number of points that fit
 * @return The number of points copied
 * @errno
 */
ssize_t
foo_point_copy(const struct foo_handle *handle, struct foo_point *points, size_t points_len);

/**
 * Watch the points added to the handle, from now until it is closed
 *
 * @param handle The handle
 * @param added Called with each point added, until the handle is closed
 * @param arg Given to 'added'
 * @return 0 on success, -EBUSY when the handle is watched already
 * @nullable arg
 * @lifetime added handle
 * @errno
 */
int
foo_point_watch(struct foo_handle *handle, foo_added_cb added, void *arg);

/**
 * Visit the points in the order they were added
 *
 * @param handle The handle
 * @param visit Called for each point, until it returns non-zero
 * @param arg Given to 'visit'
 * @return The number of points visited, -EINVAL when 'visit' is NULL
 * @nullable arg
 * @lifetime visit call
 * @errno
 */
ssize_t
foo_point_visit(struct foo_handle *handle, foo_visit_cb visit, void *arg);

/**
 * Visit the points with a visitor; as foo_point_visit()
 *
 * @param handle The handle
 * @param[in] visitor The callback and its argument
 * @return The number of points visited, -EINVAL when the callback is NULL
 * @errno
 */
ssize_t
foo_point_visit_with(struct foo_handle *handle, const struct foo_visitor *visitor);

/**
 * Submit a count of the points, completed by foo_count_complete()
 *
 * @param handle The handle
 * @param done Called once, by foo_count_complete(), with the number of points
 * @param arg Given to 'done'
 * @return 0, -EBUSY when a count is submitted and not yet completed
 * @nullable arg
 * @lifetime done once
 * @errno
 */
int
foo_count_submit(struct foo_handle *handle, foo_done_cb done, void *arg);

/**
 * Complete the count submitted, if any, calling its callback
 *
 * @param handle The handle
 * @return The number of counts completed, 0 or 1
 */
size_t
foo_count_complete(struct foo_handle *handle);

/**
 * The status of the handle
 *
 * @param handle The handle
 * @param[out] status The status to fill in
 */
void
foo_status_get(const struct foo_handle *handle, struct foo_status *status);

/**
 * Fill in a value of every kind of scalar, the limits of the fixed-width ones
 *
 * @param[out] scalars The values to fill in
 */
void
foo_scalars_fill(struct foo_scalars *scalars);

/**
 * Fill in a figure of the given shape
 *
 * @param[out] figure The figure to fill in
 * @param shape One of enum foo_shape
 * @return 0 on success, -EINVAL when 'shape' is none of enum foo_shape
 * @errno
 */
int
foo_figure_fill(struct foo_figure *figure, uint32_t shape);

/**
 * Set a value, clearing the bits it does not use
 *
 * @param[out] value The value to set
 * @param i What to set it to
 */
void
foo_value_set(union foo_value *value, int32_t i);

/**
 * Fill in a packed record
 *
 * @param[out] wire The record to fill in
 */
void
foo_wire_fill(struct foo_wire *wire);

/**
 * Output formats of the pretty-printers
 */
enum foo_pr {
	FOO_PR_DEF = 0x0,   ///< The default, YAML
	FOO_PR_YAML = 0x1,  ///< YAML
	FOO_PR_TERSE = 0x2, ///< Terse; the generated printers print YAML
	FOO_PR_JSON = 0x4,  ///< JSON, on one line
};

/**
 * Print the given struct foo_point to the given stream
 *
 * @param stream The stream to print to
 * @param obj The struct to print, NULL prints as null
 * @param flags The output format, one of enum foo_pr
 *
 * @return The number of characters written
 */
int
foo_point_fpr(FILE *stream, const struct foo_point *obj, int flags);

/**
 * Print the given struct foo_point to stdout
 *
 * @param obj The struct to print, NULL prints as null
 * @param flags The output format, one of enum foo_pr
 *
 * @return The number of characters written
 */
int
foo_point_pr(const struct foo_point *obj, int flags);

/**
 * Print the given struct foo_visitor to the given stream
 *
 * @param stream The stream to print to
 * @param obj The struct to print, NULL prints as null
 * @param flags The output format, one of enum foo_pr
 *
 * @return The number of characters written
 */
int
foo_visitor_fpr(FILE *stream, const struct foo_visitor *obj, int flags);

/**
 * Print the given struct foo_visitor to stdout
 *
 * @param obj The struct to print, NULL prints as null
 * @param flags The output format, one of enum foo_pr
 *
 * @return The number of characters written
 */
int
foo_visitor_pr(const struct foo_visitor *obj, int flags);

/**
 * Print the given struct foo_scalars to the given stream
 *
 * @param stream The stream to print to
 * @param obj The struct to print, NULL prints as null
 * @param flags The output format, one of enum foo_pr
 *
 * @return The number of characters written
 */
int
foo_scalars_fpr(FILE *stream, const struct foo_scalars *obj, int flags);

/**
 * Print the given struct foo_scalars to stdout
 *
 * @param obj The struct to print, NULL prints as null
 * @param flags The output format, one of enum foo_pr
 *
 * @return The number of characters written
 */
int
foo_scalars_pr(const struct foo_scalars *obj, int flags);

/**
 * Print the given struct foo_figure to the given stream
 *
 * @param stream The stream to print to
 * @param obj The struct to print, NULL prints as null
 * @param flags The output format, one of enum foo_pr
 *
 * @return The number of characters written
 */
int
foo_figure_fpr(FILE *stream, const struct foo_figure *obj, int flags);

/**
 * Print the given struct foo_figure to stdout
 *
 * @param obj The struct to print, NULL prints as null
 * @param flags The output format, one of enum foo_pr
 *
 * @return The number of characters written
 */
int
foo_figure_pr(const struct foo_figure *obj, int flags);

/**
 * Print the given union foo_value to the given stream
 *
 * @param stream The stream to print to
 * @param obj The union to print, NULL prints as null
 * @param flags The output format, one of enum foo_pr
 *
 * @return The number of characters written
 */
int
foo_value_fpr(FILE *stream, const union foo_value *obj, int flags);

/**
 * Print the given union foo_value to stdout
 *
 * @param obj The union to print, NULL prints as null
 * @param flags The output format, one of enum foo_pr
 *
 * @return The number of characters written
 */
int
foo_value_pr(const union foo_value *obj, int flags);

/**
 * Print the given struct foo_wire to the given stream
 *
 * @param stream The stream to print to
 * @param obj The struct to print, NULL prints as null
 * @param flags The output format, one of enum foo_pr
 *
 * @return The number of characters written
 */
int
foo_wire_fpr(FILE *stream, const struct foo_wire *obj, int flags);

/**
 * Print the given struct foo_wire to stdout
 *
 * @param obj The struct to print, NULL prints as null
 * @param flags The output format, one of enum foo_pr
 *
 * @return The number of characters written
 */
int
foo_wire_pr(const struct foo_wire *obj, int flags);

/**
 * Print the given struct foo_status to the given stream
 *
 * @param stream The stream to print to
 * @param obj The struct to print, NULL prints as null
 * @param flags The output format, one of enum foo_pr
 *
 * @return The number of characters written
 */
int
foo_status_fpr(FILE *stream, const struct foo_status *obj, int flags);

/**
 * Print the given struct foo_status to stdout
 *
 * @param obj The struct to print, NULL prints as null
 * @param flags The output format, one of enum foo_pr
 *
 * @return The number of characters written
 */
int
foo_status_pr(const struct foo_status *obj, int flags);

/**
 * The name of the given enum foo_shape value, "UNKNOWN" when it is none of them
 */
const char *
foo_shape_str(int value);

/**
 * The name of the given enum foo_option value, "UNKNOWN" when it is none of them
 */
const char *
foo_option_str(int value);

#ifdef __cplusplus
}
#endif

#endif /* LIBFOO_H */

Pretty-printers

../../../../output/capi/foo_pp.c
/**
 * libfoo: pretty-printers
 *
 * @file foo_pp.c
 *
 * Generated by yace from foo.h; do not edit.
 */
#include <inttypes.h>
#include <libfoo.h>

/* The printers are not on a fast path, so the helpers are not inlined;
 * inlined at every field, the helpers would make the printers larger */
#if defined(__GNUC__)
#define YACE_PP_HELPER __attribute__((noinline)) static
#else
#define YACE_PP_HELPER static
#endif

/* Where and how a record is printed: as JSON on one line, or as YAML with its
 * fields at 'indent'; in JSON, 'count' is the number of values printed in the
 * object or list, which a separator follows */
struct yace_pp {
	FILE *stream;
	int json;
	int indent;
	int count;
};

/* Print 'key' and what follows it; for a NULL key, the key of an element of a
 * list, print only the separator from the element before. A list is printed
 * as JSON, also in YAML, so a NULL key is never printed as YAML */
YACE_PP_HELPER int
yace_pp_key(struct yace_pp *pp, const char *key)
{
	if (!key) {
		return fprintf(pp->stream, "%s", pp->count++ ? ", " : "");
	}
	if (!pp->json) {
		return fprintf(pp->stream, "%*s%s: ", pp->indent, "", key);
	}

	return fprintf(pp->stream, "%s\"%s\": ", pp->count++ ? ", " : "", key);
}

YACE_PP_HELPER int
yace_pp_eol(struct yace_pp *pp)
{
	return pp->json ? 0 : fprintf(pp->stream, "\n");
}

YACE_PP_HELPER int
yace_pp_bool(struct yace_pp *pp, const char *key, int val)
{
	int wrtn = yace_pp_key(pp, key);

	wrtn += fprintf(pp->stream, "%s", val ? "true" : "false");

	return wrtn + yace_pp_eol(pp);
}

YACE_PP_HELPER int
yace_pp_int(struct yace_pp *pp, const char *key, intmax_t val)
{
	int wrtn = yace_pp_key(pp, key);

	wrtn += fprintf(pp->stream, "%jd", val);

	return wrtn + yace_pp_eol(pp);
}

YACE_PP_HELPER int
yace_pp_uint(struct yace_pp *pp, const char *key, uintmax_t val)
{
	int wrtn = yace_pp_key(pp, key);

	wrtn += fprintf(pp->stream, "%ju", val);

	return wrtn + yace_pp_eol(pp);
}

YACE_PP_HELPER int
yace_pp_float(struct yace_pp *pp, const char *key, double val)
{
	int wrtn = yace_pp_key(pp, key);

	wrtn += fprintf(pp->stream, "%g", val);

	return wrtn + yace_pp_eol(pp);
}

YACE_PP_HELPER int
yace_pp_ptr(struct yace_pp *pp, const char *key, uintptr_t val)
{
	int wrtn = yace_pp_key(pp, key);

	if (val) {
		wrtn += fprintf(pp->stream, "\"0x%" PRIxPTR "\"", val);
	} else {
		wrtn += fprintf(pp->stream, "null");
	}

	return wrtn + yace_pp_eol(pp);
}

/* At most 'len' characters of 'str', quoted and escaped */
YACE_PP_HELPER int
yace_pp_strn(struct yace_pp *pp, const char *key, const char *str, size_t len)
{
	int wrtn = yace_pp_key(pp, key);

	if (!str) {
		wrtn += fprintf(pp->stream, "null");
		return wrtn + yace_pp_eol(pp);
	}

	wrtn += fprintf(pp->stream, "\"");
	for (size_t i = 0; i < len && str[i]; ++i) {
		unsigned char chr = (unsigned char)str[i];

		if (chr == '"' || chr == '\\') {
			wrtn += fprintf(pp->stream, "\\%c", chr);
		} else if (chr < 0x20 || chr == 0x7f) {
			wrtn += fprintf(pp->stream, "\\u%04x", chr);
		} else {
			wrtn += fprintf(pp->stream, "%c", chr);
		}
	}
	wrtn += fprintf(pp->stream, "\"");

	return wrtn + yace_pp_eol(pp);
}

YACE_PP_HELPER int
yace_pp_str(struct yace_pp *pp, const char *key, const char *str)
{
	return yace_pp_strn(pp, key, str, SIZE_MAX);
}

/* The key of a record, whose fields follow in YAML on the lines below */
YACE_PP_HELPER int
yace_pp_nest(struct yace_pp *pp, const char *key)
{
	if (key && !pp->json) {
		return fprintf(pp->stream, "%*s%s:\n", pp->indent, "", key);
	}

	return yace_pp_key(pp, key);
}

/* The key of an array, and the context of its elements: a list, on one line */
YACE_PP_HELPER int
yace_pp_list(struct yace_pp *pp, struct yace_pp *list, const char *key)
{
	int wrtn = yace_pp_key(pp, key);

	*list = (struct yace_pp){pp->stream, 1, 0, 0};

	return wrtn + fprintf(pp->stream, "[");
}

YACE_PP_HELPER int
yace_pp_list_end(struct yace_pp *pp)
{
	int wrtn = fprintf(pp->stream, "]");

	return wrtn + yace_pp_eol(pp);
}

/* A field of bits: a mapping on one line of its value and of each of its parts */
YACE_PP_HELPER int
yace_pp_bits(struct yace_pp *pp, const char *key, uintmax_t val)
{
	int wrtn = yace_pp_key(pp, key);

	if (pp->json) {
		return wrtn + fprintf(pp->stream, "{\"val\": %ju", val);
	}

	return wrtn + fprintf(pp->stream, "{val: 0x%jx", val);
}

YACE_PP_HELPER int
yace_pp_part(struct yace_pp *pp, const char *name, uintmax_t val)
{
	if (pp->json) {
		return fprintf(pp->stream, ", \"%s\": %ju", name, val);
	}

	return fprintf(pp->stream, ", %s: 0x%jx", name, val);
}

YACE_PP_HELPER int
yace_pp_bits_end(struct yace_pp *pp)
{
	int wrtn = fprintf(pp->stream, "}");

	return wrtn + yace_pp_eol(pp);
}

/* The start of a record: in JSON a brace, in YAML its fields one level in */
YACE_PP_HELPER int
yace_pp_open(struct yace_pp *pp)
{
	if (!pp->json) {
		pp->indent += 2;
		return 0;
	}
	pp->count = 0;

	return fprintf(pp->stream, "{");
}

YACE_PP_HELPER int
yace_pp_close(struct yace_pp *pp)
{
	return pp->json ? fprintf(pp->stream, "}") : 0;
}

/* The start of a record printed by its printer: its name, in YAML */
YACE_PP_HELPER int
yace_pp_head(struct yace_pp *pp, const char *name, const void *obj)
{
	if (pp->json) {
		return obj ? 0 : fprintf(pp->stream, "null");
	}

	return fprintf(pp->stream, "%s:%s\n", name, obj ? "" : " ~");
}

YACE_PP_HELPER int
yace_pp_tail(struct yace_pp *pp)
{
	return pp->json ? fprintf(pp->stream, "\n") : 0;
}

static int
yace_pp_rec_foo_point(struct yace_pp pp, const struct foo_point *obj)
{
	int wrtn = yace_pp_open(&pp);

	wrtn += yace_pp_int(&pp, "x", (intmax_t)obj->x);
	wrtn += yace_pp_int(&pp, "y", (intmax_t)obj->y);

	return wrtn + yace_pp_close(&pp);
}

int
foo_point_fpr(FILE *stream, const struct foo_point *obj, int flags)
{
	struct yace_pp pp = {stream, (flags & FOO_PR_JSON) != 0, 0, 0};
	int wrtn = yace_pp_head(&pp, "foo_point", obj);

	if (obj) {
		wrtn += yace_pp_rec_foo_point(pp, obj);
	}

	return wrtn + yace_pp_tail(&pp);
}

int
foo_point_pr(const struct foo_point *obj, int flags)
{
	return foo_point_fpr(stdout, obj, flags);
}

static int
yace_pp_rec_foo_visitor(struct yace_pp pp, const struct foo_visitor *obj)
{
	int wrtn = yace_pp_open(&pp);

	wrtn += yace_pp_ptr(&pp, "visit", (uintptr_t)obj->visit);
	wrtn += yace_pp_ptr(&pp, "arg", (uintptr_t)obj->arg);

	return wrtn + yace_pp_close(&pp);
}

int
foo_visitor_fpr(FILE *stream, const struct foo_visitor *obj, int flags)
{
	struct yace_pp pp = {stream, (flags & FOO_PR_JSON) != 0, 0, 0};
	int wrtn = yace_pp_head(&pp, "foo_visitor", obj);

	if (obj) {
		wrtn += yace_pp_rec_foo_visitor(pp, obj);
	}

	return wrtn + yace_pp_tail(&pp);
}

int
foo_visitor_pr(const struct foo_visitor *obj, int flags)
{
	return foo_visitor_fpr(stdout, obj, flags);
}

static int
yace_pp_rec_foo_scalars(struct yace_pp pp, const struct foo_scalars *obj)
{
	int wrtn = yace_pp_open(&pp);

	wrtn += yace_pp_bool(&pp, "flag", obj->flag);
	wrtn += yace_pp_int(&pp, "letter", (intmax_t)obj->letter);
	wrtn += yace_pp_int(&pp, "schar", (intmax_t)obj->schar);
	wrtn += yace_pp_uint(&pp, "uchar", (uintmax_t)obj->uchar);
	wrtn += yace_pp_int(&pp, "s", (intmax_t)obj->s);
	wrtn += yace_pp_uint(&pp, "us", (uintmax_t)obj->us);
	wrtn += yace_pp_int(&pp, "i", (intmax_t)obj->i);
	wrtn += yace_pp_uint(&pp, "ui", (uintmax_t)obj->ui);
	wrtn += yace_pp_int(&pp, "l", (intmax_t)obj->l);
	wrtn += yace_pp_uint(&pp, "ul", (uintmax_t)obj->ul);
	wrtn += yace_pp_int(&pp, "ll", (intmax_t)obj->ll);
	wrtn += yace_pp_uint(&pp, "ull", (uintmax_t)obj->ull);
	wrtn += yace_pp_float(&pp, "f", (double)obj->f);
	wrtn += yace_pp_float(&pp, "d", (double)obj->d);
	wrtn += yace_pp_int(&pp, "i8", (intmax_t)obj->i8);
	wrtn += yace_pp_int(&pp, "i16", (intmax_t)obj->i16);
	wrtn += yace_pp_int(&pp, "i32", (intmax_t)obj->i32);
	wrtn += yace_pp_int(&pp, "i64", (intmax_t)obj->i64);
	wrtn += yace_pp_uint(&pp, "u8", (uintmax_t)obj->u8);
	wrtn += yace_pp_uint(&pp, "u16", (uintmax_t)obj->u16);
	wrtn += yace_pp_uint(&pp, "u32", (uintmax_t)obj->u32);
	wrtn += yace_pp_uint(&pp, "u64", (uintmax_t)obj->u64);
	wrtn += yace_pp_int(&pp, "iptr", (intmax_t)obj->iptr);
	wrtn += yace_pp_uint(&pp, "uptr", (uintmax_t)obj->uptr);
	wrtn += yace_pp_uint(&pp, "size", (uintmax_t)obj->size);
	wrtn += yace_pp_int(&pp, "ssize", (intmax_t)obj->ssize);
	wrtn += yace_pp_int(&pp, "diff", (intmax_t)obj->diff);

	return wrtn + yace_pp_close(&pp);
}

int
foo_scalars_fpr(FILE *stream, const struct foo_scalars *obj, int flags)
{
	struct yace_pp pp = {stream, (flags & FOO_PR_JSON) != 0, 0, 0};
	int wrtn = yace_pp_head(&pp, "foo_scalars", obj);

	if (obj) {
		wrtn += yace_pp_rec_foo_scalars(pp, obj);
	}

	return wrtn + yace_pp_tail(&pp);
}

int
foo_scalars_pr(const struct foo_scalars *obj, int flags)
{
	return foo_scalars_fpr(stdout, obj, flags);
}

static int
yace_pp_rec_foo_figure(struct yace_pp pp, const struct foo_figure *obj)
{
	int wrtn = yace_pp_open(&pp);

	wrtn += yace_pp_uint(&pp, "shape", (uintmax_t)obj->shape);
	wrtn += yace_pp_uint(&pp, "options", (uintmax_t)obj->options);
	wrtn += yace_pp_nest(&pp, "origin");
	wrtn += yace_pp_rec_foo_point(pp, &obj->origin);
	{
		struct yace_pp l0;

		wrtn += yace_pp_list(&pp, &l0, "corners");
		for (size_t i0 = 0; i0 < 4; ++i0) {
			wrtn += yace_pp_nest(&l0, NULL);
			wrtn += yace_pp_rec_foo_point(l0, &obj->corners[i0]);
		}
		wrtn += yace_pp_list_end(&pp);
	}
	wrtn += yace_pp_uint(&pp, "ncorners", (uintmax_t)obj->ncorners);
	wrtn += yace_pp_strn(&pp, "name", obj->name, 16);
	{
		struct yace_pp l0;

		wrtn += yace_pp_list(&pp, &l0, "grid");
		for (size_t i0 = 0; i0 < 2; ++i0) {
			struct yace_pp l1;

			wrtn += yace_pp_list(&l0, &l1, NULL);
			for (size_t i1 = 0; i1 < 3; ++i1) {
				wrtn += yace_pp_int(&l1, NULL, (intmax_t)obj->grid[i0][i1]);
			}
			wrtn += yace_pp_list_end(&l0);
		}
		wrtn += yace_pp_list_end(&pp);
	}
	wrtn += yace_pp_str(&pp, "label", obj->label);
	wrtn += yace_pp_float(&pp, "scale", (double)obj->scale);
	wrtn += yace_pp_float(&pp, "area", (double)obj->area);

	return wrtn + yace_pp_close(&pp);
}

int
foo_figure_fpr(FILE *stream, const struct foo_figure *obj, int flags)
{
	struct yace_pp pp = {stream, (flags & FOO_PR_JSON) != 0, 0, 0};
	int wrtn = yace_pp_head(&pp, "foo_figure", obj);

	if (obj) {
		wrtn += yace_pp_rec_foo_figure(pp, obj);
	}

	return wrtn + yace_pp_tail(&pp);
}

int
foo_figure_pr(const struct foo_figure *obj, int flags)
{
	return foo_figure_fpr(stdout, obj, flags);
}

static int
yace_pp_rec_foo_value(struct yace_pp pp, const union foo_value *obj)
{
	int wrtn = yace_pp_open(&pp);

	wrtn += yace_pp_int(&pp, "i", (intmax_t)obj->i);
	wrtn += yace_pp_uint(&pp, "u", (uintmax_t)obj->u);
	wrtn += yace_pp_nest(&pp, "point");
	wrtn += yace_pp_rec_foo_point(pp, &obj->point);

	return wrtn + yace_pp_close(&pp);
}

int
foo_value_fpr(FILE *stream, const union foo_value *obj, int flags)
{
	struct yace_pp pp = {stream, (flags & FOO_PR_JSON) != 0, 0, 0};
	int wrtn = yace_pp_head(&pp, "foo_value", obj);

	if (obj) {
		wrtn += yace_pp_rec_foo_value(pp, obj);
	}

	return wrtn + yace_pp_tail(&pp);
}

int
foo_value_pr(const union foo_value *obj, int flags)
{
	return foo_value_fpr(stdout, obj, flags);
}

static int
yace_pp_rec_foo_wire(struct yace_pp pp, const struct foo_wire *obj)
{
	int wrtn = yace_pp_open(&pp);

	wrtn += yace_pp_uint(&pp, "kind", (uintmax_t)obj->kind);
	wrtn += yace_pp_uint(&pp, "length", (uintmax_t)obj->length);
	{
		const struct foo_point v0 = obj->at;

		wrtn += yace_pp_nest(&pp, "at");
		wrtn += yace_pp_rec_foo_point(pp, &v0);
	}
	{
		struct yace_pp l0;

		wrtn += yace_pp_list(&pp, &l0, "pair");
		for (size_t i0 = 0; i0 < 2; ++i0) {
			wrtn += yace_pp_uint(&l0, NULL, (uintmax_t)obj->pair[i0]);
		}
		wrtn += yace_pp_list_end(&pp);
	}

	return wrtn + yace_pp_close(&pp);
}

int
foo_wire_fpr(FILE *stream, const struct foo_wire *obj, int flags)
{
	struct yace_pp pp = {stream, (flags & FOO_PR_JSON) != 0, 0, 0};
	int wrtn = yace_pp_head(&pp, "foo_wire", obj);

	if (obj) {
		wrtn += yace_pp_rec_foo_wire(pp, obj);
	}

	return wrtn + yace_pp_tail(&pp);
}

int
foo_wire_pr(const struct foo_wire *obj, int flags)
{
	return foo_wire_fpr(stdout, obj, flags);
}

static int
yace_pp_rec_foo_status(struct yace_pp pp, const struct foo_status *obj)
{
	int wrtn = yace_pp_open(&pp);

	wrtn += yace_pp_bits(&pp, "code", (uintmax_t)obj->code);
	wrtn += yace_pp_part(&pp, "pending",
			     ((uintmax_t)obj->code & FOO_STATUS_CODE_PENDING) >> 0);
	wrtn += yace_pp_part(&pp, "points", ((uintmax_t)obj->code & FOO_STATUS_CODE_POINTS) >> 4);
	wrtn += yace_pp_part(&pp, "full", ((uintmax_t)obj->code & FOO_STATUS_CODE_FULL) >> 15);
	wrtn += yace_pp_bits_end(&pp);
	wrtn += yace_pp_uint(&pp, "max", (uintmax_t)obj->max);

	return wrtn + yace_pp_close(&pp);
}

int
foo_status_fpr(FILE *stream, const struct foo_status *obj, int flags)
{
	struct yace_pp pp = {stream, (flags & FOO_PR_JSON) != 0, 0, 0};
	int wrtn = yace_pp_head(&pp, "foo_status", obj);

	if (obj) {
		wrtn += yace_pp_rec_foo_status(pp, obj);
	}

	return wrtn + yace_pp_tail(&pp);
}

int
foo_status_pr(const struct foo_status *obj, int flags)
{
	return foo_status_fpr(stdout, obj, flags);
}

const char *
foo_shape_str(int value)
{
	switch (value) {
	case FOO_SHAPE_NONE:
		return "FOO_SHAPE_NONE";
	case FOO_SHAPE_POINT:
		return "FOO_SHAPE_POINT";
	case FOO_SHAPE_LINE:
		return "FOO_SHAPE_LINE";
	case FOO_SHAPE_POLYGON:
		return "FOO_SHAPE_POLYGON";
	default:
		return "UNKNOWN";
	}
}

const char *
foo_option_str(int value)
{
	switch (value) {
	case FOO_OPTION_CLOSED:
		return "FOO_OPTION_CLOSED";
	case FOO_OPTION_FILLED:
		return "FOO_OPTION_FILLED";
	default:
		return "UNKNOWN";
	}
}

Check

../../../../output/capi/foo_check.c
/**
 * libfoo: check of the generated C API
 *
 * Asserts, at compile time, that the records with fields have the layout
 * recorded in the IR, then prints a zeroed instance of each, as YAML documents with
 * argument "yaml" or JSON lines with argument "json", for the caller to parse.
 *
 * @file foo_check.c
 *
 * Generated by yace from foo.h; do not edit.
 */
#include <stdalign.h>
#include <stddef.h>
#include <string.h>
#include <libfoo.h>

_Static_assert(sizeof(struct foo_point) == 8, "sizeof(foo_point)");
_Static_assert(alignof(struct foo_point) == 4, "alignof(foo_point)");
_Static_assert(offsetof(struct foo_point, x) == 0, "offsetof(foo_point, x)");
_Static_assert(offsetof(struct foo_point, y) == 4, "offsetof(foo_point, y)");

_Static_assert(sizeof(struct foo_visitor) == 16, "sizeof(foo_visitor)");
_Static_assert(alignof(struct foo_visitor) == 8, "alignof(foo_visitor)");
_Static_assert(offsetof(struct foo_visitor, visit) == 0, "offsetof(foo_visitor, visit)");
_Static_assert(offsetof(struct foo_visitor, arg) == 8, "offsetof(foo_visitor, arg)");

_Static_assert(sizeof(struct foo_scalars) == 136, "sizeof(foo_scalars)");
_Static_assert(alignof(struct foo_scalars) == 8, "alignof(foo_scalars)");
_Static_assert(offsetof(struct foo_scalars, flag) == 0, "offsetof(foo_scalars, flag)");
_Static_assert(offsetof(struct foo_scalars, letter) == 1, "offsetof(foo_scalars, letter)");
_Static_assert(offsetof(struct foo_scalars, schar) == 2, "offsetof(foo_scalars, schar)");
_Static_assert(offsetof(struct foo_scalars, uchar) == 3, "offsetof(foo_scalars, uchar)");
_Static_assert(offsetof(struct foo_scalars, s) == 4, "offsetof(foo_scalars, s)");
_Static_assert(offsetof(struct foo_scalars, us) == 6, "offsetof(foo_scalars, us)");
_Static_assert(offsetof(struct foo_scalars, i) == 8, "offsetof(foo_scalars, i)");
_Static_assert(offsetof(struct foo_scalars, ui) == 12, "offsetof(foo_scalars, ui)");
_Static_assert(offsetof(struct foo_scalars, l) == 16, "offsetof(foo_scalars, l)");
_Static_assert(offsetof(struct foo_scalars, ul) == 24, "offsetof(foo_scalars, ul)");
_Static_assert(offsetof(struct foo_scalars, ll) == 32, "offsetof(foo_scalars, ll)");
_Static_assert(offsetof(struct foo_scalars, ull) == 40, "offsetof(foo_scalars, ull)");
_Static_assert(offsetof(struct foo_scalars, f) == 48, "offsetof(foo_scalars, f)");
_Static_assert(offsetof(struct foo_scalars, d) == 56, "offsetof(foo_scalars, d)");
_Static_assert(offsetof(struct foo_scalars, i8) == 64, "offsetof(foo_scalars, i8)");
_Static_assert(offsetof(struct foo_scalars, i16) == 66, "offsetof(foo_scalars, i16)");
_Static_assert(offsetof(struct foo_scalars, i32) == 68, "offsetof(foo_scalars, i32)");
_Static_assert(offsetof(struct foo_scalars, i64) == 72, "offsetof(foo_scalars, i64)");
_Static_assert(offsetof(struct foo_scalars, u8) == 80, "offsetof(foo_scalars, u8)");
_Static_assert(offsetof(struct foo_scalars, u16) == 82, "offsetof(foo_scalars, u16)");
_Static_assert(offsetof(struct foo_scalars, u32) == 84, "offsetof(foo_scalars, u32)");
_Static_assert(offsetof(struct foo_scalars, u64) == 88, "offsetof(foo_scalars, u64)");
_Static_assert(offsetof(struct foo_scalars, iptr) == 96, "offsetof(foo_scalars, iptr)");
_Static_assert(offsetof(struct foo_scalars, uptr) == 104, "offsetof(foo_scalars, uptr)");
_Static_assert(offsetof(struct foo_scalars, size) == 112, "offsetof(foo_scalars, size)");
_Static_assert(offsetof(struct foo_scalars, ssize) == 120, "offsetof(foo_scalars, ssize)");
_Static_assert(offsetof(struct foo_scalars, diff) == 128, "offsetof(foo_scalars, diff)");

_Static_assert(sizeof(struct foo_figure) == 104, "sizeof(foo_figure)");
_Static_assert(alignof(struct foo_figure) == 8, "alignof(foo_figure)");
_Static_assert(offsetof(struct foo_figure, shape) == 0, "offsetof(foo_figure, shape)");
_Static_assert(offsetof(struct foo_figure, options) == 4, "offsetof(foo_figure, options)");
_Static_assert(offsetof(struct foo_figure, origin) == 8, "offsetof(foo_figure, origin)");
_Static_assert(offsetof(struct foo_figure, corners) == 16, "offsetof(foo_figure, corners)");
_Static_assert(offsetof(struct foo_figure, ncorners) == 48, "offsetof(foo_figure, ncorners)");
_Static_assert(offsetof(struct foo_figure, name) == 49, "offsetof(foo_figure, name)");
_Static_assert(offsetof(struct foo_figure, grid) == 66, "offsetof(foo_figure, grid)");
_Static_assert(offsetof(struct foo_figure, label) == 80, "offsetof(foo_figure, label)");
_Static_assert(offsetof(struct foo_figure, scale) == 88, "offsetof(foo_figure, scale)");
_Static_assert(offsetof(struct foo_figure, area) == 96, "offsetof(foo_figure, area)");

_Static_assert(sizeof(union foo_value) == 8, "sizeof(foo_value)");
_Static_assert(alignof(union foo_value) == 4, "alignof(foo_value)");
_Static_assert(offsetof(union foo_value, i) == 0, "offsetof(foo_value, i)");
_Static_assert(offsetof(union foo_value, u) == 0, "offsetof(foo_value, u)");
_Static_assert(offsetof(union foo_value, point) == 0, "offsetof(foo_value, point)");

_Static_assert(sizeof(struct foo_wire) == 17, "sizeof(foo_wire)");
_Static_assert(alignof(struct foo_wire) == 1, "alignof(foo_wire)");
_Static_assert(offsetof(struct foo_wire, kind) == 0, "offsetof(foo_wire, kind)");
_Static_assert(offsetof(struct foo_wire, length) == 1, "offsetof(foo_wire, length)");
_Static_assert(offsetof(struct foo_wire, at) == 5, "offsetof(foo_wire, at)");
_Static_assert(offsetof(struct foo_wire, pair) == 13, "offsetof(foo_wire, pair)");

_Static_assert(sizeof(struct foo_status) == 4, "sizeof(foo_status)");
_Static_assert(alignof(struct foo_status) == 2, "alignof(foo_status)");
_Static_assert(offsetof(struct foo_status, code) == 0, "offsetof(foo_status, code)");
_Static_assert(offsetof(struct foo_status, max) == 2, "offsetof(foo_status, max)");

int
main(int argc, char **argv)
{
	int flags = FOO_PR_YAML;

	if (argc > 1 && !strcmp(argv[1], "json")) {
		flags = FOO_PR_JSON;
	}
	(void)flags;

	{
		struct foo_point obj;

		memset(&obj, 0, sizeof(obj));
		if (flags == FOO_PR_YAML) {
			printf("---\n");
		}
		if (foo_point_fpr(stdout, &obj, flags) < 0) {
			return 1;
		}
	}

	{
		struct foo_visitor obj;

		memset(&obj, 0, sizeof(obj));
		if (flags == FOO_PR_YAML) {
			printf("---\n");
		}
		if (foo_visitor_fpr(stdout, &obj, flags) < 0) {
			return 1;
		}
	}

	{
		struct foo_scalars obj;

		memset(&obj, 0, sizeof(obj));
		if (flags == FOO_PR_YAML) {
			printf("---\n");
		}
		if (foo_scalars_fpr(stdout, &obj, flags) < 0) {
			return 1;
		}
	}

	{
		struct foo_figure obj;

		memset(&obj, 0, sizeof(obj));
		if (flags == FOO_PR_YAML) {
			printf("---\n");
		}
		if (foo_figure_fpr(stdout, &obj, flags) < 0) {
			return 1;
		}
	}

	{
		union foo_value obj;

		memset(&obj, 0, sizeof(obj));
		if (flags == FOO_PR_YAML) {
			printf("---\n");
		}
		if (foo_value_fpr(stdout, &obj, flags) < 0) {
			return 1;
		}
	}

	{
		struct foo_wire obj;

		memset(&obj, 0, sizeof(obj));
		if (flags == FOO_PR_YAML) {
			printf("---\n");
		}
		if (foo_wire_fpr(stdout, &obj, flags) < 0) {
			return 1;
		}
	}

	{
		struct foo_status obj;

		memset(&obj, 0, sizeof(obj));
		if (flags == FOO_PR_YAML) {
			printf("---\n");
		}
		if (foo_status_fpr(stdout, &obj, flags) < 0) {
			return 1;
		}
	}
	if (!strcmp(foo_shape_str(FOO_SHAPE_NONE), "UNKNOWN")) {
		return 1;
	}
	if (!strcmp(foo_shape_str(FOO_SHAPE_POINT), "UNKNOWN")) {
		return 1;
	}
	if (!strcmp(foo_shape_str(FOO_SHAPE_LINE), "UNKNOWN")) {
		return 1;
	}
	if (!strcmp(foo_shape_str(FOO_SHAPE_POLYGON), "UNKNOWN")) {
		return 1;
	}
	if (!strcmp(foo_option_str(FOO_OPTION_CLOSED), "UNKNOWN")) {
		return 1;
	}
	if (!strcmp(foo_option_str(FOO_OPTION_FILLED), "UNKNOWN")) {
		return 1;
	}

	return 0;
}

What the check printed, as YAML:

---
foo_point:
  x: 0
  y: 0
---
foo_visitor:
  visit: null
  arg: null
---
foo_scalars:
  flag: false
  letter: 0
  schar: 0
  uchar: 0
  s: 0
  us: 0
  i: 0
  ui: 0
  l: 0
  ul: 0
  ll: 0
  ull: 0
  f: 0
  d: 0
  i8: 0
  i16: 0
  i32: 0
  i64: 0
  u8: 0
  u16: 0
  u32: 0
  u64: 0
  iptr: 0
  uptr: 0
  size: 0
  ssize: 0
  diff: 0
---
foo_figure:
  shape: 0
  options: 0
  origin:
    x: 0
    y: 0
  corners: [{"x": 0, "y": 0}, {"x": 0, "y": 0}, {"x": 0, "y": 0}, {"x": 0, "y": 0}]
  ncorners: 0
  name: ""
  grid: [[0, 0, 0], [0, 0, 0]]
  label: null
  scale: 0
  area: 0
---
foo_value:
  i: 0
  u: 0
  point:
    x: 0
    y: 0
---
foo_wire:
  kind: 0
  length: 0
  at:
    x: 0
    y: 0
  pair: [0, 0]
---
foo_status:
  code: {val: 0x0, pending: 0x0, points: 0x0, full: 0x0}
  max: 0

Implementation

The C target: an idiomatic C header for the API, pretty-printers for every struct, union and enum, and a check program asserting the layout recorded in the IR and exercising the pretty-printers

Emits, into <output>/capi:

  • lib<prefix>.h, the C API

  • <prefix>_pp.c, the pretty-printers

  • <prefix>_check.c, the check program

  • <prefix>_signatures.c, the check of the signatures against the headers

The capi_pp target emits the pretty-printers alone, into <output>/capi_pp, for an API to compile into its own library:

  • lib<prefix>_pp.h, the declarations of the printers, including the headers the IR was parsed from

  • <prefix>_pp.c, the pretty-printers

  • <prefix>_check.c, the check program

class yace.targets.capi.target.CAPI(output: Path, include: List[Path] | None = None, options: Dict[str, str] | None = None)
build(model: Model, cc: str)

Compile the printers and the check program; returns the program, and what failed

check(model: Model) → list

Build and run the check program; returns what failed, if anything

context_of(model: Model) → dict

The context the templates are rendered in, by the target’s options

emit(model: Model) → list

Emit the code for ‘model’; returns the paths written

render(model: Model, files: list) → list

Write each (filename, template) of ‘files’; returns the paths

run(binary: Path) → list

Run the check program, printing YAML and JSON, and parse what it prints; returns what failed

signatures(model: Model, cc: str) → list

Compile the check of the signatures with the headers the IR was parsed from, found in the include directories, so that a function whose type in the IR is not the header’s fails; where a header is not found, it warns that the signatures are not checked, and fails nothing

sources(model: Model) → list

The C files the check program is compiled from

class yace.targets.capi.target.CAPIPP(output: Path, include: List[Path] | None = None, options: Dict[str, str] | None = None)

The C target’s pretty-printers alone: lib<prefix>_pp.h includes the headers the IR was parsed from, rather than the C target’s lib<prefix>.h. The check compiles them with those headers, found in the include directories.

The option form chooses how the printers are compiled. library, the default, declares them in the header and defines them in <prefix>_pp.c, for an API to compile into its own library. header defines the printers in the header, static inline, and the helpers they call, static, and emits no <prefix>_pp.c: a program includes the header of what it prints, and a file that calls no printer gets no code of them. The helpers are under one include guard, so that the headers of several runs can be included together; each run needs a prefix of its own

check(model: Model) → list

Build and run the check program with the headers the IR was parsed from; returns what failed, also that a header is not found

context_of(model: Model) → dict

The context the templates are rendered in, by the target’s options

emit(model: Model) → list

Emit the code for ‘model’; returns the paths written

sources(model: Model) → list

The C files the check program is compiled from

yace.targets.capi.target.comment(text: str) → str

Make ‘text’ safe inside a C block comment

yace.targets.capi.target.docblock(doc, indent: str = '', params: Sequence[Param] = ()) → str

‘doc’ as a Doxygen comment, wrapped, or nothing when it is empty; of a function, ‘params’ are its parameters

yace.targets.capi.target.header(model: Model) → str

The C API, lib<prefix>.h, as the C target emits it, for a target that includes it in what it emits

yace.targets.capi.target.string_literal(text: str, control: str = '\\{:03o}') → str

‘text’ as a string literal of C, and of the languages escaping as C does; ‘control’ formats a control character, a byte that is not UTF-8, and a ‘?’ followed by another, which C would read as a trigraph

C code for the IR: declarations of its types, and the statements of the pretty- printers. The C target’s templates lay out the files; cgen produces what goes in them that depends on the types.

class yace.targets.capi.cgen.Printer(model: Model)

The C statements printing the fields of a record, one call of a helper of the pretty-printers for each value, to the printing context pp

body(record) → List[str]

The statements printing the named fields of ‘record’, at ‘obj’

helpers(records) → set

The helpers the printers of ‘records’ call; clang warns of an unused static function, also an inline one

resolve(typ)

‘typ’, through typedefs declared in the IR

value(typ, key: str, expr: str, pp: str = 'pp', depth: int = 0, packed: bool = False) → List[str]

Statements printing ‘expr’ by ‘key’, a string literal, or NULL for an element of a list; of a field of a ‘packed’ record, a record is printed through a copy, as its address may not be aligned

yace.targets.capi.cgen.decl(typ, inner: str = '', spelled: Dict[str, str] | None = None) → str

The C declaration of ‘inner’ as a ‘typ’, such as int *x; a record or enum named in ‘spelled’ is spelled as it says, rather than by tag and name

yace.targets.capi.cgen.ordered_records(model: Model) → list

The records with fields, each after those it contains by value

yace.targets.capi.cgen.param_name(name: str) → str

The name of a parameter in the generated header, which C++ includes too

yace.targets.capi.cgen.pointer_type(function: Function, spelled: Dict[str, str]) → str

The type of a pointer to ‘function’, as the headers spell its types

yace.targets.capi.cgen.record_deps(record, model: Model) → List[str]

The records ‘record’ contains by value, which must be complete before it

yace.targets.capi.cgen.signature(function: Function) → str

The function’s declaration, with the return type on a line of its own

yace.targets.capi.cgen.sized_call(function: Function) → str

The statement of the function that unsized() describes: a call of ‘function’, passing the size of each record

yace.targets.capi.cgen.spellings(model: Model) → Dict[str, str]

The records and enums the headers spell other than by tag and name

yace.targets.capi.cgen.unsized(function: Function) → Function | None

The static inline function that C calls in place of ‘function’, which takes @recparam records: of the name without ‘_sized’, and without the sizes of the records; None where ‘function’ takes none, or is variadic, as C cannot pass on the arguments of its ellipsis. A parameter without a name is named ‘arg’ and its index, as a definition must name what it passes on