vedeu 0.4.40 → 0.4.41

data/lib/vedeu/bindings.rb

@@ -36,13 +36,13 @@ module Vedeu
     Vedeu.bind(:_drb_restart_) { Vedeu::Distributed::Server.restart }
 
     # Use the DRb server to request the client application to start.
-    Vedeu.bind(:_drb_start_)   { Vedeu::Distributed::Server.start }
+    Vedeu.bind(:_drb_start_) { Vedeu::Distributed::Server.start }
 
     # Use the DRb server to request the status of the client application.
-    Vedeu.bind(:_drb_status_)  { Vedeu::Distributed::Server.status }
+    Vedeu.bind(:_drb_status_) { Vedeu::Distributed::Server.status }
 
     # Use the DRb server to request the client application to stop.
-    Vedeu.bind(:_drb_stop_)    { Vedeu::Distributed::Server.stop }
+    Vedeu.bind(:_drb_stop_) { Vedeu::Distributed::Server.stop }
 
     # Vedeu triggers this event when `:_exit_` is triggered. You can hook into
     # this to perform a special action before the application terminates. Saving
@@ -86,28 +86,44 @@ module Vedeu
     # events. Please see those events for their behaviour.
     Vedeu.bind(:_resize_, delay: 0.15) { Vedeu.resize }
 
-    # Hide the cursor of the named interface or interface currently in focus.
-    Vedeu.bind(:_cursor_hide_) do |name|
-      Vedeu::Visibility.for_cursor(name).hide
+    # @see {Vedeu::Move}
+    Vedeu.bind(:_cursor_down_) do |name|
+      Vedeu::Move.by_name(Vedeu::Cursor, :down, name)
     end
 
-    # Show the cursor of the named interface or interface currently in focus.
-    Vedeu.bind(:_cursor_show_) do |name|
-      Vedeu::Visibility.for_cursor(name).show
+    # @see {Vedeu::Move}
+    Vedeu.bind(:_cursor_left_) do |name|
+      Vedeu::Move.by_name(Vedeu::Cursor, :left, name)
     end
 
     # @see {Vedeu::Move}
-    %w(cursor view).each do |model|
-      [:down, :left, :right, :up].each do |direction|
-        Vedeu.bind("_#{model}_#{direction}_".to_sym) do |name|
-          klass = {
-            'cursor' => Vedeu::Cursor,
-            'view'   => Vedeu::Geometry,
-          }.fetch(model)
-
-          Vedeu::Move.by_name(klass, direction, name)
-        end
-      end
+    Vedeu.bind(:_cursor_right_) do |name|
+      Vedeu::Move.by_name(Vedeu::Cursor, :right, name)
+    end
+
+    # @see {Vedeu::Move}
+    Vedeu.bind(:_cursor_up_) do |name|
+      Vedeu::Move.by_name(Vedeu::Cursor, :up, name)
+    end
+
+    # @see {Vedeu::Move}
+    Vedeu.bind(:_geometry_down_) do |name|
+      Vedeu::Move.by_name(Vedeu::Geometry, :down, name)
+    end
+
+    # @see {Vedeu::Move}
+    Vedeu.bind(:_geometry_left_) do |name|
+      Vedeu::Move.by_name(Vedeu::Geometry, :left, name)
+    end
+
+    # @see {Vedeu::Move}
+    Vedeu.bind(:_geometry_right_) do |name|
+      Vedeu::Move.by_name(Vedeu::Geometry, :right, name)
+    end
+
+    # @see {Vedeu::Move}
+    Vedeu.bind(:_geometry_up_) do |name|
+      Vedeu::Move.by_name(Vedeu::Geometry, :up, name)
     end
 
     # @see {Vedeu::Move}
@@ -117,10 +133,7 @@ module Vedeu
 
     # When triggered will return the current position of the cursor.
     Vedeu.bind(:_cursor_position_) do |name|
-      named  = name ? name : Vedeu.focus
-      cursor = Vedeu.cursors.by_name(named)
-
-      Vedeu::Position.new(cursor.y, cursor.x) if cursor
+      Vedeu.cursors.by_name(name).position
     end
 
     # Move the cursor to a relative position inside the interface.
@@ -191,9 +204,6 @@ module Vedeu
     # if given.
     Vedeu.bind(:_clear_) { |name| Vedeu::Clear.by_name(name) }
 
