compo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 13ca1304045a3fb0ac403495a4c838b53aeecb65
+  data.tar.gz: 06039743fc1c5f084a2906d548ecf322b8a12aaf
+SHA512:
+  metadata.gz: 6de424684aa210f5f48c2d422dee5e44310ccacf6f2623d180c0f2934fa55ee7191b7a479b56badd9220ef1c0ee2dcb907d3df69e3f5063ea4079e2e8448a823
+  data.tar.gz: 6fd54c3de144b876874596fcc446e9b6a4f922f0c89fbaf4d2f6f423bc98d7f3fc10c58bc4d01fcc6d2a2d9d3a7c4beb1d7936684780965fe0ae6b9b389ea167

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.sublime*

data/.rspec

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

data/CHANGELOG

@@ -0,0 +1,2 @@
+0.1.0 (2013-12-26)
+  - Initial version.

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in compo.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Matt Windsor
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,29 @@
+# Compo
+
+TODO: Write a gem description
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'compo'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install compo
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec

data/compo.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'compo/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'compo'
+  spec.version       = Compo::VERSION
+  spec.authors       = ['Matt Windsor']
+  spec.email         = ['matt.windsor@ury.org.uk']
+  spec.description   = %q{
+    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.
+  }
+  spec.summary       = 'Composite pattern style mixins with IDs'
+  spec.homepage      = 'http://github.com/CaptainHayashi/compo'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'backports'
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'fuubar'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'yardstick'
+end

data/lib/compo/array_composite.rb

@@ -0,0 +1,103 @@
+require 'forwardable'
+require 'compo/composite'
+
+module Compo
+  # Implementation of Composite that stores its children in an Array.
+  #
+  # IDs for items entering a ListComposite must be numeric, and will change if
+  # an item with an ID less than the item in question is deleted or inserted.
+  # This means the ID function for objects in a ListComposite may report
+  # different values at different times.
+  #
+  # Adding an object at an occupied ID moves the occupant and those at
+  # successive IDs up by one.
+  class ArrayComposite
+    include Composite
+    extend Forwardable
+
+    # Initialises an ArrayComposite
+    #
+    # @api  public
+    # @example  Initializes an ArrayComposite.
+    #   comp = ArrayComposite.new
+    def initialize
+      @children = []
+    end
+
+    # Returns the ArrayComposite's children, as a Hash
+    #
+    # @api  public
+    # @example  Gets the children of an empty ArrayComposite.
+    #   comp.children
+    #   #=> {}
+    # @example  Gets the children of a populated ArrayComposite.
+    #   comp.children
+    #   #=> {0: :first, 1: :second}
+    #
+    # @return [Hash]  The Hash mapping the IDs of children to their values.
+    def children
+      Hash[(0...@children.size).zip(@children)]
+    end
+
+    private
+
+    def_delegator :@children, :delete, :remove!
+    def_delegator :@children, :delete_at, :remove_id!
+
+    # Inserts a child into the ArrayComposite with the given ID
+    #
+    # You probably want to use #add instead.
+    #
+    # @api  private
+    #
+    # @param id [Object]  The ID under which the child is to be added.
+    # @param child [Object]  The child to add to the ArrayComposite.
+    #
+    # @return [Object]  The newly added child, or nil if the ID was invalid.
+    def add!(id, child)
+      valid_id?(id) ? do_insert(id, child) : nil
+    end
+
+    # Checks to see if the given ID is valid
+    #
+    # A valid ID for ArrayComposites is a number between 0 and the current
+    # size of the children list.
+    #
+    # @api  private
+    #
+    # @param id [Object]  The candidate ID.
+    #
+    # @return [Boolean]  True if the ID is valid; false if not.
+    def valid_id?(id)
+      id.is_a?(Numeric) && (0..@children.size).cover?(id)
+    end
+
+    # Actually performs the insertion of an item into the array
+    #
+    # @api  private
+    #
+    # @param id [Numeric]  The index into the array at which the child is to be
+    #   inserted.
+    # @param child [Object]  The object to insert into the children array.
+    #
+    # @return [Object]  The inserted child.
+    def do_insert(id, child)
+      @children.insert(id, child)
+      child
+    end
+
+    # Creates an ID function for the given child
+    #
+    # The returned proc is O(n), as it checks the child array at each call to
+    # find the current ID of the child.
+    #
+    # @api  private
+    #
+    # @param child [Object]  The child whose ID is to be returned by the proc.
+    #
+    # @return [Proc]  A proc returning the child's ID.
+    def id_function(object)
+      proc { @children.index(object) }
+    end
+  end
+end

