Module: Rich::Control

Defined in:
lib/rich/control.rb

Overview

Terminal control codes and escape sequences. Provides constants and methods for cursor movement, screen clearing, and other terminal control operations.

Defined Under Namespace

Modules: ControlType

Constant Summary collapse

ESC =

ESC character for ANSI sequences

"\e"
CSI =

Control Sequence Introducer

"\e["
OSC =

Operating System Command

"\e]"
ST =

String Terminator

"\e\\"
BEL =

Bell character

"\a"

Class Method Summary collapse

Class Method Details

.bell ⇒ String

Generate bell/alert

Returns:

  • (String) 


46
47
48
 
# File 'lib/rich/control.rb', line 46

def bell
  BEL
end

.carriage_return ⇒ String

Carriage return (move to column 0)

Returns:

  • (String) 


52
53
54
 
# File 'lib/rich/control.rb', line 52

def carriage_return
  "\r"
end

.clear(mode = 2) ⇒ String

Clear the screen

Parameters:

  • mode (Integer) (defaults to: 2) —

    0=cursor to end, 1=start to cursor, 2=entire screen

Returns:

  • (String) 


65
66
67
 
# File 'lib/rich/control.rb', line 65

def clear(mode = 2)
  "#{CSI}#{mode}J"
end

.clear_screen ⇒ String

Clear entire screen and move to home

Returns:

  • (String) 


71
72
73
 
# File 'lib/rich/control.rb', line 71

def clear_screen
  "#{CSI}2J#{CSI}H"
end

.contains_ansi?(text) ⇒ Boolean

Check if text contains ANSI escape sequences

Parameters:

  • text (String) —

    Text to check

Returns:

  • (Boolean) 


283
284
285
 
# File 'lib/rich/control.rb', line 283

def contains_ansi?(text)
  text.match?(/\e[\[\]()][^\a\e]*/)
end

.cursor_backward(count = 1) ⇒ String

Move cursor backward (left)

Parameters:

  • count (Integer) (defaults to: 1) —

    Number of columns

Returns:

  • (String) 


129
130
131
132
133
 
# File 'lib/rich/control.rb', line 129

def cursor_backward(count = 1)
  return "" if count < 1

  "#{CSI}#{count}D"
end

.cursor_down(count = 1) ⇒ String

Move cursor down

Parameters:

  • count (Integer) (defaults to: 1) —

    Number of rows

Returns:

  • (String) 


111
112
113
114
115
 
# File 'lib/rich/control.rb', line 111

def cursor_down(count = 1)
  return "" if count < 1

  "#{CSI}#{count}B"
end

.cursor_forward(count = 1) ⇒ String

Move cursor forward (right)

Parameters:

  • count (Integer) (defaults to: 1) —

    Number of columns

Returns:

  • (String) 


120
121
122
123
124
 
# File 'lib/rich/control.rb', line 120

def cursor_forward(count = 1)
  return "" if count < 1

  "#{CSI}#{count}C"
end

.cursor_move_to(row, column) ⇒ String

Move cursor to position (1-based coordinates)

Parameters:

  • row (Integer) —

    Row (1-based)

  • column (Integer) —

    Column (1-based)

Returns:

  • (String) 


164
165
166
 
# File 'lib/rich/control.rb', line 164

def cursor_move_to(row, column)
  "#{CSI}#{row};#{column}H"
end

.cursor_move_to_column(column) ⇒ String

Move cursor to column (1-based)

Parameters:

  • column (Integer) —

    Column number (1-based)

Returns:

  • (String) 


156
157
158
 
# File 'lib/rich/control.rb', line 156

def cursor_move_to_column(column)
  "#{CSI}#{column}G"
end

.cursor_next_line(count = 1) ⇒ String

Move cursor to next line

Parameters:

  • count (Integer) (defaults to: 1) —

    Number of lines

Returns:

  • (String) 


138
139
140
141
142
 
# File 'lib/rich/control.rb', line 138

def cursor_next_line(count = 1)
  return "" if count < 1

  "#{CSI}#{count}E"
end

.cursor_prev_line(count = 1) ⇒ String

Move cursor to previous line

