## Monday, April 6, 2015

### Mathematical APIs

You can use mathematical APIs to smooth the onboarding process for new users of your library by reusing their existing intuition for algebraic operations.

Let's use an example from my `turtle` library for shell scripting, which uses the `Shell Text` type to represent a stream of lines. You can forward such a stream to the console using `stdout`:

``stdout :: Shell Text -> IO ()``

Thanks to Haskell's `OverloadedStrings` extension, we can use a string literal to encode a 1-element stream that emits just that one string literal:

``````>>> :set -XOverloadedStrings
>>> import Turtle
>>> stdout "Hello, world!"
Hello, world
>>>``````

Now let's drop a thin mathematical API on top of these streams so that we can treat streams like ordinary numbers. These examples will only work with `turtle-1.1.0` and later.

If we add streams, we concatenate their elements in order. Here we concatenate three 1-element streams to generate a combined 3-element stream:

``````>>> stdout ("Line 1" + "Line 2" + "Line 3")
Line 1
Line 2
Line 3
>>>``````

`0` will be the empty stream:

``````>>> stdout 0
>>> -- This prints nothing``````

`1` is a stream that emits a single empty string:

``````>>> stdout 1

>>>``````

So what is 2? Well, it stands to reason that 2 must be 1 + 1:

``````>>> stdout 2

>>> stdout (1 + 1) -- Same thing

>>>``````

Similarly, 3 must be 1 + 1 + 1:

``````>>> stdout 3

>>>``````

... and so forth.

If we multiply two 1-element streams, we generate a new 1-element stream that concatenates their strings.

``````>>> stdout ("123" * "456")
123456
>>>``````

Now what do you think will happen if I do this?

``````>>> let x = "Line 1" + "Line 2"  -- A stream with two elements
>>> let y = "Line A" + "Line B"  -- A stream with two elements
>>> stdout (x * ", " * y)        -- What this will print?``````

First we substitute `x` and `y` with their definitions:

``````x * ", " * y

= ("Line 1" + "Line 2") * ", " * ("Line A" + "Line B")``````

Then we expand out the multiplication to get four terms:

``````= "Line 1" * ", " * "Line A"
+ "Line 1" * ", " * "Line B"
+ "Line 2" * ", " * "Line A"
+ "Line 2" * ", " * "Line B"``````

Then we use the rule that multiplying 1-element streams just concatenates their strings:

``````= "Line 1, Line A"
+ "Line 1, Line B"
+ "Line 2, Line A"
+ "Line 2, Line B"``````

... and there's our final result! We expect our stream to have four elements, one for each permutation of elements from the left and right streams.

Let's verify that:

``````>>> stdout (x * ", " * y)
Line 1, Line A
Line 1, Line B
Line 2, Line A
Line 2, Line B``````

We can even leverage our algebraic intuition when working with impure streams:

``````>>> stdout (stdin * ("!" + "?"))
Test<Enter>
Test!
Test?
ABC<Enter>
ABC!
ABC?
...``````

This is why I love mathematical APIs: they are concise, general, and expressive.

People judge programming languages using mindshare, but the mindshare of mathematics dwarfs all programming languages combined. By specifying programs mathematically we can unlock a large and latent pool of programming talent.