compo 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 463952c33e420e5ab401ec9774208262b4606ebc
-  data.tar.gz: 59ff0efef46f9db2fd9fdf72c463fccb46b18b96
+  metadata.gz: 9a7465849db65d98eec1007ce000a7a75fa78309
+  data.tar.gz: 6472acc91b29bda5ba2c3886a0a50a88f28f8c74
 SHA512:
-  metadata.gz: ead1e453e9ba923f8dcb12b2c9ec211d8d8946323557175eb82c0236939afc42314bc83c139f4e4076b1d3c0f4850910afcad3a29ed4b67ef9309e209eb97dbc
-  data.tar.gz: 890b61d951ad12e56aa2f329506f803dbde105c8541afd2332fb520f973a745fbacd845a7b1f213f69230cfa51e4c326c9704427561a78c754fd6ed69ee1d14c
+  metadata.gz: 84cfa4992537c356070d0a2885cff6bfd3e6e39050bdb6986ac413d1c6920dc05316b945e5f2e1f7fe79fc044d318d602c3a6a9befc404ca9814b622a238737e
+  data.tar.gz: edd697d7696e8e96783d4e02bfc37852df79abbacab5b992c1c6b8d0c95002763416caaf9e2bc2e6f51f1c98960612783cc182339e6b0956ce6ef95873cad675

data/CHANGELOG

@@ -1,3 +1,11 @@
+0.4.0 (2014-05-22) ‘De Vorzon’
+  Big release with quite a few changes:
+  - (BACKWARDS INCOMPATIBILITY) Reorganise classes into submodules.  This has
+    changed the name of pretty much every class in Compo.
+  - Null composites are now renamed to be Leaf composites, for consistency.
+  - Add branch#find_url, as a shortcut for invoking a UrlFinder.
+  - Add Compo::Branches::Constant, a Leaf branch containing a constant value.
+
 0.3.1 (2014-05-21)
   - Add UrlFinder class, for finding children inside a composite structure via
     their URLs.

data/lib/compo/branches/array.rb

@@ -0,0 +1,17 @@
+require 'compo/branches/branch'
+require 'compo/composites'
+
+module Compo
+  module Branches
+    # A simple implementation of a branch, whose children are stored in an Array
+    #
+    # An array branch is a composite object that may be moved into other
+    # composite objects.  It stores its children as an Array, and the ID of each
+    # child is its current index in the array.  Inserting and removing items
+    # into the branch may change the IDs of items with higher indices in the
+    # array.
+    class Array < Compo::Composites::Array
+      include Branch
+    end
+  end
+end

data/lib/compo/branches/branch.rb

@@ -0,0 +1,35 @@
+require 'compo/mixins'
+require 'compo/finders'
+
+module Compo
+  module Branches
+    # A movable, URL referenceable parent tracker
+    #
+    # A Branch represents a fully-featured part of a composite object.  This
+    # abstract pattern is implemented concretely by Leaf (a Branch with no
+    # children), Array (a Branch with a list of numerically identified
+    # children), and Hash (a Branch with a hash of key-identified children).
+    module Branch
+      include Mixins::Movable
+      include Mixins::ParentTracker
+      include Mixins::UrlReferenceable
+
+      # Traverses this Branch and its children following a URL
+      #
+      # See Compo::Finders::Url for more information about what this means.
+      # This is a convenience wrapper over that method object, and is equivalent
+      # to 'Compo::Finders::Url.find(self, *args, &block)'.
+      #
+      # @api  public
+      # @example  From this Branch, find the item at 'a/b/1'.
+      #   branch.on_url('a/b/1') { |item| p item }
+      #
+      # @yieldparam [Object]  The found resource.
+      #
+      # @return [Object]  Whatever is returned by the block.
+      def find_url(*args, &block)
+        Compo::Finders::Url.find(self, *args, &block)
+      end
+    end
+  end
+end

data/lib/compo/branches/constant.rb

@@ -0,0 +1,34 @@
+require 'compo/branches/leaf'
+
+module Compo
+  module Branches
+    # A Leaf containing a constant value
+    #
+    # The value can be retrieved using #value.
+    class Constant < Leaf
+      # Initialises the Constant
+      #
+      # @api public
+      # @example  Initialising a Constant with a given value.
+      #   Constant.new(:value)
+      #
+      # @param value [Object] The value of the constant.
+      #
+      def initialize(value)
+        super()
+        @value = value
+      end
+
+      # Returns the current value of this Constant
+      #
+      # @api public
+      # @example  Retrieving a Constant's value.
+      #   const = Constant.new(:spoon)
+      #   const.value
+      #   #=> :spoon
+      #
+      # @return [Object]  The Constant's internal value.
+      attr_reader :value
+    end
+  end
+end

