TermUI.Backend.Config (TermUI v1.0.0)

View Source

Configuration handling for terminal backends.

This legacy backend-specific helper provides an interface for reading backend configuration from the application environment. All configuration options have sensible defaults. The primary TermUI.Runtime reads TermUI.Config instead; use that module and runtime options for normal applications.

Configuration Options

Configure TermUI in your config/config.exs:

config :term_ui,
  backend: :auto,
  character_set: :unicode,
  fallback_character_set: :ascii,
  tty_opts: [line_mode: :full_redraw],
  raw_opts: [alternate_screen: true]

Backend Selection

The :backend option controls how the terminal backend is selected:

This legacy validator accepts only the three values above. The primary TermUI.Runtime also accepts a custom backend module implementing TermUI.Backend.

Character Set

The :character_set option specifies the preferred character set for rendering box-drawing characters and other UI elements:

  • :unicode (default) - Use Unicode box-drawing characters
  • :ascii - Use ASCII-only characters

The :fallback_character_set option specifies what to use when the preferred character set is not available:

  • :ascii (default) - Fall back to ASCII
  • :unicode - Fall back to Unicode (rarely useful)

Backend Options

The :tty_opts and :raw_opts options pass backend-specific configuration:

TTY Options:

  • :line_mode - Rendering mode (:full_redraw or :incremental)

Raw Options:

  • :alternate_screen - Whether to use alternate screen buffer (boolean)

Usage

# Get individual configuration values
backend = Config.get_backend()
char_set = Config.get_character_set()

# Get backend-specific options
tty_opts = Config.get_tty_opts()
raw_opts = Config.get_raw_opts()

Validation

Use validate!/0 to check configuration at application startup:

# In your Application.start/2
TermUI.Backend.Config.validate!()

Or use valid?/0 to check without raising:

if Config.valid?() do
  # proceed
else
  # handle invalid config
end

Summary

Types

config()

Complete runtime configuration map.

Functions

get_backend()

Returns the configured backend selection mode.

get_character_set()

Returns the configured character set for UI rendering.

get_fallback_character_set()

Returns the configured fallback character set.

get_raw_opts()

Returns the configured raw backend options.

get_tty_opts()

Returns the configured TTY backend options.

runtime_config()

Returns the complete runtime configuration as a map.

valid?()

Checks if the current configuration is valid.

validate!()

Validates the current configuration, raising on errors.

Types

config()

@type config() :: %{
  backend: :auto | module(),
  character_set: :unicode | :ascii,
  fallback_character_set: :unicode | :ascii,
  tty_opts: keyword(),
  raw_opts: keyword()
}

Complete runtime configuration map.

Contains all configuration values needed to initialize and operate the backend system.

Functions

get_backend()

@spec get_backend() :: :auto | module()

Returns the configured backend selection mode.

Returns

  • :auto - Use automatic backend detection (default)
  • A module atom - Use the specified backend module

Examples

iex> Config.get_backend()
:auto

# With config: [backend: TermUI.Backend.Raw]
iex> Config.get_backend()
TermUI.Backend.Raw

get_character_set()

@spec get_character_set() :: :unicode | :ascii

Returns the configured character set for UI rendering.

Returns

  • :unicode - Use Unicode characters (default)
  • :ascii - Use ASCII-only characters

Examples

iex> Config.get_character_set()
:unicode

# With config: [character_set: :ascii]
iex> Config.get_character_set()
:ascii

get_fallback_character_set()

@spec get_fallback_character_set() :: :unicode | :ascii

Returns the configured fallback character set.

Used when the preferred character set is not available on the terminal.

Returns

  • :ascii - Fall back to ASCII (default)
  • :unicode - Fall back to Unicode

Examples

iex> Config.get_fallback_character_set()
:ascii

# With config: [fallback_character_set: :unicode]
iex> Config.get_fallback_character_set()
:unicode

get_raw_opts()

@spec get_raw_opts() :: keyword()

Returns the configured raw backend options.

Returns

A keyword list of raw mode-specific options. Defaults to [alternate_screen: true].

Options

  • :alternate_screen - Whether to use the alternate screen buffer
    • true - Use alternate screen, restoring original on exit (default)
    • false - Use main screen buffer

Examples

iex> Config.get_raw_opts()
[alternate_screen: true]

# With config: [raw_opts: [alternate_screen: false]]
iex> Config.get_raw_opts()
[alternate_screen: false]

get_tty_opts()

@spec get_tty_opts() :: keyword()

Returns the configured TTY backend options.

Returns

A keyword list of TTY-specific options. Defaults to [line_mode: :full_redraw].

Options

  • :line_mode - Rendering mode
    • :full_redraw - Redraw entire screen each frame (default)
    • :incremental - Only redraw changed lines

Examples

iex> Config.get_tty_opts()
[line_mode: :full_redraw]

# With config: [tty_opts: [line_mode: :incremental]]
iex> Config.get_tty_opts()
[line_mode: :incremental]

runtime_config()

@spec runtime_config() :: config()

Returns the complete runtime configuration as a map.

This function validates the configuration before returning. If any configuration value is invalid, an ArgumentError is raised.

Returns

A map containing all configuration values:

  • :backend - Backend selection mode
  • :character_set - Preferred character set
  • :fallback_character_set - Fallback character set
  • :tty_opts - TTY backend options
  • :raw_opts - Raw backend options

Raises

Examples

iex> Config.runtime_config()
%{
  backend: :auto,
  character_set: :unicode,
  fallback_character_set: :ascii,
  tty_opts: [line_mode: :full_redraw],
  raw_opts: [alternate_screen: true]
}

# With custom config
iex> Config.runtime_config()
%{
  backend: TermUI.Backend.Raw,
  character_set: :ascii,
  fallback_character_set: :ascii,
  tty_opts: [line_mode: :incremental],
  raw_opts: [alternate_screen: false]
}

valid?()

@spec valid?() :: boolean()

Checks if the current configuration is valid.

Returns true if all configuration values are valid, false otherwise. Does not raise exceptions.

Returns

  • true if configuration is valid
  • false if any configuration value is invalid

Examples

iex> Config.valid?()
true

# With invalid config: [backend: :invalid]
iex> Config.valid?()
false

validate!()

@spec validate!() :: :ok

Validates the current configuration, raising on errors.

Checks that all configuration values are valid. Call this at application startup to catch configuration errors early.

Returns

  • :ok if configuration is valid

Raises

  • ArgumentError with a descriptive message if any configuration is invalid

Examples

iex> Config.validate!()
:ok

# With invalid config: [backend: :invalid]
iex> Config.validate!()
** (ArgumentError) invalid :backend value: :invalid