compo 0.3.1 → 0.4.0

data/lib/compo/parentless.rb

@@ -1,131 +0,0 @@
-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
-
-    # 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

data/lib/compo/url_finder.rb

@@ -1,164 +0,0 @@
-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/url_referenceable.rb

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

data/spec/leaf_spec.rb

@@ -1,9 +0,0 @@
-require 'spec_helper'
-require 'compo'
-require 'branch_shared_examples'
-require 'null_composite_shared_examples'
-
-describe Compo::Leaf do
-  it_behaves_like 'a branch'
-  it_behaves_like 'a null composite'
-end

data/spec/null_composite_spec.rb

@@ -1,7 +0,0 @@
-require 'spec_helper'
-require 'compo'
-require 'null_composite_shared_examples'
-
-describe Compo::NullComposite do
-  it_behaves_like 'a null composite'
-end