data/lib/compo/composite.rb

@@ -0,0 +1,130 @@
+module Compo
+  # Mixin for objects that can contain other objects
+  #
+  # Objects implementing this interface should implement add!, remove! or
+  # remove_id!, and id_function:
+  #
+  # add!        - Given a desired ID and child, adds the child to the children
+  #               of this object; returns the child if successful, nil
+  #               otherwise.
+  # remove!     - Given a child, removes and returns it from the children; if
+  #               not provided, this is implemented in terms of remove_id!.
+  # remove_id!  - Given an ID, removes and returns the child with this ID from
+  #               the children; if not provided, this is implemented in terms
+  #               of remove!.
+  # children    - Returns the children, as a Hash mapping from current IDs to
+  #               their child values.
+  # id_function - Given a newly inserted child, returns a proc that will
+  #               always return the child's current ID so long as it is part
+  #               of the Composite.
+  module Composite
+    extend Forwardable
+    include Enumerable
+
+    # Adds a child to this Composite
+    #
+    # @api  public
+    # @example  Adds a child with intended id 3.
+    #   composite.add_child(3, leaf)
+    #
+    # @param id  [Object]  The intended ID of the child in this Composite.
+    #   The actual ID may not be the same as this; consult the proc supplied
+    #   to the child via #update_parent.
+    # @param child [Object]  The child to add to this Composite.
+    #
+    # @return [Object]  The added child if successful; nil otherwise.
+    def add(id, child)
+      add!(id, child).tap(&method(:assign_parent))
+    end
+
+    # Removes a child from this Composite directly
+    #
+    # This method can fail (for example, if the child does not exist in the
+    # Composite).
+    #
+    # @api  public
+    # @example  Removes a child.
+    #   composite.remove(child)
+    #
+    # @param child [Object]  The child to remove from this object.
+    #
+    # @return [Object]  The removed child if successful; nil otherwise.
+    def remove(child)
+      remove!(child).tap(&method(:remove_parent))
+    end
+
+    # Removes a child from this Composite, given its ID
+    #
+    # This method can fail (for example, if the ID does not exist in the
+    # Composite).
+    #
+    # @api  public
+    # @example  Removes the child with ID :foo.
+    #   composite.remove_id(:foo)
+    #
+    # @param id  The ID of the child to remove from this object.
+    #
+    # @return [Object]  The removed child if successful; nil otherwise.
+    def remove_id(id)
+      remove_id!(id).tap(&method(:remove_parent))
+    end
+
+    def_delegator :children, :each
+
+    protected
+
+    # Assigns this object to a child as its parent
+    #
+    # This also updates its ID function to point to the child's ID under this
+    # parent.
+    #
+    # @api  private
+    #
+    # @param child [Object]  The child whose parent assignment is being set.
+    #
+    # @return [void]
+    def assign_parent(child)
+      child.update_parent(self, id_function(child)) unless child.nil?
+    end
+
+    # Removes a child's parent assignment
+    #
+    # This also clears its ID function.
+    #
+    # @api  private
+    #
+    # @param child [Object]  The child whose parent assignment is being set.
+    #
+    # @return [void]
+    def remove_parent(child)
+      child.remove_parent unless child.nil?
+    end
+
+    # Default implementation of #remove! in terms of #remove_id!
+    #
+    # Either this or #remove_id! must be overridden by the implementing class.
+    #
+    # @api  private
+    #
+    # @param child [Object]  The child to remove from this object.
+    #
+    # @return [void]
+    def remove!(child)
+      remove_id!(children.key(child))
+    end
+
+    # Default implementation of #remove_id! in terms of #remove!
+    #
+    # Either this or #remove! must be overridden by the implementing class.
+    #
+    # @api  private
+    #
+    # @param id [Object]  The current ID of the child to remove from this
+    #   object.
+    #
+    # @return [void]
+    def remove_id!(id)
+      remove!(get_child(id))
+    end
+  end
+end

data/lib/compo/hash_composite.rb

