C Parser

Given a C header, yace parses it into the IR with libclang. Any header can be parsed; everything that can be represented is, and every place the header steps outside the C subset is reported as a diagnostic, naming the rule, see Rules. Nothing is dropped or changed without one.

Invoking it on the example library:

yace examples/libfoo/include/foo.h --meta examples/libfoo/meta.yaml --output output

C Header

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

IR

../../../output/foo.yaml
meta:
  name: libfoo
  prefix: foo
  version: 0.0.1
  brief: An example library described in the C subset of yace
  description: ''
  author: Simon A. F. Lund <os@safl.dk>
  license: GPL-2.0-only
  headers:
  - foo.h
  prelude: []
  pkg: foo
  crate: ''
  errmsg: foo_errmsg
  abi: Linux-x86_64
entities:
- key: include
  name: stdbool.h
- key: include
  name: stddef.h
- key: include
  name: stdint.h
- key: include
  name: sys/types.h
- key: define
  name: FOO_NAME
  value:
    key: str
    value: foo
  doc:
    brief: Name of the library
- key: define
  name: FOO_MAGIC
  value:
    key: int
    value: 44252
    base: 16
  doc:
    brief: A hexadecimal constant
- key: define
  name: FOO_VERSION_MAJOR
  value:
    key: int
    value: 1
  doc:
    brief: Major version
- key: define
  name: FOO_VERSION_MINOR
  value:
    key: int
    value: 2
  doc:
    brief: Minor version
- key: define
  name: FOO_VERSION_PATCH
  value:
    key: int
    value: 3
  doc:
    brief: Patch version
- key: define
  name: FOO_POINTS_MAX
  value:
    key: int
    value: 8
  doc:
    brief: Points a handle holds at most
- key: define
  name: FOO_DEFAULT_SHAPE_SIDES
  value:
    key: int
    value: 8
  doc:
    brief: A constant, by name
- key: define
  name: FOO_STATUS_CODE_PENDING
  value:
    key: int
    value: 1
    base: 16
  doc:
    brief: A count is submitted and not yet completed; bit 0 of 'code'
- key: define
  name: FOO_STATUS_CODE_POINTS
  value:
    key: int
    value: 4080
    base: 16
  doc:
    brief: Points held; bits 11:4 of 'code'
- key: define
  name: FOO_STATUS_CODE_FULL
  value:
    key: int
    value: 32768
    base: 16
  doc:
    brief: The handle holds FOO_POINTS_MAX points; bit 15 of 'code'
- key: enum_decl
  name: foo_shape
  members:
  - name: FOO_SHAPE_NONE
    value: -1
    doc:
      brief: No figure
  - name: FOO_SHAPE_POINT
    value: 0
    doc:
      brief: A single point
  - name: FOO_SHAPE_LINE
    value: 1
    doc:
      brief: Two points
  - name: FOO_SHAPE_POLYGON
    value: 2
    doc:
      brief: Three points or more
  underlying:
    key: builtin
    name: int
  doc:
    brief: Kinds of figure
- key: enum_decl
  name: foo_option
  members:
  - name: FOO_OPTION_CLOSED
    value: 1
    doc:
      brief: The last corner connects to the first
  - name: FOO_OPTION_FILLED
    value: 2
    doc:
      brief: The inside is filled
  underlying:
    key: builtin
    name: unsigned int
  doc:
    brief: Options of a figure, combined as bits
- key: struct_decl
  name: foo_handle
  fields: []
  doc:
    brief: A collection of points, opened with foo_open() and closed with foo_close()
- key: struct_decl
  name: foo_point
  fields:
  - name: x
    typ:
      key: builtin
      name: int32_t
    offset: 0
    doc:
      brief: Horizontal position
  - name: y
    typ:
      key: builtin
      name: int32_t
    offset: 32
    doc:
      brief: Vertical position
  size: 8
  align: 4
  doc:
    brief: A point on the plane
