doku 1.0.0

data/lib/doku/solver.rb

@@ -0,0 +1,103 @@
+require 'backports' unless defined?(require_relative) and defined?(Enumerator)
+require_relative 'dancing_links'
+
+module Doku
+  # This module is included into the {Puzzle} class to provide methods
+  # for solving the puzzles using the {DancingLinks} algorithm.
+  module SolvableWithDancingLinks
+    # @return (Puzzle)
+    # Returns the first solution found by the Dancing Links algorithm,
+    # or nil if there is no solution.
+    def solve
+      each_solution { |s| return s }
+      return nil
+    end
+
+    # An enumerator for all the solutions to the puzzle.
+    # @return (Enumerable)
+    def solutions
+      Enumerator.new do |y|
+        each_solution do |solution|
+          y << solution
+        end
+      end
+    end
+
+    # This method lets you iterate over each solution.
+    # Each solution is a puzzle object of the same class
+    # such that solution.solution_for?(puzzle) is true.
+    #
+    # @yield [solution]
+    def each_solution
+      to_link_matrix.each_exact_cover do |exact_cover|
+        yield exact_cover_to_solution exact_cover
+      end
+    end
+
+    # Returns a {DancingLinks::LinkMatrix} that represents this puzzle.
+    # Every row is a {SquareAndGlyph} object representing a choice to
+    # assign a certain glyph to a certain square.
+    # Every column is a {GroupAndGlyph} object representing the
+    # requirements that needs to be satisfied (every group must have
+    # exactly one of each glyph assigned to a square in the group).
+    # @return (DancingLinks::LinkMatrix)
+    def to_link_matrix
+      # Create the link matrix.  This is a generic matrix
+      # that does not take in to account square.given_glyph.
+      sm = DancingLinks::LinkMatrix.from_sets sets_for_exact_cover_problem
+      
+      # Take into account square.given_glyph by covering certain
+      # rows (removing the row and all columns it touches).
+      each do |square, glyph|
+        sm.remove_row SquareAndGlyph.new(square,glyph)
+      end
+
+      sm
+    end
+
+    # Converts an exact cover (an array of {SquareAndGlyph} objects) to a
+    # solution of the puzzle.
+    # @return (Puzzle)
+    def exact_cover_to_solution(exact_cover)
+      solution = dup
+      exact_cover.each do |sg|
+        solution[sg.square] = sg.glyph
+      end
+
+      solution
+    end
+
+    private
+
+    def sets_for_exact_cover_problem
+      sets = {}
+      squares.each do |square|
+        groups_with_square = groups.select { |g| g.include? square }
+        
+        glyphs.each do |glyph|
+          sets[SquareAndGlyph.new(square, glyph)] = [square] +
+            groups_with_square.collect do |group|
+              GroupAndGlyph.new group, glyph
+            end
+        end
+      end
+
+      sets
+    end
+    
+    # This is a simple class that just represents the choice of a puzzle's
+    # square and a puzzle's glyph.  These are identified with rows in
+    # the {DancingLinks::LinkMatrix} when solving puzzles, and there they
+    # represent the choice to assign a particula glyph to a particular square.
+    class SquareAndGlyph < Struct.new(:square, :glyph)
+    end
+    
+    # This is a simple class that just represents the choice of a puzzle's
+    # group of squares and a glyph.  These are identifies with columns in
+    # the {DancingLinks::LinkMatrix} when solving puzzles, and they
+    # represent a requirement that must be satisfied; every group must
+    # has one of every glyph assigned to a square in it.
+    class GroupAndGlyph < Struct.new(:group, :glyph)
+    end
+  end
+end

data/lib/doku/sudoku.rb

