Skip to main content

Crate carve

Crate carve 

Source
Expand description

Carve — a parser + HTML renderer for the Carve markup language.

§Quick start

let html = carve::to_html("# Hello\n\n/italic/ and *bold*.");
assert!(html.contains("<h1>Hello</h1>"));
assert!(html.contains("<em>italic</em>"));

Use parse and render_html when a caller needs the AST between those steps. from_json reads the public AST exchange format, and try_to_json reports serialization failures for caller-built trees. HTML and BBCode importers, and importer functions named try_*, return fallible results.

File inclusion can be run through prepare_doc_with_includes or as a separate pass through includes::expand_includes. The fs feature enables the built-in filesystem resolver; disabling default features leaves resolver choice with the host.

Implementation status: passes every .crv / .html pair currently checked into this crate’s tests/spec submodule, including tables, captions / figures, admonitions, abbreviations, mentions, tags, inline extensions, attributes, and frontmatter.

Re-exports§

pub use accessibility::lint_accessibility;
pub use accessibility::AccessibilityDiagnostic;
pub use accessibility::AccessibilitySeverity;
pub use ast_envelope::from_ast_envelope_json;
pub use ast_envelope::to_ast_envelope_json;
pub use ast_envelope::AstEnvelopeError;
pub use ast_envelope::AstEnvelopeExtension;
pub use ast_envelope::AstEnvelopeOptions;
pub use ast_envelope::AstEnvelopeReaderOptions;
pub use ast_envelope::AST_CONTRACT_VERSION;
pub use ast_envelope::CORE_AST_VOCABULARY;
pub use ast_json::from_json;
pub use ast_json::to_json;
pub use ast_json::try_to_json;
pub use ast_json::AstJsonError;
pub use ast_json::AstJsonErrorKind;
pub use ast_merge::merge_ast;
pub use ast_merge::merge_ast_with_resolver;
pub use ast_merge::MergeConflict;
pub use ast_merge::MergeConflictReason;
pub use ast_merge::MergeResolution;
pub use ast_merge::MergeResult;
pub use ast_patch::apply_ast_patch;
pub use ast_patch::apply_reversible_ast_patch;
pub use ast_patch::ast_patch_from_json;
pub use ast_patch::ast_patch_to_json;
pub use ast_patch::create_ast_patch;
pub use ast_patch::create_reversible_ast_patch;
pub use ast_patch::AstPatchError;
pub use ast_patch::AstPatchOperation;
pub use ast_patch::ReversibleAstPatch;
pub use ast_sidecars::authored_provenance;
pub use ast_sidecars::fresh_node_identity;
pub use ast_sidecars::from_annotation_ranges_json;
pub use ast_sidecars::from_node_identity_json;
pub use ast_sidecars::from_provenance_json;
pub use ast_sidecars::parse_with_authored_provenance;
pub use ast_sidecars::to_annotation_ranges_json;
pub use ast_sidecars::to_node_identity_json;
pub use ast_sidecars::to_provenance_json;
pub use ast_sidecars::AnnotationAnchor;
pub use ast_sidecars::AnnotationRange;
pub use ast_sidecars::AnnotationRanges;
pub use ast_sidecars::AstSidecarError;
pub use ast_sidecars::NodeIdentity;
pub use ast_sidecars::NodeIdentityEntry;
pub use ast_sidecars::NodeProvenance;
pub use ast_sidecars::Provenance;
pub use ast_sidecars::ProvenanceOrigin;
pub use ast_sidecars::ProvenanceSource;
pub use bbcode_migrate::bbcode_to_carve;
pub use bbcode_migrate::BbcodeImportError;
pub use bbcode_migrate::BBCODE_MAX_INPUT_LENGTH;
pub use conversion_diagnostics::conversion_diagnostics;
pub use conversion_diagnostics::to_conversion_diagnostics_json;
pub use conversion_diagnostics::ConversionDiagnostic;
pub use conversion_diagnostics::ConversionDiagnosticCode;
pub use conversion_diagnostics::ConversionDiagnostics;
pub use conversion_diagnostics::ConversionPos;
pub use conversion_diagnostics::DEFAULT_MAX_CONVERSION_DIAGNOSTICS;
pub use djot_migrate::djot_to_carve;
pub use extensions::sanitize_svg;
pub use extensions::AutolinkOptions;
pub use extensions::CodeCallouts;
pub use extensions::CodeGroup;
pub use extensions::CodeGroupOptions;
pub use extensions::ColorSwatch;
pub use extensions::ContentMode;
pub use extensions::CrossrefStyle;
pub use extensions::Details;
pub use extensions::ExternalLinksOptions;
pub use extensions::FencedRender;
pub use extensions::FencedRenderOptions;
pub use extensions::Glossary;
pub use extensions::HeadingLevelShift;
pub use extensions::HeadingLevelShiftOptions;
pub use extensions::HeadingNumbers;
pub use extensions::HeadingNumbersOptions;
pub use extensions::HeadingPermalinksOptions;
pub use extensions::HeadingReference;
pub use extensions::HeadingReferenceOptions;
pub use extensions::ImgFence;
pub use extensions::Index;
pub use extensions::ListTable;
pub use extensions::ListType;
pub use extensions::MathBlock;
pub use extensions::MathBlockOptions;
pub use extensions::Position;
pub use extensions::QuoteCharacters;
pub use extensions::SanitizeResult;
pub use extensions::SanitizeSvgOptions;
pub use extensions::SmartQuotes;
pub use extensions::Spoiler;
pub use extensions::SwatchPosition;
pub use extensions::SwatchShape;
pub use extensions::TabNormalize;
pub use extensions::TableOfContents;
pub use extensions::TableOfContentsOptions;
pub use extensions::Tabs;
pub use extensions::TabsMode;
pub use extensions::TabsOptions;
pub use extensions::TocPlacement;
pub use extensions::UrlGenerator;
pub use extensions::WikilinksOptions;
pub use extensions::SMART_QUOTE_LOCALES;
pub use html_import::html_to_ast;
pub use html_import::html_to_carve;
pub use html_import::HtmlImportAdapter;
pub use html_import::HtmlImportDiagnostic;
pub use html_import::HtmlImportDiagnosticCode;
pub use html_import::HtmlImportError;
pub use html_import::HtmlImportMode;
pub use html_import::HtmlImportOptions;
pub use html_import::HtmlImportReport;
pub use html_import::HtmlImportResult;
pub use html_import::HtmlImportSeverity;
pub use html_import::ImportConfidence;
pub use html_import::ImportFidelity;
pub use html_import::MAX_HTML_IMPORT_DEPTH;
pub use includes::expand_includes;
pub use includes::expands_for_target;
pub use includes::select_include_region;
pub use includes::IncludeContext;
pub use includes::IncludeDenial;
pub use includes::IncludeDependency;
pub use includes::IncludeOptions;
pub use includes::IncludeRegion;
pub use includes::IncludeRegionError;
pub use includes::IncludeRegionMode;
pub use includes::IncludeResolved;
pub use includes::IncludeResolver;
pub use includes::IncludeResult;
pub use includes::IncludeWarning;
pub use includes::DEFAULT_MAX_DEPTH;
pub use includes::DEFAULT_MAX_RESOLVER_CALLS;
pub use includes::DEFAULT_MAX_WARNINGS;
pub use includes::FileSystemResolver;
pub use includes::DEFAULT_MAX_FILE_BYTES;
pub use incremental::parse_snapshot;
pub use incremental::parse_snapshot_with_identity;
pub use incremental::reparse;
pub use incremental::IncrementalParse;
pub use incremental::IncrementalParseError;
pub use incremental::ParserSnapshot;
pub use incremental::TextChange;
pub use lint::lint_carve;
pub use lint::lint_carve_with_options;
pub use lint::migrate_case_only_references;
pub use lint::LintWarning;
pub use markdown_import::markdown_to_ast;
pub use markdown_import::markdown_to_carve;
pub use markdown_import::migration_raw_heading_ids;
pub use markdown_import::try_markdown_to_ast;
pub use markdown_import::try_markdown_to_carve;
pub use migration::migrate_bbcode;
pub use migration::migrate_djot;
pub use migration::migrate_html;
pub use migration::migrate_markdown;
pub use migration::try_migrate_markdown;
pub use migration::try_migrate_markdown_for_directory;
pub use migration::MigrationConfidence;
pub use migration::MigrationDiagnostic;
pub use migration::MigrationFidelity;
pub use migration::MigrationReport;
pub use migration::MigrationResult;
pub use migration::SourceFormat;
pub use profile::DisallowedAction;
pub use profile::LinkPolicy;
pub use profile::Profile;
pub use profile::ProfileViolation;
pub use profile::ProfileViolationError;
pub use profile_filter::apply_profile;
pub use profile_filter::apply_profile_with_typography;
pub use profile_filter::ProfileFilterResult;
pub use prosemirror::from_prosemirror;
pub use prosemirror::from_prosemirror_with_report;
pub use prosemirror::to_prosemirror;
pub use prosemirror::ProseMirrorDoc;
pub use prosemirror::ProseMirrorError;
pub use prosemirror::ProseMirrorImport;
pub use stream::try_render_html_streaming;
pub use stream::StreamOutcome;
pub use ast::*;

