doku 1.0.0

data/lib/doku/grid.rb

@@ -0,0 +1,241 @@
+module Doku
+  # This module is meant to be included in subclasses of {Puzzle} where the
+  # squares are arranged in a grid.
+  #
+  # The {Puzzle} class contains only very abstract code, dealing with
+  # the abstract concepts of {Puzzle.squares squares},
+  # {Puzzle.glyphs glyphs}, and {Puzzle.groups groups}.
+  # The {Puzzle} class can represent a wide variety of puzzles, including
+  # three-dimensional puzzles or puzzles that don't have any particular
+  # spatial arrangement.
+  # However, most of the puzzles we are interested in studying are arranged
+  # in a grid, and this module contains code that makes it easy to define
+  # and work with those puzzles.
+  #
+  # Every {Puzzle.squares square} in a {PuzzleOnGrid} puzzle is a
+  # {SquareOnGrid} with x and y coordinates to represent its position on the grid.
+  # The x coordinate is 0 for the first row, 1 for the second row, etc.
+  # The y coordinate is 0 for the first column, 1 for the second column, etc.
+  #
+  # See the {ClassMethods} module for the class methods that are added to each
+  # class that includes PuzzleOnGrid.
+  module PuzzleOnGrid
+    # These are the separators that can appear in the {ClassMethods#template template}
+    # string or the string argument to the {#initialize} to make it more readable.
+    Separators = ['-', '+', '|']
+
+    private
+    def self.included(klass)
+      klass.extend ClassMethods
+    end
+
+    def self.parse_grid_string(string)
+      y = 0
+      string.lines.each_with_index do |line, line_number|
+        line.chomp!
+        next if (line.chars.to_a - Separators).empty?
+
+        x = 0
+        line.chars.each_with_index do |char, char_number|
+          next if Separators.include?(char)
+
+          yield char, char_number, line_number, x, y
+
+          x += 1
+        end
+        y += 1
+      end
+    end
+    public
+
+    module ClassMethods
+      # @return (Array) Array with the line number and character number
+      #   of the given square in the {#template} string.
+      def coordinates_in_grid_string(square)
+        [@line_number[square.y], @char_number[square.x]]
+      end
+
+      # This is a multi-line string that defines all the squares in the puzzle and the
+      # {Separators} to use to make the puzzle more readable in {#to_grid_string}.
+      # A period character ('.') represents a square.
+      # This is defined in the class by using the {#has_template} method.
+      # @return (String) The template string from the class definition.
+      attr_reader :template
+
+      # This is an array of characters (strings of length 1) which are used in
+      # multi-line grid strings to represent {Puzzle.glyphs glyphs} in a square.
+      # The order of this array must correspond to the order of the {Puzzle.glyphs glyphs}.
+      # For example, for {Sudoku}, this is
+      # ['1', '2', '3', '4', '5', '6', '7', '8', '9'].
+      # This is defined in the class definition using the {#has_glyph_chars} method.
+      # @return (Array) Array of characters.
+      attr_reader :glyph_chars
+      
+      # Selects all the squares in this puzzle which match
+      # the specified condition.
+      # @param conditions (Hash) See {SquareOnGrid#matches?}.
+      # @return (Array) Array of squares.
+      def squares_matching(conditions)
+        squares.select { |sq| sq.matches? conditions }
+      end
+
+      # Selects all the squares in this puzzle that are within a certain
+      # square area on the grid.
+      # @param leftmost_x (Integer) The x coordinate of the left-most column in the square area.
+      # @param top_y (Integer) The y coordinate of the top-most row in the square area.
+      # @param size (Integer) The width and height of the square.
+      # @return (Array) Array of squares.
+      def square_group(leftmost_x, top_y, size=Math.sqrt(glyphs.size))
+        squares_matching :x => leftmost_x...(leftmost_x+size), :y => top_y...(top_y+size)
+      end
+
+      # Selects some squares with a specific y coordinate.
+      # @param leftmost_x (Integer) The x coordinate of the left-most square.
+      # @param size (Integer) The width of the row.
+      # @return (Array) Array of squares.
+      def row(y, leftmost_x=0, size=glyphs.size)
+        squares_matching :x => leftmost_x...(leftmost_x+size), :y => y
+      end
+
+      # Selects some squares with a specific x coordinate.
+      # @param top_y (Integer) The y coordinate of the top-most square.
+      # @param size (Integer) The height of the column.
+      # @return (Array) Array of squares.
+      def column(x, top_y=0, size=glyphs.size)
+        squares_matching :x => x, :y => top_y...(top_y+size)
+      end
+
+      # @return (String) The character that represents the given {Puzzle.glyphs glyph}.
+      def glyph_char(glyph)
+        glyph_chars.at(glyphs.index(glyph) || (raise ArgumentError, "Invalid glyph #{glyph}."))
+      end
+
+      # @return (Object) The {Puzzle.glyphs glyph} represented by the given character.
+      def glyph_parse(char)
+        glyphs.at(glyph_chars.index(char.upcase) || (raise ArgumentError, "Invalid character '#{char}'."))
+      end
+
+      private
+
+      # This is called in the class definition to define the {#template} string,
+      # thus defining which squares are in the puzzle.
+      def has_template(string)
+        @template = string.freeze
+        define_squares_from_template
+      end
+
+      # This is called in the class definition to define the {#glyph_chars}.
+      # This function converts the characters to upper case to make it
+      # easier to parse strings provided by the user in a case insensitive way.
+      def has_glyph_chars(chars)
+        @glyph_chars = chars.collect &:upcase
+      end
+
+      def define_square_on_grid(x, y, line_num, char_num)
+        define_square SquareOnGrid.new x, y
+
+        @line_number ||= []
+        @char_number ||= []
+        @line_number[y] = line_num
+        @char_number[x] = char_num
+      end
+
+      # Using the {#template} provided for the puzzle, this method
+      # defines objects to represent each of the different squares.
+      def define_squares_from_template
+        PuzzleOnGrid.parse_grid_string(template) do |char, char_number, line_number, x, y|
+          if char == '.'
+            define_square_on_grid x, y, line_number, char_number
+          end
+        end
+      end
+    end
+
+    # Creates a new instance of the puzzle.
+    # @param grid_string (String) A multi-line string defining which glyphs are
+    #   currently written in which squares.  You can use {Separators}
+    #   to make this string more readable.
+    #   This parameter is provided to make it easy to manually type in puzzles.
+    #   If you are not typing the puzzle in, you should probably use {#set} instead.
+    #   A good way to type this string is to copy the class's
+    #   {ClassMethods#template template} and replace some of the periods with
+    #   {ClassMethods#glyph_chars glyph_chars} (e.g. replace a '.' with '3').
+    def initialize(grid_string=nil)
+      super()
+      parse_initial_grid_string grid_string if grid_string
+    end
+
+    # @return (String) A multi-line string representation of the puzzle suitable
+    #   for displaying, based on the {ClassMethods#template template}.
+    def to_grid_string
+      lines = self.class.template.split("\n")
+      each do |square, glyph|
+        line_number, char_number = self.class.coordinates_in_grid_string square
+        lines[line_number][char_number] = self.class.glyph_char glyph
+      end
+      lines.join "\n"
+    end
+
+    # Assigns a glyph to a square.
+    # This will modify the state of the puzzle, overwriting the previous
+    # glyph assignment.
+    # @param x (Integer) The x coordinate of the square.
+    # @param y (Integer) The y coordinate of the square.
+    # @param glyph The {Puzzle.glyphs glyph} to assign to that square, or nil.
+    def set(x, y, glyph)
+      self[SquareOnGrid.new(x, y)] = glyph
+    end
+
+    # Gets the glyph assignment for a given square.
+    # @param x (Integer) The x coordinate of the square.
+    # @param x (Integer) The y coordinate of the square.
+    # @return (Object) The {Puzzle.glyphs glyph} assigned to that square, or nil if
+    #   none is assigned.
+    def get(x, y)
+      self[SquareOnGrid.new(x, y)]
+    end
+
+    # @return (String) The same as {#to_grid_string}.
+    def to_s
+      to_grid_string
+    end
+
+    private
+    def parse_initial_grid_string(grid_string)
+      PuzzleOnGrid.parse_grid_string(grid_string) do |original_char, char_number, line_number, x, y|
+        square = SquareOnGrid.new(x, y)
+
+        char = original_char.upcase
+
+        if !squares.include?(square)
+          raise "Line #{line_number}, character #{char_number}: Invalid character.  Expected space." if char != ' '
+        elsif char == '.'
+          # No glyph specified for this square.
+        elsif self.class.glyph_chars.include?(char)
+          self[square] = self.class.glyph_parse(char)
+        else
+          raise ArgumentError, "Line #{line_number}, character #{char_number}: Invalid character '#{original_char}'.  Expected period (.) or glyph (#{self.class.glyph_chars.join ','})."
+        end
+      end
+    end
+  end
+
+  # Represents a square on a grid.
+  # Any two instances with the same x and y coordinates are considered
+  # to be equal, which makes it convenient to use SquareOnGrid instances
+  # as a  key in a hash table.
+  # This class is used by the {PuzzleOnGrid} module to represent the
+  # {Puzzle.squares squares} in grid-based {Puzzle}s.
+  class SquareOnGrid < Struct.new(:x, :y)
+    # @param conditions (Hash)  Should be a hash where the keys are
+    #  :x or :y and the values are either Integers or Integer ranges.
+    # @return (Boolean) True if the square matches all the conditions.
+    def matches?(conditions)
+      conditions.all? { |property, values| values === send(property) }
+    end
+
+    def to_s
+      "Square(#{x}, #{y})"
+    end
+  end
+end

