vedeu 0.4.5 → 0.4.6

data/lib/vedeu/output/clear.rb

@@ -0,0 +1,62 @@
+module Vedeu
+
+  # Clears the area defined by an interface.
+  #
+  class Clear
+
+    include Vedeu::CharBuilder
+
+    # Clears the area defined by the interface.
+    #
+    # @return [Array|String]
+    # @see #initialize
+    def self.clear(interface)
+      new(interface).write
+    end
+
+    # Return a new instance of Output.
+    #
+    # @param interface [Interface]
+    # @return [Output]
+    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 [Array<Array<Vedeu::Char>>]
+    def clear
+      out = interface.height.times.inject([]) do |row, iy|
+        row << interface.width.times.inject([]) do |column, ix|
+          column << char_builder(' ', iy, ix)
+        end
+      end
+    end
+
+    # Clear the view and send to the terminal.
+    #
+    # @return [Array]
+    def write
+      Vedeu.log(type: :output, message: "Clearing: '#{interface.name}'")
+
+      if Vedeu::Configuration.drb?
+        Vedeu.trigger(:_drb_store_output_, clear)
+
+        Vedeu::HTMLRenderer.to_file(Vedeu::VirtualBuffer.retrieve)
+      end
+
+      Vedeu::Terminal.output(Vedeu::Renderer.render(clear))
+    end
+
+    private
+
+    # @!attribute [r] interface
+    # @return [Interface]
+    attr_reader :interface
+
+  end # Clear
+
+end # Vedeu
+

data/lib/vedeu/output/colour.rb

@@ -10,9 +10,17 @@ module Vedeu
 
     include Vedeu::Coercions
 
-    attr_reader :attributes,
-      :background,
-      :foreground
+    # @!attribute [r] attributes
+    # @return [Hash]
+    attr_reader :attributes
+
+    # @!attribute [r] background
+    # @return [Background|String]
+    attr_reader :background
+
+    # @!attribute [r] foreground
+    # @return [Foreground|String]
+    attr_reader :foreground
 
     # Returns a new instance of Colour.
     #
@@ -23,8 +31,8 @@ module Vedeu
     def initialize(attributes = {})
       @attributes = defaults.merge!(attributes)
 
-      @background = Background.coerce(@attributes[:background])
-      @foreground = Foreground.coerce(@attributes[:foreground])
+      @background = Vedeu::Background.coerce(@attributes[:background])
+      @foreground = Vedeu::Foreground.coerce(@attributes[:foreground])
     end
 
     # Converts the value into a Vedeu::Foreground.
@@ -32,7 +40,7 @@ module Vedeu
     # @param value [String]
     # @return [String]
     def foreground=(value)
-      @foreground = Foreground.coerce(value)
+      @foreground = Vedeu::Foreground.coerce(value)
     end
 
     # Converts the value into a Vedeu::Background.
@@ -40,7 +48,7 @@ module Vedeu
     # @param value [String]
     # @return [String]
     def background=(value)
-      @background = Background.coerce(value)
+      @background = Vedeu::Background.coerce(value)
     end
 
     # Returns both or either of the converted attributes into a single escape

data/lib/vedeu/output/compositor.rb

@@ -34,12 +34,14 @@ module Vedeu
         view.colour   = interface.colour   unless view.colour
         view.style    = interface.style    unless view.style
 
-        Output.render(view)
+        Vedeu::Output.render(view)
       end
     end
 
     private
 
+    # @!attribute [r] name
+    # @return [String]
     attr_reader :name
 
     # @return [Vedeu::Interface]

data/lib/vedeu/output/esc.rb

@@ -69,7 +69,7 @@ module Vedeu
     #
     # @return [Hash]
     def background_codes
-      Esc.codes.inject({}) { |h, (k, v)| h.merge!(k => v + 10) }
+      Vedeu::Esc.codes.inject({}) { |h, (k, v)| h.merge!(k => v + 10) }
     end
 
     # Dynamically creates methods for each terminal named colour. When a block
@@ -183,7 +183,7 @@ module Vedeu
 
     # @return [String]
     def clear_last_line
