Module: Vedeu::Terminal

Extended by:
Terminal
Included in:
Terminal
Defined in:
lib/vedeu/support/terminal.rb

Overview

This module is the direct interface between Vedeu and your terminal/ console, via Ruby’s IO core library.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.centre ⇒ Array

Returns a coordinate tuple of the format [y, x], where ‘y` is the row/line and `x` is the column/character.

Returns:

  • (Array) 


177
178
179
 
# File 'lib/vedeu/support/terminal.rb', line 177

def centre
  [(height / 2), (width / 2)]
end

.centre_x ⇒ Fixnum

Returns the ‘x` (column/character) component of the coodinate tuple provided by centre

Returns:



193
194
195
 
# File 'lib/vedeu/support/terminal.rb', line 193

def centre_x
  centre.last
end

.centre_y ⇒ Fixnum

Returns the ‘y` (row/line) component of the coordinate tuple provided by centre

Returns:



185
186
187
 
# File 'lib/vedeu/support/terminal.rb', line 185

def centre_y
  centre.first
end

.clear ⇒ String

Clears the entire terminal space.

Returns:

  • (String) 


100
101
102
 
# File 'lib/vedeu/support/terminal.rb', line 100

def clear
  output(Esc.string('clear'))
end

.console ⇒ File

Provides our gateway into the wonderful rainbow-filled world of IO.

Returns:

  • (File) 


256
257
258
 
# File 'lib/vedeu/support/terminal.rb', line 256

def console
  IO.console
end

.cooked_mode! ⇒ Symbol

Sets the terminal in to ‘cooked` mode.

Returns:

  • (Symbol) 


133
134
135
136
137
 
# File 'lib/vedeu/support/terminal.rb', line 133

def cooked_mode!
  Vedeu.log(type: :info, message: "Terminal switching to 'cooked' mode")

  @mode = :cooked
end

.cooked_mode? ⇒ Boolean

Returns a boolean indicating whether the terminal is currently in ‘cooked` mode.

Returns:

  • (Boolean) 


126
127
128
 
# File 'lib/vedeu/support/terminal.rb', line 126

def cooked_mode?
  mode == :cooked
end

.height ⇒ Fixnum Also known as: yn, tyn

Returns the total height (number of rows/lines) of the current terminal.

Examples:

Vedeu.height # => provides the height via the Vedeu API.

Returns:



234
235
236
237
238
239
240
241
242
 
# File 'lib/vedeu/support/terminal.rb', line 234

def height
  if Configuration.drb?
    Configuration.drb_height

  else
    size.first

  end
end

.initialize_screen(&block) ⇒ void

This method returns an undefined value.

Parameters:

  • block (Proc) 


91
92
93
94
95
 
# File 'lib/vedeu/support/terminal.rb', line 91

def initialize_screen(&block)
  output(Esc.string('screen_init'))

  yield
end

.input ⇒ String Also known as: read

Takes input from the user via the keyboard. Accepts special keys like the F-Keys etc, by capturing the entire sequence.

Returns:

  • (String) 


43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/vedeu/support/terminal.rb', line 43

def input
  if raw_mode?
    keys = console.getch
    if keys.ord == 27
      keys << console.read_nonblock(3) rescue nil
      keys << console.read_nonblock(2) rescue nil
    end
    keys

  else
    console.gets.chomp

  end
end

.mode ⇒ Symbol

Returns the mode of the terminal, either ‘:raw` or `:cooked`

Returns:

  • (Symbol) 


169
170
171
 
# File 'lib/vedeu/support/terminal.rb', line 169

def mode
  @mode ||= Configuration.terminal_mode
end

.open(&block) ⇒ Array

