combinatorial_puzzle_solver 0.1.0

data/Rakefile

@@ -0,0 +1,40 @@
+require "bundler/gem_tasks"
+Bundler.setup
+
+desc "Execute RSpec with default formatter"
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = "--format RSpec::Formatters::IllustratedDocumentationFormatter"
+end
+
+desc "Execute RSpec with HTML formatter"
+# RSpec - HTML output
+RSpec::Core::RakeTask.new(:html_spec) do |t|
+  t.rspec_opts = "--format RSpec::Formatters::IllustratedHtmlFormatter --out ./doc/rspec-results.html"
+end
+
+desc "Generate API documentation."
+require 'yard'
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files   = ['lib/**/*.rb', '-', 'doc/rspec-results.html', 'doc/examples.md' ]
+end
+task :doc => [:html_spec, :examples]
+
+desc "List the undocumented code."
+YARD::Rake::YardocTask.new(:list_undoc) do |t|
+  t.stats_options = ['--list-undoc']
+end
+
+# Generate examples and documentation
+require_relative 'example_puzzles/compile_examples'
+task :examples => ['doc/examples.md']
+file 'doc/examples.md' => FileList["example_puzzles/*"] do
+  markdown = compile_examples_to_markdown(Dir.glob('example_puzzles/*.yaml'))
+  File.write('doc/examples.md', markdown)
+  $stderr.puts "examples ok!"
+end
+
+
+task :test => [:spec, :examples]
+task :default => :doc
+

data/bin/setup

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

data/combinatorial_puzzle_solver.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'combinatorial_puzzle_solver/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "combinatorial_puzzle_solver"
+  spec.version       = CombinatorialPuzzleSolver::VERSION
+  spec.authors       = ["Erik Schlyter"]
+  spec.email         = ["erik@erisc.se"]
+
+  spec.summary       = %q{A resolver of combinatorial number-placement puzzles, like Sudoku.}
+  spec.description   = %q{A resolver of combinatorial number-placement puzzles, like Sudoku.}
+  spec.homepage      = "https://github.com/ErikSchlyter/combinatorial_puzzle_solver"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.8"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec-illustrate", "~> 0.1.3"
+
+  spec.add_development_dependency "yard", "~>  0.8.7.6"
+  spec.add_development_dependency "redcarpet", "~>  3.2.2"
+
+end

data/example_puzzles/4x4

@@ -0,0 +1 @@
+this is a tiny puzzle 0040100000030100

data/example_puzzles/compile_examples.rb

