vedeu 0.4.8 → 0.4.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7649a91c05398be50b8403bf37f0f2f46fbd0317
-  data.tar.gz: 2b8f063515e7ae529fc2877ebcf482d821cebbc0
+  metadata.gz: 2f8e55b96180371a74727bb5684f829aea4fb3ae
+  data.tar.gz: d3bbd55216ffff82ebf2007cd7616228be86e155
 SHA512:
-  metadata.gz: 00be70e455d52864393e79a59f678b3d3d308370eadba24d74cf1ce216b4c84c25859cce8ae33ce43d151bd0173b8c7f555fe4e0455c916a0fa33ed671077b3a
-  data.tar.gz: 2d82fcc1f9ee603023b99c4d1b4a7bde1c9b02578bb68feeac24a1fdaf6e41ddb98845c8336a883a04be5ec3d40fbed5de3202e50449c3052ea9d36895cdb5e7
+  metadata.gz: 52b9ca57b1f4258a516e236a49e42840665bb4f40352e8d7b562de206eb1a23340fe4be40acfe02d41a28618db3e36a8841964d2a1fa2c3108bd841bdb6aa29f
+  data.tar.gz: b5caa9c02529b83537e2894d4fbc287beedef7c1cbcd7de1bc5d2eafb178d225ec9709c14fda5a8872bd2760f04c3df0ed2a95051e8fc1a8ebe1002506ff8b4e

data/README.md

