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.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Vedeu::Common

#absent?, #array?, #boolean, #boolean?, #empty_value?, #escape?, #falsy?, #hash?, #line_model?, #numeric?, #positionable?, #present?, #snake_case, #stream_model?, #string?, #symbol?, #truthy?, #view_model?

Constructor Details

#initialize(default, &block) ⇒ Vedeu::Configuration::API

Returns a new instance of Vedeu::Config::API.

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

Vedeu.configure do
  # ...
end

Parameters:

  • default (Hash)
  • block (Proc) 


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

def initialize(default, &block)
  @default = default

  instance_eval(&block) if block_given?
end

Instance Attribute Details

#default ⇒ Hash (readonly, protected)

Returns:

  • (Hash) 


585
586
587
 
# File 'lib/vedeu/configuration/api.rb', line 585

def default
  @default
end

Class Method Details

.configure(default, &block) ⇒ Object

Parameters:

  • default (Hash)
  • block (Proc) 


16
17
18
 
# File 'lib/vedeu/configuration/api.rb', line 16

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

Instance Method Details

#background(value = nil) ⇒ Vedeu::Colours::Background

Parameters:

  • value (String) (defaults to: nil)

Returns:



532
533
534
535
536
 
# File 'lib/vedeu/configuration/api.rb', line 532

def background(value = nil)
  return options[:background] unless value

  options[:background] = value
end

#base_path(path = nil) ⇒ String

Override the base path for the application (for locating templates and other resources). By default the base path is just cwd but this will not work for many applications.

Vedeu.configure do
  base_path '/path/to/application'
  # ...
end

Parameters:

  • path (String) (defaults to: nil)

Returns:

  • (String) 


378
379
380
 
# File 'lib/vedeu/configuration/api.rb', line 378

def base_path(path = nil)
  options[:base_path] = path
end

#colour(attrs = {}) ⇒ Hash<Symbol => void>

Sets the background and foreground of the terminal.

Vedeu.configure do
  colour background: '#ff0000', foreground: '#ffff00'
  # ...
end

Parameters:

  • attrs (Hash<Symbol => String>) (defaults to: {})

Returns:

  • (Hash<Symbol => void>) 


556
557
558
559
560
 
# File 'lib/vedeu/configuration/api.rb', line 556

def colour(attrs = {})
  options[:background] = attrs[:background] if attrs.key?(:background)
  options[:foreground] = attrs[:foreground] if attrs.key?(:foreground)
  options
end

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

Vedeu.configure do
  colour_mode 256
  # ...
end

Parameters:

  • value (Fixnum) (defaults to: nil)

Returns:

Raises:

  • (Vedeu::Error::InvalidSyntax) —

    When the value given for an argument or parameter cannot be used because it is not valid for the use case, unsupported or the method expects a different type.



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

def colour_mode(value = nil)
  unless valid_colour_mode?(value)
    raise Vedeu::Error::InvalidSyntax,
          '`colour_mode` must be `8`, `16`, `256`, `16777216`.'
  end

  options[:colour_mode] = value
end

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

Note:

Compression reduces the number of escape sequences being sent to the terminal which improves redraw/render/refresh rate. By default it is enabled.

Sets boolean to enable/disable compression. Vedeu’s default setting is for compression to be enabled. Setting ‘compression` to false will disable compression.

Vedeu.configure do
  compression! # enabled (default)
  # ...
end

Vedeu.configure do
  compression false
  # ...
end

  • Be aware that running an application without compression will affect performance.

Parameters:

  • value (Boolean) (defaults to: true)

Returns:



459
460
461
 
# File 'lib/vedeu/configuration/api.rb', line 459

def compression(value = true)
  options[:compression] = value
end

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

Returns the configuration options set up by the API DSL.

Returns:

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


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

def configuration
  if options[:log].nil?          ||
     options[:log] == false      ||
     empty_value?(options[:log])
    Vedeu.log(type:    :config,
              message: 'Logging has been disabled.')

    return options
  end

  log_options!

  if options[:log] != default[:log]
    Vedeu.log(message: "Switching to '#{options[:log]}' for logging.\n")
  end

  options
end

#cooked! ⇒ Boolean Also known as: cooked

Sets the terminal mode to ‘cooked`. Default terminal mode is `raw`. Also, see #raw!

