ploeh blog 2017-08-23T05:58:05+00:00 Mark Seemann danish software design http://blog.ploeh.dk 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 come back to later. </p> <p> It doesn't seem particularly useful, and a first attempt at using it seems to confirm such skepticism: </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> The Builder functor. </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> <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>The Builder functor</li> <li>Builder as Identity</li> <li>Test data without Builders</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>&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;capacity&nbsp;reservations&nbsp;reservation&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;=&nbsp;reservations&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> Instead of calling a (potentially impure) function, this version of <code>tryAccept</code> takes a list of existing reservations as input. It still sums over all the quantities, and the rest of the code is the same as before. </p> <p> Obviously, the list of existing reservations must come from somewhere, like a database, so <code>tryAcceptComposition</code> will still have to take care of that: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b&nbsp;-&gt;&nbsp;&#39;c)&nbsp;-&gt;&nbsp;&#39;b&nbsp;-&gt;&nbsp;&#39;a&nbsp;-&gt;&nbsp;&#39;c</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">flip</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x&nbsp;y&nbsp;=&nbsp;<span style="color:navy;">f</span>&nbsp;y&nbsp;x <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.Date &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">DB</span>.<span style="color:navy;">readReservations</span>&nbsp;connectionString &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">flip</span>&nbsp;(<span style="color:navy;">tryAccept</span>&nbsp;10)&nbsp;reservation &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> The type and behaviour of this composition is still the same as before, but the data flow is different. First, the function queries the database, which is an impure operation. Then, it pipes the resulting list of reservations to <code>tryAccept</code>, which is now a <a href="https://en.wikipedia.org/wiki/Pure_function">pure function</a>. It returns a <code>Reservation option</code> that's finally mapped to another impure operation, which writes the reservation to the database if the reservation was accepted. </p> <p> You'll notice that I also added a <code>flip</code> function in order to make the composition more concise, but I could also have used a lambda expression when invoking <code>tryAccept</code>. The <code>flip</code> function is a part of Haskell's standard library, but isn't in F#'s core library. It's not crucial to the example, though. </p> <p> <strong>Evaluation</strong> </p> <p> Did you notice that in the previous diagram, above, all arrows between the unit and its dependencies were gone? This means that the unit no longer has any dependencies: </p> <p> <img src="/content/binary/unit-with-direct-input-and-output.png" alt="A unit with direct input and output, but no dependencies."> </p> <p> Dependencies are, by their nature, impure, and since pure functions can't call impure functions, functional programming must reject the notion of dependencies. Pure functions can't <em>depend</em> on impure functions. </p> <p> Instead, pure functions must take direct input and produce direct output, and the impure boundary of an application must compose impure and pure functions together in order to achieve the desired behaviour. </p> <p> In the previous article, you saw how Haskell can be used to evaluate whether or not an implementation is functional. You can port the above F# code to Haskell to verify that this is the case. </p> <p> <pre><span style="color:#600277;">tryAccept</span>&nbsp;::&nbsp;Int&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;[<span style="color:blue;">Reservation</span>]&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Maybe&nbsp;<span style="color:blue;">Reservation</span> tryAccept&nbsp;capacity&nbsp;reservations&nbsp;reservation&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;<span style="color:#666666;">=</span>&nbsp;sum&nbsp;<span style="color:#666666;">$</span>&nbsp;map&nbsp;quantity&nbsp;reservations &nbsp;&nbsp;<span style="color:blue;">in</span>&nbsp;&nbsp;<span style="color:#af00db;">if</span>&nbsp;reservedSeats&nbsp;<span style="color:#666666;">+</span>&nbsp;quantity&nbsp;reservation&nbsp;<span style="color:#666666;">&lt;=</span>&nbsp;capacity &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#af00db;">then</span>&nbsp;Just&nbsp;<span style="color:#666666;">$</span>&nbsp;reservation&nbsp;{&nbsp;isAccepted&nbsp;<span style="color:#666666;">=</span>&nbsp;True&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#af00db;">else</span>&nbsp;Nothing</pre> </p> <p> This version of <code>tryAccept</code> is pure, and compiles, but as you learned in the previous article, that's not the crucial question. The question is whether the composition compiles? </p> <p> <pre><span style="color:#600277;">tryAcceptComposition</span>&nbsp;::&nbsp;<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;IO&nbsp;(Maybe&nbsp;Int) tryAcceptComposition&nbsp;reservation&nbsp;<span style="color:#666666;">=</span>&nbsp;runMaybeT&nbsp;<span style="color:#666666;">$</span> &nbsp;&nbsp;liftIO&nbsp;(<span style="color:#dd0000;">DB</span><span style="color:#666666;">.</span>readReservations&nbsp;connectionString&nbsp;<span style="color:#666666;">$</span>&nbsp;date&nbsp;reservation) &nbsp;&nbsp;<span style="color:#666666;">&gt;&gt;=</span>&nbsp;<span style="color:#dd0000;">MaybeT</span>&nbsp;<span style="color:#666666;">.</span>&nbsp;return&nbsp;<span style="color:#666666;">.</span>&nbsp;flip&nbsp;(tryAccept&nbsp;<span style="color:#09885a;">10</span>)&nbsp;reservation &nbsp;&nbsp;<span style="color:#666666;">&gt;&gt;=</span>&nbsp;liftIO&nbsp;<span style="color:#666666;">.</span>&nbsp;<span style="color:#dd0000;">DB</span><span style="color:#666666;">.</span>createReservation&nbsp;connectionString</pre> </p> <p> This version of <code>tryAcceptComposition</code> compiles, and works as desired. The code exhibits a common pattern for Haskell: First, gather data from impure sources. Second, pass pure data to pure functions. Third, take the pure output from the pure functions, and do something impure with it. </p> <p> It's like a sandwich, with the best parts in the middle, and some necessary stuff surrounding it. </p> <p> <strong>Summary</strong> </p> <p> Dependencies are, by nature, impure. They're either non-deterministic, have side-effects, or both. Pure functions can't call impure functions (because that would make them impure as well), so pure functions can't have dependencies. Functional programming must reject the notion of dependencies. </p> <p> Obviously, software is only useful with impure behaviour, so instead of injecting dependencies, functional programs must be composed in impure contexts. Impure functions can call pure functions, so at the boundary, an application must gather impure data, and use it to call pure functions. This <a href="http://blog.ploeh.dk/2016/03/18/functional-architecture-is-ports-and-adapters">automatically leads to the ports and adapters architecture</a>. </p> <p> This style of programming is surprisingly often possible, but <a href="http://blog.ploeh.dk/2017/07/10/pure-interactions">it's not a universal solution; other alternatives exist</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="https://dusted.codes/">Dustin Moris Gorski</a></div> <div class="comment-content"> <p>Hi, Thank you for this blog post series. I also read your other posts on ports and adapters and the proposed architecture makes sense in terms of how it works, but I struggle to see the benefit in a real world application. Maybe let me explain my question with a quick example.</p> <p>In the 2nd blog post of this series you demonstrated this function:</p> <pre><code>// int -&gt; (DateTimeOffset -&gt; Reservation list) -&gt; (Reservation -&gt; int) -&gt; Reservation // -&gt; int option let tryAccept capacity readReservations createReservation reservation = let reservedSeats = readReservations reservation.Date |&gt; List.sumBy (fun x -&gt; x.Quantity) if reservedSeats + reservation.Quantity &lt;= capacity then createReservation { reservation with IsAccepted = true } |&gt; Some else None</code></pre> <p>If I understand it correctly this function is pure if <code>readReservations</code> and <code>createReservation</code> are both pure otherwise it is impure.</p> <p>I also understand the benefit of having a pure function, because it is a lot easier to understand the code, test the code and reason about it. That makes sense as well :).</p> <p>So in the 3rd blog post you make <code>tryAccept</code> a pure function, by removing the function dependencies and replacing it with simple values:</p> <pre><code>// int -&gt; Reservation list -&gt; Reservation -&gt; Reservation option let tryAccept capacity reservations reservation = let reservedSeats = reservations |&gt; List.sumBy (fun x -&gt; x.Quantity) if reservedSeats + reservation.Quantity &lt;= capacity then { reservation with IsAccepted = true } |&gt; Some else None</code></pre> <p>However this was only possible because you essentially moved the impure code into another new function:</p> <pre><code>// Reservation -&gt; int option let tryAcceptComposition reservation = reservation.Date |&gt; DB.readReservations connectionString |&gt; flip (tryAccept 10) reservation |&gt; Option.map (DB.createReservation connectionString)</code></pre> <p>So after all the application hasn't really reduced the total number of impure functions (still 3 in each case - <code>readReservations</code>, <code>createReservation</code> and <code>tryAccept[Composition]</code>).</p> <p>The only difference I see is that one impure function has been refactored into 2 functions - one pure and one impure. Considering that the original <code>tryAccept</code> function was already fully testable from a unit testing point of view and quite readable what is the benefit of this additional step? I would almost argue that the original <code>tryAccept</code> function was even easier to read/understand than the combination of <code>tryAccept</code> and <code>tryAcceptComposition</code>. I understand that impure functions like this are not truly functional, but in a real world application you must have some impure functions and I would like to better understand where trade-off benefit of that additional step is? Am I missing something else?</p> <p></p> </div> <div class="comment-date">2017-02-03 10:34 UTC</div> </div> <div class="comment"> <div class="comment-author"> <a href="http://blog.ploeh.dk">Mark Seemann</a> </div> <div class="comment-content"> </div> <p> Dustin, thank you for writing. There are several answers to your question, depending on the perspective one is interested in. I'll see if I can cover the most important ones. </p> <p> <strong>Is it functional?</strong> </p> <p> On the most fundamental level, I'm interested in learning functional programming. In order to do this, I seek out strictly functional solutions to problems. Haskell is a great help in that endeavour, because it's not a hybrid language. It only allows you to do functional programming. </p> <p> Does it make sense to back-port Haskell solutions to F#, then? That depends on what one is trying to accomplish, but if the goal is nothing but learning how to do it functionally, then that goal is accomplished. </p> <p> <strong>Toy examples</strong> </p> <p> On another level, the example I've presented here is obviously nothing but a toy example. It's simplified, because if I presented readers with a more realistic example, the complexity of the real problem could easily drown out the message of the example. Additionally, most readers would probably give up reading. </p> <p> I'm asking my readers to pretend that the problem is more complex than the one I present here; pretend that this problem is a stand-in for a harder problem. </p> <p> In this particular context, there could be all sorts of complications: <ul> <li> Reservations could be for time slots instead of whole dates. In order to keep the example simple, I treat each reservation as simply blocking out an entire date. I once dined at a restaurant where they started serving at 19:00, and if you weren't there on time, you'd miss the first courses. Most restaurants, though, allow you to make reservations for a particular time, and many have more than one serving on a single evening. </li> <li> Most restaurants have tables, not seats. Again, the same restaurant I mentioned above seated 12 people at a bar-like arrangement facing the kitchen, but most restaurants have tables of varying sizes. If they get a reservation for three people, they may have to reserve a table for four. </li> <li> Perhaps the restaurant would like to implement a feature where, if it receives a reservation that doesn't fill out a table (like a reservation for three people, and only four-people tables are left), it'd defer the decision to see if a 'better' reservation arrives later. </li> <li> Some people make reservations, but never show up. For that reason, a restaurant may want to allow a degree of overbooking, just like airlines. How much overbooking to allow is a business decision. </li> <li> A further wrinkle on the overbooking business rule is that you may have a different overbooking policy for Fridays than for, say, Wednesdays. </li> <li> Perhaps the restaurant would like to implement a waiting-list feature as well. </li> </ul> As you can see, we could easily imagine that the business logic could be more convoluted. Keeping all of that decision logic pure would be beneficial. </p> <p> <strong>Separation of concerns</strong> </p> <p> In my experience, there's an entire category of software defects that occur because of state mutation in business logic. You could have an area of your code that calls other code, which calls other code, and so on, for several levels of nesting. Somewhere, deep in the bowels of such a system, a conditional statement flips a boolean flag that consequently impact how the rest of the program runs. I've seen plenty of examples of such software, and it's inhumane; it doesn't fit within human cognitive limits. </p> <p> Code that allows arbitrary side-effects is difficult to reason about. </p> <p> Knowing that an subgraph of your call tree is pure reduces defects like that. This is nothing but another way to restate the <a href="https://en.wikipedia.org/wiki/Command%E2%80%93query_separation">command-query separation</a> principle. In F#, we still can't be sure unless we exert some discipline, but in Haskell, all it takes is a look at the type of a function or value. If it doesn't include <code>IO</code>, you know that it's pure. </p> <p> Separating pure code from impure code is separation of concern. Business logic is one concern, and I/O is another concern, and the better you can separate these, the fewer sources of defects you'll have. True, I haven't reduced the amount of code by much, but I've <em>separated</em> concerns by separating the code that contains (side) effects from the pure code. </p> <p> <strong>Testability</strong> </p> <p> It's true that the partial application version of <code>tryAccept</code> is <a href="http://blog.ploeh.dk/2015/05/07/functional-design-is-intrinsically-testable">testable, because it has isolation</a>, but the tests are more complicated than they have to be: </p> <p> <pre>[&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``tryAccept&nbsp;behaves&nbsp;correctly&nbsp;when&nbsp;it&nbsp;can&nbsp;accept``</span> &nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:navy;">NonNegativeInt</span>&nbsp;excessCapacity) &nbsp;&nbsp;&nbsp;&nbsp;(expected&nbsp;:&nbsp;<span style="color:teal;">int</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Tuple2</span>.<span style="color:navy;">curry</span>&nbsp;<span style="color:navy;">id</span> &nbsp;&nbsp;&nbsp;&nbsp;&lt;!&gt;&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;&lt;*&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">listOf</span>&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;&nbsp;<span style="color:teal;">Arb</span>.<span style="color:navy;">fromGen</span>&nbsp;|&gt;&nbsp;<span style="color:teal;">Prop</span>.<span style="color:navy;">forAll</span>&nbsp;&lt;|&nbsp;<span style="color:blue;">fun</span>&nbsp;(reservation,&nbsp;reservations)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;capacity&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;excessCapacity &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;+&nbsp;(reservations&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;&nbsp;&nbsp;&nbsp;&nbsp;+&nbsp;reservation.Quantity &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">readReservations</span>&nbsp;=&nbsp;((=!)&nbsp;reservation.Date)&nbsp;&gt;&gt;!&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">createReservation</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;((=!)&nbsp;{&nbsp;reservation&nbsp;<span style="color:blue;">with</span>&nbsp;IsAccepted&nbsp;=&nbsp;<span style="color:blue;">true</span>&nbsp;})&nbsp;&gt;&gt;!&nbsp;expected &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;capacity&nbsp;<span style="color:navy;">readReservations</span>&nbsp;<span style="color:navy;">createReservation</span>&nbsp;reservation &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">Some</span>&nbsp;expected&nbsp;=!&nbsp;actual [&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``tryAccept&nbsp;behaves&nbsp;correctly&nbsp;when&nbsp;it&nbsp;can&#39;t&nbsp;accept``</span> &nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:navy;">PositiveInt</span>&nbsp;lackingCapacity)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Tuple2</span>.<span style="color:navy;">curry</span>&nbsp;<span style="color:navy;">id</span> &nbsp;&nbsp;&nbsp;&nbsp;&lt;!&gt;&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;&lt;*&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">listOf</span>&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;&nbsp;<span style="color:teal;">Arb</span>.<span style="color:navy;">fromGen</span>&nbsp;|&gt;&nbsp;<span style="color:teal;">Prop</span>.<span style="color:navy;">forAll</span>&nbsp;&lt;|&nbsp;<span style="color:blue;">fun</span>&nbsp;(reservation,&nbsp;reservations)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;capacity&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(reservations&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;lackingCapacity &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">readReservations</span>&nbsp;_&nbsp;=&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">createReservation</span>&nbsp;_&nbsp;=&nbsp;<span style="color:navy;">failwith</span>&nbsp;<span style="color:#a31515;">&quot;Mock&nbsp;shouldn&#39;t&nbsp;be&nbsp;called.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;capacity&nbsp;<span style="color:navy;">readReservations</span>&nbsp;<span style="color:navy;">createReservation</span>&nbsp;reservation &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">None</span>&nbsp;=!&nbsp;actual</pre> </p> <p> (You can find these tests in <a href="https://github.com/ploeh/dependency-rejection-samples/commit/d2387cceb81eabc349a63ab7df1249236e9b1d13">commit d2387cceb81eabc349a63ab7df1249236e9b1d13 in the accompanying sample code repository</a>.) Contrast those dependency-injection style tests to these tests against the pure version of <code>tryAccept</code>: </p> <p> <pre>[&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``tryAccept&nbsp;behaves&nbsp;correctly&nbsp;when&nbsp;it&nbsp;can&nbsp;accept``</span> &nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:navy;">NonNegativeInt</span>&nbsp;excessCapacity)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Tuple2</span>.<span style="color:navy;">curry</span>&nbsp;<span style="color:navy;">id</span> &nbsp;&nbsp;&nbsp;&nbsp;&lt;!&gt;&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;&lt;*&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">listOf</span>&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;&nbsp;<span style="color:teal;">Arb</span>.<span style="color:navy;">fromGen</span>&nbsp;|&gt;&nbsp;<span style="color:teal;">Prop</span>.<span style="color:navy;">forAll</span>&nbsp;&lt;|&nbsp;<span style="color:blue;">fun</span>&nbsp;(reservation,&nbsp;reservations)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;capacity&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;excessCapacity &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;+&nbsp;(reservations&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;&nbsp;&nbsp;&nbsp;&nbsp;+&nbsp;reservation.Quantity &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;capacity&nbsp;reservations&nbsp;reservation &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">Some</span>&nbsp;{&nbsp;reservation&nbsp;<span style="color:blue;">with</span>&nbsp;IsAccepted&nbsp;=&nbsp;<span style="color:blue;">true</span>&nbsp;}&nbsp;=!&nbsp;actual [&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``tryAccept&nbsp;behaves&nbsp;correctly&nbsp;when&nbsp;it&nbsp;can&#39;t&nbsp;accept``</span> &nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:navy;">PositiveInt</span>&nbsp;lackingCapacity)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Tuple2</span>.<span style="color:navy;">curry</span>&nbsp;<span style="color:navy;">id</span> &nbsp;&nbsp;&nbsp;&nbsp;&lt;!&gt;&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;&lt;*&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">listOf</span>&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;&nbsp;<span style="color:teal;">Arb</span>.<span style="color:navy;">fromGen</span>&nbsp;|&gt;&nbsp;<span style="color:teal;">Prop</span>.<span style="color:navy;">forAll</span>&nbsp;&lt;|&nbsp;<span style="color:blue;">fun</span>&nbsp;(reservation,&nbsp;reservations)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;capacity&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(reservations&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;lackingCapacity &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;capacity&nbsp;reservations&nbsp;reservation &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">None</span>&nbsp;=!&nbsp;actual</pre> </p> <p> They're simpler, and since they don't use <a href="http://xunitpatterns.com/Mock%20Object.html">mocks</a>, they're more robust. They were easier to write, and I subscribe to the spirit of <a href="http://amzn.to/SM8Yv0">GOOS</a>: <em>if test are difficult to write, the system under test should be simplified</em>. </p> <div class="comment-date">2017-02-05 20:09 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>Hi Mark,</p> <p>Thanks for your talk at NDC last month, and for writing this series! I feel that the functional community (myself included) has a habit of using examples that aren't obviously relevant to the sort of line-of-business programming most of us do in our day jobs, so articles like this are sorely needed.</p> <p>We talked a little about this in person after your talk at the conference: I wanted to highlight a potential criticism of this style of programming. Namely, there's still some important business logic being carried out by your <code>tryAcceptComposition</code> function, like checking the capacity <i>on the requested reservation date</i>. How do you unit test that <code>readReservations</code> is called with the correct date? Likewise, how do you unit test that rejected reservations don't get saved? Real world business logic isn't always purely functional in nature. Sometimes the side effects that your code performs are part of the requirements.</p> <p>The Haskell philosophy isn't about rejecting side effects outright - it's about measuring and controlling them. I wouldn't write <code>tryAcceptComposition</code> using <code>IO</code>. Instead I'd program to the interface, not the implementation, using an mtl-style class to abstract over monads which support saving and loading reservations.</p> <pre><code>class Monad m =&gt; MonadReservation m where readReservations :: ConnectionString -&gt; Date -&gt; m [Reservation] createReservation :: ConnectionString -&gt; Reservation -&gt; m ReservationId tryAcceptComposition :: MonadReservation m =&gt; Reservation -&gt; m (Maybe ReservationId) tryAcceptComposition r = runMaybeT $ do reservations &lt;- lift $ readReservations connectionString (date r) accepted &lt;- MaybeT $ return $ tryAccept 10 reservations r lift $ createReservation connectionString accepted</code></pre> <p>Code that lives in a <code>MonadReservation</code> context can read and create reservations in the database but nothing else; it doesn't have all the power of <code>IO</code>. During unit testing I can use an instance of <code>MonadReservation</code> that returns canned values, and in production I can use a monad that actually talks to the database.</p> <p>Since type classes are syntactic sugar for passing an argument, this is really just a nicer way of writing your original DI-style code. I don't advocate the "free monad" style that's presently trendy in Scala-land because I find it unnecessarily complex. 90% of the purported advantages of free monads are already supported by simpler language features.</p> <p>I suppose the main downside of this design is that you can't express it in F#, at least not cleanly. It relies on type classes and higher-kinded types.</p> <p>Hope you find this interesting, I'd love to hear what you think!</p> <p>Benjamin</p> </div> <div class="comment-date">2017-02-06 16:28 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. The alternative you propose looks useful in Haskell, but, as you've already suggested, it doesn't translate well into F#. </p> <p> I write F# code professionally, whereas so far, I've only used Haskell to critique my F# code. (If someone who reads this comment would offer to pay me to write some Haskell code, please get in touch.) In other words, I still have much to learn about Haskell. I think I understand as much, however, that I'd be able to use your suggested design to unit test <code>tryAcceptComposition</code> using the <code>Identity</code> monad for Stubs, or perhaps <code>MonadWriter</code> or <code>MonadState</code> for Mocks. I'll have to try that one day... </p> <p> In F#, I write integration tests. Such tests are important regardless, and often they more closely relate to actual requirements, so I find this a worthwhile effort anyway. </p> </div> <div class="comment-date">2017-02-11 22:42 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://twitter.com/la_yumba">Enrico Buonanno</a></div> <div class="comment-content"> <p> Hi Mark, </p> <p> thanks for the post series, which I find interesting and needed. There is one part of your post that I find deserves further exploration. You write: <blockquote> 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. </blockquote> Firstly, I would say that you can write expression-based programs in any language that has expressions, which naturally includes C# and Java. But that's not particularly relevant to this discussion. </p> <p> More to the point, you're glossing over this as though it were a minor detail, when in fact I don't think it is. Let's explore the case in which "you may wish to defer a query, or base it on a decision inside the unit". The way you do this "by lazy evaluation" would be - I assume - by passing a function as an argument to your unit. But this is then effectively dependency injection, because you're passing in a function which has side effects, which will be called (or not) from the unit. </p> <p> So, it seems to me that your technique of extracting side effects out of the unit provides a good general guideline, but not a completely general way to replace dependency injection. </p> </div> <div class="comment-date">2017-02-16 11:47 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. There's a lot to unpack in that quote, which was one of the reasons I didn't expand it. It would have made the article too long, and wandered off compared to its main point. I don't mind going into these details here, though. </p> <p> <strong>Direction of data</strong> </p> <p> In order to get the obvious out of the way first, the issue you point out is with my refactoring of indirect input to direct input. Refactoring from indirect to output to direct output is, as far as I can tell, not on your agenda. Designing with direct input in mind seems uncontroversial to me, so that makes sense. </p> <p> <strong>No hard rules</strong> </p> <p> On this blog, I often write articles as I figure out how to deal with problems. Sometimes, I report on my discoveries at a time where I've yet to accumulate years of experience. What I've learned so far is that dependency injection isn't functional. What I'm <em>still</em> exploring is what to do instead. </p> <p> It's my experience that the type of refactoring I demonstrate here can surprisingly often be performed. I don't want to claim that it's always possible to do it like this. In fact, I'm still looking for good examples where this will not be possible. Whenever I think of a simple enough example that I could share it here, I always realise that if only I simplify the problem, I can put it into the shape seen here. </p> <p> My thinking is, however, constrained by my professional experience. I've been doing web (service) development for so many years now that it constraints my imagination. When you execution scope is exclusively a single HTTP request at a time, you tend to keep things simple. I'd welcome a simplified, but still concrete example where the impure/pure/impure sandwich described here isn't going to be possible. </p> <p> This may seem like a digression, but my point is that I don't claim to be the holder of a single, undeniable truth. Still, I find that this article describes a broadly applicable design and implementation technique. </p> <p> <strong>Language specifics</strong> </p> <p> The next topic we need to consider is our choice of language. When I wrote that deferred execution can always be done by lazy evaluation, that's exactly how Haskell works. Haskell is lazily evaluated, so any value passed as direct input can be unevaluated until required. That goes for <code>IO</code> as well, but then, as we've learned, you can't pass impure data to a pure function. </p> <p> All execution is, in that sense, deferred, unless explicitly forced. Thus, any potential need for deferred execution has no design implications. </p> <p> F#, on the other hand, is an eagerly evaluated language, so there, deferred execution may have design implications. </p> <p> <strong>Performance</strong> </p> <p> Perhaps it's my lack of imagination again, but I can't think of a well-designed system where deferred execution is required for purposes of correctness. As far as I can tell, deferred execution is a performance concern. You wish to defer execution of a query because that operation takes significant time. </p> <p> That's a real concern, but I often find that people worry too much about performance. Again, this is probably my lack of wider experience, as I realise that performance can be important in smart phone apps, games, and the like. Clearly, performance is also important in the world of REST APIs, but I've met a lot of people who worry about performance without ever measuring it. </p> <p> When you start measuring performance, you'll often be surprised to discover where your code spends actual time. So my design approach is always to prioritise making the system work first, and then, if there are performance problems, figure out how to tweak it so that it becomes satisfactory. In my experience, such tweaking is only necessary now and then. I'm not claiming that my code is the fastest it could be, but it's often fast enough, and as easy to maintain as I can make it. </p> <p> <strong>The need for data</strong> </p> <p> Another concern is the need for data. If you consider the above <code>tryAccept</code> function, it <em>always</em> uses <code>reservations</code>. Thus, there's no gain in deferring the database query, because you'll always need the data. </p> <p> Deferred execution is only required in those cases where you have conditional branching, and only in certain cases do you need to read a particular piece of data. </p> <p> Even conditional branching isn't enough of a criterion, though, because you could have branching where, in 99.9 % of the cases, you'd be performing the query anyway. Would you, then, need deferred execution for the remaining 0.1 % of the cases? </p> <p> <strong>Lazy sequences</strong> </p> <p> Still, let's assume that we've implemented a system using pure functions that take pure data, but to our dismay we discover that there's one query that takes time to execute, and that we truly only need it some of the time. In .NET, there are two distinct situations: <ul> <li>We need a scalar value</li> <li>We need a collection of values</li> </ul> If we need a collection of values, we only need to make a minuscule change to the design of our function. Instead of taking an F# list, or an array, as direct input, we can make the function take a sequence (<code>IEnumerable&lt;T&gt;</code> in C#) as input. These can be implemented as lazily evaluated sequences, which gives us the deferred execution we need. </p> <p> <strong>Lazy scalar values</strong> </p> <p> This leaves the corner case where we need a lazily evaluated scalar value. In such cases, I may have to make a concession to performance in my function design, but I wouldn't change the argument to a function, but rather to a <a href="https://docs.microsoft.com/en-us/dotnet/articles/fsharp/language-reference/lazy-computations">lazy</a> value. </p> <p> Lazy values are deferred, but memoised, which is the reason I'd prefer them over function arguments. </p> </div> <div class="comment-date">2017-02-18 19:54 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>. Partial application is dependency injection http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection 2017-01-30T12:40:00+00:00 Mark Seemann <div id="post"> <p> <em>The equivalent of dependency injection in F# is partial function application, but it isn't functional.</em> </p> <p> This is the second 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>. </p> <p> People often ask me how to do dependency injection in F#. That's only natural, since I wrote <a href="http://amzn.to/12p90MG">Dependency Injection in .NET</a> some years ago, and also since I've increasingly focused my energy on F# and other functional programming languages. </p> <p> Over the years, I've seen other F# experts respond to that question, and often, the answer is that partial function application is the F# way to do dependency injection. For some years, I believed that as well. It turns out to be true in one sense, but incorrect in another. Partial application <em>is</em> equivalent to dependency injection. It's just not a functional solution to dealing with dependencies. </p> <p> (To be as clear as I can be: I'm not claiming that partial application isn't functional. What I claim is that partial application used for dependency injection isn't functional.) </p> <p> <strong>Attempted dependency injection using functions</strong> </p> <p> Returning to the example from the <a href="http://blog.ploeh.dk/2017/01/27/dependency-injection-is-passing-an-argument">previous article</a>, you could try to rewrite <code>MaĆ®treD.TryAccept</code> as a function: </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> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;capacity&nbsp;<span style="color:navy;">readReservations</span>&nbsp;<span style="color:navy;">createReservation</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;<span style="color:navy;">createReservation</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> You could imagine that this <code>tryAccept</code> function is part of a module called <code>MaĆ®treD</code>, just to keep the examples as equivalent as possible. </p> <p> The function takes four arguments. The first is the capacity of the restaurant in question; a primitive integer. The next two arguments, <code>readReservations</code> and <code>createReservation</code> fill the role of the injected <code>IReservationsRepository</code> in the previous article. In the object-oriented example, the <code>TryAccept</code> method used two methods on the repository: <code>ReadReservations</code> and <code>Create</code>. Instead of using an interface, in the F# function, I make the function take two independent functions. They have (almost) the same types as their C# counterparts. </p> <p> The first three arguments correspond to the injected dependencies in the previous <code>MaĆ®treD</code> class. The fourth argument is a <code>Reservation</code> value, which corresponds to the input to the previous <code>TryAccept</code> method. </p> <p> Instead of returning a nullable integer, this F# version returns an <code>int option</code>. </p> <p> The implementation is also equivalent to the C# example: Read the relevant reservations from the database using the <code>readReservations</code> function argument, and sum over their quantities. Based on the number of already reserved seats, decide whether or not to accept the reservation. If you can accept the reservation, set <code>IsAccepted</code> to <code>true</code>, call the <code>createReservation</code> function argument, and pipe the returned ID (integer) to <code>Some</code>. If you can't accept the reservation, then return <code>None</code>. </p> <p> Notice that the first three arguments are 'dependencies', whereas the last argument is the 'actual input', if you will. This means that you can use partial function application to compose this function. </p> <p> <strong>Application</strong> </p> <p> If you recall the definition of the previous <code>IMaĆ®treD</code> interface, the <code>TryAccept</code> method was defined like this (C# code snippet): </p> <p> <pre><span style="color:blue;">int</span>?&nbsp;TryAccept(<span style="color:#2b91af;">Reservation</span>&nbsp;reservation);</pre> </p> <p> You could attempt to define a similar function with the type <code>Reservation -&gt; int option</code>. Normally, you'd want to do this closer to the boundary of the application, but the following example demonstrates how to 'inject' real database operations into the function. </p> <p> Imagine that you have a <code>DB</code> module with these functions: </p> <p> <pre><span style="color:blue;">module</span>&nbsp;<span style="color:teal;">DB</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;DateTimeOffset&nbsp;-&gt;&nbsp;Reservation&nbsp;list</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">readReservations</span>&nbsp;<span style="color:#9b9b9b;">connectionString</span>&nbsp;<span style="color:#9b9b9b;">date</span>&nbsp;=&nbsp;<span style="color:green;">//&nbsp;..</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;Reservation&nbsp;-&gt;&nbsp;int</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">createReservation</span>&nbsp;<span style="color:#9b9b9b;">connectionString</span>&nbsp;<span style="color:#9b9b9b;">reservation</span>&nbsp;=&nbsp;<span style="color:green;">//&nbsp;..</span></pre> </p> <p> The <code>readReservations</code> function takes a connection string and a date as arguments, and returns a list of reservations for that date. The <code>createReservation</code> function also takes a connection string, as well as a reservation. When invoked, it creates a new record for the reservation and returns the ID of the newly created row. (This sort of API violates CQS, so you should <a href="http://blog.ploeh.dk/2016/05/06/cqs-and-server-generated-entity-ids">consider alternatives</a>.) </p> <p> If you partially apply these functions with a valid connection string, both have the type desired for their roles in <code>tryAccept</code>. This means that you can create a function from these elements: </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;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">read</span>&nbsp;&nbsp;&nbsp;=&nbsp;<span style="color:teal;">DB</span>.<span style="color:navy;">readReservations</span>&nbsp;&nbsp;connectionString &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">create</span>&nbsp;=&nbsp;<span style="color:teal;">DB</span>.<span style="color:navy;">createReservation</span>&nbsp;connectionString &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;10&nbsp;<span style="color:navy;">read</span>&nbsp;<span style="color:navy;">create</span></pre> </p> <p> Notice how <code>tryAccept</code> itself is partially applied. Only the arguments corresponding to the C# dependencies are passed to it, so the return value is a function that 'waits' for the last argument: the reservation. As I've attempted to indicate by the code comment above the function, it has the desired type of <code>Reservation -&gt; int option</code>. </p> <p> <strong>Equivalence</strong> </p> <p> Partial application used like this is equivalent to dependency injection. To see how, consider the generated Intermediate Language (IL). </p> <p> F# is a .NET language, so it compiles to IL. You can decompile that IL to C# to get a sense of what's going on. If you do that with the above <code>tryAcceptComposition</code>, you get something like this: </p> <p> <pre><span style="color:blue;">internal</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">tryAcceptComposition@17&nbsp;:&nbsp;<span style="color:#2b91af;">FSharpFunc</span>&lt;<span style="color:#2b91af;">Reservation</span>,&nbsp;<span style="color:#2b91af;">FSharpOption</span>&lt;<span style="color:blue;">int</span>&gt;&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;capacity; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">FSharpFunc</span>&lt;<span style="color:#2b91af;">Reservation</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;createReservation; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">FSharpFunc</span>&lt;<span style="color:#2b91af;">DateTimeOffset</span>,&nbsp;<span style="color:#2b91af;">FSharpList</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&gt;&nbsp;readReservations; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">internal</span>&nbsp;tryAcceptComposition@17( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>&nbsp;capacity, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">FSharpFunc</span>&lt;<span style="color:#2b91af;">DateTimeOffset</span>,&nbsp;<span style="color:#2b91af;">FSharpList</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&gt;&nbsp;readReservations, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">FSharpFunc</span>&lt;<span style="color:#2b91af;">Reservation</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;createReservation) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.capacity&nbsp;=&nbsp;capacity; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.readReservations&nbsp;=&nbsp;readReservations; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.createReservation&nbsp;=&nbsp;createReservation; &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:#2b91af;">FSharpOption</span>&lt;<span style="color:blue;">int</span>&gt;&nbsp;Invoke(<span style="color:#2b91af;">Reservation</span>&nbsp;reservation) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#2b91af;">MaĆ®treD</span>.tryAccept&lt;<span style="color:blue;">int</span>&gt;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.capacity,&nbsp;<span style="color:blue;">this</span>.readReservations,&nbsp;<span style="color:blue;">this</span>.createReservation,&nbsp;reservation); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> I've cleaned it up a bit, mostly by removing all attributes from the various elements. Notice how this is a class, with class fields, and a constructor that takes values for the fields and assigns them. <em>It's constructor injection!</em> </p> <p> Partial application is dependency injection. </p> <p> It compiles, works as expected, but is it functional? </p> <p> <strong>Evaluation</strong> </p> <p> People sometimes ask me: <em>How do I know whether my F# code is functional?</em> </p> <p> I sometimes wonder about that myself, but unfortunately, as nice a language as F# is, it doesn't offer much help in that regard. Its emphasis is on functional programming, but it allows mutation, object-oriented programming, and even procedural programming. It's a friendly and forgiving language. (This also makes it a great 'beginner' functional language, because you can learn functional concepts piecemeal.) </p> <p> Haskell, on the other hand, is a strictly functional language. In Haskell, you can only write your code in the functional way. </p> <p> Fortunately, F# and Haskell are similar enough that it's easy to port F# code to Haskell, as long as the F# code already is 'sufficiently functional'. In order to evaluate if my F# code is properly functional, I sometimes port it to Haskell. If I can get it to compile and run in Haskell, I take that as confirmation that my code is functional. </p> <p> I've <a href="http://blog.ploeh.dk/2016/03/18/functional-architecture-is-ports-and-adapters">previously shown an example similar to this one</a>, but I'll repeat the experiment here. Will porting <code>tryAccept</code> and <code>tryAcceptComposition</code> to Haskell work? </p> <p> It's easy to port <code>tryAccept</code>: </p> <p> <pre><span style="color:#600277;">tryAccept</span>&nbsp;::&nbsp;Int&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;(<span style="color:blue;">ZonedTime</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;[<span style="color:blue;">Reservation</span>])&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;(<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Int)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">Maybe</span>&nbsp;<span style="color:#dd0000;">Int</span> tryAccept&nbsp;capacity&nbsp;readReservations&nbsp;createReservation&nbsp;reservation&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;<span style="color:#666666;">=</span>&nbsp;sum&nbsp;<span style="color:#666666;">$</span>&nbsp;map&nbsp;quantity&nbsp;<span style="color:#666666;">$</span>&nbsp;readReservations&nbsp;<span style="color:#666666;">$</span>&nbsp;date&nbsp;reservation &nbsp;&nbsp;<span style="color:blue;">in</span>&nbsp;&nbsp;<span style="color:#af00db;">if</span>&nbsp;reservedSeats&nbsp;<span style="color:#666666;">+</span>&nbsp;quantity&nbsp;reservation&nbsp;<span style="color:#666666;">&lt;=</span>&nbsp;capacity &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#af00db;">then</span>&nbsp;Just&nbsp;<span style="color:#666666;">$</span>&nbsp;createReservation&nbsp;<span style="color:#666666;">$</span>&nbsp;reservation&nbsp;{&nbsp;isAccepted&nbsp;<span style="color:#666666;">=</span>&nbsp;True&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#af00db;">else</span>&nbsp;Nothing</pre> </p> <p> Clearly, there are differences, but I'm sure that you can also see the similarities. The most important feature of this function is that it's <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a>. All Haskell functions are pure by default, unless explicitly declared to be impure, and that's not the case here. This function is pure, and so are both <code>readReservations</code> and <code>createReservation</code>. </p> <p> The Haskell version of <code>tryAccept</code> compiles, but what about <code>tryAcceptComposition</code>? </p> <p> Like the F# code, the experiment is to see if it's possible to 'inject' functions that actually operate against a database. Equivalent to the F# example, imagine that you have this <code>DB</code> module: </p> <p> <pre><span style="color:#600277;">readReservations</span>&nbsp;::&nbsp;<span style="color:blue;">ConnectionString</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ZonedTime</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;IO&nbsp;[<span style="color:blue;">Reservation</span>] readReservations&nbsp;connectionString&nbsp;date&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:green;">--&nbsp;.. </span> <span style="color:#600277;">createReservation</span>&nbsp;::&nbsp;<span style="color:blue;">ConnectionString</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;IO&nbsp;Int createReservation&nbsp;connectionString&nbsp;reservation&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:green;">--&nbsp;..</span></pre> </p> <p> Database operations are, by definition, impure, and Haskell admirably models that with the type system. Notice how both functions return <code>IO</code> values. </p> <p> If you partially apply both functions with a valid connection string, the <code>IO</code> context remains. The type of <code>DB.readReservations connectionString</code> is <code>ZonedTime -&gt; IO [Reservation]</code>, and the type of <code>DB.createReservation connectionString</code> is <code>Reservation -&gt; IO Int</code>. You can try to pass them to <code>tryAccept</code>, but the types don't match: </p> <p> <pre><span style="color:#600277;">tryAcceptComposition</span>&nbsp;::&nbsp;<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;IO&nbsp;(Maybe&nbsp;Int) tryAcceptComposition&nbsp;reservation&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;read&nbsp;&nbsp;&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">DB</span><span style="color:#666666;">.</span>readReservations&nbsp;&nbsp;connectionString &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;create&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">DB</span><span style="color:#666666;">.</span>createReservation&nbsp;connectionString &nbsp;&nbsp;<span style="color:blue;">in</span>&nbsp;tryAccept&nbsp;<span style="color:#09885a;">10</span>&nbsp;read&nbsp;create&nbsp;reservation</pre> </p> <p> <em>This doesn't compile.</em> </p> <p> It doesn't compile, because the database operations are impure, and <code>tryAccept</code> wants pure functions. </p> <p> In short, partial application used for dependency injection isn't functional. </p> <p> <strong>Summary</strong> </p> <p> Partial application in F# can be used to achieve a result equivalent to dependency injection. It compiles and works as expected, but it's not functional. The reason it's not functional is that (most) dependencies are, by their very nature, impure. They're either non-deterministic, have side-effects, or both, and that's often the underlying reason that they are factored into dependencies in the first place. </p> <p> Pure functions, however, can't call impure functions. If they could, they would become impure themselves. This rule is enforced by Haskell, but not by F#. </p> <p> When you inject impure operations into an F# function, that function becomes impure as well. Dependency injection makes everything impure, which explains why it isn't functional. </p> <p> Functional programming solves the problem of decoupling (side) effects from program logic another way. That's the topic of the next article. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/02/02/dependency-rejection">Dependency rejection</a>. </p> </div> <div id="comments"> <hr /> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author">Kurren Nischal</div> <div class="comment-content"> A very useful read as always.<br /> A couple of questions: If you're porting your code from F# to Haskell and back into F#, why not just use Haskell in the first place? <br/> Also, why would you want to mark a function as having side effects in the first place? <br/> Thanks </div> <div class="comment-date">2017-07-17 14:10 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> Kurren, thank you for writing. Why not use Haskell in the first place? In some situations, if that's an option, I'd go for it. In most of my professional work, however, it's not. A bit of background is required, I think. I've spent most of my professional career working with Microsoft technologies. Most of my clients use .NET. The majority of my clients use C#, but some are interested in adopting functional programming. F# is a great bridge to functional programming, because it integrates so well with existing C# code. </p> <p> Perhaps most importantly is that while these organisations learn F# as a new programming language, and a new paradigm, all other dimensions of software development remain the same. You can use familiar libraries and frameworks, you can use the same Continuous Integration and build tools as you've been used to, you can deploy like you always do, and you can operate and monitor your software like before. </p> <p> If you start using Haskell, not only will developers have to learn an entire new ecosystem, but if you have a separate operations team, they would have be on board with that as well. </p> <p> If you can't get the entire organisation to accept Haskell-based software, then F# is a great choice for a .NET shop. Developers will obviously know the difference, but the rest of the organisation can be oblivious to the choice of language. </p> <p> When it comes to side-effects, that's one of the main motivations behind pure code in the first place. A major source of bugs is that often, programs have unintended side-effects. It's easy to introduce defects in a code base when side-effects are uncontrolled. That's the case for languages like C# and Java, and, unfortunately, F# as well. When you look at a method or function, there's no easy way to determine whether it has side-effects. In other words: all methods or functions could have side effects. (Also: all methods could return null.) </p> <p> This slows you down when you work on an existing code base, because there's only one way to determine if side-effects or non-deterministic behaviour are part of the code you're about to call: you have to <em>read it all</em>. </p> <p> On the other hand, if you can tell, just by looking at a function's type, whether or not it has side-effects, you can save yourself a lot of time. By definition, all the pure functions have no side-effect. You don't need to read the code in order to detect that. </p> <p> In Haskell, this is guaranteed. In F#, you can design your system that way, but some discipline is required in order to uphold such a guarantee. </p> </div> <div class="comment-date">2017-07-18 09:31 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 injection is passing an argument http://blog.ploeh.dk/2017/01/27/dependency-injection-is-passing-an-argument 2017-01-27T09:27:00+00:00 Mark Seemann <div id="post"> <p> <em>Is dependency injection really just passing an argument? A brief review.</em> </p> <p> This is the first 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>. </p> <p> In a talk at the 2012 Northeast Scala Symposium, <a href="https://t.co/oD1oQYZwbz">RĆŗnar Bjarnason casually remarked</a> that dependency injection is "really just a pretentious way to say 'taking an argument'". Given that I've written a 500+ pages <a href="http://amzn.to/12p90MG">book about dependency injection</a>, you might expect me to disagree with that. Yet, there's some truth to that statement, although it's not quite as simple as that. </p> <p> In this article, I'll show you some simple examples and explain why, on the one hand, RĆŗnar Bjarnason is right, but also, on the other hand, why there's a bit more to it. </p> <p> <strong>Restaurant reservation example</strong> </p> <p> Like the other articles in this series, the example scenario is on-line restaurant reservation. Imagine that you've been asked to develop an HTTP-based API that accepts JSON documents containing restaurant reservations. Furthermore, assume that you're using ASP.NET Web API with C# for the job, and that you're aspiring to use <a href="http://amzn.to/WBCwx7">domain-driven design</a>. </p> <p> In order to handle the incoming POST request, you could write an action method like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IHttpActionResult</span>&nbsp;Post(<span style="color:#2b91af;">ReservationRequestDto</span>&nbsp;dto) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;validationMsg&nbsp;=&nbsp;validator.Validate(dto); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(validationMsg&nbsp;!=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.BadRequest(validationMsg); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;r&nbsp;=&nbsp;mapper.Map(dto); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;id&nbsp;=&nbsp;maĆ®treD.TryAccept(r); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(id&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.StatusCode(<span style="color:#2b91af;">HttpStatusCode</span>.Forbidden); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.Ok(); }</pre> </p> <p> This method follows a simple and familiar path: validate input, map to a domain model, delegate to said model, examine posterior state, and return a result. </p> <p> You may have noticed, though, that this method doesn't do all the work itself. It delegates some of the work to collaborators: <code>validator</code>, <code>mapper</code>, and <code>maĆ®treD</code>. Where do these collaborators come from? </p> <p> They are <em>dependencies</em>. Could you make the <code>Post</code> method take them as arguments? </p> <p> Unfortunately, you can't. The <code>Post</code> method constitutes part of the boundary of the HTTP API. ASP NET Web API routes and dispatches incoming HTTP requests by convention, and <em>action methods</em> must follow that convention. You can't just make the function take any argument you'd like, so you have to find another place to pass those dependencies to the object. </p> <p> The second-best option (after the <code>Post</code> method itself) is via the constructor: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;ReservationsController( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IValidator</span>&nbsp;validator, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IMapper</span>&nbsp;mapper, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IMaĆ®treD</span>&nbsp;maĆ®treD) {&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.validator&nbsp;=&nbsp;validator; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.mapper&nbsp;=&nbsp;mapper; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.maĆ®treD&nbsp;=&nbsp;maĆ®treD; }</pre> </p> <p> This is the application of a design pattern called <em>constructor injection</em>. It captures the dependencies in class fields, making them available for members (like <code>Post</code>) of the class. </p> <p> This turns out to be a regular pattern. </p> <p> <strong>Turtles all the way down</strong> </p> <p> You could argue that the <code>Post</code> method is a special case, since it's part of the boundary of the system, and therefore must adhere to specific rules. On the other hand, these rule don't apply deeper in the implementation, so could you implement other objects by simply passing in dependencies as arguments? </p> <p> Consider, as an example, the implementation of <code>IMaĆ®treD.TryAccept</code>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>?&nbsp;TryAccept(<span style="color:#2b91af;">Reservation</span>&nbsp;reservation) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;reservedSeats&nbsp;=&nbsp;reservationsRepository &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.ReadReservations(reservation.Date) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Sum(r&nbsp;=&gt;&nbsp;r.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;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservation.IsAccepted&nbsp;=&nbsp;<span style="color:blue;">true</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;reservationsRepository.Create(reservation); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">null</span>; }</pre> </p> <p> This method has another collaborator: <code>reservationsRepository</code>. It's another dependency. Where does it come from? </p> <p> Could you make the <code>TryAccept</code> method take <code>reservationsRepository</code> as an argument? </p> <p> Unfortunately, that's not possible either, because the method is defined by the <code>IMaĆ®treD</code> interface: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IMaĆ®treD</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>?&nbsp;TryAccept(<span style="color:#2b91af;">Reservation</span>&nbsp;reservation); }</pre> </p> <p> You may recall that the above <code>Post</code> method is programmed against the <code>IMaĆ®treD</code> interface, and not the concrete class. It'd be a leaky abstraction to add <code>IReservationsRepository</code> as an argument to <code>IMaĆ®treD.TryAccept</code>, because not all implementations of the interface may need that dependency. Or perhaps another implementation has another dependency. Should we add that to the parameter list of <code>IMaĆ®treD.TryAccept</code>as well? </p> <p> Surely, that's not a tenable design principle. On the other hand, by using constructor injection, you can decouple implementation details from your abstractions: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;MaĆ®treD(<span style="color:blue;">int</span>&nbsp;capacity,&nbsp;<span style="color:#2b91af;">IReservationsRepository</span>&nbsp;reservationsRepository) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.capacity&nbsp;=&nbsp;capacity; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.reservationsRepository&nbsp;=&nbsp;reservationsRepository; }</pre> </p> <p> This constructor not only takes an <code>IReservationsRepository</code> object, but also an integer that represents the capacity of the restaurant in question. This demonstrates that <a href="http://blog.ploeh.dk/2012/07/02/PrimitiveDependencies">dependencies can also be primitive values</a>. </p> <p> <strong>Summary</strong> </p> <p> Dependency injection is, in a sense, only a specific way for objects to take arguments. Often, however, objects have roles defined by the the interfaces they implement. Such objects may need collaborators that are not available via the APIs defined by these interfaces, so you'll have to supply dependencies via members that belong to the concrete class in question. Passing dependencies via a class' constructor is the best way to do that. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection">Partial application is dependency injection</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>. From dependency injection to dependency rejection http://blog.ploeh.dk/2017/01/27/from-dependency-injection-to-dependency-rejection 2017-01-27T07:55:00+00:00 Mark Seemann <div id="post"> <p> <em>The problem typically solved by dependency injection in object-oriented programming is solved in a completely different way in functional programming.</em> </p> <p> Several years ago, I wrote a book called <a href="http://amzn.to/12p90MG">Dependency Injection in .NET</a>, which was published in 2011. The book contains examples in C#, but since then I've increasingly become interested in functional programming to the extend that I now consider F# my primary language. </p> <p> With that combination, it's no wonder that people often ask me how to do dependency injection in functional programming. </p> <p> I've seen more than one answer, from other people, explaining how partial function application is equivalent to dependency injection. In a small series of articles, I'll explain both why this is true, but also why it's <em>not functional</em>. I'll conclude by showing a functional alternative to decoupling logic and (side) effects. </p> <p> <img src="/content/binary/dependency-injection-in-scala-comic.jpg" alt="Bob: How do I do dependency injection in Scala? Other man: You don't, because Scala is a functional language. Bob: Fine, it's functional. How do I inject dependencies? Other man: You use a free monad which allows you to build a monad from any Functor. Bob: Did you just tell me to go fuck myself? Other man: I believe I did, Bob."> </p> <p> (<a href="https://twitter.com/hmemcpy/status/771359835514368000">Comic</a> courtesy of <a href="http://thinkdifferent.ly">John Muellerleile</a> and <a href="http://hmemcpy.com">Igal Tabachnik</a>.) </p> <p> There's another school of functional programmers who believe that dependency injection in functional programming involves a Free monad. </p> <p> You can often make do with less, though. </p> <p> In my experience, it's usually enough to refactor a unit to take only direct input and output, and then compose an impure/pure/impure 'sandwich'. You'll see an example later. </p> <p> This article series contains the following parts: <ol> <li><a href="http://blog.ploeh.dk/2017/01/27/dependency-injection-is-passing-an-argument">Dependency injection is passing an argument</a></li> <li><a href="http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection">Partial application is dependency injection</a></li> <li><a href="http://blog.ploeh.dk/2017/02/02/dependency-rejection">Dependency rejection</a></li> <li><a href="http://blog.ploeh.dk/2017/07/10/pure-interactions">Pure interactions</a></li> </ol> The first three articles revolve around a common example, which is one of my favourite scenarios: on-line restaurant reservation. You can see an actual example client in my <a href="http://www.shareasale.com/r.cfm?u=1017843&b=611266&m=53701&afftrack=&urllink=pluralsight%2Ecom%2Fcourses%2Ffunctional%2Darchitecture%2Dfsharp">Functional Architecture with F#</a> Pluralsight course. The (somewhat dated) client source code is <a href="https://github.com/ploeh/booking-web-ui">available on GitHub</a>. The server-side F# and Haskell example code for this article series is <a href="https://github.com/ploeh/dependency-rejection-samples">available on GitHub</a>. </p> <p> The scenario is to implement an HTTP-based API that can accept incoming JSON documents that represent restaurant reservations. </p> <p> The fourth article on <em>pure interactions</em> is a gateway to another article series on free monads. </p> <p> I should point out that nowhere in this article series do I reject dependency injection as a set of object-oriented patterns. In object-oriented programming, dependency injection is a well-known and comprehensively described way to achieve decoupling and testability. In the next article, you'll see a brief review of dependency injection in C#. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/01/27/dependency-injection-is-passing-an-argument">Dependency injection is passing an argument</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>. Decoupling application errors from domain models http://blog.ploeh.dk/2017/01/03/decoupling-application-errors-from-domain-models 2017-01-03T12:26:00+00:00 Mark Seemann <div id="post"> <p> <em>How to prevent application-specific error cases from infecting your domain models.</em> </p> <p> Functional error-handling is often done with the Either monad. If all is good, the <em>right</em> case is returned, but if things go wrong, you'll want to return a value that indicates the error. In an application, you'll often need to be able to distinguish between different kinds of errors. </p> <p> <strong>From application errors to HTTP responses</strong> </p> <p> When an application encounters an error, it should respond appropriately. A GUI-based application should inform the user about the error, a batch job should log it, and a <a href="https://en.wikipedia.org/wiki/Representational_state_transfer">REST</a> API should return the appropriate HTTP status code. </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> In my <a href="http://bit.ly/tddwithfsharp">Test-Driven Development with F#</a> Pluralsight course (a <a href="http://www.infoq.com/presentations/mock-fsharp-tdd">free, condensed version is also available</a>), I demonstrate how to handle various error cases in a Controller class: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">ReservationsController</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;(dtr&nbsp;:&nbsp;<span style="color:teal;">ReservationDtr</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;dtr&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationError</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;">CapacityExceeded</span>&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">StatusCode</span>&nbsp;<span style="color:teal;">HttpStatusCode</span>.Forbidden&nbsp;:&gt;&nbsp;_ &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;_</pre> </p> <p> The injected <code>imp</code> function is a complete, composed, vertical feature implementation that performs both input validation, business logic, and data access. If input validation fails, it'll return <code>Failure (ValidationError msg)</code>, and that value is translated to a <code>400 Bad Request</code> response. Likewise, if the business logic returns <code>Failure CapacityExceeded</code>, the response becomes <code>403 Forbidden</code>, and a success is returned as <code>200 OK</code>. </p> <p> Both <code>ValidationError</code> and <code>CapacityExceeded</code> are cases of an <code>Error</code> type. This is only a simple example, so these are the only cases defined by that type: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">Error</span>&nbsp;= |&nbsp;<span style="color:navy;">ValidationError</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span> |&nbsp;<span style="color:navy;">CapacityExceeded</span></pre> </p> <p> This seems reasonable, but there's a problem. </p> <p> <strong>Error infection</strong> </p> <p> In F#, a function can't use a type unless that type is already defined. This is a problem because the <code>Error</code> type defined above mixes different concerns. If you seek to <a href="http://fsharpforfunandprofit.com/posts/designing-with-types-making-illegal-states-unrepresentable">make illegal states unrepresentable</a>, it follows that validation is not a concern in your domain model. Validation is still important at the boundary of an application, so you can't just ignore it. The <code>ValidationError</code> case relates to the application boundary, while <code>CapacityExceeded</code> relates to the domain model. </p> <p> Still, when implementing your domain model, you may want to return a <code>CapacityExceeded</code> value from time to time: </p> <p> <pre><span style="color:green;">//&nbsp;int&nbsp;-&gt;&nbsp;int&nbsp;-&gt;&nbsp;Reservation&nbsp;-&gt;&nbsp;Result&lt;Reservation,Error&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">checkCapacity</span>&nbsp;capacity&nbsp;reservedSeats&nbsp;reservation&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;capacity&nbsp;&lt;&nbsp;reservation.Quantity&nbsp;+&nbsp;reservedSeats &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">CapacityExceeded</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:navy;">Success</span>&nbsp;reservation</pre> </p> <p> Notice how the return type of this function is <code>Result&lt;Reservation,Error&gt;</code>. In order to be able to implement your domain model, you've now pulled in the <code>Error</code> type, which also defines the <code>ValidationError</code> case. Your domain model is now polluted by an application boundary concern. </p> <p> I think many developers would consider this trivial, but in my experience, failure to manage dependencies is the dominant reason for <a href="https://en.wikipedia.org/wiki/Software_rot">code rot</a>. It makes the code less general, and less reusable, because it's now coupled to something that may not fit into a different context. </p> <p> Particularly, the situation in the example looks like this: </p> <p> <img src="/content/binary/error-infection-dependency-diagram.png" alt="Dependency diagram"> </p> <p> Boundary and data access modules depend on the domain model, <a href="http://blog.ploeh.dk/2013/12/03/layers-onions-ports-adapters-its-all-the-same">as they should</a>, but everything depends on the <code>Error</code> type. This is wrong. Modules or libraries should be able to define their own error types. </p> <p> The <code>Error</code> type belongs in the <a href="http://blog.ploeh.dk/2011/07/28/CompositionRoot">Composition Root</a>, but it's impossible to put it there because F# prevents circular dependencies (a <a href="http://blog.ploeh.dk/2015/04/13/less-is-more-language-features">treasured language feature</a>). </p> <p> Fortunately, the fix is straightforward. </p> <p> <strong>Mapped Either values</strong> </p> <p> A domain model should be self-contained. As Robert C. Martin puts it in <a href="http://amzn.to/19W4JHk">APPP</a>: <blockquote> Abstractions should not depend upon details. Details should depend upon abstractions. </blockquote> Your domain model is an abstraction of the real world (that's why it's called a <em>model</em>), and is the reason you're developing a piece of software in the first place. So start with the domain model: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">BookingError</span>&nbsp;=&nbsp;<span style="color:navy;">CapacityExceeded</span> <span style="color:green;">//&nbsp;int&nbsp;-&gt;&nbsp;int&nbsp;-&gt;&nbsp;Reservation&nbsp;-&gt;&nbsp;Result&lt;Reservation,BookingError&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">checkCapacity</span>&nbsp;capacity&nbsp;reservedSeats&nbsp;reservation&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;capacity&nbsp;&lt;&nbsp;reservation.Quantity&nbsp;+&nbsp;reservedSeats &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">CapacityExceeded</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:navy;">Success</span>&nbsp;reservation</pre> </p> <p> In this example, there's only a single type of domain error (<code>CapacityExceeded</code>), but that's mostly because this is an example. Real production code could define a domain error union with several cases. The crux of the matter is that <code>BookingError</code> isn't infected with irrelevant implementation details like validation error types. </p> <p> You're still going to need an exhaustive discriminated union to model all possible error cases for your particular application, but that type belongs in the Composition Root. Accordingly, you also need a way to return validation errors in your validation module. Often, a <code>string</code> is all you need: </p> <p> <pre><span style="color:green;">//&nbsp;ReservationDtr&nbsp;-&gt;&nbsp;Result&lt;Reservation,string&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">validateReservation</span>&nbsp;(dtr&nbsp;:&nbsp;<span style="color:teal;">ReservationDtr</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;dtr.Date&nbsp;|&gt;&nbsp;<span style="color:teal;">DateTimeOffset</span>.<span style="color:navy;">TryParse</span>&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;(<span style="color:blue;">true</span>,&nbsp;date)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Success</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Reservation</span>.Date&nbsp;=&nbsp;date &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Name&nbsp;=&nbsp;dtr.Name &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Email&nbsp;=&nbsp;dtr.Email &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;dtr.Quantity&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:#a31515;">&quot;Invalid&nbsp;date.&quot;</span></pre> </p> <p> The <code>validateReservation</code> function returns a <code>Reservation</code> value when validation succeeds, and a simple <code>string</code> with an error message if it fails. </p> <p> You could, conceivably, return <code>string</code> values for errors from many different places in your code, so you're going to map them into an appropriate error case that makes sense in your application. </p> <p> In this particular example, the Controller shown above should still look like this: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">Error</span>&nbsp;= |&nbsp;<span style="color:navy;">ValidationError</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span> |&nbsp;<span style="color:navy;">DomainError</span> <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">ReservationsController</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;(dtr&nbsp;:&nbsp;<span style="color:teal;">ReservationDtr</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;dtr&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationError</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;">DomainError</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">StatusCode</span>&nbsp;<span style="color:teal;">HttpStatusCode</span>.Forbidden&nbsp;:&gt;&nbsp;_ &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;_</pre> </p> <p> Notice how similar this is to the initial example. The important difference, however, is that <code>Error</code> is defined in the same module that also implements <code>ReservationsController</code>. This is part of the composition of the specific application. </p> <p> In order to make that work, you're going to need to map from one failure type to another. This is trivial to do with an extra function belonging to your Result (or Either) module: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;Result&lt;&#39;c,&#39;a&gt;&nbsp;-&gt;&nbsp;Result&lt;&#39;c,&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">mapFailure</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;x&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;succ&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Success</span>&nbsp;succ &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;fail&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">f</span>&nbsp;fail)</pre> </p> <p> This function takes any <code>Result</code> value and maps the failure case instead of the success case. It enables you to transform e.g. a <code>BookingError</code> into a <code>DomainError</code>: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;candidate&nbsp;=&nbsp;<span style="color:blue;">either</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;r&nbsp;=&nbsp;<span style="color:navy;">validateReservation</span>&nbsp;candidate&nbsp;|&gt;&nbsp;<span style="color:navy;">mapFailure</span>&nbsp;<span style="color:navy;">ValidationError</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;&nbsp;i&nbsp;=&nbsp;<span style="color:teal;">SqlGateway</span>.<span style="color:navy;">getReservedSeats</span>&nbsp;connectionString&nbsp;r.Date &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;r&nbsp;=&nbsp;<span style="color:navy;">checkCapacity</span>&nbsp;10&nbsp;i&nbsp;r&nbsp;|&gt;&nbsp;<span style="color:navy;">mapFailure</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">DomainError</span>) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:teal;">SqlGateway</span>.<span style="color:navy;">saveReservation</span>&nbsp;connectionString&nbsp;r&nbsp;}</pre> </p> <p> This composition is a variation of the composition I've <a href="http://blog.ploeh.dk/2016/03/21/composition-with-an-either-computation-expression">previously published</a>. The only difference is that the error cases are now mapped into the application-specific <code>Error</code> type. </p> <p> <strong>Conclusion</strong> </p> <p> Errors can occur in diverse places in your code base: when validating input, when making business decisions, when writing to, or reading from, databases, and so on. </p> <p> When you use the Either monad for error handling, in a strongly typed language like F#, you'll need to define a discriminated union that models all the error cases you care about in the specific application. You can map module-specific error types into such a comprehensive error type using a function like <code>mapFailure</code>. In Haskell, it would be the <code>first</code> function of the <code>Bifunctor</code> typeclass, so this is a well-known function. </p> </div> <div id="comments"> <hr> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="https://github.com/wortho">David Worthington</a></div> <div class="comment-content"> <p> Mark, </p> <p> Why is it a problem to use <code>HttpStatusCode</code> in the domain model. They appear to be a standard way of categorizing errors. </p> </div> <div class="comment-date">2017-02-07 13:37 UTC</div> </div> <div class="comment"> <div class="comment-author"> <a href="http://blog.ploeh.dk">Mark Seemann</a> </div> <div class="comment-content"> </div> <p> David, thank you for writing. The answer depends on your goals and definition of <em>domain model</em>. </p> <p> I usually think of domain models in terms of separation of concerns. The purpose of a domain model is to model the business logic, and as Martin Fowler writes in <a href="http://bit.ly/patternsofeaa">PoEAA</a> about the Domain Model pattern, "you'll want the minimum of coupling from the <em>Domain Model</em> to other layers in the system. You'll notice that a guiding force of many layering patterns is to keep as few dependencies as possible between the domain model and the other parts of the system." </p> <p> In other words, you're separating the concern of implementing the business rules from the concerns of being able to save data in a database, render it on a screen, send emails, and so on. While also important, these are separate concerns, and I want to be able to vary those independently. </p> <p> People often hear statements like that as though I want to reserve myself the right to replace my SQL Server database with Neo4J (more on that later, though!). That's actually not my main goal, but I find that if concerns are mixed, <em>all</em> change becomes harder. It becomes more difficult to change how data is saved in a database, <em>and</em> it becomes harder to change business rules. </p> <p> The Dependency Inversion Principle tries to address such problems by advising that abstractions shouldn't depend on implementation details, but instead, implementation details should depend on abstractions. </p> <p> This is where the goals come in. I find Robert C. Martin's definition of software architecture helpful. Paraphrased from memory, he defines a software architect's role as enabling change; not predicting change, but making sure that when change has to happen, it's as economical as possible. </p> <p> As an architect, one of the heuristics I use is that I try to imagine how easily I can replace one component with another. It's not that I really believe that I may have to replace the SQL Server database with Neo4J, but thinking about how hard it would be gives me some insights about how to structure a software solution. </p> <p> I also imagine what it'd be like to port an application to another environment. Can I port my web site's business rules to a batch job? Can I port my desktop client to a smart phone app? Again, it's not that I necessarily predict that I'll have to do this, but it tells me something about the degrees of freedom offered by the architecture. </p> <p> If not explicitly addressed, the opposite of freedom tends to happen. In <a href="http://amzn.to/19W4JHk">APPP</a>, Robert C. Martin describes a number of design smells, one of them <em>Immobility</em>: "A design is immobile when it contains parts that could be useful in other systems, but the effort and risk involved with separating those parts from the original system are too great. This is an unfortunate, but very common occurrence." </p> <p> Almost as side-effect, an immobile system is difficult to test. A unit test is a different environment than the intended environment. Well-architected systems are easy to unit test. </p> <p> HTTP is a communications protocol. Its purpose is to enable exchange of information over networks. While it does that well, it's specifically concerned with that purpose. This includes HTTP status code. </p> <p> If you use the heuristic of imagining that you'd have to move the heart of your application to a batch job, status codes like <code>301 Moved Permanently</code>, <code>404 Not Found</code>, or <code>405 Method Not Allowed</code> make little sense. </p> <p> Using HTTP status codes in a domain model couples the model to a particular environment, at least conceptually. It has little to do with the <em>ubiquitous language</em> that Eric Evans discusses in <a href="http://amzn.to/WBCwx7">DDD</a>. </p> <div class="comment-date">2017-02-07 17:08 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 REST to algebraic data http://blog.ploeh.dk/2016/12/16/from-rest-to-algebraic-data 2016-12-16T07:23:00+00:00 Mark Seemann <div id="post"> <p> <em>Mapping RESTful HTTP requests to values of algebraic data types is easy.</em> </p> <p> In previous articles, you've seen <a href="http://blog.ploeh.dk/2016/11/28/easy-domain-modelling-with-types">how to easily model a simple domain model with algebraic data types</a>, and <a href="http://blog.ploeh.dk/2016/12/07/domain-modelling-with-rest">how to use RESTful API design to surface such a model at the boundary of an application</a>. In this article, you'll see how trivial it is to map incoming HTTP requests back to values of <a href="https://en.wikipedia.org/wiki/Algebraic_data_type">algebraic data types</a>. </p> <p> The advantage of <a href="https://en.wikipedia.org/wiki/Representational_state_transfer">REST</a> is that you can make illegal states unrepresentable. Clients follow links, and while clients are supposed to treat links as opaque values, URLs still contain information your API can use. </p> <p> <strong>Routing and dispatching</strong> </p> <p> Continuing where the <a href="http://blog.ploeh.dk/2016/12/07/domain-modelling-with-rest">previous article</a> left off, clients can issue POST requests against a URL like <code>https://example.com/credit-card</code>. On the server, a well-known piece of code handles such requests. (In the example code base I've used so far, I've been using ASP.NET Web API, so the code that handles such a request is a Controller.) Since you know that URLs like that are always routed to that particular piece of code, you can create a new <code>PaymentType</code> value that specifically represents an individual payment with a credit card: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;paymentType&nbsp;=&nbsp;<span style="color:navy;">Individual</span>&nbsp;{&nbsp;Name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;credit-card&quot;</span>;&nbsp;Action&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Pay&quot;</span>&nbsp;}</pre> </p> <p> If, on the other hand, the client is using a provided link to POST a representation against the URL <code>https://example.com/recurrent/start/credit-card</code>, your server-side dispatcher will route the request to a different handler (Controller), in which case you can create a <code>PaymentType</code> value like this: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;paymentType&nbsp;=&nbsp;<span style="color:navy;">Parent</span>&nbsp;{&nbsp;Name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;credit-card&quot;</span>;&nbsp;Action&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Pay&quot;</span>&nbsp;}</pre> </p> <p> Finally, if the client has already created a parent payment and is now using the resulting link to create child payments, it may be POSTing to a URL like <code>https://example.com/recurrent/42</code>. Your server-side dispatcher will route that request to a third handler. Most web frameworks, including ASP.NET Web API, will be able to pull values out of URLs. In this case, you can configure it so that it pulls the value <code>42</code> out of the URL and binds it to a value called <code>transactionKey</code>. With this, again it's trivial to create a <code>PaymentType</code> value: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;paymentType&nbsp;=&nbsp;<span style="color:navy;">Child</span>&nbsp;(transactionKey,&nbsp;{&nbsp;Name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;credit-card&quot;</span>;&nbsp;Action&nbsp;=&nbsp;<span style="color:#a31515;">&quot;PayRecurrent&quot;</span>&nbsp;})</pre> </p> <p> Notice that, despite containing different data, and being created three different places in the code base, they all have the same type: <code>PaymentType</code>. This means that you can pass these values to a common <code>pay</code> function, which handles the actual communication with the third-party payment service. </p> <p> <strong>Code reuse</strong> </p> <p> Independent of the route the data arrived at, a central, reusable function named <code>pay</code> handles all such payments. This is still an impure boundary function that takes various other input apart from <code>PaymentType</code>. Without going into too much detail, it has a type like <code>Config -&gt; PaymentType -&gt; Result&lt;PaymentDtr,BoundaryFailure&gt;</code>. Don't worry if some of the details look obscure; the important point is that <code>pay</code> is a function that takes a <code>PaymentType</code> value as input. You can visualise the transition from HTTP requests to a function call like this: </p> <p> <img src="/content/binary/from-http-to-payment-type-values.png" alt="Three different URLs mapped to three different PaymentType values, which are again passed to the single pay function"> </p> <p> The <code>pay</code> function is composed from various smaller functions, some <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a> and some impure. Ultimately, it transforms all the input data to the format required by the third-party payment service, and forwards the transaction information. Inside that function you'll find the pattern match that you saw in <a href="http://blog.ploeh.dk/2016/12/07/domain-modelling-with-rest">my previous article</a>. </p> <p> <strong>Summary</strong> </p> <p> By making good use of routing and dispatching, you can easily map incoming HTTP requests to values of algebraic data types. This enables you to close the loop on exposing your domain model at the boundary of your system. Not only can clients request data from your API in terms of your model, but when clients send data to your API, you can translate that data back to your model. </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>. Domain modelling with REST http://blog.ploeh.dk/2016/12/07/domain-modelling-with-rest 2016-12-07T09:15:00+00:00 Mark Seemann <div id="post"> <p> <em>Make illegal states unrepresentable by using hyperlinks as the engine of application state.</em> </p> <p> Every piece of software, whether it's a web service, smart phone app, batch job, or speech recognition system, interfaces with the world in some way. Sometimes, that interface is a user interface, sometimes it's a machine-readable interface; sometimes it involves rendering pixels on a screen, and sometimes it involves writing to files, selecting records from a database, sending emails, and so on. </p> <p> Programmers often struggle with how to model these interactions. This is particularly difficult because at the boundaries, systems no longer adhere to popular programming paradigms. Previously, I've explained why, <a href="http://blog.ploeh.dk/2011/05/31/AttheBoundaries,ApplicationsareNotObject-Oriented">at the boundaries, applications aren't object-oriented</a>. By the same type of argument, neither are they functional (as in 'functional programming'). </p> <p> If that's the case, why should you even bother with 'domain modelling'? Particularly, does it even matter that, with <a href="https://en.wikipedia.org/wiki/Algebraic_data_type">algebraic data types</a>, you can <a href="http://fsharpforfunandprofit.com/posts/designing-with-types-making-illegal-states-unrepresentable">make illegal states unrepresentable</a>? If you need to compromise once you hit the boundary of your application, is it worth the effort? </p> <p> It is, if you structure your application correctly. Proper (<a href="http://martinfowler.com/articles/richardsonMaturityModel.html">level 3</a>) <a href="https://en.wikipedia.org/wiki/Representational_state_transfer">REST</a> architecture gives you one way to structure applications in such a way that you can surface the constraints of your domain model to the interface layer. When done correctly, you can also make illegal states unrepresentable at the boundary. </p> <p> <strong>A payment example</strong> </p> <p> In my <a href="http://blog.ploeh.dk/2016/11/28/easy-domain-modelling-with-types">previous article</a>, I demonstrated how to use (static) types to model an on-line payment domain. To summarise, my task was to model three types of payments: <ul> <li>Individual payments, which happen only once.</li> <li>Parent payments, which start a long-term payment relationship.</li> <li>Child payments, which are automated payments originally authorised by an initial parent payment.</li> </ul> The constraint I had to model is that a child payment requires a <em>transaction key</em> that identifies the original parent payment. When making a payment, however, it's only valid to supply a transaction key for a child payment. It'd be invalid to supply a transaction key to a parent or an individual payment. On the other hand, you have to distinguish individual payments from parent payments, because only parent payments can be used to start a long-term payment relationship. All this leads to this table of possible combinations: <table> <thead> <tr> <th></th> <th><code>"StartRecurrent" : "false"</code></th> <th><code>"StartRecurrent" : "true"</code></th> </tr> </thead> <tbody> <tr> <td><code>"OriginalTransactionKey" : null</code></td> <td><em>Individual</em></td> <td><em>Parent</em></td> </tr> <tr> <td><code>"OriginalTransactionKey" : "1234ABCD"</code></td> <td><em>Child</em></td> <td><strong>(Illegal)</strong></td> </tr> </tbody> </table> The table shows that it's illegal to simultaneously provide a transaction key and set <code>StartRecurrent</code> to <code>true</code>. The other three combinations, on the other hand, are valid. </p> <p> As I demonstrated in my <a href="http://blog.ploeh.dk/2016/11/28/easy-domain-modelling-with-types">previous article</a>, you can easily model this with algebraic data types. </p> <p> At the boundary, however, there are no static types, so how could you model something like that as a web service? </p> <p> <strong>A RESTful solution</strong> </p> <p> A major advantage of REST is that it gives you a way to realise your domain model at the application boundary. It does require, though, that you design the API according to <a href="http://martinfowler.com/articles/richardsonMaturityModel.html">level 3 of the Richardson maturity model</a>. In other words, it's not REST if you're merely tunnelling JSON (or XML) through HTTP. It's still not REST if you publish URL templates and expect clients to fill data into specific place-holders of those URLs. </p> <p> It's REST if the only way a client can interact with your API is by following hyperlinks. </p> <p> If you follow those design principles, however, it's easy to model the above payment domain as a RESTful API. </p> <p> In the following, I will show examples in XML, but it could as well have been JSON. After all, <a href="http://blog.ploeh.dk/2015/06/22/rest-implies-content-negotiation">a true REST API <em>must</em> support content negotiation</a>. One of the reasons that I prefer XML is that I can use <a href="https://en.wikipedia.org/wiki/XPath">XPath</a> to point out various nodes. </p> <p> A client must begin at a pre-published 'home' resource, just like the home page of a web site. This resource presents <a href="https://en.wikipedia.org/wiki/Affordance">affordances</a> in the shape of hyperlinks. As recommended by the <a href="http://amzn.to/YFnkRg">RESTful Web Services Cookbook</a>, I always use <a href="https://en.wikipedia.org/wiki/Atom_(standard)">ATOM</a> links: </p> <p> <pre><span style="color:blue;">&lt;</span><span style="color:#a31515;">home</span><span style="color:blue;">&nbsp;</span><span style="color:red;">xmlns</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">http://example.com/payment</span>&quot; <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color:red;">xmlns:atom</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">http://www.w3.org/2005/Atom</span>&quot;<span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">payment-methods</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">payment-method</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">links</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">atom:link</span><span style="color:blue;">&nbsp;</span><span style="color:red;">rel</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">example:pay-individual</span>&quot; <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color:red;">href</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">https://example.com/gift-card</span>&quot;<span style="color:blue;">&nbsp;/&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/</span><span style="color:#a31515;">links</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">id</span><span style="color:blue;">&gt;</span>gift-card<span style="color:blue;">&lt;/</span><span style="color:#a31515;">id</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&lt;/</span><span style="color:#a31515;">payment-method</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">payment-method</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">links</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">atom:link</span><span style="color:blue;">&nbsp;</span><span style="color:red;">rel</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">example:pay-individual</span>&quot; <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color:red;">href</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">https://example.com/credit-card</span>&quot;<span style="color:blue;">&nbsp;/&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">atom:link</span><span style="color:blue;">&nbsp;</span><span style="color:red;">rel</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">example:pay-parent</span>&quot; <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color:red;">href</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">https://example.com/recurrent/start/credit-card</span>&quot;<span style="color:blue;">&nbsp;/&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/</span><span style="color:#a31515;">links</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">id</span><span style="color:blue;">&gt;</span>credit-card<span style="color:blue;">&lt;/</span><span style="color:#a31515;">id</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&lt;/</span><span style="color:#a31515;">payment-method</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&lt;/</span><span style="color:#a31515;">payment-methods</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&lt;/</span><span style="color:#a31515;">home</span><span style="color:blue;">&gt;</span> </pre> </p> <p> A client receiving the above response is effectively presented with a choice. It can choose to pay with a gift card or credit card, and nothing else, however much it'd like to pay with, say, PayPal. For each of these payment methods, zero or more links are available. </p> <p> Specifically, there are links to create both an individual or a parent payment with a credit card, but it's only possible to make an individual payment with a gift card. You can't set up a long-term, automated payment relationship with a gift card. (This may or may not make sense, depending on how you look at it, but it's fundamentally a business decision.) </p> <p> Links are defined by <em>relationship types</em>, which are unique identifiers present in the <code>rel</code> attributes. You can think of them as equivalent to the human-readable text in an HTML <code>a</code> tag that suggests to a human user what to expect from clicking the link; only, <code>rel</code> attribute values are machine-readable and part of the contract between client and service. </p> <p> Notice how the above XML representation only gives a client the option of making an individual or a parent payment with a credit card. A client can't make a child payment at this point. This follows the domain model, because you can't make a child payment without first having made a parent payment. </p> <p> <strong>RESTful individual payments</strong> </p> <p> If a client wishes to make an individual payment, it follows the link identified by </p> <p> <pre>/home/payment-methods/payment-method[id = 'credit-card']/links/atom:link[@rel = 'example:pay-individual']/@href</pre> </p> <p> In the above XPath query, I've ignored the default document namespace in order to make the expression more readable. The query returns <code>https://example.com/credit-card</code>, and the client can now make an HTTP POST request against that URL with a JSON or XML document containing details about the payment (not shown here, because it's not important for this particular discussion). </p> <p> <strong>RESTful parent payments</strong> </p> <p> If a client wishes to make a parent payment, the initial procedure is the same. First, it follows the link identified by </p> <p> <pre>/home/payment-methods/payment-method[id = 'credit-card']/links/atom:link[@rel = 'example:pay-parent']/@href</pre> </p> <p> The result of that XPath query is <code>https://example.com/recurrent/start/credit-card</code>, so the client can make an HTTP POST request against that URL with the payment details. Unlike the response for an individual payment, the response for a parent payment contains <em>another</em> link: </p> <p> <pre><span style="color:blue;">&lt;</span><span style="color:#a31515;">payment</span><span style="color:blue;">&nbsp;</span><span style="color:red;">xmlns</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">http://example.com/payment</span>&quot; <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color:red;">xmlns:atom</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">http://www.w3.org/2005/Atom</span>&quot;<span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">links</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">atom:link</span><span style="color:blue;">&nbsp;</span><span style="color:red;">rel</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">example:pay-child</span>&quot; <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color:red;">href</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">https://example.com/recurrent/42</span>&quot;<span style="color:blue;">&nbsp;/&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">atom:link</span><span style="color:blue;">&nbsp;</span><span style="color:red;">rel</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">example:payment-details</span>&quot; <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color:red;">href</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">https://example.com/42</span>&quot;<span style="color:blue;">&nbsp;/&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&lt;/</span><span style="color:#a31515;">links</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">amount</span><span style="color:blue;">&gt;</span>13.37<span style="color:blue;">&lt;/</span><span style="color:#a31515;">amount</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">currency</span><span style="color:blue;">&gt;</span>EUR<span style="color:blue;">&lt;/</span><span style="color:#a31515;">currency</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">invoice</span><span style="color:blue;">&gt;</span>1234567890<span style="color:blue;">&lt;/</span><span style="color:#a31515;">invoice</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&lt;/</span><span style="color:#a31515;">payment</span><span style="color:blue;">&gt;</span></pre> </p> <p> This response echoes the details of the payment: this is a payment of 13.37 EUR for invoice 1234567890. It also includes some links that a client can use to further interact with the payment: <ul> <li>The <code>example:payment-details</code> link can be used to query the API for details about the payment, for example its status.</li> <li>The <code>example:pay-child</code> link can be used to make a child payment.</li> </ul> The <code>example:pay-child</code> link is only returned if the previous payment was a parent payment. When a client makes an individual payment, this link isn't present in the response, but when the client makes a parent payment, it is. </p> <p> Another design principle of REST is that <a href="https://www.w3.org/Provider/Style/URI.html.en">cool URIs don't change</a>; once the API has shown a URL like <code>https://example.com/recurrent/42</code> to a client, it should honour that URL indefinitely. The upshot of that is that a client can <em>save</em> that URL for later use. If a client wants to, say, renew a subscription, it can make a new HTTP POST request to that URL <em>a month later</em>, and that's going to be a child payment. Clients don't have to <a href="http://blog.ploeh.dk/2013/05/01/rest-lesson-learned-avoid-hackable-urls">hack the URL</a> in order to figure out what the transaction key is; they can simply store the complete URL as is and use it later. </p> <p> <strong>A network of options</strong> </p> <p> Using a design like the one sketched above, you can make illegal states unrepresentative. There's no way for a client to make a payment with <code>StartRecurrent = true</code> and a non-null transaction key; there's no link to that combination. Such an API uses <a href="https://en.wikipedia.org/wiki/HATEOAS">hypermedia as the engine of application state</a>. </p> <p> It shouldn't be surprising that proper RESTful design works that way. After all, REST is essentially a distillate of the properties that make the World Wide Web work. On a human-readable web page, the user follows links to other pages, and a well-designed web site will only enable a link if the destination exists. </p> <p> You can even draw a graph of the the API I've sketched above: </p> <p> <img src="/content/binary/graph-of-payment-paths.png" alt="Graph of payment options, including a start node, and end node, and a node for each of the three payment types"> </p> <p> In this diagram, you can see that when you make an individual payment, that's all you can do. You can also see that the only way to make a child payment is by first making a parent payment. There's also a path from parent payments directly to the end node, because a client doesn't <em>have</em> to make a child payment just because it made a parent payment. </p> <p> If you think that this looks like a finite state machine, then that's no coincidence. That's exactly what it is. You have states (the nodes) and paths between them. If a state is illegal, then don't add that node; only add nodes for legal states, then add links between the nodes that model legal transitions. </p> <p> Incidentally, languages like F# excel at implementing finite state machines, so it's no wonder I like to implement RESTful APIs in F#. </p> <p> <strong>Summary</strong> </p> <p> Truly RESTful design enables you to make illegal states unrepresentable by using hypermedia as the engine of application state. This gives you a powerful design tool to ensure that clients can only perform correct operations. </p> <p> As I also wrote in <a href="http://blog.ploeh.dk/2016/11/28/easy-domain-modelling-with-types">my previous article</a>, this, too, is no silver bullet. You can turn an API into a pit of success, but there are still many fault scenarios that you can't prevent. </p> <p> If you were intrigued by this article, but are having trouble applying these design techniques to your own field, I'm <a href="http://blog.ploeh.dk/hire-me">available for hire</a> for short or long-term engagements. </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>. Easy domain modelling with types http://blog.ploeh.dk/2016/11/28/easy-domain-modelling-with-types 2016-11-28T07:21:00+00:00 Mark Seemann <div id="post"> <p> <em>Algebraic data types make domain modelling easy.</em> </p> <p> People often ask me if I think that F# is a good general-purpose language, and when I emphatically answer <em>yes!</em>, the natural next question is: <em>why?</em> </p> <p> For years, I've been able to answer this question in the abstract, but I've been looking for a good concrete example with which I could illustrate the answer. I believe that I've now found such an example. </p> <p> The abstract answer, by the way, is that F# has <a href="https://en.wikipedia.org/wiki/Algebraic_data_type">algebraic data types</a>, which makes domain modelling much easier than in languages that don't have such types. Don't worry if the word 'algebraic' sounds scary, though. It's not at all difficult to understand, and I'll show you a simple example. </p> <p> <strong>Payment types</strong> </p> <p> At the moment, I'm working on an integration project: I'm developing a RESTful API that serves as Facade in front of a third-party payment provider. The third-party provider exposes their own API and web-based GUI that enable our end users to pay for services using credit cards, PayPal, and so on. The API that I'm developing presents a simplified, RESTful API to other clients in our organisation. </p> <p> The example you're going to see here is real code that I'm writing in order to implement the desired functionality. </p> <p> The system must be able to handle several different types of payment: <ul> <li>Sometimes, a user pays for a single thing, and that's the end of that transaction.</li> <li>Other times, however, a user engages into a long-term payment relationship. This could be, for example, a subscription, or an 'auto-fill' style of relationship. This is handled in two distinct phases:</li> <ul> <li>An initial payment (can sometimes be for a zero amount) that authorises the merchant to make further transactions.</li> <li>Subsequent payments, based off that initial payment. These payments can be automated, because they require no further user interaction than the initial authorisation.</li> </ul> </ul> The third-party service calls these 'long-term relationship' payments for <em>recurring</em> payments, but in order to distinguish between the first and the subsequent payments in such a relationship, I decided to call them <em>parent</em> and <em>child</em> payments; accordingly, I call the one-off payments <em>individual</em> payments. </p> <p> You can indicate the type of payment when interacting with the payment service's JSON-based API, like this: </p> <p> <pre>{ &nbsp;&nbsp;... &nbsp;&nbsp;"StartRecurrent": "false" &nbsp;&nbsp;... }</pre> </p> <p> Obviously, as the (illegal) ellipses suggests, there's much more data associated with a payment, but that's not important in this example. Since <code>StartRecurrent</code> is <code>false</code>, this is either an individual payment, or a child payment. If you want to start a long-term relationship, you must create a parent payment and set <code>StartRecurrent</code> to <code>true</code>. </p> <p> Child payments, however, are a bit different, because you have to tell the payment service about the parent payment: </p> <p><pre>{ &nbsp;&nbsp;... &nbsp;&nbsp;"OriginalTransactionKey": "1234ABCD", &nbsp;&nbsp;"StartRecurrent": "false" &nbsp;&nbsp;... }</pre> </p> <p> As you can see, when making a child payment, you supply the transaction ID for the parent payment. (This ID is given to you by the payment service when you initiate the parent payment.) </p> <p> In this case, you're clearly <em>not</em> starting a <em>new</em> recurrent transaction. </p> <p> There are two dimensions of variation in this example: <code>StartRecurrent</code> and <code>OriginalTransactionKey</code>. Let's put them in a table: <table> <thead> <tr> <th></th> <th><code>"StartRecurrent" : "false"</code></th> <th><code>"StartRecurrent" : "true"</code></th> </tr> </thead> <tbody> <tr> <td><code>"OriginalTransactionKey" : null</code></td> <td><em>Individual</em></td> <td><em>Parent</em></td> </tr> <tr> <td><code>"OriginalTransactionKey" : "1234ABCD"</code></td> <td><em>Child</em></td> <td><strong>(Illegal)</strong></td> </tr> </tbody> </table> As the table suggests, the combination of an <code>OriginalTransactionKey</code> and setting <code>StartRecurrent</code> to <code>true</code> is illegal, or, in best case, meaningless. </p> <p> How would you model the rules laid out in the above table? In languages like C#, it's difficult, but in F# it's easy. </p> <p> <strong>C# attempts</strong> </p> <p> Most C# developers would, I think, attempt to model a payment transaction with a class. If they aim for <a href="http://blog.ploeh.dk/2011/05/24/Poka-yokeDesignFromSmelltoFragrance">poka-yoke design</a>, they might come up with a design like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">PaymentType</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;PaymentType(<span style="color:blue;">bool</span>&nbsp;startRecurrent) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.StartRecurrent&nbsp;=&nbsp;startRecurrent; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;PaymentType(<span style="color:blue;">string</span>&nbsp;originalTransactionKey) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(originalTransactionKey&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>(originalTransactionKey)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.StartRecurrent&nbsp;=&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.OriginalTransactionKey&nbsp;=&nbsp;originalTransactionKey; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;StartRecurrent&nbsp;{&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">set</span>;&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;OriginalTransactionKey&nbsp;{&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">set</span>;&nbsp;<span style="color:blue;">get</span>;&nbsp;} }</pre> </p> <p> This goes a fair way towards <a href="http://fsharpforfunandprofit.com/posts/designing-with-types-making-illegal-states-unrepresentable">making illegal states unrepresentable</a>, but it doesn't communicate to a fellow programmer how it should be used. </p> <p> Code that <em>uses</em> instances of this <code>PaymentType</code> class could attempt to read the <code>OriginalTransactionKey</code>, which, depending on the type of payment, could return null. That sort of design leads to <a href="http://blog.ploeh.dk/2013/07/08/defensive-coding">defensive coding</a>. </p> <p> Other people might attempt to solve the problem by designing a class hierarchy: </p> <p> <img src="/content/binary/hypothetical-payment-class-hierarchy.png" alt="A hypothetical payment class hierarchy, showing a Payment base class, and three derived classes: IndividualPayment, ParentPayment, and ChildPayment."> </p> <p> (A variation on this design is to define an <code>IPayment</code> interface, and three concrete classes that implement that interface.) </p> <p> This design trades better protection of invariants for violations of the <a href="https://en.wikipedia.org/wiki/Liskov_substitution_principle">Liskov Substitution Principle</a>. Clients will have to (attempt to) downcast to subtypes in order to access all relevant data (particularly <code>OriginalTransactionKey</code>). </p> <p> For completeness sake, I can think of at least one other option with significantly different trade-offs: applying the <a href="https://en.wikipedia.org/wiki/Visitor_pattern">Visitor design pattern</a>. This is, however, quite a complex solution, and most people will find the disadvantages greater than the benefits. </p> <p> Is it such a big deal, then? After all, it's only a single data value (<code>OriginalTransactionKey</code>) that may or may not be there. Surely, most programmers will be able to deal with that. </p> <p> This may be true in this isolated case, but keep in mind that this is only a motivating <em>example</em>. In many other situations, the domain you're trying to model is much more intricate, with many more exceptions to general rules. The more dimensions you add, the more difficult it becomes to reason about the code. </p> <p> <strong>F# model</strong> </p> <p> F#, on the other hand, makes dealing with such problems so simple that it's almost anticlimactic. The reason is that F#'s type system enables you to model <em>alternatives</em> of data, in addition to the combinations of data that C# (or Java) enables. Such alternatives are called <a href="https://docs.microsoft.com/en-us/dotnet/articles/fsharp/language-reference/discriminated-unions">discriminated unions</a>. </p> <p> In the code base I'm currently developing, I model the various payment types like this: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PaymentService</span>&nbsp;=&nbsp;{&nbsp;Name&nbsp;:&nbsp;<span style="color:teal;">string</span>;&nbsp;Action&nbsp;:&nbsp;<span style="color:teal;">string</span>&nbsp;} <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PaymentType</span>&nbsp;= |&nbsp;<span style="color:navy;">Individual</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">PaymentService</span> |&nbsp;<span style="color:navy;">Parent</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">PaymentService</span> |&nbsp;<span style="color:navy;">Child</span>&nbsp;<span style="color:blue;">of</span>&nbsp;originalTransactionKey&nbsp;:&nbsp;<span style="color:teal;">string</span>&nbsp;*&nbsp;paymentService&nbsp;:&nbsp;<span style="color:teal;">PaymentService</span></pre> </p> <p> Here, <code>PaymentService</code> is a record type with some data about the payment (e.g. which credit card to use). </p> <p> Even if you're not used to reading F# code, you can see three alternatives outlined on each of the three lines of code that start with a vertical bar (<code>|</code>). The <code>PaymentType</code> type has <em>exactly</em> three 'subtypes' (they're called <em>cases</em>, though). The illegal state of a non-null <code>OriginalTransactionKey</code> combined with <code>StartRecurrent</code> value of <code>true</code> is not possible. It can't be compiled. </p> <p> Not only that, but all clients given a <code>PaymentType</code> value <em>must</em> deal with all three cases (or the compiler will issue a warning). Here's one example where our code is creating the JSON document to send to the payment service: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;name,&nbsp;action,&nbsp;startRecurrent,&nbsp;transaction&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;req.PaymentType&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Individual</span>&nbsp;{&nbsp;Name&nbsp;=&nbsp;name;&nbsp;Action&nbsp;=&nbsp;action&nbsp;}&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name,&nbsp;action,&nbsp;<span style="color:blue;">false</span>,&nbsp;<span style="color:navy;">None</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Parent</span>&nbsp;{&nbsp;Name&nbsp;=&nbsp;name;&nbsp;Action&nbsp;=&nbsp;action&nbsp;}&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;name,&nbsp;action,&nbsp;<span style="color:blue;">true</span>,&nbsp;<span style="color:navy;">None</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Child</span>&nbsp;(transactionKey,&nbsp;{&nbsp;Name&nbsp;=&nbsp;name;&nbsp;Action&nbsp;=&nbsp;action&nbsp;})&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name,&nbsp;action,&nbsp;<span style="color:blue;">false</span>,&nbsp;<span style="color:navy;">Some</span>&nbsp;transactionKey</pre> </p> <p> This code example also extracts <code>name</code> and <code>action</code> from the <code>PaymentType</code> value, but the relevant values to be aware of are <code>startRecurrent</code> and <code>transaction</code>. <ul> <li>For an individual payment, <code>startRecurrent</code> becomes <code>false</code> and <code>transaction</code> becomes <code>None</code> (meaning that the value is missing).</li> <li>For a parent payment, <code>startRecurrent</code> becomes <code>true</code> and <code>transaction</code> becomes <code>None</code>.</li> <li>For a child payment, <code>startRecurrent</code> becomes <code>false</code> and <code>transaction</code> becomes <code>Some transactionKey</code>.</li> </ul> Notice that the (parent) <code>transactionKey</code> is only available when the payment is a child payment. </p> <p> The values <code>startRecurrent</code> and <code>transaction </code> (as well as <code>name</code> and <code>action</code>) are then used to create a JSON document. I'm not showing that part of the code here, since there's actually a lot going on in the real code base, and it's not related to how to model the domain. Imagine that these values are passed to a constructor. </p> <p> This is a real-world example that, I hope, demonstrates why I prefer F# over C# for domain modelling. The type system enables me to model alternatives as well as combinations of data, and thereby <em>making illegal states unrepresentable</em> - all in only a few lines of code. </p> <p> <strong>Summary</strong> </p> <p> Classes, in languages like C# and Java, enable you to model <em>combinations</em> of data. The more fields or properties you add to a class, the more combinations are possible. This is often useful, but sometimes you need to be able to model <em>alternatives</em>, rather than combinations. </p> <p> Some languages, like F#, Haskell, OCaml, Elm, Kotlin, and many others, have type systems that give you the power to model both combinations and alternatives. Such types systems are said to have <a href="https://en.wikipedia.org/wiki/Algebraic_data_type">algebraic data types</a>, but while the word sounds 'mathy', such types make it much easier to model complex domains. </p> <p> There are more reasons to love F# than only its algebraic data types, but this is the foremost reason I find it a better language for mainstream development work than C#. </p> <p> If you want to see a more complex example of modelling with types, a good next step would be <a href="http://blog.ploeh.dk/2016/02/10/types-properties-software-designing-with-types">the first article</a> in my <a href="http://blog.ploeh.dk/2016/02/10/types-properties-software">Types + Properties = Software</a> article series. </p> <p> Finally, I should be careful that I don't oversell the idea of making illegal states unrepresentable. Algebraic data types give you an extra dimension in which you can model domains, but there are still rules that they can't enforce. As an example, you can't state that integers must only fall in a certain range (e.g. only positive integers allowed). There are other type systems, such as <a href="https://en.wikipedia.org/wiki/Dependent_type">dependent types</a>, that give you even more power to embed domain rules into types, but as far as I know, there are no type systems that can fully model all rules as types. You'll still have to write some code as well. </p> <p> The article is an instalment in the <a href="https://sergeytihon.wordpress.com/2016/10/23/f-advent-calendar-in-english-2016">2016 F# Advent calendar</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="https://lambdaklub.wordpress.com">Botond BalĆ”zs</a></div> <div class="comment-content"> <p>Mark,</p> <p>I must be missing something important but it seems to me that the only advantage of using F# in this case is that the match is enforced to be exhaustive by the compiler. And of course the syntax is also nicer than a bunch of if's. In all other respects, the solution is basically equivalent to the C# class hierarchy approach.</p> <p>Am I mistaken?</p> </div> <div class="comment-date">2016-12-03 08:38 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> Botond, thank you for writing. The major advantage is that enumeration of all possible cases is available at compile-time. One derived advantage of that is that the compiler can check whether a piece of code handles all cases. That's already, in my experience, a big deal. The sooner you can get feedback on your work, the better, and <a href="http://blog.ploeh.dk/2011/04/29/Feedbackmechanismsandtradeoffs">it doesn't get faster than compile-time feedback</a>. </p> <p> Another advantage of having all cases encoded in the type system is that it gives you better tool support. Imagine that you're looking at the return value of a function, and that this is the first time you're encountering that return type. If the return value is an abstract base class (or interface), you'll need to resort to either the documentation or reflection in order to figure out which subtypes exist. There can be arbitrarily many subtypes, and they can be scattered over arbitrarily many libraries (assemblies). Figuring out what to do with an abstract base class introduces a context switch that could have been avoided. </p> <p> This is exactly another advantage offered by discriminated unions: when a function returns a discriminated union, you can immediately get tool support to figure out what to do with it, even if you've never encountered the type before. </p> <p> The problem with examples such as the above is that I'm trying to explain how a language feature can help you with modelling <em>complex</em> domains, but if I try to present a really complex problem, no-one will have the patience to read the article. Instead, I have to come up with an example that's so simple that the reader doesn't give up, and hopefully still complex enough that the reader can imagine how it's a stand-in for a more complex problem. </p> <p> When you look at the problem presented above, it's not <em>that</em> complex, so you can still keep a C# implementation in your head. As you add more variability to the problem, however, you can easily find yourself in a situation where the combinatorial explosion of possible values make it difficult to ensure that you've dealt with all edge cases. This is one of the main reasons that C# and Java code often throws run-time exceptions (particularly null-reference exceptions). </p> <p> It did, in fact, turn out that the above example domain became more complex as I learned more about the entire range of problems I had to solve. When I described the problem above, I thought that all payments would have pre-selected payment methods. In other words, when a user is presented with a check-out page, he or she selects the payment method (PayPal, direct debit, and so on), and only then, when we know payment method, do we initiate the payment flow. It turns out, though, that in some cases, we should start the payment flow first, and then let the user pick the payment method from a list of options. It should be noted, however, that user-selection only makes sense for interactive payments, so a <em>child</em> payment can never be user-selectable (since it's automated). </p> <p> It was trivial to extend the domain model with that new requirement: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PaymentService</span>&nbsp;=&nbsp;{&nbsp;Name&nbsp;:&nbsp;<span style="color:teal;">string</span>;&nbsp;Action&nbsp;:&nbsp;<span style="color:teal;">string</span>&nbsp;} <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PaymentMethod</span>&nbsp;= |&nbsp;<span style="color:navy;">PreSelected</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">PaymentService</span> |&nbsp;<span style="color:navy;">UserSelectable</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span>&nbsp;<span style="color:teal;">list</span> <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">TransactionKey</span>&nbsp;=&nbsp;<span style="color:navy;">TransactionKey</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span>&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">override</span>&nbsp;this.<span style="color:navy;">ToString</span>&nbsp;()&nbsp;=&nbsp;<span style="color:blue;">match</span>&nbsp;this&nbsp;<span style="color:blue;">with</span>&nbsp;<span style="color:navy;">TransactionKey</span>&nbsp;s&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;s <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PaymentType</span>&nbsp;= |&nbsp;<span style="color:navy;">Individual</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">PaymentMethod</span> |&nbsp;<span style="color:navy;">Parent</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">PaymentMethod</span> |&nbsp;<span style="color:navy;">Child</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">TransactionKey</span>&nbsp;*&nbsp;<span style="color:teal;">PaymentService</span></pre> </p> <p> This effectively uses the static type system to state that both the <code>Individual</code> and <code>Parent</code> cases can be defined in one of two ways: <code>PreSelected</code> or <code>UserSelectable</code>, each of which, again, contains heterogeneous data (<code>PaymentService</code> versus <code>string list</code>). Child payments, on the other hand, can't be user-selectable, but must be defined by a <code>PaymentService</code> value, as well as a transaction key (at this point, I'd also created a single-case union for the transaction key, but that's a different topic; it's still a string). </p> <p> Handling all the different combinations was equally easy, and the compiler guarantees that I've handled all possible combinations: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;services,&nbsp;selectables,&nbsp;startRecurrent,&nbsp;transaction&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;req.PaymentType&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Individual</span>&nbsp;(<span style="color:navy;">PreSelected</span>&nbsp;ps)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">service</span>&nbsp;ps,&nbsp;<span style="color:navy;">None</span>,&nbsp;<span style="color:blue;">false</span>,&nbsp;<span style="color:navy;">None</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Individual</span>&nbsp;(<span style="color:navy;">UserSelectable</span>&nbsp;us)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[||],&nbsp;us&nbsp;|&gt;&nbsp;<span style="color:teal;">String</span>.<span style="color:navy;">concat</span>&nbsp;<span style="color:#a31515;">&quot;,&nbsp;&quot;</span>&nbsp;|&gt;&nbsp;<span style="color:navy;">Some</span>,&nbsp;<span style="color:blue;">false</span>,&nbsp;<span style="color:navy;">None</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Parent</span>&nbsp;(<span style="color:navy;">PreSelected</span>&nbsp;ps)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">service</span>&nbsp;ps,&nbsp;<span style="color:navy;">None</span>,&nbsp;<span style="color:blue;">true</span>,&nbsp;&nbsp;<span style="color:navy;">None</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Parent</span>&nbsp;(<span style="color:navy;">UserSelectable</span>&nbsp;us)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[||],&nbsp;us&nbsp;|&gt;&nbsp;<span style="color:teal;">String</span>.<span style="color:navy;">concat</span>&nbsp;<span style="color:#a31515;">&quot;,&nbsp;&quot;</span>&nbsp;|&gt;&nbsp;<span style="color:navy;">Some</span>,&nbsp;<span style="color:blue;">true</span>,&nbsp;&nbsp;<span style="color:navy;">None</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Child</span>&nbsp;(<span style="color:navy;">TransactionKey</span>&nbsp;transactionKey,&nbsp;ps)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">service</span>&nbsp;ps,&nbsp;<span style="color:navy;">None</span>,&nbsp;<span style="color:blue;">false</span>,&nbsp;<span style="color:navy;">Some</span>&nbsp;transactionKey</pre> </p> <p> How would you handle this with a class hierarchy, and what would the consuming code look like? </p> </div> <div class="comment-date">2016-12-06 10:50 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>. When variable names are in the way http://blog.ploeh.dk/2016/10/25/when-variable-names-are-in-the-way 2016-10-25T06:20:00+00:00 Mark Seemann <div id="post"> <p> <em>While Clean Code recommends using good variable names to communicate the intent of code, sometimes, variable names can be in the way.</em> </p> <p> Good guides to more readable code, like <a href="http://amzn.to/XCJi9X">Clean Code</a>, explain how explicitly introducing variables with descriptive names can make the code easier to understand. There's much literature on the subject, so I'm not going to reiterate it here. It's not the topic of this article. </p> <p> In the majority of cases, introducing a well-named variable will make the code more readable. There are, however, no rules without exceptions. After all, <a href="http://martinfowler.com/bliki/TwoHardThings.html">one of the hardest tasks in programming is naming things</a>. In this article, I'll show you an example of such an exception. While the example is slightly elaborate, it's a <em>real-world</em> example I recently ran into. </p> <p> <strong>Escaping object-orientation</strong> </p> <p> Regular readers of this blog will know that I write many <a href="https://en.wikipedia.org/wiki/Representational_state_transfer">RESTful APIs</a> in F#, but 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> ASP.NET Web API expects you handle HTTP requests using <em>Controllers</em>, so I use Constructor Injection to inject a function that will do all the actual work, and delegate each request to a function call. It often looks like this: </p> <p> <pre><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;(<span style="color:#9b9b9b;">portalId</span>&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;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;">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> This particular Controller only handles HTTP POST requests, and it does it by delegating to the injected <code>imp</code> function and translating the return value of that function call to various HTTP responses. This enables me to compose <code>imp</code> from F# functions, and thereby escape the object-oriented design of ASP.NET Web API. In other words, each Controller is an <a href="https://en.wikipedia.org/wiki/Adapter_pattern">Adapter</a> over a functional implementation. </p> <p> For good measure, though, this Controller implementation ought to be unit tested. </p> <p> <strong>A naive unit test attempt</strong> </p> <p> Each HTTP request is handled at the boundary of the system, and <a href="http://blog.ploeh.dk/2016/03/18/functional-architecture-is-ports-and-adapters">the boundary of the system is always impure</a> - even in Haskell. This is particularly clear in the case of the above <code>PushController</code>, because it handles <code>Success ()</code>. In success cases, the result is <code>()</code> (<code>unit</code>), which strongly implies a side effect. Thus, a unit test ought to care not only about what <code>imp</code> returns, but also the input to the function. </p> <p> While you could write a unit test like the following, it'd be naive. </p> <p> <pre>[&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``Post&nbsp;returns&nbsp;correct&nbsp;result&nbsp;on&nbsp;validation&nbsp;failure``</span>&nbsp;req&nbsp;(<span style="color:navy;">NonNull</span>&nbsp;msg)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;_&nbsp;=&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">fail</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">use</span>&nbsp;sut&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:teal;">PushController</span>&nbsp;(<span style="color:navy;">imp</span>) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;sut.<span style="color:navy;">Post</span>&nbsp;req &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="background:yellow;">actual</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:navy;background:yellow;">convertsTo</span><span style="background:yellow;">&lt;</span><span style="background:yellow;">Results</span><span style="background:yellow;">.</span><span style="color:teal;background:yellow;">BadRequestErrorMessageResult</span><span style="background:yellow;">&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">map</span><span style="background:yellow;">&nbsp;(</span><span style="color:blue;background:yellow;">fun</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">&nbsp;</span><span style="color:blue;background:yellow;">-&gt;</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">.</span><span style="background:yellow;">Message</span><span style="background:yellow;">)</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">exists</span><span style="background:yellow;">&nbsp;((</span><span style="background:yellow;">=</span><span style="background:yellow;">)&nbsp;</span><span style="background:yellow;">msg</span><span style="background:yellow;">)&nbsp;@&gt;</span></pre> </p> <p> This unit test uses <a href="https://fscheck.github.io/FsCheck">FsCheck</a>'s integration for <a href="https://xunit.github.io">xUnit.net</a>, and <a href="http://www.swensensoftware.com/unquote">Unquote</a> for assertions. Additionally, it uses a <code>convertsTo</code> function that I've <a href="http://blog.ploeh.dk/2014/03/21/composed-assertions-with-unquote">previously described</a>. </p> <p> The <code>imp</code> function for <code>PushController</code> must have the type <code>PushRequestDtr -&gt; Result&lt;unit, BoundaryFailure&gt;</code>. In the unit test, it uses a wild-card (<code>_</code>) for the input value, so its type is <code>'a -&gt; Result&lt;'b, BoundaryFailure&gt;</code>. That's a wider type, but it matches the required type, so the test compiles (and passes). </p> <p> FsCheck populates the <code>req</code> argument to the test function itself. This value is passed to <code>sut.Post</code>. If you look at the definition of <code>sut.Post</code>, you may wonder what happened to the individual (and currently unused) <code>portalId</code> argument. The explanation is that the <code>Post</code> method can be viewed as a method with two parameters, but it can also be viewed as an impure function that takes a <em>single</em> argument of the type <code>string * PushRequestDtr</code> - a tuple. In other words, the test function's <code>req</code> argument is a tuple. The test is not only concise, but also robust against refactorings. If you change the signature of the <code>Post</code> method, odds are that the test will still compile. (This is one of the many benefits of type inference.) </p> <p> The problem with the test is that it doesn't verify the data flow into <code>imp</code>, so this version of <code>PushController</code> <em>also</em> passes the test: </p> <p> <pre><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;(<span style="color:#9b9b9b;">portalId</span>&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;<span style="color:#9b9b9b;">req</span>&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;">let</span>&nbsp;minimalReq&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;Transaction&nbsp;=&nbsp;{&nbsp;Invoice&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>;&nbsp;Status&nbsp;=&nbsp;{&nbsp;Code&nbsp;=&nbsp;{&nbsp;Code&nbsp;=&nbsp;0&nbsp;}&nbsp;}&nbsp;}&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;minimalReq&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;">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> As the name implies, the <code>minimalReq</code> value is the 'smallest' value I can create of the <code>PushRequestDtr</code> type. As you can see, this implementation ignores the <code>req</code> method argument and instead passes <code>minimalReq</code> to <code>imp</code>. This is clearly wrong, but it passes the unit test test. </p> <p> <strong>Data flow testing</strong> </p> <p> Not only should you care about the output of <code>imp</code>, but you should also care about the input. This is because <code>imp</code> is inherently impure, so it'd be conceivable that the input values matter in some way. </p> <p> As <a href="http://bit.ly/xunitpatterns">xUnit Test Patterns</a> explains, automated tests should contain no branching, so I don't think it's a good idea to define a test-specific <code>imp</code> function using conditionals. Instead, we can use guard assertions to verify that the input is as expected: </p> <p> <pre>[&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``Post&nbsp;returns&nbsp;correct&nbsp;result&nbsp;on&nbsp;validation&nbsp;failure``</span>&nbsp;req&nbsp;(<span style="color:navy;">NonNull</span>&nbsp;msg)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;candidate&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;candidate&nbsp;=!&nbsp;<span style="color:navy;">snd</span>&nbsp;req &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">fail</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">use</span>&nbsp;sut&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:teal;">PushController</span>&nbsp;(<span style="color:navy;">imp</span>) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;sut.<span style="color:navy;">Post</span>&nbsp;req &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="background:yellow;">actual</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:navy;background:yellow;">convertsTo</span><span style="background:yellow;">&lt;</span><span style="background:yellow;">Results</span><span style="background:yellow;">.</span><span style="color:teal;background:yellow;">BadRequestErrorMessageResult</span><span style="background:yellow;">&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">map</span><span style="background:yellow;">&nbsp;(</span><span style="color:blue;background:yellow;">fun</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">&nbsp;</span><span style="color:blue;background:yellow;">-&gt;</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">.</span><span style="background:yellow;">Message</span><span style="background:yellow;">)</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">exists</span><span style="background:yellow;">&nbsp;((</span><span style="background:yellow;">=</span><span style="background:yellow;">)&nbsp;</span><span style="background:yellow;">msg</span><span style="background:yellow;">)&nbsp;@&gt;</span></pre> </p> <p> The <code>imp</code> function is now implemented using Unquote's custom <code>=!</code> operator, which means that <code>candidate</code> must equal <code>req</code>. If not, Unquote will throw an exception, and thereby fail the test. </p> <p> If <code>candidate</code> is equal to <code>snd req</code>, the <code>=!</code> operator does nothing, enabling the <code>imp</code> function to return the value <code>Result.fail (ValidationFailure msg)</code>. </p> <p> This version of the test verifies the entire data flow through <code>imp</code>: both input and output. </p> <p> There is, however, a small disadvantage to writing the <code>imp</code> code this way. It isn't a big issue, but it annoys me. </p> <p> Here's the heart of the matter: I had to come up with a name for the local <code>PushRequestDtr</code> value that the <code>=!</code> operator evaluates against <code>snd req</code>. I chose to call it <code>candidate</code>, which may seem reasonable, but that naming strategy doesn't scale. </p> <p> In order to keep the introductory example simple, I chose a Controller method that doesn't (yet) use its <code>portalId</code> argument, but the code base contains other Controllers, for example this one: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">IdealController</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;">IDealRequestDtr</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;">IDealResponseDtr</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;">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> This Controller's <code>Post</code> method passes <em>both</em> <code>portalId</code> and <code>req</code> to <code>imp</code>. In order to perform data flow verification of that implementation, the test has to look like this: </p> <p> <pre>[&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``Post&nbsp;returns&nbsp;correct&nbsp;result&nbsp;on&nbsp;success``</span>&nbsp;portalId&nbsp;req&nbsp;resp&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;pid&nbsp;candidate&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pid&nbsp;=!&nbsp;portalId &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;candidate&nbsp;=!&nbsp;req &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">succeed</span>&nbsp;resp &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">use</span>&nbsp;sut&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:teal;">IdealController</span>&nbsp;(<span style="color:navy;">imp</span>) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;sut.<span style="color:navy;">Post</span>&nbsp;(portalId,&nbsp;req) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="background:yellow;">actual</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:navy;background:yellow;">convertsTo</span><span style="background:yellow;">&lt;</span><span style="background:yellow;">Results</span><span style="background:yellow;">.</span><span style="color:teal;background:yellow;">OkNegotiatedContentResult</span><span style="background:yellow;">&lt;</span><span style="color:teal;background:yellow;">IDealResponseDtr</span><span style="background:yellow;">&gt;&gt;</span><span style="background:yellow;"></span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">map</span><span style="background:yellow;">&nbsp;(</span><span style="color:blue;background:yellow;">fun</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">&nbsp;</span><span style="color:blue;background:yellow;">-&gt;</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">.</span><span style="background:yellow;">Content</span><span style="background:yellow;">)</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">exists</span><span style="background:yellow;">&nbsp;((</span><span style="background:yellow;">=</span><span style="background:yellow;">)&nbsp;</span><span style="background:yellow;">resp</span><span style="background:yellow;">)&nbsp;@&gt;</span></pre> </p> <p> This is where I began to run out of good argument names. You need names for the <code>portalId</code> and <code>req</code> arguments of <code>imp</code>, but you can't use those names because they're already in use. You can't even shadow the names of the outer values, because the test-specific <code>imp</code> function has to close over those outer values in order to compare them to their expected values. </p> <p> While I decided to call the local <em>portal ID</em> argument <code>pid</code>, it's hardly helpful. Explicit arguments have become a burden rather than a help to the reader. If only we could get rid of those explicit arguments. </p> <p> <strong>Point free</strong> </p> <p> Functional programming offers a well-known alternative to explicit arguments, commonly known as <a href="https://en.wikipedia.org/wiki/Tacit_programming">point-free programming</a>. Some people find point-free style unreadable, but sometimes it can make the code more readable. Could this be the case here? </p> <p> If you look at the test-specific <code>imp</code> functions in both of the above examples with explicit arguments, you may notice that they follow a common pattern. First they invoke one or more guard assertions, and then they return a value. You can model this with a custom operator: </p> <p> <pre><span style="color:green;">//&nbsp;&#39;Guard&#39;&nbsp;composition.&nbsp;Returns&nbsp;the&nbsp;return&nbsp;value&nbsp;if&nbsp;``assert``&nbsp;doesn&#39;t&nbsp;throw.</span> <span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;unit)&nbsp;-&gt;&nbsp;&#39;b&nbsp;-&gt;&nbsp;&#39;a&nbsp;-&gt;&nbsp;&#39;b</span> <span style="color:blue;">let</span>&nbsp;(&gt;&gt;!)&nbsp;<span style="color:navy;">``assert``</span>&nbsp;returnValue&nbsp;x&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">``assert``</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;returnValue</pre> </p> <p> The first argument, <code>``assert``</code>, is a function with the type <code>'a -&gt; unit</code>. This is the assertion function: it takes any value as input, and returns <code>unit</code>. The implication is that it'll throw an exception if the assertion fails. </p> <p> After invoking the assertion, the function returns the <code>returnValue</code> argument. </p> <p> The reason I designed it that way is that it's <em>composable</em>, which you'll see in a minute. The reason I named it <code>&gt;&gt;!</code> was that I wanted some kind of arrow, and I thought that the exclamation mark relates nicely to Unquote's use of exclamation marks. </p> <p> This enables you to compose the first <code>imp</code> example (for <code>PushController</code>) in point-free style: </p> <p> <pre>[&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``Post&nbsp;returns&nbsp;correct&nbsp;result&nbsp;on&nbsp;validation&nbsp;failure``</span>&nbsp;req&nbsp;(<span style="color:navy;">NonNull</span>&nbsp;msg)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;=&nbsp;((=!)&nbsp;(<span style="color:navy;">snd</span>&nbsp;req))&nbsp;&gt;&gt;!&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">fail</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">use</span>&nbsp;sut&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:teal;">PushController</span>&nbsp;(<span style="color:navy;">imp</span>) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;sut.<span style="color:navy;">Post</span>&nbsp;req &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="background:yellow;">actual</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:navy;background:yellow;">convertsTo</span><span style="background:yellow;">&lt;</span><span style="background:yellow;">Results</span><span style="background:yellow;">.</span><span style="color:teal;background:yellow;">BadRequestErrorMessageResult</span><span style="background:yellow;">&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">map</span><span style="background:yellow;">&nbsp;(</span><span style="color:blue;background:yellow;">fun</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">&nbsp;</span><span style="color:blue;background:yellow;">-&gt;</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">.</span><span style="background:yellow;">Message</span><span style="background:yellow;">)</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">exists</span><span style="background:yellow;">&nbsp;((</span><span style="background:yellow;">=</span><span style="background:yellow;">)&nbsp;</span><span style="background:yellow;">msg</span><span style="background:yellow;">)&nbsp;@&gt;</span></pre> </p> <p> At first glance, most people would be likely to consider this to be <em>less</em> readable than before, and clearly, that's a valid standpoint. On the other hand, once you get used to identify the <code>&gt;&gt;!</code> operator, this becomes a concise shorthand. A data-flow-verifying <code>imp</code> mock function is composed of an assertion on the left-hand side of <code>&gt;&gt;!</code>, and a return value on the right-hand side. </p> <p> Most importantly, those hard-to-name arguments are gone. </p> <p> Still, let's dissect the expression <code>((=!) (snd req)) &gt;&gt;! Result.fail (ValidationFailure msg)</code>. </p> <p> The expression on the left-hand side of the <code>&gt;&gt;!</code> operator is the assertion. It uses Unquote's <em>must equal</em> <code>=!</code> operator as a function. (In F#, infix operators are functions, and you can use them as functions by surrounding them by brackets.) While you can write an assertion as <code>candidate =! snd req</code> using infix notation, you can also write the same expression as a function call: <code>(=!) (snd req) candidate</code>. Since this is a function, it can be partially applied: <code>(=!) (snd req)</code>; the type of that expression is <code>PushRequestDtr -&gt; unit</code>, which matches the required type <code>'a -&gt; unit</code> that <code>&gt;&gt;!</code> expects from its <code>``assert``</code> argument. That explains the left-hand side of the <code>&gt;&gt;!</code> operator. </p> <p> The right-hand side is easier, because that's the return value of the composed function. In this case the value is <code>Result.fail (ValidationFailure msg)</code>. </p> <p> You already know that the type of <code>&gt;&gt;!</code> is <code>('a -&gt; unit) -&gt; 'b -&gt; 'a -&gt; 'b</code>. Replacing the generic type arguments with the actual types in use, <code>'a</code> is <code>PushRequestDtr</code> and <code>'b</code> is <code>Result&lt;'a ,BoundaryFailure&gt;</code>, so the type of <code>imp</code> is <code>PushRequestDtr -&gt; Result&lt;'a ,BoundaryFailure&gt;</code>. When you set <code>'a</code> to <code>unit</code>, this fits the required type of <code>PushRequestDtr -&gt; Result&lt;unit, BoundaryFailure&gt;</code>. </p> <p> This works because in its current incarnation, the <code>imp</code> function for <code>PushController</code> only takes a single value as input. Will this also work for <code>IdealController</code>, which passes both <code>portalId</code> and <code>req</code> to its <code>imp</code> function? </p> <p> <strong>Currying</strong> </p> <p> The <code>imp</code> function for <code>IdealController</code> has the type <code>string -&gt; IDealRequestDtr -&gt; Result&lt;IDealResponseDtr, BoundaryFailure&gt;</code>. Notice that it takes two arguments instead of one. Is it possible to compose an <code>imp</code> function with the <code>&gt;&gt;!</code> operator? </p> <p> Consider the above example that exercises the success case for <code>IdealController</code>. What if, instead of writing </p> <p> <pre><span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;pid&nbsp;candidate&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;pid&nbsp;=!&nbsp;portalId &nbsp;&nbsp;&nbsp;&nbsp;candidate&nbsp;=!&nbsp;req &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">succeed</span>&nbsp;resp</pre> </p> <p> you write the following? </p> <p> <pre><span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;=&nbsp;((=!)&nbsp;req)&nbsp;&gt;&gt;!&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">succeed</span>&nbsp;resp </pre> </p> <p> Unfortunately, that does work, because the type of that function is <code>string * IDealRequestDtr -&gt; Result&lt;IDealResponseDtr, 'a&gt;</code>, and not <code>string -&gt; IDealRequestDtr -&gt; Result&lt;IDealResponseDtr, BoundaryFailure&gt;</code>, as it should be. It's almost there, but the input values are tupled, instead of curried. </p> <p> You can easily correct that with a standard <a href="https://gist.github.com/ploeh/6d8050e121a5175fabb1d08ef5266cd7">curry function</a>: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;=&nbsp;((=!)&nbsp;req)&nbsp;&gt;&gt;!&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">succeed</span>&nbsp;resp&nbsp;|&gt;&nbsp;<span style="color:teal;">Tuple2</span>.<span style="color:navy;">curry</span> </pre> </p> <p> The <code>Tuple2.curry</code> function takes as input a function that has tupled arguments, and turns it into a curried function. Exactly what we need here! </p> <p> The entire test is now: </p> <p> <pre>[&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``Post&nbsp;returns&nbsp;correct&nbsp;result&nbsp;on&nbsp;success``</span>&nbsp;req&nbsp;resp&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;=&nbsp;((=!)&nbsp;req)&nbsp;&gt;&gt;!&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">succeed</span>&nbsp;resp&nbsp;|&gt;&nbsp;<span style="color:teal;">Tuple2</span>.<span style="color:navy;">curry</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">use</span>&nbsp;sut&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:teal;">IdealController</span>&nbsp;(<span style="color:navy;">imp</span>) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;sut.<span style="color:navy;">Post</span>&nbsp;req &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="background:yellow;">actual</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:navy;background:yellow;">convertsTo</span><span style="background:yellow;">&lt;</span><span style="background:yellow;">Results</span><span style="background:yellow;">.</span><span style="color:teal;background:yellow;">OkNegotiatedContentResult</span><span style="background:yellow;">&lt;</span><span style="color:teal;background:yellow;">IDealResponseDtr</span><span style="background:yellow;">&gt;&gt;</span><span style="background:yellow;"></span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">map</span><span style="background:yellow;">&nbsp;(</span><span style="color:blue;background:yellow;">fun</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">&nbsp;</span><span style="color:blue;background:yellow;">-&gt;</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">.</span><span style="background:yellow;">Content</span><span style="background:yellow;">)</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">exists</span><span style="background:yellow;">&nbsp;((</span><span style="background:yellow;">=</span><span style="background:yellow;">)&nbsp;</span><span style="background:yellow;">resp</span><span style="background:yellow;">)&nbsp;@&gt;</span></pre> </p> <p> Whether or not you find this more readable than the previous example is, as always, subjective, but I like it because it's a succinct, composable way to address data flow verification. Once you get over the initial shock of partially applying Unquote's <code>=!</code> operator, as well as the cryptic-looking <code>&gt;&gt;!</code> operator, you may begin to realise that the same idiom is repeated throughout. In fact, it's more than an idiom. It's an implementation of a design pattern. </p> <p> <strong>Mocks</strong> </p> <p> When talking about unit testing, I prefer the vocabulary of <a href="http://bit.ly/xunitpatterns">xUnit Test Patterns</a>, because of its unrivalled consistent terminology. Using Gerard Meszaros' nomenclature, a <a href="http://martinfowler.com/bliki/TestDouble.html">Test Double</a> with built-in verification of interaction is called a <em>Mock</em>. </p> <p> Most people (including me) dislike Mocks because they tend to lead to brittle unit tests. They <em>tend</em> to, but <a href="http://blog.ploeh.dk/2013/10/23/mocks-for-commands-stubs-for-queries">sometimes you need them</a>. Mocks are useful when you care about side-effects. </p> <p> Functional programming emphasises <a href="https://en.wikipedia.org/wiki/Pure_function">pure functions</a>, which, by definition, are free of side-effects. <a href="http://blog.ploeh.dk/2015/05/07/functional-design-is-intrinsically-testable">In pure functional programming, you don't need Mocks</a>. </p> <p> Since F# is a multi-paradigmatic language, you sometimes have to write code in a more object-oriented style. In the example you've seen here, I've shown you how to unit test that Controllers correctly work as Adapters over (impure) functions. Here, Mocks are useful, even if they have no place in the rest of the code base. </p> <p> Being able to express a Mock with a couple of minimal functions is, in my opinion, preferable to adding a big dependency to a 'mocking library'. </p> <p> <strong>Concluding remarks</strong> </p> <p> Sometimes, explicit values and arguments are in the way. By their presence, they force you to name them. Often, naming is good, because it compels you to make tacit knowledge explicit. In rare cases, though, the important detail isn't a value, or an argument, but instead an <em>activity</em>. An example of this is when verifying data flow. While the values are obviously present, the focus ought to be on the comparison. Thus, by making the local function arguments implicit, you can direct the reader's attention to the interaction - in this case, Unquote's <code>=!</code> <em>must equal</em> comparison. </p> <p> In the introduction to this article, I told you that the code you've seen here is a real-life example. This is true. </p> <p> I submitted my refactoring to point-free style as an internal pull request on the project I'm currently working. When I did that, I was genuinely in doubt about the readability improvement this would give, so I asked my reviewers for their opinions. I was genuinely ready to accept if they wanted to reject the pull request. </p> <p> My reviewers disagreed internally, ultimately had a vote, and decided to reject the pull request. I don't blame them. We had a civil discussion about the pros and cons, and while they understood the advantages, they felt that the disadvantages weighed heavier. </p> <p> In their context, I understand why they decided to decline the change, but that doesn't mean that I don't find this an interesting experiment. I expect to use something like this in the future in some contexts, while in other contexts, I'll stick with the more verbose (and harder to name) test-specific functions with explicit arguments. </p> <p> Still, I like to solve problems using well-known compositions, which is the reason I prefer a composable, idiomatic approach over ad-hoc code. </p> <p> If you'd like to learn more about unit testing and property-based testing in F# (and C#), you can watch some of <a href="http://bit.ly/ploehralsight">my Pluralsight courses</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>. Decoupling decisions from effects http://blog.ploeh.dk/2016/09/26/decoupling-decisions-from-effects 2016-09-26T21:51:00+00:00 Mark Seemann <div id="post"> <p> <em>Functional programming emphasises pure functions, but sometimes decisions must be made based on impure data. The solution is to decouple decisions and effects.</em> </p> <p> Functional programmers love <a href="https://en.wikipedia.org/wiki/Pure_function">pure functions</a>. Not only do they tend to be easy to reason about, they are also <a href="http://blog.ploeh.dk/2015/05/07/functional-design-is-intrinsically-testable">intrinsically testable</a>. It'd be wonderful if we could build entire systems only from pure functions, but every functional programmer knows that the world is impure. Instead, we strive towards implementing as much of our code base as pure functions, so that an application is <a href="http://blog.ploeh.dk/2016/03/18/functional-architecture-is-ports-and-adapters">impure only at its boundaries</a>. </p> <p> The more you can do this, the more testable the system becomes. One rule of thumb about unit testing that I often use is that if a particular candidate for unit testing has a <a href="https://en.wikipedia.org/wiki/Cyclomatic_complexity">cyclomatic complexity</a> of 1, it may be acceptable to skip unit testing it. Instead, we can consider such a unit a <a href="http://xunitpatterns.com/Humble%20Object.html">humble unit</a>. If you can separate decisions from <em>effects</em> (which is what functional programmers often call impurities), you can often make the impure functions humble. </p> <p> In other words: put all logic in pure functions that can be unit tested, and implement impure effects as humble functions that you don't need to unit test. </p> <p> You want to see an example. So do I! </p> <p> <strong>Example: conditional reading from file</strong> </p> <p> In a <a href="https://gist.github.com/jcansdale/de58c2b2c389851f72b00ef525be820c">recent discussion</a>, Jamie Cansdale asks how I'd design and unit test something like the following C# method if I could instead redesign it in F#. </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;GetUpperText(<span style="color:blue;">string</span>&nbsp;path) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(!<span style="color:#2b91af;">File</span>.Exists(path))&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#a31515;">&quot;DEFAULT&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;text&nbsp;=&nbsp;<span style="color:#2b91af;">File</span>.ReadAllText(path); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;text.ToUpperInvariant(); }</pre> </p> <p> Notice how this method contains two impure operations: <code>File.Exists</code> and <code>File.ReadAllText</code>. Decision logic seems interleaved with IO. How can decisions be separated from effects? </p> <p> (For good measure I ought to point out that obviously, the above example is so simple that by itself, it almost doesn't warrant testing. Think of it as a stand-in for a more complex problem.) </p> <p> With a statement-based language like C#, it can be difficult to see how to separate decision logic from effects without introducing interfaces, but with expression-based languages like F#, it becomes close to trivial. In this article, I'll show you three alternatives. </p> <p> All three alternatives, however, make use of the same function for turning text into upper case: </p> <p> <pre><span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;string</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">getUpper</span>&nbsp;(text&nbsp;:&nbsp;<span style="color:teal;">string</span>)&nbsp;=&nbsp;text.<span style="color:navy;">ToUpperInvariant</span>&nbsp;()</pre> </p> <p> Obviously, this function is so trivial that it's hardly worth testing, but remember to think about it as a stand-in for a more complex problem. It's a pure function, so it's easy to unit test: </p> <p> <pre>[&lt;<span style="color:teal;">Theory</span>&gt;] [&lt;<span style="color:teal;">InlineData</span>(<span style="color:#a31515;">&quot;foo&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;FOO&quot;</span>)&gt;] [&lt;<span style="color:teal;">InlineData</span>(<span style="color:#a31515;">&quot;bar&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;BAR&quot;</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``getUpper&nbsp;returns&nbsp;correct&nbsp;value``</span>&nbsp;input&nbsp;expected&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:navy;">getUpper</span>&nbsp;input &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;actual</pre> </p> <p> This test uses <a href="https://xunit.github.io">xUnit.net 2.1.0</a> and <a href="http://www.swensensoftware.com/unquote">Unquote 3.1.2</a>. The <code>=!</code> operator is a custom Unquote operator; you can read it as <em>must equal</em>; that is: <em>expected must equal actual</em>. It'll throw an exception if this isn't the case. </p> <p> <strong>Custom unions</strong> </p> <p> Languages like F# come with <a href="https://en.wikipedia.org/wiki/Algebraic_data_type">algebraic data types</a>, which means that in addition to complex structures, they also enable you to express types as <em>alternatives</em>. This means that you can represent a decision as one or more alternative <em>pure</em> values. </p> <p> Although the examples you'll see later in this article are simpler, I think it'll be helpful to start with an ad hoc solution to the problem. Here, the decision is to either read from a file, or return a default value. You can express that using a custom discriminated union: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">Action</span>&nbsp;=&nbsp;<span style="color:navy;">ReadFromFile</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span>&nbsp;|&nbsp;<span style="color:navy;">UseDefault</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span> </pre> </p> <p> This type models two mutually exclusive cases: either you decide to read from the file identified by a file path (<code>string</code>), or your return a default value (also modelled as a <code>string</code>). </p> <p> Using this <code>Action</code> type, you can write a <em>pure</em> function that makes the decision: </p> <p> <pre><span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;bool&nbsp;-&gt;&nbsp;Action</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">decide</span>&nbsp;path&nbsp;fileExists&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;fileExists &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:navy;">ReadFromFile</span>&nbsp;path &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:navy;">UseDefault</span>&nbsp;<span style="color:#a31515;">&quot;DEFAULT&quot;</span></pre> </p> <p> This function takes two arguments: <code>path</code> (a <code>string</code>) and <code>fileExists</code> (a <code>bool</code>). If <code>fileExists</code> is <code>true</code>, it returns the <code>ReadFromFile</code> case; otherwise, it returns the <code>UseDefault</code> case. </p> <p> Notice how this function neither checks whether the file exists, nor does it attempt to read the contents of the file. It only makes a decision based on input, and returns information about this decision as output. This function is <em>pure</em>, so (as I've claimed numerous times) is easy to unit test: </p> <p> <pre>[&lt;<span style="color:teal;">Theory</span>&gt;] [&lt;<span style="color:teal;">InlineData</span>(<span style="color:#a31515;">&quot;ploeh.txt&quot;</span>)&gt;] [&lt;<span style="color:teal;">InlineData</span>(<span style="color:#a31515;">&quot;fnaah.txt&quot;</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``decide&nbsp;returns&nbsp;correct&nbsp;result&nbsp;when&nbsp;file&nbsp;exists``</span>&nbsp;path&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:navy;">decide</span>&nbsp;path&nbsp;<span style="color:blue;">true</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">ReadFromFile</span>&nbsp;path&nbsp;=!&nbsp;actual [&lt;<span style="color:teal;">Theory</span>&gt;] [&lt;<span style="color:teal;">InlineData</span>(<span style="color:#a31515;">&quot;ploeh.txt&quot;</span>)&gt;] [&lt;<span style="color:teal;">InlineData</span>(<span style="color:#a31515;">&quot;fnaah.txt&quot;</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``decide&nbsp;returns&nbsp;correct&nbsp;result&nbsp;when&nbsp;file&nbsp;doesn&#39;t&nbsp;exist``</span>&nbsp;path&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:navy;">decide</span>&nbsp;path&nbsp;<span style="color:blue;">false</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">UseDefault</span>&nbsp;<span style="color:#a31515;">&quot;DEFAULT&quot;</span>&nbsp;=!&nbsp;actual</pre> </p> <p> One unit test function exercises the code path where the file exists, whereas the other test exercises the code path where it doesn't. Straightforward. </p> <p> There's still some remaining work, because you need to somehow compose your pure functions with <code>File.Exists</code> and <code>File.ReadAllText</code>. You also need a way to extract the string value from the two cases of <code>Action</code>. One way to do that is to introduce another pure function: </p> <p> <pre><span style="color:green;">//&nbsp;(string&nbsp;-&gt;&nbsp;string)&nbsp;-&gt;&nbsp;Action&nbsp;-&gt;&nbsp;string</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">getValue</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;">ReadFromFile</span>&nbsp;path&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">f</span>&nbsp;path &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">UseDefault</span>&nbsp;value&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;value</pre> </p> <p> This is a function that returns the <code>UseDefault</code> data for that case, but invokes a function <code>f</code> in the <code>ReadFromFile</code> case. Again, since this function is pure it's easy to unit test it, but I'll leave that as an exercise. </p> <p> You now have all the building blocks required to compose a function similar to the above <code>GetUpperText</code> C# method: </p> <p> <pre><span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;string</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">getUpperText</span>&nbsp;path&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;path &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">File</span>.<span style="color:navy;">Exists</span> &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">decide</span>&nbsp;path &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">getValue</span>&nbsp;(<span style="color:teal;">File</span>.<span style="color:navy;">ReadAllText</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">getUpper</span>)</pre> </p> <p> This implementation pipes <code>path</code> into <code>File.Exists</code>, which returns a Boolean value indicating whether the file exists. This Boolean value is then piped into <code>decide path</code>, which (as you may recall) returns an <code>Action</code>. That value is finally piped into <code>getValue (File.ReadAllText &gt;&gt; getUpper)</code>. Recall that <code>getValue</code> will only invoke the function argument when the <code>Action</code> is <code>ReadFromFile</code>, so <code>File.ReadAllText &gt;&gt; getUpper</code> is only executed in this case. </p> <p> Notice how decisions and effectful functions are interleaved. All the decision functions are covered by unit tests; only <code>File.Exists</code> and <code>File.ReadAllText</code> aren't covered, but I find it reasonable to treat these as humble functions. </p> <p> <strong>Either</strong> </p> <p> Normally, decisions often involve a choice between two alternatives. In the above example, you saw how the alternatives were named <code>ReadFromFile</code> and <code>UseDefault</code>. Since a choice between two alternatives is so common, there's a well-known 'pattern' that gives you general-purpose tools to model decisions. This is known as the <em>Either</em> monad. </p> <p> The F# core library doesn't (<a href="https://github.com/fsharp/FSharpLangDesign/blob/master/RFCs/FS-1004-result-type.md">yet</a>) come with an implementation of the Either monad, but it's easy to add. In this example, I'm using code from <a href="https://fsharpforfunandprofit.com">Scott Wlaschin's</a> <a href="https://fsharpforfunandprofit.com/posts/recipe-part2">railway-oriented programming</a>, although slightly modified, and including only the most essential building blocks for the example: </p> <p> <pre> <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">Result<'TSuccess, 'TFailure></span>&nbsp;= | Success <span style="color:blue;">of</span> 'TSuccess | Failure <span style="color:blue;">of</span> 'TFailure <span style="color:blue;">module</span>&nbsp;<span style="color:teal;">Result</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;Result&lt;&#39;b,&nbsp;&#39;c&gt;)&nbsp;-&gt;&nbsp;Result&lt;&#39;a,&nbsp;&#39;c&gt;&nbsp;-&gt;&nbsp;Result&lt;&#39;b,&nbsp;&#39;c&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">bind</span>&nbsp;<span style="color:navy;">f</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;succ&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">f</span>&nbsp;succ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;fail&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Failure</span>&nbsp;fail &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;Result&lt;&#39;a,&nbsp;&#39;c&gt;&nbsp;-&gt;&nbsp;Result&lt;&#39;b,&nbsp;&#39;c&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;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;succ&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Success</span>&nbsp;(<span style="color:navy;">f</span>&nbsp;succ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;fail&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Failure</span>&nbsp;fail &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;bool)&nbsp;-&gt;&nbsp;&#39;a&nbsp;-&gt;&nbsp;Result&lt;&#39;a,&nbsp;&#39;a&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">split</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x&nbsp;=&nbsp;<span style="color:blue;">if</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:navy;">Success</span>&nbsp;x&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:navy;">Failure</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;(&#39;c&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;Result&lt;&#39;a,&nbsp;&#39;c&gt;&nbsp;-&gt;&nbsp;&#39;b</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">either</span>&nbsp;<span style="color:navy;">f</span>&nbsp;<span style="color:navy;">g</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;succ&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">f</span>&nbsp;succ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;fail&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">g</span>&nbsp;fail</pre> </p> <p> In fact, the <code>bind</code> and <code>map</code> functions aren't even required for this particular example, but I included them anyway, because otherwise, readers already familiar with the Either monad would wonder why they weren't there. </p> <p> All these functions are generic and pure, so they are easy to unit test. I'm not going to show you the unit tests, however, as I consider the functions belonging to that <code>Result</code> module as reusable functions. This is a module that would ship as part of a well-tested library. In fact, <a href="https://github.com/fsharp/FSharpLangDesign/blob/master/RFCs/FS-1004-result-type.md">it'll soon be added to the F# core library</a>. </p> <p> With the already tested <code>getUpper</code> function, you now have all the building blocks required to implement the desired functionality: </p> <p> <pre><span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;string</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">getUpperText</span>&nbsp;path&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;path &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">split</span>&nbsp;<span style="color:teal;">File</span>.<span style="color:navy;">Exists</span> &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">either</span>&nbsp;(<span style="color:teal;">File</span>.<span style="color:navy;">ReadAllText</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">getUpper</span>)&nbsp;(<span style="color:blue;">fun</span>&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#a31515;">&quot;DEFAULT&quot;</span>)</pre> </p> <p> This composition pipes <code>path</code> into <code>Result.split</code>, which uses <code>File.Exists</code> as a predicate to decide whether the path should be packaged into a <code>Success</code> or <code>Failure</code> case. The resulting <code>Result&lt;string, string&gt;</code> is then piped into <code>Result.either</code>, which invokes <code>File.ReadAllText &gt;&gt; getUpper</code> in the <code>Success</code> case, and the anonymous function in the <code>Failure</code> case. </p> <p> Notice how, once again, the impure functions <code>File.Exists</code> and <code>File.ReadAllText</code> are used as humble functions, but interleaved with testable, pure functions that make all the decisions. </p> <p> <strong>Maybe</strong> </p> <p> Sometimes, a decision isn't so much between two alternatives as it's a decision between something that may exist, but also may not. You can model this with the <em>Maybe</em> monad, which in F# comes in the form of the built-in <code>option</code> type. </p> <p> In fact, so much is already built in (and tested by the F# development team) that you almost don't need to add anything yourself. The only function you could consider adding is this: </p> <p> <pre><span style="color:blue;">module</span>&nbsp;<span style="color:teal;">Option</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;&#39;a&nbsp;-&gt;&nbsp;&#39;a&nbsp;option&nbsp;-&gt;&nbsp;&#39;a</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">defaultIfNone</span>&nbsp;def&nbsp;x&nbsp;=&nbsp;<span style="color:navy;">defaultArg</span>&nbsp;x&nbsp;def</pre> </p> <p> As you can see, this function simply swaps the arguments for the built-in <code>defaultArg</code> function. This is done to make it more pipe-friendly. This function <a href="https://github.com/fsharp/FSharpLangDesign/blob/master/RFCs/FS-1007-additional-Option-module-functions.md">will most likely be added in a future version of F#</a>. </p> <p> That's all you need: </p> <p> <pre><span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;string</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">getUpperText</span>&nbsp;path&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;path &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">Some</span> &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Option</span>.<span style="color:navy;">filter</span>&nbsp;<span style="color:teal;">File</span>.<span style="color:navy;">Exists</span> &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Option</span>.<span style="color:navy;">map</span>&nbsp;(<span style="color:teal;">File</span>.<span style="color:navy;">ReadAllText</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">getUpper</span>) &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Option</span>.<span style="color:navy;">defaultIfNone</span>&nbsp;<span style="color:#a31515;">&quot;DEFAULT&quot;</span></pre> </p> <p> This composition starts with the <code>path</code>, puts it into a <code>Some</code> case, and pipes that <code>option</code> value into <code>Option.filter File.Exists</code>. This means that the <code>Some</code> case will only stay a <code>Some</code> value if the file exists; otherwise, it will be converted to a <code>None</code> value. Whatever the <code>option</code> value is, it's then piped into <code>Option.map (File.ReadAllText &gt;&gt; getUpper)</code>. The composed function <code>File.ReadAllText &gt;&gt; getUpper</code> is only executed in the <code>Some</code> case, so if the file doesn't exist, the function will not attempt to read it. Finally, the <code>option</code> value is piped into <code>Option.defaultIfNone</code>, which returns the mapped value, or <code>"DEFAULT"</code> if the value was <code>None</code>. </p> <p> Like in the two previous examples, the decision logic is implemented by pure functions, whereas the impure functions <code>File.Exists</code> and <code>File.ReadAllText</code> are handled as humble functions. </p> <p> <strong>Summary</strong> </p> <p> Have you noticed a pattern in all the three examples? Decisions are separated from effects using discriminated unions (both the above <code>Action</code>, <code>Result&lt;'TSuccess, 'TFailure&gt;</code>, and the built-in <code>option</code> are discriminated unions). In my experience, as long as you need to decide between two alternatives, the Either or Maybe monads are often sufficient to decouple decision logic from effects. Often, I don't even need to write any tests, because I compose my functions from the known, well-tested functions that belong to the respective monads. </p> <p> If your decision has to branch between three or more alternatives, you can consider a custom discriminated union. For this particular example, though, I think I prefer the third, Maybe-based composition, but closely followed by the Either-based composition. </p> <p> In this article, you saw three examples of how to decouple decision from effects; and I didn't even show you the <em>Free</em> monad! </p> </div> <div id="comments"> <hr> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="https://github.com/blainne">Grzegorz Sławecki</a></div> <div class="comment-content"> <p> Mark, </p> <p> I can't understand how can the <code>getValue</code> function be pure. While I agree that it's easy to test, it's still the higher order function and it's purity depends on the purity of function passed as the argument. Even in Your example it takes <code>File.ReadAllText&nbsp;&gt;&gt;&nbsp;getUpper</code> which actually reaches to a file on the disk and I perceive it as reaching to an external shared state. Is there something I misunderstood? </p> </div> <div class="comment-date">2016-10-14 09: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> Grzegorz, thank you for writing. You make a good point, and in a sense you're correct. F# doesn't enforce purity, and this is both an advantage and a disadvantage. It's an advantage because it makes it easier for programmers migrating from C# to make a gradual transition to a more functional programming style. It's also an advantage exactly because it relies on the programmer's often-faulty reasoning to ensure that code is properly functional. </p> <p> Functions in F# are only pure if they're implemented to be pure. For any given function type (signature) you can always create an impure function that fits the type. (If nothing else, you can always write "Hello, world!" to the console, before returning a value.) </p> <p> The result of this is that few parts of F# are pure in the sense that you imply. Even <code>List.map</code> could be impure, if passed an impure function. In other words, higher-order functions in F# are only pure if composed of exclusively pure parts. </p> <p> Clearly, this is in stark contrast to Haskell, where purity is enforced at the type level. In Haskell, a throw-away, poorly designed mini-API like the <code>Action</code> type and associated functions shown here wouldn't even compile. The Either and Maybe examples, on the other hand, would. </p> <p> My assumption here is that function composition happens at the edge of the application - that is, in an impure (<code>IO</code>) context. </p> </div> <div class="comment-date">2016-10-15 09:02 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>. Untyped F# HTTP route defaults for ASP.NET Web API http://blog.ploeh.dk/2016/08/09/untyped-f-http-route-defaults-for-aspnet-web-api 2016-08-09T04:24:00+00:00 Mark Seemann <div id="post"> <p> <em>In ASP.NET Web API, route defaults can be provided by a dictionary in F#.</em> </p> <p> When you define a route in ASP.NET Web API 2, you most likely use the <a href="https://msdn.microsoft.com/en-us/library/system.web.http.httproutecollectionextensions.maphttproute">MapHttpRoute</a> overload where you have to supply default values for the route template: </p> <p> <pre><span style="color:blue;">public static</span> IHttpRoute MapHttpRoute( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span> HttpRouteCollection routes, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span> name, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span> routeTemplate, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">object</span> defaults)</pre> </p> <p> The <code>defaults</code> arguments has the type <code>object</code>, but while the compiler will allow you to put any value here, the implicit <em>intent</em> is that in C#, you should pass an anonymous object with the route defaults. A standard route looks like this: </p> <p> <pre>configuration.Routes.MapHttpRoute( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;DefaultAPI&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;{controller}/{id}&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;{&nbsp;Controller&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Home&quot;</span>,&nbsp;Id&nbsp;=&nbsp;<span style="color:#2b91af;">RouteParameter</span>.Optional&nbsp;});</pre> </p> <p> Notice how the name of the properties (<code>Controller</code> and <code>Id</code>) (case-insensitively) match the place-holders in the route template (<code>{controller}</code> and <code>{id}</code>). </p> <p> While it's not clear from the type of the argument that this is what you're supposed to do, once you've learned it, it's easy enough to do, and rarely causes problems in C#. </p> <p> <strong>Flexibility</strong> </p> <p> You can debate the soundness of this API design, but as far as I can tell, it attempts to strike a balance between flexibility and syntax easy on the eyes. It does, for example, enable you to define a list of routes like this: </p> <p> <pre>configuration.Routes.MapHttpRoute( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;AvailabilityYear&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;availability/{year}&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;{&nbsp;Controller&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Availability&quot;</span>&nbsp;}); configuration.Routes.MapHttpRoute( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;AvailabilityMonth&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;availability/{year}/{month}&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;{&nbsp;Controller&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Availability&quot;</span>&nbsp;}); configuration.Routes.MapHttpRoute( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;AvailabilityDay&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;availability/{year}/{month}/{day}&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;{&nbsp;Controller&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Availability&quot;</span>&nbsp;}); configuration.Routes.MapHttpRoute( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;DefaultAPI&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;{controller}/{id}&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;{&nbsp;Controller&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Home&quot;</span>,&nbsp;Id&nbsp;=&nbsp;<span style="color:#2b91af;">RouteParameter</span>.Optional&nbsp;});</pre> </p> <p> In this example, there are three alternative routes to an <em>availability</em> resource, keyed on either an entire year, a month, or a single date. Since the route <em>templates</em> (e.g. <code>availability/{year}/{month}</code>) don't specify an <code>id</code> place-holder, there's no reason to provide a default value for it. On the other hand, it would have been possible to define defaults for the custom place-holders <code>year</code>, <code>month</code>, or <code>day</code>, if you had so desired. In this example, however, there are no defaults for these place-holders, so if values aren't provided, none of the <em>availability</em> routes are matched, and the request falls through to the <code>DefaultAPI</code> route. </p> <p> Since you can supply an anonymous object in C#, you can give it any property you'd like, and the code will still compile. There's no type safety involved, but using an anonymous object enables you to use a compact syntax. </p> <p> <strong>Route defaults in F#</strong> </p> <p> The API design of the MapHttpRoute method seems forged with C# in mind. I don't know how it works in Visual Basic .NET, but in F# there are no anonymous objects. How do you supply route defaults, then? </p> <p> As I described in my article on <a href="http://blog.ploeh.dk/2013/08/23/how-to-create-a-pure-f-aspnet-web-api-project">creating an F# Web API project</a>, you can define a record type: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:#4ec9b0;">HttpRouteDefaults</span>&nbsp;=&nbsp;{&nbsp;Controller&nbsp;:&nbsp;<span style="color:#4ec9b0;">string</span>;&nbsp;Id&nbsp;:&nbsp;<span style="color:#4ec9b0;">obj</span>&nbsp;} </pre> </p> <p> You can use it like this: </p> <p> <pre><span style="color:#4ec9b0;">GlobalConfiguration</span>.Configuration.Routes.<span style="color:navy;">MapHttpRoute</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;DefaultAPI&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;{controller}/{id}&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;Controller&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Home&quot;</span>;&nbsp;Id&nbsp;=&nbsp;<span style="color:#4ec9b0;">RouteParameter</span>.Optional&nbsp;})&nbsp;|&gt;&nbsp;<span style="color:navy;">ignore</span></pre> </p> <p> That works fine for <code>DefaultAPI</code>, but it's hardly flexible. You <em>must</em> supply both a <code>Controller</code> and a <code>Id</code> value. If you need to define routes like the <em>availability</em> routes above, you can't use this HttpRouteDefaults type, because you can't omit the <code>Id</code> value. </p> <p> While defining <em>another</em> record type is only a one-liner, you're confronted with the problem of naming these types. </p> <p> In C#, the use of anonymous objects is, despite appearances, an untyped approach. Could something similar be possible with F#? </p> <p> It turns out that the MapHttpRoute also works if you pass it an <code>IDictionary&lt;string, object&gt;</code>, which is possible in F#: </p> <p> <pre>config.Routes.MapHttpRoute( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;DefaultAPI&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;{controller}/{id}&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;dict&nbsp;[ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:#a31515;">&quot;Controller&quot;</span>,&nbsp;box&nbsp;<span style="color:#a31515;">&quot;Home&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:#a31515;">&quot;Id&quot;</span>,&nbsp;box&nbsp;RouteParameter.Optional)])&nbsp;|&gt;&nbsp;<span style="color:navy;">ignore</span></pre> </p> <p> While this looks more verbose than the previous alternative, it's more flexible. It's also <a href="http://c2.com/cgi/wiki?StringlyTyped">stringly typed</a>, which normally isn't an endorsement, but in this case is <em>honest</em>, because it's as strongly typed as the MapHttpRoute method. <a href="https://www.python.org/dev/peps/pep-0020">Explicit is better than implicit</a>. </p> <p> The complete route configuration corresponding to the above example would look like this: </p> <p> <pre>config.Routes.<span style="color:navy;">MapHttpRoute</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;AvailabilityYear&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;availability/{year}&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">dict</span>&nbsp;[(<span style="color:#a31515;">&quot;Controller&quot;</span>,&nbsp;<span style="color:navy;">box</span>&nbsp;<span style="color:#a31515;">&quot;Availability&quot;</span>)])&nbsp;|&gt;&nbsp;<span style="color:navy;">ignore</span> config.Routes.<span style="color:navy;">MapHttpRoute</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;AvailabilityMonth&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;availability/{year}/{month}&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">dict</span>&nbsp;[(<span style="color:#a31515;">&quot;Controller&quot;</span>,&nbsp;<span style="color:navy;">box</span>&nbsp;<span style="color:#a31515;">&quot;Availability&quot;</span>)])&nbsp;|&gt;&nbsp;<span style="color:navy;">ignore</span> config.Routes.<span style="color:navy;">MapHttpRoute</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;AvailabilityDay&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;availability/{year}/{month}/{day}&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">dict</span>&nbsp;[(<span style="color:#a31515;">&quot;Controller&quot;</span>,&nbsp;<span style="color:navy;">box</span>&nbsp;<span style="color:#a31515;">&quot;Availability&quot;</span>)])&nbsp;|&gt;&nbsp;<span style="color:navy;">ignore</span> config.Routes.<span style="color:navy;">MapHttpRoute</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;DefaultAPI&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;{controller}/{id}&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">dict</span>&nbsp;[ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:#a31515;">&quot;Controller&quot;</span>,&nbsp;<span style="color:navy;">box</span>&nbsp;<span style="color:#a31515;">&quot;Home&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:#a31515;">&quot;Id&quot;</span>,&nbsp;<span style="color:navy;">box</span>&nbsp;<span style="color:teal;">RouteParameter</span>.Optional)])&nbsp;|&gt;&nbsp;<span style="color:navy;">ignore</span></pre> </p> <p> If you're interested in learning more about developing ASP.NET Web API services in F#, watch my Pluralsight course <a href="http://bitly.com/functional-architecture-with-fsharp">A Functional Architecture with F#</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>. Conditional composition of functions http://blog.ploeh.dk/2016/07/04/conditional-composition-of-functions 2016-07-04T06:53:00+00:00 Mark Seemann <div id="post"> <p> <em>A major benefit of Functional Programming is the separation of decisions and (side-)effects. Sometimes, however, one decision ought to trigger an impure operation, and then proceed to make more decisions. Using functional composition, you can succinctly conditionally compose functions.</em> </p> <p> In my <a href="http://blog.ploeh.dk/2016/03/18/functional-architecture-is-ports-and-adapters">article on how Functional Architecture falls into the Ports and Adapters pit of success</a>, I describe how Haskell forces you to separate concerns: <ul> <li> Your Domain Model should be <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a>, with business decisions implemented by pure functions. Not only does it make it easier for you to reason about the business logic, it also has the side-benefit that <a href="http://blog.ploeh.dk/2015/05/07/functional-design-is-intrinsically-testable">pure functions are intrinsically testable</a>.</li> <li> Side-effects, and other impure operations (such as database queries) can be isolated and implemented as <a href="http://xunitpatterns.com/Humble%20Object.html">humble</a> functions. </li> </ul> A common pattern that you can often use is: <ol> <li>Read some data using an impure query.</li> <li>Pass that data to a pure function.</li> <li>Use the return value from the pure function to perform various side-effects. You could, for example, write data to a database, send an email, or update a user interface.</li> </ol> Sometimes, however, things are more complex. Based on the answer from one pure function, you may need to query an additional data source to gather extra data, call a second pure function, and so on. In this article, you'll see one way to accomplish this. </p> <p> <strong>Caravans for extra space</strong> </p> <p> Based on my <a href="http://blog.ploeh.dk/2016/03/18/functional-architecture-is-ports-and-adapters">previous restaurant-booking example</a>, <a href="https://github.com/MartinRykfors">Martin Rykfors</a> suggests "a new feature request. The restaurant has struck a deal with the local caravan dealership, allowing them to rent a caravan to park outside the restaurant in order to increase the seating capacity for one evening. Of course, sometimes there are no caravans available, so we'll need to query the caravan database to see if there is a big enough caravan available that evening:" </p> <p> <pre>findCaravan :: ServiceAddress -&gt; Int -&gt; ZonedTime -&gt; IO (Maybe Caravan)</pre> </p> <p> The above <code>findCaravan</code> is a slight modification of the function Martin suggests, because I imagine that the caravan dealership exposes their caravan booking system as a web service, so the function needs a service address as well. This change doesn't impact the proposed solution, though. </p> <p> This problem definition fits the above general problem statement: you'd only want to call the <code>findCaravan</code> function if <code>checkCapacity</code> returns <code>Left CapacityExceeded</code>. </p> <p> That's still a business decision, so you ought to implement it as a pure function. If you (for a moment) imagine that you have a <code>Maybe Caravan</code> instead of an <code>IO (Maybe Caravan)</code>, you have all the information required to make that decision: </p> <p> <pre>checkCaravanCapacityOnError :: Error -&gt; Maybe Caravan -&gt; Reservation -&gt; Either Error Reservation checkCaravanCapacityOnError CapacityExceeded (Just caravan) reservation = if caravanCapacity caravan &lt; quantity reservation then Left CapacityExceeded else Right reservation checkCaravanCapacityOnError err _ _ = Left err</pre> </p> <p> Notice that this function not only takes <code>Maybe Caravan</code>, it also takes an <code>Error</code> value. This encodes into the function's type that you should only call it if you have an <code>Error</code> that originates from a previous step. This <code>Error</code> value also enables the function to only check the caravan's capacity if the previous <code>Error</code> was a <code>CapacityExceeded</code>. <code>Error</code> can also be <code>ValidationError</code>, in which case there's no reason to check the caravan's capacity. </p> <p> This takes care of the Domain Model, but you still need to figure out how to get a <code>Maybe Caravan</code> value. Additionally, if <code>checkCaravanCapacityOnError</code> returns <code>Right Reservation</code>, you'd probably want to reserve the caravan for the evening. You can imagine that this is possible with the following function: </p> <p> <pre>reserveCaravan :: ServiceAddress -&gt; ZonedTime -&gt; Caravan -&gt; IO ()</pre> </p> <p> This function reserves the caravan at the supplied time. In order to keep the example simple, you can imagine that the provided <code>ZonedTime</code> indicates an entire day (or evening), and not just an instant. </p> <p> <strong>Composition of caravan-checking</strong> </p> <p> As a first step, you can compose an impure function that <ol> <li>Queries the caravan dealership for a caravan</li> <li>Calls the pure <code>checkCaravanCapacityOnError</code> function</li> <li>Reserves the caravan if the return value was <code>Right Reservation</code></li> </ol> Notice how these steps follow the impure-pure-impure pattern I described above. You can compose such a function like this: </p> <p> <pre>import Control.Monad (forM_) import Control.Monad.Trans (liftIO) import Control.Monad.Trans.Either (EitherT(..), hoistEither) checkCaravan :: Reservation -&gt; Error -&gt; EitherT Error IO Reservation checkCaravan reservation err = do c &lt;- liftIO $ findCaravan svcAddr (quantity reservation) (date reservation) newRes &lt;- hoistEither $ checkCaravanCapacityOnError err c reservation liftIO $ forM_ c $ reserveCaravan svcAddr (date newRes) return newRes</pre> </p> <p> It starts by calling <code>findCaravan</code> by closing over <code>svcAddr</code> (a <code>ServiceAddress</code> value). This is an impure operation, but you can use <code>liftIO</code> to make <code>c</code> a <code>Maybe Caravan</code> value that can be passed to <code>checkCaravanCapacityOnError</code> on the next line. This function returns <code>Either Error Reservation</code>, but since this function is defined in an <code>EitherT Error IO Reservation</code> context, <code>newRes</code> is a <code>Reservation</code> value. Still, it's important to realise that exactly because of this context, execution will short-circuit at that point if the return value from <code>checkCaravanCapacityOnError</code> is a <code>Left</code> value. In other words, all subsequent expression are only evaluated if <code>checkCaravanCapacityOnError</code> returns <code>Right</code>. This means that the <code>reserveCaravan</code> function is only called if a caravan with enough capacity is available. </p> <p> The <code>checkCaravan</code> function will <em>unconditionally</em> execute if called, so as the final composition step, you'll need to figure out how to compose it into the overall <code>postReservation</code> function in such a way that it's only called if <code>checkCapacity</code> returns <code>Left</code>. </p> <p> <strong>Conditional composition</strong> </p> <p> In the previous incarnation of this example, the overall entry point for the HTTP request in question was this <code>postReservation</code> function: </p> <p> <pre>postReservation :: ReservationRendition -&gt; IO (HttpResult ()) postReservation candidate = fmap toHttpResult $ runEitherT $ do r &lt;- hoistEither $ validateReservation candidate i &lt;- liftIO $ getReservedSeatsFromDB connStr $ date r hoistEither $ checkCapacity 10 i r &gt;&gt;= liftIO . saveReservation connStr</pre> </p> <p> Is it possible to compose <code>checkCaravan</code> into this function in such a way that it's only going to be executed if <code>checkCapacity</code> returns <code>Left</code>? Yes, by adding to the <code>hoistEither $ checkCapacity 10 i r</code> pipeline: </p> <p> <pre>import Control.Monad.Trans (liftIO) import Control.Monad.Trans.Either (EitherT(..), hoistEither, right, eitherT) postReservation :: ReservationRendition -&gt; IO (HttpResult ()) postReservation candidate = fmap toHttpResult $ runEitherT $ do r &lt;- hoistEither $ validateReservation candidate i &lt;- liftIO $ getReservedSeatsFromDB connStr $ date r eitherT (checkCaravan r) right $ hoistEither $ checkCapacity 10 i r &gt;&gt;= liftIO . saveReservation connStr</pre> </p> <p> Contrary to F#, you have to read Haskell pipelines from right to left. In the second-to-last line of code, you can see that I've added <code>eitherT (checkCaravan r) right</code> to the left of <code>hoistEither $ checkCapacity 10 i r</code>, which was already there. This means that, instead of binding the result of <code>hoistEither $ checkCapacity 10 i r</code> directly to the <code>saveReservation</code> composition (via the monadic <code>&gt;&gt;=</code> <em>bind</em> operator), that result is first passed to <code>eitherT (checkCaravan r) right</code>. </p> <p> The <code>eitherT</code> function composes two other functions: the leftmost function is invoked if the input is <code>Left</code>, and the right function is invoked if the input is <code>Right</code>. In this particular example, <code>(checkCaravan r)</code> is the closure being invoked in the <code>Left</code> - and only in the <code>Left</code> - case. In the <code>Right</code> case, the value is passed on unmodified, but elevated back into the <code>EitherT</code> context using the <code>right</code> function. </p> <p> (BTW, the above composition has a subtle bug: the capacity is still hard-coded as <code>10</code>, even though reserving extra caravans actually increases the overall capacity of the restaurant for the day. I'll leave it as an exercise for you to make the capacity take into account any reserved caravans. You can download <a href="https://gist.github.com/ploeh/c999e2ae2248bd44d775">all of the source code</a>, if you want to give it a try.) </p> <p> <strong>Interleaving</strong> </p> <p> Haskell has strong support for composition of functions. Not only can you interleave pure and impure code, but you can also do it <em>conditionally</em>. In the above example, the <code>eitherT</code> function holds the key to that. The overall flow of the <code>postReservation</code> function is: <ol> <li>Validate the input</li> <li>Get already reserved seats from the database</li> <li>Check the reservation request against the restaurant's remaining capacity</li> <li>If the capacity is exceeded, attempt to reserve a caravan of sufficient capacity</li> <li>If one of the previous steps decided that the restaurant has enough capacity, then save the reservation in the database</li> <li>Convert the result (whether it's <code>Left</code> or <code>Right</code>) to an HTTP response</li> </ol> Programmers who are used to implementing such solutions using C#, Java, or similar languages, may feel hesitant by delegating a branching decision to a piece of composition code, instead of something they can unit test. </p> <p> Haskell's type system is remarkably helpful here. Haskell programmers often joke that <em>if it compiles, it works</em>, and there's a morsel of truth in that sentiment. Both functions used with <code>eitherT</code> must return a value of the same type, but the left function <em>must</em> be a function that takes the <code>Left</code> type as input, whereas the right function <em>must</em> be a function that takes the <code>Right</code> type as input. In the above example, <code>(checkCaravan r)</code> is a partially applied function with the type <code>Error -&gt; EitherT Error IO Reservation</code>; that is: the input type is <code>Error</code>, so it can only be composed with an <code>Either Error a</code> value. That matches the return type of <code>checkCapacity 10 i r</code>, so the code compiles, but if I accidentally switch the arguments to <code>eitherT</code>, it doesn't compile. </p> <p> I find it captivating to figure out how to 'click' together such interleaving functions using the composition functions that Haskell provides. Often, when the composition compiles, it works as intended. </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> This is something of a tangent, but I wanted to hint to you that Haskell can help reduce the boilerplate it takes to compose monadic computations like this. </p> <p> The <a href="https://hackage.haskell.org/package/mtl-2.2.1/docs/Control-Monad-Except.html#t:MonadError"><code>MonadError</code></a> class abstracts monads which support throwing and catching errors. If you don't specify the concrete monad (transformer stack) a computation lives in, it's easier to compose it into a larger environment. </p> <p> <pre>checkCaravanCapacityOnError :: MonadError Error m =&gt; Error -&gt; Maybe Caravan -&gt; Reservation -&gt; m Reservation checkCaravanCapacityOnError CapacityExceeded (Just caravan) reservation | caravanCapacity caravan &lt; quantity reservation = throwError CapacityExceeded | otherwise = return reservation checkCaravanCapacityOnError err _ _ = throwError err</pre> </p> <p> I'm programming to the interface, not the implementation, by using <code>throwError</code> and <code>return</code> instead of <code>Left</code> and <code>Right</code>. This allows me to dispense with calls to <code>hoistEither</code> when I come to call my function in the context of a bigger monad: </p> <p> <pre>findCaravan :: MonadIO m =&gt; ServiceAddress -&gt; Int -&gt; ZonedTime -&gt; m (Maybe Caravan) reserveCaravan :: MonadIO m =&gt; ServiceAddress -&gt; ZonedTime -&gt; m () checkCaravan :: (MonadIO m, MonadError Error m) =&gt; Reservation -&gt; Error -&gt; m Reservation checkCaravan reservation err = do c &lt;- findCaravan svcAddr (quantity reservation) (date reservation) newRes &lt;- checkCaravanCapacityOnError err c reservation traverse_ (reserveCaravan svcAddr (date newRes)) c return newRes</pre> </p> <p> Note how <code>findCaravan</code> and <code>reserveCaravan</code> only declare a <code>MonadIO</code> constraint, whereas <code>checkCaravan</code> needs to do both IO and error handling. The type class system lets you declare the capabilities you need from your monad without specifying the monad in question. The elaborator figures out the right number of calls to <code>lift</code> when it builds the <code>MonadError</code> dictionary, which is determined by the concrete type you choose for <code>m</code> at the edge of your system. </p> <p> A logical next step here would be to further constrain the effects that a given IO function can perform. In this example, I'd consider writing a separate class for monads which support calling the caravan service: <code>findCaravan :: MonadCaravanService m =&gt; ServiceAddress -&gt; Int -&gt; ZonedTime -&gt; m (Maybe Caravan)</code>. This ensures that <code>findCaravan</code> can <i>only</i> call the caravan service, and not perform any other IO. It also makes it easier to mock functions which call the caravan service by writing a fake instance of <code>MonadCaravanService</code>. </p> <p> F# doesn't support this style of programming because it lacks higher-kinded types. You can't abstract over <code>m</code>; you have to pick a concrete monad up-front. This is bad for code reuse: if you need to add (for example) runtime configuration to your application you have to rewrite the implementation of your monad, and potentially every function which uses it, rather than just tacking on a <code>MonadReader</code> constraint to the functions that need it and adding a call to <code>runReaderT</code> at the entry point to your application. </p> <p> Finally, monad transformers are but one style of effect typing; <a href="http://okmij.org/ftp/Haskell/extensible/more.pdf"><code>extensible-effects</code></a> is an alternative which is gaining popularity. </p> </div> <div class="comment-date">2016-07-04 12:05 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://github.com/MartinRykfors">Martin Rykfors</a></div> <div class="comment-content"> <p> Hi Mark, </p> <p> Thank you very much for the elaborate explanation. I'm also delighted that you stuck with my admittedly contrived example of using caravans to compensate for the restaurant's lack of space. Or is that nothing compared to some of the stranger real-life feature requests some of us have seen? </p> <p> I agree with your point on my previous comment that my suggestion could be considered a leaky abstraction and would introduce unnecessary requirements to the implementation. It just feels strange to let go of the idea that the domain logic is to be unconditionally pure, and not just mostly pure with the occasional impure function passed in as an argument. It's like what you say towards the end of the post - I feel hesitant to mix branching code and composition code together. The resulting solution you propose here is giving me second thoughts though. The <code>postReservation</code> function didn't become much more complex as I'd feared, with the branching logic nicely delegated to the <code>eitherT</code> function. The caravan logic also gets its own composition function that is easy enough to understand on its own. I guess I've got some thinking to do. </p> <p> So, a final question regarding this example: To what extent would you apply this technique when solving the same problem in F#? It seems that we are using an increasing amount of Haskell language features not present in F#, so maybe not everything would translate over cleanly. </p> </div> <div class="comment-date">2016-07-04 19: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> Martin, I'm still experimenting with how that influences my F# code. I'd like to at least attempt to back-port something like this to F# using computation expressions, but it may turn out that it's not worth the effort. </p> </div> <div class="comment-date">2016-07-04 20:46 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>. Roman numerals via property-based TDD http://blog.ploeh.dk/2016/06/28/roman-numerals-via-property-based-tdd 2016-06-28T07:28:00+00:00 Mark Seemann <div id="post"> <p> <em>An example of doing the Roman numerals kata with property-based test-driven development.</em> </p> <p> The <em>Roman numerals</em> kata is a simple programming exercise. You should implement conversion to and from <a href="https://en.wikipedia.org/wiki/Roman_numerals">Roman numerals</a>. This always struck me as the ultimate case for example-driven development, but I must also admit that I've managed to get stuck on the exercise doing exactly that: throwing more and more examples at the problem. Prompted by previous successes with property-based testing, I wondered whether the problem would be more tractable if approached with property-based testing. This turned out to be the case. </p> <p> <strong>Single values</strong> </p> <p> When modelling a problem with property-based testing, you should attempt to express it in terms of general rules, but even so, the fundamental rule of Roman numerals is that there are certain singular symbols that have particular numeric values. There are no overall principles guiding these relationships; they simply are. Therefore, you'll still need to express these singular values as particular values. This is best done with a simple parametrised test, here using <a href="http://xunit.github.io">xUnit.net 2.1</a>: </p> <p> <pre>[&lt;<span style="color:#4ec9b0;">Theory</span>&gt;] [&lt;<span style="color:#4ec9b0;">InlineData</span>(<span style="color:#a31515;">&quot;I&quot;</span>,&nbsp;&nbsp;&nbsp;&nbsp;1)&gt;] [&lt;<span style="color:#4ec9b0;">InlineData</span>(<span style="color:#a31515;">&quot;V&quot;</span>,&nbsp;&nbsp;&nbsp;&nbsp;5)&gt;] [&lt;<span style="color:#4ec9b0;">InlineData</span>(<span style="color:#a31515;">&quot;X&quot;</span>,&nbsp;&nbsp;&nbsp;10)&gt;] [&lt;<span style="color:#4ec9b0;">InlineData</span>(<span style="color:#a31515;">&quot;L&quot;</span>,&nbsp;&nbsp;&nbsp;50)&gt;] [&lt;<span style="color:#4ec9b0;">InlineData</span>(<span style="color:#a31515;">&quot;C&quot;</span>,&nbsp;&nbsp;100)&gt;] [&lt;<span style="color:#4ec9b0;">InlineData</span>(<span style="color:#a31515;">&quot;D&quot;</span>,&nbsp;&nbsp;500)&gt;] [&lt;<span style="color:#4ec9b0;">InlineData</span>(<span style="color:#a31515;">&quot;M&quot;</span>,&nbsp;1000)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``elemental&nbsp;symbols&nbsp;have&nbsp;correct&nbsp;values``</span>&nbsp;(symbol&nbsp;:&nbsp;<span style="color:#4ec9b0;">string</span>)&nbsp;expected&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">Some</span>&nbsp;expected&nbsp;=!&nbsp;<span style="color:#4ec9b0;">Numeral</span>.<span style="color:navy;">tryParseRoman</span>&nbsp;symbol</pre> </p> <p> The <code>=!</code> operator is a custom operator defined by <a href="http://www.swensensoftware.com/unquote">Unquote</a> (3.1.1), an assertion library. You can read it as <em>must equal</em>; that is, you can read this particular assertion as <em>some expected must equal tryParseRoman symbol</em>. </p> <p> As you can see, this simple test expresses the relationship between the singular Roman numeral values and their decimal counterparts. You might still consider this automated test as example-driven, but I more think about it as establishing the ground rules for how Roman numerals work. If you look at <a href="https://en.wikipedia.org/wiki/Roman_numerals#Roman_numeric_system">the Wikipedia article</a>, for instance, it also starts explaining the system by listing the values of these seven symbols. </p> <p> <strong>Round-tripping</strong> </p> <p> A common technique when applying property-based testing to parsing problems is to require that values can round-trip. This should also be the case here: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;romanRange&nbsp;=&nbsp;<span style="color:#4ec9b0;">Gen</span>.<span style="color:navy;">elements</span>&nbsp;[1..3999]&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">Arb</span>.<span style="color:navy;">fromGen</span> [&lt;<span style="color:#4ec9b0;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``tryParse&nbsp;is&nbsp;the&nbsp;inverse&nbsp;of&nbsp;toRoman``</span>&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#4ec9b0;">Prop</span>.<span style="color:navy;">forAll</span>&nbsp;romanRange&nbsp;&lt;|&nbsp;<span style="color:blue;">fun</span>&nbsp;i&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="color:navy;background:yellow;">Some</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">i</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">=</span><span style="background:yellow;">&nbsp;(</span><span style="background:yellow;">i</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:#4ec9b0;background:yellow;">Numeral</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">toRoman</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;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:#4ec9b0;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">bind</span><span style="background:yellow;">&nbsp;</span><span style="color:#4ec9b0;background:yellow;">Numeral</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">tryParseRoman</span><span style="background:yellow;">)&nbsp;@&gt;</span></pre> </p> <p> This property uses <a href="http://fscheck.github.io/FsCheck">FsCheck</a> (2.2.4). First, it expresses a range of relevant integers. For various reasons (that we'll return to) we're only going to attempt conversion of the integers between 1 and 3,999. The value <code>romanRange</code> has the type Arbitrary&lt;int&gt;, where Arbitrary&lt;'a&gt; is a type defined by FsCheck. You can think of it as a generator of random values. In this case, <code>romanRange</code> generates random integers between 1 and 3,999. </p> <p> When used with Prop.forAll, the property states that for all values drawn from romanRange, the anonymous function should succeed. The <code>i</code> argument within that anonymous function is populated by <code>romanRange</code>, and the function is executed 100 times (by default). </p> <p> The <code>test</code> function is another Unquote function. It evaluates and reports on the quoted boolean expression; if it evaluates to true, nothing happens, but it throws an exception if it evaluates to false. </p> <p> The particular expression states that if you call toRoman with <code>i</code>, and then call tryParseRoman with the return value of that function call, the result should be equal to <code>i</code>. Both sides should be wrapped in a Some case, though, since both toRoman and tryParseRoman might also return None. For the values in romanRange, however, you'd expect that the round-trip always succeeds. </p> <p> <strong>Additivity</strong> </p> <p> The fundamental idea about Roman numerals is that they are additive: I means 1, II means (1 + 1 =) 2, XXX means (10 + 10 + 10 =) 30, and MLXVI means (1000 + 50 + 10 + 5 + 1 =) 1066. You simply count and add. Yes, there are special rules for subtractive shorthand, but forget about those for a moment. If you have a Roman numeral with symbols in strictly descending order, you can simply add the symbol values together. </p> <p> You can express this with FsCheck. It looks a little daunting, but actually isn't that bad. I'll show it first, and then walk you through it: </p> <p> <pre>[&lt;<span style="color:#4ec9b0;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``symbols&nbsp;in&nbsp;descending&nbsp;order&nbsp;are&nbsp;additive``</span>&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">stringRepeat</span>&nbsp;char&nbsp;count&nbsp;=&nbsp;<span style="color:#4ec9b0;">String</span>&nbsp;(char,&nbsp;count) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">genSymbols</span>&nbsp;count&nbsp;symbol&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[0..count]&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">List</span>.<span style="color:navy;">map</span>&nbsp;(<span style="color:navy;">stringRepeat</span>&nbsp;symbol)&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">Gen</span>.<span style="color:navy;">elements</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;thousands&nbsp;=&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">genSymbols</span>&nbsp;3&nbsp;<span style="color:#a31515;">&#39;M&#39;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;fiveHundreds&nbsp;=&nbsp;<span style="color:navy;">genSymbols</span>&nbsp;1&nbsp;<span style="color:#a31515;">&#39;D&#39;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;hundreds&nbsp;=&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">genSymbols</span>&nbsp;3&nbsp;<span style="color:#a31515;">&#39;C&#39;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;fifties&nbsp;=&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">genSymbols</span>&nbsp;1&nbsp;<span style="color:#a31515;">&#39;L&#39;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;tens&nbsp;=&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">genSymbols</span>&nbsp;3&nbsp;<span style="color:#a31515;">&#39;X&#39;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;fives&nbsp;=&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">genSymbols</span>&nbsp;1&nbsp;<span style="color:#a31515;">&#39;V&#39;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;ones&nbsp;=&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">genSymbols</span>&nbsp;3&nbsp;<span style="color:#a31515;">&#39;I&#39;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;symbols&nbsp;=&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[thousands;&nbsp;fiveHundreds;&nbsp;hundreds;&nbsp;fifties;&nbsp;tens;&nbsp;fives;&nbsp;ones] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">Gen</span>.<span style="color:navy;">sequence</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">Gen</span>.<span style="color:navy;">map</span>&nbsp;<span style="color:#4ec9b0;">String</span>.<span style="color:navy;">Concat</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">Arb</span>.<span style="color:navy;">fromGen</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#4ec9b0;">Prop</span>.<span style="color:navy;">forAll</span>&nbsp;symbols&nbsp;&lt;|&nbsp;<span style="color:blue;">fun</span>&nbsp;s&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:#4ec9b0;">Numeral</span>.<span style="color:navy;">tryParseRoman</span>&nbsp;s &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;expected&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;s &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">Seq</span>.<span style="color:navy;">map</span>&nbsp;(<span style="color:navy;">string</span>&nbsp;&gt;&gt;&nbsp;<span style="color:#4ec9b0;">Numeral</span>.<span style="color:navy;">tryParseRoman</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">Seq</span>.<span style="color:navy;">choose</span>&nbsp;<span style="color:navy;">id</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">Seq</span>.<span style="color:navy;">sum</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">Some</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;actual</pre> </p> <p> The first two lines are two utility functions. The function <code>stringRepeat</code> has the type <code>char -&gt; int -&gt; string</code>. It simply provides a curried form of the String constructor overload that enables you to repeat a particular char value. As an example, <code>stringRepeat 'I' 0</code> is "", <code>stringRepeat 'X' 2</code> is "XX", and so on. </p> <p> The function <code>genSymbols</code> has the type <code>int -&gt; char -&gt; Gen&lt;string&gt;</code>. It returns a generator that produces a repeated string no longer than the specified length. Thus, <code>genSymbols 3 'M'</code> is a generator that draws random values from the set [""; "M"; "MM"; "MMM"], <code>genSymbols 1 'D'</code> is a generator that draws random values from the set [""; "D"], and so on. Notice that the empty string is one of the values that the generator may use. This is by design. </p> <p> Using genSymbols, you can define generators for all the symbols: up to three thousands, up to one five hundreds, up to three hundreds, etc. <code>thousands</code>, <code>fiveHundreds</code>, <code>hundreds</code>, and so on, are all values of the type Gen&lt;string&gt;. </p> <p> You can combine all these string generators to a single generator using Gen.sequence, which takes a seq&lt;Gen&lt;'a&gt;&gt; as input and returns a Gen&lt;'a list&gt;. In this case, the input is [thousands; fiveHundreds; hundreds; fifties; tens; fives; ones], which has the type <code>Gen&lt;string&gt; list</code>, so the output is a <code>Gen&lt;string list&gt;</code> value. Values generated could include ["MM"; ""; ""; ""; "X"; ""; ""], [""; "D"; "CC"; "L"; "X"; "V"; ""], and so on. </p> <p> Instead of lists of strings, you need single string values. These are easy to create using the built-in method String.Concat. You have to do it within a Gen value, though, so it's <code>Gen.map String.Concat</code>. Finally, you can convert the resulting Gen&lt;string&gt; to an Arbitrary using Arb.fromGen. The final <code>symbols</code> value has the type Arbitrary&lt;string&gt;. It'll generate values such as "MMX" and "DCCLXV". </p> <p> This is a bit of work to ensure that proper Roman numerals are generated, but the rest of the property is tractable. You can use FsCheck's Prop.forAll to express the property that when tryParseRoman is called with any of the generated numerals, the return value is equal to the expected value. </p> <p> The expected value is the sum of the value of each of the symbols in the input string, <code>s</code>. The <code>string</code> type implements the interface <code>char seq</code>, so you can map each of the characters by invoking tryParseRoman. That gives you a <cdata>seq&lt;int option&gt;</cdata>, because tryParseRoman returns <code>int option</code> values. You can use <code>Seq.choose id</code> to throw away any None values there may be, and then <code>Seq.sum</code> to calculate the sum of the integers. Finally, you can pipe the sum into the Some case constructor to turn <code>expected</code> into an <code>int option</code>, which matches the type of <code>actual</code>. </p> <p> Now that you have <code>expected</code> and <code>actual</code> values, you can assert that these two values must be equal to each other. This property states that for all strictly descending numerals, the return value must be the sum of the constituent symbols. </p> <p> <strong>Subtractiveness</strong> </p> <p> The principal rule for Roman numerals is that of additivity, but if you only apply the above rules, you'd allow numerals such as IIII for 4, LXXXX for 90, etc. While there's historical precedent for such notation, it's not allowed in 'modern' Roman numerals. If there are more than three repeated characters, you should instead prefer subtractive notation: IV for 4, XC for 90, and so on. </p> <p> Subtractive notation is, however, only allowed within adjacent groups. Logically, you could write 1999 as MIM, but this isn't allowed. The symbol I can only be used to subtract from V and X, X can only subtract from L and C, and C can only subtract from D and M. </p> <p> Within these constraints, you have to describe the property of subtractive notation. Here's one way to do it: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:#4ec9b0;">OptionBuilder</span>()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Bind</span>(v,&nbsp;<span style="color:navy;">f</span>)&nbsp;=&nbsp;<span style="color:#4ec9b0;">Option</span>.<span style="color:navy;">bind</span>&nbsp;<span style="color:navy;">f</span>&nbsp;v &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Return</span>&nbsp;v&nbsp;=&nbsp;<span style="color:navy;">Some</span>&nbsp;v <span style="color:blue;">let</span>&nbsp;opt&nbsp;=&nbsp;<span style="color:#4ec9b0;">OptionBuilder</span>() [&lt;<span style="color:#4ec9b0;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``certain&nbsp;symbols&nbsp;in&nbsp;ascending&nbsp;are&nbsp;subtractive``</span>&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">subtractive</span>&nbsp;(subtrahend&nbsp;:&nbsp;<span style="color:#4ec9b0;">char</span>)&nbsp;(minuends&nbsp;:&nbsp;<span style="color:#4ec9b0;">string</span>)&nbsp;=&nbsp;<span style="color:blue;">gen</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;minuend&nbsp;=&nbsp;<span style="color:#4ec9b0;">Gen</span>.<span style="color:navy;">elements</span>&nbsp;minuends &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;subtrahend,&nbsp;minuend&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;symbols&nbsp;=&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#4ec9b0;">Gen</span>.<span style="color:navy;">oneof</span>&nbsp;[ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">subtractive</span>&nbsp;<span style="color:#a31515;">&#39;I&#39;</span>&nbsp;<span style="color:#a31515;">&quot;VX&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">subtractive</span>&nbsp;<span style="color:#a31515;">&#39;X&#39;</span>&nbsp;<span style="color:#a31515;">&quot;LC&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">subtractive</span>&nbsp;<span style="color:#a31515;">&#39;C&#39;</span>&nbsp;<span style="color:#a31515;">&quot;DM&quot;</span>&nbsp;] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">Arb</span>.<span style="color:navy;">fromGen</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#4ec9b0;">Prop</span>.<span style="color:navy;">forAll</span>&nbsp;symbols&nbsp;&lt;|&nbsp;<span style="color:blue;">fun</span>&nbsp;(subtrahend,&nbsp;minuend)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;originalRoman&nbsp;=&nbsp;<span style="color:#4ec9b0;">String</span>&nbsp;[|&nbsp;subtrahend;&nbsp;minuend&nbsp;|] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:#4ec9b0;">Numeral</span>.<span style="color:navy;">tryParseRoman</span>&nbsp;originalRoman &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;roundTrippedRoman&nbsp;=&nbsp;actual&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">Option</span>.<span style="color:navy;">bind</span>&nbsp;<span style="color:#4ec9b0;">Numeral</span>.<span style="color:navy;">toRoman</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;expected&nbsp;=&nbsp;<span style="color:blue;">opt</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;m&nbsp;=&nbsp;<span style="color:#4ec9b0;">Numeral</span>.<span style="color:navy;">tryParseRoman</span>&nbsp;(<span style="color:navy;">string</span>&nbsp;minuend) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;s&nbsp;=&nbsp;<span style="color:#4ec9b0;">Numeral</span>.<span style="color:navy;">tryParseRoman</span>&nbsp;(<span style="color:navy;">string</span>&nbsp;subtrahend) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;m&nbsp;-&nbsp;s&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;actual &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">Some</span>&nbsp;originalRoman&nbsp;=!&nbsp;roundTrippedRoman</pre> </p> <p> Like the previous property, this looks like a mouthful, but isn't too bad. I'll walk you through it. </p> <p> Initially, ignore the OptionBuilder type and the opt value; we'll return to them shortly. The property itself starts by defining a function called <code>subtractive</code>, which has the type <code>char -&gt; string -&gt; Gen&lt;char * char&gt;</code>. The first argument is a symbol representing <a href="https://en.wikipedia.org/wiki/Subtraction">the subtrahend</a>; that is: the number being subtracted. The next argument is a sequence of minuends; that is: numbers from which the subtrahend will be subtracted. </p> <p> The <code>subtractive</code> function is implemented with a <code>gen</code> computation expression. It first uses a <code>let!</code> binding to define that a singular minuend is a random value drawn from <code>minuends</code>. As usual, Gen.elements is the workhorse: it defines a generator that randomly draws from a sequence of values, and because <code>minuends</code> is a string, and the string type implements <code>char seq</code>, it can be used with Gen.elements to define a generator of char values. While <code>Gen.elements minuends</code> returns a Gen&lt;char&gt; value, the use of a <code>let!</code> binding within a computation expression causes <code>minuend</code> to have the type <code>char</code>. </p> <p> The second line of code in <code>subtractive</code> returns a tuple of two char values: the subtrahend first, and the minuend second. Normally, when subtracting with the arithmetic minus operator, you'd write a difference as <em>minuend - subtrahend</em>; the minuends comes first, followed by the subtrahend. The Roman subtractive notation, however, is written with the subtrahend before the minuend, which is the reason that the <code>subtractive</code> function returns the symbols in that order. It's easier to think about that way. </p> <p> The <code>subtractive</code> function enables you to define generators of Roman numerals using subtractive notation. Since I can only be used before V and X, you can define a generator using <code>subtractive 'I' "VX"</code>. This is a Gen&lt;char * char&gt; value. Likewise, you can define <code>subtractive 'X' "LC"</code> and <code>subtractive 'C' "DM"</code> and use Gen.oneOf to define a generator that randomly selects one of these generators, and uses the selected generator to produce a value. As always, the last step is to convert the generator into an Arbitrary with Arb.fromGen, so that <code>symbols</code> has the type Arbitrary&lt;char * char&gt;. </p> <p> Equipped with an Arbitrary, you can again use Prop.forAll to express the desired property. First, <code>originalRoman</code> is created from the subtrahend and minuend. Due to the way <code>symbols</code> is defined, <code>originalRoman</code> will have values like "IV", "XC", and so on. </p> <p> The property then proceeds to invoke tryParseRoman. It also uses the <code>actual</code> value to produce a round-tripped value. Not only should the parser correctly understand subtractive notation, but the integer-to-Roman conversion should also prefer this notation. </p> <p> The last part of the property is the assertion. Here, you need <code>opt</code>, which is a <a href="https://msdn.microsoft.com/en-us/library/dd233182.aspx">computation builder</a> for option values. </p> <p> In the assertion, you need to calculate the expected value. Both minuend and subtrahend are char values; in order to find their corresponding decimal values, you'll need to call tryParseRoman. The problem is that tryParseRoman returns an <code>int option</code>. For example, <code>tryParseRoman "I"</code> returns <code>Some 1</code>, so you may need to subtract <code>Some 1</code> from <code>Some 5</code>. The most readable way I've found is to use a computation expression. Using <code>let!</code> bindings, both <code>m</code> and <code>s</code> are <code>int</code> values, which you can easily subtract using the normal <code>-</code> operator. </p> <p> <code>expected</code> and <code>actual</code> are both <code>int option</code> values, so can be compared using Unquote's <em>must equal</em> operator. </p> <p> Finally, the property also asserts that the original value must be equal to the round-tripped value. If not, you could have an implementation that correctly parses "IV" as 4, but converts 4 to "IIII". </p> <p> <strong>Limited repetition</strong> </p> <p> The previous property only ensures that subtractive notation is used in simple cases, like IX or CD. It doesn't verify that composite numerals are correctly written. As an example, the converter should convert 1893 to MDCCCXCIII, not MDCCCLXXXXIII. The second alternative is incorrect because it uses LXXXX to represent 90, instead of XC. </p> <p> The underlying property is that any given symbol can only be repeated at most three times. A symbol can appear more than thrice in total, as demonstrated by the valid numeral MDCCCXCIII, in which C appears four times. For any group of repeated characters, however, a character must only be repeated once, twice, or thrice. </p> <p> This also explain why the maximum Roman numeral is MMMCMXCIX, or 3,999. </p> <p> In order to express this property in code, you first need a function to group characters. Here, I've chosen to reuse <a href="http://stackoverflow.com/a/35055165/126014">one of my own creation</a>: </p> <p> <pre><span style="color:green;">//&nbsp;seq&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;&#39;a&nbsp;list&nbsp;list&nbsp;when&nbsp;&#39;a&nbsp;:&nbsp;equality</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">group</span>&nbsp;xs&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">folder</span>&nbsp;x&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;[]&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;[[x]] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;(h<span style="color:navy;">::</span>t)<span style="color:navy;">::</span>ta&nbsp;<span style="color:blue;">when</span>&nbsp;h&nbsp;=&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;(x<span style="color:navy;">::</span>h<span style="color:navy;">::</span>t)<span style="color:navy;">::</span>ta &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;acc&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;[x]<span style="color:navy;">::</span>acc &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#4ec9b0;">Seq</span>.<span style="color:navy;">foldBack</span>&nbsp;<span style="color:navy;">folder</span>&nbsp;xs&nbsp;[]</pre> </p> <p> This function will, for example, group "MDCCCXCIII" like this: </p> <p> <pre>&gt; "MDCCCXCIII" |&gt; group;; val it : char list list = [['M']; ['D']; ['C'; 'C'; 'C']; ['X']; ['C']; ['I'; 'I'; 'I']]</pre> </p> <p> All you need to do is to find the length of all such sub-lists, and assert that the maximum is at most 3: </p> <p> <pre>[&lt;<span style="color:#4ec9b0;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``there&nbsp;can&nbsp;be&nbsp;no&nbsp;more&nbsp;than&nbsp;three&nbsp;identical&nbsp;symbols&nbsp;in&nbsp;a&nbsp;row``</span>&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#4ec9b0;">Prop</span>.<span style="color:navy;">forAll</span>&nbsp;romanRange&nbsp;&lt;|&nbsp;<span style="color:blue;">fun</span>&nbsp;i&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:#4ec9b0;">Numeral</span>.<span style="color:navy;">toRoman</span>&nbsp;i &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="background:yellow;">actual</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:#4ec9b0;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">map</span><span style="background:yellow;">&nbsp;(</span><span style="color:navy;background:yellow;">group</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">&gt;&gt;</span><span style="background:yellow;">&nbsp;(</span><span style="color:#4ec9b0;background:yellow;">List</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">map</span><span style="background:yellow;">&nbsp;</span><span style="color:#4ec9b0;background:yellow;">List</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">length</span><span style="background:yellow;">)&nbsp;</span><span style="background:yellow;">&gt;&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:#4ec9b0;background:yellow;">List</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">max</span><span style="background:yellow;">)</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:#4ec9b0;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">exists</span><span style="background:yellow;">&nbsp;(</span><span style="color:blue;background:yellow;">fun</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">x</span><span style="background:yellow;">&nbsp;</span><span style="color:blue;background:yellow;">-&gt;</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">x</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">&lt;=</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">3</span><span style="background:yellow;">)&nbsp;@&gt;</span></pre> </p> <p> Since <code>actual</code> is a <code>string option</code>, you need to express the assertion within the Maybe (Option) monad. First, you can use Option.map to map any value (should there be one) to find the maximum length of any repeated character group. This returns an <code>int option</code>. </p> <p> Finally, you can pipe that <code>int option</code> into Option.exists, which will evaluate to false if there's no value, or if the boolean expression <code>x &lt;= 3</code> evaluates to false. </p> <p> <strong>Input range</strong> </p> <p> At this point, you're almost done. The only remaining properties you'll need to specify is that the maximum value is 3,999, and the minimum value is 1. Negative numbers, or zero, are not allowed: </p> <p> <pre>[&lt;<span style="color:#4ec9b0;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``negative&nbsp;numbers&nbsp;and&nbsp;zero&nbsp;are&nbsp;not&nbsp;supported``</span>&nbsp;i&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;i&nbsp;=&nbsp;-(<span style="color:navy;">abs</span>&nbsp;i) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:#4ec9b0;">Numeral</span>.<span style="color:navy;">toRoman</span>&nbsp;i &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="color:#4ec9b0;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">isNone</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">actual</span><span style="background:yellow;">&nbsp;@&gt;</span></pre> </p> <p> In this property, the function argument <code>i</code> can be <em>any</em> number, but calling <code>abs</code> ensures that it's positive (or zero), and the unary <code>-</code> operator then converts that positive value to a negative value. </p> <p> Notice that the new <code>i</code> value shadows the input argument of the same name. This is <a href="http://blog.ploeh.dk/2016/02/15/types-properties-software-properties-for-the-forties">a common trick when writing properties</a>. It prevents me from accidentally using the input value provided by FsCheck. While the input argument is useful as a seed value, it isn't guaranteed to model the particular circumstances of this property. Here, you only care to assert what happens if the input is negative or zero. Specifically, you always want the return value to be None. </p> <p> Likewise for too large input values: </p> <p> <pre>[&lt;<span style="color:#4ec9b0;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``numbers&nbsp;too&nbsp;big&nbsp;are&nbsp;not&nbsp;supported``</span>&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#4ec9b0;">Gen</span>.<span style="color:navy;">choose</span>&nbsp;(4000,&nbsp;<span style="color:#4ec9b0;">Int32</span>.MaxValue)&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">Arb</span>.<span style="color:navy;">fromGen</span>&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">Prop</span>.<span style="color:navy;">forAll</span>&nbsp;&lt;|&nbsp;<span style="color:blue;">fun</span>&nbsp;i&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:#4ec9b0;">Numeral</span>.<span style="color:navy;">toRoman</span>&nbsp;i &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="color:#4ec9b0;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">isNone</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">actual</span><span style="background:yellow;">&nbsp;@&gt;</span></pre> </p> <p> Here, Gen.choose is used to define an Arbitrary&lt;int&gt; that only produces numbers between 4000 and Int32.MaxValue (including both boundary values). </p> <p> This test is similar to the one that exercises negative values, so you could combine them to a single function if you'd like. I'll leave this as an exercise, though. </p> <p> <strong>Implementation</strong> </p> <p> The interesting part of this exercise is, I think, how to define the properties. There are many ways you can implement the functions to pass all properties. Here's one of them: </p> <p> <pre><span style="color:blue;">open</span>&nbsp;System <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">tryParseRoman</span>&nbsp;candidate&nbsp;=&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">add</span>&nbsp;x&nbsp;=&nbsp;<span style="color:#4ec9b0;">Option</span>.<span style="color:navy;">map</span>&nbsp;((+)&nbsp;x) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;acc&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:#a31515;">&#39;I&#39;</span><span style="color:navy;">::</span><span style="color:#a31515;">&#39;X&#39;</span><span style="color:navy;">::</span>xs&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(acc&nbsp;|&gt;&nbsp;<span style="color:navy;">add</span>&nbsp;&nbsp;&nbsp;&nbsp;9)&nbsp;xs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:#a31515;">&#39;I&#39;</span><span style="color:navy;">::</span><span style="color:#a31515;">&#39;V&#39;</span><span style="color:navy;">::</span>xs&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(acc&nbsp;|&gt;&nbsp;<span style="color:navy;">add</span>&nbsp;&nbsp;&nbsp;&nbsp;4)&nbsp;xs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:#a31515;">&#39;I&#39;</span><span style="color:navy;">::</span>xs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(acc&nbsp;|&gt;&nbsp;<span style="color:navy;">add</span>&nbsp;&nbsp;&nbsp;&nbsp;1)&nbsp;xs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:#a31515;">&#39;V&#39;</span><span style="color:navy;">::</span>xs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(acc&nbsp;|&gt;&nbsp;<span style="color:navy;">add</span>&nbsp;&nbsp;&nbsp;&nbsp;5)&nbsp;xs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:#a31515;">&#39;X&#39;</span><span style="color:navy;">::</span><span style="color:#a31515;">&#39;C&#39;</span><span style="color:navy;">::</span>xs&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(acc&nbsp;|&gt;&nbsp;<span style="color:navy;">add</span>&nbsp;&nbsp;&nbsp;90)&nbsp;xs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:#a31515;">&#39;X&#39;</span><span style="color:navy;">::</span><span style="color:#a31515;">&#39;L&#39;</span><span style="color:navy;">::</span>xs&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(acc&nbsp;|&gt;&nbsp;<span style="color:navy;">add</span>&nbsp;&nbsp;&nbsp;40)&nbsp;xs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:#a31515;">&#39;X&#39;</span><span style="color:navy;">::</span>xs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(acc&nbsp;|&gt;&nbsp;<span style="color:navy;">add</span>&nbsp;&nbsp;&nbsp;10)&nbsp;xs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:#a31515;">&#39;L&#39;</span><span style="color:navy;">::</span>xs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(acc&nbsp;|&gt;&nbsp;<span style="color:navy;">add</span>&nbsp;&nbsp;&nbsp;50)&nbsp;xs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:#a31515;">&#39;C&#39;</span><span style="color:navy;">::</span><span style="color:#a31515;">&#39;M&#39;</span><span style="color:navy;">::</span>xs&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(acc&nbsp;|&gt;&nbsp;<span style="color:navy;">add</span>&nbsp;&nbsp;900)&nbsp;xs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:#a31515;">&#39;C&#39;</span><span style="color:navy;">::</span><span style="color:#a31515;">&#39;D&#39;</span><span style="color:navy;">::</span>xs&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(acc&nbsp;|&gt;&nbsp;<span style="color:navy;">add</span>&nbsp;&nbsp;400)&nbsp;xs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:#a31515;">&#39;C&#39;</span><span style="color:navy;">::</span>xs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(acc&nbsp;|&gt;&nbsp;<span style="color:navy;">add</span>&nbsp;&nbsp;100)&nbsp;xs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:#a31515;">&#39;D&#39;</span><span style="color:navy;">::</span>xs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(acc&nbsp;|&gt;&nbsp;<span style="color:navy;">add</span>&nbsp;&nbsp;500)&nbsp;xs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:#a31515;">&#39;M&#39;</span><span style="color:navy;">::</span>xs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(acc&nbsp;|&gt;&nbsp;<span style="color:navy;">add</span>&nbsp;1000)&nbsp;xs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;[]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;acc &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;">-&gt;</span>&nbsp;<span style="color:navy;">None</span> &nbsp;&nbsp;&nbsp;&nbsp;candidate&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">Seq</span>.<span style="color:navy;">toList</span>&nbsp;|&gt;&nbsp;<span style="color:navy;">imp</span>&nbsp;(<span style="color:navy;">Some</span>&nbsp;0) <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">toRoman</span>&nbsp;i&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;acc&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;x&nbsp;<span style="color:blue;">when</span>&nbsp;x&nbsp;&gt;=&nbsp;1000&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(<span style="color:#a31515;">&#39;M&#39;</span><span style="color:navy;">::</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acc)&nbsp;(x&nbsp;-&nbsp;1000) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;x&nbsp;<span style="color:blue;">when</span>&nbsp;x&nbsp;&gt;=&nbsp;&nbsp;900&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(<span style="color:#a31515;">&#39;M&#39;</span><span style="color:navy;">::</span><span style="color:#a31515;">&#39;C&#39;</span><span style="color:navy;">::</span>acc)&nbsp;(x&nbsp;-&nbsp;&nbsp;900) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;x&nbsp;<span style="color:blue;">when</span>&nbsp;x&nbsp;&gt;=&nbsp;&nbsp;500&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(<span style="color:#a31515;">&#39;D&#39;</span><span style="color:navy;">::</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acc)&nbsp;(x&nbsp;-&nbsp;&nbsp;500) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;x&nbsp;<span style="color:blue;">when</span>&nbsp;x&nbsp;&gt;=&nbsp;&nbsp;400&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(<span style="color:#a31515;">&#39;D&#39;</span><span style="color:navy;">::</span><span style="color:#a31515;">&#39;C&#39;</span><span style="color:navy;">::</span>acc)&nbsp;(x&nbsp;-&nbsp;&nbsp;400) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;x&nbsp;<span style="color:blue;">when</span>&nbsp;x&nbsp;&gt;=&nbsp;&nbsp;100&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(<span style="color:#a31515;">&#39;C&#39;</span><span style="color:navy;">::</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acc)&nbsp;(x&nbsp;-&nbsp;&nbsp;100) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;x&nbsp;<span style="color:blue;">when</span>&nbsp;x&nbsp;&gt;=&nbsp;&nbsp;&nbsp;90&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(<span style="color:#a31515;">&#39;C&#39;</span><span style="color:navy;">::</span><span style="color:#a31515;">&#39;X&#39;</span><span style="color:navy;">::</span>acc)&nbsp;(x&nbsp;-&nbsp;&nbsp;&nbsp;90) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;x&nbsp;<span style="color:blue;">when</span>&nbsp;x&nbsp;&gt;=&nbsp;&nbsp;&nbsp;50&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(<span style="color:#a31515;">&#39;L&#39;</span><span style="color:navy;">::</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acc)&nbsp;(x&nbsp;-&nbsp;&nbsp;&nbsp;50) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;x&nbsp;<span style="color:blue;">when</span>&nbsp;x&nbsp;&gt;=&nbsp;&nbsp;&nbsp;40&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(<span style="color:#a31515;">&#39;L&#39;</span><span style="color:navy;">::</span><span style="color:#a31515;">&#39;X&#39;</span><span style="color:navy;">::</span>acc)&nbsp;(x&nbsp;-&nbsp;&nbsp;&nbsp;40) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;x&nbsp;<span style="color:blue;">when</span>&nbsp;x&nbsp;&gt;=&nbsp;&nbsp;&nbsp;10&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(<span style="color:#a31515;">&#39;X&#39;</span><span style="color:navy;">::</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acc)&nbsp;(x&nbsp;-&nbsp;&nbsp;&nbsp;10) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;x&nbsp;<span style="color:blue;">when</span>&nbsp;x&nbsp;&gt;=&nbsp;&nbsp;&nbsp;&nbsp;9&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(<span style="color:#a31515;">&#39;X&#39;</span><span style="color:navy;">::</span><span style="color:#a31515;">&#39;I&#39;</span><span style="color:navy;">::</span>acc)&nbsp;(x&nbsp;-&nbsp;&nbsp;&nbsp;&nbsp;9) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;x&nbsp;<span style="color:blue;">when</span>&nbsp;x&nbsp;&gt;=&nbsp;&nbsp;&nbsp;&nbsp;5&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(<span style="color:#a31515;">&#39;V&#39;</span><span style="color:navy;">::</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acc)&nbsp;(x&nbsp;-&nbsp;&nbsp;&nbsp;&nbsp;5) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;x&nbsp;<span style="color:blue;">when</span>&nbsp;x&nbsp;&gt;=&nbsp;&nbsp;&nbsp;&nbsp;4&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(<span style="color:#a31515;">&#39;V&#39;</span><span style="color:navy;">::</span><span style="color:#a31515;">&#39;I&#39;</span><span style="color:navy;">::</span>acc)&nbsp;(x&nbsp;-&nbsp;&nbsp;&nbsp;&nbsp;4) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;x&nbsp;<span style="color:blue;">when</span>&nbsp;x&nbsp;&gt;=&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;(<span style="color:#a31515;">&#39;I&#39;</span><span style="color:navy;">::</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acc)&nbsp;(x&nbsp;-&nbsp;&nbsp;&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;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;acc &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;0&nbsp;&lt;&nbsp;i&nbsp;&amp;&amp;&nbsp;i&nbsp;&lt;&nbsp;4000 &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;[]&nbsp;i&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">List</span>.<span style="color:navy;">rev</span>&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">List</span>.<span style="color:navy;">toArray</span>&nbsp;|&gt;&nbsp;<span style="color:#4ec9b0;">String</span>&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> Both functions use <a href="http://blog.ploeh.dk/2015/12/22/tail-recurse">tail-recursive inner <code>imp</code> functions</a> in order to accumulate the appropriate answer. </p> <p> One of the nice properties (that I didn't test for) of this implementation is that the tryParseRoman function is a <a href="http://martinfowler.com/bliki/TolerantReader.html">Tolerant Reader</a>. While toRoman would never create such a numeral, tryParseRoman correctly understands some alternative renderings: </p> <p> <pre>&gt; "MDCCCLXXXXIII" |&gt; tryParseRoman;; val it : int option = Some 1893 &gt; 1893 |&gt; toRoman;; val it : String option = Some "MDCCCXCIII"</pre> </p> <p> In other words, the implementation follows <a href="https://en.wikipedia.org/wiki/Robustness_principle">Postel's law</a>. tryParseRoman is liberal in what it accepts, while toRoman is conservative in what it returns. </p> <p> <strong>Summary</strong> </p> <p> Some problems look, at first glance, as obvious candidates for example-driven development. In my experience, this particularly happen when obvious examples abound. It's not difficult to come up with examples of Roman numerals, so it seems intuitive that you should just start writing some test cases with various examples. In my experience, though, that doesn't guarantee that you're led towards a good implementation. </p> <p> The more a problem description is based on examples, the harder it can be to identify the underlying properties. Still, they're often there, once you start looking. As I've <a href="http://blog.ploeh.dk/2015/01/10/diamond-kata-with-fscheck">previously reported</a>, using property-based test-driven development enables you to proceed in a more incremental fashion, because properties describe only parts of the desired solution. </p> <p> If you're interested in learning more about Property-Based Testing, you can watch my <a href="http://bit.ly/1M1zXTf">introduction to Property-based Testing with F#</a> Pluralsight course. </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>. SUT Double http://blog.ploeh.dk/2016/06/15/sut-double 2016-06-15T18:01:00+00:00 Mark Seemann <div id="post"> <p> <em>While it's possible to rely on Extract and Override for unit testing, Dependency Injection can make code and tests simpler and easier to maintain.</em> </p> <p> In object-oriented programming, many people still struggle with the intersection of design and testability. If a unit test is <em>an automated test of a unit in isolation of its dependencies</em>, then how do you isolate an object from its dependencies, most notably databases, web services, and the like? </p> <p> One technique, described in <a href="http://amzn.to/1ygZ4Jv">The Art of Unit Testing</a>, is called <em>Extract and Override</em>. The idea is that you write a class, but use a <a href="https://en.wikipedia.org/wiki/Template_method_pattern">Template Method</a>, <a href="https://en.wikipedia.org/wiki/Factory_method_pattern">Factory Method</a>, or other sort of virtual class method to expose extensibility points that a unit test can use to achieve the desired isolation. </p> <p> People sometimes ask me whether that isn't good enough, and why <a href="http://amzn.to/12p90MG">I advocate the (ostensibly) more complex technique of Dependency Injection</a>? </p> <p> It's easiest to understand the advantages and disadvantages if we have an example to discuss. </p> <p> <strong>Example: Extract and Override</strong> </p> <p> Imagine that you're creating a reservation system for a restaurant. Clients (web sites, smart phone apps, etcetera) display a user interface where you can fill in details about your reservation: your name, email address, the number of guests, and the date of your reservation. When you submit your reservation request, the client POSTs a JSON document to a web service. </p> <p> In this example, the web service is implemented by a Controller class, and the Post method handles the incoming request: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;Capacity&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} <span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IHttpActionResult</span>&nbsp;Post(<span style="color:#2b91af;">ReservationDto</span>&nbsp;reservationDto) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">DateTime</span>&nbsp;requestedDate; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>(!<span style="color:#2b91af;">DateTime</span>.TryParse(reservationDto.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;requestedDate)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.BadRequest(<span style="color:#a31515;">&quot;Invalid&nbsp;date.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;reservedSeats&nbsp;=&nbsp;<span style="color:blue;">this</span>.ReadReservedSeats(requestedDate); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>(<span style="color:blue;">this</span>.Capacity&nbsp;&lt;&nbsp;reservationDto.Quantity&nbsp;+&nbsp;reservedSeats) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.StatusCode(<span style="color:#2b91af;">HttpStatusCode</span>.Forbidden); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.SaveReservation(requestedDate,&nbsp;reservationDto); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.Ok(); }</pre> </p> <p> The implementation is simple: It first attempts to validate the incoming document, and returns an error message if the document is invalid. Second, it reads the number of already reserved seats via a helper method, and rejects the request if the remaining capacity is insufficient. On the other hand, if the remaining capacity is sufficient, it saves the reservation and returns 200 OK. </p> <p> The Post method relies on two helper methods that handles communication with the database: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">virtual</span>&nbsp;<span style="color:blue;">int</span>&nbsp;ReadReservedSeats(<span style="color:#2b91af;">DateTime</span>&nbsp;date) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">const</span>&nbsp;<span style="color:blue;">string</span>&nbsp;sql&nbsp;=&nbsp;<span style="color:maroon;">@&quot; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SELECT&nbsp;COALESCE(SUM([Quantity]),&nbsp;0)&nbsp;FROM&nbsp;[dbo].[Reservations] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;WHERE&nbsp;YEAR([Date])&nbsp;=&nbsp;YEAR(@Date) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;AND&nbsp;MONTH([Date])&nbsp;=&nbsp;MONTH(@Date) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;AND&nbsp;DAY([Date])&nbsp;=&nbsp;DAY(@Date)&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;connStr&nbsp;=&nbsp;<span style="color:#2b91af;">ConfigurationManager</span>.ConnectionStrings[<span style="color:#a31515;">&quot;booking&quot;</span>] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.ConnectionString; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">using</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;conn&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlConnection</span>(connStr)) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">using</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;cmd&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlCommand</span>(sql,&nbsp;conn)) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cmd.Parameters.Add(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Date&quot;</span>,&nbsp;date)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;conn.Open(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;(<span style="color:blue;">int</span>)cmd.ExecuteScalar(); &nbsp;&nbsp;&nbsp;&nbsp;} } <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">virtual</span>&nbsp;<span style="color:blue;">void</span>&nbsp;SaveReservation( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">DateTime</span>&nbsp;dateTime, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">ReservationDto</span>&nbsp;reservationDto) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">const</span>&nbsp;<span style="color:blue;">string</span>&nbsp;sql&nbsp;=&nbsp;<span style="color:maroon;">@&quot; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;INSERT&nbsp;INTO&nbsp;[dbo].[Reservations]&nbsp;([Date],&nbsp;[Name],&nbsp;[Email],&nbsp;[Quantity]) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;VALUES&nbsp;(@Date,&nbsp;@Name,&nbsp;@Email,&nbsp;@Quantity)&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;connStr&nbsp;=&nbsp;<span style="color:#2b91af;">ConfigurationManager</span>.ConnectionStrings[<span style="color:#a31515;">&quot;booking&quot;</span>] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.ConnectionString; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">using</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;conn&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlConnection</span>(connStr)) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">using</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;cmd&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlCommand</span>(sql,&nbsp;conn)) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cmd.Parameters.Add( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Date&quot;</span>,&nbsp;reservationDto.Date)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cmd.Parameters.Add( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Name&quot;</span>,&nbsp;reservationDto.Name)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cmd.Parameters.Add( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Email&quot;</span>,&nbsp;reservationDto.Email)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cmd.Parameters.Add( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Quantity&quot;</span>,&nbsp;reservationDto.Quantity)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;conn.Open(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cmd.ExecuteNonQuery(); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> In this example, both helper methods are <code>public</code>, but they could have been <code>protected</code> without changing any conclusions; by being <code>public</code>, though, they're easier to override using <a href="http://www.moqthis.com">Moq</a>. The important detail is that both of these methods are overridable. In C#, you declare that with the <code>virtual</code> keyword; in Java, methods are overridable by default. </p> <p> Both of these methods use elemental ADO.NET to communicate with the database. You can also use an ORM, or any other database access technique you prefer - it doesn't matter for this discussion. What matters is that the methods can be overridden by unit tests. </p> <p> Here's a unit test of the happy path: </p> <p> <pre>[<span style="color:#2b91af;">Fact</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;PostReturnsCorrectResultAndHasCorrectStateOnAcceptableRequest() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;json&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ReservationDto</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;Date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2016-05-31&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Mark&nbsp;Seemann&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Email&nbsp;=&nbsp;<span style="color:#a31515;">&quot;mark@example.com&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;1 &nbsp;&nbsp;&nbsp;&nbsp;&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:blue;">new</span>&nbsp;<span style="color:#2b91af;">Mock</span>&lt;<span style="color:#2b91af;">ReservationsController</span>&gt;&nbsp;{&nbsp;CallBase&nbsp;=&nbsp;<span style="color:blue;">true</span>&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;sut &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Setup(s&nbsp;=&gt;&nbsp;s.ReadReservedSeats(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2016,&nbsp;5,&nbsp;31))) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Returns(0); &nbsp;&nbsp;&nbsp;&nbsp;sut &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Setup(s&nbsp;=&gt;&nbsp;s.SaveReservation(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2016,&nbsp;5,&nbsp;31),&nbsp;json)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Verifiable(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;actual&nbsp;=&nbsp;sut.Object.Post(json); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.IsAssignableFrom&lt;<span style="color:#2b91af;">OkResult</span>&gt;(actual); &nbsp;&nbsp;&nbsp;&nbsp;sut.Verify(); }</pre> </p> <p> This example uses the Extract and Override technique, but instead of creating a test-specific class that derives from ReservationsController, it uses Moq to create a dynamic <a href="http://www.martinfowler.com/bliki/TestDouble.html">Test Double</a> for the System Under Test (<a href="https://en.wikipedia.org/wiki/System_under_test">SUT</a>) - a SUT Double. </p> <p> Since both <code>ReadReservedSeats</code> and <code>SaveReservation</code> are virtual, Moq can override them with test-specific behaviour. In this test, it defines the behaviour of <code>ReadReservedSeats</code> in such a way that it returns <code>0</code> when the input is a particular date. </p> <p> While the test is simple, it has a single blemish. It ought to follow the Arrange Act Assert pattern, so it shouldn't have to configure the <code>SaveReservation</code> method <em>before</em> it calls the the <code>Post</code> method. After all, the <code>SaveReservation</code> method is a Command, and you should use <a href="http://blog.ploeh.dk/2013/10/23/mocks-for-commands-stubs-for-queries">Mocks for Commands</a>. In other words, the test ought to verify the interaction with the <code>SaveReservation</code> method in the Assert phase; not configure it in the Arrange phase. </p> <p> Unfortunately, if you don't configure the <code>SaveReservation</code> method before calling <code>Post</code>, Moq will use the base implementation, which will attempt to interact with the database. The database isn't available in the unit test context, so without that override, the base method will throw an exception, causing the test to fail. </p> <p> Still, that's a minor issue. In general, the test is easy to follow, and the design of the ReservationsController class itself is also straightforward. Are there any downsides? </p> <p> <strong>Example: shared connection</strong> </p> <p> From a design perspective, the above version is fine, but you may find it inefficient that <code>ReadReservedSeats</code> and <code>SaveReservation</code> both open and close a connection to the database. Wouldn't it be more efficient if they could share a single connection? </p> <p> If (<a href="https://ericlippert.com/2012/12/17/performance-rant">by measuring</a>) you decide that you'd like to refactor the ReservationsController class to use a shared connection, your first attempt might look like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IHttpActionResult</span>&nbsp;Post(<span style="color:#2b91af;">ReservationDto</span>&nbsp;reservationDto) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">DateTime</span>&nbsp;requestedDate; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(!<span style="color:#2b91af;">DateTime</span>.TryParse(reservationDto.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;requestedDate)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.BadRequest(<span style="color:#a31515;">&quot;Invalid&nbsp;date.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">using</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;conn&nbsp;=&nbsp;<span style="color:blue;">this</span>.OpenDbConnection()) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;reservedSeats&nbsp;=&nbsp;<span style="color:blue;">this</span>.ReadReservedSeats(conn,&nbsp;requestedDate); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(<span style="color:blue;">this</span>.Capacity&nbsp;&lt;&nbsp;reservationDto.Quantity&nbsp;+&nbsp;reservedSeats) &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>.StatusCode(<span style="color:#2b91af;">HttpStatusCode</span>.Forbidden); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.SaveReservation(conn,&nbsp;requestedDate,&nbsp;reservationDto); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.Ok(); &nbsp;&nbsp;&nbsp;&nbsp;} } <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">virtual</span>&nbsp;<span style="color:#2b91af;">SqlConnection</span>&nbsp;OpenDbConnection() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;connStr&nbsp;=&nbsp;<span style="color:#2b91af;">ConfigurationManager</span>.ConnectionStrings[<span style="color:#a31515;">&quot;booking&quot;</span>] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.ConnectionString; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;conn&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlConnection</span>(connStr); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">try</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;conn.Open(); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">catch</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;conn.Dispose(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;conn; } <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">virtual</span>&nbsp;<span style="color:blue;">int</span>&nbsp;ReadReservedSeats(<span style="color:#2b91af;">SqlConnection</span>&nbsp;conn,&nbsp;<span style="color:#2b91af;">DateTime</span>&nbsp;date) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">const</span>&nbsp;<span style="color:blue;">string</span>&nbsp;sql&nbsp;=&nbsp;<span style="color:maroon;">@&quot; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SELECT&nbsp;COALESCE(SUM([Quantity]),&nbsp;0)&nbsp;FROM&nbsp;[dbo].[Reservations] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;WHERE&nbsp;YEAR([Date])&nbsp;=&nbsp;YEAR(@Date) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;AND&nbsp;MONTH([Date])&nbsp;=&nbsp;MONTH(@Date) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;AND&nbsp;DAY([Date])&nbsp;=&nbsp;DAY(@Date)&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">using</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;cmd&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlCommand</span>(sql,&nbsp;conn)) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cmd.Parameters.Add(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Date&quot;</span>,&nbsp;date)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;(<span style="color:blue;">int</span>)cmd.ExecuteScalar(); &nbsp;&nbsp;&nbsp;&nbsp;} } <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">virtual</span>&nbsp;<span style="color:blue;">void</span>&nbsp;SaveReservation( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">SqlConnection</span>&nbsp;conn, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">DateTime</span>&nbsp;dateTime, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">ReservationDto</span>&nbsp;reservationDto) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">const</span>&nbsp;<span style="color:blue;">string</span>&nbsp;sql&nbsp;=&nbsp;<span style="color:maroon;">@&quot; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;INSERT&nbsp;INTO&nbsp;[dbo].[Reservations]&nbsp;([Date],&nbsp;[Name],&nbsp;[Email],&nbsp;[Quantity]) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;VALUES&nbsp;(@Date,&nbsp;@Name,&nbsp;@Email,&nbsp;@Quantity)&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">using</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;cmd&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlCommand</span>(sql,&nbsp;conn)) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cmd.Parameters.Add( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Date&quot;</span>,&nbsp;reservationDto.Date)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cmd.Parameters.Add( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Name&quot;</span>,&nbsp;reservationDto.Name)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cmd.Parameters.Add( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Email&quot;</span>,&nbsp;reservationDto.Email)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cmd.Parameters.Add( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Quantity&quot;</span>,&nbsp;reservationDto.Quantity)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cmd.ExecuteNonQuery(); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> You've changed both <code>ReadReservedSeats</code> and <code>SaveReservation</code> to take an extra parameter: the connection to the database. That connection is created by the <code>OpenDbConnection</code> method, but you also have to make that method overridable, because otherwise, it'd attempt to connect to a database during unit testing, and thereby causing the tests to fail. </p> <p> You can still unit test using the Extract and Overide technique, but the test becomes more com