tree_delta 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: df6e2308561f7c2800ec01e8e1205db41e3fbdd2
+  data.tar.gz: 678b3ee7309db439390356c716229f8fd9afd271
+SHA512:
+  metadata.gz: dc0433f176917897f6175fa7cba1a70b69d51d76d67cbfee924f2604005559a981c40a887d29ed23babe0515d9deaa5e9d70b541cbc810bc9adf273f66475815
+  data.tar.gz: cabc88fd38856bbd3dc53e57b3ddf1fda5f33decafc7eb5e72e9bcbd2b678fd8002b8ed81727c59f171353d14fbe1b8b731f2c02b36e8fa7faccf9d51bf41c0b

data/README.md

@@ -0,0 +1,153 @@
+## Tree Delta
+
+Calculates the minimum set of operations that transform one tree into another.
+
+## Overview
+
+Let's say we have the following ordered trees:
+
+```
+                             alpha               beta
+                             /   \               /  \
+                            a     b             a    e
+                           / \     \           / \
+                          c   d     e         d   c
+```
+
+You can transform the 'alpha' tree into the 'beta' tree through a combination
+of operations:
+
+```
+create - adds a node to the tree
+update - changes the attributes of a node
+delete - removes a node from the tree
+detach - orphan a node from its parent
+attach - give a node a new parent
+```
+
+Here are the operations for the above example:
+
+```
+detach 'e'
+detach 'd'
+detach 'a'
+delete 'alpha'
+create 'beta' as root
+attach 'a' to 'beta' at position 0
+attach 'd' to 'a' at position 0
+attach 'e' to 'beta' at position 1
+```
+
+The order of these operations is somewhat important. For example, node 'a' can
+only be attached to 'beta' after 'beta' has been created.
+
+Updates are not shown here. An 'update' operation is used to make changes to the
+value object for a node. This is where you'd store the node's attributes.
+
+## Usage
+
+You must first define a node class with the following methods:
+
+```ruby
+#id
+Returns an identifier that uniquely identifies the node across trees.
+
+#parent
+Returns the parent of the node.
+
+#children
+Returns an array of child nodes.
+
+#value
+Returns the value object associated with the node.
+```
+
+You can then use your node class to create separate trees:
+
+```ruby
+alpha = Node.new("alpha", children: [
+  Node.new("a", children: [
+    Node.new("c"),
+    Node.new("d")
+  ]),
+  Node.new("b", children: [
+    Node.new("e")
+  ])
+])
+
+beta = Node.new("beta", children: [
+  Node.new("a", children: [
+    Node.new("d"),
+    Node.new("c")
+  ]),
+  Node.new("e")
+])
+```
+
+Finally, you can instantiate a delta from the roots of the trees:
+
+```ruby
+delta = TreeDelta.new(from: alpha, to: beta)
+
+delta.each do |operation|
+  # ...
+end
+```
+
+## Operation
+
+An operation is a simple object that describes a transformation.
+
+It can contain up to five pieces of information, as shown here:
+
+|          | type     | id       | value    | parent   | position |
+| --------:|:--------:|:--------:|:--------:|:--------:|:--------:|
+|   create | ✓        | ✓        | ✓        | ✓        | ✓        |
+|   update | ✓        | ✓        | ✓        |          |          |
+|   delete | ✓        | ✓        |          |          |          |
+|   detach | ✓        | ✓        |          |          |          |
+|   attach | ✓        | ✓        |          | ✓        | ✓        |
+
+Here is an example:
+
+```ruby
+operation.type
+#=> :create
+
+operation.id
+#=> "foo"
+
+operation.value
+#=> 123
+
+operation.parent
+#=> "bar"
+
+operation.position
+#=> 3
+```
+
+The 'value' is the value object for the node. This can be a literal value
+or an object, such as a hash of attributes.
+
+The 'position' refers to the node's index position relative to its siblings,
+starting at zero.
+
+The 'parent' will be nil if the node is the root of the tree.
+
+## Assumptions
+
+- The delta assumes that deletions cascade down to subtrees under a node. It
+will not yield operations to delete descendants of a node.
+
+- The delta assumes that positions for siblings are updated when a node is
+created or attached. Any sibling to the right of the node should have its
+position incremented by one.
+
+- The delta assumes that positions for siblings are updated when a node is
+deleted or detached. Any sibling to the right of the node should have its
+position decremented by one.
+
+## Contribution
+
+If you'd like to contribute, please open an issue or submit a pull request.

data/lib/tree_delta/base.rb