- key: typedef_decl
  name: foo_visit_cb
  typ:
    key: pointer
    to:
      key: function
      ret:
        key: builtin
        name: int
      params:
      - name: arg
        typ:
          key: pointer
          to:
            key: builtin
            name: void
      - name: point
        typ:
          key: pointer
          to:
            key: record
            tag: struct
            name: foo_point
            const: true
  doc:
    brief: Called back with each point visited
    params:
      arg: The argument given along with the callback
      point: The point visited
    returns: 0 to go on, anything else to stop
- key: typedef_decl
  name: foo_done_cb
  typ:
    key: pointer
    to:
      key: function
      ret:
        key: builtin
        name: void
      params:
      - name: arg
        typ:
          key: pointer
          to:
            key: builtin
            name: void
      - name: count
        typ:
          key: builtin
          name: size_t
  doc:
    brief: Called back when a count submitted completes
    params:
      arg: The argument given along with the callback
      count: The number of points when it completed
- key: typedef_decl
  name: foo_added_cb
  typ:
    key: pointer
    to:
      key: function
      ret:
        key: builtin
        name: void
      params:
      - name: arg
        typ:
          key: pointer
          to:
            key: builtin
            name: void
      - name: point
        typ:
          key: pointer
          to:
            key: record
            tag: struct
            name: foo_point
            const: true
  doc:
    brief: Called back with each point added to a handle watched
    params:
      arg: The argument given along with the callback
      point: The point added
- key: struct_decl
  name: foo_visitor
  fields:
  - name: visit
    typ:
      key: typedef
      name: foo_visit_cb
    offset: 0
    doc:
      brief: Called for each point
  - name: arg
    typ:
      key: pointer
      to:
        key: builtin
        name: void
    offset: 64
    doc:
      brief: Given to 'visit'
  size: 16
  align: 8
  doc:
    brief: A callback and its argument
- key: struct_decl
  name: foo_scalars
  fields:
  - name: flag
    typ:
      key: builtin
      name: bool
    offset: 0
    doc:
      brief: bool
  - name: letter
    typ:
      key: builtin
      name: char
    offset: 8
    doc:
      brief: char
  - name: schar
    typ:
      key: builtin
      name: signed char
    offset: 16
    doc:
      brief: signed char
  - name: uchar
    typ:
      key: builtin
      name: unsigned char
    offset: 24
    doc:
      brief: unsigned char
  - name: s
    typ:
      key: builtin
      name: short
    offset: 32
    doc:
      brief: short
  - name: us
    typ:
      key: builtin
      name: unsigned short
    offset: 48
    doc:
      brief: unsigned short
  - name: i
    typ:
      key: builtin
      name: int
    offset: 64
    doc:
      brief: int
  - name: ui
    typ:
      key: builtin
      name: unsigned int
    offset: 96
    doc:
      brief: unsigned int
  - name: l
    typ:
      key: builtin
      name: long
    offset: 128
    doc:
      brief: long
  - name: ul
    typ:
      key: builtin
      name: unsigned long
    offset: 192
    doc:
      brief: unsigned long
  - name: ll
    typ:
      key: builtin
      name: long long
    offset: 256
    doc:
      brief: long long
  - name: ull
    typ:
      key: builtin
      name: unsigned long long
    offset: 320
    doc:
      brief: unsigned long long
  - name: f
    typ:
      key: builtin
      name: float
    offset: 384
    doc:
      brief: float
  - name: d
    typ:
      key: builtin
      name: double
    offset: 448
    doc:
      brief: double
  - name: i8
    typ:
      key: builtin
      name: int8_t
    offset: 512
    doc:
      brief: int8_t
  - name: i16
    typ:
      key: builtin
      name: int16_t
    offset: 528
    doc:
      brief: int16_t
  - name: i32
    typ:
      key: builtin
      name: int32_t
    offset: 544
    doc:
      brief: int32_t
  - name: i64
    typ:
      key: builtin
      name: int64_t
    offset: 576
    doc:
      brief: int64_t
  - name: u8
    typ:
      key: builtin
      name: uint8_t
    offset: 640
    doc:
      brief: uint8_t
  - name: u16
    typ:
      key: builtin
      name: uint16_t
    offset: 656
    doc:
      brief: uint16_t
  - name: u32
    typ:
      key: builtin
      name: uint32_t
    offset: 672
    doc:
      brief: uint32_t
  - name: u64
    typ:
      key: builtin
      name: uint64_t
    offset: 704
    doc:
      brief: uint64_t
  - name: iptr
    typ:
      key: builtin
      name: intptr_t
    offset: 768
    doc:
      brief: intptr_t
  - name: uptr
    typ:
      key: builtin
      name: uintptr_t
    offset: 832
    doc:
      brief: uintptr_t
  - name: size
    typ:
      key: builtin
      name: size_t
    offset: 896
    doc:
      brief: size_t
  - name: ssize
    typ:
      key: builtin
      name: ssize_t
    offset: 960
    doc:
      brief: ssize_t
  - name: diff
    typ:
      key: builtin
      name: ptrdiff_t
    offset: 1024
    doc:
      brief: ptrdiff_t
  size: 136
  align: 8
  doc:
    brief: A value of every kind of scalar
