vedeu 0.6.6 → 0.6.7

data/lib/vedeu/bindings/visibility.rb

@@ -2,14 +2,16 @@ module Vedeu
 
   module Bindings
 
-    # System events relating to the visibility of cursors or interfaces.
+    # System events relating to the visibility of cursors or
+    # interfaces.
     #
     # :nocov:
     module Visibility
 
       extend self
 
-      # Setup events relating to visibility. This method is called by Vedeu.
+      # Setup events relating to visibility. This method is called by
+      # Vedeu.
       #
       # @return [TrueClass]
       def setup!
@@ -27,8 +29,8 @@ module Vedeu
 
       private
 
-      # Clears the spaces occupied by the interfaces belonging to the named
-      # group.
+      # Clears the spaces occupied by the interfaces belonging to the
+      # named group.
       #
       # @example
       #   Vedeu.trigger(:_clear_group_, name)
@@ -41,8 +43,8 @@ module Vedeu
         end
       end
 
-      # Hide the cursor of the named interface or when a name is not given, the
-      # interface currently in focus.
+      # Hide the cursor of the named interface or when a name is not
+      # given, the interface currently in focus.
       #
       # @example
       #   Vedeu.trigger(:_hide_cursor_, name)
@@ -76,8 +78,8 @@ module Vedeu
         end
       end
 
-      # Show the cursor of the named interface or when a name is not given, the
-      # interface currently in focus.
+      # Show the cursor of the named interface or when a name is not
+      # given, the interface currently in focus.
       #
       # @example
       #   Vedeu.trigger(:_show_cursor_, name)

data/lib/vedeu/borders/all.rb

@@ -1,5 +1,31 @@
 module Vedeu
 
+  # Borders are defined by name for each of the client application's
+  # interfaces or views. They can be enabled or disabled (which controls
+  # whether they are rendered or not), they have their own colours and styles,
+  # and each aspect of the border can be controlled.
+  #
+  # @example
+  #   # Borders can be defined when defining your interface...
+  #   Vedeu.interface 'my_interface' do
+  #     border do
+  #     # ...
+  #   end
+  #
+  #   # ...or as part of a view definition...
+  #   Vedeu.renders do
+  #     view 'border_demo' do
+  #       border do
+  #       # ...
+  #     end
+  #
+  #   # ...or standalone; referencing the target interface or view.
+  #   Vedeu.border 'some_interface' do
+  #     # ...
+  #   end
+  #
+  # See {Vedeu::Borders::DSL} for DSL methods for defining borders.
+  #
   module Borders
 
   end # Borders

data/lib/vedeu/borders/dsl.rb

@@ -2,29 +2,7 @@ module Vedeu
 
   module Borders
 
-    # Borders are defined by name for each of the client application's
-    # interfaces or views. They can be enabled or disabled (which controls
-    # whether they are rendered or not), they have their own colours and styles,
-    # and each aspect of the border can be controlled.
-    #
-    # @example
-    #   # Borders can be defined when defining your interface...
-    #   Vedeu.interface 'my_interface' do
-    #     border do
-    #     # ...
-    #   end
-    #
-    #   # ...or as part of a view definition...
-    #   Vedeu.renders do
-    #     view 'border_demo' do
-    #       border do
-    #       # ...
-    #     end
-    #
-    #   # ...or standalone; referencing the target interface or view.
-    #   Vedeu.border 'some_interface' do
-    #     # ...
-    #   end
+    # Provides a mechanism to help configure borders in Vedeu.
     #
     class DSL
 

data/lib/vedeu/buffers/all.rb

@@ -1,5 +1,16 @@
 module Vedeu
 
+  # The Buffer object represents the states of display for an interface. The
+  # states are 'front', 'back' and 'previous'.
+  #
+  # [Back] -> [Front] -> [Previous]
+  #
+  # The content on the screen, or last output will always be the 'Front'
+  # buffer. Content due to be displayed on next refresh will come from the
+  # 'Back' buffer when available, otherwise from the current 'Front' buffer.
+  # When new content is copied to the 'Front' buffer, the current 'Front'
+  # buffer is also copied to the 'Previous' buffer.
+  #
   module Buffers
 
   end # Buffers
@@ -9,5 +20,6 @@ end # Vedeu
 require 'vedeu/buffers/buffer'
 require 'vedeu/buffers/null'
 require 'vedeu/buffers/repository'
+require 'vedeu/buffers/refresh'
 require 'vedeu/buffers/virtual_buffer'
 require 'vedeu/buffers/virtual_buffers'

data/lib/vedeu/buffers/buffer.rb

@@ -2,16 +2,7 @@ module Vedeu
 
   module Buffers
 
