justinf-unification_assertion 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

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

data/README.md

@@ -0,0 +1,133 @@
+# UnificationAssertion
+
+UnificationAssertion provides powerful and simple way to compare two
+structures which may be different partialy. The comparison is based on
+unification algorithm, which is used in Prolog implementations and
+type inference algorithms.
+
+The assertion will be like the following:
+
+    assert_unifiable({ "timestamp" => :_,
+                       "person" => {
+                         "id" => :_,
+                         "name" => "John",
+                         "email" => "john@example.com",
+                         "created_at" => :_a,
+                         "updated_at" => :_a
+                       }
+                     }, JSON.parse(@response.body))
+
+It compares two hash objects, but it does not care the exact value of
+`"timestamp"`, `"id"`, `"created_at"`, and `"updated_at"`. The meta
+variable `:_a` is not a black hole but test the equality between
+`"created_at"` and `"updated_at"`.
+
+## Introduction
+
+I have been writing some tests like the following Rails functional
+tests.
+
+    # Testing a web api which create a person data and send the created person object as JSON
+    post(:create_person, { :person => { :name => "John", :email => "john@example.com" } })
+    
+    # Compare expected hash and actual result parsed by JSON parser
+    assert_equal({ "timestamp" => Time.now,
+                   "person" => {
+                     "id" => 13,
+                     "name" => "John",
+                     "email" => "john@example.com",
+                     "created_at" => Time.now,
+                     "updated_at" => Time.now
+                   }
+                 }, JSON.parse(@response.body))
+  
+You may point out some problems on the test.
+
+* The ID of the result may be different from 13
+* It is not sure to assume `result["timestamp"]` is equal to `Time.now`
+* It is not sure to assume `result["person"]["created_at"]` is equal to `Time.now`
+
+The root of the problems is that the comparison is too strict. The
+properties I would like to test is only its `name` and `email`
+fields. So I should test like the following:
+
+    assert_equal "John", result["person"]["name"]
+    assert_equal "john@example.com", result["person"]["email"]
+
+It looks too complicated, and we need some way to compare structures.
+This library, UnificationAssertion, provides the primitive for the
+comparison called `assert_unifiable`.
+
+    assert_unifiable({ "timestamp" => :_,
+                       "person" => {
+                         "id" => :_,
+                         "name" => "John",
+                         "email" => "john@example.com",
+                         "created_at" => :_a,
+                         "updated_at" => :_a
+                       }
+                     }, JSON.parse(@response.body))
+
+Symbols `:_a` for example, where its name starts with `_` is
+interpreted as a meta variable. `assert_unifiable` does not care their
+exact value is, but only the existence (can be `nil`) and equalities
+for each occurance will be tested. The special symbol `:_` is a
+wildcard.  It can appear many times, but it will not be bound with any
+value.
+
+## Examples
+
+    assert_unifiable(:_a, 1)              # pass, :_a will be 1
+    assert_unifiable([:_a, 1], [1, 1])    # pass, :_a will be 1
+    assert_unifiable([:_, :_], [1, 2])    # pass, :_ can not be bound with any value
+    assert_unifiable([:_a, :_a], [1, 2])  # fail, :_a can not be either 1 and 2
+    assert_unifiable([:_a], [1,2,3])      # fail, :_a can be a value but can not be a sequence
+    
+    assert_unifiable({ :x => :_a }, { :x => 1 })     # pass, :_a will be 1
+    assert_unifiable({ :y => :_a }, { })             # fail, a key :y should be present
+    assert_unifiable({ :y => :_a }, { :y => nil })   # pass, :_a will be nil
+    assert_unifiable({ :_a => 1 }, { :x => 1 })      # fail, meta variable can not appear as a key
+    
+    # assert_unifiable can receive a block, which will be yielded with the result of unification.
+    assert_unifiable([:_a, :_b], [1, 2]) do |unifier|
+      assert unifier[:_a] < unifier[:_b]
+    end
+
+## Installation
+
+Update your `Gemfile`.
+
+    gem "unification_assertion", :git => "git://github.com/soutaro/unification_assertion.git"
+
+Write your test case.
+
+    require "minitest/autorun"
+    require "unification_assertion"
+    
+    class GreatTest < MiniTest::Unit::TestCase
+      include UnificationAssertion
+      
+      def test_something
+        assert_unifiable([:_a, :_b], [1, 2])
+      end
+    end
+
+## Known Issues
+
+### It skips occur check
+
+The recursive pattern can not be processed well.
+
+    assert_unifiable(:_a, { :x => :_a })
+
+Usual unification algorithm rejects such input by *occur check*.  This
+library is expected to be used for testing, so that I omit the
+checking. (Who in the world will write such comparison?)
+
+## Author
+
+Written by Soutaro Matsumoto. (matsumoto at soutaro dot com)
+
+Released under the MIT License: www.opensource.org/licenses/mit-license.php
+
+github.com/soutaro/unification_assertion

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+
+desc "Test the library"
+task :test do
+  ENV['JSON'] = 'pure'
+  ENV['RUBYOPT'] = "-Ilib #{ENV['RUBY_OPT']}"
+  exec "ruby", *Dir['./test/*.rb']
+end