- key: struct_decl
  name: foo_figure
  fields:
  - name: shape
    typ:
      key: builtin
      name: uint32_t
    offset: 0
    doc:
      brief: One of enum foo_shape
  - name: options
    typ:
      key: builtin
      name: uint32_t
    offset: 32
    doc:
      brief: Bits of enum foo_option
  - name: origin
    typ:
      key: record
      tag: struct
      name: foo_point
    offset: 64
    doc:
      brief: Where the figure is
  - name: corners
    typ:
      key: array
      of:
        key: record
        tag: struct
        name: foo_point
      length: 4
    offset: 128
    doc:
      brief: The corners, relative to 'origin'
  - name: ncorners
    typ:
      key: builtin
      name: uint8_t
    offset: 384
    doc:
      brief: How many of 'corners' are used
  - name: name
    typ:
      key: array
      of:
        key: builtin
        name: char
      length: 16
    offset: 392
    doc:
      brief: Name of the figure
  - name: grid
    typ:
      key: array
      of:
        key: array
        of:
          key: builtin
          name: int16_t
        length: 3
      length: 2
    offset: 528
    doc:
      brief: A two-dimensional array
  - name: label
    typ:
      key: pointer
      to:
        key: builtin
        name: char
        const: true
    offset: 640
    doc:
      brief: A string, NULL when there is none
  - name: scale
    typ:
      key: builtin
      name: float
    offset: 704
    doc:
      brief: Scale of the figure
  - name: area
    typ:
      key: builtin
      name: double
    offset: 768
    doc:
      brief: Area of the figure
  size: 104
  align: 8
  doc:
    brief: 'A figure: its kind, where it is, and its corners'
- key: union_decl
  name: foo_value
  fields:
  - name: i
    typ:
      key: builtin
      name: int32_t
    offset: 0
    doc:
      brief: Signed
  - name: u
    typ:
      key: builtin
      name: uint32_t
    offset: 0
    doc:
      brief: Unsigned
  - name: point
    typ:
      key: record
      tag: struct
      name: foo_point
    offset: 0
    doc:
      brief: A point, its 'x' sharing the bits of 'i'
  size: 8
  align: 4
  doc:
    brief: A 32-bit value, read as signed, as unsigned, or as the 'x' of a point
