vedeu 0.2.3 → 0.2.4

data/lib/vedeu/models/offset.rb

@@ -0,0 +1,84 @@
+module Vedeu
+
+  # Offset represents the scroll position of the content for an interface. The
+  # values herein are relative to the geometry of the interface.
+  #
+  # @note (to self) An offset is a position. A cursor resides at a position in
+  #   an interface, ergo we can calculate cursors based from offsets. Also, we
+  #   could rename Offset to Position, then kill Cursor, Cursors, and the old
+  #   Position class.
+  #
+  # @api private
+  class Offset
+
+    attr_reader :name
+
+    # Returns a new instance of Offset.
+    #
+    # @param attributes [Hash]
+    # @return [Offset]
+    def initialize(attributes = {})
+      @attributes = defaults.merge!(attributes)
+      @name       = @attributes[:name]
+      @y          = @attributes[:y]
+      @x          = @attributes[:x]
+    end
+
+    # Return a convenient hash of the current values of this instance.
+    #
+    # @return [Hash]
+    def attributes
+      {
+        name: name,
+        y:    y,
+        x:    x,
+      }
+    end
+
+    # Adjusts the offset using the relative values provided, and updates the
+    # stored attributes. The values passed are -1, 0 or 1.
+    #
+    # @param relative_y [Fixnum] Move up (-1), or down (1), or no action (0).
+    # @param relative_x [Fixnum] Move left (-1), or right (1), or no action (0).
+    # @return [Offset]
+    def move(relative_y, relative_x)
+      @y += relative_y
+      @x += relative_x
+
+      Offsets.update(attributes)
+    end
+
+    # Returns the current x offset, correcting to 0 if less than 0.
+    #
+    # @return [Fixnum]
+    def x
+      return @x = 0 if @x <= 0
+
+      @x
+    end
+
+    # Returns the current y offset, correcting to 0 if less than 0.
+    #
+    # @return [Fixnum]
+    def y
+      return @y = 0 if @y <= 0
+
+      @y
+    end
+
+    private
+
+    # Return the default values for an instance of Offset.
+    #
+    # @return [Hash]
+    def defaults
+      {
+        name: '',
+        y:    0,
+        x:    0,
+      }
+    end
+
+  end # Offset
+
+end # Vedeu

data/lib/vedeu/models/stream.rb

@@ -40,27 +40,51 @@ module Vedeu
       end
     end
 
-    # Returns the content of this stream.
+    # Returns an array of characters, each element is the escape sequences of
+    # colours and styles for this stream, the character itself, and the escape
+    # sequences of colours and styles for the parent of the stream
+    # ({Vedeu::Line}).
+    #
+    # @return [Array]
+    def chars
+      return [] if empty?
+
+      char_attrs = view_attributes.merge!({ parent: parent })
+
+      @_chars ||= content.chars.map do |c|
+        Char.new(char_attrs.merge!({ value: c })).to_s
+      end
+    end
+
+    # Returns the text aligned if a width was set, otherwise just the text. This
+    # method also has the alias_method :data, a convenience method to provide
+    # Presentation with a consistent interface.
     #
     # @return [String]
     def content
-      data
+      width? ? aligned : text
     end
+    alias_method :data, :content
 
-    private
+    # Returns a boolean indicating whether the stream has content.
+    #
+    # @return [Boolean]
+    def empty?
+      size == 0
+    end
 
-    # Returns the text aligned if a width was set, otherwise just the text.
+    # Returns the size of the content in characters without formatting.
     #
-    # @api private
-    # @return [String]
-    def data
-      width? ? aligned : text
+    # @return [Fixnum]
+    def size
+      content.size
     end
 
+    private
+
     # 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
       case align
@@ -72,7 +96,6 @@ module Vedeu
 
     # Returns a boolean to indicate whether this stream has a width set.
     #
-    # @api private
     # @return [Boolean]
     def width?
       !!width
@@ -80,7 +103,6 @@ module Vedeu
 
     # The default values for a new instance of Stream.
     #
-    # @api private
     # @return [Hash]
     def defaults
       {
@@ -93,12 +115,14 @@ module Vedeu
       }
     end
 
-    # @api private
+    # @param method [Symbol] The name of the method sought.
+    # @param args [Array] The arguments which the method was to be invoked with.
+    # @param block [Proc] The optional block provided to the method.
     # @return []
     def method_missing(method, *args, &block)
       Vedeu.log("Stream#method_missing '#{method.to_s}' (args: #{args.inspect})")
 
-      @self_before_instance_eval.send(method, *args, &block)
+      @self_before_instance_eval.send(method, *args, &block) if @self_before_instance_eval
     end
 
   end # Stream

data/lib/vedeu/models/style.rb

@@ -38,7 +38,6 @@ module Vedeu
 
     # Converts the style or styles into terminal escape sequences.
     #
