vedeu 0.1.17 → 0.1.18

data/lib/vedeu/api/line.rb

@@ -5,6 +5,7 @@ module Vedeu
 
       # Define a stream (a subset of a line).
       #
+      # @api public
       # @param block [Proc] Block contains directives relating to API::Stream.
       #
       # @example
@@ -18,6 +19,8 @@ module Vedeu
       #
       # @return [Array]
       def stream(&block)
+        fail InvalidSyntax, '`stream` requires a block.' unless block_given?
+
         attributes[:streams] << API::Stream.build(&block)
       end
 
@@ -25,6 +28,7 @@ module Vedeu
       # attributes for this line but is useful for adding lines straight into
       # the interface.
       #
+      # @api public
       # @param value [String]
       #
       # @example
@@ -37,6 +41,7 @@ module Vedeu
         attributes[:streams] << { text: value }
       end
 
+      # @api public
       # @param value [String]
       # @param block [Proc]
       #
@@ -53,6 +58,7 @@ module Vedeu
                                 }, &block)
       end
 
+      # @api public
       # @param value [String]
       # @param block [Proc]
       #

data/lib/vedeu/api/stream.rb

@@ -6,6 +6,7 @@ module Vedeu
       # Specify the alignment of the stream within the line. Useful in
       # combination with #width to provide simple formatting effects.
       #
+      # @api public
       # @param value [Symbol] `:left`, `:centre` and `right` are valid values
       #   and will align accordingly. If not value is specified, the stream will
       #   left align.
@@ -18,11 +19,17 @@ module Vedeu
       #
       # @return [Symbol]
       def align(value)
-        attributes[:align] = value
+        unless [:left, :right, :centre].include?(value.to_sym)
+          fail InvalidSyntax, '`align` requires a value of `:left`, `:right` ' \
+                              'or `centre`.'
+        end
+
+        attributes[:align] = value.to_sym
       end
 
       # Add textual data to the stream via this method.
       #
+      # @api public
       # @param value [String] The text to be added to the stream. If the length
       #   of the text is greater than the interface's width, it will be
       #   truncated and ellipsized.
@@ -42,6 +49,7 @@ module Vedeu
       # stream. Useful in combination with #align to provide simple formatting
       # effects.
       #
+      # @api public
       # @param value [Fixnum] The width in characters.
       #
       # @example

data/lib/vedeu/application.rb

@@ -1,22 +1,32 @@
 module Vedeu
   class Application
+    class << self
 
-    # :nocov:
-    # @param options [Hash]
-    # @return []
-    def self.start(options = {})
-      new(options).start
-    end
+      # @return []
+      def start
+        new.start
+      end
+      alias_method :restart, :start
 
-    # @param options [Hash]
-    # @return [Application]
-    def initialize(options = {})
-      @options = options
     end
 
+    # @return [Application]
+    def initialize; end
+
+    # Starts the application!
+    # - A new terminal screen is opened (or rather the current terminal is
+    #   requested into either :raw or :cooked mode).
+    # - The cursor visibility is then set dependent on this mode. In :raw mode,
+    #   the cursor is hidden.
+    # - The `:_initialize_` event is triggered. Vedeu does not handle this
+    #   event; the client application may treat this event as Vedeu signalling
+    #   that it is now ready.
+    # - We enter into the main sequence where the application will either run
+    #   once or continuous, interactively or standalone.
+    #
     # @return []
     def start
-      Terminal.open(mode) do
+      Terminal.open do
         Terminal.set_cursor_mode
 
         Vedeu.events.trigger(:_initialize_)
@@ -27,63 +37,41 @@ module Vedeu
 
     private
 
-    attr_reader :options
-
+    # @api private
+    # @return []
     def runner
-      if interactive?
-        interactive { yield }
+      if Configuration.once?
+        yield
 
       else
-        run_once    { yield }
+        run_many { yield }
 
       end
     end
 
+    # @api private
+    # @return []
     def main_sequence