@@ -0,0 +1,55 @@
+class TreeDelta < Enumerator
+
+  attr_reader :from, :to
+
+  def initialize(from:, to:)
+    @from, @to = from, to
+  end
+
+  def each(&block)
+    deletes_and_detaches.each { |o| yield o }
+    creates_and_attaches.each { |o| yield o }
+    updates.each              { |o| yield o }
+  end
+
+  private
+
+  def deletes_and_detaches
+    traversal = Traversal.new(direction: :right_to_left, order: :post)
+    enumerator = traversal.traverse(from)
+
+    Sorter.sort(deletes.to_a + detaches.to_a, enumerator)
+  end
+
+  def creates_and_attaches
+    traversal = Traversal.new(direction: :left_to_right, order: :pre)
+    enumerator = traversal.traverse(to)
+
+    Sorter.sort(creates.to_a + attaches.to_a, enumerator)
+  end
+
+  def creates
+    intermediate.creates
+  end
+
+  def updates
+    intermediate.updates
+  end
+
+  def deletes
+    intermediate.deletes
+  end
+
+  def detaches
+    intermediate.detaches
+  end
+
+  def attaches
+    intermediate.attaches
+  end
+
+  def intermediate
+    @intermediate ||= Intermediate.new(from: from, to: to)
+  end
+
+end

data/lib/tree_delta/intermediate.rb

@@ -0,0 +1,172 @@
+class TreeDelta::Intermediate
+
+  attr_reader :from, :to
+
+  def initialize(from:, to:)
+    @from, @to = from, to
+  end
+
+  def creates
+    Enumerator.new do |y|
+      additions.each do |node|
+        y.yield TreeDelta::Operation.new(
+          type:     :create,
+          id:       node.id,
+          value:    node.value,
+          parent:   parent_id(node),
+          position: position(node)
+        )
+      end
+    end
+  end
+
+  def updates
+    Enumerator.new do |y|
+      updated_nodes.each do |node|
+        y.yield TreeDelta::Operation.new(
+          type:     :update,
+          id:       node.id,
+          value:    node.value,
+        )
+      end
+    end
+  end
+
+  def deletes
+    Enumerator.new do |y|
+      normalised_deletions.each do |node|
+        y.yield TreeDelta::Operation.new(
+          type: :delete,
+          id:   node.id
+        )
+      end
+    end
+  end
+
+  def detaches
+    Enumerator.new do |y|
+      moves.each do |node|
+        unless previous_root?(node)
+          y.yield TreeDelta::Operation.new(
+            type: :detach,
+            id:   node.id
+          )
+        end
+      end
+    end
+  end
+
+  def attaches
+    Enumerator.new do |y|
+      moves.each do |node|
+        unless root?(node)
+          y.yield TreeDelta::Operation.new(
+            type:     :attach,
+            id:       node.id,
+            parent:   parent_id(node),
+            position: position(node)
+          )
+        end
+      end
+    end
+  end
+
+  private
+
+  def from_nodes
+    @from_nodes ||= nodes(from)
+  end
+
+  def to_nodes
+    @to_nodes ||= nodes(to)
+  end
+
+  def additions
+    subtract(to_nodes, from_nodes)
+  end
+
+  def updated_nodes
+    to_nodes.select do |to_node|
+      from_node = from_node_for(to_node)
+      from_node && from_node.value != to_node.value
+    end
+  end
+
+  def normalised_deletions
+    TreeDelta::Normaliser.normalise_deletions(deletions)
+  end
+
+  def deletions
+    subtract(from_nodes, to_nodes)
+  end
+
+  def nodes(tree)
+    traversal = TreeDelta::Traversal.new(direction: :left_to_right, order: :pre)
+    traversal.traverse(tree).to_a
+  end
+
+  def subtract(a, b)
+    a.reject { |e| b.any? { |f| e.id == f.id } }
+  end
+
+  def parent_id(node)
+    node && node.parent ? node.parent.id : nil
+  end
+
+  def position(node)
+    node.parent ? node.parent.children.index(node) : 0
+  end
+
+  def moves
+    @moves ||= parent_changes + normalised_position_changes
+  end
+
+  def parent_changes
+    nodes = from_nodes.select { |n| changed_parent?(n) }
+    nodes.map { |from_node| to_node_for(from_node) }
+  end
+
+  def changed_parent?(from_node)
+    to_node = to_node_for(from_node)
+    to_node && parent_id(to_node) != parent_id(from_node)
+  end
+
+  def normalised_position_changes
+    groups = position_changes.group_by { |n| parent_id(n) }
+
+    groups.map do |_, nodes|
+      TreeDelta::Normaliser.normalise_position_changes(nodes)
+    end.flatten
+  end
+
+  def position_changes
+    nodes = from_nodes.select { |n| changed_position?(n) }
+    nodes.map { |from_node| to_node_for(from_node) }
+  end
+
+  def changed_position?(from_node)
+    to_node = to_node_for(from_node)
+
+    to_node &&
+      parent_id(from_node) == parent_id(to_node) &&
+      position(from_node) != position(to_node)
+  end
+
+  def from_node_for(to_node)
+    from_nodes.detect { |n| n.id == to_node.id }
+  end
+
+  def to_node_for(from_node)
+    to_nodes.detect { |n| n.id == from_node.id }
+  end
+
+  def root?(to_node)
+    !to_node.parent
+  end
+
+  def previous_root?(to_node)
+    from_node = from_node_for(to_node)
+    !from_node.parent
+  end
+
+end

