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::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::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::Autolink;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::ExternalLinks;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::HeadingPermalinks;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::Wikilinks;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§
- Before
Render Context - Context handed to
CarveExtension::before_render. Carries the renderOptionsand the effectiveModefor the target format - which is alwaysMode::Interactivefor the non-HTML renderers, so static rendering stays an HTML-only concern even when a singleOptionsis reused across formats. - Block
Match - Block node and line count returned by an extension matcher.
- Carve
Writer Options - Options for writing Carve source.
- Checked
Render Options - Strictness and retention limit for checked rendering.
- Citations
- Citation extension with optional bibliography data.
- CslDate
- A CSL-JSON
issueddate (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.
- Inline
Match - Inline node and endpoint returned by an extension matcher.
- Matcher
Context - Parser access supplied to an extension matcher.
- Options
- Parser and renderer settings for one Carve operation.
- Parsed
Locator - The result of parsing the locator text after a citation key’s comma.
- Prepared
With Includes - Output of
prepare_doc_with_includes: the fully prepared document plus the include diagnostics a host needs for reporting and file watching. - Render
Context - Rendering helpers and settings supplied to extension hooks.
- Render
Depth Error - A render refused because the tree is deeper than the renderer’s ceiling.
- Render
Loss - One detail that an output target would discard or change.
- Render
Loss Error - Error returned when strict rendering would lose content.
- Render
Result - Rendered value and a bounded report of losses.
- Social
Link Resolver Input - Read-only data supplied to one social-link resolver invocation.
- Source
Edit - A byte-range replacement applied by a source patch.
- Source
Patch - Stale-safe edits and unresolved suggestions for one source string.
- Source
Patch Error - Reason a source patch could not be applied.
- Source
Suggestion - Proposed replacement that the patch could not apply automatically.
- Source
Unspellable - The canonical writer cannot spell an AST node without changing it.
- Stamp
- A document’s provenance, as recorded by the marker.
- Static
Renderers - Build-time renderers for client-script extensions, supplied for a
Mode::StaticHTML 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§
- Ascii
Heading Ids - Whether smart typography renders as its glyph or as the source run the author typed.
- Carve
Write Error - Why the canonical Carve writer produced no source.
- Citation
Mode - Built-in citation formatting mode.
- Markdown
Render Error - 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”.
- RawNode
Type - Whether a raw source node is inline or block content.
- Render
Carve Error - A typed reason the canonical Carve writer refused a tree.
- Render
Target - Output format checked for render losses.
- Smart
Typography Mode - 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.
- Social
Link Kind - The two core social-token node kinds accepted by a resolver.
- Source
Edit Kind - Purpose of a source edit or suggestion.
- Stamp
Form - Source spelling used for a generated version marker.
Constants§
- DEFAULT_
MAX_ RENDER_ LOSSES - Default maximum number of retained render losses.
- LABEL_
FOOTNOTE_ BACKLINK - The
labelskey 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§
- Carve
Extension - 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
sourceas JSON lines: the header, then one block record per source line from the ownership walk. - label_
default - The English default for a
labelskey, 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
falsefor 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 theto_*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
Nonewhen 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. Seerender_markdown_with_optionsfor 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 todocupstream (seecrate::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. Seerender_markdown_with_optionsfor 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_byis 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_optionsfor 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_optionsexcept that profile errors render an empty safe output instead of returning an error. Callers that need to surface violations should usetry_to_html_with_options. - to_
html_ with_ options_ and_ report - Render HTML under
optionsand 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_optionsfor 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_optionsfor why the mode is forced toMode::Interactivein the hooks. - try_
to_ carve_ with_ options - Parse, apply the feature-restriction profile, and render canonical Carve
source. Enforces the profile’s
max_lengthon the source bytes before the parser walks them, exactly astry_to_html_with_optionsdoes, and returns aProfileViolationErrorwhen the cap is exceeded or the profile’s action isDisallowedAction::Errorand 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(ormax_lengthis 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::Interactivein 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_optionsfor why the mode is forced toMode::Interactivein the hooks. - with_
render_ loss_ report - Collect actual losses produced while
renderruns. This is the checked entry point for custom renderers and options-taking render pipelines.
Type Aliases§
- Social
Link Resolver - A host lookup that returns one complete destination, no match, or an error. Errors and unresolved results have the same inert rendered form.