Module: Vedeu::Terminal

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

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.absent?(variable) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether a variable is nil or empty.

Parameters:

  • variable (String|Symbol|Array|Fixnum) —

    The variable to check.

Returns:

.become(klass, attributes) ⇒ Class Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Converts one class into another.

Parameters:

  • klass (Class) —

    The class to become an instance of.

  • attributes (Hash) —

    The attributes of klass.

Returns:

  • (Class) —

    Returns a new instance of klass.

.boolean(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating the value was a boolean.

Parameters:

  • value (void)

Returns:

.boolean?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is a Boolean.

Parameters:

Returns:

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


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

def clear
  output(Vedeu.esc.clear)
end

.console ⇒ File

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

Returns:

  • (File) 


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

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:

.debugging! ⇒ String

Disables the mouse and shows the cursor.

Returns:

  • (String) 


80
81
82
 
# File 'lib/vedeu/terminal/terminal.rb', line 80

def debugging!
  output(Vedeu.esc.mouse_x10_off + Vedeu.esc.show_cursor)
end

.escape?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is an escape sequence object (e.g. Vedeu::Cells::Escape.)

Returns:

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

.falsy?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value should be considered false.

Parameters:

  • value (void)

Returns:

.hash?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is a Hash.

Parameters:

  • value (Hash|void)

Returns:

.initialize_screen(mode, &block) ⇒ void

This method returns an undefined value.

Parameters:

  • block (Proc)
  • mode (Symbol) 


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

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

  output(Vedeu.esc.screen_init)

  yield if block_given?
end

.line_model? ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating the model is a Views::Line.

Returns:

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

.numeric?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is a Fixnum.

Parameters:

  • value (Fixnum|void)

Returns:

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



28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/vedeu/terminal/terminal.rb', line 28

def open(&block)
  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: 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) 


46
47
48
49
50
51
52
53
 
# File 'lib/vedeu/terminal/terminal.rb', line 46

def output(*streams)
  streams.each do |stream|
    Vedeu.log(type:    :output,
              message: "Writing to terminal #{stream.size} bytes")

    console.print(stream)
  end
end

.present?(variable) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether a variable has a useful value.

Parameters:

  • variable (String|Symbol|Array|Fixnum) —

    The variable to check.

Returns:

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

.resize ⇒ Boolean

Returns:



58
59
60
61
62
63
64
 