-      Vedeu::Position.new((Terminal.height - 1), 1).to_s { clear_line }
+      Vedeu::Position.new((Vedeu::Terminal.height - 1), 1).to_s { clear_line }
     end
 
     # @return [String]

data/lib/vedeu/output/foreground.rb

@@ -7,13 +7,13 @@ module Vedeu
   # The class represents one half (the other, can be found at
   # {Vedeu::Background}) of a terminal colour escape sequence.
   #
-  class Foreground < Translator
+  class Foreground < Vedeu::Translator
 
     private
 
     # @return [String]
     def named_codes
-      Esc.foreground_codes[colour]
+      Vedeu::Esc.foreground_codes[colour]
     end
 
     # @return [String]

data/lib/vedeu/output/html_char.rb

@@ -27,6 +27,8 @@ module Vedeu
 
     private
 
+    # @!attribute [r] char
+    # @return [Vedeu::Char]
     attr_reader :char
 
     # @return [String]

data/lib/vedeu/output/html_renderer.rb

@@ -11,9 +11,10 @@ module Vedeu
     end
 
     # @param output [Array<Array<Vedeu::Char>>]
+    # @param path [String]
     # @return [String]
-    def self.to_file(output)
-      new(output).to_file
+    def self.to_file(output, path = nil)
+      new(output).to_file(path)
     end
 
     # @param output [Array<Array<Vedeu::Char>>]
@@ -24,7 +25,7 @@ module Vedeu
 
     # @return [String]
     def render
-      Template.parse(self, template)
+      Vedeu::Template.parse(self, template)
     end
 
     # Writes the parsed template to a file (at the given path) and returns the
@@ -56,6 +57,8 @@ module Vedeu
 
     private
 
+    # @!attribute [r] output
+    # @return [Array<Array<Vedeu::Char>>]
     attr_reader :output
 
     # @return [String]

data/lib/vedeu/output/output.rb

@@ -1,16 +1,17 @@
+require 'vedeu/output/clear'
+require 'vedeu/output/html_renderer'
+require 'vedeu/output/renderer'
+require 'vedeu/output/viewport'
+require 'vedeu/output/virtual_buffer'
+require 'vedeu/support/terminal'
+
 module Vedeu
 
   # Sends the interface to the terminal or output device.
   #
   class Output
 
-    # Clears the area defined by the interface.
-    #
-    # @return [Array|String]
-    # @see #initialize
-    def self.clear(interface)
-      new(interface).clear
-    end
+    include Vedeu::CharBuilder
 
     # Writes content (the provided interface object with associated lines,
     # streams, colours and styles) to the area defined by the interface.
@@ -29,19 +30,6 @@ module Vedeu
       @interface = interface
     end
 
-    # Clear the view and send to the terminal.
-    #
-    # @return [Array]
-    def clear
-      if Vedeu::Configuration.drb?
-        Vedeu.trigger(:_drb_store_output_, virtual_clear)
-
-        HTMLRenderer.to_file(VirtualBuffer.retrieve)
-      end
-
-      Terminal.output(Renderer.render(virtual_clear))
-    end
-
     # Send the view to the terminal.
     #
     # @return [Array]
@@ -49,38 +37,18 @@ module Vedeu
       if Vedeu::Configuration.drb?
         Vedeu.trigger(:_drb_store_output_, virtual_view)
 
-        HTMLRenderer.to_file(VirtualBuffer.retrieve)
+        Vedeu::HTMLRenderer.to_file(Vedeu::VirtualBuffer.retrieve)
       end
 
-      Terminal.output(Renderer.render(virtual_view, interface.cursor))
+      Vedeu::Terminal.output(Vedeu::Renderer.render(virtual_view, interface.cursor))
     end
 
     private
 
+    # @!attribute [r] interface
+    # @return [Interface]
     attr_reader :interface
 
-    # 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.
-    #
-    # @note
-    #   omg!
-    #
-    # @return [Array<Array<Vedeu::Char>>]
-    def virtual_clear
-      Vedeu.log(type: :output, message: "Clearing: '#{interface.name}'")
-
-      out = []
-      interface.height.times do |iy|
-        row = []
-        interface.width.times do |ix|
-          row << char_builder(' ', iy, ix)
-        end
-        out << row
-      end
-      out
-    end
-
     # Builds up a virtual view; a grid of Vedeu::Char objects- each one holding
     # one character along with its colour, style and position attributes.
     #
