Merge pull request #304 from gavinlaking/twerks

Refactoring, bugfixes and more documentation.

docs/events/view.md

@@ -11,6 +11,26 @@ Maximising an interface.
 
 See {Vedeu::Geometry::Geometry#maximise}
 
+### `:\_movement_refresh\_`
+When triggered, triggers additional events which aid the updating of
+the output. Used when moving an interface/view.
+
+    Vedeu.trigger(:_movement_refresh_, name)
+
+At this time, triggering this event will:
+
+- Clear the entire terminal (assuming at least one renderer is the
+  default (Vedeu::Renderer::Terminal)). This action is performed when
+  moving an interface/view so that there are no 'artefacts' left
+  behind.
+- Refresh the entire terminal (as above). This means all visible
+  interfaces are re-rendered. This action is performed to ensure other
+  views currently visible are rendered in their current position.
+- Clears the named view. This action removes the named view from the
+  terminal (or output).
+- Refreshes the named view. This action adds the named view to the
+  terminal (or output); in the new position.
+
 ### `:\_resize\_`
 When triggered will cause Vedeu to trigger the `:_clear_` and
 `:_refresh_` events. Please see those events for their behaviour.

docs/output.md

@@ -1,2 +1,4 @@
 # @title Vedeu Output
 # Vedeu Output
+
+More coming soon.

lib/vedeu/borders/null.rb

@@ -5,6 +5,8 @@ module Borders
     # Provides a non-existent Vedeu::Borders::Border that acts like
     # the real thing, but does nothing.
     #
+    # @api private
+    #
     class Null
 
       # @!attribute [r] name

lib/vedeu/borders/refresh.rb

@@ -4,6 +4,8 @@ module Borders
 
     # Renders and refreshes the named border.
     #
+    # @api private
+    #
     class Refresh
 
       extend Forwardable

lib/vedeu/borders/title.rb

@@ -6,6 +6,8 @@ module Borders
     # title is longer than the interface is wide, and pad with a space
     # either side.
     #
+    # @api private
+    #
     class Title
 
       # @param value [String|Vedeu::Borders::Title|
@@ -129,6 +131,8 @@ def width
     # the caption is longer than the interface is wide, and pad with a
     # space either side.
     #
+    # @api private
+    #
     class Caption < Title
 
     end # Caption

lib/vedeu/buffers/null.rb

@@ -5,6 +5,8 @@ module Buffers
     # Provides a non-existent Vedeu::Buffers::Buffer that acts like
     # the real thing, but does nothing.
     #
+    # @api private
+    #
     class Null < Vedeu::Null::Generic
 
     end # Null

lib/vedeu/colours/background.rb

@@ -6,6 +6,8 @@ module Colours
     # {Vedeu::Colours::Foreground}) of a terminal colour escape
     # sequence.
     #
+    # @api private
+    #
     class Background < Vedeu::Colours::Translator
 
       private

lib/vedeu/colours/foreground.rb

@@ -6,6 +6,8 @@ module Colours
     # {Vedeu::Colours::Background}) of a terminal colour escape
     # sequence.
     #
+    # @api private
+    #
     class Foreground < Vedeu::Colours::Translator
 
       private

lib/vedeu/colours/translator.rb

@@ -26,6 +26,8 @@ module Colours
     #
     # @todo More documentation required (create a fancy chart!)
     #
+    # @api private
+    #
     class Translator
 
       # @!attribute [r] colour

lib/vedeu/common.rb

@@ -2,6 +2,8 @@ module Vedeu
 
   # A module for common methods used throughout Vedeu.
   #
+  # @api private
+  #
   module Common
 
     # Returns a boolean indicating whether a variable is nil or empty.

lib/vedeu/configuration/api.rb

@@ -221,8 +221,11 @@ def raw!
       # setting is for debugging to be disabled. Using `debug!` or
       # setting `debug` to true will enable debugging.
       #
-      # At this time, debugging only toggles between viewing a full
-      # backtrace (true) upon exception or only its top line (false).
+      # Enabling debugging will:
+      # - Enable `Vedeu::Logging::Timer` meaning various timing
+      #   information is output to the log file.
+      # - Produce a full a backtrace to STDOUT and the log file upon
+      #   unrecoverable error or unhandled exception.
       #
       #   Vedeu.configure do
       #     debug!
@@ -516,9 +519,9 @@ def width(width = 80)
       def background(value = nil)
         return options[:background] unless value
 
-        new_background = Vedeu::Colours::Background.coerce(value)
+        bg = Vedeu::Colours::Background.coerce(value)
 
-        options[:background] = colour_attributes(background: new_background)
+        options[:background] = colour_attributes(background: bg)
                                .fetch(:background)
       end
 
@@ -534,9 +537,9 @@ def background(value = nil)
       def foreground(value = nil)
         return options[:foreground] unless value
 
-        new_foreground = Vedeu::Colours::Foreground.coerce(value)
+        fg = Vedeu::Colours::Foreground.coerce(value)
 
-        options[:foreground] = colour_attributes(foreground: new_foreground)
+        options[:foreground] = colour_attributes(foreground: fg)
                                .fetch(:foreground)
       end
 

lib/vedeu/cursors/cursor.rb

@@ -5,6 +5,8 @@ module Cursors
     # Each interface has its own Cursor which maintains the position
     # and visibility of the cursor within that interface.
     #
+    # @api private
+    #
     class Cursor
 
       include Vedeu::Repositories::Model

lib/vedeu/cursors/refresh.rb

@@ -6,6 +6,8 @@ module Cursors
     # the whole interface; unless the cursor's offset has caused the
     # view to change.
     #
+    # @api private
+    #
     class Refresh
 
       extend Forwardable

lib/vedeu/cursors/reposition.rb

@@ -4,6 +4,8 @@ module Cursors
 
     # Arbitrarily move the cursor to a given position.
     #
+    # @api private
+    #
     class Reposition
 
       # Returns a new instance of Vedeu::Cursors::Reposition.

lib/vedeu/editor/capture.rb

@@ -52,27 +52,20 @@ def keys
           end
         end
 
-        if keys.start_with?("\e[M")
-          button, x, y = keys.chars[3..-1].map { |c| c.ord - 32 }
-
-          Vedeu.log(type:    :input,
-                    message: "Mouse pressed: '#{button}' (x: #{x}, y: #{y})")
-
-          if button == 0 # left mouse button
-            Vedeu.trigger(:_cursor_reposition_, Vedeu.focus, y, x)
-
-          elsif button == 64 # scroll wheel up
-            Vedeu.trigger(:_cursor_up_, Vedeu.focus)
-
-          elsif button == 65 # scroll wheel down
-            Vedeu.trigger(:_cursor_down_, Vedeu.focus)
-
-          end
-        end
+        return Vedeu::Input::Mouse.click(keys) if click?(keys)
 
         keys
       end
 
+      # Returns a boolean indicating whether a mouse click was
+      # received.
+      #
+      # @param keys [String]
+      # @return [Boolean]
+      def click?(keys)
+        keys.start_with?("\e[M")
+      end
+
       # @return [IO]
       def console
         @console || Vedeu::Terminal.console

lib/vedeu/editor/cropper.rb

@@ -5,6 +5,8 @@ module Editor
     # Crop the lines to the visible area of the document, as defined
     # by the geometry provided.
     #
+    # @api private
+    #
     class Cropper
 
       extend Forwardable

lib/vedeu/editor/cursor.rb

@@ -5,6 +5,8 @@ module Editor
     # Maintains a cursor position within the {Vedeu::Editor::Document}
     # class.
     #
+    # @api private
+    #
     class Cursor
 
       extend Forwardable

lib/vedeu/editor/delete.rb

@@ -4,6 +4,8 @@ module Editor
 
     # Manipulate the lines of an Vedeu::Editor::Document.
     #
+    # @api private
+    #
     class Delete
 
       # @param (see #initialize)

lib/vedeu/editor/document.rb

@@ -4,6 +4,8 @@ module Editor
 
     # A collection of keypresses ordered by input.
     #
+    # @api private
+    #
     class Document
 
       include Vedeu::Repositories::Model
@@ -37,6 +39,11 @@ def self.store(attributes = {})
 
       # Returns a new instance of Vedeu::Editor::Document.
       #
+      # @note
+      #   If a particular key is missing from the attributes
+      #   parameter, then it is added with the respective value from
+      #   #defaults.
+      #
       # @param attributes [Hash]
       # @option attributes data [String]
       # @option attributes name [String|Symbol]

lib/vedeu/editor/insert.rb

@@ -4,6 +4,8 @@ module Editor
 
     # Manipulate the lines of an Vedeu::Editor::Document.
     #
+    # @api private
+    #
     class Insert
 
       # @param (see #initialize)

lib/vedeu/editor/item.rb

@@ -4,6 +4,8 @@ module Editor
 
     # Fetches an item from a collection.
     #
+    # @api private
+    #
     class Item
 
       # @param collection [Vedeu::Editor::Line|Vedeu::Editor::Lines]

lib/vedeu/editor/line.rb

@@ -4,6 +4,8 @@ module Editor
 
     # Manipulate a single line of an Vedeu::Editor::Document.
     #
+    # @api private
+    #
     class Line
 
       # @!attribute [rw] line

lib/vedeu/editor/lines.rb

@@ -4,6 +4,8 @@ module Editor
 
     # Manipulate the lines of an Vedeu::Editor::Document.
     #
+    # @api private
+    #
     class Lines
 
       include Enumerable

lib/vedeu/error.rb

@@ -3,6 +3,8 @@ module Vedeu
   # Custom exceptions/errors which Vedeu will raise in certain
   # circumstances.
   #
+  # @api private
+  #
   module Error
 
     # Raised with Vedeu attempts to access a client application

lib/vedeu/events/trigger.rb

@@ -38,6 +38,9 @@ def initialize(name, *args)
       #
       # @return [Array]
       def trigger
+        Vedeu.log(type:    :event,
+                  message: "No action for: '#{name.inspect}'") if results.empty?
+
         return results[0] if results.one?
 
         results

lib/vedeu/geometry/alignment.rb

@@ -10,6 +10,8 @@ module Geometry
     # @see Vedeu::Geometry::HorizontalAlignment
     # @see Vedeu::Geometry::VerticalAlignment
     #
+    # @api private
+    #
     class Alignment
 
       # @param (see #initialize)

lib/vedeu/geometry/area.rb

@@ -4,6 +4,8 @@ module Geometry
 
     # Define an area from dimensions or points.
     #
+    # @api private
+    #
     class Area
 
       # @!attribute [r] y

lib/vedeu/geometry/coordinate.rb

@@ -4,6 +4,8 @@ module Geometry
 
     # Crudely corrects out of range values.
     #
+    # @api private
+    #
     class Coordinate
 
       # Return a new instance of Vedeu::Geometry::Coordinate.

lib/vedeu/geometry/dimension.rb

@@ -4,6 +4,8 @@ module Geometry
 
     # A Dimension is either the height or width of an entity.
     #
+    # @api private
+    #
     class Dimension
 
       extend Forwardable

lib/vedeu/geometry/grid.rb

@@ -7,6 +7,8 @@ module Geometry
     # If the terminal height or width is not a multiple of 12, then
     # Grid chooses the maximum value which will fit.
     #
+    # @api private
+    #
     class Grid
 
       # @see #initialize

lib/vedeu/geometry/horizontal_alignment.rb

@@ -5,6 +5,8 @@ module Geometry
     # Provides the mechanism to align an interface/view horizontally
     # within the available terminal space.
     #
+    # @api private
+    #
     class HorizontalAlignment < Vedeu::Geometry::Alignment
 
       # @raise [Vedeu::Error::InvalidSyntax] When the value is not one

lib/vedeu/geometry/null.rb

@@ -4,6 +4,8 @@ module Geometry
 
     # Provides a non-existent model to swallow messages.
     #
+    # @api private
+    #
     class Null < Vedeu::Null::Generic
 
       extend Forwardable

lib/vedeu/geometry/position.rb

@@ -5,6 +5,8 @@ module Geometry
     # Change coordinates into an escape sequence to set the cursor
     # position.
     #
+    # @api private
+    #
     class Position
 
       # @!attribute [r] y

lib/vedeu/geometry/repository.rb

@@ -33,6 +33,7 @@ class Repository < Vedeu::Repositories::Repository
     Vedeu.geometries.by_name(name).maximise
   end
 
+  # See {file:docs/events/view.md#\_movement_refresh_}
   Vedeu.bind(:_movement_refresh_) do |name|
     Vedeu.trigger(:_clear_)
     Vedeu.trigger(:_refresh_)