@@ -0,0 +1,42 @@
+require 'backports' unless defined?(require_relative)
+require_relative 'puzzle'
+require_relative 'grid'
+
+module Doku
+  # This class represents {http://en.wikipedia.org/wiki/Sudoku Sudoku}.
+  # Each instance of this class represents a particular arrangement of
+  # numbers written in the boxes.
+  class Sudoku < Puzzle
+    include PuzzleOnGrid
+    extend PuzzleOnGrid::ClassMethods # improves generated docs
+
+    has_glyphs (1..9).to_a
+    has_glyph_chars glyphs.collect &:to_s
+    
+    has_template <<END
+...|...|...
+...|...|...
+...|...|...
+---+---+---
+...|...|...
+...|...|...
+...|...|...
+---+---+---
+...|...|...
+...|...|...
+...|...|...
+END
+    
+    0.upto(8) do |n|
+      define_group row(n)
+      define_group column(n)
+    end
+    
+    0.step(6,3).each do |x|
+      0.step(6,3).each do |y|
+        define_group square_group(x, y)
+      end
+    end
+  end
+end
+

data/spec/dancing_links_spec.rb

@@ -0,0 +1,212 @@
+require 'backports' unless defined? require_relative
+require_relative 'spec_helper'
+
+describe Doku::DancingLinks::LinkMatrix do
+  context "when created from scratch" do
+    before do
+      @m = Doku::DancingLinks::LinkMatrix.new
+    end
+
+    it "has no columns (i.e. it is empty)" do
+      @m.columns.to_a.size.should == 0
+      @m.should be_empty
+    end
+  end
+
+  describe ".from_sets" do
+    it "can create a matrix from a set of sets" do
+      @m = Doku::DancingLinks::LinkMatrix.from_sets(
+        Set.new([ Set.new([1, 2]), Set.new([2, 3]) ]) )
+    end
+
+    it "filters out duplicate column ids" do
+      @m = Doku::DancingLinks::LinkMatrix.from_sets [ [1,2,2] ]
+      @m.row([1,2,2]).nodes.to_a.size.should == 2
+    end
+
+  end
+
+  describe "find_exact_cover" do
+    it "can find one exact cover" do
+      m = Doku::DancingLinks::LinkMatrix.from_sets [[1,2], [2,3], [3,4]]
+      m.find_exact_cover.sort.should == [[1,2], [3,4]]
+    end
+
+    it "returns nil if there are no exact covers" do
+      m = Doku::DancingLinks::LinkMatrix.from_sets [[1,2], [2,3]]
+      m.find_exact_cover.should == nil
+    end
+
+    it "it finds the trivial exact cover for the trivial matrix" do
+      Doku::DancingLinks::LinkMatrix.new.find_exact_cover.should == []
+    end
+  end
+
+  describe "exact_covers" do
+    it "returns an Enumerable" do
+      Doku::DancingLinks::LinkMatrix.new.exact_covers.should be_a Enumerable
+    end
+
+    it "can find all exact covers" do
+      m = Doku::DancingLinks::LinkMatrix.from_sets [[1,2], [2,3], [3,4], [4,1]]
+      m.exact_covers.collect{|ec| ec.sort}.sort.should ==
+        [ [ [1,2], [3,4] ],
+          [ [2,3], [4,1] ] ]
+    end
+
+    it "it finds the trivial exact cover for the trivial matrix" do
+      Doku::DancingLinks::LinkMatrix.new.exact_covers.to_a.should == [[]]
+    end
+  end
+
+  describe "each_exact_cover" do
+    it "does not yield if there are no exact covers" do
+      m = Doku::DancingLinks::LinkMatrix.from_sets [[1,2], [2,3]]
+      m.each_exact_cover { |ec| true.should == false }
+    end
+
+    it "finds the trivial exact cover for the trivial matrix" do
+      already_yielded = false
+      Doku::DancingLinks::LinkMatrix.new.each_exact_cover do |ec|
+        ec.should == []
+        already_yielded.should == false
+        already_yielded = true
+      end
+    end
+  end
+
+  describe "find_exact_cover_recursive" do
+    it "find the trivial cover for the trivial matrix" do
+      Doku::DancingLinks::LinkMatrix.new.find_exact_cover_recursive.should == []
+    end
+
+    it "works even if final(k) < max(k)" do
+      # This makes sure we call collect on o[0...k] instead of on o.
+      m = Doku::DancingLinks::LinkMatrix.from_sets [
+          [1,2,     ],
+          [  2,3,   ],
+          [    3,4, ],
+          [      4,5],
+          [1,2,3,4,5] ]
+      m.find_exact_cover_recursive.sort.should == [[1, 2, 3, 4, 5]]
+    end
+  end
+
+  shared_examples_for "figure 3 from Knuth" do
+    it "has 7 columns" do
+      @m.columns.to_a.size.should == 7
+    end
+
+    it "has the expected columns" do
+      @m.columns.collect(&:id).should == @universe
+    end
+
+    it "has the expected structure" do
+      # This test is not exhaustive.
+      columns = @m.columns.to_a
+      columns[0].down.should_not == columns[0]
+      columns[0].up.should_not == columns[0]
+      columns[0].nodes.to_a.size.should == 2
+      columns[0].up.up.should == columns[0].down
+      columns[0].up.should == columns[0].down.down
+
+      columns[0].down.right.up.should == columns[3]
+      columns[3].down.left.up.should == columns[0]
+      columns[0].down.down.right.up.up.should == columns[3]
+      columns[0].down.down.right.right.right.down.down.should == columns[3]
+      columns[2].up.right.down.should == columns[5]
+
+      columns[6].down.down.down.left.up.left.down.left.down.down.should == columns[1]
+    end
+
+    it "every row has a reference to the column" do
+      @m.columns.each do |column|
+        column.nodes.each do |node|
+          node.column.should == column
+        end
+      end
+    end
+  end
+
+  context "given figure 3 from Knuth" do
+    before do
+      @universe = [1,2,3,4,5,6,7]
+      @subsets = [[    3,  5,6  ],
+                  [1,    4,    7],
+                  [  2,3,    6  ],
+                  [1,    4      ],
+                  [  2,        7],
+          Set.new([      4,5,  7]),
+                 ]
+      @m = Doku::DancingLinks::LinkMatrix.from_sets @subsets, @universe
+    end
+
+    it_should_behave_like "figure 3 from Knuth"
+
+    it "can find an exact cover" do
+      result = @m.find_exact_cover
+      result.collect(&:sort).sort.should == [[1, 4], [2, 7], [3, 5, 6]]
+    end
+
+    # TODO: test this using a matrix that has multiple exact covers
+    it "can find all exact covers" do
+      @m.exact_covers.to_a.sort.should == [[[1, 4], [3, 5, 6], [2,7]]]
+    end
+
+    context "after running each_exact_cover" do
+      before do
+        # If we let each_exact_cover run all the way through, it restores
+        # the matrix to its original state.
+        @m.each_exact_cover { }
+      end
+
+      it_should_behave_like "figure 3 from Knuth"
+    end
+
+    context "with one row covered" do
+      before do
+        @m.column(@universe[3]).cover
+      end
+
+      it "has only 6 columns" do
+        @m.columns.to_a.size.should == 6
+      end
+
+      # @m will now look like (minus means a covered element)
+      # 0 0 1 - 1 1 0
+      # - - - - - - -
+      # 0 1 1 - 0 1 0
+      # - - - - - - -
+      # 0 1 0 - 0 0 1
+      # - - - - - - -
+      it "has the expected column sizes" do
+        @universe.collect { |e| @m.column(e).size }.should == [0, 2, 2, 3, 1, 2, 1]
+        @m.columns.collect { |c| c.size }.should == [0, 2, 2, 1, 2, 1]
+      end
+
+      it "has the expected structure" do
+        columns = @m.columns.to_a
+
+        # Column 0 is empty.
+        columns[0].down.should == columns[0]
+        columns[0].up.should == columns[0]
+        columns[0].nodes.to_a.should be_empty
+
+        columns[1].down.right.up.up.should == columns[2]
+        columns[2].down.right.up.should == columns[3]
+        columns[3].up.right.down.down.should == columns[4]
+        columns[5].down.right.down.should == columns[1]
+
+        columns[5].up.left.up.right.up.right.right.down.down.should == columns[4]
+      end
+
+      context "and then uncovered" do
+        before do
+          @m.column(@universe[3]).uncover          
+        end
+
+        it_should_behave_like "figure 3 from Knuth"
+      end
+    end
+  end
+end