- key: struct_decl
  name: foo_wire
  fields:
  - name: kind
    typ:
      key: builtin
      name: uint8_t
    offset: 0
    doc:
      brief: One of enum foo_shape
  - name: length
    typ:
      key: builtin
      name: uint32_t
    offset: 8
    doc:
      brief: At offset 1
  - name: at
    typ:
      key: record
      tag: struct
      name: foo_point
    offset: 40
    doc:
      brief: A point, at offset 5
  - name: pair
    typ:
      key: array
      of:
        key: builtin
        name: uint16_t
      length: 2
    offset: 104
    doc:
      brief: An array, at offset 13
  size: 17
  align: 1
  packed: true
  doc:
    brief: 'A record laid out without padding, as a wire format is: no field after the first
      is aligned'
- key: struct_decl
  name: foo_status
  fields:
  - name: code
    typ:
      key: builtin
      name: uint16_t
    offset: 0
    masks:
    - name: pending
      define: FOO_STATUS_CODE_PENDING
      lo: 0
      width: 1
      doc:
        brief: A count is submitted and not yet completed; bit 0 of 'code'
    - name: points
      define: FOO_STATUS_CODE_POINTS
      lo: 4
      width: 8
      doc:
        brief: Points held; bits 11:4 of 'code'
    - name: full
      define: FOO_STATUS_CODE_FULL
      lo: 15
      width: 1
      doc:
        brief: The handle holds FOO_POINTS_MAX points; bit 15 of 'code'
    doc:
      brief: Status code, see FOO_STATUS_CODE_*
  - name: max
    typ:
      key: builtin
      name: uint16_t
    offset: 16
    doc:
      brief: Points the handle holds at most
  size: 4
  align: 2
  doc:
    brief: The status of a handle, its code a field of bits
- key: function_decl
  name: foo_version
  ret:
    key: pointer
    to:
      key: builtin
      name: char
      const: true
  doc:
    brief: The version of the library
    returns: The version, as "MAJOR.MINOR.PATCH"
- key: function_decl
  name: foo_errmsg
  ret:
    key: pointer
    to:
      key: builtin
      name: char
      const: true
  doc:
    brief: Why the call that failed last on the calling thread failed
    description: 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.
    returns: The message, owned by the library and valid until the next call fails on the
      calling thread; "" when no call has failed
- key: function_decl
  name: foo_open
  ret:
    key: builtin
    name: int
  params:
  - name: name
    typ:
      key: pointer
      to:
        key: builtin
        name: char
        const: true
  - name: handle
    typ:
      key: pointer
      to:
        key: pointer
        to:
          key: record
          tag: struct
          name: foo_handle
    direction: out
  errno: true
  doc:
    brief: Open a handle holding no points
    params:
      name: Name of the handle, copied
      handle: Set to the handle opened
    directions:
      name: in
      handle: out
    returns: 0 on success, -EINVAL when 'name' or 'handle' is NULL, -ENOMEM when memory ran
      out
    tags:
      errno: ''
- key: function_decl
  name: foo_close
  ret:
    key: builtin
    name: void
  params:
  - name: handle
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_handle
    nullable: true
  destroys: handle
  doc:
    brief: Close a handle
    params:
      handle: The handle to close, NULL is ignored
    tags:
      nullable: handle
      destroys: handle
- key: function_decl
  name: foo_name
  ret:
    key: pointer
    to:
      key: builtin
      name: char
      const: true
  params:
  - name: handle
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_handle
        const: true
  doc:
    brief: The name the handle was opened with
    params:
      handle: The handle
    returns: The name, owned by the handle
- key: function_decl
  name: foo_point_add
  ret:
    key: builtin
    name: int
  params:
  - name: handle
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_handle
  - name: point
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_point
        const: true
  errno: true
  doc:
    brief: Add a point to the handle
    params:
      handle: The handle
      point: The point to add, copied
    directions:
      point: in
    returns: 0 on success, -ENOSPC when the handle holds FOO_POINTS_MAX points
    tags:
      errno: ''
