twig_sys/

lib.rs

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

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

/// The C ABI contract version this binding is written against; see
/// `twig_abi_version`. Must match the value baked into the linked library
/// (asserted at runtime by the `abi_version_matches` test in `lib.rs`).
pub const TWIG_ABI_VERSION: u32 = 6;

// Freeze the canonical 64-bit layout of every `#[repr(C)]` mirror below so it
// can never silently drift from the Zig `extern struct` it shadows. These are
// the same offsets asserted on the Zig side in `src/c_abi.zig`; a change on
// either side that isn't matched on the other fails to compile. Gated on 64-bit
// (the offsets are the LP64/LLP64 layout); 32-bit targets pack tighter but the
// C ABI still keeps both languages in agreement.
#[cfg(target_pointer_width = "64")]
const _: () = {
    use std::mem::offset_of;
    use std::mem::size_of;

    assert!(size_of::<TwigSpan>() == 16);
    assert!(offset_of!(TwigSpan, start) == 0);
    assert!(offset_of!(TwigSpan, end) == 8);

    assert!(size_of::<TwigQueryMatch>() == 56);
    assert!(offset_of!(TwigQueryMatch, node_id) == 0);
    assert!(offset_of!(TwigQueryMatch, span) == 8);
    assert!(offset_of!(TwigQueryMatch, content_span) == 24);
    assert!(offset_of!(TwigQueryMatch, has_content_span) == 40);
    assert!(offset_of!(TwigQueryMatch, kind) == 48);

    assert!(size_of::<TwigChange>() == 32);
    assert!(offset_of!(TwigChange, old_span) == 0);
    assert!(offset_of!(TwigChange, new_span) == 16);

    assert!(size_of::<TwigFlatNode>() == 168);
    assert!(offset_of!(TwigFlatNode, id) == 0);
    assert!(offset_of!(TwigFlatNode, parent) == 4);
    assert!(offset_of!(TwigFlatNode, first_child) == 8);
    assert!(offset_of!(TwigFlatNode, next_sibling) == 12);
    assert!(offset_of!(TwigFlatNode, span) == 16);
    assert!(offset_of!(TwigFlatNode, content_span) == 32);
    assert!(offset_of!(TwigFlatNode, has_content_span) == 48);
    assert!(offset_of!(TwigFlatNode, level) == 52);
    assert!(offset_of!(TwigFlatNode, kind) == 56);
    assert!(offset_of!(TwigFlatNode, text_ptr) == 64);
    assert!(offset_of!(TwigFlatNode, text_len) == 72);
    assert!(offset_of!(TwigFlatNode, destination_ptr) == 80);
    assert!(offset_of!(TwigFlatNode, destination_len) == 88);
    assert!(offset_of!(TwigFlatNode, head) == 96);
    assert!(offset_of!(TwigFlatNode, alignment) == 100);
    assert!(offset_of!(TwigFlatNode, name_ptr) == 104);
    assert!(offset_of!(TwigFlatNode, name_len) == 112);
    assert!(offset_of!(TwigFlatNode, attrs_ptr) == 120);
    assert!(offset_of!(TwigFlatNode, attrs_len) == 128);
    assert!(offset_of!(TwigFlatNode, directive_form) == 136);
    // In what was `directive_form`'s tail padding: `size_of` is still 144 and
    // every offset above is unchanged. See the ABI note 5 in twig.h.
    assert!(offset_of!(TwigFlatNode, container_origin) == 140);
    // Appended, so every offset above keeps its place; only `size_of` moves
    // (144 -> 168). See `TWIG_ABI_VERSION` note 6.
    assert!(offset_of!(TwigFlatNode, marker_span) == 144);
    assert!(offset_of!(TwigFlatNode, has_marker_span) == 160);
    // In what was `has_marker_span`'s tail padding: `size_of` stays 168.
    assert!(offset_of!(TwigFlatNode, checked) == 164);

    assert!(size_of::<TwigKeyVal>() == 32);
    assert!(offset_of!(TwigKeyVal, key) == 0);
    assert!(offset_of!(TwigKeyVal, key_len) == 8);
    assert!(offset_of!(TwigKeyVal, value) == 16);
    assert!(offset_of!(TwigKeyVal, value_len) == 24);
};

#[repr(transparent)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TwigStatus(pub c_int);

