compo 0.3.1 → 0.4.0

data/lib/compo/composites/parentless.rb

@@ -0,0 +1,133 @@
+require 'compo/composites/composite'
+
+module Compo
+  module Composites
+    # A Composite that represents the non-existent parent of an orphan
+    #
+    # Parentless is the parent assigned when an object is removed from a
+    # Composite, and should be the default parent of an object that can be
+    # added to one.  It exists to make some operations easier, such as URL
+    # creation.
+    class Parentless
+      include Composite
+
+      # Creates a new instance of Parentless and adds an item to it
+      #
+      # This effectively removes the item's parent.
+      #
+      # If this method is passed nil, then nothing happens.
+      #
+      # @api  public
+      # @example  Makes a new Parentless for an item.
+      #   Parentless.for(item)
+      # @example  Does nothing.
+      #   Parentless.for(nil)
+      #
+      # @param item [Object] The item to be reparented to a Parentless.
+      #
+      # @return [void]
+      def self.for(item)
+        new.add(nil, item) unless item.nil?
+      end
+
+      # 'Removes' a child from this Parentless
+      #
+      # This always succeeds, and never triggers any other action.
+      #
+      # @api  public
+      # @example  'Removes' a child.
+      #   parentless.remove(child)
+      #
+      # @param child [Object]  The child to 'remove' from this Parentless.
+      #
+      # @return [Object]  The child.
+      def remove(child)
+        child
+      end
+
+      # Returns the empty hash
+      #
+      # @api  public
+      # @example  Gets the children
+      #   parentless.children
+      #   #=> {}
+      #
+      # @return [Hash]  The empty hash.
+      def children
+        {}
+      end
+
+      # Returns the URL of this Parentless
+      #
+      # This is always the empty string.
+      #
+      # @api  public
+      # @example  Gets the URL of a Parentless
+      #   parentless.url
+      #   #=> ''
+      #
+      # @return [Hash]  The empty string.
+      def url
+        ''
+      end
+
+      # Given the ID of a child in this Parentless, returns that child's URL
+      #
+      # This is always the empty string.  This is so that children of orphan
+      # objects have URLs starting with /their_id.
+      #
+      # @api  public
+      # @example  Gets the URL of the child of a Parentless.
+      #   parentless.child_url(:child_id)
+      #   #=> ''
+      #
+      # @return [Hash]  The empty string.
+      def child_url(_)
+        ''
+      end
+
+      # Returns the parent of this Parentless
+      #
+      # This is always the same Parentless, for convenience's sake.
+      # Technically, as a null object, Parentless has no parent.
+      #
+      # @api public
+      # @example  Gets the 'parent' of a Parentless.
+      #   parentless.parent
+      #
+      # @return [self]
+      def parent
+        self
+      end
+
+      protected
+
+      # 'Adds' a child to this Parentless
+      #
+      # This always succeeds.
+      #
+      # @api private
+      #
+      # @param id [Object]  Ignored.
+      # @param child [Object]  The object to 'add' to this Parentless.
+      #
+      # @return [Object]  The child.
+      def add!(_, child)
+        child
+      end
+
+      # Creates an ID function for the given child
+      #
+      # The returned proc is O(1), and always returns nil.
+      #
+      # @api  private
+      #
+      # @param child [Object]  The child whose ID is to be returned by the proc.
+      #
+      # @return [Proc]  A proc returning nil.
+      def id_function(_)
+        -> { nil }
+      end
+    end
+  end
+end

data/lib/compo/composites.rb

@@ -0,0 +1,20 @@
+require 'compo/composites/composite'
+require 'compo/composites/array'
+require 'compo/composites/hash'
+require 'compo/composites/leaf'
+require 'compo/composites/parentless'
+
+module Compo
+  # Submodule containing implementations of composite objects
+  #
+  # These classes only implement the concept of an object containing children,
+  # and those children being stored in such a way that they can be retrieved by
+  # ID.  For the full Compo experience, including parent tracking, URL
+  # referencing, and moving of objects between parents, see the Branches
+  # submodule.
+  #
+  # The Composites are the lowest level of Compo; everything else is an
+  # extension to them.
+  module Composites
+  end
+end

data/lib/compo/finders/url.rb