@@ -0,0 +1,116 @@
+#!/usr/bin/env ruby
+require 'yaml'
+require 'open3'
+
+# Reads documentation and test examples from YAML (examples.yaml) files and compiles
+# it into a markdown doucument.
+#
+# @param yaml_files [Array<String>] the yaml files to parse
+# @return [String] the compiled markdown document.
+def compile_examples_to_markdown(yaml_files)
+  compile(yaml_files.collect{|yaml_file| YAML.load_file(yaml_file)})
+end
+
+# Compiles a given node of the YAML tree into markdown.
+# - If the node is an Array, it will be compiled and concatenated.
+# - If the node contains :section, it will be compiled recursively.
+# - If the node contains :example, it is an example that will be executed.
+# - If the node contains :comment, it is a paragraph.
+#
+# @param node [Object] the object that was parsed from the YAML document.
+# @param level [Fixnum] the current subsection level.
+# @return [String] the examples compiled into markdown.
+def compile(node, level=1)
+  return node.collect{|e| compile(e,level)}.join("\n") if node.is_a?(Array)
+
+  if node.has_key?(:section) then
+    "#{("#"*level)}#{node[:section]}\n" <<
+    "#{node[:comment]}\n" <<
+    compile(node[:content], level+1)
+
+  elsif node.has_key?(:example)
+    example_to_markdown(verify(execute(node)), level)
+
+  elsif node.has_key?(:comment)
+    "#{node[:comment]}\n"
+
+  end
+end
+
+# @param example [Hash] the example originally described in YAML.
+# @param level [Fixnum] the subsection level
+# @return [String] the example formatted in markdown
+def example_to_markdown(example, level)
+  md = ""
+
+  if example[:example] != "" then
+    md << "#{("#"*(level))}#{example[:example]}\n\n"
+  end
+
+  if example[:comment] then
+    md << example[:comment].to_s << "\n" 
+  end
+
+  example[:input_files].each{|filename|
+    md << "Given the file `#{filename}`:\n"
+    md << block(IO.read(filename))
+  }
+
+  if example[:input] then
+    md << "Given the following input on stdin:\n"
+    md << block(example[:input])
+  end
+
+  md << "Invoking `#{example[:command]}` will return exit code " <<
+        "`#{example[:exit_code]}` and output:\n"
+  md << block(example[:stdout])
+
+  md
+end
+
+# @return [String] the given string formatted as a markdown code block.
+def block(string)
+  "\n\t#{string.gsub(/\n/,"\n\t")}\n\n"
+end
+
+# Executes an example and stores output and exit code in the hash.
+#
+# @param example [Hash] the example originally described in YAML.
+# @return [Hash] the example
+def execute(example)
+  argv = example[:input_files] + example[:argv]
+  example[:command] = "./solve_sudoku #{argv.join(' ')}"
+  full_command = "./exe/#{example[:command]}"
+
+  Open3.popen3(full_command) {|stdin, stdout, stderr, wait_thr|
+    stdin.write(example[:input]) if example[:input]
+
+    example[:exit_code] = wait_thr.value.to_i
+    example[:stdout] = stdout.read
+    example[:stderr] = stderr.read
+  }
+  example
+end
+
+# Compares exit code and expected output to assert example executes correctly.
+#
+# @param example [Hash] the example to verify
+# @return [Hash] the verified example
+def verify(example)
+  if example[:expected_output] then
+    if example[:expected_output].strip != example[:stdout].strip then
+      $stderr.puts "Expected:----\n#{example[:expected_output]}\n----"
+      $stderr.puts "Stdout:------\n#{example[:stdout]}\n----"
+      puts example.to_yaml
+      fail "expected output did not match."
+    end
+  end
+
+  if example[:expected_exit_code] then
+    if example[:expected_exit_code] != example[:exit_code] then
+      $stderr.puts example.to_yaml
+      fail "Wrong exit code"
+    end
+  end
+  example
+end

data/example_puzzles/examples.yaml

