conditional_sample 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 66f4bd90cb090564aa82b8fcf2542ee09be6d90e
+  data.tar.gz: d92cfeb38c8587e14a787c22865dd393b1ca953f
+SHA512:
+  metadata.gz: 4849a931094f7dc5577632fc630216ae22a6c28dd1f9fff08e7aaf8303f52b10a9f13e1ee5495e2a698bcd98adef440e099b7875f37dae760ace83a0db3ae161
+  data.tar.gz: 76a8a68232ec62e2a83e52d23708b669e41d7fcfe009a1e6b09689621fdd021e69a8edfeaa84f1f14955dc1eacc82de7544ba0e7ff8d5f2649fa56f7b4134510

data/.gitignore

@@ -0,0 +1,68 @@
+
+################################################################################
+# Ruby specific files
+
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+################################################################################
+# Rails stuff
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+# Ignore Byebug command history file.
+.byebug_history
+
+# Ignore application configuration
+/config/application.yml
+
+################################################################################
+# System and config files
+
+desktop.ini
+.agignore
+.ignore
+
+################################################################################
+# App specific files
+
+# Development files
+work*.rb
+/~/

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1 @@
+gemspec

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright (C) 2017 Paul Thompson
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+Full text of this licence: <https://www.gnu.org/licenses/gpl.html>.

data/README.md

