vedeu 0.1.18 → 0.1.19

data/lib/vedeu/models/geometry.rb

@@ -1,10 +1,14 @@
 module Vedeu
+
+  # Calculates and provides interface geometry determined by both the client's
+  # requirements and the terminal's current viewing area.
+  #
+  # @api private
   class Geometry
 
     attr_reader :attributes, :centred, :height, :width
 
-    # Calculate and provide interface geometry determined by both the client's
-    # requirements and the terminal's current viewing area.
+    # Returns a new instance of Geometry.
     #
     # @param attributes [Hash]
     # @return [Geometry]
@@ -55,7 +59,8 @@ module Vedeu
     # @return [Fixnum]
     def viewport_width
       if (x + width) > Terminal.width
-        width - ((x + width) - Terminal.width)
+        new_width = width - ((x + width) - Terminal.width)
+        return new_width < 1 ? 1 : new_width
 
       else
         width
@@ -75,7 +80,8 @@ module Vedeu
     # @return [Fixnum]
     def viewport_height
       if (y + height) > Terminal.height
-        height - ((y + height) - Terminal.height)
+        new_height = height - ((y + height) - Terminal.height)
+        return new_height < 1 ? 1 : new_height
 
       else
         height
@@ -94,7 +100,7 @@ module Vedeu
 
     # Returns a fixed or dynamic value depending on whether the interface is
     # centred or not.
-    # 
+    #
     # @return [Fixnum]
     def top
       if centred
@@ -209,6 +215,8 @@ module Vedeu
       (left..right).to_a
     end
 
+    # The default geometry of an interface- full screen.
+    #
     # @return [Hash]
     def defaults
       {

data/lib/vedeu/models/interface.rb

@@ -1,16 +1,21 @@
 module Vedeu
+
+  # An Interface represents a portion of the terminal defined by
+  # {Vedeu::Geometry}. It is a container for {Vedeu::Line} and {Vedeu::Stream}
+  # objects.
   class Interface
+
     include Coercions
+    include Common
     include Presentation
 
     extend Forwardable
 
-    def_delegators :geometry, :north, :east, :south, :west,
-                              :top, :right, :bottom, :left,
-                              :width, :height, :origin,
+    def_delegators :geometry, :north, :east, :south, :west, :top, :right,
+                              :bottom, :left, :width, :height, :origin,
                               :viewport_width, :viewport_height
 
-    attr_reader :attributes, :delay, :group, :name
+    attr_reader :attributes, :delay, :group, :name, :parent
 
     # @param  attributes [Hash]
     # @param  block [Proc]
@@ -27,6 +32,8 @@ module Vedeu
       new(attributes).define(&block)
     end
 
+    # Return a new instance of Interface.
+    #
     # @param  attributes [Hash]
     # @param  block [Proc]
     # @return [Interface]
@@ -36,6 +43,7 @@ module Vedeu
       @name  = @attributes[:name]
       @group = @attributes[:group]
       @delay = @attributes[:delay]
+      @parent = @attributes[:parent]
 
       if block_given?
         @self_before_instance_eval = eval('self', block.binding)
@@ -46,31 +54,22 @@ module Vedeu
 
     # @see Vedeu::API#interface
     # @param block [Proc]
-    #
-    # @example
-    #   TODO
-    #
-    # @return []
+    # @return [Interface]
     def define(&block)
       instance_eval(&block) if block_given?
 
-      if attributes[:name].nil? || attributes[:name].empty?
-        fail InvalidSyntax, 'Interfaces and views must have a `name`.'
-      end
+      validate_attributes!
 
       Vedeu::Buffers.create(attributes)
 
-      Vedeu.event("_refresh_#{attributes[:name]}_".to_sym,
-                  { delay: attributes[:delay] }) do
-        Vedeu::Buffers.refresh(attributes[:name])
-      end
-
       self
     end
 
+    # Returns a collection of lines associated with this interface.
+    #
     # @return [Array]
     def lines
-      @lines ||= Line.coercer(attributes[:lines])
+      @lines ||= Line.coercer(attributes[:lines], parent)
     end
 
     # @return [Geometry]
@@ -94,6 +93,12 @@ module Vedeu
       Render.call(self)
     end
 
+    # @param options [Hash]
+    # @return [String]
+    def render(options = {})
+      Render.call(self, options)
+    end
+
     # @return [String]
     def clear
       Clear.call(self)
@@ -101,6 +106,8 @@ module Vedeu
 
     private
 
+    # The default values for a new instance of Interface.
+    #
     # @api private
     # @return [Hash]
     def defaults
@@ -112,10 +119,19 @@ module Vedeu
         style:    '',
         geometry: {},
         cursor:   true,
-        delay:    0.0
+        delay:    0.0,
+        parent:   nil,
       }
     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)

