Why would you use Builder.Source() in a custom computation expression builder?

Question

Reading through the F# 4.0 spec, I saw the following on page 79 of the PDF:

The auxiliary function src(e) denotes b.Source(e) if the innermost ForEach is from the user code instead of generated by the translation, and a builder b contains a Source method. Otherwise, src(e) denotes e.

This is in the context of the spec's detailed (VERY detailed) description of how computation expressions are parsed and turned into a series of method calls on the expression's builder object. Scott Wlaschin's Computation Expressions series, which I found to be invaluable in helping me understand the rest of the concepts behind computation expressions, doesn't mention a Source method, nor does any other reference I've been able to find. (Google isn't much help with this one, as tons of people talk about source code and any references to Source methods gets buried).

I also don't see Source documented anywhere in the MSDN page on computation expressions. The QueryBuilder class uses Source, so I have one example I can look at, but there's no explanation of why this would be useful in other circumstances.

Under what circumstances would you want to have a Source method on a custom computation expression builder? What would be a scenario where the default ForEach handling is inadequate to one's needs and a Source method would be useful?

@mydogisbox - Thanks for the link, but I saw that page earlier. I realize that Source() is being called with the contents of the in clause (i.e., for item in x produces a call to Source(x)). And I understand that Source should return something suitable to pass into the For. I don't quite see why, though. QueryBuilder.Source wants either an IEnumerable or an IQueryable (which inherits from IEnumerable), both of which are suitable for a For function to iterate over. So why is the Source call needed here? Why not just say "They gave me an IEnumerable, so I'll iterate over it"? — rmunn
I think we are talking about the same thing, I just didn't have enough room in a comment to explain what I meant. The For I'm talking about is QueryBuilder.For, which is called to handle the for expression in query { **for** customer in db.Customers do select customer }. — rmunn

Tomas Petricek Tomas Petricek · Accepted Answer · 2016-02-09T20:14:04

I do not have any insider knowledge about this, but here is why I think the method exists, based on the translation and the implementation in built-in QueryBuilder.

All the operations in QueryBuilder represent the data source using QuerySource<'R, 'Q> where 'R is the type of elements and 'Q is the kind of data source - either IEnumerable or IQueryable.

The fact that there is just one data type means it does not need to define separate overloads for IQueryable and IEnumerable - which would be otherwise needed because the Run method at the end needs to do different things for IEnumerable and for IQueryable.

So, the Source method lets you transform whatever inputs the query can work on into some "internal representation" of the data source. On the opposite end, the Run method turns the data from this internal representation into ordinary value. (In case of QueryBuilder, you never see the QuerySource type in your own code.)

Why would you use Builder.Source() in a custom computation expression builder?

1 Answers