@@ -89,19 +57,19 @@ module Vedeu
     #
     # @return [Array<Array<Vedeu::Char>>]
     def virtual_view
-      out = [ virtual_clear ]
+      out = [ clear_area_first! ]
 
       Vedeu.log(type: :output, message: "Rendering: '#{interface.name}'")
 
       viewport.each_with_index do |line, iy|
         row = []
         line.each_with_index do |char, ix|
-          row << if char.is_a?(Vedeu::Char) && (char.x != ix || char.y != iy)
+          row << if char.x != ix || char.y != iy
             char.position = origin(iy, ix)
             char
 
           else
-            char_builder(char, iy, ix)
+            char
 
           end
         end
@@ -110,56 +78,16 @@ module Vedeu
       out
     end
 
+    # @return [Array<Array<Vedeu::Char>>]
+    def clear_area_first!
+      Vedeu::Clear.new(interface).clear
+    end
+
     # @return [void]
     def viewport
       @viewport ||= Vedeu::Viewport.new(interface).render
     end
 
-    # @param value [String]
-    # @param iy [Fixnum]
-    # @param ix [Fixnum]
-    # @return [Vedeu::Char]
-    def char_builder(value, iy, ix)
-      Vedeu::Char.new({ value:    value,
-                        colour:   interface.colour,
-                        style:    interface.style,
-                        position: origin(iy, ix) })
-    end
-
-    # Returns the position of the cursor at the top-left coordinate, relative to
-    # the interface's position.
-    #
-    # @param y_index [Fixnum]
-    # @param x_index [Fixnum]
-    # @return [Vedeu::Position]
-    def origin(y_index = 0, x_index = 0)
-      Vedeu::Position.new(virtual_y[y_index], virtual_x[x_index])
-    end
-
-    # Provides a virtual y position within the interface's dimensions.
-    #
-    # @example
-    #   # top = 3
-    #   # bottom = 6
-    #   # virtual_y # => [3, 4, 5]
-    #
-    # @return [Array]
-    def virtual_y
-      @virtual_y ||= (interface.top...interface.bottom).to_a
-    end
-
-    # Provides a virtual x position within the interface's dimensions.
-    #
-    # @example
-    #   # left = 9
-    #   # right = 13
-    #   # virtual_x # => [9, 10, 11, 12]
-    #
-    # @return [Array]
-    def virtual_x
-      @virtual_x ||= (interface.left...interface.right).to_a
-    end
-
   end # Output
 
 end # Vedeu

data/lib/vedeu/output/presentation.rb

@@ -12,6 +12,16 @@ module Vedeu
       end
     end
 
+    # @return [Vedeu::Colour]
+    def colour
+      @colour ||= Vedeu::Colour.coerce(@colour)
+    end
+
+    # @return [Vedeu::Colour]
+    def colour=(value)
+      @colour = Vedeu::Colour.coerce(value)
+    end
+
     # @return [Vedeu::Foreground|NilClass]
     def foreground
       if colour
@@ -26,6 +36,11 @@ module Vedeu
       end
     end
 
+    # @return [String|NilClass]
+    def parent_colour
+      parent.colour if parent
+    end
+
     # @return [Vedeu::Foreground|NilClass]
     def parent_foreground
       if parent_colour
@@ -33,19 +48,14 @@ module Vedeu
       end
     end
 
-    # @return [Vedeu::Colour]
-    def colour
-      Vedeu::Colour.coerce(@colour)
-    end
-
-    # @return [Vedeu::Colour]
-    def colour=(value)
-      @colour = Vedeu::Colour.coerce(value)
+    # @return [String|NilClass]
+    def parent_style
+      parent.style if parent
     end
 
     # @return [Vedeu::Style]
     def style
-      Vedeu::Style.coerce(@style)
+      @style ||= Vedeu::Style.coerce(@style)
     end
 
     # @return [Vedeu::Style]
@@ -64,20 +74,10 @@ module Vedeu
 
     private
 
