vedeu 0.4.56 → 0.4.57

data/lib/vedeu/models/group.rb

@@ -5,7 +5,6 @@ module Vedeu
   # Interfaces can be associated with one another by being members of the same
   # Group. A Group is a collection of interface names.
   #
-  # @api private
   class Group
 
     include Vedeu::Model
@@ -17,20 +16,22 @@ module Vedeu
 
     # Return a new instance of Vedeu::Group.
     #
+    # @note
+    #   A group being visible or not may not necessarily mean the members are of
+    #   the same state.
+    #
     # @param attributes [Hash]
-    # @option attributes members [Array] A collection of names of interfaces
+    # @option attributes members [Set] A collection of names of interfaces
     #   belonging to this group.
     # @option attributes name [String] The name of the group.
     # @option attributes repository [Vedeu::Repository] The storage for all
     #   Group models.
+    # @option attributes visible [Boolean] Whether the group is visible or not.
     # @return [Vedeu::Group]
     def initialize(attributes = {})
       @attributes = defaults.merge!(attributes)
 
-      @members    = Array(@attributes[:members])
-      @name       = @attributes[:name]
-      @repository = @attributes[:repository]
-      @visible    = @attributes[:visible]
+      @attributes.each { |key, value| instance_variable_set("@#{key}", value) }
     end
 
     # Add a member to the group by name.
@@ -38,15 +39,33 @@ module Vedeu
     # @param member [String]
     # @return [Vedeu::Group]
     def add(member)
-      @members = members.add(member)
+      attrs = attributes.merge!(members: members.add(member))
 
-      Vedeu::Group.new(name: name, members: @members, visible: visible).store
+      Vedeu::Group.new(attrs).store
+    end
+
+    # Returns the attributes of the group.
+    #
+    # @return [Hash<Symbol => void>]
+    def attributes
+      {
+        name:       name,
+        members:    members,
+        repository: repository,
+        visible:    visible,
+      }
     end
 
     # Hide the named group of interfaces, or without a name, the group of the
-    # currently focussed interface.
+    # currently focussed interface. Useful for hiding part of that which is
+    # currently displaying in the terminal.
+    #
+    # @note
+    #   The action of showing a group will effectively clear the terminal and
+    #   show the new group, therefore hiding the group may not be necessary.
     #
     # @example
+    #   Vedeu.trigger(:_hide_group_, name)
     #   Vedeu.hide_group(name)
     #
     # @return [Vedeu::Group]
@@ -58,11 +77,11 @@ module Vedeu
       self
     end
 
-    # Return the members as a Set.
+    # Return the members of the group.
     #
     # @return [Set]
     def members
-      @members.to_set
+      @_members ||= Set.new(@members)
     end
 
     # Remove a member from the group by name.
@@ -70,22 +89,25 @@ module Vedeu
     # @param member [String]
     # @return [Vedeu::Group]
     def remove(member)
-      @members = members.delete(member)
+      attrs = attributes.merge!(members: members.delete(member))
 
-      Vedeu::Group.new(name: name, members: @members, visible: visible).store
+      Vedeu::Group.new(attrs).store
     end
 
     # Remove all members from the group.
     #
     # @return [Vedeu::Group]
     def reset
-      Vedeu::Group.new(defaults.merge!(name: name)).store
+      attrs = defaults.merge!(name: name)
+
+      Vedeu::Group.new(attrs).store
     end
 
     # Show the named group of interfaces, or without a name, the group of the
     # currently focussed interface.
     #
     # @example
+    #   Vedeu.trigger(:_show_group_, name)
     #   Vedeu.show_group(name)
     #
     # @return [Vedeu::Group]