data/lib/unification_assertion.rb

@@ -0,0 +1,145 @@
+require "unification_assertion/version"
+
+module UnificationAssertion
+  module_function
+  
+  @@comparators = {}
+
+  @@comparators[Array] = lambda {|a, b, message, eqs, unifier, &block|
+    block.call(a.length, b.length, message + " (Array length mismatch)")
+    eqs.concat(a.zip(b))
+  }
+
+  @@comparators[Hash] = lambda {|a, b, message, eqs, unifier, &block|
+    block.call(a.keys.sort, b.keys.sort, message + " (Hash keys mismatch)")
+    eqs.concat(a.keys.map {|key| [a[key], b[key]] })
+  }
+
+  # Comparators are hash from a class to its comparator.
+  # It is used to check unifiability of two object of the given hash.
+  #
+  # There are two comparators defined by default; for |Array| and |Hash|.
+  #
+  # == Example ==
+  #   UnificationAssertion.comparators[Array] = lambda do |a, b, message, eqs, unifier, &block|
+  #     block.call(a.length, bl.ength, message + " (Array length mismatch)")
+  #     eqs.concat(a.zip(b))
+  #   end
+  #
+  # This is our comparator for |Array|. It first tests if the length of the two arrays are equal.
+  # And then, it pushes the equations of each components of the arrays.
+  # The components of the arrays will be tested unifiability later.
+  #
+  # == Comparator ==
+  #
+  # Comparator is a lambda which takes 5 arguments and block and checks the unifiability
+  # of the first two arguments.
+  #
+  # * |a|, |b|   Objects they are compared.
+  # * |message|  Message given to |unify|.
+  # * |eqs|      Equations array. This is for output.
+  # * |unifier|  Current unifier. This is just for reference.
+  # * |&block|   Block given to |unify|, which can be used to check the equality of two values.
+  # 
+  def comparators
+    @@comparators
+  end
+  
+  # Run unification algorithm for given equations.
+  # If all equations in |eqs| are unifiable, |unify| returns (the most-general) unifier.
+  # 
+  # Which identifies an symbol as a meta variable if the name matches with |options[:meta_pattern]|.
+  # The default of the meta variable pattern is |/^_/|.
+  # For example, |:_a| and |:_xyz| are meta variable, but |:a| and |:hello_world| are not.
+  #
+  # It also accepts wildcard variable. Which matches with any value, but does not introduce new equational constraints.
+  # The default wildcard is |:_|.
+  #
+  # |unify| takes a block to test equation of two values.
+  # The simplest form should be using |assert_equal|, however it can be customized as you like.
+  #
+  # == Example ==
+  #   unify([[:_a, 1], [{ :x => :_b, :y => 1 }, { :x => 3, :y => 1 }]], "Example!!") do |x, y, message|
+  #     assert_equal(x,y,message)
+  #   end
+  #
+  # The |unify| call will return an hash |{ :_a => 1, :_b => 3 }|.
+  # The block will be used to test equality between 1 and 1 (it will pass.)
+  #
+  def unify(eqs, message = "", unifier = {}, options = {}, &block)
+    options = { :meta_pattern => /^_/, :wildcard => :_ }.merge!(options)
+    
+    pattern = options[:meta_pattern]
+    wildcard = options[:wildcard]
+    
+    while eq = eqs.shift
+      a,b = eq
+      case
+      when (Symbol === a and a.to_s =~ pattern)
+        unless a == wildcard
+          eqs = substitute({ a => b }, eqs)
+          unifier = substitute({ a => b }, unifier).merge!(a => b)
+        end
+      when (Symbol === b and b.to_s =~ pattern)
+        unless b == wildcard
+          eqs = substitute({ b => a }, eqs)
+          unifier = substitute({ b => a }, unifier).merge!(b => a)
+        end
+      when (a.class == b.class and @@comparators[a.class])
+        @@comparators[a.class].call(a, b, message, eqs, unifier, &block)
+      else
+        yield(a, b, message)
+      end
+    end
+    
+    unifier.inject({}) {|acc, (key, value)|
+      if key == value
+        acc
+      else
+        acc.merge!(key => value)
+      end
+    }
+  end
+
+  @@substituters = {}
+  @@substituters[Hash] = lambda {|unifier, hash|
+    hash.inject({}) {|acc, (key, val)|
+      if unifier[val]
+        acc.merge!(key => unifier[val])
+      else
+        acc.merge!(key => substitute(unifier, val))
+      end
+    }
+  }
+  @@substituters[Symbol] = lambda {|unifier, symbol| unifier[symbol] or symbol }
+  @@substituters[Array] = lambda {|unifier, array|
+    array.map {|x| substitute(unifier, x) }
+  }
+
+  def substitutions
+    @@substituters
+  end
+  
+  def substitute(unifier, a)
+    subst = @@substituters[a.class]
+    if subst
+      subst.call(unifier, a)
+    else
+      a
+    end
+  end
+  
+  # Run unification between |a| and |b|, and fails if they are not unifiable.
+  # |assert_unifiable| can have block, which yields the unifier for |a| and |b| if exists.
+  # 
+  def assert_unifiable(a, b, message = "", options = {}, &block)
+    unifier = unify([[a, b]], message, {}, options) do |a, b, message|
+      assert_equal(a, b, message)
+    end
+
+    if block
+      yield(unifier)
+    end
+  end
+end
+