Modules§

accessibility
Accessibility lint for Carve source. Accessibility checks for Carve source.
ast
Carve AST nodes for parsing, transformation, and rendering.
ast_envelope
The versioned AST interchange envelope (PART 12 §34, [CARVE-P12-056]).
ast_json
JSON encoding/decoding for the public Carve AST exchange shape.
ast_merge
Conservative three-way merge for the normative PART 12 exchange tree.
ast_patch
Position-independent patch replay for PART 12 exchange trees.
ast_sidecars
Optional metadata beside the canonical AST (PART 12 §§38, 40, 41).
bbcode_migrate
BBCode-to-Carve migration.
conversion_diagnostics
Source conversion losses, separate from losses of a selected renderer.
djot_migrate
Migrate Djot source to Carve source.
extensions
Built-in opt-in Carve extensions, ported from the carve-js modules.
html_import
HTML5-to-Carve migration boundary.
includes
Opt-in file inclusion with host-supplied resolution and diagnostics. Processor-level file inclusion ({{ path }}), spec PART 9 §19 (I1-I11).
incremental
Incremental parsing snapshots and text-change results. Incremental parse snapshots and source edits.
lint
Source diagnostics for silent degradations.
markdown_import
Markdown-to-Carve migration boundary.
migration
Import and migration results for supported source formats. Migration results and diagnostics for supported source formats.
profile
Profile-based feature restriction (core; port of carve-php’s Profile + LinkPolicy + ProfileFilter, and parity with carve-js’ profile.ts / profile-filter.ts).
profile_filter
Profile AST transform (port of carve-php’s ProfileFilter / carve-js’ profile-filter.ts).
prosemirror
Conversion from the Carve AST to the ProseMirror/CarveKit JSON shape.
stream
Chunked HTML output on a fast path that may return NeedsAst. Chunked HTML rendering on the borrowed-layout fast path.