# File 'lib/vedeu/terminal/terminal.rb', line 58

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(Vedeu.esc.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(Vedeu.esc.show_cursor) unless raw_mode?
end

.size ⇒ Array<Fixnum>

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

Returns:

  • (Array<Fixnum>) 


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

def size
  console.winsize
end

.snake_case(klass) ⇒ String Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Converts a class name to a lowercase snake case string.

Examples:

snake_case(MyClassName) # => "my_class_name"
snake_case(NameSpaced::ClassName)
# => "name_spaced/class_name"

snake_case('MyClassName') # => "my_class_name"
snake_case(NameSpaced::ClassName)
# => "name_spaced/class_name"

Parameters:

  • klass (Module|Class|String)

Returns:

  • (String)

.stream_model? ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating the model is a Views::Stream.

Returns:

.string?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is a Fixnum.

Parameters:

  • value (String|void)

Returns:

.switch_mode!(mode = nil) ⇒ Symbol Originally defined in module Mode

Changes the mode of the terminal to the mode given or toggles the terminal mode between ‘cooked`, `fake` and `raw`, depending on the current mode.

Parameters:

  • mode (NilClass|Symbol) (defaults to: nil)

Returns:

  • (Symbol)

.truthy?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value should be considered true.

Parameters:

  • value (void)

Returns:

.valid_mode?(mode) ⇒ Boolean (private) Originally defined in module Mode

Returns a boolean indicating whether the given mode is valid.

Parameters:

  • mode (Symbol) —

    Should be one of the modes listed in #valid_modes.

Returns:

.valid_modes ⇒ Array<Symbol> (private) Originally defined in module Mode

Returns:

  • (Array<Symbol>)

.view_model? ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating the model is a Views::View.

Returns:

Instance Method Details

#absent?(variable) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether a variable is nil or empty.

Parameters:

  • variable (String|Symbol|Array|Fixnum) —

    The variable to check.

Returns:

#become(klass, attributes) ⇒ Class Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Converts one class into another.

Parameters:

  • klass (Class) —

    The class to become an instance of.

  • attributes (Hash) —

    The attributes of klass.

Returns:

  • (Class) —

    Returns a new instance of klass.

#boolean(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating the value was a boolean.

Parameters:

  • value (void)

Returns:

#boolean?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is a Boolean.

Parameters:

Returns:

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


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

def clear
  output(Vedeu.esc.clear)
end

#console ⇒ File

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

Returns:

  • (File) 


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

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:

#debugging! ⇒ String

Disables the mouse and shows the cursor.

Returns:

  • (String) 


80
81
82
 
# File 'lib/vedeu/terminal/terminal.rb', line 80

def debugging!
  output(Vedeu.esc.mouse_x10_off + Vedeu.esc.show_cursor)
end

#escape?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is an escape sequence object (e.g. Vedeu::Cells::Escape.)

Returns:

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

#falsy?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value should be considered false.

Parameters:

  • value (void)

Returns:

#hash?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is a Hash.

Parameters:

  • value (Hash|void)

Returns:

#initialize_screen(mode, &block) ⇒ void

This method returns an undefined value.

Parameters:

  • block (Proc)
  • mode (Symbol) 


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

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

  output(Vedeu.esc.screen_init)

  yield if block_given?
end

#line_model? ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating the model is a Views::Line.

Returns:

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

#numeric?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is a Fixnum.

Parameters:

  • value (Fixnum|void)

Returns:

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



28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/vedeu/terminal/terminal.rb', line 28

def open(&block)
  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: 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) 


46
47
48
49
50
51
52
53
 
# File 'lib/vedeu/terminal/terminal.rb', line 46

def output(*streams)
  streams.each do |stream|
    Vedeu.log(type:    :output,
              message: "Writing to terminal #{stream.size} bytes")

    console.print(stream)
  end
end

#present?(variable) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether a variable has a useful value.

Parameters:

  • variable (String|Symbol|Array|Fixnum) —

    The variable to check.

Returns:

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

#resize ⇒ Boolean

Returns:



58
59
60
61
62
63
64
 
# File 'lib/vedeu/terminal/terminal.rb', line 58

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(Vedeu.esc.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(Vedeu.esc.show_cursor) unless raw_mode?
end

#size ⇒ Array<Fixnum>

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

Returns:

  • (Array<Fixnum>) 


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

def size
  console.winsize
end

#snake_case(klass) ⇒ String Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Converts a class name to a lowercase snake case string.

Examples:

snake_case(MyClassName) # => "my_class_name"
snake_case(NameSpaced::ClassName)
# => "name_spaced/class_name"

snake_case('MyClassName') # => "my_class_name"
snake_case(NameSpaced::ClassName)
# => "name_spaced/class_name"

Parameters:

  • klass (Module|Class|String)

Returns:

  • (String)

#stream_model? ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating the model is a Views::Stream.

Returns:

#string?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is a Fixnum.

Parameters:

  • value (String|void)

Returns:

#switch_mode!(mode = nil) ⇒ Symbol Originally defined in module Mode

Changes the mode of the terminal to the mode given or toggles the terminal mode between ‘cooked`, `fake` and `raw`, depending on the current mode.

Parameters:

  • mode (NilClass|Symbol) (defaults to: nil)

Returns:

  • (Symbol)

#truthy?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value should be considered true.

Parameters:

  • value (void)

Returns:

#valid_mode?(mode) ⇒ Boolean (private) Originally defined in module Mode

Returns a boolean indicating whether the given mode is valid.

Parameters:

  • mode (Symbol) —

    Should be one of the modes listed in #valid_modes.

Returns:

#valid_modes ⇒ Array<Symbol> (private) Originally defined in module Mode

Returns:

  • (Array<Symbol>)

#view_model? ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating the model is a Views::View.

Returns: