ploeh blog 2017-12-14T20:06:08+00:00 Mark Seemann danish software design http://blog.ploeh.dk Semigroups accumulate http://blog.ploeh.dk/2017/12/11/semigroups-accumulate 2017-12-11T08:28:00+00:00 Mark Seemann <div id="post"> <p> <em>You can accumulate an arbitrary, non-zero number of semigroup values to a single value. An article for object-oriented programmers.</em> </p> <p> This article is part of a <a href="http://blog.ploeh.dk/2017/11/27/semigroups">series about semigroups</a>. In short, a <em>semigroup</em> is an associative binary operation. </p> <p> As you've learned in <a href="http://blog.ploeh.dk/2017/11/20/monoids-accumulate">a previous article</a>, you can accumulate an arbitrary number of monoidal values to a single value. A corresponding property holds for semigroups. </p> <p> <strong>Monoid accumulation</strong> </p> <p> When an instance method <code>Op</code> forms a monoid, you can easily write a function that accumulates an arbitrary number of <code>Foo</code> values: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Foo</span>&nbsp;Accumulate(<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:#2b91af;">Foo</span>&gt;&nbsp;foos) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;acc&nbsp;=&nbsp;Identity; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;f&nbsp;<span style="color:blue;">in</span>&nbsp;foos) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acc&nbsp;=&nbsp;acc.Op(f); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;acc; }</pre> </p> <p> Notice how this generally applicable algorithm starts with the <code>Identity</code> value. One implication of this is that when <code>foos</code> is empty, the return value will be <code>Identity</code>. When <code>Op</code> is a semigroup, however, there's no identity, so this doesn't quite work. You need a value to start the accumulation; something you can return if the collection is empty. </p> <p> <strong>Semigroup accumulation</strong> </p> <p> From <a href="https://www.haskell.org">Haskell</a> you can learn that if you have a semigroup, you can accumulate any non-empty collection: </p> <p> <code>sconcat :: Semigroup a =&gt; NonEmpty a -&gt; a</code> </p> <p> You can read this as: for any generic type <code>a</code>, when <code>a</code> forms a <code>Semigroup</code>, the <code>sconcat</code> function takes a non-empty list of <code>a</code> values, and reduces them to a single <code>a</code> value. <code>NonEmpty a</code> is a list with at least one element. </p> <p> <strong>NotEmptyCollection</strong> </p> <p> You can also define a <code>NotEmptyCollection&lt;T&gt;</code> class in C#: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">NotEmptyCollection</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;:&nbsp;<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:#2b91af;">T</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;NotEmptyCollection(<span style="color:#2b91af;">T</span>&nbsp;head,&nbsp;<span style="color:blue;">params</span>&nbsp;<span style="color:#2b91af;">T</span>[]&nbsp;tail) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(head&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(head)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Head&nbsp;=&nbsp;head; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Tail&nbsp;=&nbsp;tail; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">T</span>&nbsp;Head&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;Tail&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;Count&nbsp;{&nbsp;<span style="color:blue;">get</span>&nbsp;=&gt;&nbsp;<span style="color:blue;">this</span>.Tail.Count&nbsp;+&nbsp;1;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IEnumerator</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;GetEnumerator() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">yield</span>&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.Head; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;item&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:blue;">this</span>.Tail) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">yield</span>&nbsp;<span style="color:blue;">return</span>&nbsp;item; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IEnumerator</span>&nbsp;<span style="color:#2b91af;">IEnumerable</span>.GetEnumerator() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.GetEnumerator(); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> Because of the way the constructor is defined, you <em>must</em> supply at least one element in order to create an instance. You can provide any number of extra elements via the <code>tail</code> array, but one is minimum. </p> <p> The <code>Count</code> property returns the number of elements in <code>Tail</code>, plus one, because there's always a <code>Head</code> value. </p> <p> The <code>GetEnumerator</code> method returns an iterator that always starts with the <code>Head</code> value, and proceeds with all the <code>Tail</code> values, if there are any. </p> <p> <strong>Finding the maximum of a non-empty collection</strong> </p> <p> As you've already learned, <code>Math.Max</code> is a semigroup. Although the .NET Base Class Library has built-in methods for this, you can use a generally applicable algorithm to find the maximum value in a non-empty list of integers. </p> <p> <pre><span style="color:blue;">private</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">int</span>&nbsp;Accumulate(<span style="color:#2b91af;">NotEmptyCollection</span>&lt;<span style="color:blue;">int</span>&gt;&nbsp;numbers) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;acc&nbsp;=&nbsp;numbers.Head; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;n&nbsp;<span style="color:blue;">in</span>&nbsp;numbers.Tail) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acc&nbsp;=&nbsp;<span style="color:#2b91af;">Math</span>.Max(acc,&nbsp;n); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;acc; }</pre> </p> <p> Notice how similar this algorithm is to monoid accumulation! The only difference is that instead of using <code>Identity</code> to get started, you can use <code>Head</code>, and then loop over all elements of <code>Tail</code>. </p> <p> You can use it like this: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;nec&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">NotEmptyCollection</span>&lt;<span style="color:blue;">int</span>&gt;(42,&nbsp;1337,&nbsp;123); <span style="color:blue;">var</span>&nbsp;max&nbsp;=&nbsp;Accumulate(nec);</pre> </p> <p> Here, <code>max</code> is obviously <code>1337</code>. </p> <p> As usual, however, this is much nicer, and more succinct in Haskell: </p> <p> <pre>Prelude Data.Semigroup Data.List.NonEmpty&gt; getMax $ sconcat $ fmap Max $ 42 :| [1337, 123] 1337</pre> </p> <p> That's hardly <a href="http://blog.ploeh.dk/2015/08/03/idiomatic-or-idiosyncratic">the idiomatic</a> way of getting a maximum element in Haskell, but it does show how you can 'click together' concepts in order to achieve a goal. </p> <p> <strong>Aggregate</strong> </p> <p> Perhaps the observant reader will, at this point, have recalled to him- or herself that the .NET Base Class Library already includes an <code>Aggregate</code> extension method, with an overload that takes a seed. In general, the simpliest <code>Aggregate</code> method doesn't gracefully handle empty collections, but using the overload that takes a seed is more robust. You can rewrite the above <code>Accumulate</code> method using <code>Aggregate</code>: </p> <p> <pre><span style="color:blue;">private</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">int</span>&nbsp;Accumulate(<span style="color:#2b91af;">NotEmptyCollection</span>&lt;<span style="color:blue;">int</span>&gt;&nbsp;numbers) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;numbers.Tail.Aggregate( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;numbers.Head, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(x,&nbsp;y)&nbsp;=&gt;&nbsp;<span style="color:#2b91af;">Math</span>.Max(x,&nbsp;y)); }</pre> </p> <p> Notice how you can pass <code>Head</code> as the seed, and accumulate the <code>Tail</code> using that starting point. The <code>Aggregate</code> method is more like Haskell's <code>sconcat</code> for semigroups than <code>mconcat</code> for monoids. </p> <p> <strong>Summary</strong> </p> <p> A semigroup operation can be used to reduce values to a single value, just like a monoid can. The only difference is that a semigroup operation can't reduce an empty collection, whereas a monoid can. </p> <p> <strong>Next:</strong> Quasigroups </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Bounding box semigroup http://blog.ploeh.dk/2017/12/04/bounding-box-semigroup 2017-12-04T08:40:00+00:00 Mark Seemann <div id="post"> <p> <em>A semigroup example for object-oriented programmers.</em> </p> <p> This article is part of <a href="http://blog.ploeh.dk/2017/10/05/monoids-semigroups-and-friends">a larger series about monoids, semigroups, and other group-like algebraic structures</a>. In this article, you'll see a non-trivial example of a <a href="http://blog.ploeh.dk/2017/11/27/semigroups">semigroup</a> that's <em>not</em> a <a href="http://blog.ploeh.dk/2017/10/06/monoids">monoid</a>. In short, a semigroup is an associative binary operation. </p> <p> <strong>Shapes</strong> </p> <p> Imagine that you're developing a library of two-dimensional shapes, and that, for various reasons, each shape should have a <em>bounding box</em>. For example, here's a blue circle with a green bounding box: </p> <p> <img src="/content/binary/circle-with-bounding-box.png" alt="Circle with bounding box."> </p> <p> The code for a circle shape could look like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Circle</span>&nbsp;:&nbsp;<span style="color:#2b91af;">ICanHasBox</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;X&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;Y&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;Radius&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;Circle(<span style="color:blue;">int</span>&nbsp;x,&nbsp;<span style="color:blue;">int</span>&nbsp;y,&nbsp;<span style="color:blue;">int</span>&nbsp;radius) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.X&nbsp;=&nbsp;x; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Y&nbsp;=&nbsp;y; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Radius&nbsp;=&nbsp;<span style="color:#2b91af;">Math</span>.Abs(radius); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">BoundingBox</span>&nbsp;BoundingBox &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">get</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">BoundingBox</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.X&nbsp;-&nbsp;<span style="color:blue;">this</span>.Radius, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Y&nbsp;-&nbsp;<span style="color:blue;">this</span>.Radius, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Radius&nbsp;*&nbsp;2, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Radius&nbsp;*&nbsp;2); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> In addition to the <code>Circle</code> class, you could have other shapes, such as rectangles, triangles, or even irregular shapes, each of which have a bounding box. </p> <p> <strong>Bounding box unions</strong> </p> <p> If you have two shapes, you also have two (green) bounding boxes, but perhaps you'd like to find the (orange) bounding box of the union of both shapes. </p> <p> <img src="/content/binary/union-of-bounding-boxes.png" alt="Union of two shapes with bounding boxes."> </p> <p> That's fairly easy to do: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">BoundingBox</span>&nbsp;Unite(<span style="color:#2b91af;">BoundingBox</span>&nbsp;other) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;newX&nbsp;=&nbsp;<span style="color:#2b91af;">Math</span>.Min(<span style="color:blue;">this</span>.X,&nbsp;other.X); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;newY&nbsp;=&nbsp;<span style="color:#2b91af;">Math</span>.Min(<span style="color:blue;">this</span>.Y,&nbsp;other.Y); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;newRightX&nbsp;=&nbsp;<span style="color:#2b91af;">Math</span>.Max(<span style="color:blue;">this</span>.rightX,&nbsp;other.rightX); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;newTopY&nbsp;=&nbsp;<span style="color:#2b91af;">Math</span>.Max(<span style="color:blue;">this</span>.topY,&nbsp;other.topY); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">BoundingBox</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;newX, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;newY, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;newRightX&nbsp;-&nbsp;newX, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;newTopY&nbsp;-&nbsp;newY); }</pre> </p> <p> The <code>Unite</code> method is an instance method on the <code>BoundingBox</code> class, so <a href="http://blog.ploeh.dk/2017/10/06/monoids">it's a binary operation</a>. It's also associative, because for all <code>x</code>, <code>y</code>, and <code>z</code>, <code>isAssociative</code> is <code>true</code>: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;isAssociative&nbsp;=&nbsp;x.Unite(y).Unite(z)&nbsp;==&nbsp;x.Unite(y.Unite(z));</pre> </p> <p> Since the operation is associative, it's at least a semigroup. </p> <p> <strong>Lack of identity</strong> </p> <p> Is <code>Unite</code> also a monoid? In order to be a monoid, a binary operation must not only be associative, but also have an identity element. In <a href="http://blog.ploeh.dk/2017/10/23/convex-hull-monoid">a previous article</a>, you saw how the union of two <a href="https://en.wikipedia.org/wiki/Convex_hull">convex hulls</a> formed a monoid. A bounding box seems to be conceptually similar to a convex hull, so you'd be excused to think that our previous experience applies here as well. </p> <p> It doesn't. </p> <p> There's no <em>identity bounding box</em>. The difference between a convex hull and a bounding box is that it's possible to define an empty hull as an empty set of coordinates. A bounding box, on the other hand, always has a coordinate and a size. </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">struct</span>&nbsp;<span style="color:#2b91af;">BoundingBox</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">int</span>&nbsp;rightX; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">int</span>&nbsp;topY; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;X&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;Y&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;Width&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;Height&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;More&nbsp;members,&nbsp;including&nbsp;Unite...</span> }</pre> </p> <p> An identity element, if one exists, is one where if you <code>Unite</code> it with another <code>BoundingBox</code> object, the return value will be the other object. </p> <p> Consider, then, a (green) <code>BoundingBox x</code>. Any other <code>BoundingBox</code> inside of of <code>x</code>, including <code>x</code> itself, is a candidate for an identity element: </p> <p> <img src="/content/binary/bounding-box-with-identity-candidates.png" alt="Bounding box with candidates for an identity element."> </p> <p> In a <a href="https://en.wikipedia.org/wiki/Real_number">real</a> coordinate system, there's infinitely many candidates contained in <code>x</code>. As long as a candidate is wholly contained within <code>x</code>, then the union of the candidate and <code>x</code> will return <code>x</code>. </p> <p> In the code example, however, coordinates are 32-bit integers, so for any bounding box <code>x</code>, there's only a finite number of candidates. Even for the smallest possible bounding box, though, the box itself is an identity candidate. </p> <p> In order to be an identity element, however, the <em>same</em> element must behave as the identity element for <em>all</em> bounding boxes. It is, therefore, trivial to find a counter-example: </p> <p> <img src="/content/binary/bounding-box-identity-counter-example.png" alt="Bounding box identity element counter-example."> </p> <p> Just pick any other <code>BoundingBox y</code> outside of <code>x</code>. Every identity candidate must be within <code>x</code>, and therefore the union of the candidate and <code>y</code> cannot be <code>y</code>. </p> <p> In code, you can demonstrate the lack of identity with an <a href="https://fscheck.github.io/FsCheck">FsCheck</a>-based test like this: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Property</span>&nbsp;UniteHasNoIdentity(<span style="color:#2b91af;">PositiveInt</span>&nbsp;w,&nbsp;<span style="color:#2b91af;">PositiveInt</span>&nbsp;h) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;genCandidate&nbsp;=&nbsp;<span style="color:blue;">from</span>&nbsp;xi&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Gen</span>.Choose(1,&nbsp;w.Get) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">from</span>&nbsp;yi&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Gen</span>.Choose(1,&nbsp;h.Get) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">from</span>&nbsp;wi&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Gen</span>.Choose(1,&nbsp;w.Get&nbsp;-&nbsp;xi&nbsp;+&nbsp;1) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">from</span>&nbsp;hi&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Gen</span>.Choose(1,&nbsp;h.Get&nbsp;-&nbsp;yi&nbsp;+&nbsp;1) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">select</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">BoundingBox</span>(xi,&nbsp;yi,&nbsp;wi,&nbsp;hi); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#2b91af;">Prop</span>.ForAll( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;genCandidate.ToArbitrary(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;identityCandidate&nbsp;=&gt; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;x&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">BoundingBox</span>(1,&nbsp;1,&nbsp;w.Get,&nbsp;h.Get); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;Show&nbsp;that&nbsp;the&nbsp;candidate&nbsp;behaves&nbsp;like&nbsp;identity&nbsp;for&nbsp;x</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(x,&nbsp;x.Unite(identityCandidate)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(x,&nbsp;identityCandidate.Unite(x)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;Counter-example</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;y&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">BoundingBox</span>(0,&nbsp;0,&nbsp;1,&nbsp;1); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.NotEqual(y,&nbsp;y.Unite(identityCandidate)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}); }</pre> </p> <p> This example uses the <a href="https://www.nuget.org/packages/FsCheck.Xunit">FsCheck.Xunit</a> glue library for <a href="https://xunit.github.io">xUnit.net</a>. Notice that although FsCheck is written in F#, you can also use it from C#. This test passes. </p> <p> It follows the above 'proof' by first generating an identity candidate for <code>x</code>. This is any <code>BoundingBox</code> contained within <code>x</code>, including <code>x</code> itself. In order to keep the code as simple as possible, <code>x</code> is always placed at the coordinate <em>(1, 1)</em>. </p> <p> The test proceeds to utilise two <a href="http://xunitpatterns.com/Guard%20Assertion.html">Guard Assertions</a> to show that <code>identityCandidate</code> does, indeed, behave like an identity for <code>x</code>. </p> <p> Finally, the test finds a trivial counter-example in <code>y</code>, and verifies that <code>y.Unite(identityCandidate)</code> is not equal to <code>y</code>. Therefore, <code>identityCandidate</code> is <em>not</em> the identity for <code>y</code>. </p> <p> <code>Unite</code> is a semigroup, but not a monoid, because no identity element exists. </p> <p> <strong>Summary</strong> </p> <p> This article demonstrates (via an example) that non-trivial semigroups exist in normal object-oriented programming. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/12/11/semigroups-accumulate">Semigroups accumulate</a>. </p> </div> <div id="comments"> <hr /> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="http://criticalsoftwareblog.com/">Yacoub Massad</a></div> <div class="comment-content"> Thank you for writing about category theory. I just have a small note. "Just pick any other BoundingBox y partially or wholly outside of x." I think that one should pick a BoundingBox y wholly outside of x. Other wise the intersection between x and y would return x or y when we pass it to x.Unite or y.Unite respectively. <br> Thanks <br> </div> <div class="comment-date">2017-12-08 16:04 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Yacoub, thank you for writing. The operation used here isn't the <em>intersection</em>, but rather the <em>union</em> of two bounding boxes; that's the reason I called the method <code>Unite</code>. </p> </div> <div class="comment-date">2017-12-09 12:55 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://criticalsoftwareblog.com/">Yacoub Massad</a></div> <div class="comment-content"> <p> Hello Mark. I am aware of this, but maybe I did not explain my self correctly. <br> What I am trying to say is that when coming up with a counter-example, we should choose a BoundingBox y wholly outside of x (not just partially outside of x). <br> If we choose a BoundingBox y partially outside of x, then the intersection between x and y (the BoundingBox z = the area shared between x and y) is a valid identity element. <br> </p> </div> <div class="comment-date">2017-12-09 13:05 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Yacoub, I think you're right; sorry about that! </p> <p> Perhaps I should have written <em>Just pick any other <code>BoundingBox y</code> partially or wholly outside of the candidate.</em> Would that have been correct? </p> </div> <div class="comment-date">2017-12-09 13:57 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://criticalsoftwareblog.com/">Yacoub Massad</a></div> <div class="comment-content"> <p> That would be correct. I am not sure though if this is the best way to explain it. <br> <br> y being wholly ourside of x seems better to me. <br> </p> </div> <div class="comment-date">2017-12-09 14:15 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Yacoub, I've corrected the text in the article. Thank you for the feedback! </p> </div> <div class="comment-date">2017-12-09 15:21 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Semigroups http://blog.ploeh.dk/2017/11/27/semigroups 2017-11-27T12:39:00+00:00 Mark Seemann <div id="post"> <p> <em>Introduction to semigroups for object-oriented programmers.</em> </p> <p> This article is part of <a href="http://blog.ploeh.dk/2017/10/05/monoids-semigroups-and-friends">a larger series about monoids, semigroups, and other group-like algebraic structures</a>. In this article, you'll learn what a semigroup is, and what distinguishes it from a <a href="http://blog.ploeh.dk/2017/10/06/monoids">monoid</a>. </p> <p> <img src="/content/binary/monoids-subset-of-semigroups.png" alt="Monoids are a subset of semigroups."> </p> <p> Semigroups form a superset of monoids. They are associative binary operations. While monoids additionally require that an identity element exists, no such requirement exist for semigroups. In other words, all monoids are semigroups, but not all semigroups are monoids. </p> <p> This article gives you an overview of semigroups, as well as a few small examples. A supplemental article will show a more elaborate example. </p> <p> <strong>Minimum</strong> </p> <p> An operation that returns the smallest of two values form a semigroup. In the .NET Base Class Library, such an operation is already defined for many numbers, for example 32-bit integers. Since associativity is a property of a semigroup, it makes sense to demonstrate it with a property-based test, here using <a href="https://fscheck.github.io/FsCheck">FsCheck</a>: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;IntMinimumIsAssociative(<span style="color:blue;">int</span>&nbsp;x,&nbsp;<span style="color:blue;">int</span>&nbsp;y,&nbsp;<span style="color:blue;">int</span>&nbsp;z) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Math</span>.Min(<span style="color:#2b91af;">Math</span>.Min(x,&nbsp;y),&nbsp;z), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Math</span>.Min(x,&nbsp;<span style="color:#2b91af;">Math</span>.Min(y,&nbsp;z))); }</pre> </p> <p> This example uses the <a href="https://www.nuget.org/packages/FsCheck.Xunit">FsCheck.Xunit</a> glue library for <a href="https://xunit.github.io">xUnit.net</a>. Notice that although FsCheck is written in F#, you can also use it from C#. This test (as well as all other tests in this article) passes. </p> <p> For mathematical integers, no identity element exists, so the minimum operation doesn't form a monoid. In practice, however, .NET 32-bit integers <em>do</em> have an identity element: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;MimimumIntHasIdentity(<span style="color:blue;">int</span>&nbsp;x) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(x,&nbsp;<span style="color:#2b91af;">Math</span>.Min(<span style="color:blue;">int</span>.MaxValue,&nbsp;x)); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(x,&nbsp;<span style="color:#2b91af;">Math</span>.Min(x,&nbsp;<span style="color:blue;">int</span>.MaxValue)); }</pre> </p> <p> <a href="https://msdn.microsoft.com/en-us/library/system.int32.maxvalue">Int32.MaxValue</a> is the maximum possible 32-bit integer value, so it effectively behaves as the identity for the 32-bit integer minimum operation. All 32-bit numbers are smaller than, or equal to, <code>Int32.MaxValue</code>. This effectively makes <code>Math.Min(int, int)</code> a monoid, but conceptually, it's not. </p> <p> This may be clearer if, instead of 32-bit integers, you consider <a href="https://msdn.microsoft.com/en-us/library/system.numerics.biginteger">BigInteger</a>, which is an arbitrarily large (or small) integer. The <em>minimum</em> operation is still associative: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;BigIntMinimumIsAssociative( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">BigInteger</span>&nbsp;x, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">BigInteger</span>&nbsp;y, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">BigInteger</span>&nbsp;z) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">BigInteger</span>.Min(<span style="color:#2b91af;">BigInteger</span>.Min(x,&nbsp;y),&nbsp;z), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">BigInteger</span>.Min(x,&nbsp;<span style="color:#2b91af;">BigInteger</span>.Min(y,&nbsp;z))); }</pre> </p> <p> No identity element exists, however, because no matter which integer you have, you can always find one that's bigger: no maximum value exists. This makes <code>BigInteger.Min</code> a semigroup, but not a monoid. </p> <p> <strong>Maximum</strong> </p> <p> Like <em>minimum</em>, the <em>maximum</em> operation forms a semigroup, here demonstrated by <code>BigInteger.Max</code>: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;BigIntMaximumIsAssociative( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">BigInteger</span>&nbsp;x, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">BigInteger</span>&nbsp;y, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">BigInteger</span>&nbsp;z) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">BigInteger</span>.Max(<span style="color:#2b91af;">BigInteger</span>.Max(x,&nbsp;y),&nbsp;z), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">BigInteger</span>.Max(x,&nbsp;<span style="color:#2b91af;">BigInteger</span>.Max(y,&nbsp;z))); }</pre> </p> <p> Again, like minimum, no identity element exists because the set of integers is infinite; you can always find a bigger or smaller number. </p> <p> Minimum and maximum operations aren't limited to primitive numbers. If values can be compared, you can always find the smallest or largest of two values, here demonstrated with <code>DateTime</code> values: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;DateTimeMaximumIsAssociative( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">DateTime</span>&nbsp;x, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">DateTime</span>&nbsp;y, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">DateTime</span>&nbsp;z) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">DateTime</span>,&nbsp;<span style="color:#2b91af;">DateTime</span>,&nbsp;<span style="color:#2b91af;">DateTime</span>&gt;&nbsp;dtMax&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(dt1,&nbsp;dt2)&nbsp;=&gt;&nbsp;dt1&nbsp;&gt;&nbsp;dt2&nbsp;?&nbsp;dt1&nbsp;:&nbsp;dt2; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dtMax(dtMax(x,&nbsp;y),&nbsp;z), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dtMax(x,&nbsp;dtMax(y,&nbsp;z))); }</pre> </p> <p> As was the case with 32-bit integers, however, the presence of <a href="https://msdn.microsoft.com/en-us/library/system.datetime.minvalue">DateTime.MinValue</a> effectively makes <code>dtMax</code> a monoid, but <em>conceptually</em>, no identity element exists, because dates are infinite. </p> <p> <strong>First</strong> </p> <p> Another binary operation operation simply returns the first of two values: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">T</span>&nbsp;First&lt;<span style="color:#2b91af;">T</span>&gt;(<span style="color:#2b91af;">T</span>&nbsp;x,&nbsp;<span style="color:#2b91af;">T</span>&nbsp;y) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;x; }</pre> </p> <p> This may seem pointless, but <code>First</code> <em>is</em> associative: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;FirstIsAssociative(<span style="color:#2b91af;">Guid</span>&nbsp;x,&nbsp;<span style="color:#2b91af;">Guid</span>&nbsp;y,&nbsp;<span style="color:#2b91af;">Guid</span>&nbsp;z) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;First(First(x,&nbsp;y),&nbsp;z), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;First(x,&nbsp;First(y,&nbsp;z))); }</pre> </p> <p> On the other hand, there's no identity element, because there's no <em>left identity</em>. The <em>left identity</em> is an element <code>e</code> such that <code>First(e, x) == x</code> for any <code>x</code>. Clearly, for any generic type <code>T</code>, no such element exists because <code>First(e, x)</code> will only return <code>x</code> when <code>x</code> is equal to <code>e</code>. (There are, however, degenerate types for which an identity exists for <code>First</code>. Can you find an example?) </p> <p> <strong>Last</strong> </p> <p> Like <code>First</code>, a binary operation that returns the last (second) of two values also forms a semigroup: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">T</span>&nbsp;Last&lt;<span style="color:#2b91af;">T</span>&gt;(<span style="color:#2b91af;">T</span>&nbsp;x,&nbsp;<span style="color:#2b91af;">T</span>&nbsp;y) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;y; }</pre> </p> <p> Similar to <code>First</code>, <code>Last</code> is associative: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;LastIsAssociative(<span style="color:#2b91af;">String</span>&nbsp;x,&nbsp;<span style="color:#2b91af;">String</span>&nbsp;y,&nbsp;<span style="color:#2b91af;">String</span>&nbsp;z) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Last(Last(x,&nbsp;y),&nbsp;z), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Last(x,&nbsp;Last(y,&nbsp;z))); }</pre> </p> <p> As is also the case for <code>First</code>, no identity exists for <code>Last</code>, but here the problem is the lack of a <em>right identity</em>. The <em>right identity</em> is an element <code>e</code> for which <code>Last(x, e) == x</code> for all <code>x</code>. Clearly, <code>Last(x, e)</code> can only be equal to <code>x</code> if <code>e</code> is equal to <code>x</code>. </p> <p> <strong>Aggregation</strong> </p> <p> Perhaps you think that operations like <code>First</code> and <code>Last</code> seem useless in practice, but when you have a semigroup, you can reduce any non-empty sequence to a single value. In C#, you can use the <a href="https://msdn.microsoft.com/en-us/library/bb548651">Aggregate</a> LINQ method for this. For example </p> <p> <pre><span style="color:blue;">var</span>&nbsp;a&nbsp;=&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;1,&nbsp;0,&nbsp;1337,&nbsp;-10,&nbsp;42&nbsp;}.Aggregate(<span style="color:#2b91af;">Math</span>.Min); </pre> </p> <p> returns <code>-10</code>, while </p> <p> <pre><span style="color:blue;">var</span>&nbsp;a&nbsp;=&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;1,&nbsp;0,&nbsp;1337,&nbsp;-10,&nbsp;42&nbsp;}.Aggregate(<span style="color:#2b91af;">Math</span>.Max); </pre> </p> <p> returns <code>1337</code>. Notice that the input sequence is the same in both examples, but the semigroup differs. Likewise, you can use <code>Aggregate</code> with <code>First</code>: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;a&nbsp;=&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;1,&nbsp;0,&nbsp;1337,&nbsp;-10,&nbsp;42&nbsp;}.Aggregate(First); </pre> </p> <p> Here, <code>a</code> is <code>1</code>, while </p> <p> <pre><span style="color:blue;">var</span>&nbsp;a&nbsp;=&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;1,&nbsp;0,&nbsp;1337,&nbsp;-10,&nbsp;42&nbsp;}.Aggregate(Last); </pre> </p> <p> returns <code>42</code>. </p> <p> LINQ has specialised methods like <a href="https://msdn.microsoft.com/en-us/library/bb352408">Min</a>, <a href="https://msdn.microsoft.com/en-us/library/bb358775">Last</a>, and so on, but from the perspective of behaviour, <code>Aggregate</code> would have been enough. While there may be performance reasons why some of those specialised methods exist, you can think of all of them as being based on the same abstraction: that of a semigroup. </p> <p> <code>Aggregate</code>, and many of the specialised methods, throw an exception if the input sequence is empty. This is because there's no identity element in a semigroup. The method doesn't know how to create a value of the type <code>T</code> from an empty list. </p> <p> If, on the other hand, you have a monoid, you can return the identity element in case of an empty sequence. <a href="https://www.haskell.org">Haskell</a> explicitly makes this distinction with <code>sconcat</code> and <code>mconcat</code>, but I'm not going to go into that now. </p> <p> <strong>Summary</strong> </p> <p> Semigroups are associative binary operations. In the previous <a href="http://blog.ploeh.dk/2017/10/06/monoids">article series about monoids</a> you saw plenty of examples, and since all monoids are semigroups, you've already seen more than one semigroup example. In this article, however, you saw four examples of semigroups that are <em>not</em> monoids. </p> <p> All four examples in this article are simple, and may not seem like 'real-world' examples. In the next article, then, you'll get a more realistic example of a semigroup that's not a monoid. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/12/04/bounding-box-semigroup">Bounding box semigroup</a>. </p> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Monoids accumulate http://blog.ploeh.dk/2017/11/20/monoids-accumulate 2017-11-20T08:00:00+00:00 Mark Seemann <div id="post"> <p> <em>You can accumulate an arbitrary number of monoidal values to a single value. An article for object-oriented programmers.</em> </p> <p> This article is part of a <a href="http://blog.ploeh.dk/2017/10/06/monoids">series about monoids</a>. In short, a <em>monoid</em> is an associative binary operation with a neutral element (also known as <em>identity</em>). </p> <p> Recall that a binary operation is an operation involving two arguments of the same type, and returning a value of that type. </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Foo</span>&nbsp;Op(<span style="color:#2b91af;">Foo</span>&nbsp;x,&nbsp;<span style="color:#2b91af;">Foo</span>&nbsp;y)</pre> </p> <p> Notice that such an operation reduces two <code>Foo</code> values to a single <code>Foo</code> value. </p> <p> <strong>Accumulation</strong> </p> <p> Since you have an operation that can reduce two values to a single value, you can use that single value as the input for yet another binary operation. This enables you to accumulate, or aggregate, an arbitrary number of values. </p> <p> Consider the instance variation of the above <code>Op</code> method: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Foo</span>&nbsp;Op(<span style="color:#2b91af;">Foo</span>&nbsp;foo)</pre> </p> <p> This is another representation of the operation, but instead of being a static method, it's an instance method on the <code>Foo</code> class. </p> <p> When <code>Op</code> is a monoid, you can easily write a function that accumulates an arbitrary number of <code>Foo</code> values: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Foo</span>&nbsp;Accumulate(<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:#2b91af;">Foo</span>&gt;&nbsp;foos) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;acc&nbsp;=&nbsp;Identity; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;f&nbsp;<span style="color:blue;">in</span>&nbsp;foos) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acc&nbsp;=&nbsp;acc.Op(f); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;acc; }</pre> </p> <p> You start with the <code>Identity</code> value, which also becomes the return value if <code>foos</code> is empty. Then you simply loop over each value in <code>foos</code> and use <code>Op</code> with the value accumulated so far (<code>acc</code>) and the current element in the sequence. </p> <p> Once you're done looping, you return the accumulator. </p> <p> This implementation isn't always guaranteed to be the most efficient, but you can <em>always</em> write accumulation like that. Sometimes, a more efficient algorithm exists, but that doesn't change the overall result that you can always reduce an arbitrary number of values whenever a monoid exists for those values. </p> <p> <strong>Generalisation</strong> </p> <p> You can do this with any monoid. In <a href="https://www.haskell.org">Haskell</a>, this function is called <code>mconcat</code>, and it has this type: </p> <p> <pre>mconcat :: Monoid a =&gt; [a] -&gt; a</pre> </p> <p> The way you can read this is that for any monoid <code>a</code>, <code>mconcat</code> is a function that takes a linked list of <code>a</code> values as input, and returns a single <code>a</code> value as output. </p> <p> This function seems both more general, and more constrained, than the above C# example. It's more general than the C# example because it works on any monoid, instead of just <code>Foo.Op</code>. On the other hand, it seems more limited because it works only on Haskell lists. The C# example, in contrast, can accumulate any <code>IReadOnlyCollection&lt;Foo&gt;</code>. Could you somehow combine those two generalisations? </p> <p> Nothing stops you from doing that, but it's already in Haskell's <code>Data.Foldable</code> module: </p> <p> <pre>fold :: (Monoid m, Foldable t) =&gt; t m -&gt; m</pre> </p> <p> The way to read this is that there's a function called <code>fold</code>, and it accumulates any monoid <code>m</code> contained in any 'foldable' data container <code>t</code>. That a data container is 'foldable' means that there's a way to somehow fold, or aggregate, the element(s) in the container into a value. </p> <p> Linked lists, arrays, and other types of sequences are foldable, as are Maybe and trees. </p> <p> In fact, there's little difference between Haskell's <code>Foldable</code> type class and .NET's <code>IEnumerable&lt;T&gt;</code>, but as the names suggest, their foci are different. In Haskell, the focus is being able to fold, accumulate, or aggregate a data structure, whereas on .NET the focus is on being able to enumerate the values inside the data structure. Ultimately, though, both abstractions afford the same capabilities. </p> <p> In .NET, the focal abstraction is the <a href="https://en.wikipedia.org/wiki/Iterator_pattern">Iterator pattern</a>, which enables you to enumerate the values in the data container. On top of that abstraction, you can derive other behaviour, such as the ability to <a href="https://msdn.microsoft.com/en-us/library/system.linq.enumerable.aggregate">Aggregate</a> data. </p> <p> In Haskell, the focus is on the ability to fold, but from that central abstraction follows the ability to convert the data container into a linked list, which you can then enumerate. </p> <p> <strong>Summary</strong> </p> <p> You can accumulate an arbitrary number of monoidal values as long as they're held in a container that enables you to 'fold' it. This includes all sorts of lists and arrays. </p> <p> This article concludes the article series about monoids. In the next series of articles, you'll learn about a related category of operations. </p> <p> <strong>Next: </strong> <a href="http://blog.ploeh.dk/2017/11/27/semigroups">Semigroups</a>. </p> </div> <div id="comments"> <hr /> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="https://about.me/carsten.koenig">Carsten König</a></div> <div class="comment-content"> <p> <a href="https://twitter.com/ploeh">@ploeh</a> as always I loved your blog post but I don't 100% agree on your comparison of the iterator pattern with Foldable - the iterator pattern allows usually sideeffects and you have Traversable for that - you might also like this: <a href="http://www.cs.ox.ac.uk/jeremy.gibbons/publications/iterator.pdf">http://www.cs.ox.ac.uk/jeremy.gibbons/publications/iterator.pdf</a> … </p> <p> (Comment <a href="https://twitter.com/CarstenK_Dev/status/932597257584676864">submitted via Twitter</a>) </p> </div> <div class="comment-date">2017-11-20 13:11 UTC</div> </div> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Endomorphism monoid http://blog.ploeh.dk/2017/11/13/endomorphism-monoid 2017-11-13T07:10:00+00:00 Mark Seemann <div id="post"> <p> <em>A method that returns the same type of output as its input forms a monoid. An article for object-oriented programmers.</em> </p> <p> This article is part of a <a href="http://blog.ploeh.dk/2017/10/06/monoids">series about monoids</a>. In short, a <em>monoid</em> is an associative binary operation with a neutral element (also known as <em>identity</em>). Methods that return the same type of value as their input form monoids over composition. The formal term for such an operation is an <a href="https://en.wikipedia.org/wiki/Endomorphism">endomorphism</a>. </p> <p> <strong>Scheduling example</strong> </p> <p> Imagine that you have to develop some functionality for scheduling events in the future. As a concrete example, I recently wrote about adjusting dates while <a href="http://blog.ploeh.dk/2017/04/24/simple-holidays">taking bank holidays into account</a>. For instance, if you want to find the latest bank day <em>before</em> a given date, you could call the <code>AdjustToLatestPrecedingDutchBankDay</code> method. If you give it a normal bank day (say, a Thursday), it'll simply return the input date, but if you give it a Sunday, it'll return the preceding Friday. That is, unless that particular Friday is a bank holiday, in which case it'll return the Thursday before - as long as that's not also a bank holiday, and so on. </p> <p> In that previous article, the <code>AdjustToLatestPrecedingDutchBankDay</code> method is an extension method, but you can also model it as an instance method, like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;Adjust(<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;value) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;candidate&nbsp;=&nbsp;value; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">while</span>&nbsp;(!(IsDutchBankDay(candidate.DateTime))) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;candidate&nbsp;=&nbsp;candidate.AddDays(-1); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;candidate; }</pre> </p> <p> This method would be part of a class that implements an interface: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;Adjust(<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;value); }</pre> </p> <p> You can make other implementations of this interface. Here's one that adjusts a date and time to business hours: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">BusinessHoursAdjustment</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>&nbsp;startOfBussiness&nbsp;=&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">TimeSpan</span>.FromHours(9); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>&nbsp;endOfBusiness&nbsp;=&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">TimeSpan</span>.FromHours(17); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;Adjust(<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;value) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;Warning:&nbsp;May&nbsp;not&nbsp;handle&nbsp;DST&nbsp;changes&nbsp;appropriately!</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;It&#39;s&nbsp;only&nbsp;example&nbsp;code...</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(value.TimeOfDay&nbsp;&lt;&nbsp;startOfBussiness) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;value&nbsp;-&nbsp;value.TimeOfDay&nbsp;+&nbsp;startOfBussiness; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(endOfBusiness&nbsp;&lt;&nbsp;value.TimeOfDay) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;(value&nbsp;-&nbsp;value.TimeOfDay&nbsp;+&nbsp;startOfBussiness).AddDays(1); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;value; &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> To keep the example simple, business hours are hard-coded to 9-17. </p> <p> You could also <a href="https://en.wikipedia.org/wiki/Adapter_pattern">adapt</a> conversion to UTC: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">UtcAdjustment</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;Adjust(<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;value) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;value.ToUniversalTime(); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> Or add a month: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">NextMonthAdjustment</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;Adjust(<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;value) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;value.AddMonths(1); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> Notice that the <code>Adjust</code> method returns a value of the same type as its input. So far when discussing monoids, we've been looking at binary operations, but <code>Adjust</code> is a <em>unary</em> operation. </p> <p> An operation that returns the same type as its input is called an <em>endomorphism</em>. Those form monoids. </p> <p> <strong>Composing adjustments</strong> </p> <p> It's easy to connect two adjustments. Perhaps, for example, you'd like to first use <code>BusinessHoursAdjustment</code>, followed by the bank day adjustment. This will adjust an original input date and time to a date and time that falls on a bank day, within business hours. </p> <p> You can do this in a general-purpose, reusable way: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span>&nbsp;Append( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span>&nbsp;x, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span>&nbsp;y) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AppendedAdjustment</span>(x,&nbsp;y); } <span style="color:blue;">private</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">AppendedAdjustment</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span>&nbsp;x; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span>&nbsp;y; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;AppendedAdjustment( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span>&nbsp;x, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span>&nbsp;y) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.x&nbsp;=&nbsp;x; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.y&nbsp;=&nbsp;y; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;Adjust(<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;value) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;y.Adjust(x.Adjust(value)); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> The <code>Append</code> method takes two <code>IDateTimeOffsetAdjustment</code> values and combines them by wrapping them in a private implementation of <code>IDateTimeOffsetAdjustment</code>. When <code>AppendedAdjustment.Adjust</code> is called, it first calls <code>Adjust</code> on <code>x</code>, and then calls <code>Adjust</code> on <code>y</code> with the return value from the first call. </p> <p> In order to keep the example simple, I omitted null guards, but apart from that, <code>Append</code> should work with any two implementations of <code>IDateTimeOffsetAdjustment</code>. In other words, it obeys the <a href="https://en.wikipedia.org/wiki/Liskov_substitution_principle">Liskov Substitution Principle</a>. </p> <p> <strong>Associativity</strong> </p> <p> The <code>Append</code> method is a binary operation. It takes two <code>IDateTimeOffsetAdjustment</code> values and returns an <code>IDateTimeOffsetAdjustment</code>. It's also associative, as a test like this demonstrates: </p> <p> <pre><span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;AppendIsAssociative( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span>&nbsp;x, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span>&nbsp;y, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span>&nbsp;z) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x.Append(y).Append(z), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x.Append(y.Append(z))); }</pre> </p> <p> As usual in this article series, such a test doesn't <em>prove</em> that <code>Append</code> is associative for all values of <code>IDateTimeOffsetAdjustment</code>, but if you run it as a property-based test, it demonstrates that it's quite likely. </p> <p> <strong>Identity</strong> </p> <p> In true monoidal fashion, <code>IDateTimeOffsetAdjustment</code> also has an identity element: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">IdentityDateTimeOffsetAdjustment</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;Adjust(<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;value) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;value; &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> This implementation simply returns the input value without modifying it. That's a neutral operation, as a test like this demonstrates: </p> <p> <pre><span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;AppendHasIdentity(<span style="color:#2b91af;">IDateTimeOffsetAdjustment</span>&nbsp;x) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x.Append(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">IdentityDateTimeOffsetAdjustment</span>()),&nbsp;x); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">IdentityDateTimeOffsetAdjustment</span>().Append(x),&nbsp;x); }</pre> </p> <p> These two assertions verify that left and right identity holds. </p> <p> Since <code>Append</code> is associative and has identity, it's a monoid. </p> <p> This holds generally for any method (or function) that returns the same type as it takes as input, i.e. <code>T SomeOperation(T x)</code>. This matches the built-in library in <a href="https://www.haskell.org">Haskell</a>, where <code>Endo</code> is a <code>Monoid</code>. </p> <p> <strong>Conclusion</strong> </p> <p> A method that returns a value of the same type as its (singular) input argument is called an endomorphism. You can compose two such unary operations together in order to get a composed operation. You simply take the output of the first method and use it as the input argument for the second method. That composition is a monoid. Endomorphisms form monoids. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/11/20/monoids-accumulate">Monoids accumulate</a>. </p> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Function monoids http://blog.ploeh.dk/2017/11/06/function-monoids 2017-11-06T06:11:00+00:00 Mark Seemann <div id="post"> <p> <em>Methods are monoids if they return monoids. An article for object-oriented programmers.</em> </p> <p> This article is part of a <a href="http://blog.ploeh.dk/2017/10/06/monoids">series about monoids</a>. In short, a <em>monoid</em> is an associative binary operation with a neutral element (also known as <em>identity</em>). </p> <p> <strong>Functions</strong> </p> <p> In statically typed C-languages, like C# or Java, methods are typically declared like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Foo</span>&nbsp;Bar(<span style="color:#2b91af;">Baz</span>&nbsp;baz,&nbsp;<span style="color:#2b91af;">Qux</span>&nbsp;qux)</pre> </p> <p> As you'll see in a future article, however, you can refactor any method to a method that takes a single argument as input, and returns a single (possibly complex) value as output. In abstract form, we can write it like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Out1</span>&nbsp;Op1(<span style="color:#2b91af;">In1</span>&nbsp;arg) </pre> </p> <p> Another way to abstract a method is by using generics: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">T</span>&nbsp;Op1&lt;<span style="color:#2b91af;">T1</span>,&nbsp;<span style="color:#2b91af;">T</span>&gt;(<span style="color:#2b91af;">T1</span>&nbsp;x) </pre> </p> <p> Another future article will demonstrate how this is similar to a generic function. In <a href="http://fsharp.org">F#</a>, for instance, the type of the function would be written as <code>'a -&gt; 'b</code>, whereas in <a href="https://www.haskell.org">Haskell</a> it'd be written <code>a -&gt; b</code>. The way to read this is that the function takes a value of the generic type <code>T1</code>/<code>'a</code>/<code>a</code> as input, and returns a value of the generic type <code>T</code>/<code>'b</code>/<code>b</code> as output. For the rest of this article, I'll favour the Haskell syntax, since it has minimal noise. </p> <p> To be clear, however, although I favour the Haskell syntax because of its succinctness, I don't mean to imply that the functions that I discuss are exclusively <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a> - think of an F# function <code>'a -&gt; 'b</code> which may or may not be pure. </p> <p> <strong>Binary combination of functions</strong> </p> <p> A function <code>a -&gt; b</code> is a monoid if <code>b</code> is a monoid. This means that you can combine two functions with the same type. In an object-oriented context, it means that you can combine two methods with the same signature into one method as long as the return type forms a monoid. </p> <p> Consider the following (facetious) C# example. You're trying to establish how secure a <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">GUID</a> is. Primes are important in cryptography, so the more primes a GUID contains, the better... right? </p> <p> <pre><span style="color:blue;">private</span>&nbsp;<span style="color:blue;">const</span>&nbsp;<span style="color:blue;">string</span>&nbsp;primes&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2357bd&quot;</span>; <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">int</span>&nbsp;CountPrimes(<span style="color:#2b91af;">Guid</span>&nbsp;g) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;g.ToString(<span style="color:#a31515;">&quot;N&quot;</span>).Count(primes.Contains); }</pre> </p> <p> The <code>CountPrimes</code> method counts the number of prime digits in a given GUID. So far so good, but you also think that hexadecimal notation is more exotic than decimal notation, so surely, the digits A-F are somehow more secure, being more unfamiliar. Thus, you have a method to count those as well: </p> <p> <pre><span style="color:blue;">private</span>&nbsp;<span style="color:blue;">const</span>&nbsp;<span style="color:blue;">string</span>&nbsp;letters&nbsp;=&nbsp;<span style="color:#a31515;">&quot;abcdef&quot;</span>; <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">int</span>&nbsp;CountLetters(<span style="color:#2b91af;">Guid</span>&nbsp;g) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;g.ToString(<span style="color:#a31515;">&quot;N&quot;</span>).Count(letters.Contains); }</pre> </p> <p> Good, but both of these numbers are, clearly, excellent indicators of how secure a GUID is. Which one should you choose? Both of them, of course! </p> <p> Can you combine <code>CountPrimes</code> and <code>CountLetters</code>? Yes, you can, because, while GUIDs don't form a monoid, the return type <code>int</code> forms a monoid over addition. This enables you to write a <code>Combine</code> method: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">Guid</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;Combine( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">Guid</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;f, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">Guid</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;g) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;x&nbsp;=&gt;&nbsp;f(x)&nbsp;+&nbsp;g(x); }</pre> </p> <p> Notice that <code>Combine</code> takes two <code>Func&lt;Guid, int&gt;</code> values and return a new <code>Func&lt;Guid, int&gt;</code> value. It's a binary operation. Here's an example of how to use it: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;calculateSecurity&nbsp;=&nbsp;Combine(CountPrimes,&nbsp;CountLetters); <span style="color:blue;">var</span>&nbsp;actual&nbsp;=&nbsp;calculateSecurity(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Guid</span>(<span style="color:#a31515;">&quot;10763FF5-E3C8-46D1-A70F-6C1D9EDA8120&quot;</span>)); <span style="color:#2b91af;">Assert</span>.Equal(21,&nbsp;actual);</pre> </p> <p> Now you have an excellent measure of the security strength of GUIDs! 21 isn't <em>that</em> good, though, is it? </p> <p> Antics aside, <code>Combine</code> is a binary function. Is it a monoid? </p> <p> <strong>Monoid laws</strong> </p> <p> In order to be a monoid, <code>Combine</code> must be associative, and it is, as the following <a href="https://fscheck.github.io/FsCheck">FsCheck</a> property demonstrates: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;CombineIsAssociative( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">Guid</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;f, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">Guid</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;g, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">Guid</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;h, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Guid</span>&nbsp;guid) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Combine(Combine(f,&nbsp;g),&nbsp;h)(guid), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Combine(f,&nbsp;Combine(g,&nbsp;h))(guid)); }</pre> </p> <p> In this property-based test, FsCheck generates three functions with the same signature. Since functions don't have structural equality, the easiest way to compare them is to call them and see whether they return the same result. This explains why the assertion invokes both associative combinations with <code>guid</code>. The test passes. </p> <p> In order to be a monoid, <code>Combine</code> must also have an identity element. It does: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">Guid</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;FuncIdentity&nbsp;=&nbsp;_&nbsp;=&gt;&nbsp;0; </pre> </p> <p> This is simply a function that ignores its input and always returns <code>0</code>, which is the identity value for addition. The following test demonstrates that it behaves as expected: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;CombineHasIdentity(<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">Guid</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;f,&nbsp;<span style="color:#2b91af;">Guid</span>&nbsp;guid) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(f(guid),&nbsp;Combine(FuncIdentity,&nbsp;f)(guid)); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(f(guid),&nbsp;Combine(f,&nbsp;FuncIdentity)(guid)); }</pre> </p> <p> As was the case with <code>CombineIsAssociative</code>, in order to assert that the combined functions behave correctly, you have to call them. This, again, explains why the assertion invokes the combined functions with <code>guid</code>. This test passes as well. </p> <p> <code>Combine</code> is a monoid. </p> <p> <strong>Generalisation</strong> </p> <p> While the above C# code is only an example, the general rule is that any function that returns a monoid is itself a monoid. In Haskell, this rule is articulated in the standard library: </p> <p> <pre>instance Monoid b =&gt; Monoid (a -&gt; b)</pre> </p> <p> This means that for any monoid <code>b</code>, a function <code>a -&gt; b</code> is also (automatically) a monoid. </p> <p> <strong>Summary</strong> </p> <p> A function or method with a return type that forms a monoid is itself a monoid. </p> <p> <strong>Next: </strong> <a href="http://blog.ploeh.dk/2017/11/13/endomorphism-monoid">Endomorphism monoid</a>. </p> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Tuple monoids http://blog.ploeh.dk/2017/10/30/tuple-monoids 2017-10-30T07:01:00+00:00 Mark Seemann <div id="post"> <p> <em>Tuples of monoids form monoids. Data objects of monoids also form monoids. An article for object-oriented programmers.</em> </p> <p> This article is part of a <a href="http://blog.ploeh.dk/2017/10/06/monoids">series about monoids</a>. In short, a <em>monoid</em> is an associative binary operation with a neutral element (also known as <em>identity</em>). This article starts off with some easy-to-understand, but abstract results. Once these are established, however, you'll see how to use them in a relatable example, so keep reading! </p> <p> <strong>Tuples</strong> </p> <p> A tuple is a group of elements. In statically typed programming languages, each element has a type, and the types don't have to be the same. As an example, in C#, you can create a tuple like this: </p> <p> <pre><span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">string</span>&gt;&nbsp;pair&nbsp;=&nbsp;<span style="color:#2b91af;">Tuple</span>.Create(42,&nbsp;<span style="color:#a31515;">&quot;Foo&quot;</span>); </pre> </p> <p> This creates a tuple where the first element must be an <code>int</code> and the second element a <code>string</code>. In the example, I've explicitly declared the type instead of using the <code>var</code> keyword, but this is only to make the type clearer (since you don't have an IDE in which to read the code). </p> <p> The <code>pair</code> tuple is a two-tuple, which means that it must have exactly two elements, of the types given, but you can also create larger tuples: </p> <p> <pre><span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">string</span>,&nbsp;<span style="color:blue;">bool</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;triple&nbsp;=&nbsp;<span style="color:#2b91af;">Tuple</span>.Create(<span style="color:#a31515;">&quot;Bar&quot;</span>,&nbsp;<span style="color:blue;">false</span>,&nbsp;42); </pre> </p> <p> This is a three-tuple, but conceptually, tuples can have any size. </p> <p> <strong>Pairs of monoids</strong> </p> <p> A <em>pair</em> (a two-tuple) forms a monoid if both elements form a monoid. <a href="https://www.haskell.org">Haskell</a> formalises this by stating: </p> <p> <code>instance (Monoid a, Monoid b) =&gt; Monoid (a, b)</code> </p> <p> The way to read this is that for any monoid <code>a</code> and any monoid <code>b</code>, the pair <code>(a, b)</code> is also a monoid. </p> <p> Perhaps this is easiest to understand with a C# example. Consider a tuple of the type <code>Tuple&lt;int, string&gt;</code>. Integers form monoids under both addition and multiplication, and <a href="http://blog.ploeh.dk/2017/10/10/strings-lists-and-sequences-as-a-monoid">strings are monoids under concatenation</a>. Thus, you can make <code>Tuple&lt;int, string&gt;</code> form a monoid as well. For instance, use the multiplication monoid to define this binary operation: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">string</span>&gt;&nbsp;CombinePair( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">string</span>&gt;&nbsp;x, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">string</span>&gt;&nbsp;y) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#2b91af;">Tuple</span>.Create(x.Item1&nbsp;*&nbsp;y.Item1,&nbsp;x.Item2&nbsp;+&nbsp;y.Item2); }</pre> </p> <p> For this particular example, I've chosen multiplication as the binary operation for <code>int</code>, and the string concatenation operator <code>+</code> for <code>string</code>. The point is that since both elements are monoids, you can use their respective binary operations to return a new tuple with the combined values. </p> <p> This operation is associative, as the following <a href="https://fscheck.github.io/FsCheck">FsCheck</a> property demonstrates: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;CombinePairIsAssociative( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">string</span>&gt;&nbsp;x, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">string</span>&gt;&nbsp;y, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">string</span>&gt;&nbsp;z) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;CombinePair(CombinePair(x,&nbsp;y),&nbsp;z), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;CombinePair(x,&nbsp;CombinePair(y,&nbsp;z))); }</pre> </p> <p> This property passes for all the <code>x</code>, <code>y</code>, and <code>z</code> values that FsCheck generates. </p> <p> The <code>CombinePair</code> operation has identity as well: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">string</span>&gt;&nbsp;PairIdentity&nbsp;=&nbsp;<span style="color:#2b91af;">Tuple</span>.Create(1,&nbsp;<span style="color:#a31515;">&quot;&quot;</span>);</pre> </pre> </p> <p> Again, you can use the identity value for each of the elements in the tuple: <code>1</code> for the multiplication monoid, and <code>""</code> for string concatenation. </p> <p> This value behaves as the identity for <code>CombinePair</code>, at least for all non-null string values: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;CombinePairHasIdentity(<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">int</span>,&nbsp;<span style="color:#2b91af;">NonNull</span>&lt;<span style="color:blue;">string</span>&gt;&gt;&nbsp;seed) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;x&nbsp;=&nbsp;<span style="color:#2b91af;">Tuple</span>.Create(seed.Item1,&nbsp;seed.Item2.Get); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(CombinePair(PairIdentity,&nbsp;x),&nbsp;CombinePair(x,&nbsp;PairIdentity)); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(x,&nbsp;CombinePair(x,&nbsp;PairIdentity)); }</pre> </p> <p> Again, this test passes for all <code>seed</code> values generated by FsCheck. </p> <p> The C# code here is only an example, but I hope it's clear how the result generalises. </p> <p> <strong>Triples of monoids</strong> </p> <p> In the above section, you saw how pairs of monoids form a monoid. Not surprisingly, triples of monoids also form monoids. Here's another C# example: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">string</span>,&nbsp;<span style="color:blue;">bool</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;CombineTriple( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">string</span>,&nbsp;<span style="color:blue;">bool</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;x, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">string</span>,&nbsp;<span style="color:blue;">bool</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;y) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#2b91af;">Tuple</span>.Create( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x.Item1&nbsp;+&nbsp;y.Item1, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x.Item2&nbsp;||&nbsp;y.Item2, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x.Item3&nbsp;*&nbsp;y.Item3); }</pre> </p> <p> The <code>CombineTriple</code> method is another binary operation. This time it combines two triples to a single triple. Since both <code>string</code>, <code>bool</code>, and <code>int</code> form monoids, it's possible to combine each element in the two tuples to create a new tuple. There's more than one monoid for integers, and the same goes for Boolean values, but here I've chosen multiplication and Boolean <em>or</em>, so the identity is this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">string</span>,&nbsp;<span style="color:blue;">bool</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;TripleIdentity&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Tuple</span>.Create(<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;<span style="color:blue;">false</span>,&nbsp;1);</pre> </p> <p> This triple simply contains the identities for string concatenation, Boolean <em>or</em>, and multiplication. The operation is associative, but I'm not going to show this with a property-based test. Both tests for associativity and identity are similar to the above tests; you could consider writing them as an exercise, if you'd like. </p> <p> This triple example only demonstrates a particular triple, but you can find the generalisation in Haskell: </p> <p> <pre>instance (Monoid a, Monoid b, Monoid c) =&gt; Monoid (a, b, c)</pre> </p> <p> This simply states that for monoids <code>a</code>, <code>b</code>, and <code>c</code>, the tuple <code>(a, b, c)</code> is also a monoid. </p> <p> <strong>Generalisation</strong> </p> <p> At this point, it can hardly come as a surprise that quadruples and pentuples of monoids are also monoids. From Haskell: </p> <p> <pre>instance (Monoid a, Monoid b, Monoid c, Monoid d) =&gt; Monoid (a, b, c, d) instance (Monoid a, Monoid b, Monoid c, Monoid d, Monoid e) =&gt; Monoid (a, b, c, d, e)</pre> </p> <p> The Haskell standard library stops at pentuples (five-tuples), because it has to stop somewhere, but I'm sure you can see how this is a general rule. </p> <p> <strong>Data objects as monoids</strong> </p> <p> If you're an object-oriented programmer, you probably don't use tuples much in your day-to-day work. I'd even suggest that you shouldn't, because tuples carry too little information to make good domain objects. For example, if you have <code>Tuple&lt;int, string, string&gt;</code>, what do the elements mean? A better design would be to introduce a small <a href="https://martinfowler.com/bliki/ValueObject.html">Value Object</a> called <code>Customer</code>, with <code>Id</code>, <code>FirstName</code>, and <code>LastName</code> properties. </p> <p> (In functional programming, you frequently use tuples, because they're useful for 'gluing' generic functions together. A Haskell programmer may instead say that they are useful for composing parametrically polymorphic functions, but the meaning would be the same.) </p> <p> As on object-oriented developer, then why should you care that tuples of monoids are monoids? </p> <p> The reason this is interesting in object-oriented programming is that there's a strong relationship between tuples and data objects (Value Objects or <a href="https://en.wikipedia.org/wiki/Data_transfer_object">Data Transfer Objects</a>). Consider the <code>Customer</code> examples that I sketched out a few paragraphs above. As you'll learn in a future article, you can refactor a tuple to a class, or a class to a tuple. </p> <p> <strong>Example: Roster</strong> </p> <p> In Denmark, where I live, learning to swim is a mandatory part of the school curriculum. Teachers take the children to the nearby swimming stadium and teach them to swim. Since this is an activity outside of school, teachers would be prudent to keep a roster of the children. Modelled as a class, it might look like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Roster</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;Girls&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;Boys&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:blue;">string</span>&gt;&nbsp;Exemptions&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;Roster(<span style="color:blue;">int</span>&nbsp;girls,&nbsp;<span style="color:blue;">int</span>&nbsp;boys,&nbsp;<span style="color:blue;">params</span>&nbsp;<span style="color:blue;">string</span>[]&nbsp;exemptions) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Girls&nbsp;=&nbsp;girls; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Boys&nbsp;=&nbsp;boys; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Exemptions&nbsp;=&nbsp;exemptions; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;...</span> }</pre> </p> <p> Some children may be temporarily exempt from a swimming lesson, perhaps because of a passing medical condition. This changes from lesson to lesson, so the roster keeps track of them separately. Additionally, the boys will need to go in the men's changing rooms, and the girls in the women's changing rooms. This is the reason the roster keeps track of the number of boys and girls separately. </p> <p> This, however, presents a logistical problem, because there's only one teacher for a class. The children are small, so need the company of an adult. </p> <p> The way my children's school solved that problem was to combine two groups of children (in Danish, <em>en klasse</em>, a <a href="https://en.wikipedia.org/wiki/Class_(education)">class</a>), each with their own teacher - one female, and one male. </p> <p> To model that, the <code>Roster</code> class should have a <code>Combine</code> method: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Roster</span>&nbsp;Combine(<span style="color:#2b91af;">Roster</span>&nbsp;other) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Roster</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Girls&nbsp;+&nbsp;other.Girls, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Boys&nbsp;+&nbsp;other.Boys, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Exemptions.Concat(other.Exemptions).ToArray()); }</pre> </p> <p> Clearly, this is easy to implement. Just add the number of girls together, add the number of boys together, and concatenate the two lists of exemptions. </p> <p> Here's an example of using the method: </p> <p> <pre>[<span style="color:#2b91af;">Fact</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;UsageExample() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;x&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Roster</span>(11,&nbsp;10,&nbsp;<span style="color:#a31515;">&quot;Susan&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;George&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;y&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Roster</span>(12,&nbsp;9,&nbsp;<span style="color:#a31515;">&quot;Edward&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;roster&nbsp;=&nbsp;x.Combine(y); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;expected&nbsp;=&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Roster</span>(23,&nbsp;19,&nbsp;<span style="color:#a31515;">&quot;Susan&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;George&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;Edward&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(expected,&nbsp;roster); }</pre> </p> <p> The <code>Combine</code> method is an instance method on the <code>Roster</code> class, taking a second <code>Roster</code> as input, and returning a new <code>Roster</code> value. <a href="http://blog.ploeh.dk/2017/10/06/monoids">It's a binary operation</a>. Does it also have identity? </p> <p> Yes, it does: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Roster</span>&nbsp;Identity&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Roster</span>(0,&nbsp;0);</pre> </p> <p> Notice that the <code>exemptions</code> constructor argument is a <code>params</code> array, so omitting it means passing an empty array as the third argument. </p> <p> The following properties demonstrate that the <code>Combine</code> operation is both associative and has identity: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;CombineIsAssociative(<span style="color:#2b91af;">Roster</span>&nbsp;x,&nbsp;<span style="color:#2b91af;">Roster</span>&nbsp;y,&nbsp;<span style="color:#2b91af;">Roster</span>&nbsp;z) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x.Combine(y).Combine(z), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x.Combine(y.Combine(z))); } [<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;CombineHasIdentity(<span style="color:#2b91af;">Roster</span>&nbsp;x) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(x,&nbsp;<span style="color:#2b91af;">Roster</span>.Identity.Combine(x)); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(x,&nbsp;x.Combine(<span style="color:#2b91af;">Roster</span>.Identity)); }</pre> </p> <p> In other words, <code>Combine</code> is a monoid. </p> <p> This shouldn't surprise us in the least, since we've already established that tuples of monoids are monoids, and that a data class is more or less 'just' a tuple with named elements. Specifically, the <code>Roster</code> class is a 'tuple' of two addition monoids and the sequence concatenation monoid, so it follows that the <code>Combine</code> method is a monoid as well. </p> <p> <strong>Roster isomorphism</strong> </p> <p> In a future article, you'll learn more about isomorphisms between various representations of objects, but in this context, I think it's relevant to show how the <code>Roster</code> example is isomorphic to a tuple. It's trivial, really: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">string</span>[]&gt;&nbsp;ToTriple() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#2b91af;">Tuple</span>.Create(<span style="color:blue;">this</span>.Girls,&nbsp;<span style="color:blue;">this</span>.Boys,&nbsp;<span style="color:blue;">this</span>.Exemptions.ToArray()); } <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Roster</span>&nbsp;FromTriple(<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">string</span>[]&gt;&nbsp;triple) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Roster</span>(triple.Item1,&nbsp;triple.Item2,&nbsp;triple.Item3); }</pre> </p> <p> This pair of methods turn a <code>Roster</code> into a triple, and a corresponding triple back into a <code>Roster</code> value. As the following two FsCheck properties demonstrate, these methods form an isomorphism: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;ToTripleRoundTrips(<span style="color:#2b91af;">Roster</span>&nbsp;x) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;triple&nbsp;=&nbsp;x.ToTriple(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(x,&nbsp;<span style="color:#2b91af;">Roster</span>.FromTriple(triple)); } [<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;FromTripleRoundTrips(<span style="color:#2b91af;">Tuple</span>&lt;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">string</span>[]&gt;&nbsp;triple) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;roster&nbsp;=&nbsp;<span style="color:#2b91af;">Roster</span>.FromTriple(triple); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(triple,&nbsp;roster.ToTriple()); }</pre> </p> <p> This isn't the only possible isomorphism between triples and <code>Roster</code> objects. You could create another one where the <code>string[]</code> element goes first, instead of last; where boys go before girls; and so on. </p> <p> <strong>Summary</strong> </p> <p> Tuples of monoids are also monoids. This holds for tuples of any size, but all of the elements has to be monoids. By isomorphism, this result also applies to data objects. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/11/06/function-monoids">Function monoids</a>. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Convex hull monoid http://blog.ploeh.dk/2017/10/23/convex-hull-monoid 2017-10-23T12:32:00+00:00 Mark Seemann <div id="post"> <p> <em>The union of convex hulls form a monoid. Yet another non-trivial monoid example, this time in F#.</em> </p> <p> This article is part of a <a href="http://blog.ploeh.dk/2017/10/06/monoids">series about monoids</a>. In short, a <em>monoid</em> is an associative binary operation with a neutral element (also known as <em>identity</em>). </p> <p> If you're reading the series as an object-oriented programmer, I apologise for the digression, but this article exclusively contains F# code. The next article will return with more C# examples. </p> <p> <strong>Convex hull</strong> </p> <p> In <a href="http://blog.ploeh.dk/2015/10/19/visual-value-verification">a past article</a> I've described my adventures with finding <a href="https://en.wikipedia.org/wiki/Convex_hull">convex hulls</a> in F#. The convex hulls I've been looking at form the external convex boundary of a set of two-dimensional points. While you can generalise the concept of convex hulls to <em>n</em> dimensions, we're going to stick to two-dimensional hulls here. </p> <p> <img src="/content/binary/convex-hull-example-01.png" alt="A 2D convex hull example."> </p> <p> If you have two convex hulls, you can find the convex hull of both: </p> <p> <img src="/content/binary/convex-hull-union.png" alt="A union of two convex hulls."> </p> <p> Here, the dark green outline is the convex hull of the two lighter-coloured hulls. </p> <p> Finding the convex hull of two other hulls is a binary operation. Is it a monoid? </p> <p> In order to examine that, I'm going to make some changes to my <a href="https://github.com/ploeh/Hull">existing code base</a>, the most important of which is that I'm going to introduce a <code>Hull</code> type. The intent is that if points are contained within this type, then only the convex hull remains. It'd be better if it was possible to make the case constructor private, but if one does that, then the <code>hull</code> function can no longer be inlined and generic. </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">Hull</span>&lt;&#39;a&gt;&nbsp;=&nbsp;<span style="color:navy;">Hull</span>&nbsp;<span style="color:blue;">of</span>&nbsp;(&#39;a&nbsp;*&nbsp;&#39;a)&nbsp;<span style="color:teal;">list</span> </pre> </p> <p> With the addition of the <code>Hull</code> type, you can now add a binary operation: </p> <p> <pre><span style="color:green;">//&nbsp;Hull&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;Hull&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;Hull&lt;&#39;a&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">inline</span>&nbsp;(+)&nbsp;(<span style="color:navy;">Hull</span>&nbsp;x)&nbsp;(<span style="color:navy;">Hull</span>&nbsp;y)&nbsp;=&nbsp;<span style="color:navy;">hull</span>&nbsp;(x&nbsp;@&nbsp;y)</pre> </p> <p> This operation explicitly uses the <code>+</code> operator, so I'm clearly anticipating the turn of events here. Nothing much is going on, though. The function pattern-matches the points out of two <code>Hull</code> values. <code>x</code> and <code>y</code> are two lists of points. The <code>+</code> function concatenates the two lists with the <code>@</code> operator, and finds the convex hull of this new list of points. </p> <p> <strong>Associativity</strong> </p> <p> My choice of operator strongly suggests that the <code>+</code> operation is a monoid. If you have three hulls, the order in which you find the hulls doesn't matter. One way to demonstrate that property is with property-based testing. In this article, I'm using <a href="https://github.com/hedgehogqa/fsharp-hedgehog">Hedgehog</a>. </p> <p> <pre>[&lt;<span style="color:teal;">Fact</span>&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``Hull&nbsp;addition&nbsp;is&nbsp;associative``</span>&nbsp;()&nbsp;=&nbsp;<span style="color:teal;">Property</span>.<span style="color:navy;">check</span>&nbsp;&lt;|&nbsp;<span style="color:blue;">property</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;(x,&nbsp;y,&nbsp;z)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Range</span>.<span style="color:navy;">linear</span>&nbsp;-10000&nbsp;10000 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">int</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">tuple</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">list</span>&nbsp;(<span style="color:teal;">Range</span>.<span style="color:navy;">linear</span>&nbsp;0&nbsp;100) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">tuple3</span> &nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:navy;">hull</span>&nbsp;x&nbsp;+&nbsp;<span style="color:navy;">hull</span>&nbsp;y)&nbsp;+&nbsp;<span style="color:navy;">hull</span>&nbsp;z&nbsp;=!&nbsp;<span style="color:navy;">hull</span>&nbsp;x&nbsp;+&nbsp;(<span style="color:navy;">hull</span>&nbsp;y&nbsp;+&nbsp;<span style="color:navy;">hull</span>&nbsp;z)&nbsp;}</pre> </p> <p> This automated test generates three lists of points, <code>x</code>, <code>y</code>, and <code>z</code>. The <code>hull</code> function uses the <a href="https://en.wikipedia.org/wiki/Graham_scan">Graham Scan</a> algorithm to find the hull, and part of that algorithm includes calculating the cross product of three points. For large enough integers, the cross product will overflow, so the property constrains the point coordinates to stay within -10,000 and 10,000. The implication of that is that although <code>+</code> is associative, it's only associative for a subset of all 32-bit integers. I could probably change the internal implementation so that it calculates the cross product using <a href="https://msdn.microsoft.com/en-us/library/system.numerics.biginteger">bigint</a>, but I'll leave that as an exercise to you. </p> <p> For performance reasons, I also arbitrarily decided to constrain the size of each set of points to between 0 and 100 elements. If I change the maximum count to 1,000, it takes my laptop 9 seconds to run the test. </p> <p> In addition to Hedgehog, this test also uses <a href="https://xunit.github.io">xUnit.net</a>, and <a href="http://www.swensensoftware.com/unquote">Unquote</a> for assertions. The <code>=!</code> operator is the Unquote way of saying <em>must equal</em>. It's an assertion. </p> <p> This property passes, which demonstrates that the <code>+</code> operator for convex hulls is associative. </p> <p> <strong>Identity</strong> </p> <p> Likewise, you can write a property-based test that demonstrates that an identity element exists for the <code>+</code> operator: </p> <p> <pre>[&lt;<span style="color:teal;">Fact</span>&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``&nbsp;Hull&nbsp;addition&nbsp;has&nbsp;identity``</span>&nbsp;()&nbsp;=&nbsp;<span style="color:teal;">Property</span>.<span style="color:navy;">check</span>&nbsp;&lt;|&nbsp;<span style="color:blue;">property</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;x&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Range</span>.<span style="color:navy;">linear</span>&nbsp;-10000&nbsp;10000 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">int</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">tuple</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">list</span>&nbsp;(<span style="color:teal;">Range</span>.<span style="color:navy;">linear</span>&nbsp;0&nbsp;100) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;hasIdentity&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Hull</span>.identity&nbsp;+&nbsp;<span style="color:navy;">hull</span>&nbsp;x&nbsp;=&nbsp;<span style="color:navy;">hull</span>&nbsp;x&nbsp;+&nbsp;<span style="color:teal;">Hull</span>.identity&nbsp;&amp;&amp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">hull</span>&nbsp;x&nbsp;+&nbsp;<span style="color:teal;">Hull</span>.identity&nbsp;=&nbsp;<span style="color:navy;">hull</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="background:yellow;">hasIdentity</span><span style="background:yellow;">&nbsp;@&gt;</span>&nbsp;}</pre> </p> <p> This test generates a list of integer pairs (<code>x</code>) and applies the <code>+</code> operator to <code>x</code> and <code>Hull.identity</code>. The test passes for all <code>x</code> that Hedgehog generates. </p> <p> What's <code>Hull.identity</code>? </p> <p> It's simply the empty hull: </p> <p> <pre><span style="color:blue;">module</span>&nbsp;<span style="color:teal;">Hull</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;identity&nbsp;=&nbsp;<span style="color:navy;">Hull</span>&nbsp;[]</pre> </p> <p> If you have a set of zero 2D points, then the convex hull is empty as well. </p> <p> The <code>+</code> operator for convex hulls is a monoid for the set of coordinates where the cross product doesn't overflow. </p> <p> <strong>Summary</strong> </p> <p> If you consider that the <code>Hull</code> type is nothing but a container for a list, it should come as no surprise that a monoid exists. After all, <a href="http://blog.ploeh.dk/2017/10/10/strings-lists-and-sequences-as-a-monoid">list concatenation is a monoid</a>, and the <code>+</code> operator shown here is a combination of list concatenation (<code>@</code>) and a Graham Scan. </p> <p> The point of this article was mostly to demonstrate that monoids exist not only for primitive types, but also for (some) more complex types. The <code>+</code> operator shown here is really a <a href="https://en.wikipedia.org/wiki/Union_(set_theory)">set union</a> operation. What about <a href="https://en.wikipedia.org/wiki/Intersection_(set_theory)">intersections</a> of convex hulls? Is that a monoid as well? I'll leave that as an exercise. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/10/30/tuple-monoids">Tuple monoids</a>. </p> </div> <div id="comments"> <hr /> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"> <a href="https://mikhail.io/about/">Mikhail Shilkov</a> </div> <div class="comment-content"> <p>Is that true that you could replace hull with any other function, and (+) operator would still be a monoid? Since the operator is based on list concatenation, the "monoidness" is probably derived from there, not from function implementation.</p> </div> <div class="comment-date">2017-10-23 15:35 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Mikhail, thank you for writing. You can't replace <code>hull</code> with any other function and expect list concatenation to remain a monoid. I'm sorry if my turn of phrase gave that impression. I can see how one could interpret my summary in that way, but it wasn't my intention to imply that this relationship holds in general. It doesn't, and it's not hard to show, because we only need to come up with a single counter-example. </p> <p> One counter example is a function that always removes the first element in a list - unless the list is empty, in which case it simply returns the empty list. In Haskell, we can define a <code>newtype</code> with this behaviour in mind: </p> <p> <pre>Prelude Data.Monoid Data.List&gt; newtype Drop1 a = Drop1 [a] deriving (Show, Eq)</pre> </p> <p> For my own convenience, I wrote the entire counter-example in GHCi (the Haskell REPL), but imagine that the <code>Drop1</code> data constructor is hidden from clients. The normal way to do that is to not export the data constructor from the module. In GHCi, we can't do that, but just pretend that the <code>Drop1</code> data constructor is unavailable to clients. Instead, we'll have to use this function: </p> <p> <pre>Prelude Data.Monoid Data.List&gt; drop1 = Drop1 . drop 1</pre> </p> <p> The <code>drop1</code> function has the type <code>[a] -&gt; Drop1 a</code>; it takes a list, and returns a <code>Drop1</code> value, which contains the input list, apart from its first element. </p> <p> We can attempt to make <code>Drop 1</code> a monoid: </p> <p> <pre>Prelude Data.Monoid Data.List&gt; :{ Prelude Data.Monoid Data.List| instance Monoid (Drop1 a) where Prelude Data.Monoid Data.List| mempty = drop1 [] Prelude Data.Monoid Data.List| mappend (Drop1 xs) (Drop1 ys) = drop1 (xs ++ ys) Prelude Data.Monoid Data.List| :}</pre> </p> <p> Hopefully, you can see that the implementation of <code>mappend</code> is similar to the above F# implementation of <code>+</code> for convex hulls. In F#, the list concatenation operator is <code>@</code>, whereas in Haskell, it's <code>++</code>. </p> <p> This compiles, but it's easy to come up with some counter-examples that demonstrate that the monoid laws don't hold. First, associativity: </p> <p> <pre>Prelude Data.Monoid Data.List&gt; (drop1 [1..3] &lt;&gt; drop1 [4..6]) &lt;&gt; drop1 [7..9] Drop1 [5,6,8,9] Prelude Data.Monoid Data.List&gt; drop1 [1..3] &lt;&gt; (drop1 [4..6] &lt;&gt; drop1 [7..9]) Drop1 [3,6,8,9]</pre> </p> <p> (The <code>&lt;&gt;</code> operator is an infix alias for <code>mappend</code>.) </p> <p> Clearly, <code>[5,6,8,9]</code> is different from <code>[3,6,8,9]</code>, so the operation isn't associative. </p> <p> Equivalently, identity fails as well: </p> <p> <pre>Prelude Data.Monoid Data.List&gt; mempty &lt;&gt; drop1 [1..3] Drop1 [3] Prelude Data.Monoid Data.List&gt; drop1 [1..3] Drop1 [2,3]</pre> </p> <p> Again, <code>[3]</code> is different from <code>[2,3]</code>, so <code>mempty</code> isn't a proper identity element. </p> <p> It was easy to come up with this counter-example. I haven't attempted to come up with more, but I'd be surprised if I accidentally happened to pick the only counter-example there is. Rather, I conjecture that there are infinitely many counter-examples that each proves that there's no general rule about 'wrapped' lists operations being monoids. </p> </div> <div class="comment-date">2017-10-25 8:04 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Money monoid http://blog.ploeh.dk/2017/10/16/money-monoid 2017-10-16T07:28:00+00:00 Mark Seemann <div id="post"> <p> <em>Kent Beck's money TDD example has some interesting properties.</em> </p> <p> This article is part of a <a href="http://blog.ploeh.dk/2017/10/06/monoids">series about monoids</a>. In short, a <em>monoid</em> is an associative binary operation with a neutral element (also known as <em>identity</em>). </p> <p> In the first half of <a href="http://bit.ly/tddbe">Test-Driven Development By Example</a> Kent Beck explores how to develop a simple and flexible Money API using test-driven development. Towards the end, he arrives at a design that warrants further investigation. </p> <p> <strong>Kent Beck's API</strong> </p> <p> The following treatment of Kent Beck's code is based on <a href="http://yawar.blogspot.com">Yawar Amin</a>'s <a href="https://github.com/yawaramin/TDDMoney">C# reproduction</a> of Kent Beck's original Java code, further <a href="https://github.com/ploeh/TDDMoney">forked and manipulated</a> by me. </p> <p> The goal of Kent Beck's exercise is to develop an object-oriented API able to handle money of multiple currencies, and for example be able to express operations such as <em>5 USD + 10 CHF</em>. Towards the end of the example, he arrives at an interface that, translated to C#, looks like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IExpression</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Money</span>&nbsp;Reduce(<span style="color:#2b91af;">Bank</span>&nbsp;bank,&nbsp;<span style="color:blue;">string</span>&nbsp;to); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IExpression</span>&nbsp;Plus(<span style="color:#2b91af;">IExpression</span>&nbsp;addend); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IExpression</span>&nbsp;Times(<span style="color:blue;">int</span>&nbsp;multiplier); }</pre> </p> <p> The <code>Reduce</code> method reduces an <code>IExpression</code> object to a single currency (<code>to</code>), represented as a <code>Money</code> object. This is useful if you have an <code>IExpression</code> object that contains several currencies. </p> <p> The <code>Plus</code> method adds another <code>IExpression</code> object to the current object, and returns a new <code>IExpression</code>. This could be money in a single currency, but could also represent money held in more than one currency. </p> <p> The <code>Times</code> method multiplies an <code>IExpression</code> with a multiplier. You'll notice that, throughout this example code base, both multiplier and amounts are modelled as integers. I think that Kent Beck did this as a simplification, but a more realistic example should use <code>decimal</code> values. </p> <p> The metaphor is that you can model money as one or more <em>expressions</em>. A simple expression would be <em>5 USD</em>, but you could also have <em>5 USD + 10 CHF</em> or <em>5 USD + 10 CHF + 10 USD</em>. While you can reduce some expressions, such as <em>5 CHF + 7 CHF</em>, you can't reduce an expression like <em>5 USD + 10 CHF</em> unless you have an exchange rate. Instead of attempting to reduce monetary values, this particular design builds an expression tree until you decide to evaluate it. (<a href="http://blog.ploeh.dk/2017/10/10/strings-lists-and-sequences-as-a-monoid">Sounds familiar?</a>) </p> <p> Kent Beck implements <code>IExpression</code> twice: <ul> <li><code>Money</code> models an amount in a single currency. It contains an <code>Amount</code> and a <code>Currency</code> read-only property. It's the quintessential <a href="https://en.wikipedia.org/wiki/Value_object">Value Object</a>.</li> <li><code>Sum</code> models the sum of two other <code>IExpression</code> objects. It contains two other <code>IExpression</code> objects, called <code>Augend</code> and <code>Addend</code>.</li> </ul> If you want to express <em>5 USD + 10 CHF</em>, you can write: </p> <p> <pre><span style="color:#2b91af;">IExpression</span>&nbsp;sum&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Sum</span>(<span style="color:#2b91af;">Money</span>.Dollar(5),&nbsp;<span style="color:#2b91af;">Money</span>.Franc(10)); </pre> </p> <p> where <code>Money.Dollar</code> and <code>Money.Franc</code> are two static factory methods that return <code>Money</code> values. </p> <p> <strong>Associativity</strong> </p> <p> Did you notice that <code>Plus</code> <a href="http://blog.ploeh.dk/2017/10/06/monoids">is a binary operation</a>? Could it be a monoid as well? </p> <p> In order to be a monoid, it must obey the <em>monoid laws</em>, the first of which is that the operation must be associative. This means that for three <code>IExpression</code> objects, <code>x</code>, <code>y</code>, and <code>z</code>, <code>x.Plus(y).Plus(z)</code> must be equal to <code>x.Plus(y.Plus(z))</code>. How should you interpret equality here? The return value from <code>Plus</code> is another <code>IExpression</code> value, and interfaces don't have custom equality behaviour. Either, it's up to the individual implementations (<code>Money</code> and <code>Sum</code>) to override and implement equality, or you can use <a href="http://xunitpatterns.com/test-specific%20equality.html">test-specific equality</a>. </p> <p> The <a href="https://xunit.github.io">xUnit.net</a> assertion library supports test-specific equality via custom comparers (for more details, see my <a href="http://www.shareasale.com/r.cfm?u=1017843&b=611266&m=53701&afftrack=&urllink=www%2Epluralsight%2Ecom%2Fcourses%2Fadvanced%2Dunit%2Dtesting">Advanced Unit Testing</a> Pluralsight course). The original Money API does, however, already include a way to compare expressions! </p> <p> The <code>Reduce</code> method can reduce any <code>IExpression</code> to a single <code>Money</code> object (that is, to a single currency), and since <code>Money</code> is a Value Object, it has structural equality. You can use this to compare the values of <code>IExpression</code> objects. All you need is an exchange rate. </p> <p> In the book, Kent Beck uses a 2:1 exchange rate between CHF and USD. As I'm writing this, the exchange rate is 0.96 Swiss Franc to a Dollar, but since the example code consistently models money as integers, that rounds to a 1:1 exchange rate. This is, however, a degenerate case, so instead, I'm going to stick to the book's original 2:1 exchange rate. </p> <p> You can now add an <a href="https://en.wikipedia.org/wiki/Adapter_pattern">Adapter</a> between <code>Reduce</code> and xUnit.net in the form of an <code>IEqualityComparer&lt;IExpression&gt;</code>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">ExpressionEqualityComparer</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IEqualityComparer</span>&lt;<span style="color:#2b91af;">IExpression</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Bank</span>&nbsp;bank; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;ExpressionEqualityComparer() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bank&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Bank</span>(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bank.AddRate(<span style="color:#a31515;">&quot;CHF&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;USD&quot;</span>,&nbsp;2); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;Equals(<span style="color:#2b91af;">IExpression</span>&nbsp;x,&nbsp;<span style="color:#2b91af;">IExpression</span>&nbsp;y) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;xm&nbsp;=&nbsp;bank.Reduce(x,&nbsp;<span style="color:#a31515;">&quot;USD&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;ym&nbsp;=&nbsp;bank.Reduce(y,&nbsp;<span style="color:#a31515;">&quot;USD&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">object</span>.Equals(xm,&nbsp;ym); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;GetHashCode(<span style="color:#2b91af;">IExpression</span>&nbsp;obj) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;bank.Reduce(obj,&nbsp;<span style="color:#a31515;">&quot;USD&quot;</span>).GetHashCode(); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> You'll notice that this custom equality comparer uses a <code>Bank</code> object with a 2:1 exchange rate. <code>Bank</code> is another object from the <em>Test-Driven Development</em> example. It doesn't implement any interface itself, but it does appear as an argument in the <code>Reduce</code> method. </p> <p> In order to make your test code more readable, you can add a static helper class: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Compare</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">ExpressionEqualityComparer</span>&nbsp;UsingBank&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ExpressionEqualityComparer</span>(); }</pre> </p> <p> This enables you to write an assertion for associativity like this: </p> <p> <pre><span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;x.Plus(y).Plus(z), &nbsp;&nbsp;&nbsp;&nbsp;x.Plus(y.Plus(z)), &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Compare</span>.UsingBank);</pre> </p> <p> In my fork of Yawar Amin's code base, I added this assertion to an <a href="https://fscheck.github.io/FsCheck">FsCheck</a>-based automated test, and it holds for all the <code>Sum</code> and <code>Money</code> objects that FsCheck generates. </p> <p> In its present incarnation, <code>IExpression.Plus</code> is associative, but it's worth noting that this isn't guaranteed to last. An interface like <code>IExpression</code> is an extensibility point, so someone could easily add a third implementation that would violate associativity. We can tentatively conclude that <code>Plus</code> is currently associative, but that the situation is delicate. </p> <p> <strong>Identity</strong> </p> <p> If you accept that <code>IExpression.Plus</code> is associative, it's a monoid candidate. If an identity element exists, then it's a monoid. </p> <p> Kent Beck never adds an identity element in his book, but you can add one yourself: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Plus</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">IExpression</span>&nbsp;Identity&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PlusIdentity</span>(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">PlusIdentity</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IExpression</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IExpression</span>&nbsp;Plus(<span style="color:#2b91af;">IExpression</span>&nbsp;addend) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;addend; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Money</span>&nbsp;Reduce(<span style="color:#2b91af;">Bank</span>&nbsp;bank,&nbsp;<span style="color:blue;">string</span>&nbsp;to) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Money</span>(0,&nbsp;to); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IExpression</span>&nbsp;Times(<span style="color:blue;">int</span>&nbsp;multiplier) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> There's only a single identity element, so it makes sense to make it a <a href="https://en.wikipedia.org/wiki/Singleton_pattern">Singleton</a>. The private <code>PlusIdentity</code> class is a new <code>IExpression</code> implementation that deliberately doesn't do anything. </p> <p> In <code>Plus</code>, it simply returns the input expression. This is the same behaviour as zero has for integer addition. When adding numbers together, zero is the identity element, and the same is the case here. This is more explicitly visible in the <code>Reduce</code> method, where the identity expression simply reduces to zero in the requested currency. Finally, if you multiply the identity element, you still get the identity element. Here, interestingly, <code>PlusIdentity</code> behaves similar to the identity element for multiplication (<em>1</em>). </p> <p> You can now write the following assertions for any <code>IExpression x</code>: </p> <p> <pre><span style="color:#2b91af;">Assert</span>.Equal(x,&nbsp;x.Plus(<span style="color:#2b91af;">Plus</span>.Identity),&nbsp;<span style="color:#2b91af;">Compare</span>.UsingBank); <span style="color:#2b91af;">Assert</span>.Equal(x,&nbsp;<span style="color:#2b91af;">Plus</span>.Identity.Plus(x),&nbsp;<span style="color:#2b91af;">Compare</span>.UsingBank);</pre> </p> <p> Running this as a property-based test, it holds for all <code>x</code> generated by FsCheck. The same caution that applies to associativity also applies here: <code>IExpression</code> is an extensibility point, so you can't be sure that <code>Plus.Identity</code> will be the identity element for all <code>IExpression</code> implementations someone could create, but for the three implementations that now exist, the monoid laws hold. </p> <p> <code>IExpression.Plus</code> is a monoid. </p> <p> <strong>Multiplication</strong> </p> <p> In basic arithmetic, the multiplication operator is called <em>times</em>. When you write <em>3 * 5</em>, it literally means that you have 3 five times (or do you you have 5 three times?). In other words: </p> <p> <pre>3 * 5 = 3 + 3 + 3 + 3 + 3</pre> </p> <p> Does a similar relationship exist for <code>IExpression</code>? </p> <p> Perhaps, we can take a hint from <a href="https://www.haskell.org">Haskell</a>, where monoids and semigroups are explicit parts of the core library. You're going to learn about semigroups later, but for now, it's interesting to observe that the <code>Semigroup</code> typeclass defines a function called <code>stimes</code>, which has the type <code>Integral b =&gt; b -&gt; a -&gt; a</code>. Basically, what this means that for any integer type (16-bit integer, 32-bit integer, etc.) <code>stimes</code> takes an integer and a value <code>a</code> and 'multiplies' the value. Here, <code>a</code> is a type for which a binary operation exists. </p> <p> In C# syntax, <code>stimes</code> would look like this as an instance method on a <code>Foo</code> class: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Foo</span>&nbsp;Times(<span style="color:blue;">int</span>&nbsp;multiplier) </pre> </p> <p> I named the method <code>Times</code> instead of <code>STimes</code>, since I strongly suspect that the <em>s</em> in Haskell's <code>stimes</code> stands for <code>Semigroup</code>. </p> <p> Notice how this is the same type of signature as <code>IExpression.Times</code>. </p> <p> If it's possible to define a universal implementation of such a function in Haskell, could you do the same in C#? In <code>Money</code>, you can implement <code>Times</code> based on <code>Plus</code>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IExpression</span>&nbsp;Times(<span style="color:blue;">int</span>&nbsp;multiplier) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#2b91af;">Enumerable</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Repeat((<span style="color:#2b91af;">IExpression</span>)<span style="color:blue;">this</span>,&nbsp;multiplier) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Aggregate((x,&nbsp;y)&nbsp;=&gt;&nbsp;x.Plus(y)); }</pre> </p> <p> The static <code>Repeat</code> LINQ method returns <code>this</code> as many times as requested by <code>multiplier</code>. The return value is an <code>IEnumerable&lt;IExpression&gt;</code>, but according to the <code>IExpression</code> interface, <code>Times</code> must return a single <code>IExpression</code> value. You can use the <code>Aggregate</code> LINQ method to repeatedly combine two <code>IExpression</code> values (<code>x</code> and <code>y</code>) to one, using the <code>Plus</code> method. </p> <p> This implementation is hardly as efficient as the previous, individual implementation, but the point here isn't about efficiency, but about a common, reusable abstraction. The exact same implementation can be used to implement <code>Sum.Times</code>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IExpression</span>&nbsp;Times(<span style="color:blue;">int</span>&nbsp;multiplier) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#2b91af;">Enumerable</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Repeat((<span style="color:#2b91af;">IExpression</span>)<span style="color:blue;">this</span>,&nbsp;multiplier) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Aggregate((x,&nbsp;y)&nbsp;=&gt;&nbsp;x.Plus(y)); }</pre> </p> <p> This is literally the same code as for <code>Money.Times</code>. You can also copy and paste this code to <code>PlusIdentity.Times</code>, but I'm not going to repeat it here, because it's the same code as above. </p> <p> This means that you can remove the <code>Times</code> method from <code>IExpression</code>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IExpression</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Money</span>&nbsp;Reduce(<span style="color:#2b91af;">Bank</span>&nbsp;bank,&nbsp;<span style="color:blue;">string</span>&nbsp;to); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IExpression</span>&nbsp;Plus(<span style="color:#2b91af;">IExpression</span>&nbsp;addend); }</pre> </p> <p> Instead, you can implement it as an extension method: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Expression</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">IExpression</span>&nbsp;Times(<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">IExpression</span>&nbsp;exp,&nbsp;<span style="color:blue;">int</span>&nbsp;multiplier) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#2b91af;">Enumerable</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Repeat(exp,&nbsp;multiplier) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Aggregate((x,&nbsp;y)&nbsp;=&gt;&nbsp;x.Plus(y)); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> This works because any <code>IExpression</code> object has a <code>Plus</code> method. </p> <p> As I've already admitted, this is likely to be less efficient than specialised implementations of <code>Times</code>. In Haskell, this is addressed by making <code>stimes</code> part of the typeclass, so that implementers can implement a more efficient algorithm than the default implementation. In C#, the same effect could be achieved by refactoring <code>IExpression</code> to an abstract base class, with <code>Times</code> as a public virtual (overridable) method. </p> <p> <strong>Haskell sanity check</strong> </p> <p> Since Haskell has a more formal definition of a monoid, you may want to try to port Kent Beck's API to Haskell, as a proof of concept. In its final modification, my C# fork has three implementations of <code>IExpression</code>: <ul> <li><code>Money</code></li> <li><code>Sum</code></li> <li><code>PlusIdentity</code></li> </ul> While interfaces are extensible, we were rightfully uneasy about this, so in Haskell, it seems safer to model these three subtypes as a sum type: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;<span style="color:#dd0000;">Expression</span>&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Money</span>&nbsp;{&nbsp;amount&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">Int</span>,&nbsp;currency&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">String</span>&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">|</span>&nbsp;<span style="color:#dd0000;">Sum</span>&nbsp;{&nbsp;augend&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">Expression</span>,&nbsp;addend&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">Expression</span>&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">|</span>&nbsp;<span style="color:#dd0000;">MoneyIdentity</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Show</span>)</pre> </p> <p> You can formally make this a <code>Monoid</code>: </p> <p> <pre><span style="color:blue;">instance</span>&nbsp;<span style="color:blue;">Monoid</span>&nbsp;<span style="color:blue;">Expression</span>&nbsp;<span style="color:blue;">where</span> &nbsp;&nbsp;mempty&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">MoneyIdentity</span> &nbsp;&nbsp;mappend&nbsp;<span style="color:#dd0000;">MoneyIdentity</span>&nbsp;y&nbsp;<span style="color:#666666;">=</span>&nbsp;y &nbsp;&nbsp;mappend&nbsp;x&nbsp;<span style="color:#dd0000;">MoneyIdentity</span>&nbsp;<span style="color:#666666;">=</span>&nbsp;x &nbsp;&nbsp;mappend&nbsp;x&nbsp;y&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Sum</span>&nbsp;x&nbsp;y</pre> </p> <p> The C# <code>Plus</code> method is here implemented by the <code>mappend</code> function. The only remaining member of <code>IExpression</code> is <code>Reduce</code>, which you can implement like this: </p> <p> <pre><span style="color:blue;">import</span>&nbsp;Data.Map.Strict&nbsp;(<span style="color:blue;">Map</span>,&nbsp;<span style="color:#2b91af;">(!)</span>) <span style="color:#600277;">reduce</span>&nbsp;::&nbsp;<span style="color:blue;">Ord</span>&nbsp;a&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;<span style="color:blue;">Map</span>&nbsp;(String,&nbsp;a)&nbsp;Int&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Expression</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Int reduce&nbsp;bank&nbsp;to&nbsp;(<span style="color:#dd0000;">Money</span>&nbsp;amt&nbsp;cur)&nbsp;<span style="color:#666666;">=</span>&nbsp;amt&nbsp;<span style="color:#666666;">`div`</span>&nbsp;rate &nbsp;&nbsp;<span style="color:blue;">where</span>&nbsp;rate&nbsp;<span style="color:#666666;">=</span>&nbsp;bank&nbsp;<span style="color:#666666;">!</span>&nbsp;(cur,&nbsp;to) reduce&nbsp;bank&nbsp;to&nbsp;(<span style="color:#dd0000;">Sum</span>&nbsp;x&nbsp;y)&nbsp;<span style="color:#666666;">=</span>&nbsp;reduce&nbsp;bank&nbsp;to&nbsp;x&nbsp;<span style="color:#666666;">+</span>&nbsp;reduce&nbsp;bank&nbsp;to&nbsp;y reduce&nbsp;_&nbsp;_&nbsp;<span style="color:#dd0000;">MoneyIdentity</span>&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#09885a;">0</span></pre> </p> <p> Haskell's typeclass mechanism takes care of the rest, so that, for example, you can reproduce one of Kent Beck's original tests like this: </p> <p> <pre>λ&gt; let bank = fromList [(("CHF","USD"),2), (("USD", "USD"),1)] λ&gt; let sum = stimesMonoid 2 $ MoneyPort.Sum (Money 5 "USD") (Money 10 "CHF") λ&gt; reduce bank "USD" sum 20</pre> </p> <p> Just like <code>stimes</code> works for any <code>Semigroup</code>, <code>stimesMonoid</code> is defined for any <code>Monoid</code>, and therefore you can also use it with <code>Expression</code>. </p> <p> With the historical 2:1 exchange rate, 5 Dollars + 10 Swiss Franc, times 2, is equivalent to 20 Dollars. </p> <p> <strong>Summary</strong> </p> <p> In chapter 17 of his book, Kent Beck describes that he'd been TDD'ing a Money API many times before trying out the expression-based API he ultimately used in the book. In other words, he had much experience, both with this particular problem, and with programming in general. Clearly this is a highly skilled programmer at work. </p> <p> I find it interesting that he seems to intuitively arrive at a design involving a monoid and an interpreter. If he did this on purpose, he doesn't say so in the book, so I rather speculate that he arrived at the design simply because he recognised its superiority. This is the reason that I find it interesting to identify this, <em>an existing example</em>, as a monoid, because it indicates that there's something supremely comprehensible about monoid-based APIs. It's conceptually 'just like addition'. </p> <p> In this article, we returned to a decade-old code example in order to identify it as a monoid. In the next article, I'm going to revisit an example code base of mine from 2015. </p> <p> <strong>Next: </strong> <a href="http://blog.ploeh.dk/2017/10/23/convex-hull-monoid">Convex hull monoid</a>. </p> </div> <div id="comments"> <hr /> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"> <a href="https://github.com/baic989">Hrvoje Baic</a> </div> <div class="comment-content"> <q>You'll notice that, throughout this example code base, both multiplier and amounts are modelled as integers. I think that Kent Beck did this as a simplification, but a more realistic example should use decimal values.</q> <p>Actually, in a lot of financial systems money is stored in cents, and therefore as integers, because it avoids rounding errors.</p> <p>Great articles btw! :)</p> </div> <div class="comment-date">2017-10-20 7:09 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Hrvoje, thank you for writing. Yes, it's a good point that you could model the values as cents and rappen, but I think I recall that Kent Beck's text distinctly discusses <em>dollars</em> and <em>francs</em>. I am, however, currently travelling, without access to the book, so I can't check. </p> <p> The scenario, as simplistic as it may be, involves currency exchange, and exchange rates tend to involve much smaller fractions. As an example, right now, one currency exchange web site reports that 1 CHF is 1.01950 USD. Clearly, representing the U.S. currency with cents would incur a loss of precision, because that would imply an exchange rate of 102 cents to 100 rappen. I'm sure arbitrage opportunities would be legion if you ever wrote code like that. </p> <p> If I remember number theory correctly, you can always scale any rational number to an integer. I.e. in this case, you could scale 1.01950 to 101,950. There's little reason to do that, because you have the <code>decimal</code> struct for that purpose: <blockquote> <a href="https://docs.microsoft.com/en-us/dotnet/api/system.decimal">"The Decimal value type is appropriate for financial calculations that require large numbers of significant integral and fractional digits and no round-off errors."</a> </blockquote> All of this, however, is just idle speculation on my point. I admit that I've never had to implement complex financial calculations, so there may be some edge cases of which I'm not aware. For all the run-of-the-mill eCommerce and payment solutions I've implemented over the years, <code>decimal</code> has always been more than adequate. </p> </div> <div class="comment-date">2017-10-20 8:14 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Strings, lists, and sequences as a monoid http://blog.ploeh.dk/2017/10/10/strings-lists-and-sequences-as-a-monoid 2017-10-10T09:37:00+00:00 Mark Seemann <div id="post"> <p> <em>Strings, lists, and sequences are essentially the same monoid. An introduction for object-oriented programmers.</em> </p> <p> This article is part of a <a href="http://blog.ploeh.dk/2017/10/06/monoids">series about monoids</a>. In short, a <em>monoid</em> is an associative binary operation with a neutral element (also known as <em>identity</em>). </p> <p> <strong>Sequences</strong> </p> <p> C# models a lazily evaluated sequence of values as <code>IEnumerable&lt;T&gt;</code>. You can combine two sequences by appending one to the other: </p> <p> <pre>xs.Concat(ys);</pre> </p> <p> Here, <code>xs</code> and <code>ys</code> are instances of <code>IEnumerable&lt;T&gt;</code>. The <a href="https://msdn.microsoft.com/en-us/library/bb302894">Concat</a> extension method concatenates two sequences together. It has the signature <code>IEnumerable&lt;T&gt; Concat&lt;T&gt;(IEnumerable&lt;T&gt;, IEnumerable&lt;T&gt;)</code>, so <a href="http://blog.ploeh.dk/2017/10/06/monoids">it's a binary operation</a>. If it's also associative and has identity, then it's a monoid. </p> <p> Sequences are associative, because the order of evaluation doesn't change the outcome. Associativity is a <em>property</em> of a monoid, so one way to demonstrate this is with <a href="http://www.shareasale.com/r.cfm?u=1017843&b=611266&m=53701&afftrack=&urllink=www%2Epluralsight%2Ecom%2Fcourses%2Ffsharp%2Dproperty%2Dbased%2Dtesting%2Dintroduction">property-based testing</a>: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;ConcatIsAssociative(<span style="color:blue;">int</span>[]&nbsp;xs,&nbsp;<span style="color:blue;">int</span>[]&nbsp;ys,&nbsp;<span style="color:blue;">int</span>[]&nbsp;zs) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;xs.Concat(ys).Concat(zs), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;xs.Concat(ys.Concat(zs))); }</pre> </p> <p> This automated test uses <a href="https://fscheck.github.io/FsCheck">FsCheck</a> (yes, it also works from C#!) to demonstrate that <code>Concat</code> is associative. For simplicity's sake, the test declares <code>xs</code>, <code>ys</code>, and <code>zs</code> as <em>arrays</em>. This is because FsCheck natively knows how to create arrays, whereas it doesn't have built-in support for <code>IEnumerable&lt;T&gt;</code>. While you can use FsCheck's API to define how <code>IEnumerable&lt;T&gt;</code> objects should be created, I didn't want to add this extra complexity to the example. The associativity property holds for other <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a> implementations of <code>IEnumerable&lt;T&gt;</code> as well. Try it, if you need to convince yourself. </p> <p> The <code>Concat</code> operation also has identity. The identity element is the empty sequence, as this FsCheck-based test demonstrates: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;ConcatHasIdentity(<span style="color:blue;">int</span>[]&nbsp;xs) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Enumerable</span>.Empty&lt;<span style="color:blue;">int</span>&gt;().Concat(xs), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;xs.Concat(<span style="color:#2b91af;">Enumerable</span>.Empty&lt;<span style="color:blue;">int</span>&gt;())); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;xs, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;xs.Concat(<span style="color:#2b91af;">Enumerable</span>.Empty&lt;<span style="color:blue;">int</span>&gt;())); }</pre> </p> <p> Appending an empty sequence before or after another sequence doesn't change the other sequence. </p> <p> Since <code>Concat</code> is an associative binary operation with identity, it's a monoid. </p> <p> <strong>Linked lists and other collections</strong> </p> <p> The above FsCheck-based tests demonstrate that <code>Concat</code> is a monoid for arrays. The properties hold for all pure implementations of <code>IEnumerable&lt;T&gt;</code>. </p> <p> In <a href="https://www.haskell.org">Haskell</a>, lazily evaluated sequences are modelled as linked lists. These are lazy because all Haskell expressions are lazily evaluated by default. The monoid laws hold for Haskell lists as well: </p> <p> <pre>λ&gt; ([1,2,3] ++ [4,5,6]) ++ [7,8,9] [1,2,3,4,5,6,7,8,9] λ&gt; [1,2,3] ++ ([4,5,6] ++ [7,8,9]) [1,2,3,4,5,6,7,8,9] λ&gt; [] ++ [1,2,3] [1,2,3] λ&gt; [1,2,3] ++ [] [1,2,3]</pre> </p> <p> In Haskell, <code>++</code> is the operator that corresponds to <code>Concat</code> in C#, but the operation is normally called <em>append</em> instead of <em>concat</em>. </p> <p> In <a href="http://fsharp.org">F#</a>, linked lists are eagerly evaluated, because all F# expressions are eagerly evaluated by default. Lists are still monoids, though, because the monoid laws still hold: </p> <p> <pre>&gt; ([1; 2; 3] @ [4; 5; 6]) @ [7; 8; 9];; val it : int list = [1; 2; 3; 4; 5; 6; 7; 8; 9] &gt; [1; 2; 3] @ ([4; 5; 6] @ [7; 8; 9]);; val it : int list = [1; 2; 3; 4; 5; 6; 7; 8; 9] &gt; [] @ [1; 2; 3];; val it : int list = [1; 2; 3] &gt; [1; 2; 3] @ [];; val it : int list = [1; 2; 3]</pre> </p> <p> In F#, the list concatenation operator is <code>@</code>, instead of <code>++</code>, but the behaviour is the same. </p> <p> <strong>Strings</strong> </p> <p> Have you ever wondered why text values are called <em>strings</em> in most programming languages? After all, for most people, a string is <a href="https://en.wikipedia.org/wiki/String_(structure)">a long flexible structure made from fibres</a>. What does that have to do with text? </p> <p> In programming, text is often arranged in memory as a consecutive block of characters, one after the other. Thus, you could think of text as characters like pearls on a string. A program often reads such a consecutive block of memory until it reaches a terminator of some kind. Thus, strings of characters have an order to them. They are similar to sequences and lists. </p> <p> In fact, in Haskell, the type <code>String</code> is nothing but a synonym for <code>[Char]</code> (meaning: a list of <code>Char</code> values). Thus, anything you can do with lists of other values, you can do with <code>String</code> values: </p> <p> <pre>λ&gt; "foo" ++ [] "foo" λ&gt; [] ++ "foo" "foo" λ&gt; ("foo" ++ "bar") ++ "baz" "foobarbaz" λ&gt; "foo" ++ ("bar" ++ "baz") "foobarbaz"</pre> </p> <p> Clearly, <code>++</code> over <code>String</code> is a monoid in Haskell. </p> <p> Likewise, in .NET, <code>System.String</code> implements <code>IEnumerable&lt;char&gt;</code>, so you'd expect it to be a monoid here as well - and it <em>almost</em> is. It's certainly associative: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;PlusIsAssociative(<span style="color:blue;">string</span>&nbsp;x,&nbsp;<span style="color:blue;">string</span>&nbsp;y,&nbsp;<span style="color:blue;">string</span>&nbsp;z) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(x&nbsp;+&nbsp;y)&nbsp;+&nbsp;z, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x&nbsp;+&nbsp;(y&nbsp;+&nbsp;z)); }</pre> </p> <p> In C#, the <code>+</code> operator is actually defined for <code>string</code>, and as the FsCheck test demonstrates, it's associative. It almost also has identity. What's the equivalent of an empty list for strings? The empty string: </p> <p> <pre>[<span style="color:#2b91af;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;PlusHasIdentity(<span style="color:#2b91af;">NonNull</span>&lt;<span style="color:blue;">string</span>&gt;&nbsp;x) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(<span style="color:#a31515;">&quot;&quot;</span>&nbsp;+&nbsp;x.Get,&nbsp;x.Get&nbsp;+&nbsp;<span style="color:#a31515;">&quot;&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(x.Get,&nbsp;x.Get&nbsp;+&nbsp;<span style="color:#a31515;">&quot;&quot;</span>); }</pre> </p> <p> Here, I had to tell FsCheck to avoid <code>null</code> values, because, as usual, <code>null</code> throws a big wrench into our attempts at being able to reason about the code. </p> <p> The problem here is that <code>"" + null</code> and <code>null + ""</code> both return <code>""</code>, which is not equal to the input value (<code>null</code>). In other words, <code>""</code> is not a true identity element for <code>+</code>, because of this single special case. (And by the way, <code>null</code> isn't the identity element either, because <code>null + null</code> returns... <code>""</code>! Of course it does.) This is, however, an implementation detail. As an exercise, consider writing an (extension) method in C# that makes <code>string</code> a proper monoid, even for <code>null</code> values. If you can do that, you'll have demonstrated that string concatenation is a monoid in .NET, just as it is in Haskell. </p> <p> <strong>Free monoid</strong> </p> <p> Recall that in the previous article, you learned how both addition and multiplication of numbers form monoids. There's at least one more monoid for numbers, and that's a sequence. If you have a generic sequence (<code>IEnumerable&lt;T&gt;</code>), it can contain anything, including numbers. </p> <p> Imagine that you have two numbers, 3 and 4, and you want to combine them, but you haven't yet made up your mind about <em>how</em> you want to combine them. In order to postpone the decision, you can put both numbers in a singleton array (that is, an array with a single element, not to be confused with the <a href="https://en.wikipedia.org/wiki/Singleton_pattern">Singleton design pattern</a>): </p> <p> <pre><span style="color:blue;">var</span>&nbsp;three&nbsp;=&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;3&nbsp;}; <span style="color:blue;">var</span>&nbsp;four&nbsp;=&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;4&nbsp;};</pre> </p> <p> Since sequences are monoids, you can combine them: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;combination&nbsp;=&nbsp;three.Concat(four); </pre> </p> <p> This gives you a new sequence that contains both numbers. At this point, you haven't lost any information, so once you've decided how to combine the numbers, you can <em>evaluate</em> the data that you've collected so far. This is called the <a href="https://bartoszmilewski.com/2015/07/21/free-monoids">free monoid</a>. </p> <p> If you need the sum of the numbers, you can add them together: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;sum&nbsp;=&nbsp;combination.Aggregate(0,&nbsp;(x,&nbsp;y)&nbsp;=&gt;&nbsp;x&nbsp;+&nbsp;y); </pre> </p> <p> (Yes, I'm aware that the <a href="https://msdn.microsoft.com/en-us/library/bb338442">Sum</a> method exists, but I want you to see the details.) This <a href="https://msdn.microsoft.com/en-us/library/bb549218">Aggregate</a> overloads takes a <code>seed</code> value as the first argument, and a function to combine two values as the second. </p> <p> Here's how to get the product: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;product&nbsp;=&nbsp;combination.Aggregate(1,&nbsp;(x,&nbsp;y)&nbsp;=&gt;&nbsp;x&nbsp;*&nbsp;y); </pre> </p> <p> Notice how in both cases, the <code>seed</code> value is the identity for the monoidal operation: 0 for addition, and 1 for multiplication. Likewise, the aggregator function uses the binary operation associated with that particular monoid. </p> <p> I think it's interesting that this is called the free monoid, similar to <a href="http://blog.ploeh.dk/2017/07/10/pure-interactions">free monads</a>. In both cases, you collect data without initially interpreting it, and then later you can submit the collected data to one of several evaluators. </p> <p> <strong>Summary</strong> </p> <p> Various collection types, like .NET sequences, arrays, or Haskell and F# lists, are monoids over concatenation. In Haskell, strings <em>are</em> lists, so string concatenation is a monoid as well. In .NET, the <code>+</code> operator for strings is a monoid if you pretend that <code>null</code> strings don't exist. Still, all of these are essentially variations of the same monoid. </p> <p> It makes sense that C# uses <code>+</code> for string concatenation, because, as the <a href="http://blog.ploeh.dk/2017/10/06/monoids">previous article</a> described, addition is the most intuitive and 'natural' of all monoids. Because you know first-grade arithmetic, you can immediately grasp the concept of addition as a metaphor. A monoid, however, is more than a metaphor; it's an abstraction that describes well-behaved binary operations, where one of those operations just happen to be addition. It's a <em>generalisation</em> of the concept. It's an abstraction that you already understand. </p> <p> <strong>Next: </strong> <a href="http://blog.ploeh.dk/2017/10/16/money-monoid">Money monoid</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment"> <div class="comment-author"><a href="http://lestard.eu/">Manuel Mauky</a></div> <div class="comment-content">Hi, I have a question regarding the free monoid part. Can you concretize what exactly "is called the free monoid"? What I understand is that in your example the `Aggregate` method basically gets a monoid as argument (first the identity element and second the operation). Is `Aggregate` a free monoid here? If so, is `Aggregate` the only possible free monoid for this data type or are there other examples of free monoids for numbers? Or is the two-element sequence `combination` the free monoid? Is "free monoid" a special sort of monoids? <br> Thanks for this article series! Best regards, Manuel </div> <div class="comment-date">2017-11-15 17:33 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Manuel, thank you for writing. The confusion is entirely caused by my sloppy writing. A monoid is an associative binary operation with identity. Since the free monoid essentially elevates each number to a singleton list, the binary operation in question is <em>list concatenation</em>. </p> <p> The <code>Aggregate</code> method is a built-in BCL method that aggregates values. I'll have more to say about that in later articles, but aggregation in itself is not a monoid; it follows from monoids. </p> <p> I've yet to find a source that explains the etymology of the 'free' terminology, but as far as I can tell, free monoids, as well as free monads, are instances of a particular abstraction that you 'get for free', so to speak. You can <em>always</em> put values into singleton lists, just like you can <em>always</em> create a free monad from any functor. These instances are lossless in the sense that performing operations on them never erase data. For the free monoid, you just keep on concatenating more values to your list of values. </p> <p> This decouples the collection of data from evaluation. Data collection is lossless. Only when you want to evaluate the result must you decide on a particular type of evaluation. For integers, for example, you could choose between addition and multiplication. Once you perform the evaluation, the result is lossy. </p> <p> In Haskell, the <code>Data.Monoid</code> module defines an <code>&lt;&gt;</code> infix operator that you can use as the binary operation associated with a particular type. For lists, you can use it like this: </p> <p> <pre>Prelude Data.Monoid Data.Foldable&gt; xs = [3] &lt;&gt; [4] &lt;&gt; [5] Prelude Data.Monoid Data.Foldable&gt; xs [3,4,5]</pre> </p> <p> Notice how the operation isn't lossy. This means you can defer the decision on how to evaluate it until later: </p> <p> <pre>Prelude Data.Monoid Data.Foldable&gt; getSum $ fold $ Sum &lt;$&gt; xs 12 Prelude Data.Monoid Data.Foldable&gt; getProduct $ fold $ Product &lt;$&gt; xs 60</pre> </p> <p> Notice how you can choose to evaluate <code>xs</code> to calculate the sum, or the product. </p> </div> <div class="comment-date">2017-11-16 15:56 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://github.com/giacomociti">Giacomo Citi</a></div> <div class="comment-content"> <p> I think the word <em>free</em> is used in algebraic structures to suggest that all possible interpretations are left open. This is because they are not constrained by additional specific laws which would allow to further evaluate (reduce, simplify) expressions. </p> <p> For example, <pre>2+0</pre> can be simplified to <pre>2</pre> due to Monoid laws (identity) while <pre>2+3</pre> can be reduced to <pre>5</pre> due to specific arithmetic laws. </p> <p> Freedom from further constraints also mean that we can always devise automatically (hence free as in <q>free beer</q>) an instance from a signature. This construction is called <a href="https://en.wikipedia.org/wiki/Term_algebra/">term algebra</a>; its values are essentially the syntactic structures (AST) of the expressions allowed by the signature and the sole simplifications permitted are those specified by the general laws. </p> <p> In the case of a Monoid, thanks to associativity (which is a Monoid law, not specific to any particular instance), if we consider complex expressions like <pre>(1+3)+2</pre> we can flatten their AST to a list <pre>[1,3,2]</pre> without losing information and still without committing yet to any specific interpretation. And for atomic expressions like <pre>3</pre> the single node AST becomes a singleton list. </p> </div> <div class="comment-date">2017-11-23 19:52 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Monoids http://blog.ploeh.dk/2017/10/06/monoids 2017-10-06T07:38:00+00:00 Mark Seemann <div id="post"> <p> <em>Introduction to monoids for object-oriented programmers.</em> </p> <p> This article is part of <a href="http://blog.ploeh.dk/2017/10/05/monoids-semigroups-and-friends">a larger series about monoids, semigroups, and related concepts</a>. In this article, you'll learn what a monoid is, and what distinguishes it from a semigroup. </p> <p> <img src="/content/binary/monoids-subset-of-semigroups.png" alt="Monoids are a subset of semigroups."> </p> <p> Monoids form a subset of semigroups. The rules that govern monoids are stricter than those for semigroups, so you'd be forgiven for thinking that it would make sense to start with semigroups, and then build upon that definition to learn about monoids. From a strictly hierarchical perspective, that would make sense, but I think that monoids are more intuitive. When you see the most obvious monoid example, you'll see that they cover operations from everyday life. It's easy to think of examples of monoids, while you have to think harder to find some good semigroup examples. That's the reason I think that you should start with monoids. </p> <p> <strong>Monoid laws</strong> </p> <p> What do addition (<code>40 + 2</code>) and multiplication (<code>6 * 7</code>) have in common? </p> <p> They're both <ul> <li>associative</li> <li>binary operations</li> <li>with a neutral element.</li> </ul> That's all it takes to form a monoid. Associativity and the existence of a neutral element is sometimes referred to as the <em>monoid laws</em>. It's worth noting that a monoid is a combination of a data type (or set) and an operation. It's not a data type in itself, but rather a function (or method) that operates on that data type. For example, addition and multiplication are two different monoids that both work on numbers. </p> <p> <strong>Binary operation</strong> </p> <p> Let's start with the most basic property. That an operation is <em>binary</em> means that it works on <em>two</em> values. Perhaps you mostly associate the word <em>binary</em> with binary numbers, such as 101010, but the word originates from Latin and means something like <em>of two</em>. Astronomers talk about <em>binary stars</em>, but the word is dominantly used in computing context: apart from binary numbers, you may also have heard about binary trees. When talking about binary operations, it's implied that both input values are of the same type, and that the return type is the same as the input type. In other words, a C# method like this is a proper binary operation: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Foo</span>&nbsp;Op(<span style="color:#2b91af;">Foo</span>&nbsp;x,&nbsp;<span style="color:#2b91af;">Foo</span>&nbsp;y) </pre> </p> <p> Sometimes, if <code>Op</code> is an instance method on the <code>Foo</code> class, it can also look like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Foo</span>&nbsp;Op&nbsp;(<span style="color:#2b91af;">Foo</span>&nbsp;foo) </pre> </p> <p> On the other hand, this isn't a binary operation: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Baz</span>&nbsp;Op(<span style="color:#2b91af;">Foo</span>&nbsp;f,&nbsp;<span style="color:#2b91af;">Bar</span>&nbsp;b) </pre> </p> <p> Although it takes two input arguments, they're of different types, and the return type is a third type. </p> <p> Since all involved arguments and return values are of the same type, a binary operation exhibits what Eric Evans in <a href="http://amzn.to/WBCwx7">Domain-Driven Design</a> calls <em>Closure of Operations</em>. </p> <p> <strong>Associative</strong> </p> <p> In order to form a monoid, the binary operation must be <em>associative</em>. This simply means that the order of evaluation doesn't matter. For example, for addition, it means that </p> <p> <pre>(2 + 3) + 4 = 2 + (3 + 4) = 2 + 3 + 4 = 9</pre> </p> <p> Likewise, for multiplication </p> <p> <pre>(2 * 3) * 4 = 2 * (3 * 4) = 2 * 3 * 4 = 24</pre> </p> <p> Expressed as the above <code>Op</code> instance method, associativity would require that <code>areEqual</code> is <code>true</code> in the following code: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;areEqual&nbsp;=&nbsp;foo1.Op(foo2).Op(foo3)&nbsp;==&nbsp;foo1.Op(foo2.Op(foo3)); </pre> </p> <p> On the left-hand side, <code>foo1.Op(foo2)</code> is evaluated first, and the result then evaluated with <code>foo3</code>. On the right-hand side, <code>foo2.Op(foo3)</code> is evaluated first, and then used as an input argument to <code>foo1.Op</code>. Since the left-hand side and the right-hand side are compared with the <code>==</code> operator, associativity requires that <code>areEqual</code> is <code>true</code>. </p> <p> In C#, if you have a custom monoid like <code>Foo</code>, you'll have to override <code>Equals</code> and implement the <code>==</code> operator in order to make all of this work. </p> <p> <strong>Neutral element</strong> </p> <p> The third rule for monoids is that there must exist a neutral value. In the normal jargon, this is called the <em>identity</em> element, and this is what I'm going to be calling it from now on. I only wanted to introduce the concept using a friendlier name. </p> <p> The identity element is a value that doesn't 'do' anything. For addition, for example, it's zero, because adding zero to a value doesn't change the value: </p> <p> <pre>0 + 42 = 42 + 0 = 42</pre> </p> <p> As an easy exercise, see if you can figure out the identity value for multiplication. </p> <p> As implied by the above sum, the identity element must act neutrally both when applied to the left-hand side and the right-hand side of another value. For our <code>Foo</code> objects, it could look like this: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;hasIdentity&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Foo</span>.Identity.Op(foo)&nbsp;==&nbsp;foo.Op(<span style="color:#2b91af;">Foo</span>.Identity)&nbsp;&amp;&amp; &nbsp;&nbsp;&nbsp;&nbsp;foo.Op(<span style="color:#2b91af;">Foo</span>.Identity)&nbsp;==&nbsp;foo;</pre> </p> <p> Here, <code>Foo.Identity</code> is a static read-only field of the type <code>Foo</code>. </p> <p> <strong>Examples</strong> </p> <p> There are plenty of examples of monoids. The most obvious examples are addition and multiplication, but there are more. Depending on your perspective, you could even say that there's more than one addition monoid, because there's one for integers, one for real numbers, and so on. The same can be said for multiplication. </p> <p> There are also two monoids over boolean values called <em>all</em> and <em>any</em>. If you have a binary operation over boolean values called <em>all</em>, how do you think it works? What would be the identity value? What about <em>any?</em> </p> <p> I'll leave you to ponder (or look up) <em>all</em> and <em>any</em>, and instead, in the next articles, show you some slightly more interesting monoids. <ul> <li><a href="http://blog.ploeh.dk/2017/10/10/strings-lists-and-sequences-as-a-monoid">Strings, lists, and sequences as a monoid</a></li> <li><a href="http://blog.ploeh.dk/2017/10/16/money-monoid">Money monoid</a></li> <li><a href="http://blog.ploeh.dk/2017/10/23/convex-hull-monoid">Convex hull monoid</a></li> <li><a href="http://blog.ploeh.dk/2017/10/30/tuple-monoids">Tuple monoids</a></li> <li><a href="http://blog.ploeh.dk/2017/11/06/function-monoids">Function monoids</a></li> <li><a href="http://blog.ploeh.dk/2017/11/13/endomorphism-monoid">Endomorphism monoid</a></li> <li><a href="http://blog.ploeh.dk/2017/11/20/monoids-accumulate">Monoids accumulate</a></li> </ul> In essence, if you have a data type that 'behaves like a number', you can probably make it a monoid. Addition is often the best candidate, because it doesn't mess with the dimensions of what you're keeping track of. As an example, the .NET Base Class Library defines a <a href="https://msdn.microsoft.com/en-us/library/system.timespan">TimeSpan structure</a> with an <a href="https://msdn.microsoft.com/en-us/library/system.timespan.add">Add method</a>. It also comes with a <code>==</code> operator. On the other hand, there's no <code>Multiply</code> method for <code>TimeSpan</code>, because what does it mean to multiply two durations? What would the dimension be? <a href="https://en.wikipedia.org/wiki/Time_Squared_(Star_Trek:_The_Next_Generation)">Time squared</a>? </p> <p> <strong>Summary</strong> </p> <p> A monoid (not to be confused with a monad) is a binary operation that satisfies the two monoid laws: that the operation is associative, and that an identity element exists. Addition and multiplication are prime examples, but several others exist. </p> <p> (By the way, the identity element for multiplication is <em>one</em> (<em>1</em>), <em>all</em> is boolean <em>and</em>, and <em>any</em> is boolean <em>or</em>.) </p> <p> <strong>Next: </strong> <a href="http://blog.ploeh.dk/2017/10/10/strings-lists-and-sequences-as-a-monoid">Strings, lists, and sequences as a monoid</a>. </p> </div> <div id="comments"> <hr /> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"> <a href="https://github.com/khaledh">Khaled Hammouda</a> </div> <div class="comment-content"> <p>Great series! I'm a big fan of intuitive abstractions and composition. Can't wait for the remaining parts.</p> <p>I first heard of the <i>closure property</i> in <a href="http://sarabander.github.io/sicp/html/2_002e2.xhtml#g_t2_002e2">SICP</a>, where it's mentioned that: <blockquote>In general, an operation for combining data objects satisfies the closure property if the results of combining things with that operation can themselves be combined using the same operation.</blockquote> Also, a reference to the algebraic origin of this concept is made in the foot note for this sentence: <blockquote>The use of the word "closure" here comes from abstract algebra, where a set of elements is said to be closed under an operation if applying the operation to elements in the set produces an element that is again an element of the set.</blockquote> </p> <p>It's interesting to see this concept come up over and over, although it hasn't been widely socialized as a formal construct to software composition.</p> </div> <div class="comment-date">2017-10-06 15:38 UTC</div> </div> <div class="comment"> <div class="comment-author"> <a href="http://kearon.blogspot.co.uk/">Sean Kearon</a> </div> <div class="comment-content"> <p>This looks like it's going to be a fantastic series - I'm really looking forwards to reading the rest!</p> <p>So, as we are talking about <a href="http://blog.ploeh.dk/2017/10/04/from-design-patterns-to-category-theory/">forming a vocabulary and reducing ambiguity</a>, I have a question about the use of the word <i>closure</i>, which I think has more than one common meaning in this context.</p> <p>In Eric Evans' "Closure of Operations", <i><i>closure</i></i> refers to the fact that the operation is "closed" over it's set of possible values - in other words, the set is closed under the operation.</p> <p><i>Closure</i> is also used to describe a <a href="https://simple.wikipedia.org/wiki/Closure_(computer_science)">function with a bound value</a> (as in the <a href="http://wiki.c2.com/?ClosuresAndObjectsAreEquivalent">poor man's object"</a>).</p> <p>These are two separate concepts as far as I am aware. Also, I suspect that the latter meaning is likely more well known to C# devs reading this series, especially ReSharper users who have come across it's "implicitly captured closure" detection. So, if I am correct, do you think it is worth making this distinction clear to avoid potential confusion?</p> </div> <div class="comment-date">2017-10-18 07:30 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Sean, thank you for writing. That's a great observation, and one that I frankly admit that I hadn't made myself. In an ideal world, one of those concepts would have a different name, so that we'd be able to distinguish them from each other. </p> <p> In my experience, I find that the context in which I'm using those words tend to make the usage unambiguous, but I think that you have a good point that some readers may be more familiar with <em>closure</em> as a captured outer value, rather than the concept of an operation where the domain and the codomain is the same. I'll see if I can make this clearer when I revisit Evans' example. </p> </div> <div class="comment-date">2017-10-18 12:02 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://github.com/vitrun">Vitrun</a></div> <div class="comment-content"> <p>I'm recently learning category theory, and happened to read this blog. Great post! I'll follow up the series.</p> <p>I find it a little confusing:</p> <p> <blockquote>(By the way, the identity element for multiplication is one (1), all is boolean and, and any is boolean or.)</blockquote> </p> <p>Identity element should be the element of the collection rather than operation, right? So, the id for all should be True, and that of any should be False.</p> </div> <div class="comment-date">2017-12-03 03:36 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Vitrun, thank you for writing. Yes, the identity for <em>any</em> is <em>false</em>, and for <em>all</em> it's <em>true</em>. There are two other monoids over Boolean values. Can you figure out what they are? </p> <p> I don't understand this: <blockquote>"Identity element should be the element of the collection rather than operation"</blockquote> Can you elaborate what you mean by that? </p> </div> <div class="comment-date">2017-12-03 18:56 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://github.com/vitrun">Vitrun</a></div> <div class="comment-content"> <p>A monoid is a sequence (M, e, ⋆), where M is a set, e ∈ M is the identity, and ⋆ is the function/operator.</p> <p>To be clear. I mean, the identity should be the element of the set, rather than the operator</p> <p>Are the other two <em>and</em> and <em>or</em>?</p> <p>I found you good at bridging the gap between programming practice and ivory-tower concepts. How do you do that?</p> </div> <div class="comment-date">2017-12-04 04:25 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Vitrun, thank you for your kind words. I don't know if I have a particular way of 'bridging the gap'; I try to identify patterns in the problems I run into, and then communicate those patterns in as simple a language as I can, with as helpful examples as I can think of... </p> <p> <blockquote>the identity should be the element of the set</blockquote> Yes. </p> <p> Regarding monoids over Boolean values, <em>any</em> is another name for Boolean <em>or</em>, and <em>all</em> is another name for Boolean <em>and</em>. That's two monoids (<em>any</em> and <em>all</em>); in addition to those, there are two more monoids over Booleans. I could tell you what they are, but it's a good exercise if you can figure them out by yourself. If not, you can easily Google them. </p> </div> <div class="comment-date">2017-12-05 08:27 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Monoids, semigroups, and friends http://blog.ploeh.dk/2017/10/05/monoids-semigroups-and-friends 2017-10-05T08:24:00+00:00 Mark Seemann <div id="post"> <p> <em>Introduction to monoids, semigroups, and similar concepts, for object-oriented programmers.</em> </p> <p> This article series is part of <a href="http://blog.ploeh.dk/2017/10/04/from-design-patterns-to-category-theory">an even larger series of articles about the relationship between design patterns and category theory.</a> </p> <p> Functional programming has often been criticised for its abstruse jargon. Terminology like <em>zygohistomorphic prepromorphism</em> doesn't help sell the message, but before we start throwing stones, we should first exit our own glass house. In object-oriented design, we have names like <a href="https://en.wikipedia.org/wiki/Bridge_pattern">Bridge</a>, <a href="https://en.wikipedia.org/wiki/Visitor_pattern">Visitor</a>, <a href="https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)">SOLID</a>, <a href="https://en.wikipedia.org/wiki/Cohesion_(computer_science)">cohesion</a>, and so on. The words sound familiar, but can you actually explain or implement the Visitor design pattern, or characterise cohesion? </p> <p> That <em>Bridge</em> is a word you know doesn't make object-oriented terminology better. Perhaps it even makes it worse. After all, now the word has become ambiguous: did you mean a physical structure connecting two places, or are you talking about the design pattern? Granted, in practical use, it will often be clear from the context, but it doesn't change that if someone talks about the Bridge pattern, you'll have no idea what it is, unless you've actually learned it. Thus, that the word is familiar doesn't make it better. </p> <p> More than one object-oriented programmer have extolled the virtues of 'operations whose return type is the same as the type of its argument(s)'. Such vocabulary, however, is inconvenient. Wouldn't it be nice to have a single, well-defined word for this? Perhaps <em>monoid</em>, or <em>semigroup?</em> </p> <p> <strong>Object-oriented hunches</strong> </p> <p> In <a href="http://amzn.to/WBCwx7">Domain-Driven Design</a>, Eric Evans discusses the notion of <em>Closure of Operations</em>, that is, operations "whose return type is the same as the type of its argument(s)." In C#, it could be a method with the signature <code>public Foo Bar(Foo f1, Foo f2)</code>. This method takes two <code>Foo</code> objects as input, and returns a new <code>Foo</code> object as output. </p> <p> As Evans points out, object designs with that quality begins to look like arithmetic. If you have an operation that takes two <code>Foo</code> and returns a <code>Foo</code>, what could it be? Could it be like addition? Multiplication? Another mathematical operation? </p> <p> Some <a href="http://blog.ploeh.dk/2012/12/18/RangersandZookeepers">enterprise developers</a> just 'want to get stuff done', and don't care about mathematics. To them, the value of making code more mathematical is disputable. Still, even if you 'don't like maths', you understand addition, multiplication, and so on. Arithmetic is a powerful metaphor, because all programmers understand it. </p> <p> In his book <a href="http://bit.ly/tddbe">Test-Driven Development: By Example</a>, Kent Beck <a href="http://blog.ploeh.dk/2017/10/16/money-monoid">seems to have the same hunch</a>, although I don't think he ever explicitly calls it out. </p> <p> What Evans describes are monoids, semigroups, and similar concepts from abstract algebra. To be fair, I recently had the opportunity to discuss the matter with him, and he's perfectly aware of those concepts today. Whether he was aware of them when he wrote DDD in 2003 I don't know, but I certainly wasn't; my errand isn't to point fingers, but to point out that clever people have found this design principle valuable in object-oriented design long before they gave it a distinct name. </p> <p> <strong>Relationships</strong> </p> <p> Monoids and semigroups belong to a larger group of operations called <em>magmas</em>. You'll learn about those later, but we'll start with monoids, move on to semigroups, and then explore other magmas. All monoids are semigroups, while the inverse doesn't hold. In other words, monoids form a subset of semigroups. </p> <p> <img src="/content/binary/magmas-quasigroups-semigroups-monoids.png" alt="Monoids are a subset of semigroups, and part of the larger magma set."> </p> <p> All magmas describe binary operations of the form: an operation takes two <code>Foo</code> values as input and returns a <code>Foo</code> value as output. Both categories are governed by (intuitive) laws. The difference is that the laws governing monoids are stricter than the laws governing semigroups. Don't be put off by the terminology; 'law' may sound like you have to get involved in complicated maths, but these laws are simple and intuitive. You'll learn them as you read on. <ul> <li><a href="http://blog.ploeh.dk/2017/10/06/monoids">Monoids</a> <ul> <li><a href="http://blog.ploeh.dk/2017/10/10/strings-lists-and-sequences-as-a-monoid">Strings, lists, and sequences as a monoid</a></li> <li><a href="http://blog.ploeh.dk/2017/10/16/money-monoid">Money monoid</a></li> <li><a href="http://blog.ploeh.dk/2017/10/23/convex-hull-monoid">Convex hull monoid</a></li> <li><a href="http://blog.ploeh.dk/2017/10/30/tuple-monoids">Tuple monoids</a></li> <li><a href="http://blog.ploeh.dk/2017/11/06/function-monoids">Function monoids</a></li> <li><a href="http://blog.ploeh.dk/2017/11/13/endomorphism-monoid">Endomorphism monoid</a></li> <li><a href="http://blog.ploeh.dk/2017/11/20/monoids-accumulate">Monoids accumulate</a></li> </ul> </li> <li><a href="http://blog.ploeh.dk/2017/11/27/semigroups">Semigroups</a> <ul> <li><a href="http://blog.ploeh.dk/2017/12/04/bounding-box-semigroup">Bounding box semigroup</a></li> <li><a href="http://blog.ploeh.dk/2017/12/11/semigroups-accumulate">Semigroups accumulate</a></li> </ul> </li> <li>Quasigroups</li> <li>Magmas <ul> <li>Rock Paper Scissors magma</li> <li>Colour-mixing magma</li> </ul> </li> </ul> While they seem firmly rooted in mathematics, these categories offer insights into object-oriented design as well. More on that later. </p> <p> <strong>Summary</strong> </p> <p> To the average object-oriented programmer, terms like <em>monoid</em> and <em>semigroup</em> smell of mathematics, academia, and ivory-tower astronaut architects, but they're plain and simple concepts that anyone can understand, if they wish to invest 15 minutes of their time. </p> <p> Whether or not an object is a <em>magma</em> tells us whether Evans' <em>Closure of Operations</em> is possible. It might teach us other things about our code, as well. </p> <p> <strong>Next: </strong> <a href="http://blog.ploeh.dk/2017/10/06/monoids">Monoids</a>. </p> </div> <div id="comments"> <hr /> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"> <a href="https://megakemp.com">Enrico Campidoglio</a> </div> <div class="comment-content"> <p>Hi Mark,</p> <p>Thank you for taking the time to write such interesting articles. I'm personally fascinated by the relationship between ancient subjects like algebra and modern ones like programming. I can't wait to read more.</p> <p>That said, I understand the feeling of being put off by some of the terms used in functional programming (I'm looking at you, "<em>zygohistomorphic</em>"). I think the reason for it is that the vast majority of those words come from Greek or Latin, and to many people (me included) Greek is exactly what it sounds like — <a href="https://en.wikipedia.org/wiki/Greek_to_me">Greek</a>.</p> <p>Granted, things aren't much better in the object-oriented programming world, where a <em>Visitor</em> isn't necessarily what you think it is, even if you recognize the word.</p> <p>However, in my experience, knowing the etymology of a word is the first step in understanding it. I think that including a translation for every new term would make the subjects of these articles feel less alien. It would be a way to "break the ice", so to speak.</p> <p>One example I came to think of is the word <a href="https://en.wikipedia.org/wiki/Polymorphism_(computer_science)"><em>polymorphism</em></a> — perhaps one of the most "academic-sounding" words thrown around in object-oriented programming conversations. It may feel intimidating at first, but it quickly falls off the ivory tower once you know that it literally means "when things can take many shapes" (from the Greek <em>polys</em>, "many", <em>morphē</em>, "shape" and "<em>ismós</em>", the general concept).</p> <p>/Enrico</p> </div> <div class="comment-date">2017-10-05 12:24 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Enrico, thank you for writing. Funny you should write that, because leading with an explanation of <em>monoid</em> is exactly what I do in my new <a href="https://cleancoders.com">Clean Coders</a> episode <a href="https://cleancoders.com/episode/humane-code-real-episode-2/show">Composite as Universal Abstraction</a>. In short, <em>monoid</em> means 'one-like'. In the video, I go into more details on why that's a useful name. </p> </div> <div class="comment-date">2017-10-08 8:06 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://avpinzur.com">Av Pinzur</a></div> <div class="comment-content"> <p> Hey, Mark, what a great start on a very promising series! One more accessibility suggestion along the same lines as Enrico's: You might consider including pronunciation for new terms that aren't obvious. </p> <p> Eagerly anticipating future installments! </p> </div> <div class="comment-date">2017-10-09 14:43 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. From design patterns to category theory http://blog.ploeh.dk/2017/10/04/from-design-patterns-to-category-theory 2017-10-04T10:43:00+00:00 Mark Seemann <div id="post"> <p> <em>How do you design good abstractions? By using abstractions that already exist.</em> </p> <p> When I was a boy, I had a <a href="https://en.wikipedia.org/wiki/Cassette_deck">cassette tape player</a>. It came with playback controls like these: </p> <p> <img src="/content/binary/playback-controls.png" alt="Rewind, play/pause, and fast forward symbols."> </p> <p> Soon after cassette players had become widely adopted, <a href="https://en.wikipedia.org/wiki/Videocassette_recorder">VCR</a> manufacturers figured out that they could reuse those symbols to make their machines easier to use. Everyone could play a video tape, but 'no one' could 'program' them, because, while playback controls were already universally understood by consumers, each VCR came with its own proprietary interface for 'programming'. </p> <p> Then came <a href="https://en.wikipedia.org/wiki/CD_player">CD players</a>. Same controls. </p> <p> MP3 players. Same controls. </p> <p> Streaming audio and video players. Same controls. </p> <p> If you download an app that plays music, odds are that you'll find it easy to get started playing music. One reason is that all playback apps seem to have the same common set of controls. It's an abstraction that you already know. </p> <p> <strong>Understanding source code</strong> </p> <p> As I explain in my <a href="https://cleancoders.com/episode/humane-code-real-episode-1/show">Humane Code</a> video, you can't program without abstractions. To summarise, in <a href="http://amzn.to/19W4JHk">the words of Robert C. Martin</a> <blockquote> "Abstraction is the elimination of the irrelevant and the amplification of the essential" </blockquote> With such abstractions, source code becomes easier to understand. Like everything else, there's no silver bullet, but good coding abstractions can save you much grief, and make it easier to understand big and complex code bases. </p> <p> Not only can a good abstraction shield you from having to understand all the details in a big system, but if you're familiar with the abstraction, you may be able to quickly get up to speed. </p> <p> While the above definition is great for identifying a good abstraction, it doesn't tell you how to create one. </p> <p> <strong>Design patterns</strong> </p> <p> <a href="http://amzn.to/XBYukB">Design Patterns</a> explains that a design pattern is a general reusable solution to a commonly occurring problem. As I interpret the original intent of the Gang of Four, the book was an attempt to collect and abstract solutions that were repeatedly observed 'in the wild'. The design patterns in the book are <em>descriptive</em>, not prescriptive. </p> <p> Design patterns are useful in two ways: <ul> <li>They offer solutions</li> <li>They form a vocabulary</li> </ul> In my opinion, however, people often overlook the second advantage. Programmers are often eager to find <em>solutions</em>. "I have a problem; what's the solution? Oh, here's a design pattern that fits!" </p> <p> I have no problems with ready-made solutions, but I think that the other advantage may be even bigger. When you're looking at unfamiliar source code, you struggle to understand how it's structured, and what it does. If, hypothetically, you discover that pieces of that unfamiliar source code follows a design pattern that you know, then understanding the code becomes much easier. </p> <p> There are two criteria for this to happen: <ul> <li>The reader (you) must already know the pattern</li> <li>The original author (also you?) must have implemented the pattern without any surprising deviations</li> </ul> As a programmer (code author), you can help readers (users) of your code. Don't use every design pattern in the book, but when you use one, make it as obvious to the reader as you can: Use the terminology, class names, and so on from the book. Add comments where your naming deviates. Add links that the novice user can follow to learn more. </p> <p> <strong>Ambiguous specification</strong> </p> <p> Programming to a well-known abstraction is a force multiplier, but it does require that those two conditions are satisfied: prior knowledge, and correct implementation. </p> <p> I don't know how to solve the <em>prior knowledge</em> requirement, other than to tell you to study. I do, however, think that it's possible to formalise some of the known design patterns. </p> <p> Most design patterns are described in some depth. They come with sections on motivation, when to use and not to use, diagrams, and example code. Furthermore, they also come with an overview of <em>variations</em>. </p> <p> Picture this: as a reader, you've just identified that the code you're looking at is an implementation of a design pattern. Then you realise that it isn't structured like you'd expect, or that its behaviour surprises you. Was the author incompetent, after all? </p> <p> While you're inclined to believe the worst about your fellow (wo)man, you look up the original pattern, and there it is: the author is using a variation of the pattern. </p> <p> Design patterns are ambiguous. </p> <p> <strong>Universal abstractions</strong> </p> <p> <em>Design Patterns</em> was a great effort in 1994, and I've personally benefited from it. The catalogue was an attempt to discover good abstractions. </p> <p> What's a good abstraction? As already quoted, it's a model that amplifies the essentials, etcetera. I think a good abstraction should also be <em>intuitive</em>. </p> <p> What's the most intuitive abstractions ever? </p> <p> Mathematics. </p> <p> Stay with me, please. If you're a normal reader of my blog, you're most likely an 'industry programmer' or <a href="http://blog.ploeh.dk/2012/12/18/RangersandZookeepers">enterprise developer</a>. You're not interested in mathematics. Perhaps mathematics even turns you off, and at the very least, you never had use for mathematics in programming. </p> <p> You may not find <em>n</em>-dimensional <a href="https://en.wikipedia.org/wiki/Differential_topology">differential topology</a>, or <a href="https://en.wikipedia.org/wiki/Stochastic_calculus">stochastic calculus</a>, intuitive, but that's not the kind of mathematics I have in mind. </p> <p> Basic arithmetic is intuitive. You know: <em>1 + 3 = 4</em>, or <em>3 * 4 = 12</em>. In fact, it's <em>so intuitive</em> that you can't formally prove it -without <a href="https://en.wikipedia.org/wiki/Axiom">axioms</a>, that is. <a href="https://en.wikipedia.org/wiki/Peano_axioms">These axioms</a> are unprovable; you must take them at face value, but you'll readily do that because they're <em>so intuitive</em>. </p> <p> Mathematics is a big structure, but it's all based on intuitive axioms. Mathematics is intuitive. </p> <p> Writers before me have celebrated the power of mathematical abstraction in programming. For instance, in <a href="http://amzn.to/WBCwx7">Domain-Driven Design</a> Eric Evans discusses how <em>Closure of Operations</em> leads to object models reminiscent of arithmetic. If you can design <a href="https://martinfowler.com/bliki/ValueObject.html">Value Objects</a> in such a way that you can somehow 'add' them together, you have an intuitive and powerful abstraction. </p> <p> Notice that there's more than one way to combine numbers. You can add them together, but you can also multiply them. Could there be a common abstraction for that? What about objects that can somehow be combined, even if they aren't 'number-like'? The generalisation of such operations is a branch of mathematics called <a href="https://en.wikipedia.org/wiki/Category_theory">category theory</a>, and it has turned out to be productive when applied to functional programming. <a href="https://www.haskell.org">Haskell</a> is the most prominent example. </p> <p> By an interesting coincidence, the 'things' in category theory are called <em>objects</em>, and while they aren't objects in the sense that we think of in object-oriented design, there <em>is</em> some equivalence. Category theory concerns itself with how objects map to other objects. A functional programmer would interpret such <em>morphisms</em> as functions, but in a sense, you can also think of them as well-defined behaviour that's associated with data. </p> <p> The objects of category theory are universal abstractions. Some of them, it turns out, coincide with known design patterns. The difference is, however, that category theory concepts are governed by specific laws. In order to be a functor, for example, an object must obey certain simple and intuitive laws. This makes the category theory concepts more specific, and less ambiguous, than design patterns. </p> <p> The coming article series is an exploration of this space: <ul> <li><a href="http://blog.ploeh.dk/2017/10/05/monoids-semigroups-and-friends">Monoids, semigroups, and friends</a> <ul> <li><a href="http://blog.ploeh.dk/2017/10/06/monoids">Monoids</a> <ul> <li><a href="http://blog.ploeh.dk/2017/10/10/strings-lists-and-sequences-as-a-monoid">Strings, lists, and sequences as a monoid</a></li> <li><a href="http://blog.ploeh.dk/2017/10/16/money-monoid">Money monoid</a></li> <li><a href="http://blog.ploeh.dk/2017/10/23/convex-hull-monoid">Convex hull monoid</a></li> <li><a href="http://blog.ploeh.dk/2017/10/30/tuple-monoids">Tuple monoids</a></li> <li><a href="http://blog.ploeh.dk/2017/11/06/function-monoids">Function monoids</a></li> <li><a href="http://blog.ploeh.dk/2017/11/13/endomorphism-monoid">Endomorphism monoid</a></li> <li><a href="http://blog.ploeh.dk/2017/11/20/monoids-accumulate">Monoids accumulate</a></li> </ul> </li> <li><a href="http://blog.ploeh.dk/2017/11/27/semigroups">Semigroups</a> <ul> <li><a href="http://blog.ploeh.dk/2017/12/04/bounding-box-semigroup">Bounding box semigroup</a></li> <li><a href="http://blog.ploeh.dk/2017/12/11/semigroups-accumulate">Semigroups accumulate</a></li> </ul> </li> <li>Quasigroups</li> <li>Magmas <ul> <li>Rock Paper Scissors magma</li> <li>Colour-mixing magma</li> </ul> </li> </ul> </li> <li>Software design isomorphisms <ul> <li>Unit isomorphisms</li> <li>Function isomorphisms</li> <li>Argument list isomorphisms</li> <li>Uncurry isomorphisms</li> <li>Object isomorphisms</li> <li>Abstract class isomorphism</li> <li>Inheritance-composition isomorphism</li> </ul> </li> <li>From structural patterns to category theory <ul> <li>Composite as a monoid</li> <li>Coalescing Composite as a monoid</li> <li>Endomorphic Composite as a monoid</li> <li>Null Object as identity</li> </ul> </li> </ul> I believe that learning about these universal abstractions is the next step in software design. If you know design patterns, you have a vocabulary, but the details are still open to interpretation. If you know category theory, you have a better vocabulary. Just like design patterns, you have to learn these things, but once you've learned them, you've learned something that transcends a particular software library, a particular framework, a particular programming language. Learning about functors, monoids, and so on, is a good investment, because these concepts are rooted in mathematics, not any particular technology. </p> <p> <strong>Motivation</strong> </p> <p> The purpose of this article series is two-fold. Depending on your needs and interests, you can use it to <ul> <li>learn better abstractions</li> <li>learn how functional programming is a real alternative to object-oriented programming</li> </ul> You've already read how it's in your interest to learn universal abstractions. It'll make your code clearer, more concise, and you'll have a better software design vocabulary. </p> <p> The other goal of these articles may be less clear. Object-oriented programming (OOP) is the dominant software design <a href="https://en.wikipedia.org/wiki/Paradigm">paradigm</a>. It wasn't always so. When OOP was new, many veteran programmers couldn't see how it could be useful. They were schooled in one paradigm, and it was difficult for them to shift to the new paradigm. They were used to do things in one way (typically, procedural), and it wasn't clear how to achieve the same goals with idiomatic object-oriented design. </p> <p> The same sort of resistance applies to functional programming. Tasks that are easy in OOP seem impossible in functional programming. How do you make a <em>for</em> loop? How do you change state? How do you break out of a routine? </p> <p> This leads to both frustration, and dismissal of functional programming, which is still seen as either academic, or something only interesting in computation-heavy domains like science or finance. </p> <p> It's my secondary goal with these articles to show that: <ol> <li>There are clear equivalences between known design patterns and concepts from category theory</li> <li>Thus, functional programming is as universally useful as OOP</li> <li>Since equivalences exist, there's a learning path</li> </ol> If you're an object-oriented programmer, you can use this catalogue as a learning path. If you'd normally use a <a href="https://en.wikipedia.org/wiki/Composite_pattern">Composite</a>, you can look it up and realise that it's the same as a monoid. </p> <p> <strong>Work in progress</strong> </p> <p> I've been thinking about these topics for years. What's a good abstraction? When do abstractions compose? </p> <p> My <a href="http://blog.ploeh.dk/2010/12/03/Towardsbetterabstractions">first attempt at answering these questions</a> was in 2010, but while I had the experience that certain abstractions composed better than others, I lacked the vocabulary. I've been wanting to write a better treatment of the topic ever since, but I've been constantly learning as I've grappled with the concepts. </p> <p> I believe that I now have the vocabulary to take a stab at this again. This is hardly the ultimate treatment. A year from now, I hope to have learned even more, and perhaps that'll lead to further insights or refinement. Still, I can't postpone writing this article until I've stopped learning, because at that time I'll either be dead or senile. </p> <p> I'll write these articles in an authoritative voice, because a text that constantly moderates and qualifies its assertions easily becomes unreadable. Don't consider the tone an indication that I'm certain that I'm right. I've tried to be as rigorous in my arguments as I could, but I don't have a formal education in computer science. I welcome feedback on any article, both if it's to corroborate my findings, or if it's to refute them. If you have any sort of feedback, then <a href="https://github.com/ploeh/ploeh.github.com#readme">please leave a comment</a>. </p> <p> I consider the publication of these articles as though I submit them to peer review. If you can refute them, they deserve to be refuted. If not, they just may be valuable to other people. </p> <p> <strong>Summary</strong> </p> <p> Category theory generalises some intuitive relations, such as how numbers combine (e.g. via addition or multiplication). Instead of discussing numbers, however, category theory considers abstract 'objects'. This field of mathematics explore how object relate and compose. </p> <p> Some category theory concepts can be translated to code. These universal abstractions can form the basis of a powerful and concise software design vocabulary. </p> <p> The design patterns movement was an early attempt to create such a vocabulary. I think using category theory offers the chance of a better vocabulary, but fortunately, all the work that went into design patterns isn't wasted. It seems to me that some design patterns are essentially ad-hoc, informally specified, specialised instances of basic category theory concepts. There's quite a bit of overlap. This should further strengthen the argument that category theory is valuable in programming, because some of the concepts are equivalent to design patterns that have already proven useful. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/10/05/monoids-semigroups-and-friends">Monoids, semigroups, and friends</a>. </p> </div> <div id="comments"> <hr /> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"> <a href="https://hettomei.github.io/">Tim</a> </div> <div class="comment-content"> <p>What a perfect introduction !</p> <p>I heard about category theory more than one year ago. But it was from a PhD who code in 'haskell' and I thought it was too hard for me to understand.</p> <p>And then, this post.</p> <p>Thank you a lot! (you aleardy published the follow up ! yeah)</p> </div> <div class="comment-date">2017-10-05 21:39 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Interception vis-à-vis Pure DI http://blog.ploeh.dk/2017/09/25/interception-vis-a-vis-pure-di 2017-09-25T07:27:00+00:00 Mark Seemann <div id="post"> <p> <em>How do you do AOP with Pure DI?</em> </p> <p> One of my readers, Nick Ball, asks me this question: </p> <blockquote> <p> "Just spent the last couple of hours reading chapter 9 of your book about Interceptors. The final few pages show how to use Castle Windsor to make the code DRYer. That's cool, but I'm quite a fan of Pure DI as I tend to think it keeps things simpler. Plus I'm working in a legacy C++ application which limits the tooling available to me. </p> <p> "So, I was wondering if you had any suggestions on how to DRY up an interceptor in Pure DI? I know in your book you state that this is where DI containers come into their own, but I also know through reading your blog that you prefer going the Pure DI route too. Hence I wondered whether you'd had any further insight since the book publication?" </p> </blockquote> <p> It's been more than 15 years since I last did C++, so I'm going to give an answer based on C#, and hope it translates. </p> <p> <strong>Position</strong> </p> <p> I do, indeed, prefer <a href="http://blog.ploeh.dk/2014/06/10/pure-di">Pure DI</a>, but there may be <a href="http://blog.ploeh.dk/2012/11/06/WhentouseaDIContainer">cases where a DI Container is warranted</a>. Interception, or Aspect-Oriented Programming (AOP), is one such case, but obviously that doesn't help if you can't use a DI Container. </p> <p> Another option for AOP is some sort of post-processor of your code. As I briefly cover in chapter 9 of <a href="http://amzn.to/12p90MG">my book</a>, in .NET this is typically done by a custom tool using 'IL-weaving'. As I also outline in the book, I'm not a big fan of this approach, but perhaps that could be an option in C++ as well. In any case, I'll proceed under the assumption that you want a strictly code-based solution, involving no custom tools or build steps. </p> <p> All that said, I doubt that this is as much of a problem than one would think. AOP is typically used for cross-cutting concerns such as logging, caching, instrumentation, authorization, metering, or auditing. As an alternative, you can also <a href="http://blog.ploeh.dk/2010/04/07/DependencyInjectionisLooseCoupling">use Decorators for such cross-cutting concerns</a>. This seems daunting if you truly need to decorate hundreds, or even thousands, of classes. In such a case, convention-based interception seems like a <a href="https://en.wikipedia.org/wiki/Don%27t_repeat_yourself">DRY</a>er option. </p> <p> You'd think. </p> <p> In my experience, however, this is rarely the case. Typically, even when applying caching, logging, or authorisation logic, I've only had to create a handful of <a href="https://en.wikipedia.org/wiki/Decorator_pattern">Decorators</a>. Perhaps it's because I tend to keep my code bases to a manageable size. </p> <p> If you only need a dozen Decorators, I don't think that the loss of compile-time safety and the added dependency warrants the use of a DI Container. That doesn't mean, however, that I can't aim for as DRY code as possible. </p> <p> <strong>Instrument</strong> </p> <p> If you don't have a DI Container or an AOP tool, I believe that a Decorator is the best way to address cross-cutting concerns, and I don't think there's any way around adding those Decorator classes. The aim, then, becomes to minimise the effort involved in creating and maintaining such classes. </p> <p> As an example, I'll revisit <a href="http://blog.ploeh.dk/2010/09/20/InstrumentationwithDecoratorsandInterceptors">an old blog post</a>. In that post, the task was to instrument an <code>OrderProcessor</code> class. The solution shown in that article was to use <a href="http://www.castleproject.org/projects/windsor">Castle Windsor</a> to define an <code>IInterceptor</code>. </p> <p> To recapitulate, the code for the Interceptor looks like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">InstrumentingInterceptor</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IInterceptor</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">IRegistrar</span>&nbsp;registrar; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;InstrumentingInterceptor(<span style="color:#2b91af;">IRegistrar</span>&nbsp;registrar) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(registrar&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(registrar)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.registrar&nbsp;=&nbsp;registrar; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;Intercept(<span style="color:#2b91af;">IInvocation</span>&nbsp;invocation) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;correlationId&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.NewGuid(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.registrar.Register(correlationId, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>.Format(<span style="color:#a31515;">&quot;{0}&nbsp;begins&nbsp;({1})&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;invocation.Method.Name, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;invocation.TargetType.Name)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;invocation.Proceed(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.registrar.Register(correlationId, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>.Format(<span style="color:#a31515;">&quot;{0}&nbsp;ends&nbsp;&nbsp;&nbsp;({1})&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;invocation.Method.Name, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;invocation.TargetType.Name)); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> While, in the new scenario, you can't use Castle Windsor, you can still take the code and make a similar class out of it. Call it <code>Instrument</code>, because classes should have noun names, and <em>instrument</em> is a noun (right?). </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Instrument</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">IRegistrar</span>&nbsp;registrar; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;Instrument(<span style="color:#2b91af;">IRegistrar</span>&nbsp;registrar) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(registrar&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(registrar)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.registrar&nbsp;=&nbsp;registrar; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">T</span>&nbsp;Intercept&lt;<span style="color:#2b91af;">T</span>&gt;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;methodName, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;typeName, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;proceed) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;correlationId&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.NewGuid(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.registrar.Register( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;correlationId, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>.Format(<span style="color:#a31515;">&quot;{0}&nbsp;begins&nbsp;({1})&quot;</span>,&nbsp;methodName,&nbsp;typeName)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;result&nbsp;=&nbsp;proceed(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.registrar.Register( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;correlationId, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>.Format(<span style="color:#a31515;">&quot;{0}&nbsp;ends&nbsp;&nbsp;&nbsp;({1})&quot;</span>,&nbsp;methodName,&nbsp;typeName)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;result; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;Intercept( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;methodName, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;typeName, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Action</span>&nbsp;proceed) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;correlationId&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.NewGuid(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.registrar.Register( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;correlationId, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>.Format(<span style="color:#a31515;">&quot;{0}&nbsp;begins&nbsp;({1})&quot;</span>,&nbsp;methodName,&nbsp;typeName)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;proceed(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.registrar.Register( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;correlationId, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>.Format(<span style="color:#a31515;">&quot;{0}&nbsp;ends&nbsp;&nbsp;&nbsp;({1})&quot;</span>,&nbsp;methodName,&nbsp;typeName)); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> Instead of a single <code>Intercept</code> method, the <code>Instrument</code> class exposes two <code>Intercept</code> overloads; one for methods without a return value, and one for methods that return a value. Instead of an <code>IInvocation</code> argument, the overload for methods without a return value takes an <a href="https://msdn.microsoft.com/en-us/library/system.action">Action</a> delegate, whereas the other overload takes a <a href="https://msdn.microsoft.com/en-us/library/bb534960">Func&lt;T&gt;</a>. </p> <p> Both overload also take <code>methodName</code> and <code>typeName</code> arguments. </p> <p> Most of the code in the two methods is similar. While you could refactor to a <a href="https://en.wikipedia.org/wiki/Template_method_pattern">Template Method</a>, I invoke the <a href="https://en.wikipedia.org/wiki/Rule_of_three_(computer_programming)">Rule of three</a> and let the duplication stay for now. </p> <p> <strong>Decorators</strong> </p> <p> The <code>Instrument</code> class isn't going to magically create Decorators for you, but it reduces the effort of creating one: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">InstrumentedOrderProcessor2</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IOrderProcessor</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">IOrderProcessor</span>&nbsp;orderProcessor; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Instrument</span>&nbsp;instrument; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;InstrumentedOrderProcessor2( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IOrderProcessor</span>&nbsp;orderProcessor, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Instrument</span>&nbsp;instrument) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(orderProcessor&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(orderProcessor)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(instrument&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(instrument)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.orderProcessor&nbsp;=&nbsp;orderProcessor; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.instrument&nbsp;=&nbsp;instrument; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">SuccessResult</span>&nbsp;Process(<span style="color:#2b91af;">Order</span>&nbsp;order) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.instrument.Intercept( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">nameof</span>(Process), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.orderProcessor.GetType().Name, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;()&nbsp;=&gt;&nbsp;<span style="color:blue;">this</span>.orderProcessor.Process(order)); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> I called this class <code>InstrumentedOrderProcessor2</code> with the <code>2</code> postfix because the previous article already contains a <code>InstrumentedOrderProcessor</code> class, and I wanted to make it clear that this is a new class. </p> <p> Notice that <code>InstrumentedOrderProcessor2</code> is a Decorator of <code>IOrderProcessor</code>. It both implements the interface, and takes one as a dependency. It also takes an <code>Instrument</code> object as a <a href="http://blog.ploeh.dk/2012/08/31/ConcreteDependencies">Concrete Dependency</a>. This is mostly to enable reuse of a single <code>Instrument</code> object; no polymorphism is implied. </p> <p> The decorated <code>Process</code> method simply delegates to the <code>instrument</code>'s <code>Intercept</code> method, passing as parameters the name of the method, the name of the decorated class, and a lambda expression that closes over the outer <code>order</code> method argument. </p> <p> For simplicity's sake, the <code>Process</code> method invokes <code>this.orderProcessor.GetType().Name</code> every time it's called, which may not be efficient. Since the <code>orderProcessor</code> class field is <code>readonly</code>, though, you could optimise this by getting the name once and for all in the constructor, and assign the string to a third class field. I didn't want to complicate the example with irrelevant code, though. </p> <p> Here's another Decorator: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">InstrumentedOrderShipper</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IOrderShipper</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">IOrderShipper</span>&nbsp;orderShipper; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Instrument</span>&nbsp;instrument; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;InstrumentedOrderShipper( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IOrderShipper</span>&nbsp;orderShipper, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Instrument</span>&nbsp;instrument) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(orderShipper&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(orderShipper)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(instrument&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(instrument)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.orderShipper&nbsp;=&nbsp;orderShipper; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.instrument&nbsp;=&nbsp;instrument; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;Ship(<span style="color:#2b91af;">Order</span>&nbsp;order) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.instrument.Intercept( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">nameof</span>(Ship), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.orderShipper.GetType().Name, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;()&nbsp;=&gt;&nbsp;<span style="color:blue;">this</span>.orderShipper.Ship(order)); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> As you can tell, it's similar to <code>InstrumentedOrderProcessor2</code>, but instead of <code>IOrderProcessor</code> it decorates <code>IOrderShipper</code>. The most significant difference is that the <code>Ship</code> method doesn't return any value, so you have to use the <code>Action</code>-based overload of <code>Intercept</code>. </p> <p> For completeness sake, here's a third interesting example: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">InstrumentedUserContext</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IUserContext</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">IUserContext</span>&nbsp;userContext; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Instrument</span>&nbsp;instrument; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;InstrumentedUserContext( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IUserContext</span>&nbsp;userContext, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Instrument</span>&nbsp;instrument) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(userContext&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(userContext)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(instrument&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(instrument)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.userContext&nbsp;=&nbsp;userContext; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.instrument&nbsp;=&nbsp;instrument; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">User</span>&nbsp;GetCurrentUser() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.instrument.Intercept( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">nameof</span>(GetCurrentUser), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.userContext.GetType().Name, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.userContext.GetCurrentUser); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Currency</span>&nbsp;GetSelectedCurrency(<span style="color:#2b91af;">User</span>&nbsp;currentUser) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.instrument.Intercept( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">nameof</span>(GetSelectedCurrency), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.userContext.GetType().Name, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;()&nbsp;=&gt;&nbsp;<span style="color:blue;">this</span>.userContext.GetSelectedCurrency(currentUser)); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> This example demonstrates that you can also decorate an interface that defines more than a single method. The <code>IUserContext</code> interface defines both <code>GetCurrentUser</code> and <code>GetSelectedCurrency</code>. The <code>GetCurrentUser</code> method takes no arguments, so instead of a lambda expression, you can pass the delegate using method group syntax. </p> <p> <strong>Composition</strong> </p> <p> You can add such instrumenting Decorators for all appropriate interfaces. It's trivial (and automatable) work, but it's easy to do. While it seems repetitive, I can't come up with a more DRY way to do it without resorting to some sort of run-time Interception or AOP tool. </p> <p> There's some repetitive code, but I don't think that the maintenance overhead is particularly great. The Decorators do minimal work, so it's unlikely that there are many defects in that area of your code base. If you need to change the instrumentation implementation in itself, the <code>Instrument</code> class has that (single) responsibility. </p> <p> Assuming that you've added all desired Decorators, you can use Pure DI to compose an object graph: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;instrument&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Instrument</span>(registrar); <span style="color:blue;">var</span>&nbsp;sut&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InstrumentedOrderProcessor2</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">OrderProcessor</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InstrumentedOrderValidator</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">TrueOrderValidator</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;instrument), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InstrumentedOrderShipper</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">OrderShipper</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;instrument), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InstrumentedOrderCollector</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">OrderCollector</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InstrumentedAccountsReceivable</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AccountsReceivable</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;instrument), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InstrumentedRateExchange</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">RateExchange</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;instrument), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InstrumentedUserContext</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">UserContext</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;instrument)), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;instrument)), &nbsp;&nbsp;&nbsp;&nbsp;instrument);</pre> </p> <p> This code fragment is from a unit test, which explains why the object is called <code>sut</code>. In case you're wondering, this is also the reason for the existence of the curiously named class <code>TrueOrderValidator</code>. This is a test-specific <a href="http://xunitpatterns.com/Test%20Stub.html">Stub</a> of <code>IOrderValidator</code> that always returns <code>true</code>. </p> <p> As you can see, each leaf implementation of an interface is contained within an <code>InstrumentedXyz</code> Decorator, which also takes a shared <code>instrument</code> object. </p> <p> When I call the <code>sut</code>'s <code>Process</code> method with a proper <code>Order</code> object, I get output like this: </p> <p> <pre>4ad34380-6826-440c-8d81-64bbd1f36d39 2017-08-25T17:49:18.43 Process begins (OrderProcessor) c85886a7-1ce8-4096-8a30-5f87bf0014e3 2017-08-25T17:49:18.52 Validate begins (TrueOrderValidator) c85886a7-1ce8-4096-8a30-5f87bf0014e3 2017-08-25T17:49:18.52 Validate ends (TrueOrderValidator) 8f7606b6-f3f7-4231-808d-d5e37f1f2201 2017-08-25T17:49:18.53 Collect begins (OrderCollector) 28250a92-6024-439e-b010-f66c63903673 2017-08-25T17:49:18.55 GetCurrentUser begins (UserContext) 28250a92-6024-439e-b010-f66c63903673 2017-08-25T17:49:18.56 GetCurrentUser ends (UserContext) 294ce552-201f-41d2-b7fc-291e2d3720d6 2017-08-25T17:49:18.56 GetCurrentUser begins (UserContext) 294ce552-201f-41d2-b7fc-291e2d3720d6 2017-08-25T17:49:18.56 GetCurrentUser ends (UserContext) 96ee96f0-4b95-4b17-9993-33fa87972013 2017-08-25T17:49:18.57 GetSelectedCurrency begins (UserContext) 96ee96f0-4b95-4b17-9993-33fa87972013 2017-08-25T17:49:18.58 GetSelectedCurrency ends (UserContext) 3af884e5-8e97-44ea-aa0d-2c9e0418110b 2017-08-25T17:49:18.59 Convert begins (RateExchange) 3af884e5-8e97-44ea-aa0d-2c9e0418110b 2017-08-25T17:49:18.59 Convert ends (RateExchange) b8bd0701-515b-44fe-949f-5f5fb5a4590d 2017-08-25T17:49:18.60 Collect begins (AccountsReceivable) b8bd0701-515b-44fe-949f-5f5fb5a4590d 2017-08-25T17:49:18.60 Collect ends (AccountsReceivable) 8f7606b6-f3f7-4231-808d-d5e37f1f2201 2017-08-25T17:49:18.60 Collect ends (OrderCollector) beadabc4-df17-468f-8553-34ae4e3bdbfc 2017-08-25T17:49:18.60 Ship begins (OrderShipper) beadabc4-df17-468f-8553-34ae4e3bdbfc 2017-08-25T17:49:18.61 Ship ends (OrderShipper) 4ad34380-6826-440c-8d81-64bbd1f36d39 2017-08-25T17:49:18.61 Process ends (OrderProcessor)</pre> </p> <p> This is similar to the output from the previous article. </p> <p> <strong>Summary</strong> </p> <p> When writing object-oriented code, I still prefer Pure DI over using a DI Container, but if I absolutely needed to decorate many services, I'd seriously consider using a DI Container with run-time Interception capabilities. The need rarely materialises, though. </p> <p> As an intermediate solution, you can use a delegation-based design like the one shown here. As always, it's all a matter of balancing the constraints and goals of the specific situation. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. The Test Data Generator functor http://blog.ploeh.dk/2017/09/18/the-test-data-generator-functor 2017-09-18T07:55:00+00:00 Mark Seemann <div id="post"> <p> <em>A Test Data Generator modelled as a functor.</em> </p> <p> In a <a href="http://blog.ploeh.dk/2017/08/14/from-test-data-builders-to-the-identity-functor">previous article series</a>, you learned that while it's possible to model <a href="http://www.natpryce.com/articles/000714.html">Test Data Builders</a> as a functor, it adds little value. You shouldn't, however, dismiss the value of functors. It's an abstraction that applies broadly. </p> <p> Closely related to Test Data Builders is the concept of a generator of random test data. You could call it a Test Data Generator instead. Such a generator can be modelled as a functor. </p> <p> <strong>A C# Generator</strong> </p> <p> At its core, the idea behind a Test Data Generator is to create random test data. Still, you'll like to be able control various parts of the process, because you'd often need to pin parts of the generated data to deterministic values, while allowing other parts to vary randomly. </p> <p> In C#, you can write a generic Generator like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Generator</span>&lt;<span style="color:#2b91af;">T</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">Random</span>,&nbsp;<span style="color:#2b91af;">T</span>&gt;&nbsp;generate; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;Generator(<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">Random</span>,&nbsp;<span style="color:#2b91af;">T</span>&gt;&nbsp;generate) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(generate&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(generate)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.generate&nbsp;=&nbsp;generate; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Generator</span>&lt;<span style="color:#2b91af;">T1</span>&gt;&nbsp;Select&lt;<span style="color:#2b91af;">T1</span>&gt;(<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">T</span>,&nbsp;<span style="color:#2b91af;">T1</span>&gt;&nbsp;f) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(f&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(f)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">Random</span>,&nbsp;<span style="color:#2b91af;">T1</span>&gt;&nbsp;newGenerator&nbsp;=&nbsp;r&nbsp;=&gt;&nbsp;f(<span style="color:blue;">this</span>.generate(r)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Generator</span>&lt;<span style="color:#2b91af;">T1</span>&gt;(newGenerator); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">T</span>&nbsp;Generate(<span style="color:#2b91af;">Random</span>&nbsp;random) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(random&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(random)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.generate(random); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> The <code>Generate</code> method takes a <code>Random</code> object as input, and produces a value of the generic type <code>T</code> as output. This enables you to deterministically reproduce a particular randomly generated value, if you know the seed of the <code>Random</code> object. </p> <p> Notice how <code>Generator&lt;T&gt;</code> is a simple <a href="https://en.wikipedia.org/wiki/Adapter_pattern">Adapter</a> over a (lazily evaluated) function. This function also takes a <code>Random</code> object as input, and produces a <code>T</code> value as output. (For the FP enthusiasts, this is simply the <em>Reader functor</em> in disguise.) </p> <p> The <code>Select</code> method makes <code>Generator&lt;T&gt;</code> a functor. It takes a map function <code>f</code> as input, and uses it to define a new <code>generate</code> function. The return value is a <code>Generator&lt;T1&gt;</code>. </p> <p> <strong>General-purpose building blocks</strong> </p> <p> Functors are immanently composable. You can compose complex Test Data Generators from simpler building blocks, like the following. </p> <p> For instance, you may need a generator of alphanumeric strings. You can write it like this: </p> <p> <pre><span style="color:blue;">private</span>&nbsp;<span style="color:blue;">const</span>&nbsp;<span style="color:blue;">string</span>&nbsp;alphaNumericCharacters&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ&quot;</span>; <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Generator</span>&lt;<span style="color:blue;">string</span>&gt;&nbsp;AlphaNumericString&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Generator</span>&lt;<span style="color:blue;">string</span>&gt;(r&nbsp;=&gt; &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;length&nbsp;=&nbsp;r.Next(25);&nbsp;<span style="color:green;">//&nbsp;Arbitrarily&nbsp;chosen&nbsp;max&nbsp;length</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;chars&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:blue;">char</span>[length]; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">for</span>&nbsp;(<span style="color:blue;">int</span>&nbsp;i&nbsp;=&nbsp;0;&nbsp;i&nbsp;&lt;&nbsp;length;&nbsp;i++) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;idx&nbsp;=&nbsp;r.Next(alphaNumericCharacters.Length); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;chars[i]&nbsp;=&nbsp;alphaNumericCharacters[idx]; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:blue;">string</span>(chars); &nbsp;&nbsp;&nbsp;&nbsp;});</pre> </p> <p> This <code>Generator&lt;string&gt;</code> can generate a random string with alphanumeric characters. It randomly picks a length between 0 and 24, and fills it with randomly selected alphanumeric characters. The maximum length of 24 is arbitrarily chosen. The generated string may be empty. </p> <p> Notice that the argument passed to the constructor is a function. It's not evaluated at initialisation, but only if <code>Generate</code> is called. </p> <p> The <code>r</code> argument is the <code>Random</code> object passed to <code>Generate</code>. </p> <p> Another useful general-purpose building block is a generator that can use a single-object generator to create many objects: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Generator</span>&lt;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">T</span>&gt;&gt;&nbsp;Many&lt;<span style="color:#2b91af;">T</span>&gt;(<span style="color:#2b91af;">Generator</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;generator) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Generator</span>&lt;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">T</span>&gt;&gt;(r&nbsp;=&gt; &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;length&nbsp;=&nbsp;r.Next(25);&nbsp;<span style="color:green;">//&nbsp;Arbitrarily&nbsp;chosen&nbsp;max&nbsp;length</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;elements&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">List</span>&lt;<span style="color:#2b91af;">T</span>&gt;(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">for</span>&nbsp;(<span style="color:blue;">int</span>&nbsp;i&nbsp;=&nbsp;0;&nbsp;i&nbsp;&lt;&nbsp;length;&nbsp;i++) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;elements.Add(generator.Generate(r)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;elements; &nbsp;&nbsp;&nbsp;&nbsp;}); }</pre> </p> <p> This method takes a <code>Generator&lt;T&gt;</code> as input, and uses it to generate zero or more <code>T</code> objects. Again, the maximum length of 24 is arbitrarily chosen. It could have been a method argument, but in order to keep the example simple, I hard-coded it. </p> <p> <strong>Domain-specific generators</strong> </p> <p> From such general-purpose building blocks, you can define custom generators for your domain model. This enables you to use such generators in your unit tests. </p> <p> In order to generate post codes, you can combine the <code>AlphaNumericString</code> and the <code>Many</code> generators: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Generator</span>&lt;<span style="color:#2b91af;">PostCode</span>&gt;&nbsp;PostCode&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Generator</span>&lt;<span style="color:#2b91af;">PostCode</span>&gt;(r&nbsp;=&gt;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;postCodes&nbsp;=&nbsp;Many(AlphaNumericString).Generate(r); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PostCode</span>(postCodes.ToArray()); &nbsp;&nbsp;&nbsp;&nbsp;});</pre> </p> <p> The <code>PostCode</code> class is part of your domain model; it takes an array of strings as input to its constructor. The <code>PostCode</code> generator uses the <code>AlphaNumericString</code> generator as input to the <code>Many</code> method. This generates zero or many alphanumeric strings, which you can pass to the <code>PostCode</code> constructor. </p> <p> This, in turn, gives you all the building blocks you need to generate <code>Address</code> objects: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Generator</span>&lt;<span style="color:#2b91af;">Address</span>&gt;&nbsp;Address&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Generator</span>&lt;<span style="color:#2b91af;">Address</span>&gt;(r&nbsp;=&gt; &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;street&nbsp;=&nbsp;AlphaNumericString.Generate(r); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;city&nbsp;=&nbsp;AlphaNumericString.Generate(r); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;postCode&nbsp;=&nbsp;PostCode.Generate(r); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(street,&nbsp;city,&nbsp;postCode); &nbsp;&nbsp;&nbsp;&nbsp;});</pre> </p> <p> This <code>Generator&lt;Address&gt;</code> uses the <code>AlphaNumericString</code> generator to generate street and city strings. It uses the <code>PostCode</code> generator to generate a <code>PostCode</code> object. All these objects are passed to the <code>Address</code> constructor. </p> <p> Keep in mind that all of this logic is defined in lazily evaluated functions. Only when you invoke the <code>Generate</code> method on a generator does the code execute. </p> <p> <strong>Generating values</strong> </p> <p> You can now write tests similar to the tests shown in the the <a href="http://blog.ploeh.dk/2017/08/14/from-test-data-builders-to-the-identity-functor">article series about Test Data Builders</a>. If, for example, you need an address in Paris, you can generate it like this: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;rnd&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Random</span>(); <span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;<span style="color:#2b91af;">Gen</span>.Address.Select(a&nbsp;=&gt;&nbsp;a.WithCity(<span style="color:#a31515;">&quot;Paris&quot;</span>)).Generate(rnd);</pre> </p> <p> <code>Gen.Address</code> is the <code>Address</code> generator shown above; I put all those generators in a static class called <code>Gen</code>. If you don't modify it, <code>Gen.Address</code> will generate a random <code>Address</code> object, but by using <code>Select</code>, you can pin the city to Paris. </p> <p> You can also start with one type of generator and use <code>Select</code> to map to another type of generator, like this: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;rnd&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Random</span>(); <span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;<span style="color:#2b91af;">Gen</span>.PostCode &nbsp;&nbsp;&nbsp;&nbsp;.Select(pc&nbsp;=&gt;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:#a31515;">&quot;Rue&nbsp;Morgue&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>,&nbsp;pc)) &nbsp;&nbsp;&nbsp;&nbsp;.Generate(rnd);</pre> </p> <p> You use <code>Gen.PostCode</code> as the initial generator, and then <code>Select</code> a new <code>Address</code> in Rue Morgue, Paris, with a randomly generated post code. </p> <p> <strong>Functor</strong> </p> <p> Such a Test Data Generator is a functor. One way to see that is to use query syntax instead of the <a href="https://en.wikipedia.org/wiki/Fluent_interface">fluent API</a>: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;rnd&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Random</span>(); <span style="color:blue;">var</span>&nbsp;address&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:blue;">from</span>&nbsp;a&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Gen</span>.Address&nbsp;<span style="color:blue;">select</span>&nbsp;a.WithCity(<span style="color:#a31515;">&quot;Paris&quot;</span>)).Generate(rnd);</pre> </p> <p> Likewise, you can also translate the Rue Morgue generator to query syntax: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">from</span>&nbsp;pc&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Gen</span>.PostCode &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">select</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:#a31515;">&quot;Rue&nbsp;Morgue&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>,&nbsp;pc)).Generate(rnd);</pre> </p> <p> This is, however, awkward, because you have to enclose the query expression in brackets in order to be able to invoke the <code>Generate</code> method. Alternatively, you can separate the query from the generation, like this: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;g&nbsp;=&nbsp;<span style="color:blue;">from</span>&nbsp;a&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Gen</span>.Address&nbsp;<span style="color:blue;">select</span>&nbsp;a.WithCity(<span style="color:#a31515;">&quot;Paris&quot;</span>); <span style="color:blue;">var</span>&nbsp;rnd&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Random</span>(); <span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;g.Generate(rnd);</pre> </p> <p> Or this: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;g&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">from</span>&nbsp;pc&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Gen</span>.PostCode &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">select</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:#a31515;">&quot;Rue&nbsp;Morgue&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>,&nbsp;pc); <span style="color:blue;">var</span>&nbsp;rnd&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Random</span>(); <span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;g.Generate(rnd);</pre> </p> <p> You'd probably still prefer the fluent API over this syntax. The reason I show this alternative is to demonstrate that the functor gives you the ability to separate the definition of data generation from the actual generation. In order to emphasise this point, I defined the <code>g</code> variables <em>before</em> creating the <code>Random</code> object <code>rnd</code>. </p> <p> <strong>Property-based testing</strong> </p> <p> The above <code>Generator&lt;T&gt;</code> is only a crude example of a Test Data Generator. In order to demonstrate how such a generator is a functor, I left out several useful features. Still, this should have given you a sense for how the <code>Generator&lt;T&gt;</code> class itself, as well as such general-purpose building blocks as <code>Many</code> and <code>AlphaNumericString</code>, could be packaged in a reusable library. </p> <p> The examples above show how to use a generator to create a single random object. You could, however, easily generate many (say, 100) random objects, and run unit tests for each object created. This is the idea behind property-based testing. </p> <p> There's more to property-based testing than generation of random values, but the implementations I've seen are all based on Test Data Generators as functors (and monads). </p> <p> <strong>FsCheck</strong> </p> <p> <a href="https://fscheck.github.io/FsCheck">FsCheck</a> is an open source F# library for property-based testing. It defines a <code>Gen</code> functor (and monad) that you can use to generate <code>Address</code> values, just like the above examples: </p> <p> <pre><span style="color:blue;">let!</span>&nbsp;address&nbsp;=&nbsp;<span style="color:teal;">Gen</span>.address&nbsp;|&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">map</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;{&nbsp;a&nbsp;<span style="color:blue;">with</span>&nbsp;City&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>}&nbsp;) </pre> </p> <p> Here, <code>Gen.address</code> is a <code>Gen&lt;Address&gt;</code> value. By itself, it'll generate random <code>Address</code> values, but by using <code>Gen.map</code>, you can pin the city to Paris. </p> <p> The <code>map</code> function corresponds to the C# <code>Select</code> method. In functional programming, <em>map</em> is the most common name, although Haskell calls the function <code>fmap</code>; the <code>Select</code> name is, in fact, the odd man out. </p> <p> Likewise, you can map from one generator type to another: </p> <p> <pre><span style="color:blue;">let!</span>&nbsp;address&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Gen</span>.postCode &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">map</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;pc&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;Street&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Rue&nbsp;Morgue&quot;</span>;&nbsp;City&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>;&nbsp;PostCode&nbsp;=&nbsp;pc&nbsp;})</pre> </p> <p> This example uses <code>Gen.postCode</code> as the initial generator. This is, as the name implies, a <code>Gen&lt;PostCode&gt;</code> value. For every random <code>PostCode</code> value generated, <code>map</code> turns it into an address in Rue Morgue, Paris. </p> <p> There's more going on here than I'd like to cover in this article. The use of <code>let!</code> syntax actually requires <code>Gen&lt;'a&gt;</code> to be a monad (which it is), but that's a topic for another day. Both of these examples are contained in a computation expression, and the implication of that is that the <code>address</code> values represent a multitude of randomly generated <code>Address</code> values. </p> <p> <strong>Hedgehog</strong> </p> <p> <a href="https://github.com/hedgehogqa/fsharp-hedgehog">Hedgehog</a> is another open source F# library for property-based testing. With Hedgehog, the <code>Address</code> code examples look like this: </p> <p> <pre><span style="color:blue;">let!</span>&nbsp;address&nbsp;=&nbsp;<span style="color:teal;">Gen</span>.address&nbsp;|&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">map</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;{&nbsp;a&nbsp;<span style="color:blue;">with</span>&nbsp;City&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>}&nbsp;) </pre> </p> <p> And: </p> <p> <pre><span style="color:blue;">let!</span>&nbsp;address&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Gen</span>.postCode &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">map</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;pc&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;Street&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Rue&nbsp;Morgue&quot;</span>;&nbsp;City&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>;&nbsp;PostCode&nbsp;=&nbsp;pc&nbsp;})</pre> </p> <p> Did you notice something? </p> <p> This is <em>literally</em> the same syntax as FsCheck! This isn't because Hedgehog is copying FsCheck, but because both are based on the same underlying abstraction: functor (and monad). There are other parts of the API where Hedgehog differs from FsCheck, but their generators are similar. </p> <p> This is one of the most important advantages of using well-known abstractions like functors. Once you understand such an abstraction, it's easy to learn a new library. With professional experience with FsCheck, it only took me a few minutes to figure out how to use Hedgehog. </p> <p> <strong>Summary</strong> </p> <p> Functors are well-defined objects from category theory. It may seem abstract, and far removed from 'real' programming, but it's extraordinarily useful. Many category theory abstractions can be applied to a host of different situations. Once you've learned what a functor is, you'll find it easy to learn to use new libraries that build on that abstraction. </p> <p> In this article you saw a sketch of how the functor abstraction can be used to model Test Data Generators. Contrary to Test Data Builders, which turned out to be a redundant abstraction, a Test Data Generator is truly useful. </p> <p> Many years ago, I had the idea to create a Test Data Generator for unit testing purposes. I called it <a href="https://github.com/AutoFixture/AutoFixture">AutoFixture</a>, and although it's had some success, the API isn't as clean as it could be. Back then, I didn't know about functors, so I had to invent an API for AutoFixture. This API is proprietary to AutoFixture, so anyone learning AutoFixture must learn this particular API, and its abstractions. It would have been so much easier for all involved if I had designed AutoFixture as a functor instead. </p> </div> <div id="comments"> <hr /> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"> <a href="http://www.temporalcohesion.co.uk">Stuart Grassie</a> </div> <div class="comment-content"> <p>I'm curious as to what the "useful features" are that that you left out of the Test Data Generator?</p> </div> <div class="comment-date">2017-10-23 16:36 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Stuart, thank you for writing. Test Data Generators like the one described here are rich data structures that you can do a lot of interesting things with. As described here, the generator only generates a single value every time you invoke its <code>Generate</code> method. What property-based testing libraries like <a href="https://hackage.haskell.org/package/QuickCheck">QuickCheck</a>, <a href="https://fscheck.github.io/FsCheck">FsCheck</a>, and <a href="https://github.com/hedgehogqa/fsharp-hedgehog">Hedgehog</a> do is that instead of a single random value, they generate <em>many</em> values (the default number seems to be 100). </p> <p> These property-based testing libraries tend to then 'elevate' their generators into another type of data structure called <em>Arbitraries</em>, and these again into <em>Properties</em>. What typically happens is that they use the Generators to generate values, but for each generated value, they evaluate the associated Property. If all Properties succeed, nothing more happens, but in the case of a test failure, no more values are generated. Instead, the libraries switch to a state where they attempt to <em>shrink</em> the counter-example to a simpler counter-example. It uses a <em>Shrinker</em> associated with the Arbitrary to do this. The end result is that if your test doesn't hold, you'll get an easy-to-understand example of the input that caused the test to fail. </p> <p> Apart from that, there are many other features of Test Data Generators that I left out. Some of these include ways to combine several Generators to a single Generator. It turns out that Test Data Generators are also <em>Applicative Functors</em> and <em>Monads</em>, and you can use these traits to define powerful combinators. In the future, I'll publish more articles on this topic, but it'll take months, because my article queue has quite a few other articles in front of those. </p> <p> If you want to explore this topic, I'd recommend playing with FsCheck. While it's written in F#, it also works from C#, and its documentation includes C# examples as well. Hedgehog may also work from C#, but being a newer, more experimental library, its documentation is still sparse. </p> </div> <div class="comment-date">2017-10-24 7:53 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Test data without Builders http://blog.ploeh.dk/2017/09/11/test-data-without-builders 2017-09-11T07:28:00+00:00 Mark Seemann <div id="post"> <p> <em>We don't need no steenkin' Test Data Builders!</em> </p> <p> This is the fifth and final in <a href="http://blog.ploeh.dk/2017/08/14/from-test-data-builders-to-the-identity-functor">a series of articles about the relationship between the Test Data Builder design pattern, and the identity functor</a>. In the <a href="http://blog.ploeh.dk/2017/09/04/builder-as-identity">previous article</a>, you learned why a Builder functor adds little value. In this article, you'll see what to do instead. </p> <p> <strong>From Identity to naked values</strong> </p> <p> While you can define <a href="http://www.natpryce.com/articles/000714.html">Test Data Builders</a> with Haskell's <code>Identity</code> functor, it adds little value: </p> <p> <pre><span style="color:#dd0000;">Identity</span>&nbsp;address&nbsp;<span style="color:#666666;">=</span>&nbsp;fmap&nbsp;(<span style="color:#666666;">\</span>a&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;a&nbsp;{&nbsp;city&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>&nbsp;})&nbsp;addressBuilder </pre> </p> <p> That's nothing but an overly complicated way to create a data value from another data value. You can simplify the code from the previous article. First, instead of calling them 'Builders', we should be honest and name them as the default values they are: </p> <p> <pre><span style="color:#600277;">defaultPostCode</span>&nbsp;::&nbsp;<span style="color:blue;">PostCode</span> defaultPostCode&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">PostCode</span>&nbsp;<span style="color:blue;">[]</span> <span style="color:#600277;">defaultAddress</span>&nbsp;::&nbsp;<span style="color:blue;">Address</span> defaultAddress&nbsp;&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Address</span>&nbsp;{&nbsp;street&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;city&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;postCode&nbsp;<span style="color:#666666;">=</span>&nbsp;defaultPostCode&nbsp;}</pre> </p> <p> <code>defaultPostCode</code> is nothing but an empty <code>PostCode</code> value, and <code>defaultAddress</code> is an <code>Address</code> value with empty constituent values. Notice that <code>defaultAddress</code> uses <code>defaultPostCode</code> for the <code>postCode</code> value. </p> <p> If you need a value in Paris, you can simply write it like this: </p> <p> <pre>address&nbsp;<span style="color:#666666;">=</span>&nbsp;defaultAddress&nbsp;{&nbsp;city&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>&nbsp;} </pre> </p> <p> Likewise, if you need a more specific address, but you don't care about the post code, you can write it like this: </p> <p> <pre>address&#39;&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:#dd0000;">Address</span>&nbsp;{&nbsp;street&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;Rue&nbsp;Morgue&quot;</span>,&nbsp;city&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>,&nbsp;postCode&nbsp;<span style="color:#666666;">=</span>&nbsp;defaultPostCode&nbsp;}</pre> </p> <p> Notice how much simpler this is. There's no need to call <code>fmap</code> in order to pull the 'underlying value' out of the functor, transform it, and put it back in the functor. Haskell's 'copy and update' syntax gives you this ability for free. It's built into the language. </p> <p> <strong>Building F# values</strong> </p> <p> Haskell isn't the only language with 'copy and update' syntax. F# has it as well, and in fact, it's from <a href="https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/copy-and-update-record-expressions">the F# documentation</a> that I've taken the 'copy and update' term. </p> <p> The code corresponding to the above Haskell code looks like this in F#: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;defaultPostCode&nbsp;=&nbsp;<span style="color:navy;">PostCode</span>&nbsp;[] <span style="color:blue;">let</span>&nbsp;defaultAddress&nbsp;=&nbsp;{&nbsp;Street&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>;&nbsp;City&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>;&nbsp;PostCode&nbsp;=&nbsp;defaultPostCode&nbsp;} <span style="color:blue;">let</span>&nbsp;address&nbsp;=&nbsp;{&nbsp;defaultAddress&nbsp;<span style="color:blue;">with</span>&nbsp;City&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>&nbsp;} <span style="color:blue;">let</span>&nbsp;address&#39;&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;Street&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Rue&nbsp;Morgue&quot;</span>;&nbsp;City&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>;&nbsp;PostCode&nbsp;=&nbsp;defaultPostCode&nbsp;}</pre> </p> <p> The syntax is a little different, but the concepts are the same. F# adds the keyword <code>with</code> to 'copy and update' expressions, which translates easily back to C# <a href="https://en.wikipedia.org/wiki/Fluent_interface">fluent interfaces</a>. </p> <p> <strong>Building C# objects</strong> </p> <p> In a <a href="http://blog.ploeh.dk/2017/08/21/generalised-test-data-builder">previous article</a>, you saw how to refactor your domain model to a model of <a href="https://martinfowler.com/bliki/ValueObject.html">Value Objects</a> with fluent interfaces. </p> <p> In your unit tests, you can define natural default values for testing purposes: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Natural</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">PostCode</span>&nbsp;PostCode&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PostCode</span>(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;Address&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;PostCode); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">InvoiceLine</span>&nbsp;InvoiceLine&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InvoiceLine</span>(<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;<span style="color:#2b91af;">PoundsShillingsPence</span>.Zero); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Recipient</span>&nbsp;Recipient&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Recipient</span>(<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;Address); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Invoice</span>&nbsp;Invoice&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Invoice</span>(Recipient,&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InvoiceLine</span>[0]); }</pre> </p> <p> This static <code>Natural</code> class is a test-specific container of 'good' default values. Notice how, once more, the <code>Address</code> value uses the <code>PostCode</code> value to fill in the <code>PostCode</code> property of the default <code>Address</code> value. </p> <p> With these default test values, and the fluent interface of your domain model, you can easily build a test address in Paris: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;<span style="color:#2b91af;">Natural</span>.Address.WithCity(<span style="color:#a31515;">&quot;Paris&quot;</span>); </pre> </p> <p> Because <code>Natural.Address</code> is an <code>Address</code> object, you can use its <code>WithCity</code> method to build a test address in Paris, and where all other constituent values remain the default values. </p> <p> Likewise, you can create an address on Rue Morgue, but with a default post code: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:#a31515;">&quot;Rue&nbsp;Morgue&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>,&nbsp;<span style="color:#2b91af;">Natural</span>.PostCode); </pre> </p> <p> Here, you can simply create a new <code>Address</code> object, but with <code>Natural.PostCode</code> as the post code value. </p> <p> <strong>Conclusion</strong> </p> <p> Using a fluent domain model obviates the need for Test Data Builders. There's a tendency among functional programmers to overbearingly state that design patterns are nothing but recipes to overcome deficiencies in particular programming languages or paradigms. If you believe such a claim, at least it ought to go both ways, but at the conclusion of this article series, I hope I've been able to demonstrate that this is true for the Test Data Builder pattern. You only need it for 'classic', mutable, object-oriented domain models. <ol> <li>For mutable object models, use Test Data Builders.</li> <li>Consider, however, modelling your domain with Value Objects and 'copy and update' instance methods.</li> <li>Even better, consider using a programming language with built-in 'copy and update' expressions.</li> </ol> If you're stuck with a language like C# or Java, you don't get language-level support for 'copy and update' expressions. This means that you'll still need to incur the cost of adding and maintaining all those <code>With[...]</code> methods: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Invoice</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Recipient</span>&nbsp;Recipient&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:#2b91af;">InvoiceLine</span>&gt;&nbsp;Lines&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;Invoice( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Recipient</span>&nbsp;recipient, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:#2b91af;">InvoiceLine</span>&gt;&nbsp;lines) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(recipient&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(recipient)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(lines&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(lines)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Recipient&nbsp;=&nbsp;recipient; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Lines&nbsp;=&nbsp;lines; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Invoice</span>&nbsp;WithRecipient(<span style="color:#2b91af;">Recipient</span>&nbsp;newRecipient) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Invoice</span>(newRecipient,&nbsp;<span style="color:blue;">this</span>.Lines); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Invoice</span>&nbsp;WithLines(<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:#2b91af;">InvoiceLine</span>&gt;&nbsp;newLines) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Invoice</span>(<span style="color:blue;">this</span>.Recipient,&nbsp;newLines); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">override</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;Equals(<span style="color:blue;">object</span>&nbsp;obj) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;other&nbsp;=&nbsp;obj&nbsp;<span style="color:blue;">as</span>&nbsp;<span style="color:#2b91af;">Invoice</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(other&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">base</span>.Equals(obj); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">object</span>.Equals(<span style="color:blue;">this</span>.Recipient,&nbsp;other.Recipient) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&amp;&nbsp;<span style="color:#2b91af;">Enumerable</span>.SequenceEqual( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Lines.OrderBy(l&nbsp;=&gt;&nbsp;l.Name), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;other.Lines.OrderBy(l&nbsp;=&gt;&nbsp;l.Name)); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">override</span>&nbsp;<span style="color:blue;">int</span>&nbsp;GetHashCode() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Recipient.GetHashCode()&nbsp;^ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Lines.GetHashCode(); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> That may seem like quite a maintenance burden (and it is), but consider that it has the same degree of complexity and overhead as defining a Test Data Builder for each domain object. At least, by putting this extra code in your domain model, you make all of that API (all the <code>With[...]</code> methods, and the structural equality) available to other production code. In my experience, that's a better return of investment than isolating such useful features only to test code. </p> <p> Still, once you've tried using a language like F# or Haskell, where 'copy and update' expressions come with the language, you realise how much redundant code you're writing in C# or Java. The Test Data Builder design pattern truly is a recipe that addresses deficiencies in particular languages. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/09/18/the-test-data-generator-functor">The Test Data Generator functor</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="https://www.linkedin.com/in/romainvasseur/">Romain Vasseur</a></div> <div>Hi Marks, thanks for the whole serie. I personally tend to split my class into 2: 'core' feature and syntactic sugar one.<br>Leveraging extension methods to implement 'With' API is relatively straightforward and you have both developper friendly API and a great separation of concern namely definition and usage.<br>If you choose to implement extensions in another assembly you could manage who have access to it: unit test only, another assembly, whole project.<br>You can split API according to context/user too. It can also be useful to enforce some guidelines.</div> <div class="comment-date">2017-09-12 09:20 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Builder as Identity http://blog.ploeh.dk/2017/09/04/builder-as-identity 2017-09-04T07:41:00+00:00 Mark Seemann <div id="post"> <p> <em>In which the Builder functor turns out to be nothing but the Identity functor in disguise.</em> </p> <p> This is the fourth in <a href="http://blog.ploeh.dk/2017/08/14/from-test-data-builders-to-the-identity-functor">a series of articles about the relationship between the Test Data Builder design pattern, and the identity functor</a>. In the <a href="http://blog.ploeh.dk/2017/08/28/the-builder-functor">previous article</a>, you saw how a generic <a href="http://www.natpryce.com/articles/000714.html">Test Data Builder</a> can be modelled as a functor. </p> <p> You may, however, be excused if you're slightly underwhelmed. Modelling a Test Data Builder as a functor doesn't seem to add much value. </p> <p> <strong>Haskell's Identity functor</strong> </p> <p> In the previous article, you saw the Builder functor implemented in various languages, including Haskell: </p> <p> <pre><span style="color:blue;">newtype</span>&nbsp;<span style="color:#dd0000;">Builder</span>&nbsp;a&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Builder</span>&nbsp;a&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Show</span>,&nbsp;<span style="color:#a31515;">Eq</span>) <span style="color:blue;">instance</span>&nbsp;<span style="color:blue;">Functor</span>&nbsp;<span style="color:blue;">Builder</span>&nbsp;<span style="color:blue;">where</span> &nbsp;&nbsp;fmap&nbsp;f&nbsp;(<span style="color:#dd0000;">Builder</span>&nbsp;a)&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Builder</span>&nbsp;<span style="color:#666666;">$</span>&nbsp;f&nbsp;a</pre> </p> <p> The <code>fmap</code> implementation is literally a one-liner: pattern match the value <code>a</code> out of the <code>Builder</code>, call <code>f</code> with <code>a</code>, and package the result in a new <code>Builder</code> value. </p> <p> For many trivial functors, it turns out that the the Glasgow Haskell Compiler (GHC) can automatically implement <code>fmap</code> with a language extension: </p> <p> <pre>{-#&nbsp;<span style="color:blue;">LANGUAGE</span>&nbsp;DeriveFunctor&nbsp;#-} <span style="color:blue;">module</span>&nbsp;Builder&nbsp;<span style="color:blue;">where</span> <span style="color:blue;">newtype</span>&nbsp;<span style="color:#dd0000;">Builder</span>&nbsp;a&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Builder</span>&nbsp;a&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Show</span>,&nbsp;<span style="color:#a31515;">Eq</span>,&nbsp;<span style="color:#a31515;">Functor</span>)</pre> </p> <p> Notice the <code>DeriveFunctor</code> language extension. This enables the compiler to automatically implement <code>fmap</code> by adding <code>Functor</code> to the <code>deriving</code> list. </p> <p> Perhaps we should take this as a hint. If the compiler can automatically make <code>Builder</code> a <code>Functor</code>, perhaps it doesn't add that much value. </p> <p> This particular <code>Builder</code> is equivalent to Haskell's built-in <code>Identity</code> functor. <code>Identity</code> is a 'no-op' functor, if you will. While it's a functor, it doesn't 'do' anything. It's similar to the <a href="https://en.wikipedia.org/wiki/Null_Object_pattern">Null Object</a> design pattern, in the sense that the only value it adds is that it enables you to turn any naked value into a functor. This can occasionally be useful if you need to pass a functor to an API. </p> <p> <strong>PostCode and Address builders</strong> </p> <p> You can rewrite the previous <code>PostCode</code> and <code>Address</code> Test Data Builders as <code>Identity</code> values: </p> <p> <pre><span style="color:#600277;">postCodeBuilder</span>&nbsp;::&nbsp;<span style="color:blue;">Identity</span>&nbsp;<span style="color:blue;">PostCode</span> postCodeBuilder&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Identity</span>&nbsp;<span style="color:#666666;">$</span>&nbsp;<span style="color:#dd0000;">PostCode</span>&nbsp;<span style="color:blue;">[]</span> <span style="color:#600277;">addressBuilder</span>&nbsp;::&nbsp;<span style="color:blue;">Identity</span>&nbsp;<span style="color:blue;">Address</span> addressBuilder&nbsp;&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:#dd0000;">Identity</span>&nbsp;<span style="color:#dd0000;">Address</span>&nbsp;{&nbsp;street&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;city&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;postCode&nbsp;<span style="color:#666666;">=</span>&nbsp;pc&nbsp;} &nbsp;&nbsp;<span style="color:blue;">where</span>&nbsp;<span style="color:#dd0000;">Identity</span>&nbsp;pc&nbsp;<span style="color:#666666;">=</span>&nbsp;postCodeBuilder</pre> </p> <p> As in the previous examples, <code>postCodeBuilder</code> is nothing but a 'good' default <code>PostCode</code> value. This time, it's turned into an <code>Identity</code> value, instead of a <code>Builder</code> value. The same is true for <code>addressBuilder</code> - notice that it uses <code>postCodeBuilder</code> for the <code>postCode</code> value. </p> <p> This enables you to build an address in Paris, like previous examples: </p> <p> <pre><span style="color:#dd0000;">Identity</span>&nbsp;address&nbsp;<span style="color:#666666;">=</span>&nbsp;fmap&nbsp;(<span style="color:#666666;">\</span>a&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;a&nbsp;{&nbsp;city&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>&nbsp;})&nbsp;addressBuilder </pre> </p> <p> This builds an address with <code>city</code> bound to <code>"Paris"</code>, but with all other values still at their default values: </p> <p> <pre><span style="color:#dd0000;">Address</span>&nbsp;{street&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;city&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>,&nbsp;postCode&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">PostCode</span>&nbsp;<span style="color:blue;">[]</span>} </pre> </p> <p> You can also build an address from an <code>Identity</code> of a different generic type: </p> <p> <pre><span style="color:#dd0000;">Identity</span>&nbsp;address&#39;&nbsp;<span style="color:#666666;">=</span>&nbsp;fmap&nbsp;newAddress&nbsp;postCodeBuilder &nbsp;&nbsp;<span style="color:blue;">where</span>&nbsp;newAddress&nbsp;pc&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Address</span>&nbsp;{&nbsp;street&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;Rue&nbsp;Morgue&quot;</span>,&nbsp;city&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>,&nbsp;postCode&nbsp;<span style="color:#666666;">=</span>&nbsp;pc&nbsp;}</pre> </p> <p> Notice that this example uses <code>postCodeBuilder</code> as an origin, but creates a new <code>Address</code> value. In this expression, <code>newAddress</code> is a local function that takes a <code>PostCode</code> value as input, and returns an <code>Address</code> value as output. </p> <p> <strong>Summary</strong> </p> <p> Neither F# nor C# comes with a built-in identity functor, but it'd be as trivial to create them as the code you've already seen. In the previous article, you saw how to define a <code>Builder&lt;'a&gt;</code> type in F#. All you have to do is to change its name to <code>Identity&lt;'a&gt;</code>, and you have the identity functor. You can perform a similar rename for the C# code in the previous articles. </p> <p> Since the Identity functor doesn't really 'do' anything, there's no reason to use it for building test values. In the next article, you'll see how to discard the functor and in the process make your code simpler. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/09/11/test-data-without-builders">Test data without Builders</a>. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. The Builder functor http://blog.ploeh.dk/2017/08/28/the-builder-functor 2017-08-28T11:19:00+00:00 Mark Seemann <div id="post"> <p> <em>The Test Data Builder design pattern as a functor.</em> </p> <p> This is the third in <a href="http://blog.ploeh.dk/2017/08/14/from-test-data-builders-to-the-identity-functor">a series of articles about the relationship between the Test Data Builder design pattern, and the identity functor</a>. The <a href="http://blog.ploeh.dk/2017/08/21/generalised-test-data-builder">previous article</a> introduced this generic Builder class: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">T</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">T</span>&nbsp;item; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;Builder(<span style="color:#2b91af;">T</span>&nbsp;item) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(item&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(item)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.item&nbsp;=&nbsp;item; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">T1</span>&gt;&nbsp;Select&lt;<span style="color:#2b91af;">T1</span>&gt;(<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">T</span>,&nbsp;<span style="color:#2b91af;">T1</span>&gt;&nbsp;f) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;newItem&nbsp;=&nbsp;f(<span style="color:blue;">this</span>.item); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">T1</span>&gt;(newItem); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">T</span>&nbsp;Build() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.item; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">override</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;Equals(<span style="color:blue;">object</span>&nbsp;obj) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;other&nbsp;=&nbsp;obj&nbsp;<span style="color:blue;">as</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">T</span>&gt;; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(other&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">base</span>.Equals(obj); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">object</span>.Equals(<span style="color:blue;">this</span>.item,&nbsp;other.item); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">override</span>&nbsp;<span style="color:blue;">int</span>&nbsp;GetHashCode() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.item.GetHashCode(); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> The workhorse is the <code>Select</code> method. As I previously promised to explain, there's a reason I chose that particular name. </p> <p> <strong>Query syntax</strong> </p> <p> C# comes with a small DSL normally known as <em>query syntax</em>. People mostly think of it in relation to ORMs such as Entity Framework, but it's a general-purpose language feature. Still, most developers probably associate it with the <code>IEnumerable&lt;T&gt;</code> interface, but it's more general than that. In fact, any type that comes with a <code>Select</code> method with a compatible signature supports query syntax. </p> <p> I deliberately designed the Builder's <code>Select</code> method to support query syntax: </p> <p> <pre><span style="color:#2b91af;">Address</span>&nbsp;address&nbsp;=&nbsp;<span style="color:blue;">from</span>&nbsp;a&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Builder</span>.Address &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">select</span>&nbsp;a.WithCity(<span style="color:#a31515;">&quot;Paris&quot;</span>);</pre> </p> <p> <code>Builder.Address</code> is a <code>Builder&lt;Address&gt;</code> object that contains a 'good' default <code>Address</code> value. Since <code>Builder&lt;T&gt;</code> has a compatible <code>Select</code> method, you can 'query it'. In this example, you use the <code>WithCity</code> method to explicitly pin the <code>Address</code> object's <code>City</code> property, while all the other <code>Address</code> values remain the default values. </p> <p> There's an extra bit (pun intended) of compiler magic at work. Did you wonder how a <code>Builder&lt;Address&gt;</code> automatically turns into an <code>Address</code> value? After all, <code>address</code> is of the type <code>Address</code>, not <code>Builder&lt;Address&gt;</code>. </p> <p> I specifically added an implicit conversion so that I didn't have to surround the query expression with brackets in order to call the <code>Build</code> method: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">implicit</span>&nbsp;<span style="color:blue;">operator</span>&nbsp;<span style="color:#2b91af;">T</span>(<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;b) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;b.item; }</pre> </p> <p> This conversion is defined on <code>Builder&lt;T&gt;</code>. It's the reason I explicitly use the type name when I declare the <code>address</code> variable above, instead of using the <code>var</code> keyword. Declaring the type forces the implicit conversion. </p> <p> You can also use query syntax to map one constructed Builder type into another (and ultimately to the value it contains): </p> <p> <pre><span style="color:#2b91af;">Address</span>&nbsp;address&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">from</span>&nbsp;pc&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Builder</span>.PostCode &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">select</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:#a31515;">&quot;Rue&nbsp;Morgue&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>,&nbsp;pc);</pre> </p> <p> This expression starts with a <code>Builder&lt;PostCode&gt;</code> object, transforms it into a <code>Builder&lt;Address&gt;</code> object, and then finally uses the implicit conversion to turn the <code>Builder&lt;Address&gt;</code> into an <code>Address</code> object. </p> <p> Even a more complex 'query' looks almost palatable: </p> <p> <pre><span style="color:#2b91af;">Invoice</span>&nbsp;invoice&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">from</span>&nbsp;i&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Builder</span>.Invoice &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">select</span>&nbsp;i.WithRecipient( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">from</span>&nbsp;r&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Builder</span>.Recipient &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">select</span>&nbsp;r.WithAddress(<span style="color:#2b91af;">Builder</span>.Address.WithNoPostCode()));</pre> </p> <p> Again, the implicit type conversion makes the syntax much cleaner. </p> <p> <strong>Functor</strong> </p> <p> Isn't it amazing that the C# designers were able to come up with such a generally useful language feature? It certainly is a nice piece of work, but it's based on a an existing body of knowledge. </p> <p> A type like <code>Builder&lt;T&gt;</code> with a suitable <code>Select</code> method is a <em>functor</em>. This is a term from category theory, but I'll try to avoid turning this article into a category theory lecture. Likewise, I'm not going to talk specifically about monads here, although it's a closely related topic. A functor is a mapping between categories; it maps an object from one category into an object of another category. </p> <p> Although I've never seen Microsoft explicitly acknowledge the connection to functors and monads, it's clear that it's there. One of the principal designers of LINQ was <a href="https://en.wikipedia.org/wiki/Erik_Meijer_(computer_scientist)">Erik Meijer</a>, who definitely knows his way around category theory and functional programming. A functor is a simple, but widely applicable abstraction. </p> <p> In order to be a functor, a type must have an associated mapping. In C#'s query syntax, this is a method named <code>Select</code>, but more often it's called <code>map</code>. </p> <p> <strong>Haskell Builder</strong> </p> <p> In Haskell, the mapping is called <code>fmap</code>, and you can define the Builder functor like this: </p> <p> <pre><span style="color:blue;">newtype</span>&nbsp;<span style="color:#dd0000;">Builder</span>&nbsp;a&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Builder</span>&nbsp;a&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Show</span>,&nbsp;<span style="color:#a31515;">Eq</span>) <span style="color:blue;">instance</span>&nbsp;<span style="color:blue;">Functor</span>&nbsp;<span style="color:blue;">Builder</span>&nbsp;<span style="color:blue;">where</span> &nbsp;&nbsp;fmap&nbsp;f&nbsp;(<span style="color:#dd0000;">Builder</span>&nbsp;a)&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Builder</span>&nbsp;<span style="color:#666666;">$</span>&nbsp;f&nbsp;a</pre> </p> <p> Notice how terse the definition is, compared to the C# version. Despite the difference in size, they accomplish the same goal. The first line of code defines the <code>Builder</code> type, complete with structural equality (<code>Eq</code>) and the ability to convert a <code>Builder</code> value to a string (<code>Show</code>). </p> <p> This <code>Builder</code> type is explicitly defined as a <code>Functor</code> in the second expression, where the <code>fmap</code> function is implemented. The code is similar to the <code>Select</code> method in the above C# example: <code>f</code> is a function that takes the generic type <code>a</code> (corresponding to <code>T</code> in the C# example) as input, and returns a value of the generic type <code>b</code> (corresponding to <code>T1</code> in the C# example). The mapping pulls the underlying value out of the input Builder, calls <code>f</code> with that value, and puts the return value into a new Builder. </p> <p> In Haskell, a functor is part of the language itself, so <code>Builder</code> is explicitly declared to be a <code>Functor</code> instance. </p> <p> If you define some default <code>Builder</code> values, corresponding to the above <code>Builder.Address</code>, you can use them to build addresses in the same way: </p> <p> <pre><span style="color:#dd0000;">Builder</span>&nbsp;address&nbsp;<span style="color:#666666;">=</span>&nbsp;fmap&nbsp;(<span style="color:#666666;">\</span>a&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;a&nbsp;{&nbsp;city&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>&nbsp;})&nbsp;addressBuilder </pre> </p> <p> Here, <code>addressBuilder</code> is a <code>Builder Address</code> value, corresponding to the C# <code>Builder.Address</code> value. <code>\a -&gt; a { city = "Paris" }</code> is a lambda expression that takes an <code>Address</code> value as input, and return a similar value as output, only with <code>city</code> explicitly bound to <code>"Paris"</code>. </p> <p> <strong>F# example</strong> </p> <p> Unlike Haskell, F# doesn't treat functors as an explicit construct, but you can still define a Builder functor: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">Builder</span>&lt;&#39;a&gt;&nbsp;=&nbsp;<span style="color:navy;">Builder</span>&nbsp;<span style="color:blue;">of</span>&nbsp;&#39;a <span style="color:blue;">module</span>&nbsp;<span style="color:teal;">Builder</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;Builder&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;Builder&lt;&#39;b&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">map</span>&nbsp;<span style="color:navy;">f</span>&nbsp;(<span style="color:navy;">Builder</span>&nbsp;x)&nbsp;=&nbsp;<span style="color:navy;">Builder</span>&nbsp;(<span style="color:navy;">f</span>&nbsp;x)</pre> </p> <p> You can see how similar this is to the Haskell example. In F#, it's common to define a module with the same name as a generic type. This example defines a generic <code>Builder&lt;'a&gt;</code> type and a supporting <code>Builder</code> module. Normally, a module would contain other functions, in addition to <code>map</code>. </p> <p> Just like in C# and Haskell, you can build an address in Paris with a predefined Builder value as a start: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;(<span style="color:navy;">Builder</span>&nbsp;address)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;addressBuilder&nbsp;|&gt;&nbsp;<span style="color:teal;">Builder</span>.<span style="color:navy;">map</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;{&nbsp;a&nbsp;<span style="color:blue;">with</span>&nbsp;City&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>&nbsp;})</pre> </p> <p> Again, <code>addressBuilder</code> is a <code>Builder&lt;Address&gt;</code> that contains a 'default' <code>Address</code> (test) value. You use <code>Builder.map</code> with a lambda expression to map the default value into a new <code>Address</code> value where <code>City</code> is bound to <code>"Paris"</code>. </p> <p> <strong>Functor laws</strong> </p> <p> In order to be a proper functor, an object must obey two simple laws. It's not enough that a mapping function exists, it must also obey the laws. While that sounds uncomfortably like mathematics, the laws are simple and intuitive. </p> <p> The first law is that when the mapping returns the input, the functor returned is also the input functor. There's only one (generic) function that returns its input unmodified. It's called the <em>identity</em> function (often abbreviated <em>id</em>). </p> <p> Here's an example test case that illustrates the first functor law for the C# <code>Builder&lt;T&gt;</code>: </p> <p> <pre>[<span style="color:#2b91af;">Fact</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;BuilderObeysFirstFunctorLaw() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;id&nbsp;=&nbsp;x&nbsp;=&gt;&nbsp;x; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;sut&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:blue;">int</span>&gt;(42); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;actual&nbsp;=&nbsp;sut.Select(id); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(sut,&nbsp;actual); }</pre> </p> <p> The .NET Base Class Library doesn't come with a built-in identity function, so the test case first defines it as <code>id</code>. Normally, the identity function would be defined as a function that takes a value of the generic type <code>T</code> as input, and returns the same value (still of type <code>T</code>) as output. This test is only an example for the type <code>int</code>, so it also defines the identity function as constrained to <code>int</code>. </p> <p> The test creates a new <code>Builder&lt;int&gt;</code> with the value <code>42</code>, and calls <code>Select</code> with <code>id</code>. Since the first functor law says that mapping with the identity function must return the input functor, the expected value is the <code>sut</code> variable. </p> <p> This test is only an <em>example</em> of the first functor law. It doesn't prove that <code>Builder&lt;T&gt;</code> obeys the law for all generic types (<code>T</code>) and for all values. It only proves that it holds for the integer 42. You get the idea, though, I'm sure. </p> <p> The second functor law says that if you chain two functions to make a third function, and map your functor using that third function, the result should be equal to the result you get if you chain two mappings made out of those two functions. Here's an example: </p> <p> <pre>[<span style="color:#2b91af;">Fact</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;BuilderObeysSecondFunctorLaw() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:blue;">int</span>,&nbsp;<span style="color:blue;">string</span>&gt;&nbsp;g&nbsp;=&nbsp;i&nbsp;=&gt;&nbsp;i.ToString(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:blue;">string</span>,&nbsp;<span style="color:blue;">string</span>&gt;&nbsp;f&nbsp;=&nbsp;s&nbsp;=&gt;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:blue;">string</span>(s.Reverse().ToArray()); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;sut&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:blue;">int</span>&gt;(1337); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;actual&nbsp;=&nbsp;sut.Select(i&nbsp;=&gt;&nbsp;f(g(i))); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;expected&nbsp;=&nbsp;sut.Select(g).Select(f); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(expected,&nbsp;actual); }</pre> </p> <p> This test case (which is, again, only an example) first defines two functions, <code>f</code> and <code>g</code>. It then creates a new <code>Builder&lt;int&gt;</code> and calls <code>Select</code> with the combined function <code>f(g)</code>. This returns the <code>actual</code> result, which is a <code>Builder&lt;string&gt;</code>. </p> <p> This result should be equal to first calling <code>Select</code> with <code>g</code> (which returns a <code>Builder&lt;string&gt;</code>), and then calling <code>Select</code> with <code>f</code> (which returns another <code>Builder&lt;string&gt;</code>). These two Builder objects should be equal to each other, which they are. </p> <p> Both these tests compare an expected Builder to an actual Builder, which is the reason that <code>Builder&lt;T&gt;</code> overrides <code>Equals</code> in order to have structural equality. In Haskell, the above Builder type has structural equality because it uses the default instance of <code>Eq</code>, and in F#, <code>Builder&lt;'a&gt;</code> has structural equality because that's the default equality for the immutable F# data types. </p> <p> We can't easily talk about the functor laws without being able to talk about functor values being (or not being) equal to each other, so structural equality is an important element in the discussion. </p> <p> <strong>Summary</strong> </p> <p> You can define a Test Data Builder as a functor by defining a generic Builder type with a <code>Select</code> method. In order to be a proper functor, it must also obey the functor laws, but these laws are quite natural; you almost have to go out of your way in order to violate them. </p> <p> A functor is a well-known abstraction. Instead of trying to come up with a half-baked, ad-hoc abstraction, modelling an API based on already known and understood abstractions such as functors will make the API easier to learn. Everyone who knows what a functor is, will automatically have a good understanding of the API. Even if you didn't know about functors until now, you only have to learn about them once. </p> <p> This can often be beneficial, but for Test Data Builders, it turns out to be a red herring. The Builder functor is nothing but the Identity functor in disguise. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/09/04/builder-as-identity">Builder as Identity</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="https://github.com/andresmoschini">Andrés Moschini</a></div> <div class="comment-content"> <p>Maybe I am missing something, so could you explain with few words what is the advantage of having this _generic builder_?</p> <p>I mean, inmutable entities and _with methods_ seems to be enough to easily create test data without builders, for example:</p> <p><pre><code> var invoice = DefaultTestObjects.Invoice .WithRecipient(DefaultTestObjects.Recipient .WithAddress(DefaultTestObjects.Address .WithNoPostCode() .WithCity("Paris")) .WithDate(new DateTimeOffset(2017, 8, 29))); </code></pre></p> </div> <div class="comment-date">2017-08-29 12:50 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Andrés, thank you for writing. I hope that the next two articles in <a href="http://blog.ploeh.dk/2017/08/14/from-test-data-builders-to-the-identity-functor">this article series</a> will answer your question. It seems, however, that you've already predicted where this is headed. A fine display of critical thinking! </p> </div> <div class="comment-date">2017-08-29 17:48 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://www.linkedin.com/in/romainvasseur/">Romain Vasseur</a></div> <div class="comment-content"> <p>Just for the DSL and implicit conversion laius it's worth reading.<br> _Implicit/explicit_ is a must-have to lighten _value object_ usage and contributes to deliver proper API. <br>Thank you Mark. </p> </div> <div class="comment-date">2017-08-31 12:44 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Generalised Test Data Builder http://blog.ploeh.dk/2017/08/21/generalised-test-data-builder 2017-08-21T06:09:00+00:00 Mark Seemann <div id="post"> <p> <em>This article presents a generalised Test Data Builder.</em> </p> <p> This is the second in <a href="http://blog.ploeh.dk/2017/08/14/from-test-data-builders-to-the-identity-functor">a series of articles about the relationship between the Test Data Builder design pattern, and the identity functor</a>. The <a href="http://blog.ploeh.dk/2017/08/15/test-data-builders-in-c">previous article was a review</a> of the <a href="http://www.natpryce.com/articles/000714.html">Test Data Builder</a> pattern. </p> <p> <strong>Boilerplate</strong> </p> <p> While the Test Data Builder is an incredibly versatile and useful design pattern, it has a problem. In languages like C# and Java, it's difficult to generalise. This leads to an excess of boilerplate code. </p> <p> Expanding on <a href="http://www.natpryce.com">Nat Pryce</a>'s original example, an <code>InvoiceBuilder</code> is composed of other builders: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">InvoiceBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">Recipient</span>&nbsp;recipient; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:#2b91af;">InvoiceLine</span>&gt;&nbsp;lines; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;InvoiceBuilder() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.recipient&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">RecipientBuilder</span>().Build(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.lines&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">List</span>&lt;<span style="color:#2b91af;">InvoiceLine</span>&gt;&nbsp;{&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InvoiceLineBuilder</span>().Build()&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">InvoiceBuilder</span>&nbsp;WithRecipient(<span style="color:#2b91af;">Recipient</span>&nbsp;newRecipient) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.recipient&nbsp;=&nbsp;newRecipient; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">InvoiceBuilder</span>&nbsp;WithInvoiceLines( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:#2b91af;">InvoiceLine</span>&gt;&nbsp;newLines) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.lines&nbsp;=&nbsp;newLines; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Invoice</span>&nbsp;Build() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Invoice</span>(recipient,&nbsp;lines); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> In order to create a <code>Recipient</code>, a <code>RecipientBuilder</code> is used. Likewise, in order to create a single <code>InvoiceLine</code>, an <code>InvoiceLineBuilder</code> is used. This pattern repeats in the <code>RecipientBuilder</code>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">RecipientBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">string</span>&nbsp;name; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;address; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;RecipientBuilder() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.address&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>().Build(); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">RecipientBuilder</span>&nbsp;WithName(<span style="color:blue;">string</span>&nbsp;newName) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.name&nbsp;=&nbsp;newName; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">RecipientBuilder</span>&nbsp;WithAddress(<span style="color:#2b91af;">Address</span>&nbsp;newAddress) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.address&nbsp;=&nbsp;newAddress; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Recipient</span>&nbsp;Build() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Recipient</span>(<span style="color:blue;">this</span>.name,&nbsp;<span style="color:blue;">this</span>.address); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> In order to create an <code>Address</code> object, an <code>AddressBuilder</code> is used. </p> <p> <strong>Generalisation attempts</strong> </p> <p> You can describe the pattern in a completely automatable manner: <ol> <li>For each domain class, create a corresponding Builder class.</li> <li>For each class field or property in the domain class, define a corresponding field or property in the Builder.</li> <li> In the Builder's constructor, initialise each field or property with a 'good' default value. <ul> <li>If the field is a primitive value, such as a string or integer, hard-code an appropriate value.</li> <li>If the field is a complex domain type, use that type's corresponding Builder to create the default value.</li> </ul> </li> <li>For each class field or property, add a <code>With[...]</code> method that changes the field and returns the Builder itself.</li> <li>Add a <code>Build</code> method that returns a new instance of the domain class with the constituent values collected so far.</li> </ol> When you can deterministically descrbe an automatable process, you can write code to automate it. </p> <p> People have already done that. After having written individual Test Data Builders for a couple of months, I got tired of it and wrote <a href="https://github.com/AutoFixture/AutoFixture">AutoFixture</a>. It uses Reflection to build objects at run-time, but I've also witnessed attempts to automate Test Data Builders via automated code generation. </p> <p> AutoFixture has been moderately successful, but some people find its API difficult to learn. Correspondingly, code generation comes with its own issues. </p> <p> In languages like C# or Java, it's difficult to identify a better generalisation. </p> <p> <strong>Generic Builder</strong> </p> <p> Instead of trying to automate the Test Data Builder pattern, you can pursue a different strategy. At first, it doesn't look all that promising, but if you soldier on, it'll reveal meaningful insights. </p> <p> As an alternative to replicating the Test Data Builder pattern exactly, you can define a single generically typed Builder class: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">T</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">T</span>&nbsp;item; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;Builder(<span style="color:#2b91af;">T</span>&nbsp;item) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(item&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(item)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.item&nbsp;=&nbsp;item; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">T1</span>&gt;&nbsp;Select&lt;<span style="color:#2b91af;">T1</span>&gt;(<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">T</span>,&nbsp;<span style="color:#2b91af;">T1</span>&gt;&nbsp;f) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;newItem&nbsp;=&nbsp;f(<span style="color:blue;">this</span>.item); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">T1</span>&gt;(newItem); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">T</span>&nbsp;Build() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.item; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">override</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;Equals(<span style="color:blue;">object</span>&nbsp;obj) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;other&nbsp;=&nbsp;obj&nbsp;<span style="color:blue;">as</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">T</span>&gt;; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(other&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">base</span>.Equals(obj); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">object</span>.Equals(<span style="color:blue;">this</span>.item,&nbsp;other.item); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">override</span>&nbsp;<span style="color:blue;">int</span>&nbsp;GetHashCode() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.item.GetHashCode(); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> The <code>Builder&lt;T&gt;</code> class reduces the Test Data Builder design patterns to the essentials: <ul> <li>A constructor that initialises the Builder with default data.</li> <li>A single <a href="https://en.wikipedia.org/wiki/Fluent_interface">fluent interface</a> <code>Select</code> method, which returns a new Builder object.</li> <li>A <code>Build</code> method, which returns the built object.</li> </ul> Perhaps you wonder about the name of the <code>Select</code> method, but there's a good reason for that; you'll learn about it later. </p> <p> This example of a generic Builder class overrides <code>Equals</code> (and, therefore, also <code>GetHashCode</code>). It doesn't have to do that, but there's a good reason to do this that we'll also <a href="http://blog.ploeh.dk/2017/08/28/the-builder-functor">come back to later</a>. </p> <p> It doesn't seem particularly useful, and a first attempt at using it seems to confirm such scepticism: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;<span style="color:#2b91af;">Build</span>.Address().Select(a&nbsp;=&gt; { &nbsp;&nbsp;&nbsp;&nbsp;a.City&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;a; }).Build();</pre> </p> <p> This example first uses <code>Build.Address()</code> to create an initial Builder object with appropriate defaults. This static method is defined on the static <code>Build</code> class: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">Address</span>&gt;&nbsp;Address() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">Address</span>&gt;(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;PostCode().Build())); }</pre> </p> <p> Contrary to <code>Builder&lt;T&gt;</code>, which is a reusable, general-purpose class, the static <code>Build</code> class is an example of a collection of <a href="http://xunitpatterns.com/Test%20Utility%20Method.html">Test Utility Methods</a> specific to the domain model you're testing. Notice how the <code>Build.Address()</code> method uses <code>Build.PostCode().Build()</code> to create a default value for the initial <code>Address</code> object's post code. </p> <p> The above example passes a C# code block to the <code>Select</code> method. It takes the <code>a</code> (<code>Address</code>) object as input, specifically mutates its <code>City</code> property, and returns it. This syntax is crude, but works. It may look acceptable when pinning a single <code>City</code> property, but it quickly becomes awkward: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;invoice&nbsp;=&nbsp;<span style="color:#2b91af;">Build</span>.Invoice().Select(i&nbsp;=&gt; &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;i.Recipient&nbsp;=&nbsp;<span style="color:#2b91af;">Build</span>.Recipient().Select(r&nbsp;=&gt; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;r.Address&nbsp;=&nbsp;<span style="color:#2b91af;">Build</span>.Address().WithNoPostCode().Build(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;r; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}).Build(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;i; &nbsp;&nbsp;&nbsp;&nbsp;}).Build();</pre> </p> <p> Not only is it difficult to get right when writing such nested statements, it's also hard to read. You can, however, correct that problem, as you'll see in a little while. </p> <p> Before we commence on making the code prettier, you may have noticed that the <code>Select</code> method returns a Builder with a different generic type argument than it contains. The <code>Select</code> method on a <code>Builder&lt;T&gt;</code> object has the signature <code>public Builder&lt;T1&gt; Select&lt;T1&gt;(Func&lt;T, T1&gt; f)</code>. Until now, however, all the examples you've seen return the input object. In those examples, <code>T</code> is the same as <code>T1</code>. For completeness' sake, here's an example of a proper change of type: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;<span style="color:#2b91af;">Build</span>.PostCode() &nbsp;&nbsp;&nbsp;&nbsp;.Select(pc&nbsp;=&gt;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:#a31515;">&quot;Rue&nbsp;Morgue&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>,&nbsp;pc)) &nbsp;&nbsp;&nbsp;&nbsp;.Build();</pre> </p> <p> This example uses a <code>Builder&lt;PostCode&gt;</code> to create a new <code>Address</code> object. Plugging in the types, <code>T</code> becomes <code>PostCode</code>, and <code>T1</code> becomes <code>Address</code>. </p> <p> Perhaps you noticed that this example looks a little better than the previous examples. Instead of having to supply a C# code block, with <code>return</code> statement and all, this call to <code>Select</code> passes a proper (lambda) expression. </p> <p> <strong>Expressions from extensions</strong> </p> <p> It'd be nice if you could use expressions, instead of full code blocks, with the <code>Select</code> method. As a first step, you could write some test-specific extension methods for your domain model, like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;WithCity(<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;address,&nbsp;<span style="color:blue;">string</span>&nbsp;newCity) { &nbsp;&nbsp;&nbsp;&nbsp;address.City&nbsp;=&nbsp;newCity; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;address; }</pre> </p> <p> This is same code as one of the code blocks above, only refactored to a named extension method. It simplifies use of the generic Builder, though: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;<span style="color:#2b91af;">Build</span>.Address().Select(a&nbsp;=&gt;&nbsp;a.WithCity(<span style="color:#a31515;">&quot;Paris&quot;</span>)).Build(); </pre> </p> <p> That looks good in such a simple example, but unfortunately isn't much of an improvement when it comes to a more complex case: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;invoice&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Build</span>.Invoice() &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Select(i&nbsp;=&gt;&nbsp;i &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.WithRecipient(<span style="color:#2b91af;">Build</span>.Recipient() &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Select(r&nbsp;=&gt;&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.WithAddress(<span style="color:#2b91af;">Build</span>.Address() &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.WithNoPostCode() &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Build())) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Build())) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Build();</pre> </p> <p> If, at this point, you're tempted to give up on the overall strategy with a single generic Builder, you'd be excused. It will, however, turn out to be beneficial to carry on. There are more obstacles, but eventually, things will start to fall into place. </p> <p> <strong>Copy and update</strong> </p> <p> The above <code>WithCity</code> extension method mutates the input object, which can lead to surprising behaviour. While it's a common way to implement fluent interfaces in object-oriented languages, nothing prevents you from making the code saner. Instead of mutating the input object, create a new object with the single value changed: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;WithCity(<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;address,&nbsp;<span style="color:blue;">string</span>&nbsp;newCity) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(address.Street,&nbsp;newCity,&nbsp;address.PostCode); }</pre> </p> <p> Some people will immediately be concerned about the performance implications of doing this, but you're not one of those people, are you? </p> <p> Granted, there's allocation and garbage collection overhead by creating new objects like this, but I'd digress if I started to discuss this here. In most cases, the impact is insignificant. </p> <p> <strong>Fluent domain model</strong> </p> <p> Using extension methods enables you to use a more elegant syntax with the <code>Select</code> method, but there's still some maintenance overhead. If, for now, we accept such maintenance overhead, you could ask: given that we have to define and maintain all those <code>With[...]</code> methods, why limit them to your test code? </p> <p> Would there be any harm in defining them as proper methods on your domain model? </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;WithCity(<span style="color:blue;">string</span>&nbsp;newCity) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:blue;">this</span>.Street,&nbsp;newCity,&nbsp;<span style="color:blue;">this</span>.PostCode); }</pre> </p> <p> The above example shows the <code>WithCity</code> method as an instance method on the <code>Address</code> class. Here's the entire <code>Address</code> class, refactored to an immutable class: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Address</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">string</span>&nbsp;Street&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">string</span>&nbsp;City&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">PostCode</span>&nbsp;PostCode&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;Address(<span style="color:blue;">string</span>&nbsp;street,&nbsp;<span style="color:blue;">string</span>&nbsp;city,&nbsp;<span style="color:#2b91af;">PostCode</span>&nbsp;postCode) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(street&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(street)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(city&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(city)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(postCode&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(postCode)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Street&nbsp;=&nbsp;street; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.City&nbsp;=&nbsp;city; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.PostCode&nbsp;=&nbsp;postCode; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;WithStreet(<span style="color:blue;">string</span>&nbsp;newStreet) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(newStreet,&nbsp;<span style="color:blue;">this</span>.City,&nbsp;<span style="color:blue;">this</span>.PostCode); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;WithCity(<span style="color:blue;">string</span>&nbsp;newCity) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:blue;">this</span>.Street,&nbsp;newCity,&nbsp;<span style="color:blue;">this</span>.PostCode); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;WithPostCode(<span style="color:#2b91af;">PostCode</span>&nbsp;newPostCode) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:blue;">this</span>.Street,&nbsp;<span style="color:blue;">this</span>.City,&nbsp;newPostCode); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">override</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;Equals(<span style="color:blue;">object</span>&nbsp;obj) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;other&nbsp;=&nbsp;obj&nbsp;<span style="color:blue;">as</span>&nbsp;<span style="color:#2b91af;">Address</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(other&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">base</span>.Equals(obj); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">object</span>.Equals(<span style="color:blue;">this</span>.Street,&nbsp;other.Street) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&amp;&nbsp;<span style="color:blue;">object</span>.Equals(<span style="color:blue;">this</span>.City,&nbsp;other.City) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&amp;&nbsp;<span style="color:blue;">object</span>.Equals(<span style="color:blue;">this</span>.PostCode,&nbsp;other.PostCode); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">override</span>&nbsp;<span style="color:blue;">int</span>&nbsp;GetHashCode() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Street.GetHashCode()&nbsp;^ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.City.GetHashCode()&nbsp;^ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.PostCode.GetHashCode(); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> Technically, you could introduce instance methods like <code>WithCity</code> even if you kept the class itself mutable, but once you start down that path, it makes sense to make the class immutable. As Eric Evans recommends in <a href="http://amzn.to/WBCwx7">Domain-Driven Design</a>, modelling your domain with (immutable) <a href="https://martinfowler.com/bliki/ValueObject.html">Value Objects</a> has many benefits. Such objects should also have structural equality, which is the reason that this version of <code>Address</code> also overrides <code>Equals</code> and <code>GetHashCode</code>. </p> <p> While it looks like more work in a language like C# or Java, there are many benefits to be derived from modelling your domain with Value Objects. As an interim result, then, observe that working with unit testing (in this case a general-purpose Test Data Builder) has prompted a better design of the System Under Test. </p> <p> You may still think that this seems unnecessarily verbose, and I'd agree. This is one of the many reasons I prefer languages like F# and Haskell over C# or Java. The former have such a <em>copy and update</em> feature built-in. Here's an F# example of updating an <code>Address</code> record with a specific city: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;address&nbsp;=&nbsp;{&nbsp;a&nbsp;<span style="color:blue;">with</span>&nbsp;City&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>&nbsp;} </pre> </p> <p> This capability is built into the language. You don't have to add or maintain any code in order to be able to write code like that. Notice, even, how <code>with</code> is a keyword. I'm not sure about the etymology of the word <em>with</em> used in this context, but I find the similarity compelling. </p> <p> In Haskell, it looks similar: </p> <p> <pre>address&nbsp;<span style="color:#666666;">=</span>&nbsp;a&nbsp;{&nbsp;city&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>&nbsp;} </pre> </p> <p> In other words, domain models created from immutable Value Objects are laborious in some languages, but that only suggests a deficiency in such a language. </p> <p> <strong>Default Builders as values</strong> </p> <p> Now that the domain model is immutable, you can define default builders as values. Previously, to start building e.g. an <code>Address</code> value, you had to call the <code>Build.Address()</code> method. When the domain model was mutable, containing a single default value inside of a Builder would enable tests to mutate that default value. Now that domain classes are immutable, this is no longer a concern, and you can instead define test-specific default builders as values: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Builder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">Address</span>&gt;&nbsp;Address; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">Invoice</span>&gt;&nbsp;Invoice; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">InvoiceLine</span>&gt;&nbsp;InvoiceLine; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">PostCode</span>&gt;&nbsp;PostCode; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">PoundsShillingsPence</span>&gt;&nbsp;PoundsShillingsPence; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">Recipient</span>&gt;&nbsp;Recipient; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">static</span>&nbsp;Builder() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PoundsShillingsPence&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">PoundsShillingsPence</span>&gt;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;DomainModel.<span style="color:#2b91af;">PoundsShillingsPence</span>.Zero); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PostCode&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">PostCode</span>&gt;(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PostCode</span>()); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Address&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">Address</span>&gt;(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;PostCode.Build())); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Recipient&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">Recipient</span>&gt;(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Recipient</span>(<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;Address.Build())); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Invoice&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">Invoice</span>&gt;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Invoice</span>(Recipient.Build(),&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">List</span>&lt;<span style="color:#2b91af;">InvoiceLine</span>&gt;())); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;InvoiceLine&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">InvoiceLine</span>&gt;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InvoiceLine</span>(<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;PoundsShillingsPence.Build())); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">Address</span>&gt;&nbsp;WithNoPostCode(<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">Builder</span>&lt;<span style="color:#2b91af;">Address</span>&gt;&nbsp;b) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;b.Select(a&nbsp;=&gt;&nbsp;a.WithPostCode(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PostCode</span>())); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> This enables you to write expressions like this: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;<span style="color:#2b91af;">Builder</span>.Address.Select(a&nbsp;=&gt;&nbsp;a.WithCity(<span style="color:#a31515;">&quot;Paris&quot;</span>)).Build(); </pre> </p> <p> To be clear: such a static <code>Builder</code> class is a Test Utility API specific to your unit tests. It would often be defined in a completely different file than the <code>Builder&lt;T&gt;</code> class, perhaps even in separate libraries. </p> <p> <strong>Summary</strong> </p> <p> Instead of trying to automate Test Data Builders to the letter of the original design pattern description, you can define a single, reusable, generic <code>Builder&lt;T&gt;</code> class. It enables you to achieve some of the expressivity of Test Data Builders. </p> <p> If you still don't find this strategy's prospects fertile, I understand. We're not done, though. In the next article, you'll see why <code>Select</code> is an appropriate name for the Builder's most important method, and how it relates to good abstractions. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/08/28/the-builder-functor">The Builder functor</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment"> <div class="comment-author"><a href="https://mikhail.io/about/">Mikhail Shilkov</a></div> <div class="comment-content"> <p>When I found myself writing too many With() methods, I created an extension to <a href="https://github.com/Fody/Fody">Fody</a> code weaving tool: <a href="https://github.com/mikhailshilkov/With.Fody">Fody.With</a>.</p> <p>Basically I declare the With() methods without body implementation, and then Fody does the implementation for me. It can also convert a generic version to N overloads with an implementation per each public property.</p> <p>The link about has some usage examples, that hopefully make the idea clear.</p> </div> <div class="comment-date">2017-08-21 12:32 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://github.com/harshdeep21">Harshdeep Mehta</a></div> <div class="comment-content"> <p>C# does have <a href="https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/how-to-initialize-objects-by-using-an-object-initializer"> Object Initializer</a> to build "address" with specified "city", similar to F# and Haskell.</p> </div> <div class="comment-date">2017-08-22 12:40 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Harshdeep, thank you for writing. C# object initialisers aren't the same as <a href="https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/copy-and-update-record-expressions">F# Copy and Update Record Expressions</a>. Unless I misunderstand what you mean, when you write </p> <p> <pre><span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;{&nbsp;City&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>&nbsp;}; </pre> </p> <p> <code>address</code> will have <code>"Paris"</code> as <code>City</code>, but all other properties, such as <code>Street</code> and <code>PostCode</code> will be null. That's not what I want. That's the problem the Test Data Builder pattern attempts to address. Test values should be populated with 'good' values, not null. </p> <p> I admit that I'm not keeping up with the latest developments in C#, but if I try to use the C# object initializer syntax with an existing value, like this: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;defaultAddress&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;{&nbsp;Street&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>,&nbsp;PostCode&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;DomainModel.<span style="color:#2b91af;">PostCode</span>(),&nbsp;City&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>&nbsp;}; <span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;defaultAddress&nbsp;{&nbsp;City&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Paris&quot;</span>&nbsp;};</pre> </p> <p> it doesn't compile. </p> <p> I'm still on Visual Studio 2015, though, so that may be it... </p> </div> <div class="comment-date">2017-08-22 13:27 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://github.com/harshdeep21">Harshdeep Mehta</a></div> <div class="comment-content"> <p>Aah. Now I get it. Thanks for explaining. I am from C# world and certainly not into F# yet so I missunderstood "Copy &amp; Update Expression" with "Object Initializer".</p> </div> <div class="comment-date">2017-08-23 5:22 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Test Data Builders in C# http://blog.ploeh.dk/2017/08/15/test-data-builders-in-c 2017-08-15T06:20:00+00:00 Mark Seemann <div id="post"> <p> <em>A brief recap of the Test Data Builder design pattern with examples in C#.</em> </p> <p> This is the first in <a href="http://blog.ploeh.dk/2017/08/14/from-test-data-builders-to-the-identity-functor">a series of articles about the relationship between the Test Data Builder design pattern, and the identity functor</a>. </p> <p> In 2007 <a href="http://www.natpryce.com">Nat Pryce</a> described the <a href="http://www.natpryce.com/articles/000714.html">Test Data Builder</a> design pattern. The original article is easy to read, but in case you don't want to read it, here's a quick summary, with some of Nat Pryce's examples translated to C#. </p> <p> The purpose of a Test Data Builder is to make it easy to create input data (or objects) for unit tests. Imagine, for example, that for a particular test case, you need an address in Paris; no other values matter. With a Test Data Builder, you can write an expression that gives you such a value: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>().WithCity(<span style="color:#a31515;">&quot;Paris&quot;</span>).Build(); </pre> </p> <p> The <code>address</code> object explicity has a <code>City</code> value of <code>"Paris"</code>. Any other values are default values defined by <code>AddressBuilder</code>. The values are there, but when they're unimportant to a particular test case, you don't have to specify them. To <a href="http://amzn.to/19W4JHk">paraphrase Robert C. Martin</a>, this eliminates the irrelevant, and amplifies the essentials of the test. </p> <p> <strong>Address Builder</strong> </p> <p> An <code>AddressBuilder</code> could look like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">string</span>&nbsp;street; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">string</span>&nbsp;city; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">PostCode</span>&nbsp;postCode; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;AddressBuilder() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.street&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.city&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.postCode&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PostCodeBuilder</span>().Build(); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>&nbsp;WithStreet(<span style="color:blue;">string</span>&nbsp;newStreet) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.street&nbsp;=&nbsp;newStreet; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>&nbsp;WithCity(<span style="color:blue;">string</span>&nbsp;newCity) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.city&nbsp;=&nbsp;newCity; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>&nbsp;WithPostCode(<span style="color:#2b91af;">PostCode</span>&nbsp;newPostCode) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.postCode&nbsp;=&nbsp;newPostCode; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>&nbsp;WithNoPostcode() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.postCode&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PostCode</span>(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;Build() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:blue;">this</span>.street,&nbsp;<span style="color:blue;">this</span>.city,&nbsp;<span style="color:blue;">this</span>.postCode); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> The <code>Address</code> class is simpler than the Builder: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Address</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">string</span>&nbsp;Street&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;<span style="color:blue;">set</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">string</span>&nbsp;City&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;<span style="color:blue;">set</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">PostCode</span>&nbsp;PostCode&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;<span style="color:blue;">set</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;Address(<span style="color:blue;">string</span>&nbsp;street,&nbsp;<span style="color:blue;">string</span>&nbsp;city,&nbsp;<span style="color:#2b91af;">PostCode</span>&nbsp;postCode) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Street&nbsp;=&nbsp;street; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.City&nbsp;=&nbsp;city; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.PostCode&nbsp;=&nbsp;postCode; &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> Clearly, this class could contain some behaviour, but in order to keep the example as simple as possible, it's only a simple Data Transfer Object. </p> <p> <strong>Composition</strong> </p> <p> Given that <code>AddressBuilder</code> is more complicated than <code>Address</code> itself, the benefit of the pattern may seem obscure, but one of the benefits is that Test Data Builders easily compose: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;invoice&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InvoiceBuilder</span>() &nbsp;&nbsp;&nbsp;&nbsp;.WithRecipient(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">RecipientBuilder</span>() &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.WithAddress(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>() &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.WithNoPostcode() &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Build()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Build()) &nbsp;&nbsp;&nbsp;&nbsp;.Build();</pre> </p> <p> Perhaps that looks verbose, but in general, the alternative is worse. If you didn't have a <a href="http://xunitpatterns.com/Test%20Utility%20Method.html">Test Utility Method</a>, you'd have to fill in <em>all</em> the required data for the object: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;invoice&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Invoice</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Recipient</span>(<span style="color:#a31515;">&quot;Sherlock&nbsp;Holmes&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:#a31515;">&quot;221b&nbsp;Baker&nbsp;Street&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;London&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PostCode</span>())), &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">List</span>&lt;<span style="color:#2b91af;">InvoiceLine</span>&gt;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InvoiceLine</span>(<span style="color:#a31515;">&quot;Deerstalker&nbsp;Hat&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PoundsShillingsPence</span>(0,&nbsp;3,&nbsp;10)), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InvoiceLine</span>(<span style="color:#a31515;">&quot;Tweed&nbsp;Cape&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PoundsShillingsPence</span>(0,&nbsp;4,&nbsp;12))});</pre> </p> <p> Here, the important detail drowns in data. The post code is empty because the <code>PostCode</code> constructor is called without arguments. This hardly jumps out when you see it. Such code neither eliminates the irrelevant, nor amplifies the essential. </p> <p> <strong>Summary</strong> </p> <p> Test Data Builders are useful because they are good abstractions. They enable you to write <a href="http://blog.ploeh.dk/2013/04/02/why-trust-tests">unit tests that you can trust</a>. </p> <p> The disadvantage, as you shall see, is that in languages like C# and Java, much boilerplate code is required. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/08/21/generalised-test-data-builder">Generalised Test Data Builder</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment"> <div class="comment-author"><a href="http://blog.developers.win">Mike-EEE</a></div> <div class="comment-content">You got me to finally figure out how to post comments. :) Hope everything looks alright.<br><br> So first off, great article as always. You totally hit a subject which has been driving me nuts, personally and lately. I have been developing my first FluentAPI and have been running up against both aspects of immutability and query/command separation that you have done an excellent job of presenting here on your blog. It does seem that FluentAPI design and the builder pattern you present above deviate from these principles, so it would be great to hear a little more context and valuable insight from you on how you reconcile this. Is this perhaps a C# issue that is easily remedied in F#? Thank you in advance for any assistance and for providing such a valuable technical resource here. It's been my favorite for many years now. </div> <div class="comment-date">2017-08-15 06:52 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Mike, thank you for writing. The <a href="https://martinfowler.com/bliki/FluentInterface.html">fluent interface</a> that I show in this article is the most common form you see in C#. While it's not my preferred variation, I use it in this article because it's a direct translation of the style used in Nat Pryce's Java code. </p> <p> Ordinarily, I prefer an immutable variant, but in C# this leads to even more boilerplate code, and I didn't want to sidetrack the topic by making this recap article more complicated than absolutely necessary. </p> <p> You may be pleased to learn that future articles in this very article series will show alternatives in both C#, F#, and Haskell. </p> </div> <div class="comment-date">2017-08-15 07:30 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://gist.github.com/jand187">JanD</a></div> <div class="comment-content"> <p>Hi Mark, A while ago I made a generic builder for this exact purpose. I also made som helper extension methods, that could act as sort of an Object Mother. I quite like how it work and I have used it quite a few times. So, reading this post, I thought I'd put in a link to it, as it might be usefull to other readers.</p> <p><a href="https://gist.github.com/jand187/cabd16971097b5beb4c3">Generic Builder with Object Mother Gist</a></p> <p>It's all in one big gist and probably not very weel structured, but if you look at the class GenericBuilder it should be quite easily understood. The examples of extensionmethods can be seen towards the end of the file.</p> </div> <div class="comment-date">2017-08-15 07:42 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://github.com/mrmorcs">James Morcom</a></div> <div class="comment-content"> <p>I've used test data builders in C# just like this in the past, and couldn't decide whether I liked them or not, due to all the boilerplate.</p> <p>I'm looking forward to the next few posts, thanks for doing this.</p> </div> <div class="comment-date">2017-08-18 11:43 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://www.linkedin.com/in/rpajak/">Robert Pajak</a></div> <div class="comment-content"> <p>Hi, Mark</p> <p>In C# I starated to prefer to use a "parameterized object mother". Please take a look and tell me what out think about it: <a href="https://gist.github.com/Pellared/a31b6955af5c61a56a277a50606c3410">Address Object Mother Gist</a>.</p> <p>From my experience it is less and simplier code. It is also a bid easier to debug. Personally, the Object Mother is the first pattern when refactoring test data creationg and I use Fluent Test Data Builder only in more complex scenarios.</p> <p>@JanD: Unfortunately, your solution would not work for immutable data structures (which I prefer).</p> </div> <div class="comment-date">2017-08-19 19:25 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Robert, thank you for writing. I haven't seen that particular C# variation before, but it looks useful. I hope that as this article series progresses, it should become increasingly clear to the reader that the Test Data Builder pattern addresses various language deficiencies. (It has, by the way, for some time been a common criticism of design patterns in general that they are nothing but patches on language deficiencies. I don't think that I agree with that 100 percent, but I certainly understand the argument.) </p> <p> Nat Pryce's original article about the Test Data Builder pattern is from 2007 with example code in Java. I don't know that much about Java, but back then, I don't think C# had optional arguments (as far as I can tell, that language feature was added in 2010). My point is that the pattern described a good way to model code given the language features that were available at the time. </p> <p> As a general rule, I'm not a fan of C#'s optional argument feature (because I'm concerned what it does to forwards and backwards compatibility of my APIs), but used in the way you suggest it does look useful. Perhaps it does, indeed, address all the concerns that the Test Data Builder pattern addresses. I haven't tried it, so I can't really evaluate it (yet), but it looks like it'd be worth trying out. </p> <p> My overall goal with this article series is, however, slightly different. In fact, I'm not trying to sell the Test Data Builder pattern to anyone. Rather, the point is that with better API design, and with better languages, it'd be largely redundant. </p> </div> <div class="comment-date">2017-08-21 06:33 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://www.linkedin.com/in/romainvasseur/">Romain Vasseur</a></div> <div class="comment-content"> <p>Hi, Mark<br>Thank you for this post</p> <p>I personally leverage <a href="https://github.com/ekonbenefits/impromptu-interface">Impromptu Interface</a>. It could be also verbose but as you only provide meaningful data it fits to Robert C. Martin credo. And it avoids creating a lot of one-shot boilerplate code and/or noising existing classes with UT specific stuff.</p> </div> <div class="comment-date">2017-08-21 09:12 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Romain, do you have an example of that, that you could share? </p> </div> <div class="comment-date">2017-08-21 09:49 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://www.linkedin.com/in/romainvasseur/">Romain Vasseur</a></div> <div class="comment-content"> <p>Partial <code>IAddress</code> with <code>City</code> value only:</p> <pre><span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;City = <span style="color:#a31515;">&quot;Paris&quot;</span> &nbsp;&nbsp;}.ActLike&lt;<span style="color:#2b91af;">IAddress&gt;</span>(); </pre> <p>Partial <code>IAddress</code> with <code>City</code> value and partial <code>IPostCode</code> with <code>ISO</code> value only:</p> <pre><span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;City = <span style="color:#a31515;">&quot;Paris&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;PostCode = <span style="color:blue;">new</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ISO = <span style="color:#a31515;">&quot;FR&quot;</span> &nbsp;&nbsp;&nbsp;}.ActLike&lt;<span style="color:#2b91af;">IPostCode&gt;</span>() &nbsp;&nbsp;}.ActLike&lt;<span style="color:#2b91af;">IAddress&gt;</span>(); </pre> <p>Main drawback is verbosity but intent is pretty clear.<br>We could reduce nested code by splitting <code>IAddress</code> and <code>IPostCode</code> declarations but it also reduces intent: we do not care about <code>IPostCode</code>, we care about <code>IAddress</code> and <code>IPostCode</code> is only an implementation detail.</p> <p>I heavily leverage <code>region</code> to cope with C# verbosity and to highlight common pattern - AAA in this case - so all this code is usually hidden in one <code>ARRANGE</code> region.<br>When I need multiple declaration I used <code>sut</code> (System Under Test) marker to highlight main actor.</p> </div> <div class="comment-date">2017-08-21 21:09 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Do I understand it correctly that you'd have an interface like the following, then? </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IAddress</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;City&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;<span style="color:blue;">set</span>;&nbsp;} }</pre> </p> <p> I'm not sure that I quite follow... </p> </div> <div class="comment-date">2017-08-22 11:43 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://www.linkedin.com/in/romainvasseur/">Romain Vasseur</a></div> <div class="comment-content"> <p> Mark, I tend to avoid <code>setter</code> in my interfaces so my domain objects usually are immutable and only expose <code>getter</code>.<br> My implementation are mainly internal which prevent them to be used directly from within UT assembly (without using InternalsVisibleTo attribute).<br> I have factories - which implementation are also internal - to build my objects.<br>I then use an IoC container to access factories and create my objects. </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IAddress</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;City&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;Street&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IPostCode</span>&nbsp;PostCode&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} }</pre> </p> <p> <code>AddressBuilder</code> lives in UT world so must be in another assembly to avoid noising my model. <br>To cope with my internal visibility constraint I have at least 2 options I can live with: <ol><li>Using InternalsVisibleTo attribute for my UT assembly to be able to seamlessly use my types <li>Leveraging a test container to resolve my factory and then create my objects. </ol> To deal with the immutable constraint I can create new ones within <code>With</code> methods. I can live with this too. <br><br>The main drawback remains the verbosity/burden of those methods. <br>Using <a href="https://github.com/ekonbenefits/impromptu-interface">Impromptu Interface</a> to generate partial test data spares builder classes creation while keeping verbosity acceptable and intent clear. <br>Does it make sense? </p> </div> <div class="comment-date">2017-08-22 13:24 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> That helps clarify things, thank you. </p> <p> I know that obviously, I could try for myself, but when you write </p> <p> <pre><span style="color:blue;">var</span>&nbsp;address&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;City = <span style="color:#a31515;">&quot;Paris&quot;</span> &nbsp;&nbsp;}.ActLike&lt;<span style="color:#2b91af;">IAddress&gt;</span>();</pre> </p> <p> then what will be the value of <code>address.PostCode</code>? </p> </div> <div class="comment-date">2017-08-22 13:40 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://www.linkedin.com/in/romainvasseur/">Romain Vasseur</a></div> <div class="comment-content"> <u>It throws an exception if accessed but live peacefully otherwise</u>. It is why I talked about <span style="color:#a31515;">partial</span> data.<br> You have to be aware of this. When your test focus on a single aspect of your class you can safely use it.<br> Imagine you are testing a <code>City</code> centric algorithm: you do not care about Street, Street number, Floor, and so on.<br> No need to create heavy/costly objects you can safely use a partial object which is only compliant with a part of the original interface.<br> The way you would have deal with if you had split <span style="color:#2b91af;">IAddress</span> interface into several parts namely <span style="color:#2b91af;">IHaveACity</span>, <span style="color:#2b91af;">IHaveAStreet</span>, ...<br> As it only declares what it needs to work the UT intent is pretty clear. As test builder it removes noisy stuff. </div> <div class="comment-date">2017-08-22 14:22 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Now I think I get it! Thank you for taking the time to explain. </p> </div> <div class="comment-date">2017-08-22 14:50 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://stackoverflow.com/users/129073/gebb">Otto Gebb</a></div> <div class="comment-content"> <p>A slight variation on Robert Pajak's approach that allows writing <code>an.Address()</code> instead of unwieldy <code>AddressObjectMother.Create()</code>: <a href="https://softwareengineering.stackexchange.com/a/286403/105014">Mother Factory</a>.</p> <p>Another usage sample: <a href="https://gist.github.com/M0ns1gn0r/72dc43187418118c68d413d0eedb881d">gist</a>. </div> <div class="comment-date">2017-09-12 9:16 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. From Test Data Builders to the identity functor http://blog.ploeh.dk/2017/08/14/from-test-data-builders-to-the-identity-functor 2017-08-14T11:34:00+00:00 Mark Seemann <div id="post"> <p> <em>The Test Data Builder unit testing design pattern is closely related to the identity functor.</em> </p> <p> The <a href="http://www.natpryce.com/articles/000714.html">Test Data Builder</a> design pattern is a valuable technique for managing data for unit testing. It enables you to express test cases in such a way that the important parts of the test case stands out in your code, while the unimportant parts disappear. It perfectly fits <a href="http://amzn.to/19W4JHk">Robert C. Martin's definition</a> of an <em>abstraction:</em> <blockquote> "Abstraction is the elimination of the irrelevant and the amplification of the essential" </blockquote> Not only are Test Data Builders great abstractions, but they're also eminently composable. You can use fine-grained Test Data Builders as building blocks for more complex Test Data Builders. This turns out to be more than a coincidence. In this series of articles, you'll learn how Test Data Builders are closely related to the <em>identity functor</em>. If you don't know what a functor is, then keep reading; you'll learn about functors as well. <ol> <li><a href="http://blog.ploeh.dk/2017/08/15/test-data-builders-in-c">Test Data Builders in C#</a></li> <li><a href="http://blog.ploeh.dk/2017/08/21/generalised-test-data-builder">Generalised Test Data Builder</a></li> <li><a href="http://blog.ploeh.dk/2017/08/28/the-builder-functor">The Builder functor</a></li> <li><a href="http://blog.ploeh.dk/2017/09/04/builder-as-identity">Builder as Identity</a></li> <li><a href="http://blog.ploeh.dk/2017/09/11/test-data-without-builders">Test data without Builders</a></li> <li>(<a href="http://blog.ploeh.dk/2017/09/18/the-test-data-generator-functor">The Test Data Generator functor</a>)</li> </ol> By reading these articles, you'll learn the following: <ul> <li>How to make your code easier to use in unit tests.</li> <li>What a functor is.</li> <li>How Test Data Builders generalise.</li> <li>Why Test Data Builders are composable.</li> </ul> If you've ever struggled with defining good abstractions, learning about functors (and some related concepts) will help. </p> <p> For readers wondering if this is 'yet another monad tutorial', it's not; it's a functor tutorial. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/08/15/test-data-builders-in-c">Test Data Builders in C#</a>. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. F# free monad recipe http://blog.ploeh.dk/2017/08/07/f-free-monad-recipe 2017-08-07T08:11:00+00:00 Mark Seemann <div id="post"> <p> <em>How to create free monads in F#.</em> </p> <p> This is not a design pattern, but it's something related. Let's call it a <em>recipe</em>. A design pattern should, in my opinion, be fairly language-agnostic (although <a href="http://blog.ploeh.dk/2012/05/25/Designpatternsacrossparadigms">hardly universally applicable</a>). This article, on the contrary, specifically addresses a problem in F#: </p> <p class="text-center"> <em>How do you create a free monad in F#?</em> </p> <p class="text-center"> <strong>By following the present recipe.</strong> </p> <p> The recipe here is a step-by-step process, but be sure to first read the sections on motivation and when to use it. A free monads isn't a goal in itself. </p> <p> This article doesn't attempt to <em>explain</em> the details of free monads, but instead serve as a reference. For an introduction to free monads, I think my article <a href="http://blog.ploeh.dk/2017/06/27/pure-times">Pure times</a> is a good place to start. See also the <em>Motivating examples</em> section, below. </p> <p> <strong>Motivation</strong> </p> <p> A frequently asked question about F# is: <a href="https://stackoverflow.com/q/34011895/126014">what's the F# equivalent to an interface?</a> There's no single answer to this question, because, as always, It Depends&trade;. Why do you need an interface in the first place? What is its intended use? </p> <p> Sometimes, in OOP, an interface can be used for a <a href="https://en.wikipedia.org/wiki/Strategy_pattern">Strategy</a>. This enables you to dynamically replace or select between different (sub)algorithms at run-time. If the algorithm is <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a>, then an <a href="http://blog.ploeh.dk/2015/08/03/idiomatic-or-idiosyncratic">idiomatic</a> F# equivalent would be <em>a function</em>. </p> <p> At other times, though, the person asking the question has Dependency Injection in mind. In OOP, dependencies are often modelled as interfaces with several members. Such <a href="http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection">dependencies are systematically impure</a>, and thereby not part of functional design. If at all possible, <a href="http://blog.ploeh.dk/2017/07/10/pure-interactions">prefer impure/pure/impure sandwiches over interactions</a>. Sometimes, however, you'll need something that works like an interface or abstract base class. Free monads can address such situations. </p> <p> In general, a <a href="https://twitter.com/hmemcpy/status/771359835514368000">free monad allows you to build a monad from any functor</a>, but why would you want to do that? The most common reason I've encountered is exactly in order to model impure interactions in a pure manner; in other words: Dependency Injection. </p> <p> <strong>Refactor interface to functor</strong> </p> <p> This recipe comes in three parts: <ol> <li>A recipe for refactoring interfaces to a functor.</li> <li>The core recipe for creating a monad from any functor.</li> <li>A recipe for adding an interpreter.</li> </ol> The universal recipe for creating a monad from any functor follows in a later section. In this section, you'll see how to refactor an interface to a functor. </p> <p> Imagine that you have an interface that you'd like to refactor. In C# it might look like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IFace</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Out1</span>&nbsp;Member1(<span style="color:#2b91af;">In1</span>&nbsp;input); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Out2</span>&nbsp;Member2(<span style="color:#2b91af;">In2</span>&nbsp;input); }</pre> </p> <p> In F#, it'd look like this: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">IFace</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">abstract</span>&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:navy;">Member1</span>&nbsp;:&nbsp;input:<span style="color:teal;">In1</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:teal;">Out1</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">abstract</span>&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:navy;">Member2</span>&nbsp;:&nbsp;input:<span style="color:teal;">In2</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:teal;">Out2</span></pre> </p> <p> I've deliberately kept the interface vague and abstract in order to showcase the <em>recipe</em> instead of a particular example. For realistic examples, refer to the <em>examples</em> section, further down. </p> <p> To refactor such an interface to a functor, do the following: <ol> <li>Create a discriminated union. Name it after the interface name, but append the word <em>instruction</em> as a suffix.</li> <li>Make the union type generic.</li> <li> For each member in the interface, add a case. <ol> <li>Name the case after the name of the member.</li> <li>Declare the type of data contained in the case as a <em>pair</em> (a two-element tuple).</li> <li>Declare the type of the first element in that tuple as the type of the input argument(s) to the interface member. If the member has more than one input argument, declare it as a (nested) tuple.</li> <li>Declare the type of the second element in the tuple as a function. The <em>input</em> type of that function should be the output type of the original interface member, and the output type of the function should be the generic type argument for the union type.</li> </ol> </li> <li>Add a <em>map</em> function for the union type. I'd recommend making this function private and avoid naming it <code>map</code> in order to prevent naming conflicts. I usually name this function <code>mapI</code>, where the <em>I</em> stands for <em>instruction</em>.</li> <li>The <em>map</em> function should take a function of the type <code>'a -&gt; 'b</code> as its first (curried) argument, and a value of the union type as its second argument. It should return a value of the union type, but with the generic type argument changed from <code>'a</code> to <code>'b</code>.</li> <li>For each case in the union type, map it to a value of the same case. Copy the (non-generic) first element of the pair over without modification, but compose the function in the second element with the input function to the <em>map</em> function.</li> </ol> Following that recipe, the above interface becomes this union type: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">FaceInstruction</span>&lt;&#39;a&gt;&nbsp;= |&nbsp;<span style="color:navy;">Member1</span>&nbsp;<span style="color:blue;">of</span>&nbsp;(<span style="color:teal;">In1</span>&nbsp;*&nbsp;(<span style="color:teal;">Out1</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;&#39;a)) |&nbsp;<span style="color:navy;">Member2</span>&nbsp;<span style="color:blue;">of</span>&nbsp;(<span style="color:teal;">In2</span>&nbsp;*&nbsp;(<span style="color:teal;">Out2</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;&#39;a))</pre> </p> <p> The <em>map</em> function becomes: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;FaceInstruction&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;FaceInstruction&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:#9b9b9b;">mapI</span>&nbsp;<span style="color:navy;">f</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Member1</span>&nbsp;(x,&nbsp;<span style="color:navy;">next</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Member1</span>&nbsp;(x,&nbsp;<span style="color:navy;">next</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">f</span>) &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Member2</span>&nbsp;(x,&nbsp;<span style="color:navy;">next</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Member2</span>&nbsp;(x,&nbsp;<span style="color:navy;">next</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">f</span>)</pre> </p> <p> Such a combination of union type and <em>map</em> function satisfies the functor laws, so that's how you refactor an interface to a functor. </p> <p> <strong>Free monad recipe</strong> </p> <p> Given any functor, you can create a monad. The monad will be a new type that contains the functor; you will not be turning the functor itself into a monad. (Some functors can be turned into monads themselves, but if that's the case, you don't need to create a free monad.) </p> <p> The recipe for turning any functor into a monad is as follows: <ol> <li>Create a generic discriminated union. You can name it after the underlying functor, but append a suffix such as <em>Program</em>. In the following, this is called the 'program' union type.</li> <li>Add two cases to the union: <code>Free</code> and <code>Pure</code>.</li> <li>The <code>Free</code> case should contain a single value of the contained functor, generically typed to the 'program' union type itself. This is a recursive type definition.</li> <li>The <code>Pure</code> case should contain a single value of the union's generic type.</li> <li>Add a <code>bind</code> function for the new union type. The function should take two arguments:</li> <li>The first argument to the <code>bind</code> function should be a function that takes the generic type argument as input, and returns a value of the 'program' union type as output. In the rest of this recipe, this function is called <code>f</code>.</li> <li>The second argument to the <code>bind</code> function should be a 'program' union type value.</li> <li>The return type of the <code>bind</code> function should be a 'program' union type value, with the same generic type as the return type of the first argument (<code>f</code>).</li> <li>Declare the <code>bind</code> function as recursive by adding the <code>rec</code> keyword.</li> <li>Implement the <code>bind</code> function by pattern-matching on the <code>Free</code> and <code>Pure</code> cases:</li> <li>In the <code>Free</code> case, pipe the contained functor value to the functor's <em>map</em> function, using <code>bind f</code> as the mapper function; then pipe the result of that to <code>Free</code>.</li> <li>In the <code>Pure</code> case, return <code>f x</code>, where <code>x</code> is the value contained in the <code>Pure</code> case.</li> <li>Add a computation expression builder, using <code>bind</code> for <code>Bind</code> and <code>Pure</code> for <code>Return</code>.</li> </ol> Continuing the above example, the 'program' union type becomes: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">FaceProgram</span>&lt;&#39;a&gt;&nbsp;= |&nbsp;<span style="color:navy;">Free</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">FaceInstruction</span>&lt;<span style="color:teal;">FaceProgram</span>&lt;&#39;a&gt;&gt; |&nbsp;<span style="color:navy;">Pure</span>&nbsp;<span style="color:blue;">of</span>&nbsp;&#39;a</pre> </p> <p> It's worth noting that the <code>Pure</code> case always looks like that. While it doesn't take much effort to write it, you could copy and paste it from another free monad, and no changes would be required. </p> <p> According to the recipe, the <code>bind</code> function should be implemented like this: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;FaceProgram&lt;&#39;b&gt;)&nbsp;-&gt;&nbsp;FaceProgram&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;FaceProgram&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;<span style="color:navy;">bind</span>&nbsp;<span style="color:navy;">f</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> |&nbsp;<span style="color:navy;">Free</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x&nbsp;|&gt;&nbsp;<span style="color:navy;">mapI</span>&nbsp;(<span style="color:navy;">bind</span>&nbsp;<span style="color:navy;">f</span>)&nbsp;|&gt;&nbsp;<span style="color:navy;">Free</span> |&nbsp;<span style="color:navy;">Pure</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x</pre> </p> <p> Apart from one small detail, the <code>bind</code> function always looks like that, so you can often copy and paste it from here and use it in your code, if you will. The only variation is that the underlying functor's <em>map</em> function isn't guaranteed to be called <code>mapI</code> - but if it is, you can use the above <code>bind</code> function as is. No modifications will be necessary. </p> <p> In F#, a monad is rarely a goal in itself, but once you have a monad, you can add a <a href="https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/computation-expressions">computation expression builder</a>: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;FaceBuilder&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.Bind&nbsp;(x,&nbsp;f)&nbsp;=&nbsp;bind&nbsp;f&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.Return&nbsp;x&nbsp;=&nbsp;Pure&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.ReturnFrom&nbsp;x&nbsp;=&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.Zero&nbsp;()&nbsp;=&nbsp;Pure&nbsp;()</pre> </p> <p> While you could add more members (such as <code>Combine</code>, <code>For</code>, <code>TryFinally</code>, and so on), I find that usually, those four methods are all I need. </p> <p> Create an instance of the builder object, and you can start writing computation expressions: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;face&nbsp;=&nbsp;FaceBuilder&nbsp;() </pre> </p> <p> Finally, as an optional step, if you've refactored an interface to an instruction set, you can add convenience functions that lift each instruction case to the free monad type: <ol> <li>For each case, add a function of the same name, but camelCased instead of PascalCased.</li> <li>Each function should have input arguments that correspond to the first element of the case's contained tuple (i.e. the input argument for the original interface). I usually prefer the arguments in curried form, but that's not a requirement.</li> <li>Each function should return the corresponding instruction union case inside of the <code>Free</code> case. The case constructor must be invoked with the pair of data it requires. Populate the first element with values from the input arguments to the convenience function. The second element should be the <code>Pure</code> case constructor, passed as a function.</li> </ol> In the current example, that would be two functions, one for each case of <code>FaceInstruction&lt;'a&gt;</code>: </p> <p> <pre><span style="color:green;">//&nbsp;In1&nbsp;-&gt;&nbsp;FaceProgram&lt;Out1&gt;</span> <span style="color:blue;">let</span>&nbsp;member1&nbsp;in1&nbsp;=&nbsp;Free&nbsp;(Member1&nbsp;(in1,&nbsp;Pure)) <span style="color:green;">//&nbsp;In2&nbsp;-&gt;&nbsp;FaceProgram&lt;Out2&gt;</span> <span style="color:blue;">let</span>&nbsp;member2&nbsp;in2&nbsp;=&nbsp;Free&nbsp;(Member2&nbsp;(in2,&nbsp;Pure))</pre> </p> <p> Such functions are conveniences that make it easier to express what the underlying functor expresses, but in the context of the free monad. </p> <p> <strong>Interpreters</strong> </p> <p> A free monad is a recursive type, and values are trees. The leafs are the <code>Pure</code> values. Often (if not always), the point of a free monad is to evaluate the tree in order to pull the leaf values out of it. In order to do that, you must add an interpreter. This is a function that recursively pattern-matches over the free monad value until it encounters a <code>Pure</code> case. </p> <p> At least in the case where you've refactored an interface to a functor, writing an interpreter also follows a recipe. This is equivalent to writing a concrete class that implements an interface. <ol> <li>For each case in the instruction-set functor, write an implementation function that takes the case's 'input' tuple element type as input, and returns a value of the type used in the case's second tuple element. Recall that the second element in the pair is a function; the output type of the implementation function should be the input type for that function.</li> <li>Add a function to implement the interpreter; I often call it <code>interpret</code>. Make it recursive by adding the <code>rec</code> keyword.</li> <li>Pattern-match on <code>Pure</code> and each case contained in <code>Free</code>.</li> <li>In the <code>Pure</code> case, simply return the value contained in the case.</li> <li>In the <code>Free</code> case, pattern-match the underlying pair out if each of the instruction-set functor's cases. The first element of that tuple is the 'input value'. Pipe that value to the corresponding implementation function, pipe the return value of that to the function contained in the second element of the tuple, and pipe the result of that recursively to the interpreter function.</li> </ol> Assume that two implementation functions <code>imp1</code> and <code>imp2</code> exist. According to the recipe, <code>imp1</code> has the type <code>In1 -&gt; Out1</code>, and <code>imp2</code> has the type <code>In2 -&gt; Out2</code>. Given these functions, the running example becomes: </p> <p> <pre><span style="color:green;">//&nbsp;FaceProgram&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;&#39;a</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;interpret&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Pure&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Free&nbsp;(Member1&nbsp;(x,&nbsp;next))&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x&nbsp;|&gt;&nbsp;imp1&nbsp;|&gt;&nbsp;next&nbsp;|&gt;&nbsp;interpret &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Free&nbsp;(Member2&nbsp;(x,&nbsp;next))&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x&nbsp;|&gt;&nbsp;imp2&nbsp;|&gt;&nbsp;next&nbsp;|&gt;&nbsp;interpret</pre> </p> <p> The <code>Pure</code> case always looks like that. Each of the <code>Free</code> cases use a different implementation function, but apart from that, they are, as you can tell, the spitting image of each other. </p> <p> Interpreters like this are often impure because the implementation functions are impure. Nothing prevents you from defining pure interpreters, although they often have limited use. They do have their place in unit testing, though. </p> <p> <pre><span style="color:green;">//&nbsp;Out1&nbsp;-&gt;&nbsp;Out2&nbsp;-&gt;&nbsp;FaceProgram&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;&#39;a</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;interpretStub&nbsp;out1&nbsp;out2&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Pure&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Free&nbsp;(Member1&nbsp;(_,&nbsp;next))&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;out1&nbsp;|&gt;&nbsp;next&nbsp;|&gt;&nbsp;interpretStub&nbsp;out1&nbsp;out2 &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Free&nbsp;(Member2&nbsp;(_,&nbsp;next))&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;out2&nbsp;|&gt;&nbsp;next&nbsp;|&gt;&nbsp;interpretStub&nbsp;out1&nbsp;out2</pre> </p> <p> This interpreter effectively ignores the input value contained within each <code>Free</code> case, and instead uses the pure values <code>out1</code> and <code>out2</code>. This is essentially a <a href="http://xunitpatterns.com/Test%20Stub.html">Stub</a> - an 'implementation' that always returns pre-defined values. </p> <p> The point is that you can have more than a single interpreter, pure or impure, just like you can have more than one implementation of an interface. </p> <p> <strong>When to use it</strong> </p> <p> Free monads are often used instead of Dependency Injection. Note, however, that while the free monad values themselves are pure, they <em>imply</em> impure behaviour. In my opinion, the main benefit of pure code is that, as a code reader and maintainer, I don't have to worry about side-effects if I know that the code is pure. With a free monad, I <em>do</em> have to worry about side-effects, because, although the ASTs are pure, an impure interpreter will cause side-effects to happen. At least, however, the side-effects are <em>known</em>; they're restricted to a small subset of operations. Haskell enforces this distinction, but F# doesn't. The question, then, is how valuable you find this sort of design. </p> <p> I think it still has <em>some</em> value, because a free monad explicitly communicates an intent of doing something impure. This intent becomes encoded in the types in your code base, there for all to see. Just as I prefer that functions return <code>'a option</code> values if they may fail to produce a value, I like that I can tell from a function's return type that a delimited set of impure operations may result. </p> <p> Clearly, creating free monads in F# requires some boilerplate code. I hope that this article has demonstrated that writing that boilerplate code isn't <em>difficult</em> - just follow the recipe. You almost don't have to think. Since a monad is a universal abstraction, once you've written the code, it's unlikely that you'll need to deal with it much in the future. After all, mathematical abstractions don't change. </p> <p> Perhaps a more significant concern is how familiar free monads are to developers of a particular code base. Depending on your position, you could argue that free monads come with high cognitive overhead, or that they specifically <em>lower</em> the cognitive overhead. </p> <p> Insights are obscure until you grasp them; after that, they become clear. </p> <p> This applies to free monads as well. You have to put effort into understanding them, but once you do, you realise that they are more than a pattern. They are universal abstractions, governed by laws. Once you <a href="http://bit.ly/stranger-in-a-strange-land">grok</a> free monads, their cognitive load wane. </p> <p> Consider, then, the developers who will be interacting with the free monad. If they already know free monads, or have enough of a grasp of monads that this might be their next step, then using free monads could be beneficial. On the other hand, if most developers are new to F# or functional programming, free monads should probably be avoided for the time being. </p> <p> This flowchart summarises the above reflections: </p> <p> <img src="/content/binary/decision-flowchart-for-free-monads.png" alt="Decision flowchart for whether or not to choose free monads as a design principle."> </p> <p> Your first consideration should be whether your <a href="http://blog.ploeh.dk/2017/07/10/pure-interactions">context enables an impure/pure/impure sandwich</a>. If so, there's no reason to make things more complicated than they have to be. To use <a href="http://bit.ly/mythical-man-month">Fred Brooks' terminology</a>, this should go a long way to avoid accidental complexity. </p> <p> If you can't avoid long-running, impure interactions, then consider whether purity, or strictly functional design, is important to you. F# is a multi-paradigmatic language, and it's perfectly possible to write code that's impure, yet still well-structured. You can use <a href="http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection">partial application as an idiomatic alternative to Dependency Injection.</a> </p> <p> If you prefer to keep your code functional and explicit, you may consider using free monads. In this case, I still think you should consider the maintainers of the code base in question. If everyone involved are comfortable with free monads, or willing to learn, then I believe it's a viable option. Otherwise, I'd recommend falling back to partial application, even though Dependency Injection makes everything impure. </p> <p> <strong>Motivating examples</strong> </p> <p> The strongest motivation, I believe, for introducing free monads into a code base is to model long-running, impure interactions in a functional style. </p> <p> Like most other software design considerations, the overall purpose of application architecture is to deal with (essential) complexity. Thus, any example must be complex enough to warrant the design. There's little point in a Dependency Injection <em>hello world</em> example in C#. Likewise, a <em>hello world</em> example using free monads hardly seems justified. For that reason, examples are provided in separate articles. </p> <p> A good place to start, I believe, is with the small <a href="http://blog.ploeh.dk/2017/06/27/pure-times">Pure times</a> article series. These articles show how to address a particular, authentic problem using strictly functional programming. The focus of these articles is on problem-solving, so they sometimes omit detailed explanations in order to keep the narrative moving. </p> <p> If you need detailed explanations about all elements of free monads in F#, the <a href="http://blog.ploeh.dk/2017/07/10/pure-interactions">present article series offers just that</a>, particularly the <a href="http://blog.ploeh.dk/2017/07/11/hello-pure-command-line-interaction">Hello, pure command-line interaction</a> article. </p> <p> <strong>Variations</strong> </p> <p> The above recipes describe the regular scenario. Variations are possible. Obviously, you can choose different naming strategies and so on, but I'm not going to cover this in greater detail. </p> <p> There are, however, various degenerate cases that deserve a few words. An interaction may return no data, or take no input. In F#, you can always model the lack of data as <code>unit</code> (<code>()</code>), so it's definitely possible to define an instruction case like <code>Foo of (unit * Out1 -&gt; 'a)</code>, or <code>Bar of (In2 * unit -&gt; 'a)</code>, but since <code>unit</code> doesn't contain any data, you can remove it without changing the abstraction. </p> <p> The <a href="http://blog.ploeh.dk/2017/07/11/hello-pure-command-line-interaction">Hello, pure command-line interaction</a> article contains a single type that exemplifies both degenerate cases. It defines this instruction set: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CommandLineInstruction</span>&lt;&#39;a&gt;&nbsp;= |&nbsp;<span style="color:navy;">ReadLine</span>&nbsp;<span style="color:blue;">of</span>&nbsp;(<span style="color:teal;">string</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;&#39;a) |&nbsp;<span style="color:navy;">WriteLine</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span>&nbsp;*&nbsp;&#39;a</pre> </p> <p> The <code>ReadLine</code> case takes no input, so instead of containing a pair of input and continuation, this case contains only the continuation function. Likewise, the <code>WriteLine</code> case is also degenerate, but here, there's no output. This case <em>does</em> contain a pair, but the second element isn't a function, but a value. </p> <p> This has some superficial consequences for the implementation of functor and monad functions. For example, the <code>mapI</code> function becomes: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;CommandLineInstruction&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;CommandLineInstruction&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:navy;">mapI</span>&nbsp;<span style="color:navy;">f</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">ReadLine</span>&nbsp;<span style="color:navy;">next</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">ReadLine</span>&nbsp;(<span style="color:navy;">next</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">f</span>) &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">WriteLine</span>&nbsp;(x,&nbsp;next)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">WriteLine</span>&nbsp;(x,&nbsp;next&nbsp;|&gt;&nbsp;<span style="color:navy;">f</span>)</pre> </p> <p> Notice that in the <code>ReadLine</code> case, there's no tuple on which to pattern-match. Instead, you can directly access <code>next</code>. </p> <p> In the <code>WriteLine</code> case, the return value changes from function composition (<code>next &gt;&gt; f</code>) to a regular function call (<code>next |&gt; f</code>, which is equivalent to <code>f next</code>). </p> <p> The <em>lift</em> functions also change: </p> <p> <pre><span style="color:green;">//&nbsp;CommandLineProgram&lt;string&gt;</span> <span style="color:blue;">let</span>&nbsp;readLine&nbsp;=&nbsp;Free&nbsp;(ReadLine&nbsp;Pure) <span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;CommandLineProgram&lt;unit&gt;</span> <span style="color:blue;">let</span>&nbsp;writeLine&nbsp;s&nbsp;=&nbsp;Free&nbsp;(WriteLine&nbsp;(s,&nbsp;Pure&nbsp;()))</pre> </p> <p> Since there's no input, <code>readLine</code> degenerates to a value, instead of a function. On the other hand, while <code>writeLine</code> remains a function, you'll have to pass a <em>value</em> (<code>Pure ()</code>) as the second element of the pair, instead of the regular function (<code>Pure</code>). </p> <p> Apart from such minor changes, the omission of <code>unit</code> values for input or output has little significance. </p> <p> Another variation from the above recipe that you may see relates to interpreters. In the above recipe, I described how, for each instruction, you should create an implementation function. Sometimes, however, that function is only a few lines of code. When that happens, I occasionally inline the function directly in the interpreter. Once more, the <code>CommandLineProgram</code> API provides an example: </p> <p> <pre><span style="color:green;">//&nbsp;CommandLineProgram&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;&#39;a</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;<span style="color:navy;">interpret</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Pure</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Free</span>&nbsp;(<span style="color:navy;">ReadLine</span>&nbsp;&nbsp;<span style="color:navy;">next</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:teal;">Console</span>.<span style="color:navy;">ReadLine</span>&nbsp;()&nbsp;|&gt;&nbsp;<span style="color:navy;">next</span>&nbsp;|&gt;&nbsp;<span style="color:navy;">interpret</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Free</span>&nbsp;(<span style="color:navy;">WriteLine</span>&nbsp;(s,&nbsp;next))&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Console</span>.<span style="color:navy;">WriteLine</span>&nbsp;s &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;next&nbsp;|&gt;&nbsp;<span style="color:navy;">interpret</span></pre> </p> <p> Here, no custom implementation functions are required, because <code>Console.ReadLine</code> and <code>Console.WriteLine</code> already exist and serve the desired purpose. </p> <p> <strong>Summary</strong> </p> <p> This article describes a repeatable, and automatable, process for refactoring an interface to a free monad. I've done this enough times now that I believe that this process is always possible, but I have no formal proof for this. </p> <p> I also strongly suspect that the reverse process is possible. For any instruction set elevated to a free monad, I think you should be able to define an object-oriented interface. If this is true, then object-oriented interfaces and AST-based free monads are isomorphic. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Combining free monads in F# http://blog.ploeh.dk/2017/07/31/combining-free-monads-in-f 2017-07-31T12:30:00+00:00 Mark Seemann <div id="post"> <p> <em>An example of how to compose free monads in F#.</em> </p> <p> This article is an instalment in a <a href="http://blog.ploeh.dk/2017/07/10/pure-interactions">series of articles</a> about modelling long-running interactions with <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a>, functional code. In the <a href="http://blog.ploeh.dk/2017/07/24/combining-free-monads-in-haskell">previous article</a>, you saw how to combine a pure command-line API with an HTTP-client API in <a href="https://www.haskell.org">Haskell</a>. In this article, you'll see how to translate the Haskell proof of concept to F#. </p> <p> <strong>HTTP API client module</strong> </p> <p> You've already seen how to model command-line interactions as pure code in <a href="http://blog.ploeh.dk/2017/07/11/hello-pure-command-line-interaction">a previous article</a>. You can define interactions with the online restaurant reservation HTTP API in the same way. First, define some types required for input and output to the API: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">Slot</span>&nbsp;=&nbsp;{&nbsp;Date&nbsp;:&nbsp;<span style="color:teal;">DateTimeOffset</span>;&nbsp;SeatsLeft&nbsp;:&nbsp;<span style="color:teal;">int</span>&nbsp;} <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">Reservation</span>&nbsp;=&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;:&nbsp;<span style="color:teal;">DateTimeOffset</span> &nbsp;&nbsp;&nbsp;&nbsp;Name&nbsp;:&nbsp;<span style="color:teal;">string</span> &nbsp;&nbsp;&nbsp;&nbsp;Email&nbsp;:&nbsp;<span style="color:teal;">string</span> &nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;:&nbsp;<span style="color:teal;">int</span>&nbsp;}</pre> </p> <p> The <code>Slot</code> type contains information about how many available seats are left on a particular date. The <code>Reservation</code> type contains the information required in order to make a reservation. It's the same <code>Reservation</code> F# record type you saw in <a href="http://blog.ploeh.dk/2017/07/17/a-pure-command-line-wizard">a previous article</a>, but now it's moved here. </p> <p> The online restaurant reservation HTTP API may afford more functionality than you need, but there's no reason to model more instructions than required: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">ReservationsApiInstruction</span>&lt;&#39;a&gt;&nbsp;= |&nbsp;<span style="color:navy;">GetSlots</span>&nbsp;<span style="color:blue;">of</span>&nbsp;(<span style="color:teal;">DateTimeOffset</span>&nbsp;*&nbsp;(<span style="color:teal;">Slot</span>&nbsp;<span style="color:teal;">list</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;&#39;a)) |&nbsp;<span style="color:navy;">PostReservation</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">Reservation</span>&nbsp;*&nbsp;&#39;a</pre> </p> <p> This instruction set models two interactions. The <code>GetSlots</code> case models an instruction to request, from the HTTP API, the slots for a particular date. The <code>PostReservation</code> case models an instruction to make a POST HTTP request with a <code>Reservation</code>, thereby making a reservation. </p> <p> While Haskell can automatically make this type a <code>Functor</code>, in F# you have to write the code yourself: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;ReservationsApiInstruction&lt;&#39;a&gt;</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;ReservationsApiInstruction&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:navy;">mapI</span>&nbsp;<span style="color:navy;">f</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">GetSlots</span>&nbsp;(x,&nbsp;<span style="color:navy;">next</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">GetSlots</span>&nbsp;(x,&nbsp;<span style="color:navy;">next</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">f</span>) &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">PostReservation</span>&nbsp;(x,&nbsp;next)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">PostReservation</span>&nbsp;(x,&nbsp;next&nbsp;|&gt;&nbsp;<span style="color:navy;">f</span>)</pre> </p> <p> This turns <code>ReservationsApiInstruction&lt;'a&gt;</code> into a functor, which is, however, not the ultimate goal. The final objective is to enable syntactic sugar, so that you can write pure <code>ReservationsApiInstruction&lt;'a&gt;</code> Abstract Syntax Trees (ASTs) in standard F# syntax. In order to fulfil that ambition, you need a <a href="https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/computation-expressions">computation expression builder</a>, and to create one of those, you need a monad. </p> <p> You can turn <code>ReservationsApiInstruction&lt;'a&gt;</code> into a monad using <a href="http://blog.ploeh.dk/2017/08/07/f-free-monad-recipe">the free monad recipe</a> that you've <a href="http://blog.ploeh.dk/2017/07/11/hello-pure-command-line-interaction">already seen</a>. Creating a free monad, however, involves adding another type that will become both monad and functor, so I deliberately make <code>mapI</code> private in order to prevent confusion. This is also the reason I didn't name the function <code>map</code>: you'll need that name for a different type. The <em>I</em> in <code>mapI</code> stands for <em>instruction</em>. </p> <p> The <code>mapI</code> function pattern-matches on the (implicit) <code>ReservationsApiInstruction</code> argument. In the <code>GetSlots</code> case, it returns a new <code>GetSlots</code> value, but composes the <code>next</code> continuation with <code>f</code>. In the <code>PostReservation</code> case, it returns a new <code>PostReservation</code> value, but pipes <code>next</code> to <code>f</code>. The reason for the difference is that <code>PostReservation</code> is degenerate: <code>next</code> isn't a function, but a value. </p> <p> Now that <code>ReservationsApiInstruction&lt;'a&gt;</code> is a functor, you can create a free monad from it. The first step is to introduce a new type for the monad: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">ReservationsApiProgram</span>&lt;&#39;a&gt;&nbsp;= |&nbsp;<span style="color:navy;">Free</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">ReservationsApiInstruction</span>&lt;<span style="color:teal;">ReservationsApiProgram</span>&lt;&#39;a&gt;&gt; |&nbsp;<span style="color:navy;">Pure</span>&nbsp;<span style="color:blue;">of</span>&nbsp;&#39;a</pre> </p> <p> This is a recursive type that enables you to assemble ASTs that ultimately can return a value. The <code>Pure</code> case enables you to return a value, while the <code>Free</code> case lets you describe what should happen next. </p> <p> Using <code>mapI</code>, you can make a monad out of <code>ReservationsApiProgram&lt;'a&gt;</code> by adding a <code>bind</code> function: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;ReservationsApiProgram&lt;&#39;b&gt;)&nbsp;-&gt;&nbsp;ReservationsApiProgram&lt;&#39;a&gt;</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;ReservationsApiProgram&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;bind&nbsp;f&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Free&nbsp;instruction&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;instruction&nbsp;|&gt;&nbsp;mapI&nbsp;(bind&nbsp;f)&nbsp;|&gt;&nbsp;Free &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Pure&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;f&nbsp;x</pre> </p> <p> If you <a href="http://blog.ploeh.dk/2017/07/11/hello-pure-command-line-interaction">refer back to the <code>bind</code> implementation for <code>CommandLineProgram&lt;'a&gt;</code></a>, you'll see that <em>it's the exact same code</em>. In Haskell, creating a free monad from a functor is automatic. In F#, it's boilerplate. </p> <p> Likewise, you can make <code>ReservationsApiProgram&lt;'a&gt;</code> a functor: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;ReservationsApiProgram&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;ReservationsApiProgram&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;map&nbsp;f&nbsp;=&nbsp;bind&nbsp;(f&nbsp;&gt;&gt;&nbsp;Pure)</pre> </p> <p> Again, this is the same code as in the <code>CommandLine</code> module. You can copy and paste it. It is, however, not the same function, because the types are different. </p> <p> Finally, to round off the reservations HTTP client API, you can supply functions that lift instructions to programs: </p> <p> <pre><span style="color:green;">//&nbsp;DateTimeOffset&nbsp;-&gt;&nbsp;ReservationsApiProgram&lt;Slot&nbsp;list&gt;</span> <span style="color:blue;">let</span>&nbsp;getSlots&nbsp;date&nbsp;=&nbsp;Free&nbsp;(GetSlots&nbsp;(date,&nbsp;Pure)) <span style="color:green;">//&nbsp;Reservation&nbsp;-&gt;&nbsp;ReservationsApiProgram&lt;unit&gt;</span> <span style="color:blue;">let</span>&nbsp;postReservation&nbsp;r&nbsp;=&nbsp;Free&nbsp;(PostReservation&nbsp;(r,&nbsp;Pure&nbsp;()))</pre> </p> <p> That's everything you need to create a small computation expression builder: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">ReservationsApiBuilder</span>&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">Bind</span>&nbsp;(x,&nbsp;<span style="color:navy;">f</span>)&nbsp;=&nbsp;<span style="color:teal;">ReservationsApi</span>.<span style="color:navy;">bind</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">Return</span>&nbsp;x&nbsp;=&nbsp;<span style="color:navy;">Pure</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">ReturnFrom</span>&nbsp;x&nbsp;=&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">Zero</span>&nbsp;()&nbsp;=&nbsp;<span style="color:navy;">Pure</span>&nbsp;()</pre> </p> <p> Create an instance of the <code>ReservationsApiBuilder</code> class in order to use <code>reservationsApi</code> computation expressions: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;reservationsApi&nbsp;=&nbsp;<span style="color:teal;">ReservationsApiBuilder</span>&nbsp;() </pre> </p> <p> This, in total, defines a pure API for interacting with the online restaurant reservation system, including all the syntactic sugar you'll need to stay sane. As usual, some boilerplate code is required, but I'm not too worried about its maintenance overhead, as it's unlikely to change much, once you've added it. If you've followed <a href="http://blog.ploeh.dk/2017/08/07/f-free-monad-recipe">the recipe</a>, the API obeys the category, functor, and monad laws, so it's not something you've invented; it's an instance of a universal abstraction. </p> <p> <strong>Monad stack</strong> </p> <p> The addition of the above <code>ReservationsApi</code> module is only a step towards the overall goal, which is to write a command-line wizard you can use to make reservations against the online API. In order to do so, you must combine the two monads <code>CommandLineProgram&lt;'a&gt;</code> and <code>ReservationsApiProgram&lt;'a&gt;</code>. In Haskell, you get that combination for free via the built-in generic <code>FreeT</code> type, which enables you to stack monads. In F#, you have to explicitly declare the type: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CommandLineReservationsApiT</span>&lt;&#39;a&gt;&nbsp;= |&nbsp;<span style="color:navy;">Run</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">CommandLineProgram</span>&lt;<span style="color:teal;">ReservationsApiProgram</span>&lt;&#39;a&gt;&gt;</pre> </p> <p> This is a single-case discriminated union that stacks <code>ReservationsApiProgram</code> and <code>CommandLineProgram</code>. In this incarnation, it defines a single case called <code>Run</code>. The reason for this is that it enables you to follow the <a href="http://blog.ploeh.dk/2017/08/07/f-free-monad-recipe">free monad recipe</a> without having to do much thinking. Later, you'll see that it's possible to simplify the type. </p> <p> The naming is inspired by Haskell. This type is a piece of the puzzle corresponding to Haskell's <code>FreeT</code> type. The <em>T</em> in <code>FreeT</code> stands for <em>transformer</em>, because <code>FreeT</code> is actually something called a <em>monad transformer</em>. That's not terribly important in an F# context, but that's the reason I also tagged on the <em>T</em> in <code>CommandLineReservationsApiT&lt;'a&gt;</code>. </p> <p> <code>FreeT</code> is actually only a 'wrapper' around another monad. In order to extract the contained monad, you can use a function called <code>runFreeT</code>. That's the reason I called the F# case <code>Run</code>. </p> <p> You can easily make your stack of monads a functor: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;CommandLineProgram&lt;ReservationsApiProgram&lt;&#39;a&gt;&gt;</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;CommandLineProgram&lt;ReservationsApiProgram&lt;&#39;b&gt;&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:navy;">mapStack</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x&nbsp;=&nbsp;<span style="color:blue;">commandLine</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;x&#39;&nbsp;=&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:teal;">ReservationsApi</span>.<span style="color:navy;">map</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x&#39;&nbsp;}</pre> </p> <p> The <code>mapStack</code> function uses the <code>commandLine</code> computation expression to access the <code>ReservationsApiProgram</code> contained within the <code>CommandLineProgram</code>. Thanks to the <code>let!</code> binding, <code>x'</code> is a <code>ReservationsApiProgram&lt;'a&gt;</code> value. You can use <code>ReservationsApi.map</code> to map <code>x'</code> with <code>f</code>. </p> <p> It's now trivial to make <code>CommandLineReservationsApiT&lt;'a&gt;</code> a functor as well: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;CommandLineReservationsApiT&lt;&#39;a&gt;</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;CommandLineReservationsApiT&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;mapT&nbsp;f&nbsp;(Run&nbsp;p)&nbsp;=&nbsp;mapStack&nbsp;f&nbsp;p&nbsp;|&gt;&nbsp;Run</pre> </p> <p> The <code>mapT</code> function simply pattern-matches the monad stack out of the <code>Run</code> case, calls <code>mapStack</code>, and pipes the return value into another <code>Run</code> case. </p> <p> By now, it's should be fairly clear that we're following the same recipe as before. You have a functor; make a monad out of it. First, define a type for the monad: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CommandLineReservationsApiProgram</span>&lt;&#39;a&gt;&nbsp;= |&nbsp;<span style="color:navy;">Free</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">CommandLineReservationsApiT</span>&lt;<span style="color:teal;">CommandLineReservationsApiProgram</span>&lt;&#39;a&gt;&gt; |&nbsp;<span style="color:navy;">Pure</span>&nbsp;<span style="color:blue;">of</span>&nbsp;&#39;a</pre> </p> <p> Then add a <code>bind</code> function: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;CommandLineReservationsApiProgram&lt;&#39;b&gt;)</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;CommandLineReservationsApiProgram&lt;&#39;a&gt;</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;CommandLineReservationsApiProgram&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;bind&nbsp;f&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Free&nbsp;instruction&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;instruction&nbsp;|&gt;&nbsp;mapT&nbsp;(bind&nbsp;f)&nbsp;|&gt;&nbsp;Free &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Pure&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;f&nbsp;x</pre> </p> <p> This is almost the same code as the above <code>bind</code> function for <code>ReservationsApi</code>. The only difference is that the underlying map function is named <code>mapT</code> instead of <code>mapI</code>. The types involved, however, are different. </p> <p> You can also add a <code>map</code> function: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;(CommandLineReservationsApiProgram&lt;&#39;a&gt;</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;CommandLineReservationsApiProgram&lt;&#39;b&gt;)</span> <span style="color:blue;">let</span>&nbsp;map&nbsp;f&nbsp;=&nbsp;bind&nbsp;(f&nbsp;&gt;&gt;&nbsp;Pure)</pre> </p> <p> This is another copy-and-paste job. Such repeatable. Wow. </p> <p> When you create a monad stack, you need a way to lift values from each of the constituent monads up to the combined monad. In Haskell, this is done with the <code>lift</code> and <code>liftF</code> functions, but in F#, you must explicitly add such functions: </p> <p> <pre><span style="color:green;">//&nbsp;CommandLineProgram&lt;ReservationsApiProgram&lt;&#39;a&gt;&gt;</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;CommandLineReservationsApiProgram&lt;&#39;a&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;wrap&nbsp;x&nbsp;=&nbsp;x&nbsp;|&gt;&nbsp;Run&nbsp;|&gt;&nbsp;mapT&nbsp;Pure&nbsp;|&gt;&nbsp;Free <span style="color:green;">//&nbsp;CommandLineProgram&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;CommandLineReservationsApiProgram&lt;&#39;a&gt;</span> <span style="color:blue;">let</span>&nbsp;liftCL&nbsp;x&nbsp;=&nbsp;wrap&nbsp;&lt;|&nbsp;CommandLine.map&nbsp;ReservationsApiProgram.Pure&nbsp;x <span style="color:green;">//&nbsp;ReservationsApiProgram&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;CommandLineReservationsApiProgram&lt;&#39;a&gt;</span> <span style="color:blue;">let</span>&nbsp;liftRA&nbsp;x&nbsp;=&nbsp;wrap&nbsp;&lt;|&nbsp;CommandLineProgram.Pure&nbsp;x</pre> </p> <p> The private <code>wrap</code> function takes the underlying 'naked' monad stack (<code>CommandLineProgram&lt;ReservationsApiProgram&lt;'a&gt;&gt;</code>) and turns it into a <code>CommandLineReservationsApiProgram&lt;'a&gt;</code> value. It first wraps <code>x</code> in <code>Run</code>, which turns <code>x</code> into a <code>CommandLineReservationsApiT&lt;'a&gt;</code> value. By piping that value into <code>mapT Pure</code>, you get a <code>CommandLineReservationsApiT&lt;CommandLineReservationsApiProgram&lt;'a&gt;&gt;</code> value that you can finally pipe into <code>Free</code> in order to produce a <code>CommandLineReservationsApiProgram&lt;'a&gt;</code> value. Phew! </p> <p> The <code>liftCL</code> function lifts a <code>CommandLineProgram</code> (<em>CL</em>) to <code>CommandLineReservationsApiProgram</code> by first using <code>CommandLine.map</code> to lift <code>x</code> to a <code>CommandLineProgram&lt;ReservationsApiProgram&lt;'a&gt;&gt;</code> value. It then pipes that value to <code>wrap</code>. </p> <p> Likewise, the <code>liftRA</code> function lifts a <code>ReservationsApiProgram</code> (<em>RA</em>) to <code>CommandLineReservationsApiProgram</code>. It simply elevates <code>x</code> to a <code>CommandLineProgram</code> value by using <code>CommandLineProgram.Pure</code>. Subsequently, it pipes that value to <code>wrap</code>. </p> <p> In both of these functions, I used the slightly unusual backwards pipe operator <code>&lt;|</code>. The reason for that is that it emphasises the similarity between <code>liftCL</code> and <code>liftRA</code>. This is easier to see if you remove the type comments: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;liftCL&nbsp;x&nbsp;=&nbsp;wrap&nbsp;&lt;|&nbsp;CommandLine.map&nbsp;ReservationsApiProgram.Pure&nbsp;x <span style="color:blue;">let</span>&nbsp;liftRA&nbsp;x&nbsp;=&nbsp;wrap&nbsp;&lt;|&nbsp;CommandLineProgram.Pure&nbsp;x</pre> </p> <p> This is how I normally write my F# code. I only add the type comments for the benefit of you, dear reader. Normally, when you have an IDE, you can always inspect the types using the built-in tools. </p> <p> Using the backwards pipe operator makes it immediately clear that both functions depend in the <code>wrap</code> function. This would have been muddied by use of the normal forward pipe operator: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;liftCL&nbsp;x&nbsp;=&nbsp;CommandLine.map&nbsp;ReservationsApiProgram.Pure&nbsp;x&nbsp;|&gt;&nbsp;wrap <span style="color:blue;">let</span>&nbsp;liftRA&nbsp;x&nbsp;=&nbsp;CommandLineProgram.Pure&nbsp;x&nbsp;|&gt;&nbsp;wrap</pre> </p> <p> The behaviour is the same, but now <code>wrap</code> doesn't align, making it harder to discover the kinship between the two functions. My use of the backward pipe operator is motivated by readability concerns. </p> <p> Following the <a href="http://blog.ploeh.dk/2017/08/07/f-free-monad-recipe">free monad recipe</a>, now create a computation expression builder: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CommandLineReservationsApiBuilder</span>&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">Bind</span>&nbsp;(x,&nbsp;<span style="color:navy;">f</span>)&nbsp;=&nbsp;<span style="color:teal;">CommandLineReservationsApi</span>.<span style="color:navy;">bind</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">Return</span>&nbsp;x&nbsp;=&nbsp;<span style="color:navy;">Pure</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">ReturnFrom</span>&nbsp;x&nbsp;=&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">Zero</span>&nbsp;()&nbsp;=&nbsp;<span style="color:navy;">Pure</span>&nbsp;()</pre> </p> <p> Finally, create an instance of the class: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;commandLineReservationsApi&nbsp;=&nbsp;<span style="color:teal;">CommandLineReservationsApiBuilder</span>&nbsp;() </pre> </p> <p> Putting the <code>commandLineReservationsApi</code> value in a module will enable you to use it for computation expressions whenever you open that module. I normally put it in a module with the <code>[&lt;AutoOpen&gt;]</code> attribute so that it automatically becomes available as soon as I open the containing namespace. </p> <p> <strong>Simplification</strong> </p> <p> While there <em>can</em> be good reasons to introduce single-case discriminated unions in your F# code, they're isomorphic with their contained type. (This means that there's a lossless conversion between the union type and the contained type, in both directions.) Following the <a href="http://blog.ploeh.dk/2017/08/07/f-free-monad-recipe">free monad recipe</a>, I introduced <code>CommandLineReservationsApiT</code> as a discriminated union, but since it's a single-case union, you can refactor it to its contained type. </p> <p> If you delete the <code>CommandLineReservationsApiT</code> type, you'll first have to change the definition of the program type to this: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CommandLineReservationsApiProgram</span>&lt;&#39;a&gt;&nbsp;= |&nbsp;<span style="color:navy;">Free</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">CommandLineProgram</span>&lt;<span style="color:teal;">ReservationsApiProgram</span>&lt;<span style="color:teal;">CommandLineReservationsApiProgram</span>&lt;&#39;a&gt;&gt;&gt; |&nbsp;<span style="color:navy;">Pure</span>&nbsp;<span style="color:blue;">of</span>&nbsp;&#39;a</pre> </p> <p> You simply replace <code>CommandLineReservationsApiT&lt;_&gt;</code> with <code>CommandLineProgram&lt;ReservationsApiProgram&lt;_&gt;&gt;</code>, effectively promoting the type contained in the <code>Run</code> case to be the container in the <code>Free</code> case. </p> <p> Once <code>CommandLineReservationsApiT</code> is gone, you'll also need to delete the <code>mapT</code> function, and amend <code>bind</code>: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;CommandLineReservationsApiProgram&lt;&#39;b&gt;)</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;CommandLineReservationsApiProgram&lt;&#39;a&gt;</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;CommandLineReservationsApiProgram&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;bind&nbsp;f&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Free&nbsp;instruction&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;instruction&nbsp;|&gt;&nbsp;mapStack&nbsp;(bind&nbsp;f)&nbsp;|&gt;&nbsp;Free &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Pure&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;f&nbsp;x</pre> </p> <p> Likewise, you must also adjust the <code>wrap</code> function: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:navy;">wrap</span>&nbsp;x&nbsp;=&nbsp;x&nbsp;|&gt;&nbsp;<span style="color:navy;">mapStack</span>&nbsp;<span style="color:navy;">Pure</span>&nbsp;|&gt;&nbsp;<span style="color:navy;">Free</span> </pre> </p> <p> The rest of the above code stays the same. </p> <p> <strong>Wizard</strong> </p> <p> In Haskell, you get combinations of monads for free via the <code>FreeT</code> type, whereas in F#, you have to work for it. Once you have the combination in monadic form as well, you can write programs with that combination. Here's the wizard that collects your data and attempts to make a restaurant reservation on your behalf: </p> <p> <pre><span style="color:green;">//&nbsp;CommandLineReservationsApiProgram&lt;unit&gt;</span> <span style="color:blue;">let</span>&nbsp;tryReserve&nbsp;=&nbsp;commandLineReservationsApi&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;count&nbsp;=&nbsp;<span style="color:navy;">liftCL</span>&nbsp;readQuantity &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;date&nbsp;&nbsp;=&nbsp;<span style="color:navy;">liftCL</span>&nbsp;readDate &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;availableSeats&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">ReservationsApi</span>.<span style="color:navy;">getSlots</span>&nbsp;date &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">ReservationsApi</span>.<span style="color:navy;">map</span>&nbsp;(<span style="color:teal;">List</span>.<span style="color:navy;">sumBy</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;slot&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;slot.SeatsLeft)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">liftRA</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;availableSeats&nbsp;&lt;&nbsp;count &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:blue;">do!</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">sprintf</span>&nbsp;<span style="color:#a31515;">&quot;Only&nbsp;</span><span style="color:teal;">%i</span><span style="color:#a31515;">&nbsp;remaining&nbsp;seats.&quot;</span>&nbsp;availableSeats &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">CommandLine</span>.<span style="color:navy;">writeLine</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">liftCL</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;name&nbsp;&nbsp;=&nbsp;<span style="color:navy;">liftCL</span>&nbsp;readName &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;email&nbsp;=&nbsp;<span style="color:navy;">liftCL</span>&nbsp;readEmail &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;{&nbsp;Date&nbsp;=&nbsp;date;&nbsp;Name&nbsp;=&nbsp;name;&nbsp;Email&nbsp;=&nbsp;email;&nbsp;Quantity&nbsp;=&nbsp;count&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">ReservationsApi</span>.<span style="color:navy;">postReservation</span>&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">liftRA</span> &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> Notice that <code>tryReserve</code> is a <em>value</em>, and not a function. It's a pure value that contains an AST - a small program that describes the impure interactions that you'd like to take place. It's defined entirely within a <code>commandLineReservationsApi</code> computation expression. </p> <p> It starts by using the <code>readQuantity</code> and <code>readDate</code> program values you saw in the <a href="http://blog.ploeh.dk/2017/07/17/a-pure-command-line-wizard">previous F# article</a>. Both of these values are <code>CommandLineProgram</code> values, so you have to use <code>liftCL</code> to lift them to <code>CommandLineReservationsApiProgram</code> values - only then can you <code>let!</code> bind them to an <code>int</code> and a <code>DateTimeOffset</code>, respectively. This is just like the use of <code>lift</code> in the previous article's Haskell example. </p> <p> Once the program has collected the desired <code>date</code> from the user, it calls <code>ReservationsApi.getSlots</code> and calculates the sum over all the returned <code>SeatsLeft</code> labels. The <code>ReservationsApi.getSlots</code> function returns a <code>ReservationsApiProgram&lt;Slot list&gt;</code>, the <code>ReservationsApi.map</code> turns it into a <code>ReservationsApiProgram&lt;int&gt;</code> value that you must <code>liftRA</code> in order to be able to <code>let!</code> bind it to an <code>int</code> value. Let me stress once again: the program actually doesn't <em>do</em> any of that; it constructs an AST with instructions to that effect. </p> <p> If it turns out that there's too few seats left, the program writes that on the command line and exits. Otherwise, it continues to collect the user's name and email address. That's all the data required to create a <code>Reservation</code> record and pipe it to <code>ReservationsApi.postReservation</code>. </p> <p> <strong>Interpreters</strong> </p> <p> The <code>tryReserve</code> wizard is a pure value. It contains an AST that can be interpreted in such a way that impure operations happen. You've already seen the <code>CommandLineProgram</code> interpreter <a href="http://blog.ploeh.dk/2017/07/11/hello-pure-command-line-interaction">in a previous article</a>, so I'm not going to repeat it here. I'll only note that I renamed it to <code>interpretCommandLine</code> because I want to use the name <code>interpret</code> for the combined interpreter. </p> <p> The interpreter for <code>ReservationsApiProgram</code> values is similar to the <code>CommandLineProgram</code> interpreter: </p> <p> <pre><span style="color:green;">//&nbsp;ReservationsApiProgram&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;&#39;a</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;<span style="color:navy;">interpretReservationsApi</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:teal;">ReservationsApiProgram</span>.<span style="color:navy;">Pure</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:teal;">ReservationsApiProgram</span>.<span style="color:navy;">Free</span>&nbsp;(<span style="color:navy;">GetSlots</span>&nbsp;(d,&nbsp;<span style="color:navy;">next</span>))&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">ReservationHttpClient</span>.<span style="color:navy;">getSlots</span>&nbsp;d &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Async</span>.<span style="color:navy;">RunSynchronously</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">next</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">interpretReservationsApi</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:teal;">ReservationsApiProgram</span>.<span style="color:navy;">Free</span>&nbsp;(<span style="color:navy;">PostReservation</span>&nbsp;(r,&nbsp;next))&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">ReservationHttpClient</span>.<span style="color:navy;">postReservation</span>&nbsp;r&nbsp;|&gt;&nbsp;<span style="color:teal;">Async</span>.<span style="color:navy;">RunSynchronously</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;next&nbsp;|&gt;&nbsp;<span style="color:navy;">interpretReservationsApi</span></pre> </p> <p> The <code>interpretReservationsApi</code> function pattern-matches on its (implicit) <code>ReservationsApiProgram</code> argument, and performs the appropriate actions according to each instruction. In all <code>Free</code> cases, it delegates to implementations defined in a <code>ReservationHttpClient</code> module. The code in that module isn't shown here, but you can see it in <a href="https://github.com/ploeh/PureInteractionsInFSharp">the GitHub repository that accompanies this article</a>. </p> <p> You can combine the two 'leaf' interpreters in an interpreter of <code>CommandLineReservationsApiProgram</code> values: </p> <p> <pre><span style="color:green;">//&nbsp;CommandLineReservationsApiProgram&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;&#39;a</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;<span style="color:navy;">interpret</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:teal;">CommandLineReservationsApiProgram</span>.<span style="color:navy;">Pure</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:teal;">CommandLineReservationsApiProgram</span>.<span style="color:navy;">Free</span>&nbsp;p&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;p&nbsp;|&gt;&nbsp;<span style="color:navy;">interpretCommandLine</span>&nbsp;|&gt;&nbsp;<span style="color:navy;">interpretReservationsApi</span>&nbsp;|&gt;&nbsp;<span style="color:navy;">interpret</span></pre> </p> <p> As usual, in the <code>Pure</code> case, it simply returns the contained value. In the <code>Free</code> case, <code>p</code> is a <code>CommandLineProgram&lt;ReservationsApiProgram&lt;CommandLineReservationsApiProgram&lt;'a&gt;&gt;&gt;</code>. Since it's a <code>CommandLineProgram</code> value, you can interpret it with <code>interpretCommandLine</code>, which returns a <code>ReservationsApiProgram&lt;CommandLineReservationsApiProgram&lt;'a&gt;&gt;</code>. Since that's a <code>ReservationsApiProgram</code>, you can pipe it to <code>interpretReservationsApi</code>, which then returns a <code>CommandLineReservationsApiProgram&lt;'a&gt;</code>. An interpreter exists for that type as well, namely the <code>interpret</code> function itself, so recursively invoke it again. In other words, <code>interpret</code> will keep recursing until it hits a <code>Pure</code> case. </p> <p> <strong>Execution</strong> </p> <p> Everything is now in place so that you can execute your program. This is the program's entry point: </p> <p> <pre>[&lt;<span style="color:teal;">EntryPoint</span>&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">main</span>&nbsp;_&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">interpret</span>&nbsp;<span style="color:teal;">Wizard</span>.tryReserve &nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;<span style="color:green;">//&nbsp;return&nbsp;an&nbsp;integer&nbsp;exit&nbsp;code</span></pre> </p> <p> When you run it, you'll be able to have an interaction like this: </p> <p> <pre>Please enter number of diners: 4 Please enter your desired date: 2017-11-25 Please enter your name: Mark Seemann Please enter your email address: mark@example.net OK</pre> </p> <p> If you want to run this code sample yourself, you're going to need an appropriate HTTP API with which you can interact. I hosted the API on my local machine, and afterwards verified that the record was, indeed, written in the reservations database. </p> <p> <strong>Summary</strong> </p> <p> As expected, you can combine free monads in F#, although it requires more boilerplate code than in Haskell. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/08/07/f-free-monad-recipe">F# free monad recipe</a>. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Combining free monads in Haskell http://blog.ploeh.dk/2017/07/24/combining-free-monads-in-haskell 2017-07-24T15:33:00+00:00 Mark Seemann <div id="post"> <p> <em>An example on how to compose free monads in Haskell.</em> </p> <p> In the <a href="http://blog.ploeh.dk/2017/07/17/a-pure-command-line-wizard">previous article</a> in this <a href="http://blog.ploeh.dk/2017/07/10/pure-interactions">series on pure interactions</a>, you saw how to write a command-line wizard in F#, using a free monad to build an Abstract Syntax Tree (AST). The example collects information about a potential restaurant reservations you'd like to make. That example, however, didn't do more than that. </p> <p> For a more complete experience, you'd like your command-line interface (CLI) to not only collect data about a reservation, but actually <em>make</em> the reservation, using the available HTTP API. This means that you'll also need to model interaction with the HTTP API as an AST, but a different AST. Then, you'll have to figure out how to compose these two APIs into a combined API. </p> <p> In order to figure out how to do this in F#, I first had to do it in <a href="https://www.haskell.org">Haskell</a>. In this article, you'll see how to do it in Haskell, and in the next article, you'll see how to translate this Haskell prototype to F#. This should ensure that you get a functional F# code base as well. </p> <p> <strong>Command line API</strong> </p> <p> Let's make an easy start of it. In a previous article, you saw <a href="http://blog.ploeh.dk/2017/07/11/hello-pure-command-line-interaction">how to model command-line interactions as ASTs</a>, complete with syntactic sugar provided by a <a href="https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/computation-expressions">computation expression</a>. That took a fair amount of boilerplate code in F#, but in Haskell, it's declarative: </p> <p> <pre><span style="color:blue;">import</span>&nbsp;Control.Monad.Trans.Free&nbsp;(<span style="color:blue;">Free</span>,&nbsp;<span style="color:#600277;">liftF</span>) <span style="color:blue;">data</span>&nbsp;<span style="color:#dd0000;">CommandLineInstruction</span>&nbsp;next&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">ReadLine</span>&nbsp;(<span style="color:#dd0000;">String</span>&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;next) &nbsp;&nbsp;<span style="color:#666666;">|</span>&nbsp;<span style="color:#dd0000;">WriteLine</span>&nbsp;<span style="color:#dd0000;">String</span>&nbsp;next &nbsp;&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Functor</span>) <span style="color:blue;">type</span>&nbsp;<span style="color:#dd0000;">CommandLineProgram</span>&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Free</span>&nbsp;<span style="color:#dd0000;">CommandLineInstruction</span> <span style="color:#600277;">readLine</span>&nbsp;::&nbsp;<span style="color:blue;">CommandLineProgram</span>&nbsp;String readLine&nbsp;<span style="color:#666666;">=</span>&nbsp;liftF&nbsp;(<span style="color:#dd0000;">ReadLine</span>&nbsp;id) <span style="color:#600277;">writeLine</span>&nbsp;::&nbsp;String&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">CommandLineProgram</span>&nbsp;() writeLine&nbsp;s&nbsp;<span style="color:#666666;">=</span>&nbsp;liftF&nbsp;(<span style="color:#dd0000;">WriteLine</span>&nbsp;s&nbsp;<span style="color:blue;">()</span>)</pre> </p> <p> This is <em>all</em> the code required to define your AST and make it a monad in Haskell. Contrast that with <a href="http://blog.ploeh.dk/2017/07/11/hello-pure-command-line-interaction">all the code you have to write in F#</a>! </p> <p> The <code>CommandLineInstruction</code> type defines the instruction set, and makes use of a language extension called <code>DeriveFunctor</code>, which enables Haskell to automatically create a <code>Functor</code> instance from the type. </p> <p> The type alias <code>type CommandLineProgram = Free CommandLineInstruction</code> creates a monad from <code>CommandLineInstruction</code>, since <code>Free</code> is a <code>Monad</code> when the underlying type is a <code>Functor</code>. </p> <p> The <code>readLine</code> value and <code>writeLine</code> function are conveniences that lift the instructions from <code>CommandLineInstruction</code> into <code>CommandLineProgram</code> values. These were also one-liners in F#. </p> <p> <strong>HTTP client API</strong> </p> <p> You can write a small wizard to collect restaurant reservation data with the <code>CommandLineProgram</code> API, but the new requirement is to make HTTP calls so that the CLI program actually makes the reservation against the back-end system. You could extend <code>CommandLineProgram</code> with more instructions, but that would be to mix concerns. It'd be more appropriate to define a new instruction set for making the required HTTP requests. </p> <p> This API will send and receive more complex values than simple <code>String</code> values, so you can start by defining their types: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;<span style="color:#dd0000;">Slot</span>&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Slot</span>&nbsp;{&nbsp;slotDate&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">ZonedTime</span>,&nbsp;seatsLeft&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">Int</span>&nbsp;}&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Show</span>) <span style="color:blue;">data</span>&nbsp;<span style="color:#dd0000;">Reservation</span>&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:#dd0000;">Reservation</span>&nbsp;{&nbsp;reservationDate&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">ZonedTime</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;,&nbsp;reservationName&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">String</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;,&nbsp;reservationEmail&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">String</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;,&nbsp;reservationQuantity&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">Int</span>&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Show</span>)</pre> </p> <p> The <code>Slot</code> type contains information about how many available seats are left on a particular date. The <code>Reservation</code> type contains the information required in order to make a reservation. It's similar to the <code>Reservation</code> F# record type you saw in the previous article. </p> <p> The online restaurant reservation HTTP API may afford more functionality than you need, but there's no reason to model more instructions than required: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;<span style="color:#dd0000;">ReservationsApiInstruction</span>&nbsp;next&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">GetSlots</span>&nbsp;<span style="color:#dd0000;">ZonedTime</span>&nbsp;([<span style="color:#dd0000;">Slot</span>]&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;next) &nbsp;&nbsp;<span style="color:#666666;">|</span>&nbsp;<span style="color:#dd0000;">PostReservation</span>&nbsp;<span style="color:#dd0000;">Reservation</span>&nbsp;next &nbsp;&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Functor</span>)</pre> </p> <p> This instruction set models two interactions. The <code>GetSlots</code> case models an instruction to request, from the HTTP API, the slots for a particular date. The <code>PostReservation</code> case models an instruction to make a POST HTTP request with a <code>Reservation</code>, thereby making a reservation. </p> <p> Like the above <code>CommandLineInstruction</code>, this type is (automatically) a <code>Functor</code>, which means that we can create a <code>Monad</code> from it: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:#dd0000;">ReservationsApiProgram</span>&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Free</span>&nbsp;<span style="color:#dd0000;">ReservationsApiInstruction</span> </pre> </p> <p> Once again, the monad is nothing but a type alias. </p> <p> Finally, you're going to need the usual lifts: </p> <p> <pre><span style="color:#600277;">getSlots</span>&nbsp;::&nbsp;<span style="color:blue;">ZonedTime</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsApiProgram</span>&nbsp;[<span style="color:blue;">Slot</span>] getSlots&nbsp;d&nbsp;<span style="color:#666666;">=</span>&nbsp;liftF&nbsp;(<span style="color:#dd0000;">GetSlots</span>&nbsp;d&nbsp;id) <span style="color:#600277;">postReservation</span>&nbsp;::&nbsp;<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsApiProgram</span>&nbsp;() postReservation&nbsp;r&nbsp;<span style="color:#666666;">=</span>&nbsp;liftF&nbsp;(<span style="color:#dd0000;">PostReservation</span>&nbsp;r&nbsp;<span style="color:blue;">()</span>)</pre> </p> <p> This is all you need to write a wizard that interleaves <code>CommandLineProgram</code> and <code>ReservationsApiProgram</code> instructions in order to create a more complex AST. </p> <p> <strong>Wizard</strong> </p> <p> The wizard should do the following: <ul> <li>Collect the number of diners, and the date for the reservation.</li> <li>Query the HTTP API about availability for the requested date. If insufficient seats are available, it should exit.</li> <li>If sufficient capacity remains, collect name and email.</li> <li>Make the reservation against the HTTP API.</li> </ul> Like in the previous F# examples, you can factor some of the work that the wizard performs into helper functions. The first is one that prompts the user for a value and tries to parse it: </p> <p> <pre><span style="color:#600277;">readParse</span>&nbsp;::&nbsp;<span style="color:blue;">Read</span>&nbsp;a&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;String&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;String&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">CommandLineProgram</span>&nbsp;a readParse&nbsp;prompt&nbsp;errorMessage&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;writeLine&nbsp;prompt &nbsp;&nbsp;l&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;readLine &nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;readMaybe&nbsp;l&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;Just&nbsp;dt&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;return&nbsp;dt &nbsp;&nbsp;&nbsp;&nbsp;Nothing&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;writeLine&nbsp;errorMessage &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;readParse&nbsp;prompt&nbsp;errorMessage</pre> </p> <p> It first uses <code>writeLine</code> to write <code>prompt</code> to the command line - or rather, it creates an <em>instruction</em> to do so. The instruction is a <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a> value. No side-effects are involved until an interpreter evaluates the AST. </p> <p> The next line uses <code>readLine</code> to read the user's input. While <code>readLine</code> is a <code>CommandLineProgram String</code> value, due to Haskell's <code>do</code> notation, <code>l</code> is a <code>String</code> value. You can now attempt to parse that <code>String</code> value with <code>readMaybe</code>, which returns a <code>Maybe a</code> value that you can handle with pattern matching. If <code>readMaybe</code> returns a <code>Just</code> value, then return the contained value; otherwise, write <code>errorMessage</code> and recursively call <code>readParse</code> again. </p> <p> Like in the previous F# example, the only way to continue is to write something that <code>readMaybe</code> can parse. There's no other way to exit; there probably should be an option to quit, but it's not important for this demo purpose. </p> <p> You may also have noticed that, contrary to the previous F# example, I here succumbed to the temptation to break the <a href="https://en.wikipedia.org/wiki/Rule_of_three_(computer_programming)">rule of three</a>. It's easier to define a reusable function in Haskell, because you can leave it generic, with the proviso that the generic value must be an instance of the <code>Read</code> typeclass. </p> <p> The <code>readParse</code> function returns a <code>CommandLineProgram a</code> value. It doesn't combine <code>CommandLineProgram</code> with <code>ReservationsApiProgram</code>. That's going to happen in another function, but before we look at that, you're also going to need another little helper: </p> <p> <pre><span style="color:#600277;">readAnything</span>&nbsp;::&nbsp;String&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">CommandLineProgram</span>&nbsp;String readAnything&nbsp;prompt&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;writeLine&nbsp;prompt &nbsp;&nbsp;readLine</pre> </p> <p> The <code>readAnything</code> function simply writes a prompt, reads the user's input, and unconditionally returns it. You could also have written it as a one-liner like <code>readAnything prompt = writeLine prompt &gt;&gt; readLine</code>, but I find the above code more readable, even though it's slightly more verbose. </p> <p> That's all you need to write the wizard: </p> <p> <pre><span style="color:#600277;">tryReserve</span>&nbsp;::&nbsp;<span style="color:blue;">FreeT</span>&nbsp;<span style="color:blue;">ReservationsApiProgram</span>&nbsp;<span style="color:blue;">CommandLineProgram</span>&nbsp;() tryReserve&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;q&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;lift&nbsp;<span style="color:#666666;">$</span>&nbsp;readParse&nbsp;<span style="color:#a31515;">&quot;Please&nbsp;enter&nbsp;number&nbsp;of&nbsp;diners:&quot;</span>&nbsp;<span style="color:#a31515;">&quot;Not&nbsp;an&nbsp;Integer.&quot;</span> &nbsp;&nbsp;d&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;lift&nbsp;<span style="color:#666666;">$</span>&nbsp;readParse&nbsp;<span style="color:#a31515;">&quot;Please&nbsp;enter&nbsp;your&nbsp;desired&nbsp;date:&quot;</span>&nbsp;<span style="color:#a31515;">&quot;Not&nbsp;a&nbsp;date.&quot;</span> &nbsp;&nbsp;availableSeats&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;liftF&nbsp;<span style="color:#666666;">$</span>&nbsp;(sum&nbsp;<span style="color:#666666;">.</span>&nbsp;fmap&nbsp;seatsLeft)&nbsp;<span style="color:#666666;">&lt;$&gt;</span>&nbsp;getSlots&nbsp;d &nbsp;&nbsp;<span style="color:#af00db;">if</span>&nbsp;availableSeats&nbsp;<span style="color:#666666;">&lt;</span>&nbsp;q &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#af00db;">then</span>&nbsp;lift&nbsp;<span style="color:#666666;">$</span>&nbsp;writeLine&nbsp;<span style="color:#666666;">$</span>&nbsp;<span style="color:#a31515;">&quot;Only&nbsp;&quot;</span>&nbsp;<span style="color:#666666;">++</span>&nbsp;show&nbsp;availableSeats&nbsp;<span style="color:#666666;">++</span>&nbsp;<span style="color:#a31515;">&quot;&nbsp;remaining&nbsp;seats.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#af00db;">else</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;n&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;lift&nbsp;<span style="color:#666666;">$</span>&nbsp;readAnything&nbsp;<span style="color:#a31515;">&quot;Please&nbsp;enter&nbsp;your&nbsp;name:&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;e&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;lift&nbsp;<span style="color:#666666;">$</span>&nbsp;readAnything&nbsp;<span style="color:#a31515;">&quot;Please&nbsp;enter&nbsp;your&nbsp;email&nbsp;address:&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;liftF&nbsp;<span style="color:#666666;">$</span>&nbsp;postReservation&nbsp;<span style="color:#dd0000;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;reservationDate&nbsp;<span style="color:#666666;">=</span>&nbsp;d &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;,&nbsp;reservationName&nbsp;<span style="color:#666666;">=</span>&nbsp;n &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;,&nbsp;reservationEmail&nbsp;<span style="color:#666666;">=</span>&nbsp;e &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;,&nbsp;reservationQuantity&nbsp;<span style="color:#666666;">=</span>&nbsp;q&nbsp;}</pre> </p> <p> The <code>tryReserve</code> program first prompt the user for a number of diners and a date. Once it has the date <code>d</code>, it calls <code>getSlots</code> and calculates the sum of the remaining seats. <code>availableSeats</code> is an <code>Int</code> value like <code>q</code>, so you can compare those two values with each other. If the number of available seats is less than the desired quantity, the program writes that and exits. </p> <p> This interaction demonstrates how to interleave <code>CommandLineProgram</code> and <code>ReservationsApiProgram</code> instructions. It would be a bad user experience if the program would ask the user to input all information, and only then discover that there's insufficient capacity. </p> <p> If, on the other hand, there's enough remaining capacity, the program continues collecting information from the user, by prompting for the user's name and email address. Once all data is collected, it creates a new <code>Reservation</code> value and invokes <code>postReservation</code>. </p> <p> Consider the type of <code>tryReserve</code>. It's a combination of <code>CommandLineProgram</code> and <code>ReservationsApiProgram</code>, contained within a type called <code>FreeT</code>. This type is also a <code>Monad</code>, which is the reason the <code>do</code> notation still works. This also begins to explain the various <code>lift</code> and <code>liftF</code> calls sprinkled over the code. </p> <p> Whenever you use a <code>&lt;-</code> arrow to 'pull the value out of the monad' within a <code>do</code> block, the right-hand side of the arrow must have the same type as the return type of the overall function (or value). In this case, the return type is <code>FreeT ReservationsApiProgram CommandLineProgram ()</code>, whereas <code>readParse</code> returns a <code>CommandLineProgram a</code> value. As an example, <code>lift</code> turns <code>CommandLineProgram Int</code> into <code>FreeT ReservationsApiProgram CommandLineProgram Int</code>. </p> <p> The way the type of <code>tryReserve</code> is declared, when you have a <code>CommandLineProgram a</code> value, you use <code>lift</code>, but when you have a <code>ReservationsApiProgram a</code>, you use <code>liftF</code>. This depends on the order of the monads contained within <code>FreeT</code>. If you swap <code>CommandLineProgram</code> and <code>ReservationsApiProgram</code>, you'll also need to use <code>lift</code> instead of <code>liftF</code>, and vice versa. </p> <p> <strong>Interpreters</strong> </p> <p> <code>tryReserve</code> is a pure value. It's an Abstract Syntax Tree that combines two separate instruction sets to describe a complex interaction between user, command line, and an HTTP client. The program doesn't do anything until interpreted. </p> <p> You can write an impure interpreter for each of the APIs, and a third one that uses the other two to interpret <code>tryReserve</code>. </p> <p> Interpreting <code>CommandLineProgram</code> values is similar to the previous F# example: </p> <p> <pre><span style="color:#600277;">interpretCommandLine</span>&nbsp;::&nbsp;<span style="color:blue;">CommandLineProgram</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;IO&nbsp;a interpretCommandLine&nbsp;program&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;runFree&nbsp;program&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Pure</span>&nbsp;r&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;return&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Free</span>&nbsp;(<span style="color:#dd0000;">ReadLine</span>&nbsp;next)&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;line&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;getLine &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;interpretCommandLine&nbsp;<span style="color:#666666;">$</span>&nbsp;next&nbsp;line &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Free</span>&nbsp;(<span style="color:#dd0000;">WriteLine</span>&nbsp;line&nbsp;next)&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;putStrLn&nbsp;line &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;interpretCommandLine&nbsp;next</pre> </p> <p> This interpreter is a recursive function that pattern-matches all the cases in any <code>CommandLineProgram a</code>. When it encounters a <code>Pure</code> case, it simply returns the contained value. </p> <p> When it encounters a <code>ReadLine</code> value, it calls <code>getLine</code>, which returns an <code>IO String</code> value read from the command line, but thanks to the <code>do</code> block, <code>line</code> is a <code>String</code> value. The interpreter then calls <code>next</code> with <code>line</code>, and passes the return value of that recursively to itself. </p> <p> A similar treatment is given to the <code>WriteLine</code> case. <code>putStrLn line</code> writes <code>line</code> to the command line, where after <code>next</code> is used as an input argument to <code>interpretCommandLine</code>. </p> <p> Thanks to Haskell's type system, you can easily tell that <code>interpretCommandLine</code> is impure, because for every <code>CommandLineProgram a</code> it returns <code>IO a</code>. That was the intent all along. </p> <p> Likewise, you can write an interpreter for <code>ReservationsApiProgram</code> values: </p> <p> <pre><span style="color:#600277;">interpretReservationsApi</span>&nbsp;::&nbsp;<span style="color:blue;">ReservationsApiProgram</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;IO&nbsp;a interpretReservationsApi&nbsp;program&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;runFree&nbsp;program&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Pure</span>&nbsp;x&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;return&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Free</span>&nbsp;(<span style="color:#dd0000;">GetSlots</span>&nbsp;zt&nbsp;next)&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;slots&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;<span style="color:#dd0000;">HttpClient</span><span style="color:#666666;">.</span>getSlots&nbsp;zt &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;interpretReservationsApi&nbsp;<span style="color:#666666;">$</span>&nbsp;next&nbsp;slots &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Free</span>&nbsp;(<span style="color:#dd0000;">PostReservation</span>&nbsp;r&nbsp;next)&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">HttpClient</span><span style="color:#666666;">.</span>postReservation&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;interpretReservationsApi&nbsp;next</pre> </p> <p> The structure of <code>interpretReservationsApi</code> is similar to <code>interpretCommandLine</code>. It delegates its implementation to an <code>HttpClient</code> module that contains the impure interactions with the HTTP API. This module isn't shown in this article, but you can see it in <a href="https://github.com/ploeh/PureInteractionsInHaskell">the GitHub repository that accompanies this article</a>. </p> <p> From these two interpreters, you can create a combined interpreter: </p> <p> <pre><span style="color:#600277;">interpret</span>&nbsp;::&nbsp;<span style="color:blue;">FreeT</span>&nbsp;<span style="color:blue;">ReservationsApiProgram</span>&nbsp;<span style="color:blue;">CommandLineProgram</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;IO&nbsp;a interpret&nbsp;program&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;r&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;interpretCommandLine&nbsp;<span style="color:#666666;">$</span>&nbsp;runFreeT&nbsp;program &nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;r&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Pure</span>&nbsp;x&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;return&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Free</span>&nbsp;p&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;y&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;interpretReservationsApi&nbsp;p &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;interpret&nbsp;y</pre> </p> <p> This function has the required type: it evaluates any <code>FreeT ReservationsApiProgram CommandLineProgram a</code> and returns an <code>IO a</code>. <code>runFreeT</code> returns the <code>CommandLineProgram</code> part of the combined program. Passing this value to <code>interpretCommandLine</code>, you get the underlying type - the <code>a</code> in <code>CommandLineProgram a</code>, if you will. In this case, however, the <code>a</code> is quite a complex type that I'm not going to write out here. Suffice it to say that, at the container level, it's a <code>FreeF</code> value, which can be either a <code>Pure</code> or a <code>Free</code> case that you can use for pattern matching. </p> <p> In the <code>Pure</code> case, you're done, so you can simply return the underlying value. </p> <p> In the <code>Free</code> case, the <code>p</code> contained inside is a <code>ReservationsApiProgram</code> value, which you can interpret with <code>interpretReservationsApi</code>. That returns an <code>IO a</code> value, and due to the <code>do</code> block, <code>y</code> is the <code>a</code>. In this case, however, <code>a</code> is <code>FreeT ReservationsApiProgram CommandLineProgram a</code>, but that means that the function can now recursively call itself with <code>y</code> in order to interpret the next instruction. </p> <p> <strong>Execution</strong> </p> <p> Armed with both an AST and an interpreter, executing the program is trivial: </p> <p> <pre><span style="color:#600277;">main</span>&nbsp;::&nbsp;IO&nbsp;() main&nbsp;<span style="color:#666666;">=</span>&nbsp;interpret&nbsp;tryReserve</pre> </p> <p> When you run the program, you could produce an interaction like this: </p> <p> <pre>Please enter number of diners: 4 Please enter your desired date: 2017-11-25 18-30-00Z Not a date. Please enter your desired date: 2017-11-25 18:30:00Z Please enter your name: Mark Seemann Please enter your email address: mark@example.org Status {statusCode = 200, statusMessage = "OK"}</pre> </p> <p> You'll notice that I initially made a mistake on the date format, which caused <code>readParse</code> to prompt me again. </p> <p> If you want to run this code sample yourself, you're going to need an appropriate HTTP API with which you can interact. I hosted the API on my local machine, and afterwards verified that the record was, indeed, written in the reservations database. </p> <p> <strong>Summary</strong> </p> <p> This proof of concept proves that it's possible to combine separate free monads. Now that we know that it works, and the overall outline of it, it should be possible to translate this to F#. You should, however, expect more boilerplate code. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/07/31/combining-free-monads-in-f">Combining free monads in F#</a>. </p> </div> <div id="comments"> <hr /> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="https://twitter.com/porges">George Pollard</a></div> <div class="comment-content"> <p>Here's an additional simplification. Rather than writing <code>FreeT ReservationsApiProgram CommandLineProgram</code> which requires you to lift, you can instead form the sum (coproduct) of both functors:</p> <pre> import Data.Functor.Sum type Program = Free (Sum CommandLineInstruction ReservationsApiInstruction) liftCommandLine :: CommandLineInstruction a -> Program a liftCommandLine = liftF . InL liftReservation :: ReservationsApiInstruction a -> Program a liftReservation = liftF . InR </pre> <p>Now you can lift the helpers directly to <code>Program</code>, like so:</p> <pre> readLine :: Program String readLine = liftCommandLine (ReadLine id) writeLine :: String -> Program () writeLine s = liftCommandLine (WriteLine s ()) getSlots :: ZonedTime -> Program [Slot] getSlots d = liftReservation (GetSlots d id) postReservation :: Reservation -> Program () postReservation r = liftReservation (PostReservation r ()) </pre> <p>Then (after you change the types of the <code>read*</code> helpers), you can drop all <code>lift</code>s from <code>tryReserve</code>:</p> <pre> tryReserve :: Program () tryReserve = do q &lt;- readParse "Please enter number of diners:" "Not an Integer." d &lt;- readParse "Please enter your desired date:" "Not a date." availableSeats &lt;- (sum . fmap seatsLeft) &lt;$> getSlots d if availableSeats &lt; q then writeLine $ "Only " ++ show availableSeats ++ " remaining seats." else do n &lt;- readAnything "Please enter your name:" e &lt;- readAnything "Please enter your email address:" postReservation Reservation { reservationDate = d , reservationName = n , reservationEmail = e , reservationQuantity = q } </pre> <p>And finally your interpreter needs to dispatch over <code>InL</code>/<code>InR</code> (this is using functions from <code>Control.Monad.Free</code>, you can actually drop the <code>Trans</code> import at this point):</p> <pre> interpretCommandLine :: CommandLineInstruction (IO a) -> IO a interpretCommandLine (ReadLine next) = getLine >>= next interpretCommandLine (WriteLine line next) = putStrLn line >> next interpretReservationsApi :: ReservationsApiInstruction (IO a) -> IO a interpretReservationsApi (GetSlots zt next) = HttpClient.getSlots zt >>= next interpretReservationsApi (PostReservation r next) = HttpClient.postReservation r >> next interpret :: Program a -> IO a interpret program = iterM go program where go (InL cmd) = interpretCommandLine cmd go (InR res) = interpretReservationsApi res </pre> <p>I find this to be quite clean!</p> </div> <div class="comment-date">2017-07-27 3:58 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> George, thank you for writing. That alternative does, indeed, look simpler and cleaner than mine. Thank you for sharing. </p> <p> FWIW, one reason I write articles on this blog is to learn and become better. I publish what I know and have learned so far, and sometimes, people tell me that there's a better way. That's great, because it makes me a better programmer, and hopefully, it may make other readers better as well. </p> <p> In case you'll be puzzling over my next blog post, however, I'm going to share a little secret (which is not a secret if you look at the blog's commit history): I wrote this article series more than a month ago, which means that all the remaining articles are already written. While I agree that using the sum of functors instead of <code>FreeT</code> simplifies the Haskell code, I don't think it makes that much of a difference when translating to F#. I may be wrong, but I haven't tried yet. My point, though, is that the next article in the series is going to ignore this better alternative, because, when it was written, I didn't know about it. I invite any interested reader to post, as a comment to that future article, their better alternatives :) </p> </div> <div class="comment-date">2017-07-27 7:31 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://stackoverflow.com/users/1523776/benjamin-hodgson?tab=profile">Benjamin Hodgson</a></div> <div class="comment-content"> <p> Hi Mark, </p> <p> I think you'll enjoy <a href="http://www.cs.ru.nl/~W.Swierstra/Publications/DataTypesALaCarte.pdf"><i>Data Types a la Carte</i></a>. It's the definitive introduction to the style that George Pollard demonstrates above. Swierstra covers how to build datatypes with initial algebras over coproducts, compose them abstracting over the concrete functor, and tear them down generically. It's well written, too 😉 </p> <p> Benjamin </p> </div> <div class="comment-date">2017-07-23 28:40 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. A pure command-line wizard http://blog.ploeh.dk/2017/07/17/a-pure-command-line-wizard 2017-07-17T12:04:00+00:00 Mark Seemann <div id="post"> <p> <em>An example of a small Abstract Syntax Tree written with F# syntactic sugar.</em> </p> <p> In the <a href="http://blog.ploeh.dk/2017/07/11/hello-pure-command-line-interaction">previous article</a>, you got an introduction to a functional command-line API in F#. The example in that article, however, was too simple to highlight its composability. In this article, you'll see a fuller example. </p> <p> <strong>Command-line wizard for on-line restaurant reservations</strong> </p> <p> In <a href="http://blog.ploeh.dk/2017/01/27/from-dependency-injection-to-dependency-rejection">previous articles</a>, you can see variations on an HTTP-based back-end for an on-line restaurant reservation system. In this article, on the other hand, you're going to see a first attempt at a command-line <em>client</em> for the API. </p> <p> Normally, an on-line restaurant reservation system would have GUIs hosted in web pages or mobile apps, but with an open HTTP API, a self-respecting geek would prefer a command-line interface (CLI)... right?! </p> <p> <pre>Please enter number of diners: four Not an integer. Please enter number of diners: 4 Please enter your desired date: My next birthday Not a date. Please enter your desired date: 2017-11-25 Please enter your name: Mark Seemann Please enter your email address: mark@example.com {Date = 25.11.2017 00:00:00 +01:00; Name = "Mark Seemann"; Email = "mark@example.com"; Quantity = 4;}</pre> </p> <p> In this incarnation, the CLI only collects information in order to dump a rendition of an F# record on the command-line. In a future article, you'll see how to combine this with an HTTP client in order to make a reservation with the back-end system. </p> <p> Notice that the CLI is a wizard. It leads you through a series of questions. You have to give an appropriate answer to each question before you can move on to the next question. For instance, you must type an integer for the number of guests; if you don't, the wizard will repeatedly ask you for an integer until you do. </p> <p> You can develop such an interface with the <code>commandLine</code> computation expression from <a href="http://blog.ploeh.dk/2017/07/11/hello-pure-command-line-interaction">the previous article</a>. </p> <p> <strong>Reading quantities</strong> </p> <p> There are four steps in the wizard. The first is to read the desired quantity from the command line: </p> <p> <pre><span style="color:green;">//&nbsp;CommandLineProgram&lt;int&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;readQuantity&nbsp;=&nbsp;<span style="color:blue;">commandLine</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;<span style="color:teal;">CommandLine</span>.<span style="color:navy;">writeLine</span>&nbsp;<span style="color:#a31515;">&quot;Please&nbsp;enter&nbsp;number&nbsp;of&nbsp;diners:&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;l&nbsp;=&nbsp;<span style="color:teal;">CommandLine</span>.readLine &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:teal;">Int32</span>.<span style="color:navy;">TryParse</span>&nbsp;l&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:blue;">true</span>,&nbsp;dinerCount&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">return</span>&nbsp;dinerCount &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;<span style="color:teal;">CommandLine</span>.<span style="color:navy;">writeLine</span>&nbsp;<span style="color:#a31515;">&quot;Not&nbsp;an&nbsp;integer.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return!</span>&nbsp;readQuantity&nbsp;}</pre> </p> <p> This small piece of interaction is defined entirely within a <code>commandLine</code> expression. This enables you to use <code>do!</code> expressions and <code>let!</code> bindings to compose smaller <code>CommandLineProgram</code> values, such as <code>CommandLine.writeLine</code> and <code>CommandLine.readLine</code> (both shown in the previous article). </p> <p> After prompting the user to enter a number, the program reads the user's input from the command line. While <code>CommandLine.readLine</code> is a <code>CommandLineProgram&lt;string&gt;</code> value, the <code>let!</code> binding turns <code>l</code> into a <code>string</code> value. If you can parse <code>l</code> as an integer, you return the integer; otherwise, you recursively return <code>readQuantity</code>. </p> <p> The <code>readQuantity</code> program will continue to prompt the user for an integer. It gives you no option to cancel the wizard. This is a deliberate simplification I did in order to keep the example as simple as possible, but a real program should offer an option to abort the wizard. </p> <p> The function returns a <code>CommandLineProgram&lt;int&gt;</code> value. This is a <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a> value containing an Abstract Syntax Tree (AST) that describes the interactions to perform. It doesn't do anything until interpreted. Contrary to designing with Dependency Injection and interfaces, however, you can immediately tell, from the type, that explicitly delimited impure interactions may take place within that part of your code base. </p> <p> <strong>Reading dates</strong> </p> <p> When you've entered a proper number of diners, you proceed to enter a date. The program for that looks similar to <code>readQuantity</code>: </p> <p> <pre><span style="color:green;">//&nbsp;CommandLineProgram&lt;DateTimeOffset&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;readDate&nbsp;=&nbsp;commandLine&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;<span style="color:teal;">CommandLine</span>.<span style="color:navy;">writeLine</span>&nbsp;<span style="color:#a31515;">&quot;Please&nbsp;enter&nbsp;your&nbsp;desired&nbsp;date:&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;l&nbsp;=&nbsp;<span style="color:teal;">CommandLine</span>.readLine &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:teal;">DateTimeOffset</span>.<span style="color:navy;">TryParse</span>&nbsp;l&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:blue;">true</span>,&nbsp;dt&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">return</span>&nbsp;dt &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;<span style="color:teal;">CommandLine</span>.<span style="color:navy;">writeLine</span>&nbsp;<span style="color:#a31515;">&quot;Not&nbsp;a&nbsp;date.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return!</span>&nbsp;readDate&nbsp;}</pre> </p> <p> The <code>readDate</code> value is so similar to <code>readQuantity</code> that you might be tempted to refactor both into a single, reusable function. In this case, however, I chose to stick to the <a href="https://en.wikipedia.org/wiki/Rule_of_three_(computer_programming)">rule of three</a>. </p> <p> <strong>Reading strings</strong> </p> <p> Reading the customer's name and email address from the command line is easy, as no parsing is required: </p> <p> <pre><span style="color:green;">//&nbsp;CommandLineProgram&lt;string&gt;</span> <span style="color:blue;">let</span>&nbsp;readName&nbsp;=&nbsp;commandLine&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;CommandLine.writeLine&nbsp;<span style="color:#a31515;">&quot;Please&nbsp;enter&nbsp;your&nbsp;name:&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return!</span>&nbsp;CommandLine.readLine&nbsp;} <span style="color:green;">//&nbsp;CommandLineProgram&lt;string&gt;</span> <span style="color:blue;">let</span>&nbsp;readEmail&nbsp;=&nbsp;commandLine&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;CommandLine.writeLine&nbsp;<span style="color:#a31515;">&quot;Please&nbsp;enter&nbsp;your&nbsp;email&nbsp;address:&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return!</span>&nbsp;CommandLine.readLine&nbsp;}</pre> </p> <p> Both of these values unconditionally accept whatever you write when prompted. From a security standpoint, <em>all input is evil</em>, so in a production code base, you should still perform some validation. This, on the other hand, is demo code, so with that caveat, it accepts all strings you might type. </p> <p> These values are similar to each other, but once again I invoke the rule of three and keep them as separate values. </p> <p> <strong>Composing the wizard</strong> </p> <p> Together with the general-purpose command line API, the above values are all you need to compose the wizard. In this incarnation, the wizard should collect the information you type, and create a single record with those values. This is the type of record it must create: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">Reservation</span>&nbsp;=&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;:&nbsp;<span style="color:teal;">DateTimeOffset</span> &nbsp;&nbsp;&nbsp;&nbsp;Name&nbsp;:&nbsp;<span style="color:teal;">string</span> &nbsp;&nbsp;&nbsp;&nbsp;Email&nbsp;:&nbsp;<span style="color:teal;">string</span> &nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;:&nbsp;<span style="color:teal;">int</span>&nbsp;}</pre> </p> <p> You can easily compose the wizard like this: </p> <p> <pre><span style="color:green;">//&nbsp;CommandLineProgram&lt;Reservation&gt;</span> <span style="color:blue;">let</span>&nbsp;readReservationRequest&nbsp;=&nbsp;commandLine&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;count&nbsp;=&nbsp;readQuantity &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;date&nbsp;&nbsp;=&nbsp;readDate &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;name&nbsp;&nbsp;=&nbsp;readName &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;email&nbsp;=&nbsp;readEmail &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;{&nbsp;Date&nbsp;=&nbsp;date;&nbsp;Name&nbsp;=&nbsp;name;&nbsp;Email&nbsp;=&nbsp;email;&nbsp;Quantity&nbsp;=&nbsp;count&nbsp;}&nbsp;}</pre> </p> <p> There's really nothing to it. As all the previous code examples in this article, you compose the <code>readReservationRequest</code> value entirely inside a <code>commandLine</code> expression. You use <code>let!</code> bindings to collect the four data elements you need, and once you have all four, you can return a <code>Reservation</code> value. </p> <p> <strong>Running the program</strong> </p> <p> You may have noticed that no code so far shown define functions; they are all <em>values</em>. They are small program fragments, expressed as ASTs, composed into slightly larger programs that are still ASTs. So far, all the code is pure. </p> <p> In order to run the program, you need an interpreter. You can reuse the interpreter from the <a href="http://blog.ploeh.dk/2017/07/11/hello-pure-command-line-interaction">previous article</a> when composing your <code>main</code> function: </p> <p> <pre>[&lt;<span style="color:teal;">EntryPoint</span>&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">main</span>&nbsp;_&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Wizard</span>.readReservationRequest &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">CommandLine</span>.<span style="color:navy;">bind</span>&nbsp;(<span style="color:teal;">CommandLine</span>.<span style="color:navy;">writeLine</span>&nbsp;&lt;&lt;&nbsp;(<span style="color:navy;">sprintf</span>&nbsp;<span style="color:#a31515;">&quot;</span><span style="color:teal;">%A</span><span style="color:#a31515;">&quot;</span>)) &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">interpret</span> &nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;<span style="color:green;">//&nbsp;return&nbsp;an&nbsp;integer&nbsp;exit&nbsp;code</span></pre> </p> <p> Notice that most of the behaviour is defined by the above <code>Wizard.readReservationRequest</code> value. That program, however, returns a <code>Reservation</code> value that you should also print to the command line, using the <code>CommandLine</code> module. You can achieve that behaviour by composing <code>Wizard.readReservationRequest</code> with <code>CommandLine.writeLine</code> using <code>CommandLine.bind</code>. Another way to write the same composition would be by using a <code>commandLine</code> computation expression, but in this case, I find the small pipeline of functions easier to read. </p> <p> When you bind two <code>CommandLineProgram</code> values to each other, the result is a third <code>CommandLineProgram</code>. You can pipe that to <code>interpret</code> in order to run the program. The result is an interaction like the one shown in the beginning of this article. </p> <p> <strong>Summary</strong> </p> <p> In this article, you've seen how you can create larger ASTs from smaller ASTs, using the syntactic sugar that F# computation expressions afford. The point, so far, is that you can make side-effects and non-deterministic behaviour <em>explicit</em>, while retaining the 'normal' F# development experience. </p> <p> In Haskell, impure code can execute within an <code>IO</code> context, but inside <code>IO</code>, <em>any</em> sort of side-effect or non-deterministic behaviour could take place. For that reason, even in Haskell, it often makes sense to define an explicitly delimited set of impure operations. In the previous article, you can see a small Haskell code snippet that defines a command-line instruction AST type using <code>Free</code>. When you, as a code reader, encounter a value of the type <code>CommandLineProgram String</code>, you know more about the potential impurities than if you encounter a value of the type <code>IO String</code>. The same argument applies, with qualifications, in F#. </p> <p> When you encounter a value of the type <code>CommandLineProgram&lt;Reservation&gt;</code>, you know what sort of impurities to expect: the program will only write to the command line, or read from the command line. What if, however, you'd like to combine those particular interactions with other types of interactions? </p> <p> Read on. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/07/24/combining-free-monads-in-haskell">Combining free monads in Haskell</a>. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Hello, pure command-line interaction http://blog.ploeh.dk/2017/07/11/hello-pure-command-line-interaction 2017-07-11T12:48:00+00:00 Mark Seemann <div id="post"> <p> <em>A gentle introduction to modelling impure interactions with pure code.</em> </p> <p> Dependency Injection is a <a href="http://amzn.to/12p90MG">well-described</a> concept in object-oriented programming, but as I've <a href="http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection">explained earlier</a>, its not functional, because it makes everything impure. In general, you should <a href="http://blog.ploeh.dk/2017/02/02/dependency-rejection">reject the notion of dependencies</a> by instead designing your application on the concept of an impure/pure/impure sandwich. This is possible more often than you'd think, but <a href="http://blog.ploeh.dk/2017/07/10/pure-interactions">there's still a large group of applications where this will not work</a>. If your application needs to interact with the impure world for an extended time, you need a way to model such interactions in a pure way. </p> <p> This article introduces a way to do that. </p> <p> <strong>Command line API</strong> </p> <p> Imagine that you have to write a command-line program that can ask a series of questions and print appropriate responses. In the general case, this is a (potentially) long-running series of interactions between the user and the program. To keep it simple, though, in this article we'll start by looking at a degenerate example: </p> <p> <pre>Please enter your name. Mark Hello, Mark!</pre> </p> <p> The program is simply going to request that you enter your name. Once you've done that, it prints the greeting. In object-oriented programming, using Dependency Injection, you might introduce an interface. Keeping it simple, you can restrict such an interface to two methods: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">ICommandLine</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;ReadLine(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">void</span>&nbsp;WriteLine(<span style="color:blue;">string</span>&nbsp;text); }</pre> </p> <p> Please note that this is clearly a toy example. In later articles, you'll see how to expand the example to cover some more complex interactions, but you could also <a href="http://blog.ploeh.dk/2017/06/27/pure-times">read a more realistic example already</a>. Initially, the example is degenerate, because there's only a single interaction. In this case, an impure/pure/impure sandwich is still possible, but such a design wouldn't scale to more complex interactions. </p> <p> The problem with defining and injecting an interface is that it isn't functional. What's the functional equivalent, then? </p> <p> <strong>Instruction set</strong> </p> <p> Instead of defining an interface, you can define a discriminated union that describes a limited instruction set for command-line interactions: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CommandLineInstruction</span>&lt;&#39;a&gt;&nbsp;= |&nbsp;<span style="color:navy;">ReadLine</span>&nbsp;<span style="color:blue;">of</span>&nbsp;(<span style="color:teal;">string</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;&#39;a) |&nbsp;<span style="color:navy;">WriteLine</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span>&nbsp;*&nbsp;&#39;a</pre> </p> <p> You may notice that it looks a bit like the above C# interface. Instead of defining two methods, it defines two cases, but the names are similar. </p> <p> The <code>ReadLine</code> case is an <em>instruction</em> that an interpreter can evaluate. The data contained in the case is a continuation function. After evaluating the instruction, an interpreter must invoke this function with a string. It's up to the interpreter to figure out which string to use, but it could, for example, come from reading an input string from the command line. The continuation function is the next step in whatever program you're writing. </p> <p> The <code>WriteLine</code> case is another instruction for interpreters. The data contained in this case is a tuple. The first element of the tuple is input for the interpreter, which can choose to e.g. print the value on the command line, or ignore it, and so on. The second element of the tuple is a value used to continue whatever program this case is a part of. </p> <p> This enables you to write a small, specialised Abstract Syntax Tree (AST), but there's currently no way to return from it. One way to do that is to add a third 'stop' case. If you're interested in that option, <a href="https://fsharpforfunandprofit.com">Scott Wlaschin</a> covers this as one iteration in his <a href="https://fsharpforfunandprofit.com/posts/13-ways-of-looking-at-a-turtle-2/#way13">excellent explanation of the AST design</a>. </p> <p> Instead of adding a third 'stop' case to <code>CommandLineInstruction&lt;'a&gt;</code>, another option is to add a new wrapper type around it: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CommandLineProgram</span>&lt;&#39;a&gt;&nbsp;= |&nbsp;<span style="color:navy;">Free</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">CommandLineInstruction</span>&lt;<span style="color:teal;">CommandLineProgram</span>&lt;&#39;a&gt;&gt; |&nbsp;<span style="color:navy;">Pure</span>&nbsp;<span style="color:blue;">of</span>&nbsp;&#39;a</pre> </p> <p> The <code>Free</code> case contains a <code>CommandLineInstruction</code> that always continues to a new <code>CommandLineProgram</code> value. The only way you can escape the AST is via the <code>Pure</code> case, which simply contains the 'return' value. </p> <p> <strong>Abstract Syntax Trees</strong> </p> <p> With these two types you can write specialised programs that contain instructions for an interpreter. Notice that the types are pure by intent, although in F# we can't really tell. You can, however, repeat this exercise in <a href="https://www.haskell.org">Haskell</a>, where the instruction set looks like this: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;<span style="color:#dd0000;">CommandLineInstruction</span>&nbsp;next&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">ReadLine</span>&nbsp;(<span style="color:#dd0000;">String</span>&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;next) &nbsp;&nbsp;<span style="color:#666666;">|</span>&nbsp;<span style="color:#dd0000;">WriteLine</span>&nbsp;<span style="color:#dd0000;">String</span>&nbsp;next &nbsp;&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Functor</span>) <span style="color:blue;">type</span>&nbsp;<span style="color:#dd0000;">CommandLineProgram</span>&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Free</span>&nbsp;<span style="color:#dd0000;">CommandLineInstruction</span></pre> </p> <p> Both of these types are <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a>, because <code>IO</code> is nowhere in sight. In Haskell, functions are pure by default. This also applies to the <code>String -&gt; next</code> function contained in the <code>ReadLine</code> case. </p> <p> Back in F# land, you can write an AST that implements the command-line interaction shown in the beginning of the article: </p> <p> <pre><span style="color:green;">//&nbsp;CommandLineProgram&lt;unit&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:#9b9b9b;">program</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">Free</span>&nbsp;(<span style="color:navy;">WriteLine</span>&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;Please&nbsp;enter&nbsp;your&nbsp;name.&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">Free</span>&nbsp;(<span style="color:navy;">ReadLine</span>&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">fun</span>&nbsp;s&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Free</span>&nbsp;(<span style="color:navy;">WriteLine</span>&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">sprintf</span>&nbsp;<span style="color:#a31515;">&quot;Hello,&nbsp;</span><span style="color:teal;">%s</span><span style="color:#a31515;">!&quot;</span>&nbsp;s, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">Pure</span>&nbsp;()))))))</pre> </p> <p> This AST defines a little program. The first step is a <code>WriteLine</code> instruction with the input value <code>"Please enter your name."</code>. The <code>WriteLine</code> case constructor takes a tuple as input argument. The first tuple element is that prompt, and the second element is the continuation, which has to be a new <code>CommandLineInstruction&lt;CommandLineProgram&lt;'a&gt;&gt;</code> value. </p> <p> In this example, the continuation value is a <code>ReadLine</code> case, which takes a continuation function as input. This function should return a new program value, which it does by returning a <code>WriteLine</code>. </p> <p> This second <code>WriteLine</code> value creates a <code>string</code> from the outer value <code>s</code>. The second tuple element for the <code>WriteLine</code> case must, again, be a new program value, but now the program is done, so you can use the 'stop' value <code>Pure ()</code>. </p> <p> You probably think that I should quit the mushrooms. No one in their right mind will want to write code like this. Neither would I. Fortunately, you can make the coding experience <em>much</em> better, but you'll see how to do that later. </p> <p> <strong>Interpretation</strong> </p> <p> The above <code>program</code> value is a small <code>CommandLineProgram&lt;unit&gt;</code>. It's a pure value. In itself, it doesn't do anything. </p> <p> Clearly, we'd like it to <em>do</em> something. In order to make that happen, you can write an interpreter: </p> <p> <pre><span style="color:green;">//&nbsp;CommandLineProgram&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;&#39;a</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;<span style="color:navy;">interpret</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Pure</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Free</span>&nbsp;(<span style="color:navy;">ReadLine</span>&nbsp;&nbsp;<span style="color:navy;">next</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:teal;">Console</span>.<span style="color:navy;">ReadLine</span>&nbsp;()&nbsp;|&gt;&nbsp;<span style="color:navy;">next</span>&nbsp;|&gt;&nbsp;<span style="color:navy;">interpret</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Free</span>&nbsp;(<span style="color:navy;">WriteLine</span>&nbsp;(s,&nbsp;next))&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Console</span>.<span style="color:navy;">WriteLine</span>&nbsp;s &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;next&nbsp;|&gt;&nbsp;<span style="color:navy;">interpret</span></pre> </p> <p> This interpreter is a recursive function that pattern-matches all the cases in any <code>CommandLineProgram&lt;'a&gt;</code>. When it encounters a <code>Pure</code> case, it simply returns the contained value. </p> <p> When it encounters a <code>ReadLine</code> value, it calls <code>Console.ReadLine ()</code>, which returns a <code>string</code> value read from the command line. It then pipes that input value to its <code>next</code> continuation function, which produces a new <code>CommandLineInstruction&lt;CommandLineProgram&lt;'a&gt;&gt;</code> value. Finally, it pipes that continuation value recursively to itself. </p> <p> A similar treatment is given to the <code>WriteLine</code> case. <code>Console.WriteLine s</code> writes <code>s</code> to the command line, where after <code>next</code> is recursively piped to <code>interpret</code>. </p> <p> When you run <code>interpret program</code>, you get an interaction like this: </p> <p> <pre>Please enter your name. ploeh Hello, ploeh!</pre> </p> <p> The <code>program</code> is pure; the <code>interpret</code> function is impure. </p> <p> <strong>Syntactic sugar</strong> </p> <p> Clearly, you don't want to write programs as ASTs like the above. Fortunately, you don't have to. You can add syntactic sugar in the form of <a href="https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/computation-expressions">computation expressions</a>. The way to do that is to turn your AST types into a monad. In Haskell, you'd already be done, because <code>Free</code> is a monad. In F#, some code is required. </p> <p> <strong>Source functor</strong> </p> <p> The first step is to define a map function for the underlying instruction set union type. Conceptually, when you can define a map function for a type, you've created a <em>functor</em> (if it obeys the functor laws, that is). Functors are common, so it often pays off being aware of them. </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;CommandLineInstruction&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;CommandLineInstruction&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:navy;">mapI</span>&nbsp;<span style="color:navy;">f</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">ReadLine</span>&nbsp;<span style="color:navy;">next</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">ReadLine</span>&nbsp;(<span style="color:navy;">next</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">f</span>) &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">WriteLine</span>&nbsp;(x,&nbsp;next)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">WriteLine</span>&nbsp;(x,&nbsp;next&nbsp;|&gt;&nbsp;<span style="color:navy;">f</span>)</pre> </p> <p> The <code>mapI</code> function takes a <code>CommandLineInstruction&lt;'a&gt;</code> value and maps it to a new value by mapping the 'underlying value'. I decided to make the function <code>private</code> because later, I'm also going to define a map function for <code>CommandLineProgram&lt;'a&gt;</code>, and I don't want to confuse users of the API with two different map functions. This is also the reason that the name of the function isn't simply <code>map</code>, but rather <code>mapI</code>, where the <em>I</em> stands for <em>instruction</em>. </p> <p> <code>mapI</code> pattern-matches on the (implicit) input argument. If it's a <code>ReadLine</code> case, it returns a new <code>ReadLine</code> value, but it uses the mapper function <code>f</code> to translate the <code>next</code> function. Recall that <code>next</code> is a function of the type <code>string -&gt; 'a</code>. When you compose it with <code>f</code> (which is a function of the type <code>'a -&gt; 'b</code>), you get <code>(string -&gt; 'a) &gt;&gt; ('a -&gt; 'b)</code>, or <code>string -&gt; 'b</code>. You've transformed the <code>'a</code> to a <code>'b</code> for the <code>ReadLine</code> case. If you can do the same for the <code>WriteLine</code> case, you'll have a functor. </p> <p> Fortunately, the <code>WriteLine</code> case is similar, although a small tweak is required. This case contains a tuple of data. The first element (<code>x</code>) isn't a generic type (it's a <code>string</code>), so there's nothing to map. You can use it as-is in the new <code>WriteLine</code> value that you'll return. The <code>WriteLine</code> case is degenerate because <code>next</code> isn't a function, but rather a value. It has a type of <code>'a</code>, and <code>f</code> is a function of the type <code>'a -&gt; 'b</code>, so piping <code>next</code> to <code>f</code> returns a <code>'b</code>. </p> <p> That's it: now you have a functor. </p> <p> (In order to keep the category theorists happy, I should point out that such functors are really a sub-type of functors called <em>endo-functors</em>. Additionally, functors must obey some simple and intuitive laws in order to be functors, but that's all I'll say about that here.) </p> <p> <strong>Free monad</strong> </p> <p> There's a reason I spend so much time talking about functors. The goal is syntactic sugar. You can get that with computation expressions. In order to create a computation expression builder, you need a monad. </p> <p> You need a recipe for creating a monad. Fortunately, there's a type of monad called a <em>free monad</em>. It has the virtue that it enables you to create a monad from any functor. </p> <p> Just what you need. </p> <p> In Haskell, this happens automatically when you declare <code>type CommandLineProgram = Free CommandLineInstruction</code>. Thanks to Haskell's type system, <code>Free</code> is automatically a <code>Monad</code> when the underlying type is a <code>Functor</code>. In F#, you have to work for your monads, but the fact that Haskell can automate this means that <a href="http://blog.ploeh.dk/2017/08/07/f-free-monad-recipe">there's a recipe that you can follow</a>. </p> <p> Earlier in this article, I mentioned in passing that there are alternative ways in which you can define a 'stop' case for your instruction set. The reason I chose to separate the API into two types (an 'instruction set', and a 'program') is that the instruction set is the underlying functor. The 'program' is part of the free monad. The other part is a <code>bind</code> function (that obeys the monad laws). </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;CommandLineProgram&lt;&#39;b&gt;)&nbsp;-&gt;&nbsp;CommandLineProgram&lt;&#39;a&gt;</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;CommandLineProgram&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;bind&nbsp;f&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Free&nbsp;instruction&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;instruction&nbsp;|&gt;&nbsp;mapI&nbsp;(bind&nbsp;f)&nbsp;|&gt;&nbsp;Free &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Pure&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;f&nbsp;x</pre> </p> <p> This recursive function pattern-matches on the (implicit) <code>CommandLineProgram&lt;'a&gt;</code> argument. In the <code>Pure</code> case, the 'return' value <code>x</code> has the type <code>'a</code>, which fits as input for the <code>f</code> function. The result is a value of type <code>CommandLineProgram&lt;'b&gt;</code>. </p> <p> In the <code>Free</code> case, the <code>instruction</code> is a functor with the map function <code>mapI</code>. The first argument to the <code>mapI</code> function must be a function with the type <code>'a -&gt; 'b</code>. How can you compose such a function? </p> <p> If you partially apply the recursive <code>bind</code> function with <code>f</code> (that is: <code>bind f</code>), you get a function of the type <code>CommandLineProgram&lt;'a&gt; -&gt; CommandLineProgram&lt;'b&gt;</code>. This fits with <code>mapI</code>, because <code>instruction</code> has the type <code>CommandLineInstruction&lt;CommandLineProgram&lt;'a&gt;&gt;</code> (refer back to the definition of the <code>Free</code> case if need to convince yourself of that). The result of calling <code>mapI</code> with <code>instruction</code> is a <code>CommandLineInstruction&lt;CommandLineProgram&lt;'b&gt;&gt;</code> value. In order to turn it into a <code>CommandLineProgram&lt;'b&gt;</code> value, you wrap it in a new <code>Free</code> case. </p> <p> Although this required a bit of explanation, defining a <code>bind</code> function for a free monad is a repeatable process. After all, in Haskell it's automated. In F#, you have to explicitly write the code, but it follows a recipe. Once you get the hang of it, there's not much to it. </p> <p> <strong>Functor</strong> </p> <p> You'll occasionally need to explicitly use the <code>bind</code> function, but often it'll 'disappear' into a computation expression. There are other building blocks to an API than a <code>bind</code> function, though. You may, for example, need a <code>map</code> function: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;CommandLineProgram&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;CommandLineProgram&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;map&nbsp;f&nbsp;=&nbsp;bind&nbsp;(f&nbsp;&gt;&gt;&nbsp;Pure)</pre> </p> <p> This makes <code>CommandLineProgram&lt;'a&gt;</code> a functor as well. This is the reason I made <code>mapI</code> private, because <code>mapI</code> makes the instruction set a functor, but the API is expressed in terms of AST programs, and it should be consistent. Within the same module, <code>map</code> should work on the same data type as <code>bind</code>. </p> <p> Notice that <code>map</code> can be defined as a composition of <code>bind</code> and <code>Pure</code>. This is part of <a href="http://blog.ploeh.dk/2017/08/07/f-free-monad-recipe">the recipe</a>. For a free monad, the <code>map</code> function always looks like that. The <code>f</code> function is a function with the type <code>'a -&gt; 'b</code>, and <code>Pure</code> is a case constructor with the type <code>'b -&gt; CommandLineProgram&lt;'b&gt;</code>. Notice that I've used <code>'b</code> for the generic type argument instead of the usual <code>'a</code>. Hopefully, this makes it clear that when you compose these two functions together (<code>f &gt;&gt; Pure</code>), you get a function of the type <code>('a -&gt; 'b) &gt;&gt; ('b -&gt; CommandLineProgram&lt;'b&gt;)</code>, or <code>'a -&gt; CommandLineProgram&lt;'b&gt;</code>. That's just the type of function needed for the <code>bind</code> function, so the whole composition turns out to type-check and work as intended. </p> <p> <strong>API</strong> </p> <p> In order to work with an API, you need the ability to create values of the API's type(s). In this case, you must be able to create <code>CommandLineProgram&lt;'a&gt;</code> values. While you can create them explicitly using the <code>ReadLine</code>, <code>WriteLine</code>, <code>Free</code>, and <code>Pure</code> case constructors, it'll be more convenient if you have some predefined functions and values for that. </p> <p> <pre><span style="color:green;">//&nbsp;CommandLineProgram&lt;string&gt;</span> <span style="color:blue;">let</span>&nbsp;readLine&nbsp;=&nbsp;Free&nbsp;(ReadLine&nbsp;Pure) <span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;CommandLineProgram&lt;unit&gt;</span> <span style="color:blue;">let</span>&nbsp;writeLine&nbsp;s&nbsp;=&nbsp;Free&nbsp;(WriteLine&nbsp;(s,&nbsp;Pure&nbsp;()))</pre> </p> <p> In the <code>ReadLine</code> case, there's no input to the instruction, so you can define <code>readLine</code> as a predefined <code>CommandLineProgram&lt;string&gt;</code> value. </p> <p> The <code>WriteLine</code> case, on the other hand, takes as an input argument a string to write, so you can define <code>writeLine</code> as a function that returns a <code>CommandLineProgram&lt;unit&gt;</code> value. </p> <p> <strong>Computation expression</strong> </p> <p> The addition of <code>map</code> and supporting API is, to be honest, a bit of digression. You're going to use these functions later, but they aren't required in order to create a computation expression builder. All you need is a <code>bind</code> function and a way to lift a raw value into the monad. All of these are in place, so the builder is a matter of delegation: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CommandLineBuilder</span>&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">Bind</span>&nbsp;(x,&nbsp;<span style="color:navy;">f</span>)&nbsp;=&nbsp;<span style="color:teal;">CommandLine</span>.<span style="color:navy;">bind</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">Return</span>&nbsp;x&nbsp;=&nbsp;<span style="color:navy;">Pure</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">ReturnFrom</span>&nbsp;x&nbsp;=&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">Zero</span>&nbsp;()&nbsp;=&nbsp;<span style="color:navy;">Pure</span>&nbsp;()</pre> </p> <p> This is a fairly minimal builder, but in my experience, most of times, this is all you need. </p> <p> Create an instance of the <code>CommandLineBuilder</code> class, and you can write computation expressions: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;commandLine&nbsp;=&nbsp;<span style="color:teal;">CommandLineBuilder</span>&nbsp;() </pre> </p> <p> I usually put such an object in a module with an <code>[&lt;AutoOpen&gt;]</code> attribute, so that it's available as a global object. </p> <p> <strong>Producing ASTs with pretty code</strong> </p> <p> Using the <code>commandLine</code> computation expression is like using the built-in <code>async</code> or <code>seq</code> expressions. You can use it to rewrite the above AST as readable code: </p> <p> <pre><span style="color:green;">//&nbsp;CommandLineProgram&lt;unit&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:#9b9b9b;">program</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">commandLine</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;&nbsp;<span style="color:teal;">CommandLine</span>.<span style="color:navy;">writeLine</span>&nbsp;<span style="color:#a31515;">&quot;Please&nbsp;enter&nbsp;your&nbsp;name.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;name&nbsp;=&nbsp;<span style="color:teal;">CommandLine</span>.readLine &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;&nbsp;<span style="color:navy;">sprintf</span>&nbsp;<span style="color:#a31515;">&quot;Hello,&nbsp;</span><span style="color:teal;">%s</span><span style="color:#a31515;">!&quot;</span>&nbsp;name&nbsp;|&gt;&nbsp;<span style="color:teal;">CommandLine</span>.<span style="color:navy;">writeLine</span>&nbsp;}</pre> </p> <p> This produces the same AST as before, but with much more readable syntax. The AST is the same, and you can use the above <code>interpret</code> function to run it. The interaction is the same as before: </p> <p> <pre>Please enter your name. Free Hello, Free!</pre> </p> <p> This is, obviously, a toy example, but in coming articles, you'll see how to gradually enhance the code to perform some more complex interactions. </p> <p> <strong>Summary</strong> </p> <p> Functional programming emphasises pure functions, and a separation of pure and impure code. The simplest way to achieve such a separation is to design your code as an impure/pure/impure sandwich, but sometimes this isn't possible. When it's not possible, an alternative is to define an instruction set for an AST, and turn it into a free monad in order to enable enough syntactic sugar to keep the code readable. </p> <p> While this may seem complicated, it has the benefit of making impurities explicit in the code. Whenever you see a <code>CommandLineProgram</code> value, you know that, at run-time, something impure is likely to happen. It's not <em>uncontrolled</em> impurity, though. Inside a <code>CommandLineProgram</code>, only reading from, and writing to, the command line will happen. It's not going to generate random values, change global variables, send an email, or any other unpredictable operation - that is, unless the interpreter does that... </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/07/17/a-pure-command-line-wizard">A pure command-line wizard</a>. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Pure interactions http://blog.ploeh.dk/2017/07/10/pure-interactions 2017-07-10T14:29:00+00:00 Mark Seemann <div id="post"> <p> <em>Long-running, non-deterministic interactions can be modelled in a pure, functional way.</em> </p> <p> In a <a href="http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection">previous article</a>, you can read why Dependency Injection and (strict) functional programming are mutually exclusive. Dependency Injection makes everything impure, and if nothing is <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a>, then it's hardly functional. In <a href="http://blog.ploeh.dk/2017/02/02/dependency-rejection">Dependency rejection</a>, you can see how you can often separate impure and pure code into an impure/pure/impure sandwich. </p> <p> <strong>Micro-operation-based architectures</strong> </p> <p> The impure/pure/impure sandwich architecture works well in scenarios with limited interaction. Some data arrives at the boundary of the system, the system responds, and that's it. That, however, describes a significant fraction of all software running in the world today. </p> <p> Any HTTP-based application (web site, REST API, most SOAP services) fits the description: an HTTP request arrives, and the server responds with an HTTP response. In a well-designed and well-running system, you should return the response within seconds, if not faster. Everything the software needs in order to run to completion is either part of the request, or part of the application state. You may need to query a database to gather more data based on the incoming request, but you can still gather most data from impure sources, pass it all to your pure core implementation, get the pure values back and return the response. </p> <p> Likewise, asynchronous message-based systems, such as pub/sub, Pipes and Filters, Actor-based systems, 'SOA done right', CQRS/Event Sourcing, and so on, are based on short-lived, stateless interactions. Similar to HTTP-based applications, there's often (persisted) application state, but once a message arrives at a message handler, the software should process it as quickly as possible. Again, it can read extra (impure) data from a database, pass everything to a pure function, and finally do something impure with the return value. </p> <p> Common for all such systems is that while they can handle large volumes of data, they do so as the result of a multitude of parallel, distinct, and isolated micro-operations. </p> <p> <strong>Interactive software</strong> </p> <p> There is, however, another category of software. We could call it 'interactive software'. As the name implies, this includes everything with a user interface, but can also be a long-running batch job, or, as you've <a href="http://blog.ploeh.dk/2017/06/27/pure-times">already seen</a>, time-sensitive software. </p> <p> For such software, the impure/pure/impure sandwich architecture is no longer possible. Just think of a UI-based program, like an email client. You compose and send an email, receive a response, then compose a reply, and so on. Every send and receive is impure, as is all the user interface rendering. What happens next depends on what happened before, and everything that happens in the real world is impure. </p> <p> Have we finally identified the limitations of functional programming? </p> <p> Hardly. In this series of articles, I'm going to show you how to model pure interactions: <ul> <li><a href="http://blog.ploeh.dk/2017/07/11/hello-pure-command-line-interaction">Hello, pure command-line interaction</a></li> <li><a href="http://blog.ploeh.dk/2017/07/17/a-pure-command-line-wizard">A pure command-line wizard</a></li> <li><a href="http://blog.ploeh.dk/2017/07/24/combining-free-monads-in-haskell">Combining free monads in Haskell</a></li> <li><a href="http://blog.ploeh.dk/2017/07/31/combining-free-monads-in-f">Combining free monads in F#</a></li> <li><a href="http://blog.ploeh.dk/2017/08/07/f-free-monad-recipe">F# free monad recipe</a></li> </ul> You can skip the Haskell article if you only want to read the F# articles. </p> <p> This series of articles gives you a comprehensive walkthrough of pure interactions and free monads in F#. For a motivating example, see <a href="http://blog.ploeh.dk/2017/06/27/pure-times">Pure times</a>, which presents a more realistic example that, on the other hand, doesn't go to the same level of detail. </p> <p> <strong>Summary</strong> </p> <p> The solution to the problem of continuous impure interactions is to model them as a instructions in a (domain-specific) Abstract Syntax Tree (AST), and then using an impure interpreter for the pure AST. You can model the AST as a (free) monad in order to make the required syntax nice. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/07/11/hello-pure-command-line-interaction">Hello, pure command-line interaction</a>. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Pure times in F# http://blog.ploeh.dk/2017/07/04/pure-times-in-f 2017-07-04T07:07:00+00:00 Mark Seemann <div id="post"> <p> <em>A Polling Consumer implementation written in F#.</em> </p> <p> <a href="http://blog.ploeh.dk/2017/06/28/pure-times-in-haskell">Previously</a>, you saw how to implement a <a href="http://www.enterpriseintegrationpatterns.com/PollingConsumer.html">Polling Consumer</a> in <a href="https://www.haskell.org">Haskell</a>. This proves that it's possible to write <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a> functional code modelling long-running interactions with the (impure) world. In this article, you'll see how to port the Haskell code to F#. </p> <p> For reference, I'll repeat the state transition diagram here: </p> <p> <img src="/content/binary/polling-consumer-finite-state-machine.png" alt="Polling Consumer state machine transition diagram"> </p> <p> For a complete description of the goals and constraints of this particular Polling Consumer implementation, see my earlier <a href="http://blog.ploeh.dk/2015/08/10/type-driven-development">Type Driven Development</a> article, or, even better, watch my Pluralsight course <a href="http://www.shareasale.com/r.cfm?u=1017843&b=611266&m=53701&afftrack=&urllink=www%2Epluralsight%2Ecom%2Fcourses%2Ffsharp%2Dtype%2Ddriven%2Ddevelopment">Type-Driven Development with F#</a>. </p> <p> <strong>State data types</strong> </p> <p> The program has to keep track of various durations. You can model these as naked <code>TimeSpan</code> values, but in order to add extra type safety, you can, instead, define them as separate types: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PollDuration</span>&nbsp;=&nbsp;<span style="color:navy;">PollDuration</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">TimeSpan</span> <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">IdleDuration</span>&nbsp;=&nbsp;<span style="color:navy;">IdleDuration</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">TimeSpan</span> <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">HandleDuration</span>&nbsp;=&nbsp;<span style="color:navy;">HandleDuration</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">TimeSpan</span> <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CycleDuration</span>&nbsp;=&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;PollDuration&nbsp;:&nbsp;<span style="color:teal;">PollDuration</span> &nbsp;&nbsp;&nbsp;&nbsp;HandleDuration&nbsp;:&nbsp;<span style="color:teal;">HandleDuration</span>&nbsp;}</pre> </p> <p> This is a straightforward port of the Haskell code. See the <a href="http://blog.ploeh.dk/2017/06/28/pure-times-in-haskell">previous article</a> for more details about the motivation for doing this. </p> <p> You can now define the states of the finite state machine: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">State</span>&lt;&#39;msg&gt;&nbsp;= |&nbsp;<span style="color:navy;">ReadyState</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">CycleDuration</span>&nbsp;<span style="color:teal;">list</span> |&nbsp;<span style="color:navy;">ReceivedMessageState</span>&nbsp;<span style="color:blue;">of</span>&nbsp;(<span style="color:teal;">CycleDuration</span>&nbsp;<span style="color:teal;">list</span>&nbsp;*&nbsp;<span style="color:teal;">PollDuration</span>&nbsp;*&nbsp;&#39;msg) |&nbsp;<span style="color:navy;">NoMessageState</span>&nbsp;<span style="color:blue;">of</span>&nbsp;(<span style="color:teal;">CycleDuration</span>&nbsp;<span style="color:teal;">list</span>&nbsp;*&nbsp;<span style="color:teal;">PollDuration</span>) |&nbsp;<span style="color:navy;">StoppedState</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">CycleDuration</span>&nbsp;<span style="color:teal;">list</span></pre> </p> <p> Again, this is a straight port of the Haskell code. </p> <p> <strong>From instruction set to syntactic sugar</strong> </p> <p> The Polling Consumer must interact with its environment in various ways: <ol> <li>Query the system clock</li> <li>Poll for messages</li> <li>Handle messages</li> <li>Idle</li> </ol> You can model these four cases of interactions as a single discriminated union that describe a small instruction set: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PollingInstruction</span>&lt;&#39;msg,&nbsp;&#39;next&gt;&nbsp;= |&nbsp;<span style="color:navy;">CurrentTime</span>&nbsp;<span style="color:blue;">of</span>&nbsp;(<span style="color:teal;">DateTimeOffset</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;&#39;next) |&nbsp;<span style="color:navy;">Poll</span>&nbsp;<span style="color:blue;">of</span>&nbsp;((&#39;msg&nbsp;<span style="color:teal;">option</span>&nbsp;*&nbsp;<span style="color:teal;">PollDuration</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;&#39;next) |&nbsp;<span style="color:navy;">Handle</span>&nbsp;<span style="color:blue;">of</span>&nbsp;(&#39;msg&nbsp;*&nbsp;(<span style="color:teal;">HandleDuration</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;&#39;next)) |&nbsp;<span style="color:navy;">Idle</span>&nbsp;<span style="color:blue;">of</span>&nbsp;(<span style="color:teal;">IdleDuration</span>&nbsp;*&nbsp;(<span style="color:teal;">IdleDuration</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;&#39;next))</pre> </p> <p> Once more, this is a direct translation of the Haskell code, but from here, this is where your F# code will have to deviate from Haskell. In Haskell, you can, with a single line of code, declare that such a type is a functor. This isn't possible in F#. Instead, you have to explicitly write a <em>map</em> function. This isn't difficult, though. There's a reason that the Haskell compiler can automate this: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;PollingInstruction&lt;&#39;c,&#39;a&gt;&nbsp;-&gt;&nbsp;PollingInstruction&lt;&#39;c,&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:navy;">mapI</span>&nbsp;<span style="color:navy;">f</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">CurrentTime</span>&nbsp;<span style="color:navy;">next</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">CurrentTime</span>&nbsp;(<span style="color:navy;">next</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">f</span>) &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Poll</span>&nbsp;<span style="color:navy;">next</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Poll</span>&nbsp;(<span style="color:navy;">next</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">f</span>) &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Handle</span>&nbsp;(x,&nbsp;<span style="color:navy;">next</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Handle</span>&nbsp;(x,&nbsp;<span style="color:navy;">next</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">f</span>) &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Idle</span>&nbsp;(x,&nbsp;<span style="color:navy;">next</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Idle</span>&nbsp;(x,&nbsp;<span style="color:navy;">next</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">f</span>)</pre> </p> <p> The function is named <code>mapI</code>, where the <code>I</code> stands for <em>instruction</em>. It's <code>private</code> because the next step is to package the functor in a monad. From that monad, you can define a new functor, so in order to prevent any confusion, I decided to hide the underlying functor from any consumers of the API. </p> <p> Defining a map function for a generic type like <code>PollingInstruction&lt;'msg, 'next&gt;</code> is well-defined. Pattern-match each union case and return the same case, but with the <code>next</code> function composed with the input function argument <code>f</code>: <code>next &gt;&gt; f</code>. In later articles, you'll see more examples, and you'll see how <a href="http://blog.ploeh.dk/2017/08/07/f-free-monad-recipe">this recipe is entirely repeatable</a> and automatable. </p> <p> While a <em>functor</em> isn't an explicit concept in F#, this is how <code>PollingInstruction msg next</code> is a <code>Functor</code> in Haskell. Given a functor, you can produce a free monad. The reason you'd want to do this is that once you have a monad, you can get syntactic sugar. Currently, <code>PollingInstruction&lt;'msg, 'next&gt;</code> only enables you to create Abstract Syntax Trees (ASTs), but the programming experience would be cumbersome and alien. Monads give you automatic <code>do</code> notation in Haskell; in F#, it enables you to write a <a href="https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/computation-expressions">computation expression builder</a>. </p> <p> Haskell's type system enables you to make a monad from a functor with a one-liner: <code>type PollingProgram msg = Free (PollingInstruction msg)</code>. In F#, you'll have to write some boilerplate code. First, you have to define the monadic type: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PollingProgram</span>&lt;&#39;msg,&nbsp;&#39;next&gt;&nbsp;= |&nbsp;<span style="color:navy;">Free</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">PollingInstruction</span>&lt;&#39;msg,&nbsp;<span style="color:teal;">PollingProgram</span>&lt;&#39;msg,&nbsp;&#39;next&gt;&gt; |&nbsp;<span style="color:navy;">Pure</span>&nbsp;<span style="color:blue;">of</span>&nbsp;&#39;next</pre> </p> <p> You already saw a hint of such a type in the previous article. The <code>PollingProgram&lt;'msg, 'next&gt;</code> discriminated union defines two cases: <code>Free</code> and <code>Pure</code>. The <code>Free</code> case is a <code>PollingInstruction</code> that produces a new <code>PollingProgram</code> as its next step. In essence, this enables you to build an AST, but you also need a signal to stop and return a value from the AST. That's the purpose of the <code>Pure</code> case. </p> <p> Such a type is only a monad if it defines a <code>bind</code> function (that obey the monad laws): </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;PollingProgram&lt;&#39;b,&#39;c&gt;)&nbsp;-&gt;&nbsp;PollingProgram&lt;&#39;b,&#39;a&gt;</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;PollingProgram&lt;&#39;b,&#39;c&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;bind&nbsp;f&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Free&nbsp;instruction&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;instruction&nbsp;|&gt;&nbsp;mapI&nbsp;(bind&nbsp;f)&nbsp;|&gt;&nbsp;Free &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Pure&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;f&nbsp;x</pre> </p> <p> This <code>bind</code> function pattern-matches on <code>Free</code> and <code>Pure</code>, respectively. In the <code>Pure</code> case, it simply uses the underlying result value <code>x</code> as an input argument to <code>f</code>. In the <code>Free</code> case, it composes the underlying functor (<code>mapI</code>) with itself recursively. If you find this step obscure, I will not blame you. Just like the implementation of <code>mapI</code> is a bit of boilerplate code, then so is this. It always seems to work this way. If you want to dig deeper into the inner workings of this, then <a href="https://fsharpforfunandprofit.com">Scott Wlaschin</a> has a <a href="https://fsharpforfunandprofit.com/posts/13-ways-of-looking-at-a-turtle-2/#way13">detailed explanation</a>. </p> <p> With the addition of <code>bind</code> <code>PollingProgram&lt;'msg, 'next&gt;</code> becomes a monad (I'm not going to show that the monad laws hold, but they do). Making it a functor is trivial: </p> <p> <pre><span style="color:green;">//&nbsp;&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;PollingProgram&lt;&#39;c,&#39;a&gt;&nbsp;-&gt;&nbsp;PollingProgram&lt;&#39;c,&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;map&nbsp;f&nbsp;=&nbsp;bind&nbsp;(f&nbsp;&gt;&gt;&nbsp;Pure)</pre> </p> <p> The underlying <code>PollingInstruction</code> type was already a functor. This function makes <code>PollingProgram</code> a functor as well. </p> <p> It'll be convenient with some functions that lifts each <code>PollingInstruction</code> case to a corresponding <code>PollingProgram</code> value. In Haskell, you can use the <code>liftF</code> function for this, but in F# you'll have to be slightly more explicit: </p> <p> <pre><span style="color:green;">//&nbsp;PollingProgram&lt;&#39;a,DateTimeOffset&gt;</span> <span style="color:blue;">let</span>&nbsp;currentTime&nbsp;=&nbsp;Free&nbsp;(CurrentTime&nbsp;Pure) <span style="color:green;">//&nbsp;PollingProgram&lt;&#39;a,(&#39;a&nbsp;option&nbsp;*&nbsp;PollDuration)&gt;</span> <span style="color:blue;">let</span>&nbsp;poll&nbsp;=&nbsp;Free&nbsp;(Poll&nbsp;Pure) <span style="color:green;">//&nbsp;&#39;a&nbsp;-&gt;&nbsp;PollingProgram&lt;&#39;a,HandleDuration&gt;</span> <span style="color:blue;">let</span>&nbsp;handle&nbsp;msg&nbsp;=&nbsp;Free&nbsp;(Handle&nbsp;(msg,&nbsp;Pure)) <span style="color:green;">//&nbsp;IdleDuration&nbsp;-&gt;&nbsp;PollingProgram&lt;&#39;a,IdleDuration&gt;</span> <span style="color:blue;">let</span>&nbsp;idle&nbsp;duration&nbsp;=&nbsp;Free&nbsp;(Idle&nbsp;(duration,&nbsp;Pure))</pre> </p> <p> <code>currentTime</code> and <code>poll</code> aren't even functions, but <em>values</em>. They are, however, small <code>PollingProgram</code> values, so while they look like values (as contrasted to functions), they represent singular executable instructions. </p> <p> <code>handle</code> and <code>idle</code> are both functions that return <code>PollingProgram</code> values. </p> <p> You can now implement a small computation expression builder: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PollingBuilder</span>&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">Bind</span>&nbsp;(x,&nbsp;<span style="color:navy;">f</span>)&nbsp;=&nbsp;<span style="color:teal;">Polling</span>.<span style="color:navy;">bind</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">Return</span>&nbsp;x&nbsp;=&nbsp;<span style="color:navy;">Pure</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">ReturnFrom</span>&nbsp;x&nbsp;=&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;<span style="color:#9b9b9b;">this</span>.<span style="color:navy;">Zero</span>&nbsp;()&nbsp;=&nbsp;this.<span style="color:navy;">Return</span>&nbsp;()</pre> </p> <p> As you can tell, not much is going on here. The <code>Bind</code> method simply delegates to the above <code>bind</code> function, and the rest are trivial one-liners. </p> <p> You can create an instance of the <code>PollingBuilder</code> class so that you can write <code>PollingProgram</code>s with syntactic sugar: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;polling&nbsp;=&nbsp;<span style="color:teal;">PollingBuilder</span>&nbsp;() </pre> </p> <p> This enables you to write <code>polling</code> computation expressions. You'll see examples of this shortly. </p> <p> Most of the code you've seen here is automated in Haskell. This means that while you'll have to explicitly write it in F#, it follows <a href="http://blog.ploeh.dk/2017/08/07/f-free-monad-recipe">a recipe</a>. Once you get the hang of it, it doesn't take much time. The maintenance overhead of the code is also minimal, because you're essentially implementing a universal abstraction. It's not going to change. </p> <p> <strong>Support functions</strong> </p> <p> Continuing the port of the previous article's Haskell code, you can write a pair of support functions. These are small <code>PollingProgram</code> values: </p> <p> <pre><span style="color:green;">//&nbsp;IdleDuration&nbsp;-&gt;&nbsp;DateTimeOffset&nbsp;-&gt;&nbsp;PollingProgram&lt;&#39;a,bool&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:navy;">shouldIdle</span>&nbsp;(<span style="color:navy;">IdleDuration</span>&nbsp;d)&nbsp;stopBefore&nbsp;=&nbsp;<span style="color:blue;">polling</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;now&nbsp;=&nbsp;<span style="color:teal;">Polling</span>.currentTime &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;now&nbsp;+&nbsp;d&nbsp;&lt;&nbsp;stopBefore&nbsp;}</pre> </p> <p> This <code>shouldIdle</code> function uses the <code>polling</code> computation expression defined above. It first uses the above <code>Polling.currentTime</code> value to get the current time. While <code>Polling.currentTime</code> is a value of the type <code>PollingProgram&lt;'b,DateTimeOffset&gt;</code>, the <code>let!</code> binding makes <code>now</code> a simple <code>DateTimeOffset</code> value. Computation expressions give you the same sort of syntactic sugar that <code>do</code> notation does in Haskell. </p> <p> If you add <code>now</code> to <code>d</code>, you get a new <code>DateTimeOffset</code> value that represents the time that the program will resume, <em>if</em> it decides to suspend itself for the idle duration. If this time is before <code>stopBefore</code>, the return value is <code>true</code>; otherwise, it's <code>false</code>. Similar to the Haskell example, the return value of <code>shouldIdle</code> isn't just <code>bool</code>, but rather <code>PollingProgram&lt;'a,bool&gt;</code>, because it all takes place inside the <code>polling</code> computation expression. </p> <p> The function looks impure, but it <em>is</em> pure. </p> <p> In the same vein, you can implement a <code>shouldPoll</code> function: </p> <p> <pre><span style="color:green;">//&nbsp;CycleDuration&nbsp;-&gt;&nbsp;TimeSpan</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">toTotalCycleTimeSpan</span>&nbsp;x&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;(<span style="color:navy;">PollDuration</span>&nbsp;pd)&nbsp;=&nbsp;x.PollDuration &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;(<span style="color:navy;">HandleDuration</span>&nbsp;hd)&nbsp;=&nbsp;x.HandleDuration &nbsp;&nbsp;&nbsp;&nbsp;pd&nbsp;+&nbsp;hd <span style="color:green;">//&nbsp;TimeSpan&nbsp;-&gt;&nbsp;DateTimeOffset&nbsp;-&gt;&nbsp;CycleDuration&nbsp;list&nbsp;-&gt;&nbsp;PollingProgram&lt;&#39;a,bool&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:navy;">shouldPoll</span>&nbsp;estimatedDuration&nbsp;stopBefore&nbsp;statistics&nbsp;=&nbsp;<span style="color:blue;">polling</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;expectedHandleDuration&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;statistics &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">List</span>.<span style="color:navy;">map</span>&nbsp;<span style="color:navy;">toTotalCycleTimeSpan</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Statistics</span>.<span style="color:navy;">calculateExpectedDuration</span>&nbsp;estimatedDuration &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;now&nbsp;=&nbsp;<span style="color:teal;">Polling</span>.currentTime &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;now&nbsp;+&nbsp;expectedHandleDuration&nbsp;&lt;&nbsp;stopBefore&nbsp;}</pre> </p> <p> This function uses two helper functions: <code>toTotalCycleTimeSpan</code> and <code>Statistics.calculateExpectedDuration</code>. I've included <code>toTotalCycleTimeSpan</code> in the code shown here, while I'm skipping <code>Statistics.calculateExpectedDuration</code>, because it hasn't changed since the code I show in <a href="http://www.shareasale.com/r.cfm?u=1017843&b=611266&m=53701&afftrack=&urllink=www%2Epluralsight%2Ecom%2Fcourses%2Ffsharp%2Dtype%2Ddriven%2Ddevelopment">my Pluralsight course</a>. You can also see the function in the <a href="https://github.com/ploeh/PollingConsumer">GitHub repository accompanying this article</a>. </p> <p> Compared to <code>shouldIdle</code>, the <code>shouldPoll</code> function needs an extra (pure) step in order to figure out the <code>expectedHandleDuration</code>, but from there, the two functions are similar. </p> <p> <strong>Transitions</strong> </p> <p> All building blocks are now ready for the finite state machine. In order to break the problem into manageable pieces, you can write a function for each state. Such a function should take as input the data associated with a particular state, and return the next state, based on the input. </p> <p> The simplest transition is when the program reaches the <em>end</em> state, because there's no way out of that state: </p> <p> <pre><span style="color:green;">//&nbsp;CycleDuration&nbsp;list&nbsp;-&gt;&nbsp;PollingProgram&lt;&#39;a,State&lt;&#39;b&gt;&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">transitionFromStopped</span>&nbsp;s&nbsp;=&nbsp;<span style="color:blue;">polling</span>&nbsp;{&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:navy;">StoppedState</span>&nbsp;s&nbsp;}</pre> </p> <p> The data contained in a <code>StoppedState</code> case has the type <code>CycleDuration list</code>, so the <code>transitionFromStopped</code> function simply lifts such a list to a <code>PollingProgram</code> value by returning a <code>StoppedState</code> value from within a <code>polling</code> computation expression. </p> <p> Slightly more complex, but still simple, is the transition out of the <em>received</em> state. There's no branching logic involved. You just have to handle the message, measure how much time it takes, append the measurements to previous statistics, and return to the <em>ready</em> state: </p> <p> <pre><span style="color:green;">//&nbsp;CycleDuration&nbsp;list&nbsp;*&nbsp;PollDuration&nbsp;*&nbsp;&#39;a&nbsp;-&gt;&nbsp;PollingProgram&lt;&#39;a,State&lt;&#39;b&gt;&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">transitionFromReceived</span>&nbsp;(statistics,&nbsp;pd,&nbsp;msg)&nbsp;=&nbsp;<span style="color:blue;">polling</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;hd&nbsp;=&nbsp;<span style="color:teal;">Polling</span>.<span style="color:navy;">handle</span>&nbsp;msg &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;PollDuration&nbsp;=&nbsp;pd;&nbsp;HandleDuration&nbsp;=&nbsp;hd&nbsp;}&nbsp;<span style="color:navy;">::</span>&nbsp;statistics &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">ReadyState</span>&nbsp;}</pre> </p> <p> This function uses the <code>Polling.handle</code> convenience function to handle the input message. Although the <code>handle</code> function returns a <code>PollingProgram&lt;'a,HandleDuration&gt;</code> value, the <code>let!</code> binding inside of a <code>polling</code> computation expression makes <code>hd</code> a <code>HandleDuration</code> value. </p> <p> The data contained within a <code>ReceivedMessageState</code> case is a <code>CycleDuration list * PollDuration * 'msg</code> tuple. That's the input argument to the <code>transitionFromReceived</code> function, which immediately pattern-matches the tuple's three elements into <code>statistics</code>, <code>pd</code>, and <code>msg</code>. </p> <p> The <code>pd</code> element is the <code>PollDuration</code> - i.e. the time it took to reach the <em>received</em> state. The <code>hd</code> value returned by <code>Polling.handle</code> gives you the time it took to handle the message. From those two values you can create a new <code>CycleDuration</code> value, and cons (<code>::</code>) it onto the previous <code>statistics</code>. This returns an updated list of statistics that you can pipe to the <code>ReadyState</code> case constructor. </p> <p> <code>ReadyState</code> in itself creates a new <code>State&lt;'msg&gt;</code> value, but since all of this takes place inside a <code>polling</code> computation expression, the return type of the function becomes <code>PollingProgram&lt;'a,State&lt;'b&gt;&gt;</code>. </p> <p> The <code>transitionFromReceived</code> function handles the state when the program has received a message, but you also need to handle the state when no message was received: </p> <p> <pre><span style="color:green;">//&nbsp;IdleDuration&nbsp;-&gt;&nbsp;DateTimeOffset&nbsp;-&gt;&nbsp;CycleDuration&nbsp;list&nbsp;*&nbsp;&#39;a</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;PollingProgram&lt;&#39;b,State&lt;&#39;c&gt;&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">transitionFromNoMessage</span>&nbsp;d&nbsp;stopBefore&nbsp;(statistics,&nbsp;_)&nbsp;=&nbsp;<span style="color:blue;">polling</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;b&nbsp;=&nbsp;<span style="color:navy;">shouldIdle</span>&nbsp;d&nbsp;stopBefore &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;b&nbsp;<span style="color:blue;">then</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;<span style="color:teal;">Polling</span>.<span style="color:navy;">idle</span>&nbsp;d&nbsp;|&gt;&nbsp;<span style="color:teal;">Polling</span>.<span style="color:navy;">map</span>&nbsp;<span style="color:navy;">ignore</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:navy;">ReadyState</span>&nbsp;statistics &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:navy;">StoppedState</span>&nbsp;statistics&nbsp;}</pre> </p> <p> This function first calls the <code>shouldIdle</code> support function. Similar to Haskell, you can see how you can compose larger <code>PollingProgram</code>s from smaller <code>PollingProgram</code> values - just like you can compose 'normal' functions from smaller functions. </p> <p> With the syntactic sugar in place, <code>b</code> is simply a <code>bool</code> value that you can use in a standard <code>if/then/else</code> expression. If <code>b</code> is <code>false</code>, then return a <code>StoppedState</code> value; otherwise, continue with the next steps. </p> <p> <code>Polling.idle</code> returns the duration of the suspension, but you don't actually need this data, so you can <code>ignore</code> it. When <code>Polling.idle</code> returns, you can return a <code>ReadyState</code> value. </p> <p> It may look as though that <code>do!</code> expression is a blocking call, but it really isn't. The <code>transitionFromNoMessage</code> function only builds an Abstract Syntax Tree, where one of the instructions suggests that an interpreter could block. Unless evaluated by an impure interpreter, <code>transitionFromNoMessage</code> is pure. </p> <p> The final transition is the most complex, because there are three possible outcomes: </p> <p> <pre><span style="color:green;">//&nbsp;TimeSpan&nbsp;-&gt;&nbsp;DateTimeOffset&nbsp;-&gt;&nbsp;CycleDuration&nbsp;list</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;PollingProgram&lt;&#39;a,State&lt;&#39;a&gt;&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">transitionFromReady</span>&nbsp;estimatedDuration&nbsp;stopBefore&nbsp;statistics&nbsp;=&nbsp;<span style="color:blue;">polling</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;b&nbsp;=&nbsp;<span style="color:navy;">shouldPoll</span>&nbsp;estimatedDuration&nbsp;stopBefore&nbsp;statistics &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;b&nbsp;<span style="color:blue;">then</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;pollResult&nbsp;=&nbsp;<span style="color:teal;">Polling</span>.poll &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;pollResult&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Some</span>&nbsp;msg,&nbsp;pd&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:navy;">ReceivedMessageState</span>&nbsp;(statistics,&nbsp;pd,&nbsp;msg) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">None</span>,&nbsp;pd&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:navy;">NoMessageState</span>&nbsp;(statistics,&nbsp;pd) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:navy;">StoppedState</span>&nbsp;statistics&nbsp;}</pre> </p> <p> In the same way that <code>transitionFromNoMessage</code> uses <code>shouldIdle</code>, the <code>transitionFromReady</code> function uses the <code>shouldPoll</code> support function to decide whether or not to keep going. If <code>b</code> is <code>false</code>, it returns a <code>StoppedState</code> value. </p> <p> Otherwise, it goes on to <code>poll</code>. Thanks to all the syntactic sugar, <code>pollResult</code> is an <code>'a option * PollDuration</code> value. As always, when you have a discriminated union, you can handle all cases with pattern matching (and the compiler will help you keep track of whether or not you've handled all of them). </p> <p> In the <code>Some</code> case, you have a message, and the duration it took to poll for that message. This is all the data you need to return a <code>ReceivedMessageState</code> value. </p> <p> In the <code>None</code> case, you also have the poll duration <code>pd</code>; return a <code>NoMessageState</code> value. </p> <p> That's four transition functions that you can combine in a single function that, for any state, returns a new state: </p> <p> <pre><span style="color:green;">//&nbsp;TimeSpan&nbsp;-&gt;&nbsp;IdleDuration&nbsp;-&gt;&nbsp;DateTimeOffset&nbsp;-&gt;&nbsp;State&lt;&#39;a&gt;</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;PollingProgram&lt;&#39;a,State&lt;&#39;a&gt;&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">transition</span>&nbsp;estimatedDuration&nbsp;idleDuration&nbsp;stopBefore&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">ReadyState</span>&nbsp;s&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">transitionFromReady</span>&nbsp;estimatedDuration&nbsp;stopBefore&nbsp;s &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">ReceivedMessageState</span>&nbsp;s&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">transitionFromReceived</span>&nbsp;s &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">NoMessageState</span>&nbsp;s&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">transitionFromNoMessage</span>&nbsp;idleDuration&nbsp;stopBefore&nbsp;s &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">StoppedState</span>&nbsp;s&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">transitionFromStopped</span>&nbsp;s</pre> </p> <p> You simply pattern-match the (implicit) input argument with the four state cases, and call the appropriate transition function for each case. </p> <p> <strong>Interpretation</strong> </p> <p> The <code>transition</code> function is pure. It returns a <code>PollingProgram</code> value. How do you turn it into something that performs real work? </p> <p> You write an interpreter: </p> <p> <pre><span style="color:green;">//&nbsp;PollingProgram&lt;Msg,&#39;a&gt;&nbsp;-&gt;&nbsp;&#39;a</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;<span style="color:navy;">interpret</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Pure</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Free</span>&nbsp;(<span style="color:navy;">CurrentTime</span>&nbsp;<span style="color:navy;">next</span>)&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:teal;">DateTimeOffset</span>.Now&nbsp;|&gt;&nbsp;<span style="color:navy;">next</span>&nbsp;|&gt;&nbsp;<span style="color:navy;">interpret</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Free</span>&nbsp;(<span style="color:navy;">Poll</span>&nbsp;<span style="color:navy;">next</span>)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:teal;">Imp</span>.<span style="color:navy;">poll</span>&nbsp;()&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">next</span>&nbsp;|&gt;&nbsp;<span style="color:navy;">interpret</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Free</span>&nbsp;(<span style="color:navy;">Handle</span>&nbsp;(msg,&nbsp;<span style="color:navy;">next</span>))&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:teal;">Imp</span>.<span style="color:navy;">handle</span>&nbsp;msg&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">next</span>&nbsp;|&gt;&nbsp;<span style="color:navy;">interpret</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Free</span>&nbsp;(<span style="color:navy;">Idle</span>&nbsp;(d,&nbsp;<span style="color:navy;">next</span>))&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:teal;">Imp</span>.<span style="color:navy;">idle</span>&nbsp;d&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">next</span>&nbsp;|&gt;&nbsp;<span style="color:navy;">interpret</span></pre> </p> <p> A <code>PollingProgram</code> is either a <code>Pure</code> or a <code>Free</code> case. In the <code>Free</code> case, the contained data is a <code>PollingInstruction</code> value, which can be one of four separate cases. With pattern matching, the interpreter handles all five cases. </p> <p> In the <code>Pure</code> case, it returns the value, but in all the <code>Free</code> cases, it recursively calls itself after having first followed the instruction in each <code>PollingInstruction</code> case. For instance, when the instruction is <code>CurrentTime</code>, it invokes <code>DateTimeOffset.Now</code>, passes the return value (a <code>DateTimeOffset</code> value) to the <code>next</code> continuation, and then recursively calls <code>interpret</code>. The next instruction, then, could be another <code>Free</code> case, or it could be <code>Pure</code>. </p> <p> The other three instruction cases delegate to implementation functions defined in an <code>Imp</code> module. I'm not going to show them here. They're normal, although impure, F# functions. </p> <p> <strong>Execution</strong> </p> <p> You're almost done. You have a function that returns a new state for any given input state, as well as an interpreter. You need a function that can repeat this in a loop until it reaches <code>StoppedState</code>: </p> <p> <pre><span style="color:green;">//&nbsp;TimeSpan&nbsp;-&gt;&nbsp;IdleDuration&nbsp;-&gt;&nbsp;DateTimeOffset&nbsp;-&gt;&nbsp;State&lt;Msg&gt;&nbsp;-&gt;&nbsp;State&lt;Msg&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;<span style="color:navy;">run</span>&nbsp;estimatedDuration&nbsp;idleDuration&nbsp;stopBefore&nbsp;s&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;ns&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">PollingConsumer</span>.<span style="color:navy;">transition</span>&nbsp;estimatedDuration&nbsp;idleDuration&nbsp;stopBefore&nbsp;s &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">interpret</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;ns&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:teal;">PollingConsumer</span>.<span style="color:navy;">StoppedState</span>&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;ns &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">run</span>&nbsp;estimatedDuration&nbsp;idleDuration&nbsp;stopBefore&nbsp;ns</pre> </p> <p> This function calls <code>PollingConsumer.transition</code> with the input state <code>s</code>, which returns a new <code>PollingProgram&lt;Msg,PollingConsumer.State&lt;Msg&gt;&gt;</code> value that you can pipe to the <code>interpret</code> function. That gives you the new state <code>ns</code>. If <code>ns</code> is a <code>StoppedState</code>, you return; otherwise, you recurse into <code>run</code> for another round. </p> <p> Finally, you can write the entry point for the application: </p> <p> <pre>[&lt;<span style="color:teal;">EntryPoint</span>&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">main</span>&nbsp;_&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;timeAtEntry&nbsp;=&nbsp;<span style="color:teal;">DateTimeOffset</span>.Now &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">printOnEntry</span>&nbsp;timeAtEntry &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;stopBefore&nbsp;=&nbsp;timeAtEntry&nbsp;+&nbsp;limit &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;estimatedDuration&nbsp;=&nbsp;<span style="color:teal;">TimeSpan</span>.<span style="color:navy;">FromSeconds</span>&nbsp;2. &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;idleDuration&nbsp;=&nbsp;<span style="color:teal;">TimeSpan</span>.<span style="color:navy;">FromSeconds</span>&nbsp;5.&nbsp;|&gt;&nbsp;<span style="color:navy;">IdleDuration</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;durations&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">PollingConsumer</span>.<span style="color:navy;">ReadyState</span>&nbsp;[] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">run</span>&nbsp;estimatedDuration&nbsp;idleDuration&nbsp;stopBefore &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">PollingConsumer</span>.<span style="color:navy;">durations</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">List</span>.<span style="color:navy;">map</span>&nbsp;<span style="color:teal;">PollingConsumer</span>.<span style="color:navy;">toTotalCycleTimeSpan</span> &nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">printOnExit</span>&nbsp;timeAtEntry&nbsp;durations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;Return&nbsp;0.&nbsp;This&nbsp;indicates&nbsp;success.</span> &nbsp;&nbsp;&nbsp;&nbsp;0</pre> </p> <p> This defines an estimated duration of 2 seconds, an idle duration of 5 seconds, and a maximum run time of 60 seconds (<code>limit</code>). The initial state is <code>ReadyState</code> with no prior statistics. Pass all these arguments to the <code>run</code> function, and you have a running program. </p> <p> This function also uses a few printout functions that I'm not going to show here. When you run the program, you should see output like this: </p> <p> <pre>Started polling at 11:18:28. Polling <span style="color:green;">Handling</span> Polling <span style="color:green;">Handling</span> Polling <span style="color:orange;">Sleeping</span> Polling <span style="color:orange;">Sleeping</span> Polling <span style="color:green;">Handling</span> Polling <span style="color:green;">Handling</span> Polling <span style="color:orange;">Sleeping</span> Polling <span style="color:orange;">Sleeping</span> Polling <span style="color:orange;">Sleeping</span> Polling <span style="color:green;">Handling</span> Polling <span style="color:orange;">Sleeping</span> Polling <span style="color:orange;">Sleeping</span> Polling <span style="color:orange;">Sleeping</span> Polling <span style="color:orange;">Sleeping</span> Polling <span style="color:green;">Handling</span> Stopped polling at 11:19:26. Elapsed time: <span style="color:green;">00:00:58.4428980</span>. Handled 6 message(s). Average duration: 00:00:01.0550346 Standard deviation: 00:00:00.3970599</pre> </p> <p> It does, indeed, exit before 60 seconds have elapsed. </p> <p> <strong>Summary</strong> </p> <p> You can model long-running interactions with an Abstract Syntax Tree. Without computation expressions, writing programs as 'raw' ASTs would be cumbersome, but turning the AST into a (free) monad makes it all quite palatable. </p> <p> Haskell code with a free monad can be ported to F#, although some boilerplate code is required. That code, however, is unlikely to be much of a burden, because it follows a well-known recipe that implements a universal abstraction. </p> <p> For more details on how to write free monads in F#, see <a href="http://blog.ploeh.dk/2017/07/10/pure-interactions">Pure interactions</a>. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Pure times in Haskell http://blog.ploeh.dk/2017/06/28/pure-times-in-haskell 2017-06-28T07:54:00+00:00 Mark Seemann <div id="post"> <p> <em>A Polling Consumer implementation written in Haskell.</em> </p> <p> As you can read in the <a href="http://blog.ploeh.dk/2017/06/27/pure-times">introductory article</a>, I've come to realise that the <a href="http://www.enterpriseintegrationpatterns.com/PollingConsumer.html">Polling Consumer</a> that I <a href="http://blog.ploeh.dk/2015/08/10/type-driven-development">originally wrote in F#</a> isn't particularly functional. Being the friendly and productive language that it is, F# doesn't protect you from mixing pure and impure code, but <a href="https://www.haskell.org">Haskell</a> does. For that reason, you can develop a prototype in Haskell, and later port it to F#, if you want to learn how to solve the problem in a strictly functional way. </p> <p> To recapitulate, the task is to implement a Polling Consumer that runs for a predefined duration, after which it exits (so that it can be restarted by a scheduler). </p> <p> <img src="/content/binary/polling-consumer-finite-state-machine.png" alt="Polling Consumer state machine transition diagram"> </p> <p> The program is a finite state machine that moves between four states. From the <em>ready</em> state, it'll need to decide whether to poll for a new message or exit. Polling and handling takes time (and at compile-time we don't know how long), and the program ought to stop at a pre-defined time. If it gets too close to that time, it should exit, but otherwise, it should attempt to handle a message (and keep track of how long this takes). You can read a more elaborate description of the problem in the <a href="http://blog.ploeh.dk/2015/08/10/type-driven-development">original article</a>. </p> <p> <strong>State data types</strong> </p> <p> The premise in that initial article was that F#'s type system is so powerful that it can aid you in designing a good solution. Haskell's type system is even more powerful, so it can give you even better help. </p> <p> The Polling Consumer program must measure and keep track of how long it takes to poll, handle a message, or idle. All of these are durations. In Haskell, we can represent them as <code>NominalDiffTime</code> values. I'm a bit concerned, though, that if I represent all of these durations as <code>NominalDiffTime</code> values, I may accidentally use a poll duration where I really need a handle duration, and so on. Perhaps I'm being overly cautious, but I like to get help from the type system. In the words of <a href="http://hmemcpy.com">Igal Tabachnik</a>, <em><a href="https://twitter.com/hmemcpy/status/867647943108681728">types prevent typos</a>:</em> </p> <p> <pre><span style="color:blue;">newtype</span>&nbsp;<span style="color:#dd0000;">PollDuration</span>&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">PollDuration</span>&nbsp;<span style="color:#dd0000;">NominalDiffTime</span>&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Eq</span>,&nbsp;<span style="color:#a31515;">Show</span>) <span style="color:blue;">newtype</span>&nbsp;<span style="color:#dd0000;">IdleDuration</span>&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">IdleDuration</span>&nbsp;<span style="color:#dd0000;">NominalDiffTime</span>&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Eq</span>,&nbsp;<span style="color:#a31515;">Show</span>) <span style="color:blue;">newtype</span>&nbsp;<span style="color:#dd0000;">HandleDuration</span>&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">HandleDuration</span>&nbsp;<span style="color:#dd0000;">NominalDiffTime</span>&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Eq</span>,&nbsp;<span style="color:#a31515;">Show</span>) <span style="color:blue;">data</span>&nbsp;<span style="color:#dd0000;">CycleDuration</span>&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">CycleDuration</span> &nbsp;&nbsp;{&nbsp;pollDuration&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">PollDuration</span>,&nbsp;handleDuration&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">HandleDuration</span>&nbsp;} &nbsp;&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Eq</span>,&nbsp;<span style="color:#a31515;">Show</span>)</pre> </p> <p> This simply declares that <code>PollDuration</code>, <code>IdleDuration</code>, and <code>HandleDuration</code> are all <code>NominalDiffTime</code> values, but you can't mistakenly use a <code>PollDuration</code> where a <code>HandleDuration</code> is required, and so on. </p> <p> In addition to those three types of duration, I also define a <code>CycleDuration</code>. This is the data that I actually need to keep track of: <em>how long does it take to handle a single message?</em> I'm assuming that polling for a message is an I/O-bound operation, so it may take significant time. Likewise, handling a message may take time. When deciding whether to exit or handle a new message, both durations count. Instead of defining <code>CycleDuration</code> as a <code>newtype</code> alias for <code>NominalDiffTime</code>, I decided to define it as a record type comprised of a <code>PollDuration</code> and a <code>HandleDuration</code>. It's not that I'm really interested in keeping track of these two values individually, but it protects me from making stupid mistakes. I can only create a <code>CycleDuration</code> value if I have both a <code>PollDuration</code> and a <code>HandleDuration</code> value. </p> <p> In short, I'm trying to combat <a href="http://blog.ploeh.dk/2011/05/25/DesignSmellPrimitiveObsession">primitive obsession</a>. </p> <p> With these duration types in place, you can define the states of the finite state machine: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;<span style="color:#dd0000;">PollingState</span>&nbsp;msg&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Ready</span>&nbsp;[<span style="color:#dd0000;">CycleDuration</span>] &nbsp;&nbsp;<span style="color:#666666;">|</span>&nbsp;<span style="color:#dd0000;">ReceivedMessage</span>&nbsp;[<span style="color:#dd0000;">CycleDuration</span>]&nbsp;<span style="color:#dd0000;">PollDuration</span>&nbsp;msg &nbsp;&nbsp;<span style="color:#666666;">|</span>&nbsp;<span style="color:#dd0000;">NoMessage</span>&nbsp;[<span style="color:#dd0000;">CycleDuration</span>]&nbsp;<span style="color:#dd0000;">PollDuration</span> &nbsp;&nbsp;<span style="color:#666666;">|</span>&nbsp;<span style="color:#dd0000;">Stopped</span>&nbsp;[<span style="color:#dd0000;">CycleDuration</span>] &nbsp;&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Show</span>)</pre> </p> <p> Like the original F# code, state data can be represented as a sum type, with a case for each state. In all four cases, a <code>CycleDuration</code> list keeps track of the observed message-handling statistics. This is the way the program should attempt to calculate whether it's safe to handle another message, or exit. Two of the cases (<code>ReceivedMessage</code> and <code>NoMessage</code>) also contain a <code>PollDuration</code>, which informs the program about the duration of the poll operation that caused it to reach that state. Additionally, the <code>ReceivedMessage</code> case contains a message of the generic type <code>msg</code>. This makes the entire <code>PollingState</code> type generic. A message can be of any type: a string, a number, or a complex data structure. The Polling Consumer program doesn't care, because it doesn't handle messages; it only schedules the polling. </p> <p> This is reminiscent of the previous F# attempt, with the most notable difference that it doesn't attempt to capture durations as <code>Timed&lt;'a&gt;</code> values. It <em>does</em> capture durations, but not when the operations started and stopped. So how will it know what time it is? </p> <p> <strong>Interactions as pure values</strong> </p> <p> This is the heart of the matter. The Polling Consumer must constantly look at the clock. It's under a deadline, and it must also measure durations of poll, handle, and idle operations. All of this is non-deterministic, so not <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a>. The program has to interact with impure operations during its entire lifetime. In fact, its ultimate decision to exit will be based on impure data. How can you model this in a pure fashion? </p> <p> You can model long-running (impure) interactions by defining a small instruction set for an Abstract Syntax Tree (AST). That sounds intimidating, but once you get the hang of it, it becomes routine. In <a href="http://blog.ploeh.dk/2017/07/10/pure-interactions">later articles</a>, I'll expand on this, but for now I'll refer you to <a href="https://fsharpforfunandprofit.com/posts/13-ways-of-looking-at-a-turtle-2/#way13">an excellent article</a> by <a href="https://fsharpforfunandprofit.com">Scott Wlaschin</a>, who explains the approach in F#. </p> <p> <pre><span style="color:blue;">data</span>&nbsp;<span style="color:#dd0000;">PollingInstruction</span>&nbsp;msg&nbsp;next&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">CurrentTime</span>&nbsp;(<span style="color:#dd0000;">UTCTime</span>&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;next) &nbsp;&nbsp;<span style="color:#666666;">|</span>&nbsp;<span style="color:#dd0000;">Poll</span>&nbsp;((<span style="color:#dd0000;">Maybe</span>&nbsp;msg,&nbsp;<span style="color:#dd0000;">PollDuration</span>)&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;next) &nbsp;&nbsp;<span style="color:#666666;">|</span>&nbsp;<span style="color:#dd0000;">Handle</span>&nbsp;msg&nbsp;(<span style="color:#dd0000;">HandleDuration</span>&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;next) &nbsp;&nbsp;<span style="color:#666666;">|</span>&nbsp;<span style="color:#dd0000;">Idle</span>&nbsp;<span style="color:#dd0000;">IdleDuration</span>&nbsp;(<span style="color:#dd0000;">IdleDuration</span>&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;next) &nbsp;&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#a31515;">Functor</span>)</pre> </p> <p> This <code>PollingInstruction</code> sum type defines four cases of interaction. Each case is <ol> <li>named after the interaction</li> <li>defines the type of data used as input arguments for the interaction</li> <li>and also defines a <em>continuation</em>; that is: a function that will be executed with the return value of the interaction</li> </ol> Half of the above cases are degenerate, but the <code>Handle</code> case contains all three elements: the interaction is named <code>Handle</code>, the input to the interaction is of the generic type <code>msg</code>, and the continuation is a function that takes a <code>HandleDuration</code> value as input, and returns a value of the generic type <code>next</code>. In other words, the interaction takes a <code>msg</code> value as input, and returns a <code>HandleDuration</code> value as output. That duration is the time it took to handle the input message. (The intent is that the operation that 'implements' this interaction also actually <em>handles</em> the message, whatever that means.) </p> <p> Likewise, the <code>Idle</code> interaction takes an <code>IdleDuration</code> as input, and also returns an <code>IdleDuration</code>. The intent here is that the 'implementation' of the interaction suspends itself for the duration of the input value, and returns the time it actually spent in suspension (which is likely to be slightly longer than the requested duration). </p> <p> Both <code>CurrentTime</code> and <code>Poll</code>, on the other hand, are degenerate, because they take no input. You don't need to supply any input argument to read the current time. You could model that interaction as taking <code>()</code> ('unit') as an input argument (<code>CurrentTime () (UTCTime -&gt; next)</code>), but the <code>()</code> is redundant and can be omitted. The same is the case for the <code>Poll</code> case, which returns a <code>Maybe msg</code> and how long the poll took. </p> <p> (The <code>PollingInstruction</code> sum type defines four cases, which is also the number of cases defined by <code>PollingState</code>. This is a coincidence; don't read anything into it.) </p> <p> The <code>PollingInstruction</code> type is generic in a way that you can make it a <code>Functor</code>. Haskell can do this for you automatically, using the <code>DeriveFunctor</code> language extension; that's what <code>deriving (Functor)</code> does. If you'd like to see how to explicitly make such a data structure a functor, please refer to the F# example; F# can't automatically derive functors, so you'll have to do it manually. </p> <p> Since <code>PollingInstruction</code> is a <code>Functor</code>, we can make a <code>Monad</code> out of it. <a href="https://twitter.com/hmemcpy/status/771359835514368000">You use a free monad, which allows you to build a monad from any functor</a>: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:#dd0000;">PollingProgram</span>&nbsp;msg&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Free</span>&nbsp;(<span style="color:#dd0000;">PollingInstruction</span>&nbsp;msg) </pre> </p> <p> In Haskell, it's literally a one-liner, but in F# you'll have to write the code yourself. Thus, if you're interested in learning how this magic happens, I'm going to dissect this step in the next article. </p> <p> The motivation for defining a <code>Monad</code> is that we get automatic syntactic sugar for our <code>PollingProgram</code> ASTs, via Haskell's <code>do</code> notation. In F#, we're going to write a computation expression builder to achieve the same effect. </p> <p> The final building blocks for the specialised <code>PollingProgram</code> API is a convenience function for each case: </p> <p> <pre><span style="color:#600277;">currentTime</span>&nbsp;::&nbsp;<span style="color:blue;">PollingProgram</span>&nbsp;msg&nbsp;<span style="color:blue;">UTCTime</span> currentTime&nbsp;<span style="color:#666666;">=</span>&nbsp;liftF&nbsp;(<span style="color:#dd0000;">CurrentTime</span>&nbsp;id) <span style="color:#600277;">poll</span>&nbsp;::&nbsp;<span style="color:blue;">PollingProgram</span>&nbsp;msg&nbsp;(Maybe&nbsp;msg,&nbsp;<span style="color:blue;">PollDuration</span>) poll&nbsp;<span style="color:#666666;">=</span>&nbsp;liftF&nbsp;(<span style="color:#dd0000;">Poll</span>&nbsp;id) <span style="color:#600277;">handle</span>&nbsp;::&nbsp;msg&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">PollingProgram</span>&nbsp;msg&nbsp;<span style="color:blue;">HandleDuration</span> handle&nbsp;msg&nbsp;<span style="color:#666666;">=</span>&nbsp;liftF&nbsp;(<span style="color:#dd0000;">Handle</span>&nbsp;msg&nbsp;id) <span style="color:#600277;">idle</span>&nbsp;::&nbsp;<span style="color:blue;">IdleDuration</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">PollingProgram</span>&nbsp;msg&nbsp;<span style="color:blue;">IdleDuration</span> idle&nbsp;d&nbsp;<span style="color:#666666;">=</span>&nbsp;liftF&nbsp;(<span style="color:#dd0000;">Idle</span>&nbsp;d&nbsp;id)</pre> </p> <p> More one-liners, as you can tell. These all use <code>liftF</code> to turn <code>PollingInstruction</code> cases into <code>PollingProgram</code> values. The degenerate cases <code>CurrentTime</code> and <code>Poll</code> simply become values, whereas the complete cases become (pure) functions. </p> <p> <strong>Support functions</strong> </p> <p> You may have noticed that until now, I haven't written much 'code' in the sense that most people think of it. It's mostly been type declarations and a few one-liners. A strong and sophisticated type system like Haskell's enable you to shift some of the programming burden from 'real programming' to type definitions, but you'll still have to write some code. </p> <p> Before we get to the state transitions proper, we'll look at some support functions. These will, I hope, serve as a good introduction to how to use the <code>PollingProgram</code> API. </p> <p> One decision the Polling Consumer program has to make is to decide whether it should suspend itself for a short time. That's easy to express using the API: </p> <p> <pre><span style="color:#600277;">shouldIdle</span>&nbsp;::&nbsp;<span style="color:blue;">IdleDuration</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">UTCTime</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">PollingProgram</span>&nbsp;msg&nbsp;Bool shouldIdle&nbsp;(<span style="color:#dd0000;">IdleDuration</span>&nbsp;d)&nbsp;stopBefore&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;now&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;currentTime &nbsp;&nbsp;return&nbsp;<span style="color:#666666;">$</span>&nbsp;d&nbsp;<span style="color:#666666;">`addUTCTime`</span>&nbsp;now&nbsp;<span style="color:#666666;">&lt;</span>&nbsp;stopBefore</pre> </p> <p> The <code>shouldIdle</code> function returns a small program that, when evaluated, will decide whether or not to suspend itself. It first reads the current time using the above <code>currentTime</code> value. While <code>currentTime</code> has the type <code>PollingProgram msg UTCTime</code>, due to Haskell's <code>do</code> notation, the <code>now</code> value simply has the type <code>UTCTime</code>. This enables you to use the built-in <code>addUTCTime</code> function (here written using infix notation) to add <code>now</code> to <code>d</code> (a <code>NominalDiffTime</code> value, due to pattern matching into <code>IdleDuration</code>). </p> <p> Adding the idle duration <code>d</code> to the current time <code>now</code> gives you the time the program would resume, were it to suspend itself. The <code>shouldIdle</code> function compares that time to the <code>stopBefore</code> argument (another <code>UTCTime</code> value). If the time the program would resume is before the time it ought to stop, the return value is <code>True</code>; otherwise, it's <code>False</code>. </p> <p> Since the entire function is defined within a <code>do</code> block, the return type isn't just <code>Bool</code>, but rather <code>PollingProgram msg Bool</code>. It's a little <code>PollingProgram</code> AST, but it looks like imperative code. </p> <p> You sometimes hear the bon mot that <em>Haskell is the world's greatest imperative language</em>. The combination of free monads and <code>do</code> notation certainly makes it easy to define small grammars (dare I say <a href="https://en.wikipedia.org/wiki/Domain-specific_language">DSL</a>s?) that look like imperative code, while still being strictly functional. </p> <p> The crux is that <code>shouldIdle</code> is pure. It looks impure, but it's not. It's an Abstract Syntax Tree, and it only becomes non-deterministic if interpreted by an impure interpreter (more on that later). </p> <p> The purpose of <code>shouldIdle</code> is to decide whether or not to idle or exit. If the program decides to idle, it should return to the <em>ready</em> state, as per the above state diagram. In this state, it needs to decide whether or not to poll for a message. If there's a message, it should be handled, and all of that takes time. In the <em>ready</em> state, then, the program must figure out how much time it thinks that handling a message will take. </p> <p> One way to do that is to consider the observed durations so far. This helper function calculates the expected duration based on the average and standard deviation of the previous durations: </p> <p> <pre><span style="color:#600277;">calculateExpectedDuration</span>&nbsp;::&nbsp;<span style="color:blue;">NominalDiffTime</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;[<span style="color:#dd0000;">CycleDuration</span>] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">NominalDiffTime</span> calculateExpectedDuration&nbsp;estimatedDuration&nbsp;<span style="color:blue;">[]</span>&nbsp;<span style="color:#666666;">=</span>&nbsp;estimatedDuration calculateExpectedDuration&nbsp;_&nbsp;statistics&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;toEnum&nbsp;<span style="color:#666666;">$</span>&nbsp;fromEnum&nbsp;<span style="color:#666666;">$</span>&nbsp;avg&nbsp;<span style="color:#666666;">+</span>&nbsp;stdDev&nbsp;<span style="color:#666666;">*</span>&nbsp;<span style="color:#09885a;">3</span> &nbsp;&nbsp;<span style="color:blue;">where</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#600277;">fromCycleDuration</span>&nbsp;::&nbsp;<span style="color:blue;">CycleDuration</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Float &nbsp;&nbsp;&nbsp;&nbsp;fromCycleDuration&nbsp;(<span style="color:#dd0000;">CycleDuration</span>&nbsp;(<span style="color:#dd0000;">PollDuration</span>&nbsp;pd)&nbsp;(<span style="color:#dd0000;">HandleDuration</span>&nbsp;hd))&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;toEnum&nbsp;<span style="color:#666666;">$</span>&nbsp;fromEnum&nbsp;<span style="color:#666666;">$</span>&nbsp;pd&nbsp;<span style="color:#666666;">+</span>&nbsp;hd &nbsp;&nbsp;&nbsp;&nbsp;durations&nbsp;<span style="color:#666666;">=</span>&nbsp;fmap&nbsp;fromCycleDuration&nbsp;statistics &nbsp;&nbsp;&nbsp;&nbsp;l&nbsp;<span style="color:#666666;">=</span>&nbsp;toEnum&nbsp;<span style="color:#666666;">$</span>&nbsp;length&nbsp;durations &nbsp;&nbsp;&nbsp;&nbsp;avg&nbsp;<span style="color:#666666;">=</span>&nbsp;sum&nbsp;durations&nbsp;<span style="color:#666666;">/</span>&nbsp;l &nbsp;&nbsp;&nbsp;&nbsp;stdDev&nbsp;<span style="color:#666666;">=</span>&nbsp;sqrt&nbsp;(sum&nbsp;(fmap&nbsp;(<span style="color:#666666;">\</span>x&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;(x&nbsp;<span style="color:#666666;">-</span>&nbsp;avg)&nbsp;<span style="color:#666666;">**</span>&nbsp;<span style="color:#09885a;">2</span>)&nbsp;durations)&nbsp;<span style="color:#666666;">/</span>&nbsp;l)</pre> </p> <p> I'm not going to dwell much on this function, as it's a normal, pure, mathematical function. The only feature I'll emphasise is that in order to call it, you must pass an <code>estimatedDuration</code> that will be used when <code>statistics</code> is empty. This is because you can't calculate the average of an empty list. This estimated duration is simply your wild guess at how long you think it'll take to handle a message. </p> <p> With this helper function, you can now write a small <code>PollingProgram</code> that decides whether or not to poll: </p> <p> <pre><span style="color:#600277;">shouldPoll</span>&nbsp;::&nbsp;<span style="color:blue;">NominalDiffTime</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">UTCTime</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;[<span style="color:#dd0000;">CycleDuration</span>] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">PollingProgram</span>&nbsp;msg&nbsp;<span style="color:#dd0000;">Bool</span> shouldPoll&nbsp;estimatedDuration&nbsp;stopBefore&nbsp;statistics&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;expectedHandleDuration&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;calculateExpectedDuration&nbsp;estimatedDuration&nbsp;statistics &nbsp;&nbsp;now&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;currentTime &nbsp;&nbsp;return&nbsp;<span style="color:#666666;">$</span>&nbsp;expectedHandleDuration&nbsp;<span style="color:#666666;">`addUTCTime`</span>&nbsp;now&nbsp;<span style="color:#666666;">&lt;</span>&nbsp;stopBefore</pre> </p> <p> Notice that the <code>shouldPoll</code> function looks similar to <code>shouldIdle</code>. As an extra initial step, it first calculates <code>expectedHandleDuration</code> using the above <code>calculateExpectedDuration</code> function. With that, it follows the same two steps as <code>shouldIdle</code>. </p> <p> This function is also pure, because it returns an AST. While it <em>looks</em> impure, it's not, because it doesn't actually <code>do</code> anything. </p> <p> <strong>Transitions</strong> </p> <p> Those are all the building blocks required to write the state transitions. In order to break down the problem in manageable chunks, you can write a transition function for each state. Such a function would return the next state, given a particular input state. </p> <p> While it'd be intuitive to begin with the <em>ready</em> state, let's instead start with the simplest transition. In the <em>end</em> state, nothing should happen, so the transition is a one-liner: </p> <p> <pre><span style="color:#600277;">transitionFromStopped</span>&nbsp;::&nbsp;<span style="color:blue;">Monad</span>&nbsp;m&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;[<span style="color:blue;">CycleDuration</span>]&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;(<span style="color:blue;">PollingState</span>&nbsp;msg) transitionFromStopped&nbsp;statistics&nbsp;<span style="color:#666666;">=</span>&nbsp;return&nbsp;<span style="color:#666666;">$</span>&nbsp;<span style="color:#dd0000;">Stopped</span>&nbsp;statistics</pre> </p> <p> Once stopped, the program stays in the <code>Stopped</code> state. This function simply takes a list of <code>CycleDuration</code> values and elevates them to a monad type. Notice that the return value isn't specifically a <code>PollingProgram</code>, but any monad. Since <code>PollingProgram</code> is a monad, that'll work too, though. </p> <p> Slightly more complicated than <code>transitionFromStopped</code> is the transition from the <em>received</em> state. There's no branching in that case; simply handle the message, measure how long it took, add the observed duration to the statistics, and transition back to <em>ready:</em> </p> <p> <pre><span style="color:#600277;">transitionFromReceived</span>&nbsp;::&nbsp;[<span style="color:blue;">CycleDuration</span>] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">PollDuration</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;msg &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">PollingProgram</span>&nbsp;msg&nbsp;(<span style="color:#dd0000;">PollingState</span>&nbsp;msg) transitionFromReceived&nbsp;statistics&nbsp;pd&nbsp;msg&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;hd&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;handle&nbsp;msg &nbsp;&nbsp;return&nbsp;<span style="color:#666666;">$</span>&nbsp;<span style="color:#dd0000;">Ready</span>&nbsp;(<span style="color:#dd0000;">CycleDuration</span>&nbsp;pd&nbsp;hd&nbsp;<span style="color:#666666;">:</span>&nbsp;statistics)</pre> </p> <p> Again, this <em>looks</em> impure, but the return type is <code>PollingProgram msg (PollingState msg)</code>, indicating that the return value is an AST. As is not uncommon in Haskell, the type declaration is larger than the implementation. </p> <p> Things get slightly more interesting in the <em>no message</em> state. Here you get to use the above <code>shouldIdle</code> support function: </p> <p> <pre><span style="color:#600277;">transitionFromNoMessage</span>&nbsp;::&nbsp;<span style="color:blue;">IdleDuration</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">UTCTime</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;[<span style="color:#dd0000;">CycleDuration</span>] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">PollingProgram</span>&nbsp;msg&nbsp;(<span style="color:#dd0000;">PollingState</span>&nbsp;msg) transitionFromNoMessage&nbsp;d&nbsp;stopBefore&nbsp;statistics&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;b&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;shouldIdle&nbsp;d&nbsp;stopBefore &nbsp;&nbsp;<span style="color:#af00db;">if</span>&nbsp;b &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#af00db;">then</span>&nbsp;idle&nbsp;d&nbsp;<span style="color:#666666;">&gt;&gt;</span>&nbsp;return&nbsp;(<span style="color:#dd0000;">Ready</span>&nbsp;statistics) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#af00db;">else</span>&nbsp;return&nbsp;<span style="color:#666666;">$</span>&nbsp;<span style="color:#dd0000;">Stopped</span>&nbsp;statistics</pre> </p> <p> The first step in <code>transitionFromNoMessage</code> is calling <code>shouldIdle</code>. Thanks to Haskell's <code>do</code> notation, the <code>b</code> value is a simple <code>Bool</code> value that you can use to branch. If <code>b</code> is <code>True</code>, then first call <code>idle</code> and then return to the <code>Ready</code> state; otherwise, exit to the <code>Stopped</code> state. </p> <p> Notice how <code>PollingProgram</code> values are <em>composable</em>. For instance, <code>shouldIdle</code> defines a small <code>PollingProgram</code> that can be (re)used in a bigger program, such as in <code>transitionFromNoMessage</code>. </p> <p> Finally, from the <em>ready</em> state, the program can transition to three other states, so this is the most complex transition: </p> <p> <pre><span style="color:#600277;">transitionFromReady</span>&nbsp;::&nbsp;<span style="color:blue;">NominalDiffTime</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">UTCTime</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;[<span style="color:#dd0000;">CycleDuration</span>] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">PollingProgram</span>&nbsp;msg&nbsp;(<span style="color:#dd0000;">PollingState</span>&nbsp;msg) transitionFromReady&nbsp;estimatedDuration&nbsp;stopBefore&nbsp;statistics&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;b&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;shouldPoll&nbsp;estimatedDuration&nbsp;stopBefore&nbsp;statistics &nbsp;&nbsp;<span style="color:#af00db;">if</span>&nbsp;b &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#af00db;">then</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pollResult&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;poll &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;pollResult&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(Just&nbsp;msg,&nbsp;pd)&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;return&nbsp;<span style="color:#666666;">$</span>&nbsp;<span style="color:#dd0000;">ReceivedMessage</span>&nbsp;statistics&nbsp;pd&nbsp;msg &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(Nothing&nbsp;,&nbsp;pd)&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;return&nbsp;<span style="color:#666666;">$</span>&nbsp;<span style="color:#dd0000;">NoMessage</span>&nbsp;statistics&nbsp;pd &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#af00db;">else</span>&nbsp;return&nbsp;<span style="color:#666666;">$</span>&nbsp;<span style="color:#dd0000;">Stopped</span>&nbsp;statistics</pre> </p> <p> Like <code>transitionFromNoMessage</code>, the <code>transitionFromReady</code> function first calls a supporting function (this time <code>shouldPoll</code>) in order to make a decision. If <code>b</code> is <code>False</code>, the next state is <code>Stopped</code>; otherwise, the program moves on to the next step. </p> <p> The program polls for a message using the <code>poll</code> helper function defined above. While <code>poll</code> is a <code>PollingProgram msg (Maybe msg, PollDuration)</code> value, thanks to <code>do</code> notation, <code>pollResult</code> is a <code>Maybe msg, PollDuration</code> value. Matching on that value requires you to handle two separate cases: If a message was received (<code>Just msg</code>), then return a <code>ReceivedMessage</code> state with the message. Otherwise (<code>Nothing</code>), return a <code>NoMessage</code> state. </p> <p> With those four functions you can now define a function that can transition from any input state: </p> <p> <pre><span style="color:#600277;">transition</span>&nbsp;::&nbsp;<span style="color:blue;">NominalDiffTime</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">IdleDuration</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">UTCTime</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">PollingState</span>&nbsp;msg &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">PollingProgram</span>&nbsp;msg&nbsp;(<span style="color:#dd0000;">PollingState</span>&nbsp;msg) transition&nbsp;estimatedDuration&nbsp;idleDuration&nbsp;stopBefore&nbsp;state&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;state&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Ready</span>&nbsp;stats&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;transitionFromReady&nbsp;estimatedDuration&nbsp;stopBefore&nbsp;stats &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">ReceivedMessage</span>&nbsp;stats&nbsp;pd&nbsp;msg&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;transitionFromReceived&nbsp;stats&nbsp;pd&nbsp;msg &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">NoMessage</span>&nbsp;stats&nbsp;_&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;transitionFromNoMessage&nbsp;idleDuration&nbsp;stopBefore&nbsp;stats &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Stopped</span>&nbsp;stats&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;transitionFromStopped&nbsp;stats</pre> </p> <p> The <code>transition</code> function simply pattern-matches on the input <code>state</code> and delegates to each of the four above transition functions. </p> <p> <strong>A short philosophical interlude</strong> </p> <p> All code so far has been pure, although it may not look that way. At this stage, it may be reasonable to pause and consider: <em>what's the point, even?</em> </p> <p> After all, when interpreted, a <code>PollingProgram</code> can (and, in reality, almost certainly <em>will</em>) have impure behaviour. If we create an entire executable upon this abstraction, then we've essentially developed a big program with impure behaviour... </p> <p> Indeed we have, but the alternative would have been to write it all in the context of <code>IO</code>. If you'd done that, then you'd allow <em>any</em> non-deterministic, side-effecty behaviour anywhere in your program. At least with a <code>PollingProgram</code>, any reader will quickly learn that only a maximum of four impure operations can happen. In other words, you've managed to control and restrict the impurity to exactly those interactions you want to model. </p> <p> Not only that, but the type of impurity is immediately visible as part of a value's type. In a later article, you'll see how different impure interaction APIs can be composed. </p> <p> <strong>Interpretation</strong> </p> <p> At this point, you have a program in the form of an AST. How do you execute it? </p> <p> You write an interpreter: </p> <p> <pre><span style="color:#600277;">interpret</span>&nbsp;::&nbsp;<span style="color:blue;">PollingProgram</span>&nbsp;<span style="color:blue;">Message</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;IO&nbsp;a interpret&nbsp;program&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;runFree&nbsp;program&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Pure</span>&nbsp;r&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;return&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Free</span>&nbsp;(<span style="color:#dd0000;">CurrentTime</span>&nbsp;next)&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;getCurrentTime&nbsp;<span style="color:#666666;">&gt;&gt;=</span>&nbsp;interpret&nbsp;<span style="color:#666666;">.</span>&nbsp;next &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Free</span>&nbsp;(<span style="color:#dd0000;">Poll</span>&nbsp;next)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;pollImp&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">&gt;&gt;=</span>&nbsp;interpret&nbsp;<span style="color:#666666;">.</span>&nbsp;next &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Free</span>&nbsp;(<span style="color:#dd0000;">Handle</span>&nbsp;msg&nbsp;next)&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;handleImp&nbsp;msg&nbsp;&nbsp;<span style="color:#666666;">&gt;&gt;=</span>&nbsp;interpret&nbsp;<span style="color:#666666;">.</span>&nbsp;next &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Free</span>&nbsp;(<span style="color:#dd0000;">Idle</span>&nbsp;d&nbsp;next)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;idleImp&nbsp;d&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">&gt;&gt;=</span>&nbsp;interpret&nbsp;<span style="color:#666666;">.</span>&nbsp;next</pre> </p> <p> When you turn a functor into a monad using the <code>Free</code> constructor (see above), your functor is wrapped in a general-purpose sum type with two cases: <code>Pure</code> and <code>Free</code>. Your functor is always contained in the <code>Free</code> case, whereas <code>Pure</code> is the escape hatch. This is where you return the value of the entire computation. </p> <p> An interpreter must match both <code>Pure</code> and <code>Free</code>. <code>Pure</code> is easy, because you simply return the result value. </p> <p> In the <code>Free</code> case, you'll need to match each of the four cases of <code>PollingInstruction</code>. In all four cases, you invoke an impure implementation function, pass its return value to <code>next</code>, and finally recursively invoke <code>interpret</code> with the value returned by <code>next</code>. </p> <p> Three of the implementations are details that aren't of importance here, but if you want to review them, the entire source code for this article is <a href="https://gist.github.com/ploeh/3965c5df81f2a16f41a81cffeaae35c5">available as a gist</a>. The fourth implementation is the built-in <code>getCurrentTime</code> function. They are all impure; all return <code>IO</code> values. This also implies that the return type of the entire <code>interpret</code> function is <code>IO a</code>. </p> <p> This particular interpreter is impure, but nothing prevents you from writing a pure interpreter, for example for use in unit testing. </p> <p> <strong>Execution</strong> </p> <p> You're almost done. You have a function that returns a new state for any given input state, as well as an interpreter. You need a function that can repeat this in a loop until it reaches the <code>Stopped</code> state: </p> <p> <pre><span style="color:#600277;">run</span>&nbsp;::&nbsp;<span style="color:blue;">NominalDiffTime</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">IdleDuration</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">UTCTime</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">PollingState</span>&nbsp;<span style="color:#dd0000;">Message</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">IO</span>&nbsp;(<span style="color:#dd0000;">PollingState</span>&nbsp;<span style="color:#dd0000;">Message</span>) run&nbsp;estimatedDuration&nbsp;idleDuration&nbsp;stopBefore&nbsp;state&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;ns&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;interpret&nbsp;<span style="color:#666666;">$</span>&nbsp;transition&nbsp;estimatedDuration&nbsp;idleDuration&nbsp;stopBefore&nbsp;state &nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;ns&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Stopped</span>&nbsp;_&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;return&nbsp;ns &nbsp;&nbsp;&nbsp;&nbsp;_&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;run&nbsp;estimatedDuration&nbsp;idleDuration&nbsp;stopBefore&nbsp;ns</pre> </p> <p> This recursive function calls <code>transition</code> with the input <code>state</code>. You may recall that <code>transition</code> returns a <code>PollingProgram msg (PollingState msg)</code> value. Passing this value to <code>interpret</code> returns an <code>IO (PollingState Message)</code> value, and because of the <code>do</code> notation, the new state (<code>ns</code>) is a <code>PollingState Message</code> value. </p> <p> You can now pattern match on <code>ns</code>. If it's a <code>Stopped</code> value, you return the value. Otherwise, you recursively call <code>run</code> once more. </p> <p> The <code>run</code> function keeps doing this until it reaches the <code>Stopped</code> state. </p> <p> <em>Finally</em>, then, you can write the entry point for the program: </p> <p> <pre><span style="color:#600277;">main</span>&nbsp;::&nbsp;IO&nbsp;() main&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;timeAtEntry&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;getCurrentTime &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;estimatedDuration&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#09885a;">2</span> &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;idleDuration&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">IdleDuration</span>&nbsp;<span style="color:#09885a;">5</span> &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;stopBefore&nbsp;<span style="color:#666666;">=</span>&nbsp;addUTCTime&nbsp;<span style="color:#09885a;">60</span>&nbsp;timeAtEntry &nbsp;&nbsp;s&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;run&nbsp;estimatedDuration&nbsp;idleDuration&nbsp;stopBefore&nbsp;<span style="color:#666666;">$</span>&nbsp;<span style="color:#dd0000;">Ready</span>&nbsp;<span style="color:blue;">[]</span> &nbsp;&nbsp;timeAtExit&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;getCurrentTime &nbsp;&nbsp;putStrLn&nbsp;<span style="color:#666666;">$</span>&nbsp;<span style="color:#a31515;">&quot;Elapsed&nbsp;time:&nbsp;&quot;</span>&nbsp;<span style="color:#666666;">++</span>&nbsp;show&nbsp;(diffUTCTime&nbsp;timeAtExit&nbsp;timeAtEntry) &nbsp;&nbsp;putStrLn&nbsp;<span style="color:#666666;">$</span>&nbsp;printf&nbsp;<span style="color:#a31515;">&quot;%d&nbsp;message(s)&nbsp;handled.&quot;</span>&nbsp;<span style="color:#666666;">$</span>&nbsp;report&nbsp;s</pre> </p> <p> It defines the initial input parameters: <ul> <li>My wild guess about the handle duration is 2 seconds</li> <li>I'd like the idle duration to be 5 seconds</li> <li>The program should run for 60 seconds</li> </ul> The initial state is <code>Ready []</code>. These are all the arguments you need to call <code>run</code>. </p> <p> Once <code>run</code> returns, you can print the number of messages handled using a (trivial) <code>report</code> function that I haven't shown (but which is available in the gist). </p> <p> If you run the program, it'll produce output similar to this: </p> <p> <pre>Polling Handling Polling Handling Polling Handling Polling Sleeping Polling Handling Polling Sleeping Polling Handling Polling Handling Polling Sleeping Polling Sleeping Polling Sleeping Polling Sleeping Polling Sleeping Polling Handling Polling Handling Polling Handling Polling Handling Polling Sleeping Polling Elapsed time: 56.6835022s 10 message(s) handled.</pre> </p> <p> It does, indeed, exit before 60 seconds have elapsed. </p> <p> <strong>Summary</strong> </p> <p> You can model long-running interactions with an Abstract Syntax Tree. Without <code>do</code> notation, writing programs as 'raw' ASTs would be cumbersome, but turning the AST into a (free) monad makes it all quite palatable. </p> <p> Haskell's sophisticated type system makes this a fairly low-hanging fruit, once you understand how to do it. You can also port this type of design to F#, although, as you shall see next, more boilerplate is required. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/07/04/pure-times-in-f">Pure times in F#</a>. </p> </div> <div id="comments"> <hr /> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="http://stackoverflow.com/users/1523776/benjamin-hodgson?tab=profile">Benjamin Hodgson</a></div> <div class="comment-content"> <p> Good introduction to the notion of programs-as-embedded-languages here, thanks for writing it! </p> <p> In my experience a majority of <code>Free</code> interpreters fit into the <a href="https://hackage.haskell.org/package/free-4.12.4/docs/Control-Monad-Free.html#v:foldFree"><code>foldFree</code></a> pattern. Saves you the repetitous bits of your <code>interpret</code> function: </p> <pre><code>interpret = foldFree eta where eta (CurrentTime k) = k &lt;$&gt; getCurrentTime eta (Poll k) = k &lt;$&gt; pollImp eta (Handle msg k) = k &lt;$&gt; handleImp msg eta (Idle d k) = k &lt;$&gt; idleImp d</code></pre> <p> Anyway, I just wanted to give an alternative viewpoint on the topic of <code>Free</code> which will hopefully be some food for thought. I'm generally not an advocate of the <code>Free</code> approach to modelling effectful computation. I don't think it has much of an advantage over the old fashioned <code>mtl</code> style, especially since you have only one effect and only one interpreter. I'd have written your interface like this: </p> <pre><code>class Monad m =&gt; MonadPoll msg m | m -> msg where currentTime :: m UTCTime poll :: m (Maybe msg, PollDuration) handle :: msg -&gt; m HandleDuration idle :: m IdleDuration transitionFromNoMessage :: MonadPoll msg m =&gt; IdleDuration -&gt; UTCTime -&gt; [CycleDuration] -&gt; m (PollingState msg) transitionFromNoMessage d stopBefore statistics = do b &lt;- shouldIdle d stopBefore if b then idle d &gt;&gt; return (Ready statistics) else return $ Stopped statistics</code></pre> <p> It's a clearer, more direct expression of the monadic interface, in my opinion, and it admits simpler implementations (and it's faster because GHC can specialise and inline everything). Computations with access to only a <code>MonadPoll</code> context can only perform polling actions, so it's still pure, and you can swap out different implementations of <code>MonadPoll</code> (eg, for testing) by writing types with different instances. You can do eg <a href="https://gist.github.com/ocharles/6b1b9440b3513a5e225e">this</a> if you need "decorator"-style interpreters. The main downside of the <code>mtl</code> style is the "n^2 instances problem" (though <code>GeneralizedNewtypeDeriving</code> does somewhat ease the pain). </p> <p> Kiselyov has some good <a href="http://okmij.org/ftp/tagless-final/course/lecture.pdf">lecture notes</a> about using the <code>mtl</code> style to model abstract syntax trees and compositional interpreters. I probably wouldn't go that far if I were building a compiler! Type classes are good at effect systems and algebraic data types are good at syntax trees, and while each job can be done by either it pays to pick your tools carefully. </p> <p> Having said all that, the <code>Free</code> approach is probably more attractive in F#, because it doesn't feature type classes or higher kinds. And <code>Free</code> has other uses outside of the world of effect systems. </p> <p> Hope all the above is interesting to you! </p> <p> Benjamin </p> </div> <div class="comment-date">2017-06-29 2:13 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Benjamin, thank you for writing. It is, indeed, interesting to me, and I appreciate that you took the time to write such a helpful and concise comment. </p> <p> I wasn't aware of <code>foldFree</code>, but I can see that I'll have to look into it. </p> <p> One day (soon), I'll have to try writing a small Haskell program using the <code>mtl</code> style instead. It looks as though the code would be quite similar, although the types are different. Are these approaches isomorphic? </p> <p> In any case, I hope that I'm not coming off as being too authoritative. In some sense, this blog often serves as my own elaborate journal documenting what I've been learning recently. I hope that what I write is mostly correct, but I don't presume that what I write is the one and only truth; it's bound by my knowledge at the time of writing. I still have much to learn, and I'm always happy when people help me expand my horizon. </p> <p> I think that you hit the nail concerning F#. One of my motivations for exploring this space was to figure out what can be done in F#. As far as I can tell, the <code>mtl</code> style doesn't translate well to F#. You can debate whether or not free monads translate <em>well</em> to F#, but at least the concept does carry over. </p> </div> <div class="comment-date">2017-06-29 6:47 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://stackoverflow.com/users/1523776/benjamin-hodgson?tab=profile">Benjamin Hodgson</a></div> <div class="comment-content"> <p> Yep, they're isomorphic, in that you can round-trip in either direction between the two representations - <code>to . from = from . to = id</code>: </p> <pre><code>instance MonadPoll msg (Free (PollingInstruction msg)) where currentTime = liftF (CurrentTime id) poll = liftF (Poll id) handle msg = liftF (Handle msg id) idle d = liftF (Idle d id) to :: (forall m. MonadPoll msg m =&gt; m a) -&gt; Free (PollingInstruction msg) a to x = x from :: MonadPoll msg m =&gt; Free (PollingInstruction msg) a -&gt; m a from x = foldFree eta where eta (CurrentTime k) = k &lt;$&gt; currentTime eta (Poll k) = k &lt;$&gt; poll eta (Handle msg k) = k &lt;$&gt; handle msg eta (Idle d k) = k &lt;$&gt; idle d</pre></code> <p> But the representations being isomorphic doesn't mean they're equally convenient. (Another example of this would be lenses: van Laarhoven lenses (à la <code>lens</code>) are isomorphic to "costate comonad coalgebra" (ie <code>get</code>/<code>set</code>) lenses, but they're much more composable.) </p> <p> Benjamin </p> </div> <div class="comment-date">2017-06-29 16:39 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Benjamin, thank you once again for writing. It's amazing that not only are they isomorphic, but you can actually prove it with code. I have to admit, though, that I haven't tried compiling or running your code yet. First, I need to digest this. </p> <p> I was never under the impression that I knew most of what there was to know, but <em>by Jove!</em>, poking at Haskell unearths fathomless depths of knowledge of which I still only glance the surface. It's occasionally frustrating, but mostly exhilarating. </p> </div> <div class="comment-date">2017-06-29 20:26 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Pure times http://blog.ploeh.dk/2017/06/27/pure-times 2017-06-27T09:11:00+00:00 Mark Seemann <div id="post"> <p> <em>How to interact with the system clock using strict functional programming.</em> </p> <p> A couple of years ago, I published an article called <a href="http://blog.ploeh.dk/2014/12/17/good-times-with-f">Good times with F#</a>. Unfortunately, that article never lived up to my expectations. Not that I don't have a good time with F# (I do), but the article introduced an attempt to model execution durations of operations in a functional manner. The article introduced a <code>Timed&lt;'a&gt;</code> generic type that I had high hopes for. </p> <p> Later, I published a Pluralsight course called <a href="http://www.shareasale.com/r.cfm?u=1017843&b=611266&m=53701&afftrack=&urllink=www%2Epluralsight%2Ecom%2Fcourses%2Ffsharp%2Dtype%2Ddriven%2Ddevelopment">Type-Driven Development with F#</a>, in which I used <code>Timed&lt;'a&gt;</code> to implement a <a href="http://www.enterpriseintegrationpatterns.com/PollingConsumer.html">Polling Consumer</a>. It's a good course that teaches you how to let F#'s type system give you rapid feedback. You can read <a href="http://blog.ploeh.dk/2015/08/10/type-driven-development">a few articles</a> that highlight the important parts of the course. </p> <p> There's a problem with the implementation, though. It's not functional. </p> <p> It's nice F# code, but F# is this friendly, forgiving, multi-paradigmatic language that enables you to get real work done. If you want to do this using <a href="http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection">partial application as a replacement for Dependency Injection</a>, it'll let you. It is, however, <a href="http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection">not functional</a>. </p> <p> Consider, as an example, this function: </p> <p> <pre><span style="color:green;">//&nbsp;(Timed&lt;TimeSpan&nbsp;list&gt;&nbsp;-&gt;&nbsp;bool)&nbsp;-&gt;&nbsp;(unit&nbsp;-&gt;&nbsp;Timed&lt;&#39;a&gt;)&nbsp;-&gt;&nbsp;Timed&lt;TimeSpan&nbsp;list&gt;</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;State</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">transitionFromNoMessage</span>&nbsp;<span style="color:navy;">shouldIdle</span>&nbsp;<span style="color:navy;">idle</span>&nbsp;nm&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;<span style="color:navy;">shouldIdle</span>&nbsp;nm &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:navy;">idle</span>&nbsp;()&nbsp;|&gt;&nbsp;<span style="color:teal;">Untimed</span>.<span style="color:navy;">withResult</span>&nbsp;nm.Result&nbsp;|&gt;&nbsp;<span style="color:navy;">ReadyState</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:navy;">StoppedState</span>&nbsp;nm.Result</pre> </p> <p> The <code>idle</code> function has the type <code>unit -&gt; Timed&lt;'a&gt;</code>. This can't possibly be a <a href="https://en.wikipedia.org/wiki/Pure_function">pure function</a>, since a deterministic function can't produce a value from nothing when it doesn't know the type of the value. (In F#, this is technically not true, since we could return null for all reference types, and 'zero' for all value types, but even so, it should be clear that we can't produce any <em>useful</em> return value in a deterministic manner.) </p> <p> The same argument applies, in weaker form, to the <code>shouldIdle</code> function. While it <em>is</em> possible to write more than one pure function with the type <code>Timed&lt;TimeSpan list&gt; -&gt; bool</code>, the <em>intent</em> is that it should look at the time statistics and the current time, and decide whether or not it's 'safe' to poll again. Getting the current time from the system clock is a non-deterministic operation. </p> <p> Ever since I discovered that Dependency Injection is impossible in functional programming, I knew that I had to return to the Polling Consumer example and show how to implement it in a truly functional style. In order to be sure that I don't accidentally call an impure function from a 'pure' function, I'll first <a href="http://blog.ploeh.dk/2017/06/28/pure-times-in-haskell">rewrite the Polling Consumer in Haskell</a>, and afterwards <a href="http://blog.ploeh.dk/2017/07/04/pure-times-in-f">translate the Haskell code to F#</a>. When reading, you can skip the Haskell article and go directly to the F# article, or vice versa, if you like. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/06/28/pure-times-in-haskell">Pure times in Haskell</a>. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Fractal trees with PureScript http://blog.ploeh.dk/2017/06/06/fractal-trees-with-purescript 2017-06-06T08:10:00+00:00 Mark Seemann <div id="post"> <p> <em>A fractal tree drawn with PureScript</em> </p> <p> Last week, I attended <a href="http://brandewinder.com">Mathias Brandewinder's</a> F# (and <a href="https://clojure.org">Clojure</a>) dojo in Copenhagen, and had great fun drawing a fractal tree in F# together with other attendees. Afterwards, I started thinking that it'd be fairly easy to port the F# code to <a href="https://www.haskell.org">Haskell</a>, but then I reconsidered. The combination of Haskell, Windows, and drawing sounded intimidating. This seemed a good opportunity to take <a href="http://www.purescript.org">PureScript</a> for a spin, because that would enable me to draw the tree on an HTML canvas. </p> <p> In case you're wondering, a fractal tree is simply a tree that branches infinitely in (I suppose) a deterministic fashion. Here's an example of the output of of the code of this article: </p> <p> <img src="/content/binary/symmetric-fractal-tree.png" alt="A symmetric fractal tree."> </p> <p> This is my first attempt at PureScript, and I think I spent between five and ten hours in total. Most of them I used to figure out how to install PureScript, how to set up a development environment, and so on. All in all I found the process pleasing. </p> <p> While it's a separate, independent language, PureScript is clearly a descendant of Haskell, and the syntax is similar. </p> <p> <strong>Separating data from effects</strong> </p> <p> In functional programming, you routinely separate data from effects. Instead of trying to both draw and calculate branches of a tree in a single operation, you figure out how to first define a fractal tree as data, and then subsequently you can draw it. </p> <p> A generic binary tree is a staple of functional programming. Here's one way to do it: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;<span style="color:#dd0000;">Tree</span>&nbsp;a&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Leaf</span>&nbsp;a&nbsp;<span style="color:#666666;">|</span>&nbsp;<span style="color:#dd0000;">Node</span>&nbsp;a&nbsp;(<span style="color:#dd0000;">Tree</span>&nbsp;a)&nbsp;(<span style="color:#dd0000;">Tree</span>&nbsp;a) </pre> </p> <p> Such a tree is either a leaf node with a generically typed value, or an (intermediate) node with a value and two branches, which are themselves (sub)trees. </p> <p> In a sense, this definition is an approximation, because a 'real' fractal tree has no leafs. In Haskell you can easily define infinite trees, because Haskell is lazily evaluated. PureScript, on the other hand, is eagerly evaluated, so infinite recursion would require jumping through some hoops, and I don't think it's important in this exercise. </p> <p> While the above tree type can contain values of any type, in this exercise, it should contain line segments. One way to do this is to define a <code>Line</code> record type: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;<span style="color:#dd0000;">Line</span>&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Line</span>&nbsp;{ &nbsp;&nbsp;<span style="color:#600277;">x</span>&nbsp;::&nbsp;<span style="color:blue;">Number</span>, &nbsp;&nbsp;<span style="color:#600277;">y</span>&nbsp;::&nbsp;<span style="color:blue;">Number</span>, &nbsp;&nbsp;<span style="color:#600277;">angle</span>&nbsp;::&nbsp;<span style="color:blue;">Number</span>, &nbsp;&nbsp;<span style="color:#600277;">length</span>&nbsp;::&nbsp;<span style="color:blue;">Number</span>, &nbsp;&nbsp;<span style="color:#600277;">width</span>&nbsp;::&nbsp;<span style="color:blue;">Number</span>&nbsp;} </pre> </p> <p> This is a type with five labelled values, all of them numbers. <code>x</code> and <code>y</code> are coordinates for the origin of the line, <code>angle</code> defines the angle (measured in <a href="https://en.wikipedia.org/wiki/Radian">radians</a>) from the origin, and <code>length</code> the length of the line. In a similarly obvious vein, <code>width</code> denotes the width of the line, although this data element has no impact on the calculation of the tree. It's purely a display concern. </p> <p> Given the first four numbers in a <code>Line</code> value, you can calculate the endpoint of a line: </p> <p> <pre><span style="color:#600277;">endpoint</span>&nbsp;::&nbsp;forall&nbsp;r. &nbsp;&nbsp;{&nbsp;x&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">Number</span> &nbsp;&nbsp;,&nbsp;y&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">Number</span> &nbsp;&nbsp;,&nbsp;angle&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">Number</span> &nbsp;&nbsp;,&nbsp;length&nbsp;<span style="color:#666666;">::</span>&nbsp;<span style="color:#dd0000;">Number</span> &nbsp;&nbsp;<span style="color:#666666;">|</span>&nbsp;r&nbsp;} &nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">Tuple</span>&nbsp;<span style="color:#dd0000;">Number</span>&nbsp;<span style="color:#dd0000;">Number</span> endpoint&nbsp;line&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:green;">--&nbsp;Flip&nbsp;the&nbsp;y&nbsp;value&nbsp;because&nbsp;Canvas&nbsp;coordinate&nbsp;system&nbsp;points&nbsp;down&nbsp;from&nbsp;upper </span>&nbsp;&nbsp;<span style="color:green;">--&nbsp;left&nbsp;corner </span>&nbsp;&nbsp;<span style="color:#dd0000;">Tuple</span> &nbsp;&nbsp;&nbsp;&nbsp;(line<span style="color:#666666;">.</span>x&nbsp;<span style="color:#666666;">+</span>&nbsp;line<span style="color:#666666;">.</span>length&nbsp;<span style="color:#666666;">*</span>&nbsp;cos&nbsp;line<span style="color:#666666;">.</span>angle) &nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:#666666;">-</span>(<span style="color:#666666;">-</span>line<span style="color:#666666;">.</span>y&nbsp;<span style="color:#666666;">+</span>&nbsp;line<span style="color:#666666;">.</span>length&nbsp;<span style="color:#666666;">*</span>&nbsp;sin&nbsp;line<span style="color:#666666;">.</span>angle)) </pre> </p> <p> This may look more intimidating than it really is. The first seven lines are simply the (optional) type declaration; ignore that for a minute. The function itself is a one-liner, although I've formatted it on several lines in order to stay within an 80 characters line width. It simply performs a bit of <a href="https://en.wikipedia.org/wiki/Trigonometry">trigonometry</a> in order to find the endpoint of a line with an origin, angle, and length. As the code comment states, it negates the <code>y</code> value because the HTML canvas coordinate system points down instead of up (larger <code>y</code> values are further towards the bottom of the screen than smaller values). </p> <p> The function calculates a new set of coordinates for the endpoint, and returns them as a tuple. In PureScript, tuples are explicit and created with the <code>Tuple</code> data constructor. </p> <p> In general, as far as I can tell, you have less need of tuples in PureScript, because instead, you have <em>row type polymorphism</em>. This is still a new concept to me, but as far as I can tell, it's a sort of static duck typing. You can see it in the type declaration of the <code>endpoint</code> function. The function takes a <code>line</code> argument, the type of which is <em>any</em> record type that contains <code>x</code>, <code>y</code>, <code>angle</code>, and <code>length</code> labels of the <code>Number</code> type. For instance, as you'll soon see, you can pass a <code>Line</code> value to the <code>endpoint</code> function. </p> <p> <strong>Creating branches</strong> </p> <p> In a fractal tree, you calculate two branches for any given branch. Typically, in order to draw a pretty picture, you make the sub-branches smaller than the parent branch. You also incline each branch an angle from the parent branch. While you can hard-code the values for these operations, you can also pass them as arguments. In order to prevent an explosion of primitive function arguments, I collected all such parameters in a single data type: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;<span style="color:#dd0000;">FractalParameters</span>&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">FractalParameters</span>&nbsp;{ &nbsp;&nbsp;<span style="color:#600277;">leftAngle</span>&nbsp;::&nbsp;<span style="color:blue;">Number</span>, &nbsp;&nbsp;<span style="color:#600277;">rightAngle</span>&nbsp;::&nbsp;<span style="color:blue;">Number</span>, &nbsp;&nbsp;<span style="color:#600277;">shrinkFactor</span>&nbsp;::&nbsp;<span style="color:blue;">Number</span>&nbsp;} </pre> </p> <p> This is a record type similar to the <code>Line</code> type you've already seen. </p> <p> When you have a <code>FractalParameters</code> value and a (parent) line, you can calculate its branches: </p> <p> <pre><span style="color:#600277;">createBranches</span>&nbsp;::&nbsp;<span style="color:blue;">FractalParameters</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Line</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Tuple</span>&nbsp;<span style="color:blue;">Line</span>&nbsp;<span style="color:blue;">Line</span> createBranches&nbsp;(<span style="color:#dd0000;">FractalParameters</span>&nbsp;p)&nbsp;(<span style="color:#dd0000;">Line</span>&nbsp;line)&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:#dd0000;">Tuple</span>&nbsp;left&nbsp;right &nbsp;&nbsp;<span style="color:blue;">where</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#dd0000;">Tuple</span>&nbsp;x&nbsp;y&nbsp;<span style="color:#666666;">=</span>&nbsp;endpoint&nbsp;line &nbsp;&nbsp;&nbsp;&nbsp;left&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Line</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x<span style="color:#666666;">:</span>&nbsp;x, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;y<span style="color:#666666;">:</span>&nbsp;y, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;angle<span style="color:#666666;">:</span>&nbsp;pi&nbsp;<span style="color:#666666;">*</span>&nbsp;(line<span style="color:#666666;">.</span>angle&nbsp;<span style="color:#666666;">/</span>&nbsp;pi&nbsp;<span style="color:#666666;">+</span>&nbsp;p<span style="color:#666666;">.</span>leftAngle), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;length<span style="color:#666666;">:</span>&nbsp;(line<span style="color:#666666;">.</span>length&nbsp;<span style="color:#666666;">*</span>&nbsp;p<span style="color:#666666;">.</span>shrinkFactor), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;width<span style="color:#666666;">:</span>&nbsp;(line<span style="color:#666666;">.</span>width&nbsp;<span style="color:#666666;">*</span>&nbsp;p<span style="color:#666666;">.</span>shrinkFactor)&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;right&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Line</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x<span style="color:#666666;">:</span>&nbsp;x, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;y<span style="color:#666666;">:</span>&nbsp;y, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;angle<span style="color:#666666;">:</span>&nbsp;pi&nbsp;<span style="color:#666666;">*</span>&nbsp;(line<span style="color:#666666;">.</span>angle&nbsp;<span style="color:#666666;">/</span>&nbsp;pi&nbsp;<span style="color:#666666;">-</span>&nbsp;p<span style="color:#666666;">.</span>rightAngle), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;length<span style="color:#666666;">:</span>&nbsp;(line<span style="color:#666666;">.</span>length&nbsp;<span style="color:#666666;">*</span>&nbsp;p<span style="color:#666666;">.</span>shrinkFactor), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;width<span style="color:#666666;">:</span>&nbsp;(line<span style="color:#666666;">.</span>width&nbsp;<span style="color:#666666;">*</span>&nbsp;p<span style="color:#666666;">.</span>shrinkFactor)&nbsp;} </pre> </p> <p> The <code>createBranches</code> function returns a tuple of <code>Line</code> values, one for the left branch, and one for the right branch. First, it calls <code>endpoint</code> with <code>line</code>. Notice that <code>line</code> is a <code>Line</code> value, and because <code>Line</code> defines <code>x</code>, <code>y</code>, <code>angle</code>, and <code>length</code> labels, it can be used as an input argument. This type-checks because of row type polymorphism. </p> <p> Given the endpoint of the parent line, <code>createBranches</code> then creates two new <code>Line</code> values (<code>left</code> and <code>right</code>) with that endpoint as their origins. Both of these values are modified with the <code>FractalParameters</code> argument, so that they branch off to the left and the right, and also shrink in an aesthetically pleasing manner. </p> <p> <strong>Creating a tree</strong> </p> <p> Now that you can calculate the branches of a line, you can create a tree using recursion: </p> <p> <pre><span style="color:#600277;">createTree</span>&nbsp;::&nbsp;Int&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">FractalParameters</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Line</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Tree</span>&nbsp;<span style="color:blue;">Line</span> createTree&nbsp;depth&nbsp;p&nbsp;line&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:#af00db;">if</span>&nbsp;depth&nbsp;<span style="color:#666666;">&lt;=</span>&nbsp;<span style="color:#09885a;">0</span> &nbsp;&nbsp;<span style="color:#af00db;">then</span>&nbsp;<span style="color:#dd0000;">Leaf</span>&nbsp;line &nbsp;&nbsp;<span style="color:#af00db;">else</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:#dd0000;">Tuple</span>&nbsp;leftLine&nbsp;rightLine&nbsp;<span style="color:#666666;">=</span>&nbsp;createBranches&nbsp;p&nbsp;line &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;left&nbsp;&nbsp;<span style="color:#666666;">=</span>&nbsp;createTree&nbsp;(depth&nbsp;<span style="color:#666666;">-</span>&nbsp;<span style="color:#09885a;">1</span>)&nbsp;p&nbsp;leftLine &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;right&nbsp;<span style="color:#666666;">=</span>&nbsp;createTree&nbsp;(depth&nbsp;<span style="color:#666666;">-</span>&nbsp;<span style="color:#09885a;">1</span>)&nbsp;p&nbsp;rightLine &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#dd0000;">Node</span>&nbsp;line&nbsp;left&nbsp;right </pre> </p> <p> The <code>createTree</code> function takes a <code>depth</code> argument, which specifies the depth (or is it the height?) of the tree. The reason I called it <code>depth</code> is because <code>createTree</code> is recursive, and <code>depth</code> controls the depth of the recursion. If <code>depth</code> is zero or less, the function returns a <code>Leaf</code> node containing the input <code>line</code>. </p> <p> Otherwise, it calls <code>createBranches</code> with the input <code>line</code>, and recursively calls <code>createTree</code> for each of these branches, but with a decremented <code>depth</code>. It then returns a <code>Node</code> containing the input <code>line</code> and the two sub-trees <code>left</code> and <code>right</code>. </p> <p> This implementation isn't tail-recursive, but the above image was generated with a recursion depth of only 10, so running out of stack space wasn't my biggest concern. </p> <p> <strong>Drawing the tree</strong> </p> <p> With the <code>createTree</code> function you can create a fractal tree, but it's no fun if you can't draw it. You can use the <code>Graphics.Canvas</code> module in order to draw on an HTML canvas. First, here's how to draw a single line: </p> <p> <pre><span style="color:#600277;">drawLine</span>&nbsp;::&nbsp;<span style="color:blue;">Context2D</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Line</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Eff</span>&nbsp;(canvas&nbsp;::&nbsp;<span style="color:blue;">CANVAS</span>)&nbsp;<span style="color:blue;">Unit</span> drawLine&nbsp;ctx&nbsp;(<span style="color:#dd0000;">Line</span>&nbsp;line)&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:#dd0000;">Tuple</span>&nbsp;x&#39;&nbsp;y&#39;&nbsp;<span style="color:#666666;">=</span>&nbsp;endpoint&nbsp;line &nbsp;&nbsp;void&nbsp;<span style="color:#666666;">$</span>&nbsp;strokePath&nbsp;ctx&nbsp;<span style="color:#666666;">$</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;void&nbsp;<span style="color:#666666;">$</span>&nbsp;moveTo&nbsp;ctx&nbsp;line<span style="color:#666666;">.</span>x&nbsp;line<span style="color:#666666;">.</span>y &nbsp;&nbsp;&nbsp;&nbsp;void&nbsp;<span style="color:#666666;">$</span>&nbsp;setLineWidth&nbsp;line<span style="color:#666666;">.</span>width&nbsp;ctx &nbsp;&nbsp;&nbsp;&nbsp;void&nbsp;<span style="color:#666666;">$</span>&nbsp;lineTo&nbsp;ctx&nbsp;x&#39;&nbsp;y&#39; &nbsp;&nbsp;&nbsp;&nbsp;closePath&nbsp;ctx </pre> </p> <p> While hardly unmanageable, I was surprised that I wasn't able to find a pre-defined function that would let me draw a line. Perhaps I was looking in the wrong place. </p> <p> With this helper function, you can now draw a tree using pattern matching: </p> <p> <pre><span style="color:#600277;">drawTree</span>&nbsp;::&nbsp;<span style="color:blue;">Context2D</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Tree</span>&nbsp;<span style="color:blue;">Line</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Eff</span>&nbsp;(canvas&nbsp;::&nbsp;<span style="color:blue;">CANVAS</span>)&nbsp;<span style="color:blue;">Unit</span> drawTree&nbsp;ctx&nbsp;(<span style="color:#dd0000;">Leaf</span>&nbsp;line)&nbsp;<span style="color:#666666;">=</span>&nbsp;drawLine&nbsp;ctx&nbsp;line drawTree&nbsp;ctx&nbsp;(<span style="color:#dd0000;">Node</span>&nbsp;line&nbsp;left&nbsp;right)&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;drawLine&nbsp;ctx&nbsp;line &nbsp;&nbsp;drawTree&nbsp;ctx&nbsp;left &nbsp;&nbsp;drawTree&nbsp;ctx&nbsp;right </pre> </p> <p> If the input tree is a <code>Leaf</code> value, the first line matches and the function simply draws the line, using the <code>drawLine</code> function. </p> <p> When the input tree is a <code>Node</code> value, the function first draws the <code>line</code> associated with that node, and then recursively calls itself with the <code>left</code> and <code>right</code> sub-trees. </p> <p> <strong>Execution</strong> </p> <p> The <code>drawTree</code> function enables you to draw using a <code>Context2D</code> value, which you can create from an HTML canvas: </p> <p> <pre>mcanvas&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;getCanvasElementById&nbsp;<span style="color:#a31515;">&quot;canvas&quot;</span> <span style="color:blue;">let</span>&nbsp;canvas&nbsp;<span style="color:#666666;">=</span>&nbsp;unsafePartial&nbsp;(fromJust&nbsp;mcanvas) ctx&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;getContext2D&nbsp;canvas </pre> </p> <p> From where does the <code>"canvas"</code> element come? Ultimately, PureScript compiles to JavaScript, and you can put the compiled script in an HTML file together with a <code>canvas</code> element: </p> <p> <pre><span style="color:blue;">&lt;</span><span style="color:maroon;">body</span><span style="color:blue;">&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">&lt;</span><span style="color:maroon;">canvas</span>&nbsp;<span style="color:red;">id</span><span style="color:blue;">=</span><span style="color:blue;">&quot;canvas&quot;</span>&nbsp;<span style="color:red;">width</span><span style="color:blue;">=</span><span style="color:blue;">&quot;800&quot;</span>&nbsp;<span style="color:red;">height</span><span style="color:blue;">=</span><span style="color:blue;">&quot;800&quot;</span><span style="color:blue;">&gt;&lt;/</span><span style="color:maroon;">canvas</span><span style="color:blue;">&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">&lt;</span><span style="color:maroon;">script</span>&nbsp;<span style="color:red;">src</span><span style="color:blue;">=</span><span style="color:blue;">&quot;index.js&quot;</span>&nbsp;<span style="color:red;">type</span><span style="color:blue;">=</span><span style="color:blue;">&quot;text/javascript&quot;</span><span style="color:blue;">&gt;&lt;/</span><span style="color:maroon;">script</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&lt;/</span><span style="color:maroon;">body</span><span style="color:blue;">&gt;</span></pre> </p> <p> Once you have a <code>Context2D</code> value, you can draw a tree. Here's the whole entry point, including the above canvas-finding code: </p> <p> <pre><span style="color:#600277;">main</span>&nbsp;::&nbsp;<span style="color:blue;">Eff</span>&nbsp;(canvas&nbsp;::&nbsp;<span style="color:blue;">CANVAS</span>)&nbsp;<span style="color:blue;">Unit</span> main&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#af00db;">do</span> &nbsp;&nbsp;mcanvas&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;getCanvasElementById&nbsp;<span style="color:#a31515;">&quot;canvas&quot;</span> &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;canvas&nbsp;<span style="color:#666666;">=</span>&nbsp;unsafePartial&nbsp;(fromJust&nbsp;mcanvas) &nbsp;&nbsp;ctx&nbsp;<span style="color:#666666;">&lt;-</span>&nbsp;getContext2D&nbsp;canvas &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;trunk&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">Line</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;x<span style="color:#666666;">:</span>&nbsp;<span style="color:#09885a;">300.0</span>,&nbsp;y<span style="color:#666666;">:</span>&nbsp;<span style="color:#09885a;">600.0</span>,&nbsp;angle<span style="color:#666666;">:</span>&nbsp;(pi&nbsp;<span style="color:#666666;">/</span>&nbsp;<span style="color:#09885a;">2.0</span>),&nbsp;length<span style="color:#666666;">:</span>&nbsp;<span style="color:#09885a;">100.0</span>,&nbsp;width<span style="color:#666666;">:</span>&nbsp;<span style="color:#09885a;">4.0</span>&nbsp;} &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;p&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">FractalParameters</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;leftAngle<span style="color:#666666;">:</span>&nbsp;<span style="color:#09885a;">0.1</span>,&nbsp;rightAngle<span style="color:#666666;">:</span>&nbsp;<span style="color:#09885a;">0.1</span>,&nbsp;shrinkFactor<span style="color:#666666;">:</span>&nbsp;<span style="color:#09885a;">0.8</span>&nbsp;} &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;tree&nbsp;<span style="color:#666666;">=</span>&nbsp;createTree&nbsp;<span style="color:#09885a;">10</span>&nbsp;p&nbsp;trunk &nbsp;&nbsp;drawTree&nbsp;ctx&nbsp;tree </pre> </p> <p> After it finds the <code>Context2D</code> value, it hard-codes a <code>trunk</code> <code>Line</code> and a set of <code>FractalParameters</code>. From these, it creates a tree of size 10 and draws the tree in the beginning of this article. </p> <p> You can fiddle with the parameters to your liking. For example, you can make the right angle wider than the left angle: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;p&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">FractalParameters</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;leftAngle<span style="color:#666666;">:</span>&nbsp;<span style="color:#09885a;">0.1</span>,&nbsp;rightAngle<span style="color:#666666;">:</span>&nbsp;<span style="color:#09885a;">0.2</span>,&nbsp;shrinkFactor<span style="color:#666666;">:</span>&nbsp;<span style="color:#09885a;">0.8</span>&nbsp;} </pre> </p> <p> This produces an asymmetric tree: </p> <p> <img src="/content/binary/asymmetric-fractal-tree.png" alt="An asymmetric fractal tree."> </p> <p> In order to compile the code, I used this command: </p> <p> <pre>$ pulp browserify -t html/index.js</pre> </p> <p> This compiles the PureScript code to a single <code>index.js</code> file, which is output to the <code>html</code> directory. This directory also contains the HTML file with the canvas. </p> <p> You can find the entire PureScript file in <a href="https://gist.github.com/ploeh/d9d207906adf44713e302ba7d3654f11">this Gist</a>. </p> <p> <strong>Summary</strong> </p> <p> It was fun to try PureScript. I've been staying away from JavaScript-based development for many years now, but if I ever have to do some client-side development, I may consider it. So far, I've found that PureScript seems viable for drawing. How good it is if you need to interact with 'normal' web-pages or SPAs, I don't know (yet). </p> <p> If you have some experience with Haskell, it looks like it's easy to get started with PureScript. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Using Polly with F# async workflows http://blog.ploeh.dk/2017/05/30/using-polly-with-f-async-workflows 2017-05-30T12:03:00+00:00 Mark Seemann <div id="post"> <p> <em>How to use Polly as a Circuit Breaker in F# async workflows.</em> </p> <p> <a href="http://amzn.to/11Kmrb2">Release It!</a> describes a stability design pattern called <a href="https://en.wikipedia.org/wiki/Circuit_breaker_design_pattern">Circuit Breaker</a>, which is used to fail fast if a downstream service is experiencing problems. </p> <p> I recently had to add a Circuit Breaker to an F# async workflow, and although Circuit Breaker isn't that difficult to implement (<a href="http://amzn.to/12p90MG">my book</a> contains an example in C#), I found it most prudent to use an existing implementation. <a href="http://www.thepollyproject.org">Polly</a> seemed a good choice. </p> <p> In my F# code base, I was already working with an 'abstraction' of the type <code>HttpRequestMessage -> Async&lt;HttpResponseMessage&gt;</code>: given an <code>HttpClient</code> called <code>client</code>, the implementation is as simple as <code>client.SendAsync &gt;&gt; Async.AwaitTask</code>. Since <code>SendAsync</code> can throw <code>HttpRequestException</code> or <code>WebException</code>, I wanted to define a Circuit Breaker policy for these two exception types. </p> <p> While Polly supports policies for Task-based APIs, it doesn't automatically work with F# async workflows. The problem is that whenever you convert an async workflow into a Task (using <code>Async.AwaitTask</code>), or a Task into an async workflow (using <code>Async.StartAsTask</code>), any exceptions thrown will end up buried within an <code>AggregateException</code>. In order to dig them out again, I first had to write this function: </p> <p> <pre><span style="color:green;">//&nbsp;Exception&nbsp;-&gt;&nbsp;bool</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:navy;">isNestedHttpException</span>&nbsp;(e&nbsp;:&nbsp;<span style="color:teal;">Exception</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;e&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;:?&nbsp;<span style="color:teal;">AggregateException</span>&nbsp;<span style="color:blue;">as</span>&nbsp;ae&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ae.InnerException&nbsp;<span style="color:navy;">::</span>&nbsp;<span style="color:teal;">Seq</span>.<span style="color:navy;">toList</span>&nbsp;ae.InnerExceptions &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Seq</span>.<span style="color:navy;">exists</span>&nbsp;<span style="color:navy;">isNestedHttpException</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;:?&nbsp;<span style="color:teal;">HttpRequestException</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">true</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;:?&nbsp;<span style="color:teal;">WebException</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">true</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">false</span></pre> </p> <p> This function recursively searches through all inner exceptions of an <code>AggregateException</code> and returns <code>true</code> if if finds one of the exception types I'm interested in handling; otherwise, it returns <code>false</code>. </p> <p> This predicate enabled me to write the Polly policy I needed: </p> <p> <pre><span style="color:blue;">open</span>&nbsp;Polly <span style="color:green;">//&nbsp;int&nbsp;-&gt;&nbsp;TimeSpan&nbsp;-&gt;&nbsp;CircuitBreaker.CircuitBreakerPolicy</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">createPolicy</span>&nbsp;exceptionsAllowedBeforeBreaking&nbsp;durationOfBreak&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Policy</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.<span style="color:navy;">Handle</span>&lt;<span style="color:teal;">AggregateException</span>&gt;(<span style="color:blue;">fun</span>&nbsp;ae&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">isNestedHttpException</span>&nbsp;ae) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.<span style="color:navy;">CircuitBreakerAsync</span>(exceptionsAllowedBeforeBreaking,&nbsp;durationOfBreak)</pre> </p> <p> Since Polly exposes an object-oriented API, I wanted a curried alternative, so I also wrote this curried helper function: </p> <p> <pre><span style="color:green;">//&nbsp;Policy&nbsp;-&gt;&nbsp;(&#39;a&nbsp;-&gt;&nbsp;Async&lt;&#39;b&gt;)&nbsp;-&gt;&nbsp;&#39;a&nbsp;-&gt;&nbsp;Async&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:navy;">execute</span>&nbsp;(policy&nbsp;:&nbsp;<span style="color:teal;">Policy</span>)&nbsp;<span style="color:navy;">f</span>&nbsp;&nbsp;req&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;policy.<span style="color:navy;">ExecuteAsync</span>(<span style="color:blue;">fun</span>&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">f</span>&nbsp;req&nbsp;|&gt;&nbsp;<span style="color:teal;">Async</span>.<span style="color:navy;">StartAsTask</span>)&nbsp;|&gt;&nbsp;<span style="color:teal;">Async</span>.<span style="color:navy;">AwaitTask</span></pre> </p> <p> The <code>execute</code> function executes any function of the type <code>'a -> Async&lt;'b&gt;</code> with a Polly policy. As you can see, there's some back-and-forth between Tasks and async workflows, so this is probably not the most efficient Circuit Breaker ever configured, but I wagered that since the underlying operation was going to involve an HTTP request and response, the overhead would be insignificant. No one has complained yet. </p> <p> When Polly opens the Circuit Breaker, it throws an exception of the type <code>BrokenCircuitException</code>. Again because of all the marshalling, this also gets wrapped within an <code>AggregateException</code>, so I had to write another function to unwrap it: </p> <p> <pre><span style="color:green;">//&nbsp;Exception&nbsp;-&gt;&nbsp;bool</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:navy;">isNestedCircuitBreakerException</span>&nbsp;(e&nbsp;:&nbsp;<span style="color:teal;">Exception</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;e&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;:?&nbsp;<span style="color:teal;">AggregateException</span>&nbsp;<span style="color:blue;">as</span>&nbsp;ae&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ae.InnerException&nbsp;<span style="color:navy;">::</span>&nbsp;<span style="color:teal;">Seq</span>.<span style="color:navy;">toList</span>&nbsp;ae.InnerExceptions &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Seq</span>.<span style="color:navy;">exists</span>&nbsp;<span style="color:navy;">isNestedCircuitBreakerException</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;:?&nbsp;CircuitBreaker.<span style="color:teal;">BrokenCircuitException</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">true</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">false</span></pre> </p> <p> The <code>isNestedCircuitBreakerException</code> is similar to <code>isNestedHttpException</code>, so it'd be tempting to refactor. I decided, however, to rely on the <a href="https://en.wikipedia.org/wiki/Rule_of_three_(computer_programming)">rule of three</a> and leave both functions as they were. </p> <p> In my F# code I prefer to handle application errors using Either values instead of relying on exceptions, so I wanted to translate any <code>BrokenCircuitException</code> to a particular <a href="http://blog.ploeh.dk/2017/01/03/decoupling-application-errors-from-domain-models">application error</a>. With the above <code>isNestedCircuitBreakerException</code> predicate, this was now possible with a <code>try/with</code> expression: </p> <p> <pre><span style="color:green;">//&nbsp;Policy&nbsp;-&gt;&nbsp;(&#39;a&nbsp;-&gt;&nbsp;Async&lt;&#39;b&gt;)&nbsp;-&gt;&nbsp;&#39;a&nbsp;-&gt;&nbsp;Async&lt;Result&lt;&#39;b,&nbsp;BoundaryFailure&gt;&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">sendUsingPolicy</span>&nbsp;policy&nbsp;<span style="color:navy;">send</span>&nbsp;req&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">async</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">try</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;resp&nbsp;=&nbsp;req&nbsp;|&gt;&nbsp;<span style="color:navy;">execute</span>&nbsp;policy&nbsp;<span style="color:navy;">send</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">succeed</span>&nbsp;resp &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">with</span>&nbsp;e&nbsp;<span style="color:blue;">when</span>&nbsp;<span style="color:navy;">isNestedCircuitBreakerException</span>&nbsp;e&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">fail</span>&nbsp;<span style="color:teal;">Controllers</span>.<span style="color:navy;">StabilityFailure</span>&nbsp;}</pre> </p> <p> This function takes a policy, a <code>send</code> function that actually sends the request, and the request to send. If all goes well, the <code>resp</code>onse is lifted into a <code>Success</code> case and returned. If the Circuit Breaker is open, a <code>StabilityFailure</code> value is returned instead. </p> <p> Since the <code>with</code> expression uses an exception filter, all other exceptions will still be thrown from this function. </p> <p> It might still be worthwhile to look into options for a more F#-friendly Circuit Breaker. One option would be to <a href="https://github.com/App-vNext/Polly/issues/252">work with the Polly maintainers to add such an API to Polly itself</a>. Another option would be to write a separate F# implementation. </p> </div> <div id="comments"> <hr /> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author">Johannes Egger</div> <div class="comment-content"> Nice post, thanks.<br /> There are two minor points I want to address: * I think instead of the recursive search for a nested exception you can use <a href="https://msdn.microsoft.com/en-US/library/system.aggregateexception.flatten%28v=vs.110%29.aspx?f=255&MSPPError=-2147217396">AggregateException.Flatten()</a> |> Seq.exists ...<br /> * And I know that you know that a major difference between <code>Async</code> and <code>Task</code> is that a <code>Task</code> is typically started whereas an <code>Async</code> is not. So it might be irritating that calling <code>execute</code> already starts the execution. If you wrapped the body of <code>execute</code> inside another <code>async</code> block it would be lazy as usual, I think. </div> <div class="comment-date">2017-06-03 21:21 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Simple holidays http://blog.ploeh.dk/2017/04/24/simple-holidays 2017-04-24T13:42:00+00:00 Mark Seemann <div id="post"> <p> <em>A story about arriving at the simplest solution that could possibly work.</em> </p> <p> The Zen of Python states: <a href="https://www.python.org/dev/peps/pep-0020">Simple is better than complex</a>. If I've met a programmer who disagrees with that, I'm not aware of it. It's hardly a controversial assertion, but what does 'simplicity' mean? Can you even identify a simple solution? </p> <p> I often see software developers defaulting to complex solutions, because a simpler solution isn't immediately obvious. In retrospect, a simple solution often <em>is</em> obvious, but only once you've found it. Until then, it's elusive. </p> <p> I'd like to share a story in which I arrived at a simple solution after several false starts. I hope it can be an inspiration. </p> <p> <strong>Dutch holidays</strong> </p> <p> Recently, I had to write some code that takes into account Dutch holidays. (In order to address any confusion that could arise from this: No, I'm not Dutch, I'm Danish, but currently, I'm doing some work on a system targeting a market in the Netherlands.) Specifically, given a date, I had to find the latest possible Dutch bank day on or before that date. </p> <p> For normal week days (Monday to Friday), it's easy, because such a date is already a bank date. In other words, in that case, you can simply return the input date. Also, in normal weeks, given a Saturday or Sunday, you should return the preceding Friday. The problem is, however, that some Fridays are holidays, and therefore not bank days. </p> <p> Like many other countries, the Netherlands have complicated rules for determining official holidays. Here are some tricky parts: <ul> <li> Some holidays always fall on the same date. One example is <em>Bevrijdingsdag (Liberation Day)</em>, which always falls on May 5. This holiday celebrates a historic event (the end of World War II in Europe), so if you wanted to calculate bank holidays in the past, you'd have to figure out in which year this became a public holiday. Surely, at least, it must have been 1945 or later.</li> <li> Some holidays fall on specific week days. The most prominent example is Easter, where <em>Goede Vrijdag (Good Friday)</em> always (as the name implies) falls on a Friday. Which Friday exactly can be calculated using a complicated algorithm. </li> <li> One holiday (<em>Koningsdag (King's Day)</em>) celebrates the king's birthday. The date is determined by the currently reigning monarch's birthday, and it's called <em>Queen's Day</em> when the reigning monarch is a queen. Obviously, the exact date changes depending on who's king or queen, and you can't predict when it's going to change. And what will happen if the current monarch abdicates or dies <em>before</em> his or her birthday, but <em>after</em> the new monarch's birthday? Does that mean that there will be no such holiday that year? Or what about the converse? Could there be <em>two</em> such holidays if a monarch abdicates <em>after</em> his or her birthday, and the new monarch's birthday falls later the same year? </li> </ul> Such problems aren't particular to the Netherlands. In Denmark, we can find similar examples, as I think you can do in many other countries. Ultimately, what constitutes an official holiday is a political decision. </p> <p> Figuring out if a date is a bank day, then, is what you might call an 'interesting' problem. How would you solve it? Before you read on, take a moment to consider how you'd attempt to solve the problem. If you will, you can consider the test cases immediately below to get a better sense of the problem. </p> <p> <strong>Test cases</strong> </p> <p> Here's a small set of test cases that I wrote in order to describe the problem: <table> <thead> <tr> <th>Test case</th> <th>Input date</th> <th>Expected output</th> </tr> </thead> <tbody> <tr><td>Monday</td><td>2017-03-06</td><td>2017-03-06</td></tr> <tr><td>Tuesday</td><td>2017-03-07</td><td>2017-03-07</td></tr> <tr><td>Wednesday</td><td>2017-03-08</td><td>2017-03-08</td></tr> <tr><td>Thursday</td><td>2017-03-09</td><td>2017-03-09</td></tr> <tr><td>Friday</td><td>2017-03-10</td><td>2017-03-10</td></tr> <tr><td>Saturday</td><td>2017-03-11</td><td>2017-03-10</td></tr> <tr><td>Sunday</td><td>2017-03-12</td><td>2017-03-10</td></tr> <tr><td>Good Friday</td><td>2017-04-14</td><td>2017-04-13</td></tr> <tr><td>Saturday after Good Friday</td><td>2017-04-15</td><td>2017-04-13</td></tr> <tr><td>Sunday after Good Friday</td><td>2017-04-16</td><td>2017-04-13</td></tr> <tr><td>Easter Monday</td><td>2017-04-17</td><td>2017-04-13</td></tr> <tr><td>Ascension Day - Thursday</td><td>2017-05-25</td><td>2017-05-24</td></tr> <tr><td>Whit Monday</td><td>2110-05-26</td><td>2110-05-23</td></tr> <tr><td>Liberation Day</td><td>9713-05-05</td><td>9713-05-04</td></tr> </tbody> </table> You'll notice that while I wrote most of my test cases in the near future (they're actually already in the past, now), I also added some far future dates for good measure. This assumes that the Netherlands will still celebrate Christian religious holidays in a hundred years from now, or their liberation day in 9713. That the Netherlands still exist then as the country we know today is a more than dubious assumption. </p> <p> <strong>Option: query a third-party service</strong> </p> <p> How would you solve the problem? The first solution that occurred to me was to use a third-party service. My guess is that most developers would consider this option. After all, it's essentially third-part data. The official holidays are determined by a third party, in this case the Dutch state. Surely, some Dutch official organisation would publish the list of official holidays somewhere. Perhaps, if you're lucky, there's even an on-line service you can query in order to download the list of holidays in some machine-readable format. </p> <p> There are, however, problems with this alternative: if you query such a service each time you need to find an appropriate bank date, how are you going to handle network errors? What if the third-part service is (temporarily) unavailable? </p> <p> Since I'm trying to figure out bank dates, you may already have guessed that I'm handling money, so it's not desirable to simple throw an exception and say that a caller would have to try again later. This could lead to loss of revenue. </p> <p> Querying a third-party service <em>every time</em> you need to figure out a Dutch bank holiday is out of the question for that reason. It's also likely to be inefficient. </p> <p> <strong>Option: cache third-party data</strong> </p> <p> Public holidays rarely change, so your next attempt could be a variation of the previous. Use third-party data, but instead of querying a third-party service every time you need the information, cache it. </p> <p> The problem with caching is that you're not guaranteed that the data you seek is in the cache. At application start, caches are usually empty. You'd have to rely on making one good query to the third-party data source in order to put the data in the cache. Only if that succeeds can you use the cache. This, again, leaves you vulnerable to the normal failure modes of distributed computing. If you can't reach the third-party data source, you have nothing to put in the cache. </p> <p> This can be a problem at application start, or when the cache data expires. </p> <p> Using a cache <em>reduces</em> the risk that the data is unavailable, but it doesn't eliminate it. It also adds complexity in the form of a cache that has to be configured and managed. Granted, you can use a reusable cache library or service to minimise that cost, so it may not be a big deal. Still, when making a decision about application architecture, I think it helps to explicitly identify advantages and disadvantages. </p> <p> Using a cache felt better to me, but I still wasn't happy. Too many things could go wrong. </p> <p> <strong>Option: persistent cache</strong> </p> <p> An incremental improvement on the previous option would be to write the cache data to persistent storage. This takes care of the issue with the cache being empty at application start-up. You can even deal with cache expiry by keep using stale data if you can't reach the 'official' source of the data. </p> <p> It leaves me a bit concerned, though, because if you allow the system to continue working with stale data, perhaps the application could enter a state where the data <em>never</em> updates. This could happen if the official data source moves, or changes format. In such a case, your application would keep trying to refresh the cache, and it would permanently fail. It would permanently run with stale data. Would you ever discover that problem? </p> <p> My concern is that the application could silently fail. You could counter that by logging a warning somewhere, but that would introduce a permanent burden on the team responsible for operating the application. This isn't impossible, but it does constitute an extra complexity. This alternative still didn't feel good to me. </p> <p> <strong>Option: cron</strong> </p> <p> Because I wasn't happy with any of the above alternatives, I started looking for different approaches to the problem. For a short while, I considered using a .NET implementation of <a href="https://en.wikipedia.org/wiki/Cron">cron</a>, with a crontab file. As far as I can tell, though there's no easy way to define Easter using cron, so I quickly abandoned that line of inquiry. </p> <p> <strong>Option: Nager.Date</strong> </p> <p> I wasn't entirely done with idea of calculating holidays on the fly. While calculating Easter is complicated, it can be done; there <em>is</em> a well-defined algorithm for it. Whenever I run into a general problem like this, I assume that someone has already done the required work, and this is also the case here. I quickly found an open source library called <a href="https://github.com/tinohager/Nager.Date">Nager.Date</a>; I'm sure that there are other alternatives, but Nager.Date looks like it's more than good enough. </p> <p> Such a library would be able to calculate all holidays for a given year, based on the algorithms embedded in it. That looked really promising. </p> <p> And yet... again, I was concerned. Official holidays are, as we've already established, politically decided. Using an algorithmic approach is <em>fundamentally</em> wrong, because that's not really how the holidays are determined. Holidays are defined by decree; it just so happens that some of the decrees take the form of an algorithm (such as Easter). </p> <p> What would happen if the Dutch state decides to add a new holiday? Or to take one away? Of when a new monarch is crowned? In order to handle such changes, we'd now have to hope that Nager.Date would be updated. We could try to make that more likely to happen by sending a pull request, but we'd still be vulnerable to a third party. What if the maintainer of Nager.Date is on vacation? </p> <p> Even if you can get a change into a library like Nager.Date, how is the algorithmic approach going to deal with historic dates? If the monarch changes, you can update the library, but does it correctly handle dates in the past, where the King's Day was different? </p> <p> Using an algorithm to determine a holiday seemed promising, but ultimately, I decided that I didn't like this option either. </p> <p> <strong>Option: configuration file</strong> </p> <p> My main concern about using an algorithm is that it'd make it difficult to handle arbitrary changes and exceptional cases. If we'd use a configuration file, on the other hand, we could always edit the configuration file in order to add or remove holidays for a given year. </p> <p> In essence, I was envisioning a configuration file that simply contained a list of holidays for each year. </p> <p> That sounds fairly simple and maintainable, but from where should the data come? </p> <p> You could probably download a list of official holidays for the next few years, like 2017, 2018, 2019, and so on, but the list would be finite, and probably not cover more than a few years into the future. </p> <p> What if, for example, I'd only be able to find an official list that goes to 2020? What will happen, then, when our application enters 2021? To the rest of the code base, it'd look like there were no holidays in 2021. </p> <p> At this time we can expect that new official lists have been published, so a programmer could obtain such a list and update the configuration file when it's time. This, unfortunately, is easy to forget. Four years in the future, perhaps none of the original programmers are left. It's more than likely that no one will remember to do this. </p> <p> <strong>Option: algorithm-generated configuration file</strong> </p> <p> The problem that the configuration data could 'run out' can be addressed by initialising the configuration file with data generated algorithmically. You could, for example, ask Nager.Date to generate all the holidays for the next many years. In fact, the year 9999 is the maximum year handled by .NET's <code>System.DateTime</code>, so you could ask it to generate all the holidays until 9999. </p> <p> That sounds like a lot, but it's only about half a megabyte of data... </p> <p> This solves the problem of 'running out' of holiday data, but still enables you to edit the holiday data when it changes in the future. For example, if the King's Day changes in 2031, you can change all the King's Day values from 2031 onward, while retaining the correct values for the previous years. </p> <p> This seems promising... </p> <p> <strong>Option: hard-coded holidays</strong> </p> <p> I almost decided to use the previous, configuration-based solution, and I was getting ready to invent a configuration file format, and a reader for it, and so on. Then I recalled <a href="http://mikehadlow.blogspot.com">Mike Hadlow</a>'s article about the <a href="http://mikehadlow.blogspot.com/2012/05/configuration-complexity-clock.html">configuration complexity clock</a>. </p> <p> I'm fairly certain that the only people who would be editing a hypothetical holiday configuration file would be programmers. In that case, why put the configuration in a proprietary format? Why deal with the hassle of reading and parsing such a file? Why not put the data in code? </p> <p> That's what I decided to do. </p> <p> It's not a perfect solution. It's still necessary to go and change that code file when the holiday rules change. For example, when the King's Day changes, you'd have to edit the file. </p> <p> Still, it's the <em>simplest</em> solution I could come up with. It has no moving parts, and uses a 'best effort' approach in order to guarantee that holidays will always be present. If you can come up with a better alternative, please leave a comment. </p> <p> <strong>Data generation</strong> </p> <p> Nager.Date seemed useful for generating the initial set of holidays, so I wrote a small F# script that generated the necessary C# code snippets: </p> <p> <pre><span style="color:blue;">#r</span>&nbsp;<span style="color:#a31515;">@&quot;packages/Nager.Date.1.3.0/lib/net45/Nager.Date.dll&quot;</span> <span style="color:blue;">open</span>&nbsp;System.IO <span style="color:blue;">open</span>&nbsp;Nager.Date <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">formatHoliday</span>&nbsp;(h&nbsp;:&nbsp;Model.<span style="color:teal;">PublicHoliday</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;y,&nbsp;m,&nbsp;d&nbsp;=&nbsp;h.Date.Year,&nbsp;h.Date.Month,&nbsp;h.Date.Day &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">sprintf</span>&nbsp;<span style="color:#a31515;">&quot;new&nbsp;DateTime(</span><span style="color:teal;">%i</span><span style="color:#a31515;">,&nbsp;</span><span style="color:teal;">%2i</span><span style="color:#a31515;">,&nbsp;</span><span style="color:teal;">%2i</span><span style="color:#a31515;">),&nbsp;//&nbsp;</span><span style="color:teal;">%s</span><span style="color:#a31515;">/</span><span style="color:teal;">%s</span><span style="color:#a31515;">&quot;</span>&nbsp;y&nbsp;m&nbsp;d&nbsp;h.Name&nbsp;h.LocalName <span style="color:blue;">let</span>&nbsp;holidays&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;[2017..9999] &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Seq</span>.<span style="color:navy;">collect</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;y&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:teal;">DateSystem</span>.<span style="color:navy;">GetPublicHoliday</span>&nbsp;(<span style="color:teal;">CountryCode</span>.NL,&nbsp;y)) &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Seq</span>.<span style="color:navy;">map</span>&nbsp;<span style="color:navy;">formatHoliday</span> <span style="color:teal;">File</span>.<span style="color:navy;">WriteAllLines</span>&nbsp;(<span style="color:blue;">__SOURCE_DIRECTORY__</span>&nbsp;+&nbsp;<span style="color:#a31515;">&quot;/dutch-holidays.txt&quot;</span>,&nbsp;holidays)</pre> </p> <p> This script simply asks Nager.Date to calculate all Dutch holidays for the years 2017 to 9999, format them as C# code snippets, and write the lines to a text file. The size of that file is 4 MB, because the auto-generated code comments also take up some space. </p> <p> <strong>First implementation attempt</strong> </p> <p> The next thing I did was to copy the text from <code>dutch-holidays.txt</code> to a C# code file, which I had already prepared with a class and a few methods that would query my generated data. The result looked like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">DateTimeExtensions</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;AdjustToLatestPrecedingDutchBankDay( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;value) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;candidate&nbsp;=&nbsp;value; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">while</span>&nbsp;(!(IsDutchBankDay(candidate.DateTime))) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;candidate&nbsp;=&nbsp;candidate.AddDays(-1); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;candidate; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;IsDutchBankDay(<span style="color:#2b91af;">DateTime</span>&nbsp;date) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(date.DayOfWeek&nbsp;==&nbsp;<span style="color:#2b91af;">DayOfWeek</span>.Saturday) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(date.DayOfWeek&nbsp;==&nbsp;<span style="color:#2b91af;">DayOfWeek</span>.Sunday) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(dutchHolidays.Contains(date.Date)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">true</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">#region</span>&nbsp;Dutch&nbsp;holidays &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">DateTime</span>[]&nbsp;dutchHolidays&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2017,&nbsp;&nbsp;1,&nbsp;&nbsp;1),&nbsp;<span style="color:green;">//&nbsp;New&nbsp;Year&#39;s&nbsp;Day/Nieuwjaarsdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2017,&nbsp;&nbsp;4,&nbsp;14),&nbsp;<span style="color:green;">//&nbsp;Good&nbsp;Friday/Goede&nbsp;Vrijdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2017,&nbsp;&nbsp;4,&nbsp;17),&nbsp;<span style="color:green;">//&nbsp;Easter&nbsp;Monday/&nbsp;Pasen</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2017,&nbsp;&nbsp;4,&nbsp;27),&nbsp;<span style="color:green;">//&nbsp;King&#39;s&nbsp;Day/Koningsdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2017,&nbsp;&nbsp;5,&nbsp;&nbsp;5),&nbsp;<span style="color:green;">//&nbsp;Liberation&nbsp;Day/Bevrijdingsdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2017,&nbsp;&nbsp;5,&nbsp;25),&nbsp;<span style="color:green;">//&nbsp;Ascension&nbsp;Day/Hemelvaartsdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2017,&nbsp;&nbsp;6,&nbsp;&nbsp;5),&nbsp;<span style="color:green;">//&nbsp;Whit&nbsp;Monday/Pinksteren</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2017,&nbsp;12,&nbsp;25),&nbsp;<span style="color:green;">//&nbsp;Christmas&nbsp;Day/Eerste&nbsp;kerstdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2017,&nbsp;12,&nbsp;26),&nbsp;<span style="color:green;">//&nbsp;St.&nbsp;Stephen&#39;s&nbsp;Day/Tweede&nbsp;kerstdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;&nbsp;1,&nbsp;&nbsp;1),&nbsp;<span style="color:green;">//&nbsp;New&nbsp;Year&#39;s&nbsp;Day/Nieuwjaarsdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;&nbsp;3,&nbsp;30),&nbsp;<span style="color:green;">//&nbsp;Good&nbsp;Friday/Goede&nbsp;Vrijdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;Lots&nbsp;and&nbsp;lots&nbsp;of&nbsp;dates...</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(9999,&nbsp;&nbsp;5,&nbsp;&nbsp;6),&nbsp;<span style="color:green;">//&nbsp;Ascension&nbsp;Day/Hemelvaartsdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(9999,&nbsp;&nbsp;5,&nbsp;17),&nbsp;<span style="color:green;">//&nbsp;Whit&nbsp;Monday/Pinksteren</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(9999,&nbsp;12,&nbsp;25),&nbsp;<span style="color:green;">//&nbsp;Christmas&nbsp;Day/Eerste&nbsp;kerstdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(9999,&nbsp;12,&nbsp;26),&nbsp;<span style="color:green;">//&nbsp;St.&nbsp;Stephen&#39;s&nbsp;Day/Tweede&nbsp;kerstdag</span> &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">#endregion</span> }</pre> </p> <p> My old computer isn't happy about having to compile 71,918 lines of C# in a single file, but it's doable, and as far as I can tell, Visual Studio caches the result of compilation, so as long as I don't change the file, there's little adverse effect. </p> <p> <strong>Unit tests</strong> </p> <p> In order to verify that the implementation works, I wrote this parametrised test: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">DateTimeExtensionsTests</span> { &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">Theory</span>] &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2017-03-06&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2017-03-06&quot;</span>)]&nbsp;<span style="color:green;">//&nbsp;Monday</span> &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2017-03-07&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2017-03-07&quot;</span>)]&nbsp;<span style="color:green;">//&nbsp;Tuesday</span> &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2017-03-08&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2017-03-08&quot;</span>)]&nbsp;<span style="color:green;">//&nbsp;Wednesday</span> &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2017-03-09&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2017-03-09&quot;</span>)]&nbsp;<span style="color:green;">//&nbsp;Thursday</span> &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2017-03-10&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2017-03-10&quot;</span>)]&nbsp;<span style="color:green;">//&nbsp;Friday</span> &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2017-03-11&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2017-03-10&quot;</span>)]&nbsp;<span style="color:green;">//&nbsp;Saturday</span> &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2017-03-12&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2017-03-10&quot;</span>)]&nbsp;<span style="color:green;">//&nbsp;Sunday</span> &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2017-04-14&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2017-04-13&quot;</span>)]&nbsp;<span style="color:green;">//&nbsp;Good&nbsp;Friday</span> &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2017-04-15&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2017-04-13&quot;</span>)]&nbsp;<span style="color:green;">//&nbsp;Saturday&nbsp;after&nbsp;Good&nbsp;Friday</span> &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2017-04-16&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2017-04-13&quot;</span>)]&nbsp;<span style="color:green;">//&nbsp;Sunday&nbsp;after&nbsp;Good&nbsp;Friday</span> &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2017-04-17&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2017-04-13&quot;</span>)]&nbsp;<span style="color:green;">//&nbsp;Easter&nbsp;Monday</span> &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2017-05-25&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2017-05-24&quot;</span>)]&nbsp;<span style="color:green;">//&nbsp;Ascension&nbsp;Day&nbsp;-&nbsp;Thursday</span> &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2110-05-26&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2110-05-23&quot;</span>)]&nbsp;<span style="color:green;">//&nbsp;Whit&nbsp;Monday</span> &nbsp;&nbsp;&nbsp;&nbsp;[<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;9713-05-05&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;9713-05-04&quot;</span>)]&nbsp;<span style="color:green;">//&nbsp;Liberation&nbsp;Day</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;AdjustToLatestPrecedingDutchBankDayReturnsCorrectResult( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;sutS, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;expectedS) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;sut&nbsp;=&nbsp;<span style="color:#2b91af;">DateTimeOffset</span>.Parse(sutS); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;actual&nbsp;=&nbsp;sut.AdjustToLatestPrecedingDutchBankDay(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.Equal(<span style="color:#2b91af;">DateTimeOffset</span>.Parse(expectedS),&nbsp;actual); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> All test cases pass. This works in <code>[Theory]</code>, but unfortunately, it turns out, it doesn't work in practice. </p> <p> When used in an ASP.NET Web API application, <code>AdjustToLatestPrecedingDutchBankDay</code> throws a <code>StackOverflowException</code>. It took me a while to figure out why, but it turns out that the stack size is smaller in IIS than when you run a 'normal' .NET process, such as an automated test. </p> <p> <code>System.DateTime</code> is a value type, and as far as I can tell, it uses some stack space during initialisation. When the <code>DateTimeExtensions</code> class is first used, the static <code>dutchHolidays</code> array is initialised, and that uses enough stack space to exhaust the stack when running in IIS. </p> <p> <strong>Final implementation</strong> </p> <p> The stack space problem seems to be related to <code>DateTime</code> initialisation. If I store a similar number of 64-bit integers in an array, it seems that there's no problem. </p> <p> First, I had to modify the <code>formatHoliday</code> function: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;<span style="color:navy;">formatHoliday</span>&nbsp;(h&nbsp;:&nbsp;Model.PublicHoliday)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;t,&nbsp;y,&nbsp;m,&nbsp;d&nbsp;=&nbsp;h.Date.Ticks,&nbsp;h.Date.Year,&nbsp;h.Date.Month,&nbsp;h.Date.Day &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">sprintf</span>&nbsp;<span style="color:#a31515;">&quot;</span><span style="color:teal;">%19i</span><span style="color:#a31515;">L,&nbsp;//&nbsp;</span><span style="color:teal;">%i</span><span style="color:#a31515;">-</span><span style="color:teal;">%02i</span><span style="color:#a31515;">-</span><span style="color:teal;">%02i</span><span style="color:#a31515;">,&nbsp;</span><span style="color:teal;">%s</span><span style="color:#a31515;">/</span><span style="color:teal;">%s</span><span style="color:#a31515;">&quot;</span>&nbsp;t&nbsp;y&nbsp;m&nbsp;d&nbsp;h.Name&nbsp;h.LocalName</pre> </p> <p> This enabled me to generate a new file with C# code fragments, but now containing ticks instead of <code>DateTime</code> values. Copying those C# fragments into my file gave me this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">DateTimeExtensions</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;AdjustToLatestPrecedingDutchBankDay( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">DateTimeOffset</span>&nbsp;value) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;candidate&nbsp;=&nbsp;value; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">while</span>&nbsp;(!(IsDutchBankDay(candidate.DateTime))) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;candidate&nbsp;=&nbsp;candidate.AddDays(-1); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;candidate; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;IsDutchBankDay(<span style="color:#2b91af;">DateTime</span>&nbsp;date) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(date.DayOfWeek&nbsp;==&nbsp;<span style="color:#2b91af;">DayOfWeek</span>.Saturday) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(date.DayOfWeek&nbsp;==&nbsp;<span style="color:#2b91af;">DayOfWeek</span>.Sunday) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(dutchHolidays.Contains(date.Date.Ticks)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">true</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">#region</span>&nbsp;Dutch&nbsp;holidays &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">long</span>[]&nbsp;dutchHolidays&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;636188256000000000L,&nbsp;<span style="color:green;">//&nbsp;2017-01-01,&nbsp;New&nbsp;Year&#39;s&nbsp;Day/Nieuwjaarsdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;636277248000000000L,&nbsp;<span style="color:green;">//&nbsp;2017-04-14,&nbsp;Good&nbsp;Friday/Goede&nbsp;Vrijdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;636279840000000000L,&nbsp;<span style="color:green;">//&nbsp;2017-04-17,&nbsp;Easter&nbsp;Monday/&nbsp;Pasen</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;636288480000000000L,&nbsp;<span style="color:green;">//&nbsp;2017-04-27,&nbsp;King&#39;s&nbsp;Day/Koningsdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;636295392000000000L,&nbsp;<span style="color:green;">//&nbsp;2017-05-05,&nbsp;Liberation&nbsp;Day/Bevrijdingsdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;636312672000000000L,&nbsp;<span style="color:green;">//&nbsp;2017-05-25,&nbsp;Ascension&nbsp;Day/Hemelvaartsdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;636322176000000000L,&nbsp;<span style="color:green;">//&nbsp;2017-06-05,&nbsp;Whit&nbsp;Monday/Pinksteren</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;636497568000000000L,&nbsp;<span style="color:green;">//&nbsp;2017-12-25,&nbsp;Christmas&nbsp;Day/Eerste&nbsp;kerstdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;636498432000000000L,&nbsp;<span style="color:green;">//&nbsp;2017-12-26,&nbsp;St.&nbsp;Stephen&#39;s&nbsp;Day/Tweede&nbsp;kerstdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;636503616000000000L,&nbsp;<span style="color:green;">//&nbsp;2018-01-01,&nbsp;New&nbsp;Year&#39;s&nbsp;Day/Nieuwjaarsdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;636579648000000000L,&nbsp;<span style="color:green;">//&nbsp;2018-03-30,&nbsp;Good&nbsp;Friday/Goede&nbsp;Vrijdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;Lots&nbsp;and&nbsp;lots&nbsp;of&nbsp;dates...</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3155171616000000000L,&nbsp;<span style="color:green;">//&nbsp;9999-05-06,&nbsp;Ascension&nbsp;Day/Hemelvaartsdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3155181120000000000L,&nbsp;<span style="color:green;">//&nbsp;9999-05-17,&nbsp;Whit&nbsp;Monday/Pinksteren</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3155372928000000000L,&nbsp;<span style="color:green;">//&nbsp;9999-12-25,&nbsp;Christmas&nbsp;Day/Eerste&nbsp;kerstdag</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3155373792000000000L,&nbsp;<span style="color:green;">//&nbsp;9999-12-26,&nbsp;St.&nbsp;Stephen&#39;s&nbsp;Day/Tweede&nbsp;kerstdag</span> &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">#endregion</span> }</pre> </p> <p> That implementation still passes all tests, <em>and</em> works at in practice as well. </p> <p> <strong>Conclusion</strong> </p> <p> It took me some time to find a satisfactory solution. I had more than once false start, until I ultimately arrived at the solution I've described here. I consider it simple because it's self-contained, deterministic, easy to understand, and fairly easy to maintain. I even left a comment in the code (not shown here) that described how to recreate the configuration data using the F# script shown here. </p> <p> The first solution that comes into your mind may not be the simplest solution, but if you take some time to consider alternatives, you may save yourself and your colleagues some future grief. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment"> <div class="comment-author"><a href="http://stackoverflow.com/users/861565/jadarnel27">jadarnel27</a></div> <div class="comment-content"> <p> What do you think about creating an "admin page" that would allow users to configure the bank holidays themselves (which would then be persisted in the application database)? This moves the burden of correctness to the administrators of the application, who I'm sure are highly motivated to get this right - as well as maintain it. It also removes the need for a deployment in the face of changing holidays. </p> <p> For the sake of convenience, you could still "seed" the database with the values generated by your F# script </p> </div> <div class="comment-date">2017-04-25 20:00 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> jadarnel27, thank you for writing. Your suggestion could be an option as well, but is hardly the simplest solution. In order to implement that, I'd need to add an administration web site for my application, program the user interface, connect the administration site and my original application (a REST API) to a persistent data source, write code for input validation, etcetera. </p> <p> Apart from all that work, the bank holidays would have to be stored in an out-of-process data store, such as a database or NoSQL data store, because the REST API that needs this feature is running in a server farm. This adds latency to each lookup, as well as a potential error source. What should happen if the connection to the data store is broken? Additionally, such a data store should be backed up, so we'd also need to establish an operational procedure to ensure that that happens. </p> <p> It was never a requirement that the owners of the application should be able to administer this themselves. It's certainly an option, but it's so much more complex than the solution outlined above that I think one should start by making a return-on-investment analysis. </p> </div> <div class="comment-date">2017-04-26 7:55 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://www.lefdal.cc/info">Alf Kåre Lefdal</a></div> <div class="comment-content"> <p> Another option: Calculate the holidays! I think you might find som useful code in my <a href="https://github.com/aklefdal/HolidaysApi/tree/master/HolidaysApi">HolidaysAPI</a>. It is even in F#, and the Web project is based upon a course or blog post by you. </p> </div> <div class="comment-date">2017-04-26 19:26 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Alf, thank you for writing. Apart from the alternative library, how is that different from the option I covered under the heading <em>Option: Nager.Date?</em> </p> </div> <div class="comment-date">2017-04-27 5:38 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.enazarov.ru">EQR</a></div> <div class="comment-content"> <p> Great post, thanks. The minor point here is that it is probably not so effective to do Contains over long[]. I'd consider using something that can check the value existance faster. </p> </div> <div class="comment-date">2017-04-30 19:00 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> EQR, thank you for writing. The performance profile of the implementation wasn't my main concern with this article, so it's likely that it can be improved. </p> <p> I did do some lackadaisical performance testing, but didn't detect any measurable difference between the implementation shown here, and one using a HashSet. On the other hand, there are other options I didn't try at all. One of these could be to perform a binary search, since the array is already ordered. </p> </div> <div class="comment-date">2017-05-15 11:03 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://evilpilaf.io/">Thomas</a></div> <div class="comment-content"> <p> Hi Mark, thanks for this post. One small note on your selection of bank holidays. Liberation day is an official bank holiday, but only for civil servants, for us 'normal' people this only happens every 5 years. This is reflected in Nager.Date wrong <a href="https://github.com/tinohager/Nager.Date/blob/master/Nager.Date/PublicHolidays/NetherlandsProvider.cs#L51">here</a> </p> </div> <div class="comment-date">2017-07-25 13:35 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Thomas, thank you for writing. That just goes to show, I think, that holiday calculation is as complicated as any other 'business logic'. It should be treated as such, and not as an algorithmic calculation. </p> </div> <div class="comment-date">2017-07-25 15:12 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. A reusable ApiController Adapter http://blog.ploeh.dk/2017/03/30/a-reusable-apicontroller-adapter 2017-03-30T10:17:00+00:00 Mark Seemann <div id="post"> <p> <em>Refactor ApiController Adapters to a single, reusable base class.</em> </p> <p> Regular readers of this blog will know that I write many RESTful APIs in F#, using ASP.NET Web API. Since I like to write functional F#, but ASP.NET Web API is an object-oriented framework, I prefer to escape the object-oriented framework as soon as possible. (In general, it makes good architectural sense to write most of your code as framework-independent as possible.) </p> <p> (Regular readers will also have <a href="http://blog.ploeh.dk/2017/01/03/decoupling-application-errors-from-domain-models">seen the above paragraph before</a>.) </p> <p> To bridge the gap between the object-oriented framework and my functional code, I implement Controller classes like this: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CreditCardController</span>&nbsp;(<span style="color:navy;">imp</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">ApiController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Post</span>&nbsp;(portalId&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;req&nbsp;:&nbsp;<span style="color:teal;">PaymentDtr</span>)&nbsp;:&nbsp;<span style="color:teal;">IHttpActionResult</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;portalId&nbsp;req&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;(resp&nbsp;:&nbsp;<span style="color:teal;">PaymentDtr</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">Ok</span>&nbsp;resp&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">RouteFailure</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">NotFound</span>&nbsp;()&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">BadRequest</span>&nbsp;msg&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">IntegrationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">InternalServerError</span>&nbsp;(<span style="color:teal;">InvalidOperationException</span>&nbsp;msg)&nbsp;:&gt;&nbsp;_</pre> </p> <p> The above example is a Controller that handles <a href="http://blog.ploeh.dk/2016/12/16/from-rest-to-algebraic-data">incoming payment data</a>. It immediately delegates all work to an injected <code>imp</code> function, and pattern matches on the return value in order to return correct responses. </p> <p> This <code>CreditCardController</code> extends ApiController in order to work nicely with ASP.NET Web API, while the injected <code>imp</code> function is written using functional programming. If you want to be charitable, you could say that the Controller is an <a href="https://en.wikipedia.org/wiki/Adapter_pattern">Adapter</a> between ASP.NET Web API and the functional F# API that actually implements the service. If you want to be cynical, you could also call it an <a href="http://wiki.c2.com/?AnticorruptionLayer">anti-corruption layer</a>. </p> <p> This works well, but tends to become repetitive: </p> <p> <pre><span style="color:blue;">open</span>&nbsp;System <span style="color:blue;">open</span>&nbsp;System.Web.Http <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">BoundaryFailure</span>&nbsp;= |&nbsp;<span style="color:navy;">RouteFailure</span> |&nbsp;<span style="color:navy;">ValidationFailure</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span> |&nbsp;<span style="color:navy;">IntegrationFailure</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span> <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">HomeController</span>&nbsp;(<span style="color:navy;">imp</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">ApiController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;[&lt;<span style="color:teal;">AllowAnonymous</span>&gt;] &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Get</span>&nbsp;()&nbsp;:&nbsp;<span style="color:teal;">IHttpActionResult</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;()&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;(resp&nbsp;:&nbsp;<span style="color:teal;">HomeDtr</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">Ok</span>&nbsp;resp&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">RouteFailure</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">NotFound</span>&nbsp;()&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">BadRequest</span>&nbsp;msg&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">IntegrationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">InternalServerError</span>&nbsp;(<span style="color:teal;">InvalidOperationException</span>&nbsp;msg)&nbsp;:&gt;&nbsp;_ <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CreditCardController</span>&nbsp;(<span style="color:navy;">imp</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">ApiController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Post</span>&nbsp;(portalId&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;req&nbsp;:&nbsp;<span style="color:teal;">PaymentDtr</span>)&nbsp;:&nbsp;<span style="color:teal;">IHttpActionResult</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;portalId&nbsp;req&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;(resp&nbsp;:&nbsp;<span style="color:teal;">PaymentDtr</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">Ok</span>&nbsp;resp&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">RouteFailure</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">NotFound</span>&nbsp;()&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">BadRequest</span>&nbsp;msg&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">IntegrationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">InternalServerError</span>&nbsp;(<span style="color:teal;">InvalidOperationException</span>&nbsp;msg)&nbsp;:&gt;&nbsp;_ <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CreditCardRecurrentStartController</span>&nbsp;(<span style="color:navy;">imp</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">ApiController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Post</span>&nbsp;(portalId&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;req&nbsp;:&nbsp;<span style="color:teal;">PaymentDtr</span>)&nbsp;:&nbsp;<span style="color:teal;">IHttpActionResult</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;portalId&nbsp;req&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;(resp&nbsp;:&nbsp;<span style="color:teal;">PaymentDtr</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">Ok</span>&nbsp;resp&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">RouteFailure</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">NotFound</span>&nbsp;()&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">BadRequest</span>&nbsp;msg&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">IntegrationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">InternalServerError</span>&nbsp;(<span style="color:teal;">InvalidOperationException</span>&nbsp;msg)&nbsp;:&gt;&nbsp;_ <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CreditCardRecurrentController</span>&nbsp;(<span style="color:navy;">imp</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">ApiController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Post</span>&nbsp;(portalId&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;transactionKey&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;req&nbsp;:&nbsp;<span style="color:teal;">PaymentDtr</span>)&nbsp;:&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">IHttpActionResult</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;portalId&nbsp;transactionKey&nbsp;req&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;(resp&nbsp;:&nbsp;<span style="color:teal;">PaymentDtr</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">Ok</span>&nbsp;resp&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">RouteFailure</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">NotFound</span>&nbsp;()&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">BadRequest</span>&nbsp;msg&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">IntegrationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">InternalServerError</span>&nbsp;(<span style="color:teal;">InvalidOperationException</span>&nbsp;msg)&nbsp;:&gt;&nbsp;_ <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PushController</span>&nbsp;(<span style="color:navy;">imp</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">ApiController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Post</span>&nbsp;(portalId&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;req&nbsp;:&nbsp;<span style="color:teal;">PushRequestDtr</span>)&nbsp;:&nbsp;<span style="color:teal;">IHttpActionResult</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;portalId&nbsp;req&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">Ok</span>&nbsp;()&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">RouteFailure</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">NotFound</span>&nbsp;()&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">BadRequest</span>&nbsp;msg&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">IntegrationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">InternalServerError</span>&nbsp;(<span style="color:teal;">InvalidOperationException</span>&nbsp;msg)&nbsp;:&gt;&nbsp;_</pre> </p> <p> At this point in our code base, we had five Controllers, and they all had similar implementations. They all pass their input parameters to their injected <code>imp</code> functions, and they all pattern match in exactly the same way. There are, however, small variations. Notice that one of the Controllers expose an HTTP GET operation, whereas the other four expose a POST operation. Conceivably, there could also be Controllers that allow both GET and POST, and so on, but this isn't the case here. </p> <p> The parameter list for each of the action methods also vary. Some take two arguments, one takes three, and the GET method takes none. </p> <p> Another variation is that <code>HomeController.Get</code> is annotated with an <code>[&lt;AllowAnonymous&gt;]</code> attribute, while the other action methods aren't. </p> <p> Despite these variations, it's possible to make the code less repetitive. </p> <p> You'd think you could easily refactor the code by turning the identical pattern matches into a reusable function. Unfortunately, it's not so simple, because the methods used to return HTTP responses are all <code>protected</code> (to use a C# term for something that F# doesn't even have). You can call <code>this.Ok ()</code> or <code>this.NotFound ()</code> from a derived class, but not from a 'free' <code>let</code>-bound function. </p> <p> After much trial and error, I finally arrived at this reusable base class: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:teal;">Imp</span>&lt;&#39;inp,&nbsp;&#39;out&gt;&nbsp;=&nbsp;&#39;inp&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:teal;">Result</span>&lt;&#39;out,&nbsp;<span style="color:teal;">BoundaryFailure</span>&gt; [&lt;<span style="color:teal;">AbstractClass</span>&gt;] <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">FunctionController</span>&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">ApiController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;Imp&lt;&#39;a,&#39;b&gt;&nbsp;-&gt;&nbsp;&#39;a&nbsp;-&gt;&nbsp;IHttpActionResult</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Execute</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;req&nbsp;:&nbsp;<span style="color:teal;">IHttpActionResult</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;req&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;resp&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">Ok</span>&nbsp;resp&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">RouteFailure</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">NotFound</span>&nbsp;()&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">BadRequest</span>&nbsp;msg&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">IntegrationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">InternalServerError</span>&nbsp;(<span style="color:teal;">InvalidOperationException</span>&nbsp;msg)&nbsp;:&gt;&nbsp;_</pre> </p> <p> It's been more than a decade, I think, since I last used inheritance to enable reuse, but in this case I could find no other way because of the design of ApiController. It gets the job done, though: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">HomeController</span>&nbsp;(<span style="color:navy;">imp</span>&nbsp;:&nbsp;<span style="color:teal;">Imp</span>&lt;_,&nbsp;<span style="color:teal;">HomeDtr</span>&gt;)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">FunctionController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;[&lt;<span style="color:teal;">AllowAnonymous</span>&gt;] &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Get</span>&nbsp;()&nbsp;=&nbsp;this.<span style="color:navy;">Execute</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;() <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CreditCardController</span>&nbsp;(<span style="color:navy;">imp</span>&nbsp;:&nbsp;<span style="color:teal;">Imp</span>&lt;_,&nbsp;<span style="color:teal;">PaymentDtr</span>&gt;)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">FunctionController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Post</span>&nbsp;(portalId&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;req&nbsp;:&nbsp;<span style="color:teal;">PaymentDtr</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">Execute</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(portalId,&nbsp;req) <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CreditCardRecurrentStartController</span>&nbsp;(<span style="color:navy;">imp</span>&nbsp;:&nbsp;<span style="color:teal;">Imp</span>&lt;_,&nbsp;<span style="color:teal;">PaymentDtr</span>&gt;)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">FunctionController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Post</span>&nbsp;(portalId&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;req&nbsp;:&nbsp;<span style="color:teal;">PaymentDtr</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">Execute</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(portalId,&nbsp;req) <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">CreditCardRecurrentController</span>&nbsp;(<span style="color:navy;">imp</span>&nbsp;:&nbsp;<span style="color:teal;">Imp</span>&lt;_,&nbsp;<span style="color:teal;">PaymentDtr</span>&gt;)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">FunctionController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Post</span>&nbsp;(portalId&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;transactionKey&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;req&nbsp;:&nbsp;<span style="color:teal;">PaymentDtr</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">Execute</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(portalId,&nbsp;transactionKey,&nbsp;req) <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PushController</span>&nbsp;(<span style="color:navy;">imp</span>&nbsp;:&nbsp;<span style="color:teal;">Imp</span>&lt;_,&nbsp;<span style="color:teal;">unit</span>&gt;)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">FunctionController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Post</span>&nbsp;(portalId&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;req&nbsp;:&nbsp;<span style="color:teal;">PushRequestDtr</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">Execute</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(portalId,&nbsp;req)</pre> </p> <p> Notice that all five Controllers now derive from <code>FunctionController</code> instead of <code>ApiController</code>. The <code>HomeController.Get</code> method is still annotated with the <code>[&lt;AllowAnonymous&gt;]</code> attribute, and it's still a GET operation, whereas all the other methods still implement POST operations. You'll also notice that the various <code>Post</code> methods have retained their varying number of parameters. </p> <p> In order to make this work, I had to make one trivial change: previously, all the <code>imp</code> functions were curried, but that doesn't fit into a single reusable base implementation. If you consider the type of <code>FunctionController.Execute</code>, you can see that the <code>imp</code> function is expected to take a single input value of the type <code>'a</code> (and return a value of the type <code>Result&lt;'b, BoundaryFailure&gt;</code>). Since any <code>imp</code> function can only take a single input value, I had to uncurry them all. You can see that now all the <code>Post</code> methods pass their input parameters as a single tuple to their injected <code>imp</code> function. </p> <p> You may be wondering about the <code>Imp&lt;&#39;inp,&nbsp;&#39;out&gt;</code> type alias. It's not strictly necessary, but helps keep the code clear. As I've attempted to indicate with the code comment above the <code>Execute</code> method, it's generic. When used in a derived Controller, the compiler can infer the type of <code>'a</code> because it already knows the types of the input parameters. For example, in <code>CreditCardController.Post</code>, the input parameters are already annotated as <code>string</code> and <code>PaymentDtr</code>, so the compiler can easily infer the type of <code>(portalId, req)</code>. </p> <p> On the other hand, the compiler can't infer the type of <code>'b</code>, because that value doesn't relate to <code>IHttpActionResult</code>. To help the compiler, I introduced the <code>Imp</code> type, because it enabled me to concisely annotate the type of the output value, while using a wild-card type for the input type. </p> <p> I wouldn't mind getting rid of Controllers altogether, but this is as close as I've been able to get with ASP.NET Web API. </p> </div> <div id="comments"> <hr> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="https://github.com/Alxandr">Aleksander Heintz</a></div> <div class="comment-content"> <p> I find a few issues with your blog post. Technically, I don't think anything you write in it is wrong, but there are a few of the statements I find problematic in the sense that people will probably read the blog post and conclude that "this is the only solution because of X" when in fact X is trivial to circumvent. </p> <p> The main issue I have with your post is the following: </p> <p> You'd think you could easily refactor the code by turning the identical pattern matches into a reusable function. Unfortunately, it's not so simple, because the methods used to return HTTP responses are all <code>protected</code> (to use a C# term for something that F# doesn't even have). You can call <code>this.Ok ()</code> or <code>this.NotFound ()</code> from a derived class, but not from a 'free' let-bound function. </p> <p> As stated earlier, there is nothing in your statement that is technically wrong, but I'd argue that you've reached the wrong conclusion due to lack of data. Or in this case familiarity with Web API and it's source code. If you go look at the source for <a href="https://aspnetwebstack.codeplex.com/SourceControl/latest#src/System.Web.Http/ApiController.cs"><code>ApiController</code></a>, you will notice that while true, the methods are <code>protected</code>, they are also trivial one-liners (helper methods) calling public APIs. It is completely possible to create a helper ala: </p> <p> <pre>// NOTE: Untested let handle (ctrl: ApiController) = function | Success of result -&gt; OkNegotiatedContentResult (result, ctrl) | Failure RouteFailure -&gt; NotFoundResult (ctrl) | Failure (ValidationFailure msg) -&gt; BadRequestErrorMessageResult (msg, ctrl) | Failure (IntegrationFailure msg) -&gt; ExceptionResult ((InvalidOperationException msg), ctrl)</pre> </p> <p> Another thing you can do is implement IHttpActionResult on your discriminate union, so you can just return it directly from you controller, in which case you'd end up with code like this: </p> <p> <pre>member this.Post (portalId : string, req : PaymentDtr) = imp portalId req</pre> </p> <p> It's definitely a bit more work, but in no way is it undoable. Thirdly, Web API (and especially the new MVC Core which has taken over for it) is incredibly pluggable through it's DI. You don't have to use the base <code>ApiController</code> class if you don't want to. You can override the resolution logic, the handing of return types, routing, you name it. It should for instance be entirely doable to write a handler for "controllers" that look like this: </p> <p> <pre>[&lt;Controller&gt;] module MyController = [&lt;AllowAnonymous&gt;] // assume impl is imported and in scope here - this controller has no DI let post (portalId : string) (req : PaymentDtr) = impl portalId req</pre> </p> <p> This however would probably be a bit of work requiring quite a bit of reflection voodoo. But somebody could definitely do it and put it in a library, and it would be nuget-installable for all. </p> <p> Anyways, I hope this shows you that there are more options to solve the problem. And who knows, you may have considered all of them and concluded them unviable. I've personally dug through the source code of both MVC and Web API a few times which is why I know a bunch of this stuff, and I just figured you might want to know some of it too :). </p> </div> <div class="comment-date">2017-03-30 22:06 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Aleksander, thank you for writing. I clearly have some scars from working with ASP.NET Web API since version 0.6 (or some value in that neighbourhood). In general, if a method is defined on <code>ApiController</code>, I've learned the hard way that such methods tend to be tightly coupled to the Controller. Often, such methods even look into the untyped context dictionary in the request message object, so I've gotten used to use them whenever they're present. </p> <p> These scars have prevented me from pushing the envelope on the 'new' methods that return various <code>IHttpActionResult</code> objects, but as you write, they truly are thin wrappers over constructors. </p> <p> This does, indeed, enable us to write the mapping of result values as a let-bound function. Thank you for pointing that out! </p> <p> Mine ended up looking like the following. We've added a few more success and error cases since I originally wrote this article, so it looks more complex than the initial example. </p> <p> <pre><span style="color:blue;">let</span>&nbsp;<span style="color:navy;">toHttpResult</span>&nbsp;(controller&nbsp;:&nbsp;<span style="color:teal;">ApiController</span>)&nbsp;result&nbsp;:&nbsp;<span style="color:teal;">IHttpActionResult</span>&nbsp;=&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;result&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;(<span style="color:navy;">OK</span>&nbsp;resp)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:teal;">OkNegotiatedContentResult</span>&nbsp;(resp,&nbsp;controller)&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;(<span style="color:navy;">Created</span>&nbsp;(resp,&nbsp;location))&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">CreatedNegotiatedContentResult</span>&nbsp;(location,&nbsp;resp,&nbsp;controller)&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">RouteFailure</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:teal;">NotFoundResult</span>&nbsp;controller&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">BadRequestErrorMessageResult</span>&nbsp;(msg,&nbsp;controller)&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">IntegrationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;resp&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;controller.Request.<span style="color:navy;">CreateErrorResponse</span>&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">HttpStatusCode</span>.InternalServerError, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;msg) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">ResponseMessageResult</span>&nbsp;resp&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">StabilityFailure</span>&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;resp&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:teal;">HttpResponseMessage</span>&nbsp;(<span style="color:teal;">HttpStatusCode</span>.ServiceUnavailable) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;resp.Headers.RetryAfter&nbsp;&lt;- &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">RetryConditionHeaderValue</span>&nbsp;(<span style="color:teal;">TimeSpan</span>.<span style="color:navy;">FromMinutes</span>&nbsp;5.) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">ResponseMessageResult</span>&nbsp;resp&nbsp;:&gt;&nbsp;_</pre> </p> <p> Letting my <code>BoundaryFailure</code> discriminated union implement <code>IHttpActionResult</code> sounds promising, but how would that be possible? </p> <p> The interface has a single method with the type <code>CancellationToken -&gt; Task&lt;HttpResponseMessage&gt;</code>. In order to create e.g. <code>NotFoundResult</code>, you need either an <code>HttpRequestMessage</code> or an <code>ApiController</code>, and none of those are available when <code>IHttpActionResult.ExecuteAsync</code> is invoked. </p> <p> When it comes to not having to derive from <code>ApiController</code>, I'm aware that even on the full .NET framework (we're not on .NET Core), 'all' the framework needs are <code>IHttpController</code> instances. As you imply, plugging into the framework is likely to be non-trivial, and so far, I haven't found that such an effort would be warranted. I might use it if someone else wrote it, though :) </p> </div> <div class="comment-date">2017-03-31 13:13 UTC</div> </div> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Dependency rejection http://blog.ploeh.dk/2017/02/02/dependency-rejection 2017-02-02T08:56:00+00:00 Mark Seemann <div id="post"> <p> <em>In functional programming, the notion of dependencies must be rejected. Instead, applications should be composed from pure and impure functions.</em> </p> <p> This is the third article in a small article series called <a href="http://blog.ploeh.dk/2017/01/27/from-dependency-injection-to-dependency-rejection">from dependency injection to dependency rejection</a>. In the <a href="http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection">previous article in the series</a>, you learned that dependency injection can't be functional, because it makes everything impure. In this article, you'll see what to do instead. </p> <p> <strong>Indirect input and output</strong> </p> <p> One of the first concepts you learned when you learned to program was that units of operation (functions, methods, procedures) take input and produce output. Input is in the form or input parameters, and output is in the form of return values. (Sometimes, though, a method returns nothing, but we know from category theory that nothing is also a value (called <em>unit</em>).) </p> <p> In addition to such input and output, a unit with dependencies also take indirect input, and produce indirect output: </p> <p> <img src="/content/binary/unit-with-dependencies-and-direct-and-indirect-input-and-output.png" alt="A unit with dependencies and direct and indirect input and output."> </p> <p> When a unit queries a dependency for data, the data returned from the dependency is indirect input. In the restaurant reservation example used in this article series, when <code>tryAccept</code> calls <code>readReservations</code>, the returned reservations are indirect input. </p> <p> Likewise, when a unit invokes a dependency, all arguments passed to that dependency constitute indirect output. In the example, when <code>tryAccept</code> calls <code>createReservation</code>, the reservation value it uses as input argument to that function call becomes output. The intent, in this case, is to save the reservation in a database. </p> <p> <strong>From indirect output to direct output</strong> </p> <p> Instead of producing indirect output, you can refactor functions to produce direct output. </p> <p> <img src="/content/binary/unit-with-dependencies-and-direct-input-and-output-but-no-indirect-output.png" alt="A unit with dependencies and direct input and output, but no indirect output."> </p> <p> Such a refactoring is often problematic in mainstream object-oriented languages like C# and Java, because you wish to control the circumstances in which the indirect output must be produced. Indirect output often implies side-effects, but perhaps the side-effect must only happen when certain conditions are fulfilled. In the restaurant reservation example, the desired side-effect is to add a reservation to a database, but this must only happen when the restaurant has sufficient remaining capacity to serve the requested number of people. Since languages like C# and Java are statement-based, it can be difficult to separate the decision from the action. </p> <p> In expression-based languages like F# and Haskell, <a href="http://blog.ploeh.dk/2016/09/26/decoupling-decisions-from-effects">it's trivial to decouple decisions from effects</a>. </p> <p> In the <a href="http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection">previous article</a>, you saw a version of <code>tryAccept</code> with this signature: </p> <p> <pre><span style="color:green;">//&nbsp;int&nbsp;-&gt;&nbsp;(DateTimeOffset&nbsp;-&gt;&nbsp;Reservation&nbsp;list)&nbsp;-&gt;&nbsp;(Reservation&nbsp;-&gt;&nbsp;int)&nbsp;-&gt;&nbsp;Reservation</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;int&nbsp;option</span></pre> </p> <p> The second function argument, with the type <code>Reservation&nbsp;-&gt;&nbsp;int</code>, produces indirect output. The <code>Reservation</code> value is the output. The function even violates Command Query Separation and returns the database ID of the added reservation, so that's additional indirect input. The overall function returns <code>int option</code>: the database ID if the reservation was added, and <code>None</code> if it wasn't. </p> <p> Refactoring the indirect output to direct output is easy, then: just remove the <code>createReservation</code> function and return the <code>Reservation</code> value instead: </p> <p> <pre><span style="color:green;">//&nbsp;int&nbsp;-&gt;&nbsp;(DateTimeOffset&nbsp;-&gt;&nbsp;Reservation&nbsp;list)&nbsp;-&gt;&nbsp;Reservation&nbsp;-&gt;&nbsp;Reservation&nbsp;option</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;capacity&nbsp;<span style="color:navy;">readReservations</span>&nbsp;reservation&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">readReservations</span>&nbsp;reservation.Date&nbsp;|&gt;&nbsp;<span style="color:teal;">List</span>.<span style="color:navy;">sumBy</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x.Quantity) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;reservedSeats&nbsp;+&nbsp;reservation.Quantity&nbsp;&lt;=&nbsp;capacity &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;{&nbsp;reservation&nbsp;<span style="color:blue;">with</span>&nbsp;IsAccepted&nbsp;=&nbsp;<span style="color:blue;">true</span>&nbsp;}&nbsp;|&gt;&nbsp;<span style="color:navy;">Some</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:navy;">None</span></pre> </p> <p> Notice that this refactored version of <code>tryAccept</code> returns a <code>Reservation option</code> value. The implication is that the reservation was accepted if the return value is a <code>Some</code> case, and rejected if the value is <code>None</code>. The decision is embedded in the value, but decoupled from the side-effect of writing to the database. </p> <p> This function clearly never writes to the database, so at the boundary of your application, you'll have to connect the decision to the effect. To keep the example consistent with the previous article, you can do this in a <code>tryAcceptComposition</code> function, like this: </p> <p> <pre><span style="color:green;">//&nbsp;Reservation&nbsp;-&gt;&nbsp;int&nbsp;option</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">tryAcceptComposition</span>&nbsp;reservation&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;reservation &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;10&nbsp;(<span style="color:teal;">DB</span>.<span style="color:navy;">readReservations</span>&nbsp;connectionString) &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Option</span>.<span style="color:navy;">map</span>&nbsp;(<span style="color:teal;">DB</span>.<span style="color:navy;">createReservation</span>&nbsp;connectionString)</pre> </p> <p> Notice that the type of <code>tryAcceptComposition</code> remains <code>Reservation&nbsp;-&gt;&nbsp;int&nbsp;option</code>. This is a true refactoring. The overall API remains the same, as does the behaviour. The reservation is added to the database only if there's sufficient remaining capacity, and in that case, the ID of the reservation is returned. </p> <p> <strong>From indirect input to direct input</strong> </p> <p> Just as you can refactor from indirect output to direct output can you refactor from indirect input to direct input. </p> <p> <img src="/content/binary/unit-with-dependencies-and-direct-input-and-output.png" alt="A unit with dependencies and direct input and output."> </p> <p> Again, in statement-based languages like C# and Java, this may be problematic, because you may wish to defer a query, or base it on a decision inside the unit. In expression-based languages you can decouple decisions from effects, and deferred execution can always be done by lazy evaluation, if that's required. In the case of the current example, however, the refactoring is easy: </p> <p> <pre><span style="color:green;">//&nbsp;int&nbsp;-&gt;&nbsp;Reservation&nbsp;list&nbsp;-&gt;&nbsp;Reservation&nbsp;-&gt;&nbsp;Reservation&nbsp;option</span> <span style="color:blue;">let</span>&am