@@ -176,7 +176,9 @@ Pull requests are very welcome! Please try to follow these simple rules if appli
 * Update the [README](https://github.com/gavinlaking/vedeu/blob/master/README.md).
 * Please **do not change** the version number.
 
-Any branch on the repository that is not `master` is probably experimental; do not rely on anything in these branches.
+Any branch on the repository that is not `master` is probably experimental; do not rely on anything in these branches. Typically, `twerks` will be merged into `master` before a release,
+and branches prefixed with `spike/` are me playing with ideas.
+
 
 ### General contribution help
 

data/docs/object_graph.md

@@ -0,0 +1,14 @@
+## Producing an object graph of Vedeu
+
+Sometimes I find looking at the project as a graph helps me to understand the
+relationship between the various objects. To achieve this, I use Yard's graph
+options. If this sort of thing floats your boat too, and you have the
+appropriate software installed:
+
+```shell
+yard graph --full --dependencies --private --protected --dot --file vedeu.dot
+
+dot -Tpdf vedeu.dot -o vedeu.pdf
+```
+
+Cool stuff.

data/examples/borders_app.rb

@@ -28,7 +28,7 @@ class VedeuBordersApp
 
   interface 'border_off' do
     geometry do
-      x      13
+      x      14
       y      2
       height 4
       width  10
@@ -38,7 +38,7 @@ class VedeuBordersApp
 
   interface 'no_top' do
     geometry do
-      x      24
+      x      26
       y      2
       height 4
       width  10
@@ -48,7 +48,7 @@ class VedeuBordersApp
 
   interface 'no_bottom' do
     geometry do
-      x      35
+      x      38
       y      2
       height 4
       width  10
@@ -58,7 +58,7 @@ class VedeuBordersApp
 
   interface 'no_left' do
     geometry do
-      x      46
+      x      50
       y      2
       height 4
       width  10
@@ -68,7 +68,7 @@ class VedeuBordersApp
 
   interface 'no_right' do
     geometry do
-      x      57
+      x      62
       y      2
       height 4
       width  10
@@ -79,7 +79,7 @@ class VedeuBordersApp
   interface 'custom_corners' do
     geometry do
       x      2
-      y      7
+      y      8
       height 4
       width  10
     end
@@ -88,8 +88,8 @@ class VedeuBordersApp
 
   interface 'custom_sides' do
     geometry do
-      x      13
-      y      7
+      x      14
+      y      8
       height 4
       width  10
     end
@@ -98,8 +98,8 @@ class VedeuBordersApp
 
   interface 'only_top' do
     geometry do
-      x      24
-      y      7
+      x      26
+      y      8
       height 4
       width  10
     end
@@ -108,8 +108,8 @@ class VedeuBordersApp
 
   interface 'only_bottom' do
     geometry do
-      x      35
-      y      7
+      x      38
+      y      8
       height 4
       width  10
     end
@@ -118,8 +118,8 @@ class VedeuBordersApp
 
   interface 'only_left' do
     geometry do
-      x      46
-      y      7
+      x      50
+      y      8
       height 4
       width  10
     end
@@ -128,8 +128,8 @@ class VedeuBordersApp
 
   interface 'only_right' do
     geometry do
-      x      57
-      y      7
+      x      62
+      y      8
       height 4
       width  10
     end
@@ -139,7 +139,7 @@ class VedeuBordersApp
   interface 'custom_colour' do
     geometry do
       x      2
-      y      12
+      y      14
       height 4
       width  10
     end
@@ -148,8 +148,8 @@ class VedeuBordersApp
 
   interface 'negative' do
     geometry do
-      x      13
-      y      12
+      x      14
+      y      14
       height 4
       width  10
     end

data/lib/vedeu/api.rb

@@ -14,6 +14,19 @@ module Vedeu
   # Provides the API to Vedeu. Methods therein, and classes belonging to this
   # module expose Vedeu's core functionality.
   #
+  # These methods are used in a variety of ways, sometimes in combination:
+  #
+  #   # with parameters
+  #   Vedeu.method_name(*params)
+  #
+  #   # with a block
+  #   Vedeu.method_name(*params) do
+  #     # ...
+  #   end
+  #
+  #   # with other methods
+  #   Vedeu.method_name.other_method
+  #
   # @api public
   #
   module API
@@ -21,35 +34,134 @@ module Vedeu
     extend Forwardable
     extend self
 
-    def_delegators Vedeu::Borders,       :borders
-    def_delegators Vedeu::Buffers,       :buffers
-    def_delegators Vedeu::Canvas,        :canvas
-    def_delegators Vedeu::Cursors,       :cursors
-    def_delegators Vedeu::Cursors,       :cursor
+    # @!method borders
+    #   @see Vedeu::Borders.borders
+    def_delegators Vedeu::Borders, :borders
+
+    # @!method buffers
+    #   @see Vedeu::Buffers.buffers
+    def_delegators Vedeu::Buffers, :buffers
+
+    # @!method canvas
+    #   @see Vedeu::Canvas.canvas
+    def_delegators Vedeu::Canvas, :canvas
+
+    # @!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
-    def_delegators Vedeu::Geometries,    :geometries
-    def_delegators Vedeu::Groups,        :groups
+
+    # @!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
 
-    def_delegators Vedeu::Keymaps,       :keymaps
-    def_delegators Vedeu::Mapper,        :keypress
-    def_delegators Vedeu::Menus,         :menus
+    # @!method keymaps
+    #   @see Vedeu::Keymaps.keymaps
+    def_delegators Vedeu::Keymaps, :keymaps
 
-    def_delegators Vedeu::Event,         :bind, :trigger, :unbind
-    def_delegators Vedeu::Configuration, :configure, :configuration
-    def_delegators Vedeu::DSL::Border,   :border
+    # @!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 trigger
+    #   @see Vedeu::Event.trigger
+    # @!method unbind
+    #   @see Vedeu::Event.unbind
+    def_delegators Vedeu::Event, :bind,
+      :trigger,
+      :unbind
+
+    # @!method configure
+    #   @see Vedeu::Configuration.configure
+    # @!method configuration
+    #   @see Vedeu::Configuration.configuration
+    def_delegators Vedeu::Configuration, :configure,
+      :configuration
+
+    # @!method border
+    #   @see Vedeu::DSL::Border.border
+    def_delegators Vedeu::DSL::Border, :border
+
+    # @!method geometry
+    #   @see Vedeu::DSL::Geometry.geometry
     def_delegators Vedeu::DSL::Geometry, :geometry
-    def_delegators Vedeu::DSL::Keymap,   :keymap
-    def_delegators Vedeu::DSL::Group,    :group
-    def_delegators Vedeu::DSL::Use,      :use
-    def_delegators Vedeu::DSL::View,     :interface, :renders, :views
 
-    def_delegators Vedeu::Focus,         :focus, :focus_by_name, :focussed?,
-                                         :focus_next, :focus_previous
+    # @!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 use
+    #   @see Vedeu::DSL::Use#use
+    def_delegators Vedeu::DSL::Use, :use
+
+    # @!method interface
+    #   @see Vedeu::DSL::View.interface
+    # @!method renders
+    #   @see Vedeu::DSL::View.renders
+    # @!method views
+    #   @see Vedeu::DSL::View.views
+    def_delegators Vedeu::DSL::View, :interface,
+      :renders,
+      :views
+
+    # @!method focus
+    #   @see Vedeu::Focus#focus
+    # @!method focus_by_name
+    #   @see Vedeu::Focus#focus_by_name
+    # @!method focussed?
+    #   @see Vedeu::Focus#focussed?
+    # @!method focus_next
+    #   @see Vedeu::Focus#focus_next
+    # @!method focus_previous
+    #   @see Vedeu::Focus#focus_previous
+    def_delegators Vedeu::Focus, :focus,
+      :focus_by_name,
+      :focussed?,
+      :focus_next,
+      :focus_previous
+
+    # @!method log
+    #   @see Vedeu::Log.log
+    def_delegators Vedeu::Log, :log
+
+    # @!method menu
+    #   @see Vedeu::Menu.menu
+    def_delegators Vedeu::Menu, :menu
 
-    def_delegators Vedeu::Log,           :log
-    def_delegators Vedeu::Menu,          :menu
-    def_delegators Vedeu::Terminal,      :height, :width, :resize
+    # @!method height
+    #   @see Vedeu::Terminal#height
+    # @!method width
+    #   @see Vedeu::Terminal#width
+    # @!method resize
+    #   @see Vedeu::Terminal#resize
+    def_delegators Vedeu::Terminal, :height,
+      :width,
+      :resize
 
   end # API
 

data/lib/vedeu/buffers/buffer.rb

@@ -5,25 +5,27 @@ module Vedeu
   # The Buffer object represents the states of display for an interface. The
   # states are 'front', 'back' and 'previous'.
   #
-  # - 'front':    The currently displayed buffer; contains the content which was
-  #               last output.
-  # - 'back':     The next buffer to be displayed; contains the content which
-  #               will be shown on next refresh.
-  # - 'previous': The previous buffer which was displayed; contains the content
-  #               that was shown before 'front'.
-  #
   class Buffer
 
     include Vedeu::Model
 
+    # The next buffer to be displayed; contains the content which will be shown
+    # on next refresh.
+    #
     # @!attribute [rw] back
     # @return [Interface]
     attr_accessor :back
 
+    # The currently displayed buffer, contains the content which was last
+    # output.
+    #
     # @!attribute [rw] front
     # @return [Interface]
     attr_accessor :front
 
+    # The previous buffer which was displayed; contains the content that was
+    # shown before 'front'.
+    #
     # @!attribute [rw] previous
     # @return [Interface]
     attr_accessor :previous
@@ -32,7 +34,8 @@ module Vedeu
     # @return [String]
     attr_reader :name
 
-    # Return a new instance of Buffer.
+    # Return a new instance of Buffer. Generally a Buffer is initialized with
+    # only a 'name' and 'back' parameter.
     #
     # @param name [String] The name of the interface for which the buffer
     #   belongs.

data/lib/vedeu/cursor/cursor.rb

@@ -11,7 +11,8 @@ module Vedeu
 
     extend Forwardable
 
-    def_delegators :state, :visible?, :invisible?
+    def_delegators :state, :visible?,
+      :invisible?
 
     include Vedeu::Model
 

data/lib/vedeu/dsl/shared/colour.rb

@@ -17,7 +17,7 @@ module Vedeu
       # @note The last defined background colour for a particular interface,
       #   line or stream overrides previously defined entries in the same block.
       #
-      # @param value [String]
+      # @param value [String] A HTML/CSS value.
       #
       # @example
       #   interface 'my_interface' do

data/lib/vedeu/geometry/area.rb

@@ -5,22 +5,22 @@ module Vedeu
   class Area
 
     # @!attribute [r] y
-    # @return [Fixnum]
+    # @return [Fixnum] Returns the top coordinate of the interface.
     attr_reader :y
     alias_method :top, :y
 
     # @!attribute [r] yn
-    # @return [Fixnum]
+    # @return [Fixnum] Returns the bottom coordinate of the interface.
     attr_reader :yn
     alias_method :bottom, :yn
 
     # @!attribute [r] x
-    # @return [Fixnum]
+    # @return [Fixnum] Returns the left coordinate of the interface.
     attr_reader :x
     alias_method :left, :x
 
     # @!attribute [r] xn
-    # @return [Fixnum]
+    # @return [Fixnum] Returns the right coordinate of the interface.
     attr_reader :xn
     alias_method :right, :xn
 
@@ -53,12 +53,6 @@ module Vedeu
       @y, @yn, @x, @xn  = y, yn, x, xn
     end
 
-    # @param other [Vedeu::Area]
-    # @return [Boolean]
-    def ==(other)
-      eql?(other)
-    end
-
     # @param other [Vedeu::Area]
     # @return [Boolean]
     def eql?(other)
@@ -68,6 +62,7 @@ module Vedeu
       x          == other.x     &&
       xn         == other.xn
     end
+    alias_method :==, :eql?
 
     # @return [Array<Fixnum>]
     def centre
@@ -76,12 +71,22 @@ module Vedeu
 
     # @return [Fixnum]
     def centre_y
-      ((yn - y) / 2) + y
+      (height / 2) + y
     end
 
     # @return [Fixnum]
     def centre_x
-      ((xn - x) / 2) + x
+      (width / 2) + x
+    end
+
+    # @return [Fixnum]
+    def height
+      (y..yn).size
+    end
+
+    # @return [Fixnum]
+    def width
+      (x..xn).size
     end
 
     # Returns the row above the top by default.
@@ -90,8 +95,8 @@ module Vedeu
     #   `top` / `y` is 4.
     #
     #   north     # => 3
-    #   north(2)  # => 2
-    #   north(-4) # => 8
+    #   north(2)  # => 2 (positive goes north)
+    #   north(-4) # => 8 (negative goes south)
     #
     # @param offset [Fixnum]
     # @return [Fixnum]
@@ -105,8 +110,8 @@ module Vedeu
     #   `right` / `xn` is 19.
     #
     #   east     # => 20
-    #   east(2)  # => 21
-    #   east(-4) # => 15
+    #   east(2)  # => 21 (positive goes east)
+    #   east(-4) # => 15 (negative goes west)
     #
     # @param offset [Fixnum]
     # @return [Fixnum]
@@ -120,8 +125,8 @@ module Vedeu
     #   `bottom` / `yn` is 12.
     #
     #   south     # => 13
-    #   south(2)  # => 14
-    #   south(-4) # => 8
+    #   south(2)  # => 14 (positive goes south)
+    #   south(-4) # => 8  (negative goes north)
     #
     # @param offset [Fixnum]
     # @return [Fixnum]
@@ -135,8 +140,8 @@ module Vedeu
     #   `left` / `x` is 8.
     #
     #   west      # => 7
-    #   west(2)   # => 6
-    #   west(-4)  # => 12
+    #   west(2)   # => 6  (positive goes west)
+    #   west(-4)  # => 12 (negative goes east)
     #
     # @param offset [Fixnum]
     # @return [Fixnum]