ClojureCheck / src / main / clojure / clojurecheck / core.clj

Diff from to

src/main/clojure/clojurecheck/core.clj

     :exclude (int float list vec set sorted-set hash-map sorted-map))
   (:use clojure.test))
 
+;; # Interfaces
+;;
+;; ## Generator
+;;
+;; A generator is used to generate random input values. A generator
+;; supports a single method – `arbitrary` – which is called by the
+;; `generate` function.
 (defprotocol Generator
   (#^{:added "2.1"} arbitrary
     [generator size]
-    "Choose an arbitrary value by virtue of the given generator."))
+    "Choose an arbitrary value by virtue of the given generator.
+  The `size` parameter may be used to generate increasingly
+  complex values. May return `nil` when it was not possible to
+  generate a value."))
+
+;; Since a generator might return `nil` in case it was not able to
+;; generate a value (cf. `guard`) `generate` will try to `*trials*`
+;; times to generate a value.
+(def #^{:doc "Number of trials a property is tested with generated input.
+  Default is 1000."
+        :added   "2.0"
+        :dynamic true}
+  *trials*
+  1000)
+
+(defn generate
+  "Try *trials* times to generate a valid random input. This is the
+  public entry point to generate a value via a generator."
+  {:added "2.0"}
+  [gen size]
+  (loop [n *trials*]
+    (if (pos? n)
+      (if-let [dval (arbitrary gen size)]
+        dval
+        (recur (dec n)))
+      (throw (Exception. "trials exhausted while generating input")))))
 
 (deftype DomainValue [domain value])
 
   (let [f (if (fn? f) f (constantly f))]
     (reify Generator (arbitrary [this size] (arbitrary gen (f size))))))
 
-(def #^{:doc "Number of trials a property is tested with generated input.
-  Default is 1000."
-        :added   "2.0"
-        :dynamic true}
-  *trials*
-  1000)
-
-(defn generate-input
-  "Try *trials* times to generate a valid random input."
-  {:added "2.0"}
-  [gen size]
-  (loop [n *trials*]
-    (if (pos? n)
-      (if-let [dval (arbitrary gen size)]
-        dval
-        (recur (dec n)))
-      (throw (Exception. "trials exhausted while generating input")))))
-
 (defn *size-scale*
   "The scale function used to scale up the size guidance with increasing
   trials while testing a property with generated input."
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.