-    # @return [String|NilClass]
-    def parent_colour
-      parent.colour if parent
-    end
-
-    # @return [String|NilClass]
-    def parent_style
-      parent.style if parent
-    end
-
     # @return [String]
     def render_border
       if self.respond_to?(:border) && !border.nil?
-        Esc.border { yield }
+        Vedeu::Esc.border { yield }
 
       else
         yield
@@ -100,7 +100,7 @@ module Vedeu
 
     # @return [String]
     def render_position
-      if self.respond_to?(:position) && position.is_a?(Position)
+      if self.respond_to?(:position) && self.position.is_a?(Vedeu::Position)
         position.to_s { yield }
 
       else

data/lib/vedeu/output/renderer.rb

@@ -24,6 +24,8 @@ module Vedeu
 
     private
 
+    # @!attribute [r] output
+    # @return [Array<Array<Vedeu::Char>>]
     attr_reader :output
 
   end # Renderer

data/lib/vedeu/output/style.rb

@@ -11,9 +11,11 @@ module Vedeu
     include Vedeu::Common
     include Vedeu::Coercions
 
+    # @!attribute [rw] value
+    # @return [String|Symbol]
     attr_accessor :value
 
-    # Return a new instance of Style.
+    # Return a new instance of Vedeu::Style.
     #
     # @param value [Array|Array<String>|Array<Symbol>|String|Symbol]
     #   The style value or a collection of values.
@@ -37,7 +39,7 @@ module Vedeu
     def to_s
       return '' unless defined_value?(value)
 
-      @sequences ||= Array(value).flatten.map { |v| Esc.string(v) }.join
+      @sequences ||= Array(value).flatten.map { |v| Vedeu::Esc.string(v) }.join
     end
     alias_method :escape_sequences, :to_s
 

data/lib/vedeu/output/text.rb

@@ -41,7 +41,13 @@ module Vedeu
 
     private
 
-    attr_reader :value, :options
+    # @!attribute [r] value
+    # @return [String]
+    attr_reader :value
+
+    # @!attribute [r] options
+    # @return [Hash]
+    attr_reader :options
 
     # @return [Symbol] One of :align, :centre, :center, :left, :right, :text
     def anchor

data/lib/vedeu/output/translator.rb

@@ -25,6 +25,8 @@ module Vedeu
 
     include Vedeu::Coercions
 
+    # @!attribute [r] colour
+    # @return [String]
     attr_reader :colour
     alias_method :value, :colour
 
@@ -104,7 +106,7 @@ module Vedeu
     #
     # @return [Boolean]
     def valid_name?
-      Esc.codes.keys.include?(colour)
+      Vedeu::Esc.codes.keys.include?(colour)
     end
 
     # Returns a boolean indicating whether the colour provided is a terminal
@@ -140,7 +142,7 @@ module Vedeu
     #
     # @return [String]
     def rgb
-      if Configuration.colour_mode == 16777216
+      if Vedeu::Configuration.colour_mode == 16777216
         sprintf(rgb_prefix, *css_to_rgb)
 
       else

data/lib/vedeu/output/viewport.rb

@@ -65,6 +65,8 @@ module Vedeu
 
     private
 
+    # @!attribute [r] interface
+    # @return [Vedeu::Interface]
     attr_reader :interface
 
     # Returns the visible content for the interface.
@@ -78,7 +80,7 @@ module Vedeu
     def show
       return [] unless lines?
 
-      padded_lines.map { |line| padded_columns(line) }.compact
+      padded_lines.map { |line| padded_columns(line) }
     end
 
     # Returns the lines, padded where necessary for the viewport.
@@ -112,7 +114,7 @@ module Vedeu
 
       return visible unless size < dim
 
-      visible + [" "] * (dim - size)
+      visible + [Vedeu::Char.new({ value: ' ' })] * (dim - size)
     end
 
     # Using the current cursor's y position, return a range of visible lines.

data/lib/vedeu/output/virtual_buffer.rb

@@ -1,6 +1,16 @@
 module Vedeu
 
