vedeu 0.8.7 → 0.8.8

data/lib/vedeu/cursors/reposition.rb

@@ -67,8 +67,8 @@ module Vedeu
 
       # Determine correct x and y related coordinates.
       #
-      # @param offset []
-      # @param type []
+      # @param offset [Fixnum]
+      # @param type [Symbol]
       # @return [Vedeu::Cursors::Coordinate]
       def coordinate(offset, type)
         Vedeu::Cursors::Coordinate.new(name:   name,

data/lib/vedeu/cursors/repository.rb

@@ -12,11 +12,7 @@ module Vedeu
 
       class << self
 
-        # Fetch the cursor of the currently focussed interface/view.
-        #
-        # @example
-        #   Vedeu.cursor
-        #
+        # {include:file:docs/dsl/by_method/cursor.md}
         # @return [NilClass|Vedeu::Cursors::Cursor]
         def cursor
           cursors.by_name
@@ -37,17 +33,16 @@ module Vedeu
 
   end # Cursors
 
-  # Manipulate the repository of cursors.
-  #
-  # @example
-  #   Vedeu.cursors
-  #
+  # {include:file:docs/dsl/by_method/cursors.md}
   # @!method cursors
   #   @return [Vedeu::Cursors::Repository]
+  def_delegators Vedeu::Cursors::Repository,
+                 :cursors
+
+  # {include:file:docs/dsl/by_method/cursor.md}
   # @!method cursor
   #   @see Vedeu::Cursors::Repository.cursor
   def_delegators Vedeu::Cursors::Repository,
-                 :cursor,
-                 :cursors
+                 :cursor
 
 end # Vedeu

data/lib/vedeu/dsl/elements.rb

@@ -167,7 +167,6 @@ module Vedeu
             else
               s  = Vedeu::Views::Stream.new(attrs)
               ss = Vedeu::Views::Streams.coerce([s])
-
               Vedeu::Views::Line.new(attrs.merge!(value: ss))
 
             end

data/lib/vedeu/error.rb

@@ -24,11 +24,18 @@ module Vedeu
     end # ControllerNotFound
 
     # Raised when Vedeu encounters an error it cannot recover from.
-    # This would happen if there was not interfaces, or specifically
-    # if there were no entries in {Vedeu::Models::Focus}, since the
-    # fallback for most of the system when a name is not given or
-    # cannot be found is to use the name of the currently focussed
-    # interface.
+    # Generally, all Vedeu exceptions are fatal- however, fatal here
+    # means that it is not known how to recover from an error.
+    #
+    # If you encounter a `Vedeu::Error::Fatal` error and the error
+    # message is insufficient to help you, please raise an issue so
+    # that we can attempt to accommodate your intentions.
+    #
+    # An example of this would happen if there was no interfaces, or
+    # specifically if there were no entries in {Vedeu::Models::Focus},
+    # since the fallback for most of the system when a name is not
+    # given or cannot be found is to use the name of the currently
+    # focussed interface.
     #
     class Fatal < StandardError
 
@@ -105,6 +112,11 @@ module Vedeu
     #
     # @see Vedeu::Geometries::Grid
     #
+    # @!macro [new] raise_out_of_range
+    #   @raise [Vedeu::Error::OutOfRange] When the value given for
+    #     an argument or parameter cannot be used because it is
+    #     outside the allowed range.
+    #
     class OutOfRange < StandardError
 
       # Returns an error message.

data/lib/vedeu/geometries/dsl/dsl.rb

@@ -139,10 +139,6 @@ module Vedeu
       #     # ... some code
       #   end
       #
-      # @note
-      #   Vedeu.width in the example above will set the width to the
-      #   default width of the terminal, this can be substituted for
-      #   your own positive integer.
       # @param height [Fixnum] The number of lines/rows.
       # @return [Vedeu::Geometries::Geometry]
       def align_bottom(height = nil)
@@ -166,10 +162,6 @@ module Vedeu
       #
       #   # Also allows `align_center` if preferred.
       #
-      # @note
-      #   Vedeu.height in the example above will set the height to the
-      #   default height of the terminal, this can be substituted for
-      #   your own positive integer.
       # @param width [Fixnum] The number of characters/columns.
       # @return [Vedeu::Geometries::Geometry]
       def align_centre(width = nil)
@@ -192,10 +184,6 @@ module Vedeu
       #     # ... some code
       #   end
       #
-      # @note
-      #   Vedeu.height in the example above will set the height to the
-      #   default height of the terminal, this can be substituted for
-      #   your own positive integer.
       # @param width [Fixnum] The number of characters/columns.
       # @return [Vedeu::Geometries::Geometry]
       def align_left(width = nil)
@@ -218,10 +206,6 @@ module Vedeu
       #     # ... some code
       #   end
       #
-      # @note
-      #   Vedeu.width in the example above will set the width to the
-      #   default width of the terminal, this can be substituted for
-      #   your own positive integer.
       # @param height [Fixnum] The number of lines/rows.
       # @return [Vedeu::Geometries::Geometry]
       def align_middle(height = nil)
@@ -243,10 +227,6 @@ module Vedeu
       #     # ... some code
       #   end
       #
-      # @note
-      #   Vedeu.height in the example above will set the height to the
-      #   default height of the terminal, this can be substituted for
-      #   your own positive integer.
       # @param width [Fixnum] The number of characters/columns.
       # @return [Vedeu::Geometries::Geometry]
       def align_right(width = nil)
@@ -269,10 +249,6 @@ module Vedeu
       #     # ... some code
       #   end
       #
-      # @note
-      #   Vedeu.width in the example above will set the width to the
-      #   default width of the terminal, this can be substituted for
-      #   your own positive integer.
       # @param height [Fixnum] The number of lines/rows.
       # @return [Vedeu::Geometries::Geometry]
       def align_top(height = nil)
@@ -291,8 +267,7 @@ module Vedeu
       #   end
       #
       # @param value [Fixnum]
-      # @raise [Vedeu::Error::OutOfRange] When the value parameter is
-      #   not between 1 and 12 inclusive.
+      # @macro raise_out_of_range
       # @return [Fixnum|Vedeu::Error::OutOfRange]
       def columns(value)
         Vedeu::Geometries::Grid.columns(value)
@@ -325,8 +300,7 @@ module Vedeu
       #   end
       #
       # @param value [Fixnum]
-      # @raise [Vedeu::Error::OutOfRange] When the value parameter is
-      #   not between 1 and 12 inclusive.
+      # @macro raise_out_of_range
       # @return [Fixnum]
       def rows(value)
         Vedeu::Geometries::Grid.rows(value)

data/lib/vedeu/geometries/dsl/grid.rb

@@ -33,6 +33,7 @@ module Vedeu
         @value = value
       end
 
+      # @macro raise_out_of_range
       # @see Vedeu::Geometries::DSL#columns
       def columns
         fail Vedeu::Error::OutOfRange if out_of_range?
@@ -40,6 +41,7 @@ module Vedeu
         column * value
       end
 
+      # @macro raise_out_of_range
       # @see Vedeu::Geometries::DSL#rows
       def rows
         fail Vedeu::Error::OutOfRange if out_of_range?

data/lib/vedeu/geometries/geometry.rb

@@ -147,12 +147,7 @@ module Vedeu
       end
       alias == eql?
 
-      # Will maximise the named interface geometry. This means it will
-      # occupy all of the available space on the terminal window.
-      #
-      # @example
-      #   Vedeu.trigger(:_maximise_, name)
-      #
+      # {include:file:docs/events/by_name/maximise.md}
       # @return [Vedeu::Geometries::Geometry|NilClass]
       def maximise
         return self if maximised?
@@ -165,15 +160,7 @@ module Vedeu
         end
       end
 
-      # Will unmaximise the named interface geometry. Previously, when
-      # a geometry was maximised, then triggering the unmaximise event
-      # will return it to its usual defined size (terminal size
-      # permitting: when the terminal has been resized, then the new
-      # geometry size should adapt).
-      #
-      # @example
-      #   Vedeu.trigger(:_unmaximise_, name)
-      #
+      # {include:file:docs/events/by_name/unmaximise.md}
       # @return [Vedeu::Geometries::Geometry|NilClass]
       def unmaximise
         return self unless maximised?
@@ -183,18 +170,11 @@ module Vedeu
         store do
           Vedeu.trigger(:_clear_)
           Vedeu.trigger(:_refresh_)
-          Vedeu.trigger(:_refresh_view_, name)
         end
       end
 
       private
 
-      # @todo Investigate the differences between memoizing this and
-      #   not memoizing. Memoizing saves ~80ms on running test suite
-      #   and considerably impacts app responsiveness, however changes
-      #   to the geometry (such as movement or maximising) are not
-      #   reflected. (GL: 2016-01-11)
-      #
       # @return [Vedeu::Geometries::Area]
       def area
         Vedeu::Geometries::Area.from_attributes(area_attributes)

data/lib/vedeu/geometries/move.rb

@@ -41,7 +41,7 @@ module Vedeu
 
         Vedeu::Geometries::Geometry.store(new_attributes) do
           update_cursor!
-          refresh!
+          Vedeu.trigger(:_movement_refresh_, name)
         end
       end
 
@@ -87,7 +87,7 @@ module Vedeu
       end
 
       # @return [Hash<Symbol => Symbol>]
-      def event
+      def cursor_event
         {
           down:   :_cursor_down_,
           left:   :_cursor_left_,
@@ -129,13 +129,6 @@ module Vedeu
         }
       end
 
-      # Refresh the screen after moving.
-      #
-      # @return [void]
-      def refresh!
-        Vedeu.trigger(:_movement_refresh_, name)
-      end
-
       # Moves the geometry right by the offset.
       #
       # @return [Hash<Symbol => Fixnum]
@@ -169,7 +162,13 @@ module Vedeu
       #
       # @return [void]
       def update_cursor!
-        Vedeu.trigger(event, name)
+        if direction == :origin
+          Vedeu.trigger(cursor_event, name)
+
+        else
+          Vedeu.trigger(cursor_event, name, 0)
+
+        end
       end
 
       # @return [Boolean]
@@ -207,4 +206,40 @@ module Vedeu
 
   end # Geometries
 
+  # :nocov:
+
+  # {include:file:docs/events/by_name/movement_refresh.md}
+  Vedeu.bind(:_movement_refresh_) do |name|
+    Vedeu.trigger(:_clear_)
+    Vedeu.trigger(:_refresh_)
+    Vedeu.trigger(:_clear_view_, name)
+    Vedeu.trigger(:_refresh_view_, name)
+  end
+
+  # {include:file:docs/events/by_name/view_down.md}
+  Vedeu.bind(:_view_down_) do |name, offset|
+    Vedeu::Geometries::Move.move(name: name, offset: offset, direction: :down)
+  end
+
+  # {include:file:docs/events/by_name/view_left.md}
+  Vedeu.bind(:_view_left_) do |name, offset|
+    Vedeu::Geometries::Move.move(name: name, offset: offset, direction: :left)
+  end
+
+  # {include:file:docs/events/by_name/view_right.md}
+  Vedeu.bind(:_view_right_) do |name, offset|
+    Vedeu::Geometries::Move.move(name: name, offset: offset, direction: :right)
+  end
+
+  # {include:file:docs/events/by_name/view_up.md}
+  Vedeu.bind(:_view_up_) do |name, offset|
+    Vedeu::Geometries::Move.move(name: name, offset: offset, direction: :up)
+  end
+
+  [:down, :left, :right, :up].each do |direction|
+    Vedeu.bind_alias(:"_geometry_#{direction}_", :"_view_#{direction}_")
+  end
+
+  # :nocov:
+
 end # Vedeu

data/lib/vedeu/geometries/repository.rb

@@ -35,31 +35,11 @@ module Vedeu
     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_)