@@ -104,7 +126,7 @@ module Vedeu
     # @return [Hash]
     def defaults
       {
-        members:    [],
+        members:    Set.new,
         name:       '',
         repository: Vedeu.groups,
         visible:    true,

data/lib/vedeu/models/interface.rb

@@ -10,7 +10,6 @@ module Vedeu
   # {Vedeu::Geometry}. It is a container for {Vedeu::Line} and {Vedeu::Stream}
   # objects.
   #
-  # @api private
   class Interface
 
     include Vedeu::Model
@@ -134,8 +133,8 @@ module Vedeu
 
       output = [
         Vedeu::Clear::NamedInterface.render(name),
-        Vedeu.borders.by_name(name).render,
         Vedeu::Viewport.render(self),
+        Vedeu.borders.by_name(name).render,
       ]
 
       Vedeu.trigger(:_show_cursor_, name)

data/lib/vedeu/models/line.rb

@@ -4,7 +4,6 @@ module Vedeu
   # {Vedeu::Stream} objects. A line's width is determined by the
   # {Vedeu::Interface} it belongs to.
   #
-  # @api private
   class Line
 
     include Vedeu::Model

data/lib/vedeu/models/menu.rb

@@ -3,7 +3,6 @@ module Vedeu
   # Converts the collection passed into a list of menu items which can be
   # navigated using the instance methods or events provided.
   #
-  # @api private
   class Menu
 
     include Vedeu::Model

data/lib/vedeu/models/stream.rb

@@ -4,7 +4,6 @@ module Vedeu
   # {Vedeu::Line} which you wish to colour and style independently of the other
   # characters in that line.
   #
-  # @api private
   class Stream
 
     include Vedeu::Model

data/lib/vedeu/models/toggleable.rb

@@ -1,8 +1,11 @@
 module Vedeu
 
-  # Toggleable instance methods for certain models.
+  # This module provides behaviour for certain classes which can be toggled
+  # between being shown and hidden.
+  #
+  # Currently using this are: {Vedeu::Cursor}, {Vedeu::Group} and
+  # {Vedeu::Interface}.
   #
-  # @api private
   module Toggleable
 
     # @!attribute [rw] visible
@@ -10,6 +13,8 @@ module Vedeu
     attr_accessor :visible
     alias_method :visible?, :visible
 
+    # Set the visible state to false and store the model.
+    #
     # @return [FalseClass]
     def hide
       @visible = false
@@ -17,6 +22,8 @@ module Vedeu
       store
     end
 
+    # Set the visible state to true and store the model.
+    #
     # @return [TrueClass]
     def show
       @visible = true
@@ -24,6 +31,8 @@ module Vedeu
       store
     end
 
+    # Toggle the visible state and store the model.
+    #
     # @return [FalseClass|TrueClass]
     def toggle
       if visible?
@@ -35,11 +44,12 @@ module Vedeu
       end
     end
 
-    # Toggleable class methods for models.
+    # Provide class methods to models to allow the visibility to be changed.
     #
-    # @api private
     module ClassMethods
 
+      # Hides the model.
+      #
       # @param name [String]
       # @return [void]
       def hide(name = nil)
@@ -49,6 +59,8 @@ module Vedeu
       alias_method :hide_group,     :hide
       alias_method :hide_interface, :hide
 
+      # Shows the model.
+      #
       # @param name [String]
       # @return [void]
       def show(name = nil)
@@ -58,6 +70,8 @@ module Vedeu
       alias_method :show_group,     :show
       alias_method :show_interface, :show
 
+      # Toggles the visibility of the model.
+      #
       # @param name [String]
       # @return [void]
       def toggle(name = nil)
@@ -69,17 +83,13 @@ module Vedeu
 
       private
 
+      # Fetch the model by name.
+      #
       # @param name [String]
       # @param klass [void] The repository of the model.
       # @return [void]
       def model_by_name(name = nil, klass)
-        klass.by_name(model_name(name))
-      end
-
-      # @param name [String]
-      # @return [void]
-      def model_name(name = nil)
-        name || Vedeu.focus
+        klass.by_name(name || Vedeu.focus)
       end
 
     end # ClassMethods

data/lib/vedeu/null/all.rb

@@ -4,7 +4,6 @@ module Vedeu
   # real counterpart. In most cases the call is muted or returns a generic
   # value that does not halt processing.
   #
-  # @api private
   module Null
 
   end

data/lib/vedeu/null/border.rb

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

data/lib/vedeu/null/buffer.rb

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

data/lib/vedeu/null/generic.rb

@@ -4,7 +4,6 @@ module Vedeu
 
     # Provides a non-existent model to swallow messages.
     #
-    # @api private
     class Generic
 
       # Returns an instance of the Vedeu::Null::Generic class.

data/lib/vedeu/null/geometry.rb

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

data/lib/vedeu/null/interface.rb

@@ -6,7 +6,6 @@ module Vedeu
 
     # Provides a non-existent model to swallow messages.
     #
-    # @api private
     class Interface
 
       include Vedeu::Presentation

data/lib/vedeu/output/border.rb

@@ -10,7 +10,6 @@ module Vedeu
   # @note Refer to UTF-8 U+2500 to U+257F for border characters. More details
   #   can be found at: http://en.wikipedia.org/wiki/Box-drawing_character
   #
-  # @api private
   class Border
 
     extend Forwardable

data/lib/vedeu/output/clear/named_group.rb

@@ -1,10 +1,11 @@
 module Vedeu
 
+  # Provides the mechanisms to clear an interface or group of interfaces.
+  #
   module Clear
 
-    # Clear the named group.
+    # Clear the interfaces belonging to the named group.
     #
-    # @api private
     class NamedGroup
 
       class << self

data/lib/vedeu/output/clear/named_interface.rb

@@ -1,10 +1,11 @@
 module Vedeu
 
+  # Provides the mechanisms to clear an interface or group of interfaces.
+  #
   module Clear
 
     # Clear the named interface.
     #
-    # @api private
     class NamedInterface
 
       class << self

data/lib/vedeu/output/compressor.rb

@@ -4,7 +4,6 @@ module Vedeu
   # sequences, this class removes multiple occurences of the same escape
   # sequence, resulting in a smaller payload being sent to the renderer.
   #
-  # @api private
   class Compressor
 
     # @param output [Array<Array<Vedeu::Char>>]

data/lib/vedeu/output/html_char.rb

@@ -5,7 +5,6 @@ module Vedeu
   # Represents a {Vedeu::Char} as a HTML tag with value. By default, a table
   # cell is used.
   #
-  # @api private
   class HTMLChar
 
     include Vedeu::Common

data/lib/vedeu/output/output.rb

@@ -2,7 +2,6 @@ module Vedeu
 
   # Sends the output to the renderers.
   #
-  # @api private
   class Output
 
     # Writes output to the defined renderers.

data/lib/vedeu/output/presentation.rb

@@ -3,7 +3,6 @@ module Vedeu
   # This module allows the sharing of presentation concerns between the models:
   # Interface, Line and Stream.
   #
-  # @api private
   module Presentation
 
     # Returns the background colour for the model, or if it does not exist,

data/lib/vedeu/output/refresh_group.rb

@@ -4,7 +4,6 @@ module Vedeu
 
   # Refreshes the given named group of interfaces.
   #
-  # @api private
   class RefreshGroup
 
     include Vedeu::Common

data/lib/vedeu/output/render_border.rb

@@ -2,7 +2,6 @@ module Vedeu
 
   # Renders the provided border.
   #
-  # @api private
   class RenderBorder
 
     extend Forwardable

data/lib/vedeu/output/renderers/all.rb

@@ -11,7 +11,6 @@ module Vedeu
 
   # Provides a single interface to all registered renderers.
   #
-  # @api private
   module Renderers
 
     extend Enumerable

data/lib/vedeu/output/renderers/escape_sequence.rb

@@ -4,7 +4,6 @@ module Vedeu
 
     # A renderer which returns the escape sequence for each character.
     #
-    # @api private
     class EscapeSequence
 
       include Vedeu::RendererOptions

data/lib/vedeu/output/renderers/file.rb

@@ -4,7 +4,6 @@ module Vedeu
 
     # Writes the given output to a file.
     #
-    # @api private
     class File
 
       # Returns a new instance of Vedeu::Renderers::File.

data/lib/vedeu/output/renderers/html.rb

@@ -5,7 +5,6 @@ module Vedeu
     # Renders a {Vedeu::VirtualBuffer} or {Vedeu::Output} as a HTML snippet;
     # a table by default.
     #
-    # @api private
     class HTML < Vedeu::Renderers::File
 
       # Returns a new instance of Vedeu::Renderers::HTML.