dyph 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31873ea8f91e94aab1cc18aa9a2d5bbfe2bb871d5585df0c0b01d2189e8ee8fd
+  data.tar.gz: 1243dc1bfe1301be1b52ec8a4a865262445ec88c4cf741955b1300422c22fcdb
+SHA512:
+  metadata.gz: 905655168bb4664168aa7f903d7ffc746c6f1886b474c06219235640014872490fb26373a53713f0a47328f519e63459c1f90559b20b0196bb4010bacda1855f
+  data.tar.gz: 04bec6b8ebeadcad31c2ef34eb36f44c752aa9f78ea278c824223f9ac63762f95692d20a95f9289baa78930ffdc8e0f5ba00291b8f46b964c06fc7d86a167a18

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Boundless
+
+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,199 @@
+Dyph
+=====
+[![Circle CI](https://img.shields.io/circleci/project/kevinmookorg/dyph/master.svg)](https://circleci.com/gh/kevinmookorg/dyph)
+[![Documentation](https://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/kevinmook/dyph/master)
+
+A library of useful diffing algorithms for Ruby.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'dyph'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install dyph
+
+# Quick start
+## Two way diffing
+To diff two arrays:
+
+    left = [:a, :b, :c, :d]
+    right = [:b, :c, :d, :e]
+    Dyph::Differ.two_way_diff(left, right)
+
+which will return an array of `Dyph::Action` with offsets
+
+    [
+      <Action::Delete   @new_index=0, @old_index=1, @value=:a>,
+      <Action::NoChange @new_index=0, @old_index=1, @value=:b>,
+      <Action::NoChange @new_index=1, @old_index=2, @value=:c>,
+      <Action::NoChange @new_index=2, @old_index=3, @value=:d>,
+      <Action::Add      @new_index=4, @old_index=4, @value=:e>
+    ]
+
+## Three way diffing
+Three way diffing is able to detect changes between two documents relative to a common base.
+
+### No conflicts
+To execute a three way diff and merge:
+
+    left  = [:a, :b, :c, :d]
+    base  = [:a, :b, :c]
+    right = [:b, :c, :d, :e]
+    Dyph::Differ.merge(left, base, right)
+
+Which returns a `Dyph::MergeResult` with a list of result outcomes:
+
+    [ <OutCome::Resolved(@result=[:b, :c, :d, :e]> ]
+
+and has `MergeResult#conflict` set to `false`
+### Conflicts
+
+Conflicts are when left and right make a change relative to base in the same relative place, so an end user must determine how to merge
+
+For example:
+
+    left  = [:a, :l, :c]
+    base  = [:a, :b, :c]
+    right = [:a, :r, :c]
+    Dyph::Differ.merge(left, base, right)
+
+returns the following `MergeResult#result`
+
+    [
+      <Outcome::Resolved   @result=[:a]>
+      <Outcome::Conflicted @base=[:b], @left=[:l], @right=[:r]>,
+      <Outcome::Resolved   @result=[:c]>
+    ]
+
+and has `MergeResult#conflict` set to `true`
+
+## Split, Join, and Conflict functions
+Dyph works on arrays of objects that implement equatable and hash (see `Dyph::Equatable`). For various reasons one might want to delegate the splitting and joining of the input/out to Dyph. (i.e. so one would not have to `map` over the input and output to do the transformation)
+
+### With merge parameter `lambdas`
+One can define `split_funciton`, `join_function`, and `conflict_function` to `Dyph::Diff.merge` such as splitting on word boundries, (but keeping delimiters):
+
+    split_function =  ->(string) { string.split(/\b/) }
+
+and then a join function to handle the resulting arrays
+
+    join_function =  ->(array) { array.join }
+
+which may be invoked with
+
+    left  = "The quick brown fox left the lazy dog"
+    base  = "The quick brown fox jumped over the lazy dog."
+    right = "The right brown fox jumped over the lazy dog"
+    merge_results = Dyph::Differ.merge(left, base, right, split_function: split_function, join_function: join_function)
+    merge_results.joined_results
+will then return
+
+    "The right brown fox left the lazy dog"
+
+### Conflict Handlers
+Similarly one can instruct the differ on how to deal with conflicts. The `conflict_function` is passed a list of Outcomes from the diff:
+
+    conflict_funciton = ->(outcome_list) { ... }
+
+which one can then pass to the `Differ#merge` method as
+
+    Dyph::Differ.merge(left, base, right, conflict_function: conflict_funciton)
+
+### Class Level Processor with Example
+In addition to argument level `split`, `join`, `merge` functions, Dyph also supports object level processors:
+
+    DIFF_PREPROCESSOR = -> (object) { ... }
+    DIFF_POSTPROCESSOR = -> (array) { ... }
+    DIFF_CONFLICT_PROCESSOR = ->(outcome_list) { ... }
+
+that will look something like:
+
+    class GreetingCard
+      attr_reader :message
+
+      #Dyph Processors
+      DIFF_PREPROCESSOR  = -> (sentence) { sentence.message.split(/\b/) }
+      DIFF_POSTPROCESSOR = -> (array) { array.join }
+      DIFF_CONFLICT_PROCESSOR = ->(outcome_list) do
+        outcome_list.map do |outcome|
+          if outcome.conflicted?
+            [
+              "<span class='conflict_left'>#{outcome.left.join}</span>",
+              "<span class='conflict_base'>#{outcome.base.join}</span>",
+              "<span class='conflict_right'>#{outcome.right.join}</span>"
+            ].join
+          else
+            outcome.result.join
+          end
+        end.join
+      end
+
+      def initialize(message)
+        @message = message
+      end
+
+    end
+
+When there are no conflictes:
+
+    left = GreetingCard.new("Ho! Ho! Ho! Merry Christmas!")
+    base = GreetingCard.new("Merry Christmas!")
+    right = GreetingCard.new("Merry Christmas! And a Happy New Year")
+    Dyph::Differ.merge(left, base, right).joined_results
+
+    => "Ho! Ho! Ho! Merry Christmas! And a Happy New Year"
+
+and when there are:
+
+    left = GreetingCard.new("Happy Christmas!")
+    base = GreetingCard.new("Merry Christmas!")
+    right = GreetingCard.new("Just Christmas!")
+    Dyph::Differ.merge(left, base, right).joined_results
+
+    => "<span class='conflict_left'>Happy</span><span class='conflict_base'>Merry</span><span class='conflict_right'>Just</span> Christmas!"
+
+
+## References:
+[Three-way file comparison algorithm (python)](https://www.cbica.upenn.edu/sbia/software/basis/apidoc/v1.2/diff3_8py_source.html)
+
+[Moin Three way differ (python)](http://hg.moinmo.in/moin/2.0/file/4a997d9f5e26/MoinMoin/util/diff3.py)
+
+[Text Diff3 (perl)](http://search.cpan.org/~tociyuki/Text-Diff3-0.10/lib/Text/Diff3.pm)
+
+
+## Forked from GoBoundless/dyph
+This project was forked from [GoBoundless/dyph](https://github.com/GoBoundless/dyph).
+
+
+## The MIT License (MIT)
+
+Copyright © `2016` `Boundless`
+
+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/lib/dyph.rb

@@ -0,0 +1,25 @@
+require "dyph/version"
+require "dyph/differ"
+
+require "dyph/merge_result"
+
+require "dyph/outcome"
+require "dyph/outcome/resolved"
+require "dyph/outcome/conflicted"
+
+require "dyph/support/diff3"
+
+require "dyph/support/collater"
+require "dyph/support/merger"
+require "dyph/support/sanity_check"
+require "dyph/support/assign_action"
+
+require "dyph/two_way_differs/heckel_diff"
+
+require "dyph/two_way_differs/output_converter"
+
+require "dyph/action"
+require "dyph/action/add"
+require "dyph/action/no_change"
+require "dyph/action/delete"
+require "dyph/equatable"

data/lib/dyph/action.rb

@@ -0,0 +1,12 @@
+module Dyph
+  class Action
+    attr_accessor :value, :old_index, :new_index
+
+    def initialize(value:, old_index:, new_index:)
+      @value = value
+      @old_index = old_index
+      @new_index = new_index
+    end
+
+  end
+end

data/lib/dyph/action/add.rb

@@ -0,0 +1,7 @@
+module Dyph
+  class Action::Add < Action
+    def symbol
+      :add
+    end
+  end
+end

data/lib/dyph/action/delete.rb

@@ -0,0 +1,7 @@
+module Dyph
+  class Action::Delete < Action
+    def symbol
+      :delete
+    end
+  end
+end

data/lib/dyph/action/no_change.rb

@@ -0,0 +1,7 @@
+module Dyph
+  class Action::NoChange < Action ;
+    def symbol
+      :no_change
+    end
+  end
+end

data/lib/dyph/differ.rb

@@ -0,0 +1,102 @@
+module Dyph
+  class Differ
+    # Perform a three way diff, which attempts to merge left and right relative to a common base
+    # @param left [Object]
+    # @param base [Object]
+    # @param right [Object]
+    # @param options [Hash] custom split, join, conflict functions, can also override the diff2 and diff3 algorithm. (see default_merge_options)
+    # @return [MergeResult]
+    def self.merge(left, base, right, options = {})
+      options = default_merge_options.merge(options)
+
+      split_function, join_function, conflict_function = set_processors(base, options)
+      split_left, split_base, split_right = [left, base, right].map { |t| split_function.call(t) }
+      merge_result = Dyph::Support::Merger.merge(split_left, split_base, split_right, diff2: options[:diff2], diff3: options[:diff3] )
+      collated_merge_results = Dyph::Support::Collater.collate_merge(merge_result, join_function, conflict_function)
+
+      if collated_merge_results.success?
+        Dyph::Support::SanityCheck.ensure_no_lost_data(split_left, split_base, split_right, collated_merge_results.results)
+      end
+
+      collated_merge_results
+    end
+
+    # Perform a two way diff
+    # @param left [Array]
+    # @param right [Array]
+    # @param options [Hash] Pass in an optional diff2 class
+    # @return [Array] array of Dyph::Action
+    def self.two_way_diff(left, right, options = {})
+      diff2 = options[:diff2] || default_diff2
+      diff_results = diff2.execute_diff(left, right)
+      raw_merge = Dyph::TwoWayDiffers::OutputConverter.merge_results(diff_results[:old_text], diff_results[:new_text],)
+      Dyph::TwoWayDiffers::OutputConverter.objectify(raw_merge)
+    end
+
+    # @return [Proc] helper proc for keeping newlines on string
+    def self.split_on_new_line
+      -> (some_string) { some_string.split(/(\n)/).each_slice(2).map { |x| x.join } }
+    end
+
+    # @return [Proc] helper proc for joining an array
+    def self.standard_join
+      -> (array) { array.join }
+    end
+
+    # @return [Proc] helper proc for identity
+    def self.identity
+      -> (x) { x }
+    end
+
+    # @return [Hash] the default options for a merge
+    def self.default_merge_options
+      {
+        split_function: identity,
+        join_function: identity,
+        conflict_function: identity,
+        diff2: default_diff2,
+        diff3: default_diff3,
+        use_class_processors: true
+      }
+    end
+
+    # @return [TwoWayDiffer]
+    def self.default_diff2
+      Dyph::TwoWayDiffers::HeckelDiff
+    end
+
+    # @return [ThreeWayDiffer]
+    def self.default_diff3
+      Dyph::Support::Diff3
+    end
+
+    def self.set_processors(base, options)
+      split_function    = options[:split_function]
+      join_function     = options[:join_function]
+      conflict_function = options[:conflict_function]
+      if options[:use_class_processors]
+        check_for_class_overrides(base.class, split_function, join_function, conflict_function)
+      else
+        [split_function, join_function, conflict_function]
+      end
+    end
+
+    def self.check_for_class_overrides(klass, split_function, join_function, conflict_function)
+      if klass.constants.include?(:DIFF_PREPROCESSOR)
+        split_function = klass::DIFF_PREPROCESSOR
+      end
+
+      if klass.constants.include?(:DIFF_POSTPROCESSOR)
+        join_function  = klass::DIFF_POSTPROCESSOR
+      end
+
+      if klass.constants.include?(:DIFF_CONFLICT_PROCESSOR)
+        conflict_function = klass::DIFF_CONFLICT_PROCESSOR
+      end
+
+      [split_function, join_function, conflict_function]
+    end
+
+    private_class_method :check_for_class_overrides, :set_processors
+  end
+end

data/lib/dyph/equatable.rb

@@ -0,0 +1,24 @@
+module Dyph
+  module Equatable
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def equate_with(*fields)
+        self.class_eval <<-CODE, __FILE__, __LINE__ + 1
+          def hash
+            self.class.hash ^ #{fields.map { |field| "#{field}.hash"}.join(" ^ ")}
+          end
+        CODE
+
+        self.class_eval <<-CODE, __FILE__, __LINE__ + 1
+          def ==(other)
+            self.class == other.class && #{fields.map { |field| "#{field} == other.#{field}"}.join(" && ")}
+          end
+          alias_method :eql?, :==
+        CODE
+      end
+    end
+  end
+end

data/lib/dyph/merge_result.rb

@@ -0,0 +1,45 @@
+module Dyph
+  class MergeResult
+
+    # @param results [Array]  diff3 output
+    # @param join_function [Proc] how to join the results together
+    # @param conflict [Boolean] sets the conflict's state
+    # @param conflict_handler [Proc] what to do with the conflicted results
+    def initialize(results, join_function, conflict: false, conflict_handler: nil)
+      @results = results
+      @join_function = join_function
+      @conflict_handler = conflict_handler
+      @conflict = conflict
+    end
+
+    # @return [Array] of outcomes (Outcome::Conflicted  or Outcome::Resolved)
+    def results
+      @results
+    end
+
+    #@return [Boolean] success state
+    def success?
+      !@conflict
+    end
+
+    #@return [Boolean] conflict state
+    def conflict?
+      @conflict
+    end
+
+    # Applies the join function or conflict handler to diff3 results array
+    # @return the results with the methods provided by user or defaults applied
+    def joined_results
+      if conflict?
+        if @conflict_handler
+          @conflict_handler[results]
+        else
+          results
+        end
+      else
+        first, rest = results.first, results[1..-1]
+        rest.reduce(first) { |rs, r| rs.combine(r) }.apply(@join_function).result
+      end
+    end
+  end
+end