vedeu 0.4.62 → 0.4.63

data/lib/vedeu/cursor/refresh_cursor.rb

@@ -80,7 +80,7 @@ module Vedeu
     # Fetch the border by name.
     #
     # @note
-    #   Vedeu::Border is used in this way because if there is not a border
+    #   Vedeu::Border is used in this way because when there is not a border
     #   defined, it will fallback to a Vedeu::Null::Border which uses
     #   Vedeu::Geometry to determine it's dimensions based on the name also.
     #   When a Vedeu::Geometry cannot be found, this falls back to a

data/lib/vedeu/distributed/server.rb

@@ -182,7 +182,7 @@ module Vedeu
 
         end
       rescue NoMethodError # raised when #join is called on NilClass.
-        Vedeu.log(type: :debug, message: 'Attempted to #join on DRb.thread.')
+        Vedeu.log(type: :drb, message: 'Attempted to #join on DRb.thread.')
       end
 
       protected

data/lib/vedeu/dsl/border.rb

@@ -109,7 +109,7 @@ module Vedeu
       end
 
       # Enable the border:
-      # (Borders are enabled by default if defined for an interface).
+      # (Borders are enabled by default when defined for an interface).
       #
       #   Vedeu.border 'border_demo' do
       #     enable!

data/lib/vedeu/dsl/geometry.rb

@@ -140,7 +140,7 @@ module Vedeu
       end
 
       # Specify the number of characters/rows/lines tall the interface will be.
-      # This value will be ignored if by `y` and `yn` are set.
+      # This value will be ignored when `y` and `yn` are set.
       #
       #   Vedeu.geometry 'some_interface' do
       #     height 8
@@ -172,7 +172,7 @@ module Vedeu
       end
 
       # Specify the number of characters/columns wide the interface will be.
-      # This value will be ignored if by `x` and `xn` are set.
+      # This value will be ignored when `x` and `xn` are set.
       #
       #   Vedeu.geometry 'some_interface' do
       #     width 25
@@ -210,9 +210,10 @@ module Vedeu
       #   Vedeu.geometry 'some_interface' do
       #     xn 37 # end at column 37.
       #
-      #     xn  { use('other_interface').right } # if `other_interface` changes
-      #     # ... some code                      # position, `some_interface`
-      #   end                                    # will too.
+      #     xn  { use('other_interface').right } # when `other_interface`
+      #                                          # changes position,
+      #     # ... some code                      # `some_interface` will too.
+      #   end
       #
       # @param value [Fixnum]
       # @param block [Proc]
@@ -228,7 +229,7 @@ module Vedeu
       #   Vedeu.geometry 'some_interface' do
       #     y  4 # start at row 4
       #
-      #     y  { use('other_interface').north } # start on row/line 3, if
+      #     y  { use('other_interface').north } # start on row/line 3, when
       #     # ... some code                     # `other_interface` changes
       #   end                                   # position, `some_interface`
       #                                         # will too.

data/lib/vedeu/dsl/view.rb

@@ -9,8 +9,8 @@ module Vedeu
     # Both of these approaches require that you have defined an interface (or
     # 'visible area') first. You can find out how to define an interface with
     # Vedeu here. The examples in 'Immediate Render' and 'Deferred View' use
-    # these interface definitions: (Note: if you use these examples, ensure your
-    # terminal is at least 70 characters in width and 5 lines in height.)
+    # these interface definitions: (Note: should you use these examples, ensure
+    # your terminal is at least 70 characters in width and 5 lines in height.)
     #
     #   Vedeu.interface 'main' do
     #     geometry do
@@ -111,7 +111,7 @@ module Vedeu
 
         # Directly write a view buffer to the terminal. Using this method means
         # that the refresh event does not need to be triggered after creating
-        # the views, though can be later triggered if needed.
+        # the views, though can be later triggered when needed.
         #
         #   Vedeu.renders do
         #     view 'some_interface' do

data/lib/vedeu/events/event.rb

@@ -236,7 +236,7 @@ module Vedeu
       false
     end
 
-    # Returns a boolean indicating if this event has a deadline.
+    # Returns a boolean indicating whether this event has a deadline.
     #
     # @return [Boolean]
     def deadline?

data/lib/vedeu/events/trigger.rb

