Class: Vedeu::Config::API

Inherits:
Object
  • Object
show all
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

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



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

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) 


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

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


586
587
588
589
590
 
# File 'lib/vedeu/configuration/api.rb', line 586

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.



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

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:



487
488
489
 
# File 'lib/vedeu/configuration/api.rb', line 487

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



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:



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

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

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



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:



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:



571
572
573
574
575
 
# File 'lib/vedeu/configuration/api.rb', line 571

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) 


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

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:



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

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.



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


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

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

#log_except(*types) ⇒ Array<Symbol>

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


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

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


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

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:



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

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

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



369
370
371
 
# File 'lib/vedeu/configuration/api.rb', line 369

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:



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


390
391
392
 
# File 'lib/vedeu/configuration/api.rb', line 390

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) 


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

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:



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

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



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) 


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

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) 


433
434
435
 
# File 'lib/vedeu/configuration/api.rb', line 433

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) 


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

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:



521
522
523
524
525
 
# File 'lib/vedeu/configuration/api.rb', line 521

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:



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:



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) 


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

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