Pote.Format behaviour (Pote v2.2.0)

Copy Markdown View Source

Behaviour for color format handlers.

This module defines the contract for all color format modules. It provides default implementations for common conversions based on to_rgb/1.

Each color format module (ANSI, Hex, RGB, ARGB, HSL, HSV, CMYK, XTerm256, Atom) implements this behaviour to provide a consistent interface for color parsing, validation, and conversion to all supported color spaces.

See Pote.Format.RGB, Pote.Format.Hex, Pote.Format.HSL, etc. for the built-in implementations.

Usage with use

defmodule MyFormat do
  use Pote.Format

  @impl true
  def parse(input), do: # ...
end

The use Pote.Format macro provides default implementations for to_hex/1, to_argb/1, to_hsl/1, to_hsv/1, to_cmyk/1, to_xterm256/1, valid?/1, name/1, and info/1.

Summary

Types

t()

Callbacks

from_rgb(rgb)

Creates the format from RGB.

info(t)

Returns a map with all the information about the color.

name(t)

Returns the color name. Defaults to returning nil.

parse(any)

Parses a string or value into the specific format.

to_argb(t)

Converts the format to ARGB {a, r, g, b}. Defaults to returning {255, r, g, b}.

to_cmyk(t)

Converts the format to CMYK. Defaults to using to_rgb/1 and then Pote.Converters.RGB.to_cmyk/1.

to_hex(t)

Converts the format to hexadecimal. Defaults to using to_rgb/1 and then Pote.Converters.RGB.to_hex/1.

to_hsl(t)

Converts the format to HSL. Defaults to using to_rgb/1 and then Pote.Converters.RGB.to_hsl/1.

to_hsv(t)

Converts the format to HSV. Defaults to using to_rgb/1 and then Pote.Converters.RGB.to_hsv/1.

to_rgb(t)

Converts the format to RGB.

to_xterm256(t)

Converts the format to XTerm256. Defaults to using to_rgb/1 and then Pote.Converters.RGB.to_xterm256/1.

valid?(any)

Validates whether the value is valid for this format. Defaults to returning true if parse/1 succeeds.

Functions

valid_via_parse(module, input)

Helper to implement valid?/1 based on parse/1.

Types

t()

@type t() :: any()

Callbacks

from_rgb(rgb)

@callback from_rgb(Pote.rgb()) :: t()

Creates the format from RGB.

info(t)

@callback info(t()) :: map()

Returns a map with all the information about the color.

name(t)

@callback name(t()) :: String.t() | nil

Returns the color name. Defaults to returning nil.

parse(any)

@callback parse(any()) :: {:ok, any()} | {:error, String.t()}

Parses a string or value into the specific format.

to_argb(t)

@callback to_argb(t()) :: {0..255, 0..255, 0..255, 0..255}

Converts the format to ARGB {a, r, g, b}. Defaults to returning {255, r, g, b}.

to_cmyk(t)

@callback to_cmyk(t()) :: Pote.cmyk()

Converts the format to CMYK. Defaults to using to_rgb/1 and then Pote.Converters.RGB.to_cmyk/1.

to_hex(t)

@callback to_hex(t()) :: String.t()

Converts the format to hexadecimal. Defaults to using to_rgb/1 and then Pote.Converters.RGB.to_hex/1.

to_hsl(t)

@callback to_hsl(t()) :: Pote.hsl()

Converts the format to HSL. Defaults to using to_rgb/1 and then Pote.Converters.RGB.to_hsl/1.

to_hsv(t)

@callback to_hsv(t()) :: Pote.hsv()

Converts the format to HSV. Defaults to using to_rgb/1 and then Pote.Converters.RGB.to_hsv/1.

to_rgb(t)

@callback to_rgb(t()) :: Pote.rgb()

Converts the format to RGB.

to_xterm256(t)

@callback to_xterm256(t()) :: Pote.xterm256()

Converts the format to XTerm256. Defaults to using to_rgb/1 and then Pote.Converters.RGB.to_xterm256/1.

valid?(any)

@callback valid?(any()) :: boolean()

Validates whether the value is valid for this format. Defaults to returning true if parse/1 succeeds.

Functions

valid_via_parse(module, input)

Helper to implement valid?/1 based on parse/1.