bfs_brute_force 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d9930b15a9a8a806ab35bd20859d81154d3cd8c2
+  data.tar.gz: 5f86c835cef8195335c7c522bce1b4b9b3d60f09
+SHA512:
+  metadata.gz: 482eaa39bd9e01336086bb52ef921f811b43166095bb5268db83c0b46a8b3728d924b4e23d9c1419810dc7bcdff9d65ad4aa6a111ad6bb2c35a4148820f2ef67
+  data.tar.gz: f4118407512dc990b627e8fb5479de802c89601d73d9f9f6eccefa5514cf50d453995fd8a25c3bbd59519e095427949c361775e82e262e33649f46cd87d148a9

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.ruby-gemset

@@ -0,0 +1 @@
+bfs_brute_force

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.1.4

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in bfs_brute_force.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Joe Sortelli
+
+MIT License
+
+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,122 @@
+# BfsBruteForce
+
+Lazy breadth first brute force search for solutions to puzzles.
+
+This ruby gem provides an API for representing the initial state
+and allowed next states of a puzzle, reachable through user defined
+moves. The framework also provides a simple solver which will lazily
+evaluate all the states in a breadth first manner to find a solution
+state, returning the list of moves required to transition from the
+initial state to solution state.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'bfs_brute_force'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install bfs_brute_force
+
+## Usage
+
+Your puzzle must be represented by a subclass of ```BfsBruteForce::State```.
+Each instance of your State subclass must:
+
+1. Store the current state of the puzzle (instance attributes)
+2. Determine if the state is a win condition of the puzzle (```solved?```)
+3. Provide a generator for reaching all possible next states (```next_states```)
+
+### Example Puzzle
+
+Imagine a simple puzzle where you are given a starting number, an
+ending number, and you can only perform one of three addition
+operations (adding one, ten, or one hundred).
+
+To use ```BfsBruteForce``` you will create your
+```BfsBruteForce::State``` subclass as follows:
+    require 'bfs_brute_force'
+
+    class AdditionPuzzleState < BfsBruteForce::State
+      attr_reader :value
+
+      def initialize(start, final)
+        @start = start
+        @value = start
+        @final = final
+      end
+
+      def solved?
+        @value == @final
+      end
+
+      def to_s
+        "<#{self.class} puzzle from #{@start} to #{@final}>"
+      end
+
+      def next_states(already_seen)
+        return if @value > @final
+
+        [1, 10, 100].each do |n|
+          new_value = @value + n
+          if already_seen.add?(new_value)
+            yield "Add #{n}", AdditionPuzzleState.new(new_value, @final)
+          end
+        end
+      end
+    end
+
+Each instance of ```AdditionPuzzleState``` is immutable. The
+```next_states``` method takes a single argument, which is a ```Set```
+instance, that can be optionally used by your implementation to
+record states that have already been evaluated, as any previously
+evaluated state is already known to not be a solution.
+
+Inside of ```next_states``` you should yield two arguments for every
+valid next state of the puzzle:
+
+1. A string, naming the move required to get to the next state
+2. The next state, as a new instance of your ```BfsBruteForce::State``` class.
+
+Now that you have your ```BfsBruteForce::State``` class, you can
+initialize it with your starting puzzle state, and pass it to
+```BfsBruteForce::Solver#solve```, which will return an object that
+has a ```moves``` method, which returns an array of the move
+names yielded by your ```next_states``` method:
+
+    solver   = BfsBruteForce::Solver.new
+    solution = solver.solve(AdditionPuzzleState.new(0, 42))
+
+    solution.moves.each_with_index do |move, index|
+      puts "Move %02d) %s" % [index + 1, move]
+    end
+
+## License
+
+Copyright (c) 2014 Joe Sortelli
+
+MIT License
+
+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/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/*.rb']
+end
+
+task :build => :test

data/bfs_brute_force.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bfs_brute_force/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "bfs_brute_force"
+  spec.version       = BfsBruteForce::VERSION
+  spec.authors       = ["Joe Sortelli"]
+  spec.email         = ["joe@sortelli.com"]
+  spec.summary       = "Lazy breadth first brute force search for solutions to puzzles"
+  spec.description   = %q{
+    Provides an API for representing the initial state and allowed
+    next states of a puzzle, reachable through user defined moves.
+    The framework also provides a simple solver which will lazily
+    evaluate all the states in a breadth first manner to find a
+    solution state, returning the list of moves required to transition
+    from the initial state to solution state.
+  }
+  spec.homepage      = "https://github.com/sortelli/bfs_brute_force"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 4.7"
+end

data/lib/bfs_brute_force/version.rb

@@ -0,0 +1,3 @@
+module BfsBruteForce
+  VERSION = "0.1.0"
+end

data/lib/bfs_brute_force.rb

@@ -0,0 +1,145 @@
+require "bfs_brute_force/version"
+require "set"
+
+# Top level module for this framework
+module BfsBruteForce
+  # Exception thrown by {Solver#solve}
+  class NoSolution < StandardError
+    # @param num_of_solutions_tried [Fixnum] number of solutions previously tried
+    def initialize(num_of_solutions_tried)
+      super("No solution in #{num_of_solutions_tried} tries. There are no more states to analyze")
+    end
+  end
+
+  # Context object that contains a State and a list of moves required
+  # to reach that State from the initial State.
+  #
+  # @!attribute state [r]
+  #    @return [State] the current state
+  #
+  # @!attribute moves [r]
+  #    @return [Array] the list of moves to this state from
+  #      the initial state
+  class Context
+    attr_reader :state, :moves
+
+    # @param state        [State]  current state
+    # @param already_seen [Set]    set of states already processed
+    # @param moves        [Array]  list of moves to get to this state
+    def initialize(state, already_seen = Set.new, moves = [])
+      @state        = state
+      @already_seen = already_seen
+      @moves        = moves
+    end
+
+    # Check if current state is a solution
+    # @return [Boolean]
+    def solved?
+      @state.solved?
+    end
+
+    # Generate all contexts that can be reached from this current context
+    # @return [void]
+    # @yieldparam next_context [Context] next context
+    def next_contexts
+      @state.next_states(@already_seen) do |next_move, next_state|
+        yield Context.new(next_state, @already_seen, @moves + [next_move])
+      end
+    end
+  end
+
+  # Single state in a puzzle. Represent your puzzle as
+  # a subclass of {State}.
+  #
+  # @abstract Override {#next_states}, {#to_s} and {#solved?}
+  class State
+    # Your implementation should yield a (move,state) pair for every
+    # state reachable by the current state.
+    #
+    # You should make use of the already_seen set to only yield
+    # states that have not previously been yielded.
+    #
+    # @example Use already_seen to only yield states not already yielded
+    #   def next_states(already_seen)
+    #     next_value = @my_value + 100
+    #
+    #     # See {Set#add?}. Returns nil value is already in the Set.
+    #     if already_seen.add?(next_value)
+    #       yield "Add 100", MyState.new(next_value)
+    #     end
+    #   end
+    #
+    # @param already_seen [Set] Set of all already processed states
+    #
+    # @yield [move, state]
+    # @yieldparam move  [#to_s] Text description of a state transition
+    # @yieldparam state [State] New state, reachable from current state with
+    #                           the provided move
+    #
+    # @raise [NotImplementedError] if you failed to provide your own implementation
+    # @return [void]
+    def next_states(already_seen)
+      raise NotImplementedError, "next_states is not implemented yet"
+    end
+
+    # Returns true if current state is a solution to the puzzle.
+    #
+    # @raise [NotImplementedError] if you failed to provide your own implementation
+    # @return [Boolean]
+    def solved?
+      raise NotImplementedError, "solved? is not implemented yet"
+    end
+  end
+
+  # Lazy breadth first puzzle solver
+  class Solver
+    # Find a list of moves from the starting state of the puzzle to a solution state.
+    #
+    # @param initial_state [State] Initial state of your puzzle
+    # @param status        [#<<]   IO object to receive status messages
+    #
+    # @raise [NoSolution] No solution is found
+    # @return [Context] Solved Context object has the final {State} and list of moves
+    def solve(initial_state, status = $stdout)
+      status << "Looking for solution for:\n#{initial_state}\n\n"
+
+      initial_context = Context.new(initial_state)
+
+      if initial_context.solved?
+        status << "Good news, its already solved\n"
+        return initial_context
+      end
+
+      tries    = 0
+      contexts = [initial_context]
+
+      until contexts.empty?
+        status << ("Checking for solutions that take %4d moves ... " % [
+          contexts.first.moves.size + 1
+        ])
+
+        new_contexts = []
+
+        contexts.each do |current_context|
+          current_context.next_contexts do |context|
+            tries += 1
+
+            if context.solved?
+              status << "solved in #{tries} tries\n\nMoves:\n"
+              context.moves.each {|m| status << "  #{m}\n"}
+              status << "\nFinal state:\n #{context.state}\n"
+              return context
+            end
+
+            new_contexts << context
+          end
+        end
+
+        contexts = new_contexts
+        status << ("none in %9d new states\n" % contexts.size)
+      end
+
+      raise NoSolution.new(tries)
+    end
+  end
+end

data/test/basic.rb

@@ -0,0 +1,46 @@
+require "minitest/autorun"
+require "bfs_brute_force"
+
+class AlreadySolvedState < BfsBruteForce::State
+  def solved?
+    true
+  end
+end
+
+class BrokenState < BfsBruteForce::State
+  def solved?
+    false
+  end
+end
+
+class TestBasic < Minitest::Unit::TestCase
+  def test_module_exists
+    mod_key = :BfsBruteForce
+    assert Kernel.const_defined?(mod_key), "Module #{mod_key} missing"
+
+    mod = Kernel.const_get mod_key
+    %w{Context State Solver}.each do |c|
+      assert mod.const_defined?(c), "Class #{mod}::#{c} missing"
+    end
+  end
+
+  def test_already_solved
+    state  = AlreadySolvedState.new
+    solver = BfsBruteForce::Solver.new
+
+    assert_raises(NotImplementedError) {state.next_states(nil)}
+    assert state.solved?
+
+    solver.solve state, []
+  end
+
+  def test_broken
+    state  = BrokenState.new
+    solver = BfsBruteForce::Solver.new
+
+    assert_raises(NotImplementedError) {state.next_states(nil)}
+    refute state.solved?
+
+    assert_raises(NotImplementedError) { solver.solve(state, []) }
+  end
+end

data/test/simple_puzzle.rb

@@ -0,0 +1,91 @@
+require "minitest/autorun"
+require "bfs_brute_force"
+
+class SimplePuzzleState < BfsBruteForce::State
+  attr_reader :value
+
+  def initialize(start, final)
+    @start = start
+    @value = start
+    @final = final
+  end
+
+  def solved?
+    @value == @final
+  end
+
+  def to_s
+    "<#{self.class} puzzle from #{@start} to #{@final}>"
+  end
+
+  def next_states(already_seen)
+    return if @value > @final
+
+    [1, 10, 100].each do |n|
+      new_value = @value + n
+      if already_seen.add?(new_value)
+        yield "Add #{n}", SimplePuzzleState.new(new_value, @final)
+      end
+    end
+  end
+end
+
+class SlightlyHarderPuzzleState < SimplePuzzleState
+  def next_states(already_seen)
+    [10, 100].each do |n|
+      new_value = @value + n
+      if already_seen.add?(new_value)
+        yield "Add #{n}", SlightlyHarderPuzzleState.new(new_value, @final)
+      end
+    end
+
+    new_value = @value - 1
+    if already_seen.add?(new_value)
+      yield "Subtract 1", SlightlyHarderPuzzleState.new(new_value, @final)
+    end
+  end
+end
+
+class TestSimplePuzzle < Minitest::Unit::TestCase
+  def test_simple_puzzle
+    [
+      [0, 42,  ["Add 1"]  * 2 + ["Add 10"] * 4],
+      [2, 42,  ["Add 10"] * 4],
+      [3, 427, ["Add 1"]  * 4 + ["Add 10"] * 2 + ["Add 100"] * 4]
+    ].each do |args|
+      solve_puzzle(SimplePuzzleState, *args)
+    end
+
+    assert_raises(BfsBruteForce::NoSolution) do
+      solve_puzzle(SimplePuzzleState, 3, 2, [])
+    end
+  end
+
+  def test_slightly_harder_puzzle
+    [
+      [0, 42,  ["Add 10"] * 5 + ["Subtract 1"] * 8],
+      [2, 42,  ["Add 10"] * 4],
+      [3, 427, ["Add 10"] * 3 + ["Add 100"] * 4 + ["Subtract 1"] * 6]
+    ].each do |args|
+      solve_puzzle(SlightlyHarderPuzzleState, *args)
+    end
+  end
+
+  def solve_puzzle(type, start, final, expected_moves)
+    state  = type.new(start, final)
+    solver = BfsBruteForce::Solver.new
+
+    refute state.solved?, "Not already solved"
+
+    context = solver.solve state
+
+    assert_instance_of(BfsBruteForce::Context, context)
+    assert_instance_of(type, context.state)
+    assert_instance_of(Array, context.moves)
+
+    assert context.solved?
+    assert context.state.solved?
+    assert_equal context.state.value, final
+    assert_equal expected_moves, context.moves
+  end
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: bfs_brute_force
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joe Sortelli
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-12-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !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: '4.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+description: "\n    Provides an API for representing the initial state and allowed\n
+  \   next states of a puzzle, reachable through user defined moves.\n    The framework
+  also provides a simple solver which will lazily\n    evaluate all the states in
+  a breadth first manner to find a\n    solution state, returning the list of moves
+  required to transition\n    from the initial state to solution state.\n  "
+email:
+- joe@sortelli.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".ruby-gemset"
+- ".ruby-version"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bfs_brute_force.gemspec
+- lib/bfs_brute_force.rb
+- lib/bfs_brute_force/version.rb
+- test/basic.rb
+- test/simple_puzzle.rb
+homepage: https://github.com/sortelli/bfs_brute_force
+licenses:
+- MIT
+metadata: {}
+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.4.4
+signing_key: 
+specification_version: 4
+summary: Lazy breadth first brute force search for solutions to puzzles
+test_files:
+- test/basic.rb
+- test/simple_puzzle.rb