# `Pote.Orchestrator`
[🔗](https://github.com/Lorenzo-SF/pote/blob/2.2.0/lib/pote/orchestrator.ex#L1)

Color orchestration module for parsing, converting, and formatting colors.

This module provides a unified interface for working with various color
formats, converting between them, and generating ANSI escape codes.

## Supported Color Formats

* RGB tuples: `{r, g, b}` where each value is 0-255
* Hex strings: `"#RRGGBB"` or `"RRGGBB"`
* HSL tuples: `{h, s, l}` where h is 0-360°, s and l are 0-100%
* HSV tuples: `{h, s, v}` where h is 0-360°, s and v are 0-100%
* CMYK tuples: `{c, m, y, k}` where each value is 0-100%
* XTerm256: Integer 0-255
* Atom colors: `:red`, `:green`, `:blue`, etc.
* Named colors: `"red"`, `"green"`, `"blue"`, etc.

Type aliases defined here reference the canonical types in `Pote`.

## Usage

    iex> Pote.Orchestrator.parse_color("#FF8000")
    {:ok, {255, 128, 0}}

    iex> Pote.Orchestrator.to_ansi({255, 128, 0})
    "\e[38;2;255;128;0m"

# `cmyk`

```elixir
@type cmyk() :: Pote.cmyk()
```

# `color_input`

```elixir
@type color_input() :: Pote.color_input()
```

# `color_output`

```elixir
@type color_output() :: Pote.color_output()
```

# `hex`

```elixir
@type hex() :: Pote.hex()
```

# `hsl`

```elixir
@type hsl() :: Pote.hsl()
```

# `hsv`

```elixir
@type hsv() :: Pote.hsv()
```

# `rgb`

```elixir
@type rgb() :: Pote.rgb()
```

# `xterm256`

```elixir
@type xterm256() :: Pote.xterm256()
```

# `named_colors`

```elixir
@spec named_colors() :: keyword()
```

Returns the list of supported named colors.

## Examples

    iex> Orchestrator.named_colors() |> Keyword.keys()
    [:black, :blue, :bright_black, ...]

# `parse_color`

```elixir
@spec parse_color(color_input()) :: {:ok, rgb()} | {:error, String.t()}
```

Parses a color from various input formats.

## Parameters

- `input` - Color in any supported format

## Returns

- `{:ok, rgb}` - RGB tuple on success
- `{:error, message}` - Error string with explanation

## Examples

    iex> Orchestrator.parse_color("#FF8000")
    {:ok, {255, 128, 0}}

    iex> Orchestrator.parse_color({30.0, 100.0, 50.0})
    {:ok, {255, 128, 0}}

    iex> Orchestrator.parse_color(:red)
    {:ok, {255, 0, 0}}

    iex> Orchestrator.parse_color("invalid")
    {:error, "Unknown color format. ..."}

# `to_ansi`

```elixir
@spec to_ansi(color_input() | nil) :: String.t()
```

Converts a color to its ANSI escape code for foreground.

## Parameters

- `input` - Color in any supported format

## Returns

- ANSI escape code string

## Examples

    iex> Orchestrator.to_ansi({255, 128, 0})
    "\e[38;2;255;128;0m"

    iex> Orchestrator.to_ansi("#FF8000")
    "\e[38;2;255;128;0m"

    iex> Orchestrator.to_ansi(nil)
    ""

# `to_ansi_bg`

```elixir
@spec to_ansi_bg(color_input() | nil) :: String.t()
```

Converts a color to its ANSI escape code for background.

## Parameters

- `input` - Color in any supported format

## Returns

- ANSI escape code string for background color

## Examples

    iex> Orchestrator.to_ansi_bg({255, 128, 0})
    "\e[48;2;255;128;0m"

# `to_color_info`

```elixir
@spec to_color_info(atom() | String.t() | tuple()) :: Pote.ColorInfo.t()
```

Converts a color value to a `Pote.ColorInfo` struct.

## Parameters

- `color` — Any supported color input: atom name, hex string, RGB tuple, etc.

## Returns

- A `Pote.ColorInfo` struct populated with the color in all available formats.
  Returns an empty `ColorInfo` if the input cannot be parsed.

## Examples

    iex> Orchestrator.to_color_info(:red).rgb
    {255, 0, 0}

    iex> Orchestrator.to_color_info("#FF8000").hex
    "#FF8000"

# `to_rgb`

```elixir
@spec to_rgb(color_input()) :: {:ok, rgb()} | {:error, String.t()}
```

Converts any color format to RGB tuple.

## Parameters

- `input` - Color in any supported format

## Returns

- `{:ok, rgb}` - RGB tuple on success
- `{:error, reason}` - Error tuple if conversion fails

## Examples

    iex> Orchestrator.to_rgb("#FF8000")
    {:ok, {255, 128, 0}}

    iex> Orchestrator.to_rgb(:red)
    {:ok, {255, 0, 0}}

    iex> Orchestrator.to_rgb({30.0, 100.0, 50.0})
    {:ok, {255, 128, 0}}

# `to_rgb!`

```elixir
@spec to_rgb!(color_input()) :: rgb()
```

Converts any color format to RGB tuple (raises on error).

## Parameters

- `input` - Color in any supported format

## Returns

- RGB tuple

## Examples

    iex> Orchestrator.to_rgb!("#FF8000")
    {255, 128, 0}

    iex> Orchestrator.to_rgb!(:red)
    {255, 0, 0}

# `to_xterm256`

```elixir
@spec to_xterm256(color_input()) :: {:ok, xterm256()} | {:error, String.t()}
```

Converts a color to XTerm256 index.

## Parameters

- `input` - Color in any supported format

## Returns

- `{:ok, xterm256}` - XTerm256 index on success
- `{:error, reason}` - Error tuple if conversion fails

## Examples

    iex> Orchestrator.to_xterm256({255, 128, 0})
    {:ok, 208}

    iex> Orchestrator.to_xterm256("#FF8000")
    {:ok, 208}

---

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