data/lib/unification_assertion/version.rb

@@ -0,0 +1,3 @@
+module UnificationAssertion
+  VERSION = "0.0.1"
+end

data/test/unification_assertion_test.rb

@@ -0,0 +1,127 @@
+require "minitest/autorun"
+require "unification_assertion"
+
+class UnificationAssertionTest < MiniTest::Unit::TestCase
+  include UnificationAssertion
+  
+  def call_unify(a, b)
+    begin
+      unifier = unify([[a,b]]) do |a, b|
+        unless a == b
+          raise "Failure"
+        end
+      end
+      return unifier
+    rescue
+      nil
+    end
+  end
+  
+  def test_substitution
+    subst = { :a => 1 }
+    
+    assert_equal 1, substitute(subst, :a)
+    assert_equal :b, substitute(subst, :b)
+    
+    assert_equal "a", substitute(subst, "a")
+    
+    assert_equal [], substitute(subst, [])
+    assert_equal [1], substitute(subst, [:a])
+    assert_equal [:b], substitute(subst, [:b])
+
+    assert_equal [[1]], substitute(subst, [[:a]])
+    assert_equal [[:b]], substitute(subst, [[:b]])
+
+    assert_equal({}, substitute(subst, {}))
+    assert_equal({ x: 1 }, substitute(subst, { x: :a }))
+    assert_equal({ x: :b}, substitute(subst, { x: :b }))
+    
+    assert_equal({ x: { y: 1 } }, substitute(subst, { x: { y: :a } }))
+    assert_equal({ x: { y: :b } }, substitute(subst, { x: { y: :b } }))
+  end
+
+  def test_unify
+    assert_nil call_unify(:a, :b)
+    
+    assert_equal({}, call_unify(:a, :a))
+    
+    assert_equal({ :_a => 1 }, call_unify(:_a, 1))
+    assert_equal({ :_b => :a }, call_unify(:a, :_b))
+    
+    assert_equal({ :_a => [1,:_b,3] }, call_unify([1,:_b,3], :_a))
+    assert_equal({}, call_unify([1,2,3], [1,2,3]))
+    assert_nil call_unify([1,2,3], [1,3])
+    assert_equal({ :_b => 2 }, call_unify([1,2,3], [1,:_b, 3]))
+    assert_nil call_unify([1,2,3], [:_a, 2, :_a])
+
+    assert_equal({}, call_unify({ a:1, b:2 }, { b:2, a:1 }))
+    assert_equal({ :_a => 2 }, call_unify({ a:1, b: :_a }, { b:2, a:1 }))
+    assert_equal({ :_b => :_a }, call_unify({ a: :_b, b: :_a }, { b: :_b, a: :_a }))
+    assert_equal({ :_a => 1 }, call_unify([1, { :x => :_a }], [:_a, { :x => 1 }]))
+    assert_nil call_unify([1, { :x => :_a }], [:_a, { :x => 2 }])
+    assert_equal({ :_a => 1, :_b => 1},  call_unify([1, :_b], [:_a, :_a]))
+
+    assert_equal({}, call_unify([:_, :_], [1,2]))
+  end
+
+  def test_assertion
+    assert_unifiable(:_a, [1,2,3])
+    
+    assert_unifiable(:_a, 1) do |unifier|
+      assert_equal 1, unifier[:_a]
+    end
+
+    # :_ is wildcard
+    assert_unifiable([:_, :_, :_], [1,2,3])
+    
+    assert_unifiable({ :created_at => :_a,
+                       :updated_at => :_b },
+                     { :created_at => Time.now,
+                       :updated_at => Time.now + 1 }) do |unifier|
+      assert unifier[:_a] <= unifier[:_b]
+    end
+
+    # Meta variable pattern can be changed (ML type variable style)
+    assert_unifiable([:"'a", :"'b", :"'_"], 
+                     [1, 2, 3],
+                     "Test message",
+                     :meta_pattern => /^'/,
+                     :wildcard => :"'_")
+  end
+
+  def test_assertion_failure
+    # 1 and 3 is incompatible
+    assert_raises(MiniTest::Assertion) do
+      assert_unifiable([:_a, :_a], [1, 3])
+    end
+
+    # Time.now and Time.now+1 is incompatible
+    assert_raises(MiniTest::Assertion) do
+      assert_unifiable({ :created_at => :_a,
+                         :updated_at => :_a },
+                       { :created_at => Time.now,
+                         :updated_at => Time.now + 1 })
+    end
+    
+    # There is no ``row'' variable
+    assert_raises(MiniTest::Assertion) do
+      assert_unifiable([:_a, :_b], [1,2,3])
+    end
+    
+    # There is no ``row'' variable
+    assert_raises(MiniTest::Assertion) do
+      assert_unifiable({ :_a => 3 }, { :x => :_b })
+    end
+  end
+
+  def test_occur_check_skipped
+    # This should be nil because of (absent) occur check will fail.
+    # :_a \in FV( { :x => :_a } )  => cyclic!!
+    #
+    # However, I have not implement it.
+    # This unification implementation is only for testing.
+    # Who on the earth write this kind of test? (meaningless and it will result different from what the programmer expects)
+    #
+    assert_equal({ :_a => { :x => :_a }}, call_unify(:_a, { :x => :_a }))
+  end
+end

