compo 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9a7465849db65d98eec1007ce000a7a75fa78309
-  data.tar.gz: 6472acc91b29bda5ba2c3886a0a50a88f28f8c74
+  metadata.gz: b36ac99cbd26e363126ccaa0e1a2dd20ba9d4b10
+  data.tar.gz: 3a026f05f3e59917727599e3cc83b2a7888e9bb8
 SHA512:
-  metadata.gz: 84cfa4992537c356070d0a2885cff6bfd3e6e39050bdb6986ac413d1c6920dc05316b945e5f2e1f7fe79fc044d318d602c3a6a9befc404ca9814b622a238737e
-  data.tar.gz: edd697d7696e8e96783d4e02bfc37852df79abbacab5b992c1c6b8d0c95002763416caaf9e2bc2e6f51f1c98960612783cc182339e6b0956ce6ef95873cad675
+  metadata.gz: 457dec32c46dabfa7e03b79545930df61cd9b9777dab0f8d8c436ec4dc425e091ab04b85af9810302fe9725809edab277c4f90a032676acc30fd3711d8c9032f
+  data.tar.gz: 18fd9981c0e31255bce927311b4c624ec2c08adbc27c9de043353228267230e3f896cfd6ac068ff28b2859dba8ca56a1869847cc57b8d65996aada33bed5af01

data/.rspec

@@ -1,2 +1 @@
---format Fuubar
 --color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.1.2

data/CHANGELOG