Vedeu.configure do
  cooked!
  # ...
end

Returns:



142
143
144
 
# File 'lib/vedeu/configuration/api.rb', line 142

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.

Enabling debugging will:

  • Enable ‘Vedeu::Logging::Timer` meaning various timing information is output to the log file.

  • Produce a full a backtrace to STDOUT and the log file upon unrecoverable error or unhandled exception.

    Vedeu.configure do

    debug!
# ...

    end

    Vedeu.configure do

    debug false
# ...

    end

Parameters:

  • value (Boolean) (defaults to: true)

Returns:



198
199
200
 
# File 'lib/vedeu/configuration/api.rb', line 198

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

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

Parameters:

  • value (Boolean) (defaults to: true)

Returns:



88
89
90
 
# File 'lib/vedeu/configuration/api.rb', line 88

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

#drb_height(height = 25) ⇒ Fixnum

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

Vedeu.configure do
  drb_height 25
  # ...
end

Parameters:

  • height (Fixnum) (defaults to: 25)

Returns:

  • (Fixnum) 


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

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

#drb_host(hostname = '') ⇒ String

Parameters:

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

Returns:

  • (String) 


96
97
98
 
# File 'lib/vedeu/configuration/api.rb', line 96

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

#drb_port(port = '') ⇒ String

Parameters:

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

Returns:

  • (String) 


103
104
105
 
# File 'lib/vedeu/configuration/api.rb', line 103

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.

Vedeu.configure do
  drb_width 80
  # ...
end

Parameters:

  • width (Fixnum) (defaults to: 80)

Returns:

  • (Fixnum) 


129
130
131
 
# File 'lib/vedeu/configuration/api.rb', line 129

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

#fake! ⇒ Boolean Also known as: fake

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

Examples:

Vedeu.configure do
  fake!
  # ...
end

Returns:



157
158
159
 
# File 'lib/vedeu/configuration/api.rb', line 157

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

#foreground(value = nil) ⇒ Vedeu::Colours::Foreground

Parameters:

  • value (String) (defaults to: nil)

Returns:



541
542
543
544
545
 
# File 'lib/vedeu/configuration/api.rb', line 541

def foreground(value = nil)
  return options[:foreground] unless value

  options[:foreground] = value
end

#height(height = 25) ⇒ Fixnum Also known as: height=

Sets the height of the terminal.

Vedeu.configure do
  height 25

  # or...

  height = 25

  # ...
end

Parameters:

  • height (Fixnum) (defaults to: 25)

Returns:

  • (Fixnum) 


243
244
245
 
# File 'lib/vedeu/configuration/api.rb', line 243

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

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

Parameters:

  • value (Boolean) (defaults to: true)

Returns:



64
65
66
 
# File 'lib/vedeu/configuration/api.rb', line 64

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

#invalid_mode! ⇒ Object (private)

Raises:

  • (Vedeu::Error::InvalidSyntax) —

    When the value given for an argument or parameter cannot be used because it is not valid for the use case, unsupported or the method expects a different type.



590
591
592
593
 
# File 'lib/vedeu/configuration/api.rb', line 590

def invalid_mode!
  raise Vedeu::Error::InvalidSyntax,
        'Terminal mode can be set to either :cooked, :fake or :raw'
end

#log(filename_or_false = false) ⇒ NilClass|String

Sets the location of the log file, or disables the log. By default, the log file is set to ‘/tmp/vedeu_bootstrap.log’.

# Log messages will be sent to the path given.
Vedeu.configure do
  log '/var/log/vedeu.log'
  # ...
end

# Log messages will be silently dropped.
Vedeu.configure do
  log false
  # ...
end

Parameters:

  • filename_or_false (FalseClass|String) (defaults to: false)

Returns:

  • (NilClass|String) 


265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/vedeu/configuration/api.rb', line 265

def log(filename_or_false = false)
  options[:log] = if filename_or_false.nil? ||
                     filename_or_false == false ||
                     empty_value?(filename_or_false)
                    nil

                  else
                    filename_or_false

                  end
end

#log_except(*types) ⇒ Array<Symbol>

Log specific message types except those given. A complete list of message types can be found at Vedeu::Configuration.log_types.

Vedeu.configure do
  log_except :debug, :event

  # or
  log_except [:debug, :info]

  # ...
end

Parameters:

  • types (Array<Symbol>) —

    The message types which should not be logged.

Returns:

  • (Array<Symbol>) 


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

def log_except(*types)
  options[:log_except] = types.flatten
end

#log_only(*types) ⇒ Array<Symbol>

Only log specific message types. A complete list of message types can be found at Vedeu::Configuration.log_types.

Vedeu.configure do
  log_only :debug, :event

  # or
  log_only [:debug, :info]

  # ...
end

Parameters:

  • types (Array<Symbol>) —

    The message types which should be logged.

Returns:

  • (Array<Symbol>) 


312
313
314
 
# File 'lib/vedeu/configuration/api.rb', line 312

def log_only(*types)
  options[:log_only] = types.flatten
end

#log_options! ⇒ Hash (private)

Returns:

  • (Hash) 


596
597
598
599
600
601
 
# File 'lib/vedeu/configuration/api.rb', line 596

def log_options!
  options.each do |option, value|
    Vedeu.log(type:    :config,
              message: "#{option}: #{value.inspect}")
  end
end

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

Sets boolean to enable/disable mouse support.

Vedeu.configure do
  mouse! # => same as `mouse true`

  # or...
  mouse true

  mouse false

end

Parameters:

  • value (Boolean) (defaults to: true)

Returns:



576
577
578
 
# File 'lib/vedeu/configuration/api.rb', line 576

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

#options ⇒ Hash<Symbol => void> (private)

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

Returns:

  • (Hash<Symbol => void>) 


607
608
609
 
# File 'lib/vedeu/configuration/api.rb', line 607

def options
  @options ||= {}
end

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

Note:

Be aware that running an application with profiling enabled will affect performance.

Vedeu.configure do

profile!
# ...

end

Vedeu.configure do

profile false
# ...

end

Sets boolean to enable/disable profiling. Vedeu’s default setting is for profiling to be disabled. Using ‘profile!` or setting `profile` to true will enable profiling.