-    Vedeu.trigger(:_clear_view_, name)
-    Vedeu.trigger(:_refresh_view_, name)
-  end
-
   # See {file:docs/events/view.md#\_unmaximise_}
   Vedeu.bind(:_unmaximise_) do |name|
     Vedeu.geometries.by_name(name).unmaximise
   end
 
-  [:down, :left, :right, :up].each do |direction|
-    Vedeu.bind(:"_view_#{direction}_") do |name, offset|
-      Vedeu::Geometries::Move.move(direction: direction,
-                                   name:      name,
-                                   offset:    offset)
-    end
-  end
-
-  [:down, :left, :right, :up].each do |direction|
-    Vedeu.bind_alias(:"_geometry_#{direction}_", :"_view_#{direction}_")
-  end
-
   # :nocov:
 
 end # Vedeu

data/lib/vedeu/input/capture.rb

@@ -2,7 +2,8 @@
 
 module Vedeu
 
-  ESCAPE_KEY_CODE = 27 # \e
+  # \e
+  ESCAPE_KEY_CODE = 27
 
   module Input
 

data/lib/vedeu/logging/log.rb

@@ -6,6 +6,12 @@ module Vedeu
 
     # Provides the ability to log anything to the Vedeu log file.
     #
+    # @!macro [new] vedeu_logging_log_param_message
+    #    @param message [String] The message you wish to emit, useful
+    #      for debugging.
+    #
+    # @api public
+    #
     class Log
 
       class << self
