Carvex.Document (Carvex v0.0.1)

Copy Markdown View Source

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 - true while rendering for Carvex.to_heex/2 or ~CRV"..."HEEX. Carvex.Raw is written verbatim, so braces in element content would be read as HEEx expressions; build such HTML with Carvex.safe_html(html, heex: true).
  • :stream - %{id: id} on each per-block document built by Carvex.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.

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

plugin()

@type plugin() :: module() | {module(), keyword()} | (t() -> t())

selector()

@type selector() :: module() | atom() | struct() | (struct() -> boolean()) | integer()

step()

@type step() :: (t() -> t() | {t(), Exception.t()}) | {module(), atom(), [term()]}

t()

@type t() :: %Carvex.Document{
  current_steps: [atom()],
  halted: boolean(),
  nodes: [struct()],
  options: keyword(),
  private: map(),
  registered_options: MapSet.t(atom()),
  source: String.t() | nil,
  steps: keyword(step())
}

Functions

append_steps(doc, steps)

@spec append_steps(t(), keyword(step())) :: t()

Appends named steps to the pipeline.

assign(doc, assigns)

@spec assign(t(), map() | keyword()) :: t()

Merges assigns from a map or keyword list.

assign(doc, key, value)

@spec assign(t(), atom(), term()) :: t()

Adds one assign.

default_sanitize_options()

@spec default_sanitize_options() :: keyword()

Default sanitize options; pass to sanitize: to enable sanitizing with the defaults.

get_option(doc, key, default \\ nil)

@spec get_option(t(), atom(), term()) :: term()

Returns an option value.

get_private(doc, key, default \\ nil)

@spec get_private(t(), atom(), term()) :: term()

Reads private data.

halt(doc)

@spec halt(t()) :: t()

Stops the pipeline; no further steps run. The document still renders.

halt(doc, exception)

@spec halt(t(), Exception.t()) :: {t(), Exception.t()}

Stops the pipeline with an exception; rendering returns {:error, exception}.

prepend_steps(doc, steps)

@spec prepend_steps(t(), keyword(step())) :: t()

Prepends named steps to the pipeline.

put_extensions(doc, extensions)

@spec put_extensions(t(), list()) :: t()

Merges :extensions: a repeated name replaces its entry in place, new names append.

put_node_in_document_root(doc, node, position \\ :top)

@spec put_node_in_document_root(t(), struct(), :top | :bottom) :: t()

Inserts node at the :top (default) or :bottom of the document root.

put_options(doc, options)

@spec put_options(t(), keyword()) :: t()

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.

put_parse_options(doc, options)

@spec put_parse_options(t(), keyword()) :: t()

Merges :parse options.

put_plugins(doc, plugins)

@spec put_plugins(t(), [plugin()]) :: t()

Attaches plugins: module calls module.attach(doc, []), {module, opts} calls module.attach(doc, opts), and a 1-arity function is called with the doc.

put_private(doc, key, value)

@spec put_private(t(), atom(), term()) :: t()

Stores private (plugin-internal) data.

put_render_options(doc, options)

@spec put_render_options(t(), keyword()) :: t()

Merges :render options.

put_sanitize_options(doc, options)

@spec put_sanitize_options(t(), keyword() | nil) :: t()

Merges :sanitize options; nil disables sanitizing.

put_source(doc, source)

@spec put_source(t(), String.t() | nil) :: t()

Sets Carve source to be parsed by run/1.

put_syntax_highlight_options(doc, options)

@spec put_syntax_highlight_options(t(), keyword() | nil) :: t()

Merges :syntax_highlight options; nil disables highlighting.

register_options(doc, options)

@spec register_options(t(), [atom()]) :: t()

Registers user option keys so put_options/2 accepts them.

run(doc)

@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.

update_nodes(doc, selector, fun)

@spec update_nodes(t(), selector(), (struct() -> struct())) :: t()

Applies fun to every node matching selector (post-order).

update_private(doc, key, default, fun)

@spec update_private(t(), atom(), term(), (term() -> term())) :: t()

Updates private data with fun, starting from default.

wrap(node_or_nodes)

@spec wrap(struct() | [struct()]) :: t()

Wraps a node or a list of nodes in a document.