data/lib/vedeu/models/line.rb

@@ -1,9 +1,14 @@
 module Vedeu
+
+  # A Line represents a single row of the terminal. It is a container for
+  # {Vedeu::Stream} objects. A line's width is determined by the
+  # {Vedeu::Interface} it belongs to.
   class Line
+
     include Coercions
     include Presentation
 
-    attr_reader :attributes
+    attr_reader :attributes, :parent
 
     # @param attributes [Hash]
     # @param block [Proc]
@@ -12,11 +17,14 @@ module Vedeu
       new(attributes, &block).attributes
     end
 
+    # Returns a new instance of Line.
+    #
     # @param attributes [Hash]
     # @param block [Proc]
     # @return [Line]
     def initialize(attributes = {}, &block)
       @attributes = defaults.merge!(attributes)
+      @parent     = @attributes[:parent]
 
       if block_given?
         @self_before_instance_eval = eval('self', block.binding)
@@ -25,25 +33,33 @@ module Vedeu
       end
     end
 
+    # Returns a collection of streams associated with this line.
+    #
     # @return [Array]
     def streams
-      @streams ||= Stream.coercer(attributes[:streams])
-    end
-
-    # @return [String]
-    def to_s
-      [ colour, style, streams ].join
+      @streams ||= Stream.coercer(attributes[:streams], parent)
     end
 
     private
 
+    # Convenience method to provide Presentation with a consistent interface.
+    #
+    # @api private
+    # @return [Array]
+    def data
+      streams
+    end
+
+    # The default values for a new instance of Line.
+    #
     # @api private
     # @return [Hash]
     def defaults
       {
         colour:  {},
         streams: [],
-        style:   []
+        style:   [],
+        parent:  nil,
       }
     end
 

data/lib/vedeu/models/stream.rb

@@ -1,9 +1,14 @@
 module Vedeu
+
+  # A Stream can represent a character or collection of characters as part of a
+  # {Vedeu::Line} which you wish to colour and style independently of the other
+  # characters in that line.
   class Stream
+
     include Coercions
     include Presentation
 
-    attr_reader :attributes, :align, :text, :width
+    attr_reader :attributes, :align, :text, :width, :parent
 
     # @param attributes [Hash]
     # @param block [Proc]
@@ -12,6 +17,8 @@ module Vedeu
       new(attributes, &block).attributes
     end
 
+    # Returns a new instance of Stream.
+    #
     # @param attributes [Hash]
     # @param block [Proc]
     # @return [Stream]
@@ -20,6 +27,7 @@ module Vedeu
       @align      = @attributes[:align]
       @text       = @attributes[:text]
       @width      = @attributes[:width]
+      @parent     = @attributes[:parent]
 
       if block_given?
         @self_before_instance_eval = eval('self', block.binding)
@@ -28,11 +36,6 @@ module Vedeu
       end
     end
 
-    # @return [String]
-    def to_s
-      [ colour, style, data ].join
-    end
-
     private
 
     # @api private
@@ -57,6 +60,8 @@ module Vedeu
       !!width
     end
 
+    # The default values for a new instance of Stream.
+    #
     # @api private
     # @return [Hash]
     def defaults
@@ -65,7 +70,8 @@ module Vedeu
         style:  [],
         text:   '',
         width:  nil,
