kanren 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 67670e33fe713a422e5149f2f01748851540d2ac
+  data.tar.gz: d1e95c8070cea4b57c24e87d5f5abd76aca0eb05
+SHA512:
+  metadata.gz: 4400e2f646e4543204997c48cd9d7e88313349f279e2d643e71dd45b9ad6560b33c028bdd5b5baa9c714fbf1d025a0c8e80caf1888dafcc17258711ce837be58
+  data.tar.gz: 18b82172ef9564b0177aa6747554582f944e158ba9a8ed8a8de571ea170387415d1633358c7b7820c3d1bca39a05cfcd8ac268df75ed7e96dd5957e61c6193dc

data/.gitignore

@@ -0,0 +1 @@
+Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org/'
+
+gemspec

data/LICENSE

@@ -0,0 +1,116 @@
+CC0 1.0 Universal
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator and
+subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for the
+purpose of contributing to a commons of creative, cultural and scientific
+works ("Commons") that the public can reliably and without fear of later
+claims of infringement build upon, modify, incorporate in other works, reuse
+and redistribute as freely as possible in any form whatsoever and for any
+purposes, including without limitation commercial purposes. These owners may
+contribute to the Commons to promote the ideal of a free culture and the
+further production of creative, cultural and scientific works, or to gain
+reputation or greater distribution for their Work in part through the use and
+efforts of others.
+
+For these and/or other purposes and motivations, and without any expectation
+of additional consideration or compensation, the person associating CC0 with a
+Work (the "Affirmer"), to the extent that he or she is an owner of Copyright
+and Related Rights in the Work, voluntarily elects to apply CC0 to the Work
+and publicly distribute the Work under its terms, with knowledge of his or her
+Copyright and Related Rights in the Work and the meaning and intended legal
+effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not limited
+to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display, communicate,
+  and translate a Work;
+
+  ii. moral rights retained by the original author(s) and/or performer(s);
+
+  iii. publicity and privacy rights pertaining to a person's image or likeness
+  depicted in a Work;
+
+  iv. rights protecting against unfair competition in regards to a Work,
+  subject to the limitations in paragraph 4(a), below;
+
+  v. rights protecting the extraction, dissemination, use and reuse of data in
+  a Work;
+
+  vi. database rights (such as those arising under Directive 96/9/EC of the
+  European Parliament and of the Council of 11 March 1996 on the legal
+  protection of databases, and under any national implementation thereof,
+  including any amended or successor version of such directive); and
+
+  vii. other similar, equivalent or corresponding rights throughout the world
+  based on applicable law or treaty, and any national implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention of,
+applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and
+unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
+and Related Rights and associated claims and causes of action, whether now
+known or unknown (including existing as well as future claims and causes of
+action), in the Work (i) in all territories worldwide, (ii) for the maximum
+duration provided by applicable law or treaty (including future time
+extensions), (iii) in any current or future medium and for any number of
+copies, and (iv) for any purpose whatsoever, including without limitation
+commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes
+the Waiver for the benefit of each member of the public at large and to the
+detriment of Affirmer's heirs and successors, fully intending that such Waiver
+shall not be subject to revocation, rescission, cancellation, termination, or
+any other legal or equitable action to disrupt the quiet enjoyment of the Work
+by the public as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason be
+judged legally invalid or ineffective under applicable law, then the Waiver
+shall be preserved to the maximum extent permitted taking into account
+Affirmer's express Statement of Purpose. In addition, to the extent the Waiver
+is so judged Affirmer hereby grants to each affected person a royalty-free,
+non transferable, non sublicensable, non exclusive, irrevocable and
+unconditional license to exercise Affirmer's Copyright and Related Rights in
+the Work (i) in all territories worldwide, (ii) for the maximum duration
+provided by applicable law or treaty (including future time extensions), (iii)
+in any current or future medium and for any number of copies, and (iv) for any
+purpose whatsoever, including without limitation commercial, advertising or
+promotional purposes (the "License"). The License shall be deemed effective as
+of the date CC0 was applied by Affirmer to the Work. Should any part of the
+License for any reason be judged legally invalid or ineffective under
+applicable law, such partial invalidity or ineffectiveness shall not
+invalidate the remainder of the License, and in such case Affirmer hereby
+affirms that he or she will not (i) exercise any of his or her remaining
+Copyright and Related Rights in the Work or (ii) assert any associated claims
+and causes of action with respect to the Work, in either case contrary to
+Affirmer's express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+  a. No trademark or patent rights held by Affirmer are waived, abandoned,
+  surrendered, licensed or otherwise affected by this document.
+
+  b. Affirmer offers the Work as-is and makes no representations or warranties
+  of any kind concerning the Work, express, implied, statutory or otherwise,
+  including without limitation warranties of title, merchantability, fitness
+  for a particular purpose, non infringement, or the absence of latent or
+  other defects, accuracy, or the present or absence of errors, whether or not
+  discoverable, all to the greatest extent permissible under applicable law.
+
+  c. Affirmer disclaims responsibility for clearing rights of other persons
+  that may apply to the Work or any use thereof, including without limitation
+  any person's Copyright and Related Rights in the Work. Further, Affirmer
+  disclaims responsibility for obtaining any necessary consents, permissions
+  or other rights required for any use of the Work.
+
+  d. Affirmer understands and acknowledges that Creative Commons is not a
+  party to this document and has no duty or obligation with respect to this
+  CC0 or use of the Work.
+
+For more information, please see
+<http://creativecommons.org/publicdomain/zero/1.0/>