-    # Clears the spaces occupied by the interfaces belonging to the named group.
-    Vedeu.bind(:_clear_group_) { |name| Vedeu::Clear.by_group(name) }
-
     # Will cause all interfaces to refresh, or the named interface if given.
     #
     # @note
@@ -209,12 +219,14 @@ module Vedeu
     # Will cause all interfaces in the named group to refresh.
     Vedeu.bind(:_refresh_group_) { |name| Vedeu::Refresh.by_group(name) }
 
-    # Will clear the terminal and then show all of the interfaces belonging to
-    # the named group.
-    Vedeu.bind(:_show_group_) do |name|
-      Vedeu.trigger(:_clear_)
-      Vedeu.trigger(:_refresh_group_, name)
+    # Clears the spaces occupied by the interfaces belonging to the named group.
+    Vedeu.bind(:_clear_group_) { |name| Vedeu::Clear.by_group(name) }
+
+    # Hide the cursor of the named interface or interface currently in focus.
+    Vedeu.bind(:_hide_cursor_) do |name|
+      Vedeu::Visibility.for_cursor(name).hide
     end
+    Vedeu.bind(:_cursor_hide_) { |name| Vedeu.trigger(:_hide_cursor_, name) }
 
     # Will hide all of the interfaces belonging to the named group. Useful for
     # hiding part of that which is currently displaying in the terminal.
@@ -222,50 +234,37 @@ module Vedeu
     # @note
     #   This may be rarely used, since the action of showing a group using
     #   `Vedeu.trigger(:_show_group_, group_name)` will effectively clear the
-    #   terminal and show the new group.
+    #   terminal and show the new group.}
     Vedeu.bind(:_hide_group_) { |name| Vedeu.trigger(:_clear_group_, name) }
 
-    # Will hide the named interface. If the interface is currently visible, it
-    # will be cleared- rendered blank. To show the interface, the
-    # ':_show_interface_' event should be triggered.
-    # Triggering the ':_hide_group_' event to which this named interface belongs
-    # will also hide the interface.
+    # @see Vedeu::Buffer#hide
     Vedeu.bind(:_hide_interface_) { |name| Vedeu.buffers.by_name(name).hide }
 
-    # Will show the named interface. If the interface is currently invisible, it
-    # will be shown- rendered with its latest content. To hide the interface,
-    # the ':_hide_interface_' event should be triggered.
-    # Triggering the ':_show_group_' event to which this named interface belongs
-    # will also show the interface.
-    Vedeu.bind(:_show_interface_) { |name| Vedeu.buffers.by_name(name).show }
+    # Show the cursor of the named interface or interface currently in focus.
+    Vedeu.bind(:_show_cursor_) do |name|
+      Vedeu::Visibility.for_cursor(name).show
+    end
+    Vedeu.bind(:_cursor_show_) { |name| Vedeu.trigger(:_show_cursor_, name) }
 
-    # Will toggle the visibility of the named interface. If the interface is
-    # currently visible, the area it occupies will be clears and the interface
-    # will be marked invisible. If the interface is invisible, then the
-    # interface will be marked visible and rendered in the area it occupies.
-    #
-    # @note
-    #   If an interface is marked visible whilst another view is occupying some
-    #   or all of the interface's current position, the interface will overwrite
-    #   this area- this may cause visual corruption.
-    Vedeu.bind(:_toggle_interface_) do |name|
-      if Vedeu.interfaces.by_name(name).visible?
-        Vedeu.trigger(:_hide_interface_, name)
+    # Will clear the terminal and then show all of the interfaces belonging to
+    # the named group.
+    Vedeu.bind(:_show_group_) do |name|
+      Vedeu.trigger(:_clear_)
+      Vedeu.trigger(:_refresh_group_, name)
+    end
 
-      else
-        Vedeu.trigger(:_show_interface_, name)
+    # @see Vedeu::Buffer#show
+    Vedeu.bind(:_show_interface_) { |name| Vedeu.buffers.by_name(name).show }
 
-      end
+    # @see Vedeu::Buffer#toggle
+    Vedeu.bind(:_toggle_interface_) do |name|
+      Vedeu.buffers.by_name(name).toggle
     end
 
-    # Will maximise the named interface geometry. This means it will occupy all
-    # of the available space on the terminal window.
+    # @see Vedeu::Geometry#maximise
     Vedeu.bind(:_maximise_) { |name| Vedeu.geometries.by_name(name).maximise }
 
