compo 0.3.1 → 0.4.0

data/lib/compo/array_composite.rb

@@ -1,103 +0,0 @@
-require 'forwardable'
-require 'compo/composite'
-
-module Compo
-  # Implementation of Composite that stores its children in an Array.
-  #
-  # IDs for items entering a ListComposite 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 a ListComposite 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 ArrayComposite
-    include Composite
-    extend Forwardable
-
-    # Initialises an ArrayComposite
-    #
-    # @api  public
-    # @example  Initializes an ArrayComposite.
-    #   comp = ArrayComposite.new
-    def initialize
-      @children = []
-    end
-
-    # Returns the ArrayComposite's children, as a Hash
-    #
-    # @api  public
-    # @example  Gets the children of an empty ArrayComposite.
-    #   comp.children
-    #   #=> {}
-    # @example  Gets the children of a populated ArrayComposite.
-    #   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 ArrayComposite 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 ArrayComposite.
-    #
-    # @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

data/lib/compo/branch.rb

@@ -1,18 +0,0 @@
-require 'compo/movable'
-require 'compo/parent_tracker'
-require 'compo/url_referenceable'
-
-module Compo
-  # 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), ArrayBranch (a Branch with a list of numerically identified
-  # children), and HashBranch (a Branch with a hash of key-identified children).
-  # reports no children.
-  module Branch
-    include Movable
-    include ParentTracker
-    include UrlReferenceable
-  end
-end

data/lib/compo/composite.rb

@@ -1,181 +0,0 @@
-require 'forwardable'
-
-module Compo
-  # 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

data/lib/compo/hash_branch.rb

@@ -1,17 +0,0 @@
-require 'compo/branch'
-
-module Compo
-  # A simple implementation of a branch, whose children are stored in an Hash
-  #
-  # An HashBranch 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 HashBranch will not
-  # change the IDs of other items, but inserting with an existing key will
-  # remove the previous occupant.
-  #
-  # This is an extension of HashComposite to include the Movable and
-  # ParentTracker mixins.
-  class HashBranch < HashComposite
-    include Branch
-  end
-end

data/lib/compo/hash_composite.rb

@@ -1,70 +0,0 @@
-require 'forwardable'
-require 'compo/composite'
-
-module Compo
-  # 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 HashComposite
-    include Composite
-    extend Forwardable
-
-    # Initialises a HashComposite
-    #
-    # @api  public
-    # @example  Initializes a HashComposite.
-    #   comp = HashComposite.new
-    def initialize
-      @children = {}
-    end
-
-    # Returns the HashComposite's children, as a Hash
-    #
-    # @api  public
-    # @example  Gets the children of an empty HashComposite.
-    #   comp.children
-    #   #=> {}
-    # @example  Gets the children of a populated HashComposite.
-    #   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 HashComposite 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 HashComposite.
-    #
-    # @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

data/lib/compo/leaf.rb

@@ -1,14 +0,0 @@
-require 'compo/branch'
-require 'compo/null_composite'
-require 'compo/parent_tracker'
-
-module Compo
-  # 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 < NullComposite
-    include Branch
-  end
-end

data/lib/compo/movable.rb

@@ -1,53 +0,0 @@
-module Compo
-  # Helper mixin for objects that can be moved into other objects
-  #
-  # This mixin defines a method, #move_to, which handles removing a child
-  # from its current parent and adding it to a new one.
-  #
-  # It expects the current parent to be reachable from #parent.
-  module Movable
-    # Moves this model object to a new parent with a new ID
-    #
-    # @api  public
-    # @example  Moves the object to a new parent.
-    #   movable.move_to(parent, :id)
-    # @example  Moves the object out of its parent (deleting it, if there are
-    #   no other live references).
-    #   movable.move_to(nil, nil)
-    #
-    # @param new_parent [ModelObject] The new parent for this object (can be
-    #   nil).
-    # @param new_id [Object]  The new ID under which the object will exist in
-    #   the parent.
-    #
-    # @return [self]
-    def move_to(new_parent, new_id)
-      move_from_old_parent
-      move_to_new_parent(new_parent, new_id)
-      self
-    end
-
-    private
-
-    # Performs the move from an old parent, if necessary
-    #
-    # @api private
-    #
-    # @return [void]
-    def move_from_old_parent
-      parent.remove(self)
-    end
-
-    # Performs the move to a new parent, if necessary
-    #
-    # @api private
-    #
-    # @param new_parent [Composite]  The target parent of the move.
-    # @param new_id [Object]  The intended new ID of this child.
-    #
-    # @return [void]
-    def move_to_new_parent(new_parent, new_id)
-      new_parent.add(new_id, self) unless new_parent.nil?
-    end
-  end
-end

data/lib/compo/null_composite.rb

@@ -1,62 +0,0 @@
-require 'compo/composite'
-
-module Compo
-  # Null implementation of Composite
-  #
-  # Add/remove operations on NullComposite always fail, and #children always
-  # returns the empty hash.
-  #
-  # This is useful for leaf classes that still need to expose the composite
-  # API.
-  class NullComposite
-    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 NullComposite
-    #
-    # @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

data/lib/compo/parent_tracker.rb

@@ -1,80 +0,0 @@
-require 'forwardable'
-require 'compo/parentless'
-
-module Compo
-  # Basic implementation of parent tracking as a mixin
-  #
-  # This implements #parent, #update_parent and #remove_parent to track the
-  # current parent and ID function as instance variables.  It also implements
-  # #parent, and #id in terms of the ID function.
-  module ParentTracker
-    extend Forwardable
-
-    # Initialises the ParentTracker
-    #
-    # This constructor sets the tracker up so it initially has an instance of
-    # Parentless as its 'parent'.
-    #
-    # @api  semipublic
-    # @example  Creates a new ParentTracker.
-    #   ParentTracker.new
-    #
-    # @return [Void]
-    def initialize
-      super()
-      remove_parent
-    end
-
-    # Gets this object's current ID
-    #
-    # @api  public
-    # @example  Gets the object's parent while it has none.
-    #   parent_tracker.parent
-    #   #=> nil
-    # @example  Gets the object's parent while it has one.
-    #   parent_tracker.parent
-    #   #=> :the_current_parent
-    #
-    # @return [Composite]  The current parent.
-    attr_reader :parent
-
-    # Gets this object's current ID
-    #
-    # @api  public
-    # @example  Gets the object's ID while it has no parent.
-    #   parent_tracker.id
-    #   #=> nil
-    # @example  Gets the object's ID while it has a parent.
-    #   parent_tracker.id
-    #   #=> :the_current_id
-    #
-    # @return [Object]  The current ID.
-    def_delegator :@id_function, :call, :id
-
-    # Updates this object's parent and ID function
-    #
-    # @api  public
-    # @example  Update this Leaf's parent and ID function.
-    #   parent_tracker.update_parent(new_parent, new_id_function)
-    #
-    # @return [void]
-    def update_parent(new_parent, new_id_function)
-      fail 'Parent cannot be nil: use #remove_parent.' if new_parent.nil?
-      fail 'ID function cannot be nil: use -> { nil }.' if new_id_function.nil?
-
-      @parent = new_parent
-      @id_function = new_id_function
-    end
-
-    # Blanks out this object's parent and ID function
-    #
-    # @api  public
-    # @example  Update this Leaf's parent and ID function.
-    #   movable.update_parent(new_parent, new_id_function)
-    #
-    # @return [void]
-    def remove_parent
-      update_parent(Parentless.new, -> { nil })
-    end
-  end
-end