@@ -16,8 +22,7 @@ module Vedeu
         #   Vedeu.log(type:    :debug,
         #             message: 'A useful debugging message: Error!')
         #
-        # @param message [String] The message you wish to emit to the
-        #   log file, useful for debugging.
+        # @macro vedeu_logging_log_param_message
         # @param force [Boolean] When evaluates to true will attempt
         #   to write to the log file regardless of the Configuration
         #   setting.
@@ -33,29 +38,29 @@ module Vedeu
           end
         end
 
-        # Write a message to STDOUT.
-        #
-        # @example
-        #   Vedeu.log_stdout
-        #
+        # {include:file:docs/dsl/by_method/log_stdout.md}
+        # @macro vedeu_logging_log_param_message
+        # @param type [Symbol] See {Vedeu::Logging::Log.message_types}
+        #   for valid values.
         # @return [String]
-        def log_stdout(type: :info, message:)
+        def log_stdout(message:, type: :info)
+          log(message: message, type: type)
+
           $stdout.puts log_entry(type, message)
         end
 
-        # Write a message to STDERR.
-        #
-        # @example
-        #   Vedeu.log_stderr
-        #
+        # {include:file:docs/dsl/by_method/log_stderr.md}
+        # @macro vedeu_logging_log_param_message
+        # @param type [Symbol] See {Vedeu::Logging::Log.message_types}
+        #   for valid values.
         # @return [String]
-        def log_stderr(type: :info, message:)
+        def log_stderr(message:, type: :error)
+          log(message: message, type: type)
+
           $stderr.puts log_entry(type, message)
         end
 
-        # Returns a formatted timestamp.
-        # eg. [137.7824]
-        #
+        # {include:file:docs/dsl/by_method/log_timestamp.md}
         # @return [String]
         def timestamp
           @now  = Vedeu.clock_time
@@ -82,12 +87,8 @@ module Vedeu
           end
         end
 
-        # Returns the message with timestamp.
-        #
-        #    [ 0.0987] [debug]  Something happened.
-        #
-        # @param message [String] The message type and message
-        #   coloured and combined.
+        # {include:file:docs/api/by_method/log_timestamp.md}
+        # @macro vedeu_logging_log_param_message
         # @return [String]
         def formatted_message(message)
           "#{timestamp}#{message}\n" if message
@@ -98,8 +99,7 @@ module Vedeu
         #     [type] message
         #
         # @param type [Symbol] The type of log message.
-        # @param message [String] The message you wish to emit to the
-        #   log file, useful for debugging.
+        # @macro vedeu_logging_log_param_message
         # @return [String]
         def log_entry(type, message)
           colours = message_types.fetch(type, [:default, :default])