Module: Vedeu::Terminal

Extended by:
Terminal
Includes:
Mode
Included in:
Terminal
Defined in:
lib/vedeu/terminal/terminal.rb,
lib/vedeu/terminal/mode.rb,
lib/vedeu/terminal/buffer.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

Methods included from Mode

#cooked_mode!, #cooked_mode?, #fake_mode!, #fake_mode?, #mode, #raw_mode!, #raw_mode?, #switch_mode!

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) 


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

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) 


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

def centre_x
  centre[-1]
end

.centre_y ⇒ Fixnum

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

Returns:

  • (Fixnum) 


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

def centre_y
  centre[0]
end

.clear ⇒ String

Clears the entire terminal space.

Examples:

Vedeu.clear

Returns:

  • (String) 


88
89
90
91
92
 
# File 'lib/vedeu/terminal/terminal.rb', line 88

def clear
  virtual.clear if Vedeu::Configuration.drb?

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

.console ⇒ File

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

Returns:

  • (File) 


206
207
208
 
# File 'lib/vedeu/terminal/terminal.rb', line 206

def console
  IO.console
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) 


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

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

  size.first
end

.initialize_screen(mode) ⇒ void

This method returns an undefined value.

Parameters:

  • mode (Symbol) 


74
75
76
77
78
79
80
 
# File 'lib/vedeu/terminal/terminal.rb', line 74

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

  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) 


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

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

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

  else
    console.gets.chomp

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



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

def open
  fail Vedeu::Error::InvalidSyntax, 'block not given' 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) 


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

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) 


51
52
53
 
# File 'lib/vedeu/terminal/terminal.rb', line 51

def output(*streams)
  streams.each { |stream| console.print(stream) }
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.

Examples:

Vedeu.resize

Returns:

  • (TrueClass) 


64
65
66
67
68
69
70
 
# File 'lib/vedeu/terminal/terminal.rb', line 64

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) 


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

def restore_screen
  output(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) 


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

def set_cursor_mode
  output(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) 


194
195
196
197
198
199
200
201
 
# File 'lib/vedeu/terminal/terminal.rb', line 194

def size
  h, w = console.winsize

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

  [h, w]
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) 


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

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

  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) 


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

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) 


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

def centre_x
  centre[-1]
end

#centre_y ⇒ Fixnum

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

Returns:

  • (Fixnum) 


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

def centre_y
  centre[0]
end

#clear ⇒ String

Clears the entire terminal space.

Examples:

Vedeu.clear

Returns:

  • (String) 


88
89
90
91
92
 
# File 'lib/vedeu/terminal/terminal.rb', line 88

def clear
  virtual.clear if Vedeu::Configuration.drb?

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

#console ⇒ File

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

Returns:

  • (File) 


206
207
208
 
# File 'lib/vedeu/terminal/terminal.rb', line 206

def console
  IO.console
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) 


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

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

  size.first
end

#initialize_screen(mode) ⇒ void

This method returns an undefined value.

Parameters:

  • mode (Symbol) 


74
75
76
77
78
79
80
 
# File 'lib/vedeu/terminal/terminal.rb', line 74

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

  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) 


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

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

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

  else
    console.gets.chomp

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



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

def open
  fail Vedeu::Error::InvalidSyntax, 'block not given' 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) 


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

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) 


51
52
53
 
# File 'lib/vedeu/terminal/terminal.rb', line 51

def output(*streams)
  streams.each { |stream| console.print(stream) }
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.

Examples:

Vedeu.resize

Returns:

  • (TrueClass) 


64
65
66
67
68
69
70
 
# File 'lib/vedeu/terminal/terminal.rb', line 64

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) 


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

def restore_screen
  output(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) 


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

def set_cursor_mode
  output(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) 


194
195
196
197
198
199
200
201
 
# File 'lib/vedeu/terminal/terminal.rb', line 194

def size
  h, w = console.winsize

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

  [h, w]
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) 


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

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

  size[-1]
end