Pote.Orchestrator (Pote v1.0.0)

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"

Summary

Types

cmyk()

color_input()

color_output()

hex()

hsl()

hsv()

rgb()

xterm256()

Functions

named_colors()

Returns the list of supported named colors.

parse_color(input)

Parses a color from various input formats.

to_ansi(input)

Converts a color to its ANSI escape code for foreground.

to_ansi_bg(input)

Converts a color to its ANSI escape code for background.

to_color_info(color)

Converts a color value to a Pote.ColorInfo struct.

to_rgb(input)

Converts any color format to RGB tuple.

to_rgb!(input)

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

to_xterm256(input)

Converts a color to XTerm256 index.

Types

cmyk()

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

color_input()

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

color_output()

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

hex()

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

hsl()

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

hsv()

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

rgb()

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

xterm256()

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

Functions

named_colors()

@spec named_colors() :: keyword()

Returns the list of supported named colors.

Examples

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

parse_color(input)

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

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

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

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

@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!(input)

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

@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}