# `ExRatatui.CodeBlock`
[🔗](https://github.com/mcass19/ex_ratatui/blob/v0.10.0/lib/ex_ratatui/code_block.ex#L1)

Helpers for syntax-highlighted code, complementing the
`ExRatatui.Widgets.CodeBlock` widget.

`highlight/3` is the seam for users composing their own widgets — a
DiffViewer building side-by-side panels of highlighted source, an
Inspector pretty-printing structs — without dropping a full `CodeBlock`
into the tree.

## Supported languages

Powered by syntect's bundled Sublime-syntax set, plus **Elixir** which
we ship in addition to the defaults (see
`native/ex_ratatui/syntaxes/`). Languages with built-in support:
Bash, C, C++, C#, CSS, D, Diff, **Elixir**, Erlang, Go, Groovy,
Haskell, HTML, Java, JavaScript, JSON, Lisp, Lua, Make, Markdown,
MATLAB, OCaml, Objective-C, Pascal, Perl, PHP, Python, R, Regexp, Ruby,
Rust, Scala, Shell-Script, SQL, TCL, XML, YAML. Unknown languages fall
back to plain text (still themed, but uncoloured).

Lookup is case-insensitive and accepts file extensions, so `"elixir"`,
`:Elixir`, `"ex"`, and `"exs"` all resolve to the same syntax.

## Themes

Curated atoms resolve to syntect's bundled `ThemeSet`:

  * `:base16_ocean_dark` (default for `ExRatatui.Widgets.CodeBlock`)
  * `:base16_ocean_light`
  * `:base16_eighties_dark`
  * `:base16_mocha_dark`
  * `:inspired_github`
  * `:solarized_dark`
  * `:solarized_light`

Raw strings pass through unchanged.

## Examples

    iex> [%ExRatatui.Text.Line{} | _] =
    ...>   ExRatatui.CodeBlock.highlight("fn main() {}", "rust", :base16_ocean_dark)

# `native_span`

```elixir
@type native_span() :: %{
  content: String.t(),
  fg: nil | {0..255, 0..255, 0..255},
  bg: nil | {0..255, 0..255, 0..255},
  bold: boolean(),
  italic: boolean(),
  underlined: boolean()
}
```

Raw span shape returned by the underlying highlighter NIF.

`fg`/`bg` are `nil` for the theme's default (when syntect's effective
alpha is `0`), or a `{r, g, b}` tuple otherwise.

# `from_native`

```elixir
@spec from_native([[native_span()]]) :: [ExRatatui.Text.Line.t()]
```

Converts the raw NIF response into `%ExRatatui.Text.Line{}` structs.

Useful for callers reaching for the underlying highlighter directly
to skip per-call theme atom resolution (e.g. in a hot loop reusing the
same theme), or for tooling that consumes the wire shape. Most callers
should use `highlight/3` instead — it resolves the theme and emits the
`[:ex_ratatui, :code_block, :highlight]` telemetry span.

## Examples

    iex> raw = [[%{content: "x", fg: {10, 20, 30}, bg: nil,
    ...>           bold: true, italic: false, underlined: false}]]
    iex> [%ExRatatui.Text.Line{spans: [span]}] = ExRatatui.CodeBlock.from_native(raw)
    iex> {span.content, span.style.fg, span.style.modifiers}
    {"x", {:rgb, 10, 20, 30}, [:bold]}

# `highlight`

```elixir
@spec highlight(
  String.t(),
  String.t() | atom() | nil,
  ExRatatui.Widgets.CodeBlock.theme()
) :: [
  ExRatatui.Text.Line.t()
]
```

Highlight `code` for `language` using `theme`.

Returns a list of `%ExRatatui.Text.Line{}` with per-token styled spans.
Unknown languages fall back to a single plain span per line; unknown
themes fall back to `:base16_ocean_dark`.

## Examples

    iex> [%ExRatatui.Text.Line{spans: spans} | _] =
    ...>   ExRatatui.CodeBlock.highlight("hello", nil, :base16_ocean_dark)
    iex> Enum.map(spans, & &1.content) |> Enum.join() |> String.trim()
    "hello"

# `resolve_theme`

```elixir
@spec resolve_theme(ExRatatui.Widgets.CodeBlock.theme()) :: String.t()
```

Resolves a `CodeBlock` theme into the raw syntect theme name.

Accepts a curated atom (one of seven) or a raw string. Raises
`ArgumentError` for unknown atoms with a message listing valid choices.
Raw strings pass through unchanged so callers can load custom theme
sets without modifying this module.

---

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