vedeu 0.4.19 → 0.4.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dab76c44fae79844ccc5b6321392ee99a09c23d0
-  data.tar.gz: 43162ef0fdcf20ba49b09957d32316379e3e0583
+  metadata.gz: 7c7cd26a499c374db75b879fd68895f3556128d7
+  data.tar.gz: eb83922ae30bc67dd8dd4c85f5187b677db16168
 SHA512:
-  metadata.gz: a9774a3562701e47aaacc997d01dd157ce021c46b688adda4f56b4cdffb323c918189bc1038b0af46031aa858825449b865eb77b37b41d482aa106e6120f406e
-  data.tar.gz: 222d43c099bf843b27b616536b10b0cc316c6c0cb9bb09e06606ffd00362aa2ee02eb79f84cd09c4ac437d94270df33ec88a1fd4e328d0a6d22e8f9259b104a2
+  metadata.gz: f0e7347e6b8b32abd258f387ffb16dfedba70a02969bd441d66c0075429b53da21337e990159daf02763dbf77342a42a1ea6b95bf0ee6f427858fa2717a124e3
+  data.tar.gz: 14583143e3615ad64da7c574403882ec6a40dea16445990c0f892322a9839cd670caa91e107be0171c8d34ecb65656285fb92ee2114a60de8516f342732707de

data/lib/vedeu/api.rb

@@ -36,6 +36,10 @@ module Vedeu
 
     module_function
 
+    # @!method background_colours
+    #   @see Vedeu::BackgroundColours.background_colours
+    def_delegators Vedeu::BackgroundColours, :background_colours
+
     # @!method borders
     #   @see Vedeu::Borders.borders
     def_delegators Vedeu::Borders, :borders
@@ -48,66 +52,18 @@ module Vedeu
     #   @see Vedeu::Canvas.canvas
     def_delegators Vedeu::Canvas, :canvas
 
-    # @!method background_colours
-    #   @see Vedeu::BackgroundColours.background_colours
-    def_delegators Vedeu::BackgroundColours, :background_colours
-
-    # @!method foreground_colours
-    #   @see Vedeu::ForegroundColours.foreground_colours
-    def_delegators Vedeu::ForegroundColours, :foreground_colours
-
-    # @!method cursors
-    #   @see Vedeu::Cursors.cursors
-    def_delegators Vedeu::Cursors, :cursors
-
-    # @!method cursor
-    #   @see Vedeu::Cursors.cursor
-    def_delegators Vedeu::Cursors, :cursor
-
-    # @!method events
-    #   @see Vedeu::EventsRepository.events
-    def_delegators Vedeu::EventsRepository, :events
-
-    # @!method geometries
-    #   @see Vedeu::Geometries.geometries
-    def_delegators Vedeu::Geometries, :geometries
-
-    # @!method groups
-    #   @see Vedeu::Groups.groups
-    def_delegators Vedeu::Groups, :groups
-
-    # @!method interfaces
-    #   @see Vedeu::InterfacesRepository.interfaces
-    def_delegators Vedeu::InterfacesRepository, :interfaces
-
-    # @!method keymaps
-    #   @see Vedeu::Keymaps.keymaps
-    def_delegators Vedeu::Keymaps, :keymaps
-
-    # @!method keypress
-    #   @see Vedeu::Mapper.keypress
-    def_delegators Vedeu::Mapper, :keypress
-
-    # @!method menus
-    #   @see Vedeu::Menus.menus
-    def_delegators Vedeu::Menus, :menus
-
-    # @!method bind
-    #   @see Vedeu::Event.bind
-    # @!method unbind
-    #   @see Vedeu::Event.unbind
-    def_delegators Vedeu::Event, :bind, :unbind
-
-    # @!method trigger
-    #   @see Vedeu::Trigger.trigger
-    def_delegators Vedeu::Trigger, :trigger
-
     # @!method configure
     #   @see Vedeu::Configuration.configure
     # @!method configuration
     #   @see Vedeu::Configuration.configuration
     def_delegators Vedeu::Configuration, :configure, :configuration
 
+    # @!method cursor
+    #   @see Vedeu::Cursors.cursor
+    # @!method cursors
+    #   @see Vedeu::Cursors.cursors
+    def_delegators Vedeu::Cursors, :cursor, :cursors
+
     # @!method border
     #   @see Vedeu::DSL::Border.border
     def_delegators Vedeu::DSL::Border, :border
@@ -116,14 +72,14 @@ module Vedeu
     #   @see Vedeu::DSL::Geometry.geometry
     def_delegators Vedeu::DSL::Geometry, :geometry
 
