Module: Vedeu::Terminal

Extended by:
Terminal
Includes:
Mode
Included in:
Terminal
Defined in:
lib/vedeu/terminal/all.rb,
lib/vedeu/terminal/mode.rb,
lib/vedeu/terminal/buffer.rb,
lib/vedeu/terminal/terminal.rb

Overview

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

Defined Under Namespace

Modules: Buffer, Mode

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) 


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

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) 


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

def centre_x
  centre[-1]
end

.centre_y ⇒ Fixnum

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

Returns:

  • (Fixnum) 


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

def centre_y
  centre[0]
end

.clear ⇒ String

Clears the entire terminal space.

Examples:

Vedeu.clear

Returns:

  • (String) 


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

def clear
  output(Vedeu::EscapeSequences::Esc.string('clear'))
end

.console ⇒ File

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

Returns:

  • (File) 


213
214
215
 
# File 'lib/vedeu/terminal/terminal.rb', line 213

def console
  IO.console
end

.cooked_mode! ⇒ Symbol Originally defined in module Mode

Sets the terminal in to ‘cooked` mode.

Returns:

  • (Symbol)

.cooked_mode? ⇒ Boolean Originally defined in module Mode

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

Returns:

  • (Boolean)

.fake_mode! ⇒ Symbol Originally defined in module Mode

Sets the terminal in to ‘fake` mode.

Returns:

  • (Symbol)

.fake_mode? ⇒ Boolean Originally defined in module Mode

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

Returns:

  • (Boolean)

.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) 


172
173
174
175
176
177
 
# File 'lib/vedeu/terminal/terminal.rb', line 172

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

  size[0]
end

.initialize_screen(mode) ⇒ void

This method returns an undefined value.

Parameters:

  • mode (Symbol) 


77
78
79
80
81
82
83
 
# File 'lib/vedeu/terminal/terminal.rb', line 77

def initialize_screen(mode)
  Vedeu.log(message: "Terminal entering '#{mode}' mode".freeze)

  output(Vedeu::EscapeSequences::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) 


36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/vedeu/terminal/terminal.rb', line 36

def input
  Vedeu.log(type: :input, message: 'Waiting for user input...'.freeze)

  if raw_mode? || fake_mode?
    Vedeu::Editor::Capture.read(console)

  else
    console.gets.chomp

  end
end

.mode ⇒ Symbol Originally defined in module Mode

Returns the mode of the terminal, either ‘:cooked`, `:fake` or `:raw`. Can change throughout the lifespan of the client application.

Returns:

  • (Symbol)

.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:



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

def open
  fail Vedeu::Error::RequiresBlock unless block_given?

  if raw_mode? || fake_mode?
    console.raw    { initialize_screen(mode) { yield } }

  else
    console.cooked { initialize_screen(mode) { 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) 


141
142
143
 
# File 'lib/vedeu/terminal/terminal.rb', line 141

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) 


53
54
55
 
# File 'lib/vedeu/terminal/terminal.rb', line 53

def output(*streams)
  streams.each { |stream| console.print(stream) }
end

.raw_mode! ⇒ Symbol Originally defined in module Mode

Sets the terminal in to ‘raw` mode.

Returns:

  • (Symbol)

.raw_mode? ⇒ Boolean Originally defined in module Mode

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

Returns:

  • (Boolean)

.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.

Examples:

Vedeu.resize

Returns:

  • (TrueClass) 


67
68
69
70
71
72
73
 
# File 'lib/vedeu/terminal/terminal.rb', line 67

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) 


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

def restore_screen
  output(Vedeu::EscapeSequences::Esc.string('screen_exit'))
end

.set_cursor_mode ⇒ String

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

Returns:

  • (String) 


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

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

.size ⇒ Array

Note:

If the terminal is a odd number of characters in height or width, then 1 is deducted from the dimension to make it even. For example; the actual terminal is height: 37, width: 145, then the reported size will be 36, 144 respectively.

This is done to make it easier for client applications to divide the terminal space up when defining interfaces or views, leading to more consistent rendering.

If the client application is using the Geometry::Grid#rows or Geometry::Grid#columns helpers, the dimensions are made more consistent using this approach.

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

Returns:

  • (Array) 


200
201
202
203
204
205
206
207
 
# File 'lib/vedeu/terminal/terminal.rb', line 200

def size
  h, w = console.winsize

  h = (h.even? ? h : h - 1)
  w = (w.even? ? w : w - 1)

  [h, w]
end

.switch_mode! ⇒ Symbol Originally defined in module Mode

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