@@ -1,3 +1,14 @@
+0.5.0 (2014-07-10) ‘Brimble’
+  - Implement a root finder, which has the ability to enumerate the entire path
+    from a parent-tracking composite object up to its root.
+  - Implement new method #on_node, which executes a block if, and only if, the
+    object is an actual composite node (not a Parentless, etc.).
+  - Implement new method #root?, which returns true if, and only if, the
+    object does not have a valid parent (its parent ignores #on_node).
+  - Refactor UrlReferenceable such that URLs are calculated via the root finder.
+    This is now an iterative algorithm and shouldn't exhaust the stack on large
+    composites.
+  - (BACKWARDS INCOMPATIBILITY) Remove #child_url, as it is no longer needed.
 0.4.0 (2014-05-22) ‘De Vorzon’
   Big release with quite a few changes:
   - (BACKWARDS INCOMPATIBILITY) Reorganise classes into submodules.  This has

data/README.md

@@ -1,5 +1,8 @@
 # Compo
 
+[![Gem Version](https://badge.fury.io/rb/compo.svg)](http://badge.fury.io/rb/compo)
+[![Build Status](https://travis-ci.org/CaptainHayashi/compo.svg)](https://travis-ci.org/CaptainHayashi/compo)
+
 **Compo** is a library providing mixins and base classes for setting up
 composite objects.
 

data/compo.gemspec

@@ -9,11 +9,11 @@ Gem::Specification.new do |spec|
   spec.version       = Compo::VERSION
   spec.authors       = ['Matt Windsor']
   spec.email         = ['matt.windsor@ury.org.uk']
-  spec.description   = %q(
+  spec.description   = <<-DESC
     Compo provides mixins and classes that assist in implementing a variant of
     the Composite design pattern, in which each child has an ID that uniquely
     identifies it inside the parent's child set.
-  )
+  DESC
   spec.summary       = 'Composite pattern style mixins with IDs'
   spec.homepage      = 'http://github.com/CaptainHayashi/compo'
   spec.license       = 'MIT'
@@ -25,9 +25,8 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'backports'
   spec.add_development_dependency 'bundler', '~> 1.6'
-  spec.add_development_dependency 'fuubar'
   spec.add_development_dependency 'rake'
-  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rspec', '~> 3'
   spec.add_development_dependency 'simplecov'
   spec.add_development_dependency 'yard'
   spec.add_development_dependency 'yardstick'

data/lib/compo/composites/composite.rb

@@ -123,6 +123,22 @@ module Compo
 
       def_delegator :children, :each
 
+      # Performs an action on this node, if it is an actual Composite node
+      #
+      # By default, this does indeed run the block provided, and returns the
+      # block's result.  Composites that do not represent proper nodes (for
+      # example, Parentless) may override this to ignore the block and return
+      # nil.
+      #
+      # @api public
+      # @example  Performs an action on this Parentless.
+      #   parentless.on_node { |n| 3 }
+      #   #=> 3
+      # @return [false]
+      def on_node
+        yield self
+      end
+
       protected
 
       # Assigns this object to a child as its parent

data/lib/compo/composites/parentless.rb

@@ -71,21 +71,6 @@ module Compo
         ''
       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.
@@ -100,6 +85,20 @@ module Compo
         self
       end
 
+      # Performs an action on this node, if it is an actual Composite node
+      #
+      # A Parentless is not, and thus this method returns nil and ignores
+      # any block present.
+      #
+      # @api public
+      # @example  (Doesn't) perform an action on this Parentless.
+      #   parentless.on_node { |n| 3 }
+      #   #=> nil
+      # @return [nil]
+      def on_node
+        nil
+      end
+
       protected
 
       # 'Adds' a child to this Parentless

data/lib/compo/finders/root.rb

@@ -0,0 +1,77 @@
+module Compo
+  module Finders
+    # A method object for finding the root of an item in a composite tree
+    #
+    # The RootFinder can be used as an Enumerable, where the enumerated items
+    # are the path of nodes from the composite to its root, inclusive.
+    #
+    # Root finders are *not* thread-safe.
+    class Root
+      include Enumerable
+
+      # Initialises a root finder
+      #
+      # @api  public
+      # @example  Initialises a RootFinder
+      #   RootFinder.new(composite)
+      #
+      # @param leaf [Composite] A composite object whose root is to be found.
+      def initialize(leaf)
+        @leaf = leaf
+      end
+
+      # Finds the root of a composite object
+      #
+      # @api  public
+      # @example  Finds the root of an object
+      #   RootFinder.find(composite) { |root| p root }
+      #
+      # @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 the root of this RootFinder's composite object
+      #
+      # When the resource is found, it will be yielded to the attached block.
+      #
+      # @api  public
+      # @example  Runs an RootFinder, returning the root unchanged.
+      #   finder.run { |root| root }
+      #   #=> root
+      #
+      # @yieldparam resource [Object]  The resource found.
+      #
+      # @return [Object]  The return value of the block.
+      def run
+        each { |node| yield node if node.root? }
+      end
+
+      # Performs an action on each node in the path to the root
+      #
+      # This includes both the root and the object whose root is sought, and
+      # runs from the latter to the former.
+      #
+      # @api  public
+      # @example  Prints each item from the object to the root.
+      #   finder.each { |item| puts item }
+      #
+      # @yieldparam resource [Object]  The resource found.
+      #
+      # @return [void]
+      def each
+        node = @leaf
+        done = false
+        until done
+          yield node
+          done = node.root?
+          node = node.parent
+        end
+      end
+    end
+  end
+end

data/lib/compo/finders.rb

@@ -1,3 +1,4 @@
+require 'compo/finders/root'
 require 'compo/finders/url'
 
 module Compo

data/lib/compo/mixins/parent_tracker.rb

@@ -29,6 +29,21 @@ module Compo
         Compo::Composites::Parentless.for(self)
       end
 
+      # Gets whether this ParentTracker is the root of its composite tree
+      #
+      # This is equivalent to the ParentTracker having no parent.
+      #
+      # @api  public
+      # @example  Checks if a ParentTracker with no parent is a root.
+      #   orphan.root?
+      #   #=> true
+      # @example  Checks if a ParentTracker with a parent is a root.
+      #   parented.root?
+      #   #=> false
+      def root?
+        parent.on_node { |p| p }.nil?
+      end
+
       # Gets this object's current ID
       #
       # @api  public

data/lib/compo/mixins/url_referenceable.rb

@@ -1,3 +1,5 @@
+require 'compo/finders/root'
+
 module Compo
   module Mixins
     # Adds ID-based 'URL's to Compo classes
@@ -26,30 +28,13 @@ module Compo
       #   #=> ''
       # @example  Gets the URL of an object with a parent.
       #   leaf.url
-      #   #=> 'grandparent_id/parent_id/id'
+      #   #=> '/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('/')
+        Compo::Finders::Root.new(self).reverse_each.map do |item|
+          item.root? ? '' : item.id
+        end.join('/')
       end
 
       # Returns the URL of this object's parent
@@ -57,10 +42,10 @@ module Compo
       # @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'
+      #   #=> '/grandparent_id/parent_id'
       #
       # @return [String]  The URL of this object's parent, or nil if there is no
       #   parent.

data/lib/compo/version.rb

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

data/spec/array_branch_spec.rb

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

data/spec/array_composite_shared_examples.rb

@@ -1,113 +1,120 @@
 require 'compo'
 require 'composite_shared_examples'
 
-shared_examples 'an array composite' do
+RSpec.shared_examples 'an array composite' do
   it_behaves_like 'a composite'
 
-  let(:child1) { double(:child1) }
-  let(:child2) { double(:child2) }
-  let(:child3) { double(:child3) }
+  # Children
+  let(:c1) { double(:c1) }
+  let(:c2) { double(:c2) }
+  let(:c3) { double(:c3) }
 
   before(:each) do
-    allow(child1).to receive(:update_parent)
-    allow(child2).to receive(:update_parent)
-    allow(child3).to receive(:update_parent)
+    allow(c1).to receive(:update_parent)
+    allow(c2).to receive(:update_parent)
+    allow(c3).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 }
+      specify { expect(subject.add(:mr_flibble, c1)).to be_nil }
 
       it 'does not add to the list of children' do
-        subject.add(:rimmer, child1)
-        expect(subject.children).to eq({})
+        expect { subject.add(:rimmer, c1) }.to_not change { subject.children }
+                                           .from({})
+
+        subject.add(0, c1)
 
-        subject.add(0, child1)
-        subject.add(:lister, child2)
-        expect(subject.children).to eq(0 => child1)
+        expect { subject.add(:lister, c2) }.to_not change { subject.children }
+                                           .from(0 => c1)
 
-        subject.add(1, child2)
-        subject.add(:cat, child3)
-        expect(subject.children).to eq(0 => child1, 1 => child2)
+        subject.add(1, c2)
+
+        expect { subject.add(:cat, c3) }.to_not change { subject.children }
+                                        .from(0 => c1, 1 => c2)
       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)
+          expect(subject.add(0, c1)).to eq(c1)
+          expect(subject.add(1, c2)).to eq(c2)
+          expect(subject.add(2, c3)).to eq(c3)
         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)
+          expect { subject.add(0, c1) }.to change { subject.children }
+                                           .from({})
+                                           .to(0 => c1)
+          expect { subject.add(1, c2) }.to change { subject.children }
+                                           .from(0 => c1)
+                                           .to(0 => c1, 1 => c2)
+          expect { subject.add(2, c3) }.to change { subject.children }
+                                           .from(0 => c1, 1 => c2)
+                                           .to(0 => c1, 1 => c2, 2 => c3)
         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)
+          expect(c1).to receive(:update_parent).with(
+            subject,
+            an_object_satisfying { |proc| proc.call == 0 }
+          )
+          subject.add(0, c1)
         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
+          expect(subject.add(1, c1)).to be_nil
+          subject.add(0, c1)
+          expect(subject.add(2, c2)).to be_nil
+          subject.add(1, c2)
+          expect(subject.add(3, c3)).to be_nil
         end
 
         it 'does not add to the list of children' do
-          subject.add(1, child1)
-          expect(subject.children).to eq({})
+          expect { subject.add(1, c1) }.to_not change { subject.children }
+                                       .from({})
 
-          subject.add(0, child1)
-          subject.add(2, child2)
-          expect(subject.children).to eq(0 => child1)
+          subject.add(0, c1)
+          expect { subject.add(2, c2) }.to_not change { subject.children }
+                                       .from(0 => c1)
 
-          subject.add(1, child2)
-          subject.add(3, child3)
-          expect(subject.children).to eq(0 => child1, 1 => child2)
+          subject.add(1, c2)
+          expect { subject.add(3, c2) }.to_not change { subject.children }
+                                       .from(0 => c1, 1 => c2)
         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)
