Raxol.Terminal.Emulator (Raxol v0.4.0)

View Source

Manages the state of the terminal emulator, including screen buffer, cursor position, attributes, and modes.

Scrollback Limit Configuration

The scrollback buffer limit can be set via application config:

config :raxol, :terminal, scrollback_lines: 1000

Or overridden per emulator instance by passing the :scrollback option to new/3:

Emulator.new(80, 24, scrollback: 2000)

Summary

Functions

Clears the scrollback buffer.

Gets the currently active buffer (:main or :alt) from the emulator state.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_charset_state/1.

Gets whether the cursor is currently visible.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_hyperlink_url/1.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_icon_name/1.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_last_col_exceeded/1.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_mode_manager/1.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_scroll_region/1.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_state_stack/1.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_window_title/1.

Checks if the cursor is below the scroll region and scrolls up if necessary. Called after operations like LF, IND, NEL that might move the cursor off-screen. Version called with no specific target Y - checks current cursor position.

See Raxol.Terminal.Cursor.Manager.move_down/2.

See Raxol.Terminal.Cursor.Manager.move_left/2.

See Raxol.Terminal.Cursor.Manager.move_right/2.

See Raxol.Terminal.Cursor.Manager.move_to_column/2.

See Raxol.Terminal.Cursor.Manager.move_up/2.

Creates a new terminal emulator instance with the specified dimensions and options.

Creates a new terminal emulator instance with specified dimensions, session ID, and client options. This function is required by the TerminalChannel.

Processes input from the user, handling both regular characters and escape sequences. Delegates to Raxol.Terminal.InputHandler.process_terminal_input/2.

Resizes the emulator's screen buffers.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.restore_state/1.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.save_state/1.

See Raxol.Terminal.Cursor.Manager.set_position/2.

Updates the currently active screen buffer.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_charset_state/2.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_hyperlink_url/2.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_icon_name/2.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_last_col_exceeded/2.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_mode_manager/2.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_scroll_region/2.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_state_stack/2.

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_window_title/2.

Types

cursor_style_type()

@type cursor_style_type() ::
  :blinking_block
  | :steady_block
  | :blinking_underline
  | :steady_underline
  | :blinking_bar
  | :steady_bar

t()

@type t() :: %Raxol.Terminal.Emulator{
  active_buffer_type: :main | :alternate,
  alternate_screen_buffer: Raxol.Terminal.ScreenBuffer.t(),
  charset_state: Raxol.Terminal.ANSI.CharacterSets.charset_state(),
  client_options: map(),
  color_palette: map(),
  command: Raxol.Terminal.Command.Manager.t(),
  command_history: list(),
  current_command_buffer: String.t(),
  current_hyperlink: map() | nil,
  current_hyperlink_url: String.t() | nil,
  cursor: Raxol.Terminal.Cursor.Manager.t(),
  cursor_style: cursor_style_type(),
  cwd: String.t() | nil,
  default_palette: map() | nil,
  height: non_neg_integer(),
  icon_name: String.t() | nil,
  last_col_exceeded: term(),
  last_key_event: map() | nil,
  main_screen_buffer: Raxol.Terminal.ScreenBuffer.t(),
  max_command_history: non_neg_integer(),
  memory_limit: non_neg_integer(),
  mode_manager: Raxol.Terminal.ModeManager.t(),
  options: map(),
  output_buffer: String.t(),
  parser_state: map(),
  plugin_manager: Raxol.Terminal.Cursor.Manager.t(Raxol.Plugins.Manager.Core),
  saved_cursor: Raxol.Terminal.Cursor.Manager.t() | nil,
  scroll_region: {non_neg_integer(), non_neg_integer()} | nil,
  scrollback_buffer: list(),
  scrollback_limit: non_neg_integer(),
  session_id: String.t() | nil,
  sixel_state: map() | nil,
  state: Raxol.Terminal.ANSI.CharacterSets.StateManager.t(),
  state_stack: term(),
  style: Raxol.Terminal.ANSI.TextFormatting.text_style(),
  tab_stops: MapSet.t(),
  width: non_neg_integer(),
  window_state: %{
    title: String.t(),
    icon_name: String.t(),
    size: {non_neg_integer(), non_neg_integer()},
    position: {non_neg_integer(), non_neg_integer()},
    stacking_order: :normal | :maximized | :iconified,
    iconified: boolean(),
    maximized: boolean(),
    previous_size: {non_neg_integer(), non_neg_integer()} | nil
  },
  window_title: String.t() | nil
}

Functions

add_to_history(emulator, command)

See Raxol.Terminal.Command.Manager.add_to_history/2.

clear_history(emulator)

See Raxol.Terminal.Command.Manager.clear_history/1.

clear_scrollback(emulator)

@spec clear_scrollback(t()) :: t()

Clears the scrollback buffer.

get_active_buffer(emulator)

@spec get_active_buffer(t()) :: Raxol.Terminal.ScreenBuffer.t()

Gets the currently active buffer (:main or :alt) from the emulator state.

get_charset_state(emulator)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_charset_state/1.

get_command_buffer(emulator)

See Raxol.Terminal.Command.Manager.get_command_buffer/1.

get_command_history(emulator)

See Raxol.Terminal.Command.Manager.get_command_history/1.

get_cursor_position(emulator)

