Add @property-test-generator

Clean/Doc.dcl

@@ -18,32 +18,36 @@ from Clean.Types import :: Type
  */
 :: MultiLineString = MultiLine !String
 
-class docDescription       d :: !d -> Maybe Description
-class docParams            d :: !d -> [Description]
-class docVars              d :: !d -> [Description]
-class docResults           d :: !d -> [Description]
-class docType              d :: !d -> Maybe Type
-class docThrows            d :: !d -> [Description]
-class docMembers           d :: !d -> [Maybe ClassMemberDoc]
-class docFields            d :: !d -> Maybe [Maybe Description]
-class docConstructors      d :: !d -> Maybe [Maybe ConstructorDoc]
-class docRepresentation    d :: !d -> Maybe (Maybe Description)
-class docPropertyBootstrap d :: !d -> Maybe String
-class docPropertyTestWith  d :: !d -> [PropertyVarInstantiation]
-class docProperties        d :: !d -> [Property]
+class docDescription            d :: !d -> Maybe Description
+class docParams                 d :: !d -> [Description]
+class docVars                   d :: !d -> [Description]
+class docResults                d :: !d -> [Description]
+class docType                   d :: !d -> Maybe Type
+class docThrows                 d :: !d -> [Description]
+class docMembers                d :: !d -> [Maybe ClassMemberDoc]
+class docFields                 d :: !d -> Maybe [Maybe Description]
+class docConstructors           d :: !d -> Maybe [Maybe ConstructorDoc]
+class docRepresentation         d :: !d -> Maybe (Maybe Description)
+class docPropertyBootstrap      d :: !d -> Maybe String
+class docPropertyTestWith       d :: !d -> [PropertyVarInstantiation]
+class docPropertyTestGenerators d :: !d -> [PropertyTestGenerator]
+class docProperties             d :: !d -> [Property]
 
 /**
  * Documentation of a Clean module.
  */
 :: ModuleDoc =
 	{ description        :: !Maybe Description
-	, property_bootstrap :: !Maybe MultiLineString //* For generating unit tests with clean-test
+	, property_bootstrap :: !Maybe MultiLineString      //* For generating unit tests with clean-test
 	, property_test_with :: ![PropertyVarInstantiation] //* With which types to test the properties
+	, property_test_generators :: ![PropertyTestGenerator]
+	  //* Functions to generate values of types for which Gast's {{`gen`}} is not good enough, like {{`Map`}}
 	}
 
 instance docDescription ModuleDoc
 instance docPropertyBootstrap ModuleDoc
 instance docPropertyTestWith ModuleDoc
+instance docPropertyTestGenerators ModuleDoc
 derive gDefault ModuleDoc
 
 /**
@@ -69,12 +73,31 @@ instance docThrows FunctionDoc
 instance docPropertyTestWith FunctionDoc
 instance docProperties FunctionDoc
 
+/**
+ * A property of a function.
+ * Typically, the property can be tested with Gast.
+ *
+ * - `ForAll`: the right-hand side (the third argument) holds for all values of
+ *   the arguments (the second argument). The first argument is the name.
+ */
 :: Property
 	= ForAll !String ![(!String,!Type)] !String
 
+/**
+ * When a property type contains type variables, a `PropertyVarInstantiation`
+ * can be used to instantiate those variables when generating test cases.
+ */
 :: PropertyVarInstantiation = PropertyVarInstantiation !(!String, !Type)
 
-derive gDefault FunctionDoc, Property, PropertyVarInstantiation
+/**
+ * A test generator generates values of some type. The first argument of the
+ * constructor is the function type of the generator, for instance
+ * `[(k,v)] -> {{Map}} k v`. The second argument is the implementation, which
+ * should assume the generator is called `gen` (e.g.: `gen elems = ...`).
+ */
+:: PropertyTestGenerator = PropertyTestGenerator !Type !String
+
+derive gDefault FunctionDoc, Property, PropertyVarInstantiation, PropertyTestGenerator
 
 /**
  * Documentation of a Clean class member.

Clean/Doc.icl

@@ -36,6 +36,7 @@ fromMultiLine (MultiLine s) = s
 instance docDescription       ModuleDoc where docDescription       d = d.ModuleDoc.description
 instance docPropertyBootstrap ModuleDoc where docPropertyBootstrap d = fromMultiLine <$> d.property_bootstrap
 instance docPropertyTestWith  ModuleDoc where docPropertyTestWith  d = d.ModuleDoc.property_test_with
+instance docPropertyTestGenerators ModuleDoc where docPropertyTestGenerators d = d.property_test_generators
 
 instance docDescription      FunctionDoc where docDescription      d = d.FunctionDoc.description
 instance docParams           FunctionDoc where docParams           d = d.FunctionDoc.params
@@ -67,7 +68,7 @@ instance docRepresentation TypeDoc where docRepresentation d = d.TypeDoc.represe
 
 derive gDefault Type, TypeRestriction, ModuleDoc, FunctionDoc, ClassMemberDoc,
 	ConstructorDoc, ClassDoc, TypeDoc, Property, PropertyVarInstantiation,
-	MultiLineString
+	MultiLineString, PropertyTestGenerator
 
 constructorToFunctionDoc :: !ConstructorDoc -> FunctionDoc
 constructorToFunctionDoc d =
@@ -176,6 +177,12 @@ docBlockToDoc{|PropertyVarInstantiation|} (Left [s]) = case split "=" s of
 		Nothing -> Left (UnknownError "type could not be parsed")
 	_ -> Left (UnknownError "property var instantiation could not be parsed")
 
+docBlockToDoc{|PropertyTestGenerator|} (Left [s]) = case 'T'.parseType (fromString sig) of
+	Just t -> Right (PropertyTestGenerator t (trimMultiLine imp), [])
+	Nothing -> Left (UnknownError "type could not be parsed")
+where
+	[sig:imp] = split "\n" s
+
 derive docBlockToDoc ModuleDoc, FunctionDoc, ClassMemberDoc, ConstructorDoc,
 	ClassDoc, TypeDoc
 

Cloogle/DB.icl

@@ -64,13 +64,13 @@ derive JSONEncode ClassDoc, ClassEntry, ClassMemberDoc, CloogleEntry,
 	InstanceEntry, Location, ModuleDoc, ModuleEntry, Priority, RecordField,
 	SyntaxEntry, Type, TypeDef, TypeDefEntry, TypeDefRhs, TypeDoc,
 	TypeRestriction, ABCInstructionEntry, Property, PropertyVarInstantiation,
-	MultiLineString, NGramIndex
+	MultiLineString, NGramIndex, PropertyTestGenerator
 derive JSONDecode ClassDoc, ClassEntry, ClassMemberDoc, CloogleEntry,
 	Constructor, ConstructorDoc, DeriveEntry, FunctionDoc, FunctionEntry,
 	InstanceEntry, Location, ModuleDoc, ModuleEntry, Priority, RecordField,
 	SyntaxEntry, Type, TypeDef, TypeDefEntry, TypeDefRhs, TypeDoc,
 	TypeRestriction, ABCInstructionEntry, Property, PropertyVarInstantiation,
-	MultiLineString, NGramIndex
+	MultiLineString, NGramIndex, PropertyTestGenerator
 
 printersperse :: Bool a [b] -> [String] | print a & print b
 printersperse ia a bs = intercalate (print False a) (map (print ia) bs)