@@ -28,7 +28,7 @@ module Vedeu
       @repository = Vedeu.events
     end
 
-    # Trigger the event and return the result (if one) or an array of results.
+    # Trigger the event and return the result or an array of results.
     #
     # @return [Array]
     def trigger

data/lib/vedeu/exceptions.rb

@@ -1,5 +1,19 @@
 module Vedeu
 
+  # Raised with Vedeu attempts to access a client application controller that
+  # does not exist.
+  #
+  class ControllerNotFound < StandardError
+
+  end # ControllerNotFound
+
+  # Raised with Vedeu attempts to access a client application controller's
+  # action that does not exist.
+  #
+  class ActionNotFound < StandardError
+
+  end # ActionNotFound
+
   # Raised with Vedeu attempts to access a named model that does not exist.
   #
   class ModelNotFound < StandardError

data/lib/vedeu/geometry/dimension.rb

@@ -123,7 +123,7 @@ module Vedeu
       (default / 2) + (length / 2)
     end
 
-    # Fetch the starting coordinate, or use 1 if not set.
+    # Fetch the starting coordinate, or use 1 when not set.
     #
     # @return [Fixnum]
     def _d

data/lib/vedeu/geometry/geometry.rb

@@ -123,9 +123,9 @@ module Vedeu
       work
     end
 
-    # Will unmaximise the named interface geometry. Previously, if a geometry
+    # 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: if the terminal has been
+    # usual defined size (terminal size permitting: when the terminal has been
     # resized, then the new geometry size should adapt).
     #
     # @example

data/lib/vedeu/geometry/position_validator.rb

@@ -39,7 +39,7 @@ module Vedeu
     end
 
     # Ensures the coordinates provided are within the terminal, interface and
-    # if applicable, bordered interface area.
+    # when applicable, bordered interface area.
     #
     # @return [PositionValidator]
     def validate

data/lib/vedeu/input/input.rb

@@ -22,8 +22,9 @@ module Vedeu
       @reader = reader
     end
 
-    # Triggers either a ':_command_' event with the command if the reader is in
-    # cooked mode, or if raw mode, the keypress event with the key(s) pressed.
+    # Triggers either a ':_command_' event with the command when the reader is
+    # in cooked mode, or when in raw mode, the keypress event with the key(s)
+    # pressed.
     #
     # @return [Array|String|Symbol]
     def capture
@@ -52,8 +53,8 @@ module Vedeu
     end
     alias_method :command, :input
 
-    # Returns the translated (if possible) keypress(es) as either a String or a
-    # Symbol.
+    # Returns the translated (when possible) keypress(es) as either a String or
+    # a Symbol.
     #
     # @return [String|Symbol]
     def keypress
@@ -62,7 +63,7 @@ module Vedeu
       specials.fetch(key, key)
     end
 
-    # Translates (if possible) entered escape sequences into symbols
+    # Translates (when possible) entered escape sequences into symbols
     # representing the key which was pressed.
     #
     # @return [Hash]

data/lib/vedeu/input/keymap.rb

@@ -52,8 +52,8 @@ module Vedeu
       keys.any? { |key| key.input == input }
     end
 
-    # Triggers the action associated with the key, if it is registered with this
-    # keymap.
+    # When the given input is registered with this keymap, this method triggers
+    # the action associated with the key.
     #
     # @param input [String|Symbol]
     # @return [Array|FalseClass]
@@ -87,7 +87,7 @@ module Vedeu
     def valid?(key)
       return true unless key_defined?(key.input)
 
