unific 0.9

data/.autotest

@@ -0,0 +1,23 @@
+# -*- ruby -*-
+
+require 'autotest/restart'
+
+# Autotest.add_hook :initialize do |at|
+#   at.extra_files << "../some/external/dependency.rb"
+#
+#   at.libs << ":../some/external"
+#
+#   at.add_exception 'vendor'
+#
+#   at.add_mapping(/dependency.rb/) do |f, _|
+#     at.files_matching(/test_.*rb$/)
+#   end
+#
+#   %w(TestA TestB).each do |klass|
+#     at.extra_class_map[klass] = "test/test_misc.rb"
+#   end
+# end
+
+# Autotest.add_hook :run_command do |at|
+#   system "rake build"
+# end

data/History.txt

@@ -0,0 +1,5 @@
+=== 0.9 / 2012-01-12
+
+* unific split out from the in-development rulog (Ruby With Logic) gem
+
+

data/Manifest.txt

@@ -0,0 +1,8 @@
+.autotest
+History.txt
+Manifest.txt
+README.rdoc
+README.txt
+Rakefile
+lib/unific.rb
+test/test_unific.rb

data/README.rdoc

@@ -0,0 +1,307 @@
+= unific
+
+https://github.com/jimwise/unific
+
+Author::    Jim Wise  (mailto:jwise@draga.com)
+Copyright:: Copyright (c) 2011, 2012 Jim Wise
+License::   2-clause BSD-Style (see LICENSE.txt)
+
+== DESCRIPTION:
+
+Unific is a ruby unification engine.
+
+A unification engine is an essential part of a logic programming environment
+(the whole logic programming environment this is taken from is available as
+the in-development Rulog[http://github.com/jimwise/rulog]] (Ruby With Logic)
+gem), but can also be useful on its own as a pattern matching engine which
+can enforce consistency across multiple matches.
+
+=== What is Unfication?
+
+Unfication is a generalization of pattern matching -- it allows you to
+compare two patterns or values, and determine if they match, possibly
+substituting variables in each pattern to make a match possible.
+
+Two values can be unified by passing both to the Unific::unify class method.
+This method returns false if the two values cannot be unified, or a
+(possibly empty) _environment_ if they can.  For the moment, it is enough to
+remember that this environment is a true value, but soon we will see that it
+is much more.
+
+===== Simple unification
+
+So, what does it mean to unify two values?
+
+In the simplest case, we can compare two values:
+
+    Unific::unify("foo", "foo")
+    ==> succeeds, returns an empty environment, which is a true value (see below)
+
+    Unific::unify(42, 42)
+    ==> succeeds, returns an empty environment, which is a true value (see below)
+
+    Unific::unify("foo", 42)
+    ==> false
+
+If two Enumerables are compared, they match if (and only if) their
+corresponding members match (and thus Enumerables of different lengths do
+not unify[1]):
+
+    Unific::unify([42, "a", "b"], [42, "a", "b"])
+    ==> an empty environment, which is a true value (see below)
+
+    Unific::unify({"a" => 1, "b" => 2}, {"a" => 1, "b" => 2})
+    ==> an empty environment, which is a true value (see below)
+
+    Unific::unify([42, "a", "b", "hike!"], [42, "a", "b"])
+    ==> false
+
+    Unific::unify([42, 33, "b"], [42, "a", "b"])
+    ==> false
+
+this implies that nested Enumerables are unified recursively:
+
+    Unific::unify([["a", 42], ["b", 33]], [["a", 42], ["b", 33]])
+    ==> returns an empty environment, which is a true value (see below)
+
+So far, this does nothing that we could not do with the == operator... but
+there's more.
+
+==== Pattern variables
+
+A unification variable of class Unific::Var can be created with any name of
+your choice, for use in unifications:
+
+    Unific::Var.new("x")
+    ==> #<Unific::Var:0x823b920 @name="x">
+
+when used with Unific::unify, a variable will successfully unify with any
+value:
+
+    x = Unific::Var.new("x")
+    Unific::unify(x, 42);
+    ==> a non-empty environment, which is a true value (see below)
+
+This also applies when a variable is unified as part of a larger expression
+
+    x = Unific::Var.new("x")
+    Unific::unify([1, x, 3], [1, 42, 3]);
+    ==> a non-empty environment, which is a true value (see below)
+
+Note that as a variable unifies with any object, a single variable can also
+be unified with an entire Enumerable
+
+    x = Unific::Var.new("x")
+    Unific::unify(x, [1, 2, 3]);
+    ==> a non-empty environment, which is a true value (see below)
+
+Note that when a variable matches a given value, it must match the _same_
+value everywhere in the same expression:
+
+    x = Unific::Var.new("x")
+    e = Unific::unify([x, x], [1, 2])
+    ==> false; x cannot be unified with both 1 and 2 in the same expression
+    x = Unific::Var.new("x")
+    e = Unific::unify([x, x], [2, 2])
+    ==> a non-empty environment, which is a true value (see below) 
+
+Binding a variable to another variable always succeeds (but is very useful
+when we start using the environments returned by unification, below).
+
+So where does the environment returned by Unific::unify come in?  The
+returned environment, an object of class Unific::Env, matches ('binds') each
+variable to the value with which it was actually unified.  The method Env#[]
+can be used to see whether a variable is bound in a given environment:
+
+    x = Unific::Var.new("x")
+    y = Unific::Var.new("y")
+    e = Unific::unify([1, x, 3], [1, 42, 3]);
+    e[x]
+    ==> 42
+    e[y]
+    ==> nil
+
+So far, we can perform some relatively interesting pattern matches with
+Unific:
+
+    jumper = Unific::Var.new("jumper")
+    jumpee = Unific::Var.new("jumpee")
+    pattern = ["The", "quick", "brown", jumper, "jumped", "over", "the", "lazy", jumpee]
+    sentence = "The quick brown fox jumped over the lazy dog"
+    e = Unific::unify(pattern, sentence.split)
+    e[jumper]
+    ==> "fox"
+
+but where this becomes more interesting is when we want to perform multiple
+unifications in a consistent way.
+
+
+==== Chaining unifications
+
+Any unification can be performed against a given environment by using
+Env#unify method.  If the given environment is empty, this is the same as
+calling Unific::unify.[2] If the environment already has bindings, however,
+the new unification will use these bindings; this means that any variable
+matches performed against the same variables must be consistent with the
+values already bound to those variables:
+
+    animal = Unific::Var.new("animal")
+    e = Unific::unify([animal, "is", "a", "mammal"], "fido is a mammal".split)
+    e[animal]
+    ==> "fido"
+    e.unify([animal, "is", "a", "bear"], "teddy is a bear".split)
+    ==> false (cannot unify, as "animal" is bound to "fido" in environment e)
+
+Note that unifying against a given environment returns a _new_ environment
+in which any additional variables matched by that unification are also
+bound; the original environment is not modified.
+
+This is often used by chaining calls to unify (since each call returns a new
+environment);  note that this can only be done if none of the unifications
+returns `false', however[3]:
+
+    a = Unific::Var.new("a")
+    a = Unific::Var.new("b")
+    e = Unific::unify([a, 1, 2], [0, 1, 2]).unify([a, b, 5], [0, 3, 5])
+    ==> a new environment where a is bound to 0, and b is bound to 3
+
+Now, it becomes useful to be able to unify to variables:
+
+     # x = y + 3
+     # y = 2
+     x = Unific::Var.new("x")
+     y = Unific::Var.new("y")
+     e1 = Unific::unify(x, [y, "+", 3])
+     e2 = e1.unify(y, 2)
+
+We can use the #instantiate method of Unific::Env to recursively substitute
+a variable until we get an uninstantiated variable, or a non-variable
+("ground") value.  Given the above, for instance:
+
+    e2[x]
+    ==> [y, "+", 3]
+    e2[y]
+    ==> 2
+    e2.instantate x
+    ==> [2, "+", 3]
+
+The #instantiate method of Unific::Env is also more general than the #[]
+method -- in addition to a variable, it can take _any_ value which could be
+passed to unify, and will substitute any variables in the term.
+
+    jumper = Unific::Var.new("jumper")
+    jumpee = Unific::Var.new("jumpee")
+    pattern = ["The", "quick", "brown", jumper, "jumped", "over", "the", "lazy", jumpee]
+    sentence = "The quick brown fox jumped over the lazy dog"
+    e = Unific::unify(pattern, sentence.split)
+    e.instantiate(["The", jumpee, "chased", "the", jumper]).join(" ")
+    ==> "The dog chased the fox"
+
+==== Wildcards
+
+Finally, the value Unific::_ is a special variable which matches any value:
+
+    x = Unific::Var.new("x")
+    e = Unific::unify([Unific::_, x, Unific::_], [1, 2, 3])
+    ==> a new environment where x is bound to 2
+
+We could not use a plain variable for this purpose, since it would have to
+evaluate to the same value whenever used in the same expression.
+
+Matching against Unific::_ does not cause any binding in the returned
+environment, either:
+
+    x = Unific::Var.new("x")
+    e = Unific::unify([Unific::_, x], [1, 2]).unify([x, Unific::_], [2, 3])
+    ==> a new environment where x is bound to 2
+
+==== Watching Unific work
+
+The class method Unific::trace can be used to enable debug tracing of Unific
+operations.  Repeated calls to Unific::trace increase the verbosity of trace
+output (though this has no effect in the current version), and a specific
+trace level (as an integer) may also be passed to Unific::trace as an
+optional argument.
+
+Trace output is written to STDERR.  Trace output can be disabled by
+specifying a trace level of 0, or by calling Unific::untrace.
+
+==== Notes
+
+[1] Unific does not currently have an equivalent of Prolog's incomplete data
+structures.  I am looking at a clean way to implement this in a future
+release.
+
+[2] Which actually just creates an empty environment and unifies against it
+
+[3] This may be revisited in a future version, but the current behavior of
+returning false on unification failure allows the idiom of
+    
+    if e.unify(...)
+      ...
+    end
+
+which is very useful.
+
+==== References
+
+For more information on unification, see
+
+* Sterling, Leon and Ehud Shapiro, <em>The Art of Prolog</em>, MIT Press, 1994
+
+The implementation of unification given here is heavily influenced by the
+presentation there.
+
+
+== INSTALL:
+
+To install: 
+
+    $ gem install unific
+
+== DEVELOPERS:
+
+After checking out the source, run:
+
+  $ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the RDoc.
+
+== SYNOPSIS:
+
+  FIX (code sample of usage)
+
+== REQUIREMENTS:
+
+This gem should run fine under Ruby 1.8.7 or 1.9.  If you experience any
+issues, please let me know.
+
+== LICENSE:
+
+(The BSD 2-clause License)
+
+ Copyright (c) 2011, 2012 Jim Wise
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS
+ BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.

data/README.txt

@@ -0,0 +1,307 @@
+= unific
+
+https://github.com/jimwise/unific
+
+Author::    Jim Wise  (mailto:jwise@draga.com)
+Copyright:: Copyright (c) 2011, 2012 Jim Wise
+License::   2-clause BSD-Style (see LICENSE.txt)
+
+== DESCRIPTION:
+
+Unific is a ruby unification engine.
+
+A unification engine is an essential part of a logic programming environment
+(the whole logic programming environment this is taken from is available as
+the in-development Rulog[http://github.com/jimwise/rulog]] (Ruby With Logic)
+gem), but can also be useful on its own as a pattern matching engine which
+can enforce consistency across multiple matches.
+
+=== What is Unfication?
+
+Unfication is a generalization of pattern matching -- it allows you to
+compare two patterns or values, and determine if they match, possibly
+substituting variables in each pattern to make a match possible.
+
+Two values can be unified by passing both to the Unific::unify class method.
+This method returns false if the two values cannot be unified, or a
+(possibly empty) _environment_ if they can.  For the moment, it is enough to
+remember that this environment is a true value, but soon we will see that it
+is much more.
+
+===== Simple unification
+
+So, what does it mean to unify two values?
+
+In the simplest case, we can compare two values:
+
+    Unific::unify("foo", "foo")
+    ==> succeeds, returns an empty environment, which is a true value (see below)
+
+    Unific::unify(42, 42)
+    ==> succeeds, returns an empty environment, which is a true value (see below)
+
+    Unific::unify("foo", 42)
+    ==> false
+
+If two Enumerables are compared, they match if (and only if) their
+corresponding members match (and thus Enumerables of different lengths do
+not unify[1]):
+
+    Unific::unify([42, "a", "b"], [42, "a", "b"])
+    ==> an empty environment, which is a true value (see below)
+
+    Unific::unify({"a" => 1, "b" => 2}, {"a" => 1, "b" => 2})
+    ==> an empty environment, which is a true value (see below)
+
+    Unific::unify([42, "a", "b", "hike!"], [42, "a", "b"])
+    ==> false
+
+    Unific::unify([42, 33, "b"], [42, "a", "b"])
+    ==> false
+
+this implies that nested Enumerables are unified recursively:
+
+    Unific::unify([["a", 42], ["b", 33]], [["a", 42], ["b", 33]])
+    ==> returns an empty environment, which is a true value (see below)
+
+So far, this does nothing that we could not do with the == operator... but
+there's more.
+
+==== Pattern variables
+
+A unification variable of class Unific::Var can be created with any name of
+your choice, for use in unifications:
+
+    Unific::Var.new("x")
+    ==> #<Unific::Var:0x823b920 @name="x">
+
+when used with Unific::unify, a variable will successfully unify with any
+value:
+
+    x = Unific::Var.new("x")
+    Unific::unify(x, 42);
+    ==> a non-empty environment, which is a true value (see below)
+
+This also applies when a variable is unified as part of a larger expression
+
+    x = Unific::Var.new("x")
+    Unific::unify([1, x, 3], [1, 42, 3]);
+    ==> a non-empty environment, which is a true value (see below)
+
+Note that as a variable unifies with any object, a single variable can also
+be unified with an entire Enumerable
+
+    x = Unific::Var.new("x")
+    Unific::unify(x, [1, 2, 3]);
+    ==> a non-empty environment, which is a true value (see below)
+
+Note that when a variable matches a given value, it must match the _same_
+value everywhere in the same expression:
+
+    x = Unific::Var.new("x")
+    e = Unific::unify([x, x], [1, 2])
+    ==> false; x cannot be unified with both 1 and 2 in the same expression
+    x = Unific::Var.new("x")
+    e = Unific::unify([x, x], [2, 2])
+    ==> a non-empty environment, which is a true value (see below) 
+
+Binding a variable to another variable always succeeds (but is very useful
+when we start using the environments returned by unification, below).
+
+So where does the environment returned by Unific::unify come in?  The
+returned environment, an object of class Unific::Env, matches ('binds') each
+variable to the value with which it was actually unified.  The method Env#[]
+can be used to see whether a variable is bound in a given environment:
+
+    x = Unific::Var.new("x")
+    y = Unific::Var.new("y")
+    e = Unific::unify([1, x, 3], [1, 42, 3]);
+    e[x]
+    ==> 42
+    e[y]
+    ==> nil
+
+So far, we can perform some relatively interesting pattern matches with
+Unific:
+
+    jumper = Unific::Var.new("jumper")
+    jumpee = Unific::Var.new("jumpee")
+    pattern = ["The", "quick", "brown", jumper, "jumped", "over", "the", "lazy", jumpee]
+    sentence = "The quick brown fox jumped over the lazy dog"
+    e = Unific::unify(pattern, sentence.split)
+    e[jumper]
+    ==> "fox"
+
+but where this becomes more interesting is when we want to perform multiple
+unifications in a consistent way.
+
+
+==== Chaining unifications
+
+Any unification can be performed against a given environment by using
+Env#unify method.  If the given environment is empty, this is the same as
+calling Unific::unify.[2] If the environment already has bindings, however,
+the new unification will use these bindings; this means that any variable
+matches performed against the same variables must be consistent with the
+values already bound to those variables:
+
+    animal = Unific::Var.new("animal")
+    e = Unific::unify([animal, "is", "a", "mammal"], "fido is a mammal".split)
+    e[animal]
+    ==> "fido"
+    e.unify([animal, "is", "a", "bear"], "teddy is a bear".split)
+    ==> false (cannot unify, as "animal" is bound to "fido" in environment e)
+
+Note that unifying against a given environment returns a _new_ environment
+in which any additional variables matched by that unification are also
+bound; the original environment is not modified.
+
+This is often used by chaining calls to unify (since each call returns a new
+environment);  note that this can only be done if none of the unifications
+returns `false', however[3]:
+
+    a = Unific::Var.new("a")
+    a = Unific::Var.new("b")
+    e = Unific::unify([a, 1, 2], [0, 1, 2]).unify([a, b, 5], [0, 3, 5])
+    ==> a new environment where a is bound to 0, and b is bound to 3
+
+Now, it becomes useful to be able to unify to variables:
+
+     # x = y + 3
+     # y = 2
+     x = Unific::Var.new("x")
+     y = Unific::Var.new("y")
+     e1 = Unific::unify(x, [y, "+", 3])
+     e2 = e1.unify(y, 2)
+
+We can use the #instantiate method of Unific::Env to recursively substitute
+a variable until we get an uninstantiated variable, or a non-variable
+("ground") value.  Given the above, for instance:
+
+    e2[x]
+    ==> [y, "+", 3]
+    e2[y]
+    ==> 2
+    e2.instantate x
+    ==> [2, "+", 3]
+
+The #instantiate method of Unific::Env is also more general than the #[]
+method -- in addition to a variable, it can take _any_ value which could be
+passed to unify, and will substitute any variables in the term.
+
+    jumper = Unific::Var.new("jumper")
+    jumpee = Unific::Var.new("jumpee")
+    pattern = ["The", "quick", "brown", jumper, "jumped", "over", "the", "lazy", jumpee]
+    sentence = "The quick brown fox jumped over the lazy dog"
+    e = Unific::unify(pattern, sentence.split)
+    e.instantiate(["The", jumpee, "chased", "the", jumper]).join(" ")
+    ==> "The dog chased the fox"
+
+==== Wildcards
+
+Finally, the value Unific::_ is a special variable which matches any value:
+
+    x = Unific::Var.new("x")
+    e = Unific::unify([Unific::_, x, Unific::_], [1, 2, 3])
+    ==> a new environment where x is bound to 2
+
+We could not use a plain variable for this purpose, since it would have to
+evaluate to the same value whenever used in the same expression.
+
+Matching against Unific::_ does not cause any binding in the returned
+environment, either:
+
+    x = Unific::Var.new("x")
+    e = Unific::unify([Unific::_, x], [1, 2]).unify([x, Unific::_], [2, 3])
+    ==> a new environment where x is bound to 2
+
+==== Watching Unific work
+
+The class method Unific::trace can be used to enable debug tracing of Unific
+operations.  Repeated calls to Unific::trace increase the verbosity of trace
+output (though this has no effect in the current version), and a specific
+trace level (as an integer) may also be passed to Unific::trace as an
+optional argument.
+
+Trace output is written to STDERR.  Trace output can be disabled by
+specifying a trace level of 0, or by calling Unific::untrace.
+
+==== Notes
+
+[1] Unific does not currently have an equivalent of Prolog's incomplete data
+structures.  I am looking at a clean way to implement this in a future
+release.
+
+[2] Which actually just creates an empty environment and unifies against it
+
+[3] This may be revisited in a future version, but the current behavior of
+returning false on unification failure allows the idiom of
+    
+    if e.unify(...)
+      ...
+    end
+
+which is very useful.
+
+==== References
+
+For more information on unification, see
+
+* Sterling, Leon and Ehud Shapiro, <em>The Art of Prolog</em>, MIT Press, 1994
+
+The implementation of unification given here is heavily influenced by the
+presentation there.
+
+
+== INSTALL:
+
+To install: 
+
+    $ gem install unific
+
+== DEVELOPERS:
+
+After checking out the source, run:
+
+  $ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the RDoc.
+
+== SYNOPSIS:
+
+  FIX (code sample of usage)
+
+== REQUIREMENTS:
+
+This gem should run fine under Ruby 1.8.7 or 1.9.  If you experience any
+issues, please let me know.
+
+== LICENSE:
+
+(The BSD 2-clause License)
+
+ Copyright (c) 2011, 2012 Jim Wise
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS
+ BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -0,0 +1,23 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+
+# Hoe.plugin :compiler
+# Hoe.plugin :compiler
+# Hoe.plugin :gem_prelude_sucks
+# Hoe.plugin :gem_prelude_sucks
+# Hoe.plugin :inline
+# Hoe.plugin :inline
+# Hoe.plugin :racc
+# Hoe.plugin :racc
+# Hoe.plugin :rubyforge
+# Hoe.plugin :rubyforge
+
+Hoe.spec 'unific' do
+
+  developer('Jim Wise', 'jwise@draga.com')
+
+end
+
+# vim: syntax=ruby

data/lib/unific.rb

@@ -0,0 +1,245 @@
+require 'singleton'
+
+module Unific
+
+  VERSION = '0.9'
+
+  # An environment (set of variable bindings) resulting from unification
+  class Env
+    @@trace = 0
+
+    # Allocate a new environment.  Usually not needed -- use Unific::unify, instead.
+    #
+    # The new environment will be empty unless a hash of variable bindings
+    # is included.  Use this with care.
+    def initialize prev = {}
+      @theta = prev.clone
+    end
+
+    # Turn on tracing (to STDERR) of Unific operations
+    #
+    # intended for use by Unific::trace
+    #
+    # The optional level argument sets the verbosity -- if not passed, each
+    # call to this method increases verbosity
+    def self.trace lvl #:nodoc:
+      if lvl
+        @@trace = lvl
+      else
+        @@trace = @@trace + 1
+      end
+    end
+
+    # Turn off tracing (to STDERR) of Unific operations
+    #
+    # intended for use by Unific::trace
+    def self.untrace #:nodoc:
+      @@trace = 0
+    end
+
+    # Return whether a given variable is fresh (not bound) in this environment
+    def fresh? x
+      not @theta.has_key? x
+    end
+
+    # Return the binding of a variable in this environment, or +nil+ if it is unbound
+    def [] x
+      @theta[x]
+    end
+
+    # private helper to extend this environment with one or more new mappings
+    def _extend mappings
+      Env.new @theta.update mappings.reject {|k, v| k.kind_of? Wildcard or v.kind_of? Wildcard }
+    end
+
+    def to_s
+      "{ " + @theta.map{|k, v| "#{k} => #{v}"}.join(", ") + "} "
+    end
+
+    # Unify two values against this environment, returning a new environment
+    #
+    # If the two values cannot be unified, `false' is returned.  If they can, a _new_
+    # environment is returned which is this environment extended with any new bindings
+    # created by unification.
+    # 
+    # Each value to unify can be
+    #
+    # a. a Unific::Var variable
+    # b. the wildcard variable, Unific::_
+    # c. any ruby Enumerable except a String, in which case unification recurs on the members
+    # e. a String or any other ruby object (as a ground term -- unification succeeds
+    # if the two are equal (with '=='))
+    #
+    # In logic programming terms, the returned env is the Most General Unifier (MGU) of the two
+    # terms
+    def unify a, b
+      puts "unifying #{a.to_s} and #{b.to_s}" if @@trace > 0
+
+      # if either is already bound, substitute up front
+      a = instantiate a
+      b = instantiate b
+
+      # any remaining Var is fresh.
+      if a.kind_of? Var and b.kind_of? Var
+        _extend a => b
+      elsif a.kind_of? Var
+        _extend a => b
+      elsif b.kind_of? Var
+        _extend b => a
+      elsif a.kind_of? String and b.kind_of? String # strings should be treated as ground
+        if a == b
+          self
+        else
+          Unific::fail
+        end
+      elsif a.kind_of? Enumerable and b.kind_of? Enumerable
+        return Unific::fail unless a.size == b.size
+        a.zip(b).inject(self) do |e, pair|
+          e.unify(pair[0], pair[1]) or return Unific::fail
+        end
+      else # both are ground terms
+        if a == b
+          self
+        else
+          Unific::fail
+        end
+      end
+    end
+
+    # Given a value, substitute any variables present in the term.
+    #
+    # If the passed value is a Ruby Enumerable other than a String, recurs on the members of
+    # the Enumerable.  Unlike #[], also repeatedly substitutes each variable until it gets a
+    # ground (non-variable) term or a free variable
+    def instantiate s
+      _traverse s do |v|
+        if fresh? v
+          v
+        else
+          instantiate @theta[v]
+        end
+      end
+    end
+
+    # Perform alpha renaming on an expression
+    #
+    # Alpha-renaming an expression replaces all fresh variables in the
+    # expression with new variables of the same name.  This is used by rulog
+    # to to give each Rule its own private copy of all of its variables.
+    def rename s
+      _traverse s do |v|
+        if fresh? v
+          n = Unific::Var.new(v.name)
+          @theta[v] = n;
+          n
+        else
+          instantiate @theta[v]
+        end
+      end
+    end
+
+    # private helper for instantiate and rename
+    # given an argument, if it is an:
+    #   a.) var, replace it with the result of calling a block on it
+    #   b.) enumerable, recur, instantiating it's members
+    #   c.) any object, return it
+    def _traverse s, &block
+      case s
+      when Unific::Wildcard
+        s
+      when Var
+        block.call(s)
+      # XXX XXX rulog had handling for Functor here, we may need to provide something similar?
+      when String
+        # in ruby 1.8, strings are enumerable, but we want them to be ground
+        s
+      when Enumerable
+        s.map {|x| _traverse(x, &block)}
+      else
+        s
+      end
+    end
+
+    private :_extend, :_traverse
+  end
+
+  # Unify two terms against an empty environment
+  # 
+  # See README.rdoc or Env#unify for details
+  #
+  # If the two values cannot be unified, `false' is returned.  If they can, a _new_
+  # environment is returned which is this environment extended with any new bindings
+  # created by unification.
+  #--
+  # XXX This documentation must be kept in sync with that for Env#unify
+  #++
+  def self.unify a, b, env = Env.new
+    env.unify a, b
+  end
+
+  # A unification variable
+  class Var
+    attr_accessor :name
+
+    # Create a new variable
+    #
+    # The optional argument provides a name for use in printing the variable
+    def initialize name = "new_var"
+      @name = name
+      self.freeze
+    end
+    
+    # Return a string representing a variable
+    #
+    # A variable named"foo" is presented as as "?foo"
+    def to_s
+      "?#{@name}"
+    end
+  end
+
+  # The unique Unific wildcard variable
+  class Wildcard < Var
+    include Singleton
+
+    # The wildcard variable is named "_"
+    def initialize #:nodoc:
+      super "_"
+    end
+
+    # The wildcard variable is presented as "_"
+    def to_s
+      "_"
+    end
+
+    # The wildcard variable matches any value
+    def == x
+      true
+    end
+  end
+
+  # Return the Unific wildcard variable
+  def self._
+    Unific::Wildcard.instance
+  end
+
+  # Turn on tracing (to STDERR) of Unific operations
+  #
+  # The optional level argument sets the verbosity -- if not passed, each
+  # call to this method increases verbosity
+  def self.trace lvl = false
+    Unific::Env::trace lvl
+  end
+
+  # Turn off tracing (to STDERR) of Unific operations
+  def self.untrace
+    Unific::Env::untrace untrace
+  end
+
+  # Return false
+  #
+  # Placeholder for possible future expansion of failed unification behavior
+  def self.fail
+    false
+  end
+
+end

data/test/test_unific.rb

@@ -0,0 +1,54 @@
+require "test/unit"
+require "unific"
+
+class TestUnific < Test::Unit::TestCase
+
+  def test_unify_simple
+    assert Unific::unify(42, 42)
+    assert Unific::unify("abc", "abc")
+    assert Unific::unify(42, Unific::Var.new)
+    assert Unific::unify(Unific::Var.new, 42)
+    assert Unific::unify(Unific::Var.new, Unific::Var.new)
+    v1 = Unific::Var.new("v1")
+    assert Unific::unify(v1, v1)
+    assert Unific::unify(v1, 42).unify(v1, 42)
+    assert !Unific::unify(v1, 42).unify(v1, 35)
+  end
+
+  def test_unify_enum
+    assert Unific::unify([1, 2, 3], [1, 2, 3])
+    assert !Unific::unify([1, 2, 3], [1, 2, 3, 4])
+    assert Unific::unify([1, 2, 3], [1, Unific::Var.new, 3])
+    assert Unific::unify({"a" => 1}, {"a" => 1})
+    assert !Unific::unify({"a" => 2}, {"a" => 3})
+  end
+
+  def test_unify_recursive_enum
+    assert Unific::unify([["a", 1], ["b", 2]], [["a", 1], ["b", 2]])
+    assert !Unific::unify([["a", 1], ["b", 2]], [["x", 3], ["y", 4]])
+    assert Unific::unify([[1,2], [3,4], [5,6]], [[1,2], Unific::Var.new, [5,6]])
+  end
+
+  def test_wildcard
+    assert Unific::unify(Unific::_, 42);
+    assert Unific::unify(Unific::_, Unific::Var.new);
+    assert Unific::unify([Unific::_, 2], [1, 2]).unify([2, Unific::_], [2, 3])
+    v1 = Unific::Var.new("v1")
+    e1 = Unific::Env.new
+    e2 = Unific::unify(v1, 42);
+    assert Unific::unify(v1, Unific::_, e2);
+    assert Unific::unify([1, 2, 3], Unific::_)
+    assert Unific::unify([1, Unific::_, 3], [1, 2, 3])
+    assert Unific::unify([Unific::_, 3, Unific::_], [2, 3, 4])
+  end
+
+  def test_vars
+    v1 = Unific::Var.new("v1")
+    v2 = Unific::Var.new("v2")
+    assert Unific::unify(v1, v2).unify(v1, 42).unify(v2, 42)
+    assert !Unific::unify(v1, v2).unify(v1, 42).unify(v2, 35)
+    assert Unific::unify(v1, 42).unify(v1, v2).unify(v2, 42)
+    assert !Unific::unify(v1, 42).unify(v1, v2).unify(v2, 35)
+  end
+
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification 
+name: unific
+version: !ruby/object:Gem::Version 
+  hash: 25
+  prerelease: 
+  segments: 
+  - 0
+  - 9
+  version: "0.9"
+platform: ruby
+authors: 
+- Jim Wise
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-01-12 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 3
+        - 10
+        version: "3.10"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 2
+        - 12
+        version: "2.12"
+  type: :development
+  version_requirements: *id002
+description: |-
+  Unific is a ruby unification engine.
+  
+  A unification engine is an essential part of a logic programming environment
+  (the whole logic programming environment this is taken from is available as
+  the in-development Rulog[http://github.com/jimwise/rulog]] (Ruby With Logic)
+  gem), but can also be useful on its own as a pattern matching engine which
+  can enforce consistency across multiple matches.
+email: 
+- jwise@draga.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- .autotest
+- History.txt
+- Manifest.txt
+- README.rdoc
+- README.txt
+- Rakefile
+- lib/unific.rb
+- test/test_unific.rb
+- .gemtest
+homepage: https://github.com/jimwise/unific
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+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: unific
+rubygems_version: 1.8.13
+signing_key: 
+specification_version: 3
+summary: Unific is a ruby unification engine
+test_files: 
+- test/test_unific.rb