Class: Vedeu::Config::API

Inherits:
Object
  • Object
show all
Includes:
Vedeu::Common
Defined in:
lib/vedeu/configuration/api.rb

Overview

The Configuration::API class parses client application configuration into options used by Vedeu to affect certain behaviours.

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Vedeu::Common

#defined_value?

Constructor Details

#initialize(&block) ⇒ Configuration::API

Configure Vedeu via a simple configuration API DSL. Options set here override the default Vedeu configuration set in Vedeu::Configuration#defaults.

Examples:

Vedeu.configure do
  ...

Parameters:

  • block (Proc) 


26
27
28
 
# File 'lib/vedeu/configuration/api.rb', line 26

def initialize(&block)
  instance_eval(&block) if block_given?
end

Class Method Details

.configure(&block) ⇒ Object

Parameters:

  • block (Proc) 


12
13
14
 
# File 'lib/vedeu/configuration/api.rb', line 12

def self.configure(&block)
  new(&block).configuration
end

Instance Method Details

#colour_mode(value = nil) ⇒ Boolean

Note:

iTerm 2 on Mac OSX will handle the true colour setting (16777216), whereas Terminator on Linux will not display colours correctly. For compatibility across platforms, it is recommended to either not set the colour mode at all and allow it to be detected, or use 256 here.

Sets the colour mode of the terminal.

Examples:

Vedeu.configure do
  colour_mode 256
  ...

Parameters:

  • value (Fixnum) (defaults to: nil)

Returns:

  • (Boolean)

Raises:

  • (InvalidSyntax) —

    When the value parameter is not one of 8, 16, 256 or 16777216.



247
248
249
250
251
 
# File 'lib/vedeu/configuration/api.rb', line 247

def colour_mode(value = nil)
  fail InvalidSyntax, '`colour_mode` must be `8`, `16`, `256`, ' \
                      '`16777216`.' unless valid_colour_mode?(value)
  options[:colour_mode] = value
end

#configuration ⇒ Hash<Symbol => Boolean, Fixnum, String>

Returns the configuration options set up by the API DSL.

Returns:

  • (Hash<Symbol => Boolean, Fixnum, String>) 


33
34
35
36
37
38
 
# File 'lib/vedeu/configuration/api.rb', line 33

def configuration
  new_system_keys = Configuration.default_system_keys.merge!(system_keys)
  options.merge!(system_keys: new_system_keys) if system_keys.any?

  Vedeu::Config.log(Esc.green { '[api]' }, options)
end

#cooked! ⇒ Boolean Also known as: cooked

Sets the terminal mode to ‘cooked`. Default terminal mode is `raw`.

Examples:

Vedeu.configure do
  cooked!
  ...

Returns:

  • (Boolean) 


164
165
166
 
# File 'lib/vedeu/configuration/api.rb', line 164

def cooked!
  options[:terminal_mode] = :cooked
end

#debug!(value = true) ⇒ Boolean Also known as: debug

Sets boolean to enable/disable debugging. Vedeu’s default setting is for debugging to be disabled. Using ‘debug!` or setting `debug` to true will enable debugging. If `trace!` is used, or `trace` is set to true, debugging will be enabled, overriding any setting here.

Examples:

Vedeu.configure do
  debug!
  ...

Vedeu.configure do
  debug false
  ...

Parameters:

  • value (Boolean) (defaults to: true)

Returns:

  • (Boolean) 


198
199
200
201
202
203
204
205
206
 
# File 'lib/vedeu/configuration/api.rb', line 198

def debug!(value = true)
  if options.key?(:trace) && options[:trace] != false
    options[:debug] = true

  else
    options[:debug] = value

  end
end

#drb!(value = true) ⇒ Boolean Also known as: drb

Sets boolean to run a DRb server.

Examples:

Vedeu.configure do
  drb!
  ...

Parameters:

  • value (Boolean) (defaults to: true)

Returns:

  • (Boolean) 


99
100
101
 
# File 'lib/vedeu/configuration/api.rb', line 99

def drb!(value = true)
  options[:drb] = value
end

#drb_height(height = 25) ⇒ Fixnum

Sets the height of the fake terminal in the DRb server.

Examples:

Vedeu.configure do
  drb_height 25
  ...

Parameters:

  • height (Fixnum) (defaults to: 25)

Returns:

  • (Fixnum) 


139
140
141
 
# File 'lib/vedeu/configuration/api.rb', line 139

def drb_height(height = 25)
  options[:drb_height] = height
end

#drb_host(hostname = '') ⇒ String

Sets the hostname or IP address of the DRb server.

Examples:

Vedeu.configure do
  drb_host 'localhost'
  ...

Parameters:

  • hostname (String) (defaults to: '')

Returns:

  • (String) 


113
114
115
 
# File 'lib/vedeu/configuration/api.rb', line 113

def drb_host(hostname = '')
  options[:drb_host] = hostname
end

#drb_port(port = '') ⇒ String