-    # @!method keymap
-    #   @see Vedeu::DSL::Keymap.keymap
-    def_delegators Vedeu::DSL::Keymap, :keymap
-
     # @!method group
     #   @see Vedeu::DSL::Group.group
     def_delegators Vedeu::DSL::Group, :group
 
+    # @!method keymap
+    #   @see Vedeu::DSL::Keymap.keymap
+    def_delegators Vedeu::DSL::Keymap, :keymap
+
     # @!method interface
     #   @see Vedeu::DSL::View.interface
     # @!method renders
@@ -132,6 +88,16 @@ module Vedeu
     #   @see Vedeu::DSL::View.views
     def_delegators Vedeu::DSL::View, :interface, :renders, :views
 
+    # @!method bind
+    #   @see Vedeu::Event.bind
+    # @!method unbind
+    #   @see Vedeu::Event.unbind
+    def_delegators Vedeu::Event, :bind, :unbind
+
+    # @!method events
+    #   @see Vedeu::EventsRepository.events
+    def_delegators Vedeu::EventsRepository, :events
+
     # @!method focus
     #   @see Vedeu::Focus#focus
     # @!method focus_by_name
@@ -145,14 +111,48 @@ module Vedeu
     def_delegators Vedeu::Focus, :focus, :focus_by_name, :focussed?,
                    :focus_next, :focus_previous
 
+    # @!method foreground_colours
+    #   @see Vedeu::ForegroundColours.foreground_colours
+    def_delegators Vedeu::ForegroundColours, :foreground_colours
+
+    # @!method geometries
+    #   @see Vedeu::Geometries.geometries
+    def_delegators Vedeu::Geometries, :geometries
+
+    # @!method groups
+    #   @see Vedeu::Groups.groups
+    def_delegators Vedeu::Groups, :groups
+
+    # @!method interfaces
+    #   @see Vedeu::InterfacesRepository.interfaces
+    def_delegators Vedeu::InterfacesRepository, :interfaces
+
+    # @!method keymaps
+    #   @see Vedeu::Keymaps.keymaps
+    def_delegators Vedeu::Keymaps, :keymaps
+
     # @!method log
     #   @see Vedeu::Log.log
     def_delegators Vedeu::Log, :log
 
+    # @!method keypress
+    #   @see Vedeu::Mapper.keypress
+    def_delegators Vedeu::Mapper, :keypress
+
     # @!method menu
     #   @see Vedeu::Menu.menu
     def_delegators Vedeu::Menu, :menu
 
+    # @!method menus
+    #   @see Vedeu::Menus.menus
+    def_delegators Vedeu::Menus, :menus
+
+    # @!method renderer
+    #   @see Vedeu::Renderers#renderer
+    # @!method renderers
+    #   @see Vedeu::Renderers#renderers
+    def_delegators Vedeu::Renderers, :renderer, :renderers
+
     # @!method height
     #   @see Vedeu::Terminal#height
     # @!method width
@@ -161,11 +161,9 @@ module Vedeu
     #   @see Vedeu::Terminal#resize
     def_delegators Vedeu::Terminal, :height, :width, :resize
 
-    # @!method renderer
-    #   @see Vedeu::Renderers#renderer
-    # @!method renderers
-    #   @see Vedeu::Renderers#renderers
-    def_delegators Vedeu::Renderers, :renderer, :renderers
+    # @!method trigger
+    #   @see Vedeu::Trigger.trigger
+    def_delegators Vedeu::Trigger, :trigger
 
   end # API
 

data/lib/vedeu/buffers/buffer.rb

@@ -2,6 +2,14 @@ module Vedeu
 
   # The Buffer object represents the states of display for an interface. The
   # states are 'front', 'back' and 'previous'.
+  #
+  # [Back] -> [Front] -> [Previous]
+  #
+  # The content on the screen, or last output will always be the 'Front' buffer.
+  # Content due to be displayed on next refresh will come from the 'Back' buffer
+  # if available, otherwise from the current 'Front' buffer. When new content
+  # is copied to the 'Front' buffer, the current 'Front' buffer is also copied
+  # to the 'Previous' buffer.
   class Buffer
 
     include Vedeu::Model
@@ -36,17 +44,15 @@ module Vedeu
     #
     # @option attributes name [String] The name of the interface for which the
     #   buffer belongs.
-    # @option attributes back [Interface]
-    # @option attributes front [Interface]
-    # @option attributes previous [Interface]
+    # @option attributes back [Vedeu::Interface]
+    # @option attributes front [Vedeu::Interface]
+    # @option attributes previous [Vedeu::Interface]
     # @option attributes repository [Vedeu::Buffers]
     # @return [Vedeu::Buffer]
     def initialize(attributes = {})
       @attributes = defaults.merge!(attributes)
 