-    # @api private
     # @return [String]
     def escape_sequences
       return '' unless defined_value?(values)

data/lib/vedeu/output/area.rb

@@ -0,0 +1,284 @@
+module Vedeu
+
+  # Provides a collection of methods useful in calculating geometries for
+  # interfaces, cursors and viewports.
+  #
+  class Area
+
+    attr_reader  :attributes, :height, :x_min, :y_min, :width, :x, :y
+
+    # Returns an instance of Area.
+    #
+    # @param interface [Interface]
+    # @return [Area]
+    def self.from_interface(interface)
+      new({
+        y_min:  interface.top,
+        height: interface.height,
+        x_min:  interface.left,
+        width:  interface.width
+      })
+    end
+
+    # Returns an instance of Area.
+    #
+    # @param  attributes [Hash] The attributes to initialize this class with.
+    # @option attributes :y_min [Fixnum] The starting y coordinate for the area,
+    #   equivalent to +:top+ in {Geometry} parlance.
+    # @option attributes :height [Fixnum] The number of rows or lines to use.
+    # @option attributes :x_min [Fixnum] The starting x coordinate for the area,
+    #   equivalent to +:left+ in {Geometry} parlance.
+    # @option attributes :width [Fixnum] The number of characters or columns to
+    #   use.
+    # @option attributes :y [Fixnum] A coordinate in the area. This value should
+    #   be an actual terminal coordinate.
+    # @option attributes :x [Fixnum] A coordinate in the area. This value should
+    #   be an actual terminal coordinate.
+    #
+    # @return [Area]
+    def initialize(attributes = {})
+      @attributes = defaults.merge!(attributes)
+
+      @y_min  = @attributes.fetch(:y_min)
+      @height = @attributes.fetch(:height)
+
+      @x_min  = @attributes.fetch(:x_min)
+      @width  = @attributes.fetch(:width)
+
+      @y      = @attributes.fetch(:y)
+      @x      = @attributes.fetch(:x)
+    end
+
+    # Returns the same as #y_range, except as indices of an array.
+    #
+    # @example
+    #   # height = 4
+    #   y_indices # => [0, 1, 2, 3]
+    #
+    # @return [Array]
+    def y_indices
+      (0...height).to_a
+    end
+
+    # Returns the same as #x_range, except as indices of an array.
+    #
+    # @example
+    #   # width = 10
+    #   x_indices # => [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+    #
+    # @return [Array]
+    def x_indices
+      (0...width).to_a
+    end
+
+    # Returns the maximum y coordinate for an area.
+    #
+    # @example
+    #   # y_min = 2
+    #   # height = 4
+    #   y_max # => 6
+    #
+    # @return [Fixnum]
+    def y_max
+      if height <= 0
+        0
+
+      else
+        y_min + height
+
+      end
+    end
+
+    # Returns the maximum x coordinate for an area.
+    #
+    # @example
+    #   # x_min = 5
+    #   # width = 20
+    #   x_max # => 25
+    #
+    # @return [Fixnum]
+    def x_max
+      if width <= 0
+        0
+
+      else
+        x_min + width
+
+      end
+    end
+
+    # Returns the maximum y index for an area.
+    #
+    # @example
+    #   # height = 3
+    #   y_max_index # => 2
+    #
+    # @return [Fixnum]
+    def y_max_index
+      return 0 if y_indices.empty?
+
+      y_indices.last
+    end
+
+    # Returns the maximum x index for an area.
+    #
+    # @example
+    #   # width = 6
+    #   x_max_index # => 5
+    #
+    # @return [Fixnum]
+    def x_max_index
+      return 0 if x_indices.empty?
+
+      x_indices.last
+    end
+
+    # Returns the y coordinate as an offset index in the area's y range. When a
+    # value is provided, the y coordinate is overridden. Crudely corrects out of
+    # range values.
+    #
+    # @example
+    #   # y_range  = [7, 8, 9, 10]
+    #   # y = 8
+    #   y_index     # => 1
+    #   y_index(10) # => 3
+    #   y_index(5)  # => 0
+    #   y_index(15) # => 3
+    #
+    # @param value [Fixnum]
+    # @return [Fixnum]
+    def y_index(value = y)
+      if height <= 0 || value <= y_min
+        0
+
+      elsif value >= y_max
+        y_max_index
+
+      else
+        y_range.index(value)
+
+      end
+    end
+
+    # Returns the x coordinate as an offset index in the area's x range. When a
+    # value is provided, the x coordinate is overridden. Crudely corrects out of
+    # range values.
+    #
+    # @example
+    #   # x_range = [4, 5, 6, 7, 8, 9, 10, 11, 12, 13]
+    #   # x = 8
+    #   x_index     # => 4
+    #   x_index(11) # => 7
+    #   x_index(2)  # => 0
+    #   x_index(15) # => 9
+    #
+    # @param value [Fixnum]
+    # @return [Fixnum]
+    def x_index(value = x)
+      if width <= 0 || value <= x_min
+        0
+
+      elsif value >= x_max
+        x_max_index
+
+      else
+        x_range.index(value)
+
+      end
+    end
+
+    # Returns the actual position of y for a given index. Crudely corrects out
+    # of range values.
+    #
+    # @example
+    #   # y_range = [7, 8, 9, 10, 11]
+    #   y_position     # => 7
+    #   y_position(-2) # => 7
+    #   y_position(2)  # => 9
+    #   y_position(7)  # => 11
+    #
+    # @param index [Fixnum]
+    # @return [Fixnum]
+    def y_position(index = 0)
+      if index <= 0
+        y_min
+
+      elsif index >= y_max_index
+        y_max
+
+      else
+        y_range[index]
+
+      end
+    end
+
+    # Returns the actual position of x for a given index. Crudely corrects out
+    # of range values.
+    #
+    # @example
+    #   # x_range = [4, 5, 6, 7, 8, 9, 10, 11, 12, 13]
+    #   x_position     # => 4
+    #   x_position(-2) # => 4
+    #   x_position(2)  # => 6
+    #   x_position(15) # => 13
+    #
+    # @param index [Fixnum]
+    # @return [Fixnum]
+    def x_position(index = 0)
+      if index <= 0
+        x_min
+
+      elsif index >= x_max_index
+        x_max
+
+      else
+        x_range[index]
+
+      end
+    end
+
+    # Returns an array with all coordinates from x to x_max.
+    #
+    # @example
+    #   # width = 10
+    #   # x_min = 4
+    #   # x_max = 14
+    #   x_range # => [4, 5, 6, 7, 8, 9, 10, 11, 12, 13]
+    #
+    # @return [Array]
+    def x_range
+      (x_min...x_max).to_a
+    end
+
+    # Returns an array with all coordinates from y to y_max.
+    #
+    # @example
+    #   # height = 4
+    #   # y_min  = 7
+    #   # y_max  = 11
+    #   y_range # => [7, 8, 9, 10]
+    #
+    # @return [Array]
+    def y_range
+      (y_min...y_max).to_a
+    end
+
+    private
+
+    # Returns the default attributes for an Area instance.
+    #
+    # @return [Hash]
+    def defaults
+      {
+        height: 0,
+        x_min:  0,
+        y_min:  0,
+        width:  0,
+        x:      0,
+        y:      0,
+      }
+    end
+
+  end # Area
+
+end # Vedeu

