vedeu 0.2.1 → 0.2.2

data/lib/vedeu/configuration/cli.rb

@@ -0,0 +1,110 @@
+module Vedeu
+
+  module Configuration
+
+    # The Configuration::CLI class parses command-line arguments using
+    # OptionParser into options used by Vedeu to affect certain behaviours.
+    #
+    # @api private
+    class CLI
+
+      # Configure Vedeu via command-line arguments. Options set here via
+      # arguments override the client application configuration set via
+      # {Vedeu::API#configure}.
+      #
+      # @param args [Array]
+      # @return [Hash]
+      def self.configure(args = [])
+        new(args = []).configuration
+      end
+
+      # Returns an instance of Configuration::CLI.
+      #
+      # @param args [Array]
+      # @return [Configuration::CLI]
+      def initialize(args = [])
+        @args = args
+      end
+
+      # Returns the configuration options set up by parsing the command-line
+      # arguments passed to the client application.
+      #
+      # @return [Hash]
+      def configuration
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: #{$PROGRAM_NAME} [options]"
+
+          opts.on('-i', '--interactive',
+                  'Run the application in interactive mode (default).') do
+            options[:interactive] = true
+          end
+
+          opts.on('-I', '--noninteractive', '--standalone',
+                  'Run the application non-interactively; i.e. not requiring ' \
+                  'intervention from the user.') do
+            options[:interactive] = false
+          end
+
+          opts.on('-1', '--run-once',
+                  'Run the application loop once.') do
+            options[:once] = true
+          end
+
+          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[:terminal_mode] = :cooked
+          end
+
+          opts.on('-r', '--raw', 'Run application in raw mode (default).') do
+            options[:terminal_mode] = :raw
+          end
+
+          opts.on('-d', '--debug', 'Run application with debugging on.') do
+            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 [COLOURS]', Integer,
+                  'Run application in either `8`, `16`, `256` or `16777216` ' \
+                  'colour mode.') do |colours|
+            if [8, 16, 256, 16777216].include?(colours)
+              options[:colour_mode] = colours
+
+            else
+              options[:colour_mode] = 8
+
+            end
+          end
+        end
+        parser.parse!(args)
+
+        options
+      end
+
+      private
+
+      attr_reader :args
+
+      # Returns the options set via command-line arguments parsed by
+      # OptionParser, or an empty Hash if none were set or parsed.
+      #
+      # @api private
+      # @return [Hash]
+      def options
+        @_options ||= {}
+      end
+
+    end
+
+  end
+
+end

data/lib/vedeu/{configuration.rb → configuration/configuration.rb}

@@ -1,74 +1,30 @@
 module Vedeu
 
-  # Allows the customisation of Vedeu's behaviour through command-line
-  # arguments.
+  # Allows the customisation of Vedeu's behaviour through the configuration API
+  # or command-line arguments.
+
+  # Provides access to Vedeu's configuration, which was set with sensible
+  # defaults (influenced by environment variables), overridden by client
+  # application settings (via the configuration API), or any command-line
+  # arguments provided.
   #
-  # @api public
+  # @api private
   module Configuration
 
     extend self
 
-    # Parses arguments passed on the command-line or via {Vedeu::Launcher} into
-    # options used by Vedeu to affect certain behaviours.
+    # Configure Vedeu with sensible defaults. If the client application sets
+    # options, override the defaults with those, and if command-line arguments
+    # are provided at application invocation, override any options with the
+    # arguments provided.
     #
     # @param args [Array]
+    # @param block [Proc]
     # @return [Hash]
