carve-rs

Rust parser and renderer for the Carve markup language. The crate implements Carve spec 0.1 and renders HTML, Markdown, plain text, ANSI, and canonical Carve source. The versioning contract says what a release may change.

Install

cargo add carve-lang

Install the CLI with cargo install carve-lang, or download a release archive.

The package name is carve-lang; Rust code imports it as carve, and the CLI binary is named carve.

Library use

let html = carve::to_html("# Hello\n\nThis is /italic/ and *bold*.");

Lower-level functions expose the typed AST:

let document = carve::parse(source);
let html = carve::render_html(&document)?;

Use fallible entry points for imported content and caller-built trees:

let document = carve::from_json(payload)?;
let serialized = carve::try_to_json(&document)?;
let source = carve::try_markdown_to_carve(markdown)?;

AstJsonError::kind() distinguishes syntax, depth, unknown-field, and other AST refusals. path() identifies an unknown field; syntax errors expose line(), column(), and the original serde error through std::error::Error::source(). The compatibility to_json and markdown_to_carve functions panic on refusal.

Checked render functions report content omitted for the selected output and can return RenderLossError before publishing a value. Source-aware tools can prepare canonical formatting with to_carve_patch and apply it with apply_source_patch.

See Source-preserving patches and the full usage walkthrough.

CLI and migration

The carve CLI renders documents, formats source, exports the serialized AST, and imports HTML, Markdown, Djot, and BBCode. Importers emit structured fidelity reports and participate in --check-loss.

• Command line
• Migration
• Migration reports

Extensions and security

Extensions can add syntax, AST transforms, and renderers. Built-in profiles restrict constructs and resource use for untrusted content. Raw HTML, custom renderers, and symbol values have separate trust boundaries.

For untrusted CLI input, use --safe to escape raw HTML. See Extensions, Security, and Linting.

File inclusion

Includes are opt-in. Library hosts supply a resolver. For named CLI input, the root defaults to the file's directory; stdin stays literal unless --include-root is supplied. Expansion reports dependencies and warnings.

The file inclusion reference covers renaming, heading shifts, nested directives, containment, and current limits.

Documentation

The docs/ directory contains topic guides for rendering, extensions, the CLI, migrations, conformance, editor integration, streaming, accessibility, security, patches, and parser snapshots.

Development

Start with CONTRIBUTING.md for the toolchain, the test commands, and what a spec-affecting change involves. Build setup, tests, and engine-pin maintenance are in the development guide and engine pin guard.

Whitespace and annotation offsets

An escaped space produces a non_breaking_space node. Preserved line-block columns use the same node. Text and verbatim values keep literal Unicode, including U+E000. HTML renders generated spaces as  ; Markdown uses U+00A0, and plain text and ANSI use ordinary spaces. Package and envelope versions remain on the existing release line.

Annotation offsets count Unicode codepoints in the contract's fixed field order. They do not depend on JSON property insertion order or source positions. The shared annotation fixture covers image alt text, math, breaks and reversed ranges.