Module: Charming::Internal::Terminal::Adapter

Included in:
MemoryBackend, TTYBackend
Defined in:
lib/charming/internal/terminal/adapter.rb

Overview

Adapter defines the duck-typed interface that terminal backends must implement. Concrete adapters (‘TTYBackend`, `MemoryBackend`) mix this module in and provide the actual implementations; the methods below raise NotImplementedError to make missing implementations fail loudly.

Input methods:

  • ‘read_event(timeout:)` returns the next event (KeyEvent, MouseEvent, or nil on timeout)

Output methods:

  • ‘size` returns the [width, height] of the terminal

  • ‘enter_alt_screen` / `leave_alt_screen` switch to/from the alternate screen buffer

  • ‘hide_cursor` / `show_cursor` toggle the cursor

  • ‘clear` clears the screen

  • ‘move_cursor(row, column)` positions the cursor (1-based)

  • ‘write_frame(frame)` writes a full multi-line frame string

  • ‘write_lines(line_changes, frame: nil)` writes a partial frame of [row, line] changes

Instance Method Summary collapse

Instance Method Details

#clear ⇒ Object

Clears the entire screen and homes the cursor.

Raises:

  • (NotImplementedError) 


56
57
58
 
# File 'lib/charming/internal/terminal/adapter.rb', line 56

def clear
  raise NotImplementedError, "#{self.class} must implement #clear"
end

#enter_alt_screen ⇒ Object

Switches the terminal into the alternate screen buffer (used to keep the host terminal scrollback untouched while a TUI app is running).

Raises:

  • (NotImplementedError) 


36
37
38
 
# File 'lib/charming/internal/terminal/adapter.rb', line 36

def enter_alt_screen
  raise NotImplementedError, "#{self.class} must implement #enter_alt_screen"
end

#hide_cursor ⇒ Object

Hides the terminal cursor.

Raises:

  • (NotImplementedError) 


46
47
48
 
# File 'lib/charming/internal/terminal/adapter.rb', line 46

def hide_cursor
  raise NotImplementedError, "#{self.class} must implement #hide_cursor"
end

#leave_alt_screen ⇒ Object

Returns the terminal to the primary screen buffer (paired with ‘enter_alt_screen`).

Raises:

  • (NotImplementedError) 


41
42
43
 
# File 'lib/charming/internal/terminal/adapter.rb', line 41

def leave_alt_screen
  raise NotImplementedError, "#{self.class} must implement #leave_alt_screen"
end

#move_cursor(row, column) ⇒ Object

Moves the cursor to the given 1-based (row, column) position.

Raises:

  • (NotImplementedError) 


61
62
63
 
# File 'lib/charming/internal/terminal/adapter.rb', line 61

def move_cursor(row, column)
  raise NotImplementedError, "#{self.class} must implement #move_cursor"
end

#read_event(timeout: nil) ⇒ Object

Reads the next event from the backend. Returns nil when no event is available within timeout seconds. Must be implemented by the including class.

Raises:

  • (NotImplementedError) 


25
26
27
 
# File 'lib/charming/internal/terminal/adapter.rb', line 25

def read_event(timeout: nil)
  raise NotImplementedError, "#{self.class} must implement #read_event"
end

#show_cursor ⇒ Object

Shows the terminal cursor.

Raises:

  • (NotImplementedError) 


51
52
53
 
# File 'lib/charming/internal/terminal/adapter.rb', line 51

def show_cursor
  raise NotImplementedError, "#{self.class} must implement #show_cursor"
end

#size ⇒ Object

Returns the current terminal dimensions as [width, height] in cells.

Raises:

  • (NotImplementedError) 


30
31
32
 
# File 'lib/charming/internal/terminal/adapter.rb', line 30

def size
  raise NotImplementedError, "#{self.class} must implement #size"
end

#write_frame(frame) ⇒ Object

Writes a full multi-line frame string to the terminal in one operation.

Raises:

  • (NotImplementedError) 


66
67
68
 
# File 'lib/charming/internal/terminal/adapter.rb', line 66

def write_frame(frame)
  raise NotImplementedError, "#{self.class} must implement #write_frame"
end

#write_lines(line_changes, frame: nil) ⇒ Object

Writes a partial frame composed of [row, line] tuples. Optional frame: is the full frame string for backends that want to track it (e.g., the MemoryBackend).

Raises:

  • (NotImplementedError) 


72
73
74
 
# File 'lib/charming/internal/terminal/adapter.rb', line 72

def write_lines(line_changes, frame: nil)
  raise NotImplementedError, "#{self.class} must implement #write_lines"
end