-  # Store and retrieve virtual terminals.
+  # Store and retrieve {Vedeu::VirtualTerminal} objects.
+  #
+  # Each {Vedeu::VirtualTerminal} object is a copy of the current terminal
+  # including content but not as String objects but {Vedeu::Char} objects. Using
+  # {Vedeu::Char} objects means that we can store the data used to make up the
+  # displayed character, complete with its colour, position and style.
+  #
+  # Once a {Vedeu::Char} has been converted to a String, it is tricky to
+  # separate the escape sequences and string data. By deferring this conversion
+  # we can display the {Vedeu::Char} in multiple ways (e.g. HTML) or in multiple
+  # formats (e.g. JSON), and render/use that in an appropriate way.
   #
   module VirtualBuffer
 

data/lib/vedeu/output/virtual_terminal.rb

@@ -1,23 +1,34 @@
 module Vedeu
 
-  # Represents a {Vedeu::Terminal} view.
+  # Represents a {Vedeu::Terminal} view as a grid of {Vedeu::Cell} objects.
   #
   class VirtualTerminal
 
+    # @!attribute [rw] renderer
+    # @return [void]
     attr_accessor :renderer
-    attr_reader :cell_height, :cell_width, :height, :width
+
+    # @!attribute [r] height
+    # @return [Fixnum]
+    attr_reader :height
+
+    # @!attribute [r] width
+    # @return [Fixnum]
+    attr_reader :width
 
     # @param height [Fixnum]
     # @param width [Fixnum]
     # @param renderer [Object|HTMLRenderer] An object responding to .render.
     # @return [Vedeu::VirtualTerminal]
-    def initialize(height, width, renderer = HTMLRenderer)
-      @cell_height, @cell_width = Vedeu::PositionIndex[height, width]
+    def initialize(height, width, renderer = Vedeu::HTMLRenderer)
       @height   = height
       @width    = width
       @renderer = renderer
     end
 
+    # Return a grid of {Vedeu::Char} objects defined by the height and width of
+    # this virtual terminal.
+    #
     # @return [Array<Array<Vedeu::Char>>]
     def cells
       @cells ||= new_virtual_terminal
@@ -25,6 +36,11 @@ module Vedeu
 
     # Read a single cell from the virtual terminal.
     #
+    # @note
+    #   Given two actual coordinates (y, x) e.g. (1, 1)
+    #   Convert to coordinate indices (cy, cx) e.g. (0, 0)
+    #   Fetch the row at cy and return the cell from cx
+    #
     # @param y [Fixnum]
     # @param x [Fixnum]
     # @return [Vedeu::Char]
@@ -49,7 +65,9 @@ module Vedeu
       cells
     end
 
-    # @return [void]
+    # Send the cells to the renderer and return the rendered result.
+    #
+    # @return [String|void] Most likely to be a String.
     def render
       renderer.render(cells)
     end
@@ -64,15 +82,18 @@ module Vedeu
 
     # Write a single cell to the virtual terminal.
     #
+    # @note
+    #   If the position (y, x) is nil; we're out of bounds.
+    #   Otherwise, write the data to (cy, cx).
+    #
     # @param y [Fixnum]
     # @param x [Fixnum]
     # @param data [Vedeu::Char]
     # @return [Vedeu::Char]
     def write(y, x, data)
-      cy, cx = Vedeu::PositionIndex[y, x]
-
-      return false unless read(cy, cx).is_a?(Vedeu::Char)
+      return false unless read(y, x).is_a?(Vedeu::Char)
 
+      cy, cx = Vedeu::PositionIndex[y, x]
       cells[cy][cx] = data
 
       true
@@ -80,16 +101,18 @@ module Vedeu
 
     private
 
-    # @param from [Array]
-    # @param which [Array]
+    # @param from [Array] An Array of rows, or an Array of cells.
+    # @param which [Fixnum] A Fixnum representing the index; the row number or
+    #   the cell number for a row.
     # @return [Array<Vedeu::Char>|Array]
     def fetch(from, which)
       from[which] || []
     end
 
     # @return [Array<Array<Vedeu::Char>>]
+    # @see {Vedeu::VirtualTerminal#cells}
     def new_virtual_terminal
-      Array.new(cell_height) { Array.new(cell_width) { Vedeu::Char.new } }
+      Array.new(height) { Array.new(width) { Vedeu::Char.new } }
     end
 
   end # VirtualTerminal