Opens a terminal screen in either ‘raw` or `cooked` mode. On exit, attempts to restore the screen. See #restore_screen.

Parameters:

  • block (Proc)

Returns:

  • (Array)

Raises:

  • (InvalidSyntax) —

    The required block was not given.



20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
 
# File 'lib/vedeu/support/terminal.rb', line 20

def open(&block)
  fail InvalidSyntax, 'block not given' unless block_given?

  if raw_mode?
    Vedeu.log(type: :info, message: "Terminal entering 'raw' mode")

    console.raw    { initialize_screen { yield } }

  else
    Vedeu.log(type: :info, message: "Terminal entering 'cooked' mode")

    console.cooked { initialize_screen { yield } }

  end
ensure
  restore_screen

end

.origin ⇒ Fixnum Also known as: x, y, tx, ty

Returns 1. This 1 is either the top-most or left-most coordinate of the terminal.

Returns:



201
202
203
 
# File 'lib/vedeu/support/terminal.rb', line 201

def origin
  1
end

.output(*streams) ⇒ Array Also known as: write

Prints the streams to the screen and returns the streams.

Parameters:

  • streams (String|Array)

Returns:

  • (Array) 


63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/vedeu/support/terminal.rb', line 63

def output(*streams)
  streams.each do |stream|
    # Vedeu.log(Esc.escape(stream))

    console.print(stream)

    # Vedeu::Console.write(stream)
  end

  streams
end

.raw_mode! ⇒ Symbol

Sets the terminal in to ‘raw` mode.

Returns:

  • (Symbol) 


150
151
152
153
154
 
# File 'lib/vedeu/support/terminal.rb', line 150

def raw_mode!
  Vedeu.log(type: :info, message: "Terminal switching to 'raw' mode")

  @mode = :raw
end

.raw_mode? ⇒ Boolean

Returns a boolean indicating whether the terminal is currently in ‘raw` mode.

Returns:

  • (Boolean) 


143
144
145
 
# File 'lib/vedeu/support/terminal.rb', line 143

def raw_mode?
  mode == :raw
end

.resize ⇒ TrueClass

When the terminal emit the ‘SIGWINCH’ signal, Vedeu can intercept this and attempt to redraw the current interface with varying degrees of success. Can also be used to simulate a terminal resize.

Returns:

  • (TrueClass) 


81
82
83
84
85
86
87
 
# File 'lib/vedeu/support/terminal.rb', line 81

def resize
  Vedeu.trigger(:_clear_)

  Vedeu.trigger(:_refresh_)

  true
end

.restore_screen ⇒ String

Attempts to tidy up the screen just before the application terminates. The cursor is shown, colours are reset to terminal defaults, the terminal is told to reset, and finally we clear the last line ready for the prompt.

Returns:

  • (String) 


110
111
112
 
# File 'lib/vedeu/support/terminal.rb', line 110

def restore_screen
  output(Esc.string('screen_exit'), Esc.string('clear_last_line'))
end

.set_cursor_mode ⇒ String

Sets the cursor to be visible unless in raw mode, whereby it will be left hidden.

Returns:

  • (String) 


118
119
120
 
# File 'lib/vedeu/support/terminal.rb', line 118

def set_cursor_mode
  output(Esc.string('show_cursor')) unless raw_mode?
end

.size ⇒ Array

Returns a tuple containing the height and width of the current terminal.

Returns:

  • (Array) 


249
250
251
 
# File 'lib/vedeu/support/terminal.rb', line 249

def size
  console.winsize
end

.switch_mode! ⇒ Symbol

Toggles the terminal’s mode between ‘cooked` and `raw`, depending on its current mode.

Returns:

  • (Symbol) 


160
161
162
163
164
 
# File 'lib/vedeu/support/terminal.rb', line 160

def switch_mode!
  return cooked_mode! if raw_mode?

  raw_mode!
end

.virtual ⇒ VirtualTerminal

Returns:



261
262
263
 
# File 'lib/vedeu/support/terminal.rb', line 261

def virtual
  @virtual ||= VirtualTerminal.new(height, width)
end

.width ⇒ Fixnum Also known as: xn, txn

Returns the total width (number of columns/characters) of the current terminal.

Examples:

Vedeu.width # => provides the width via the Vedeu API.

Returns:



216
217
218
219
220
221
222
223
224
 
# File 'lib/vedeu/support/terminal.rb', line 216