Sets the port of the DRb server.

Examples:

Vedeu.configure do
  drb_port 12345
  ...

Parameters:

  • port (Fixnum|String) (defaults to: '')

Returns:

  • (String) 


126
127
128
 
# File 'lib/vedeu/configuration/api.rb', line 126

def drb_port(port = '')
  options[:drb_port] = port
end

#drb_width(width = 80) ⇒ Fixnum

Sets the width of the fake terminal in the DRb server.

Examples:

Vedeu.configure do
  drb_width 80
  ...

Parameters:

  • width (Fixnum) (defaults to: 80)

Returns:

  • (Fixnum) 


152
153
154
 
# File 'lib/vedeu/configuration/api.rb', line 152

def drb_width(width = 80)
  options[:drb_width] = width
end

#exit_key(value) ⇒ String|Symbol

Sets the key used to exit the client application. The default is ‘q`.

Examples:

Vedeu.configure do
  exit_key 'x'
  ...

Vedeu.configure do
  exit_key :f4
  ...

Parameters:

  • value (String|Symbol)

Returns:

  • (String|Symbol) 


337
338
339
340
 
# File 'lib/vedeu/configuration/api.rb', line 337

def exit_key(value)
  return invalid_key('exit_key') unless valid_key?(value)
  system_keys[:exit] = value
end

#focus_next_key(value) ⇒ String|Symbol

Sets the key used to switch focus to the next defined interface. The default is ‘:tab`.

Examples:

Vedeu.configure do
  focus_next_key 'n'
  ...

Vedeu.configure do
  focus_next_key :right
  ...

Parameters:

  • value (String|Symbol)

Returns:

  • (String|Symbol) 


356
357
358
359
 
# File 'lib/vedeu/configuration/api.rb', line 356

def focus_next_key(value)
  return invalid_key('focus_next_key') unless valid_key?(value)
  system_keys[:focus_next] = value
end

#focus_prev_key(value) ⇒ String|Symbol

Sets the key used to switch focus to the previous interface. The default is ‘:shift_tab`.

Examples:

Vedeu.configure do
  focus_prev_key 'p'
  ...

Vedeu.configure do
  focus_prev_key :left
  ...

Parameters:

  • value (String|Symbol)

Returns:

  • (String|Symbol) 


375
376
377
378
 
# File 'lib/vedeu/configuration/api.rb', line 375

def focus_prev_key(value)
  return invalid_key('focus_prev_key') unless valid_key?(value)
  system_keys[:focus_prev] = value
end

#interactive!(value = true) ⇒ Boolean Also known as: interactive

Sets boolean to allow user input. The default behaviour of Vedeu is to be interactive.

Examples:

Vedeu.configure do
  interactive!
  ...

Vedeu.configure do
  interactive false
  ...

Parameters:

  • value (Boolean) (defaults to: true)

Returns:

  • (Boolean) 


54
55
56
 
# File 'lib/vedeu/configuration/api.rb', line 54

def interactive!(value = true)
  options[:interactive] = value
end

#invalid_key(system_key) ⇒ InvalidSyntax (private)

Raises an exception on behalf of the calling method to report that the value provided is not valid.

Parameters:

  • system_key (String) —

    The calling method wishing to raise an exception.

Returns:

  • (InvalidSyntax)

Raises:

  • (InvalidSyntax) —

    When the system_key parameter is not a String or Symbol.



447
448
449
 
# File 'lib/vedeu/configuration/api.rb', line 447

def invalid_key(system_key)
  fail InvalidSyntax, "`#{system_key}` must be a String or a Symbol."
end

#log(filename = '') ⇒ String

Sets the location of the log file.

Examples:

Vedeu.configure do
  log '/var/log/vedeu.log'
  ...

Parameters:

  • filename (String) (defaults to: '')

Returns:

  • (String) 


262
263
264
 
# File 'lib/vedeu/configuration/api.rb', line 262

def log(filename = '')
  options[:log] = filename
end

#mode_switch_key(value) ⇒ String|Symbol

Sets the key used to switch between raw and cooked mode in Vedeu. The default is ‘:escape`.

Examples:

Vedeu.configure do
  mode_switch_key 'm'
  ...

Vedeu.configure do
  mode_switch_key :f1
  ...

Parameters:

  • value (String|Symbol)

Returns:

  • (String|Symbol) 


394
395
396
397
 
# File 'lib/vedeu/configuration/api.rb', line 394

def mode_switch_key(value)
  return invalid_key('mode_switch_key') unless valid_key?(value)
  system_keys[:mode_switch] = value
end

#options ⇒ Hash (private)

Returns the options set via the configuration API DSL or an empty Hash if none were set.

Returns:

  • (Hash) 


405
406
407
 
# File 'lib/vedeu/configuration/api.rb', line 405

def options
  @options ||= {}
end

#raw! ⇒ Boolean Also known as: raw

Sets the terminal mode to ‘raw`. Default terminal mode is `raw`.

