vedeu 0.1.18 → 0.1.19

data/lib/vedeu/output/refresh.rb

@@ -0,0 +1,129 @@
+module Vedeu
+
+  # Refreshes the terminal.
+  #
+  # @api private
+  module Refresh
+
+    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]
+    def all
+      Vedeu::Interfaces.registered.each { |name| by_name(name) }
+    end
+
+    # Refresh the interface which is currently focussed.
+    #
+    # @return [|NoInterfacesDefined]
+    def by_focus
+      by_name(Vedeu::Focus.current)
+    end
+
+    # Refresh an interface, or collection of interfaces belonging to a group.
+    #
+    # @param group_name [String] The name of the group to be refreshed.
+    # @return [Array|GroupNotFound] A collection of the names of interfaces
+    #   refreshed, or an exception if the group was not found.
+    def by_group(group_name)
+      Vedeu::Groups.find(group_name).each { |name| by_name(name) }
+    end
+
+    # Refresh an interface by name.
+    #
+    # @param name [String] The name of the interface to be refreshed.
+    # @return [|BufferNotFound]
+    def by_name(name)
+      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.
+    #
+    # @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))
+
+      Vedeu.event(event_name(name), { delay: delay }) do
+        Vedeu::Refresh.by_name(name)
+      end
+
+      true
+    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))
+
+      Vedeu.event(group_event_name(name), { delay: delay }) do
+        Vedeu::Refresh.by_group(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

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

@@ -1,23 +1,32 @@
 module Vedeu
+
+  # Attempts to convert the provided interface object with associated lines,
+  # streams, colours, styles, etc, into a single string containing all content
+  # and escape sequences.
+  #
+  # @api private
   class Render
 
-    # Attempts to convert the provided interface object with associated lines,
-    # streams, colours, styles, etc, into a single string containing all content
-    # and escape sequences.
+    # Create a new instance of Render with the provided {Vedeu::Interface} and
+    # then convert the interface into a single string of content and escape
+    # sequences.
     #
     # @api private
     # @param interface [Interface]
+    # @param options [Hash]
     # @return [String]
-    def self.call(interface)
-      new(interface).render
+    def self.call(interface, options = {})
+      new(interface, options).render
     end
 
-    # Initializes a new Render object with the provided interface.
+    # Return a new instance of Render.
     #
     # @param interface [Interface]
+    # @param options [Hash]
     # @return [Render]
-    def initialize(interface)
+    def initialize(interface, options = {})
       @interface = interface
+      @options   = options
     end
 
     # Produces a single string which contains all content and escape sequences
@@ -27,10 +36,8 @@ module Vedeu
     def render
       out = [ Clear.call(interface) ]
       processed_lines.each_with_index do |line, index|
-        if index + 1 <= height
-          out << interface.origin(index)
-          out << line.to_s
-        end
+        out << interface.origin(index)
+        out << line.to_s
       end
       out << interface.cursor
       out.join
@@ -63,6 +70,7 @@ module Vedeu
                              colour: stream.colour.attributes,
                              style:  stream.style.values,
                              text:   truncate(stream.text, remainder),
+                             parent: line.view_attributes,
                            })
 
             else
@@ -75,6 +83,7 @@ module Vedeu
             colour:  line.colour.attributes,
             streams: processed,
             style:   line.style.values,
+            parent:  interface.view_attributes,
           })
 
         else
@@ -106,19 +115,24 @@ module Vedeu
     end
 
     # Provides a collection of lines associated with the interface.
+    # If the option `:top` was set, we will start at that line. Any lines
+    # outside of the height will not be rendered.
     #
     # @api private
     # @return [Array]
     def lines
-      interface.lines
+      interface.lines[top..height]
     end
 
     # Provides the currently available height of the interface.
     #
+    # @note The height is reported to be one less line than actual because
+    #   terminal coordinates count from 1, not 0.
+    #
     # @api private
     # @return [Fixnum]
     def height
-      interface.viewport_height
+      interface.viewport_height - 1
     end
 
     # Provides the currently available width of the interface.
@@ -129,5 +143,27 @@ module Vedeu
       interface.viewport_width
     end
 
+    # The current top line.
+    #
+    # @api private
+    # @return [Fixnum]
+    def top
+      options[:top]
+    end
+
+    # @api private
+    # @return [Hash]
+    def options
+      @_options ||= defaults.merge!(@options)
+    end
+
+    # @api private
+    # @return [Hash]
+    def defaults
+      {
+        top: 0
+      }
+    end
+
   end
 end

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

@@ -1,4 +1,9 @@
 module Vedeu
+
+  # Subclassing Vedeu::View will allow Vedeu to call your #render method.
+  # This method should contain attributes required to build a view or views.
+  # These attributes will be added to the back buffer of each interface
+  # mentioned, to be rendered upon next refresh.
   class View
 
     include Vedeu::API
@@ -9,6 +14,8 @@ module Vedeu
       new(object).enqueue
     end
 
+    # Returns a new instance of View.
+    #
     # @param object []
     # @return [View]
     def initialize(object = nil)
@@ -17,31 +24,31 @@ module Vedeu
 
     # @return [Array]
     def enqueue
