Usage

You describe the FFI boundary of a C API as a C header, in the subset of C99 described in The C Subset. yace parses the header into its Interface Definition, and generates the code of the API for each target language from the IR.

Command-Line Interface

yace --help
usage: yace [-h] [--emit TARGET [TARGET ...]] [--generate GENERATOR]
            [--generator-option GENERATOR.KEY=VALUE]
            [--target-option TARGET.KEY=VALUE] [--output OUTPUT] [--meta META]
            [-I INCLUDE] [--prelude HEADER] [--lenient] [--no-check]
            [--schema] [--toolchains] [--version] [--log-level]
            [filepath ...]

Describe a C API in a subset of C, and generate its bindings

positional arguments:
  filepath              C headers (.h) to parse, as one API, or IR files
                        (.yaml) to emit code from

options:
  -h, --help            show this help message and exit
  --emit TARGET [TARGET ...]
                        targets to generate code for; installed: capi,
                        capi_pp, cpp, cython, go, python, rust, zig
  --generate GENERATOR  generator to write headers with, which are then parsed
                        with the headers given, by its name or as <file.py or
                        module>:<class>; installed: none
  --generator-option GENERATOR.KEY=VALUE
                        an option of a generator
  --target-option TARGET.KEY=VALUE
                        an option of a target given with '--emit'
  --output OUTPUT       directory to write the IR, the status and the
                        generated code to
  --meta META           YAML file of the IR meta, such as its name, prefix and
                        license
  -I INCLUDE            include directory, for parsing headers and building
                        the checks
  --prelude HEADER      system header, such as stdio.h, to include ahead of
                        the headers, for what they use but do not include;
                        what the API uses of it is still external
  --lenient             generate the code when a header steps outside the C
                        subset, instead of failing; the diagnostics are
                        reported either way
  --no-check            emit the code, but do not build and check it
  --schema              print the JSON Schema of the IR
  --toolchains          print, as JSON, the toolchains the checks of the '--
                        emit' targets, or of every target, build with, and the
                        formatters that format their code: the command, where
                        it is, and its version
  --version             show program's version number and exit
  --log-level, -l       increase the log level

Given C headers, yace parses them as one API, see The C Subset, writes the IR to <prefix>.yaml and the diagnostics to <prefix>.status, and prints the diagnostics. The prefix is the one that --meta gives, or else the name of the first header. A diagnostic is a place where the header steps outside the C subset. The header is still parsed and the IR written, but a diagnostic fails the run before any code is generated. With --lenient, the code is generated anyway, and what the diagnostics point at will likely not bind well, or at all. A note reports what is skipped without the header breaking a rule, such as a static inline function; notes are written to <prefix>.status, and do not fail the run, see Rules.

Given IR files, .yaml, yace reads them instead. Either way, --emit generates the code of the given targets, and checks it, unless --no-check. A check builds with the toolchain of its target, named by a variable of the environment where set: CC, CXX, CARGO, ZIG and GO. A missing toolchain fails the check, naming the variable.

The emitted code is formatted by the formatter of its language: the Python by black, the Go by gofmt and its go.mod by go mod edit -fmt, the Rust by rustfmt, the Zig by zig fmt, the TOML by taplo, and the C and C++, in every target, by clang-format in the style of xNVMe, src/yace/xnvme.clang-format. black, clang-format and taplo are dependencies of yace, pinned to one version each; gofmt, rustfmt and zig fmt come with the toolchain of their language, named by GOFMT, RUSTFMT, GO and ZIG where set. Cython has no formatter, so the .pyx and .pxd files of the Cython target keep the layout yace writes. The Rust target also writes the rustfmt.toml it is formatted with. The same headers then give the same bytes for the same versions of yace and of those toolchains. A target whose formatter is missing is not emitted, also with --no-check, and the run fails naming the formatter.

--toolchains prints, as JSON, the toolchains and the formatters of the --emit targets, or of every target: each one’s command, where it is found, and its version, so that whoever records a run can record what it was checked and formatted with.

The IR has no place in a C header for the name, prefix, license and so on of the API; give those in a YAML file with --meta, of the fields of yace.ir.model.Meta.