data/lib/compo/branches/hash.rb

@@ -0,0 +1,17 @@
+require 'compo/branches/branch'
+require 'compo/composites'
+
+module Compo
+  module Branches
+    # A simple implementation of a branch, whose children are stored in an Hash
+    #
+    # A hash branch is a composite object that may be moved into other composite
+    # objects.  It stores its children as an Hash, and the ID of each child is
+    # its hash key.  Inserting and removing items into the branch will not
+    # change the IDs of other items, but inserting with an existing key will
+    # remove the previous occupant.
+    class Hash < Compo::Composites::Hash
+      include Branch
+    end
+  end
+end

data/lib/compo/branches/leaf.rb

@@ -0,0 +1,15 @@
+require 'compo/branches/branch'
+require 'compo/composites'
+
+module Compo
+  module Branches
+    # A simple implementation of a leaf node
+    #
+    # Leaves have no children, but can be moved to one.  They implement the
+    # Composite API, but all additions and removals fail, and the Leaf always
+    # reports no children.
+    class Leaf < Compo::Composites::Leaf
+      include Branch
+    end
+  end
+end

data/lib/compo/branches.rb

@@ -0,0 +1,15 @@
+require 'compo/branches/array'
+require 'compo/branches/branch'
+require 'compo/branches/hash'
+require 'compo/branches/leaf'
+require 'compo/branches/constant'
+
+module Compo
+  # Module implementing the branch classes
+  #
+  # A branch is a fully-featured part of a Compo composite object.  It tracks
+  # both children (if applicable) and its parent (if any), and supports a range
+  # of helper methods for traversing the composite tree.
+  module Branches
+  end
+end

data/lib/compo/composites/array.rb

@@ -0,0 +1,105 @@
+require 'forwardable'
+require 'compo/composites/composite'
+
+module Compo
+  module Composites
+    # Implementation of Composite that stores its children in an Array.
+    #
+    # IDs for items entering an Array must be numeric, and will change if
+    # an item with an ID less than the item in question is deleted or inserted.
+    # This means the ID function for objects in an Array may report
+    # different values at different times.
+    #
+    # Adding an object at an occupied ID moves the occupant and those at
+    # successive IDs up by one.
+    class Array
+      include Composite
+      extend Forwardable
+
+      # Initialises an array composite
+      #
+      # @api  public
+      # @example  Initializes an array composite.
+      #   comp = Compo::Composites::Array.new
+      def initialize
+        @children = []
+      end
+
+      # Returns the array composite's children, as a Hash
+      #
+      # @api  public
+      # @example  Gets the children of an empty array composite.
+      #   comp.children
+      #   #=> {}
+      # @example  Gets the children of a populated array composite.
+      #   comp.children
+      #   #=> {0: :first, 1: :second}
+      #
+      # @return [Hash]  The Hash mapping the IDs of children to their values.
+      def children
+        ::Hash[(0...@children.size).zip(@children)]
+      end
+
+      private
+
+      def_delegator :@children, :delete, :remove!
+      def_delegator :@children, :delete_at, :remove_id!
+
+      # Inserts a child into the array composite with the given ID
+      #
+      # You probably want to use #add instead.
+      #
+      # @api  private
+      #
+      # @param id [Object]  The ID under which the child is to be added.
+      # @param child [Object]  The child to add to the array composite.
+      #
+      # @return [Object]  The newly added child, or nil if the ID was invalid.
+      def add!(id, child)
+        valid_id?(id) ? do_insert(id, child) : nil
+      end
+
+      # Checks to see if the given ID is valid
+      #
+      # A valid ID for ArrayComposites is a number between 0 and the current
+      # size of the children list.
+      #
+      # @api  private
+      #
+      # @param id [Object]  The candidate ID.
+      #
+      # @return [Boolean]  True if the ID is valid; false if not.
+      def valid_id?(id)
+        id.is_a?(Numeric) && (0..@children.size).cover?(id)
+      end
+
+      # Actually performs the insertion of an item into the array
+      #
+      # @api  private
+      #
+      # @param id [Numeric]  The index into the array at which the child is to
+      #   be inserted.
+      # @param child [Object]  The object to insert into the children array.
+      #
+      # @return [Object]  The inserted child.
+      def do_insert(id, child)
+        @children.insert(id, child)
+        child
+      end
+
+      # Creates an ID function for the given child
+      #
+      # The returned proc is O(n), as it checks the child array at each call to
+      # find the current ID of the child.
+      #
+      # @api  private
+      #
+      # @param child [Object]  The child whose ID is to be returned by the proc.
+      #
+      # @return [Proc]  A proc returning the child's ID.
+      def id_function(object)
+        proc { @children.index(object) }
+      end
+    end
+  end
+end