- key: function_decl
  name: foo_point_add_many
  ret:
    key: builtin
    name: ssize_t
  params:
  - name: handle
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_handle
  - name: points
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_point
        const: true
    length: points_len
  - name: points_len
    typ:
      key: builtin
      name: size_t
  errno: true
  doc:
    brief: Add points to the handle, as many as it has room for
    params:
      handle: The handle
      points: The points to add, copied
      points_len: The number of points
    directions:
      points: in
    returns: The number of points added, -ENOSPC when there was room for none
    arrays:
    - points
    tags:
      errno: ''
- key: function_decl
  name: foo_point_count
  ret:
    key: builtin
    name: size_t
  params:
  - name: handle
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_handle
        const: true
  doc:
    brief: The number of points held
    params:
      handle: The handle
    returns: The number of points
- key: function_decl
  name: foo_point_get
  ret:
    key: pointer
    to:
      key: record
      tag: struct
      name: foo_point
      const: true
  params:
  - name: handle
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_handle
        const: true
  - name: idx
    typ:
      key: builtin
      name: size_t
  nullable: true
  doc:
    brief: A point held by the handle
    params:
      handle: The handle
      idx: Index of the point
    returns: The point, NULL when 'idx' is past the last one
    tags:
      nullable: return
- key: function_decl
  name: foo_point_copy
  ret:
    key: builtin
    name: ssize_t
  params:
  - name: handle
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_handle
        const: true
  - name: points
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_point
    direction: out
    length: points_len
  - name: points_len
    typ:
      key: builtin
      name: size_t
  errno: true
  doc:
    brief: Copy the points held, as many as fit
    params:
      handle: The handle
      points: Where to copy the points to
      points_len: The number of points that fit
    directions:
      points: out
    returns: The number of points copied
    arrays:
    - points
    tags:
      errno: ''
- key: function_decl
  name: foo_point_watch
  ret:
    key: builtin
    name: int
  params:
  - name: handle
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_handle
  - name: added
    typ:
      key: typedef
      name: foo_added_cb
    lifetime: handle
  - name: arg
    typ:
      key: pointer
      to:
        key: builtin
        name: void
    nullable: true
    context: added
  errno: true
  doc:
    brief: Watch the points added to the handle, from now until it is closed
    params:
      handle: The handle
      added: Called with each point added, until the handle is closed
      arg: Given to 'added'
    returns: 0 on success, -EBUSY when the handle is watched already
    tags:
      nullable: arg
      lifetime: added handle
      errno: ''
- key: function_decl
  name: foo_point_visit
  ret:
    key: builtin
    name: ssize_t
  params:
  - name: handle
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_handle
  - name: visit
    typ:
      key: typedef
      name: foo_visit_cb
    lifetime: call
  - name: arg
    typ:
      key: pointer
      to:
        key: builtin
        name: void
    nullable: true
    context: visit
  errno: true
  doc:
    brief: Visit the points in the order they were added
    params:
      handle: The handle
      visit: Called for each point, until it returns non-zero
      arg: Given to 'visit'
    returns: The number of points visited, -EINVAL when 'visit' is NULL
    tags:
      nullable: arg
      lifetime: visit call
      errno: ''
- key: function_decl
  name: foo_point_visit_with
  ret:
    key: builtin
    name: ssize_t
  params:
  - name: handle
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_handle
  - name: visitor
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_visitor
        const: true
  errno: true
  doc:
    brief: Visit the points with a visitor; as foo_point_visit()
    params:
      handle: The handle
      visitor: The callback and its argument
    directions:
      visitor: in
    returns: The number of points visited, -EINVAL when the callback is NULL
    tags:
      errno: ''
- key: function_decl
  name: foo_count_submit
  ret:
    key: builtin
    name: int
  params:
  - name: handle
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_handle
  - name: done
    typ:
      key: typedef
      name: foo_done_cb
    lifetime: once
  - name: arg
    typ:
      key: pointer
      to:
        key: builtin
        name: void
    nullable: true
    context: done
  errno: true
  doc:
    brief: Submit a count of the points, completed by foo_count_complete()
    params:
      handle: The handle
      done: Called once, by foo_count_complete(), with the number of points
      arg: Given to 'done'
    returns: 0, -EBUSY when a count is submitted and not yet completed
    tags:
      nullable: arg
      lifetime: done once
      errno: ''