+          subject.add(0, c1)
+          expect(subject.add(0, c2)).to eq(c2)
+          expect(subject.add(1, c3)).to eq(c3)
         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)
+          expect { subject.add(0, c1) }.to change { subject.children }
+                                       .from({})
+                                       .to(0 => c1)
+          expect { subject.add(0, c2) }.to change { subject.children }
+                                       .from(0 => c1)
+                                       .to(0 => c2, 1 => c1)
+          expect { subject.add(1, c3) }.to change { subject.children }
+                                       .from(0 => c2, 1 => c1)
+                                       .to(0 => c2, 1 => c3, 2 => c1)
         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(c1).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)
+          subject.add(0, c2)
+          subject.add(0, c1)
         end
       end
     end
@@ -115,80 +122,80 @@ shared_examples 'an array composite' do
 
   describe '#remove' do
     context 'when the child exists in the list' do
-      before(:each) { subject.add(0, child1) }
+      before(:each) { subject.add(0, c1) }
 
       it 'returns the child' do
-        expect(subject.remove(child1)).to eq(child1)
+        expect(subject.remove(c1)).to eq(c1)
       end
 
       it 'calls #update_parent on the child with a Parentless' do
-        expect(child1).to receive(:update_parent).once do |parent, _|
+        expect(c1).to receive(:update_parent).once do |parent, _|
           expect(parent).to be_a(Compo::Composites::Parentless)
         end
