compo 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: de0ae1a9f06c21a0818cb86865d5bd26d79aa7e0
-  data.tar.gz: 7cce675b54964af406c7391913fde1b8f6741c34
+  metadata.gz: 463952c33e420e5ab401ec9774208262b4606ebc
+  data.tar.gz: 59ff0efef46f9db2fd9fdf72c463fccb46b18b96
 SHA512:
-  metadata.gz: 075f6b9688444e1ee13333c97fddf7fce91d897ac4088df6e56fa9c1a5cce5e75b2a279ed2ecbc89999d72da57e95d380f830490a847c7a288586ef06b32abce
-  data.tar.gz: 6900ffec47c87b03f12de21196b2a603b54569882a5e20ee682e5eca555740d2e33ee887f102142f447406ccd6a32dea89e3fe253a9057178ac4bcac91d3a0b9
+  metadata.gz: ead1e453e9ba923f8dcb12b2c9ec211d8d8946323557175eb82c0236939afc42314bc83c139f4e4076b1d3c0f4850910afcad3a29ed4b67ef9309e209eb97dbc
+  data.tar.gz: 890b61d951ad12e56aa2f329506f803dbde105c8541afd2332fb520f973a745fbacd845a7b1f213f69230cfa51e4c326c9704427561a78c754fd6ed69ee1d14c

data/CHANGELOG

@@ -1,3 +1,8 @@
+0.3.1 (2014-05-21)
+  - Add UrlFinder class, for finding children inside a composite structure via
+    their URLs.
+  - 100% YARD, LOC and Rubocop coverage.
+
 0.3.0 (2014-05-21)
   - Require bundler 1.6.
   - Remove some unnecessary checks for nil: Parentless should be used instead.

data/README.md

@@ -3,11 +3,11 @@
 **Compo** is a library providing mixins and base classes for setting up
 composite objects.
 
-It implements something similar to the Gang of Four Composite pattern, but with
-the difference that children are identified in their parents by an *ID*,
-such as the index or hash key, that the child is aware of at all times.
+It's similar to the Gang of Four Composite pattern, but in Compo
+children are identified in their parents by an *ID*,
+such as an index or hash key, that the child is aware of at all times.
 
-Compo was designed for the purpose of creating models whose natural composite
+Compo was designed for models whose composite
 structure can be expressed as URLs made from their recursive ID trails.
 
 ## Installation
@@ -33,6 +33,8 @@ Compo consists of several classes and mixins that implement various parts of the
 - **Composite**, which specifies the #add/#remove/#remove_id/#get_child API on top of an implementation;
 - **Movable**, which creates a #move_to method that simplifies the act of moving a child between Composites;
 - **ParentTracker**, which implements keeping track of a child's parent and the child end of #add/#remove;
+- **URLReferenceable**, which allows the current position of an object in a hierarchy of composites to be retrieved as an URL-style reference;
+- **Branch**, which is simply a **Moveable** **URLReferenceable** **ParentTracker**.
 
 ### Composite implementation classes
 
@@ -44,9 +46,13 @@ These implement the methods needed for **Composite** to work, but don't implemen
 
 ### Simple leaf and node classes
 
-These include **Composite**, **Movable** and **ParentTracker**, and thus can be moved around, added to and removed from composites, and track their current parents and IDs.
+These include **Branch**, and thus can be moved around, added to and removed from composites, and track their current parents and IDs.
 
-- **Leaf**, which is based on NullComposite and is intended for objects that don't have children but can be placed in other Composites.
+- **Leaf**, which is based on NullComposite and is intended for objects that don't have children but can be placed in other Composites;
+- **ArrayBranch**, which is based on ArrayComposite;
+- **HashBranch**, which is based on HashComposite.
+
+Generally, you'll only need to use these classes (use **Leaf** when creating objects that can be part of other objects but not have children themselves, **ArrayBranch** when an object has a list of ordered children *whose ordering changes as more children are added and deleted*, and **HashBranch** when it has a collection of children with arbitrary IDs).
 
 ## Contributing
 

data/lib/compo.rb