Examples:

Vedeu.configure do
  raw!
  ...

Returns:

  • (Boolean) 


177
178
179
 
# File 'lib/vedeu/configuration/api.rb', line 177

def raw!
  options[:terminal_mode] = :raw
end

#renderer(*renderer) ⇒ Array<Class> Also known as: renderers

Sets the renderers for Vedeu. Each renderer added must have the class method ‘.render’ defined as this will be called when rendering content.

Examples:

Vedeu.configure do
  renderer MyRenderer
  ...

Vedeu.configure do
  renderers MyRenderer, MyOtherRenderer
  ...

Parameters:

  • renderer (Array<Class>|Class)

Returns:

  • (Array<Class>) 


280
281
282
 
# File 'lib/vedeu/configuration/api.rb', line 280

def renderer(*renderer)
  options[:renderers] = Vedeu::Configuration.renderers + renderer
end

#run_once!(value = true) ⇒ Boolean Also known as: run_once

Sets boolean to run the Vedeu main application loop once. In effect, using ‘run_once!` or setting `run_once` to true will allow Vedeu to initialize, run any client application code, cleanup, then terminate.

Examples:

Vedeu.configure do
  run_once!
  ...

Parameters:

  • value (Boolean) (defaults to: true)

Returns:

  • (Boolean) 


85
86
87
 
# File 'lib/vedeu/configuration/api.rb', line 85

def run_once!(value = true)
  options[:once] = value
end

#standalone!(value = true) ⇒ Boolean Also known as: standalone

Sets boolean to prevent user intervention. This is the same as setting #interactive! to false.

Examples:

Vedeu.configure do
  standalone!
  ...

Parameters:

  • value (Boolean) (defaults to: true)

Returns:

  • (Boolean) 


69
70
71
 
# File 'lib/vedeu/configuration/api.rb', line 69

def standalone!(value = true)
  options[:interactive] = !value
end

#stderr(io) ⇒ File|IO

Sets the value of STDERR.

Examples:

Vedeu.configure do
  stderr IO.console
  ...

Parameters:

  • io (File|IO)

Returns:

  • (File|IO) 


320
321
322
 
# File 'lib/vedeu/configuration/api.rb', line 320

def stderr(io)
  options[:stderr] = io
end

#stdin(io) ⇒ File|IO

Sets the value of STDIN.

Examples:

Vedeu.configure do
  stdin IO.console
  ...

Parameters:

  • io (File|IO)

Returns:

  • (File|IO) 


294
295
296
 
# File 'lib/vedeu/configuration/api.rb', line 294

def stdin(io)
  options[:stdin] = io
end

#stdout(io) ⇒ File|IO

Sets the value of STDOUT.

Examples:

Vedeu.configure do
  stdout IO.console
  ...

Parameters:

  • io (File|IO)

Returns:

  • (File|IO) 


307
308
309
 
# File 'lib/vedeu/configuration/api.rb', line 307

def stdout(io)
  options[:stdout] = io
end

#system_keys ⇒ Hash (private)

Returns the system keys set via the configuration API DSL or an empty hash if none were redefined.

Returns:

  • (Hash) 


413
414
415
 
# File 'lib/vedeu/configuration/api.rb', line 413

def system_keys
  @system_keys ||= {}
end

#trace!(value = true) ⇒ Boolean Also known as: trace

Sets boolean to enable/disable tracing. Vedeu’s default setting is for tracing to be disabled. Using ‘trace!` or setting `trace` to true will enable tracing and debugging.

Examples:

Vedeu.configure do
  trace!
  ...

Vedeu.configure do
  trace false
  ...

Parameters:

  • value (Boolean) (defaults to: true)

Returns:

  • (Boolean) 


224
225
226
227
 
# File 'lib/vedeu/configuration/api.rb', line 224

def trace!(value = true)
  options[:debug] = true if value
  options[:trace] = value
end

#valid_colour_mode?(value) ⇒ Boolean (private)

Checks that the value provided to #colour_mode is valid.

Parameters:

  • value (Fixnum)

Returns:

  • (Boolean) 


421
422
423
 
# File 'lib/vedeu/configuration/api.rb', line 421

def valid_colour_mode?(value)
  value.is_a?(Fixnum) && [8, 16, 256, 16_777_216].include?(value)
end

#valid_key?(value) ⇒ Boolean (private)

Checks that the value provided to #exit_key, #focus_next_key, #focus_prev_key and #mode_switch_key is valid. Must be a Symbol or a non-empty String.

Parameters:

  • value (String|Symbol)

Returns:

  • (Boolean) 


431
432
433
434
435
436
437
 
# File 'lib/vedeu/configuration/api.rb', line 431

def valid_key?(value)
  return false unless value.is_a?(String) || value.is_a?(Symbol)

  return false if value.is_a?(String) && value.size != 1

  (value.is_a?(String) || value.is_a?(Symbol)) && defined_value?(value)
end