@@ -0,0 +1,348 @@
+# Conditional Sample
+
+by Paul Thompson - nossidge@gmail.com
+
+This is a Ruby gem that will patch the Array class with a couple of
+nice methods for sampling based on the results of an array of Boolean
+procs. Array is sampled using the procs as conditions that each specific
+array index element must conform to.
+
+I'm using this primarily for procedural generation, where I have an
+array of possible values and a certain sample I need, or order in which
+I want the values arranged.
+
+This code was spun off into a gem from my poetry generation project
+https://github.com/nossidge/poefy
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'conditional_sample'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install conditional_sample
+
+
+## Usage
+
+When you require the gem, two extra methods are added to Array.
+
+```ruby
+array.conditional_permutation(conditions, seconds)
+array.conditional_sample(conditions, seconds)
+```
+
+`#conditional_permutation` returns a permutation of the array where
+each element validates to the same index in a 'conditions' array of
+procs that return Boolean. At the end of the 'conditions' array, if
+there are any elements in the array that have not been assigned, they
+are appended without comparison.
+
+`#conditional_sample` returns values from 'array' where each element
+validates to the same index in a 'conditions' array of procs that
+return Boolean. At the end of the 'conditions' array, no further
+elements from the input array are appended.
+
+
+### The 'conditions' argument
+
+This is an array of boolean procs that evaluate true if an element is
+allowed to be placed in that position.
+The arguments for each proc are |arr, elem|
+* **arr**  is a reference to the current array that has been built up
+           through the recursion chain.
+* **elem** is a reference to the current element being considered.
+
+
+### The 'seconds' argument
+
+This optional argument will force the method to give up and return an
+empty array after a given number of seconds.
+
+If you've ever tried to run `Array#permutation` on an array of even a
+seemingly moderate size, you will know that it is very computationally
+expensive. The results are [factorial][1], and get exponentially larger
+the more elements there are in the input array.
+
+For example, this code takes my machine two whole minutes to run.
+```ruby
+puts (1..12).to_a.permutation.count
+```
+
+These methods are not usually as computationally expensive, as there is
+only one array for the output, but they can take a very long time to run
+depending on how many rejected permutations there are before a valid one.
+If there are no valid permutations for the given conditions array, all
+permutations will be compared before simply outputting an empty array.
+And that will take even longer than `Array#permutation`.
+
+The methods have an optional argument to assuage this. This takes a
+number that represents a time in seconds (which can be a fraction) and
+returns an empty array if a valid sample is not found in that time.
+
+Below is an example. If it fails to resolve in, say, two seconds, then
+it's probably not possible to fit the conditions to the lines:
+
+```ruby
+lines.shuffle.conditional_sample(conditions, 2)
+```
+
+This is **strongly** recommended when first developing a project, as it
+may not be transparent how computationally expensive a condition array
+will be, especially on input arrays larger than about 10.
+
+**It's really useful, honest. I wouldn't have built this in to the
+methods if it wasn't super needed.**
+
+Example programs can be found in the `spec` directory.
+
+[1]: https://en.wikipedia.org/wiki/Factorial
+
+
+## Examples
+
+All of these examples can be found in `spec/examples_spec.rb`, and
+are evaluated when using the `$ rspec` or `$ rake test` commands.
+
+
+### Basic example
+
+```ruby
+# 5 element input array.
+numbers = (1..5).to_a
+
+# 3 element conditions array.
+conditions = [
+  proc { |arr, elem| elem < 3 },
+  proc { |arr, elem| elem > 3 },
+  proc { |arr, elem| elem > 1 }
+]
+
+# These will always return the below output
+# because they are the first values that match.
+permut = numbers.conditional_permutation(conditions)
+sample = numbers.conditional_sample(conditions)
+p permut  # => [1, 4, 2, 3, 5]
+p sample  # => [1, 4, 2]
+
+# To get a random sample, #shuffle the array first.
+# These results will vary based on the shuffle.
+shuf = numbers.shuffle
+shuf_permut = shuf.conditional_permutation(conditions)
+shuf_sample = shuf.conditional_sample(conditions)
+p shuf_permut  # => [2, 5, 4, 1, 3]
+p shuf_sample  # => [2, 5, 4]
+```
+
+
+### Random rhyming lines
+
+A really simple way to extract rhyming lines from an input array.
+
+```ruby
+# Use this gem to get the rhyme of the line's final word.
+require 'ruby_rhymes'
+
+# Input lines, just two limericks concat together.
+lines = [
+  "There was a young rustic named Mallory,",
+  "who drew but a very small salary.",
+  "When he went to the show,",
+  "his purse made him go",
+  "to a seat in the uppermost gallery.",
+  "There was an Old Man with a beard,",
+  "Who said, 'It is just as I feared!—",
+  "Two Owls and a Hen,",
+  "four Larks and a Wren,",
+  "Have all built their nests in my beard.'"
+]
+
+# Output a couplet of any two lines that rhyme.
+couplet_conditions = [
+  proc { |arr, elem| true },
+  proc { |arr, elem| elem.to_phrase.rhyme_key == arr.last.to_phrase.rhyme_key }
+]
+puts lines.shuffle.conditional_sample(couplet_conditions)
+#   Who said, 'It is just as I feared!—
+#   There was an Old Man with a beard,
+
+# Output a jumbled limerick from the input lines.
+limerick_conditions = [
+  proc { |arr, elem| true },
+  proc { |arr, elem| elem.to_phrase.rhyme_key == arr[0].to_phrase.rhyme_key },
+  proc { |arr, elem| elem.to_phrase.rhyme_key != arr[0].to_phrase.rhyme_key },
+  proc { |arr, elem| elem.to_phrase.rhyme_key == arr[2].to_phrase.rhyme_key },
+  proc { |arr, elem| elem.to_phrase.rhyme_key == arr[0].to_phrase.rhyme_key }
+]
+puts lines.shuffle.conditional_sample(limerick_conditions)
+#   to a seat in the uppermost gallery.
+#   who drew but a very small salary.
+#   Two Owls and a Hen,
+#   four Larks and a Wren,
+#   There was a young rustic named Mallory,
+```
+
+
+### Logic puzzle
+
+You can use this to solve simple one-dimensional logic puzzles, such as
+determining seating order, or racehorse results. Here's an example I just
+made up:
+
+**It's E's birthday!** Her good buddies have invited her for a big ol'
+birthday meal at the fanciest restaurant in the whole prefecture. They'll
+be sitting at the Top Bench, getting to look down at all the nonbirthdaying
+plebs. E's gonna love it! All that needs sorting out now is the seating
+arrangement, but A isn't worried. He knows he just has to follow the simple
+rules below:
+
+1. E has to be in the middle, obviously. It's her birthday!
+2. B and D are besties. They must always sit together.
+3. B and E are beasties. They can't sit together, or they'll beast out
+   all over each other.
+4. For religious reasons, C and D must have exactly two people between them.
+5. For different (but equally culturally valid) religious reasons, A must
+   always sit to the left of C.
+
+```ruby
+# Create an array of procs, one for each rule.
+rules = []
+
+# E has to be in the middle.
+rules << proc do |arr, elem|
+  !(arr.count == 2) || elem == 'e'
+end
+
+# B and D must always sit together.
+rules << proc do |arr, elem|
+  if elem == 'b' and arr.include?('d')
+    arr.last == 'd'
+  elsif elem == 'd' and arr.include?('b')
+    arr.last == 'b'
+  else
+    true
+  end
+end
+
+# B and E can't sit together.
+rules << proc do |arr, elem|
+  if elem == 'b'
+    arr.last != 'e'
+  elsif elem == 'e'
+    arr.last != 'b'
+  else
+    true
+  end
+end
+
+# C and D must have exactly two people between them.
+rules << proc do |arr, elem|
+  if elem == 'c' and arr.include?('d')
+    arr[-3] == 'd'
+  elsif elem == 'd' and arr.include?('c')
+    arr[-3] == 'c'
+  else
+    true
+  end
+end
+
+# A must always sit to the left of C.
+rules << proc do |arr, elem|
+  !(elem == 'c') || arr.include?('a')
+end
+
+# Method to apply all the rules to a given |arr, elem|
+def apply_all(rules, arr, elem)
+  rules.all? { |p| p.call(arr, elem) }
+end
+
+# The names of E and her friends.
+people = ['a', 'b', 'c', 'd', 'e']
+
+# Conditions array that implements all the rules.
+conditions = people.count.times.map do
+  proc { |arr, elem| apply_all(rules, arr, elem) }
+end
+
+# Output the permutation that satisfies all rules.
+p people.conditional_permutation(conditions)
+#   ['b', 'd', 'e', 'a', 'c']
+```
+
+
+### Logic puzzle 2
+
+Puzzle found at: http://www.braingle.com/brainteasers/teaser.php?id=20962
+
+At the wedding reception, there are five guests, Colin, Emily, Kate,
+Fred, and Irene, who are not sure where to sit at the dinner table.
+They ask the bride's mother, who responds, "As I remember, Colin is
+not next to Kate, Emily is not next to Fred or Kate. Neither Kate or
+Emily are next to Irene. And Fred should sit on Irene's left." As you
+look at them from the opposite side of the table, can you correctly
+seat the guests from left to right?
+
+```ruby
+# Make sure certain people don't sit next to each other.
+# e.g. "A is not next to B (or C, or D)"
+def person_not_next_to(arr, elem, subject, *people)
+  if elem == subject
+    people.all? do |person|
+      !arr.include?(person) || arr.last != person
+    end
+  elsif people.include?(elem)
+    !arr.include?(subject) || arr.last != subject
+  else
+    true
+  end
+end
+
+# Create an array of procs, one for each rule.
+rules = []
+
+# Colin is not next to Kate.
+rules << proc do |arr, elem|
+  person_not_next_to(arr, elem, 'Colin', 'Kate')
+end
+
+# Emily is not next to Fred or Kate.
+rules << proc do |arr, elem|
+  person_not_next_to(arr, elem, 'Emily', 'Fred', 'Kate')
+end
+
+# Neither Kate or Emily are next to Irene.
+rules << proc do |arr, elem|
+  person_not_next_to(arr, elem, 'Irene', 'Kate', 'Emily')
+end
+
+# And Fred should sit on Irene's left.
+rules << proc do |arr, elem|
+  !(elem == 'Irene') || arr.last == 'Fred'
+end
+
+# Method to apply all the rules to a given |arr, elem|
+def apply_all(rules, arr, elem)
+  rules.all? { |p| p.call(arr, elem) }
+end
+
+# The names of the wedding guests.
+people = ['Colin', 'Emily', 'Kate', 'Fred', 'Irene']
+
+# Conditions array that implements all the rules.
+conditions = people.count.times.map do
+  proc { |arr, elem| apply_all(rules, arr, elem) }
+end
+
+# Output the permutation that satisfies all rules.
+p people.conditional_permutation(conditions).reverse
+#   ['Emily', 'Colin', 'Irene', 'Fred', 'Kate']
+```

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.verbose = false
+end
+task :default => :spec
+task :test    => :spec