-        subject.remove(child1)
+        subject.remove(c1)
       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(c1).to receive(:update_parent).once do |_, idp|
           expect(idp.call).to be_nil
         end
-        subject.remove(child1)
+        subject.remove(c1)
       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)
+        subject.add(1, c2)
+        subject.add(2, c3)
+
+        expect { subject.remove(c2) }.to change { subject.children }
+                                     .from(0 => c1, 1 => c2, 2 => c3)
+                                     .to(0 => c1, 1 => c3)
       end
     end
 
     context 'when the child does not exist in the list' do
-      specify { expect(subject.remove(child1)).to be_nil }
+      specify { expect(subject.remove(c1)).to be_nil }
 
       it 'does not change the children' do
         expect(subject.children).to eq({})
-        subject.remove(child1)
-        expect(subject.children).to eq({})
+        expect { subject.remove(c1) }.to_not change { subject.children }
+                                     .from({})
 
-        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)
+        subject.add(0, c1)
+        subject.add(1, c2)
+        expect { subject.remove(c3) }.to_not change { subject.children }
+                                     .from eq(0 => c1, 1 => c2)
       end
     end
   end
 
   describe '#remove_id' do
     context 'when the ID exists' do
-      before(:each) { subject.add(0, child1) }
+      before(:each) { subject.add(0, c1) }
 
       it 'returns the child' do
-        expect(subject.remove_id(0)).to eq(child1)
+        expect(subject.remove_id(0)).to eq(c1)
       end
 
       it 'calls #update_parent on the child with a Parentless' do
-        expect(child1).to receive(:update_parent).once do |parent, _|
+        expect(c1).to receive(:update_parent).once do |parent, _|
           expect(parent).to be_a(Compo::Composites::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(c1).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)
+        subject.add(1, c2)
+        subject.add(2, c3)
+        expect { subject.remove_id(1) }.to change { subject.children }
+                                       .from(0 => c1, 1 => c2, 2 => c3)
+                                       .to(0 => c1, 1 => c3)
       end
     end
 
@@ -196,15 +203,13 @@ shared_examples 'an array composite' 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({})
+        expect { subject.remove_id(0) }.to_not change { subject.children }
+                                       .from({})
 
-        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)
+        subject.add(0, c1)
+        subject.add(1, c2)
+        expect { subject.remove_id(2) }.to_not change { subject.children }
+                                       .from(0 => c1, 1 => c2)
       end
     end
   end
@@ -220,20 +225,20 @@ shared_examples 'an array composite' 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(0, c1)
+        expect(subject.children).to eq(0 => c1)
 
-        subject.add(1, child2)
-        expect(subject.children).to eq(0 => child1, 1 => child2)
+        subject.add(1, c2)
+        expect(subject.children).to eq(0 => c1, 1 => c2)
 
-        subject.add(2, child3)
-        expect(subject.children).to eq(0 => child1, 1 => child2, 2 => child3)
+        subject.add(2, c3)
+        expect(subject.children).to eq(0 => c1, 1 => c2, 2 => c3)
 
-        subject.remove(child2)
-        expect(subject.children).to eq(0 => child1, 1 => child3)
+        subject.remove(c2)
+        expect(subject.children).to eq(0 => c1, 1 => c3)
 
-        subject.add(0, child2)
-        expect(subject.children).to eq(0 => child2, 1 => child1, 2 => child3)
+        subject.add(0, c2)
+        expect(subject.children).to eq(0 => c2, 1 => c1, 2 => c3)
       end
     end
   end