compo 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4d82d283e9442502f0df1ce95352e5e3312f29cf
-  data.tar.gz: 6f32308cec8aa4cbf9484e04f9d7cdac1cd205ff
+  metadata.gz: c6db898fd60a7a46a30a7d851bd634c2be59a1d4
+  data.tar.gz: 78d2ccf08de768e42ca7df43a29f6491b0adbcfb
 SHA512:
-  metadata.gz: a5026150227f95c11b51babf65ea6c3aea4db97c43478604639c4b7a9792e77768650bf3520e10867eae5f81404fabf954c97b1ce103838ddd7536d7af4118ea
-  data.tar.gz: ea6aa80894e7bfb605ab31e57885aebe328da45bbd455804c784ac8ff694c575ee6a0d2ee37a6cc7d3a6735f82ea7a848196d80caae71c8d81e0a82f3c456c53
+  metadata.gz: 1694942f4173cd3c464a66d904ff36044ea714c79c8e2c8fc708d7c2d296dd28da42d760ebae89442c3734bf692fbf7ee3feceeebeecab5d00ce0d47ffa75f20
+  data.tar.gz: 1c7db6618f24c57980ad14b6200cd212d516d4c800e5718fe46964576eb9ec6175c06d3a1337997507fe972ba70da7b3bcd92d396026e527a99301217b1e3d17

data/.gitignore

@@ -1,3 +1,5 @@
+.ruby-version
+.ruby-gemset
 *.gem
 *.rbc
 .bundle

data/CHANGELOG

@@ -1,3 +1,11 @@
+0.2.0 (2013-12-29)
+  - (BACKWARDS INCOMPATIBILITY) Implement Parentless as a null object for the
+    result of calling #parent on a parentless child.  This case now returns
+    an instance of Parentless, not nil.
+  - #remove_child no longer exists, as Parentless calls #update_child with
+    itself when a parent removes a child.
+  - Numerous test improvements; now using shared examples.
+
 0.1.5 (2013-12-29)
   - Add a missing require 'forwardable', and remove one that wasn't needed.
 

data/lib/compo/composite.rb

@@ -116,7 +116,7 @@ module Compo
     #
     # @return [void]
     def remove_parent_of(child)
-      child.remove_parent unless child.nil?
+      Parentless.new.add(nil, child) unless child.nil?
     end
 
     # Default implementation of #remove! in terms of #remove_id!

data/lib/compo/parent_tracker.rb

@@ -1,4 +1,5 @@
 require 'forwardable'
+require 'compo/parentless'
 
 module Compo
   # Basic implementation of parent tracking as a mixin
@@ -58,7 +59,7 @@ module Compo
     #
     # @return [void]
     def remove_parent
-      update_parent(nil, -> { nil })
+      update_parent(Parentless.new, -> { nil })
     end
   end
 end

data/lib/compo/parentless.rb

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

data/lib/compo/url_referenceable.rb

@@ -27,7 +27,26 @@ module Compo
     #
     # @return [String]  The URL of this object.
     def url
-      parent.nil? ? '' : [parent_url, id].join('/')
+      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

data/lib/compo/version.rb

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

data/lib/compo.rb

@@ -8,6 +8,7 @@ require 'compo/url_referenceable'
 require 'compo/array_composite'
 require 'compo/hash_composite'
 require 'compo/null_composite'
+require 'compo/parentless'
 
 # Leaf and branch classes
 require 'compo/array_branch'

data/spec/array_branch_spec.rb

@@ -1,14 +1,9 @@
 require 'spec_helper'
 require 'compo'
+require 'array_composite_shared_examples'
+require 'branch_shared_examples'
 
 describe Compo::ArrayBranch do
-  describe '#initialize' do
-    it 'initialises with no parent' do
-      expect(subject.parent).to be_nil
-    end
-
-    it 'initialises with an ID function returning nil' do
-      expect(subject.id).to be_nil
-    end
-  end
+  it_behaves_like 'a branch'
+  it_behaves_like 'an array composite'
 end

data/spec/array_composite_shared_examples.rb

