Pigeon

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

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

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 ],
    ...
};

Functions

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

In a parameter list, the function name is the argument name. 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. Parentheses around return type are only required for multiple return values.

Namespace

namespace namespace_name
    [ docspec ]
{
    ...
};

Documentation Specification

docspec

[| brief: "brief_docstring" ]
[| detailed: "detailed_docstring" ]
[| deprecated[: "use_instead"]]