#[allow(dead_code)]
impl TwigStatus {
    pub const OK: c_int = 0;
    pub const INVALID_ARGUMENT: c_int = 1;
    pub const PARSE_ERROR: c_int = 2;
    pub const OUT_OF_MEMORY: c_int = 3;
    pub const UNSUPPORTED_FORMAT: c_int = 4;
    pub const NOT_FOUND: c_int = 5;
    pub const AMBIGUOUS: c_int = 6;
    pub const NOT_EDITABLE: c_int = 7;
    pub const EDIT_CONFLICT: c_int = 8;
    pub const UNSAFE_METADATA: c_int = 9;
    /// `twig_language_register` refused the language; its `err_buf` says why.
    pub const INVALID_LANGUAGE: c_int = 10;
    pub const INTERNAL_ERROR: c_int = 255;
}

#[repr(C)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum TwigFormat {
    Djot = 1,
    Markdown = 2,
    Xml = 3,
    Html = 4,
    /// Parses, renders, serializes and edits. The link, image, footnote and
    /// table gestures report `TWIG_STATUS_UNSUPPORTED_FORMAT` over an
    /// AsciiDoc document (their AsciiDoc spellings have a shape the gesture
    /// algorithms cannot write); every other gesture works. What the parser
    /// leaves unmodelled survives as literal source text.
    Asciidoc = 5,
    /// Strict CommonMark, a dialect of `Markdown`: one parser under a
    /// different preset, `md_flags` laid over it. Writes as Markdown.
    Commonmark = 6,
    /// GitHub-Flavored Markdown, a dialect of `Markdown` the same way.
    Gfm = 7,
    /// SVG, a dialect of `Xml`: one parser, one serializer, one spelling
    /// table, under a code of its own. Writes as XML.
    Svg = 8,
}

/// `TWIG_FORMAT_RUNTIME_BASE`: the first format code that names a language
/// registered at runtime rather than compiled in — handed out by
/// `twig_language_register`, per process, never pinned. Every [`TwigFormat`]
/// member is below it, and a code in the range that no registration holds is
/// refused with `TWIG_STATUS_UNSUPPORTED_FORMAT`.
pub const TWIG_FORMAT_RUNTIME_BASE: c_int = 4096;
const _: () = assert!((TwigFormat::Svg as c_int) < TWIG_FORMAT_RUNTIME_BASE);

/// Bumped only when a field of [`TwigLanguageVTable`] changes meaning.
pub const TWIG_LANGUAGE_VTABLE_VERSION: u32 = 1;

/// A language function: `input` in, and on success an allocation of the
/// host's out through `out`/`out_len`, returning 0. On failure it returns
/// non-zero and may hand out a UTF-8 message the same way. Twig releases
/// whatever it hands out with the table's `free`.
pub type TwigLanguageFn = unsafe extern "C" fn(
    user_data: *mut std::ffi::c_void,
    row: *const u8,
    row_len: usize,
    input: *const u8,
    input_len: usize,
    out: *mut *mut u8,
    out_len: *mut usize,
) -> c_int;

/// Mirrors `TwigLanguageVTable` in `twig.h`.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct TwigLanguageVTable {
    pub version: u32,
    pub user_data: *mut std::ffi::c_void,
    /// The `describe` document, JSON.
    pub description: *const u8,
    pub description_len: usize,
    pub parse: Option<TwigLanguageFn>,
    /// `None` for a language that only reads.
    pub print: Option<TwigLanguageFn>,
    pub free: Option<unsafe extern "C" fn(user_data: *mut std::ffi::c_void, ptr: *mut u8, len: usize)>,
}

/// Bumped only when a field of [`TwigTransport`] changes meaning.
pub const TWIG_TRANSPORT_VERSION: u32 = 1;

/// Mirrors `TwigTransport` in `twig.h`: one line of the helper wire traded
/// for another. The library speaks the wire; the host moves the lines.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct TwigTransport {
    pub version: u32,
    pub user_data: *mut std::ffi::c_void,
    pub exchange: Option<
        unsafe extern "C" fn(
            user_data: *mut std::ffi::c_void,
            request: *const u8,
            request_len: usize,
            out: *mut *mut u8,
            out_len: *mut usize,
        ) -> c_int,
    >,
    pub free: Option<unsafe extern "C" fn(user_data: *mut std::ffi::c_void, ptr: *mut u8, len: usize)>,
}

#[cfg(target_pointer_width = "64")]
const _: () = {
    assert!(std::mem::size_of::<TwigTransport>() == 32);
    assert!(std::mem::offset_of!(TwigTransport, exchange) == 16);
    assert!(std::mem::size_of::<TwigLanguageVTable>() == 56);
    assert!(std::mem::offset_of!(TwigLanguageVTable, user_data) == 8);
    assert!(std::mem::offset_of!(TwigLanguageVTable, parse) == 32);
    assert!(std::mem::offset_of!(TwigLanguageVTable, free) == 48);
};

