# `Carvex.Document`
[🔗](https://github.com/paradox460/carvex/blob/v0.0.1/lib/carvex/document.ex#L1)

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

# `plugin`

```elixir
@type plugin() :: module() | {module(), keyword()} | (t() -&gt; t())
```

# `selector`

```elixir
@type selector() :: module() | atom() | struct() | (struct() -&gt; boolean()) | integer()
```

# `step`

```elixir
@type step() :: (t() -&gt; t() | {t(), Exception.t()}) | {module(), atom(), [term()]}
```

# `t`

```elixir
@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())
}
```

# `append_steps`

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

Appends named steps to the pipeline.

# `assign`

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

Merges assigns from a map or keyword list.

# `assign`

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

Adds one assign.

# `default_sanitize_options`

```elixir
@spec default_sanitize_options() :: keyword()
```

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

# `get_option`

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

Returns an option value.

# `get_private`

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

Reads private data.

# `halt`

```elixir
@spec halt(t()) :: t()
```

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

# `halt`

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

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

# `prepend_steps`

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

Prepends named steps to the pipeline.

# `put_extensions`

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

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

# `put_node_in_document_root`

```elixir
@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`

```elixir
@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`

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

Merges `:parse` options.

# `put_plugins`

```elixir
@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`

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

Stores private (plugin-internal) data.

# `put_render_options`

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

Merges `:render` options.

# `put_sanitize_options`

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

Merges `:sanitize` options; `nil` disables sanitizing.

# `put_source`

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

Sets Carve source to be parsed by `run/1`.

# `put_syntax_highlight_options`

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

Merges `:syntax_highlight` options; `nil` disables highlighting.

# `register_options`

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

Registers user option keys so `put_options/2` accepts them.

# `run`

```elixir
@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`

```elixir
@spec update_nodes(t(), selector(), (struct() -&gt; struct())) :: t()
```

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

# `update_private`

```elixir
@spec update_private(t(), atom(), term(), (term() -&gt; term())) :: t()
```

Updates private data with `fun`, starting from `default`.

# `wrap`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