-    # Will unmaximise the named interface geometry. Previously, if 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
-    # resized, then the new geometry size should adapt).
+    # @see Vedeu::Geometry#unmaximise
     Vedeu.bind(:_unmaximise_) do |name|
       Vedeu.geometries.by_name(name).unmaximise
     end

data/lib/vedeu/bootstrap.rb

@@ -13,6 +13,8 @@ module Vedeu
       new(argv, entry_point).start
     end
 
+    # Returns a new instance of Vedeu::Bootstrap.
+    #
     # @param argv [Array<String>]
     # @param entry_point [void]
     # @return [Vedeu::Bootstrap]

data/lib/vedeu/buffers/buffer.rb

@@ -106,6 +106,15 @@ module Vedeu
 
     # Hide this buffer.
     #
+    # @example
+    #   Vedeu.trigger(:_hide_interface_, name)
+    #
+    # Will hide the named interface. If the interface is currently visible, it
+    # will be cleared- rendered blank. To show the interface, the
+    # ':_show_interface_' event should be triggered.
+    # Triggering the ':_hide_group_' event to which this named interface belongs
+    # will also hide the interface.
+    #
     # @return [void]
     def hide
       return nil unless visible?
@@ -133,6 +142,15 @@ module Vedeu
 
     # Show this buffer.
     #
+    # @example
+    #   Vedeu.trigger(:_show_interface_, name)
+    #
+    # Will show the named interface. If the interface is currently invisible, it
+    # will be shown- rendered with its latest content. To hide the interface,
+    # the ':_hide_interface_' event should be triggered.
+    # Triggering the ':_show_group_' event to which this named interface belongs
+    # will also show the interface.
+    #
     # @return [void]
     def show
       return nil if visible?
@@ -141,6 +159,32 @@ module Vedeu
       render
     end
 
+    # Toggles the visibility of this buffer.
+    #
+    # @example
+    #   Vedeu.trigger(:_toggle_interface_, name)
+    #
+    # Will toggle the visibility of the named interface. If the interface is
+    # currently visible, the area it occupies will be clears and the interface
+    # will be marked invisible. If the interface is invisible, then the
+    # interface will be marked visible and rendered in the area it occupies.
+    #
+    # @note
+    #   If an interface is marked visible whilst another view is occupying some
+    #   or all of the interface's current position, the interface will overwrite
+    #   this area- this may cause visual corruption.
+    #
+    # @return [void]
+    def toggle
+      if visible?
+        hide
+
+      else
+        show
+
+      end
+    end
+
     private
 
     # Retrieve the latest content from the buffer.

data/lib/vedeu/configuration/api.rb

@@ -15,13 +15,16 @@ module Vedeu
         new(&block).configuration
       end
 
+      # Returns a new instance of Vedeu::Config::API.
+      #
       # Configure Vedeu via a simple configuration API DSL. Options set here
       # override the default Vedeu configuration set in
       # {Vedeu::Configuration#defaults}.
       #
       # @example
       #   Vedeu.configure do
-      #     ...
+      #     # ...
+      #   end
       #
       # @param block [Proc]
       # @return [Configuration::API]
@@ -33,9 +36,6 @@ module Vedeu
       #
       # @return [Hash<Symbol => Boolean, Fixnum, String>]
       def configuration
-        new_system_keys = Configuration.default_system_keys.merge!(system_keys)
-        options.merge!(system_keys: new_system_keys) if system_keys.any?
-
         Vedeu::Config.log(Esc.green { '[api]' }, options)
       end
 
@@ -45,11 +45,13 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     interactive!
-      #     ...
+      #     # ...
+      #   end
       #
       #   Vedeu.configure do
       #     interactive false
-      #     ...
+      #     # ...
+      #   end
       #
       # @param value [Boolean]
       # @return [Boolean]
@@ -64,7 +66,8 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     standalone!
-      #     ...
+      #     # ...
+      #   end
       #
       # @param value [Boolean]
       # @return [Boolean]
@@ -80,7 +83,8 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     run_once!
-      #     ...
+      #     # ...
+      #   end
       #
       # @param value [Boolean]
       # @return [Boolean]
@@ -94,7 +98,8 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     drb!
-      #     ...
+      #     # ...
+      #   end
       #
       # @param value [Boolean]
       # @return [Boolean]
@@ -108,7 +113,8 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     drb_host 'localhost'
-      #     ...
+      #     # ...
+      #   end
       #
       # @param hostname [String]
       # @return [String]