data/lib/tree_delta/normaliser.rb

@@ -0,0 +1,29 @@
+module TreeDelta::Normaliser
+  class << self
+
+    def normalise_position_changes(nodes)
+      moving_nodes = []
+
+      previous_node = nil
+      nodes.each do |current_node|
+        if previous_node && position(current_node) < position(previous_node)
+          moving_nodes << current_node
+        end
+        previous_node = current_node
+      end
+
+      moving_nodes
+    end
+
+    def normalise_deletions(nodes)
+      nodes.reject { |n| nodes.any? { |m| n.parent == m } }
+    end
+
+    private
+
+    def position(node)
+      node.parent ? node.parent.children.index(node) : 0
+    end
+
+  end
+end

data/lib/tree_delta/operation.rb

@@ -0,0 +1,21 @@
+class TreeDelta::Operation
+
+  attr_reader :type, :id, :value, :parent, :position
+
+  def initialize(type:, id:, value: nil, parent: nil, position: nil)
+    @type     = type
+    @id       = id
+    @value    = value    if value
+    @parent   = parent   if parent
+    @position = position if position
+  end
+
+  def ==(other)
+    @type       == other.type   &&
+      @id       == other.id     &&
+      @value    == other.value  &&
+      @parent   == other.parent &&
+      @position == other.position
+  end
+
+end

data/lib/tree_delta/sorter.rb

@@ -0,0 +1,12 @@
+module TreeDelta::Sorter
+  def self.sort(array, enumerator)
+    sorted_array = []
+
+    enumerator.each do |object|
+      element = array.detect { |e| e.id == object.id }
+      sorted_array << element if element
+    end
+
+    sorted_array
+  end
+end

data/lib/tree_delta/traversal.rb

@@ -0,0 +1,34 @@
+class TreeDelta::Traversal < Enumerator
+
+  attr_reader :direction, :order
+
+  def initialize(direction:, order:)
+    @direction = direction
+    @order     = order
+  end
+
+  def traverse(node)
+    Enumerator.new do |y|
+      if node
+        y.yield(node) if order == :pre
+
+        ordered_children(node).each do |child|
+          traverse(child).each { |n| y.yield(n) }
+        end
+
+        y.yield(node) if order == :post
+      end
+    end
+  end
+
+  private
+
+  def ordered_children(node)
+    if direction == :left_to_right
+      node.children
+    elsif direction == :right_to_left
+      node.children.reverse
+    end
+  end
+
+end

data/lib/tree_delta.rb

@@ -0,0 +1,6 @@
+require "tree_delta/base"
+require "tree_delta/operation"
+require "tree_delta/traversal"
+require "tree_delta/sorter"
+require "tree_delta/intermediate"
+require "tree_delta/normaliser"

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: tree_delta
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Chris Patuzzo
+- Nick Haworth
+- Jason Pernthaller
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-03-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: ascii_tree
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.3
+description: Calculates the minimum set of operations that transform one tree into
+  another.
+email:
+- chris@patuzzo.co.uk
+- nick.haworth@which.co.uk
+- jason.pernthaller@which.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/tree_delta.rb
+- lib/tree_delta/base.rb
+- lib/tree_delta/intermediate.rb
+- lib/tree_delta/normaliser.rb
+- lib/tree_delta/operation.rb
+- lib/tree_delta/sorter.rb
+- lib/tree_delta/traversal.rb
+homepage: https://github.com/whichdigital/tree_delta
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Tree Delta
+test_files: []