TermUI.SGR (TermUI v1.0.0)

View Source

SGR (Select Graphic Rendition) sequence generation for terminal styling.

This module provides centralized generation of SGR parameters and sequences for terminal text styling, including colors and text attributes.

Overview

SGR sequences control text appearance (colors, bold, italic, etc.) in terminals. They follow the format ESC[<params>m where params are semicolon-separated numbers.

Two Modes of Operation

  1. Parameter mode - Returns parameter strings for combining into sequences

  2. Sequence mode - Returns complete escape sequences

Color Types

  • Named colors: :red, :green, :blue, :cyan, :magenta, :yellow, :black, :white
  • Bright variants: :bright_red, :bright_green, etc.
  • 256-color palette: Integer 0-255
  • True color RGB: {r, g, b} tuple
  • Default: :default to reset to terminal default

Attributes

Supported: :bold, :dim, :italic, :underline, :blink, :reverse, :hidden, :strikethrough

Examples

# Parameter mode for combining
iex> SGR.color_param(:fg, :red)
"31"

iex> SGR.color_param(:fg, {255, 128, 0})
"38;2;255;128;0"

iex> SGR.attr_param(:bold)
"1"

# Building combined sequence
iex> params = [SGR.attr_param(:bold), SGR.color_param(:fg, :red)]
iex> SGR.build_sequence(params)
["\e[", ["1", ";", "31"], "m"]

# Sequence mode for direct output
iex> SGR.color_sequence(:fg, :red) |> IO.iodata_to_binary()
"\e[31m"

iex> SGR.attr_sequence(:bold) |> IO.iodata_to_binary()
"\e[1m"

Summary

Functions

attr_off_param(arg1)

Returns SGR parameter string to turn off an attribute.

attr_param(arg1)

Returns SGR parameter string for an attribute.

attr_sequence(attr)

Returns complete SGR escape sequence for an attribute.

build_sequence(params)

Builds a combined SGR sequence from a list of parameters.

color_param(arg1, n)

Returns SGR parameter string for a color.

color_sequence(type, color)

Returns complete SGR escape sequence for a color.

named_colors()

Returns all supported named colors.

reset()

Returns SGR reset sequence.

supported_attrs()

Returns all supported attributes.

valid_attr?(attr)

Checks if an attribute is valid.

valid_color?(color)

Checks if a color value is valid.

Functions

attr_off_param(arg1)

@spec attr_off_param(atom()) :: String.t() | nil

Returns SGR parameter string to turn off an attribute.

Used when removing specific attributes without full reset.

Examples

iex> SGR.attr_off_param(:bold)
"22"

iex> SGR.attr_off_param(:underline)
"24"

attr_param(arg1)

@spec attr_param(atom()) :: String.t() | nil

Returns SGR parameter string for an attribute.

Used when building combined sequences.

Examples

iex> SGR.attr_param(:bold)
"1"

iex> SGR.attr_param(:underline)
"4"

attr_sequence(attr)

@spec attr_sequence(atom()) :: iolist()

Returns complete SGR escape sequence for an attribute.

Used for direct terminal output.

Examples

iex> SGR.attr_sequence(:bold) |> IO.iodata_to_binary()
"\e[1m"

build_sequence(params)

@spec build_sequence([String.t()]) :: iolist()

Builds a combined SGR sequence from a list of parameters.

Examples

iex> SGR.build_sequence(["1", "31"])
["\e[", ["1", ";", "31"], "m"]

iex> SGR.build_sequence([])
[]

color_param(arg1, n)

@spec color_param(:fg | :bg, color :: term()) :: String.t() | nil

Returns SGR parameter string for a color.

Used when building combined sequences like ESC[1;31;4m.

Examples

iex> SGR.color_param(:fg, :red)
"31"

iex> SGR.color_param(:bg, :blue)
"44"

iex> SGR.color_param(:fg, 196)
"38;5;196"

iex> SGR.color_param(:bg, {0, 255, 128})
"48;2;0;255;128"

color_sequence(type, color)

@spec color_sequence(:fg | :bg, color :: term()) :: iolist()

Returns complete SGR escape sequence for a color.

Used for direct terminal output.

Examples

iex> SGR.color_sequence(:fg, :red) |> IO.iodata_to_binary()
"\e[31m"

iex> SGR.color_sequence(:fg, :default) |> IO.iodata_to_binary()
"\e[39m"

named_colors()

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

Returns all supported named colors.

reset()

@spec reset() :: iolist()

Returns SGR reset sequence.

Resets all attributes and colors to terminal defaults.

supported_attrs()

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

Returns all supported attributes.

valid_attr?(attr)

@spec valid_attr?(term()) :: boolean()

Checks if an attribute is valid.

valid_color?(color)

@spec valid_color?(term()) :: boolean()

Checks if a color value is valid.