-      @attributes.each do |key, value|
-        instance_variable_set("@#{key}", value)
-      end
+      @attributes.each { |key, value| instance_variable_set("@#{key}", value) }
     end
 
     # Add the content to the back buffer, then update the repository.
@@ -71,6 +77,8 @@ module Vedeu
       clear_buffer
     end
 
+    # Hide this buffer.
+    #
     # @return [void]
     def hide
       return nil unless visible?
@@ -98,6 +106,8 @@ module Vedeu
     end
     alias_method :content, :render
 
+    # Show this buffer.
+    #
     # @return [void]
     def show
       return nil if visible?
@@ -108,6 +118,8 @@ module Vedeu
 
     private
 
+    # Retrieve the latest content from the buffer.
+    #
     # @return [Array<Array<Array<Vedeu::Char>>>]
     def buffer
       swap if content_for?(:back)
@@ -124,6 +136,8 @@ module Vedeu
       end
     end
 
+    # Clear the buffer.
+    #
     # @return [void]
     def clear_buffer
       @clear_buffer ||= Vedeu::Clear.new(view).clear
@@ -166,6 +180,8 @@ module Vedeu
       true
     end
 
+    # Retrieve the interface by name.
+    #
     # @return [Vedeu::Interface]
     def interface
       @interface ||= Vedeu.interfaces.by_name(name)

data/lib/vedeu/buffers/display_buffer.rb

@@ -23,7 +23,7 @@ module Vedeu
     # refresh event is triggered for the interface.
     #
     # @raise [InvalidSyntax] The name is not defined.
-    # @return [Interface]
+    # @return [Vedeu::Interface]
     def store_deferred
       unless defined_value?(name)
         fail InvalidSyntax, 'Cannot store an interface without a name.'
@@ -40,7 +40,7 @@ module Vedeu
     # and also adds interface's name to list of focussable interfaces.
     #
     # @see Vedeu::Buffer
-    # @return [Interface]
+    # @return [Vedeu::Interface]
     def store_new_buffer
       if Vedeu.buffers.registered?(name)
         Vedeu.buffers.find(name).add(self)
@@ -55,7 +55,7 @@ module Vedeu
 
     # Registers interface name in focus list unless already registered.
     #
-    # @return [Interface]
+    # @return [Vedeu::Interface]
     def store_focusable
       Vedeu.focusable.add(name) unless Vedeu.focusable.registered?(name)
 
@@ -64,20 +64,18 @@ module Vedeu
 
     # Registers a new cursor for the interface unless already registered.
     #
-    # @return [Interface]
+    # @return [Vedeu::Interface]
     def store_cursor
-      Vedeu::Cursor.new(name: name).store unless Vedeu.cursors.registered?(name)
+      Vedeu.cursors.by_name(name)
 
       self
     end
 
     # Registers a new group for the interface unless already registered.
     #
-    # @return [Interface]
+    # @return [Vedeu::Interface]
     def store_group
-      unless group.nil? || group.empty? || Vedeu.groups.registered?(group)
-        Vedeu::Group.new(members: name, name: group).store
-      end
+      Vedeu.groups.by_name(group).add(name) if group?
 
       self
     end

data/lib/vedeu/configuration/cli.rb

@@ -46,6 +46,8 @@ module Vedeu
 
       private
 
+      # Setup Vedeu using CLI configuration options for the client application.
+      #
       # @return [void]
       def setup!
         ([:banner] + allowed_options).each { |opt| send(opt) }

data/lib/vedeu/cursor/cursor.rb

@@ -100,6 +100,8 @@ module Vedeu
 
     private
 
+    # Return the position of this cursor.
+    #
     # @return [Vedeu::Position]
     def position
       @position ||= Vedeu::Position.new(y, x)

data/lib/vedeu/cursor/move.rb

@@ -133,11 +133,15 @@ module Vedeu
 
     private
 
+    # Retrieve the attributes of the cursor.
+    #
     # @return [Hash<Symbol => Fixnum, String>]
     def attributes
       cursor.attributes
     end
 
+    # Provide the new attributes for the cursor.
+    #
     # @return [Hash<Symbol => Fixnum>]
     def new_attributes
       {
@@ -148,6 +152,8 @@ module Vedeu
       }
     end
 
+    # Validates the new position of the cursor.
+    #
     # @return [PositionValidator]
     def validator
       @validator ||= Vedeu::PositionValidator.validate(name,
@@ -155,16 +161,23 @@ module Vedeu
                                                        y_position)
     end
 
+    # Returns the cursors x position based on its current offset.
+    #
     # @return [Fixnum]
     def x_position
       coordinate.x_position(ox)
     end
 
+    # Returns the cursors y position based on its current offset.
+    #
     # @return [Fixnum]
     def y_position
       coordinate.y_position(oy)
     end
 
