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

Constructor Details

#initialize(&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:

  • block (Proc) 


30
31
32
 
# File 'lib/vedeu/configuration/api.rb', line 30

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

Class Method Details

.configure(&block) ⇒ Object

Parameters:

  • block (Proc) 


14
15
16
 
# File 'lib/vedeu/configuration/api.rb', line 14

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

Instance Method Details

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

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

Parameters:

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

    The variable to check.

Returns:

  • (Boolean)

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

  • (Boolean)

Raises:



262
263
264
265
266
267
268
269
 
# File 'lib/vedeu/configuration/api.rb', line 262

def colour_mode(value = nil)
  unless valid_colour_mode?(value)
    fail 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:

  • (Boolean) 


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


37
38
39
40
 
# File 'lib/vedeu/configuration/api.rb', line 37

def configuration
  Vedeu::Config
    .log(Vedeu::EscapeSequences::Esc.green { '[api]' }, 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:

  • (Boolean) 


186
187
188
 
# File 'lib/vedeu/configuration/api.rb', line 186

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.

At this time, debugging only toggles between viewing a full backtrace (true) upon exception or only its top line (false).

Vedeu.configure do
  debug!
  # ...
end

Vedeu.configure do
  debug false
  # ...
end

Parameters:

  • value (Boolean) (defaults to: true)

Returns:

  • (Boolean) 


239
240
241
 
# File 'lib/vedeu/configuration/api.rb', line 239

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

#demodulize(klass) ⇒ String Originally defined in module Vedeu::Common

Removes the module part from the expression in the string.

Examples:

demodulize('Vedeu::SomeModule::SomeClass') # => "SomeClass"

Parameters:

  • klass (Class|String)

Returns:

  • (String)

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

Sets boolean to run a DRb server.

Vedeu.configure do
  drb!
  # ...
end

Parameters:

  • value (Boolean) (defaults to: true)

Returns:

  • (Boolean) 


120
121
122
 
# File 'lib/vedeu/configuration/api.rb', line 120

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) 


160
161
162
 
# File 'lib/vedeu/configuration/api.rb', line 160

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

#drb_host(hostname = '') ⇒ String

Sets the hostname or IP address of the DRb server.

Vedeu.configure do
  drb_host 'localhost'
  # ...
end

Parameters:

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

Returns:

  • (String) 


134
135
136
 
# File 'lib/vedeu/configuration/api.rb', line 134

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

#drb_port(port = '') ⇒ String

Sets the port of the DRb server.

Vedeu.configure do
  drb_port 12345
  # ...
end

Parameters:

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

Returns:

  • (String) 


147
148
149
 
# File 'lib/vedeu/configuration/api.rb', line 147

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) 


173
174
175
 
# File 'lib/vedeu/configuration/api.rb', line 173

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:

  • (Boolean) 


201
202
203
 
# File 'lib/vedeu/configuration/api.rb', line 201

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

#height(height = 25) ⇒ Fixnum

Sets the height of the terminal.

Vedeu.configure do
  height 25
  # ...
end

Parameters:

  • height (Fixnum) (defaults to: 25)

Returns:

  • (Fixnum) 


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

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

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

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

Vedeu.configure do
  interactive! # => same as `interactive true` or
               #    `standalone false`
  # ...
end

Vedeu.configure do
  interactive true # => Allow user input.
  # ...
end

Vedeu.configure do
  interactive false # => Disallow user input.
  # ...
end

Parameters:

  • value (Boolean) (defaults to: true)

Returns:

  • (Boolean) 


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

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

#invalid_mode! ⇒ Object (private)

Raises:



510
511
512
513
 
# File 'lib/vedeu/configuration/api.rb', line 510

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

#log(filename = '') ⇒ String

Sets the location of the log file.

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

Parameters:

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

Returns:

  • (String) 


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

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

#log_only(*types) ⇒ Array<Symbol>

Only log specific message types. A complete list of message types can be found at Logging::Log.message_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

#options ⇒ Hash (private)

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

Returns:

  • (Hash) 


519
520
521
 
# File 'lib/vedeu/configuration/api.rb', line 519

def options
  @options ||= {}
end

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

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

Parameters:

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

    The variable to check.

Returns:

  • (Boolean)

#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 ‘profile.html’ 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:

  • (Boolean) 


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:

  • (Boolean) 


215
216
217
 
# File 'lib/vedeu/configuration/api.rb', line 215

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

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.

Vedeu.configure do
  run_once!
  # ...
end

Parameters:

  • value (Boolean) (defaults to: true)

Returns:

  • (Boolean) 


106
107
108
 
# File 'lib/vedeu/configuration/api.rb', line 106

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

#snake_case(name) ⇒ String Originally defined in module Vedeu::Common

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"

Parameters:

  • name (String)

Returns:

  • (String)

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

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

Vedeu.configure do
  standalone! # => same as `standalone true` or
              #    `interactive false`
  # ...
end

Vedeu.configure do
  standalone true # => Disallow user input.
  # ...
end

Vedeu.configure do
  standalone false # => Allow user input.
  # ...
end

Parameters:

  • value (Boolean) (defaults to: true)

Returns:

  • (Boolean) 


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

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

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

  # ... some code
end

Parameters:

  • mode (Symbol) —

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

Returns:

  • (Symbol)

Raises:

See Also:



488
489
490
491
492
 
# File 'lib/vedeu/configuration/api.rb', line 488

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

  options[:terminal_mode] = mode
end

#valid_colour_mode?(value) ⇒ Boolean (private)

Checks that the value provided to #colour_mode is valid.

Parameters:

  • value (Fixnum)

Returns:

  • (Boolean) 


527
528
529
 
# File 'lib/vedeu/configuration/api.rb', line 527

def valid_colour_mode?(value)
  value.is_a?(Fixnum) && [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:

  • (Boolean) 


535
536
537
 
# File 'lib/vedeu/configuration/api.rb', line 535

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

#width(width = 80) ⇒ Fixnum

Sets the width of the terminal.

Vedeu.configure do
  width 80
  # ...
end

Parameters:

  • width (Fixnum) (defaults to: 80)

Returns:

  • (Fixnum) 


503
504
505
 
# File 'lib/vedeu/configuration/api.rb', line 503

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