doku 1.0.1 → 1.1.0

data/README.rdoc

@@ -43,23 +43,23 @@ This gem is designed to solve Sudoku-like puzzles.  For the purposes of this gem
 
 For example, in Sudoku, the glyphs are the numbers 0 through 9, the squares are the squares of a 9x9 grid, and the groups consist of nine rows, nine columns, and nine 3x3 squares.
 
-Every Sudoku-like puzzle can be reduced to an {exact cover problem}[http://en.wikipedia.org/wiki/Exact_cover].  From there is can be efficiently solved with the {Dancing Links}[http://arxiv.org/abs/cs/0011047] algorithm discovered by Donald Knuth.  That is the main purpose of this gem.
+Every Sudoku-like puzzle can be reduced to an {exact cover problem}[http://en.wikipedia.org/wiki/Exact_cover].  From there it can be efficiently solved with the {Dancing Links}[http://arxiv.org/abs/cs/0011047] algorithm discovered by Donald Knuth.  That is the main purpose of this gem.
 
 == Classes and Modules Overview
 
-The Doku::Puzzle class is an abstract class for working with Sudoku-like puzzles.  It implements the concepts of groups, glyphs and squares.  Each instance of this class represents a particular assignment of glyphs to squares; at its core, an instance is just a hash where the keys are squares and values are glyphs.  This class provides <code>[]</code> and <code>[]=</code> methods for reading and modifying instances of the puzzle.  It provides equality comparison and solution checking.
+The <b>Doku::DancingLinks</b> module contains several classes that comprise a general-purpose implementation of the Dancing Links algorithm.  This module is included in the Doku gem for convenience, but it is not specifically for solving Sudoku-like puzzles; it can be applied to any exact cover problem.
 
-The Puzzle class includes the Doku::SolvableWithDancingLinks module which provides methods for solving puzzles using the Dancing Links algorithm.  The solutions returned are instances of Puzzle.
+The <b>Doku::Puzzle</b> class is an abstract class for working with Sudoku-like puzzles.  It implements the concepts of groups, glyphs and squares.  Each instance of this class represents a particular assignment of glyphs to squares; at its core, an instance is just a hash where the keys are squares and the values are glyphs.  This class provides <code>[]</code> and <code>[]=</code> methods for reading and modifying instances of the puzzle, and it makes <code>dup</code> and <code>clone</code> work correctly.  This class provides equality comparison and solution checking.
 
-The Doku::SquareOnGrid module provides methods used for Sudoku-like puzzles that can be drawn on a 2D grid.  It implements the string representations of the puzzle by providing an <code>initialize</code> method that creates puzzles from strings and a <code>to_s</code> method that creates strings from puzzles.  It provides <code>get</code> and <code>set</code> methods for modifying suqares of the puzzle by their coordinates.
+The Puzzle class includes the <b>Doku::SolvableWithDancingLinks</b> module which provides methods for solving puzzles using Doku::DancingLinks.  The solutions returned are instances of Puzzle.  This module is the glue that connects Doku::Puzzle to Doku::DancingLinks.
 
-The classes Doku::Sudoku, Doku::Hexadoku, and Doku::Hexamurai all inherit from Doku::Puzzle and include Doku::SquareOnGrid.  Because of the framework set up by that class and that module, the definitions of these classes are short and the methods provided by each of them are rich and consistent with eachother.
+The <b>Doku::SquareOnGrid</b> module is useful for any Sudoku-like puzzle that can be drawn on a 2D grid.  It implements the string representations of the puzzle by providing an <code>initialize</code> method that creates puzzles from strings and a <code>to_s</code> method that creates strings from puzzles.  It also provides convenient <code>get</code> and <code>set</code> methods for reading and modifying instances of the puzzle using grid coordinates.
 
-The Doku::DancingLinks module contains several class that comprise a general-purpose implementation of the Dancing Links algorithm.  This module is included in the Doku gem for convenience, but it is not specifically for solving Sudoku-like puzzles; it can be applied to any exact cover problem.
+The classes <b>Doku::Sudoku</b>, <b>Doku::Hexadoku</b>, and <b>Doku::Hexamurai</b> all inherit from Doku::Puzzle and include Doku::SquareOnGrid.  As a user of the gem, these are the classes you will probably interact with most of the time.  Because of the framework set up by Doku::Puzzle and include Doku::SquareOnGrid, the definitions of these classes are short and the methods provided by each of them are rich and consistent with eachother.
 
 == Detailed Documentation
 
-For detailed documentation of every class, module, and method, see the "Class List" link above.
+For detailed documentation of every class, module, and method go to the {rubydoc.info page}[http://rubydoc.info/github/DavidEGrayson/doku/master/frames] and look for the Class List.
 
 == Contributing
 
@@ -74,6 +74,8 @@ There are many directions this gem could go in.  The direction will be determine
 * More types of puzzles that are solvable (e.g. puzzles that have groups with fewer squares than the number of glyphs).
 * Improve this page.  Ideally the method names should be linkified on the {rubydoc.info page}[http://rubydoc.info/github/DavidEGrayson/doku/master], but I still want something presentable to be on the {github repository}[https://github.com/DavidEGrayson/doku].  Here's an example of a link that looks good on RubyDoc.info but not on github: {Doku::Sudoku Sudoku}.  If either YARD or Github could be configured to use a different file on the front page, that would suffice!
 
+To report bugs, use the {github issues page}[https://github.com/DavidEGrayson/doku/issues].
+
 == Philosophy
 
 This gem is meant to showcase beautiful Ruby code.  Test-driven development was used at all times during the development of this gem.  I have spent many hours reviewing the code, looking for ways to make it simpler, and refactoring it.  Every class and public method is documented.  Every method is short.  There are no ugly hacks.  All method names were chosen carefully.  At every level, the power of the Ruby language is exploited to its fullest potential.  --David Grayson

data/VERSION

@@ -1 +1 @@
-1.0.1
+1.1.0

data/lib/doku/dancing_links.rb

@@ -250,19 +250,29 @@ module Doku::DancingLinks
       alias :nodes :nodes_rightward
 
       # Removes a row from the {LinkMatrix} by covering every
-      # column that it touches.  This represents (tentatively)
+      # column that it touches.
+      def choose
+        nodes_rightward.each do |node|
+          node.column.cover
+        end
+      end
+
+      # Removes a row from the {LinkMatrix} by covering every
+      # column that it touches EXCEPT self.column, which is
+      # assumed to already be covered.
+      # This represents (tentatively)
       # choosing the node's row to be in our exact cover.
       # When that choice is proven to not work, this action can
-      # be efficiently undone with {#unchoose}.
-      def choose
+      # be efficiently undone with {#unchoose_except_self_column}.
+      def choose_except_self_column
         nodes_except_self_rightward.each do |node|
           node.column.cover
         end
       end
 
-      # Undoes the effect of {#choose}, putting
+      # Undoes the effect of {#choose_except_self_column}, putting
       # the nodes of the row back into the {LinkMatrix}.
-      def unchoose
+      def unchoose_except_self_column
         nodes_except_self_leftward.each do |node|
           node.column.uncover
         end
@@ -366,7 +376,7 @@ module Doku::DancingLinks
     # as a new column.
     #
     # @param column_ids (Enumerable) The column_ids that are in this row.
-    # @param row_id (Object) The id of this row.  This is used to express express exact covers and as the argument to {#remove_row}.
+    # @param row_id (Object) The id of this row.  This is used to express express exact covers.
     def add_row(column_ids, row_id=column_ids.dup)
       first_node = nil
       column_ids = column_ids.uniq if column_ids.respond_to?(:uniq)
@@ -390,16 +400,6 @@ module Doku::DancingLinks
       end
     end
 
-    # Removes a row from the matrix.
-    # @param row_id (Object) The ID of the row that was specified when
-    #   {#add_row} was called.
-    def remove_row(row_id)
-      raise ArgumentError, "Row with id #{row_id} not found." if !@rows[row_id]
-      @rows[row_id].nodes_rightward.each do |node|
-        node.column.cover
-      end
-    end
-
     # Retrieves a node in the row with the specified ID or returns nil if there is
     # no row with that ID.
     # @param id (Object) The ID of the row that was specified when
@@ -493,7 +493,7 @@ module Doku::DancingLinks
 
         # Try the node (push it and cover its columns).
         nodes.push node
-        node.choose
+        node.choose_except_self_column
 
       end
     end
@@ -538,7 +538,7 @@ module Doku::DancingLinks
         # We tried nodes.last and it didn't work, so
         # pop it off and uncover the corresponding columns.
         node = nodes.pop
-        node.unchoose
+        node.unchoose_except_self_column
         
         # Try the next node in this column.
         x = node.down

data/lib/doku/solver.rb

@@ -38,13 +38,14 @@ module Doku
     # @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.
+      # that does not take in to account the state of this instance.
       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).
+      # Take into account the state of this instance
+      # by "choosing" rows.  This removes them from the matrix
+      # by covering all the columns they touch.
       each do |square, glyph|
-        sm.remove_row SquareAndGlyph.new(square,glyph)
+        sm.row(SquareAndGlyph.new(square,glyph)).choose
       end
 
       sm

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: doku
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-27 00:00:00.000000000 Z
+date: 2012-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: backports
-  requirement: &12242900 !ruby/object:Gem::Requirement
+  requirement: &23796760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *12242900
+  version_requirements: *23796760
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &12241680 !ruby/object:Gem::Requirement
+  requirement: &23796140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *12241680
+  version_requirements: *23796140
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &12240840 !ruby/object:Gem::Requirement
+  requirement: &23795460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *12240840
+  version_requirements: *23795460
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &12256480 !ruby/object:Gem::Requirement
+  requirement: &23811100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: 1.6.2
   type: :development
   prerelease: false
-  version_requirements: *12256480
+  version_requirements: *23811100
 - !ruby/object:Gem::Dependency
   name: rcov
-  requirement: &12255860 !ruby/object:Gem::Requirement
+  requirement: &23810380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *12255860
+  version_requirements: *23810380
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &12255300 !ruby/object:Gem::Requirement
+  requirement: &23809620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *12255300
+  version_requirements: *23809620
 - !ruby/object:Gem::Dependency
   name: watchr
-  requirement: &12253280 !ruby/object:Gem::Requirement
+  requirement: &23808740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *12253280
+  version_requirements: *23808740
 - !ruby/object:Gem::Dependency
   name: ruby-prof
-  requirement: &12251880 !ruby/object:Gem::Requirement
+  requirement: &23805220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,10 +98,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *12251880
+  version_requirements: *23805220
 - !ruby/object:Gem::Dependency
   name: linecache19
-  requirement: &12250680 !ruby/object:Gem::Requirement
+  requirement: &23812680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -109,10 +109,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *12250680
+  version_requirements: *23812680
 - !ruby/object:Gem::Dependency
   name: ruby-debug-base19
-  requirement: &12249640 !ruby/object:Gem::Requirement
+  requirement: &23852140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -120,10 +120,10 @@ dependencies:
         version: 0.11.26
   type: :development
   prerelease: false
-  version_requirements: *12249640
+  version_requirements: *23852140
 - !ruby/object:Gem::Dependency
   name: ruby-debug19
-  requirement: &12264740 !ruby/object:Gem::Requirement
+  requirement: &23851580 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -131,7 +131,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *12264740
+  version_requirements: *23851580
 description: ! 'This gem allows you to represent Sudoku-like puzzles
 
   (Sudoku, Hexadoku, and Hexamurai) as objects and find