TermUI.CharacterSet (TermUI v1.0.0)

Character set definitions for Unicode and ASCII box-drawing characters.

This module provides character sets for rendering borders, progress bars, check marks, and other UI elements. Two character sets are available:

:unicode - Full Unicode box-drawing characters for modern terminals
:ascii - ASCII fallback characters for limited terminals

Usage

Widgets should use get/1 to retrieve the appropriate character set based on terminal capabilities:

chars = TermUI.CharacterSet.get(:unicode)
top_border = chars.tl <> String.duplicate(chars.h_line, width - 2) <> chars.tr

For runtime queries, use current/0 which reads from persistent_term:

chars = TermUI.CharacterSet.get(TermUI.CharacterSet.current())

Or use the convenience function current_charset/0:

chars = TermUI.CharacterSet.current_charset()

Available Characters

Box Drawing

tl, tr, bl, br - Corners (top-left, top-right, bottom-left, bottom-right)
tl_round, tr_round, bl_round, br_round - Rounded corners
h_line, v_line - Horizontal and vertical lines (light)
h_line_heavy, v_line_heavy - Heavy horizontal and vertical lines
t_up, t_down, t_left, t_right - T-junctions
cross - Cross junction (four-way)

Progress/Gauge

bar_full - Full block for filled progress
bar_empty - Empty/light block for unfilled progress
bar_levels - List of characters for fractional progress (8 levels Unicode, 5 ASCII)
sparkline_levels - List of vertical bar characters for sparklines

Indicators

check - Check mark for success/selected
cross_mark - X mark for failure/deselected
bullet, bullet_empty - Filled and empty circle bullets
pointer - Pointer/cursor indicator

Arrows and Triangles

arrow_up, arrow_down, arrow_left, arrow_right - Directional arrows
arrow_up_down - Bidirectional vertical arrow
triangle_up, triangle_down, triangle_left, triangle_right - Solid triangles

Special Icons

info - Information icon
warning - Warning icon
loading - Loading/spinner icon

Misc

ellipsis - Ellipsis character
dot - Bullet dot/point

Configuration

When no runtime context exists, the fallback character set can be configured in your application:

config :term_ui, :character_set, :unicode

Or changed while no runtime-managed value is present:

Application.put_env(:term_ui, :character_set, :ascii)

Summary

Types

charset()

Character set type.

t()

Character set map containing all box-drawing and special characters.

Functions

box_bottom(width)

Creates the bottom border of a box.

box_top(width)

Creates the top border of a box.

current()

Returns the currently configured character set type.

current_charset()

Returns the current character set as a map.

get(invalid)

Returns the character set for the given type.

horizontal_line(width)

Creates a horizontal line of the specified width.

keys()

Returns the list of all character keys available in a character set.

vertical_line(height)

Creates a vertical line as a list of strings.

Types

charset()

@type charset() :: :unicode | :ascii

Character set type.

:unicode - Full Unicode box-drawing characters
:ascii - ASCII fallback characters

t()

@type t() :: %{
  tl: String.t(),
  tr: String.t(),
  bl: String.t(),
  br: String.t(),
  tl_round: String.t(),
  tr_round: String.t(),
  bl_round: String.t(),
  br_round: String.t(),
  h_line: String.t(),
  v_line: String.t(),
  h_line_heavy: String.t(),
  v_line_heavy: String.t(),
  t_up: String.t(),
  t_down: String.t(),
  t_left: String.t(),
  t_right: String.t(),
  cross: String.t(),
  bar_full: String.t(),
  bar_empty: String.t(),
  bar_levels: [String.t()],
  sparkline_levels: [String.t()],
  check: String.t(),
  cross_mark: String.t(),
  arrow_up: String.t(),
  arrow_down: String.t(),
  arrow_left: String.t(),
  arrow_right: String.t(),
  arrow_up_down: String.t(),
  triangle_up: String.t(),
  triangle_down: String.t(),
  triangle_left: String.t(),
  triangle_right: String.t(),
  bullet: String.t(),
  bullet_empty: String.t(),
  pointer: String.t(),
  info: String.t(),
  warning: String.t(),
  loading: String.t(),
  ellipsis: String.t(),
  dot: String.t()
}

Character set map containing all box-drawing and special characters.

Functions

box_bottom(width)

@spec box_bottom(non_neg_integer()) :: String.t()

Creates the bottom border of a box.

Format: └ + horizontal line + ┘

Parameters

width - Total width including corners (minimum 2)

Examples

iex> TermUI.CharacterSet.box_bottom(10)
"└────────┘"  # Unicode mode

box_top(width)

@spec box_top(non_neg_integer()) :: String.t()

Creates the top border of a box.

Format: ┌ + horizontal line + ┐

Parameters

width - Total width including corners (minimum 2)

Examples

iex> TermUI.CharacterSet.box_top(10)
"┌────────┐"  # Unicode mode

current()

@spec current() :: charset()

Returns the currently configured character set type.

Reads from persistent_term via PersistentTerms (set by Runtime from detected Unicode capabilities), falling back to application config. Defaults to :unicode if neither is configured.

Returns

Either :unicode or :ascii.

Examples

iex> TermUI.CharacterSet.current()
:unicode

# After Runtime sets it based on capabilities
iex> :persistent_term.put(:term_ui_character_set, :ascii)
iex> TermUI.CharacterSet.current()
:ascii

current_charset()

@spec current_charset() :: t()

Returns the current character set as a map.

Convenience function that combines current/0 and get/1.

Returns

A map containing all box-drawing and special characters for the currently configured character set.

Examples

iex> chars = TermUI.CharacterSet.current_charset()
iex> is_map(chars)
true

iex> Application.put_env(:term_ui, :character_set, :ascii)
iex> TermUI.CharacterSet.current_charset().tl
"+"

get(invalid)

@spec get(charset()) :: t()

Returns the character set for the given type.

Parameters

type - Either :unicode or :ascii

Returns

A map containing all box-drawing and special characters.

Examples

iex> chars = TermUI.CharacterSet.get(:unicode)
iex> chars.tl
"┌"

iex> chars = TermUI.CharacterSet.get(:ascii)
iex> chars.tl
"+"

horizontal_line(width)

@spec horizontal_line(non_neg_integer()) :: String.t()

Creates a horizontal line of the specified width.

Uses the current character set's horizontal line character.

Parameters

width - Width of the line in characters

Examples

iex> TermUI.CharacterSet.horizontal_line(5)
"─────"  # Unicode mode

iex> Application.put_env(:term_ui, :character_set, :ascii)
iex> TermUI.CharacterSet.horizontal_line(5)
"-----"

keys()

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

Returns the list of all character keys available in a character set.

Keys are derived from the actual character set map at compile time, ensuring they stay in sync with the character set definitions.

Useful for validation and testing.

Returns

List of atom keys.

Examples

iex> :tl in TermUI.CharacterSet.keys()
true

vertical_line(height)

@spec vertical_line(non_neg_integer()) :: [String.t()]

Creates a vertical line as a list of strings.

Returns a list of vertical line characters, one per line.

Parameters

height - Height of the line in characters

Examples

iex> TermUI.CharacterSet.vertical_line(3)
["│", "│", "│"]  # Unicode mode