# `Alaja.Syntax`
[🔗](https://github.com/Lorenzo-SF/alaja/blob/2.1.0/lib/alaja/syntax.ex#L1)

Syntax highlighting for terminal output.

Two-tier system:
- **Built-in languages** (`:elixir`, `:json`, `:markdown`, `:text`)
  use inline tokenizers for Alaja's own CLI.
- **Registered languages** (Python, TypeScript, Rust, etc.) use
  `Alaja.Syntax.Engine` driven by `Alaja.Syntax.Language` definitions,
  typically registered by host applications (e.g. Delfos).

## Usage

    # Built-in
    Alaja.Syntax.highlight_content(code, :elixir)

    # Registered by host app
    Alaja.Syntax.highlight_content(code, :python)

## Registering a language

    alias Alaja.Syntax.Language

    Alaja.Syntax.register_language(:python, %Language{
      name: "Python",
      line_comment: "#",
      keywords: MapSet.new(~w(def class if elif else for while return)),
      colors: %{keyword: {:blue, [:bold]}}
    })

# `language`

```elixir
@type language() ::
  :elixir
  | :json
  | :markdown
  | :text
  | :python
  | :typescript
  | :rust
  | :go
  | :java
  | :ruby
```

# `token`

```elixir
@type token() :: {atom(), String.t()}
```

# `detect_language`

```elixir
@spec detect_language(String.t()) :: atom()
```

Detects language atom from file path extension.

# `get_language`

```elixir
@spec get_language(atom()) :: {:ok, Alaja.Syntax.Language.t()} | :error
```

Retrieves a registered language definition.

# `highlight_ansi`

```elixir
@spec highlight_ansi(String.t(), language()) :: iodata()
```

Highlights source code and returns ANSI escape sequences.

Same API as `highlight_content/2` but produces terminal-ready output.

# `highlight_buffer`

```elixir
@spec highlight_buffer(String.t(), language(), keyword()) :: Alaja.Buffer.t()
```

Highlights source code and returns an `Alaja.Buffer.t/0`.

This is the Buffer-first canonical render. Each token becomes one
cell per visible character with the resolved fg colour from the
language/theme chain. Effects (`:bold`, `:italic`, ...) are stored
on the cell but currently not visually distinct in the buffer — use
`highlight_ansi/2` for full effect rendering.

## Options

  - `:theme` — overrides the global syntax theme (default: `Theme.default()`)
  - `:max_width` — wraps long lines; pass `false` to disable wrapping

## Examples

    buf = Alaja.Syntax.highlight_buffer("defmodule Foo do end", :elixir)
    Alaja.Printer.print_raw(buf)

# `highlight_content`

```elixir
@spec highlight_content(String.t(), language()) :: [{String.t(), String.t()}]
```

Highlights source code for a given language.

Returns `[{color_string, text}]` tuples. For ANSI-rendered output
use `highlight_ansi/2`.

# `highlight_file`

```elixir
@spec highlight_file(String.t()) :: {:ok, list()} | {:error, String.t()}
```

Highlights a file by detecting language from extension.

# `list_languages`

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

Lists all registered language names.

# `register_language`

```elixir
@spec register_language(atom(), Alaja.Syntax.Language.t()) :: :ok
```

Registers a language definition under an atom key.

# `tokenize`

```elixir
@spec tokenize(String.t(), language()) :: [token()]
```

Tokenizes source code into `{type, text}` tuples.

---

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