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) 


180
181
182
 
# File 'lib/vedeu/support/terminal.rb', line 180

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

.centre_x ⇒ Fixnum

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

Returns:

  • (Fixnum) 


196
197
198
 
# File 'lib/vedeu/support/terminal.rb', line 196

def centre_x
  centre.last
end

.centre_y ⇒ Fixnum

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

Returns:

  • (Fixnum) 


188
189
190
 
# File 'lib/vedeu/support/terminal.rb', line 188

def centre_y
  centre.first
end

.clear ⇒ String

Clears the entire terminal space.

Returns:

  • (String) 


103
104
105
 
# File 'lib/vedeu/support/terminal.rb', line 103

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

.console ⇒ File

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

Returns:

  • (File) 


259
260
261
 
# File 'lib/vedeu/support/terminal.rb', line 259

def console
  IO.console
end

.cooked_mode! ⇒ Symbol

Sets the terminal in to ‘cooked` mode.

Returns:

  • (Symbol) 


136
137
138
139
140
 
# File 'lib/vedeu/support/terminal.rb', line 136

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) 


129
130
131
 
# File 'lib/vedeu/support/terminal.rb', line 129

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:

  • (Fixnum) 


237
238
239
240
241
242
243
244
245
 
# File 'lib/vedeu/support/terminal.rb', line 237

def height
  if Vedeu::Configuration.drb?
    Vedeu::Configuration.drb_height

  else
    size.first

  end
end

.initialize_screen ⇒ void

This method returns an undefined value.



94
95
96
97
98
 
# File 'lib/vedeu/support/terminal.rb', line 94

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

  yield if block_given?
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) 


39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/vedeu/support/terminal.rb', line 39

def input
  Vedeu.log(type: :debug, message: "--- Waiting for user input")

  keys_or_cmd = 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

  Vedeu.trigger(:tick, Time.now.to_f)

  keys_or_cmd
end

.mode ⇒ Symbol

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

Returns:

  • (Symbol) 


172
173
174
 
# File 'lib/vedeu/support/terminal.rb', line 172

def mode
  @mode ||= Vedeu::Configuration.terminal_mode
end

.open ⇒ Array

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

Returns:

  • (Array)

Raises:

  • (InvalidSyntax) —

    The required block was not given.



17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/vedeu/support/terminal.rb', line 17

def open
  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:

  • (Fixnum) 


204
205
206
 
# File 'lib/vedeu/support/terminal.rb', line 204

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) 


66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/vedeu/support/terminal.rb', line 66

def output(*streams)
  streams.each do |stream|
    # Write the stream to the log file.
    # 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) 


153
154
155
156
157
 
# File 'lib/vedeu/support/terminal.rb', line 153

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) 


146
147
148
 
# File 'lib/vedeu/support/terminal.rb', line 146

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) 


85
86
87
88
89
90
91
 
# File 'lib/vedeu/support/terminal.rb', line 85

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) 


113
114
115
 
# File 'lib/vedeu/support/terminal.rb', line 113

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) 


121
122
123
 
# File 'lib/vedeu/support/terminal.rb', line 121

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) 


252
253
254
 
# File 'lib/vedeu/support/terminal.rb', line 252

def size
  console.winsize
end

.switch_mode! ⇒ Symbol

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

Returns:

  • (Symbol) 


163
164
165
166
167
 
# File 'lib/vedeu/support/terminal.rb', line 163

def switch_mode!
  return cooked_mode! if raw_mode?

  raw_mode!
end

.virtual ⇒ VirtualTerminal

Returns:



264
265
266
 
# File 'lib/vedeu/support/terminal.rb', line 264

def virtual
  @virtual ||= Vedeu::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:

  • (Fixnum) 


219
220
221
222
223
224
225
226
227
 
# File 'lib/vedeu/support/terminal.rb', line 219

def width
  if Vedeu::Configuration.drb?
    Vedeu::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) 


180
181
182
 
# File 'lib/vedeu/support/terminal.rb', line 180

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

#centre_x ⇒ Fixnum

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

Returns:

  • (Fixnum) 


196
197
198
 
# File 'lib/vedeu/support/terminal.rb', line 196

def centre_x
  centre.last
end

#centre_y ⇒ Fixnum

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

Returns:

  • (Fixnum) 


188
189
190
 
# File 'lib/vedeu/support/terminal.rb', line 188

def centre_y
  centre.first
end

#clear ⇒ String

Clears the entire terminal space.

Returns:

  • (String) 


103
104
105
 
# File 'lib/vedeu/support/terminal.rb', line 103

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

#console ⇒ File

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

Returns:

  • (File) 


259
260
261
 
# File 'lib/vedeu/support/terminal.rb', line 259

def console
  IO.console
end

#cooked_mode! ⇒ Symbol

Sets the terminal in to ‘cooked` mode.