data/conditional_sample.gemspec

@@ -0,0 +1,29 @@
+# Encoding: UTF-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'conditional_sample/version.rb'
+
+Gem::Specification.new do |s|
+  s.name          = 'conditional_sample'
+  s.authors       = ['Paul Thompson']
+  s.email         = ['nossidge@gmail.com']
+
+  s.summary       = %q{Array sampling based on an input array of Boolean procs}
+  s.description   = %q{Patch the Array with a couple of nice methods for sampling based on the results of an array of Boolean procs. Array is sampled using the procs as conditions that each specific array index element must conform to.}
+  s.homepage      = 'https://github.com/nossidge/conditional_sample'
+
+  s.version       = ConditionalSample.version_number
+  s.date          = ConditionalSample.version_date
+  s.license       = 'GPL-3.0'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ['lib']
+
+  s.add_development_dependency('bundler',     '~> 1.13')
+  s.add_development_dependency('rake',        '~> 10.0')
+  s.add_development_dependency('rspec',       '~> 3.0')
+  s.add_development_dependency('ruby_rhymes', '~> 0.1')
+end

data/lib/conditional_sample/private.rb

@@ -0,0 +1,138 @@
+#!/usr/bin/env ruby
+# Encoding: UTF-8
+
+module ConditionalSample
+
+  module MixMe
+
+    private
+
+      ##
+      # Run a bloc in a given number of 'seconds'. If the bloc completes in
+      # time, then return the result of the bloc, else return 'rescue_value'.
+      #
+      def timeout_rescue seconds, rescue_value = nil
+        begin
+          Timeout::timeout(seconds.to_f) do
+            yield
+          end
+        rescue Timeout::Error
+          rescue_value
+        end
+      end
+
+      ##
+      # Delete the first matching value in an array.
+      # Destructive to the first argument.
+      #
+      def delete_first! array, value
+        array.delete_at(array.index(value) || array.length)
+      end
+
+      ##
+      # Private recursive method.
+      # #conditional_permutation is the public interface.
+      #
+      def conditional_permutation_recurse (
+          array,
+          conditions,
+          current_iter = 0,
+          current_array = [])
+
+        output = []
+
+        # Get the current conditional.
+        cond = conditions[current_iter]
+
+        # Loop through and return the first element that validates.
+        valid = false
+        array.each do |elem|
+
+          # Test the condition. If we've run out of elements
+          #   in the condition array, then allow any value.
+          valid = cond ? cond.call(current_array, elem) : true
+          if valid
+
+            # Remove this element from the array, and recurse.
+            remain = array.dup
+            delete_first!(remain, elem)
+
+            # If the remaining array is empty, no need to recurse.
+            new_val = nil
+            if !remain.empty?
+              new_val = conditional_permutation_recurse(
+                        remain,
+                        conditions,
+                        current_iter + 1,
+                        current_array + [elem])
+            end
+
+            # If we cannot use this value, because it breaks future conditions.
+            if !remain.empty? && new_val.empty?
+              valid = false
+            else
+              output << elem << new_val
+            end
+          end
+
+          break if valid
+        end
+
+        output.flatten.compact
+      end
+
+      ##
+      # Private recursive method.
+      # #conditional_sample is the public interface.
+      #
+      def conditional_sample_recurse (
+          array,
+          conditions,
+          current_iter = 0,
+          current_array = [])
+
+        output = []
+
+        # Get the current conditional.
+        cond = conditions[current_iter]
+
+        # Return nil if we have reached the end of the conditionals.
+        return nil if cond.nil?
+
+        # Loop through and return the first element that validates.
+        valid = false
+        array.each do |elem|
+
+          # Test the condition. If we've run out of elements
+          #   in the condition array, then allow any value.
+          valid = cond.call(current_array, elem)
+          if valid
+
+            # Remove this element from the array, and recurse.
+            remain = array.dup
+            delete_first!(remain, elem)
+
+            # If the remaining array is empty, no need to recurse.
+            new_val = conditional_sample_recurse(
+                      remain,
+                      conditions,
+                      current_iter + 1,
+                      current_array + [elem])
+
+            # If we cannot use this value, because it breaks future conditions.
+            if new_val and new_val.empty?
+              valid = false
+            else
+              output << elem << new_val
+            end
+          end
+
+          break if valid
+        end
+
+        output.flatten.compact
+      end
+
+  end
+
+end