-      Vedeu.log(type:    :debug,
+      Vedeu.log(type:    :input,
                 message: "Keymap '#{name}' already defines '#{key.input}'.")
 
       false

data/lib/vedeu/input/mapper.rb

@@ -5,7 +5,7 @@ module Vedeu
   class Mapper
 
     # Takes a key as a keypress and sends it to registered keymaps. If found,
-    # the associated action is fired, if not, we move to the next keymap or
+    # the associated action is fired, otherwise, we move to the next keymap or
     # return false.
     #
     # @example
@@ -21,7 +21,7 @@ module Vedeu
       new(key, name).keypress
     end
 
-    # Checks a key is valid; i.e. not already registered to a keymap. If the
+    # Checks a key is valid; i.e. not already registered to a keymap. When the
     # key is registered, then the key is invalid and cannot be used again.
     #
     # @param (see #initialize)
@@ -51,7 +51,7 @@ module Vedeu
     def keypress
       return false unless key
 
-      Vedeu.log(type: :debug, message: "Key detected: #{key.inspect}")
+      Vedeu.log(type: :input, message: "Key detected: #{key.inspect}")
 
       return true if key_defined? && keymap.use(key)
 

data/lib/vedeu/internal_api.rb

@@ -0,0 +1,147 @@
+module Vedeu
+
+  # Vedeu's internal API methods provide convenient ways to access Vedeu's
+  # internals. They are not supposed to be used by client applications as they
+  # have limited value there.
+  #
+  module InternalAPI
+
+    extend Forwardable
+
+    module_function
+
+    # Manipulate the repository of background colours.
+    #
+    # @example
+    #   Vedeu.background_colours
+    #
+    # @!method background_colours
+    # @return [Vedeu::Backgrounds]
+    def_delegators Vedeu::Backgrounds, :background_colours
+
+    # Manipulate the repository of borders.
+    #
+    # @example
+    #   Vedeu.borders
+    #
+    # @!method borders
+    # @return [Vedeu::Borders]
+    def_delegators Vedeu::Borders, :borders
+
+    # Manipulate the repository of buffers.
+    #
+    # @example
+    #   Vedeu.buffers
+    #
+    # @!method buffers
+    # @return [Vedeu::Buffers]
+    def_delegators Vedeu::Buffers, :buffers
+
+    # Manipulate the repository of cursors.
+    #
+    # @example
+    #   Vedeu.cursors
+    #
+    # @!method cursors
+    # @return [Vedeu::Cursors]
+    def_delegators Vedeu::Cursors, :cursors
+
+    # Manipulate the repository of events.
+    #
+    # @example
+    #   Vedeu.events
+    #
+    # @!method events
+    # @return [Vedeu::Events]
+    def_delegators Vedeu::Events, :events
+
+    # Manipulate the repository of foreground colours.
+    #
+    # @example
+    #   Vedeu.foreground_colours
+    #
+    # @!method foreground_colours
+    # @return [Vedeu::Foregrounds]
+    def_delegators Vedeu::Foregrounds, :foreground_colours
+
+    # Manipulate the repository of geometries.
+    #
+    # @example
+    #   Vedeu.geometries
+    #
+    # @!method geometries
+    # @return [Vedeu::Geometries]
+    def_delegators Vedeu::Geometries, :geometries
+
+    # Manipulate the repository of groups.
+    #
+    # @example
+    #   Vedeu.groups
+    #
+    # @!method groups
+    # @return [Vedeu::Groups]
+    def_delegators Vedeu::Groups, :groups
+
+    # Manipulate the repository of interfaces.
+    #
+    # @example
+    #   Vedeu.interfaces
+    #
+    # @!method interfaces
+    # @return [Vedeu::Interfaces]
+    def_delegators Vedeu::Interfaces, :interfaces
+
+    # Manipulate the repository of keymaps.
+    #
+    # @example
+    #   Vedeu.keymaps
+    #
+    # @!method keymaps
+    # @return [Vedeu::Keymaps]
+    def_delegators Vedeu::Keymaps, :keymaps
+
+    # Manipulate the repository of menus.
+    #
+    # @example
+    #   Vedeu.menus
+    #
+    # @!method menus
+    # @return [Vedeu::Menus]
+    def_delegators Vedeu::Menus, :menus
+
+    # @example
+    #   Vedeu.renderer
+    #   Vedeu.renderers
+    #
+    # @!method renderer
+    #   @see Vedeu::Renderers#renderer
+    # @!method renderers
+    #   @see Vedeu::Renderers#renderers
+    def_delegators Vedeu::Renderers, :renderer, :renderers
+
+    # Instruct the terminal to resize. This will happen automatically as the
+    # terminal recieves SIGWINCH signals.
+    #
+    # @example
+    #   Vedeu.resize
+    #
+    # @!method resize
+    #   @see Vedeu::Terminal#resize
+    def_delegators Vedeu::Terminal, :resize
+
+    # Measure the execution time of the code in the given block.
+    #
+    # @example
+    #   Vedeu.timer do
+    #     # ... some code here ...
+    #   end
+    #
+    # @!method timer
+    #   @see Vedeu::Timer.timer
+    def_delegators Vedeu::Timer, :timer
+
+  end # InternalAPI
+
+  extend InternalAPI
+
+end # Vedeu

data/lib/vedeu/models/char.rb

@@ -101,14 +101,14 @@ module Vedeu
       end
     end
 
-    # Returns the x position for the Char if set.
+    # Returns the x position for the Char when set.
     #
     # @return [Fixnum|NilClass]
     def x
       position.x if position
     end
 
-    # Returns the y position for the Char if set.
+    # Returns the y position for the Char when set.
     #
     # @return [Fixnum|NilClass]
     def y

data/lib/vedeu/models/focus.rb

@@ -188,7 +188,7 @@ module Vedeu
     private
 
     # Return the name of the interface in focus after triggering the refresh
-    # event for that interface. Returns false if the storage is empty.
+    # event for that interface. Returns false when the storage is empty.
     #
     # @return [String|FalseClass]
     def update

data/lib/vedeu/models/line.rb

@@ -75,7 +75,7 @@ module Vedeu
     end
     alias_method :value, :streams
 
-    # Delegate to Vedeu::Interface#width if available.
+    # Delegate to Vedeu::Interface#width when available.
     #
     # @return [Fixnum]
     def width

data/lib/vedeu/models/stream.rb

@@ -94,7 +94,7 @@ module Vedeu
       value.size
     end
 
-    # Delegate to Vedeu::Line#width if available.
+    # Delegate to Vedeu::Line#width when available.
     #
     # @return [Fixnum]
     def width

data/lib/vedeu/output/esc.rb

@@ -22,7 +22,7 @@ module Vedeu
     end
 
     # Return the escape sequence string from the list of recognised sequence
-    # 'commands', or an empty string if the 'command' cannot be found.
+    # 'commands', or an empty string when the 'command' cannot be found.
     #
     # @param value [String|Symbol]
     # @return [String]

data/lib/vedeu/output/presentation.rb

@@ -5,7 +5,7 @@ module Vedeu
   #
   module Presentation
 
-    # Returns the background colour for the model, or if it does not exist,
+    # When the background colour for the model exists, return it, otherwise
     # returns the parent background colour, or an empty Vedeu::Background.
     #
     # @return [Vedeu::Background]
@@ -51,7 +51,7 @@ module Vedeu
       @colour = attributes[:colour] = Vedeu::Colour.coerce(value)
     end
 
-    # Returns the foreground colour for the model, or if it does not exist,
+    # When the foreground colour for the model exists, return it, otherwise
     # returns the parent foreground colour, or an empty Vedeu::Foreground.
     #
     # @return [Vedeu::Foreground]
@@ -75,8 +75,8 @@ module Vedeu
         background: colour.background)
     end
 