Structs§

BeforeRenderContext
Context handed to CarveExtension::before_render. Carries the render Options and the effective Mode for the target format - which is always Mode::Interactive for the non-HTML renderers, so static rendering stays an HTML-only concern even when a single Options is reused across formats.
BlockMatch
Block node and line count returned by an extension matcher.
CarveWriterOptions
Options for writing Carve source.
CheckedRenderOptions
Strictness and retention limit for checked rendering.
Citations
Citation extension with optional bibliography data.
CslDate
A CSL-JSON issued date (the subset the minimal formatter reads).
CslEntry
A CSL-JSON bibliography entry (the subset the minimal formatter reads).
CslName
A CSL-JSON name object (the subset the minimal formatter reads). The host builds these from parsed CSL-JSON; the extension does no file I/O or parsing.
InlineMatch
Inline node and endpoint returned by an extension matcher.
MatcherContext
Parser access supplied to an extension matcher.
Options
Parser and renderer settings for one Carve operation.
ParsedLocator
The result of parsing the locator text after a citation key’s comma.
PreparedWithIncludes
Output of prepare_doc_with_includes: the fully prepared document plus the include diagnostics a host needs for reporting and file watching.
RenderContext
Rendering helpers and settings supplied to extension hooks.
RenderDepthError
A render refused because the tree is deeper than the renderer’s ceiling.
RenderLoss
One detail that an output target would discard or change.
RenderLossError
Error returned when strict rendering would lose content.
RenderResult
Rendered value and a bounded report of losses.
SocialLinkResolverInput
Read-only data supplied to one social-link resolver invocation.
SourceEdit
A byte-range replacement applied by a source patch.
SourcePatch
Stale-safe edits and unresolved suggestions for one source string.
SourcePatchError
Reason a source patch could not be applied.
SourceSuggestion
Proposed replacement that the patch could not apply automatically.
SourceUnspellable
The canonical writer cannot spell an AST node without changing it.
Stamp
A document’s provenance, as recorded by the marker.
StaticRenderers
Build-time renderers for client-script extensions, supplied for a Mode::Static HTML render. Each maps the construct’s source to a self-contained string the engine emits directly (an <svg> / <img> for a diagram, MathML / HTML for math). When the renderer a node needs is absent, the extension’s static path falls back to source - never blank.

