maze_crosser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 46f547e36865ec4a97fd4277bd862540d00f8a8e
+  data.tar.gz: 6b95a2930232b9cc3c5ac22c8154c7047cfa2194
+SHA512:
+  metadata.gz: e3dbdf0f5b40dc2bd9153147834f69c8b5acafa48bb32a07489842c666865a921fc23944184ea155edf857c932f23d7586c45e948a6fbd499a07c77941dbf778
+  data.tar.gz: 1d16f2fb62751ab13bf96c44f251cecf516b54a711e4c657d0e17de7bb090060a9dcc80a10af2762b402d7f28f44e556673600306f63f9ff62c1e82be88cf135

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,6 @@
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.4.1
+before_install: gem install bundler -v 1.15.4

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in mazer.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Kiriakos Velissariou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,62 @@
+# maze_crosser
+
+[![Build Status](https://travis-ci.org/kiriakosv/maze_crosser.svg?branch=master)](https://travis-ci.org/kiriakosv/maze_crosser)
+[![Coverage Status](https://coveralls.io/repos/github/kiriakosv/maze_crosser/badge.svg)](https://coveralls.io/github/kiriakosv/maze_crosser)
+[![Maintainability](https://api.codeclimate.com/v1/badges/ade071d041026dd0928d/maintainability)](https://codeclimate.com/github/kiriakosv/maze_crosser/maintainability)
+
+A simple 2D maze solving application.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'maze_crosser'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install maze_crosser
+
+## Usage
+
+After installing the gem, open an irb prompt and type
+```ruby
+require 'maze_crosser'
+```
+You are now provided with two instance variables, @maze_crosser_runner and @cache_provider. You can use these as follows:
+```ruby
+# Empty the cache
+@cache_provider.empty!
+
+# Provide a path to a grid file and a solving algorithm. Currently, the only
+# algorithm option is 'recursive' (set as default).
+@maze_crosser_runner.run('path_to_file')
+```
+### Grid file
+The grid file should have a .txt extension and follow the format below:
+```
+___SX
+XXX_X
+G___X
+XX_XX
+```
+where:
+* G: End goal
+* S: Starting poing
+* X: Blocked point
+* _: Free point
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/load` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/bin/load

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'maze_crosser'
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/etc/general_information.md

@@ -0,0 +1,20 @@
+# General information
+
+## Development process
+
+I tried to follow a TDD approach for the most part. This was not always easy,
+especially at the beginning, since the general structure of the application
+was under constant change.
+
+## External sources
+
+This application was created as a gem. The initial setup, as well as the gem
+release was done using bundler. Every other dependency is listed in the gemspec
+file.
+
+The implementation of the recursive algorithm is based on information I
+found [here](https://www.cs.bu.edu/teaching/alg/maze/).
+
+## Final notes
+The initial gem name was Mazer. Unfortunately, the name was already taken by
+another gem.

data/lib/maze_crosser/algorithms/recursive_algorithm_runner.rb

@@ -0,0 +1,87 @@
+module MazeCrosser
+  # Class responsible for applying resursive algorithm to a maze.
+  #
+  # recursive_algorithm = RecursiveAlgorithmRunner.new(maze)
+  #
+  # Run the algorithm
+  # recursive_algorithm.run
+  class RecursiveAlgorithmRunner
+    def initialize(maze)
+      @maze = maze
+      @path = []
+    end
+
+    def run
+      find_path(@maze.start)
+      @path
+    end
+
+    private
+
+    # This method is based on the recursive algorithm described in:
+    # https://www.cs.bu.edu/teaching/alg/maze/
+    # PROS: Easy to understand, simple implementation
+    # CONS: Does not necessarily find the shortest path
+    def find_path(coords)
+      return false if dead_end?(coords)
+
+      if goal_found?(coords)
+        @path << coords
+        return true
+      end
+
+      # This cell may actually be part of the solution, let's check
+      @path << coords
+      return true if valid_move_available?(coords)
+
+      # Since we got here, this cell can't be part of the solution
+      @path.pop
+      false
+    end
+
+    def already_visited?(coords)
+      @path.include?(coords)
+    end
+
+    def out_of_bounds?(coords)
+      !@maze.inside_grid?(coords)
+    end
+
+    def blocked?(coords)
+      @maze.blocked_cell?(coords)
+    end
+
+    def dead_end?(coords)
+      out_of_bounds?(coords) ||
+        blocked?(coords) ||
+        already_visited?(coords)
+    end
+
+    def goal_found?(coords)
+      coords == @maze.goal
+    end
+
+    def valid_move_available?(coords)
+      return true if move_north(coords) ||
+                     move_south(coords) ||
+                     move_east(coords) ||
+                     move_west(coords)
+    end
+
+    def move_north(coords)
+      find_path([coords[0] - 1, coords[1]])
+    end
+
+    def move_south(coords)
+      find_path([coords[0] + 1, coords[1]])
+    end
+
+    def move_east(coords)
+      find_path([coords[0], coords[1] + 1])
+    end
+
+    def move_west(coords)
+      find_path([coords[0], coords[1] - 1])
+    end
+  end
+end

data/lib/maze_crosser/basic_grid_validator.rb

@@ -0,0 +1,35 @@
+module MazeCrosser
+  # Module responsible for aplying basic maze validations.
+  module BasicGridValidator
+    ALLOWED_CHARACTERS = {
+      empty: '_',
+      start: 'S',
+      goal: 'G',
+      blocked: 'X'
+    }.freeze
+
+    def valid?(maze)
+      only_valid_characters?(maze) && \
+        one_start_and_one_end?(maze) && \
+        rectangular?(maze)
+    end
+
+    private
+
+    def only_valid_characters?(maze)
+      maze.flatten.reject { |c| ALLOWED_CHARACTERS.values.include? c }.empty?
+    end
+
+    def one_start_and_one_end?(maze)
+      flat_maze = maze.flatten
+
+      flat_maze.count { |c| c == ALLOWED_CHARACTERS[:goal] } == 1 &&
+        flat_maze.count { |c| c == ALLOWED_CHARACTERS[:start] } == 1
+    end
+
+    def rectangular?(maze)
+      row_size = maze[0].size
+      maze.select { |row| row.size == row_size }.size == maze.size
+    end
+  end
+end

data/lib/maze_crosser/cache_provider.rb

@@ -0,0 +1,31 @@
+module MazeCrosser
+  # Class responsible for maintaining a cache of already solved mazes.
+  #
+  # cache_provider = CacheProvider.new
+  #
+  # Add solution to cache
+  # cache_provider.add(grid, solution)
+  #
+  # Get a solution
+  # cache_provider.get_solution(grid)
+  #
+  # Empty cache
+  # cache_provider.empty_cache!
+  class CacheProvider
+    def initialize(solutions = {})
+      @solutions = solutions
+    end
+
+    def add(grid, solution)
+      @solutions[grid] = solution
+    end
+
+    def get_solution(grid)
+      @solutions[grid]
+    end
+
+    def empty_cache!
+      @solutions = {}
+    end
+  end
+end

data/lib/maze_crosser/file_checker.rb

@@ -0,0 +1,26 @@
+module MazeCrosser
+  # Module containing a file validator.
+  module FileChecker
+    ALLOWED_EXTENSIONS = %w[txt].freeze
+
+    def check(file)
+      raise ArgumentError, 'Invalid file' unless valid_file? file
+
+      file
+    end
+
+    private
+
+    def valid_file?(file)
+      file_exists?(file) && allowed_extension?(file)
+    end
+
+    def file_exists?(file)
+      File.file? file
+    end
+
+    def allowed_extension?(file)
+      file =~ /^.+.#{ALLOWED_EXTENSIONS.join('|')}/
+    end
+  end
+end

data/lib/maze_crosser/file_maze_definer.rb

@@ -0,0 +1,14 @@
+require_relative 'file_checker'
+require_relative 'helpers/file_helper'
+
+module MazeCrosser
+  # Module that contains a utilities for defining a maze grid from a file.
+  module FileMazeDefiner
+    include MazeCrosser::FileChecker
+
+    def define(file)
+      file = check(file)
+      MazeCrosser::FileHelper.file_to_array(file)
+    end
+  end
+end

data/lib/maze_crosser/helpers/file_helper.rb

@@ -0,0 +1,8 @@
+module MazeCrosser
+  # Module containing utilities for files.
+  module FileHelper
+    def self.file_to_array(file)
+      File.readlines(file).map { |line| line.strip.split('') }
+    end
+  end
+end

data/lib/maze_crosser/helpers/presentation_helper.rb

@@ -0,0 +1,9 @@
+module MazeCrosser
+  # Module containing utilities for presentation.
+  module PresentationHelper
+    def present_solution(solution)
+      return 'The maze has no solution.' if solution.empty?
+      "Solution: #{solution}"
+    end
+  end
+end

data/lib/maze_crosser/maze.rb

@@ -0,0 +1,61 @@
+require_relative 'basic_grid_validator'
+
+module MazeCrosser
+  # Class responsible for representing a maze.
+  #
+  # maze = Maze.new(grid)
+  #
+  # Check if the coordinates are inside the grid
+  # maze.inside_grid? [4, 2]
+  #
+  # Check if a cell is blocked
+  # maze.blocked_cell? [4, 2]
+  class Maze
+    include MazeCrosser::BasicGridValidator
+
+    attr_reader :grid,
+                :number_of_rows,
+                :number_of_columns,
+                :start,
+                :goal
+
+    def initialize(grid)
+      raise ArgumentError, 'Invalid maze' unless valid? grid
+
+      @grid = grid
+      set_dimensions
+      set_start
+      set_goal
+    end
+
+    def inside_grid?(coordinates)
+      coordinates[0].between?(0, @number_of_rows - 1) && \
+        coordinates[1].between?(0, @number_of_columns - 1)
+    end
+
+    def blocked_cell?(coordinates)
+      @grid[coordinates[0]][coordinates[1]] == ALLOWED_CHARACTERS[:blocked]
+    end
+
+    private
+
+    def set_dimensions
+      @number_of_rows = @grid.size
+      @number_of_columns = @grid[0].size
+    end
+
+    def set_start
+      @start = [
+        r = @grid.index { |row| row.include? ALLOWED_CHARACTERS[:start] },
+        @grid[r].index(ALLOWED_CHARACTERS[:start])
+      ]
+    end
+
+    def set_goal
+      @goal = [
+        r = @grid.index { |row| row.include? ALLOWED_CHARACTERS[:goal] },
+        @grid[r].index(ALLOWED_CHARACTERS[:goal])
+      ]
+    end
+  end
+end

data/lib/maze_crosser/maze_crosser_runner.rb

@@ -0,0 +1,50 @@
+require 'require_all'
+require_relative 'file_maze_definer'
+require_relative 'maze_solver'
+require_relative 'helpers/presentation_helper'
+require_relative 'maze'
+require_rel 'algorithms'
+
+module MazeCrosser
+  # Class responsible for running the application.
+  #
+  # maze_crosser_runner = MazerRunner.new
+  # maze_crosser_runner.run(file, algorithm)
+  class MazeCrosserRunner
+    include MazeCrosser::PresentationHelper
+    include MazeCrosser::FileMazeDefiner
+
+    def initialize(cache_provider)
+      @cache_provider = cache_provider
+    end
+
+    def run(file = nil, algorithm = 'recursive')
+      # When an additional grid import method is implemented (e.g. via CLI)
+      # the following should be done:
+      # 1) The line that raises ArgumentError should be removed
+      # 2) Grid assignment should be moved to a private method
+      raise ArgumentError, 'Please provide a file' unless file
+
+      grid = define(file) if file
+
+      maze = MazeCrosser::Maze.new(grid)
+      algorithm = load_algorithm(algorithm, maze)
+      present_solution(MazeSolver.new(maze, algorithm, @cache_provider).solve)
+    end
+
+    private
+
+    def load_algorithm(algorithm, maze)
+      # An alternative to this implementation would be to use metaprogramming
+      # and dynamically initialize the correct algorithm runner. Having said
+      # that, such an approach would be unsafe since it would involve the use
+      # of eval.
+      case algorithm
+      when 'recursive'
+        RecursiveAlgorithmRunner.new(maze)
+      else
+        raise ArgumentError, 'The algorithm does not exist.'
+      end
+    end
+  end
+end

data/lib/maze_crosser/maze_solver.rb

@@ -0,0 +1,24 @@
+module MazeCrosser
+  # Class responsible for solving a maze, by using a given algorithm or a
+  # cache.
+  #
+  # maze_solver = MazeSolver.new(maze, algorithm, cache_provider)
+  # maze_solver.solve
+  class MazeSolver
+    def initialize(maze, algorithm, cache_provider)
+      @algorithm = algorithm
+      @cache_provider = cache_provider
+      @maze = maze
+    end
+
+    def solve
+      if @cache_provider.get_solution(@maze.grid)
+        return @cache_provider.get_solution(@maze.grid)
+      end
+
+      solution = @algorithm.run
+      @cache_provider.add(@maze.grid, solution)
+      solution
+    end
+  end
+end

data/lib/maze_crosser/version.rb

@@ -0,0 +1,3 @@
+module MazeCrosser
+  VERSION = '0.1.0'.freeze
+end

data/lib/maze_crosser.rb

@@ -0,0 +1,6 @@
+require 'maze_crosser/version'
+require 'maze_crosser/maze_crosser_runner'
+require 'maze_crosser/cache_provider'
+
+@cache_provider = MazeCrosser::CacheProvider.new
+@maze_crosser_runner = MazeCrosser::MazeCrosserRunner.new(@cache_provider)

data/maze_crosser.gemspec

@@ -0,0 +1,37 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "maze_crosser/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "maze_crosser"
+  spec.version       = MazeCrosser::VERSION
+  spec.authors       = ["Kiriakos Velissariou"]
+  spec.email         = ["kir.velissariou@gmail.com"]
+
+  spec.summary       = %q{A simple 2d maze solving application}
+  spec.homepage      = "https://github.com/kiriakosv/maze_crosser"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org/"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.15"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "coveralls", "~> 0.8"  
+  spec.add_development_dependency "require_all", "~> 1.4"  
+end

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification
+name: maze_crosser
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kiriakos Velissariou
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-11-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: require_all
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: 
+email:
+- kir.velissariou@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/load
+- bin/setup
+- etc/general_information.md
+- lib/maze_crosser.rb
+- lib/maze_crosser/algorithms/recursive_algorithm_runner.rb
+- lib/maze_crosser/basic_grid_validator.rb
+- lib/maze_crosser/cache_provider.rb
+- lib/maze_crosser/file_checker.rb
+- lib/maze_crosser/file_maze_definer.rb
+- lib/maze_crosser/helpers/file_helper.rb
+- lib/maze_crosser/helpers/presentation_helper.rb
+- lib/maze_crosser/maze.rb
+- lib/maze_crosser/maze_crosser_runner.rb
+- lib/maze_crosser/maze_solver.rb
+- lib/maze_crosser/version.rb
+- maze_crosser.gemspec
+homepage: https://github.com/kiriakosv/maze_crosser
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org/
+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.6.11
+signing_key: 
+specification_version: 4
+summary: A simple 2d maze solving application
+test_files: []