/// Markdown extension flags for the `md_flags` bitmask of `twig_parse_ext` and
/// `twig_editor_create_ext`.
pub const TWIG_MD_DIRECTIVES: u32 = 1 << 0;
pub const TWIG_MD_MATH: u32 = 1 << 1;
pub const TWIG_MD_HTML_ELEMENTS: u32 = 1 << 2;
pub const TWIG_MD_HIGHLIGHT: u32 = 1 << 3;
pub const TWIG_MD_HIGHLIGHT_COLORS: u32 = 1 << 4;

pub enum TwigDocument {}

pub enum TwigEditor {}

pub enum TwigBuilder {}

/// C ABI mirror of Zig's `TwigKeyVal` — one `(key, value)` attribute pair. Used
/// on the read path ([`TwigFlatNode::attrs_ptr`], borrowed) and the write path
/// (`twig_builder_set_attrs`, copied). A NULL `value` is a bare attribute.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct TwigKeyVal {
    pub key: *const u8,
    pub key_len: usize,
    pub value: *const u8,
    pub value_len: usize,
}

/// C ABI mirror of Zig's `TwigSpan` — a byte range `[start, end)`.
#[repr(C)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TwigSpan {
    pub start: usize,
    pub end: usize,
}

/// C ABI mirror of Zig's `TwigQueryMatch` — one node returned by
/// `twig_document_query`. `content_span` is only meaningful when
/// `has_content_span` is non-zero. `kind` is a NUL-terminated node-kind name
/// in static, library-owned storage (never freed).
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct TwigQueryMatch {
    pub node_id: u32,
    pub span: TwigSpan,
    pub content_span: TwigSpan,
    pub has_content_span: c_int,
    pub kind: *const c_char,
}

/// C ABI mirror of Zig's `TwigWarning` — one thing a conversion would silently
/// lose. `path` is a slash-separated child-index trail from the analyzed root
/// (empty for the root itself); `kind` is a NUL-terminated node-kind name in
/// static, library-owned storage. Both borrow, with the lifetime of the
/// `twig_document_diagnostics` output array they came from.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct TwigWarning {
    pub fidelity: c_int,
    pub path_ptr: *const u8,
    pub path_len: usize,
    pub kind: *const c_char,
}

/// [`TwigWarning::fidelity`] codes. `FAITHFUL` completes the space and is never
/// the value of a reported warning — a faithful node is not a warning.
#[allow(dead_code)]
pub const TWIG_FIDELITY_FAITHFUL: c_int = 0;
pub const TWIG_FIDELITY_DEGRADED: c_int = 1;
pub const TWIG_FIDELITY_DROPPED: c_int = 2;
pub const TWIG_FIDELITY_ATTRS_DEGRADED: c_int = 3;
pub const TWIG_FIDELITY_ATTRS_DROPPED: c_int = 4;

/// The sentinel `node_id` for "no such node" in a [`TwigFlatNode`] link field.
pub const TWIG_NO_NODE: u32 = u32::MAX;

/// C ABI mirror of Zig's `TwigChange` — the byte effect of an edit. `old_span`
/// is the replaced range in the pre-edit source; `new_span` is the range the
/// replacement occupies in the post-edit source (same start).
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct TwigChange {
    pub old_span: TwigSpan,
    pub new_span: TwigSpan,
}

/// C ABI mirror of Zig's `TwigFlatNode` — one node of the editor's flat tree
/// snapshot. Link fields (`parent`/`first_child`/`next_sibling`) are ids or
/// [`TWIG_NO_NODE`]. `content_span` is meaningful only when `has_content_span`.
/// `kind` is static, library-owned storage; `text`/`destination` pointers
/// borrow the current parse's payloads (NULL when the kind carries none).
/// `head`/`alignment` carry a `row`/`cell` payload, each `-1` for a kind that
/// has none (see [`TWIG_HEAD_NONE`] / [`TWIG_ALIGN_NONE`]). `name_ptr` is a
/// generic container's name — an HTML/XML tag or a directive's type — and NULL
/// for every other kind; `directive_form` is a [`TWIG_DIRECTIVE_NONE`]-defaulted
/// code for which of the three surface forms it took; `container_origin` is a
/// [`TWIG_CONTAINER_ORIGIN_NONE`]-defaulted code for whether it was WRITTEN as a
/// tag or a directive (the two questions are different — see the constants);
/// `attrs_ptr` points at
/// `attrs_len` [`TwigKeyVal`]s (NULL/0 when the node has no attributes). Both
/// borrow the current parse's payloads with the same lifetime as `text_ptr`.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct TwigFlatNode {
    pub id: u32,
    pub parent: u32,
    pub first_child: u32,
    pub next_sibling: u32,
    pub span: TwigSpan,
    pub content_span: TwigSpan,
    pub has_content_span: c_int,
    pub level: u32,
    pub kind: *const c_char,
    pub text_ptr: *const u8,
    pub text_len: usize,
    pub destination_ptr: *const u8,
    pub destination_len: usize,
    pub head: c_int,
    pub alignment: c_int,
    pub name_ptr: *const u8,
    pub name_len: usize,
    pub attrs_ptr: *const TwigKeyVal,
    pub attrs_len: usize,
    pub directive_form: c_int,
    pub container_origin: c_int,
    pub marker_span: TwigSpan,
    pub has_marker_span: c_int,
    pub checked: c_int,
}

