prop_check 0.6.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a8b10e33dfef86ed35b2a13ff0261552bbd2c7d7f39a6fa6997bedb4c57651f
-  data.tar.gz: c2400550a28e15baa8b4d7323adea18ec3aa858384f774b76c59f6ff87f38c82
+  metadata.gz: 8e5aeef61ddf82569ca885327d32b9fe8fd939f2fdbef48709cb19504b5cf041
+  data.tar.gz: d914dcac32f7a3a976661a0280c71f0a7a665411550aed9902317b04c82ee290
 SHA512:
-  metadata.gz: 758c27825f78f4d51ad6ff076f5866d2c0d7ee0a0b6f150b4247d9acb6804676c10d1223278506a2c1f2b1ecd683d8951f4c2331d6e0063cd8039fd6dedbdd94
-  data.tar.gz: f3db2b04c823a7bc29afa6dd23e58c1c7696873d836b2f42ad0af70f150ba623fbd67b8204e521c544e0a7600bd094c0b4971d6f2ceac37c456e1a050716aac5
+  metadata.gz: 85c5b76ac37ba8e03b2c41c04c4cc359844fa2e52d0af8893787531c23f3a54b046eb7eed13b055fed44c8983f87cbfe492d1524746624a3744300a73caf01da
+  data.tar.gz: 9beb7ac4e605c72cc8e9b3907e727ae532c2eec4a530b6a9b7c31445135e37c8849c9f186d4571aaf38c24e28989ebe856ed2e5e873baf2ed7b740a73561dae7

data/.tool-versions

@@ -1 +1 @@
-ruby 2.5.1
+ruby 2.6.5

data/.travis.yml

@@ -4,4 +4,15 @@ language: ruby
 cache: bundler
 rvm:
   - 2.5.1
-before_install: gem install bundler -v 2.0.1
+before_install: gem install bundler -v 2.0.2
+env:
+  global:
+    - CC_TEST_REPORTER_ID=9d18f5b43e49eecd6c3da64d85ea9c765d3606c129289d7c8cadf6d448713311
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+script:
+  - bundle exec rspec
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/CHANGELOG.md

@@ -0,0 +1 @@
+- 0.8.0 New syntax that is more explicit, passng generated values to blocks as parameters.

data/Gemfile

@@ -5,3 +5,4 @@ gemspec
 
 gem 'simplecov', require: false, group: :test
 gem 'doctest-rspec', require: false, group: :test
+gem 'awesome_print', require: true

data/Gemfile.lock

@@ -1,11 +1,12 @@
 PATH
   remote: .
   specs:
