TermUI.PersistentTerms (TermUI v1.0.0)

Centralized management of persistent_term storage for TermUI.

TermUI uses :persistent_term for fast global access to runtime configuration like backend mode, capabilities, and character set. This module provides a single interface for managing the lifecycle of these terms.

These values are node-global context for the active local Raw/TTY runtime. Explicit custom/SSH runtimes keep capabilities in their own state and do not overwrite these terms.

Persistent Term Keys

The following keys are used by TermUI:

:term_ui_backend_mode - Current local backend mode (:raw, :tty, :skip, or nil)
:term_ui_capabilities - Detected terminal capabilities map
term_ui_character_set - Character set (:unicode or :ascii)

BufferManager also uses persistent terms with its own name prefix:

{TermUI.Renderer.BufferManager, name, :current} - Current buffer reference
{TermUI.Renderer.BufferManager, name, :previous} - Previous buffer reference
{TermUI.Renderer.BufferManager, name, :dirty} - Dirty flag atomic

Cleanup

Always call cleanup/0 when shutting down a TermUI application to prevent memory leaks from orphaned persistent terms.

Usage

# Store backend context
PersistentTerms.store_backend_context(:raw, capabilities)

# Query backend mode
:raw = PersistentTerms.backend_mode()

# Clean up on shutdown
PersistentTerms.cleanup()

Summary

Functions

any_terms?()

Checks if any TermUI persistent terms are currently set.

backend_mode()

Gets the current backend mode from persistent_term.

capabilities()

Gets the detected terminal capabilities from persistent_term.

character_set()

Gets the current character set from persistent_term.

cleanup()

Cleans up all TermUI persistent terms.

store_backend_context(backend_mode, capabilities)

Stores backend context in persistent_term.

Functions

any_terms?()

@spec any_terms?() :: boolean()

Checks if any TermUI persistent terms are currently set.

Useful for testing and debugging to ensure cleanup is working.

Examples

iex> TermUI.PersistentTerms.any_terms?()
false

backend_mode()

@spec backend_mode() :: :raw | :tty | :skip | nil

Gets the current backend mode from persistent_term.

Returns :raw, :tty, :skip, or nil if not set. Explicit custom backends do not publish a process-global backend context.

capabilities()

@spec capabilities() :: map() | nil

Gets the detected terminal capabilities from persistent_term.

Returns a map with keys like :colors, :unicode, :dimensions, :terminal or nil if not set.

character_set()

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

Gets the current character set from persistent_term.

Returns :unicode or :ascii.

cleanup()

@spec cleanup() :: :ok

Cleans up all TermUI persistent terms.

This should be called during graceful shutdown to prevent memory leaks. BufferManager persistent terms are handled by BufferManager itself.

Examples

TermUI.PersistentTerms.cleanup()

store_backend_context(backend_mode, capabilities)

@spec store_backend_context(:raw | :tty | :skip | nil, map() | nil) :: :ok

Stores backend context in persistent_term.

This is called by Runtime during initialization to make backend information globally available to components that need to query capabilities.

Parameters

backend_mode - The local backend mode (:raw, :tty, or :skip)
capabilities - The detected capabilities map