A Carve document: a tree of nodes plus a Req-like pipeline of options and steps.
The API mirrors MDEx.Document (MDEx 0.14) so plugins port mechanically.
Tree
nodes holds the top-level blocks (see Carvex.Heading, Carvex.Paragraph, …),
decoded from carve's AST exchange format. Headings are top-level blocks;
<section> wrapping happens at render time (render: [sections: true]).
Documents and nodes implement Access and Enumerable:
iex> doc = Carvex.parse_document!("Hello *world*")
iex> doc[Carvex.Strong]
[%Carvex.Strong{nodes: [%Carvex.Text{value: "world"}]}]
iex> doc[:text] |> Enum.map(& &1.value)
["Hello ", "world"]Selectors are a node module, a bare atom (:strong → Carvex.Strong), a struct
pattern where non-default fields must match (%Carvex.Heading{level: 2}), a
1-arity predicate, or an integer index into the pre-order walk.
Pipeline
Plugins are modules with an attach/2 function (or 1-arity functions) that
register options, put options, and append steps. A step is a 1-arity function
or {module, function, args} that receives the document and returns it, or
returns halt/2's {document, exception}.
defmodule ShoutPlugin do
alias Carvex.Document
def attach(doc, opts) do
doc
|> Document.register_options([:shout])
|> Document.put_options(opts)
|> Document.append_steps(shout: &shout/1)
end
defp shout(doc) do
if Document.get_option(doc, :shout) do
Document.update_nodes(doc, Carvex.Text, &%{&1 | value: String.upcase(&1.value)})
else
doc
end
end
end
Carvex.to_html!("hi", plugins: [{ShoutPlugin, shout: true}])
#=> "<p>HI</p>"Private keys set by Carvex
Steps can read these with get_private/3:
:heex-truewhile rendering forCarvex.to_heex/2or~CRV"..."HEEX.Carvex.Rawis written verbatim, so braces in element content would be read as HEEx expressions; build such HTML withCarvex.safe_html(html, heex: true).:stream-%{id: id}on each per-block document built byCarvex.stream/2. Plugins that inject page-level content (scripts, styles) should skip it (load that from the page layout instead), and include the id in element ids so they stay unique across blocks.
Options
:extensions, :parse, :render, :syntax_highlight, :sanitize, :plugins,
and :assigns; see Carvex.new/1.
Summary
Functions
Appends named steps to the pipeline.
Merges assigns from a map or keyword list.
Adds one assign.
Default sanitize options; pass to sanitize: to enable sanitizing with the defaults.
Returns an option value.
Reads private data.
Stops the pipeline; no further steps run. The document still renders.
Stops the pipeline with an exception; rendering returns {:error, exception}.
Prepends named steps to the pipeline.
Merges :extensions: a repeated name replaces its entry in place, new names append.
Inserts node at the :top (default) or :bottom of the document root.
Merges options into the document. :plugins are attached first, then the
remaining keys are applied in order.
Merges :parse options.
Attaches plugins: module calls module.attach(doc, []), {module, opts}
calls module.attach(doc, opts), and a 1-arity function is called with the doc.
Stores private (plugin-internal) data.
Merges :render options.
Merges :sanitize options; nil disables sanitizing.
Sets Carve source to be parsed by run/1.
Merges :syntax_highlight options; nil disables highlighting.
Registers user option keys so put_options/2 accepts them.
Runs the pipeline: parses pending source (appending to nodes), then runs
the pending steps in order until one halts.
Applies fun to every node matching selector (post-order).
Updates private data with fun, starting from default.
Wraps a node or a list of nodes in a document.
Types
Functions
Appends named steps to the pipeline.
Merges assigns from a map or keyword list.
Adds one assign.
@spec default_sanitize_options() :: keyword()
Default sanitize options; pass to sanitize: to enable sanitizing with the defaults.
Returns an option value.
Reads private data.
Stops the pipeline; no further steps run. The document still renders.
@spec halt(t(), Exception.t()) :: {t(), Exception.t()}
Stops the pipeline with an exception; rendering returns {:error, exception}.
Prepends named steps to the pipeline.
Merges :extensions: a repeated name replaces its entry in place, new names append.
Inserts node at the :top (default) or :bottom of the document root.
Merges options into the document. :plugins are attached first, then the
remaining keys are applied in order.
Raises ArgumentError for keys that are neither built-in nor registered.
Merges :parse options.
Attaches plugins: module calls module.attach(doc, []), {module, opts}
calls module.attach(doc, opts), and a 1-arity function is called with the doc.
Stores private (plugin-internal) data.
Merges :render options.
Merges :sanitize options; nil disables sanitizing.
Sets Carve source to be parsed by run/1.
Merges :syntax_highlight options; nil disables highlighting.
Registers user option keys so put_options/2 accepts them.
@spec run(t()) :: t() | {t(), Exception.t()}
Runs the pipeline: parses pending source (appending to nodes), then runs
the pending steps in order until one halts.
A parse failure returns {document, %Carvex.CarveError{}} with source cleared.
Applies fun to every node matching selector (post-order).
Updates private data with fun, starting from default.
Wraps a node or a list of nodes in a document.