+    # Retrieve the border for the named view: this will provide the geometry for
+    # the cursor, ensuring it displays within the interface boundaries.
+    #
     # @return (see Vedeu::Borders#by_name)
     def border
       @border ||= Vedeu.borders.by_name(name)

data/lib/vedeu/cursor/refresh_cursor.rb

@@ -44,6 +44,10 @@ module Vedeu
 
     private
 
+    # Returns true when the view should be refreshed. This is determined by
+    # checking that the offsets for x and y are outside the width and height
+    # of the named interface.
+    #
     # @return [Boolean]
     def refresh_view?
       new_cursor.ox >= width || new_cursor.oy >= height

data/lib/vedeu/dsl/composition.rb

@@ -96,6 +96,8 @@ module Vedeu
         attributes.merge!(existing_attributes(name))
       end
 
+      # Retrieve the attributes of the interface by name.
+      #
       # @param name [String] The name of the interface.
       # @return [Hash]
       def existing_attributes(name)

data/lib/vedeu/geometry/grid.rb

@@ -4,9 +4,10 @@ class Fixnum
 
   # Augment Fixnum to calculate column width in a grid-based layout.
   #
-  # The grid system splits the terminal width into 12 equal parts, by dividing
-  # the available width by 12. If the terminal width is not a multiple of 12,
-  # then Grid chooses the maximum value which will fit.
+  # The grid system splits the terminal height and width into 12 equal parts, by
+  # dividing the available height and width by 12. If the terminal height or
+  # width is not a multiple of 12, then Grid chooses the maximum value which
+  # will fit.
   #
   # Used primarily at interface creation time:
   #
@@ -17,19 +18,45 @@ class Fixnum
     Vedeu::Grid.columns(self)
   end
 
+  def rows
+    Vedeu::Grid.rows(self)
+  end
+
 end # Fixnum
 
 module Vedeu
 
-  # Divides horizontal terminal space into 12 equal columns, discarding
-  # the remainder.
+  # Augment Fixnum to calculate column width or row height in a grid-based
+  # layout.
+  #
+  # The grid system splits the terminal height and width into 12 equal parts, by
+  # dividing the available height and width by 12. If the terminal height or
+  # width is not a multiple of 12, then Grid chooses the maximum value which
+  # will fit.
+  #
+  # Used primarily whilst defining geometry:
+  #
+  #   width: 9.columns  # (Terminal width / 12) * 9 characters wide; e.g.
+  #                     # Terminal is 92 characters wide, maximum value is
+  #                     # therefore 84, meaning a column is 7 characters wide.
+  #
+  #   height: 3.columns # (Terminal height / 12) * 3 rows high; e.g.
+  #                     # Terminal is 38 characters wide, maximum value is
+  #                     # therefore 36, meaning a row is 3 characters tall.
   class Grid
 
-    # @see (#initialize)
+    # @see #initialize
+    # @see #columns
     def self.columns(value)
       new(value).columns
     end
 
+    # @see #initialize
+    # @see #rows
+    def self.rows(value)
+      new(value).rows
+    end
+
     # Returns a new instance of Vedeu::Grid.
     #
     # @param value [Fixnum]
@@ -38,6 +65,8 @@ module Vedeu
       @value = value
     end
 
+    # Returns the width in characters for the number of columns specified.
+    #
     # @raise [OutOfRange] When the value parameter is not between 1 and 12
     #   inclusive.
     # @return [Fixnum|OutOfRange]
@@ -48,6 +77,34 @@ module Vedeu
       column * value
     end
 
+    # Returns the height of a single row in characters.
+    #
+    # @return [Fixnum]
+    def height
+      actual_height / 12
+    end
+    alias_method :row, :height
+
+    # Returns the height in characters for the number of rows specified.
+    #
+    # @raise [OutOfRange] When the value parameter is not between 1 and 12
+    #   inclusive.
+    # @return [Fixnum|OutOfRange]
+    def rows
+      fail OutOfRange,
+           'Valid value between 1 and 12 inclusive.' if out_of_range?
+
+      row * value
+    end
+
+    # Returns the width of a single column in characters.
+    #
+    # @return [Fixnum]
+    def width
+      actual_width / 12
+    end
+    alias_method :column, :width
+
     protected
 
     # @!attribute [r] value
@@ -56,15 +113,13 @@ module Vedeu
 
     private
 
-    # Returns the width of a single column in characters.
-    #
     # @return [Fixnum]
-    def column
-      actual / 12
+    def actual_height
+      Vedeu::Terminal.height
     end
 
     # @return [Fixnum]
-    def actual
+    def actual_width
       Vedeu::Terminal.width
     end