-    def configure(args = [])
-      parser = OptionParser.new do |opts|
-        opts.banner = "Usage: #{$PROGRAM_NAME} [options]"
-
-        opts.on('-i', '--interactive',
-                'Run the application in interactive mode (default).') do
-          options[:interactive] = true
-        end
-
-        opts.on('-I', '--noninteractive', '--standalone',
-                'Run the application non-interactively; i.e. not requiring ' \
-                'intervention from the user.') do
-          options[:interactive] = false
-        end
-
-        opts.on('-1', '--run-once',
-                'Run the application loop once.') do
-          options[:once] = true
-        end
-
-        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[:terminal_mode] = :cooked
-        end
-
-        opts.on('-r', '--raw', 'Run application in raw mode (default).') do
-          options[:terminal_mode] = :raw
-        end
-
-        opts.on('-d', '--debug', 'Run application with debugging on.') do
-          options[:debug] = true
-        end
+    def configure(args = [], &block)
+      options.merge!(API.configure(&block)) if block_given?
 
-        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 [COLOURS]', Integer,
-                'Run application in either `8`, `16`, `256` or `16777216` ' \
-                'colour mode.') do |colours|
-          if [8, 16, 256, 16777216].include?(colours)
-            options[:colour_mode] = colours
-
-          else
-            options[:colour_mode] = 8
-
-          end
-        end
-      end
-      parser.parse!(args)
+      options.merge!(CLI.configure(args)) if args.any?
 
       options
     end
@@ -133,23 +89,37 @@ module Vedeu
     end
     alias_method :trace, :trace?
 
-    # Returns all the options current configured.
+    # Resets all options to Vedeu defaults.
     #
     # @return [Hash]
-    def options
-      @options ||= defaults
+    def reset
+      @options = defaults
     end
 
-    # Resets all options to Vedeu defaults.
+    # Vedeu's default system keys. Use {#system_keys}.
     #
+    # @api private
     # @return [Hash]
-    def reset
-      @options = defaults
+    def default_system_keys
+      {
+        exit:        'q',
+        focus_next:  :tab,
+        focus_prev:  :shift_tab,
+        mode_switch: :escape,
+      }
     end
 
     private
 
-    # The Vedeu default options, which of course are influenced by enviroment
+    # Returns all the options current configured.
+    #
+    # @api private
+    # @return [Hash]
+    def options
+      @options ||= defaults
+    end
+
+    # The Vedeu default options, which of course are influenced by environment
     # variables also.
     #
     # @api private
@@ -161,28 +131,20 @@ module Vedeu
         interactive:   true,
         once:          false,
         system_keys:   default_system_keys,
-        terminal_mode: :raw,  #cooked
+        terminal_mode: :raw,
         trace:         detect_trace_mode,
       }
     end
 
-    # Vedeu's system keys.
-    def default_system_keys
-      {
-        exit:        'q',
-        focus_next:  :tab,
-        focus_prev:  :shift_tab,
-        mode_switch: :escape,
-      }
-    end
-
-    # Determine the terminal colour mode via enviroment variables, or be
-    # optimistic and settle for 256 colours.
+    # Attempt to determine the terminal colour mode via environment variables,
+    # or be optimistic and settle for 256 colours.
     #
     # @api private
     # @return [Fixnum]
     # :nocov:
     def detect_colour_mode
+      return 16777216 if ENV['VEDEU_TESTMODE']
+
       if ENV['VEDEU_TERM']
         case ENV['VEDEU_TERM']
         when /-256color$/  then 256
@@ -204,23 +166,17 @@ module Vedeu
     end
     # :nocov:
 
-    # Determine the debug mode via an enviroment variable.
+    # Determine the debug mode via an environment variable.
     #
     # @api private
     # @return [Boolean]
     # :nocov:
     def detect_debug_mode
-      if ENV['VEDEU_DEBUG']
-        case ENV['VEDEU_DEBUG']
-        when 'true'  then true
-        when 'false' then false
-        else false
-        end
+      return false if ENV['VEDEU_TESTMODE']
 
-      else
-        false
+      return true if ENV['VEDEU_DEBUG']
 
-      end
+      false
     end
     # :nocov:
 
@@ -230,17 +186,11 @@ module Vedeu
     # @return [Boolean]
     # :nocov:
     def detect_trace_mode