@@ -0,0 +1,166 @@
+module Compo
+  module Finders
+    # A method object for finding an item in a composite tree via its URL
+    #
+    # These are *not* thread-safe.
+    class Url
+      # Initialises an URL finder
+      #
+      # @api  public
+      # @example  Initialises an UrlFinder with default missing resource
+      #   handling.
+      #   UrlFinder.new(composite, 'a/b/c')
+      # @example  Initialises an UrlFinder returning a default value.
+      #   UrlFinder.new(composite, 'a/b/c', missing_proc=->(_) { :default })
+      #
+      # @param root [Composite] A composite object serving as the root of the
+      #   search tree, and the URL.
+      #
+      # @param url [String] A partial URL that follows this model object's URL
+      #   to form the URL of the resource to locate.  Can be nil, in which case
+      #   this object is returned.
+      #
+      # @param missing_proc [Proc] A proc to call, with the requested URL, if
+      #   the resource could not be found.  If nil (the default), this raises a
+      #   string exception.
+      def initialize(root, url, missing_proc: nil)
+        @root         = root
+        @url          = url
+        @missing_proc = missing_proc || method(:default_missing_proc)
+
+        reset
+      end
+
+      # Finds the model object at a URL, given a model root
+      #
+      # @api  public
+      # @example  Finds a URL with default missing resource handling.
+      #   UrlFinder.find(composite, 'a/b/c') { |item| p item }
+      #
+      # @param (see #initialize)
+      #
+      # @yieldparam (see #run)
+      #
+      # @return [Object]  The return value of the block.
+      def self.find(*args, &block)
+        new(*args).run(&block)
+      end
+
+      # Attempts to find a child resource with the given partial URL
+      #
+      # If the resource is found, it will be yielded to the attached block;
+      # otherwise, an exception will be raised.
+      #
+      # @api  public
+      # @example  Runs an UrlFinder, returning the item unchanged.
+      #   finder.run { |item| item }
+      #   #=> item
+      #
+      # @yieldparam resource [ModelObject]  The resource found.
+      # @yieldparam args [Array]  The splat from above.
+      #
+      # @return [Object]  The return value of the block.
+      def run
+        # We're traversing down the URL by repeatedly splitting it into its
+        # head (part before the next /) and tail (part after).  While we still
+        # have a tail, then the URL still needs walking down.
+        reset
+        descend until hit_end_of_url?
+        yield @resource
+      end
+
+      private
+
+      # Performs a descending step in the URL finder
+      #
+      # This tries to move down a level of the URL hierarchy, fetches the
+      # resource at that level, and fails according to @missing_proc if there is
+      # no such resource.
+      #
+      # @api  private
+      #
+      # @return [Void]
+      def descend
+        descend_url
+        next_resource
+        fail_with_no_resource if @resource.nil?
+      end
+
+      # Seeks to the next resource pointed at by @next_id
+      #
+      # @api  private
+      #
+      # @return [Void]
+      def next_resource
+        @resource = @resource.get_child_such_that { |id| id.to_s == @next_id }
+      end
+
+      # Fails, using @missing_proc, due to a missing resource
+      #
+      # @api  private
+      #
+      # @return [Void]
+      def fail_with_no_resource
+        # If the proc returns a value instead of raising an error, then set
+        # things up so that value is yielded in place of the missing resource.
+        @tail = nil
+        @resource = @missing_proc.call(@url)
+      end
+
+      # Default value for @missing_proc
+      #
+      # @api  private
+      #
+      # @param url [String]  The URL whose finding failed.
+      #
+      # @return [Void]
+      def default_missing_proc(url)
+        fail("Could not find resource: #{url}")
+      end
+
+      # Decides whether we have reached the end of the URL
+      #
+      # @api  private
+      #
+      # @return [Boolean]  Whether we have hit the end of the URL.
+      def hit_end_of_url?
+        @tail.nil? || @tail.empty?
+      end
+
+      # Splits the tail on the next URL level
+      #
+      # @api  private
+      #
+      # @return [Void]
+      def descend_url
+        @next_id, @tail = @tail.split('/', 2)
+      end
+
+      # Resets this UrlFinder so it can be used again
+      #
+      # @api  private
+      #
+      # @return [Void]
+      def reset
+        @next_id, @tail = nil, trimmed_url
+        @resource = @root
+      end
+
+      # Removes any leading or trailing slash from the URL, returning the result
+      #
+      # This only removes one leading or trailing slash.  Thus, '///' will be
+      # returned as '/'.
+      #
+      # @api  private
+      #
+      # @return [String] The URL with no trailing or leading slash.
+      def trimmed_url
+        first, last = 0, @url.length
+        first += 1 if @url.start_with?('/')
+        last  -= 1 if @url.end_with?('/')
+
+        @url[first...last]
+      end
+    end
+  end
+end

data/lib/compo/finders.rb

@@ -0,0 +1,10 @@
+require 'compo/finders/url'
+
+module Compo
+  # Module implementing the finders
+  #
+  # A finder is a method object that performs some form of traversal on a
+  # branch or composite.
+  module Finders
+  end
+end