@@ -0,0 +1,243 @@
+---
+:section: Sudoku Solver
+:content:
+- :comment: >
+    The program `solve_sudoku` reads sudoku puzzles from files
+    (or stdin, if no filenames is given) and solves them by
+    constraint resolution. If constraint resolution is not enough
+    to solve the puzzle, it will resort to a trial and error
+    approach. The exit code will indicate if all parsed puzzles
+    was completely solved or not.
+
+    Each resolution step and the current state of the puzzle can
+    be written to stdout for diagnostic purposes. It is also
+    possible to abort after a given number of steps if a complete
+    resolution is not desired, which would be the case if you only
+    want a couple of clues.
+
+    Note that the step output and abort functionality is not
+    available when the puzzle is solved by trial and error.
+
+    The default behavior is resolve all given puzzles (with trial
+    and error, if neccessary) and indicate by exit status whether
+    all puzzles where completely resolved. No output is given
+    unless explicitly asked for.
+
+- :example: Printing the parsed puzzles, `-i`.
+  :comment: >
+    The parser will interpret digits (0-9) as values in the puzzle
+    and disregard anything else. The option `-i` will output the
+    parsed puzzle before it solves it.
+  :input_files:
+  - example_puzzles/simple
+  :argv:
+  - -i
+  :expected_exit_code: 0
+  :expected_output: |
+    9   6|8 1 3|5 4  
+    2   1|  4 5|  6 3
+      4  |     |     
+    -----+-----+-----
+         |6 2  |    9
+        9|     |2    
+    7    |  3 4|     
+    -----+-----+-----
+         |     |  9  
+    5 9  |3 6  |1   4
+      2 7|4 5 9|3   6
+- :example: "Parsing several puzzles at the same time"
+  :input_files:
+  - example_puzzles/simple
+  - example_puzzles/medium
+  :argv:
+  - -i
+  :expected_exit_code: 0
+  :expected_output: |
+    9   6|8 1 3|5 4  
+    2   1|  4 5|  6 3
+      4  |     |     
+    -----+-----+-----
+         |6 2  |    9
+        9|     |2    
+    7    |  3 4|     
+    -----+-----+-----
+         |     |  9  
+    5 9  |3 6  |1   4
+      2 7|4 5 9|3   6
+
+         |3   1|     
+        9|     |     
+      8  |     |  3  
+    -----+-----+-----
+         |    4|9 8  
+        7|1 2  |5    
+    2    |  9  |1 7  
+    -----+-----+-----
+      5  |  1 2|     
+      9  |    7|     
+    3    |4   5|    8
+- :example: Parsing 4x4 puzzles, `-4`, `-4x4`.
+  :input_files:
+  - example_puzzles/4x4
+  :argv:
+  - -i
+  - -4
+  :expected_exit_code: 0
+  :expected_output: "   |4  \n1  |   \n---+---\n   |  3\n  1|   \n\n"
+
+- :example: Printing the output, `-o`.
+  :input_files:
+  - example_puzzles/simple
+  :argv:
+  - -o
+  :expected_exit_code: 0
+  :expected_output: |
+    9 7 6|8 1 3|5 4 2
+    2 8 1|7 4 5|9 6 3
+    3 4 5|2 9 6|8 1 7
+    -----+-----+-----
+    8 5 3|6 2 1|4 7 9
+    4 6 9|5 7 8|2 3 1
+    7 1 2|9 3 4|6 5 8
+    -----+-----+-----
+    6 3 4|1 8 2|7 9 5
+    5 9 8|3 6 7|1 2 4
+    1 2 7|4 5 9|3 8 6
+- :example: Printing the resolution steps, `-s`.
+  :input_files:
+  - example_puzzles/simple
+  :argv:
+  - -o -s
+  :expected_exit_code: 0
+  :expected_output: |
+    [1,2]=7
+    [8,3]=8
+    [9,8]=8
+    [1,9]=2
+    [2,2]=8
+    [9,1]=1
+    [7,7]=7
+    [3,1]=3
+    [7,5]=8
+    [7,9]=5
+    [2,7]=9
+    [8,8]=2
+    [3,3]=5
+    [5,5]=7
+    [2,4]=7
+    [3,7]=8
+    [8,6]=7
+    [6,3]=2
+    [3,5]=9
+    [4,7]=4
+    [6,7]=6
+    [3,4]=2
+    [4,1]=8
+    [4,3]=3
+    [3,6]=6
+    [7,4]=1
+    [4,6]=1
+    [7,3]=4
+    [7,6]=2
+    [5,4]=5
+    [4,2]=5
+    [5,6]=8
+    [7,1]=6
+    [6,4]=9
+    [4,8]=7
+    [6,2]=1
+    [5,9]=1
+    [7,2]=3
+    [5,1]=4
+    [3,8]=1
+    [6,8]=5
+    [6,9]=8
+    [5,2]=6
+    [5,8]=3
+    [3,9]=7
+    9 7 6|8 1 3|5 4 2
+    2 8 1|7 4 5|9 6 3
+    3 4 5|2 9 6|8 1 7
+    -----+-----+-----
+    8 5 3|6 2 1|4 7 9
+    4 6 9|5 7 8|2 3 1
+    7 1 2|9 3 4|6 5 8
+    -----+-----+-----
+    6 3 4|1 8 2|7 9 5
+    5 9 8|3 6 7|1 2 4
+    1 2 7|4 5 9|3 8 6
+
+- :example: Printing the entire puzzle for each resolution step, `-p`.
+  :input_files:
+  - example_puzzles/4x4
+  :argv:
+  - --4x4 -p
+  :expected_exit_code: 0
+  #
+  # this output looks really bad since YAML doesn't support ASCII art that
+  # starts with spaces, which is the case of certain puzzles.
+  #
+  :expected_output: ! "   |4  \n1  |  2\n---+---\n   |  3\n  1|   \n\n   |4  \n1  |  2\n---+---\n
+    \  |  3\n  1|2  \n\n   |4  \n1  |3 2\n---+---\n   |  3\n  1|2  \n\n   |4 1\n1  |3
+      2\n---+---\n   |  3\n  1|2  \n\n   |4 1\n1  |3 2\n---+---\n   |  3\n  1|2 4\n\n
+        \  |4 1\n1  |3 2\n---+---\n   |1 3\n  1|2 4\n\n   |4 1\n1 4|3 2\n---+---\n   |1
+          3\n  1|2 4\n\n   |4 1\n1 4|3 2\n---+---\n   |1 3\n3 1|2 4\n\n   |4 1\n1 4|3 2\n---+---\n
+            \ 2|1 3\n3 1|2 4\n\n2  |4 1\n1 4|3 2\n---+---\n  2|1 3\n3 1|2 4\n\n2  |4 1\n1 4|3
+              2\n---+---\n4 2|1 3\n3 1|2 4\n\n2 3|4 1\n1 4|3 2\n---+---\n4 2|1 3\n3 1|2 4\n\n"
+
+- :example: Use constraint resolution only, `-r`.
+  :comment: >
+    You can avoid the trial and error functionality. Note though that this might not
+    lead to a completely solved puzzle, which would imply a failure return code.
+
+    The input and incomplete result is demonstrated below.
+
+  :input_files:
+  - example_puzzles/medium
+  :argv:
+  - -i -o -r
+  :expected_exit_code: 256
+  #
+  # this puzzle looks really bad since YAML doesn't support ASCII art that
+  # starts with spaces, which is the case of certain puzzles.
+  #
+  :expected_output: ! "     |3   1|     \n    9|     |     \n  8  |     |  3  \n-----+-----+-----\n
+    \    |    4|9 8  \n    7|1 2  |5    \n2    |  9  |1 7  \n-----+-----+-----\n  5
+      \ |  1 2|     \n  9  |    7|     \n3    |4   5|    8\n\n  2  |3 8 1|  5 9\n  3 9|7
+        5 6|8 2  \n  8 5|2 4 9|  3  \n-----+-----+-----\n5 1 3|6 7 4|9 8 2\n9   7|1 2 8|5
+          \  3\n2   8|5 9 3|1 7  \n-----+-----+-----\n8 5  |9 1 2|3   7\n  9 2|8 3 7|  1 5\n3
+            7 1|4 6 5|2 9 8\n\n"
+
+- :example: ""
+  :input_files:
+  - example_puzzles/hard
+  :argv:
+  - -i -o -r
+  :expected_exit_code: 256
+  #
+  # this puzzle looks really bad since YAML doesn't support ASCII art that
+  # starts with spaces, which is the case of certain puzzles.
+  #
+  :expected_output: ! "     |2    |  6 3\n3    |    5|4   1\n    1|    3|9 8  \n-----+-----+-----\n
+    \    |     |  9  \n     |5 3 8|     \n  3  |     |     \n-----+-----+-----\n  2
+      6|3    |5    \n5   3|7    |    8\n4 7  |    1|     \n\n     |2 1  |7 6 3\n3   7|
+        \   5|4 2 1\n2   1|  7 3|9 8 5\n-----+-----+-----\n     |     |3 9  \n     |5 3
+          8|     \n  3  |     |8 5  \n-----+-----+-----\n  2 6|3    |5    \n5   3|7    |    8\n4
+            7  |  5 1|  3  \n\n"
+
+
+- :example: Abort after a given number of steps, `-c NUM`, `--clues NUM`.
+  :comment: >
+      If you don't want the entire puzzle solved, but just a couple of clues on
+      how to get forward, you can abort the resolution with `-c`, and print each
+      step with  `-s`.
+  :input_files:
+  - example_puzzles/simple
+  :argv:
+  - "-s"
+  - "-c 3"
+  :expected_exit_code: 0
+  :expected_output: |
+    [1,2]=7
+    [8,3]=8
+    [9,8]=8

data/example_puzzles/hard

@@ -0,0 +1,11 @@
+000|200|063
+300|005|401
+001|003|980
+---+---+---
+000|000|090
+000|538|000
+030|000|000
+---+---+---
+026|300|500
+503|700|008
+470|001|000