-      if ENV['VEDEU_TRACE']
-        case ENV['VEDEU_TRACE']
-        when 'true'  then true
-        when 'false' then false
-        else false
-        end
+      return false if ENV['VEDEU_TESTMODE']
 
-      else
-        false
+      return true if ENV['VEDEU_TRACE']
 
-      end
+      false
     end
     # :nocov:
 

data/lib/vedeu/launcher.rb

@@ -48,7 +48,6 @@ module Vedeu
 
     private
 
-    # @return [Array]
     attr_reader :argv
 
   end

data/lib/vedeu/models/attributes/colour_translator.rb

@@ -11,13 +11,14 @@ module Vedeu
   # :black, :red, :green, :yellow, :blue, :magenta, :cyan, :white, :default.
   #
   # When a number between 0 and 255 is provided, Vedeu will use the terminal
-  # colour corresponding with that colour. TODO: Create chart.
+  # colour corresponding with that colour.
   #
   # Finally, when provided a CSS/HTML colour string e.g. '#ff0000', Vedeu will
   # translate that to the 8-bit escape sequence or if you have a capable
   # terminal and the `VEDEU_TERM=xterm-truecolor` environment variable set,
   # a 24-bit representation.
   #
+  # @todo More documentation required (create a fancy chart!)
   # @api private
   class ColourTranslator
 
@@ -60,7 +61,6 @@ module Vedeu
 
     private
 
-    # @return [Fixnum|NilClass|Symbol|String]
     attr_reader :colour
 
     # @api private

data/lib/vedeu/models/colour.rb

@@ -7,7 +7,6 @@ module Vedeu
   # @api private
   class Colour
 
-    # @return [Hash]
     attr_reader :attributes
 
     # Returns a new instance of Colour.

data/lib/vedeu/models/composition.rb

@@ -1,6 +1,8 @@
 module Vedeu
 
   # A composition is a collection of interfaces.
+  #
+  # @api private
   class Composition
 
     attr_reader :attributes
@@ -44,14 +46,6 @@ module Vedeu
       {}
     end
 
-    # Returns the complete escape sequence which this composition renders to.
-    # This is used by {Vedeu::Terminal.output} to draw the view.
-    #
-    # @return [String]
-    def to_s
-      interfaces.map(&:to_s).join
-    end
-
     private
 
     # The default values for a new instance of Composition.

data/lib/vedeu/models/cursor.rb