@@ -0,0 +1,70 @@
+require 'forwardable'
+require 'compo/composite'
+
+module Compo
+  # Implementation of Composite that stores its children in a Hash.
+  #
+  # IDs for items entering a ListComposite may be any permissible hash.
+  #
+  # Adding an item at an occupied ID removes the occupant.
+  class HashComposite
+    include Composite
+    extend Forwardable
+
+    # Initialises a HashComposite
+    #
+    # @api  public
+    # @example  Initializes a HashComposite.
+    #   comp = HashComposite.new
+    def initialize
+      @children = {}
+    end
+
+    # Returns the HashComposite's children, as a Hash
+    #
+    # @api  public
+    # @example  Gets the children of an empty HashComposite.
+    #   comp.children
+    #   #=> {}
+    # @example  Gets the children of a populated HashComposite.
+    #   comp.children
+    #   #=> {foo: 3, bar: 5}
+    #
+    # @return [Hash]  The Hash mapping the IDs of children to their values.
+    attr_reader :children
+
+    private
+
+    # Inserts a child into the HashComposite with the given ID
+    #
+    # You probably want to use #add instead.
+    #
+    # @api  private
+    #
+    # @param id [Object]  The ID under which the child is to be added.
+    # @param child [Object]  The child to add to the HashComposite.
+    #
+    # @return [Object]  The newly added child.
+    def add!(id, child)
+      remove_id(id)
+      @children[id] = child
+    end
+
+    def_delegator :@children, :delete, :remove_id!
+
+    # Creates an ID function for the given child
+    #
+    # The returned proc is O(1), as it stores the ID assigned to the child at
+    # calling time under the assumption that it will not change until removal.
+    #
+    # @api  private
+    #
+    # @param child [Object]  The child whose ID is to be returned by the proc.
+    #
+    # @return [Proc]  A proc returning the child's ID.
+    def id_function(child)
+      id = @children.key(child)
+      proc { id }
+    end
+  end
+end

data/lib/compo/leaf.rb

@@ -0,0 +1,22 @@
+require 'compo/movable'
+require 'compo/null_composite'
+require 'compo/parent_tracker'
+
+module Compo
+  # A simple implementation of a leaf
+  #
+  # Leaves have no children, but can be moved to one.
+  class Leaf < NullComposite
+    include Movable
+    include ParentTracker
+
+    # Initialises the Leaf
+    #
+    # @api  public
+    # @example  Creates a new Leaf.
+    #   leaf.new
+    def initialize
+      remove_parent
+    end
+  end
+end

data/lib/compo/movable.rb

@@ -0,0 +1,53 @@
+module Compo
+  # 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) unless parent.nil?
+    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

data/lib/compo/null_composite.rb

@@ -0,0 +1,63 @@
+require 'forwardable'
+require 'compo/composite'
+
+module Compo
+  # Null implementation of Composite
+  #
+  # Add/remove operations on NullComposite always fail, and #children always
+  # returns the empty hash.
+  #
+  # This is useful for leaf classes that still need to expose the composite
+  # API.
+  class NullComposite
+    include Composite
+
+    # Returns the empty hash
+    #
+    # @api  public
+    # @example  Gets the children
+    #   comp.children
+    #   #=> {}
+    #
+    # @return [Hash]  The empty hash.
+    def children
+      {}
+    end
+
+    private
+
+    # Fails to add a child into the NullComposite
+    #
+    # @api  private
+    #
+    # @param id [Object]  Ignored.
+    # @param child [Object]  Ignored.
+    #
+    # @return [nil]
+    def add!(_, _)
+      nil
+    end
+
+    # Fails to remove the given child
+    #
+    # @api  private
+    #
+    # @param child [Object]  Ignored.
+    #
+    # @return [nil]
+    def remove!(_)
+      nil
+    end
+
+    # Fails to remove the child with the given ID
+    #
+    # @api  private
+    #
+    # @param id [Object]  Ignored.
+    #
+    # @return [nil]
+    def remove_id!(_)
+      nil
+    end
+  end
+end

data/lib/compo/parent_tracker.rb

@@ -0,0 +1,64 @@
+require 'forwardable'
+
+module Compo
+  # Basic implementation of parent tracking as a mixin
+  #
+  # 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.
+  #
+  # Subclasses should call #remove_parent in their #initialize methods, to
+  # set the parent and ID function to their default, empty values.
+  module ParentTracker
+    extend Forwardable
+
+    # 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_function, :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_function)
+      @parent = new_parent
+      @id_function = new_id_function
+    end
+
+    # Blanks out this object's parent and ID function
+    #
+    # @api  public
+    # @example  Update this Leaf's parent and ID function.
+    #   movable.update_parent(new_parent, new_id_function)
+    #
+    # @return [void]
+    def remove_parent
+      update_parent(nil, ->{ nil })
+    end
+  end
+end

data/lib/compo/version.rb

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

data/lib/compo.rb

@@ -0,0 +1,12 @@
+require 'compo/array_composite'
+require 'compo/composite'
+require 'compo/hash_composite'
+require 'compo/leaf'
+require 'compo/movable'
+require 'compo/null_composite'
+require 'compo/parent_tracker'
+require 'compo/version'
+
+# The main module for Compo.
+module Compo
+end