def width
  if Configuration.drb?
    Configuration.drb_width

  else
    size.last

  end
end

Instance Method Details

#centre ⇒ Array

Returns a coordinate tuple of the format [y, x], where ‘y` is the row/line and `x` is the column/character.

Returns:

  • (Array) 


177
178
179
 
# File 'lib/vedeu/support/terminal.rb', line 177

def centre
  [(height / 2), (width / 2)]
end

#centre_x ⇒ Fixnum

Returns the ‘x` (column/character) component of the coodinate tuple provided by centre

Returns:



193
194
195
 
# File 'lib/vedeu/support/terminal.rb', line 193

def centre_x
  centre.last
end

#centre_y ⇒ Fixnum

Returns the ‘y` (row/line) component of the coordinate tuple provided by centre

Returns:



185
186
187
 
# File 'lib/vedeu/support/terminal.rb', line 185

def centre_y
  centre.first
end

#clear ⇒ String

Clears the entire terminal space.

Returns:

  • (String) 


100
101
102
 
# File 'lib/vedeu/support/terminal.rb', line 100

def clear
  output(Esc.string('clear'))
end

#console ⇒ File

Provides our gateway into the wonderful rainbow-filled world of IO.

Returns:

  • (File) 


256
257
258
 
# File 'lib/vedeu/support/terminal.rb', line 256

def console
  IO.console
end

#cooked_mode! ⇒ Symbol

Sets the terminal in to ‘cooked` mode.

Returns:

  • (Symbol) 


133
134
135
136
137
 
# File 'lib/vedeu/support/terminal.rb', line 133

def cooked_mode!
  Vedeu.log(type: :info, message: "Terminal switching to 'cooked' mode")

  @mode = :cooked
end

#cooked_mode? ⇒ Boolean

Returns a boolean indicating whether the terminal is currently in ‘cooked` mode.

Returns:

  • (Boolean) 


126
127
128
 
# File 'lib/vedeu/support/terminal.rb', line 126

def cooked_mode?
  mode == :cooked
end

#height ⇒ Fixnum Also known as: yn, tyn

Returns the total height (number of rows/lines) of the current terminal.

Examples:

Vedeu.height # => provides the height via the Vedeu API.

Returns:



234
235
236
237
238
239
240
241
242
 
# File 'lib/vedeu/support/terminal.rb', line 234

def height
  if Configuration.drb?
    Configuration.drb_height

  else
    size.first

  end
end

#initialize_screen(&block) ⇒ void

This method returns an undefined value.

Parameters:

  • block (Proc) 


91
92
93
94
95
 
# File 'lib/vedeu/support/terminal.rb', line 91

def initialize_screen(&block)
  output(Esc.string('screen_init'))

  yield
end

#input ⇒ String Also known as: read

Takes input from the user via the keyboard. Accepts special keys like the F-Keys etc, by capturing the entire sequence.

Returns:

  • (String) 


43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/vedeu/support/terminal.rb', line 43

def input
  if raw_mode?
    keys = console.getch
    if keys.ord == 27
      keys << console.read_nonblock(3) rescue nil
      keys << console.read_nonblock(2) rescue nil
    end
    keys

  else
    console.gets.chomp

  end
end

#mode ⇒ Symbol

Returns the mode of the terminal, either ‘:raw` or `:cooked`

Returns:

  • (Symbol) 


169
170
171
 
# File 'lib/vedeu/support/terminal.rb', line 169

def mode
  @mode ||= Configuration.terminal_mode
end

#open(&block) ⇒ Array