@@ -0,0 +1,261 @@
+module Vedeu
+
+  # Each interface has its own Cursor which maintains the position and
+  # visibility of the cursor within that interface.
+  #
+  # @api private
+  class Cursor
+
+    extend Forwardable
+
+    def_delegators :geometry, :top, :right, :bottom, :left
+
+    # Provides a new instance of Cursor.
+    #
+    # @param attributes [Hash] The stored attributes for a cursor.
+    # @return [Cursor]
+    def initialize(attributes = {})
+      @attributes = defaults.merge!(attributes)
+
+      @name  = @attributes[:name]
+      @state = @attributes[:state]
+      @x     = @attributes[:x]
+      @y     = @attributes[:y]
+    end
+
+    # Returns an attribute hash for the current position and visibility of the
+    # cursor.
+    #
+    # @return [Hash]
+    def attributes
+      {
+        name:  name,
+        state: state,
+        x:     x,
+        y:     y,
+      }
+    end
+    alias_method :refresh, :attributes
+
+    # Move the cursor up one row.
+    #
+    # @return [Cursor]
+    def move_up
+      unless y == top || y - 1 < top
+        @y -= 1
+      end
+
+      attributes
+    end
+
+    # Move the cursor down one row.
+    #
+    # @return [Cursor]
+    def move_down
+      unless y == bottom || y + 1 >= bottom
+        @y += 1
+      end
+
+      attributes
+    end
+
+    # Move the cursor left one column.
+    #
+    # @return [Cursor]
+    def move_left
+      unless x == left || x - 1 < left
+        @x -= 1
+      end
+
+      attributes
+    end
+
+    # Move the cursor right one column.
+    #
+    # @return [Cursor]
+    def move_right
+      unless x == right || x + 1 >= right
+        @x += 1
+      end
+
+      attributes
+    end
+
+    # Make the cursor visible if it is not already.
+    #
+    # @return [Symbol]
+    def show
+      @state = :show
+
+      attributes
+    end
+
+    # Make the cursor invisible if it is not already.
+    #
+    # @return [Symbol]
+    def hide
+      @state = :hide
+
+      attributes
+    end
+
+    # Toggle the visibility of the cursor.
+    #
+    # @return [Symbol]
+    def toggle
+      if visible?
+        @state = :hide
+
+      else
+        @state = :show
+
+      end
+
+      attributes
+    end
+
+    # Returns an escape sequence to position the cursor and set its visibility.
+    # When passed a block, will position the cursor, yield and return the
+    # original position.
+    #
+    # @param block [Proc]
+    # @return [String]
+    def to_s(&block)
+      if block_given?
+        [ sequence, yield, sequence ].join
+
+      else
+        sequence
+
+      end
+    end
+
+    private
+
+    attr_reader :name, :state
+
+    # Returns the escape sequence to position the cursor and set its visibility.
+    #
+    # @api private
+    # @return [String]
+    def sequence
+      [ position, visibility ].join
+    end
+
+    # Returns the escape sequence to position the cursor.
+    #
+    # @api private
+    # @return [String]
+    def position
+      ["\e[", y, ';', x, 'H'].join
+    end
+
+    # Returns the escape sequence for setting the visibility of the cursor.
+    #
+    # @api private
+    # @return [String]
+    def visibility
+      return Esc.string('show_cursor') if visible?
+
+      Esc.string('hide_cursor')
+    end
+
+    # Return a boolean indicating the visibility of the cursor, invisible if
+    # the state is not defined.
+    #
+    # @api private
+    # @return [Boolean]
+    def visible?
+      return false unless states.include?(state)
+      return false if state == :hide
+
+      true
+    end
+
+    # Returns the y coordinate of the cursor, unless out of range, in which case
+    # sets y to the first row (top) of the interface.
+    #
+    # @api private
+    # @return [Fixnum]
+    def y
+      if y_out_of_range?
+        @y = top
+
+      else
+        @y
+
+      end
+    end
+
+    # Returns the x coordinate of the cursor, unless out of range, in which case
+    # sets x to the first column (left) of the interface.
+    #
+    # @api private
+    # @return [Fixnum]
+    def x
+      if x_out_of_range?
+        @x = left
+
+      else
+        @x
+
+      end
+    end
+
+    # Returns a boolean indicating whether the previous y coordinate is still
+    # inside the interface or terminal.
+    #
+    # @api private
+    # @return [Boolean]
+    def y_out_of_range?
+      @y < top || @y > bottom
+    end
+
+    # Returns a boolean indicating whether the previous x coordinate is still
+    # inside the interface or terminal.
+    #
+    # @api private
+    # @return [Boolean]
+    def x_out_of_range?
+      @x < left || @x > right
+    end
+
+    # Returns the position and size of the interface.
+    #
+    # @api private
+    # @return [Geometry]
+    def geometry
+      @geometry ||= Vedeu::Geometry.new(interface[:geometry])
+    end
+
+    # Returns the attributes of a named interface.
+    #
+    # @api private
+    # @return [Hash]
+    def interface
+      Vedeu::Interfaces.find(name)
+    end
+
+    # The valid visibility states for the cursor.
+    #
+    # @api private
+    # @return [Array]
+    def states
+      [:show, :hide]
+    end
+
+    # The default values for a new instance of Cursor.
+    #
+    # @api private
+    # @return [Hash]
+    def defaults
+      {
+        name:  '',
+        x:     1,
+        y:     1,
+        state: :hide,
+      }
+    end
+  end
+
+end