- key: function_decl
  name: foo_count_complete
  ret:
    key: builtin
    name: size_t
  params:
  - name: handle
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_handle
  doc:
    brief: Complete the count submitted, if any, calling its callback
    params:
      handle: The handle
    returns: The number of counts completed, 0 or 1
- key: function_decl
  name: foo_status_get
  ret:
    key: builtin
    name: void
  params:
  - name: handle
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_handle
        const: true
  - name: status
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_status
    direction: out
  doc:
    brief: The status of the handle
    params:
      handle: The handle
      status: The status to fill in
    directions:
      status: out
- key: function_decl
  name: foo_scalars_fill
  ret:
    key: builtin
    name: void
  params:
  - name: scalars
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_scalars
    direction: out
  doc:
    brief: Fill in a value of every kind of scalar, the limits of the fixed-width ones
    params:
      scalars: The values to fill in
    directions:
      scalars: out
- key: function_decl
  name: foo_figure_fill
  ret:
    key: builtin
    name: int
  params:
  - name: figure
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_figure
    direction: out
  - name: shape
    typ:
      key: builtin
      name: uint32_t
  errno: true
  doc:
    brief: Fill in a figure of the given shape
    params:
      figure: The figure to fill in
      shape: One of enum foo_shape
    directions:
      figure: out
    returns: 0 on success, -EINVAL when 'shape' is none of enum foo_shape
    tags:
      errno: ''
- key: function_decl
  name: foo_value_set
  ret:
    key: builtin
    name: void
  params:
  - name: value
    typ:
      key: pointer
      to:
        key: record
        tag: union
        name: foo_value
    direction: out
  - name: i
    typ:
      key: builtin
      name: int32_t
  doc:
    brief: Set a value, clearing the bits it does not use
    params:
      value: The value to set
      i: What to set it to
    directions:
      value: out
- key: function_decl
  name: foo_wire_fill
  ret:
    key: builtin
    name: void
  params:
  - name: wire
    typ:
      key: pointer
      to:
        key: record
        tag: struct
        name: foo_wire
    direction: out
  doc:
    brief: Fill in a packed record
    params:
      wire: The record to fill in
    directions:
      wire: out

Implementation

Parse a C header into the yace IR

The header describes an FFI boundary in a subset of C99. Any header is parsed, also one outside the subset: everything that can be represented is, and every place the header steps outside the subset is reported as a yace.ir.diagnostics.Diagnostic. Nothing is dropped or changed without one, so the IR of a header outside the subset is usable, and the diagnostics say what to change for it to be within.

class yace.ir.cparser.CParser(args: List[str] | None = None)

Wraps libclang; parse a header with parse()

parse(paths, meta: dict | None = None, prelude: List[str] | None = None)

Parse the header, or the headers, at ‘paths’ as one API; returns the (Model, [Diagnostic]). What the headers declare is in the model, and what any other header declares is external. The system headers named in ‘prelude’, such as ‘stdio.h’, are included ahead of them.

exception yace.ir.cparser.MissingHeader

A header yace includes itself, of the C library or of the compiler, is not found; every layout would then be guessed, so nothing is parsed

exception yace.ir.cparser.Unsupported

A type that the IR cannot represent; the message says which

yace.ir.cparser.actual_layout(cursor) → tuple

The size, alignment and field offsets, in bytes, of the record

yace.ir.cparser.attribute(cursor) → str

The name of an attribute, from its tokens where libclang has none

yace.ir.cparser.c_to_yace(paths: List[Path], output: Path, meta: dict | None = None, args=None, prelude: List[str] | None = None) → Tuple[Model, List[Diagnostic]]