data/lib/conditional_sample/public.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+# Encoding: UTF-8
+
+module ConditionalSample
+
+  ##
+  # This module is suitable as a mixin, using the results of self#to_a
+  #
+  # It is automatically included in Array, so each of these methods are added
+  # to Array when you require 'conditional_sample'
+  #
+  # For both methods, the 'conditions' array must contain boolean procs
+  # using args |arr, elem|
+  # arr::  a reference to the current array that has been built up
+  #        through the recursion chain.
+  # elem:: a reference to the current element being considered.
+  #
+  module MixMe
+
+    ##
+    # Return a permutation of 'array' where each element validates to the
+    # same index in a 'conditions' array of procs that return Boolean.
+    #
+    # The output is an array that is a complete permutation of the input array.
+    # i.e. output.length == array.length
+    #
+    # Any elements in the array that are extra to the number of conditions
+    # will be assumed valid.
+    #
+    #    array = [1,2,3,4,5].shuffle
+    #    conditions = [
+    #      proc { |arr, elem| elem < 2},
+    #      proc { |arr, elem| elem > 2},
+    #      proc { |arr, elem| elem > 1}
+    #    ]
+    #    array.conditional_permutation(conditions)
+    #
+    #    possible output => [1, 3, 4, 5, 2]
+    #
+    # Will not work on arrays that contain nil values.
+    #
+    def conditional_permutation conditions, seconds = nil
+      timeout_rescue(seconds, []) do
+        conditional_permutation_recurse(self.to_a, conditions)
+      end
+    end
+
+    ##
+    # Return values from 'array' where each element validates to the same
+    # index in a 'conditions' array of procs that return Boolean.
+    #
+    # The output is an array of conditions.length that is a partial
+    # permutation of the input array, where satisfies only the conditions.
+    #
+    # Any elements in the array that are extra to the number of conditions
+    # will not be output.
+    #
+    #    array = [1,2,3,4,5].shuffle
+    #    conditions = [
+    #      proc { |arr, elem| elem < 2},
+    #      proc { |arr, elem| elem > 2},
+    #      proc { |arr, elem| elem > 1}
+    #    ]
+    #    array.conditional_sample(conditions)
+    #
+    #    possible output => [1, 5, 3]
+    #
+    # Will not work on arrays that contain nil values.
+    #
+    def conditional_sample conditions, seconds = nil
+      timeout_rescue(seconds, []) do
+        conditional_sample_recurse(self.to_a, conditions)
+      end
+    end
+
+  end
+
+end

