Commits

Meikel Brandmeyer committed 349b2cd

Document domain value interface

  • Participants
  • Parent commits e6520ef

Comments (0)

Files changed (1)

src/main/clojure/clojurecheck/core.clj

         (recur (dec n)))
       (throw (Exception. "trials exhausted while generating input")))))
 
-(deftype DomainValue [domain value])
+;; ## Domain Values
+;;
+;; So far we didn't consider the actual type of value a generator
+;; returns. So naive implementation just returns the generated value.
+;; However this is not enough for shrinking. The value itself is not
+;; enough to do meaningful shrinking. You have to know how you arrived
+;; at the value at hand. So the value itself needs to carry such
+;; knowledge.
+;;
+;; So generators return so called “domain values”. They carry the
+;; generated value itself as well as the instructions on how to shrink
+;; the given value.
+;;
+;; Shrinking itself is implemented as a sequence of shrunken values.
+;; They are tried in turn with the initially failing property. In case
+;; the property still fails the failing value is further shrunken. In
+;; case the property suddenly succeeds the next value from the sequence
+;; is tried.
+(defprotocol DomainValue
+  (#^{:added "2.1"} value
+    [this]
+    "Return the generated value associated with this domain value.")
+  (#^{:added "2.1"} shrink
+    [this]
+    "Return a sequence of less complex value than the one given.
+  In case the value is not further shrinkable, return `nil`."))
 
 (extend-protocol Generator
   clojure.lang.Fn