data/lib/compo/mixins/movable.rb

@@ -0,0 +1,55 @@
+module Compo
+  module Mixins
+    # 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
+end

data/lib/compo/mixins/parent_tracker.rb

@@ -0,0 +1,74 @@
+require 'forwardable'
+require 'compo/composites/parentless'
+
+module Compo
+  module Mixins
+    # Basic implementation of parent tracking as a mixin
+    #
+    # Adding this to a Composite allows the composite to be aware of its current
+    # parent.
+    #
+    # 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()
+        Compo::Composites::Parentless.for(self)
+      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_proc, :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_proc)
+        fail 'Parent cannot be nil: use #remove_parent.' if new_parent.nil?
+        fail 'ID function cannot be nil: use -> { nil }.' if new_id_proc.nil?
+
+        @parent = new_parent
+        @id_proc = new_id_proc
+      end
+    end
+  end
+end

data/lib/compo/mixins/url_referenceable.rb

@@ -0,0 +1,70 @@
+module Compo
+  module Mixins
+    # Adds ID-based 'URL's to Compo classes
+    #
+    # For the purposes of this module, a URL is a string of slash-delimited IDs
+    # representing the location of a Composite in the tree structure formed by
+    # its ancestors.  Depending on the types of IDs used in the structure, the
+    # URLs may not actually be literal Uniform Resource Locators.
+    #
+    # This module expects its includer to define #parent and #id.  These are
+    # defined, for example, by the Compo::ParentTracker mixin.
+    module UrlReferenceable
+      extend Forwardable
+
+      # Returns the URL of this object
+      #
+      # The #url of a Composite is defined inductively as '' for composites that
+      # have no parent, and the joining of the parent URL and the current ID
+      # otherwise.
+      #
+      # The result of #url can be used to give a URL hierarchy to Composites.
+      #
+      # @api  public
+      # @example  Gets the URL of an object with no parent.
+      #   orphan.url
+      #   #=> ''
+      # @example  Gets the URL of an object with a parent.
+      #   leaf.url
+      #   #=> 'grandparent_id/parent_id/id'
+      #
+      # @return [String]  The URL of this object.
+      def url
+        parent.child_url(id)
+      end
+
+      # Returns the URL of a child of this object, with the given ID
+      #
+      # This defaults to joining the ID to this object's URL with a slash.
+      #
+      # @api  public
+      # @example  Gets the URL of the child of an object without a parent.
+      #   orphan.child_url(:id)
+      #   #=> '/id'
+      # @example  Gets the URL of the child of an object with a parent.
+      #   leaf.child_url(:id)
+      #   #=> 'grandparent_id/parent_id/id'
+      #
+      # @param child_id [Object]  The ID of the child whose URL is sought.
+      #
+      # @return [String]  The URL of the child with the given ID.
+      def child_url(child_id)
+        [url, child_id].join('/')
+      end
+
+      # Returns the URL of this object's parent
+      #
+      # @api  public
+      # @example  Gets the parent URL of an object with no parent.
+      #   orphan.parent_url
+      #   #=> nil
+      # @example  Gets the URL of an object with a parent.
+      #   leaf.parent_url
+      #   #=> 'grandparent_id/parent_id'
+      #
+      # @return [String]  The URL of this object's parent, or nil if there is no
+      #   parent.
+      def_delegator :parent, :url, :parent_url
+    end
+  end
+end

data/lib/compo/mixins.rb

@@ -0,0 +1,9 @@
+require 'compo/mixins/movable'
+require 'compo/mixins/parent_tracker'
+require 'compo/mixins/url_referenceable'
+
+module Compo
+  # The module containing the various mixins that implement composite patterns
+  module Mixins
+  end
+end

data/lib/compo/version.rb

@@ -1,4 +1,4 @@
 # The current gem version.  See CHANGELOG for information.
 module Compo
-  VERSION = '0.3.1'
+  VERSION = '0.4.0'
 end

data/lib/compo.rb

@@ -1,24 +1,7 @@
-# Base mixins
-require 'compo/composite'
-require 'compo/movable'
-require 'compo/parent_tracker'
-require 'compo/url_referenceable'
-
-# Composite implementations
-require 'compo/array_composite'
-require 'compo/hash_composite'
-require 'compo/null_composite'
-require 'compo/parentless'
-
-# Leaf and branch classes
-require 'compo/array_branch'
-require 'compo/hash_branch'
-require 'compo/leaf'
-
-# Utilities
-require 'compo/url_finder'
-
-# Misc
+require 'compo/composites'
+require 'compo/mixins'
+require 'compo/branches'
+require 'compo/finders'
 require 'compo/version'
 
 # The main module for Compo