data/lib/doku/hexadoku.rb

@@ -0,0 +1,56 @@
+require 'backports' unless defined?(require_relative)
+require_relative 'puzzle'
+require_relative 'grid'
+
+module Doku
+  # This class represents Hexadoku, otherwise known as 16x16 {Sudoku}.
+  # This is a more complex version of Sudoku with a 16x16 grid, using
+  # hex digits 0 through F.
+  # Each instance of this class represents a particular arrangement of
+  # numbers written in the boxes.
+  class Hexadoku < Puzzle
+    include PuzzleOnGrid
+    extend PuzzleOnGrid::ClassMethods # improves generated docs
+
+    has_glyphs (0..15).to_a
+    has_glyph_chars glyphs.collect { |s| '%x'%[s] }
+
+    has_template <<END
+....|....|....|....
+....|....|....|....
+....|....|....|....
+....|....|....|....
+----+----+----+----
+....|....|....|....
+....|....|....|....
+....|....|....|....
+....|....|....|....
+----+----+----+----
+....|....|....|....
+....|....|....|....
+....|....|....|....
+....|....|....|....
+----+----+----+----
+....|....|....|....
+....|....|....|....
+....|....|....|....
+....|....|....|....
+END
+
+    # Define row and column groups.
+    0.upto(15).each do |n|
+      define_group row(n)
+      define_group column(n)
+    end
+    
+    # Define the 4x4 groups.
+    0.step(12,4).each do |x|
+      0.step(12,4).each do |y|
+        define_group square_group(x, y)
+      end
+    end
+    
+  end
+
+end
+

