fig-sys 5.0.0

//! Low-level FFI bindings for fig's C ABI, plus the build script that compiles
//! and links the native `libfig.a`.
//!
//! This is the `-sys` layer: raw `extern "C"` functions, `#[repr(C)]` type
//! mirrors, and status/format constants — nothing else. The safe, ergonomic
//! API (and serde/derive integration) lives in the `fig` crate, which depends
//! on this one. Direct use is `unsafe` and unstable across ABI-version bumps.
#![allow(non_camel_case_types)]

use std::os::raw::{c_char, c_int, c_void};

/// A fig C ABI status code, as a transparent wrapper over the raw `c_int` the
/// ABI returns — deliberately *not* a Rust `enum`.
///
/// A fieldless `#[repr(C)]` enum returned by value from an `extern "C"` function
/// is undefined behavior the instant the callee returns a discriminant the enum
/// does not list, and fig's status set is allowed to grow after 1.0. The newtype
/// preserves any code unchanged. Compare against the associated constants —
/// each is a `FigStatus`, so `status == FigStatus::OK` and a `match` arm both
/// work — and route unrecognized values through a fallback (the `fig` crate
/// does this in its `Error::from_status`).
#[repr(transparent)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct FigStatus(pub c_int);

impl FigStatus {
    pub const OK: FigStatus = FigStatus(0);
    pub const INVALID_ARGUMENT: FigStatus = FigStatus(1);
    pub const PARSE_ERROR: FigStatus = FigStatus(2);
    pub const OUT_OF_MEMORY: FigStatus = FigStatus(3);
    pub const UNSUPPORTED_FORMAT: FigStatus = FigStatus(4);
    pub const NOT_FOUND: FigStatus = FigStatus(5);
    /// The operation is not defined for these arguments, though each is
    /// individually valid. Added in core 2.7.0; see `fig_embed_retype`.
    pub const UNSUPPORTED_OPERATION: FigStatus = FigStatus(6);
    pub const INTERNAL_ERROR: FigStatus = FigStatus(255);
}

#[repr(C)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum FigFormat {
    Json = 1,
    Jsonc = 2,
    Yaml = 3,
    Toml = 4,
    Zon = 5,
    // 6 was generic XML through core 2.x; retired with the format in core
    // 3.0 and never reused, which is why JSON5 keeps its gap.
    Json5 = 7,
    // The native `fig` authoring dialect. Appended, same reasoning as JSON5.
    Fig = 8,
    Ini = 9,
    Dotenv = 10,
    Properties = 11,
    Plist = 12,
    Nestedtext = 13,
}

/// Mirror of fig.h's `FIG_FORMAT_RUNTIME_BASE`: a format integer at or above
/// this names a language registered at runtime, assigned per process and
/// never a `FigFormat` variant. Every compiled-in variant above is below it.
pub const FIG_FORMAT_RUNTIME_BASE: c_int = 4096;

pub enum FigDocument {}

pub type FigNodeId = u32;

/// Sentinel for "no such node", matching `FIG_NODE_NONE` in `fig.h`.
pub const FIG_NODE_NONE: FigNodeId = 0xFFFF_FFFF;

#[repr(C)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[allow(dead_code)]
pub enum FigNodeKind {
    Invalid = -1,
    Null = 0,
    Bool = 1,
    Int = 2,
    Float = 3,
    String = 4,
    Sequence = 5,
    Mapping = 6,
    Keyvalue = 7,
    Alias = 8,
    /// A format-specific scalar; `fig_node_extended` says which.
    Extended = 9,
}

impl FigNodeKind {
    /// Map the raw `c_int` returned by `fig_node_kind` onto a `FigNodeKind`.
    /// Unknown / future kinds collapse to [`FigNodeKind::Invalid`] rather than
    /// being reinterpreted as an out-of-range enum value — which, for a value
    /// returned by an `extern "C"` function into a Rust enum, is undefined
    /// behavior. This is the only place a raw kind crosses into the enum.
    pub fn from_c(raw: c_int) -> Self {
        match raw {
            0 => FigNodeKind::Null,
            1 => FigNodeKind::Bool,
            2 => FigNodeKind::Int,
            3 => FigNodeKind::Float,
            4 => FigNodeKind::String,
            5 => FigNodeKind::Sequence,
            6 => FigNodeKind::Mapping,
            7 => FigNodeKind::Keyvalue,
            8 => FigNodeKind::Alias,
            9 => FigNodeKind::Extended,
            _ => FigNodeKind::Invalid,
        }
    }
}

