prop_check 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 912a84633a6ab5b7f209555be0086e4dcafd371f337b289113003edf765fb668
-  data.tar.gz: 92146dcaf693c20f4cb3021178e881495de8b63f3819c254aea186a3780891c0
+  metadata.gz: e59cf670bcc8cf9720d6278e984925c50e75ca65023459174f8b511d6421fb71
+  data.tar.gz: '088e0eb8d2d301bc3c03cc63bf68196969e8653cad37ff0b9d5d10f9b417a1ae'
 SHA512:
-  metadata.gz: 192ed9c6887dc19f29fc3d8aba9278eeb0fd389aab9fae546c940e2831833ea8064ea53e1e903c599d7d7ec2a8fe5bdc04a2c3122c2374a2d1d933b2184a2ab0
-  data.tar.gz: 63005af74e5f0d1757930f64ce031f5cc922e34b4e876cdaebbbf139280e9e923d134440f20ab63129c4fd1647d1e524b07b6ed3800828b29d22ad7e2cc5e394
+  metadata.gz: de5808bced970e0c474367bf125837ac0eefa4aa752acb31cd74e884fea858b98fb518e9fe15493c81f8238e5e0490f3cbc855eda3a9b687196ca7830daad0aa
+  data.tar.gz: 312957d1ab0f990985f43ae7e4b0793df583ff2d3d8bb95573c11fe3e4d9c5f964d91050fe9bafb98ceb92dd6790d2ffce04257b02b0c152d75d9b4772b7423a

data/CHANGELOG.md

@@ -1,3 +1,6 @@
+- 0.17.0
+  - Features:
+    - Recursive generation using `PropCheck::Generators.tree`.
 - 0.16.0
   - Features:
     - New option in `PropCheck::Property::Configuration` to resize all generators at once.

data/README.md

@@ -64,7 +64,7 @@ Before releasing v1.0, we want to finish the following:
 - [x] Builtin generation of `Set`s
 - [x] Builtin generation of `Date`s, `Time`s and `DateTime`s.
 - [x] Configuration option to resize all generators given to a particular Property instance.
-- [ ] A simple way to create recursive generators
+- [x] A simple way to create recursive generators
 - [ ] A usage guide.
 
 ## Nice-to-haves

data/lib/prop_check/generators.rb

@@ -872,5 +872,75 @@ module PropCheck
         end
       end
     end
+
+    ##
+    # Helper to build recursive generators
+    #
+    # Given a `leaf_generator`
+    # and a block which:
+    #  - is given a generator that generates subtrees.
+    #  - it should return the generator for intermediate tree nodes.
+    #
+    # This is best explained with an example.
+    # Say we want to generate a binary tree of integers.
+    #
+    # If we have a struct representing internal nodes:
+    #  ```ruby
+    #  Branch = Struct.new(:left, :right, keyword_init: true)
+    #  ```
+    #  we can generate trees like so:
+    #  ```ruby
+    #  Generators.tree(Generators.integer) do |subtree_gen|
+    #    G.instance(Branch, left: subtree_gen, right: subtree_gen)
+    #  end
+    #  ```
+    #
+    # As another example, consider generating lists of integers:
+    #
+    #     >> G = PropCheck::Generators
+    #     >> G.tree(G.integer) {|child_gen| G.array(child_gen) }.sample(5, size: 37, rng: Random.new(42))
+    #     => [[7, [2, 3], -10], [[-2], [-2, [3]], [[2, 3]]], [], [0, [-2, -3]], [[1], -19, [], [1, -1], [1], [-1, -1], [1]]]
+    #
+    # And finally, here is how one could create a simple generator for parsed JSON data:
+    #
+    # ```ruby`
+    #  G = PropCheck::Generators
+    #  def json
+    #    G.tree(G.one_of(G.boolean, G.real_float, G.ascii_string)) do |json_gen|
+    #      G.one_of(G.array(json_gen), G.hash_of(G.ascii_string, json_gen))
+    #    end
+    #  end
+    # ```
+    #
+    def tree(leaf_generator, &block)
+      # Implementation is based on
+      # https://hexdocs.pm/stream_data/StreamData.html#tree/2
+      Generator.new do |size:, rng:, **other_kwargs|
+        nodes_on_each_level = random_pseudofactors(size.pow(1.1).to_i, rng)
+        result = nodes_on_each_level.reduce(leaf_generator) do |subtree_generator, nodes_on_this_level|
+          frequency(1 => subtree_generator,
+                    2 => block.call(subtree_generator).resize { |_size| nodes_on_this_level })
+        end
+
+        result.generate(size: size, rng: rng, **other_kwargs)
+      end
+    end
+
+    private def random_pseudofactors(size, rng)
+      return [size].to_enum if size < 2
+
+      Enumerator.new do |yielder|
+        loop do
+          factor = rng.rand(1..(Math.log2(size).to_i))
+          if factor == 1
+            yielder << size
+            break
+          else
+            yielder << factor
+            size /= factor
+          end
+        end
+      end
+    end
   end
 end

data/lib/prop_check/version.rb

@@ -1,3 +1,3 @@
 module PropCheck
-  VERSION = '0.16.0'
+  VERSION = '0.17.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prop_check
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Qqwy/Wiebe-Marten Wijnja