Callback implementation for Raxol.Terminal.EmulatorBehaviour.get_cursor_position/1.

get_cursor_style(emulator)

See Raxol.Terminal.Cursor.Manager.get_style/1.

get_cursor_visible(emulator)

@spec get_cursor_visible(t()) :: boolean()

Gets whether the cursor is currently visible.

Parameters

  • emulator - The emulator to check

Returns

Boolean indicating if cursor is visible

get_history_command(emulator, index)

See Raxol.Terminal.Command.Manager.get_history_command/2.

get_icon_name(emulator)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_icon_name/1.

get_last_col_exceeded(emulator)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_last_col_exceeded/1.

get_last_key_event(emulator)

See Raxol.Terminal.Command.Manager.get_last_key_event/1.

get_mode_manager(emulator)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_mode_manager/1.

get_scroll_region(emulator)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_scroll_region/1.

get_state_stack(emulator)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_state_stack/1.

get_window_title(emulator)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.get_window_title/1.

is_cursor_visible?(emulator)

See Raxol.Terminal.Cursor.Manager.is_visible?/1.

maybe_scroll(emulator)

@spec maybe_scroll(t()) :: t()

Checks if the cursor is below the scroll region and scrolls up if necessary. Called after operations like LF, IND, NEL that might move the cursor off-screen. Version called with no specific target Y - checks current cursor position.

move_cursor_down(emulator, lines \\ 1)

See Raxol.Terminal.Cursor.Manager.move_down/2.

move_cursor_left(emulator, columns \\ 1)

See Raxol.Terminal.Cursor.Manager.move_left/2.

move_cursor_right(emulator, columns \\ 1)

See Raxol.Terminal.Cursor.Manager.move_right/2.

move_cursor_to(emulator, position)

See Raxol.Terminal.Cursor.Manager.move_to/2.

move_cursor_to_column(emulator, column)

See Raxol.Terminal.Cursor.Manager.move_to_column/2.

move_cursor_to_line_start(emulator)

See Raxol.Terminal.Cursor.Manager.move_to_line_start/1.

move_cursor_up(emulator, lines \\ 1)

See Raxol.Terminal.Cursor.Manager.move_up/2.

new(width \\ 80, height \\ 24, opts \\ [])

@spec new(non_neg_integer(), non_neg_integer(), keyword()) :: t()

Creates a new terminal emulator instance with the specified dimensions and options.

Options

  • :scrollback - Maximum number of scrollback lines (default: from config or 1000)
  • :memorylimit - Memory limit (default: 1_000_000)
  • :max_command_history - Max command history (default: 100)

Examples

iex> emulator = Raxol.Terminal.Emulator.new(80, 24, scrollback: 2000)
iex> emulator.scrollback_limit
2000

new(width, height, session_id, client_options)

Creates a new terminal emulator instance with specified dimensions, session ID, and client options. This function is required by the TerminalChannel.

process_input(emulator, input)

@spec process_input(t(), String.t()) :: {t(), String.t()}

Processes input from the user, handling both regular characters and escape sequences. Delegates to Raxol.Terminal.InputHandler.process_terminal_input/2.

process_key_event(emulator, key_event)

See Raxol.Terminal.Command.Manager.process_key_event/2.

resize(emulator, new_width, new_height)

@spec resize(
  t(),
  non_neg_integer(),
  non_neg_integer()
) :: t()

Resizes the emulator's screen buffers.

Parameters

  • emulator - The emulator to resize
  • new_width - New width in columns
  • new_height - New height in rows

Returns

Updated emulator with resized buffers

restore_cursor_state(emulator)

See Raxol.Terminal.Cursor.Manager.restore_state/1.

restore_state(emulator)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.restore_state/1.

save_cursor_state(emulator)

See Raxol.Terminal.Cursor.Manager.save_state/1.

save_state(emulator)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.save_state/1.

search_history(emulator, prefix)

See Raxol.Terminal.Command.Manager.search_history/2.

set_cursor_position(emulator, position)

See Raxol.Terminal.Cursor.Manager.set_position/2.

set_cursor_style(emulator, style)

See Raxol.Terminal.Cursor.Manager.set_style/2.

set_cursor_visibility(emulator, visible)

See Raxol.Terminal.Cursor.Manager.set_visibility/2.

update_active_buffer(emulator, new_buffer)

@spec update_active_buffer(
  t(),
  Raxol.Terminal.ScreenBuffer.t()
) :: t()

Updates the currently active screen buffer.

update_charset_state(emulator, charset_state)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_charset_state/2.

update_command_buffer(emulator, buffer)

See Raxol.Terminal.Command.Manager.update_command_buffer/2.

update_icon_name(emulator, name)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_icon_name/2.

update_last_col_exceeded(emulator, last_col_exceeded)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_last_col_exceeded/2.

update_last_key_event(emulator, event)

See Raxol.Terminal.Command.Manager.update_last_key_event/2.

update_max_history(emulator, new_size)

See Raxol.Terminal.Command.Manager.update_max_history/2.

update_mode_manager(emulator, mode_manager)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_mode_manager/2.

update_scroll_region(emulator, scroll_region)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_scroll_region/2.

update_state_stack(emulator, state_stack)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_state_stack/2.

update_window_title(emulator, title)

See Raxol.Terminal.ANSI.CharacterSets.StateManager.update_window_title/2.