/// `TwigFlatNode::checked` for a node that is not a `task_list_item`.
pub const TWIG_TASK_CHECKED_NONE: c_int = -1;

/// `TwigFlatNode::head` for a node that is neither a `row` nor a `cell`.
pub const TWIG_HEAD_NONE: c_int = -1;

/// `TwigFlatNode::alignment` codes; `NONE` means the node isn't a `cell`.
/// `NONE` is part of the ABI contract even though `Alignment::from_c` folds it
/// into its catch-all, so spell it out rather than leaving the -1 a mystery.
#[allow(dead_code)]
pub const TWIG_ALIGN_NONE: c_int = -1;
pub const TWIG_ALIGN_DEFAULT: c_int = 0;
pub const TWIG_ALIGN_LEFT: c_int = 1;
pub const TWIG_ALIGN_RIGHT: c_int = 2;
pub const TWIG_ALIGN_CENTER: c_int = 3;

/// `TwigFlatNode::directive_form` codes — the generic-directives proposal's
/// three spellings: `:name[x]` (text), `::name{…}` (leaf), `:::name{…}` … `:::`
/// (container). These double as `twig_builder_add_directive`'s `form` argument.
/// `NONE` means the node isn't a `directive` at all; like [`TWIG_ALIGN_NONE`] it
/// is a read-path-only code, never something you can build with.
#[allow(dead_code)]
pub const TWIG_DIRECTIVE_NONE: c_int = -1;
pub const TWIG_DIRECTIVE_TEXT: c_int = 0;
pub const TWIG_DIRECTIVE_LEAF: c_int = 1;
pub const TWIG_DIRECTIVE_CONTAINER: c_int = 2;

/// `TwigFlatNode::container_origin` codes — whether a generic container was
/// WRITTEN as a tag or as a directive.
///
/// A different question from [`TWIG_DIRECTIVE_TEXT`] and friends, which say
/// which of the three directive spellings a node's producer draws. HTML's
/// parser gives `<div>` and `<span>` a `directive_form` (they are the two tags
/// djot and Markdown have generic spellings for), so `directive_form` cannot
/// separate an HTML `<div>` from a Markdown `:::div`: those two agree on kind,
/// on name and on form, field for field. This is the code that separates them.
///
/// `NONE` means nothing recorded an origin — the node isn't a container, or no
/// parser produced it.
#[allow(dead_code)]
pub const TWIG_CONTAINER_ORIGIN_NONE: c_int = -1;
pub const TWIG_CONTAINER_ORIGIN_ELEMENT: c_int = 0;
pub const TWIG_CONTAINER_ORIGIN_DIRECTIVE: c_int = 1;

// `op` codes for `twig_editor_table_edit` — mirror of `TwigTableOp` in twig.h.
pub const TWIG_TABLE_INSERT_ROW: c_int = 0;
pub const TWIG_TABLE_DELETE_ROW: c_int = 1;
pub const TWIG_TABLE_INSERT_COLUMN: c_int = 2;
pub const TWIG_TABLE_DELETE_COLUMN: c_int = 3;
pub const TWIG_TABLE_SET_ALIGNMENT: c_int = 4;
pub const TWIG_TABLE_MOVE_ROW: c_int = 5;
pub const TWIG_TABLE_MOVE_COLUMN: c_int = 6;

