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

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:

  • (Boolean)

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

Sets the background of the terminal.

Vedeu.configure do
  background '#ff0000'
  # ...
end

Parameters:

  • value (String) (defaults to: nil)

Returns:



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

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

  bg = Vedeu::Colours::Background.coerce(value)

  options[:background] = colour_attributes(background: bg)
                         .fetch(:background)
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) 


387
388
389
 
# File 'lib/vedeu/configuration/api.rb', line 387

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


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

def colour(attrs = {})
  options[:background] = background(attrs[:background])
  options[:foreground] = foreground(attrs[:foreground])
  options
end

#colour_attributes(attrs = {}) ⇒ Hash<Symbol => Symbol> (private)

Parameters:

Options Hash (attrs):

Returns:

  • (Hash<Symbol => Symbol>) 


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

def colour_attributes(attrs = {})
  {
    background: Vedeu::Configuration.background,
    foreground: Vedeu::Configuration.foreground,
  }.merge!(attrs)
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:



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

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) 


468
469
470
 
# File 'lib/vedeu/configuration/api.rb', line 468

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.

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:

  • (Boolean) 


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

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

#demodulize(klass) ⇒ String Originally defined in module Vedeu::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.

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

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

Sets the foreground of the terminal.

Vedeu.configure do
  foreground '#ffff00'
  # ...
end

Parameters:

  • value (String) (defaults to: nil)

Returns:



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

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

  fg = Vedeu::Colours::Foreground.coerce(value)

  options[:foreground] = colour_attributes(foreground: fg)
                         .fetch(:foreground)
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) 


288
289
290
 
# File 'lib/vedeu/configuration/api.rb', line 288

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:



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

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) 


302
303
304
 
# File 'lib/vedeu/configuration/api.rb', line 302

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


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

def log_only(*types)
  options[:log_only] = types.flatten
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:

  • (Boolean) 


594
595
596
 
# File 'lib/vedeu/configuration/api.rb', line 594

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


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

def options
  @options ||= {}
end

#present?(variable) ⇒ Boolean Originally defined in module Vedeu::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:

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


350
351
352
 
# File 'lib/vedeu/configuration/api.rb', line 350

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


371
372
373
 
# File 'lib/vedeu/configuration/api.rb', line 371

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) 


401
402
403
 
# File 'lib/vedeu/configuration/api.rb', line 401

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

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"

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) 


440
441
442
 
# File 'lib/vedeu/configuration/api.rb', line 440

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) 


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

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) 


427
428
429
 
# File 'lib/vedeu/configuration/api.rb', line 427

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:

See Also:



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

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) 


631
632
633
 
# File 'lib/vedeu/configuration/api.rb', line 631

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) 


639
640
641
 
# File 'lib/vedeu/configuration/api.rb', line 639

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