Profile uses ‘ruby-prof’ to write a ‘vedeu_profile’ file to the /tmp directory which contains a call trace of the running application. Upon exit, this file can be examined to ascertain certain behaviours of Vedeu.

Parameters:

  • value (Boolean) (defaults to: true)

Returns:



341
342
343
 
# File 'lib/vedeu/configuration/api.rb', line 341

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

#raw! ⇒ Boolean Also known as: raw

Sets the terminal mode to ‘raw`. Default terminal mode is `raw`. Also, see #cooked!

Vedeu.configure do
  raw!
  # ...
end

Returns:



171
172
173
 
# File 'lib/vedeu/configuration/api.rb', line 171

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.

Vedeu.configure do
  renderer MyRenderer
  # ...
end

Vedeu.configure do
  renderers MyRenderer, MyOtherRenderer
  # ...
end

Parameters:

  • renderer (Array<Class>|Class)

Returns:

  • (Array<Class>) 


362
363
364
 
# File 'lib/vedeu/configuration/api.rb', line 362

def renderer(*renderer)
  options[:renderers] = renderer.flatten
end

#root(*args) ⇒ Class

Sets the root of the client application. Vedeu will execute this controller with action and optional arguments first.

Vedeu.configure do
  root :controller, :action, args
  # ...
end

Parameters:

  • args (Array<Symbol|void>)

Returns:

  • (Class) 


392
393
394
 
# File 'lib/vedeu/configuration/api.rb', line 392

def root(*args)
  options[:root] = args
end

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

Parameters:

  • value (Boolean) (defaults to: true)

Returns:



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

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

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

Parameters:

  • value (Boolean) (defaults to: true)

Returns:



72
73
74
 
# File 'lib/vedeu/configuration/api.rb', line 72

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

#stderr(io) ⇒ File|IO

Sets the value of STDERR.

Vedeu.configure do
  stderr IO.console
  # ...
end

Parameters:

  • io (File|IO)

Returns:

  • (File|IO) 


431
432
433
 
# File 'lib/vedeu/configuration/api.rb', line 431

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

#stdin(io) ⇒ File|IO

Sets the value of STDIN.

Vedeu.configure do
  stdin IO.console
  # ...
end

Parameters:

  • io (File|IO)

Returns:

  • (File|IO) 


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

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

#stdout(io) ⇒ File|IO

Sets the value of STDOUT.

Vedeu.configure do
  stdout IO.console
  # ...
end

Parameters:

  • io (File|IO)

Returns:

  • (File|IO) 


418
419
420
 
# File 'lib/vedeu/configuration/api.rb', line 418

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

#terminal_mode(mode) ⇒ Symbol Also known as: terminal_mode=

Sets the terminal mode. Valid values can be either ‘:cooked’, ‘:fake’ or :raw’.

Vedeu.configure do
  terminal_mode :cooked

  # or...

  terminal_mode :fake

  # or...

  terminal_mode :raw

  # or...

  terminal_mode = :raw
  terminal_mode = :fake
  terminal_mode = :cooked

  # ... some code
end

Parameters:

  • mode (Symbol) —

    Either ‘:cooked’, ‘:fake’ or ‘:raw’.

Returns:

  • (Symbol)

Raises:

  • (Vedeu::Error::InvalidSyntax) —

    When the value given for an argument or parameter cannot be used because it is not valid for the use case, unsupported or the method expects a different type.

See Also:



493
494
495
496
497
 
# File 'lib/vedeu/configuration/api.rb', line 493

def terminal_mode(mode)
  return invalid_mode! unless valid_mode?(mode)

  options[:terminal_mode] = mode
end

#threaded(boolean) ⇒ Boolean Also known as: threaded=

Instructs Vedeu to use threads to perform certain actions. This can have a performance impact.

Parameters:

Returns:



505
506
507
 
# File 'lib/vedeu/configuration/api.rb', line 505

def threaded(boolean)
  options[:threaded] = boolean
end

#valid_colour_mode?(value) ⇒ Boolean (private)

Checks that the value provided to #colour_mode is valid.

Parameters:

  • value (Fixnum)

Returns:



615
616
617
 
# File 'lib/vedeu/configuration/api.rb', line 615

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

#valid_mode?(mode) ⇒ Boolean (private)

Checks that the mode provided is valid.

Parameters:

  • mode (Symbol) —

    :cooked, :fake or :raw are valid

Returns:



623
624
625
 
# File 'lib/vedeu/configuration/api.rb', line 623

def valid_mode?(mode)
  [:cooked, :fake, :raw].include?(mode)
end

#width(width = 80) ⇒ Fixnum Also known as: width=

Sets the width of the terminal.

Vedeu.configure do
  width 80

  # or...

  width = 80

  # ...
end

Parameters:

  • width (Fixnum) (defaults to: 80)

Returns:

  • (Fixnum) 


524
525
526
 
# File 'lib/vedeu/configuration/api.rb', line 524

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