Enums§

AsciiHeadingIds
Whether smart typography renders as its glyph or as the source run the author typed.
CarveWriteError
Why the canonical Carve writer produced no source.
CitationMode
Built-in citation formatting mode.
MarkdownRenderError
A Markdown render refused by the depth guard or by a roundtrip carrier.
Mode
Render mode - a render OPTION, not document syntax. See the extensions contract §2.5 “Static rendering mode”.
RawNodeType
Whether a raw source node is inline or block content.
RenderCarveError
A typed reason the canonical Carve writer refused a tree.
RenderTarget
Output format checked for render losses.
SmartTypographyMode
is usually better off with the characters that were actually typed: the glyph is a presentation choice the consumer did not ask for and cannot undo, and a search for the source spelling misses it.
SocialLinkKind
The two core social-token node kinds accepted by a resolver.
SourceEditKind
Purpose of a source edit or suggestion.
StampForm
Source spelling used for a generated version marker.

Constants§

DEFAULT_MAX_RENDER_LOSSES
Default maximum number of retained render losses.
LABEL_FOOTNOTE_BACKLINK
The labels key for the endnote backlink’s accessible name (PART 9 §16a).
MAX_RENDER_DEPTH
The recursion bound every renderer shares, and it MUST sit ABOVE the parser’s (§25).
SPEC_VERSION
The Carve specification version this engine implements.

Traits§

CarveExtension
Hooks for recognizing, transforming, and rendering extension nodes.

Functions§