data/spec/hexadoku_spec.rb

@@ -0,0 +1,71 @@
+require 'backports' unless defined? require_relative
+require_relative 'spec_helper'
+
+describe Doku::Hexadoku do
+  it 'has the upper-case glyph characters' do
+    Doku::Hexadoku.glyph_chars.should == %w{0 1 2 3 4 5 6 7 8 9 A B C D E F}
+  end
+
+  it 'rejects invalid glyphs in glyph_char' do
+    lambda { Doku::Hexadoku.glyph_char(19) }.should raise_error ArgumentError, "Invalid glyph 19."
+  end
+
+  it 'rejects invalid characters in glyph_parse' do
+    lambda { Doku::Hexadoku.glyph_parse('H') }.should raise_error ArgumentError, "Invalid character 'H'."
+  end
+
+  it 'accepts both cases in glyph_parse' do
+    Doku::Hexadoku.glyph_parse('d').should == 0xD
+    Doku::Hexadoku.glyph_parse('D').should == 0xD
+  end
+
+  it 'rejects invalid characters in the constructor' do
+    grid_string = <<END
+ABCD|....|....|....
+....|abcd|....|....
+X...|....|....|....
+....|....|....|....
+----+----+----+----
+....|....|....|....
+....|....|....|....
+....|....|....|....
+....|....|....|....
+----+----+----+----
+....|....|....|....
+....|....|....|....
+....|....|....|....
+....|....|....|....
+----+----+----+----
+....|....|....|....
+....|....|....|....
+....|....|....|....
+....|....|....|....
+END
+    lambda { Doku::Hexadoku.new(grid_string) }.should raise_error ArgumentError, "Line 2, character 0: Invalid character 'X'.  Expected period (.) or glyph (0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F)."
+  end
+
+  it 'accepts lower-case or upper-case in the consturctor' do
+    grid_string = <<END.strip
+ABCD|....|....|....
+....|abcd|....|....
+....|....|....|....
+....|....|....|....
+----+----+----+----
+....|....|....|....
+....|....|....|....
+....|....|....|....
+....|....|....|....
+----+----+----+----
+....|....|....|....
+....|....|....|....
+....|....|....|....
+....|....|....|....
+----+----+----+----
+....|....|....|....
+....|....|....|....
+....|....|....|....
+....|....|....|....
+END
+    Doku::Hexadoku.new(grid_string).to_s.should == grid_string.upcase
+  end
+end