Parameters:

  • count (Integer) (defaults to: 1) —

    Number of lines

Returns:

  • (String) 


147
148
149
150
151
 
# File 'lib/rich/control.rb', line 147

def cursor_prev_line(count = 1)
  return "" if count < 1

  "#{CSI}#{count}F"
end

.cursor_up(count = 1) ⇒ String

Move cursor up

Parameters:

  • count (Integer) (defaults to: 1) —

    Number of rows

Returns:

  • (String) 


102
103
104
105
106
 
# File 'lib/rich/control.rb', line 102

def cursor_up(count = 1)
  return "" if count < 1

  "#{CSI}#{count}A"
end

.disable_alt_screen ⇒ String

Disable alternative screen buffer

Returns:

  • (String) 


95
96
97
 
# File 'lib/rich/control.rb', line 95

def disable_alt_screen
  "#{CSI}?1049l"
end

.enable_alt_screen ⇒ String

Enable alternative screen buffer

Returns:

  • (String) 


89
90
91
 
# File 'lib/rich/control.rb', line 89

def enable_alt_screen
  "#{CSI}?1049h"
end

.erase_end_of_line ⇒ String

Erase from cursor to end of line

Returns:

  • (String) 


189
190
191
 
# File 'lib/rich/control.rb', line 189

def erase_end_of_line
  "#{CSI}0K"
end

.erase_line(mode = 2) ⇒ String

Erase in line

Parameters:

  • mode (Integer) (defaults to: 2) —

    0=cursor to end, 1=start to cursor, 2=entire line

Returns:

  • (String) 


183
184
185
 
# File 'lib/rich/control.rb', line 183

def erase_line(mode = 2)
  "#{CSI}#{mode}K"
end

.erase_start_of_line ⇒ String

Erase from start of line to cursor

Returns:

  • (String) 


195
196
197
 
# File 'lib/rich/control.rb', line 195

def erase_start_of_line
  "#{CSI}1K"
end

.generate(control_type, param1 = nil, param2 = nil) ⇒ String

Generate control code for a control type

Parameters:

  • control_type (Symbol) —

    Control type

  • param1 (Object) (defaults to: nil) —

    First parameter

  • param2 (Object) (defaults to: nil) —

    Second parameter

Returns:

  • (String) 


292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
 
# File 'lib/rich/control.rb', line 292

def generate(control_type, param1 = nil, param2 = nil)
  case control_type
  when ControlType::BELL
    bell
  when ControlType::CARRIAGE_RETURN
    carriage_return
  when ControlType::HOME
    home
  when ControlType::CLEAR
    clear
  when ControlType::SHOW_CURSOR
    show_cursor
  when ControlType::HIDE_CURSOR
    hide_cursor
  when ControlType::ENABLE_ALT_SCREEN
    enable_alt_screen
  when ControlType::DISABLE_ALT_SCREEN
    disable_alt_screen
  when ControlType::CURSOR_UP
    cursor_up(param1 || 1)
  when ControlType::CURSOR_DOWN
    cursor_down(param1 || 1)
  when ControlType::CURSOR_FORWARD
    cursor_forward(param1 || 1)
  when ControlType::CURSOR_BACKWARD
    cursor_backward(param1 || 1)
  when ControlType::CURSOR_MOVE_TO_COLUMN
    cursor_move_to_column(param1 || 1)
  when ControlType::CURSOR_MOVE_TO
    cursor_move_to(param1 || 1, param2 || 1)
  when ControlType::ERASE_IN_LINE
    erase_line(param1 || 2)
  when ControlType::SET_WINDOW_TITLE
    set_title(param1.to_s)
  else
    ""
  end
end

.hide_cursor ⇒ String

Hide the cursor

Returns:

  • (String) 


83
84
85
 
# File 'lib/rich/control.rb', line 83

def hide_cursor
  "#{CSI}?25l"
end

.home ⇒ String

Move cursor to home position (1,1)

Returns:

  • (String) 


58
59
60
 
# File 'lib/rich/control.rb', line 58

def home
  "#{CSI}H"
end

.hyperlink(url, text, id: nil) ⇒ String

Create a hyperlink

