Alaja.Syntax (Alaja v2.0.0)

Copy Markdown View Source

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]}}
})

Summary

Types

language()
token()

Functions

detect_language(path)

Detects language atom from file path extension.

get_language(name)

Retrieves a registered language definition.

highlight_ansi(content, language)

Highlights source code and returns ANSI escape sequences.

highlight_buffer(content, language, opts \\ [])

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

highlight_content(content, language)

Highlights source code for a given language.

highlight_file(path)

Highlights a file by detecting language from extension.

list_languages()

Lists all registered language names.

register_language(name, lang)

Registers a language definition under an atom key.

tokenize(content, language)

Tokenizes source code into {type, text} tuples.

Types

language()

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

token()

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

Functions

detect_language(path)

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

Detects language atom from file path extension.

get_language(name)

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

Retrieves a registered language definition.

highlight_ansi(content, language)

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

Highlights source code and returns ANSI escape sequences.

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

highlight_buffer(content, language, opts \\ [])

@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(content, language)

@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(path)

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

Highlights a file by detecting language from extension.

list_languages()

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

Lists all registered language names.

register_language(name, lang)

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

Registers a language definition under an atom key.

tokenize(content, language)

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

Tokenizes source code into {type, text} tuples.