-      Input.capture
-    end
-
-    def interactive?
-      options.fetch(:interactive)
-    end
-
-    def interactive
-      loop { yield }
-
-    rescue ModeSwitch
-      if Terminal.raw_mode?
-        Application.start({ mode: :cooked })
+      if Configuration.interactive?
+        Input.capture
 
       else
-        Application.start({ mode: :raw })
+        # TODO: What should happen here?
 
       end
     end
 
-    def run_once
-      yield
-    end
-
-    def mode
-      options.fetch(:mode)
-    end
+    # @api private
+    # @return []
+    def run_many
+      loop { yield }
 
-    def debug
-      Vedeu::API::Trace.call if options.fetch(:debug)
-    end
+    rescue ModeSwitch
+      Terminal.switch_mode!
 
-    def options
-      defaults.merge!(@options)
-    end
+      Application.restart
 
-    def defaults
-      {
-        debug:       false,
-        interactive: true,
-        mode:        :raw
-      }
     end
-    # :nocov:
 
   end
 end

data/lib/vedeu/configuration.rb

@@ -1,97 +1,216 @@
 module Vedeu
-  class Configuration
+  module Configuration
+    extend self
 
+    # Parses arguments passed on the command-line or via {Vedeu::Launcher} into
+    # options used by Vedeu to affect certain behaviours.
+    #
     # @param args [Array]
     # @return [Hash]
-    def self.configure(args = [])
-      new(args).configure
-    end
+    def configure(args = [])
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: #{$PROGRAM_NAME} [options]"
 
-    # @return [Hash]
-    def self.options
-      new.options
-    end
+        opts.on('-i', '--interactive',
+                'Run the application in interactive mode (default).') do
+          options[:interactive] = true
+        end
 
-    # @param args [Array]
-    # @return [Configuration]
-    def initialize(args = [])
-      @_options = {}
-      @args     = args
-    end
+        opts.on('-I', '--noninteractive', '--standalone',
+                'Run the application non-interactively; i.e. not requiring ' \
+                'intervention from the user.') do
+          options[:interactive] = false
+        end
 
-    # @return [Hash]
-    def configure
-      parser = OptionParser.new do |opts|
-        opts.banner = "Usage: #{$PROGRAM_NAME} [options]"
+        opts.on('-1', '--run-once',
+                'Run the application loop once.') do
+          options[:once] = true
+        end
 
-        opts.on('-1', '--run-once', 'Run application once.') do
-          _options[:interactive] = false
+        opts.on('-n', '--run-many',
+                'Run the application loop continuously (default).') do
+          options[:once] = false
         end
 
         opts.on('-c', '--cooked', 'Run application in cooked mode.') do
-          _options[:mode] = :cooked
+          options[:terminal_mode] = :cooked
         end
 
         opts.on('-r', '--raw', 'Run application in raw mode (default).') do
-          _options[:mode] = :raw
+          options[:terminal_mode] = :raw
         end
 
         opts.on('-d', '--debug', 'Run application with debugging on.') do
-          _options[:debug] = true
+          options[:debug] = true
+        end
+
+        opts.on('-D', '--trace', 'Run application with debugging on with ' \
+                                 'method and event tracing (noisy!).') do
+          options[:debug] = true
+          options[:trace] = true
         end
 
-        opts.on('-C',
-                '--colour-mode',
-                'Run application in either `16` or `256` colour mode.') do |mode|
-          if ['16', '256'].include?(mode)
-            _options[:colour_mode] = mode
+        opts.on('-C', '--colour-mode [COLOURS]', Integer,
+                'Run application in either `8`, `16` or `256` colour ' \
+                'mode.') do |colours|
+          if [8, 16, 256].include?(colours)
+            options[:colour_mode] = colours
 
           else
-            exit
+            options[:colour_mode] = 8
 
           end
         end
       end
       parser.parse!(args)
 