Parse the headers in ‘paths’ as one API, after the system headers named in ‘prelude’, writing its IR to ‘<output>/<prefix>.yaml’ and its diagnostics to ‘<output>/<prefix>.status’. The prefix is that of the meta, or else the name of the first header.

yace.ir.cparser.calling_convention(ctype) → int

The calling convention of the function type ‘ctype’, by libclang’s clang_getFunctionTypeCallingConv(), which its Python bindings do not wrap

yace.ir.cparser.comment_before(lines: List[str], lineno: int) → str | None

The Doxygen comment ending on the line above ‘lineno’, or trailing on it; libclang does not attach comments to macros, so they are found in the source

yace.ir.cparser.decl_key(cursor) → Tuple[str, int]

Identifies a declaration, also an anonymous one, within a translation unit

yace.ir.cparser.element(ctype)

The type ‘ctype’ is made of, through pointers and arrays

yace.ir.cparser.has_flexible(ctype) → bool

Whether ‘ctype’ is a struct ending in a flexible array member, or a union holding one, which ISO C allows neither in an array nor in a struct

yace.ir.cparser.is_unnamed(cursor) → bool

Whether the record or enum has no tag; libclang spells such a one ‘’ or ‘(anonymous …)’ / ‘(unnamed …)’, and is_anonymous() misses typedef’d ones

yace.ir.cparser.natural_layout(cursor) → tuple | None

The layout that the types of the record’s fields give it, as C lays them out without attributes or ‘#pragma pack’, as actual_layout() gives one; None where it is not computed: of a record of bit-fields, or with a field whose size or alignment libclang does not give

yace.ir.cparser.qualify(typ: Annotated[Builtin | Pointer | Array | Record | EnumRef | TypedefRef | FunctionType, FieldInfo(annotation=NoneType, required=True, discriminator='key')])

Make ‘typ’ const; C qualifies an array by its elements

yace.ir.cparser.unescape(text: str) → str

The value of the body of a C string literal, its escapes decoded; bytes that are not UTF-8 are kept as the surrogates of ‘surrogateescape’

Semantics

What C cannot say about an FFI boundary, taken from the documentation of its functions, and checked: which way each pointer goes, which may be NULL, which integer is the length of which pointer, which pointer is to a record of arguments, which void * is the context of which callback, which functions report errors as a negative errno, and which destroy the handles others create.

The targets need this to bind the API idiomatically rather than only as raw calls: to return what a function writes through an [out] pointer, to raise or return an error, to release a handle when it goes out of scope, and to pass a closure as a callback. Each is a rule of the C subset, or a tag in the Doxygen comment of the function:

@param[in], @param[out], @param[in,out]

Doxygen’s own: whether the function reads what the pointer points to, writes it, or both. A pointer documented with neither is read, [in].

@recparam name text

As @param, of a record of arguments: name is a pointer to a const struct, and its size is the size_t <name>_nbytes, or the parameter that @nbytes_at{size} in the text names. The function’s name ends in _sized, and a static inline function of the name without it passes sizeof.

@arrparam name text

As @param, of an array: its length is the unsigned integer <name>_len, or the parameter that @len_at{length} in the text names. Of an [out] array, the length is the capacity, and an [out] pointer to an unsigned integer <name>_nwritten, or the one @nwritten_at{count} names, is the number of elements the function wrote. Where <name>_len or <name>_nwritten is a parameter, no reference names another.

@nullable name ...

The named pointer parameters may be NULL; return names what the function returns. Every other pointer must not be NULL.

@errno

The function returns a negative errno on failure, and zero or more on success. It returns a signed integer. @errno partial says that the function writes its [out] parameters also when it fails, so that what it wrote is not lost. It returns int, has an [out] parameter, and none is a handle.

@destroys name

The function releases the handle given as name, its only parameter; after it, the handle is not used again. An opaque record created through an [out] pointer must have one.

@lifetime callback call|once|handle ...

