Generate a C API and bindings for other languages from a simple specification.

.api

API generator, APIGEN, APIGEoN, Pigeon.

Types

Boolean Type

bool

Integral Types

i8/i16/i32/i64

u8/u16/u32/u64

Floating point types

f32/f64

Handle Type

handle

A void*-backed opaque type.

String

string

Lowers to a pointer to null-terminated char data in languages without first-class string support.

Variable Length Array

type[]

Lowers to a pointer to data and length argument in languages without first-class variable length array support.

Optional

type?

Function Type

(
    arg0_name: arg0_type
        [ docspec ],
    ...
) -> (return0_name: return0_type
         [ docspec ],
     ...)

Struct return values are lowered to an output argument pointer to a caller-owned struct which is filled in by the function. Optional return values are lowered to an output argument pointer to a pointer to the underlying type which the function can dereference and set to null. Likewise, optional parameters are a pointer to the underlying type which may be null. The first return will be the return value in languages with only one return value, the others will be out parameters.

Typedef

use type0 as type1 [docspec];

Enums

enum enum_name
    [ docspec ]
{
    member0_name [= member0_value]
        [ docspec ],
    ...
};

Structs

struct struct_name
    [ docspec ]
{
    member0_name: member0_type
        [ docspec ],
    ...
};

Namespace

namespace namespace_name
    [ docspec ]
{
    ...
};

Documentation Specification

docspec

[| docstring ]
[| detailed: docstring ]
[| deprecated[: docstring]]

docstring

Sequence of strings, export names, and type names.

Export

export_name: export_type
    [ docspec ];

Event

event event_name: event_callback_function_type
    [ docspec ];

History

.history.api

The previous version of the API file to verify backward compatibility between changes. Option to generate new history file from old history file and new version.