-    # The Buffer object represents the states of display for an interface. The
-    # states are 'front', 'back' and 'previous'.
-    #
-    # [Back] -> [Front] -> [Previous]
-    #
-    # The content on the screen, or last output will always be the 'Front'
-    # buffer. Content due to be displayed on next refresh will come from the
-    # 'Back' buffer when available, otherwise from the current 'Front' buffer.
-    # When new content is copied to the 'Front' buffer, the current 'Front'
-    # buffer is also copied to the 'Previous' buffer.
+    # Used by Vedeu internally to manage the buffers of each interface defined.
     #
     class Buffer
 

data/lib/vedeu/buffers/refresh.rb

@@ -0,0 +1,57 @@
+module Vedeu
+
+  module Buffers
+
+    # Refreshes the given named interface.
+    #
+    # @example
+    #   Vedeu.trigger(:_refresh_, name)
+    #
+    class Refresh
+
+      include Vedeu::Common
+
+      # @param name [String] The name of the interface to be refreshed using the
+      #   named buffer.
+      # @return [Array|Vedeu::Error::ModelNotFound]
+      def self.by_name(name)
+        new(name).by_name
+      end
+
+      # Return a new instance of Vedeu::Buffers::Refresh.
+      #
+      # @param name [String]
+      # @return [Vedeu::Buffers::Refresh]
+      def initialize(name)
+        @name = name
+      end
+
+      # @return [void]
+      def by_name
+        Vedeu.timer("Refresh Buffer: '#{buffer_name}'") do
+          Vedeu.buffers.by_name(buffer_name).render
+        end
+      end
+
+      protected
+
+      # # @!attribute [r] name
+      # @return [String]
+      attr_reader :name
+
+      private
+
+      # @raise [Vedeu::Error::MissingRequired] When the name is empty or nil.
+      # @return [String]
+      def buffer_name
+        return name if present?(name)
+
+        fail Vedeu::Error::MissingRequired,
+             'Cannot refresh interface with an empty interface name.'
+      end
+
+    end # Refresh
+
+  end # Buffers
+
+end # Vedeu

data/lib/vedeu/buffers/virtual_buffer.rb

@@ -120,7 +120,7 @@ module Vedeu
     end
 
     # @return [Array<Array<Vedeu::Cell>>]
-    # @see {Vedeu::VirtualBuffer#cells}
+    # @see Vedeu::VirtualBuffer#cells
     def new_virtual_buffer
       Array.new(height) { Array.new(width) { Vedeu::Cell.new } }
     end

data/lib/vedeu/cursors/all.rb

@@ -1,5 +1,14 @@
 module Vedeu
 
+  # Vedeu creates an individual cursor for each interface defined,
+  # these take their name from the interface, which means that your
+  # position within the view for each interface is maintained.
+  #
+  # The cursor also manages the content offset for a particular view.
+  # For example, if the user has moved around within the content and
+  # then moved to another interface, when they return their position
+  # will be restored.
+  #
   module Cursors
 
   end # Cursors

data/lib/vedeu/cursors/cursor.rb

@@ -213,6 +213,22 @@ module Vedeu
         render
       end
 
+      # Toggle the visibility of the cursor with the given name.
+      #
+      # @example
+      #   Vedeu.toggle_cursor(name)
+      #
+      # @return [Vedeu::Escape]
+      def toggle
+        if visible?
+          hide
+
+        else
+          show
+
+        end
+      end
+
       # @return [Fixnum] The column/character coordinate.
       def x
         @x = bx  if @x < bx

data/lib/vedeu/dsl/interface.rb

@@ -228,7 +228,7 @@ module Vedeu
       #     # ... some code
       #   end
       #
-      # @return [void]
+      # @return [Boolean]
       def show!
         visible(true)
       end
@@ -240,7 +240,7 @@ module Vedeu
       #     # ... some code
       #   end
       #
-      # @return [void]
+      # @return [Boolean]
       def hide!
         visible(false)
       end
@@ -279,7 +279,7 @@ module Vedeu
       #     # ... some code
       #   end
       #
-      # @return [void]
+      # @return [Boolean]
       def visible(value = true)
         boolean = value ? true : false
 
@@ -302,7 +302,7 @@ module Vedeu
       #   end
       #
       # @param value [Fixnum]
-      # @return [void]
+      # @return [Fixnum]
       def zindex(value)
         model.zindex = value
       end

data/lib/vedeu/events/aliases.rb

@@ -2,20 +2,33 @@ module Vedeu
 
   module Events
 
-    # Allows the storing of event aliases. Each alias can contain multiple event
-    # names.
+    # Allows the storing of event aliases. Each alias can contain
+    # multiple event names.
+    #
+    # @note
+    #
     #
     module Aliases
 
       extend self
 
