TermUI.Error (TermUI v1.0.0)

Standardized error types for TermUI.

This module provides a consistent set of error types that are used throughout the TermUI codebase. Using standardized error types makes error handling more predictable and allows for better error messages to users.

Error Types

The following error types are defined:

:invalid_argument - A required argument was missing or invalid
:not_found - A requested resource was not found
:not_supported - An operation is not supported in the current context
:timeout - An operation timed out
:terminal_setup_failed - Failed to initialize the terminal
:size_detection_failed - Failed to detect terminal dimensions
:invalid_size - Terminal dimensions were invalid
:out_of_bounds - An operation exceeded valid bounds
:backend_unavailable - The requested backend is not available
:command_failed - An external command failed
:command_not_found - An external command was not found
:command_not_allowed - An external command is not in the whitelist
:invalid_configuration - Application configuration is invalid
:component_crashed - A component process crashed
:component_unavailable - A component is not available

Usage

When returning errors from functions, use these standardized reasons:

def init(opts) do
  case Keyword.get(opts, :size) do
    nil -> {:error, {:invalid_size, "size is required"}}
    size when is_integer(size) and size > 0 -> {:ok, size}
    _ -> {:error, {:invalid_size, "size must be a positive integer"}}
  end
end

Error Reasons

Error reasons are either:

An atom from the list above (simple error)
A tuple {error_type, details} (error with additional context)

Examples

{:error, :not_found}
{:error, {:invalid_size, "dimensions must be positive"}}
{:error, {:command_failed, {:exit_code, 1}}}

Summary

Types

error_reason()

result()

Functions

error(type, details)

Creates an error reason with details.

error_reason?(arg1)

Returns true if the given term is an error reason.

error_type(type)

Returns the error type from an error reason.

format(arg1)

Formats an error reason into a human-readable string.

Types

error_reason()

@type error_reason() ::
  :invalid_argument
  | :not_found
  | :not_supported
  | :timeout
  | :terminal_setup_failed
  | :size_detection_failed
  | :invalid_size
  | :out_of_bounds
  | :backend_unavailable
  | :command_failed
  | :command_not_found
  | :command_not_allowed
  | :invalid_configuration
  | :component_crashed
  | :component_unavailable
  | {atom(), term()}

result()

@type result() :: {:ok, term()} | {:error, error_reason()}

Functions

error(type, details)

@spec error(atom(), term()) :: {atom(), term()}

Creates an error reason with details.

Examples

iex> TermUI.Error.error(:invalid_size, "dimensions must be positive")
{:invalid_size, "dimensions must be positive"}

error_reason?(arg1)

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

Returns true if the given term is an error reason.

Examples

iex> TermUI.Error.error_reason?(:not_found)
true

iex> TermUI.Error.error_reason?({:invalid_size, "too small"})
true

iex> TermUI.Error.error_reason?(:ok)
false

iex> TermUI.Error.error_reason?({:ok, "result"})
false

error_type(type)

@spec error_type(error_reason()) :: atom()

Returns the error type from an error reason.

For simple error reasons (atoms), returns the atom itself. For tuple error reasons, returns the first element (the type).

Examples

iex> TermUI.Error.error_type(:not_found)
:not_found

iex> TermUI.Error.error_type({:invalid_size, "too small"})
:invalid_size

format(arg1)

@spec format(error_reason()) :: String.t()

Formats an error reason into a human-readable string.

Examples

iex> TermUI.Error.format(:not_found)
"not found"

iex> TermUI.Error.format({:invalid_size, "must be positive"})
"invalid size: must be positive"

iex> TermUI.Error.format({:command_failed, {:exit_code, 1}})
"command failed: {:exit_code, 1}"