vedeu 0.2.0 → 0.2.1

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

@@ -64,13 +64,13 @@ module Vedeu
     attr_reader :colour
 
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def no_colour?
       colour.nil? || colour.to_s.empty?
     end
 
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def named?
       colour.is_a?(Symbol) && valid_name?
     end
@@ -82,13 +82,13 @@ module Vedeu
     end
 
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def valid_name?
       codes.keys.include?(colour)
     end
 
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def numbered?
       colour.is_a?(Fixnum) && valid_range?
     end
@@ -100,13 +100,13 @@ module Vedeu
     end
 
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def valid_range?
       colour >= 0 && colour <= 255
     end
 
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def rgb?
       colour.is_a?(String) && valid_rgb?
     end
@@ -118,7 +118,7 @@ module Vedeu
     end
 
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def valid_rgb?
       !!(colour =~ /^#([A-Fa-f0-9]{6})$/)
     end

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

@@ -6,7 +6,7 @@ module Vedeu
   # @api private
   module Presentation
 
-    # Returns the colour attributes of the receiving class.
+    # Returns the colour and style attributes of the receiving class.
     #
     # @return [Hash]
     def view_attributes
@@ -45,18 +45,28 @@ module Vedeu
 
     private
 
+    # Renders the colour attributes of the receiver, yields (to then render the
+    # the styles) and once returned, attempts to set the colours back to the
+    # those of the receiver's parent.
+    #
     # @api private
     # @return [String]
     def render_colour(&block)
       [ colour.to_s, yield, parent_colour ].join
     end
 
+    # Renders the style attributes of the receiver, yields (to then render the
+    # next model, or finally, the content) and once returned, attempts to set
+    # the colours back to those of the receiver's parent.
+    #
     # @api private
     # @return [String]
     def render_style(&block)
       [ style.to_s, yield, parent_style ].join
     end
 
+    # Returns the parent colour as an escape sequence if set.
+    #
     # @api private
     # @return [String]
     def parent_colour
@@ -65,6 +75,7 @@ module Vedeu
       Colour.new(parent[:colour]).to_s
     end
 
+    # Returns the parent style as an escape sequence if set.
     # @api private
     # @return [String]
     def parent_style

data/lib/vedeu/models/geometry.rb

@@ -3,13 +3,15 @@ module Vedeu
   # Calculates and provides interface geometry determined by both the client's
   # requirements and the terminal's current viewing area.
   #
+  # With terminal geometry, the origin is top-left, y = 1, x = 1.
+  #
   # @api private
   class Geometry
 
     # @return [Hash]
     attr_reader :attributes
 
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     attr_reader :centred
 
     # @return [Fixnum]
@@ -166,6 +168,8 @@ module Vedeu
       left - value
     end
 
+    # Returns a fixed or dynamic value depending on the value of {#top}.
+    #
     # @return [Fixnum]
     def bottom
       top + height

data/lib/vedeu/models/interface.rb

@@ -17,6 +17,8 @@ module Vedeu
 
     attr_reader :attributes, :delay, :group, :name, :parent
 
+    # Builds up a new Interface object and returns the attributes.
+    #
     # @param  attributes [Hash]
     # @param  block [Proc]
     # @return [Hash]
@@ -58,9 +60,7 @@ module Vedeu
     def define(&block)
       instance_eval(&block) if block_given?
 
-      validate_attributes!
-
-      Vedeu::Buffers.create(attributes)
+      Registrar.record(attributes)
 
       self
     end
@@ -69,9 +69,11 @@ module Vedeu
     #
     # @return [Array]
     def lines
-      @lines ||= Line.coercer(attributes[:lines], parent)
+      @lines ||= Line.coercer(attributes[:lines])
     end
 
+    # Returns the position and size of the interface.
+    #
     # @return [Geometry]
     def geometry
       @geometry ||= Geometry.new(attributes[:geometry])
@@ -88,22 +90,6 @@ module Vedeu
       end
     end
 
-    # @return [String]
-    def to_s
-      Render.call(self)
-    end
-
-    # @param options [Hash]
-    # @return [String]
-    def render(options = {})
-      Render.call(self, options)
-    end
-
-    # @return [String]
-    def clear
-      Clear.call(self)
-    end
-
     private
 
     # The default values for a new instance of Interface.
@@ -124,33 +110,6 @@ module Vedeu
       }
     end
 