-    # Returns the parent background colour if a parent colour is available, or
-    # an empty Vedeu::Background.
+    # When a parent colour is available, returns the parent background colour,
+    # otherwise an empty Vedeu::Background.
     #
     # @return [Vedeu::Background]
     def parent_background
@@ -89,15 +89,15 @@ module Vedeu
       end
     end
 
-    # Returns the parent colour if available or NilClass.
+    # Returns the parent colour when available or NilClass.
     #
     # @return [String|NilClass]
     def parent_colour
       parent.colour if parent
     end
 
-    # Returns the parent foreground colour if a parent colour is available, or
-    # an empty Vedeu::Foreground.
+    # When a parent colour is available, returns the parent foreground colour,
+    # otherwise an empty Vedeu::Foreground.
     #
     # @return [Vedeu::Foreground]
     def parent_foreground
@@ -110,7 +110,7 @@ module Vedeu
       end
     end
 
-    # Returns the parent style if available or NilClass.
+    # Returns the parent style when available or NilClass.
     #
     # @return [String|NilClass]
     def parent_style
@@ -142,7 +142,7 @@ module Vedeu
       @style = Vedeu::Style.coerce(value)
     end
 
-    # Converts the colours and styles to escape sequences, and if the parent
+    # Converts the colours and styles to escape sequences, and when the parent
     # model has previously set the colour and style, reverts back to that for
     # consistent formatting.
     #