@@ -15,6 +15,9 @@ require 'compo/array_branch'
 require 'compo/hash_branch'
 require 'compo/leaf'
 
+# Utilities
+require 'compo/url_finder'
+
 # Misc
 require 'compo/version'
 

data/lib/compo/composite.rb

@@ -73,6 +73,9 @@ module Compo
 
     # 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)
@@ -80,6 +83,9 @@ module Compo
     # @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.
     #
@@ -88,6 +94,32 @@ module Compo
       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

data/lib/compo/parent_tracker.rb

@@ -10,6 +10,16 @@ module Compo
   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

data/lib/compo/url_finder.rb

@@ -0,0 +1,164 @@
+module Compo
+  # An 'UrlFinder' finds an object in a composite tree via its URL
+  #
+  # It is a method object that implements only the finding of a specific URL.
+  # UrlFinders are *not* thread-safe.
+  class UrlFinder
+    # Initialises a UrlFinder
+    #
+    # @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

data/lib/compo/version.rb

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

data/spec/branch_shared_examples.rb

@@ -16,12 +16,12 @@ shared_examples 'a branch' do
   end
 
   describe '#url' do
-    context 'when the Leaf has no parent' do
+    context 'when the Branch has no parent' do
       it 'returns the empty string' do
         expect(subject.url).to eq('')
       end
     end
-    context 'when the Leaf is the child of a root' do
+    context 'when the Branch is the child of a root' do
       let(:parent) { Compo::HashBranch.new }
       before(:each) { subject.move_to(parent, :id) }
 
@@ -30,4 +30,22 @@ shared_examples 'a branch' do
       end
     end
   end
+
+  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 }
+        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)
+        end
+
+        it 'is no longer a child of its parent' do
+          subject.move_to(nil, :id)
+          expect(parent.children).to_not include(subject)
+        end
+      end
+    end
+  end
 end

data/spec/branch_spec.rb

@@ -0,0 +1,12 @@
+require 'spec_helper'
+require 'compo'
+require 'branch_shared_examples'
+
+# Mock implementation of a Branch
+class MockBranch
+  include Compo::Branch
+end
+
+describe MockBranch do
+  it_behaves_like 'a branch'
+end

data/spec/parent_tracker_spec.rb

@@ -5,6 +5,9 @@ require 'compo'
 class MockParentTracker
   include Compo::ParentTracker
 
+  # Initialises a MockParentTracker
+  #
+  # @api  private
   def initialize(parent, id_function)
     @parent = parent
     @id_function = id_function

data/spec/url_finder_spec.rb