data/lib/conditional_sample/version.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# Encoding: UTF-8
+
+module ConditionalSample
+
+  ##
+  # The number of the current version.
+  #
+  def self.version_number
+    major = 0
+    minor = 1
+    tiny  = 0
+    pre   = nil
+
+    string = [major, minor, tiny, pre].compact.join('.')
+  end
+
+  ##
+  # The date of the current version.
+  #
+  def self.version_date
+    '2017-06-27'
+  end
+end

data/lib/conditional_sample.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# Encoding: UTF-8
+
+require 'timeout'
+
+module ConditionalSample
+
+  ##
+  # Require everything in the subdirectory.
+  #
+  Dir[File.dirname(__FILE__) + '/*/*.rb'].each { |file| require file }
+
+  ##
+  # Add the instance methods to the Array class.
+  #
+  Array.include ConditionalSample::MixMe
+
+end

data/spec/conditional_sample_spec.rb

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+# Encoding: UTF-8
+
+################################################################################
+
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+################################################################################
+
+describe ConditionalSample, "basic behaviour" do
+
+  # Input values.
+  let(:numbers) { (1..5).to_a }
+  let(:conditions) {
+    [
+      proc { |arr, elem| elem < 2},
+      proc { |arr, elem| elem > 4},
+      proc { |arr, elem| elem > 1}
+    ]
+  }
+  let(:output_sample) { [1, 5, 2] }
+  let(:output_permutation) { [1, 5, 2, 3, 4] }
+
+  it "should output the correct results" do
+    result = numbers.conditional_sample(conditions)
+    expect(result).to eq output_sample
+
+    result = numbers.conditional_permutation(conditions)
+    expect(result).to eq output_permutation
+  end
+
+  it "when shuffled, should output an array of the correct length" do
+    result = numbers.shuffle.conditional_sample(conditions)
+    expect(result.count).to be conditions.count
+    expect(result[0]).to be 1
+    expect(result[1]).to be 5
+
+    result = numbers.shuffle.conditional_permutation(conditions)
+    expect(result.count).to be numbers.count
+    expect(result[0]).to be 1
+    expect(result[1]).to be 5
+  end
+end
+
+################################################################################
+
+describe ConditionalSample, "mixin behaviour" do
+
+  # Input and output values.
+  let(:numbers) { (1..5).to_a }
+  let(:conditions) {
+    [
+      proc { |arr, elem| elem < 2},
+      proc { |arr, elem| elem > 4},
+      proc { |arr, elem| elem > 1}
+    ]
+  }
+  let(:output_sample) { [1, 5, 2] }
+  let(:output_permutation) { [1, 5, 2, 3, 4] }
+
+  it "should correctly work with a Struct implementing #to_a" do
+
+    # Attempt to mix in using extend on a Struct instance.
+    struct = Struct.new(:contents) do
+      def to_a
+        contents.to_a
+      end
+    end.new numbers
+    struct.extend ConditionalSample::MixMe
+
+    # Run the methods, and compare results.
+    result = struct.conditional_sample(conditions)
+    expect(result).to eq output_sample
+
+    result = struct.conditional_permutation(conditions)
+    expect(result).to eq output_permutation
+  end
+
+  it "should fail on a Struct not implementing #to_a" do
+
+    # Attempt to mix in using extend on a Struct instance.
+    struct = Struct.new(:contents).new numbers
+    struct.extend ConditionalSample::MixMe
+
+    # Run the methods, and expect that they will fail.
+    expect do
+      struct.conditional_sample(conditions)
+    end.to raise_error NoMethodError
+
+    expect do
+      struct.conditional_permutation(conditions)
+    end.to raise_error NoMethodError
+  end
+end
+
+################################################################################