data/spec/array_branch_spec.rb

@@ -3,7 +3,9 @@ require 'compo'
 require 'array_composite_shared_examples'
 require 'branch_shared_examples'
 
-describe Compo::ArrayBranch do
-  it_behaves_like 'a branch'
+describe Compo::Branches::Array do
+  it_behaves_like 'a branch with children' do
+    let(:initial_ids) { [0, 1] }
+  end
   it_behaves_like 'an array composite'
 end

data/spec/array_composite_shared_examples.rb

@@ -123,7 +123,7 @@ shared_examples 'an array composite' do
 
       it 'calls #update_parent on the child with a Parentless' do
         expect(child1).to receive(:update_parent).once do |parent, _|
-          expect(parent).to be_a(Compo::Parentless)
+          expect(parent).to be_a(Compo::Composites::Parentless)
         end
         subject.remove(child1)
       end
@@ -171,7 +171,7 @@ shared_examples 'an array composite' do
 
       it 'calls #update_parent on the child with a Parentless' do
         expect(child1).to receive(:update_parent).once do |parent, _|
-          expect(parent).to be_a(Compo::Parentless)
+          expect(parent).to be_a(Compo::Composites::Parentless)
         end
         subject.remove_id(0)
       end

data/spec/array_composite_spec.rb

@@ -2,6 +2,6 @@ require 'spec_helper'
 require 'compo'
 require 'array_composite_shared_examples'
 
-describe Compo::ArrayComposite do
+describe Compo::Composites::Array do
   it_behaves_like 'an array composite'
 end

data/spec/branch_shared_examples.rb

@@ -1,3 +1,4 @@
+require 'url_finder_shared_examples'
 require 'url_referenceable_shared_examples'
 require 'movable_shared_examples'
 
@@ -7,7 +8,7 @@ shared_examples 'a branch' do
 
   describe '#initialize' do
     it 'initialises with a Parentless as parent' do
-      expect(subject.parent).to be_a(Compo::Parentless)
+      expect(subject.parent).to be_a(Compo::Composites::Parentless)
     end
 
     it 'initialises with an ID function returning nil' do
@@ -22,10 +23,10 @@ shared_examples 'a branch' do
       end
     end
     context 'when the Branch is the child of a root' do
-      let(:parent) { Compo::HashBranch.new }
+      let(:parent) { Compo::Branches::Hash.new }
       before(:each) { subject.move_to(parent, :id) }
 
-      it 'returns /ID, where ID is the ID of the Leaf' do
+      it 'returns /ID, where ID is the ID of the Branch' do
         expect(subject.url).to eq('/id')
       end
     end
@@ -34,11 +35,13 @@ shared_examples 'a branch' do
   describe '#move_to' do
     context 'when the Branch has a parent' do
       context 'when the new parent is nil' do
-        let(:parent) { Compo::HashBranch.new }
+        let(:parent) { Compo::Branches::Hash.new }
         before(:each) { subject.move_to(parent, :id) }
 
         it 'loses its previous parent' do
-          expect(subject.move_to(nil, :id).parent).to be_a(Compo::Parentless)
+          expect(subject.move_to(nil, :id).parent).to be_a(
+            Compo::Composites::Parentless
+          )
         end
 
         it 'is no longer a child of its parent' do
@@ -49,3 +52,33 @@ shared_examples 'a branch' do
     end
   end
 end
+
+shared_examples 'a branch with children' do
+  it_behaves_like 'a branch'
+
+  describe '#find_url' do
+    it_behaves_like 'a URL finding' do
+      let(:target) { Compo::Branches::Leaf.new }
+
+      before(:each) do
+        a    = Compo::Branches::Hash.new
+        b    = Compo::Branches::Array.new
+        d    = Compo::Branches::Leaf.new
+        e    = Compo::Branches::Leaf.new
+        zero = Compo::Branches::Leaf.new
+
+        a.move_to(subject, initial_ids[0])
+        b.move_to(a, 'b')
+        zero.move_to(b, 0)
+        target.move_to(b, 1)
+        d.move_to(subject, initial_ids[1])
+        e.move_to(a, 'e')
+      end
+
+      let(:correct_url)   { "#{initial_ids[0]}/b/1" }
+      let(:incorrect_url) { "#{initial_ids[0]}/z/1" }
+
+      let(:proc) { ->(*args, &b) { subject.find_url(*args, &b) } }
+    end
+  end
+end