data/README.md

@@ -0,0 +1,60 @@
+# Kanren
+
+This library provides an example Ruby implementation of [μKanren](http://webyrd.net/scheme-2013/papers/HemannMuKanren2013.pdf), along with some simple data structures and relations. It is intended to accompany the article [“Hello, declarative world”](http://codon.com/hello-declarative-world).
+
+That article explains the details, but here’s a brief demonstration:
+
+```irb
+$ irb -Ilib
+>> require 'kanren/micro'
+=> true
+>> include Kanren::Micro
+=> Object
+
+>> goal = Goal.with_variables { |x, y|
+     Goal.either(Goal.equal(x, 1), Goal.equal(y, 2))
+   }
+=> #<Kanren::Micro::Goal …>
+>> states = goal.pursue_in(State.new)
+=> #<Enumerator: …>
+>> states.next.values
+=> {x=>1}
+>> states.next.values
+=> {y=>2}
+>> states.next.values
+StopIteration: iteration reached an end
+
+>> include Kanren
+=> Object
+
+>> goal = Goal.with_variables { |x|
+     Relations.multiply(Peano.from_integer(3), Peano.from_integer(4), x)
+   }
+=> #<Kanren::Micro::Goal …>
+>> states = goal.pursue_in(State.new)
+=> #<Enumerator: …>
+>> Peano.to_integer(states.next.result)
+=> 12
+
+>> goal = Goal.with_variables { |x, y|
+     Relations.add(x, y, Peano.from_integer(8))
+   }
+=> #<Kanren::Micro::Goal …>
+>> states = goal.pursue_in(State.new)
+=> #<Enumerator: …>
+>> states.each do |state|
+     p state.results(2).map { |peano| Peano.to_integer(peano) }
+   end
+[0, 8]
+[1, 7]
+[2, 6]
+[3, 5]
+[4, 4]
+[5, 3]
+[6, 2]
+[7, 1]
+[8, 0]
+=> nil
+```
+
+If you have any questions, please get in touch via [Twitter](http://twitter.com/tomstuart) or [email](mailto:tom@codon.com). If you find any bugs or other problems with the code, please [open an issue](https://github.com/tomstuart/kanren/issues/new).

data/kanren.gemspec

@@ -0,0 +1,20 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'kanren/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'kanren'
+  spec.version       = Kanren::VERSION
+  spec.author        = 'Tom Stuart'
+  spec.email         = 'tom@codon.com'
+
+  spec.summary       = 'An example Ruby implementation of μKanren.'
+  spec.homepage      = 'https://github.com/tomstuart/kanren'
+  spec.license       = 'CC0-1.0'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'rspec', '~> 3.3', '>= 3.3.0'
+end

data/lib/kanren.rb

@@ -0,0 +1,6 @@
+require 'kanren/list'
+require 'kanren/micro'
+require 'kanren/pair'
+require 'kanren/peano'
+require 'kanren/utils'
+require 'kanren/version'

data/lib/kanren/list.rb

@@ -0,0 +1,35 @@
+require 'kanren/pair'
+
+module Kanren
+  module List
+    EMPTY = Object.new
+
+    module_function
+
+    def from_array(array)
+      if array.empty?
+        EMPTY
+      else
+        first, *rest = array
+        Pair.new(first, from_array(rest))
+      end
+    end
+
+    def to_array(list)
+      if list == EMPTY
+        []
+      else
+        first, rest = list.left, list.right
+        [first, *to_array(rest)]
+      end
+    end
+
+    def to_list(array)
+      from_array array
+    end
+
+    def from_list(list)
+      to_array list
+    end
+  end
+end

data/lib/kanren/micro.rb

@@ -0,0 +1,4 @@
+require 'kanren/micro/goal'
+require 'kanren/micro/relations'
+require 'kanren/micro/state'
+require 'kanren/micro/variable'

data/lib/kanren/micro/goal.rb

@@ -0,0 +1,62 @@
+require 'kanren/utils'
+
+module Kanren
+  module Micro
+    class Goal
+      def initialize(&block)
+        @block = block
+      end
+
+      def pursue_in(state)
+        @block.call state
+      end
+
+      def pursue_in_each(states)
+        Enumerator.new do |yielder|
+          results = pursue_in(states.next)
+          results = Utils.interleave(results, pursue_in_each(states))
+
+          results.each do |state|
+            yielder.yield state
+          end
+        end
+      end
+
+      def self.equal(a, b)
+        new do |state|
+          state = state.unify(a, b)
+
+          Enumerator.new do |yielder|
+            yielder.yield state if state
+          end
+        end
+      end
+
+      def self.with_variables(&block)
+        names = block.parameters.map { |type, name| name }
+
+        new do |state|
+          state, variables = state.create_variables(names)
+          goal = block.call(*variables)
+          goal.pursue_in state
+        end
+      end
+
+      def self.either(first_goal, second_goal)
+        new do |state|
+          first_stream = first_goal.pursue_in(state)
+          second_stream = second_goal.pursue_in(state)
+
+          Utils.interleave first_stream, second_stream
+        end
+      end
+
+      def self.both(first_goal, second_goal)
+        new do |state|
+          states = first_goal.pursue_in(state)
+          second_goal.pursue_in_each states
+        end
+      end
+    end
+  end
+end

data/lib/kanren/micro/relations.rb

@@ -0,0 +1,66 @@
+require 'kanren/list'
+require 'kanren/micro/goal'
+require 'kanren/pair'
+require 'kanren/peano'
+
+module Kanren
+  module Micro
+    module Relations
+      module_function
+
+      def append(a, b, c)
+        Goal.either(
+          Goal.both(
+            Goal.equal(a, List::EMPTY),
+            Goal.equal(b, c)
+          ),
+          Goal.with_variables { |first, rest_of_a, rest_of_c|
+            Goal.both(
+              Goal.both(
+                Goal.equal(a, Pair.new(first, rest_of_a)),
+                Goal.equal(c, Pair.new(first, rest_of_c))
+              ),
+              append(rest_of_a, b, rest_of_c)
+            )
+          }
+        )
+      end
+
+      def add(x, y, z)
+        Goal.either(
+          Goal.both(
+            Goal.equal(x, Peano::ZERO),
+            Goal.equal(y, z)
+          ),
+          Goal.with_variables { |smaller_x, smaller_z|
+            Goal.both(
+              Goal.both(
+                Goal.equal(x, Pair.new(Peano::SUCC, smaller_x)),
+                Goal.equal(z, Pair.new(Peano::SUCC, smaller_z))
+              ),
+              add(smaller_x, y, smaller_z)
+            )
+          }
+        )
+      end
+
+      def multiply(x, y, z)
+        Goal.either(
+          Goal.both(
+            Goal.equal(x, Peano::ZERO),
+            Goal.equal(z, Peano::ZERO)
+          ),
+          Goal.with_variables { |smaller_x, smaller_z|
+            Goal.both(
+              Goal.both(
+                Goal.equal(x, Pair.new(Peano::SUCC, smaller_x)),
+                add(smaller_z, y, z)
+              ),
+              multiply(smaller_x, y, smaller_z)
+            )
+          }
+        )
+      end
+    end
+  end
+end

data/lib/kanren/micro/state.rb

@@ -0,0 +1,56 @@
+require 'kanren/micro/variable'
+require 'kanren/pair'
+
+module Kanren
+  module Micro
+    class State
+      def initialize(variables = [], values = {})
+        @variables, @values = variables, values
+      end
+
+      attr_reader :variables, :values
+
+      def create_variables(names)
+        new_variables = names.map { |name| Variable.new(name) }
+        [State.new(variables + new_variables, values), new_variables]
+      end
+
+      def assign_values(new_values)
+        State.new(variables, values.merge(new_values))
+      end
+
+      def value_of(key)
+        if values.has_key?(key)
+          value_of values.fetch(key)
+        elsif key.is_a?(Pair)
+          Pair.new(value_of(key.left), value_of(key.right))
+        else
+          key
+        end
+      end
+
+      def unify(a, b)
+        a, b = value_of(a), value_of(b)
+
+        if a == b
+          self
+        elsif a.is_a?(Variable)
+          assign_values a => b
+        elsif b.is_a?(Variable)
+          assign_values b => a
+        elsif a.is_a?(Pair) && b.is_a?(Pair)
+          state = unify(a.left, b.left)
+          state.unify(a.right, b.right) if state
+        end
+      end
+
+      def results(n)
+        variables.first(n).map { |variable| value_of(variable) }
+      end
+
+      def result
+        results(1).first
+      end
+    end
+  end
+end

data/lib/kanren/micro/variable.rb

@@ -0,0 +1,13 @@
+module Kanren
+  module Micro
+    class Variable
+      def initialize(name)
+        @name = name
+      end
+
+      def inspect
+        @name.to_s
+      end
+    end
+  end
+end

data/lib/kanren/pair.rb

@@ -0,0 +1,7 @@
+module Kanren
+  Pair = Struct.new(:left, :right) do
+    def inspect
+      "(#{left.inspect}, #{right.inspect})"
+    end
+  end
+end

data/lib/kanren/peano.rb

@@ -0,0 +1,33 @@
+require 'kanren/pair'
+
+module Kanren
+  module Peano
+    ZERO, SUCC = 2.times.map { Object.new }
+
+    module_function
+
+    def from_integer(integer)
+      if integer.zero?
+        ZERO
+      else
+        Pair.new(SUCC, from_integer(integer.pred))
+      end
+    end
+
+    def to_integer(peano)
+      if peano == ZERO
+        0
+      else
+        to_integer(peano.right).succ
+      end
+    end
+
+    def to_peano(integer)
+      from_integer integer
+    end
+
+    def from_peano(peano)
+      to_integer peano
+    end
+  end
+end

data/lib/kanren/utils.rb

@@ -0,0 +1,17 @@
+module Kanren
+  module Utils
+    module_function
+
+    def interleave(*enumerators)
+      Enumerator.new do |yielder|
+        until enumerators.empty?
+          loop do
+            enumerator = enumerators.shift
+            yielder.yield enumerator.next
+            enumerators.push enumerator
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kanren/version.rb

@@ -0,0 +1,3 @@
+module Kanren
+  VERSION = '0.0.1'
+end

data/spec/acceptance/relations_on_lists_spec.rb

@@ -0,0 +1,69 @@
+require 'kanren/list'
+require 'kanren/micro/goal'
+require 'kanren/micro/relations'
+require 'kanren/micro/state'
+
+module Kanren
+  module Micro
+    RSpec.describe 'relations on lists' do
+      describe 'equality' do
+        it 'allows two lists to be unified' do
+          goal = Goal.with_variables { |x, y, z| Goal.equal(List.from_array([x, 2, z]), List.from_array([1, y, 3])) }
+          states = goal.pursue_in(State.new)
+
+          state = states.next
+          x, y, z = state.variables
+          expect(state.values).to eq x => 1, y => 2, z => 3
+
+          expect { states.next }.to raise_error StopIteration
+        end
+
+        describe 'append' do
+          it 'appends two lists' do
+            goal =
+              Goal.with_variables { |x|
+                Relations.append(List.from_array(%w(h e)), List.from_array(%w(l l o)), x)
+              }
+            states = goal.pursue_in(State.new)
+
+            results = states.map { |state| List.to_array(state.result) }
+            expect(results).to eq [
+              %w(h e l l o)
+            ]
+          end
+
+          it 'finds the prefix which makes one list equal to another' do
+            goal =
+              Goal.with_variables { |x|
+                Relations.append(x, List.from_array(%w(l o)), List.from_array(%w(h e l l o)))
+              }
+            states = goal.pursue_in(State.new)
+
+            results = states.map { |state| List.to_array(state.result) }
+            expect(results).to eq [
+              %w(h e l)
+            ]
+          end
+
+          it 'finds all pairs of lists which are equal to another when appended' do
+            goal =
+              Goal.with_variables { |x, y|
+                Relations.append(x, y, List.from_array(%w(h e l l o)))
+              }
+            states = goal.pursue_in(State.new)
+
+            results = states.map { |state| state.results(2).map(&List.method(:to_array)) }
+            expect(results).to eq [
+              [%w(), %w(h e l l o)],
+              [%w(h), %w(e l l o)],
+              [%w(h e), %w(l l o)],
+              [%w(h e l), %w(l o)],
+              [%w(h e l l), %w(o)],
+              [%w(h e l l o), %w()]
+            ]
+          end
+        end
+      end
+    end
+  end
+end

data/spec/acceptance/relations_on_numbers_spec.rb

@@ -0,0 +1,85 @@
+require 'kanren/micro/goal'
+require 'kanren/micro/relations'
+require 'kanren/micro/state'
+require 'kanren/peano'
+
+module Kanren
+  module Micro
+    module Data
+      RSpec.describe 'relations on numbers' do
+        describe 'addition' do
+          it 'adds two numbers' do
+            goal = Goal.with_variables { |x|
+              Relations.add(Peano.from_integer(5), Peano.from_integer(3), x)
+            }
+            states = goal.pursue_in(State.new)
+
+            results = states.map { |state| Peano.to_integer(state.result) }
+            expect(results).to eq [8]
+          end
+
+          it 'subtracts two numbers' do
+            goal = Goal.with_variables { |x|
+              Relations.add(x, Peano.from_integer(3), Peano.from_integer(8))
+            }
+            states = goal.pursue_in(State.new)
+
+            results = states.map { |state| Peano.to_integer(state.result) }
+            expect(results).to eq [5]
+          end
+
+          it 'finds all pairs of numbers which are equal to another when added' do
+            goal = Goal.with_variables { |x, y|
+              Relations.add(x, y, Peano.from_integer(8))
+            }
+            states = goal.pursue_in(State.new)
+
+            results = states.map { |state| state.results(2).map(&Peano.method(:to_integer)) }
+            expect(results).to eq [
+              [0, 8],
+              [1, 7],
+              [2, 6],
+              [3, 5],
+              [4, 4],
+              [5, 3],
+              [6, 2],
+              [7, 1],
+              [8, 0]
+            ]
+          end
+        end
+
+        describe 'multiplication' do
+          it 'mutiplies two numbers' do
+            goal = Goal.with_variables { |x|
+              Relations.multiply(Peano.from_integer(3), Peano.from_integer(8), x)
+            }
+            states = goal.pursue_in(State.new)
+
+            results = states.take(1).map { |state| Peano.to_integer(state.result) }
+            expect(results).to eq [24]
+          end
+
+          it 'finds all pairs of numbers which are equal to another when multiplied' do
+            goal = Goal.with_variables { |x, y|
+              Relations.multiply(x, y, Peano.from_integer(24))
+            }
+            states = goal.pursue_in(State.new)
+
+            results = states.take(8).map { |state| state.results(2).map(&Peano.method(:to_integer)) }
+            expect(results).to eq [
+              [1, 24],
+              [2, 12],
+              [3, 8],
+              [4, 6],
+              [6, 4],
+              [8, 3],
+              [12, 2],
+              [24, 1]
+            ]
+          end
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+RSpec.configure do |config|
+  config.disable_monkey_patching!
+end

data/spec/unit/goal_spec.rb

@@ -0,0 +1,113 @@
+require 'kanren/micro/goal'
+require 'kanren/micro/state'
+
+module Kanren
+  module Micro
+    RSpec.describe Goal do
+      describe '.new' do
+        it 'doesn’t immediately yield to the block' do
+          expect { |block| Goal.new(&block) }.not_to yield_control
+        end
+      end
+
+      describe '#pursue_in' do
+        let(:state) { double }
+
+        it 'yields the state to the block' do
+          expect { |block| Goal.new(&block).pursue_in(state) }.to yield_with_args(state)
+        end
+      end
+
+      describe '#pursue_in_each' do
+        let(:a) { double }
+        let(:b) { double }
+        let(:c) { double }
+        let(:a_results) { 3.times.map { double }.to_enum }
+        let(:b_results) { 4.times.map { double }.to_enum }
+        let(:c_results) { 5.times.map { double }.to_enum }
+        let(:goal) { Goal.new }
+
+        it 'pursues the goal in each state and interleaves the results' do
+          allow(goal).to receive(:pursue_in).with(a).and_return a_results
+          allow(goal).to receive(:pursue_in).with(b).and_return b_results
+          allow(goal).to receive(:pursue_in).with(c).and_return c_results
+          results = goal.pursue_in_each([a, b, c].to_enum)
+          expect(results).to contain_exactly *a_results, *b_results, *c_results
+        end
+      end
+
+      describe '.equal' do
+        it 'unifies its arguments' do
+          state, (x, y, z) = State.new.create_variables [:x, :y, :z]
+          goal = Goal.equal(x, 5)
+          states = goal.pursue_in(state)
+          state = states.next
+          expect(state.values).to eq x => 5
+          expect { states.next }.to raise_error StopIteration
+        end
+      end
+
+      describe '.with_variables' do
+        it 'introduces local variables' do
+          goal = Goal.with_variables { |x| Goal.equal x, 5 }
+          states = goal.pursue_in(State.new)
+          state = states.next
+          x = state.variables.first
+          expect(state.values).to eq x => 5
+          expect { states.next }.to raise_error StopIteration
+        end
+      end
+
+      describe '.either' do
+        it 'satisfies either subgoal' do
+          goal = Goal.with_variables { |x| Goal.either Goal.equal(x, 5), Goal.equal(x, 6) }
+          states = goal.pursue_in(State.new)
+
+          state = states.next
+          x = state.variables.first
+          expect(state.values).to eq x => 5
+
+          state = states.next
+          x = state.variables.first
+          expect(state.values).to eq x => 6
+
+          expect { states.next }.to raise_error StopIteration
+        end
+      end
+
+      describe '.both' do
+        it 'satisfies both simple subgoals' do
+          goal = Goal.with_variables { |x, y| Goal.both(Goal.equal(x, 5), Goal.equal(y, 7)) }
+          states = goal.pursue_in(State.new)
+
+          state = states.next
+          x, y = state.variables
+          expect(state.values).to eq x => 5, y => 7
+
+          expect { states.next }.to raise_error StopIteration
+        end
+
+        it 'satisfies compound subgoals' do
+          goal = Goal.both Goal.with_variables { |a| Goal.equal(a, 7) }, Goal.with_variables { |b| Goal.either(Goal.equal(b, 5), Goal.equal(b, 6)) }
+          states = goal.pursue_in(State.new)
+
+          state = states.next
+          a, b = state.variables
+          expect(state.values).to eq a => 7, b => 5
+
+          state = states.next
+          a, b = state.variables
+          expect(state.values).to eq a => 7, b => 6
+
+          expect { states.next }.to raise_error StopIteration
+        end
+
+        it 'doesn’t satisfy contradictory goals' do
+          goal = Goal.with_variables { |x| Goal.both(Goal.equal(1, x), Goal.equal(x, 2)) }
+          states = goal.pursue_in(State.new)
+          expect { states.next }.to raise_error StopIteration
+        end
+      end
+    end
+  end
+end

data/spec/unit/list_spec.rb

@@ -0,0 +1,40 @@
+require 'kanren/list'
+require 'kanren/pair'
+
+module Kanren
+  RSpec.describe List do
+    let(:array) { %i(a b c) }
+    let(:list) { Pair.new(:a, Pair.new(:b, Pair.new(:c, List::EMPTY))) }
+
+    describe '#from_array' do
+      it 'turns an array into a list' do
+        expect(List.from_array(array)).to eq list
+      end
+    end
+
+    describe '#to_array' do
+      it 'turns a list into an array' do
+        expect(List.to_array(list)).to eq array
+      end
+    end
+
+    describe 'backwards compatibility' do
+      let(:argument) { double }
+      let(:result) { double }
+
+      describe '#to_list' do
+        it 'is an alias for #from_array' do
+          expect(List).to receive(:from_array).with(argument).and_return(result)
+          expect(List.to_list(argument)).to eq result
+        end
+      end
+
+      describe '#from_list' do
+        it 'is an alias for #to_array' do
+          expect(List).to receive(:to_array).with(argument).and_return(result)
+          expect(List.from_list(argument)).to eq result
+        end
+      end
+    end
+  end
+end

data/spec/unit/pair_spec.rb

@@ -0,0 +1,33 @@
+require 'kanren/pair'
+
+module Kanren
+  RSpec.describe Pair do
+    let(:left) { double }
+    let(:right) { double }
+
+    subject(:pair) { Pair.new(left, right) }
+
+    describe '#inspect' do
+      before(:example) do
+        allow(left).to receive(:inspect).and_return 'l'
+        allow(right).to receive(:inspect).and_return 'r'
+      end
+
+      it 'shows the left and right elements between parentheses' do
+        expect(pair.inspect).to eq '(l, r)'
+      end
+    end
+
+    describe '#left' do
+      it 'returns the left element' do
+        expect(pair.left).to eq left
+      end
+    end
+
+    describe '#right' do
+      it 'returns the right element' do
+        expect(pair.right).to eq right
+      end
+    end
+  end
+end

data/spec/unit/peano_spec.rb

@@ -0,0 +1,40 @@
+require 'kanren/pair'
+require 'kanren/peano'
+
+module Kanren
+  RSpec.describe Peano do
+    let(:integer) { 3 }
+    let(:peano) { Pair.new(Peano::SUCC, Pair.new(Peano::SUCC, Pair.new(Peano::SUCC, Peano::ZERO))) }
+
+    describe '#from_integer' do
+      it 'turns an integer into a Peano number' do
+        expect(Peano.from_integer(integer)).to eq peano
+      end
+    end
+
+    describe '#to_integer' do
+      it 'turns a Peano number into an integer' do
+        expect(Peano.to_integer(peano)).to eq integer
+      end
+    end
+
+    describe 'backwards compatibility' do
+      let(:argument) { double }
+      let(:result) { double }
+
+      describe '#to_peano' do
+        it 'is an alias for #from_integer' do
+          expect(Peano).to receive(:from_integer).with(argument).and_return(result)
+          expect(Peano.to_peano(argument)).to eq result
+        end
+      end
+
+      describe '#from_peano' do
+        it 'is an alias for #to_integer' do
+          expect(Peano).to receive(:to_integer).with(argument).and_return(result)
+          expect(Peano.from_peano(argument)).to eq result
+        end
+      end
+    end
+  end
+end

data/spec/unit/state_spec.rb

@@ -0,0 +1,122 @@
+require 'kanren/micro/state'
+require 'kanren/pair'
+
+module Kanren
+  module Micro
+    RSpec.describe State do
+      before(:example) do
+        @state = State.new
+      end
+
+      context 'when empty' do
+        describe '#variables' do
+          it 'returns an empty variable array' do
+            expect(@state.variables).to be_empty
+          end
+        end
+
+        describe '#values' do
+          it 'returns an empty value hash' do
+            expect(@state.values).to be_empty
+          end
+        end
+      end
+
+      context 'with declared variables' do
+        before(:example) do
+          @state, (@x, @y, @z) = @state.create_variables [:x, :y, :z]
+        end
+
+        describe '#variables' do
+          it 'returns an array of the declared variables' do
+            expect(@state.variables).to eq [@x, @y, @z]
+          end
+        end
+
+        context 'with assigned values' do
+          before(:example) do
+            @state = @state.assign_values @x => @y, @y => @z, @z => 5
+          end
+
+          describe '#values' do
+            it 'returns a hash of the assigned values' do
+              expect(@state.values).to eq @x => @y, @y => @z, @z => 5
+            end
+          end
+
+          describe '#value_of' do
+            it 'looks up the final value of an assigned variable' do
+              expect(@state.value_of(@x)).to eq 5
+            end
+
+            it 'doesn’t affect a non-variable value' do
+              expect(@state.value_of(7)).to eq 7
+            end
+
+            it 'doesn’t affect an unassigned variable' do
+              @state, (a, b, c) = @state.create_variables [:a, :b, :c]
+              expect(@state.value_of(a)).to eq a
+            end
+          end
+        end
+      end
+
+      describe '#unify' do
+        before(:example) do
+          @state, (@x, @y) = @state.create_variables [:x, :y]
+        end
+
+        it 'changes nothing if the values are already equal' do
+          @state = @state.unify(@x, @x)
+          expect(@state.values).to be_empty
+        end
+
+        it 'adds an assignment to the state if the first value is an unassigned variable' do
+          @state = @state.unify(@x, @y)
+          expect(@state.values).to eq @x => @y
+        end
+
+        it 'adds an assignment to the state if the second value is an unassigned variable' do
+          @state = @state.unify(@x, @y).unify(@x, 5)
+          expect(@state.values).to eq @x => @y, @y => 5
+        end
+
+        it 'fails if the values cannot be made equal' do
+          @state = @state.unify(@x, @y).unify(@x, 5).unify(@y, 6)
+          expect(@state).to be_nil
+        end
+      end
+
+      context 'with pairs' do
+        describe 'unification' do
+          before(:example) do
+            @state, (@x, @y) = @state.create_variables [:x, :y]
+          end
+
+          it 'successfully unifies values within pairs' do
+            @state = @state.unify(Pair.new(3, @x), Pair.new(@y, Pair.new(5, @y)))
+            expect(@state.values).to eq @x => Pair.new(5, 3), @y => 3
+          end
+        end
+      end
+
+      describe 'extracting results' do
+        let(:x_value) { double }
+        let(:y_value) { double }
+
+        before(:example) do
+          @state, (x, y) = @state.create_variables [:x, :y]
+          @state = @state.assign_values x => x_value, y => y_value
+        end
+
+        it 'exposes the values of variables' do
+          expect(@state.results(2)).to eq [x_value, y_value]
+        end
+
+        it 'exposes the value of the outermost variable' do
+          expect(@state.result).to eq x_value
+        end
+      end
+    end
+  end
+end

data/spec/unit/utils_spec.rb

@@ -0,0 +1,25 @@
+require 'kanren/utils'
+
+module Kanren
+  RSpec.describe Utils do
+    describe '#interleave' do
+      context 'when the streams are finite' do
+        let(:letters) { 'a'.upto('z') }
+        let(:numbers) { 1.upto(10) }
+
+        it 'interleaves the streams' do
+          expect(Utils.interleave(letters, numbers).entries).to eq ['a', 1, 'b', 2, 'c', 3, 'd', 4, 'e', 5, 'f', 6, 'g', 7, 'h', 8, 'i', 9, 'j', 10, 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z']
+        end
+      end
+
+      context 'when the streams are infinite' do
+        let(:letters) { ['a', 'b', 'c'].cycle }
+        let(:numbers) { 1.upto(Float::INFINITY) }
+
+        it 'interleaves the streams' do
+          expect(Utils.interleave(letters, numbers).take(20)).to eq ['a', 1, 'b', 2, 'c', 3, 'a', 4, 'b', 5, 'c', 6, 'a', 7, 'b', 8, 'c', 9, 'a', 10]
+        end
+      end
+    end
+  end
+end

data/spec/unit/variable_spec.rb

@@ -0,0 +1,32 @@
+require 'kanren/micro/variable'
+
+module Kanren
+  module Micro
+    RSpec.describe Variable do
+      let(:name) { :x }
+      let(:different_name) { :y }
+
+      subject(:variable) { Variable.new(name) }
+
+      describe '#inspect' do
+        it 'returns the variable’s name' do
+          expect(subject.inspect).to eq name.to_s
+        end
+      end
+
+      describe 'equality' do
+        it 'is equal to itself' do
+          expect(variable).to eq variable
+        end
+
+        it 'is not equal to a variable with a different name' do
+          expect(variable).not_to eq Variable.new(different_name)
+        end
+
+        it 'is not equal to a different variable with the same name' do
+          expect(variable).not_to eq Variable.new(name)
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: kanren
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Tom Stuart
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-08-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.3.0
+description: 
+email: tom@codon.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- LICENSE
+- README.md
+- kanren.gemspec
+- lib/kanren.rb
+- lib/kanren/list.rb
+- lib/kanren/micro.rb
+- lib/kanren/micro/goal.rb
+- lib/kanren/micro/relations.rb
+- lib/kanren/micro/state.rb
+- lib/kanren/micro/variable.rb
+- lib/kanren/pair.rb
+- lib/kanren/peano.rb
+- lib/kanren/utils.rb
+- lib/kanren/version.rb
+- spec/acceptance/relations_on_lists_spec.rb
+- spec/acceptance/relations_on_numbers_spec.rb
+- spec/spec_helper.rb
+- spec/unit/goal_spec.rb
+- spec/unit/list_spec.rb
+- spec/unit/pair_spec.rb
+- spec/unit/peano_spec.rb
+- spec/unit/state_spec.rb
+- spec/unit/utils_spec.rb
+- spec/unit/variable_spec.rb
+homepage: https://github.com/tomstuart/kanren
+licenses:
+- CC0-1.0
+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.4.5
+signing_key: 
+specification_version: 4
+summary: An example Ruby implementation of μKanren.
+test_files:
+- spec/acceptance/relations_on_lists_spec.rb
+- spec/acceptance/relations_on_numbers_spec.rb
+- spec/spec_helper.rb
+- spec/unit/goal_spec.rb
+- spec/unit/list_spec.rb
+- spec/unit/pair_spec.rb
+- spec/unit/peano_spec.rb
+- spec/unit/state_spec.rb
+- spec/unit/utils_spec.rb
+- spec/unit/variable_spec.rb