Opens a terminal screen in either ‘raw` or `cooked` mode. On exit, attempts to restore the screen. See #restore_screen.

Parameters:

  • block (Proc)

Returns:

  • (Array)

Raises:

  • (InvalidSyntax) —

    The required block was not given.



20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
 
# File 'lib/vedeu/support/terminal.rb', line 20

def open(&block)
  fail InvalidSyntax, 'block not given' unless block_given?

  if raw_mode?
    Vedeu.log(type: :info, message: "Terminal entering 'raw' mode")

    console.raw    { initialize_screen { yield } }

  else
    Vedeu.log(type: :info, message: "Terminal entering 'cooked' mode")

    console.cooked { initialize_screen { yield } }

  end
ensure
  restore_screen

end

#origin ⇒ Fixnum Also known as: x, y, tx, ty

Returns 1. This 1 is either the top-most or left-most coordinate of the terminal.

Returns:



201
202
203
 
# File 'lib/vedeu/support/terminal.rb', line 201

def origin
  1
end

#output(*streams) ⇒ Array Also known as: write

Prints the streams to the screen and returns the streams.

Parameters:

  • streams (String|Array)

Returns:

  • (Array) 


63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/vedeu/support/terminal.rb', line 63

def output(*streams)
  streams.each do |stream|
    # Vedeu.log(Esc.escape(stream))

    console.print(stream)

    # Vedeu::Console.write(stream)
  end

  streams
end

#raw_mode! ⇒ Symbol

Sets the terminal in to ‘raw` mode.

Returns:

  • (Symbol) 


150
151
152
153
154
 
# File 'lib/vedeu/support/terminal.rb', line 150

def raw_mode!
  Vedeu.log(type: :info, message: "Terminal switching to 'raw' mode")

  @mode = :raw
end

#raw_mode? ⇒ Boolean

Returns a boolean indicating whether the terminal is currently in ‘raw` mode.

Returns:

  • (Boolean) 


143
144
145
 
# File 'lib/vedeu/support/terminal.rb', line 143

def raw_mode?
  mode == :raw
end

#resize ⇒ TrueClass

When the terminal emit the ‘SIGWINCH’ signal, Vedeu can intercept this and attempt to redraw the current interface with varying degrees of success. Can also be used to simulate a terminal resize.

Returns:

  • (TrueClass) 


81
82
83
84
85
86
87
 
# File 'lib/vedeu/support/terminal.rb', line 81

def resize
  Vedeu.trigger(:_clear_)

  Vedeu.trigger(:_refresh_)

  true
end

#restore_screen ⇒ String

Attempts to tidy up the screen just before the application terminates. The cursor is shown, colours are reset to terminal defaults, the terminal is told to reset, and finally we clear the last line ready for the prompt.

Returns:

  • (String) 


110
111
112
 
# File 'lib/vedeu/support/terminal.rb', line 110

def restore_screen
  output(Esc.string('screen_exit'), Esc.string('clear_last_line'))
end

#set_cursor_mode ⇒ String

Sets the cursor to be visible unless in raw mode, whereby it will be left hidden.

Returns:

  • (String) 


118
119
120
 
# File 'lib/vedeu/support/terminal.rb', line 118

def set_cursor_mode
  output(Esc.string('show_cursor')) unless raw_mode?
end

#size ⇒ Array

Returns a tuple containing the height and width of the current terminal.

Returns:

  • (Array) 


249
250
251
 
# File 'lib/vedeu/support/terminal.rb', line 249

def size
  console.winsize
end

#switch_mode! ⇒ Symbol

Toggles the terminal’s mode between ‘cooked` and `raw`, depending on its current mode.

Returns:

  • (Symbol) 


160
161
162
163
164
 
# File 'lib/vedeu/support/terminal.rb', line 160

def switch_mode!
  return cooked_mode! if raw_mode?

  raw_mode!
end

#virtual ⇒ VirtualTerminal

Returns:



261
262
263
 
# File 'lib/vedeu/support/terminal.rb', line 261

def virtual
  @virtual ||= VirtualTerminal.new(height, width)
end

#width ⇒ Fixnum Also known as: xn, txn

Returns the total width (number of columns/characters) of the current terminal.

Examples:

Vedeu.width # => provides the width via the Vedeu API.

Returns:



216
217
218
219
220
221
222
223
224
 
# File 'lib/vedeu/support/terminal.rb', line 216

def width
  if Configuration.drb?
    Configuration.drb_width

  else
    size.last

  end
end