Returns:

  • (Symbol) 


136
137
138
139
140
 
# File 'lib/vedeu/support/terminal.rb', line 136

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) 


129
130
131
 
# File 'lib/vedeu/support/terminal.rb', line 129

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:

  • (Fixnum) 


237
238
239
240
241
242
243
244
245
 
# File 'lib/vedeu/support/terminal.rb', line 237

def height
  if Vedeu::Configuration.drb?
    Vedeu::Configuration.drb_height

  else
    size.first

  end
end

#initialize_screen ⇒ void

This method returns an undefined value.



94
95
96
97
98
 
# File 'lib/vedeu/support/terminal.rb', line 94

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

  yield if block_given?
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) 


39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/vedeu/support/terminal.rb', line 39

def input
  Vedeu.log(type: :debug, message: "--- Waiting for user input")

  keys_or_cmd = 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

  Vedeu.trigger(:tick, Time.now.to_f)

  keys_or_cmd
end

#mode ⇒ Symbol

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

Returns:

  • (Symbol) 


172
173
174
 
# File 'lib/vedeu/support/terminal.rb', line 172

def mode
  @mode ||= Vedeu::Configuration.terminal_mode
end

#open ⇒ Array

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

Returns:

  • (Array)

Raises:

  • (InvalidSyntax) —

    The required block was not given.



17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/vedeu/support/terminal.rb', line 17

def open
  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:

  • (Fixnum) 


204
205
206
 
# File 'lib/vedeu/support/terminal.rb', line 204

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) 


66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/vedeu/support/terminal.rb', line 66

def output(*streams)
  streams.each do |stream|
    # Write the stream to the log file.
    # 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) 


153
154
155
156
157
 
# File 'lib/vedeu/support/terminal.rb', line 153

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) 


146
147
148
 
# File 'lib/vedeu/support/terminal.rb', line 146

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) 


85
86
87
88
89
90
91
 
# File 'lib/vedeu/support/terminal.rb', line 85

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) 


113
114
115
 
# File 'lib/vedeu/support/terminal.rb', line 113

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) 


121
122
123
 
# File 'lib/vedeu/support/terminal.rb', line 121

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) 


252
253
254
 
# File 'lib/vedeu/support/terminal.rb', line 252

def size
  console.winsize
end

#switch_mode! ⇒ Symbol

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

Returns:

  • (Symbol) 


163
164
165
166
167
 
# File 'lib/vedeu/support/terminal.rb', line 163

def switch_mode!
  return cooked_mode! if raw_mode?

  raw_mode!
end

#virtual ⇒ VirtualTerminal

Returns:



264
265
266
 
# File 'lib/vedeu/support/terminal.rb', line 264

def virtual
  @virtual ||= Vedeu::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:

  • (Fixnum) 


219
220
221
222
223
224
225
226
227
 
# File 'lib/vedeu/support/terminal.rb', line 219

def width
  if Vedeu::Configuration.drb?
    Vedeu::Configuration.drb_width

  else
    size.last

  end
end