-      interfaces.map { |interface| Buffers.enqueue(interface.name, interface) }
+      composition.interfaces.map do |interface|
+        Buffers.add(interface.attributes)
+      end
     end
 
     # @return [Exception]
     def render
       fail NotImplemented, 'Implement #render on your subclass of Vedeu::View.'
     end
-    alias_method :output, :render
 
     private
 
     attr_reader :object
 
-    # @api private
-    # @return [Array]
-    def interfaces
-      composition.interfaces
-    end
-
+    # Create a new Composition object with the attributes.
+    #
     # @api private
     # @return [Composition]
     def composition
       @_composition ||= Composition.new(attributes)
     end
 
+    # Calls the #render method of the subclass, hopefully receives attributes
+    # suitable to create one or more views.
+    #
     # @api private
     # @return []
     def attributes

data/lib/vedeu/repositories/buffers.rb

@@ -0,0 +1,181 @@
+module Vedeu
+
+  # Stores interface views to be later combined with interface geometry to be
+  # displayed.
+  #
+  # @api private
+  module Buffers
+
+    include Vedeu::Common
+    extend self
+
+    # @param attributes [Hash]
+    # @return [Hash]
+    def create(attributes)
+      add(attributes)
+
+      Vedeu::Interfaces.add(attributes)
+      Vedeu::Refresh.add_interface(attributes)
+
+      Vedeu::Groups.add(attributes)
+      Vedeu::Refresh.add_group(attributes)
+
+      Vedeu::Focus.add(attributes)
+    end
+
+    # Add an interface view into the back buffer. If the buffer is already
+    # registered, then we preserve its front buffer.
+    #
+    # @param attributes [Hash]
+    # @return [Hash]
+    def add(attributes)
+      if registered?(attributes[:name])
+        buffer = find(attributes[:name])
+        buffer[:back_buffer] = attributes
+
+      else
+        storage.store(attributes[:name], {
+          back_buffer:  attributes,
+          front_buffer: nil,
+        })
+
+      end
+
+      storage
+    end
+
+    # Find the buffer by name.
+    #
+    # @param name [String]
+    # @return [Hash]
+    def find(name)
+      storage.fetch(name) do
+        fail BufferNotFound, "Cannot find buffer with this name: #{name.to_s}."
+      end
+    end
+
+    # Returns the latest content for the named buffer. The latest content always
+    # goes on to the back buffer. The content which was last output is on the
+    # front buffer.
+    #
+    # When the back buffer has new content, we swap the back onto the front and
+    # return the front buffer to be rendered.
+    #
+    # When the back buffer has no new content, we display that which we
+    # previously displayed, by returning the front buffer.
+    #
+    # If both the back and front buffers have no content, then the view is blank
+    # and we should return nothing.
+    #
+    # @param name [String]
+    # @return [Hash]
+    def latest(name)
+      if new_content?(name)
+        swap_buffers(name)
+        content(name)
+
+      elsif old_content?(name)
+        content(name)
+
+      else
+        nil
+
+      end
+    end
+
+    # Returns the named front buffer.
+    #
+    # @param name [String]
+    # @return [Hash]
+    def content(name)
+      front_buffer(name)
+    end
+
+    # Swap the named back buffer into the front buffer of the same name.
+    #
+    # @param name [String]
+    # @return [Hash]
+    def swap_buffers(name)
+      buffer = find(name)
+
+      storage.store(name, {
+        front_buffer: buffer[:back_buffer],
+        back_buffer:  nil,
+      })
+    end
+
+    # Reset the buffers repository; removing all buffers. This does not delete
+    # the interfaces themselves.
+    #
+    # @return [Hash]
+    def reset
+      @_storage = in_memory
+    end
+
+    private
+
+    # Return a boolean indicating whether the named back buffer has new content.
+    #
+    # @api private
+    # @param name [String]
+    # @return [TrueClass|FalseClass]
+    def new_content?(name)
+      defined_value?(back_buffer(name))
+    end
+
+    # Return a boolean indicating whether the named front buffer has content.
+    #
+    # @api private
+    # @param name [String]
+    # @return [TrueClass|FalseClass]
+    def old_content?(name)
+      defined_value?(front_buffer(name))
+    end
+
+    # Return the named back buffer.
+    #
+    # @api private
+    # @param name [String]
+    # @return [Hash|Nil]
+    def back_buffer(name)
+      find(name).fetch(:back_buffer, nil)
+    end
+
+    # Return the named front buffer.
+    #
+    # @api private
+    # @param name [String]
+    # @return [Hash|Nil]
+    def front_buffer(name)
+      find(name).fetch(:front_buffer, nil)
+    end
+
+    # Returns a boolean indicating whether the named buffer is registered.
+    #
+    # @api private
+    # @param name [String]
+    # @return [TrueClass|FalseClass]
+    def registered?(name)
+      storage.key?(name)
+    end
+
+    # @api private
+    # @return [Hash]
+    def storage
+      @_storage ||= in_memory
+    end
+
+    # @api private
+    # @return [Hash]
+    def in_memory
+      Hash.new do |hash, interface_name|
+        hash[interface_name] = {
+          front_buffer: nil,
+          back_buffer:  nil,
+        }
+      end
+    end
+
+  end
+
+end