-    # @api private
-    # @return [TrueClass|FalseClass]
-    def validate_attributes!
-      unless defined_value?(attributes[:name])
-        fail InvalidSyntax, 'Interfaces and views must have a `name`.'
-      end
-    end
-
-    # @api private
-    # @return [String]
-    def out_of_bounds(name)
-      "Note: For this terminal, the value of '#{name}' may lead to content " \
-      "that is outside the viewable area."
-    end
-
-    # @api private
-    # @return [TrueClass|FalseClass]
-    def y_out_of_bounds?(value)
-      value < 1 || value > Terminal.height
-    end
-
-    # @api private
-    # @return [TrueClass|FalseClass]
-    def x_out_of_bounds?(value)
-      value < 1 || value > Terminal.width
-    end
-
     # @api private
     # @return []
     def method_missing(method, *args, &block)

data/lib/vedeu/models/keymap.rb

@@ -0,0 +1,66 @@
+module Vedeu
+
+  # A Keymap is the binding of a keypress to one or more interfaces; or globally
+  # to perform a client application defined action.
+  class Keymap
+
+    include Common
+
+    attr_reader :attributes
+
+    # Define a keymap for an interface or interfaces to perform an action when
+    # a key is pressed whilst an aforementioned interface is in focus.
+    #
+    # @param attributes [Hash]
+    # @param block [Proc]
+    # @return [Keymap]
+    def self.define(attributes = {}, &block)
+      new(attributes).define(&block)
+    end
+
+    # Instantiate a new instance of the Keymap model.
+    #
+    # @param attributes [Hash]
+    # @return [Keymap]
+    def initialize(attributes = {})
+      @attributes = defaults.merge!(attributes)
+    end
+
+    # Adds the attributes to the Keymaps repository.
+    #
+    # @param block [Proc]
+    # @return [Interface]
+    def define(&block)
+      if block_given?
+        @self_before_instance_eval = eval('self', block.binding)
+
+        instance_eval(&block)
+      end
+
+      Keymaps.add(attributes)
+
+      self
+    end
+
+    private
+
+    # The default attributes of the Keymap model.
+    #
+    # @api private
+    # @return [Hash]
+    def defaults
+      {
+        interfaces: [], # the interface(s) which will respond to the keypress(es)
+        keys: [], # the keypress/action pairs for this keymap
+      }
+    end
+
+    # @api private
+    # @return []
+    def method_missing(method, *args, &block)
+      @self_before_instance_eval.send(method, *args, &block)
+    end
+
+  end
+
+end

data/lib/vedeu/models/line.rb

@@ -10,6 +10,8 @@ module Vedeu
 
     attr_reader :attributes, :parent
 
+    # Builds up a new Line object and returns the attributes.
+    #
     # @param attributes [Hash]
     # @param block [Proc]
     # @return [Hash]
@@ -37,7 +39,7 @@ module Vedeu
     #
     # @return [Array]
     def streams
-      @streams ||= Stream.coercer(attributes[:streams], parent)
+      @streams ||= Stream.coercer(attributes[:streams])
     end
 
     private

data/lib/vedeu/models/stream.rb

@@ -10,6 +10,8 @@ module Vedeu
 
     attr_reader :attributes, :align, :text, :width, :parent
 
+    # Builds up a new Stream object and returns the attributes.
+    #
     # @param attributes [Hash]
     # @param block [Proc]
     # @return [Hash]
@@ -38,12 +40,17 @@ module Vedeu
 
     private
 
+    # Returns the text aligned if a width was set, otherwise just the text.
+    #
     # @api private
     # @return [String]
     def data
       width? ? aligned : text
     end
 
+    # Returns an aligned string if the string is shorter than the specified
+    # width; the excess area being padded by spaces.
+    #
     # @api private
     # @return [String]
     def aligned
@@ -54,8 +61,10 @@ module Vedeu
       end
     end
 
+    # Returns a boolean to indicate whether this stream has a width set.
+    #
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     def width?
       !!width
     end

data/lib/vedeu/models/style.rb

