diff --git a/src/FsToolkit.ErrorHandling/Async.fs b/src/FsToolkit.ErrorHandling/Async.fs index c0b07848..e7e4eae7 100644 --- a/src/FsToolkit.ErrorHandling/Async.fs +++ b/src/FsToolkit.ErrorHandling/Async.fs @@ -1,25 +1,56 @@ namespace FsToolkit.ErrorHandling +/// +/// Helper functions for working with the Async type. +/// [] module Async = + /// + /// Converts a value to an Async value + /// + /// The value to convert to an Async value. + /// The Async value. let inline singleton (value: 'value) : Async<'value> = value |> async.Return + /// + /// Converts a value to an Async value + /// + /// The value to convert to an Async value. + /// The Async value. let inline retn (value: 'value) : Async<'value> = value |> async.Return + /// + /// Takes a transformation function and applies it to the value of an Async value. + /// + /// The function to bind over the Async value. + /// The Async value to bind over. + /// The result of binding the function over the Async value. let inline bind ([] binder: 'input -> Async<'output>) (input: Async<'input>) : Async<'output> = async.Bind(input, binder) + /// + /// Applies an Async function to an Async value. + /// + /// The Async function to apply. + /// The Async value to apply the function to. + /// The result of applying the function to the value. let inline apply (applier: Async<'input -> 'output>) (input: Async<'input>) : Async<'output> = bind (fun f' -> bind (fun x' -> singleton (f' x')) input) applier + /// + /// Applies a transformation to the value of an Async value to a new Async value using the provided function. + /// + /// The function to apply to the value of the Async value. + /// The Async value to transform. + /// The transformed Async value. let inline map ([] mapper: 'input -> 'output) (input: Async<'input>) @@ -31,6 +62,13 @@ module Async = ) input + /// + /// Applies a transformation to the values of two Async values to a new Async value using the provided function. + /// + /// The function to apply to the values of the Async values. + /// The first Async value to transform. + /// The second Async value to transform. + /// The transformed Async value. let inline map2 ([] mapper: 'input1 -> 'input2 -> 'output) (input1: Async<'input1>) @@ -47,6 +85,14 @@ module Async = ) input1 + /// + /// Applies a transformation to the values of three Async values to a new Async value using the provided function. + /// + /// The function to apply to the values of the Async values. + /// The first Async value to transform. + /// The second Async value to transform. + /// The third Async value to transform. + /// The transformed Async value. let inline map3 ([] mapper: 'input1 -> 'input2 -> 'input3 -> 'output) (input1: Async<'input1>) @@ -68,21 +114,47 @@ module Async = ) input1 + /// /// Takes two asyncs and returns a tuple of the pair + /// + /// The first async value. + /// The second async value. + /// The tuple of the pair. let inline zip (left: Async<'left>) (right: Async<'right>) : Async<'left * 'right> = bind (fun l -> bind (fun r -> singleton (l, r)) right) left +/// +/// Operators for working with the Async type. +/// module AsyncOperators = + /// + /// Shorthand for Async.map + /// + /// The function to map over the Async value. + /// The Async value to map over. + /// The result of mapping the function over the Async value. let inline () ([] mapper: 'input -> 'output) (input: Async<'input>) : Async<'output> = Async.map mapper input + /// + /// Shorthand for Async.apply + /// + /// The Async function to apply. + /// The Async value to apply the function to. + /// The result of applying the function to the value. let inline (<*>) (applier: Async<'input -> 'output>) (input: Async<'input>) : Async<'output> = Async.apply applier input + /// + /// Shorthand for Async.bind + /// + /// The Async value to bind over. + /// The function to bind over the Async value. + /// The result of binding the function over the Async value. let inline (>>=) (input: Async<'input>) ([] binder: 'input -> Async<'output>) diff --git a/src/FsToolkit.ErrorHandling/Option.fs b/src/FsToolkit.ErrorHandling/Option.fs index 5731a364..33dec41f 100644 --- a/src/FsToolkit.ErrorHandling/Option.fs +++ b/src/FsToolkit.ErrorHandling/Option.fs @@ -1,5 +1,8 @@ namespace FsToolkit.ErrorHandling +/// +/// Operators for working with the Option type. +/// [] module Option = diff --git a/src/FsToolkit.ErrorHandling/OptionCE.fs b/src/FsToolkit.ErrorHandling/OptionCE.fs index 5c2c46ea..29dd8e0b 100644 --- a/src/FsToolkit.ErrorHandling/OptionCE.fs +++ b/src/FsToolkit.ErrorHandling/OptionCE.fs @@ -131,6 +131,9 @@ module OptionCE = /// member inline _.Source(vopt: 'value voption) : 'value option = Option.ofValueOption vopt + /// + /// The default instance of the `OptionBuilder` type. + /// let option = OptionBuilder() [] @@ -176,8 +179,8 @@ module OptionExtensions = /// member inline _.Source(s: #seq<'value>) : #seq<'value> = s - // /// - // /// Method lets us transform data types into our internal representation. - // /// + /// + /// Method lets us transform data types into our internal representation. + /// member inline _.Source(nullable: Nullable<'value>) : 'value option = Option.ofNullable nullable diff --git a/src/FsToolkit.ErrorHandling/OptionOp.fs b/src/FsToolkit.ErrorHandling/OptionOp.fs index f6f6583e..4bc60d55 100644 --- a/src/FsToolkit.ErrorHandling/OptionOp.fs +++ b/src/FsToolkit.ErrorHandling/OptionOp.fs @@ -2,8 +2,18 @@ namespace FsToolkit.ErrorHandling.Operator.Option open FsToolkit.ErrorHandling +/// +/// Operators for working with the Option type. +/// [] module Option = + + /// + /// Shorthand for Option.map + /// + /// The Option value to bind over. + /// The function to bind over the Option value. + /// The result of binding the function over the Option value. let inline (>>=) (input: Option<'input>) ([] binder: 'input -> Option<'output>) diff --git a/src/FsToolkit.ErrorHandling/Result.fs b/src/FsToolkit.ErrorHandling/Result.fs index 2ced74d4..406300d0 100644 --- a/src/FsToolkit.ErrorHandling/Result.fs +++ b/src/FsToolkit.ErrorHandling/Result.fs @@ -1,5 +1,8 @@ namespace FsToolkit.ErrorHandling +/// +/// Helper functions for working with Result values. +/// [] module Result = @@ -115,7 +118,7 @@ module Result = | Error err -> Error(onError err) /// - /// Combines two Result values and returns a new Result value. + /// Applies a function to the value within a Result and returns a new Result with the output of the function. /// /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/apply /// diff --git a/src/FsToolkit.ErrorHandling/ResultCE.fs b/src/FsToolkit.ErrorHandling/ResultCE.fs index 02cda259..9ef5afb6 100644 --- a/src/FsToolkit.ErrorHandling/ResultCE.fs +++ b/src/FsToolkit.ErrorHandling/ResultCE.fs @@ -125,6 +125,9 @@ module ResultCE = /// member inline _.Source(result: Result<'ok, 'error>) : Result<'ok, 'error> = result + /// + /// The Result computation expression. + /// let result = ResultBuilder() [] diff --git a/src/FsToolkit.ErrorHandling/ResultOp.fs b/src/FsToolkit.ErrorHandling/ResultOp.fs index cd9256ef..801ca775 100644 --- a/src/FsToolkit.ErrorHandling/ResultOp.fs +++ b/src/FsToolkit.ErrorHandling/ResultOp.fs @@ -2,20 +2,42 @@ namespace FsToolkit.ErrorHandling.Operator.Result open FsToolkit.ErrorHandling +/// +/// Operators for working with the Result type. +/// [] module Result = + + /// + /// Shorthand for Result.map + /// + /// The function to map over the Result value. + /// The Result value to map over. + /// The result of mapping the function over the Result value. let inline () (([] mapper: 'okInput -> 'okOutput)) (input: Result<'okInput, 'error>) : Result<'okOutput, 'error> = Result.map mapper input + /// + /// Shorthand for Result.apply + /// + /// The Result value containing the function to apply. + /// The Result value containing the value to apply the function to. + /// The result of applying the function in the Result value to the value in the other Result value. let inline (<*>) (applier: Result<'okInput -> 'okOutput, 'error>) (input: Result<'okInput, 'error>) : Result<'okOutput, 'error> = Result.apply applier input + /// + /// Shorthand for Result.bind + /// + /// The Result value to bind over. + /// The function to bind over the Result value. + /// The result of binding the function over the Result value. let inline (>>=) (input: Result<'input, 'error>) ([] binder: 'input -> Result<'okOutput, 'error>) diff --git a/src/FsToolkit.ErrorHandling/ResultOption.fs b/src/FsToolkit.ErrorHandling/ResultOption.fs index 5fd291ad..3fac9cb7 100644 --- a/src/FsToolkit.ErrorHandling/ResultOption.fs +++ b/src/FsToolkit.ErrorHandling/ResultOption.fs @@ -1,22 +1,54 @@ namespace FsToolkit.ErrorHandling +/// +/// Helper functions for working with Result values that contain Option values. +/// [] module ResultOption = + /// + /// Converts a value to a value into a Result which contains the value wrapped in an Option. + /// + /// The value to convert. + /// The value wrapped in an Option and then wrapped in a Result. let inline retn x = Ok(Some x) + /// + /// Applies a transformation function to a Result value that contains an Option value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/map + /// + /// The transformation function to apply. + /// The Result value to apply the transformation function to. + /// The result of applying the transformation function to the Result value. let inline map ([] mapper: 'okInput -> 'okOutput) (input: Result<'okInput option, 'error>) : Result<'okOutput option, 'error> = Result.map (Option.map mapper) input + /// + /// Maps the error value of a Result value that contains an Option value using the provided function. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/maperror + /// + /// The function to map over the error value. + /// The Result value to map the error value of. + /// The result of mapping the error value of the Result value. let inline mapError ([] mapper: 'errorInput -> 'errorOutput) (input: Result<'ok option, 'errorInput>) : Result<'ok option, 'errorOutput> = Result.mapError mapper input + /// + /// Takes a transformation function and applies to to the value in a Result value that contains an Option value, if is is Ok and Some. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/bind + /// + /// The transformation function to apply. + /// The Result value to apply the transformation function to. + /// The result of applying the transformation function to the Result value. let inline bind ([] binder: 'okInput -> Result<'okOutput option, 'error>) (input: Result<'okInput option, 'error>) @@ -27,6 +59,14 @@ module ResultOption = | None -> Ok None) input + /// + /// Applies a transformation function to a Result value that contains an Option value and returns the result wrapped in an Option within a Result. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/apply + /// + /// The Result containing a potential function to apply + /// The Result containing a potential value to apply the function to + /// The result of applying the function to the value, wrapped in an Option and then wrapped in a Result. let inline apply (applier: Result<('okInput -> 'okOutput) option, 'error>) (input: Result<'okInput option, 'error>) @@ -40,6 +80,15 @@ module ResultOption = | _, Error e -> Error e + /// + /// Combines two Result values that contain Option values into a single Result value that contains the result wrapped in an Option. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/map2 + /// + /// The function to combine the two values with. + /// The first Result value to combine. + /// The second Result value to combine. + /// The result of combining the two Result values, wrapped in an Option and then wrapped in a Result. let inline map2 ([] mapper: 'okInput1 -> 'okInput2 -> 'okOutput) (input1: Result<'okInput1 option, 'error>) @@ -53,6 +102,16 @@ module ResultOption = | Error e, _ | _, Error e -> Error e + /// + /// Combines three Result values that contain Option values into a single Result value that contains the result wrapped in an Option. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/map3 + /// + /// The function to combine the three values with. + /// The first Result value to combine. + /// The second Result value to combine. + /// The third Result value to combine. + /// The result of combining the three Result values, wrapped in an Option and then wrapped in a Result. let inline map3 ([] mapper: 'okInput1 -> 'okInput2 -> 'okInput3 -> 'okOutput) (input1: Result<'okInput1 option, 'error>) @@ -68,18 +127,34 @@ module ResultOption = | _, Error e, _ | _, _, Error e -> Error e + /// + /// Combines two Result values that contain Option values into a single Result value that contains the tuple of the two values wrapped in an Option, if they are both Some. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/zip + /// + /// The first Result value to combine. + /// The second Result value to combine. + /// A tuple of the two values wrapped in an Option and then wrapped in a Result. let zip (left: Result<'leftOk option, 'error>) (right: Result<'rightOk option, 'error>) : Result<('leftOk * 'rightOk) option, 'error> = match left, right with - | Ok x1res, Ok x2res -> //Ok(x1res, x2res) + | Ok x1res, Ok x2res -> match x1res, x2res with | Some x1, Some x2 -> Ok(Some(x1, x2)) | _ -> Ok None | Error e, _ -> Error e | _, Error e -> Error e + /// + /// Takes two results and returns a tuple of the error pair + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/ziperror + /// + /// The first Result value to combine. + /// The second Result value to combine. + /// A tuple of the error pair of the input results. let zipError (left: Result<'ok option, 'leftError>) (right: Result<'ok option, 'rightError>) @@ -89,18 +164,37 @@ module ResultOption = | Ok e, _ -> Ok e | _, Ok e -> Ok e + /// /// Replaces the wrapped value with unit + /// + /// The Result value to ignore the value of. + /// The Result value with the value replaced with an Option unit. let inline ignore<'ok, 'error> (resultOpt: Result<'ok option, 'error>) = resultOpt |> map ignore<'ok> + /// + /// Converts a Result into a Result that contains the value wrapped in an Option. + /// + /// The Result to convert. + /// The Result with the value wrapped in an Option. let inline ofResult (result: Result<'ok, 'error>) : Result<'ok option, 'error> = match result with | Ok x -> Ok(Some x) | Error e -> Error e + /// + /// Converts an Option into a Result that contains the Option + /// + /// The Option to convert. + /// The Result with the Option. let inline ofOption (option: 'T option) : Result<'T option, 'error> = Ok option + /// + /// Converts a Choice into a Result that contains the value wrapped in an Option. + /// + /// The Choice to convert. + /// The Result with the value wrapped in an Option. let inline ofChoice (choice: Choice<'ok, 'error>) : Result<'ok option, 'error> = match choice with | Choice1Of2 x -> Ok(Some x) diff --git a/src/FsToolkit.ErrorHandling/ResultOptionOp.fs b/src/FsToolkit.ErrorHandling/ResultOptionOp.fs index 1f11f88c..2f340fef 100644 --- a/src/FsToolkit.ErrorHandling/ResultOptionOp.fs +++ b/src/FsToolkit.ErrorHandling/ResultOptionOp.fs @@ -2,13 +2,56 @@ namespace FsToolkit.ErrorHandling.Operator.ResultOption open FsToolkit.ErrorHandling +/// +/// Operators for working with the Result and Option types. +/// [] module ResultOption = - let inline () f x = ResultOption.map f x - let inline (<*>) f x = ResultOption.apply f x + /// + /// Shorthand for ResultOption.map + /// + /// The function to map over the Result value. + /// The Result value to map over. + /// The result of mapping the function over the Result value. + let inline () + ([] mapper: 'okInput -> 'okOutput) + (input: Result<'okInput option, 'error>) + : Result<'okOutput option, 'error> = + ResultOption.map mapper input - let inline (<*^>) f x = - ResultOption.apply f (Result.map Some x) + /// + /// Shortand for ResultOption.apply + /// + /// The Result value containing the function to apply. + /// The Result value containing the value to apply the function to. + /// The result of applying the function in the Result value to the value in the other Result value. + let inline (<*>) + (applier: Result<('okInput -> 'okOutput) option, 'error>) + (input: Result<'okInput option, 'error>) + : Result<'okOutput option, 'error> = + ResultOption.apply applier input - let inline (>>=) x f = ResultOption.bind f x + /// + /// Shorthand for ResultOption.apply, where the value is wrapped in an Option for you + /// + /// The Result value containing the function to apply. + /// The Result value containing the value to apply the function to. + /// The result of applying the function in the Result value to the value in the other Result value. + let inline (<*^>) + (applier: Result<('okInput -> 'okOutput) option, 'error>) + (input: Result<'okInput, 'error>) + : Result<'okOutput option, 'error> = + ResultOption.apply applier (Result.map Some input) + + /// + /// Shorthand for ResultOption.bind + /// + /// The Result value to bind over. + /// The function to bind over the Result value. + /// The result of binding the function over the Result value. + let inline (>>=) + (input: Result<'okInput option, 'error>) + ([] binder: 'okInput -> Result<'okOutput option, 'error>) + : Result<'okOutput option, 'error> = + ResultOption.bind binder input