-        align:  :left
+        align:  :left,
+        parent: nil,
       }
     end
 

data/lib/vedeu/models/style.rb

@@ -1,14 +1,23 @@
 module Vedeu
+
+  # Converts the style value or value collection into a terminal escape
+  # sequence. Unrecognised values are discarded- an empty string is returned.
   class Style
 
+    include Vedeu::Common
+
     attr_reader :values
 
-    # @param values [String|Array]
+    # Return a new instance of Style.
+    #
+    # @param values [String|Array] The style value or values collection.
     # @return [Style]
     def initialize(values)
       @values = values
     end
 
+    # Return the terminal escape sequences for the values provided.
+    #
     # @return [String]
     def to_s
       escape_sequences
@@ -16,16 +25,17 @@ module Vedeu
 
     private
 
+    # Converts the style or styles into terminal escape sequences.
+    #
     # @api private
     # @return [String]
     def escape_sequences
-      @_sequences ||= if values.nil? || values.empty?
-        ''
+      return '' unless defined_value?(values)
 
-      else
-        Array(values).flatten.map { |value| Esc.string(value) }.join
-
-      end
+      @_sequences ||= Array(values).flatten.map do |value|
+        Esc.string(value)
+      end.join
     end
+
   end
 end

data/lib/vedeu/{support → output}/clear.rb

@@ -1,18 +1,32 @@
 module Vedeu
+
+  # Clears all the character data for the area defined by an interface. This
+  # class is called every time an interface is rendered to prepare the area
+  # for new data.
+  #
+  # @api private
   class Clear
 
+    # Blanks the area defined by the interface.
+    #
     # @param interface [Interface]
     # @return [String]
     def self.call(interface)
       new(interface).clear
     end
 
+    # Returns a new instance of Clear.
+    #
     # @param interface [Interface]
     # @return [Clear]
     def initialize(interface)
       @interface = interface
     end
 
+    # For each visible line of the interface, set the foreground and background
+    # colours to those specified when the interface was defined, then starting
+    # write space characters over the area which the interface occupies.
+    #
     # @return [String]
     def clear
       rows.inject([colours]) do |line, index|

data/lib/vedeu/output/compositor.rb

@@ -0,0 +1,77 @@
+module Vedeu
+
+  # Combines stored interface layout/geometry with an interface view/buffer
+  # to create a single view to be sent to the terminal for output.
+  #
+  # @api private
+  class Compositor
+
+    include Common
+
+    # @param name [String] The name of the interface/buffer.
+    # @return [Compositor]
+    def self.render(name)
+      new(name).render
+    end
+
+    # Initialize a new Compositor.
+    #
+    # @param name [String] The name of the interface/buffer.
+    # @return [Compositor]
+    def initialize(name)
+      @name = name
+    end
+
+    # Send the view to the terminal.
+    #
+    # @return [Array]
+    def render
+      Terminal.output(view)
+    end
+
+    private
+
+    attr_reader :name
+
+    # @api private
+    # @return [String]
+    def view
+      if buffer
+        Render.call(Interface.new(new_interface))
+
+      else
+        Clear.call(Interface.new(interface))
+
+      end
+    end
+
+    # Combine the buffer attributes with the interface attributes. Buffer
+    # presentation attributes will override interface defaults.
+    #
+    # @api private
+    # @return [Hash]
+    def new_interface
+      combined = interface
+      combined[:lines]  = buffer[:lines]
+      combined[:colour] = buffer[:colour] if defined_value?(buffer[:colour])
+      combined[:style]  = buffer[:style]  if defined_value?(buffer[:style])
+      combined
+    end
+
+    # Returns the attributes of the named interface (layout).
+    #
+    # @api private
+    # @return [Hash]
+    def interface
+      @_interface ||= Vedeu::Interfaces.find(name)
+    end
+
+    # Returns the attributes of the latest buffer (view).
+    #
+    # @api private
+    # @return [Hash]
+    def buffer
+      @_buffer ||= Vedeu::Buffers.latest(name)
+    end
+  end
+end