unsafe extern "C" {
    pub fn twig_abi_version() -> u32;
    pub fn twig_language_register(
        vtable: *const TwigLanguageVTable,
        out_format: *mut c_int,
        err_buf: *mut c_char,
        err_cap: usize,
    ) -> TwigStatus;
    pub fn twig_language_register_transport(
        transport: *const TwigTransport,
        out_format: *mut c_int,
        err_buf: *mut c_char,
        err_cap: usize,
    ) -> TwigStatus;
    pub fn twig_format_by_name(name: *const u8, name_len: usize, out_format: *mut c_int) -> TwigStatus;
    pub fn twig_format_name(format: c_int, out_ptr: *mut *const u8, out_len: *mut usize) -> TwigStatus;
    pub fn twig_version() -> u32;
    pub fn twig_version_string() -> *const c_char;
    pub fn twig_parse(
        input: *const u8,
        input_len: usize,
        format: c_int,
        out_doc: *mut *mut TwigDocument,
    ) -> TwigStatus;
    pub fn twig_parse_ext(
        input: *const u8,
        input_len: usize,
        format: c_int,
        md_flags: u32,
        out_doc: *mut *mut TwigDocument,
    ) -> TwigStatus;
    pub fn twig_document_destroy(doc: *mut TwigDocument);
    pub fn twig_document_render_html(
        doc: *mut TwigDocument,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_document_serialize(
        doc: *mut TwigDocument,
        format: c_int,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_document_ast_json(
        doc: *mut TwigDocument,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_document_query(
        doc: *mut TwigDocument,
        selector: *const u8,
        selector_len: usize,
        out_ptr: *mut *const TwigQueryMatch,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_document_node_span(
        doc: *mut TwigDocument,
        node_id: u32,
        out_span: *mut TwigSpan,
    ) -> TwigStatus;
    pub fn twig_document_node_content_span(
        doc: *mut TwigDocument,
        node_id: u32,
        out_span: *mut TwigSpan,
    ) -> TwigStatus;
    pub fn twig_document_node_marker_span(
        doc: *mut TwigDocument,
        node_id: u32,
        out_span: *mut TwigSpan,
    ) -> TwigStatus;
    pub fn twig_document_attrs_span(
        doc: *mut TwigDocument,
        node_id: u32,
        out_span: *mut TwigSpan,
    ) -> TwigStatus;
    pub fn twig_document_line_prefix(
        doc: *mut TwigDocument,
        offset: usize,
        out_span: *mut TwigSpan,
    ) -> TwigStatus;
    pub fn twig_document_continuation_prefix(
        doc: *mut TwigDocument,
        offset: usize,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
        out_columns: *mut usize,
    ) -> TwigStatus;
    pub fn twig_document_blank_line_prefix(
        doc: *mut TwigDocument,
        offset: usize,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
        out_columns: *mut usize,
    ) -> TwigStatus;
    pub fn twig_document_cell_colspan(
        doc: *mut TwigDocument,
        node_id: u32,
        out_colspan: *mut u32,
    ) -> TwigStatus;
    pub fn twig_document_cell_rowspan(
        doc: *mut TwigDocument,
        node_id: u32,
        out_rowspan: *mut u32,
    ) -> TwigStatus;
    pub fn twig_document_nodes(
        doc: *mut TwigDocument,
        out_ptr: *mut *const TwigFlatNode,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_document_definitions(
        doc: *mut TwigDocument,
        out_ptr: *mut *const TwigQueryMatch,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_document_diagnostics(
        doc: *mut TwigDocument,
        format: c_int,
        out_ptr: *mut *const TwigWarning,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_document_children(
        doc: *mut TwigDocument,
        node_id: u32,
        out_ptr: *mut *const TwigQueryMatch,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_document_subtree(
        doc: *mut TwigDocument,
        node_id: u32,
        out_ptr: *mut *const TwigFlatNode,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_document_node_at(
        doc: *mut TwigDocument,
        offset: usize,
        out_match: *mut TwigQueryMatch,
    ) -> TwigStatus;
    pub fn twig_document_nodes_at(
        doc: *mut TwigDocument,
        offset: usize,
        out_ptr: *mut *const TwigQueryMatch,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_document_node_at_caret(
        doc: *mut TwigDocument,
        offset: usize,
        out_match: *mut TwigQueryMatch,
    ) -> TwigStatus;
    pub fn twig_document_nodes_at_caret(
        doc: *mut TwigDocument,
        offset: usize,
        out_ptr: *mut *const TwigQueryMatch,
        out_len: *mut usize,
    ) -> TwigStatus;

    pub fn twig_editor_create(
        input: *const u8,
        input_len: usize,
        format: c_int,
        out_editor: *mut *mut TwigEditor,
    ) -> TwigStatus;
    pub fn twig_editor_create_ext(
        input: *const u8,
        input_len: usize,
        format: c_int,
        md_flags: u32,
        out_editor: *mut *mut TwigEditor,
    ) -> TwigStatus;
    pub fn twig_editor_destroy(editor: *mut TwigEditor);
    pub fn twig_editor_replace(
        editor: *mut TwigEditor,
        locator: *const u8,
        locator_len: usize,
        text: *const u8,
        text_len: usize,
    ) -> TwigStatus;
    pub fn twig_editor_replace_content(
        editor: *mut TwigEditor,
        locator: *const u8,
        locator_len: usize,
        text: *const u8,
        text_len: usize,
    ) -> TwigStatus;
    pub fn twig_editor_insert_before(
        editor: *mut TwigEditor,
        locator: *const u8,
        locator_len: usize,
        text: *const u8,
        text_len: usize,
    ) -> TwigStatus;
    pub fn twig_editor_insert_after(
        editor: *mut TwigEditor,
        locator: *const u8,
        locator_len: usize,
        text: *const u8,
        text_len: usize,
    ) -> TwigStatus;
    pub fn twig_editor_insert_child(
        editor: *mut TwigEditor,
        locator: *const u8,
        locator_len: usize,
        child_index: usize,
        text: *const u8,
        text_len: usize,
    ) -> TwigStatus;
    pub fn twig_editor_delete(
        editor: *mut TwigEditor,
        locator: *const u8,
        locator_len: usize,
    ) -> TwigStatus;
    pub fn twig_editor_delete_smart(
        editor: *mut TwigEditor,
        locator: *const u8,
        locator_len: usize,
    ) -> TwigStatus;
    pub fn twig_editor_unwrap(
        editor: *mut TwigEditor,
        locator: *const u8,
        locator_len: usize,
    ) -> TwigStatus;
    pub fn twig_editor_move_before(
        editor: *mut TwigEditor,
        locator: *const u8,
        locator_len: usize,
        anchor: *const u8,
        anchor_len: usize,
    ) -> TwigStatus;
    pub fn twig_editor_move_after(
        editor: *mut TwigEditor,
        locator: *const u8,
        locator_len: usize,
        anchor: *const u8,
        anchor_len: usize,
    ) -> TwigStatus;
    pub fn twig_editor_filter(
        editor: *mut TwigEditor,
        drop: *const u8,
        drop_len: usize,
        keep: *const u8,
        keep_len: usize,
        unwrap_kept: c_int,
    ) -> TwigStatus;
    pub fn twig_editor_source(
        editor: *mut TwigEditor,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_editor_document(
        editor: *mut TwigEditor,
        out_doc: *mut *mut TwigDocument,
    ) -> TwigStatus;
    pub fn twig_editor_ast_json(
        editor: *mut TwigEditor,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_editor_query(
        editor: *mut TwigEditor,
        selector: *const u8,
        selector_len: usize,
        out_ptr: *mut *const TwigQueryMatch,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_editor_edit_range(
        editor: *mut TwigEditor,
        start: usize,
        end: usize,
        text: *const u8,
        text_len: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_last_change(
        editor: *mut TwigEditor,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_undo(editor: *mut TwigEditor, out_change: *mut TwigChange) -> TwigStatus;
    pub fn twig_editor_redo(editor: *mut TwigEditor, out_change: *mut TwigChange) -> TwigStatus;
    pub fn twig_editor_coalesce_last(editor: *mut TwigEditor) -> TwigStatus;
    pub fn twig_editor_revision(editor: *mut TwigEditor) -> u64;
    pub fn twig_editor_dirty_range(editor: *mut TwigEditor, out_span: *mut TwigSpan) -> TwigStatus;
    pub fn twig_editor_clear_dirty(editor: *mut TwigEditor) -> TwigStatus;
    pub fn twig_editor_set_caret_blob(
        editor: *mut TwigEditor,
        blob_ptr: *const u8,
        blob_len: usize,
    ) -> TwigStatus;
    pub fn twig_editor_caret_blob(
        editor: *mut TwigEditor,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_editor_nodes(
        editor: *mut TwigEditor,
        out_ptr: *mut *const TwigFlatNode,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_editor_child_spans(
        editor: *mut TwigEditor,
        node_id: u32,
        out_ptr: *mut *const TwigQueryMatch,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_editor_subtree(
        editor: *mut TwigEditor,
        node_id: u32,
        out_ptr: *mut *const TwigFlatNode,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_editor_node_at(
        editor: *mut TwigEditor,
        offset: usize,
        out_match: *mut TwigQueryMatch,
    ) -> TwigStatus;
    pub fn twig_editor_nodes_at(
        editor: *mut TwigEditor,
        offset: usize,
        out_ptr: *mut *const TwigQueryMatch,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_editor_wrap_range(
        editor: *mut TwigEditor,
        start: usize,
        end: usize,
        kind: c_int,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_toggle_inline(
        editor: *mut TwigEditor,
        start: usize,
        end: usize,
        kind: c_int,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_set_block(
        editor: *mut TwigEditor,
        offset: usize,
        block_kind: c_int,
        level: u32,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_toggle_block_container(
        editor: *mut TwigEditor,
        start: usize,
        end: usize,
        container_kind: c_int,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_renumber_ordered_lists(
        editor: *mut TwigEditor,
        offset: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    /// Whether `format` can spell `gesture` — the toolbar's gray-out question,
    /// asked without a document. `kind` is read in that gesture's own kind
    /// space (a `TWIG_GESTURE_*` doc comment in `twig.h` lists which), and must
    /// be 0 for a gesture that takes none.
    pub fn twig_format_supports(
        format: c_int,
        gesture: c_int,
        kind: c_int,
        out_supported: *mut c_int,
    ) -> TwigStatus;
    /// `twig_format_supports` for a document parsed with `md_flags` — the
    /// question asked of the table the editor actually holds. A Markdown
    /// extension can widen what may be authored: `==x==` is text under default
    /// options and a `mark` under `TWIG_MD_HIGHLIGHT`, and
    /// `TWIG_GESTURE_SET_MARK_COLOR` needs `TWIG_MD_HIGHLIGHT_COLORS` on top.
    pub fn twig_format_supports_ext(
        format: c_int,
        md_flags: u32,
        gesture: c_int,
        kind: c_int,
        out_supported: *mut c_int,
    ) -> TwigStatus;
    /// Whether `format` can be authored into at all — 0 for a parse-only
    /// format. A weaker claim than it looks; see `twig_format_supports`.
    pub fn twig_format_is_authorable(format: c_int, out_authorable: *mut c_int) -> TwigStatus;
    pub fn twig_editor_table_edit(
        editor: *mut TwigEditor,
        offset: usize,
        op: c_int,
        arg: c_int,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_insert_table(
        editor: *mut TwigEditor,
        offset: usize,
        rows: usize,
        cols: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_insert_directive(
        editor: *mut TwigEditor,
        offset: usize,
        name_ptr: *const u8,
        name_len: usize,
        label_ptr: *const u8,
        label_len: usize,
        attrs_ptr: *const TwigKeyVal,
        attrs_len: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_set_block_attrs(
        editor: *mut TwigEditor,
        offset: usize,
        attrs_ptr: *const TwigKeyVal,
        attrs_len: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_wrap_range_attrs(
        editor: *mut TwigEditor,
        start: usize,
        end: usize,
        attrs_ptr: *const TwigKeyVal,
        attrs_len: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_set_node_attrs(
        editor: *mut TwigEditor,
        node_id: u32,
        attrs_ptr: *const TwigKeyVal,
        attrs_len: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_insert_link(
        editor: *mut TwigEditor,
        start: usize,
        end: usize,
        destination: *const u8,
        destination_len: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_insert_image(
        editor: *mut TwigEditor,
        start: usize,
        end: usize,
        destination: *const u8,
        destination_len: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;

    pub fn twig_editor_insert_literal(
        editor: *mut TwigEditor,
        offset: usize,
        text: *const u8,
        text_len: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;

    pub fn twig_editor_insert_line_break(
        editor: *mut TwigEditor,
        offset: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;

    pub fn twig_editor_insert_thematic_break(
        editor: *mut TwigEditor,
        offset: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;

    pub fn twig_editor_split_block(
        editor: *mut TwigEditor,
        offset: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;

    pub fn twig_editor_join_blocks(
        editor: *mut TwigEditor,
        offset: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;

    pub fn twig_editor_move_block(
        editor: *mut TwigEditor,
        from: usize,
        to: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    // `language` is OPTIONAL, carried as this ABI's (ptr, len, has_*) triple:
    // has_language == 0 leaves the fence bare, and "absent" is a different
    // request from "present but empty".
    pub fn twig_editor_toggle_code_block(
        editor: *mut TwigEditor,
        start: usize,
        end: usize,
        language: *const u8,
        language_len: usize,
        has_language: c_int,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_set_code_language(
        editor: *mut TwigEditor,
        offset: usize,
        language: *const u8,
        language_len: usize,
        has_language: c_int,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    /// Set — or clear, with `has_color == 0` — the colour of the highlight the
    /// caret at `offset` is inside. Markdown with `TWIG_MD_HIGHLIGHT_COLORS`
    /// only; the name is a `data-color` value (`red`, `blue`, …).
    pub fn twig_editor_set_mark_color(
        editor: *mut TwigEditor,
        offset: usize,
        color: *const u8,
        color_len: usize,
        has_color: c_int,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_toggle_task_item(
        editor: *mut TwigEditor,
        offset: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_set_task_checked(
        editor: *mut TwigEditor,
        offset: usize,
        checked: c_int,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_toggle_task_checked(
        editor: *mut TwigEditor,
        offset: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;
    pub fn twig_editor_insert_footnote(
        editor: *mut TwigEditor,
        offset: usize,
        label: *const u8,
        label_len: usize,
        out_change: *mut TwigChange,
    ) -> TwigStatus;

    pub fn twig_builder_create(out_builder: *mut *mut TwigBuilder) -> TwigStatus;
    pub fn twig_builder_destroy(builder: *mut TwigBuilder);
    pub fn twig_builder_add(builder: *mut TwigBuilder, kind: c_int, out_id: *mut u32)
    -> TwigStatus;
    pub fn twig_builder_add_text(
        builder: *mut TwigBuilder,
        kind: c_int,
        text: *const u8,
        text_len: usize,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_heading(
        builder: *mut TwigBuilder,
        level: u32,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_code_block(
        builder: *mut TwigBuilder,
        lang: *const u8,
        lang_len: usize,
        has_lang: c_int,
        text: *const u8,
        text_len: usize,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_raw_block(
        builder: *mut TwigBuilder,
        format: *const u8,
        format_len: usize,
        text: *const u8,
        text_len: usize,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_metadata(
        builder: *mut TwigBuilder,
        lang: *const u8,
        lang_len: usize,
        text: *const u8,
        text_len: usize,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_raw_inline(
        builder: *mut TwigBuilder,
        format: *const u8,
        format_len: usize,
        text: *const u8,
        text_len: usize,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_smart_punctuation(
        builder: *mut TwigBuilder,
        punct_kind: c_int,
        text: *const u8,
        text_len: usize,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_link(
        builder: *mut TwigBuilder,
        destination: *const u8,
        destination_len: usize,
        has_destination: c_int,
        reference: *const u8,
        reference_len: usize,
        has_reference: c_int,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_image(
        builder: *mut TwigBuilder,
        destination: *const u8,
        destination_len: usize,
        has_destination: c_int,
        reference: *const u8,
        reference_len: usize,
        has_reference: c_int,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_directive(
        builder: *mut TwigBuilder,
        form: c_int,
        name: *const u8,
        name_len: usize,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_element(
        builder: *mut TwigBuilder,
        name: *const u8,
        name_len: usize,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_processing_instruction(
        builder: *mut TwigBuilder,
        target: *const u8,
        target_len: usize,
        data: *const u8,
        data_len: usize,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_footnote(
        builder: *mut TwigBuilder,
        label: *const u8,
        label_len: usize,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_citation(
        builder: *mut TwigBuilder,
        label: *const u8,
        label_len: usize,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_substitution(
        builder: *mut TwigBuilder,
        label: *const u8,
        label_len: usize,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_reference(
        builder: *mut TwigBuilder,
        label: *const u8,
        label_len: usize,
        destination: *const u8,
        destination_len: usize,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_bullet_list(
        builder: *mut TwigBuilder,
        style: c_int,
        tight: c_int,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_ordered_list(
        builder: *mut TwigBuilder,
        numbering: c_int,
        delim: c_int,
        tight: c_int,
        start: u32,
        has_start: c_int,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_task_list(
        builder: *mut TwigBuilder,
        tight: c_int,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_task_list_item(
        builder: *mut TwigBuilder,
        checked: c_int,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_row(
        builder: *mut TwigBuilder,
        head: c_int,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_cell(
        builder: *mut TwigBuilder,
        head: c_int,
        alignment: c_int,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_add_cell_spanning(
        builder: *mut TwigBuilder,
        head: c_int,
        alignment: c_int,
        colspan: u32,
        rowspan: u32,
        out_id: *mut u32,
    ) -> TwigStatus;
    pub fn twig_builder_set_children(
        builder: *mut TwigBuilder,
        parent: u32,
        ids: *const u32,
        ids_len: usize,
    ) -> TwigStatus;
    pub fn twig_builder_set_attrs(
        builder: *mut TwigBuilder,
        id: u32,
        kvs: *const TwigKeyVal,
        kvs_len: usize,
    ) -> TwigStatus;
    pub fn twig_builder_render_html(
        builder: *mut TwigBuilder,
        root: u32,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_builder_serialize(
        builder: *mut TwigBuilder,
        root: u32,
        format: c_int,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_builder_ast_json(
        builder: *mut TwigBuilder,
        root: u32,
        out_ptr: *mut *const u8,
        out_len: *mut usize,
    ) -> TwigStatus;
    pub fn twig_builder_query(
        builder: *mut TwigBuilder,
        root: u32,
        selector: *const u8,
        selector_len: usize,
        out_ptr: *mut *const TwigQueryMatch,
        out_len: *mut usize,
    ) -> TwigStatus;
}