errmsg in the meta names the function of the API that returns the message of the call that failed last on the calling thread, a const char *f(void), such as foo_errmsg. The C++ and the Python targets then put that message in the error of a function documented @errno, see cpp and python. A name that is no such function is reported by the rule meta. The Rust, Zig and Go targets do not use errmsg.

A target takes its options as --target-option <target>.<key>=<value>: capi_pp.form, see capi, and cpp.std, see The C++ standard.

Example

The header of the example library, examples/libfoo/include/foo.h:

../../../examples/libfoo/include/foo.h
/**
 * An example library, using every construct of the C subset of yace
 *
 * It is the fixture the targets are checked against: each target's check calls
 * it through the bindings generated from this header and prints what it got
 * back, which must be what 'expected.yaml' says.
 */
#ifndef FOO_H
#define FOO_H

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

#define FOO_NAME "foo"           ///< Name of the library
#define FOO_MAGIC 0xACDC         ///< A hexadecimal constant
#define FOO_VERSION_MAJOR 1      ///< Major version
#define FOO_VERSION_MINOR 2      ///< Minor version
#define FOO_VERSION_PATCH 3      ///< Patch version
#define FOO_POINTS_MAX (1 << 3)  ///< Points a handle holds at most
#define FOO_DEFAULT_SHAPE_SIDES FOO_POINTS_MAX ///< A constant, by name

/**
 * 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 = 0x1, ///< The last corner connects to the first
	FOO_OPTION_FILLED = 0x2, ///< The inside is filled
};

/**
 * A collection of points, opened with foo_open() and closed with foo_close()
 */
struct foo_handle;

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

/**
 * 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 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
};

/** 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

/**
 * 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);

#endif /* FOO_H */

Its meta, examples/libfoo/meta.yaml:

../../../examples/libfoo/meta.yaml
---
# SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
#
# SPDX-License-Identifier: GPL-2.0-only

name: libfoo
prefix: foo
version: 0.0.1
brief: An example library described in the C subset of yace
author: Simon A. F. Lund <os@safl.dk>
license: GPL-2.0-only
pkg: foo
errmsg: foo_errmsg

Parse it, and generate and check its bindings for every target:

yace examples/libfoo/include/foo.h --meta examples/libfoo/meta.yaml --output output --emit capi python rust cpp zig go

which writes:

output
├── capi
│   ├── cc.log
│   ├── check.json
│   ├── check.yaml
│   ├── foo_check
│   ├── foo_check.c
│   ├── foo_pp.c
│   ├── foo_signatures.c
│   ├── libfoo.h
│   └── signatures.log
├── cpp
│   ├── cc.log
│   ├── check.json
│   ├── check.yaml
│   ├── foo.hpp
│   ├── foo_check
│   └── foo_check.cpp
├── cython
│   ├── check.json
│   ├── check.yaml
│   ├── cython.log
│   ├── foo.c
│   ├── foo.cpython-312-x86_64-linux-gnu.so
│   ├── foo.pxd
│   ├── foo.pyi
│   ├── foo.pyx
│   ├── foo_check.py
│   ├── foo_check.pyx
│   ├── libfoo.h
│   └── pxd_check.c
├── foo.status
├── foo.yaml
├── go
│   ├── check
│   ├── check.json
│   ├── check.yaml
│   ├── foo.go
│   ├── foo_callbacks.c
│   ├── foo_check
│   ├── foo_link.go
│   ├── foo_no_link.c
│   ├── go.log
│   ├── go.mod
│   └── libfoo.h
├── pad
│   ├── capi
│   ├── pad.status
│   └── pad.yaml
├── python
│   ├── __pycache__
│   ├── check.json
│   ├── check.yaml
│   ├── foo.py
│   └── foo_check.py
├── rust
│   ├── Cargo.lock
│   ├── Cargo.toml
│   ├── bindings.rs
│   ├── build.rs
│   ├── cargo.log
│   ├── check.json
│   ├── check.rs
│   ├── check.yaml
│   ├── lib.rs
│   ├── rustfmt.toml
│   └── target
└── zig
    ├── check.json
    ├── check.yaml
    ├── foo.zig
    ├── foo_check
    ├── foo_check.zig
    ├── foo_compile.zig
    ├── foo_signatures.zig
    ├── signatures.log
    └── zig.log

13 directories, 64 files

The C API generated:

../../../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 */