-      # @param alias_name [Symbol]
-      # @param event_name [Symbol]
+      # Add events by name to the alias name group. When an alias is
+      # triggered, all the events stored in the group are also
+      # triggered.
+      #
+      # @example
+      #   Vedeu.bind_alias(alias_name, event_name)
+      #
+      # @param alias_name [Symbol] The name of the alias. This can
+      #   represent a single event or group of events.
+      # @param event_name [Symbol] The name of the event to bind to
+      #   the alias. When the alias is triggered, all events bound
+      #   will also be triggered.
       # @return [Hash<Symbol => Array<Symbol>>]
-      def add(alias_name, event_name)
+      def bind_alias(alias_name, event_name)
         storage[alias_name] << event_name
       end
-      alias_method :bind_alias, :add
+      alias_method :add, :bind_alias
 
       # Return a boolean indicating whether the storage is empty.
       #
@@ -41,16 +54,22 @@ module Vedeu
         storage.include?(alias_name)
       end
 
-      # @param alias_name [Symbol]
+      # Remove an alias by name. The alias name group is destroyed,
+      #   but events stored within this alias are not.
+      #
+      # @example
+      #   Vedeu.unbind_alias(alias_name)
+      #
+      # @param alias_name [Symbol] The name of the alias.
       # @return [FalseClass|Hash<Symbol => Array<Symbol>>]
-      def remove(alias_name)
+      def unbind_alias(alias_name)
         return false if empty?
         return false unless registered?(alias_name)
 
         storage.delete(alias_name)
         storage
       end
-      alias_method :unbind_alias, :remove
+      alias_method :remove, :unbind_alias
 
       # @return [Hash<Symbol => Array<Symbol>>]
       def reset

data/lib/vedeu/events/collection.rb

@@ -4,6 +4,7 @@ module Vedeu
 
     # A collection of {Vedeu::Events::Event} instances.
     #
+    # @api private
     class Collection < Vedeu::Collection
 
     end # Collection

data/lib/vedeu/events/trigger.rb

@@ -7,11 +7,13 @@ module Vedeu
     # registered for a name, then the result of each event will be returned as
     # part of a collection.
     #
-    # @example
-    #   Vedeu.trigger(:my_event, :oxidize, 'nitrogen')
-    #
     class Trigger
 
+      # Trigger an event by name.
+      #
+      # @example
+      #   Vedeu.trigger(:my_event, :oxidize, 'nitrogen')
+      #
       # @param name [Symbol] The name of the event you wish to trigger. The
       #   event does not have to exist.
       # @param args [Array] Any arguments the event needs to execute correctly.

data/lib/vedeu/geometry/all.rb

@@ -1,5 +1,12 @@
 module Vedeu
 
+  # The Geometry group of classes all handle the size of interfaces in
+  # relation to the current size of the terminal. This helps Vedeu to
+  # draw content in a consistent way.
+  #
+  # You can define the geometry of your interfaces using the
+  # {Vedeu::Geometry::DSL}.
+  #
   module Geometry
 
   end # Geometry

data/lib/vedeu/geometry/position.rb

@@ -24,7 +24,7 @@ module Vedeu
       end
 
       # @param value [Array<Fixnum>|Vedeu::Position]
-      # @return [void]
+      # @return [Vedeu::Geometry::Position]
       def self.coerce(value)
         if value.is_a?(self)
           value
@@ -97,7 +97,7 @@ module Vedeu
       # aforementioned, call the block and then reposition to this location.
       #
       # @return [String]
-      # @yieldreturn [void] Returns the block wrapped in position escape
+      # @yieldreturn [String] Returns the block wrapped in position escape
       #   sequences.
       def to_s
         return "#{sequence}#{yield}" if block_given?

data/lib/vedeu/input/editor/editor.rb

@@ -27,7 +27,7 @@ module Vedeu
       #
       # @param name [String]
       # @param input [String|Symbol]
-      # @return [void]
+      # @return [String|Symbol]
       def self.keypress(input:, name:)
         new(input: input, name: name).keypress
       end

data/lib/vedeu/log/log.rb

@@ -32,6 +32,9 @@ module Vedeu
 
       # Write a message to STDOUT.
       #
+      # @example
+      #   Vedeu.log_stdout
+      #
       # @return [TrueClass]
       def log_stdout(type: :info, message:)
         $stdout.puts log_entry(type, message)
@@ -39,6 +42,9 @@ module Vedeu
 
       # Write a message to STDERR.
       #
+      # @example
+      #   Vedeu.log_stderr
+      #
       # @return [TrueClass]
       def log_stderr(type: :info, message:)
         $stderr.puts log_entry(type, message)