data/spec/examples_spec.rb

@@ -0,0 +1,223 @@
+#!/usr/bin/env ruby
+# Encoding: UTF-8
+
+################################################################################
+
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+################################################################################
+
+describe ConditionalSample, "examples" do
+
+  it "should output the correct results: Basic example" do
+
+    # 5 element input array.
+    numbers = (1..5).to_a
+
+    # 3 element conditions array.
+    conditions = [
+      proc { |arr, elem| elem < 3 },
+      proc { |arr, elem| elem > 3 },
+      proc { |arr, elem| elem > 1 }
+    ]
+
+    # These will always return the below output
+    # because they are the first values that match.
+    permut = numbers.conditional_permutation(conditions)
+    sample = numbers.conditional_sample(conditions)
+    expect(permut).to eq [1, 4, 2, 3, 5]
+    expect(sample).to eq [1, 4, 2]
+
+    # To get a random sample, #shuffle the array first.
+    # These results will vary based on the shuffle.
+    srand(42)
+    shuf = numbers.shuffle
+    shuf_permut = shuf.conditional_permutation(conditions)
+    shuf_sample = shuf.conditional_sample(conditions)
+    expect(shuf_permut).to eq [2, 5, 3, 1, 4]
+    expect(shuf_sample).to eq [2, 5, 3]
+  end
+
+  ##############################################################################
+
+  it "should output the correct results: Random rhyming lines" do
+
+    # Use this gem to get the rhyme of the line's final word.
+    require 'ruby_rhymes'
+
+    # Input lines, just two limericks concat together.
+    lines = [
+      "There was a young rustic named Mallory,",
+      "who drew but a very small salary.",
+      "When he went to the show,",
+      "his purse made him go",
+      "to a seat in the uppermost gallery.",
+      "There was an Old Man with a beard,",
+      "Who said, 'It is just as I feared!—",
+      "Two Owls and a Hen,",
+      "four Larks and a Wren,",
+      "Have all built their nests in my beard.'"
+    ]
+
+    # Output a couplet of any two lines that rhyme.
+    couplet_conditions = [
+      proc { |arr, elem| true },
+      proc { |arr, elem| elem.to_phrase.rhyme_key == arr.last.to_phrase.rhyme_key }
+    ]
+    srand(42)
+    results = lines.shuffle.conditional_sample(couplet_conditions)
+    expect(results).to eq ["four Larks and a Wren,", "Two Owls and a Hen,"]
+
+    # Output a jumbled limerick from the input lines.
+    limerick_conditions = [
+      proc { |arr, elem| true },
+      proc { |arr, elem| elem.to_phrase.rhyme_key == arr[0].to_phrase.rhyme_key },
+      proc { |arr, elem| elem.to_phrase.rhyme_key != arr[0].to_phrase.rhyme_key },
+      proc { |arr, elem| elem.to_phrase.rhyme_key == arr[2].to_phrase.rhyme_key },
+      proc { |arr, elem| elem.to_phrase.rhyme_key == arr[0].to_phrase.rhyme_key }
+    ]
+    srand(42)
+    results = lines.shuffle.conditional_sample(limerick_conditions)
+    expect(results).to eq ["who drew but a very small salary.",
+      "There was a young rustic named Mallory,",
+      "four Larks and a Wren,",
+      "Two Owls and a Hen,",
+      "to a seat in the uppermost gallery."
+    ]
+
+  end
+
+  ##############################################################################
+
+  it "should output the correct results: Logic puzzle 1" do
+
+    # Create an array of procs, one for each rule.
+    rules = []
+
+    # E has to be in the middle.
+    rules << proc do |arr, elem|
+      !(arr.count == 2) || elem == 'e'
+    end
+
+    # B and D must always sit together.
+    rules << proc do |arr, elem|
+      if elem == 'b' and arr.include?('d')
+        arr.last == 'd'
+      elsif elem == 'd' and arr.include?('b')
+        arr.last == 'b'
+      else
+        true
+      end
+    end
+
+    # B and E can't sit together.
+    rules << proc do |arr, elem|
+      if elem == 'b'
+        arr.last != 'e'
+      elsif elem == 'e'
+        arr.last != 'b'
+      else
+        true
+      end
+    end
+
+    # C and D must have exactly two people between them.
+    rules << proc do |arr, elem|
+      if elem == 'c' and arr.include?('d')
+        arr[-3] == 'd'
+      elsif elem == 'd' and arr.include?('c')
+        arr[-3] == 'c'
+      else
+        true
+      end
+    end
+
+    # A must always sit to the left of C.
+    rules << proc do |arr, elem|
+      !(elem == 'c') || arr.include?('a')
+    end
+
+    # Method to apply all the rules to a given |arr, elem|
+    def apply_all(rules, arr, elem)
+      rules.all? { |p| p.call(arr, elem) }
+    end
+
+    # The names of E and her friends.
+    people = ['a', 'b', 'c', 'd', 'e']
+
+    # Conditions array that implements all the rules
+    conditions = people.count.times.map do
+      proc { |arr, elem| apply_all(rules, arr, elem) }
+    end
+
+    # Output the permutation that satisfies all rules.
+    20.times do
+      result = people.shuffle.conditional_permutation(conditions)
+      expect(result).to eq ['b', 'd', 'e', 'a', 'c']
+    end
+  end
+
+  ##############################################################################
+
+  it "should output the correct results: Logic puzzle 2" do
+
+    # Make sure certain people don't sit next to each other.
+    # e.g. "A is not next to B (or C, or D)"
+    def person_not_next_to(arr, elem, subject, *people)
+      if elem == subject
+        people.all? do |person|
+          !arr.include?(person) || arr.last != person
+        end
+      elsif people.include?(elem)
+        !arr.include?(subject) || arr.last != subject
+      else
+        true
+      end
+    end
+
+    # Create an array of procs, one for each rule.
+    rules = []
+
+    # Colin is not next to Kate.
+    rules << proc do |arr, elem|
+      person_not_next_to(arr, elem, 'Colin', 'Kate')
+    end
+
+    # Emily is not next to Fred or Kate.
+    rules << proc do |arr, elem|
+      person_not_next_to(arr, elem, 'Emily', 'Fred', 'Kate')
+    end
+
+    # Neither Kate or Emily are next to Irene.
+    rules << proc do |arr, elem|
+      person_not_next_to(arr, elem, 'Irene', 'Kate', 'Emily')
+    end
+
+    # And Fred should sit on Irene's left.
+    rules << proc do |arr, elem|
+      !(elem == 'Irene') || arr.last == 'Fred'
+    end
+
+    # Method to apply all the rules to a given |arr, elem|
+    def apply_all(rules, arr, elem)
+      rules.all? { |p| p.call(arr, elem) }
+    end
+
+    # The names of the wedding guests.
+    people = ['Colin', 'Emily', 'Kate', 'Fred', 'Irene']
+
+    # Conditions array that implements all the rules.
+    conditions = people.count.times.map do
+      proc { |arr, elem| apply_all(rules, arr, elem) }
+    end
+
+    # Output the permutation that satisfies all rules.
+    20.times do
+      result = people.shuffle.conditional_permutation(conditions).reverse
+      expect(result).to eq ['Emily', 'Colin', 'Irene', 'Fred', 'Kate']
+    end
+  end
+
+end
+
+################################################################################

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'bundler/setup'
+Bundler.setup
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+require 'conditional_sample'

