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

[Carve](https://markup-carve.github.io/carve/) parsing and rendering, backed by
the Rust [carve-rs](https://github.com/markup-carve/carve-rs) engine.

The API follows [MDEx](https://github.com/leandrocp/mdex):

  * `to_html/2` renders source or a `Carvex.Document`; `to_markdown/2`,
    `to_plain_text/2`, `to_ansi/2` and `to_carve/2` render other outputs
  * `parse_document/2` returns a `Carvex.Document` tree you can query and edit
  * plugins and pipeline steps (`Carvex.Document`)
  * carve-rs extensions, profiles and safe mode (`new/1` options)
  * syntax highlighting with syntect or Lumis, with code block decorators
  * HTML sanitization (ammonia)
  * HEEx components and expressions (`to_heex/2`, `~CRV"..."HEEX`)
  * streaming of chunked input (`stream/2`)
  * linting (`lint/2`)

## Examples

    iex> Carvex.to_html("Hello *world*!")
    {:ok, "<p>Hello <strong>world</strong>!</p>"}

    iex> Carvex.to_html!("# Hi", render: [sections: false])
    "<h1 id=\"Hi\">Hi</h1>"

## Code block decorators

Block attributes on a code block control highlighting and are never rendered:

    {theme=github_dark pre_class="a b" highlight_lines="1,3-5" highlight_lines_style="background: #ff0" highlight_lines_class=hl include_highlights=true}
    ```elixir
    IO.puts("hi")
    ```

Without `syntax_highlight:`, `pre_class` becomes a class on the code block and
the other decorators are ignored.

## `use Carvex`

`use Carvex` requires `Carvex`, imports `Carvex.Sigil`, and stores its options in
`@carvex_options`, which `~CRV` uses at compile time.

# `source`

```elixir
@type source() :: String.t() | Carvex.Document.t()
```

Carve source or a document.

# `extensions`

```elixir
@spec extensions() :: [atom()]
```

The carve-rs extension names accepted by the `:extensions` option.

    iex> :table_of_contents in Carvex.extensions()
    true

# `lint`

```elixir
@spec lint(String.t(), keyword()) :: [Carvex.LintWarning.t()]
```

Lints Carve source, returning carve-rs's diagnostics in source order.

Offsets in each `Carvex.LintWarning` are UTF-8 byte offsets into `source`.

    iex> [warning] = Carvex.lint("{#orphan}\n")
    iex> warning.rule
    "unattached-block-attribute"

## Options

* `:extensions` (list of `t:term/0`) - As in `new/1`. The default value is `[]`.

* `:parse` (`t:keyword/0`) - As in `new/1`. The default value is `[]`.

* `:caption_hints` (`t:boolean/0`) - Also flag paragraphs that look like a caption missing its `^` marker. The default value is `false`.

# `new`

```elixir
@spec new(keyword()) :: Carvex.Document.t()
```

Builds a document from options. `:source` is parsed when the pipeline runs.

## Options

* `:extensions` (list of `t:term/0`) - carve-rs built-in extensions, in render order: a name or `{name, options}`,
  e.g. `[:table_of_contents, heading_permalinks: [symbol: "§"]]`. Names are
  `Carvex.extensions/0`. Options (omitted keys keep the engine default):
  `autolink` (`allowed_schemes`), `code_group` (`wrapper_class`, `panel_class`,
  `label_class`, `radio_class`, `id_prefix`), `external_links` (`target`, `rel`,
  `nofollow`), `heading_level_shift` (`shift`), `heading_permalinks` (`symbol`,
  `css_class`, `aria_label`, `levels`, `prepend`, `show_on_hover`,
  `copy_to_clipboard`, `lowercase_ids`), `heading_reference` (`css_class`),
  `math_block` (`language`), `wikilinks` (`css_class`, `new_window`),
  `heading_numbers` (`min_level`, `label`, `crossref`: `:number | :number_title | :title`),
  `table_of_contents` (`min_level`, `max_level`, `list_type`: `:ul | :ol`,
  `css_class`, `position`: `:top | :bottom`, `lowercase_ids`), `tabs` (`mode`:
  `:css | :aria`, `wrapper_class`, `tab_class`, `label_class`, `radio_class`,
  `id_prefix`), `fenced_render` (`languages`, `css_class`, `tag`, `content_mode`:
  `:text | :json`, `wrap_in_figure`, `figure_class`), `img_fence` (`allow_style`,
  `allow_links`, `allow_animation`, `allow_external_images`). Putting the option
  again merges by name: a repeated name replaces its entry in place. The default value is `[]`.

* `:parse` (`t:keyword/0`) - carve-rs parser options. The default value is `[ascii_heading_ids: :off, lowercase_heading_ids: false, positions: false]`.

  * `:positions` (`t:boolean/0`) - Record `pos` (codepoint spans) on every node. The default value is `false`.

  * `:lowercase_heading_ids` (`t:boolean/0`) - Lowercase generated heading ids. The default value is `false`.

  * `:ascii_heading_ids` - Transliterate generated heading ids to ASCII. The default value is `:off`.

* `:render` (`t:keyword/0`) - carve-rs renderer options. The default value is `[align_tables: false, smart_typography: :glyph, symbols: %{}, tag_url: nil, mention_url: nil, profile_base_host: nil, profile: nil, safe: false, mode: :interactive, source_lines: false, sections: true]`.

  * `:sections` (`t:boolean/0`) - Wrap top-level headings and their content in `<section>`. The default value is `true`.

  * `:source_lines` (`t:boolean/0`) - Add `data-source-line` to top-level blocks. The default value is `false`.

  * `:mode` - HTML render mode; `:static` flattens interactive constructs. The default value is `:interactive`.

  * `:safe` (`t:boolean/0`) - Escape raw HTML (`` `x`{=html} ``, ```` ```=html ````) instead of emitting it. `Carvex.Raw` nodes are unaffected. The default value is `false`.

  * `:profile` - carve-rs feature-restriction profile for untrusted input. The default value is `nil`.

  * `:profile_base_host` - Host the profile's link policy treats as internal. The default value is `nil`.

  * `:mention_url` - URL template for `@user` mentions, e.g. `"https://example.com/{}"`. The default value is `nil`.

  * `:tag_url` - URL template for `#tag`s. The default value is `nil`.

  * `:symbols` (map of `t:String.t/0` keys and `t:String.t/0` values) - `:name:` replacements, emitted as TRUSTED raw HTML. Never build from user input. The default value is `%{}`.

  * `:smart_typography` - Markdown output only: emit glyphs or the author's source runs. The default value is `:glyph`.

  * `:align_tables` (`t:boolean/0`) - `to_carve/2` only: align table columns. The default value is `false`.

* `:syntax_highlight` - Code block highlighting, e.g. `[engine: :syntect]` or `[engine: :lumis]`. `nil` disables it. The default value is `nil`.

* `:sanitize` - ammonia sanitization of the rendered HTML. `nil` disables it. The default value is `nil`.

* `:plugins` (list of `t:term/0`) - Plugins to attach. The default value is `[]`.

* `:assigns` - Assigns for `Carvex.to_heex/2`. The default value is `%{}`.

# `parse_document`

```elixir
@spec parse_document(String.t(), keyword()) ::
  {:ok, Carvex.Document.t()} | {:error, Exception.t()}
```

Parses source into a `Carvex.Document` and runs the pipeline.

    iex> {:ok, doc} = Carvex.parse_document("Hello *world*")
    iex> doc.nodes
    [%Carvex.Paragraph{nodes: [%Carvex.Text{value: "Hello "}, %Carvex.Strong{nodes: [%Carvex.Text{value: "world"}]}]}]

# `parse_document!`

```elixir
@spec parse_document!(String.t(), keyword()) :: Carvex.Document.t()
```

Like `parse_document/2` but raises on error.

# `safe_html`

```elixir
@spec safe_html(String.t(), keyword()) :: String.t()
```

Sanitizes and/or escapes an HTML string. Plugins use this to build safe
`Carvex.Raw` nodes.

## Options

  * `:sanitize` - ammonia options merged over `Carvex.Document.default_sanitize_options/0`,
    or `nil` to skip sanitizing. Defaults to the default sanitize options.
  * `:escape` - HTML-escape `& < > " '` after sanitizing. Defaults to `false`.
  * `:heex` - replace `{` and `}` with `&lbrace;` / `&rbrace;` last, so the
    HTML is not read as HEEx expressions by `to_heex/2`. Pass
    `Carvex.Document.get_private(doc, :heex, false)` from a step. Defaults to `false`.

## Examples

    iex> Carvex.safe_html("<script>x</script><b onclick=\"y\">hi</b>")
    "<b>hi</b>"

    iex> Carvex.safe_html("<a>&</a>", sanitize: nil, escape: true)
    "&lt;a&gt;&amp;&lt;/a&gt;"

    iex> Carvex.safe_html("<pre>A{b}</pre>", sanitize: nil, heex: true)
    "<pre>A&lbrace;b&rbrace;</pre>"

# `stream`

```elixir
@spec stream(Enumerable.t(), keyword()) :: Enumerable.t()
```

Streams chunks of Carve source, emitting `{id, %Carvex.Document{}}` for each
top-level block that is new or changed. A later emission with the same id
replaces the earlier one; an empty document means the block was removed.

Each block renders standalone: a footnote reference resolves only if its
definition is in the same block. `opts` are as in `new/1` (plugins attach
once); `:source` is not accepted.

    iex> ["# Hel", "lo\n\nPara"]
    ...> |> Carvex.stream()
    ...> |> Enum.map(fn {id, doc} -> {id, Carvex.to_html!(doc, render: [sections: false])} end)
    [{0, "<h1 id=\"Hel\">Hel</h1>"}, {0, "<h1 id=\"Hello\">Hello</h1>"}, {1, "<p>Para</p>"}]

# `to_ansi`

```elixir
@spec to_ansi(source(), keyword()) :: {:ok, String.t()} | {:error, Exception.t()}
```

Renders source or a document to ANSI-styled terminal text.

# `to_ansi!`

```elixir
@spec to_ansi!(source(), keyword()) :: String.t()
```

Like `to_ansi/2` but raises on error.

# `to_carve`

```elixir
@spec to_carve(source(), keyword()) :: {:ok, String.t()} | {:error, Exception.t()}
```

Writes canonical Carve source: carve-rs's formatter for source, and on a
document the (possibly edited) tree written back to Carve.

    iex> Carvex.to_carve("#  Title")
    {:ok, "# Title\n"}

# `to_carve!`

```elixir
@spec to_carve!(source(), keyword()) :: String.t()
```

Like `to_carve/2` but raises on error.

# `to_heex`
*macro* 

Renders Carve with HEEx components and expressions into a `Phoenix.LiveView.Rendered`.

Requires `{:phoenix_live_view, "~> 1.2"}`. HEEx tags (`<.link>`, `<Mod.fun>`,
`<:slot>`), `{@expr}` expressions and `<%= %>` blocks are recognized outside
code; Carve brace syntax like `{.class}`, `[Tab]{kbd}`, `{^sup^}` or a block
attribute line (`{loose}`) is left alone, so write `{@name}` rather than a bare
`{name}` alone on a line. Explicit `` `...`{=heex} `` and ```` ```=heex ```` raw
blocks also work.

Braces in the rendered HTML (text, code, attributes, raw `html`) become
`&lbrace;`/`&rbrace;`, except inside `<script>` and `<style>`.

Assigns come from the `:assigns` option. The template is compiled at runtime
with the caller's environment, so imports (e.g. `Phoenix.Component`) apply.
`sanitize:` is not supported.

# `to_heex!`
*macro* 

Like `to_heex/2` but raises on error.

# `to_html`

```elixir
@spec to_html(source(), keyword()) :: {:ok, String.t()} | {:error, Exception.t()}
```

Renders source or a document to HTML. `opts` are merged into the document
options (see `new/1`).

    iex> Carvex.to_html("/hi/")
    {:ok, "<p><em>hi</em></p>"}

# `to_html!`

```elixir
@spec to_html!(source(), keyword()) :: String.t()
```

Like `to_html/2` but raises on error.

# `to_markdown`

```elixir
@spec to_markdown(source(), keyword()) :: {:ok, String.t()} | {:error, Exception.t()}
```

Renders source or a document to Markdown.

    iex> Carvex.to_markdown("/hi/ *there*")
    {:ok, "*hi* **there**\n"}

# `to_markdown!`

```elixir
@spec to_markdown!(source(), keyword()) :: String.t()
```

Like `to_markdown/2` but raises on error.

# `to_plain_text`

```elixir
@spec to_plain_text(source(), keyword()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

Renders source or a document to plain text.

    iex> Carvex.to_plain_text("/hi/ *there*")
    {:ok, "hi there\n"}

# `to_plain_text!`

```elixir
@spec to_plain_text!(source(), keyword()) :: String.t()
```

Like `to_plain_text/2` but raises on error.

# `traverse_and_update`

Traverses and updates the tree post-order; returning `nil` or `:pop` removes a node.

# `traverse_and_update`

Like `traverse_and_update/2` with an accumulator; the function returns `{node, acc}`.

---

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