@@ -0,0 +1,240 @@
+require 'compo'
+require 'composite_shared_examples'
+
+shared_examples 'an array composite' do
+  it_behaves_like 'a composite'
+
+  let(:child1) { double(:child1) }
+  let(:child2) { double(:child2) }
+  let(:child3) { double(:child3) }
+
+  before(:each) do
+    allow(child1).to receive(:update_parent)
+    allow(child2).to receive(:update_parent)
+    allow(child3).to receive(:update_parent)
+  end
+
+  describe '#add' do
+    context 'when the ID is not Numeric' do
+      specify { expect(subject.add(:mr_flibble, child1)).to be_nil }
+
+      it 'does not add to the list of children' do
+        subject.add(:rimmer, child1)
+        expect(subject.children).to eq({})
+
+        subject.add(0, child1)
+        subject.add(:lister, child2)
+        expect(subject.children).to eq(0 => child1)
+
+        subject.add(1, child2)
+        subject.add(:cat, child3)
+        expect(subject.children).to eq(0 => child1, 1 => child2)
+      end
+    end
+    context 'when the ID is Numeric' do
+      context 'and is equal to the number of children' do
+        it 'returns the child' do
+          expect(subject.add(0, child1)).to eq(child1)
+          expect(subject.add(1, child2)).to eq(child2)
+          expect(subject.add(2, child3)).to eq(child3)
+        end
+
+        it 'adds to the end of the list of children' do
+          expect(subject.children).to eq({})
+
+          subject.add(0, child1)
+          expect(subject.children).to eq(0 => child1)
+
+          subject.add(1, child2)
+          expect(subject.children).to eq(0 => child1, 1 => child2)
+
+          subject.add(2, child3)
+          expect(subject.children).to eq(0 => child1, 1 => child2, 2 => child3)
+        end
+
+        it 'calls #update_parent on the child with itself and an ID proc' do
+          expect(child1).to receive(:update_parent) do |parent, proc|
+            expect(parent).to eq(subject)
+            expect(proc.call).to eq(0)
+          end
+          subject.add(0, child1)
+        end
+      end
+
+      context 'and is greater than the number of children' do
+        it 'returns nil' do
+          expect(subject.add(1, child1)).to be_nil
+          subject.add(0, child1)
+          expect(subject.add(2, child2)).to be_nil
+          subject.add(1, child2)
+          expect(subject.add(3, child3)).to be_nil
+        end
+
+        it 'does not add to the list of children' do
+          subject.add(1, child1)
+          expect(subject.children).to eq({})
+
+          subject.add(0, child1)
+          subject.add(2, child2)
+          expect(subject.children).to eq(0 => child1)
+
+          subject.add(1, child2)
+          subject.add(3, child3)
+          expect(subject.children).to eq(0 => child1, 1 => child2)
+        end
+      end
+
+      context 'and is less than the number of children' do
+        it 'returns the child' do
+          subject.add(0, child1)
+          expect(subject.add(0, child2)).to eq(child2)
+          expect(subject.add(1, child3)).to eq(child3)
+        end
+
+        it 'adds to the list of children at the correct position' do
+          expect(subject.children).to eq({})
+          subject.add(0, child1)
+          expect(subject.children).to eq(0 => child1)
+          subject.add(0, child2)
+          expect(subject.children).to eq(0 => child2, 1 => child1)
+          subject.add(1, child3)
+          expect(subject.children).to eq(0 => child2, 1 => child3, 2 => child1)
+        end
+
+        it 'calls #update_parent on the child with itself and an ID proc' do
+          expect(child1).to receive(:update_parent) do |parent, proc|
+            expect(parent).to eq(subject)
+            expect(proc.call).to eq(0)
+          end
+          subject.add(0, child2)
+          subject.add(0, child1)
+        end
+      end
+    end
+  end
+
+  describe '#remove' do
+    context 'when the child exists in the list' do
+      before(:each) { subject.add(0, child1) }
+
+      it 'returns the child' do
+        expect(subject.remove(child1)).to eq(child1)
+      end
+
+      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)
+        end
+        subject.remove(child1)
+      end
+
+      it 'calls #update_parent on the child with a nil-returning ID proc' do
+        expect(child1).to receive(:update_parent).once do |_, idp|
+          expect(idp.call).to be_nil
+        end
+        subject.remove(child1)
+      end
+
+      it 'moves succeeding IDs down by one' do
+        subject.add(1, child2)
+        subject.add(2, child3)
+        expect(subject.children).to eq(0 => child1, 1 => child2, 2 => child3)
+        subject.remove(child2)
+        expect(subject.children).to eq(0 => child1, 1 => child3)
+      end
+    end
+
+    context 'when the child does not exist in the list' do
+      specify { expect(subject.remove(child1)).to be_nil }
+
+      it 'does not change the children' do
+        expect(subject.children).to eq({})
+        subject.remove(child1)
+        expect(subject.children).to eq({})
+
+        subject.add(0, child1)
+        subject.add(1, child2)
+        expect(subject.children).to eq(0 => child1, 1 => child2)
+        subject.remove(child3)
+        expect(subject.children).to eq(0 => child1, 1 => child2)
+      end
+    end
+  end
+
+  describe '#remove_id' do
+    context 'when the ID exists' do
+      before(:each) { subject.add(0, child1) }
+
+      it 'returns the child' do
+        expect(subject.remove_id(0)).to eq(child1)
+      end
+
+      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)
+        end
+        subject.remove_id(0)
+      end
+
+      it 'calls #update_parent on the child with a nil-returning ID proc' do
+        expect(child1).to receive(:update_parent).once do |_, idp|
+          expect(idp.call).to be_nil
+        end
+        subject.remove_id(0)
+      end
+
+      it 'moves succeeding IDs down by one' do
+        subject.add(1, child2)
+        subject.add(2, child3)
+        expect(subject.children).to eq(0 => child1, 1 => child2, 2 => child3)
+        subject.remove_id(1)
+        expect(subject.children).to eq(0 => child1, 1 => child3)
+      end
+    end
+
+    context 'when the ID does not exist' do
+      specify { expect(subject.remove_id(0)).to be_nil }
+
+      it 'does not change the children' do
+        expect(subject.children).to eq({})
+        subject.remove_id(0)
+        expect(subject.children).to eq({})
+
+        subject.add(0, child1)
+        subject.add(1, child2)
+        expect(subject.children).to eq(0 => child1, 1 => child2)
+        subject.remove_id(2)
+        expect(subject.children).to eq(0 => child1, 1 => child2)
+      end
+    end
+  end
+
+  describe '#children' do
+    context 'when the list has no children' do
+      it 'returns the empty hash' do
+        expect(subject.children).to eq({})
+      end
+    end
+
+    context 'when the list has children' do
+      it 'returns a hash mapping their current indices to themselves' do
+        expect(subject.children).to eq({})
+
+        subject.add(0, child1)
+        expect(subject.children).to eq(0 => child1)
+
+        subject.add(1, child2)
+        expect(subject.children).to eq(0 => child1, 1 => child2)
+
+        subject.add(2, child3)
+        expect(subject.children).to eq(0 => child1, 1 => child2, 2 => child3)
+
+        subject.remove(child2)
+        expect(subject.children).to eq(0 => child1, 1 => child3)
+
+        subject.add(0, child2)
+        expect(subject.children).to eq(0 => child2, 1 => child1, 2 => child3)
+      end
+    end
+  end
+end