@@ -121,7 +127,8 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     drb_port 12345
-      #     ...
+      #     # ...
+      #   end
       #
       # @param port [Fixnum|String]
       # @return [String]
@@ -134,7 +141,8 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     drb_height 25
-      #     ...
+      #     # ...
+      #   end
       #
       # @param height [Fixnum]
       # @return [Fixnum]
@@ -147,7 +155,8 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     drb_width 80
-      #     ...
+      #     # ...
+      #   end
       #
       # @param width [Fixnum]
       # @return [Fixnum]
@@ -160,7 +169,8 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     cooked!
-      #     ...
+      #     # ...
+      #   end
       #
       # @return [Boolean]
       def cooked!
@@ -173,7 +183,8 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     raw!
-      #     ...
+      #     # ...
+      #   end
       #
       # @return [Boolean]
       def raw!
@@ -192,11 +203,13 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     debug!
-      #     ...
+      #     # ...
+      #   end
       #
       #   Vedeu.configure do
       #     debug false
-      #     ...
+      #     # ...
+      #   end
       #
       # @param value [Boolean]
       # @return [Boolean]
@@ -210,7 +223,8 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     colour_mode 256
-      #     ...
+      #     # ...
+      #   end
       #
       # @note
       #   iTerm 2 on Mac OSX will handle the true colour setting (16777216),
@@ -233,7 +247,8 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     log '/var/log/vedeu.log'
-      #     ...
+      #     # ...
+      #   end
       #
       # @param filename [String]
       # @return [String]
@@ -247,11 +262,13 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     renderer MyRenderer
-      #     ...
+      #     # ...
+      #   end
       #
       #   Vedeu.configure do
       #     renderers MyRenderer, MyOtherRenderer
-      #     ...
+      #     # ...
+      #   end
       #
       # @param renderer [Array<Class>|Class]
       # @return [Array<Class>]
@@ -265,7 +282,8 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     stdin IO.console
-      #     ...
+      #     # ...
+      #   end
       #
       # @param io [File|IO]
       # @return [File|IO]
@@ -278,7 +296,8 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     stdout IO.console
-      #     ...
+      #     # ...
+      #   end
       #
       # @param io [File|IO]
       # @return [File|IO]
@@ -291,7 +310,8 @@ module Vedeu
       # @example
       #   Vedeu.configure do
       #     stderr IO.console
-      #     ...
+      #     # ...
+      #   end
       #
       # @param io [File|IO]
       # @return [File|IO]
@@ -299,81 +319,6 @@ module Vedeu
         options[:stderr] = io
       end
 
-      # Sets the key used to exit the client application. The default is `q`.
-      #
-      # @example
-      #   Vedeu.configure do
-      #     exit_key 'x'
-      #     ...
-      #
-      #   Vedeu.configure do
-      #     exit_key :f4
-      #     ...
-      #
-      # @param value [String|Symbol]
-      # @return [String|Symbol]
-      def exit_key(value)
-        return invalid_key('exit_key') unless valid_key?(value)
-        system_keys[:exit] = value
-      end
-
-      # Sets the key used to switch focus to the next defined interface. The
-      # default is `:tab`.
-      #
-      # @example
-      #   Vedeu.configure do
-      #     focus_next_key 'n'
-      #     ...
-      #
-      #   Vedeu.configure do
-      #     focus_next_key :right
-      #     ...
-      #
-      # @param value [String|Symbol]
-      # @return [String|Symbol]
-      def focus_next_key(value)
-        return invalid_key('focus_next_key') unless valid_key?(value)
-        system_keys[:focus_next] = value
-      end
-
-      # Sets the key used to switch focus to the previous interface. The default
-      # is `:shift_tab`.
-      #
-      # @example
-      #   Vedeu.configure do
-      #     focus_prev_key 'p'
-      #     ...
-      #
-      #   Vedeu.configure do
-      #     focus_prev_key :left
-      #     ...
-      #
-      # @param value [String|Symbol]
-      # @return [String|Symbol]
-      def focus_prev_key(value)
-        return invalid_key('focus_prev_key') unless valid_key?(value)
-        system_keys[:focus_prev] = value
-      end
-
-      # Sets the key used to switch between raw and cooked mode in Vedeu. The
-      # default is `:escape`.
-      #
-      # @example
-      #   Vedeu.configure do
-      #     mode_switch_key 'm'
-      #     ...
-      #
-      #   Vedeu.configure do
-      #     mode_switch_key :f1
-      #     ...
-      #
-      # @param value [String|Symbol]
-      # @return [String|Symbol]
-      def mode_switch_key(value)
-        return invalid_key('mode_switch_key') unless valid_key?(value)
-        system_keys[:mode_switch] = value
-      end
-
       private
 
       # Returns the options set via the configuration API DSL or an empty Hash