-    prop_check (0.6.0)
+    prop_check (0.9.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    awesome_print (1.8.0)
     diff-lcs (1.3)
     docile (1.3.2)
     doctest-core (0.0.2)
@@ -13,7 +14,7 @@ GEM
       doctest-core (~> 0.0.2)
       rspec
     json (2.2.0)
-    rake (10.5.0)
+    rake (12.3.3)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
       rspec-expectations (~> 3.8.0)
@@ -37,12 +38,13 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  awesome_print
   bundler (~> 2.0)
   doctest-rspec
   prop_check!
-  rake (~> 10.0)
+  rake (~> 12.3)
   rspec (~> 3.0)
   simplecov
 
 BUNDLED WITH
-   2.0.2
+   2.1.4

data/README.md

@@ -2,6 +2,11 @@
 
 PropCheck allows you to do Property Testing in Ruby.
 
+[![Gem](https://img.shields.io/gem/v/prop_check.svg)](https://rubygems.org/gems/prop_check)
+[![Build Status](https://travis-ci.org/Qqwy/ruby-prop_check.svg?branch=master)](https://travis-ci.org/Qqwy/ruby-prop_check)
+[![Maintainability](https://api.codeclimate.com/v1/badges/71897f5e6193a5124a53/maintainability)](https://codeclimate.com/github/Qqwy/ruby-prop_check/maintainability)
+[![RubyDoc](https://img.shields.io/badge/%F0%9F%93%9ARubyDoc-documentation-informational.svg)](https://www.rubydoc.info/github/Qqwy/ruby-prop_check/master/PropCheck)
+
 It features:
 
 - Generators for common datatypes.
@@ -9,7 +14,7 @@ It features:
 - Shrinking to a minimal counter-example on failure.
 
 
-## TODOs before release
+## TODOs before stable release
 
 Before releasing this gem on Rubygems, the following things need to be finished:
 
@@ -21,11 +26,11 @@ Before releasing this gem on Rubygems, the following things need to be finished:
   - [x] Stop after a ludicrous amount of generator runs, to prevent malfunctioning (infinitely looping) generators from blowing up someone's computer.
  - [x] Look into customization of settings from e.g. command line arguments.
 - [x] Good, unicode-compliant, string generators.
-- [ ] Filtering generator outputs.
+- [x] Filtering generator outputs.
 
 # Nice-to-haves
  
-- [ ] Basic integration with RSpec. See also https://groups.google.com/forum/#!msg/rspec/U-LmL0OnO-Y/iW_Jcd6JBAAJ for progress on this.
+- [x] Basic integration with RSpec. See also https://groups.google.com/forum/#!msg/rspec/U-LmL0OnO-Y/iW_Jcd6JBAAJ for progress on this.
  - [ ] `aggregate` , `resize` and similar generator-modifying calls (c.f. PropEr's variants of these) which will help with introspection/metrics.
  - [ ] Integration with other Ruby test frameworks.
  - Stateful property testing. If implemented at some point, will probably happen in a separate add-on library.
@@ -61,8 +66,9 @@ _(to be precise: a method on the execution context is defined which returns the
 Raise an exception from the block if there is a problem. If there is no problem, just return normally.
 
 ```ruby
+include PropCheck::Generators
 # testing that Enumerable#sort sorts in ascending order
-PropCheck.forall(numbers: array(integer())) do
+PropCheck.forall(array(integer)) do |numbers|
   sorted_numbers = numbers.sort
   
   # Check that no number is smaller than the previous number
@@ -72,6 +78,50 @@ PropCheck.forall(numbers: array(integer())) do
 end
 ```
 
+
+Here is another example, using it inside a test case.
+Here we check if `naive_average` indeed always returns an integer for all arrays of numbers we can pass it:
+
+```ruby
+# Somewhere you have this function definition:
+def naive_average(array)
+  array.sum / array.length
+end
+
+# And then in a test case:
+include PropCheck::Generators
+PropCheck.forall(numbers: array(integer)) do |numbers:|
+  result = naive_average(numbers)
+  unless result.is_a?(Integer) do
+    raise "Expected the average to be an integer!"
+  end
+end
+```
+
+When running this particular example PropCheck very quickly finds out that we have made a programming mistake:
+
+```ruby
+ZeroDivisionError: 
+(after 6 successful property test runs)
+Failed on: 
+`{
+    :numbers => []
+}`
+
+Exception message:
+---
+divided by 0
+---
+
+(shrinking impossible)
+---
+```
+
+Clearly we forgot to handle the case of an empty array being passed to the function.
+This is a good example of the kind of conceptual bugs that PropCheck (and property-based testing in general)
+are able to check for.
+
+
 #### Shrinking
 
 When a failure is found, PropCheck will re-run the block given to `forall` to test
@@ -83,8 +133,8 @@ PropCheck will see if the failure still happens with `x = 50`.
 If it does , it will try `x = 25`. If not, it will try `x = 75`, and so on.
 
 This means if something only goes wrong for `x = 2`, the program will try:
-- `x = 100`(fails),`
-- x = 50`(fails), 
+- `x = 100`(fails),
+- `x = 50`(fails), 
 - `x = 25`(fails), 
 - `x = 12`(fails), 
 - `x = 6`(fails), 
@@ -101,21 +151,28 @@ A short summary:
 - Arrays and hashes shrink to fewer elements, as well as shrinking their elements.
 - Strings shrink to shorter strings, as well as characters earlier in their alphabet.
 
+### Builtin Generators
+
+PropCheck comes with [many builtin generators in the PropCheck::Generators](https://www.rubydoc.info/github/Qqwy/ruby-prop_check/master/PropCheck/Generators) module.
+
+It contains generators for:
+- (any, positive, negative, etc.) integers, 
+- (any, only real-valued) floats, 
+- (any, printable only, alphanumeric only, etc) strings and symbols
+- fixed-size arrays and hashes 
+- as well as varying-size arrays and hashes.
+- and many more!
+
+It is common to call `include PropCheck::Generators` in e.g. your testing-suite files to be able to use these.
+If you want to be more explicit (but somewhat more verbose) when calling these functions. feel free to e.g. create a module-alias (like `PG = PropCheck::Generators`) instead.
 
 ### Writing Custom Generators
 
-PropCheck comes bundled with a bunch of common generators, for:
-- integers
-- floats
-- strings
-- symbols
-- arrays
-- hashes
-etc.
+As described in the previous section, PropCheck already comes bundled with a bunch of common generators.
 
 However, you can easily adapt them to generate your own datatypes:
 
-#### Generator#wrap
+#### Generators#constant / Generator#wrap
 
 Always returns the given value. No shrinking.
 
@@ -157,6 +214,9 @@ you can use `Generators.frequency` which takes a hash of (integer_frequency => g
 There are even more functions in the `Generator` class and the `Generators` module that you might want to use,
 although above are the most generally useful ones.
 
+[PropCheck::Generator documentation](https://www.rubydoc.info/github/Qqwy/ruby-prop_check/master/PropCheck/Generator)
+[PropCheck::Generators documentation](https://www.rubydoc.info/github/Qqwy/ruby-prop_check/master/PropCheck/Generators)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/prop_check.rb

@@ -3,14 +3,33 @@ require 'prop_check/property'
 require 'prop_check/generator'
 require 'prop_check/generators'
 require 'prop_check/helper'
+##
+# Main module of the PropCheck library.
+#
+# You probably want to look at the documentation of
+# PropCheck::Generator and PropCheck::Generators
+# to find out more about how to use generators.
+#
+# Common usage is to call `extend PropCheck` in your (testing) modules.
+#
+# This will:
+# 1. Add the local method `forall` which  will call `PropCheck.forall`
+# 2. `include PropCheck::Generators`.
+#
 module PropCheck
-  class Error < StandardError; end
-  class UserError < Error; end
-  class GeneratorExhaustedError < UserError; end
-  class MaxShrinkStepsExceededError < UserError; end
+  module Errors
+    class Error < StandardError; end
+    class UserError < Error; end
+    class GeneratorExhaustedError < UserError; end
+    class MaxShrinkStepsExceededError < UserError; end
+  end
 
   extend self
 
+  ##
+  # Runs a property.
+  #
+  # See the README for more details.
   def forall(*args, **kwargs, &block)
     PropCheck::Property.forall(*args, **kwargs, &block)
   end

data/lib/prop_check/generator.rb

@@ -72,7 +72,7 @@ module PropCheck
       #   end.flatten
       # end
       Generator.new do |size, rng|
-        outer_result = generate(size, rng)
+        outer_result = self.generate(size, rng)
         outer_result.bind do |outer_val|
           inner_generator = generator_proc.call(outer_val)
           inner_generator.generate(size, rng)
@@ -91,5 +91,24 @@ module PropCheck
         result.map(&proc)
       end
     end
+
+    ##
+    # Creates a new Generator that only produces a value when the block `condition` returns a truthy value.
+    def where(&condition)
+      self.map do |result|
+        if condition.call(*result)
+          result
+        else
+          :"_PropCheck.filter_me"
+        end
+      end
+      # self.map do |*result|
+      #   if condition.call(*result)
+      #     result
+      #   else
+      #     :'_PropCheck.filter_me'
+      #   end
+      # end
+    end
   end
 end

data/lib/prop_check/generators.rb

@@ -1,3 +1,6 @@
+# coding: utf-8
+# frozen_string_literal: true
+
 require 'prop_check/generator'
 require 'prop_check/lazy_tree'
 module PropCheck
@@ -116,27 +119,40 @@ module PropCheck
     end
 
     ##
-    # Generates floating point numbers
+    # Generates floating-point numbers
     # These start small (around 0)
     # and become more extreme (large positive and large negative numbers)
     #
+    # Will only generate 'reals',
+    # that is: no infinity, no NaN,
+    # no numbers testing the limits of floating-point arithmetic.
     #
     # Shrinks to numbers closer to zero.
     #
-    # TODO testing for NaN, Infinity?
-    def float
-      # integer.bind do |a|
-      #   integer.bind do |b|
-      #     integer.bind do |c|
-      #       Generator.wrap(fraction(a, b, c))
-      #     end
-      #   end
-      # end
+    #    >> Generators.real_float().sample(10, size: 10, rng: Random.new(42))
+    #    => [-2.2, -0.2727272727272727, 4.0, 1.25, -3.7272727272727275, -8.833333333333334, -8.090909090909092, 1.1428571428571428, 0.0, 8.0]
+    def real_float
       tuple(integer, integer, integer).map do |a, b, c|
         fraction(a, b, c)
       end
     end
 
+    @special_floats = [Float::NAN, Float::INFINITY, -Float::INFINITY, Float::MAX, Float::MIN, 0.0.next_float, 0.0.prev_float]
+    ##
+    # Generates floating-point numbers
+    # Will generate NaN, Infinity, -Infinity,
+    # as well as Float::EPSILON, Float::MAX, Float::MIN,
+    # 0.0.next_float, 0.0.prev_float,
+    # to test the handling of floating-point edge cases.
+    # Approx. 1/100 generated numbers is a special one.
+    #
+    # Shrinks to smaller, real floats.
+    #    >> Generators.float().sample(10, size: 10, rng: Random.new(42))
+    #    => [4.0, 9.555555555555555, 0.0, -Float::INFINITY, 5.5, -5.818181818181818, 1.1428571428571428, 0.0, 8.0, 7.857142857142858]
+    def float
+      frequency(99 => real_float, 1 => one_of(*@special_floats.map(&method(:constant))))
+    end
+
     ##
     # Picks one of the given generators in `choices` at random uniformly every time.
     #
@@ -156,6 +172,9 @@ module PropCheck
     # (representing the relative frequency of this generator)
     # and values to be generators.
     #
+    # Side note: If you want to use the same frequency number for multiple generators,
+    # Ruby syntax requires you to send an array of two-element arrays instead of a hash.
+    #
     # Shrinks to arbitrary elements (since hashes are not ordered).
     #
     #   >> Generators.frequency(5 => Generators.integer, 1 => Generators.printable_ascii_char).sample(size: 10, rng: Random.new(42))
@@ -174,7 +193,7 @@ module PropCheck
     #
     # Shrinks element generators, one at a time (trying last one first).
     #
-    #   >> Generators.tuple(Generators.integer, Generators.float).call(10, Random.new(42))
+    #   >> Generators.tuple(Generators.integer, Generators.real_float).call(10, Random.new(42))
     #   => [-4, 13.0]
     def tuple(*generators)
       Generator.new do |size, rng|
@@ -191,7 +210,7 @@ module PropCheck
     #
     # Shrinks element generators.
     #
-    #    >> Generators.fixed_hash(a: Generators.integer(), b: Generators.float(), c: Generators.integer()).call(10, Random.new(42))
+    #    >> Generators.fixed_hash(a: Generators.integer(), b: Generators.real_float(), c: Generators.integer()).call(10, Random.new(42))
     #    => {:a=>-4, :b=>13.0, :c=>-3}
     def fixed_hash(hash)
       keypair_generators =
@@ -242,7 +261,9 @@ module PropCheck
     # containing one of a..z, A..Z, 0..9
     #
     # Shrinks towards lowercase 'a'.
-    # 
+    #
+    #    >> Generators.alphanumeric_char.sample(5, size: 10, rng: Random.new(42))
+    #    => ["M", "Z", "C", "o", "Q"]
     def alphanumeric_char
       one_of(*@alphanumeric_chars.map(&method(:constant)))
     end
@@ -250,7 +271,11 @@ module PropCheck
     ##
     # Generates a string
     # containing only the characters a..z, A..Z, 0..9
+    #
     # Shrinks towards fewer characters, and towards lowercase 'a'.
+    #
+    #    >> Generators.alphanumeric_string.sample(5, size: 10, rng: Random.new(42))
+    #    => ["ZCoQ", "8uM", "wkkx0JNx", "v0bxRDLb", "Gl5v8RyWA6"]
     def alphanumeric_string
       array(alphanumeric_char).map(&:join)
     end
@@ -272,7 +297,11 @@ module PropCheck
     ##
     # Generates strings
     # from the printable ASCII character set.
+    #
     # Shrinks towards fewer characters, and towards ' '.
+    #
+    #    >> Generators.printable_ascii_string.sample(5, size: 10, rng: Random.new(42))
+    #    => ["S|.g", "rvjjw7\"5T!", "=", "!_[4@", "Y"]
     def printable_ascii_string
       array(printable_ascii_char).map(&:join)
     end
@@ -295,7 +324,11 @@ module PropCheck
     ##
     # Generates a single-character string
     # from the printable ASCII character set.
+    #
     # Shrinks towards '\n'.
+    #
+    #    >> Generators.ascii_char.sample(size: 10, rng: Random.new(42))
+    #    => ["d", "S", "|", ".", "g", "\\", "4", "d", "r", "v"]
     def ascii_char
       one_of(*@ascii_chars.map(&method(:constant)))
     end
@@ -303,7 +336,11 @@ module PropCheck
     ##
     # Generates strings
     # from the printable ASCII character set.
+    #
     # Shrinks towards fewer characters, and towards '\n'.
+    #
+    #    >> Generators.ascii_string.sample(5, size: 10, rng: Random.new(42))
+    #    => ["S|.g", "drvjjw\b\a7\"", "!w=E!_[4@k", "x", "zZI{[o"]
     def ascii_string
       array(ascii_char).map(&:join)
     end
@@ -321,6 +358,8 @@ module PropCheck
     #
     # Shrinks towards characters with lower codepoints, e.g. ASCII
     #
+    #    >> Generators.printable_char.sample(size: 10, rng: Random.new(42))
+    #    => ["吏", "", "", "", "", "", "", "", "", "Ȍ"]
     def printable_char
       one_of(*@printable_chars.map(&method(:constant)))
     end
@@ -331,6 +370,8 @@ module PropCheck
     #
     # Shrinks towards shorter strings, and towards characters with lower codepoints, e.g. ASCII
     #
+    #    >> Generators.printable_string.sample(5, size: 10, rng: Random.new(42))
+    #    => ["", "Ȍ", "𐁂", "Ȕ", ""]
     def printable_string
       array(printable_char).map(&:join)
     end
@@ -341,6 +382,8 @@ module PropCheck
     #
     # Shrinks towards characters with lower codepoints, e.g. ASCII
     #
+    #    >> Generators.printable_char.sample(size: 10, rng: Random.new(42))
+    #    => ["吏", "", "", "", "", "", "", "", "", "Ȍ"]
     def char
       choose(0..0x10FFFF).map do |num|
         [num].pack('U')
@@ -353,6 +396,8 @@ module PropCheck
     #
     # Shrinks towards characters with lower codepoints, e.g. ASCII
     #
+    #    >> Generators.string.sample(5, size: 10, rng: Random.new(42))
+    #    => ["\u{A3DB3}𠍜\u{3F46A}\u{1AEBC}", "􍙦𡡹󴇒\u{DED74}𪱣\u{43E97}ꂂ\u{50695}􏴴\u{C0301}", "\u{4FD9D}", "\u{C14BF}\u{193BB}𭇋󱣼\u{76B58}", "𦐺\u{9FDDB}\u{80ABB}\u{9E3CF}𐂽\u{14AAE}"]
     def string
       array(char).map(&:join)
     end
@@ -361,7 +406,9 @@ module PropCheck
     # Generates either `true` or `false`
     #
     # Shrinks towards `false`
-    # 
+    #
+    #    >> Generators.boolean.sample(5, size: 10, rng: Random.new(42))
+    #    => [false, true, false, false, false]
     def boolean
       one_of(constant(false), constant(true))
     end
@@ -370,6 +417,9 @@ module PropCheck
     # Generates always `nil`.
     #
     # Does not shrink.
+    #
+    #    >> Generators.nil.sample(5, size: 10, rng: Random.new(42))
+    #    => [nil, nil, nil, nil, nil]
     def nil
       constant(nil)
     end
@@ -379,15 +429,34 @@ module PropCheck
     #
     # Shrinks towards `nil`.
     #
+    #    >> Generators.falsey.sample(5, size: 10, rng: Random.new(42))
+    #    => [nil, false, nil, nil, nil]
     def falsey
       one_of(constant(nil), constant(false))
     end
 
+    ##
+    # Generates symbols consisting of lowercase letters and potentially underscores.
+    #
+    # Shrinks towards shorter symbols and the letter 'a'.
+    #
+    #    >> Generators.simple_symbol.sample(5, size: 10, rng: Random.new(42))
+    #    => [:tokh, :gzswkkxudh, :vubxlfbu, :lzvlyq__jp, :oslw]
+    def simple_symbol
+      alphabet = ('a'..'z').to_a
+      alphabet << '_'
+      array(one_of(*alphabet.map(&method(:constant))))
+        .map(&:join)
+        .map(&:to_sym)
+    end
+
     ##
     # Generates common terms that are not `nil` or `false`.
     #
     # Shrinks towards simpler terms, like `true`, an empty array, a single character or an integer.
     #
+    #    >> Generators.truthy.sample(5, size: 10, rng: Random.new(42))
+    #    => [[4, 0, -3, 10, -4, 8, 0, 0, 10], -3, [5.5, -5.818181818181818, 1.1428571428571428, 0.0, 8.0, 7.857142857142858, -0.6666666666666665, 5.25], [], ["\u{9E553}\u{DD56E}\u{A5BBB}\u{8BDAB}\u{3E9FC}\u{C4307}\u{DAFAE}\u{1A022}\u{938CD}\u{70631}", "\u{C4C01}\u{32D85}\u{425DC}"]]
     def truthy
       one_of(constant(true),
              constant([]),
@@ -399,7 +468,7 @@ module PropCheck
              array(float),
              array(char),
              array(string),
-             hash(symbol, integer),
+             hash(simple_symbol, integer),
              hash(string, integer),
              hash(string, string)
             )
@@ -408,6 +477,9 @@ module PropCheck
     ##
     # Generates whatever `other_generator` generates
     # but sometimes instead `nil`.`
+    #
+    #    >> Generators.nillable(Generators.integer).sample(20, size: 10, rng: Random.new(42))
+    #    => [9, 10, 8, 0, 10, -3, -8, 10, 1, -9, -10, nil, 1, 6, nil, 1, 9, -8, 8, 10]
     def nillable(other_generator)
       frequency(9 => other_generator, 1 => constant(nil))
     end

data/lib/prop_check/helper/lazy_append.rb

@@ -0,0 +1,18 @@
+module PropCheck
+  module Helper
+    ##
+    # A refinement for enumerators
+    # to allow lazy appending of two (potentially lazy) enumerators:
+    #   >> [1,2,3].lazy_append([4,5.6]).to_a
+    #   => [1,2,3,4,5,6]
+    module LazyAppend
+      refine Enumerable do
+        ##   >> [1,2,3].lazy_append([4,5.6]).to_a
+        ##   => [1,2,3,4,5,6]
+        def lazy_append(other_enumerator)
+          [self, other_enumerator].lazy.flat_map(&:lazy)
+        end
+      end
+    end
+  end
+end

data/lib/prop_check/lazy_tree.rb

@@ -1,22 +1,13 @@
-##
-# A refinement for enumerators
-# to allow lazy appending of two (potentially lazy) enumerators:
-module LazyAppend
-  refine Enumerable do
-    ##   >> [1,2,3].lazy_append([4,5.6]).to_a
-    ##   => [1,2,3,4,5,6]
-    def lazy_append(other_enumerator)
-      [self, other_enumerator].lazy.flat_map(&:lazy)
-    end
-  end
-end
+# frozen_string_literal: true
+
+require 'prop_check/helper/lazy_append'
 
 module PropCheck
   ##
   # A Rose tree with the root being eager,
   # and the children computed lazily, on demand.
   class LazyTree
-    using LazyAppend
+    using PropCheck::Helper::LazyAppend
 
     attr_accessor :root, :children
     def initialize(root, children = [].lazy)
@@ -82,7 +73,8 @@ module PropCheck
         [tree.root].lazy_append(new_children)
       end
 
-      squish.call(self, [])
+      squish
+        .call(self, [])
 
       # base = [root]
       # recursive = children.map(&:each)
@@ -108,7 +100,8 @@ module PropCheck
     #   >> LazyTree.new(1, [LazyTree.new(2, [LazyTree.new(3)]), LazyTree.new(4)]).to_a
     #   => [1, 4, 2, 3]
     def to_a
-      each.force
+      each
+        .force
     end
 
     # TODO: fix implementation

data/lib/prop_check/property.rb

@@ -1,41 +1,90 @@
 require 'stringio'
+require "awesome_print"
 
 require 'prop_check/property/configuration'
-require 'prop_check/property/check_evaluator'
 module PropCheck
+  ##
+  # Run properties
   class Property
 
-    def self.forall(**bindings, &block)
-
-      property = new(bindings)
+    ##
+    # Main entry-point to create (and possibly immediately run) a property-test.
+    #
+    # This method accepts a list of generators and a block.
+    # The block will then be executed many times, passing the values generated by the generators
+    # as respective arguments:
+    #
+    # ```
+    # include PropCheck::Generators
+    # PropCheck.forall(integer(), float()) { |x, y| ... }
+    # ```
+    #
+    # It is also possible (and recommended when having more than a few generators) to use a keyword-list
+    # of generators instead:
+    #
+    # ```
+    # include PropCheck::Generators
+    # PropCheck.forall(x: integer(), y: float()) { |x:, y:| ... }
+    # ```
+    #
+    #
+    # If you do not pass a block right away,
+    # a Property object is returned, which you can call the other instance methods
+    # of this class on before finally passing a block to it using `#check`.
+    # (so `forall(Generators.integer) do |val| ... end` and forall(Generators.integer).check do |val| ... end` are the same)
+    def self.forall(*bindings, &block)
+
+      property = new(*bindings)
 
       return property.check(&block) if block_given?
 
       property
     end
 
+    ##
+    # Returns the default configuration of the library as it is configured right now
+    # for introspection.
+    #
+    # For the configuration of a single property, check its `configuration` instance method.
+    # See PropCheck::Property::Configuration for more info on available settings.
     def self.configuration
       @configuration ||= Configuration.new
     end
 
+    ##
+    # Yields the library's configuration object for you to alter.
+    # See PropCheck::Property::Configuration for more info on available settings.
     def self.configure
       yield(configuration)
     end
 
     attr_reader :bindings, :condition
 
-    def initialize(**bindings)
-      raise ArgumentError, 'No bindings specified!' if bindings.empty?
+    def initialize(*bindings, **kwbindings)
+      raise ArgumentError, 'No bindings specified!' if bindings.empty? && kwbindings.empty?
 
       @bindings = bindings
-      @condition = -> { true }
+      @kwbindings = kwbindings
+      @condition = proc { true }
       @config = self.class.configuration
     end
 
+    ##
+    # Returns the configuration of this property
+    # for introspection.
+    #
+    # See PropCheck::Property::Configuration for more info on available settings.
     def configuration
       @config
     end
 
+    ##
+    # Allows you to override the configuration of this property
+    # by giving a hash with new settings.
+    #
+    # If no other changes need to occur before you want to check the property,
+    # you can immediately pass a block to this method.
+    # (so `forall(a: Generators.integer).with_config(verbose: true) do ... end` is the same as `forall(a: Generators.integer).with_config(verbose: true).check do ... end`)
     def with_config(**config, &block)
       @config = @config.merge(config)
 
@@ -44,15 +93,35 @@ module PropCheck
       self
     end
 
-    def where(&new_condition)
+    ##
+    # filters the generator using the  given `condition`.
+    # The final property checking block will only be run if the condition is truthy.
+    #
+    # If wanted, multiple `where`-conditions can be specified on a property.
+    # Be aware that if you filter away too much generated inputs,
+    # you might encounter a GeneratorExhaustedError.
+    # Only filter if you have few inputs to reject. Otherwise, improve your generators.
+    def where(&condition)
       original_condition = @condition.dup
-      @condition = -> { instance_exec(&original_condition) && instance_exec(&new_condition) }
+      @condition = proc do |**kwargs|
+        original_condition.call(**kwargs) && condition.call(**kwargs)
+      end
 
       self
     end
 
+    ##
+    # Checks the property (after settings have been altered using the other instance methods in this class.)
     def check(&block)
-      binding_generator = PropCheck::Generators.fixed_hash(bindings)
+      gens =
+        if @kwbindings != {}
+          kwbinding_generator = PropCheck::Generators.fixed_hash(**@kwbindings)
+          @bindings + [kwbinding_generator]
+        else
+          @bindings
+        end
+      binding_generator = PropCheck::Generators.tuple(*gens)
+      # binding_generator = PropCheck::Generators.fixed_hash(**@kwbindings)
 
       n_runs = 0
       n_successful = 0
@@ -70,7 +139,11 @@ module PropCheck
     private def ensure_not_exhausted!(n_runs)
       return if n_runs >= @config.n_runs
 
-      raise GeneratorExhaustedError, """
+      raise_generator_exhausted!
+    end
+
+    private def raise_generator_exhausted!()
+      raise Errors::GeneratorExhaustedError, """
         Could not perform `n_runs = #{@config.n_runs}` runs,
         (exhausted #{@config.max_generate_attempts} tries)
         because too few generator results were adhering to
@@ -81,7 +154,7 @@ module PropCheck
     end
 
     private def check_attempt(generator_result, n_successful, &block)
-      CheckEvaluator.new(generator_result.root, &block).call
+      block.call(*generator_result.root)
 
     # immediately stop (without shrinnking) for when the app is asked
     # to close by outside intervention
@@ -117,8 +190,8 @@ module PropCheck
       (0...@config.max_generate_attempts)
         .lazy
         .map { binding_generator.generate(size, rng) }
-        .reject { |val| val.root == :"_PropCheck.filter_me" }
-        .select { |val| CheckEvaluator.new(val.root, &@condition).call }
+        .reject { |val| val.root.any? { |elem| elem == :"_PropCheck.filter_me" }}
+        .select { |val| @condition.call(*val.root) }
         .map do |result|
           n_runs += 1
           size += 1
@@ -131,7 +204,7 @@ module PropCheck
     private def show_problem_output(problem, generator_results, n_successful, &block)
       output = @config.verbose ? STDOUT : StringIO.new
       output = pre_output(output, n_successful, generator_results.root, problem)
-      shrunken_result, shrunken_exception, n_shrink_steps = shrink2(generator_results, output, &block)
+      shrunken_result, shrunken_exception, n_shrink_steps = shrink(generator_results, output, &block)
       output = post_output(output, n_shrink_steps, shrunken_result, shrunken_exception)
 
       [output, shrunken_result, shrunken_exception, n_shrink_steps]
@@ -151,24 +224,29 @@ module PropCheck
     end
 
     private def post_output(output, n_shrink_steps, shrunken_result, shrunken_exception)
-      output.puts ''
-      output.puts "Shrunken input (after #{n_shrink_steps} shrink steps):"
-      output.puts "`#{print_roots(shrunken_result)}`"
-      output.puts ""
-      output.puts "Shrunken exception:\n---\n#{shrunken_exception}"
-      output.puts "---"
-      output.puts ""
-
+      if n_shrink_steps == 0
+        output.puts '(shrinking impossible)'
+      else
+        output.puts ''
+        output.puts "Shrunken input (after #{n_shrink_steps} shrink steps):"
+        output.puts "`#{print_roots(shrunken_result)}`"
+        output.puts ""
+        output.puts "Shrunken exception:\n---\n#{shrunken_exception}"
+        output.puts "---"
+        output.puts ""
+      end
       output
     end
 
-    private def print_roots(lazy_tree_hash)
-      lazy_tree_hash.map do |name, val|
-        "#{name} = #{val.inspect}"
-      end.join(", ")
+    private def print_roots(lazy_tree_val)
+      if lazy_tree_val.is_a?(Array) && lazy_tree_val.length == 1 && lazy_tree_val[0].is_a?(Hash)
+        lazy_tree_val[0].ai
+      else
+        lazy_tree_val.ai
+      end
     end
 
-    private def shrink2(bindings_tree, io, &fun)
+    private def shrink(bindings_tree, io, &block)
       io.puts 'Shrinking...' if @config.verbose
       problem_child = bindings_tree
       siblings = problem_child.children.lazy
@@ -190,12 +268,12 @@ module PropCheck
         io.print '.' if @config.verbose
 
         begin
-          CheckEvaluator.new(sibling.root, &fun).call
-        rescue Exception => problem
+          block.call(*sibling.root)
+        rescue Exception => e
           problem_child = sibling
           parent_siblings = siblings
           siblings = problem_child.children.lazy
-          problem_exception = problem
+          problem_exception = e
         end
       end
 

data/lib/prop_check/version.rb

@@ -1,3 +1,3 @@
 module PropCheck
-  VERSION = "0.6.1"
+  VERSION = "0.9.0"
 end

data/prop_check.gemspec

@@ -37,6 +37,6 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 2.5.1'
 
   spec.add_development_dependency "bundler", "~> 2.0"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", "~> 12.3"
   spec.add_development_dependency "rspec", "~> 3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prop_check
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Qqwy/Wiebe-Marten Wijnja
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2019-07-03 00:00:00.000000000 Z
+date: 2020-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '12.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '12.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -81,11 +81,10 @@ files:
 - lib/prop_check/generator.rb
 - lib/prop_check/generators.rb
 - lib/prop_check/helper.rb
+- lib/prop_check/helper/lazy_append.rb
 - lib/prop_check/lazy_tree.rb
 - lib/prop_check/property.rb
-- lib/prop_check/property/check_evaluator.rb
 - lib/prop_check/property/configuration.rb
-- lib/prop_check/rspec.rb
 - lib/prop_check/version.rb
 - prop_check.gemspec
 homepage: https://github.com/Qqwy/ruby-prop_check/
@@ -95,7 +94,7 @@ metadata:
   homepage_uri: https://github.com/Qqwy/ruby-prop_check/
   source_code_uri: https://github.com/Qqwy/ruby-prop_check/
   changelog_uri: https://github.com/Qqwy/ruby-prop_check/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -110,9 +109,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
-signing_key: 
+rubygems_version: 3.0.3
+signing_key:
 specification_version: 4
 summary: PropCheck allows you to do property-based testing, including shrinking.
 test_files: []

data/lib/prop_check/property/check_evaluator.rb

@@ -1,45 +0,0 @@
-module PropCheck
-  class Property
-    ##
-    # A wrapper class that implements the 'Cloaker' concept
-    # which allows us to refer to variables set in 'bindings',
-    # while still being able to access things that are only in scope
-    # in the creator of '&block'.
-    #
-    # This allows us to bind the variables specified in `bindings`
-    # one way during checking and another way during shrinking.
-    class CheckEvaluator
-      include RSpec::Matchers if Object.const_defined?('RSpec')
-
-      def initialize(bindings, &block)
-        @caller = block.binding.receiver
-        @block = block
-        define_named_instance_methods(bindings)
-      end
-
-      def call
-        self.instance_exec(&@block)
-      end
-
-      private def define_named_instance_methods(results)
-        results.each do |name, result|
-          define_singleton_method(name) { result }
-        end
-      end
-
-      ##
-      # Dispatches to caller whenever something is not part of `bindings`.
-      # (No need to invoke this method manually)
-      def method_missing(method, *args, &block)
-        @caller.__send__(method, *args, &block) || super
-      end
-
-      ##
-      # Checks respond_to of caller whenever something is not part of `bindings`.
-      # (No need to invoke this method manually)
-      def respond_to_missing?(*args)
-        @caller.respond_to?(*args) || super
-      end
-    end
-  end
-end

data/lib/prop_check/rspec.rb

@@ -1,14 +0,0 @@
-module PropCheck
-  ##
-  # Integration with RSpec
-  module RSpec
-    # To make it available within examples
-    def self.extend_object(obj)
-      obj.define_method(:forall) do |*args, **kwargs, &block|
-        PropCheck::Property.forall(*args, **kwargs) do
-          instance_exec(self, &block)
-        end
-      end
-    end
-  end
-end