Merge pull request #465 from hedgehogqa/add-missing-linq-combinators

Add missing LINQ combinators

Author: AlexeyRaga

src/Hedgehog/Gen.Traversable.fs

@@ -18,14 +18,18 @@ module GenTraversable =
         |> Gen.apply (f a))
       <| ma
 
+    /// Apply a generator-producing function to each element and collect the results.
     let traverse (f: 'a -> Gen<'b>) (ma: #seq<'a>) : Gen<seq<'b>> =
       traverse' f ma |> Gen.map Seq.ofList
 
+    /// Turn a sequence of generators into a generator of a sequence.
     let sequence (gens : #seq<Gen<'a>>) : Gen<seq<'a>> =
         gens |> traverse id
 
+    /// Apply a generator-producing function to each list element and collect the results.
     let traverseList (f: 'a -> Gen<'b>) (ma: List<'a>) : Gen<List<'b>> =
       traverse' f ma
 
+    /// Turn a list of generators into a generator of a list.
     let sequenceList (gens : List<Gen<'a>>) : Gen<List<'a>> =
         gens |> traverseList id

src/Hedgehog/Gen.fs

@@ -23,9 +23,11 @@ module Gen =
     let delay (f : unit -> Gen<'a>) : Gen<'a> =
         Random.delay (toRandom << f) |> ofRandom
 
+    /// Ensures a cleanup function runs after a generator executes, even if it throws an exception.
     let tryFinally (after : unit -> unit) (m : Gen<'a>) : Gen<'a> =
         toRandom m |> Random.tryFinally after |> ofRandom
 
+    /// Catches exceptions thrown by a generator and handles them with a recovery function.
     let tryWith (k : exn -> Gen<'a>) (m : Gen<'a>) : Gen<'a> =
         toRandom m |> Random.tryWith (toRandom << k) |> ofRandom
 

src/Hedgehog/Hedgehog.fsproj

@@ -71,6 +71,7 @@ Failures are automatically simplified, giving developers coherent, intelligible
     <Compile Include="Linq\Gen.fs" />
     <Compile Include="Linq\Gen.Extensions.fs" />
     <Compile Include="Linq\Gen.Collections.fs" />
+    <Compile Include="Linq\Gen.Functions.fs" />
     <Compile Include="Linq\AutoGenExtensions.fs" />
     <Compile Include="Linq\PropertyConfig.fs" />
     <Compile Include="Linq\Property.fs" />

src/Hedgehog/Linq/Gen.Collections.fs

@@ -1,5 +1,6 @@
 namespace Hedgehog.Linq
 
+open System
 open System.Runtime.CompilerServices
 open Hedgehog
 open Hedgehog.FSharp
@@ -23,3 +24,13 @@ type GenListExtensions() =
     [<Extension>]
     static member AddElement(self : Gen<ResizeArray<'T>>, x : 'T) =
         self |> Gen.map List.ofSeq |> Gen.addElement x |> Gen.map ResizeArray
+
+    /// Turn a sequence of generators into a generator of a sequence.
+    [<Extension>]
+    static member Sequence(self : #seq<Gen<'T>>) : Gen<seq<'T>> =
+        self |> Gen.sequence
+
+    /// Apply a generator-producing function to each element and collect the results.
+    [<Extension>]
+    static member Traverse(self : #seq<'T>, f : Func<'T, Gen<'TResult>>) : Gen<seq<'TResult>> =
+        self |> Gen.traverse f.Invoke

src/Hedgehog/Linq/Gen.Extensions.fs

@@ -209,10 +209,26 @@ type GenExtensions private () =
     static member ToRandom (gen : Gen<'T>) : Random<Tree<'T>> =
         Gen.toRandom gen
 
+    /// <summary>
+    /// Ensures a cleanup action runs after the generator executes, even if an exception is thrown.
+    /// </summary>
+    /// <param name="gen">The generator to wrap with cleanup logic.</param>
+    /// <param name="after">Action to execute after the generator completes or fails.</param>
     [<Extension>]
     static member TryFinally (gen : Gen<'T>, after : Action) : Gen<'T> =
         Gen.tryFinally after.Invoke gen
 
+    /// <summary>
+    /// Catches exceptions thrown by a generator and handles them with a recovery function.
+    /// Use this to provide fallback behavior when a generator might throw an exception.
+    /// </summary>
+    /// <param name="gen">The generator that might throw an exception.</param>
+    /// <param name="after">Function that receives the exception and returns a recovery generator.</param>
+    /// <example>
+    /// <code>
+    /// var gen = riskyGen.TryWith(ex => Gen.Constant(defaultValue));
+    /// </code>
+    /// </example>
     [<Extension>]
     static member TryWith (gen : Gen<'T>, after : Func<exn, Gen<'T>>) : Gen<'T> =
         Gen.tryWith after.Invoke gen

src/Hedgehog/Linq/Gen.Functions.fs

@@ -0,0 +1,51 @@
+namespace Hedgehog.Linq
+
+open System
+open System.Runtime.CompilerServices
+open Hedgehog
+open Hedgehog.FSharp
+
+[<AbstractClass; Sealed>]
+type GenFunctionExtensions private () =
+
+    /// <summary>
+    /// Generates a list together with a function that maps each of the distinct
+    /// elements in the list to values generated by outGen.
+    /// </summary>
+    /// <remarks>
+    /// Distinct elements in the input list may map to the same output values.
+    /// For example, [2; 3; 2] may map to ['A'; 'B'; 'A'] or ['A'; 'A'; 'A'],
+    /// but never ['A'; 'B'; 'C']. The generated function throws if called with
+    /// values not present in the input list.
+    /// </remarks>
+    /// <param name="inpGen">Generator for the input list.</param>
+    /// <param name="outGen">Generator for the output values.</param>
+    /// <returns>A generator that produces a tuple of the input list and a mapping function.</returns>
+    [<Extension>]
+    static member WithMapTo(inpGen : Gen<ResizeArray<'T>>, outGen : Gen<'TResult>) : Gen<struct (ResizeArray<'T> * Func<'T, 'TResult>)> =
+        inpGen
+        |> Gen.map List.ofSeq
+        |> Gen.withMapTo outGen
+        |> Gen.map (fun (inputs, f) -> struct (ResizeArray inputs, Func<'T, 'TResult>(f)))
+
+    /// <summary>
+    /// Generates a list together with a function that maps each of the distinct
+    /// elements in the list to distinct values generated by outGen.
+    /// </summary>
+    /// <remarks>
+    /// Distinct elements in the input list are guaranteed to map to distinct
+    /// output values. For example, [2; 3; 2] may map to ['A'; 'B'; 'A'], but
+    /// never ['A'; 'A'; 'A'] or ['A'; 'B'; 'C']. Only use this if the output
+    /// space is large enough that the required number of distinct output values
+    /// are likely to be generated. The generated function throws if called with
+    /// values not present in the input list.
+    /// </remarks>
+    /// <param name="inpGen">Generator for the input list.</param>
+    /// <param name="outGen">Generator for the output values.</param>
+    /// <returns>A generator that produces a tuple of the input list and a mapping function.</returns>
+    [<Extension>]
+    static member WithDistinctMapTo(inpGen : Gen<ResizeArray<'T>>, outGen : Gen<'TResult>) : Gen<struct(ResizeArray<'T> * Func<'T, 'TResult>)> =
+        inpGen
+        |> Gen.map List.ofSeq
+        |> Gen.withDistinctMapTo outGen
+        |> Gen.map (fun (inputs, f) -> struct (ResizeArray inputs, Func<'T, 'TResult>(f)))