data/lib/compo/composites/composite.rb

@@ -0,0 +1,183 @@
+require 'forwardable'
+
+module Compo
+  module Composites
+    # Mixin for objects that can contain other objects
+    #
+    # Objects implementing this interface should implement add!, remove! or
+    # remove_id!, and id_function.
+    #
+    # add!        - Given a desired ID and child, adds the child to the children
+    #               of this object; returns the child if successful, nil
+    #               otherwise.
+    # remove!     - Given a child, removes and returns it from the children; if
+    #               not provided, this is implemented in terms of remove_id!.
+    # remove_id!  - Given an ID, removes and returns the child with this ID from
+    #               the children; if not provided, this is implemented in terms
+    #               of remove!.
+    # children    - Returns the children, as a Hash mapping from current IDs to
+    #               their child values.
+    # id_function - Given a newly inserted child, returns a proc that will
+    #               always return the child's current ID so long as it is part
+    #               of the Composite.
+    module Composite
+      extend Forwardable
+      include Enumerable
+
+      # Adds a child to this Composite
+      #
+      # @api  public
+      # @example  Adds a child with intended id 3.
+      #   composite.add_child(3, leaf)
+      #
+      # @param id  [Object]  The intended ID of the child in this Composite.
+      #   The actual ID may not be the same as this; consult the proc supplied
+      #   to the child via #update_parent.
+      # @param child [Object]  The child to add to this Composite.
+      #
+      # @return [Object]  The added child if successful; nil otherwise.
+      def add(id, child)
+        add!(id, child).tap(&method(:assign_parent_to))
+      end
+
+      # Removes a child from this Composite directly
+      #
+      # This method can fail (for example, if the child does not exist in the
+      # Composite).
+      #
+      # @api  public
+      # @example  Removes a child.
+      #   composite.remove(child)
+      #
+      # @param child [Object]  The child to remove from this object.
+      #
+      # @return [Object]  The removed child if successful; nil otherwise.
+      def remove(child)
+        remove!(child).tap(&method(:remove_parent_of))
+      end
+
+      # Removes a child from this Composite, given its ID
+      #
+      # This method can fail (for example, if the ID does not exist in the
+      # Composite).
+      #
+      # @api  public
+      # @example  Removes the child with ID :foo.
+      #   composite.remove_id(:foo)
+      #
+      # @param id  The ID of the child to remove from this object.
+      #
+      # @return [Object]  The removed child if successful; nil otherwise.
+      def remove_id(id)
+        remove_id!(id).tap(&method(:remove_parent_of))
+      end
+
+      # Gets the child in this Composite with the given ID
+      #
+      # The ID is compared directly against the IDs of the children of this
+      # composite.  To use a predicate to find an ID, use #get_child_such_that.
+      #
+      # @api  public
+      # @example  Gets the child with ID :in, if children is {in: 3}.
+      #   composite.get_child(:in)
+      #   #=> 3
+      # @example  Fails to get the child with ID :out, if children is {in: 3}.
+      #   composite.get_child(:out)
+      #   #=> nil
+      # @example Fails to get the child with ID '1', if children is {1 => 3}.
+      #   composite.get_child('1')
+      #   #=> nil
+      #
+      # @param id  [Object]  The ID of the child to get from this Composite.
+      #
+      # @return [Object]  The child if successful; nil otherwise.
+      def get_child(id)
+        children[id]
+      end
+
+      # Gets the child in this Composite whose ID matches a given predicate
+      #
+      # If multiple children match this predicate, the result is the first child
+      # in the hash.
+      #
+      # @api  public
+      # @example  Gets the child with ID :in, if children is {in: 3}.
+      #   composite.get_child_such_that { |x| x == :in }
+      #   #=> 3
+      # @example  Fails to get the child with ID :out, if children is {in: 3}.
+      #   composite.get_child_such_that { |x| x == :out }
+      #   #=> nil
+      # @example Get the child with an ID whose string form is '1', if children
+      #   is {1 => 3}.
+      #   composite.get_child_such_that { |x| x.to_s == '3' }
+      #   #=> 3
+      #
+      # @yieldparam id  [Object]  An ID to check against the predicate.
+      #
+      # @return [Object]  The child if successful; nil otherwise.
+      def get_child_such_that(&block)
+        child = children.each.find { |k, _| block.call(k) }
+        (_, value) = child unless child.nil?
+        value
+      end
+
+      def_delegator :children, :each
+
+      protected
+
+      # Assigns this object to a child as its parent
+      #
+      # This also updates its ID function to point to the child's ID under this
+      # parent.
+      #
+      # @api  private
+      #
+      # @param child [Object]  The child whose parent assignment is being set.
+      #
+      # @return [void]
+      def assign_parent_to(child)
+        child.update_parent(self, id_function(child)) unless child.nil?
+      end
+
+      # Removes a child's parent assignment
+      #
+      # This also clears its ID function.
+      #
+      # @api  private
+      #
+      # @param child [Object]  The child whose parent assignment is being set.
+      #
+      # @return [void]
+      def remove_parent_of(child)
+        Parentless.for(child)
+      end
+
+      # Default implementation of #remove! in terms of #remove_id!
+      #
+      # Either this or #remove_id! must be overridden by the implementing class.
+      #
+      # @api  private
+      #
+      # @param child [Object]  The child to remove from this object.
+      #
+      # @return [void]
+      def remove!(child)
+        remove_id!(children.key(child))
+      end
+
+      # Default implementation of #remove_id! in terms of #remove!
+      #
+      # Either this or #remove! must be overridden by the implementing class.
+      #
+      # @api  private
+      #
+      # @param id [Object]  The current ID of the child to remove from this
+      #   object.
+      #
+      # @return [void]
+      def remove_id!(id)
+        remove!(get_child(id))
+      end
+    end
+  end
+end