data/spec/array_composite_spec.rb

@@ -1,225 +1,7 @@
 require 'spec_helper'
 require 'compo'
+require 'array_composite_shared_examples'
 
 describe Compo::ArrayComposite do
-  let(:child1) { double(:child1) }
-  let(:child2) { double(:child2) }
-  let(:child3) { double(:child3) }
-
-  before(:each) do
-    allow(child1).to receive(:update_parent)
-    allow(child1).to receive(:remove_parent)
-
-    allow(child2).to receive(:update_parent)
-    allow(child2).to receive(:remove_parent)
-
-    allow(child3).to receive(:update_parent)
-    allow(child3).to receive(:remove_parent)
-  end
-
-  describe '#add' do
-    context 'when the ID is not Numeric' do
-      specify { expect(subject.add(:mr_flibble, child1)).to be_nil }
-
-      it 'does not add to the list of children' do
-        subject.add(:rimmer, child1)
-        expect(subject.children).to eq({})
-
-        subject.add(0, child1)
-        subject.add(:lister, child2)
-        expect(subject.children).to eq(0 => child1)
-
-        subject.add(1, child2)
-        subject.add(:cat, child3)
-        expect(subject.children).to eq(0 => child1, 1 => child2)
-      end
-    end
-    context 'when the ID is Numeric' do
-      context 'and is equal to the number of children' do
-        it 'returns the child' do
-          expect(subject.add(0, child1)).to eq(child1)
-          expect(subject.add(1, child2)).to eq(child2)
-          expect(subject.add(2, child3)).to eq(child3)
-        end
-
-        it 'adds to the end of the list of children' do
-          expect(subject.children).to eq({})
-
-          subject.add(0, child1)
-          expect(subject.children).to eq(0 => child1)
-
-          subject.add(1, child2)
-          expect(subject.children).to eq(0 => child1, 1 => child2)
-
-          subject.add(2, child3)
-          expect(subject.children).to eq(0 => child1, 1 => child2, 2 => child3)
-        end
-
-        it 'calls #update_parent on the child with itself and an ID proc' do
-          expect(child1).to receive(:update_parent) do |parent, proc|
-            expect(parent).to eq(subject)
-            expect(proc.call).to eq(0)
-          end
-          subject.add(0, child1)
-        end
-      end
-
-      context 'and is greater than the number of children' do
-        it 'returns nil' do
-          expect(subject.add(1, child1)).to be_nil
-          subject.add(0, child1)
-          expect(subject.add(2, child2)).to be_nil
-          subject.add(1, child2)
-          expect(subject.add(3, child3)).to be_nil
-        end
-
-        it 'does not add to the list of children' do
-          subject.add(1, child1)
-          expect(subject.children).to eq({})
-
-          subject.add(0, child1)
-          subject.add(2, child2)
-          expect(subject.children).to eq(0 => child1)
-
-          subject.add(1, child2)
-          subject.add(3, child3)
-          expect(subject.children).to eq(0 => child1, 1 => child2)
-        end
-      end
-
-      context 'and is less than the number of children' do
-        it 'returns the child' do
-          subject.add(0, child1)
-          expect(subject.add(0, child2)).to eq(child2)
-          expect(subject.add(1, child3)).to eq(child3)
-        end
-
-        it 'adds to the list of children at the correct position' do
-          expect(subject.children).to eq({})
-          subject.add(0, child1)
-          expect(subject.children).to eq(0 => child1)
-          subject.add(0, child2)
-          expect(subject.children).to eq(0 => child2, 1 => child1)
-          subject.add(1, child3)
-          expect(subject.children).to eq(0 => child2, 1 => child3, 2 => child1)
-        end
-
-        it 'calls #update_parent on the child with itself and an ID proc' do
-          expect(child1).to receive(:update_parent) do |parent, proc|
-            expect(parent).to eq(subject)
-            expect(proc.call).to eq(0)
-          end
-          subject.add(0, child2)
-          subject.add(0, child1)
-        end
-      end
-    end
-  end
-
-  describe '#remove' do
-    context 'when the child exists in the list' do
-      before(:each) { subject.add(0, child1) }
-
-      it 'returns the child' do
-        expect(subject.remove(child1)).to eq(child1)
-      end
-
-      it 'calls #remove_parent on the child' do
-        expect(child1).to receive(:remove_parent).once.with(no_args)
-        subject.remove(child1)
-      end
-
-      it 'moves succeeding IDs down by one' do
-        subject.add(1, child2)
-        subject.add(2, child3)
-        expect(subject.children).to eq(0 => child1, 1 => child2, 2 => child3)
-        subject.remove(child2)
-        expect(subject.children).to eq(0 => child1, 1 => child3)
-      end
-    end
-
-    context 'when the child does not exist in the list' do
-      specify { expect(subject.remove(child1)).to be_nil }
-
-      it 'does not change the children' do
-        expect(subject.children).to eq({})
-        subject.remove(child1)
-        expect(subject.children).to eq({})
-
-        subject.add(0, child1)
-        subject.add(1, child2)
-        expect(subject.children).to eq(0 => child1, 1 => child2)
-        subject.remove(child3)
-        expect(subject.children).to eq(0 => child1, 1 => child2)
-      end
-    end
-  end
-
-  describe '#remove_id' do
-    context 'when the ID exists' do
-      before(:each) { subject.add(0, child1) }
-
-      it 'returns the child' do
-        expect(subject.remove_id(0)).to eq(child1)
-      end
-
-      it 'calls #remove_parent on the child' do
-        expect(child1).to receive(:remove_parent).once.with(no_args)
-        subject.remove_id(0)
-      end
-
-      it 'moves succeeding IDs down by one' do
-        subject.add(1, child2)
-        subject.add(2, child3)
-        expect(subject.children).to eq(0 => child1, 1 => child2, 2 => child3)
-        subject.remove_id(1)
-        expect(subject.children).to eq(0 => child1, 1 => child3)
-      end
-    end
-
-    context 'when the ID does not exist' do
-      specify { expect(subject.remove_id(0)).to be_nil }
-
-      it 'does not change the children' do
-        expect(subject.children).to eq({})
-        subject.remove_id(0)
-        expect(subject.children).to eq({})
-
-        subject.add(0, child1)
-        subject.add(1, child2)
-        expect(subject.children).to eq(0 => child1, 1 => child2)
-        subject.remove_id(2)
-        expect(subject.children).to eq(0 => child1, 1 => child2)
-      end
-    end
-  end
-
-  describe '#children' do
-    context 'when the list has no children' do
-      it 'returns the empty hash' do
-        expect(subject.children).to eq({})
-      end
-    end
-
-    context 'when the list has children' do
-      it 'returns a hash mapping their current indices to themselves' do
-        expect(subject.children).to eq({})
-
-        subject.add(0, child1)
-        expect(subject.children).to eq(0 => child1)
-
-        subject.add(1, child2)
-        expect(subject.children).to eq(0 => child1, 1 => child2)
-
-        subject.add(2, child3)
-        expect(subject.children).to eq(0 => child1, 1 => child2, 2 => child3)
-
-        subject.remove(child2)
-        expect(subject.children).to eq(0 => child1, 1 => child3)
-
-        subject.add(0, child2)
-        expect(subject.children).to eq(0 => child2, 1 => child1, 2 => child3)
-      end
-    end
-  end
+  it_behaves_like 'an array composite'
 end