module Vedeu
module Config
# The Configuration::API class parses client application configuration into
# options used by Vedeu to affect certain behaviours.
#
class API
include Vedeu::Common
# @param (see #initialize)
def self.configure(&block)
new(&block).configuration
end
# 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
#
# @param block [Proc]
# @return [Vedeu::Configuration::API]
def initialize(&block)
instance_eval(&block) if block_given?
end
# Returns the configuration options set up by the API DSL.
#
# @return [Hash<Symbol => Boolean, Fixnum, String>]
def configuration
Vedeu::Config.log(Esc.green { '[api]' }, options)
end
# 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
#
# @param value [Boolean]
# @return [Boolean]
def interactive!(value = true)
options[:interactive] = value
end
alias_method :interactive, :interactive!
# Sets boolean to prevent user intervention. This is the same as setting
# {include:Vedeu::Config::API#interactive!} 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
#
# @param value [Boolean]
# @return [Boolean]
def standalone!(value = true)
options[:interactive] = !value
end
alias_method :standalone, :standalone!
# 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
#
# @param value [Boolean]
# @return [Boolean]
def run_once!(value = true)
options[:once] = value
end
alias_method :run_once, :run_once!
# Sets boolean to run a DRb server.
#
# Vedeu.configure do
# drb!
# # ...
# end
#
# @param value [Boolean]
# @return [Boolean]
def drb!(value = true)
options[:drb] = value
end
alias_method :drb, :drb!
# Sets the hostname or IP address of the DRb server.
#
# Vedeu.configure do
# drb_host 'localhost'
# # ...
# end
#
# @param hostname [String]
# @return [String]
def drb_host(hostname = '')
options[:drb_host] = hostname
end
# Sets the port of the DRb server.
#
# Vedeu.configure do
# drb_port 12345
# # ...
# end
#
# @param port [Fixnum|String]
# @return [String]
def drb_port(port = '')
options[:drb_port] = port
end
# Sets the height of the fake terminal in the DRb server.
#
# Vedeu.configure do
# drb_height 25
# # ...
# end
#
# @param height [Fixnum]
# @return [Fixnum]
def drb_height(height = 25)
options[:drb_height] = height
end
# Sets the width of the fake terminal in the DRb server.
#
# Vedeu.configure do
# drb_width 80
# # ...
# end
#
# @param width [Fixnum]
# @return [Fixnum]
def drb_width(width = 80)
options[:drb_width] = width
end
# Sets the terminal mode to `cooked`. Default terminal mode is `raw`.
# Also, see {Vedeu::Config::API#raw!}
#
# Vedeu.configure do
# cooked!
# # ...
# end
#
# @return [Boolean]
def cooked!
options[:terminal_mode] = :cooked
end
alias_method :cooked, :cooked!
# Sets the terminal mode to `fake`. Default terminal mode is `raw`.
#
# @example
# Vedeu.configure do
# fake!
# # ...
# end
#
# @return [Boolean]
def fake!
options[:terminal_mode] = :fake
end
alias_method :fake, :fake!
# Sets the terminal mode to `raw`. Default terminal mode is `raw`.
# Also, see {Vedeu::Config::API#cooked!}
#
# Vedeu.configure do
# raw!
# # ...
# end
#
# @return [Boolean]
def raw!
options[:terminal_mode] = :raw
end
alias_method :raw, :raw!
# 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.
#
# @note
# Be aware that running an application with debugging enabled will
# affect performance.
#
# Vedeu.configure do
# debug!
# # ...
# end
#
# Vedeu.configure do
# debug false
# # ...
# end
#
# @param value [Boolean]
# @return [Boolean]
def debug!(value = true)
options[:debug] = value
end
alias_method :debug, :debug!
# Sets the colour mode of the terminal.
#
# Vedeu.configure do
# colour_mode 256
# # ...
# end
#
# @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.
#
# @param value [Fixnum]
# @raise [Vedeu::Error::InvalidSyntax] When the value parameter is not one
# of +8+, +16+, +256+ or +16777216+.
# @return [Boolean]
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
# Sets the location of the log file.
#
# Vedeu.configure do
# log '/var/log/vedeu.log'
# # ...
# end
#
# @param filename [String]
# @return [String]
def log(filename = '')
options[:log] = filename
end
# Only log specific message types. A complete list of message
# types can be found at {Vedeu::Logging::Log.message_types}.
#
# Vedeu.configure do
# log_only :debug, :event
# # ...
# end
#
# @param types [Array<Symbol>] The message types which should be
# slogged.
# @return [Array<Symbol>]
def log_only(*types)
options[:log_only] = types
end
# 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
#
# @param renderer [Array<Class>|Class]
# @return [Array<Class>]
def renderer(*renderer)
options[:renderers] = Vedeu::Configuration.renderers + renderer
end
alias_method :renderers, :renderer
# 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
#
# @param path [String]
# @return [String]
def base_path(path = nil)
options[:base_path] = path
end
# 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
#
# @param args [Array<Symbol|void>]
# @return [Class]
def root(*args)
options[:root] = args
end
# Sets the value of STDIN.
#
# Vedeu.configure do
# stdin IO.console
# # ...
# end
#
# @param io [File|IO]
# @return [File|IO]
def stdin(io)
options[:stdin] = io
end
# Sets the value of STDOUT.
#
# Vedeu.configure do
# stdout IO.console
# # ...
# end
#
# @param io [File|IO]
# @return [File|IO]
def stdout(io)
options[:stdout] = io
end
# Sets the value of STDERR.
#
# Vedeu.configure do
# stderr IO.console
# # ...
# end
#
# @param io [File|IO]
# @return [File|IO]
def stderr(io)
options[:stderr] = io
end
# 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
#
# @note
# - Be aware that running an application without compression will
# affect performance.
# - Compression cannot yet be configured using a CLI option flag.
#
# @param value [Boolean]
# @return [Boolean]
def compression(value = true)
options[:compression] = value
end
alias_method :compression!, :compression
# 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
#
# @param mode [Symbol] Either ':cooked', ':fake' or ':raw'.
# @raise [Vedeu::Error::InvalidSyntax] When the mode is not ':cooked',
# ':fake' or ':raw'.
# @return [Symbol]
# @see Vedeu::Config::API#cooked!
# @see Vedeu::Config::API#fake!
# @see Vedeu::Config::API#raw!
def terminal_mode(mode)
if [:cooked, :fake, :raw].include?(mode)
options[:terminal_mode] = mode
else
fail Vedeu::Error::InvalidSyntax,
'Terminal mode can be set to either :cooked, :fake or :raw'
end
end
private
# Returns the options set via the configuration API DSL or an empty Hash
# when none were set.
#
# @return [Hash]
def options
@options ||= {}
end
# Checks that the value provided to {#colour_mode} is valid.
#
# @param value [Fixnum]
# @return [Boolean]
def valid_colour_mode?(value)
value.is_a?(Fixnum) && [8, 16, 256, 16_777_216].include?(value)
end
end # API
end # Config
end # Vedeu