How long the library may invoke the callback, a promise only the author of the header can make: call, only during the call; once, at most once, after the call, and not at all when it fails; handle, any number of times, until the handle the function is a method of is destroyed, and not at all when the call fails. The tag takes pairs, one for every callback. A callback is invoked during a call into the library, on its thread: call, during the call itself; the others, of a method, during a later call given the same handle, or of a function, during any later call.

@nobind

The function is not bound: the parser leaves it out of the IR, before reading its types, which may be outside the C subset, such as the FILE * of a printer. It takes nothing.

A void * parameter right after a callback is the callback’s context, as the callback-context rule requires; a returned const char * is borrowed, as the string-return rule requires.

Buffers of memory follow names, as the buffer-lifecycle rule requires: <stem>_alloc returns a void * buffer of size_t nbytes bytes; <stem>_free frees it, taking it as its one void *; and <stem>_realloc, where it exists, resizes it, taking it and nbytes. <stem>_register, documented @errno, registers size_t nbytes bytes of the caller’s at its one void *, until <stem>_unregister takes that address. The other parameters of <stem>_free, <stem>_realloc and <stem>_unregister are named, and typed, as parameters of <stem>_alloc or <stem>_register, which the bindings pass them again.

class yace.ir.semantics.Semantics(entities: list, report: Callable[[str, str, object], None], inlines: Iterable[str] = ())

Applies the tags of the functions to the IR, reporting what is wrong

arrparam(func: Function, name: str, annotation, counted: set)

Apply the @arrparam ‘name’ of ‘func’: a pointer, and its length, an unsigned integer, by @len_at{} or ‘<name>_len’. An [out] one may have a count written, an [out] pointer to an unsigned integer, by @nwritten_at{} or ‘<name>_nwritten’; ‘counted’ holds those already taken

buffers(cursors: Dict[str, object])

Apply the buffer pattern: mark what each function of it does with a buffer, and report the allocations and registrations nothing releases

callback(typ) → FunctionType | None

The function type of ‘typ’, when it is a pointer to a function

is_method(func: Function) → bool

Whether the first parameter of ‘func’ is a handle, an opaque record

is_out_count(param: Param) → bool

Whether ‘param’ is an [out] pointer to an unsigned integer

is_pointer(typ) → bool

Whether ‘typ’ is a pointer, also one by a typedef of a callback

lifecycle(cursors: Dict[str, object])

Report the records created through an [out] pointer, never destroyed

misplaced(entity, cursor)

Report the @arrparam, @recparam and references in the comments of ‘entity’, and of its fields or members, which is no function

opaque(record: Record) → bool

Whether the header has ‘record’ without fields, only to point to

paired(func: Function, name: str, command: str, suffix: str, annotation, required: bool = True) → Param | None

The parameter that the @<command>{} in the text of ‘name’ names, or else the one named ‘<name><suffix>’; None, reported where ‘required’, when there is neither, and reported when both are parameters and differ, as the name of the one would mislead

partial(func: Function, annotation) → bool

Whether ‘func’ can write its [out] parameters when it fails: ‘func’ has an [out] parameter, none of them is a handle, as the owner of a handle written by a failed call is undefined, and ‘func’ returns int, as a failure returns no count

points_to_struct(typ) → bool

Whether ‘typ’ is a pointer to a const struct the headers define, which has a size, also by a typedef

recparam(func: Function, name: str, annotation, sized: set)

Apply the @recparam ‘name’ of ‘func’, a function taking its arguments as a record: ‘name’ is an [in] pointer to a const struct the headers define, and its size is a size_t, by @nbytes_at{} or ‘<name>_nbytes’; ‘sized’ holds the sizes already taken. The record’s parameter then holds the size’s name

renamed_record(typ) → bool

Whether ‘typ’ reaches a record only through a typedef of another name, such as foo_t * for typedef struct foo_s foo_t;

sized(func: Function, annotation) → bool

Whether the name of ‘func’, a function taking a @recparam, ends in ‘_sized’, and a static inline function of the name without it exists; what that function passes is not checked