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) 


64
65
66
 
# File 'lib/charming/internal/terminal/adapter.rb', line 64

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) 


44
45
46
 
# File 'lib/charming/internal/terminal/adapter.rb', line 44

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

#hide_cursor ⇒ Object

Hides the terminal cursor.

Raises:

  • (NotImplementedError) 


54
55
56
 
# File 'lib/charming/internal/terminal/adapter.rb', line 54

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

#input_pending? ⇒ Boolean

True when at least one input event is immediately available to read without blocking. The runtime uses this to drain held-key auto-repeat without stalling on the final, empty read. Defaults to false so a backend that can't answer simply opts out of coalescing (the runtime then dispatches each event individually).

Returns:

  • (Boolean) 


33
34
35
 
# File 'lib/charming/internal/terminal/adapter.rb', line 33

def input_pending?
  false
end

#leave_alt_screen ⇒ Object

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

Raises:

  • (NotImplementedError) 


49
50
51
 
# File 'lib/charming/internal/terminal/adapter.rb', line 49

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) 


69
70
71
 
# File 'lib/charming/internal/terminal/adapter.rb', line 69

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) 


59
60
61
 
# File 'lib/charming/internal/terminal/adapter.rb', line 59

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) 


38
39
40
 
# File 'lib/charming/internal/terminal/adapter.rb', line 38

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

#write_escape(sequence) ⇒ Object

Writes an out-of-band escape sequence (image transmission, clipboard write, notification, window title) straight to the terminal, bypassing the line-based frame pipeline. sequence responds to payload (the escape-sequence string). Defaults to a no-op so backends opt in.



87
88
 
# File 'lib/charming/internal/terminal/adapter.rb', line 87

def write_escape(sequence)
end

#write_frame(frame) ⇒ Object

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

Raises:

  • (NotImplementedError) 


74
75
76
 
# File 'lib/charming/internal/terminal/adapter.rb', line 74

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) 


80
81
82
 
# File 'lib/charming/internal/terminal/adapter.rb', line 80

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