data/lib/vedeu/output/clear.rb

@@ -32,7 +32,7 @@ module Vedeu
       Vedeu.log("Clearing view: '#{interface.name}'")
 
       rows.inject([colours]) do |line, index|
-        line << interface.origin(index) { ' ' * interface.viewport_width }
+        line << interface.origin(index) { ' ' * interface.width }
       end.join
     end
 
@@ -40,16 +40,14 @@ module Vedeu
 
     attr_reader :interface
 
-    # @api private
     # @return [String]
     def colours
       interface.colour.to_s
     end
 
-    # @api private
     # @return [Enumerator]
     def rows
-      interface.viewport_height.times
+      interface.height.times
     end
 
   end # Clear

data/lib/vedeu/output/compositor.rb

@@ -36,7 +36,6 @@ module Vedeu
     # Renders the buffer unless empty, otherwise clears the area which the
     # interface occupies.
     #
-    # @api private
     # @return [String]
     def view
       if buffer
@@ -51,7 +50,6 @@ module Vedeu
     # Combine the buffer attributes with the interface attributes. Buffer
     # presentation attributes will override interface defaults.
     #
-    # @api private
     # @return [Hash]
     def new_interface
       combined = interface
@@ -63,7 +61,6 @@ module Vedeu
 
     # Returns the attributes of the named interface (layout).
     #
-    # @api private
     # @return [Hash]
     def interface
       @_interface ||= Vedeu::Interfaces.find(name)
@@ -71,7 +68,6 @@ module Vedeu
 
     # Returns the attributes of the latest buffer (view).
     #
-    # @api private
     # @return [Hash]
     def buffer
       @_buffer ||= Vedeu::Buffers.latest(name)

data/lib/vedeu/output/refresh.rb

@@ -37,7 +37,7 @@ module Vedeu
     # Refresh an interface by name.
     #
     # @param name [String] The name of the interface to be refreshed.
-    # @return [|BufferNotFound]
+    # @return [Array|BufferNotFound]
     def by_name(name)
       Vedeu::Compositor.render(name)
     end
@@ -46,7 +46,6 @@ module Vedeu
     # When the event is called, the interface, or all interfaces belonging to
     # the group with this name will be refreshed.
     #
-    # @api private
     # @param type [Symbol]
     # @param name [String]
     # @param delay [Float]