apply_source_patch
Apply a patch only when its source fingerprint and byte ranges still match.
create_source_patch
Build the smallest single replacement that produces replacement.
decision_trace
The decision trace of source as JSON lines: the header, then one block record per source line from the ownership walk.
label_default
The English default for a labels key, and the whole set.
needs_review
Whether a document was last processed under an older spec version than this implementation targets, so its [behavior] changelog entries are worth reviewing.
parse
Parse Carve source with default options.
parse_experimental_event_blocks
Try the opt-in line-event parser for simple documents. The boolean reports whether the event route was admitted; other inputs use the standard parser.
parse_experimental_event_blocks_with_options
Try the opt-in line-event parser with parser options. Unsupported option combinations use the standard parser and return false for admission.
parse_locator
Parse the locator portion of a citation (the text after the comma and key).
parse_with_options
Parse Carve source using the supplied parser options.
parse_with_source_layout
Parse with positions enabled and return the semantic document plus its sidecar JSON.
prepare_doc_with_includes
Parse, expand {{ … }} includes, then run the same extension-hook and profile pipeline the to_* entry points use, returning the prepared document alongside the include diagnostics.
prepare_document_for_render
Run render-time extension hooks and the configured feature profile on an already-built document. Used by --from-json, where parsing has happened in another process but render restrictions must still apply.
read_stamp
Read a document’s provenance marker, or None when it carries none.
render_ansi
Render a tree that did NOT come from the parser, refusing at the ceiling.
render_ansi_with_options
Render a document to ANSI-styled text, honouring Options::smart_typography. See render_markdown_with_options for why the options-taking wrapper exists; the profile transform runs upstream. Render a tree that did NOT come from the parser, refusing at the ceiling.
render_carve
Render a tree as canonical Carve source.
render_carve_with_options
Render a tree with writer options.
render_html
Render a tree that did NOT come from the parser, refusing at the ceiling.
render_html_owned
Render an owned document without cloning its tree.
render_html_owned_with_options
Render an owned document with options, without cloning its tree.
render_html_with_options
Render a tree that did NOT come from the parser, refusing at the ceiling.
render_markdown
Render a document to Markdown with the default settings, so smart typography renders as its glyph. Render a tree that did NOT come from the parser, refusing at the ceiling.
render_markdown_with_options
Render a document to Markdown, honouring Options::smart_typography. The profile transform is applied to doc upstream (see crate::prepare_doc). Render a tree that did NOT come from the parser, refusing at the ceiling.
render_plain_text
Render a tree that did NOT come from the parser, refusing at the ceiling.
render_plain_text_with_options
Render a document to plain text, honouring Options::smart_typography. See render_markdown_with_options for why the options-taking wrapper exists; the profile transform runs upstream. Render a tree that did NOT come from the parser, refusing at the ceiling.
source_fingerprint
Compute the FNV-1a fingerprint used to reject stale patches.
stamp_carve
Append (or replace) the provenance marker on already-formatted Carve. generated_by is the engine identity, e.g. carve-rs 0.1.0.
to_ansi
Parse a Carve source string and render it as ANSI-styled text in one call.
to_ansi_with_options
Infallible ANSI entry point. See to_html_with_options.
to_ansi_with_report
Render ANSI text and report raw inline nodes. Raw blocks have a visible [raw:format] fallback and therefore are not losses on this target.
to_carve
Parse a Carve source string and render canonical Carve source in one call.
to_carve_patch
Prepare canonical formatting as a stale-safe patch without changing source.
to_carve_with_options
Infallible Carve-writer entry point. See to_html_with_options for the error-action fallback behavior.
to_carve_with_report
Canonical Carve reports nested list items whose tightness cannot be kept.
to_html
Parse a Carve source string and render it as HTML in one call.
to_html_with_options
Infallible HTML entry point. Identical to try_to_html_with_options except that profile errors render an empty safe output instead of returning an error. Callers that need to surface violations should use try_to_html_with_options.
to_html_with_options_and_report
Render HTML under options and report what the render dropped.
to_html_with_report
Render HTML and report target-routed raw nodes that were omitted.
to_json_with_options
Parse and serialize with options, returning an empty string on failure.
to_markdown
Parse a Carve source string and render it as Markdown in one call.
to_markdown_with_options
Infallible Markdown entry point. See to_html_with_options for the error-action fallback behavior.
to_markdown_with_report
Render Markdown and report target-routed raw nodes that were omitted.
to_plain_text
Parse a Carve source string and render it as plain text in one call.
to_plain_text_with_options
Infallible plain-text entry point. See to_html_with_options.
to_plain_text_with_report
Render plain text and report every raw node omitted by that target.
to_source_layout_json
Encode the opt-in PART 12 §13 source-layout sidecar. Default AST JSON is unchanged.
try_to_ansi_with_options
Parse, run extension hooks, apply the profile, and render to ANSI text. ANSI is inherently static; see try_to_markdown_with_options for why the mode is forced to Mode::Interactive in the hooks.
try_to_carve_with_options
Parse, apply the feature-restriction profile, and render canonical Carve source. Enforces the profile’s max_length on the source bytes before the parser walks them, exactly as try_to_html_with_options does, and returns a ProfileViolationError when the cap is exceeded or the profile’s action is DisallowedAction::Error and a disallowed node is found.
try_to_html_with_options
Parse, run extension hooks, apply the profile, and render to HTML. Returns an error only when the profile’s action is DisallowedAction::Error (or max_length is exceeded).
try_to_json_with_options
Parse, run extension/profile transforms, and serialize the AST as JSON.
try_to_markdown_with_options
Parse, run extension hooks, apply the profile, and render to Markdown. Markdown is inherently static, so the render mode is forced to Mode::Interactive in the hooks (the HTML-only static path never runs); the Markdown renderer flattens containers on its own. Returns a typed writer refusal when a roundtrip carrier cannot be spelled.
try_to_plain_text_with_options
Parse, run extension hooks, apply the profile, and render to plain text. Plain text is inherently static; see try_to_markdown_with_options for why the mode is forced to Mode::Interactive in the hooks.
with_render_loss_report
Collect actual losses produced while render runs. This is the checked entry point for custom renderers and options-taking render pipelines.

Type Aliases§

SocialLinkResolver
A host lookup that returns one complete destination, no match, or an error. Errors and unresolved results have the same inert rendered form.