@@ -384,14 +329,6 @@ module Vedeu
         @options ||= {}
       end
 
-      # Returns the system keys set via the configuration API DSL or an empty
-      # hash if none were redefined.
-      #
-      # @return [Hash]
-      def system_keys
-        @system_keys ||= {}
-      end
-
       # Checks that the value provided to {#colour_mode} is valid.
       #
       # @param value [Fixnum]
@@ -414,18 +351,6 @@ module Vedeu
         (value.is_a?(String) || value.is_a?(Symbol)) && present?(value)
       end
 
-      # Raises an exception on behalf of the calling method to report that the
-      # value provided is not valid.
-      #
-      # @param system_key [String] The calling method wishing to raise an
-      #   exception.
-      # @raise [InvalidSyntax] When the system_key parameter is not a String or
-      #   Symbol.
-      # @return [InvalidSyntax]
-      def invalid_key(system_key)
-        fail InvalidSyntax, "`#{system_key}` must be a String or a Symbol."
-      end
-
     end # API
 
   end # Config

data/lib/vedeu/configuration/cli.rb

@@ -13,6 +13,8 @@ module Vedeu
         new(args).configuration
       end
 
+      # Returns a new instance of Vedeu::Config::CLI.
+      #
       # Configure Vedeu via command-line arguments. Options set here via
       # arguments override the client application configuration set via
       # {Vedeu::API#configure}.

data/lib/vedeu/configuration/configuration.rb

@@ -41,6 +41,8 @@ module Vedeu
       #
       # @example
       #   Vedeu.configure
+      #     # ...
+      #   end
       #
       # @param args [Array]
       # @param opts [Hash]
@@ -58,6 +60,8 @@ module Vedeu
       #
       # @example
       #   Vedeu.configuration
+      #     # ...
+      #   end
       #
       # @return [Vedeu::Configuration]
       def configuration
@@ -171,13 +175,6 @@ module Vedeu
         instance.options[:stderr]
       end
 
-      # Returns the redefined system keys for vital Vedeu functions.
-      #
-      # @return [Hash]
-      def system_keys
-        instance.options[:system_keys]
-      end
-
       # Returns the terminal mode for the application. Default is `:raw`.
       #
       # @return [Symbol]
@@ -185,18 +182,6 @@ module Vedeu
         instance.options[:terminal_mode]
       end
 
-      # Vedeu's default system keys. Use {Vedeu::Configuration.system_keys}.
-      #
-      # @return [Hash]
-      def default_system_keys
-        {
-          exit:        'q',
-          focus_next:  :tab,
-          focus_prev:  :shift_tab,
-          mode_switch: :escape,
-        }
-      end
-
       # @param value [void]
       # @return [void]
       def options=(value)
@@ -270,7 +255,6 @@ module Vedeu
         stdin:         nil,
         stdout:        nil,
         stderr:        nil,
-        system_keys:   Vedeu::Configuration.default_system_keys,
         terminal_mode: :raw,
       }
     end

data/lib/vedeu/cursor/cursor.rb

@@ -97,6 +97,13 @@ module Vedeu
       @hide_cursor ||= Vedeu::EscapeChar.new(Vedeu::Esc.hide_cursor)
     end
 
+    # Return the position of this cursor.
+    #
+    # @return [Vedeu::Position]
+    def position
+      @position ||= Vedeu::Position.new(y, x)
+    end
+
     # @return [Vedeu::EscapeChar]
     def show_cursor
       @show_cursor ||= Vedeu::EscapeChar.new(Vedeu::Esc.show_cursor)
@@ -110,13 +117,6 @@ module Vedeu
 
     private
 
-    # Return the position of this cursor.
-    #
-    # @return [Vedeu::Position]
-    def position
-      @position ||= Vedeu::Position.new(y, x)
-    end
-
     # The default values for a new instance of this class.
     #
     # @return [Hash]

data/lib/vedeu/cursor/reposition.rb

@@ -11,6 +11,8 @@ module Vedeu
       new(entity, name, y, x).to
     end
 
+    # Returns a new instance of Vedeu::Reposition.
+    #
     # @param entity []
     # @param name [String]
     # @param y [Fixnum]