-      _options
+      options
+    end
+
+    # Returns the chosen colour mode.
+    #
+    # @return [Fixnum]
+    def colour_mode
+      options[:colour_mode]
+    end
+
+    # Returns whether debugging is enabled or disabled. Default is false;
+    # meaning nothing apart from warnings are written to the log file.
+    #
+    # @return [TrueClass|FalseClass]
+    def debug?
+      options[:debug]
+    end
+    alias_method :debug, :debug?
+
+    # Returns whether the application is interactive (required user input) or
+    # standalone (will run until terminates of natural causes.) Default is true;
+    # meaning the application will require user input.
+    #
+    # @return [TrueClass|FalseClass]
+    def interactive?
+      options[:interactive]
+    end
+    alias_method :interactive, :interactive?
+
+    # Returns whether the application will run through its main loop once or
+    # not. Default is false; meaning the application will loop forever or until
+    # terminated by the user.
+    #
+    # @return [TrueClass|FalseClass]
+    def once?
+      options[:once]
+    end
+    alias_method :once, :once?
+
+    # Returns the terminal mode for the application. Default is `:raw`.
+    #
+    # @return [Symbol]
+    def terminal_mode
+      options[:terminal_mode]
     end
 
+    # Returns whether tracing is enabled or disabled. Tracing is very noisy in
+    # the log file (logging method calls and events trigger). Default is false;
+    # meaning tracing is disabled.
+    #
+    # @return [TrueClass|FalseClass]
+    def trace?
+      options[:trace]
+    end
+    alias_method :trace, :trace?
+
+    # Returns all the options current configured.
+    #
     # @return [Hash]
     def options
-      @options ||= defaults.merge!(@_options)
+      @options ||= defaults
     end
 
-    private
+    # Resets all options to Vedeu defaults.
+    #
+    # @return [Hash]
+    def reset
+      @options = defaults
+    end
 
-    attr_accessor :args, :_options
+    private
 
+    # The Vedeu default options, which of course are influenced by enviroment
+    # variables also.
+    #
+    # @api private
+    # @return [Hash]
     def defaults
       {
-        colour_mode: detect_colour_mode,
-        debug:       false,
-        interactive: true,
-        mode:        :raw
+        colour_mode:   detect_colour_mode,
+        debug:         detect_debug_mode,
+        interactive:   true,
+        once:          false,
+        terminal_mode: :raw,  #cooked
+        trace:         detect_trace_mode,
       }
     end
 
+    # Determine the terminal colour mode via enviroment variables, or be
+    # optimistic and settle for 256 colours.
+    #
+    # @api private
+    # @return [Fixnum]
     def detect_colour_mode
-      if ENV['VEDEUTERM']
-        case ENV['VEDEUTERM']
+      if ENV['VEDEU_TERM']
+        case ENV['VEDEU_TERM']
         when /-256color$/  then 256
         when /-truecolor$/ then 16777216
-        else
-          256
+        else 256
         end
 
-      else
+      elsif ENV['TERM']
         case ENV['TERM']
         when /-256color$/, 'xterm' then 256
         when /-color$/, 'rxvt'     then 16
-        else
-          256
+        else 256
         end
 
+      else
+        256
+
+      end
+    end
+
+    # Determine the debug mode via an enviroment variable.
+    #
+    # @api private
+    # @return [TrueClass|FalseClass]
+    def detect_debug_mode
+      if ENV['VEDEU_DEBUG']
+        case ENV['VEDEU_DEBUG']
+        when 'true'  then true
+        when 'false' then false
+        else false
+        end
+
+      else
+        false
+
+      end
+    end
+
+    # Determine the trace mode via an environment variable.
+    #
+    # @api private
+    # @return [TrueClass|FalseClass]
+    def detect_trace_mode
+      if ENV['VEDEU_TRACE']
+        case ENV['VEDEU_TRACE']
+        when 'true'  then true
+        when 'false' then false
+        else false
+        end
+
+      else
+        false
+
       end
     end