data/lib/doku/hexamurai.rb

@@ -0,0 +1,95 @@
+require 'backports' unless defined?(require_relative)
+require_relative 'puzzle'
+require_relative 'grid'
+
+module Doku
+  # This class represents the Hexamurai, a puzzle that consists of
+  # five {Hexadoku} puzzles superimposed on eachother.
+  # The {http://www.elektor.com/magazines/2011/july-047-august/hexamurai.1852786.lynkx Hexamurai puzzle appeared in the July/August issue of Elektor magazine}.
+  # Each instance of this class represents a particular arrangement of
+  # numbers written in the boxes.
+  class Hexamurai < Puzzle
+    include PuzzleOnGrid
+    extend Doku::PuzzleOnGrid::ClassMethods # improves generated docs
+
+    has_glyphs (0..15).to_a
+    has_glyph_chars glyphs.collect { |s| "%X"%[s] }
+    
+    has_template <<END
+        |........|........|
+        |........|........|
+        |........|........|
+        |........|........|
+        |........|........|
+        |........|........|
+        |........|........|
+        |........|........|
+--------+--------+--------+--------
+........|........|........|........
+........|........|........|........
+........|........|........|........
+........|........|........|........
+........|........|........|........
+........|........|........|........
+........|........|........|........
+........|........|........|........
+--------+--------+--------+--------
+........|........|........|........
+........|........|........|........
+........|........|........|........
+........|........|........|........
+........|........|........|........
+........|........|........|........
+........|........|........|........
+........|........|........|........
+--------+--------+--------+--------
+        |........|........|
+        |........|........|
+        |........|........|
+        |........|........|
+        |........|........|
+        |........|........|
+        |........|........|
+        |........|........|
+END
+
+    # A track of 32 rows that runs down the center, and
+    # a track of 32 columns that runs through the center.
+    0.upto(31) do |n|
+      define_group row(n, 8)
+      define_group column(n, 8)
+    end
+
+    # The columns and rows that weren't included in the
+    # defintitions above.
+    0.upto(15) do |n|
+      define_group row(n+8, 0)     # for the left Hexadoku
+      define_group row(n+8, 16)    # for the right Hexadoku
+      define_group column(n+8, 0)  # for the top Hexadoku
+      define_group column(n+8, 16) # for the bottom Hexadoku
+    end
+
+    # A track of 32 4x4 groups that runs from top-to-bottom
+    # and a track of 32 4x4 groups that runs from left-to-right.
+    # These two tracks intersect, but that's ok because
+    # define_group checks for uniqueness of groups.
+    0.step(28, 4) do |n|
+      8.step(20, 4) do |m|
+        define_group square_group(n, m)
+        define_group square_group(m, n)
+      end
+    end
+
+    # Deduced groups!
+    # These groups are not explicitly stated in the puzzle, but
+    # we can use logic to deduce that they are groups (no
+    # glyph can appear twice in them).
+    # TODO: see if these deduced groups actually speed up algorithm!
+    8.upto(23) do |n|
+      define_group row(n, 0, 8) + row(n, 24, 8)
+      define_group column(n, 0, 8) + column(n, 24, 8)
+    end
+
+  end
+end
+

data/lib/doku/puzzle.rb

@@ -0,0 +1,250 @@
+require 'set'
+require 'backports' unless defined?(require_relative)
+require_relative 'solver'
+
+# The Doku module contains everything defined by the doku gem, including
+# classes for puzzles, and a general-purpose implementation of the
+# {DancingLinks} algorithm for finding exact covers.
+module Doku
+
+  # @abstract Use the {Sudoku}, {Hexadoku}, or {Hexamurai}
+  #   subclasses or make a subclass to represent your own type
+  #   of Sudoku-like puzzle.
+  #
+  # This in abstract class for creating classes that represent
+  # Sudoku-like puzzles.
+  #
+  # Every subclass of {Doku::Puzzle} represents a Sudoku-like puzzle consisting
+  # of a set of glyphs, a set of squares, and a set of groups of squares.
+  # For example, the {Doku::Sudoku} subclass represents the famous 9x9 puzzle,
+  # Sudoku.
+  #
+  # Every instance of a subclass of Puzzle represents a particular state
+  # of that type of puzzle, i.e. a record of which glyph is assigned
+  # to each square.
+  class Puzzle
+    include SolvableWithDancingLinks
+
+    # A hash that associates squares to glyphs, representing
+    # the arrangement of glyphs in the puzzle.
+    attr_reader :glyph_state
+
+    # Creates a new instance of the puzzle.
+    #
+    # @param [Hash] glyph_state The state of the puzzle, represented as a hash
+    # where the keys are squares and the values are nil or glyphs in the context
+    # of this puzzle class.  For example, this represents what numbers have been
+    # written in the boxes of a {Sudoku} puzzle.
+    def initialize(glyph_state = {})
+      @glyph_state = {}
+      # We initialize glyph_state this way so that the data gets validated.
+      glyph_state.each { |square, glyph| self[square] = glyph }
+    end
+
+    class << self
+      
+      # Returns an array of all the valid glyphs for this class of puzzle.
+      # A glyph can be any type of Ruby object, and it is meant to
+      # represent a symbol which can be drawn inside a square in a
+      # Sudoku-like puzzle.
+      #
+      # For example, the glyphs for {Sudoku} are the Ruby integers 1, 2, 3,
+      # 4, 5, 6, 7, 8, and 9.
+      #
+      # The glyphs, squares, and groups, are defined at the class level, in the subclasses of Doku::Puzzle.
+      # @return [Array] Array of objects representing glyphs.
+      attr_reader :glyphs
+
+      # Returns an array of all the valid squares in this class of puzzle.
+      # A square can be any type of Ruby object, and it is meant to
+      # represent a square in which glyphs are drawn in a Sudoku-like puzzle.
+      # 
+      # For example, there are 81 squares defined in the {Sudoku} class,
+      # one for each square on the 9x9 Sudoku grid.
+      #
+      # The glyphs, squares, and groups, are defined at the class level, in the subclasses of Doku::Puzzle.
+      # @return [Array] Array of objects representing squares.
+      attr_reader :squares
+
+      # Returns an array of all the groups for this class of puzzle.
+      # A group should be a Set object that contains some squares.
+      # A group represents a constraint on solutions to the puzzle:
+      # every glyph must appear exactly once in every group.
+      #
+      # For example, the groups of the {Sudoku} class represent the
+      # nie columns, nine rows, and nine 3x3 boxes of Sudoku.
+      #
+      # The glyphs, squares, and groups, are defined at the class level, in the subclasses of Doku::Puzzle.
+      # @return [Array] Array of glyphs.
+      attr_reader :groups
+    end
+
+    # Shortcut for calling the {Puzzle.glyphs} class method.
+    # @return [Array] Array of glyphs.
+    def glyphs
+      self.class.glyphs
+    end
+
+    # Shortcut for calling the {Puzzle.squares} class method.
+    # @return [Array] Array of squares.
+    def squares
+      self.class.squares
+    end
+
+    # Shortcut for calling the {Puzzle.groups} class method.
+    # @return [Array] Array of groups.
+    def groups
+      self.class.groups
+    end
+
+    # Gets the glyph assigned to the given square.
+    # @param square Must be one of the {Puzzle.squares} for this puzzle.
+    # @return The glyph that is assigned to the given square
+    #   (one of the {Puzzle.glyphs} defined for this puzzle),
+    #   or nil if no glyph is assigned.
+    def [](square)
+      raise IndexError, "Square not found in #{self.class.name}: #{square}." if !squares.include?(square)
+      @glyph_state[square]
+    end
+
+    # Sets the glyph assigned to the given square.
+    # @param square Must be one of the {Puzzle.squares} for this puzzle.
+    # @param glyph Must be one of the {Puzzle.glyphs} for this puzzle, or nil.
+    def []=(square, glyph)
+      raise IndexError, "Square not found in #{self.class}: #{square}." if !squares.include?(square)
+      raise ArgumentError, "Value must be a glyph in this puzzle or nil." if !glyph.nil? && !glyphs.include?(glyph)
+
+      # Do NOT store nils as values in the hash, because we
+      # don't want them to affect equality comparisons.
+      if glyph == nil
+        @glyph_state.delete square
+      else
+        @glyph_state[square] = glyph
+      end
+    end
+
+    # This method allows you to iterate over every square that has a
+    # glyph assigned to it.
+    #
+    # @yield [square, glyph]
+    # @yieldparam square A square that has a glyph assigned to it.
+    # @yieldparam glyph The glyph that is assigned to the square.
+    def each(&block)
+      @glyph_state.each(&block)
+    end
+
+    # @return [Fixnum] Returns a hash code based on the glyph assignments.
+    def hash
+      @glyph_state.hash
+    end
+
+    # Two puzzles are equal if they have the same class and glyph assignments. 
+    # @return [Boolean] True if the two puzzles are equal.
+    def eql?(puzzle)
+      self.class == puzzle.class and glyph_state == puzzle.glyph_state
+    end
+
+    # Same as {#eql?}.
+    def == (puzzle)
+      eql? puzzle
+    end
+
+    # Returns true if the puzzle's glyphs assignments are a subset
+    # of the given puzzle's glyph assignments and the two puzzles are
+    # the same class.
+    #
+    # Every puzzle is a subset of itself.
+    #
+    # For example, if you find a Sudoku puzzle and start working on it,
+    # you have changed the original puzzle into a new puzzle.
+    # The original puzzle will be a subset of the new puzzle,
+    # assuming you didn't erase any numbers.
+    #
+    # @return [Boolean]
+    def subset?(puzzle)
+      self.class == puzzle.class and glyph_assignment_subset?(puzzle)
+    end
+
+    # Returns true if this puzzle is completely filled in,
+    # which means every square has a glyph assigned to it.
+    # For example, a Sudoku puzzle is considered to be filled after
+    # you have written a number in every box, regardless of whether
+    # the numbers obey the rules of Sudoku or not.
+    # See also {#solution?} and {#solution_for?}.
+    #
+    # @return [Boolean]
+    def filled?
+      squares.size == glyph_state.keys.size
+    end
+
+    # Returns true if this puzzle follows the rules.
+    # A puzzle is valid if no glyph appears twice in any group.
+    # For example, a {Sudoku} puzzle would be invalid if you
+    # wrote a "3" twice in the same column.
+    #
+    # @return [Boolean]
+    def valid?
+      groups.all? do |group|
+        glyphs = group.collect { |square| self[square] } - [nil]
+        glyphs.uniq.size == glyphs.size
+      end
+    end
+
+    # Returns true if the puzzle is {#filled?} and {#valid?}.
+    # @return [Boolean]
+    def solution?
+      filled? and valid?
+    end
+
+    # Returns true if the puzzle is valid solution for the given puzzle.
+    #
+    # @return [Boolean]
+    def solution_for?(puzzle)
+      solution? and puzzle.subset?(self)
+    end
+
+    private
+
+    # This is called when the puzzle is duped or cloned.
+    def initialize_copy(source)
+      @glyph_state = @glyph_state.dup
+    end
+
+    # This should be called inside the definition of a Puzzle subclass
+    # to define what glyphs the puzzle has.
+    def self.has_glyphs(glyphs)
+      @glyphs = glyphs
+    end
+
+    # This should be called inside the definition of a Puzzle subclass
+    # to define what squares the puzzle has.
+    # This method defines one square at a time.  See also #has_squares.
+    def self.define_square(square)
+      raise ArgumentError, "square should not be nil" if square.nil?
+      @squares ||= []
+      @squares << square
+    end
+
+    # This should be called inside the definition of a Puzzle subclass
+    # to define what squares the puzzle has.
+    # This method defines all the squares at once.  See also #define_square.
+    def self.has_squares(squares)
+      raise ArgumentError, "list of squares should not contain nil" if squares.include? nil
+      @squares = squares.uniq
+    end
+
+    def glyph_assignment_subset?(puzzle)
+      glyph_state.all? do |square, glyph|
+        glyph == puzzle[square]
+      end
+    end
+
+    def self.define_group(squares)
+      group = Set.new(squares)
+      raise ArgumentError, "Expected groups to be of size #{glyphs.size} but got one of size #{group.size}.  squares = #{group.inspect}" if group.size != glyphs.size 
+      @groups ||= []
+      @groups << group unless @groups.include?(group)
+    end
+
+  end
+end