data/spec/timeout_spec.rb

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+# Encoding: UTF-8
+
+################################################################################
+
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+################################################################################
+
+# Using the timeout function is recommended when first developing a
+# project, as it may not be transparent how computationally expensive
+# a condition array will be.
+
+describe ConditionalSample, "timeout" do
+
+  # Even if a conditions array can be fulfilled using the corpus array,
+  # it may just take too long.
+  it "should output [] or valid array if conditions are possible but long" do
+
+    # Read in the Rakefile, just as an example.
+    # Multiply the array, so there's more rows.
+    # Add just a few unique needles to this haystack.
+    lines = File.read('Rakefile').split("\n")
+    lines *= 500000
+    lines << 'unique_string_1'
+    lines << 'unique_string_2'
+    lines << 'unique_string_3'
+
+    # The first 3 will be easy to fill, as there are multiple valid lines.
+    # The rest will be harder, as only one line matches each.
+    conditions = [
+      proc { |arr, elem| elem.match(/spec/i) },
+      proc { |arr, elem| elem.match(/core/i) },
+      proc { |arr, elem| elem.match(/rspec/i) },
+      proc { |arr, elem| elem.match(/unique_string_1/i) },
+      proc { |arr, elem| elem.match(/unique_string_2/i) },
+      proc { |arr, elem| elem.match(/unique_string_3/i) }
+    ]
+
+    # Exact timing will depend on the results of the 'Array#shuffle'.
+    # So this may or may not succeed.
+    results = lines.shuffle.conditional_sample(conditions, 2.5)
+
+    # Output will either be a 6 element or an empty array.
+    expect([0, 6]).to include(results.count)
+  end
+
+  ##############################################################################
+
+  # Example of using the Timeout module to ensure CPUs aren't locked up
+  # until the heat-death of the universe.
+  #
+  # This will never succeed, because the corpus array and the conditions
+  # array are incompatible. Without a timeout, it would calculate all
+  # permutations, in factorial time, before telling you it's impossible.
+  #
+  # Using the timeout function is recommended when first developing a
+  # project, as it may not be transparent how computationally expensive
+  # a condition array will be.
+  it "should output [] if conditions are impossible" do
+
+    # Read in the Rakefile, just as an example.
+    # Multiply the array, so there's more rows.
+    # Add just a few unique needles to this haystack.
+    lines = File.read('Rakefile').split("\n")
+    lines *= 500000
+    lines << 'unique_string_1'
+    lines << 'unique_string_2'
+    lines << 'unique_string_3'
+
+    # Look at the last condition! It will never return true!
+    # So this will take ages, unless we use the timer argument.
+    conditions = [
+      proc { |arr, elem| elem.match(/core/i) },
+      proc { |arr, elem| elem.match(/rspec/i) },
+      proc { |arr, elem| elem.match(/unique_string_1/i) },
+      proc { |arr, elem| elem.match(/unique_string_2/i) },
+      proc { |arr, elem| elem.match(/unique_string_3/i) },
+      proc { |arr, elem| elem.match(/unique_string_4/i) }
+    ]
+
+    # Give up after some time.
+    results = lines.shuffle.conditional_sample(conditions, 2.5)
+
+    # Output will always be [], no matter how long we give it.
+    expect(results).to eq []
+  end
+
+end
+
+################################################################################

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: conditional_sample
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Paul Thompson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-06-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: ruby_rhymes
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: Patch the Array with a couple of nice methods for sampling based on the
+  results of an array of Boolean procs. Array is sampled using the procs as conditions
+  that each specific array index element must conform to.
+email:
+- nossidge@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- conditional_sample.gemspec
+- lib/conditional_sample.rb
+- lib/conditional_sample/private.rb
+- lib/conditional_sample/public.rb
+- lib/conditional_sample/version.rb
+- spec/conditional_sample_spec.rb
+- spec/examples_spec.rb
+- spec/spec_helper.rb
+- spec/timeout_spec.rb
+homepage: https://github.com/nossidge/conditional_sample
+licenses:
+- GPL-3.0
+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.5.2
+signing_key: 
+specification_version: 4
+summary: Array sampling based on an input array of Boolean procs
+test_files: []