data/spec/hexamurai_spec.rb

@@ -0,0 +1,38 @@
+require 'backports' unless defined? require_relative
+require_relative 'spec_helper'
+
+describe Doku::Hexamurai do
+  it 'has 768 squares' do
+    Doku::Hexamurai.squares.size.should == 768
+  end
+
+  it 'has 16 squares in the first row' do
+    first_row = Doku::Hexamurai.squares_matching :y => 0
+    first_row.size.should == 16
+  end
+
+  it 'has 16 squares in the first column of the top hexadoku' do
+    column = Doku::Hexamurai.squares_matching :x => 8, :y => (0..15)
+    column.size.should == 16
+  end
+
+  it 'has the right number of groups' do
+    # A hexadoku has 3*16 groups (16 columns, 16 rows, 16 boxes)
+    # There are 5 hexadokus.
+    # The reckoning above counted the 16 rows and 16 columns of the 
+    # center hexadoku twice (-32), and counted the 16 boxes of the
+    # center hexaodoku thrice (-32), so subtract 64.
+    # There are 2*16 inferred groups (16 columns, 16 rows).
+    Doku::Hexamurai.groups.size.should == (5*3*16 - 64 + 2*16)
+  end
+
+  it 'has valid line and char numbers' do
+    lines = Doku::Hexamurai.template.split("\n")
+    Doku::Hexamurai.squares.each do |square|
+      line_number, char_number = Doku::Hexamurai.coordinates_in_grid_string(square)
+      line = lines[line_number]
+      line.should_not be_nil
+      line.size.should > char_number
+    end
+  end
+end