Returns:

  • (Symbol)

.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) 


156
157
158
159
160
161
 
# File 'lib/vedeu/terminal/terminal.rb', line 156

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

  size[-1]
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) 


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

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) 


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

def centre_x
  centre[-1]
end

#centre_y ⇒ Fixnum

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

Returns:

  • (Fixnum) 


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

def centre_y
  centre[0]
end

#clear ⇒ String

Clears the entire terminal space.

Examples:

Vedeu.clear

Returns:

  • (String) 


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

def clear
  output(Vedeu::EscapeSequences::Esc.string('clear'))
end

#console ⇒ File

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

Returns:

  • (File) 


213
214
215
 
# File 'lib/vedeu/terminal/terminal.rb', line 213

def console
  IO.console
end

#cooked_mode! ⇒ Symbol Originally defined in module Mode

Sets the terminal in to ‘cooked` mode.

Returns:

  • (Symbol)

#cooked_mode? ⇒ Boolean Originally defined in module Mode

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

Returns:

  • (Boolean)

#fake_mode! ⇒ Symbol Originally defined in module Mode

Sets the terminal in to ‘fake` mode.

Returns:

  • (Symbol)

#fake_mode? ⇒ Boolean Originally defined in module Mode

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

Returns:

  • (Boolean)

#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) 


172
173
174
175
176
177
 
# File 'lib/vedeu/terminal/terminal.rb', line 172

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

  size[0]
end

#initialize_screen(mode) ⇒ void

This method returns an undefined value.

Parameters:

  • mode (Symbol) 


77
78
79
80
81
82
83
 
# File 'lib/vedeu/terminal/terminal.rb', line 77

def initialize_screen(mode)
  Vedeu.log(message: "Terminal entering '#{mode}' mode".freeze)

  output(Vedeu::EscapeSequences::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) 


36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/vedeu/terminal/terminal.rb', line 36

def input
  Vedeu.log(type: :input, message: 'Waiting for user input...'.freeze)

  if raw_mode? || fake_mode?
    Vedeu::Editor::Capture.read(console)

  else
    console.gets.chomp

  end
end

#mode ⇒ Symbol Originally defined in module Mode

Returns the mode of the terminal, either ‘:cooked`, `:fake` or `:raw`. Can change throughout the lifespan of the client application.

Returns:

  • (Symbol)

#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:



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

def open
  fail Vedeu::Error::RequiresBlock unless block_given?

  if raw_mode? || fake_mode?
    console.raw    { initialize_screen(mode) { yield } }

  else
    console.cooked { initialize_screen(mode) { 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) 


141
142
143
 
# File 'lib/vedeu/terminal/terminal.rb', line 141

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) 


53
54
55
 
# File 'lib/vedeu/terminal/terminal.rb', line 53

def output(*streams)
  streams.each { |stream| console.print(stream) }
end

#raw_mode! ⇒ Symbol Originally defined in module Mode

Sets the terminal in to ‘raw` mode.

Returns:

  • (Symbol)

#raw_mode? ⇒ Boolean Originally defined in module Mode

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

Returns:

  • (Boolean)

#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.

Examples:

Vedeu.resize

Returns:

  • (TrueClass) 


67
68
69
70
71
72
73
 
# File 'lib/vedeu/terminal/terminal.rb', line 67

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) 


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

def restore_screen
  output(Vedeu::EscapeSequences::Esc.string('screen_exit'))
end

#set_cursor_mode ⇒ String

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

Returns:

  • (String) 


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

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

#size ⇒ Array

Note:

If the terminal is a odd number of characters in height or width, then 1 is deducted from the dimension to make it even. For example; the actual terminal is height: 37, width: 145, then the reported size will be 36, 144 respectively.

This is done to make it easier for client applications to divide the terminal space up when defining interfaces or views, leading to more consistent rendering.

If the client application is using the Geometry::Grid#rows or Geometry::Grid#columns helpers, the dimensions are made more consistent using this approach.

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

Returns:

  • (Array) 


200
201
202
203
204
205
206
207
 
# File 'lib/vedeu/terminal/terminal.rb', line 200

def size
  h, w = console.winsize

  h = (h.even? ? h : h - 1)
  w = (w.even? ? w : w - 1)

  [h, w]
end

#switch_mode! ⇒ Symbol Originally defined in module Mode

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

Returns:

  • (Symbol)

#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) 


156
157
158
159
160
161
 
# File 'lib/vedeu/terminal/terminal.rb', line 156

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

  size[-1]
end