data/lib/compo/composites/hash.rb

@@ -0,0 +1,72 @@
+require 'forwardable'
+require 'compo/composites/composite'
+
+module Compo
+  module Composites
+    # Implementation of Composite that stores its children in a Hash.
+    #
+    # IDs for items entering a ListComposite may be any permissible hash.
+    #
+    # Adding an item at an occupied ID removes the occupant.
+    class Hash
+      include Composite
+      extend Forwardable
+
+      # Initialises a hash composite
+      #
+      # @api  public
+      # @example  Initializes a hash composite.
+      #   comp = Compo::Composites::Hash.new
+      def initialize
+        @children = {}
+      end
+
+      # Returns the hash composite's children, as a Hash
+      #
+      # @api  public
+      # @example  Gets the children of an empty hash composite.
+      #   comp.children
+      #   #=> {}
+      # @example  Gets the children of a populated hash composite.
+      #   comp.children
+      #   #=> {foo: 3, bar: 5}
+      #
+      # @return [Hash]  The Hash mapping the IDs of children to their values.
+      attr_reader :children
+
+      private
+
+      # Inserts a child into the hash composite with the given ID
+      #
+      # You probably want to use #add instead.
+      #
+      # @api  private
+      #
+      # @param id [Object]  The ID under which the child is to be added.
+      # @param child [Object]  The child to add to the hash composite.
+      #
+      # @return [Object]  The newly added child.
+      def add!(id, child)
+        remove_id(id)
+        @children[id] = child
+      end
+
+      def_delegator :@children, :delete, :remove_id!
+
+      # Creates an ID function for the given child
+      #
+      # The returned proc is O(1), as it stores the ID assigned to the child at
+      # calling time under the assumption that it will not change until removal.
+      #
+      # @api  private
+      #
+      # @param child [Object]  The child whose ID is to be returned by the proc.
+      #
+      # @return [Proc]  A proc returning the child's ID.
+      def id_function(child)
+        id = @children.key(child)
+        proc { id }
+      end
+    end
+  end
+end

data/lib/compo/composites/leaf.rb

@@ -0,0 +1,64 @@
+require 'compo/composites/composite'
+
+module Compo
+  module Composites
+    # A Composite that cannot have children
+    #
+    # Add/remove operations on a leaf composite always fail, and #children
+    # always returns the empty hash.
+    #
+    # This is useful for leaf classes that still need to expose the composite
+    # API.
+    class Leaf
+      include Composite
+
+      # Returns the empty hash
+      #
+      # @api  public
+      # @example  Gets the children
+      #   comp.children
+      #   #=> {}
+      #
+      # @return [Hash]  The empty hash.
+      def children
+        {}
+      end
+
+      private
+
+      # Fails to add a child into the leaf
+      #
+      # @api  private
+      #
+      # @param id [Object]  Ignored.
+      # @param child [Object]  Ignored.
+      #
+      # @return [nil]
+      def add!(_, _)
+        nil
+      end
+
+      # Fails to remove the given child
+      #
+      # @api  private
+      #
+      # @param child [Object]  Ignored.
+      #
+      # @return [nil]
+      def remove!(_)
+        nil
+      end
+
+      # Fails to remove the child with the given ID
+      #
+      # @api  private
+      #
+      # @param id [Object]  Ignored.
+      #
+      # @return [nil]
+      def remove_id!(_)
+        nil
+      end
+    end
+  end
+end