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

Public facade for the Alaja terminal rendering framework.

Provides a simplified API for the most common operations: printing
styled messages (`print_success`, `print_error`, `print_warning`,
`print_info`), creating buffers and cells, converting colour formats,
and rendering tables.

For advanced usage see the sub-modules directly:
`Alaja.Printer`, `Alaja.Components`, and `Alaja.Buffer`.

# `empty`

```elixir
@spec empty() :: Alaja.Cell.t()
```

Creates an empty cell (space, no colour, no effects).

Returns a `%Cell{}` struct filled with defaults.

# `new_buffer`

```elixir
@spec new_buffer(non_neg_integer(), non_neg_integer()) :: Alaja.Buffer.t()
```

Creates a new buffer with the given dimensions.

Returns a `%Buffer{}` with `width * height` empty cells stored in a
flat tuple for O(1) access.

# `print`

```elixir
@spec print(keyword() | list()) :: :ok
```

Prints a table to stdout.

Delegates to `Alaja.Components.Table.print/2`. Accepts a keyword list
or a list of lists where the first row is treated as headers.

# `print_error`

```elixir
@spec print_error(String.t()) :: :ok
```

Prints an error message (icon: ✗).

# `print_info`

```elixir
@spec print_info(String.t()) :: :ok
```

Prints an informational message (icon: ℹ).

# `print_raw`

```elixir
@spec print_raw(iodata()) :: :ok
```

Writes an `iodata` payload to stdout **without any transformation**.

Use this when you need to emit raw ANSI escapes (or any pre-formatted
text) that should pass through untouched by Alaja's printers.

## Example

    Alaja.print_raw("\e[31mError\e[0m\n")

# `print_raw`

```elixir
@spec print_raw(
  iodata(),
  keyword()
) :: :ok
```

Writes an `iodata` payload to a specific device (default `:stdio`).

## Options

  * `:device` — `:stdio | {:fd, posix} | pid()`. Defaults to `:stdio`.

Useful for writing to alternative file descriptors or to a process
socket in interactive components.

# `print_success`

```elixir
@spec print_success(String.t()) :: :ok
```

Prints a success message (icon: ✓).

# `print_warning`

```elixir
@spec print_warning(String.t()) :: :ok
```

Prints a warning message (icon: ⚠).

# `rgb_to_hex`

```elixir
@spec rgb_to_hex({byte(), byte(), byte()}) :: String.t()
```

Converts an RGB tuple to uppercase hex string.

## Examples

    iex> Alaja.rgb_to_hex({255, 180, 0})
    "#FFB400"

# `run`

```elixir
@spec run([String.t()], module()) :: any()
```

Unified entry point for running an Alaja-based CLI.

The default `cli_module` is `Alaja.CLI` (the self-hosted demo CLI shipped
with the framework). Pass any module built with
`use Alaja.CLI.Definition, otp_app: :my_app, halt_on_error: true` to run your own (escript-style aborts the BEAM on error). Set `halt_on_error: false` if you want main/1 to return `{:error, reason}` instead.

Both escript entry points and library callers should go through this
function rather than calling `cli_module.main/1` directly so the
public facade has a single documented entry point.

## Examples

    # Library caller
    Alaja.run(System.argv())

    # Custom CLI
    Alaja.run(System.argv(), MyApp.CLI)

    # escript main_module
    defmodule MyApp.CLIEntry do
      def main(argv), do: Alaja.run(argv, MyApp.CLI)
    end

---

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