@@ -0,0 +1,129 @@
+require 'spec_helper'
+require 'compo'
+
+describe Compo::UrlFinder do
+  subject { Compo::UrlFinder }
+  describe '.find' do
+    let(:target) { Compo::Leaf.new }
+
+    let(:root) do
+      s    = Compo::HashBranch.new
+      a    = Compo::HashBranch.new
+      b    = Compo::ArrayBranch.new
+      d    = Compo::Leaf.new
+      e    = Compo::Leaf.new
+      zero = Compo::Leaf.new
+
+      s.add('a', a)
+      a.add('b', b)
+      b.add(0, zero)
+      b.add(1, target)
+      s.add('d', d)
+      a.add('e', e)
+      s
+    end
+
+    context 'when given a nil root' do
+      specify { expect { |b| subject.find(nil, 'a/b/1', &b) }.to raise_error }
+    end
+
+    context 'when given a nil URL' do
+      specify { expect { |b| subject.find(root, nil, &b) }.to raise_error }
+    end
+
+    shared_examples 'a successful finding' do
+      it 'returns the correct resource' do
+        expect { |b| subject.find(root, url, &b) }.to yield_with_args(target)
+      end
+    end
+
+    shared_examples 'an unsuccessful finding' do
+      specify do
+        expect { |b| subject.find(root, url, &b) }.to raise_error(
+          "Could not find resource: #{url}"
+        )
+      end
+    end
+
+    shared_examples 'an unsuccessful finding with custom error' do
+      specify do
+        mp = ->(_) { :a }
+        expect { |b| subject.find(root, url, missing_proc: mp,  &b) }
+          .to yield_with_args(:a)
+      end
+    end
+
+    context 'when given a correct root but incorrect URL' do
+      context 'using the default missing resource handler' do
+        context 'when the URL has a leading slash' do
+          it_behaves_like 'an unsuccessful finding' do
+            let(:url) { '/a/z' }
+          end
+        end
+        context 'when the URL has a trailing slash' do
+          it_behaves_like 'an unsuccessful finding' do
+            let(:url) { 'a/z/' }
+          end
+        end
+        context 'when the URL has a leading and trailing slash' do
+          it_behaves_like 'an unsuccessful finding' do
+            let(:url) { '/a/z/' }
+          end
+        end
+        context 'when the URL has neither leading nor trailing slash' do
+          it_behaves_like 'an unsuccessful finding' do
+            let(:url) { 'a/z' }
+          end
+        end
+      end
+
+      context 'using a custom error handler' do
+        context 'when the URL has a leading slash' do
+          it_behaves_like 'an unsuccessful finding with custom error' do
+            let(:url) { '/d/e/d' }
+          end
+        end
+        context 'when the URL has a trailing slash' do
+          it_behaves_like 'an unsuccessful finding with custom error' do
+            let(:url) { 'd/e/d/' }
+          end
+        end
+        context 'when the URL has a leading and trailing slash' do
+          it_behaves_like 'an unsuccessful finding with custom error' do
+            let(:url) { '/d/e/d/' }
+          end
+        end
+        context 'when the URL has neither leading nor trailing slash' do
+          it_behaves_like 'an unsuccessful finding with custom error' do
+            let(:url) { 'd/e/d' }
+          end
+        end
+      end
+    end
+
+    context 'when given a correct root and URL' do
+      context 'when the URL leads to a resource' do
+        context 'when the URL has a leading slash' do
+          it_behaves_like 'a successful finding' do
+            let(:url) { '/a/b/1' }
+          end
+        end
+        context 'when the URL has a trailing slash' do
+          it_behaves_like 'a successful finding' do
+            let(:url) { 'a/b/1/' }
+          end
+        end
+        context 'when the URL has a leading and trailing slash' do
+          it_behaves_like 'a successful finding' do
+            let(:url) { '/a/b/1/' }
+          end
+        end
+        context 'when the URL has neither leading nor trailing slash' do
+          it_behaves_like 'a successful finding' do
+            let(:url) { 'a/b/1' }
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: compo
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Matt Windsor
@@ -151,12 +151,14 @@ files:
 - lib/compo/null_composite.rb
 - lib/compo/parent_tracker.rb
 - lib/compo/parentless.rb
+- lib/compo/url_finder.rb
 - lib/compo/url_referenceable.rb
 - lib/compo/version.rb
 - spec/array_branch_spec.rb
 - spec/array_composite_shared_examples.rb
 - spec/array_composite_spec.rb
 - spec/branch_shared_examples.rb
+- spec/branch_spec.rb
 - spec/composite_shared_examples.rb
 - spec/composite_spec.rb
 - spec/hash_branch_spec.rb
@@ -170,6 +172,7 @@ files:
 - spec/parent_tracker_spec.rb
 - spec/parentless_spec.rb
 - spec/spec_helper.rb
+- spec/url_finder_spec.rb
 - spec/url_referenceable_shared_examples.rb
 - spec/url_referenceable_spec.rb
 homepage: http://github.com/CaptainHayashi/compo
@@ -201,6 +204,7 @@ test_files:
 - spec/array_composite_shared_examples.rb
 - spec/array_composite_spec.rb
 - spec/branch_shared_examples.rb
+- spec/branch_spec.rb
 - spec/composite_shared_examples.rb
 - spec/composite_spec.rb
 - spec/hash_branch_spec.rb
@@ -214,6 +218,7 @@ test_files:
 - spec/parent_tracker_spec.rb
 - spec/parentless_spec.rb
 - spec/spec_helper.rb
+- spec/url_finder_spec.rb
 - spec/url_referenceable_shared_examples.rb
 - spec/url_referenceable_spec.rb
 has_rdoc: