theseus 1.0.0

data/lib/theseus/solvers/backtracker.rb

@@ -0,0 +1,79 @@
+require 'theseus/solvers/base'
+
+module Theseus
+  module Solvers
+    # An implementation of a recursive backtracker for solving a maze. Although it will
+    # work (eventually) for multiply-connected mazes, it will almost certainly not
+    # return an optimal solution in that case. Thus, this solver is best suited only
+    # for "perfect" mazes (those with no loops).
+    #
+    # For mazes that contain loops, see the Theseus::Solvers::Astar class.
+    class Backtracker < Base
+      def initialize(maze, a=maze.start, b=maze.finish) #:nodoc:
+        super
+        @visits = Array.new(@maze.height) { Array.new(@maze.width, 0) }
+        @stack = []
+      end
+
+      VISIT_MASK = { false => 1, true => 2 }
+
+      def current_solution #:nodoc:
+        @stack[1..-1].map { |item| item[0] }
+      end
+
+      def step #:nodoc:
+        if @stack == [:fail]
+          return false
+        elsif @stack.empty?
+          @stack.push(:fail)
+          @stack.push([@a, @maze.potential_exits_at(@a[0], @a[1]).dup])
+          return @a.dup
+        elsif @stack.last[0] == @b
+          @solution = @stack[1..-1].map { |pt, tries| pt }
+          return false
+        else
+          x, y = @stack.last[0]
+          cell = @maze[x, y]
+          loop do
+            try = @stack.last[1].pop
+
+            if try.nil?
+              spot = @stack.pop
+              x, y = spot[0]
+              return :backtrack
+            elsif (cell & try) != 0
+              # is the current path an "under" path for the current cell (x,y)?
+              is_under = (try & Maze::UNDER != 0)
+
+              dir = is_under ? (try >> Maze::UNDER_SHIFT) : try
+              opposite = @maze.opposite(dir)
+
+              nx, ny = @maze.move(x, y, dir)
+
+              # is the new path an "under" path for the next cell (nx,ny)?
+              going_under = @maze[nx, ny] & (opposite << Maze::UNDER_SHIFT) != 0
+
+              # might be out of bounds, due to the entrance/exit passages
+              next if !@maze.valid?(nx, ny) || (@visits[ny][nx] & VISIT_MASK[going_under] != 0)
+
+              @visits[ny][nx] |= VISIT_MASK[going_under]
+              ncell = @maze[nx, ny]
+              p = [nx, ny]
+
+              if ncell & (opposite << Maze::UNDER_SHIFT) != 0 # underpass
+                unders = (ncell & Maze::UNDER) >> Maze::UNDER_SHIFT
+                exit_dir = unders & ~opposite
+                directions = [exit_dir << Maze::UNDER_SHIFT]
+              else
+                directions = @maze.potential_exits_at(nx, ny) - [@maze.opposite(dir)]
+              end
+
+              @stack.push([p, directions])
+              return p.dup
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/theseus/solvers/base.rb

@@ -0,0 +1,95 @@
+require 'theseus/maze'
+
+module Theseus
+  module Solvers
+    # The abstract superclass for solver implementations. It simply provides
+    # some helper methods that implementations would otherwise have to duplicate.
+    class Base
+      # The maze object that this solver will provide a solution for.
+      attr_reader :maze
+
+      # The point (2-tuple array) at which the solution path should begin.
+      attr_reader :a
+
+      # The point (2-tuple array) at which the solution path should end.
+      attr_reader :b
+
+      # Create a new solver instance for the given maze, using the given
+      # start (+a+) and finish (+b+) points. The solution will not be immediately
+      # generated; to do so, use the #step or #solve methods.
+      def initialize(maze, a=maze.start, b=maze.finish)
+        @maze = maze
+        @a = a
+        @b = b
+        @solution = nil
+      end
+
+      # Returns +true+ if the solution has been generated.
+      def solved?
+        @solution != nil
+      end
+
+      # Returns the solution path as an array of 2-tuples, beginning with #a and
+      # ending with #b. If the solution has not yet been generated, this will
+      # generate the solution first, and then return it.
+      def solution
+        solve unless solved?
+        @solution
+      end
+
+      # Generates the solution to the maze, and returns +self+. If the solution
+      # has already been generated, this does nothing.
+      def solve
+        while !solved?
+          step
+        end
+
+        self
+      end
+
+      # If the maze is solved, this yields each point in the solution, in order.
+      #
+      # If the maze has not yet been solved, this yields the result of calling
+      # #step, until the maze has been solved.
+      def each
+        if solved?
+          solution.each { |s| yield s }
+        else
+          yield s while s = step
+        end
+      end
+
+      # Returns the solution (or, if the solution is not yet fully generated,
+      # the current_solution) as a Theseus::Path object.
+      def to_path(options={})
+        path = @maze.new_path(options)
+        prev = @maze.entrance
+
+        (@solution || current_solution).each do |pt|
+          how = path.link(prev, pt)
+          path.set(pt, how)
+          prev = pt
+        end
+
+        how = path.link(prev, @maze.exit)
+        path.set(@maze.exit, how)
+
+        path
+      end
+
+      # Returns the current (potentially partial) solution to the maze. This
+      # is for use while the algorithm is running, so that the current best-solution
+      # may be inspected (or displayed).
+      def current_solution
+        raise NotImplementedError, "solver subclasses must implement #current_solution"
+      end
+
+      # Runs a single iteration of the solution algorithm. Returns +false+ if the
+      # algorithm has completed, and non-nil otherwise. The return value is
+      # algorithm-dependent.
+      def step
+        raise NotImplementedError, "solver subclasses must implement #step"
+      end
+    end
+  end
+end

data/lib/theseus/upsilon_maze.rb

@@ -0,0 +1,37 @@
+require 'theseus/maze'
+
+module Theseus
+  # An upsilon maze is one in which the field is tesselated into octogons and
+  # squares:
+  #
+  #    _   _   _   _
+  #   / \_/ \_/ \_/ \
+  #   | |_| |_| |_| |
+  #   \_/ \_/ \_/ \_/
+  #   |_| |_| |_| |_|
+  #   / \_/ \_/ \_/ \
+  #   | |_| |_| |_| |
+  #   \_/ \_/ \_/ \_/
+  #
+  # Upsilon mazes in Theseus support weaving, but not symmetry (yet).
+  #
+  #   maze = Theseus::UpsilonMaze.generate(width: 10)
+  #   puts maze
+  class UpsilonMaze < Maze
+    def potential_exits_at(x, y) #:nodoc:
+      if (x+y) % 2 == 0 # octogon
+        [N, S, E, W, NW, NE, SW, SE]
+      else # square
+        [N, S, E, W]
+      end
+    end
+
+    def perform_weave(from_x, from_y, to_x, to_y, direction) #:nodoc:
+      apply_move_at(to_x, to_y, direction << UNDER_SHIFT)
+      apply_move_at(to_x, to_y, opposite(direction) << UNDER_SHIFT)
+
+      nx, ny = move(to_x, to_y, direction)
+      [nx, ny, direction]
+    end
+  end
+end

data/lib/theseus/version.rb

@@ -0,0 +1,10 @@
+module Theseus
+  # The current version of the Theseus library.
+  module Version
+    MAJOR = 1
+    MINOR = 0
+    TINY  = 0
+
+    STRING = [MAJOR, MINOR, TINY].join(".")
+  end
+end

data/test/maze_test.rb

@@ -0,0 +1,193 @@
+require 'minitest/autorun'
+require 'theseus'
+
+class MazeTest < MiniTest::Unit::TestCase
+  def test_maze_without_explicit_height_uses_width
+    maze = Theseus::OrthogonalMaze.new(width: 10)
+    assert_equal 10, maze.width
+    assert_equal maze.width, maze.height
+  end
+
+  def test_maze_without_explicit_width_uses_height
+    maze = Theseus::OrthogonalMaze.new(height: 10)
+    assert_equal 10, maze.height
+    assert_equal maze.height, maze.width
+  end
+
+  def test_maze_is_initially_blank
+    maze = Theseus::OrthogonalMaze.new(width: 10)
+    assert !maze.generated?
+
+    zeros = 0
+    maze.height.times do |y|
+      maze.width.times do |x|
+        zeros += 1if maze[x, y] == 0
+      end
+    end
+
+    assert_equal 100, zeros
+  end
+
+  def test_maze_created_with_generate_is_identical_to_maze_created_with_step
+    srand(14)
+    maze1 = Theseus::OrthogonalMaze.generate(width: 10)
+    assert maze1.generated?
+
+    srand(14)
+    maze2 = Theseus::OrthogonalMaze.new(width: 10)
+    maze2.step until maze2.generated?
+
+    assert_equal maze1.width, maze2.width
+    assert_equal maze1.height, maze2.height
+
+    differences = 0
+
+    maze1.width.times do |x|
+      maze1.height.times do |y|
+        differences += 1 unless maze1[x,y] == maze2[x,y]
+      end
+    end
+
+    assert_equal 0, differences
+  end
+
+  def test_apply_move_at_should_combine_direction_with_existing_directions
+    maze = Theseus::OrthogonalMaze.new(width: 10)
+
+    maze[5,5] = Theseus::Maze::E
+    maze.apply_move_at(5, 5, Theseus::Maze::N)
+    assert_equal (Theseus::Maze::N | Theseus::Maze::E), maze[5,5]
+  end
+
+  def test_apply_move_at_with_under_should_move_existing_directions_to_under_plane
+    maze = Theseus::OrthogonalMaze.new(width: 10)
+
+    maze[5,5] = Theseus::Maze::E
+    maze.apply_move_at(5, 5, :under)
+    assert_equal (Theseus::Maze::E << Theseus::Maze::UNDER_SHIFT), maze[5,5]
+  end
+
+  def test_apply_move_at_with_x_symmetry_should_populate_x_mirror
+    maze = Theseus::OrthogonalMaze.new(width: 10, symmetry: :x)
+
+    maze.apply_move_at(1, 2, Theseus::Maze::E)
+    assert_equal Theseus::Maze::W, maze[8, 2]
+
+    maze.apply_move_at(2, 1, Theseus::Maze::NE)
+    assert_equal Theseus::Maze::NW, maze[7, 1]
+
+    maze.apply_move_at(2, 3, Theseus::Maze::N)
+    assert_equal Theseus::Maze::N, maze[7, 3]
+  end
+
+  def test_apply_move_at_with_y_symmetry_should_populate_y_mirror
+    maze = Theseus::OrthogonalMaze.new(width: 10, symmetry: :y)
+
+    maze.apply_move_at(1, 2, Theseus::Maze::S)
+    assert_equal Theseus::Maze::N, maze[1, 7]
+
+    maze.apply_move_at(2, 1, Theseus::Maze::SW)
+    assert_equal Theseus::Maze::NW, maze[2, 8]
+
+    maze.apply_move_at(2, 3, Theseus::Maze::W)
+    assert_equal Theseus::Maze::W, maze[2, 6]
+  end
+
+  def test_apply_move_at_with_xy_symmetry_should_populate_xy_mirror
+    maze = Theseus::OrthogonalMaze.new(width: 10, symmetry: :xy)
+
+    maze.apply_move_at(1, 2, Theseus::Maze::S)
+    assert_equal Theseus::Maze::N, maze[1, 7]
+    assert_equal Theseus::Maze::S, maze[8, 2]
+    assert_equal Theseus::Maze::N, maze[8, 7]
+
+    maze.apply_move_at(2, 1, Theseus::Maze::SW)
+    assert_equal Theseus::Maze::NW, maze[2, 8]
+    assert_equal Theseus::Maze::SE, maze[7, 1]
+    assert_equal Theseus::Maze::NE, maze[7, 8]
+
+    maze.apply_move_at(2, 3, Theseus::Maze::W)
+    assert_equal Theseus::Maze::W, maze[2, 6]
+    assert_equal Theseus::Maze::E, maze[7, 3]
+    assert_equal Theseus::Maze::E, maze[7, 6]
+  end
+
+  def test_apply_move_at_with_radial_symmetry_should_populate_radial_mirror
+    maze = Theseus::OrthogonalMaze.new(width: 10, symmetry: :radial)
+
+    maze.apply_move_at(1, 2, Theseus::Maze::S)
+    assert_equal Theseus::Maze::E, maze[2, 8]
+    assert_equal Theseus::Maze::W, maze[7, 1]
+    assert_equal Theseus::Maze::N, maze[8, 7]
+
+    maze.apply_move_at(2, 1, Theseus::Maze::SW)
+    assert_equal Theseus::Maze::SE, maze[1, 7]
+    assert_equal Theseus::Maze::NW, maze[8, 2]
+    assert_equal Theseus::Maze::NE, maze[7, 8]
+
+    maze.apply_move_at(2, 3, Theseus::Maze::W)
+    assert_equal Theseus::Maze::S, maze[3, 7]
+    assert_equal Theseus::Maze::N, maze[6, 2]
+    assert_equal Theseus::Maze::E, maze[7, 6]
+  end
+
+  def test_dx_east_should_increase
+    maze = Theseus::OrthogonalMaze.new(width: 10)
+    assert_equal 1, maze.dx(Theseus::Maze::E)
+    assert_equal 1, maze.dx(Theseus::Maze::NE)
+    assert_equal 1, maze.dx(Theseus::Maze::SE)
+  end
+
+  def test_dx_west_should_decrease
+    maze = Theseus::OrthogonalMaze.new(width: 10)
+    assert_equal -1, maze.dx(Theseus::Maze::W)
+    assert_equal -1, maze.dx(Theseus::Maze::NW)
+    assert_equal -1, maze.dx(Theseus::Maze::SW)
+  end
+
+  def test_dy_south_should_increase
+    maze = Theseus::OrthogonalMaze.new(width: 10)
+    assert_equal 1, maze.dy(Theseus::Maze::S)
+    assert_equal 1, maze.dy(Theseus::Maze::SE)
+    assert_equal 1, maze.dy(Theseus::Maze::SW)
+  end
+
+  def test_dy_north_should_decrease
+    maze = Theseus::OrthogonalMaze.new(width: 10)
+    assert_equal -1, maze.dy(Theseus::Maze::N)
+    assert_equal -1, maze.dy(Theseus::Maze::NE)
+    assert_equal -1, maze.dy(Theseus::Maze::NW)
+  end
+
+  def test_opposite_should_report_inverse_direction
+    maze = Theseus::OrthogonalMaze.new(width: 10)
+    assert_equal Theseus::Maze::N, maze.opposite(Theseus::Maze::S)
+    assert_equal Theseus::Maze::NE, maze.opposite(Theseus::Maze::SW)
+    assert_equal Theseus::Maze::E, maze.opposite(Theseus::Maze::W)
+    assert_equal Theseus::Maze::SE, maze.opposite(Theseus::Maze::NW)
+    assert_equal Theseus::Maze::S, maze.opposite(Theseus::Maze::N)
+    assert_equal Theseus::Maze::SW, maze.opposite(Theseus::Maze::NE)
+    assert_equal Theseus::Maze::W, maze.opposite(Theseus::Maze::E)
+    assert_equal Theseus::Maze::NW, maze.opposite(Theseus::Maze::SE)
+  end
+
+  def test_step_should_populate_current_cell_and_next_cell
+    maze = Theseus::OrthogonalMaze.new(width: 10)
+
+    cx, cy = maze.x, maze.y
+    assert cx >= 0 && cx < maze.width
+    assert cy >= 0 && cy < maze.height
+    assert_equal 0, maze[cx, cy]
+
+    assert maze.step
+
+    direction = maze[cx, cy]
+    refute_equal 0, direction
+
+    nx, ny = maze.move(cx, cy, direction)
+    refute_equal [nx, ny], [cx, cy]
+    assert_equal [nx, ny], [maze.x, maze.y]
+
+    assert_equal maze.opposite(direction), maze[nx, ny]
+  end
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification 
+name: theseus
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Jamis Buck
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-19 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: chunky_png
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 12
+        - 0
+        version: 0.12.0
+  type: :runtime
+  version_requirements: *id001
+description: Theseus is a library for building random mazes.
+email: jamis@jamisbuck.org
+executables: 
+- theseus
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.rdoc
+- Rakefile
+- lib/theseus/delta_maze.rb
+- lib/theseus/formatters/ascii/delta.rb
+- lib/theseus/formatters/ascii/orthogonal.rb
+- lib/theseus/formatters/ascii/sigma.rb
+- lib/theseus/formatters/ascii/upsilon.rb
+- lib/theseus/formatters/ascii.rb
+- lib/theseus/formatters/png/delta.rb
+- lib/theseus/formatters/png/orthogonal.rb
+- lib/theseus/formatters/png/sigma.rb
+- lib/theseus/formatters/png/upsilon.rb
+- lib/theseus/formatters/png.rb
+- lib/theseus/mask.rb
+- lib/theseus/maze.rb
+- lib/theseus/orthogonal_maze.rb
+- lib/theseus/path.rb
+- lib/theseus/sigma_maze.rb
+- lib/theseus/solvers/astar.rb
+- lib/theseus/solvers/backtracker.rb
+- lib/theseus/solvers/base.rb
+- lib/theseus/upsilon_maze.rb
+- lib/theseus/version.rb
+- lib/theseus.rb
+- examples/a-star-search.rb
+- bin/theseus
+- test/maze_test.rb
+has_rdoc: true
+homepage: http://github.com/jamis/theseus
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: 
+- Ruby 1.9
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Maze generator for Ruby
+test_files: []
+