Parameters:

  • url (String) —

    URL

  • text (String) —

    Link text

  • id (String, nil) (defaults to: nil) —

    Optional link ID

Returns:

  • (String) 


251
252
253
254
 
# File 'lib/rich/control.rb', line 251

def hyperlink(url, text, id: nil)
  params = id ? "id=#{id}" : ""
  "#{OSC}8;#{params};#{url}#{ST}#{text}#{OSC}8;;#{ST}"
end

.hyperlink_end ⇒ String

End hyperlink

Returns:

  • (String) 


267
268
269
 
# File 'lib/rich/control.rb', line 267

def hyperlink_end
  "#{OSC}8;;#{ST}"
end

.hyperlink_start(url, id: nil) ⇒ String

Start hyperlink

Parameters:

  • url (String) —

    URL

  • id (String, nil) (defaults to: nil) —

    Optional link ID

Returns:

  • (String) 


260
261
262
263
 
# File 'lib/rich/control.rb', line 260

def hyperlink_start(url, id: nil)
  params = id ? "id=#{id}" : ""
  "#{OSC}8;#{params};#{url}#{ST}"
end

.request_cursor_position ⇒ String

Request cursor position (terminal will respond)

Returns:

  • (String) 


222
223
224
 
# File 'lib/rich/control.rb', line 222

def request_cursor_position
  "#{CSI}6n"
end

.reset ⇒ String

Reset all attributes

Returns:

  • (String) 


242
243
244
 
# File 'lib/rich/control.rb', line 242

def reset
  "#{CSI}0m"
end

.restore_cursor ⇒ String

Restore cursor position

Returns:

  • (String) 


176
177
178
 
# File 'lib/rich/control.rb', line 176

def restore_cursor
  "#{CSI}u"
end

.save_cursor ⇒ String

Save cursor position

Returns:

  • (String) 


170
171
172
 
# File 'lib/rich/control.rb', line 170

def save_cursor
  "#{CSI}s"
end

.scroll_down(count = 1) ⇒ String

Scroll down

Parameters:

  • count (Integer) (defaults to: 1) —

    Number of lines

Returns:

  • (String) 


236
237
238
 
# File 'lib/rich/control.rb', line 236

def scroll_down(count = 1)
  "#{CSI}#{count}T"
end

.scroll_up(count = 1) ⇒ String

Scroll up

Parameters:

  • count (Integer) (defaults to: 1) —

    Number of lines

Returns:

  • (String) 


229
230
231
 
# File 'lib/rich/control.rb', line 229

def scroll_up(count = 1)
  "#{CSI}#{count}S"
end

.set_icon_and_title(title) ⇒ String

Set both icon name and window title

Parameters:

  • title (String) —

    Title/name

Returns:

  • (String) 


216
217
218
 
# File 'lib/rich/control.rb', line 216

def set_icon_and_title(title)
  "#{OSC}0;#{title}#{ST}"
end

.set_icon_name(name) ⇒ String

Set icon name (some terminals)

Parameters:

  • name (String) —

    Icon name

Returns:

  • (String) 


209
210
211
 
# File 'lib/rich/control.rb', line 209

def set_icon_name(name)
  "#{OSC}1;#{name}#{ST}"
end

.set_title(title) ⇒ String

Set window title

Parameters:

  • title (String) —

    Window title

Returns:

  • (String) 


202
203
204
 
# File 'lib/rich/control.rb', line 202

def set_title(title)
  "#{OSC}2;#{title}#{ST}"
end

.show_cursor ⇒ String

Show the cursor

Returns:

  • (String) 


77
78
79
 
# File 'lib/rich/control.rb', line 77

def show_cursor
  "#{CSI}?25h"
end

.strip_ansi(text) ⇒ String

Strip ANSI escape sequences from text

Parameters:

  • text (String) —

    Text to strip

Returns:

  • (String) —

    Text without ANSI sequences



274
275
276
277
278
 
# File 'lib/rich/control.rb', line 274

def strip_ansi(text)
  text.gsub(/\e\[[0-9;]*[A-Za-z]/, "")
      .gsub(/\e\][^\a\e]*(?:\a|\e\\)/, "")
      .gsub(/\e[()][\dAB]/, "")
end