/// A caller-allocated parse diagnostic. Mirrors `FigError` in `fig.h`. Lead with
/// `size = size_of::<FigError>()`: the library writes only the fields `size`
/// covers, so it can gain fields in a later release without breaking this layout.
/// `byte_offset`/`line`/`column` are 0 when unknown. A runtime language's parse
/// failure fills `byte_offset` with the offset its parser reported; the compiled
/// formats leave all three 0 for now. `message` is NUL-terminated and truncated
/// to fit; `message_len` excludes the NUL.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct FigError {
    pub size: u32,
    pub code: c_int,
    pub byte_offset: usize,
    pub line: u32,
    pub column: u32,
    pub message_len: usize,
    pub message: [u8; 256],
}

impl FigError {
    /// A zeroed struct with `size` set, ready to pass to `fig_parse_ex`.
    pub fn new() -> Self {
        FigError {
            size: std::mem::size_of::<FigError>() as u32,
            code: 0,
            byte_offset: 0,
            line: 0,
            column: 0,
            message_len: 0,
            message: [0; 256],
        }
    }
}

unsafe extern "C" {
    pub fn fig_version() -> u32;
    pub fn fig_version_string() -> *const std::os::raw::c_char;
    pub fn fig_format_capabilities(format: c_int) -> u32;

    // Declared for ABI-mirror completeness; the binding parses via `fig_parse_ex`
    // (richer errors), so this plain entry point is not called from Rust.
    #[allow(dead_code)]
    pub fn fig_parse(
        input: *const u8,
        input_len: usize,
        format: c_int,
        out_doc: *mut *mut FigDocument,
    ) -> FigStatus;

    pub fn fig_parse_ex(
        input: *const u8,
        input_len: usize,
        format: c_int,
        out_doc: *mut *mut FigDocument,
        out_err: *mut FigError,
    ) -> FigStatus;

    pub fn fig_document_destroy(doc: *mut FigDocument);

    pub fn fig_document_serialize(
        doc: *mut FigDocument,
        format: c_int,
        options: *const FigSerializeOptions,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> FigStatus;
}

// Read traversal — consumed by `Document::to_value` and the serde deserializer.
unsafe extern "C" {
    pub fn fig_document_root(doc: *const FigDocument) -> FigNodeId;
    // Returns the raw kind as `c_int`, not `FigNodeKind`: decoding it directly
    // into the enum would be UB if the core returned an unlisted value. Callers
    // go through `FigNodeKind::from_c`.
    pub fn fig_node_kind(doc: *const FigDocument, node: FigNodeId) -> c_int;
    pub fn fig_node_first_child(doc: *const FigDocument, node: FigNodeId) -> FigNodeId;
    pub fn fig_node_next_sibling(doc: *const FigDocument, node: FigNodeId) -> FigNodeId;
    pub fn fig_node_child_count(doc: *const FigDocument, node: FigNodeId) -> usize;
    pub fn fig_keyvalue_key(doc: *const FigDocument, node: FigNodeId) -> FigNodeId;
    pub fn fig_keyvalue_value(doc: *const FigDocument, node: FigNodeId) -> FigNodeId;

    pub fn fig_node_bool(doc: *const FigDocument, node: FigNodeId, out: *mut bool) -> bool;
    pub fn fig_node_number(
        doc: *const FigDocument,
        node: FigNodeId,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> bool;
    pub fn fig_node_string(
        doc: *const FigDocument,
        node: FigNodeId,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> bool;
    pub fn fig_node_extended(
        doc: *const FigDocument,
        node: FigNodeId,
        out_kind: *mut c_int,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> bool;
}

// ---- value construction + serialization ----

pub enum FigValue {}

/// A `key: value` entry for `fig_value_map`. Mirrors `FigKeyValue` in `fig.h`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigKeyValue {
    pub key: FigNodeId,
    pub value: FigNodeId,
}

/// Output style for `fig_value_serialize_opts`/`fig_document_serialize`. Mirrors
/// `FigSerializeOptions` in `fig.h`. ALL trailing fields are declared explicitly
/// (not left to struct padding): with `size = size_of` the core reads every byte
/// up to `size`, so an undeclared `strip_comments`/`lossless` would otherwise be
/// read out of uninitialized padding.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigSerializeOptions {
    /// Set to `size_of::<FigSerializeOptions>()`. Version tag for the struct:
    /// the core reads a field only when `size` covers it, so fields can be
    /// appended without breaking this layout. See `FigSerializeOptions` in `fig.h`.
    pub size: u32,
    pub pretty: u8,
    pub indent: u8,
    pub strip_comments: u8,
    pub lossless: u8,
    pub width: u16,
    /// fig-format fragments only: nonzero renders a container root as inline
    /// flow (`[a, b]` / `{ k = v }`). Set by the editors' splice path (see
    /// `value_text`); not exposed on the public `SerializeOptions` — inline is
    /// a property of *where* the text goes, not a caller style preference.
    pub flow: u8,
    /// Nonzero renders the value as the editor takes it spliced into a
    /// document (plist's bare element, a NestedText scalar's plain text).
    /// Set by the editors' splice path; not exposed on the public
    /// `SerializeOptions`.
    pub splice: u8,
}

/// One lossy event from `fig_*_diagnose`, pulled by index via `fig_*_warning`.
/// Caller-allocated; lead with `size = size_of::<FigWarning>()` (same policy as
/// `FigSerializeOptions`/`FigError`). `path`/`note` are NOT NUL-terminated and
/// borrow the producing handle's diagnostics arena (valid until the next
/// diagnose on it or its destroy) — copy them out before then. Mirrors
/// `FigWarning` in `fig.h`.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct FigWarning {
    pub size: u32,
    pub code: c_int,
    pub cause: c_int,
    pub path: *const u8,
    pub path_len: usize,
    pub note: *const u8,
    pub note_len: usize,
}

impl FigWarning {
    /// A zeroed struct with `size` set, ready to pass to a `fig_*_warning` call.
    pub fn new() -> Self {
        FigWarning {
            size: std::mem::size_of::<FigWarning>() as u32,
            code: 0,
            cause: 0,
            path: std::ptr::null(),
            path_len: 0,
            note: std::ptr::null(),
            note_len: 0,
        }
    }
}

unsafe extern "C" {
    pub fn fig_value_create(out_value: *mut *mut FigValue) -> FigStatus;
    pub fn fig_value_destroy(value: *mut FigValue);

    pub fn fig_value_null(value: *mut FigValue, out_id: *mut FigNodeId) -> FigStatus;
    pub fn fig_value_bool(value: *mut FigValue, b: bool, out_id: *mut FigNodeId) -> FigStatus;
    pub fn fig_value_int(value: *mut FigValue, n: i64, out_id: *mut FigNodeId) -> FigStatus;
    pub fn fig_value_uint(value: *mut FigValue, n: u64, out_id: *mut FigNodeId) -> FigStatus;
    pub fn fig_value_number(
        value: *mut FigValue,
        raw: *const u8,
        raw_len: usize,
        is_float: bool,
        out_id: *mut FigNodeId,
    ) -> FigStatus;
    pub fn fig_value_string(
        value: *mut FigValue,
        ptr: *const u8,
        len: usize,
        out_id: *mut FigNodeId,
    ) -> FigStatus;
    pub fn fig_value_extended(
        value: *mut FigValue,
        kind: c_int,
        text: *const u8,
        text_len: usize,
        out_id: *mut FigNodeId,
    ) -> FigStatus;
    pub fn fig_value_seq(
        value: *mut FigValue,
        items: *const FigNodeId,
        items_len: usize,
        out_id: *mut FigNodeId,
    ) -> FigStatus;
    pub fn fig_value_map(
        value: *mut FigValue,
        entries: *const FigKeyValue,
        entries_len: usize,
        out_id: *mut FigNodeId,
    ) -> FigStatus;
    // ABI-mirror decl; the binding always serializes through the `_opts` form.
    #[allow(dead_code)]
    pub fn fig_value_serialize(
        value: *mut FigValue,
        root: FigNodeId,
        format: c_int,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> FigStatus;
    pub fn fig_value_serialize_opts(
        value: *mut FigValue,
        root: FigNodeId,
        format: c_int,
        options: *const FigSerializeOptions,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> FigStatus;
}

// ---- serialization diagnostics ----

unsafe extern "C" {
    pub fn fig_document_diagnose(
        doc: *mut FigDocument,
        format: c_int,
        options: *const FigSerializeOptions,
        out_count: *mut usize,
    ) -> FigStatus;
    pub fn fig_document_warning(
        doc: *mut FigDocument,
        index: usize,
        out: *mut FigWarning,
    ) -> FigStatus;
    pub fn fig_value_diagnose(
        value: *mut FigValue,
        root: FigNodeId,
        format: c_int,
        options: *const FigSerializeOptions,
        out_count: *mut usize,
    ) -> FigStatus;
    pub fn fig_value_warning(value: *mut FigValue, index: usize, out: *mut FigWarning)
    -> FigStatus;
}

// ---- editing (write path) ----

pub enum FigEditor {}
pub enum FigEmbed {}

/// One step of a path: `kind == 0` selects mapping key `key_ptr[0..key_len]`;
/// `kind == 1` selects sequence element `index`. Mirrors `FigPathSegment` in
/// `fig.h`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigPathSegment {
    pub kind: c_int,
    pub key_ptr: *const u8,
    pub key_len: usize,
    pub index: usize,
}

/// A borrowed UTF-8 string slice (`ptr[0..len]`) passed across the C ABI.
/// Mirrors `FigStr` in `fig.h`; used for the key list of `*_reorder_keys`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigStr {
    pub ptr: *const u8,
    pub len: usize,
}

// `FigSpan`/`FigRegion`/`fig_embed_extract` mirror the low-level embed C ABI.
// The Rust-facing consumer is `Embed` (which uses `fig_embed_*`); these are
// declared for parity with the header and for any future low-level wrapper.
#[repr(C)]
#[derive(Clone, Copy, Debug, Default)]
#[allow(dead_code)]
pub struct FigSpan {
    pub start: usize,
    pub end: usize,
}

#[repr(C)]
#[derive(Clone, Copy, Debug, Default)]
#[allow(dead_code)]
pub struct FigRegion {
    /// Size-version tag: set to `size_of::<FigRegion>()` before
    /// `fig_embed_extract` so the library only writes the fields this layout
    /// covers. A zero `size` (e.g. from `Default`) makes the library write
    /// nothing — always set it explicitly.
    pub size: u32,
    pub open_fence: FigSpan,
    pub content: FigSpan,
    pub close_fence: FigSpan,
    pub body: FigSpan,
    /// `[0, open_fence.start)` and `[close_fence.end, input_len)` — the host
    /// text on each side of the block. With the three region spans they tile
    /// the input exactly, so a rebuild loses nothing. Added in core 2.7.0; an older
    /// `size` leaves them unwritten.
    pub body_before: FigSpan,
    pub body_after: FigSpan,
}

/// The container half of an embed selector; every `fig_embed_*` entry point
/// that selects a region takes one of these beside a `FigFormat`. The four
/// parametric containers read the format; the three presets pin their own
/// and ignore it. Mirrors `FigEmbedContainer` in `fig.h` (ABI 2).
#[repr(C)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[allow(dead_code)]
pub enum FigEmbedContainer {
    MdFrontmatter = 0,
    Fenced = 1,
    HtmlScript = 2,
    HtmlCode = 3,
    SemicolonsJson = 4,
    PlusToml = 5,
    EndmatterYaml = 6,
}

unsafe extern "C" {
    pub fn fig_editor_create(
        input: *const u8,
        input_len: usize,
        format: c_int,
        out_editor: *mut *mut FigEditor,
    ) -> FigStatus;
    pub fn fig_editor_destroy(editor: *mut FigEditor);

    pub fn fig_editor_replace_val(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        repl: *const u8,
        repl_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_replace_key(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        repl: *const u8,
        repl_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_replace_named_key(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        name: *const u8,
        name_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_set(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        val: *const u8,
        val_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_add_leading_comment(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        text: *const u8,
        text_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_set_trailing_comment(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        text: *const u8,
        text_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_delete_leading_comments(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_delete_trailing_comment(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_get_leading_comment(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> FigStatus;
    pub fn fig_editor_get_trailing_comment(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> FigStatus;
    pub fn fig_editor_add_dangling_comment(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        text: *const u8,
        text_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_delete_dangling_comments(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_get_dangling_comment(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> FigStatus;
    pub fn fig_editor_comment_out(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_uncomment_leading(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        first_line: usize,
        line_count: usize,
    ) -> FigStatus;
    pub fn fig_editor_uncomment_dangling(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        first_line: usize,
        line_count: usize,
    ) -> FigStatus;
    pub fn fig_editor_insert_key(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        key: *const u8,
        key_len: usize,
        val: *const u8,
        val_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_insert_named_key(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        name: *const u8,
        name_len: usize,
        val: *const u8,
        val_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_delete_key(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_append_seq(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        val: *const u8,
        val_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_prepend_seq(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        val: *const u8,
        val_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_remove_seq_item(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        index: usize,
    ) -> FigStatus;
    pub fn fig_editor_move_key(
        editor: *mut FigEditor,
        src_path: *const FigPathSegment,
        src_path_len: usize,
        dest_path: *const FigPathSegment,
        dest_path_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_reorder_keys(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        keys: *const FigStr,
        keys_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_move_item(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        from: usize,
        to: usize,
    ) -> FigStatus;
    pub fn fig_editor_reorder_items(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        indices: *const usize,
        indices_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_set_sequence(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        items: *const FigStr,
        items_len: usize,
    ) -> FigStatus;
    // Whole-container ops, for containers scattered through the source (a TOML
    // `[header]` table, an INI `[section]`, a fig block container). The key ops
    // above cannot address one, and refuse with `INVALID_ARGUMENT` at such a
    // path. A format that does not support the op answers `UNSUPPORTED_FORMAT`.
    pub fn fig_editor_delete_container(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_insert_container(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        body: *const u8,
        body_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_rename_container(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        new_leaf: *const u8,
        new_leaf_len: usize,
    ) -> FigStatus;
    /// A NULL `dest_path` means "to the end of the document" — distinct from a
    /// zero-length path, which every other entry point reads as the root.
    pub fn fig_editor_move_container(
        editor: *mut FigEditor,
        src_path: *const FigPathSegment,
        src_path_len: usize,
        dest_path: *const FigPathSegment,
        dest_path_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_reorder_containers(
        editor: *mut FigEditor,
        order: *const FigStr,
        order_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_append_container_to_seq(
        editor: *mut FigEditor,
        path: *const FigPathSegment,
        path_len: usize,
        body: *const u8,
        body_len: usize,
    ) -> FigStatus;
    pub fn fig_editor_source(
        editor: *const FigEditor,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> FigStatus;

    pub fn fig_embed_extract(
        input: *const u8,
        input_len: usize,
        container: c_int,
        format: c_int,
        out_region: *mut FigRegion,
    ) -> FigStatus;

    pub fn fig_embed_detect(
        input: *const u8,
        input_len: usize,
        out_container: *mut c_int,
        out_format: *mut c_int,
    ) -> FigStatus;

    /// Re-house an embedded region under a different archetype's fences. On
    /// `OK` the result is an OWNED buffer — release it with `fig_free`, passing
    /// back the exact `out_len`. Added in core 2.7.0.
    pub fn fig_embed_retype(
        input: *const u8,
        input_len: usize,
        from_container: c_int,
        from_format: c_int,
        to_container: c_int,
        to_format: c_int,
        content: *const u8,
        content_len: usize,
        out_ptr: *mut *mut u8,
        out_len: *mut usize,
    ) -> FigStatus;

    /// Sized free for a buffer fig allocated (`fig_embed_retype`'s result) or
    /// that the caller obtained from `fig_alloc`. `len` must be exact.
    pub fn fig_free(ptr: *mut u8, len: usize);

    pub fn fig_embed_open(
        input: *const u8,
        input_len: usize,
        container: c_int,
        format: c_int,
        out_embed: *mut *mut FigEmbed,
    ) -> FigStatus;
    pub fn fig_embed_open_or_init(
        input: *const u8,
        input_len: usize,
        container: c_int,
        format: c_int,
        out_embed: *mut *mut FigEmbed,
    ) -> FigStatus;
    pub fn fig_embed_destroy(fm: *mut FigEmbed);

    pub fn fig_embed_replace_val(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        repl: *const u8,
        repl_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_replace_key(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        repl: *const u8,
        repl_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_replace_named_key(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        name: *const u8,
        name_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_set(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        val: *const u8,
        val_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_add_leading_comment(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        text: *const u8,
        text_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_set_trailing_comment(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        text: *const u8,
        text_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_delete_leading_comments(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_delete_trailing_comment(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_get_leading_comment(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> FigStatus;
    pub fn fig_embed_get_trailing_comment(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> FigStatus;
    pub fn fig_embed_add_dangling_comment(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        text: *const u8,
        text_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_delete_dangling_comments(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_get_dangling_comment(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> FigStatus;
    pub fn fig_embed_comment_out(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_uncomment_leading(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        first_line: usize,
        line_count: usize,
    ) -> FigStatus;
    pub fn fig_embed_uncomment_dangling(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        first_line: usize,
        line_count: usize,
    ) -> FigStatus;
    pub fn fig_embed_insert_key(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        key: *const u8,
        key_len: usize,
        val: *const u8,
        val_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_insert_named_key(
        embed: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        name: *const u8,
        name_len: usize,
        val: *const u8,
        val_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_delete_key(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_append_seq(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        val: *const u8,
        val_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_prepend_seq(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        val: *const u8,
        val_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_remove_seq_item(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        index: usize,
    ) -> FigStatus;
    pub fn fig_embed_move_key(
        fm: *mut FigEmbed,
        src_path: *const FigPathSegment,
        src_path_len: usize,
        dest_path: *const FigPathSegment,
        dest_path_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_reorder_keys(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        keys: *const FigStr,
        keys_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_move_item(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        from: usize,
        to: usize,
    ) -> FigStatus;
    pub fn fig_embed_reorder_items(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        indices: *const usize,
        indices_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_set_sequence(
        fm: *mut FigEmbed,
        path: *const FigPathSegment,
        path_len: usize,
        items: *const FigStr,
        items_len: usize,
    ) -> FigStatus;
    pub fn fig_embed_replace_body(fm: *mut FigEmbed, body: *const u8, body_len: usize)
    -> FigStatus;
    pub fn fig_embed_render(
        fm: *mut FigEmbed,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> FigStatus;
}

// ── Runtime languages ──────────────────────────────────────────────────────
//
// Mirrors of fig.h's "Runtime languages" section: the vtable a host fills to
// register a language, and the node table its parse returns and its print
// receives. Field for field with the header; `zig build abi-check` runs a
// C-hosted language through the same structs, and the `fig` crate's tests run
// a Rust-hosted one through these.

/// Mirror of `FIG_LANGUAGE_VTABLE_VERSION`.
pub const FIG_LANGUAGE_VTABLE_VERSION: u32 = 2;
/// Mirror of `FIG_OFFSET_NONE` / `FIG_LEN_NONE`: an absent optional span or
/// string.
pub const FIG_OFFSET_NONE: usize = usize::MAX;
pub const FIG_LEN_NONE: usize = usize::MAX;
/// Mirror of `FIG_ROW_NONE`: the root's `parent`.
pub const FIG_ROW_NONE: u32 = u32::MAX;
/// Mirror of `FIG_EXT_NONE`.
pub const FIG_EXT_NONE: c_int = -1;
/// Mirror of `FIG_DEPTH_NONE`: a vtable's `max_mapping_depth` when unbounded.
pub const FIG_DEPTH_NONE: c_int = -1;

pub const FIG_MENTION_HEADER: c_int = 0;
pub const FIG_MENTION_ENTRY: c_int = 1;
pub const FIG_COMMENT_LEADING: c_int = 0;
pub const FIG_COMMENT_TRAILING: c_int = 1;
pub const FIG_COMMENT_DANGLING: c_int = 2;
pub const FIG_COMMENT_LINE: c_int = 0;
pub const FIG_COMMENT_BLOCK: c_int = 1;

impl FigStr {
    /// The absent optional string.
    pub const NONE: FigStr = FigStr {
        ptr: std::ptr::null(),
        len: FIG_LEN_NONE,
    };
}

impl FigSpan {
    /// The absent optional span.
    pub const NONE: FigSpan = FigSpan {
        start: FIG_OFFSET_NONE,
        end: FIG_OFFSET_NONE,
    };
}

/// Mirror of `FigNodeRow`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigNodeRow {
    pub kind: c_int,
    pub ext_kind: c_int,
    pub parent: u32,
    pub span: FigSpan,
    pub text: FigStr,
    pub anchor: FigStr,
    pub anchor_span: FigSpan,
    pub tag: FigStr,
    pub tag_span: FigSpan,
    pub marker: FigSpan,
    pub sep: FigSpan,
}

/// Mirror of `FigRegionRow`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigRegionRow {
    pub node: u32,
    pub start: usize,
    pub end: usize,
}

/// Mirror of `FigMentionRow`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigMentionRow {
    pub node: u32,
    pub span: FigSpan,
    pub kind: c_int,
}

/// Mirror of `FigCommentRow`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigCommentRow {
    pub node: u32,
    pub slot: c_int,
    pub style: c_int,
    pub text: FigStr,
}

/// Mirror of `FigDirectiveRow`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigDirectiveRow {
    pub handle: FigStr,
    pub prefix: FigStr,
}

/// Mirror of `FigNodeTable`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigNodeTable {
    /// fig's `sizeof(FigNodeTable)` on a table fig hands over; write and
    /// read only the fields it covers.
    pub size: u32,
    /// The stride of `rows`: `size_of::<FigNodeRow>()` in a table `parse`
    /// returns; read the rows `print` is handed at the stride it says.
    pub row_size: u32,
    pub rows: *const FigNodeRow,
    pub row_count: usize,
    pub regions: *const FigRegionRow,
    pub region_count: usize,
    pub mentions: *const FigMentionRow,
    pub mention_count: usize,
    pub comments: *const FigCommentRow,
    pub comment_count: usize,
    pub directives: *const FigDirectiveRow,
    pub directive_count: usize,
    pub owner: *mut c_void,
}

/// Mirror of `FigPrintOptions`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigPrintOptions {
    /// fig's `sizeof`: read a field only when it covers it.
    pub size: u32,
    pub pretty: bool,
    pub strip_comments: bool,
    pub indent: u8,
    pub width: u16,
    pub splice: bool,
    pub flow: bool,
}

/// Mirror of `FigCommentDelimiter`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigCommentDelimiter {
    pub open: *const c_char,
    pub close: *const c_char,
    pub forbidden: *const c_char,
}

/// Mirror of `FigComments`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigComments {
    pub style: c_int,
    pub line: FigCommentDelimiter,
    pub trailing: FigCommentDelimiter,
}

/// Mirror of `FigSectionHeader`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigSectionHeader {
    pub open: *const c_char,
    pub close: *const c_char,
    pub seq_open: *const c_char,
    pub seq_close: *const c_char,
    pub sep: *const c_char,
    pub skip_index: bool,
}

/// Mirror of `FigClosedContainers`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigClosedContainers {
    pub map_open: *const c_char,
    pub map_close: *const c_char,
    pub seq_open: *const c_char,
    pub seq_close: *const c_char,
}

/// Mirror of `FigSyntax`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigSyntax {
    /// `size_of::<FigSyntax>()`.
    pub size: u32,
    pub comments: FigComments,
    pub kv_sep: *const c_char,
    pub flow_kv_sep_from_siblings: bool,
    pub flow_map_pad: *const c_char,
    pub key_style: c_int,
    pub key_sigil: u8,
    pub empty_map_literal: *const c_char,
    pub block_seq_editable: bool,
    pub flow_containers: bool,
    pub indent_unit: *const c_char,
    pub seq_item_marker: *const c_char,
    pub closed_containers: FigClosedContainers,
    pub single_line_block_mapping: bool,
    pub bare_document_mapping: bool,
    pub flow_map_open: *const c_char,
    pub flow_map_close: *const c_char,
    pub structural_indent: bool,
    pub section_noun: c_int,
    pub section_header: FigSectionHeader,
    pub merge_key: *const c_char,
}

/// `FigLanguageVTable::lossless`: the language takes the `$fig` envelope.
pub const FIG_LOSSLESS_ENVELOPE: u32 = 1 << 0;
/// With the envelope, a null the format holds natively.
pub const FIG_NATIVE_NULL: u32 = 1 << 1;
/// With the envelope, the `FigExtKind` `k` held natively.
pub const fn fig_native_ext(k: u32) -> u32 {
    1 << (2 + k)
}

/// Mirror of `FigDialectDesc`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigDialectDesc {
    pub name: *const c_char,
    pub extensions: *const *const c_char,
    pub splice: c_int,
    pub empty_doc_seed: *const c_char,
    pub syntax: *const FigSyntax,
}

pub type FigParseFn = unsafe extern "C" fn(
    ctx: *mut c_void,
    dialect: *const c_char,
    input: FigStr,
    out: *mut FigNodeTable,
    err: *mut FigError,
) -> c_int;
pub type FigPrintFn = unsafe extern "C" fn(
    ctx: *mut c_void,
    dialect: *const c_char,
    table: *const FigNodeTable,
    options: *const FigPrintOptions,
    out: *mut FigStr,
    err: *mut FigError,
) -> c_int;
pub type FigFreeTableFn = unsafe extern "C" fn(ctx: *mut c_void, table: *mut FigNodeTable);
pub type FigFreeBytesFn = unsafe extern "C" fn(ctx: *mut c_void, bytes: FigStr);
/// Mirror of `FigRenderRequest`: everything a renderer is told. fig writes
/// it, and a renderer reads a field only when `size` covers it.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct FigRenderRequest {
    /// fig's `sizeof`: read a field only when it covers it.
    pub size: u32,
    pub dialect: *const c_char,
    pub indent: FigStr,
    pub key: FigStr,
    pub value: FigStr,
    pub literal: *const c_char,
    pub old_key: FigStr,
    pub parent_key: FigStr,
    pub parent_tag: FigStr,
}

/// Every `render_*` slot's shape.
pub type FigRenderFn = unsafe extern "C" fn(
    ctx: *mut c_void,
    request: *const FigRenderRequest,
    out: *mut FigStr,
    err: *mut FigError,
) -> c_int;

/// Mirror of `FigLanguageVTable`. The five `render_*` slots and `print` are
/// `Option`, which is the null pointer on the C side.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct FigLanguageVTable {
    pub version: u32,
    /// `size_of::<FigLanguageVTable>()`.
    pub size: u32,
    pub ctx: *mut c_void,
    pub name: *const c_char,
    pub caps: u32,
    pub max_mapping_depth: c_int,
    /// `FIG_LOSSLESS_ENVELOPE` and `FIG_NATIVE_*` bits; 0 for no envelope.
    pub lossless: u32,
    pub syntax: *const FigSyntax,
    pub dialects: *const FigDialectDesc,
    pub dialect_count: usize,
    /// `size_of::<FigDialectDesc>()`.
    pub dialect_size: usize,
    pub samples: *const FigStr,
    pub sample_count: usize,
    pub parse: FigParseFn,
    pub print: Option<FigPrintFn>,
    pub free_table: FigFreeTableFn,
    pub free_bytes: FigFreeBytesFn,
    pub render_value: Option<FigRenderFn>,
    pub render_entry: Option<FigRenderFn>,
    pub render_item: Option<FigRenderFn>,
    pub render_tail: Option<FigRenderFn>,
    pub render_key: Option<FigRenderFn>,
}

unsafe extern "C" {
    pub fn fig_language_vtable_version() -> u32;
    pub fn fig_language_register(
        vt: *const FigLanguageVTable,
        out_format: *mut c_int,
        out_err: *mut FigError,
    ) -> FigStatus;
    pub fn fig_format_by_name(name: *const c_char) -> c_int;
}