@@ -6,7 +6,7 @@ module Vedeu
 
     include Vedeu::Common
 
-    attr_reader :values
+    attr_reader :attributes, :values
 
     # Return a new instance of Style.
     #
@@ -16,6 +16,15 @@ module Vedeu
       @values = values
     end
 
+    # Return an attributes hash for this class.
+    #
+    # @return [Hash]
+    def attributes
+      {
+        style: values
+      }
+    end
+
     # Return the terminal escape sequences for the values provided.
     #
     # @return [String]

data/lib/vedeu/output/compositor.rb

@@ -34,6 +34,9 @@ module Vedeu
     # @return [String]
     attr_reader :name
 
+    # Renders the buffer unless empty, otherwise clears the area which the
+    # interface occupies.
+    #
     # @api private
     # @return [String]
     def view

data/lib/vedeu/output/refresh.rb

@@ -8,22 +8,6 @@ module Vedeu
     include Vedeu::Common
     extend self
 
-    # Add a refresh event for the interface.
-    #
-    # @param attributes [Hash]
-    # @return [TrueClass|FalseClass]
-    def add_interface(attributes)
-      register_by_name(attributes[:name], attributes[:delay])
-    end
-
-    # Add a refresh event for the group.
-    #
-    # @param attributes [Hash]
-    # @return [TrueClass|FalseClass]
-    def add_group(attributes)
-      register_by_group(attributes[:group], attributes[:delay])
-    end
-
     # Refresh all registered interfaces.
     #
     # @return [Array]
@@ -55,75 +39,33 @@ module Vedeu
       Vedeu::Compositor.render(name)
     end
 
-    private
-
-    # Register a refresh event for an interface by name. When the event is
-    # called, the interface with this name will be refreshed.
+    # Register a refresh event for an interface or group of interfaces by name.
+    # When the event is called, the interface, or all interfaces belonging to
+    # the group with this name will be refreshed.
     #
     # @api private
-    # @param name  [String] The name of the interface to be refreshed.
-    # @param delay [Float]  The throttle for how often this interface can be
-    #   refreshed.
-    # @return []
-    def register_by_name(name, delay)
-      return false unless defined_value?(name)
-      return false if event_registered?(event_name(name))
+    # @param type [Symbol]
+    # @param name [String]
+    # @param delay [Float]
+    # @return [Boolean]
+    def register_event(type, name, delay = 0.0)
+      event = if type == :by_group
+        "_refresh_group_#{name}_".to_sym
 
-      Vedeu.event(event_name(name), { delay: delay }) do
-        Vedeu::Refresh.by_name(name)
-      end
+      else
+        "_refresh_#{name}_".to_sym
 
-      true
-    end
+      end
 
-    # Register a refresh event for a group of interfaces by name. When the event
-    # is called, all interfaces belonging to the group with this name will be
-    # refreshed.
-    #
-    # @api private
-    # @param name  [String] The name of the group to be refreshed.
-    # @param delay [Float]  The throttle for how often this group can be
-    #   refreshed.
-    # @return []
-    def register_by_group(name, delay)
-      return false unless defined_value?(name)
-      return false if event_registered?(group_event_name(name))
+      return false if Vedeu.events.registered?(event)
 
-      Vedeu.event(group_event_name(name), { delay: delay }) do
-        Vedeu::Refresh.by_group(name)
+      Vedeu.event(event, { delay: delay }) do
+        Vedeu::Refresh.send(type, name)
       end
 
       true
     end
 
-    # Returns the event name for refreshing the named interface.
-    #
-    # @api private
-    # @param name [String] The name of the interface.
-    # @return [Symbol]
-    def event_name(name)
-      "_refresh_#{name}_".to_sym
-    end
-
-    # Returns the event name for refreshing the named group of interfaces.
-    #
-    # @api private
-    # @param name [String] The name of the group.
-    # @return [Symbol]
-    def group_event_name(name)
-      "_refresh_group_#{name}_".to_sym
-    end
-
-    # Returns a boolean indicating that an event by name has already been
-    # registered.
-    #
-    # @api private
-    # @param name [Symbol] The event name to check.
-    # @return [TrueClass|FalseClass]
-    def event_registered?(name)
-      Vedeu.events.registered?(name)
-    end
-
   end
 
 end