Note: This post was written a while back but sat in draft. I’ve published this now, but I’m not sure it’s relevant to the latest versions etc. so please bear this in mind.
So in a previous post I looked at my first attempt at creating a computational expression in F#. By anyone’s level this was basic. So I figured it was time to look at all the available “standard” methods available for a computational expression. By “standard” I means those which are implciitly recognized by F# as opposed to creating custom methods.
See Computation Expressions (F#) for more info.
There are plenty of posts on this subject from Microsoft or F# for fun or profit, so why am I writing yet another post – basically just to give my perspective and to help me remember this stuff.
Let’s start with the basics, we have a type SampleBuilder defined as
type SampleBuilder() =
// our code will be filled is as required
// but an example might have just the following
member this.Bind(m, f) = f m
We shall use the builder thus
let builder = SampleBuilder()
builder {
// expressions, such as
let x = 100
}
and now to the various builder methods…
Bind
let! x = 100
// translates to
builder.Bind(100, (fun x -> expression))
So as can be seen, in essence the order of the arguments is reversed. So if we were to simply duplicate the way let binding works but in a computational expression we’d write something like
member this.Bind(m, f) =
f m
Return and ReturnFrom
At the time of writing this, I’m a little confused as to the difference between Return and ReturnFrom. Computation expressions and wrapper types states that the Return returns a wrapped type whilst ReturnFrom returns an unwrapped type. However it is seems it’s possible to pretty much return whatever I like as shown below
member this.Return(x) = x
member this.ReturnFrom(x) = x
Return is called when we have a return in the computation expression, i.e.
builder {
return 100
} |> printfn "%A"
and ReturnFrom is used when return! exists, i.e.
builder {
return! 100
} |> printfn "%A"
One slightly odd thing if you’re used to C# or the likes is that we can have multiple return and/or return! in a computational expression as per
builder {
return 100
return! 100
} |> printfn "%A"
As per multiple yield statements, we need a Combine method implemented in our builder to combine the return values. A return does not mean the rest of the computational expression is not executed, it means that the return values are combined to produce a value at the end of the workflow. So for example
builder {
printfn "First"
return 100
printfn "Second"
return 100
} |> printfn "%A"
Assuming our Return method and Combine are as simple as the following
member this.Return(x) =
printfn "Return"
x
member this.Combine(a, b) = a + b
Then our output will look like the following
First
Return
Second
Return
200
In other words, the first printfn (actually the Delay builder method is called for each printfn) is called then the Return method, then the second printfn then the second Return, then the Combine is called. In this case Combine simply adds the return values together to produce the output of the workflow.
Combine
The combine method combines multiple values – so for example if you had something like the following
builder {
yield 100
yield 200
} |> printfn "%A"
without a combine method you’ll get the following compiler error This control construct may only be used if the computation expression builder defines a ‘Combine’ method. Simple enough to see the problem here. So we cannot yield more than once unless we implement a combine method. Here’s an example which implements the combine by creating a list and combining elements into a new list
member this.Combine(a, b) = a @ b
If we now compile this code we’ll get another error, “This control construct may only be used if the computation expression builder defines a ‘Delay’ method”. So we need to implement a Delay method. See the example listed for Delay below…
Delay
The Delay method allows the builder to delay the evaluation of a computational expression until it’s required. For example if we yield multiple times within a computational expression the idea is to combine the yields until we’re ready to invoke something.
The example above creates a list of the yields and then in the Delay we might want to do something with those combined yields. In this example below we’ll simply use the following code
member this.Delay(f) = f()
which essentially just invokes the function passed to the delay.
Run
Whilst the Delay method is used to delay evaluation, the Run method is mean’t to use the delayed expression, i.e. it might be to run something or the likes. An example which simply turns the list created by the combine into an array instead
member this.Run(f) = Array.ofList f
this is obviously a rather simplistic example, had our builder been creating the data for a web service call, for example, possibly run would make the call for us.
For
I again must point anybody reading this section to the excellent post Implementing a builder: The rest of the standard methods where an implementation of the For method is describe, for simplicity I’ll recreate it here
member this.For(sequence:seq<_>, body) =
this.Using(sequence.GetEnumerator(),fun enum ->
this.While(enum.MoveNext,
this.Delay(fun () -> body enum.Current)))
The Using, While and Delay methods are described elsewhere in this post.
Here’s some sample code using the For method from our computational expression block
builder {
for i = 1 to 10 do
printfn "%d" i
}
TryFinally
An implementation of the TryFinally method is fairly straightforward
member this.TryFinally(body, compensation) =
try this.ReturnFrom(body())
finally compensation()
and in usage within a computational expression block, we have
builder {
try
let x = 1 / 0
printfn "should not make it to here"
finally
printfn "exception"
}
In the above code, when we step into the try block we will actually enter the TryFinally method and obviously this then takes over executing the body of the code and then executing the finally block.
TryWith
Very much like the TryFinally block, we have the following implementation
member this.TryWith(body, handler) =
try this.ReturnFrom(body())
with e -> handler e
and an example of the computational expression block might be
builder {
try
let x = 1 / 0
printfn "should not make it to here"
with
| :? DivideByZeroException -> printfn "divide by zero"
}
Using
As the name suggests, this is used for IDisposable types. Here’s a sample of it’s implementation
member thisTryFinally(body, compensation) =
try __.ReturnFrom(body())
finally compensation()
member this.Using(disposable:#System.IDisposable, body) =
let body' = fun () -> body disposable
this.TryFinally(body', fun () ->
match disposable with
| null -> ()
| disp -> disp.Dispose())
The Using method relates to the use! keyword and hence we might have code such as
builder {
use! x = new MemoryStream()
printfn "do something with the memory stream"
}
So at the point use! is invoked our Using method takes over. We i
While
The example of a while loop in a computational expression was lifted from “Implementing a builder: The rest of the standard methods” and I highly recommend anyone visiting this post goes and reads the computational expression series on F# for fun and profit.
So our example code is as follows
let mutable i = 0
let test() = i < 5
let inc() = i <- i + 1
let builder = SampleBuilder()
builder {
while test() do
printfn "%i" i
inc()
} |> ignore
It’s important to note that the three let statements at the top of the source must be global or you’ll get an error along the lines of “The mutable variable ‘i’ is used in an invalid way. Mutable variables cannot be captured by closures. Consider eliminating this use of mutation or using a heap-allocated mutable reference cell via ‘ref’ and ‘!’.”
So our builder code should look something like the following
member this.Bind(m, f) = f m
member this.Return(x) = x
member this.Zero() = this.Return ()
member this.Delay(f) = f
member this.Run(f) = f()
member this.While(guard, body) =
if not (guard())
then
this.Zero()
else
this.Bind( body(), fun () ->
this.While(guard, body))
So as can be seen, in the While method we are passed the guard and the body of the while loop and as expected we need to invoke these bits of code to evaluate them. When the guard completes we invoke the Zero method which in this case simply called the Return method. If the loop has not completed we simply keep looping.
Yield and YieldFrom
We can use yield or yield! from a computational expression, but to do so we need to implement the Yield and YieldFrom methods (respectively) on the builder, otherwise we’ll be greeted with the “This control construct may only be used if the computation expression builder defines a ‘Yield’ method”, here’s an example of the yield being used from a computational expression block
builder {
yield 100
} |> printfn "%A"
// or
builder {
yield! 100
} |> printfn "%A"
An example of the Yield and YieldFrom methods in the builder might look like the following
member this.Yield(x) = Some x
member this.YieldFrom(x) = x
Zero
You may have noticed, if you’ve written your own builder type that something like the following
builder {
}
// or
builder {
} |> ignore
doesn’t compile, this is because a computational expression must have something within the curly braces. So if instead we write the following
builder {
printfn "Hello"
}
We’re get an altogether different error at compile time stating This control construct may only be used if the computational expression builder defines a ‘Zero’ method. Basically a computational expression must return something, either explicitly or implicitly. In this case Zero is used for any implicit return, so we could resolve this error using
member this.Zero() = ()
or ofcourse we might implicitly return the same thing we would with an explicit return such as
member this.Return(x) = x
member this.Zero() = this.Return ()