data/unification_assertion.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "unification_assertion/version"
+
+Gem::Specification.new do |s|
+  s.name        = "justinf-unification_assertion"
+  s.version     = UnificationAssertion::VERSION
+  s.authors     = ["Soutaro Matsumoto"]
+  s.email       = ["matsumoto@soutaro.com"]
+  s.homepage    = "https://github.com/soutaro/unification_assertion"
+  s.summary     = "Assertion to test unifiability of two structures"
+  s.description = "UnificationAssertion defines +assert_unifiable+ assertion to test if given two values are unifiable.
+I only made this gem because Soutaro hadn't pushed it to rubygems yet.
+  "
+
+  s.rubyforge_project = "unification_assertion"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  # s.add_development_dependency "rspec"
+  # s.add_runtime_dependency "rest-client"
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: justinf-unification_assertion
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Soutaro Matsumoto
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-02-29 00:00:00 Z
+dependencies: []
+
+description: "UnificationAssertion defines +assert_unifiable+ assertion to test if given two values are unifiable.\n\
+  I only made this gem because Soutaro hadn't pushed it to rubygems yet.\n  "
+email: 
+- matsumoto@soutaro.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- lib/unification_assertion.rb
+- lib/unification_assertion/version.rb
+- test/unification_assertion_test.rb
+- unification_assertion.gemspec
+homepage: https://github.com/soutaro/unification_assertion
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: unification_assertion
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Assertion to test unifiability of two structures
+test_files: []
+