Let's write a database (part 4)

Unknown — Sun, 07 Sep 2025 00:00:00 +0000

Hello, hello, hello. Welcome to part four of this adventure where we're making a database by hand. In part three we did some joins, and today we're doing to do some limiting.</p>

If you'd like to look at the code, it's right here</a>.</p>

No no, no no no no, no no no no, no no, there's no limits</h2>

Limit is very straightforward, it's used to control the amount of data we get back from a query.</p>

select </span>* </span>from</span> albums </span>limit </span>10
</span></code></pre>
...will get 10 items from the albums table. To help decide how we choose which</em> 10, we'll need ordering which will come next.</p>
We add a new Limit</code> to the Query</code> type, containing the following:</p>
pub struct </span>Limit {
</span>    </span>pub </span>from</span>: Box<Query>,
</span>    </span>pub </span>limit</span>: </span>u64</span>,
</span>}
</span></code></pre>
Then we add this to our run_query</code> function:</p>
Query::Limit(Limit { limit, from }) => {
</span>    </span>let</span> QueryStep {
</span>        schema,
</span>        </span>mut</span> rows,
</span>    } = </span>run_query</span>(from)?;
</span>
</span>let</span> size: </span>usize </span>= (*limit).</span>try_into</span>().</span>unwrap</span>();
</span>
</span>    rows.</span>truncate</span>(size);
</span>
</span>    Ok(QueryStep { schema, rows })
</span>}
</span></code></pre>
That's the whole thing. What a disappointing blog post.</p>
What's next?</h2>
Next time we're doing ordering, which is marginally more exciting, but not that exciting tbh.</p>
Make sense? If not, get in touch</a>!</p>

Let's write a database (part 3)

Unknown — Sun, 24 Aug 2025 00:00:00 +0000

Well, well, well, if it isn't part 3. Last time we tidied up a bit so that we're ready to tackle joins. As ever, all the code lives right here</a>.</p>

What is a join then?</h2>

Say we have a table of Albums that looks something like:</p>

{
</span>  "</span>albumId</span>": </span>1</span>,
</span>  "</span>title</span>": "</span>Best of the Beatles</span>",
</span>  "</span>artistId</span>": </span>1
</span>},
</span>{
</span>  "</span>albumId</span>": </span>2</span>,
</span>  "</span>title</span>": "</span>Horses</span>",
</span>  "</span>artistId</span>": </span>2
</span>}
</span></code></pre>
...and another table full of Artists like:</p>
{
</span>  "</span>artistId</span>": </span>1</span>,
</span>  "</span>name</span>": "</span>The Beatles</span>"
</span>},
</span>{
</span>  "</span>artistId</span>": </span>2</span>,
</span>  "</span>name</span>": "</span>Patti Smith</span>"
</span>}
</span></code></pre>
A join is what lets us look up the artist name for a given album.</p>
select </span>* </span>from</span> Albums
</span>left join</span> Artists on artistId
</span></code></pre>
Will return something like:</p>
[
</span>  {"</span>albumId</span>": </span>1</span>, "</span>title</span>": "</span>Best of the Beatles</span>", "</span>name</span>": "</span>The Beatles</span>"},
</span>  {"</span>albumId</span>": </span>2</span>, "</span>title</span>": "</span>Horses</span>", "</span>name</span>": "</span>Patti Smith</span>"}
</span>]
</span></code></pre>
What makes it a 'join' is that for each row on the left hand side we attach the rows from the right hand table where the join condition</code> (here, Albums.artistId = Artists.artistId</code>). Where one row matches from each side like this, it's all very neat.</p>
select </span>* </span>from</span> Artists
</span>left join</span> Albums on artistId
</span></code></pre>
Now, each artist may have zero or more albums, so our result will look like</p>
[
</span>  {"</span>artistId</span>":</span>1</span>, "</span>name</span>": "</span>The Beatles</span>", "</span>title</span>": "</span>Best of the Beatles</span>"},
</span>  {"</span>artistId</span>":</span>1</span>, "</span>name</span>": "</span>The Beatles</span>", "</span>title</span>": "</span>Revolver</span>"},
</span>  {"</span>artistId</span>":</span>1</span>, "</span>name</span>": "</span>The Beatles</span>", "</span>title</span>": "</span>Help</span>"},
</span>  {"</span>artistId</span>":</span>2</span>, "</span>name</span>": "</span>Patti Smith</span>", "</span>title</span>": "</span>Horses</span>"},
</span>  {"</span>artistId</span>": </span>3</span>, "</span>name</span>": "</span>Johnny Noalbums</span>"}
</span>]
</span></code></pre>
Because The Beatles</code> have multiple albums, we make a copy of each left hand side for each right hand side. What about our old friend Johnny Noalbums</code> though? He has no matching albums, but we still include the left hand side. If we didn't want to include him though, we could use an inner join</code> instead:</p>
select </span>* </span>from</span> Artists
</span>inner join</span> Albums on artistId
</span></code></pre>
Here we'd only include items where there is a match on both sides, so our result would look like:</p>
[
</span>  {"</span>artistId</span>":</span>1</span>, "</span>name</span>": "</span>The Beatles</span>", "</span>title</span>": "</span>Best of the Beatles</span>"},
</span>  {"</span>artistId</span>":</span>1</span>, "</span>name</span>": "</span>The Beatles</span>", "</span>title</span>": "</span>Revolver</span>"},
</span>  {"</span>artistId</span>":</span>1</span>, "</span>name</span>": "</span>The Beatles</span>", "</span>title</span>": "</span>Help</span>"},
</span>  {"</span>artistId</span>":</span>2</span>, "</span>name</span>": "</span>Patti Smith</span>", "</span>title</span>": "</span>Horses</span>"}
</span>]
</span></code></pre>
There are a bunch of other kinds of joins too, but we'll stick with these two for now.</p>
Implementing the joins</h2>
We'll be using the classic hash join</a> to join our tables.</p>
So in our Artists -> Albums</code> join, we start by creating a HashMap</code> and adding an empty array for each artistId</code> found in the Artists</code> table (as artistId</code> is the column we are joining on). It should look like:</p>
{
</span>  </span>1</span>: [],
</span>  </span>2</span>: [],
</span>  </span>3</span>: []
</span>}
</span></code></pre>
Then we go through the Albums</code> table, and for every row with an artistId</code>, add the entire row's values under the key in the HashMap</code>. Our HashMap</code> should now look like:</p>
{
</span>  </span>1</span>: [
</span>    {"</span>artistId</span>":</span>1</span>,"</span>name</span>":"</span>Best of the Beatles</span>"},
</span>    {"</span>artistId</span>":</span>1</span>,"</span>name</span>":"</span>Revolver</span>"},
</span>    {"</span>artistId</span>":</span>1</span>,"</span>name</span>":"</span>Help</span>"}
</span>  ],
</span>  </span>2</span>: [
</span>    {"</span>artistId</span>":</span>2</span>,"</span>name</span>":"</span>Horses</span>"}
</span>  ],
</span>  </span>3</span>: []
</span>}
</span></code></pre>
The final step is to put everything together. For each row in the Artist</code> table, we:</p>


Look up the artistId</code> in the HashMap</code>.</p>
</li>

For each entry we find, output a new row combining the Artist</code> row with the Album</code> entry from the HashMap</code>.</p>
</li>

if we don't find any entries, then</p>
</li>
</ol>


for left outer join</code>, emit a new row containing the Artist</code> row columns only, with null</code> for any other columns in Album</code>.</p>
</li>

for inner join</code>, don't emit a row.</p>
</li>
</ul>
In code</h2>
We have a new Query::Join</code> item.</p>
pub struct </span>Join {
</span>    </span>pub </span>join_type</span>: JoinType,
</span>    </span>pub </span>left_from</span>: Box<Query>,
</span>    </span>pub </span>right_from</span>: Box<Query>,
</span>    </span>pub </span>on</span>: JoinOn,
</span>}
</span>
</span>pub struct </span>JoinOn {
</span>    </span>pub </span>left</span>: Column,
</span>    </span>pub </span>right</span>: Column,
</span>}
</span>
</span>pub enum </span>JoinType {
</span>    Inner,
</span>    LeftOuter,
</span>}
</span></code></pre>
We deal with these in run_query</code> as follows:</p>
Query::Join(Join {
</span>    left_from,
</span>    right_from,
</span>    join_type,
</span>    on,
</span>}) => {
</span>    </span>// get the left-hand side items
</span>    </span>let</span> QueryStep {
</span>        schema: left_schema,
</span>        rows: left_rows,
</span>    } = </span>run_query</span>(left_from)?;
</span>
</span>    </span>// get the right-hand side items
</span>    </span>let</span> QueryStep {
</span>        schema: right_schema,
</span>        rows: right_rows,
</span>    } = </span>run_query</span>(right_from)?;
</span>
</span>    </span>// join the left and right hand sides
</span>    join::hash_join(
</span>        left_rows,
</span>        &left_schema,
</span>        right_rows,
</span>        &right_schema,
</span>        on,
</span>        join_type,
</span>    )
</span>}
</span></code></pre>
Here is the hash_join</code> function:</p>
pub fn </span>hash_join</span>(
</span>    </span>left_rows</span>: Vec<Row>,
</span>    </span>left_schema</span>: &Schema,
</span>    </span>right_rows</span>: Vec<Row>,
</span>    </span>right_schema</span>: &Schema,
</span>    </span>on</span>: &JoinOn,
</span>    </span>join_type</span>: &JoinType,
</span>) -> Result<QueryStep, QueryError> {
</span>    </span>let mut</span> build_items = HashMap::new();
</span>
</span>    </span>// add all the relevant `on` values to map,
</span>    </span>for</span> left_row in &left_rows {
</span>        </span>let</span> value = 
</span>          left_row
</span>            .</span>get_column</span>(&on.left, left_schema)
</span>            .</span>ok_or_else</span>(|| {
</span>              QueryError::ColumnNotFoundInSchema {
</span>                  column_name: on.left.</span>clone</span>(),
</span>              }
</span>            })?;
</span>
</span>        build_items.</span>insert</span>(</span>calculate_hash</span>(value), vec![]);
</span>    }
</span>
</span>    </span>// collect all the different right side values
</span>    </span>for</span> right_row in right_rows {
</span>        </span>let</span> value = right_row
</span>            .</span>get_column</span>(&on.right, right_schema)
</span>            .</span>ok_or_else</span>(|| QueryError::ColumnNotFoundInSchema {
</span>                column_name: on.right.</span>clone</span>(),
</span>            })?;
</span>
</span>        </span>// this assumes left or inner join and 
</span>        </span>// ignores where there's no left match
</span>        </span>if let </span>Some(items) = build_items.</span>get_mut</span>(&</span>calculate_hash</span>(value)) {
</span>            items.</span>push</span>(right_row.</span>clone</span>());
</span>        }
</span>    }
</span>
</span>    </span>let mut</span> output_rows = vec![];
</span>
</span>    </span>for</span> left_row in left_rows {
</span>        </span>let</span> value = 
</span>          left_row
</span>            .</span>get_column</span>(&on.left, left_schema)
</span>            .</span>ok_or_else</span>(|| {
</span>              QueryError::ColumnNotFoundInSchema {
</span>                  column_name: on.left.</span>clone</span>(),
</span>              }
</span>            })?;
</span>
</span>        </span>if let </span>Some(rhs) = build_items.</span>get</span>(&</span>calculate_hash</span>(value)) {
</span>            </span>if</span> rhs.</span>is_empty</span>() {
</span>                </span>// if left outer join
</span>                </span>if let </span>JoinType::LeftOuter = join_type {
</span>                    </span>let mut</span> whole_row = left_row.</span>clone</span>();
</span>
</span>                    </span>// we can't find value, so add a bunch of nulls
</span>                    </span>for </span>_ in &right_schema.columns {
</span>                        whole_row.items.</span>push</span>(serde_json::Value::Null);
</span>                    }
</span>                    output_rows.</span>push</span>(whole_row);
</span>                }
</span>            } </span>else </span>{
</span>                </span>for</span> item in rhs {
</span>                    </span>let mut</span> whole_row = left_row.</span>clone</span>();
</span>                    whole_row.</span>extend</span>(item.</span>clone</span>());
</span>                    output_rows.</span>push</span>(whole_row);
</span>                }
</span>            }
</span>        }
</span>    }
</span>
</span>    </span>let mut</span> schema = left_schema.</span>clone</span>();
</span>    schema.</span>extend</span>(right_schema.</span>clone</span>());
</span>
</span>    Ok(QueryStep {
</span>        rows: output_rows,
</span>        schema,
</span>    })
</span>}
</span></code></pre>
Is that it?</h2>
Well yeah, sorta. We only handle two kinds of joins here, left outer</code> and inner</code>, and so there's a bunch more we can do here. Really with joins the trick is optimising them right - ideally we want the smaller table on the left hand side, for instance. We'll get to that once we start implementing some optimisations.</p>
What's next?</h2>
Haven't really decided yet actually. Perhaps some nice optimisations? Let's see what takes our fancy.</p>
Make sense? If not, get in touch</a>!</p>



Let's write a database (part 2)
Unknown — Tue, 05 Aug 2025 00:00:00 +0000
Hello, hello, hello. Welcome to part two of this adventure where we're making a database by hand. In part one we stole a SQL parser, did some table scans, filtered some results, and projected the ones we're interested in. I promised we'd look at joins today, but first we need to do a bit of housekeeping.</p>
If you'd like to look at the code, it's right here</a>.</p>
Storing our rows better</h2>
Previously we passed our rows around as Vec<serde_json::Value></code> so each row was a JSON value that looked like this:</p>
{ 
</span>  "</span>id</span>": </span>1</span>,
</span>  "</span>name</span>": "</span>Mr Horse</span>",
</span>  "</span>age</span>": </span>100
</span>}
</span></code></pre>
This is poor for two reasons:</p>


Having the column names in every row is wasteful</p>
</li>

If we want to rename columns (or disambiguate the "name" column from two tables that have been joined), we have to change every row</p>
</li>
</ol>
Instead we have a Row</code> type that contains a Vec</code> full of individual serde_json::Value</code> types for each column entry:</p>
pub struct </span>Row {
</span>    </span>pub </span>items</span>: Vec<serde_json::Value>,
</span>}
</span></code></pre>
And we pass around a single Schema</code> type that holds all the column names:</p>
pub struct </span>Schema {
</span>    </span>pub </span>columns</span>: Vec<Column>,
</span>}
</span>
</span>pub struct </span>Column {
</span>    </span>pub </span>name</span>: String,
</span>}
</span></code></pre>
Changes to our query functions</h2>
Previously we just returned a big pile of rows from each query function, but now each one returns a QueryStep</code> type:</p>
pub struct </span>QueryStep {
</span>    </span>pub </span>schema</span>: Schema,
</span>    </span>pub </span>rows</span>: Vec<Row>,
</span>}
</span></code></pre>
Now we have a bunch of rows, and a Schema</code> so we know what's in them.</p>
From</h3>
When selecting fields, we grab all the rows, and then return a schema too. These are hardcoded for now:</p>
fn </span>schema</span>(</span>table_name</span>: &TableName) -> Vec<Column> {
</span>    </span>match</span> table_name.</span>0.</span>as_str</span>() {
</span>        "</span>Album</span>" => vec!["</span>AlbumId</span>".</span>into</span>(), "</span>Title</span>".</span>into</span>(), "</span>ArtistId</span>".</span>into</span>()],
</span>        "</span>Artist</span>" => vec!["</span>ArtistId</span>".</span>into</span>(), "</span>Name</span>".</span>into</span>()],
</span>        "</span>Track</span>" => vec![
</span>            "</span>TrackId</span>".</span>into</span>(),
</span>            "</span>Name</span>".</span>into</span>(),
</span>            "</span>AlbumId</span>".</span>into</span>(),
</span>            "</span>MediaTypeId</span>".</span>into</span>(),
</span>            "</span>GenreId</span>".</span>into</span>(),
</span>            "</span>Composer</span>".</span>into</span>(),
</span>            "</span>Milliseconds</span>".</span>into</span>(),
</span>            "</span>Bytes</span>".</span>into</span>(),
</span>            "</span>UnitPrice</span>".</span>into</span>(),
</span>        ],
</span>        _ => todo!("</span>unknown schema</span>"),
</span>    }
</span>}
</span></code></pre>
Filtering</h3>
For instance, this means our filtering now looks like this, passing the schema through unchanged from whatever Query</code> it wraps:</p>
Query::Filter(Filter { from, filter }) => {
</span>    </span>let</span> QueryStep {
</span>        schema,
</span>        rows,
</span>    } = </span>run_query</span>(from)?;
</span>
</span>    </span>let mut</span> filtered_rows = vec![];
</span>
</span>    </span>for</span> row in rows {
</span>        </span>if </span>filter::apply_predicate(&row, &schema, filter)? {
</span>            filtered_rows.</span>push</span>(row);
</span>        }
</span>    }
</span>
</span>    Ok(QueryStep {
</span>        schema,
</span>        rows: filtered_rows
</span>    })
</span>}
</span></code></pre>
Projections</h3>
Our projections let us drop and reorder fields, so they'll change the schemas as well as the rows:</p>
Query::Project(Project { from, fields }) => {
</span>    </span>let</span> QueryStep {
</span>        schema,
</span>        rows,
</span>    } = </span>run_query</span>(from)?;
</span>
</span>    </span>let mut</span> projected_rows = vec![];
</span>
</span>    </span>for</span> row in &rows {
</span>        projected_rows.</span>push</span>(project::project_fields(row, &schema, fields)?);
</span>    }
</span>
</span>    </span>let</span> schema = project::project_schema(&schema, fields)?;
</span>
</span>    Ok(QueryStep {
</span>        schema,
</span>        rows: projected_rows,
</span>    })
</span>}
</span></code></pre>
As well as a project_fields</code> function we have a matching project_schema</code> function that creates a new schema.</p>
pub fn </span>project_schema</span>(</span>schema</span>: &Schema, </span>fields</span>: &[Column]) 
</span>  -> Result<Schema, QueryError>
</span>{
</span>  </span>let mut</span> columns = vec![];
</span>
</span>  </span>for</span> field in fields {
</span>    </span>let</span> index = schema.</span>get_index_for_column</span>(field).</span>ok_or_else</span>(|| {
</span>      QueryError::ColumnNotFoundInSchema {
</span>        column_name: field.</span>clone</span>(),
</span>      }
</span>    })?;
</span>
</span>    </span>let</span> column = schema
</span>      .columns
</span>      .</span>get</span>(index)
</span>      .</span>ok_or</span>(QueryError::IndexNotFoundInSchema { index })?;
</span>
</span>    columns.</span>push</span>(column.</span>clone</span>());
</span>  }
</span>
</span>  Ok(Schema { columns })
</span>}
</span></code></pre>
Outputting everything</h3>
We still want to output everything in JSON as before, so our QueryStep</code> has a to_json</code> function that puts everything back as it was before.</p>
impl </span>QueryStep {
</span>  </span>// reconstruct JSON output
</span>  </span>pub fn </span>to_json</span>(&</span>self</span>) -> serde_json::Value {
</span>    </span>let mut</span> output_rows = vec![];
</span>
</span>    </span>for</span> row in &</span>self</span>.rows {
</span>      </span>let mut</span> output_row = serde_json::Map::new();
</span>      </span>for</span> column in &</span>self</span>.schema.columns {
</span>        </span>let</span> value = row.</span>get_column</span>(column, &</span>self</span>.schema).</span>unwrap</span>();
</span>        output_row.</span>insert</span>(column.</span>to_string</span>(), value.</span>clone</span>());
</span>      }
</span>      output_rows.</span>push</span>(serde_json::Value::Object(output_row));
</span>    }
</span>    serde_json::Value::Array(output_rows)
</span>  }
</span>}
</span></code></pre>
After this, all the outputs look the same as before and our tests all pass again. Nice!</p>
What's next?</h2>
OK, we've got all our ducks in a row, next time we'll do the joins, I promise.</p>
Make sense? If not, get in touch</a>!</p>


Let's write a database (part 1)
Unknown — Sat, 26 Jul 2025 00:00:00 +0000
So, confession, I love playing on the computer, but I'm terrible at SQL. I know that it's Good or whatever and there's this whole very sensible looking Relational Algebra</a> behind it all, but like when I have to interact with it, I get the job done and then immediately wipe whatever I learned from my brain.</p>
Enough is enough. It's time to learn it properly. And what better way than to write an ANSI SQL database from scratch!</p>
Disclaimers etc</h2>
Setting some expectations, this is very much a "fun" learning project, and we're gonna get a lot of things wrong. We'll be using Rust, because I write that a lot atm and so it's what my brain thinks in, but I would definitely not read this hoping for a Rust tutorial because I am almost as bad at Rust as SQL. I am going to describe things in a very hand-wavy way that will probably annoy people that know what they're talking about, but it's my blog and I can do what I want.</p>
So, let's do it?</h2>
OK. So what we're going to do in part 1 is:</p>

Make (steal) a SQL parser</li>
Do a table scan (From</code>)</li>
Filter results from that table (Filter</code>)</li>
Choose the fields we want to look at (Project</code>)</li>
</ul>
We're going to be concentrating on the Query Engine part of the database initially,mostly because I'm more interested in it, so our tables are going to be static JSON files taken from the chinook dataset</a>. We are using this because it's full of rock albums and it's nice to be reminder that Led Zeppelin are a totally sick band from time to time.</p>
Our types</h2>
We might not be implementing in Haskell but it's spirit lives on - let's start by defining the types of our query.</p>
// the type that defines a query
</span>enum </span>Query {
</span>  From(From),
</span>  Filter(Filter),
</span>  Project(Project)
</span>}
</span>
</span>// select `FROM` a table
</span>struct </span>From {
</span>  </span>table_name</span>: TableName
</span>}
</span>
</span>// filter the results for a `WHERE` clause
</span>struct </span>Filter {
</span>  </span>from</span>: Box<Query>,
</span>  </span>filter</span>: Expr,
</span>}
</span>
</span>// boolean expression type
</span>pub enum </span>Expr {
</span>  ColumnComparison {
</span>    column: Column,
</span>    op: Op,
</span>    literal: serde_json::Value,
</span>  }
</span>}
</span>
</span>// compare two items  
</span>pub enum </span>Op {
</span>  Equals,
</span>}
</span>
</span>// choose which fields to return 
</span>struct </span>Project {
</span>  </span>from</span>: Box<Query>,
</span>  </span>fields</span>: Vec<ColumnName> 
</span>}
</span>
</span>// name of a table
</span>struct </span>TableName(pub String);
</span>
</span>// name of a column
</span>struct </span>ColumnName(pub String);
</span></code></pre>
A parser</h2>
This could quickly become a parsing tutorial and we don't want that, so we're going to use the sqlparser</a> crate. It takes a string input and returns either it's own AST or an error. We'll pattern match on this and extract only the things we support into a Query</code> type we defined above.</p>
Nothing about this is very interesting, so I will just link to it</a>. Know that we parse some SQL and make the types above.</p>
Our run_query</code> function</h2>
Now we've worked out what the user wants, we need to run the query. Initially we'll do this by matching on the Query</code> type.</p>
pub fn </span>run_query</span>(</span>query</span>: &Query) -> Vec<serde_json::Value> {
</span>  </span>match</span> query {
</span>    Query::From(_) => todo!("</span>Query::From</span>"), 
</span>    Query::Filter(_) => todo!("</span>Query::Filter</span>"), 
</span>    Query::Project(_) => todo!("</span>Query::Project</span>")
</span>  }
</span>}
</span></code></pre>
We'll fill these todo!</code> out one by one now.</p>
Query::From</h2>
The first thing we'll implement is a simple table scan. A table scan is "get all of the rows in the table". If you're thinking "that doesn't sound wildly performant", rest assured your Software Craftsperson spidey-sense is still working correctly. However, our tables only have ~300 items in them, so for now we'll live with it until we start thinking about indexes.</p>
Here is some code. Forgive me, Padre.</p>
fn </span>table_scan</span>(</span>table_name</span>: &TableName) -> Vec<serde_json::Value> {
</span>  </span>match</span> table_name.</span>0.</span>as_str</span>() {
</span>    "</span>Album</span>" => {
</span>      </span>let</span> my_str = include_str!("</span>../static/Album.json</span>");
</span>      serde_json::from_str::<Vec<serde_json::Value>>(my_str).</span>unwrap</span>()
</span>    },
</span>    "</span>Artist</span>" => {
</span>      </span>let</span> my_str = include_str!("</span>../static/Artist.json</span>");
</span>      serde_json::from_str::<Vec<serde_json::Value>>(my_str).</span>unwrap</span>()
</span>    }
</span>    _ => panic!("</span>table not found {table_name:?}</span>"),
</span>    }
</span>}
</span></code></pre>
Let's smash that into our run_query</code> function:</p>
pub fn </span>run_query</span>(</span>query</span>: &Query) -> Vec<serde_json::Value> {
</span>  </span>match</span> query {
</span>    Query::From(From { table_name }) => </span>table_scan</span>(table_name), 
</span>    </span>// ..  
</span></code></pre>
It is not good code, but it is code. We'd test it, but it would still fail because of the other todo!</code>. Oh well. Onwards.</p>
Query::Filter</h2>
Call me a staunch traditionalist, but often when I am accessing a database I do not wish to download all of it's data at once. We're going to allow users to filter data using a where</code> clause, which lets us define properties about rows we are interested in.</p>
Let's recap on our Expr</code> type:</p>
pub enum </span>Expr {
</span>  ColumnComparison {
</span>    column: Column,
</span>    op: Op,
</span>    literal: serde_json::Value,
</span>  },
</span>}
</span>
</span>pub enum </span>Op {
</span>  Equals,
</span>}
</span></code></pre>
This is pretty limited, but it does let us express select * from Album where album_id = 1</code>.</p>
We start by defining a function for deciding whether we care about a row. It takes a row (which we store as a serde_json::Value</code>) and an Expr</code>, returning a bool</code> telling us to keep the row or throw it in the bin.</p>
fn </span>apply_predicate</span>(</span>row</span>: &serde_json::Value, </span>where_expr</span>: &Expr) -> </span>bool </span>{
</span>  </span>match</span> where_expr {
</span>    Expr::ColumnComparison {
</span>      column,
</span>      op,
</span>      literal,
</span>    } => {
</span>      </span>// unwrap row into a map
</span>      </span>let</span> row_object = row.</span>as_object</span>().</span>unwrap</span>();
</span>
</span>      </span>// grab the column we care about 
</span>      </span>let</span> value = row_object.</span>get</span>(&column.name).</span>unwrap</span>();
</span>
</span>      </span>// compare it to `value` 
</span>      </span>match</span> op {
</span>        Op::Equals => value == literal,
</span>      }
</span>    }
</span>  }
</span>}
</span></code></pre>
Let's use it in our run_query</code> function:</p>
pub fn </span>run_query</span>(</span>query</span>: &Query) -> Vec<serde_json::Value> {
</span>  </span>match</span> query {
</span>    Query::From(From { table_name }) => </span>table_scan</span>(table_name),
</span>    Query::Filter(Filter { from, filter }) => </span>run_query</span>(from)
</span>      .</span>into_iter</span>()
</span>      .</span>filter</span>(|</span>row</span>| </span>apply_predicate</span>(row, filter))
</span>      .</span>collect</span>(), 
</span>      </span>// ..
</span></code></pre>
We'd test a query, but it'd still fail. But nearly!</p>
Query::Project</h2>
So far we return every single field from our table scan, so every select</code> is a select * from ...</code>. We can do better than that, let's implement Project</code>, which is how we extract fields from rows. Eventually, we'll allowing renaming things with aliases, but that's quite boring and fiddly, so for now we're just supporting stuff like select Title, ArtistId from Album</code>.</p>
fn </span>project_fields</span>(</span>row</span>: serde_json::Value, </span>fields</span>: &[Column]) -> serde_json::Value {
</span>  </span>// make set of columns to keep
</span>  </span>let</span> field_set: BTreeSet<_> = 
</span>    fields
</span>      .</span>iter</span>()
</span>      .</span>map</span>(|</span>c</span>| c.name.</span>clone</span>())
</span>      .</span>collect</span>();
</span>
</span>    
</span>  </span>if let </span>serde_json::Value::Object(map) = row {
</span>    </span>// collect all the items we still want
</span>    </span>let</span> new_map = map
</span>      .</span>into_iter</span>()
</span>      .</span>filter</span>(|(</span>k</span>, _)| field_set.</span>contains</span>(k))
</span>      .</span>collect</span>();
</span>
</span>    </span>// wrap it back up again
</span>    serde_json::Value::Object(new_map)
</span>  } </span>else </span>{
</span>    panic!("</span>expected Object</span>")
</span>  }
</span>}
</span></code></pre>
Then we add it to run_query</code>, completing it for now.</p>
pub fn </span>run_query</span>(</span>query</span>: &Query) -> Vec<serde_json::Value> {
</span>  </span>match</span> query {
</span>    Query::From(From { table_name }) => </span>table_scan</span>(table_name),
</span>    Query::Filter(Filter { from, filter }) => </span>run_query</span>(from)
</span>      .</span>into_iter</span>()
</span>      .</span>filter</span>(|</span>row</span>| </span>apply_predicate</span>(row, filter))
</span>      .</span>collect</span>(),
</span>    Query::Project(Project { from, fields }) => {
</span>      </span>// filter the columns in each row
</span>      </span>run_query</span>(from)
</span>        .</span>into_iter</span>()
</span>        .</span>map</span>(|</span>row</span>| </span>project_fields</span>(row, fields))
</span>        .</span>collect</span>(),
</span>    }
</span>  }
</span>}
</span></code></pre>
Bringing it together</h2>
We then add a basic CLI using clap</a>, that takes a single argument --sql</code>. Nothing surprising or interesting here, sorry.</p>
use </span>clap::Parser;
</span>use </span>core::{parse, run_query};
</span>
</span>#[</span>derive</span>(Parser, Debug)]
</span>#[</span>command</span>(version, about, long_about = None)]
</span>struct </span>Args {
</span>  </span>/// SQL query to run
</span>  #[</span>arg</span>(short, long)]
</span>  </span>sql</span>: String,
</span>}
</span>
</span>fn </span>main</span>() {
</span>  </span>let</span> args = Args::parse();
</span>
</span>  </span>let</span> query = </span>parse</span>(&args.sql).</span>unwrap</span>();
</span>  </span>let</span> results = </span>run_query</span>(&query);
</span>
</span>  </span>for</span> result in results {
</span>    println!("</span>{result}</span>");
</span>  }
</span>}
</span></code></pre>
This means we can run a query with cargo run --bin cli -- --sql 'select Title from Album where AlbumId = 48' | jq </code> and look what we get:</p>
{
</span>  "</span>AlbumId</span>"</span>:</span> 48,
</span>  "</span>Title</span>"</span>: </span>"</span>The Essential Miles Davis (Disc 1)</span>",
</span>  "</span>ArtistId</span>"</span>:</span> 68
</span>}
</span></code></pre>
Not bad, not bad at all.</p>
What's next?</h2>
If you've made it this far without being furious about my use of unwrap()</code>, then in part two we're going to add some JOINS.</p>
Make sense? If not, get in touch</a>!</p>


llvm-calc is dead, long live wasm-calc
Unknown — Wed, 03 Jul 2024 00:00:00 +0000
So last year I started writing a
series</a> on compiling a functional language to
LLVM, and I have to confess, I came utterly unstuck</a>.</p>
</p>
Until recent versions, LLVM tried to be helpful by making you specify types
for all pointers you pass around. This is really helpful in simple cases as you
get basic typechecking at compile time. However, once you start implementing things like sum types (ie, reserve a slab of memory, and stuff it with one of several sets of data), it becomes super annoying.</p>
For example, compiling an Either<Int, Bool></code> type requires you to constantly cast between "arbitrary array type we've chosen
that takes up the right amount of memory", "this thing if it turns out
to be Left<Int></code>" and "this thing if it turns out to be Right<Bool></code>.</p>
This has been solved though! More recent versions of LLVM have the concept of an Opaque
pointer</a>, which allows us to pass
pointers around without caring what type they are, and then think about the
types when it comes to actually interacting with the underlying data. This is
ideal!</p>
However, it's only available in LLVM 14 onwards, and getting a working
version-matched set
of LLVM Haskell libraries turns out to be precarious at best. I got reasonably
close</a> using
the LLVM-15 branch</a> of llvm-hs-pure</code>, but could not find an equivalent for llvm-hs-pretty</a>.</p>
Basically, it was all getting a bit fiddly and stupid, and writing a tutorial that is either a) already out of date or b) relies on a set of arbitrary commits from a
bunch of forks doesn't feel like it will be particularly useful, so I have decided to change tack.</p>
The good news?</h2>
I decided to port the project to compile to WebAssembly instead! Development of
the thing itself has been going really well, see for yourself here: wasm-calc</a></p>
The language is fully featured enough that we can create a very simple
wasm-4</a>
game with it.</p>
</p>
Some thoughts so far:</p>


The wasm</a> package for Haskell is lovely!</p>
</li>

Not being able to cheat by including a bunch of C in a runtime has forced me to learn how allocators work</p>
</li>

There's a bunch of useful resources, like
watlings</a> and Mozilla's
docs</a>.</p>
</li>
</ul>
What's next?</h2>
As well as serving as a big excuse, this blog is supposed to be a forcing
function to write the tutorials to go with all the wasm-calc</code> versions. I'll
start by porting the llvm-calc</code> blogs, and then move onto the new features
we've got.</p>
Make sense? If not, get in touch</a>!</p>
Further reading:</p>
wasm-calc</a></p>


Compiling a functional language to LLVM, part 3
Unknown — Tue, 11 Apr 2023 00:00:00 +0000
Welcome to part 3 of this series in compiling functional languages to LLVM. In
part 2</a> we added basic control
flow to our langauge with an if / then / else</code> construct.</p>
Today we're going to get one important step towards a functional programming
language by adding functions and variables.</p>
By the end of today we'll be able to make small modules such as:</p>
function </span>add</span>(</span>a:</span> integer, b: integer) {
</span>  </span>a</span> + b
</span>}
</span>
</span>function </span>increment</span>(</span>a:</span> integer) {
</span>  </span>a</span> + 1
</span>}
</span>
</span>add</span>(increment(1)</span>,</span> add(2, 3))
</span></code></pre>
However, there are quite a few things our functions won't</em> do.</p>

They can't call themselves recursively (ie, function factorial(a: Integer) { if a == 0 then 1 else a * factorial(a - 1) }</code>. This is to simplify the typechecker
implementation for the time being rather than any limitation in LLVM - we'll come back round to making this
possible.</li>
We must define all function arguments up front (ie, a: Integer, b: Boolean</code>). It is possible to infer these, but let's keep things simple for
now.</li>
Functions can only call functions defined before them. This can be solved by
doing some dependency analysis before typechecking (ie, move things around to
typecheck them in a sensible order). We avoid this for now, but will come
back to it.</li>
Functions can't return other functions, they can only be defined at the top
level. This is a limitation of LLVM, however in future chapters we'll work around this by
implementing closures.</li>
</ul>
OK, lets get concrete</h2>
We're going to need some new datatypes to express all the new things we want to
do.</p>
Function</h3>
Firstly, we have a Function</code> type.</p>
data </span>Function</span> ann = </span>Function
</span>  { fnAnn :: ann,
</span>    </span>fnArgs </span>::</span> [(</span>ArgumentName</span>, </span>Type </span>ann</span>)],
</span>    </span>fnFunctionName </span>:: FunctionName</span>,
</span>    </span>fnBody </span>:: Expr </span>ann
</span>  }
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>, </span>Functor</span>)
</span></code></pre>
This lets us describe something like:</p>
function </span>add</span>(</span>a:</span> Integer, b: Integer) { 
</span>  </span>a</span> + b 
</span>}
</span></code></pre>
Note that the function body is a single Expr</code>, and that it can use variables
a</code> and b</code> introduced as function arguments.</p>
The ann</code> type will contain file location information
after parsing, and then will contain the type of the function after
typechecking.</p>
Our function implementation is very limited - we can only
use variables passed into the function as arguments, and must explicitly
annotate each function argument with it's type.</p>
Module</h3>
A Module</code> lets us combine multiple functions and a main</code> expression.</p>
data </span>Module</span> ann = </span>Module
</span>  { mdFunctions :: [</span>Function</span> ann],
</span>    </span>mdExpr </span>:: Expr </span>ann
</span>  }
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>, </span>Functor</span>)
</span></code></pre>
This lets us write code like:</p>
function </span>increment</span>(</span>a:</span> Integer) {
</span>  </span>a</span> + 1
</span>}
</span>
</span>function </span>decrement</span>(</span>a:</span> Integer) {
</span>  </span>a</span> - 1
</span>}
</span>
</span>increment</span>(decrement(1)) =</span>= </span>1
</span></code></pre>
As mentioned earlier, functions can only be used in the order
they are defined. Therefore decrement</code> could call increment</code>, but not the
other way round. We can improve this in future with some basic dependency
analysis.</p>
Expr</h3>
Our Expr</code> needs a couple of new constructors.</p>
data </span>Expr</span> ann
</span>  = </span>EPrim</span> ann </span>Prim
</span>  | </span>EInfix</span> ann </span>Op</span> (</span>Expr</span> ann) (</span>Expr</span> ann)
</span>  | </span>EIf</span> ann (</span>Expr</span> ann) (</span>Expr</span> ann) (</span>Expr</span> ann)
</span>  | </span>EVar</span> ann </span>Identifier </span>-- new!
</span>  | </span>EApply</span> ann </span>FunctionName</span> [</span>Expr</span> ann] </span>-- new!
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>, </span>Functor</span>, </span>Foldable</span>, </span>Traversable</span>)
</span></code></pre>
EVar</code> represents a variable such as a</code>, and EApply</code> represents function application (add(1,2)</code>).</p>
</p>
Typechecker changes</h2>
After a rather sizable swerve into bidirectional typechecking in the previous
part, we are going to focus less on the changes here.</p>
Adding state</h3>
The most important part is that it's become stateful, as we will be learning
about both functions and variables as we typecheck. We have created a
TypecheckM</code> newtype that we use, that contains both a ReaderT</code> and a
StateT</code>.</p>
newtype </span>TypecheckEnv</span> ann = </span>TypecheckEnv
</span>  { tceVars :: </span>HashMap Identifier</span> (</span>Type</span> ann)
</span>  }
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>)
</span>
</span>newtype </span>TypecheckState</span> ann = </span>TypecheckState
</span>  {tcsFunctions :: </span>HashMap FunctionName</span> (</span>Type</span> ann)}
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>)
</span>
</span>newtype </span>TypecheckM</span> ann a = </span>TypecheckM
</span>  { getTypecheckM ::
</span>      </span>ReaderT</span> (</span>TypecheckEnv</span> ann)
</span>          (</span>StateT</span> (</span>TypecheckState</span> ann) 
</span>            (</span>Either</span> (</span>TypeError</span> ann))) a
</span>  }
</span>  </span>deriving newtype
</span>    ( </span>Functor</span>,
</span>      </span>Applicative</span>,
</span>      </span>Monad</span>,
</span>      </span>MonadReader</span> (</span>TypecheckEnv</span> ann),
</span>      </span>MonadError</span> (</span>TypeError</span> ann),
</span>      </span>MonadState</span> (</span>TypecheckState</span> ann)
</span>    )
</span></code></pre>
The reasons for separate Reader</code> and State</code> are the nature of the state in
them. Variables only live for the life of a function that are defined in, so
they live in the TypecheckEnv</code> used by Reader</code>, and disappear after the
function definition is typechecked (more information on this technique
here</a>).</p>
The trick is using the local</code> function from Control.Monad.Reader</code>:</p>
withFunctionArgs </span>::</span> [(</span>Identifier</span>, </span>Type </span>ann</span>)] </span>-> TypecheckM </span>ann a </span>-> TypecheckM </span>ann a
</span>withFunctionArgs args computation =
</span>  local
</span>    ( \tce ->
</span>        tce
</span>          { tceVars = tceVars tce <> </span>HM</span>.fromList args
</span>          }
</span>    )
</span>    computation
</span></code></pre>
We pass in some args</code>, which are the function arguments and their types, and
computation</code>, which is whatever typechecking we'd like do. Then throughout
running computation</code>, we'll have extra variables in scope, and then they'll
disappear again. This is helpful for typechecking functions, where the vars
only exist inside.</p>
Inference changes</h3>
We have two new infer</code> cases, EVar</code> and EApply</code>. EVar</code> is pretty
straightforward:</p>
infer (</span>EVar</span> ann var) = </span>do
</span>  ty <- lookupVar ann var
</span>  pure (</span>EVar</span> ty var)
</span></code></pre>
We lookup the type for var</code>, and decorate the type with it. If lookupVar</code>
fails, it "throws" a TypeError ann</code>.</p>
-- | look up a saved identifier "in the environment"
</span>lookupVar </span>:: </span>ann </span>-> Identifier -> TypecheckM </span>ann</span> (</span>Type </span>ann</span>)
</span>lookupVar ann identifier = </span>do
</span>  maybeType <- asks (</span>HM</span>.lookup identifier . tceVars)
</span>  </span>case</span> maybeType </span>of
</span>    </span>Just</span> found -> pure found
</span>    </span>Nothing </span>-> </span>do
</span>      allIdentifiers <- asks (</span>HM</span>.keysSet . tceVars)
</span>      throwError (</span>VarNotFound</span> ann identifier allIdentifiers)
</span></code></pre>
The other new infer</code> case is EApply</code>. This is used to get the type of an
applied function.</p>
infer (</span>EApply</span> ann fnName args) = </span>do
</span>  </span>-- lookup function by name in State
</span>  fn <- lookupFunction ann fnName
</span>  (ty, elabArgs) <- </span>case</span> fn </span>of
</span>    </span>TFunction</span> _ tArgs tReturn -> </span>do
</span>      </span>-- check the arguments length match the function 
</span>      when
</span>        (length args /= length tArgs)
</span>        (throwError $ 
</span>            </span>FunctionArgumentLengthMismatch</span> ann 
</span>              (length tArgs) 
</span>              (length args)
</span>        )
</span>      </span>-- check each arg against type
</span>      elabArgs <- zipWithM check tArgs args      
</span>      </span>-- return type and elaborated arguments
</span>      pure (tReturn, elabArgs)
</span>    _ -> throwError $ </span>NonFunctionTypeFound</span> ann fn
</span>  pure (</span>EApply</span> (ty $> ann) fnName elabArgs)
</span></code></pre>
Note how we use check</code> here to check each argument against the expected type in the
function. This is where the bidirectional type checking approach really starts
to shine, as any problems become immediately apparent.</p>
The lookupFunction</code> helper is very similar to lookupVar</code>, except it looks in
the State</code> instead of Reader</code>:</p>
-- | look up a saved identifier "in the environment"
</span>lookupFunction </span>:: </span>ann </span>-> FunctionName -> TypecheckM </span>ann</span> (</span>Type </span>ann</span>)
</span>lookupFunction ann fnName = </span>do
</span>  maybeType <- gets (</span>HM</span>.lookup fnName . tcsFunctions)
</span>  </span>case</span> maybeType </span>of
</span>    </span>Just</span> found -> pure found
</span>    </span>Nothing </span>-> </span>do
</span>      allFunctions <- gets (</span>HM</span>.keysSet . tcsFunctions)
</span>      throwError (</span>FunctionNotFound</span> ann fnName allFunctions)
</span></code></pre>
These types, and the functions used to store / fetch variables and functions
are defined
here</a>.</p>
Elaborating a function</h3>
Our functions have types for the arguments, so we push them into the Reader</code>
environment, and then elaborate the expression inside.</p>
elaborateFunction </span>::
</span>  </span>Function </span>ann </span>->
</span>  </span>TypecheckM </span>ann</span> (</span>Function</span> (</span>Type </span>ann</span>))
</span>elaborateFunction (</span>Function</span> ann args name expr) = </span>do
</span>  </span>-- with the `args` added to the Reader, infer the type of `expr`
</span>  exprA <- withFunctionArgs args (infer expr)
</span>  </span>-- adjust the types of the arguments
</span>  </span>let</span> argsA :: [(</span>ArgumentName</span>, </span>Type</span> (</span>Type</span> ann))]
</span>      argsA = fmap (second (\ty -> fmap (const ty) ty)) args
</span>  </span>-- create type of function
</span>  </span>let</span> tyFn = </span>TFunction</span> ann (snd <$> args) (getOuterAnnotation exprA)
</span>  </span>-- wrap it all back up again
</span>  pure (</span>Function</span> tyFn argsA name exprA)
</span></code></pre>
We've extended the Type</code> datatype to add a TFunction</code> constructor, which
contains the types of all the arguments, and the return type. All functions
will have a TFunction</code> type.</p>
data </span>Type</span> ann
</span>  = </span>TPrim</span> ann </span>TypePrim
</span>  | </span>TFunction</span> ann [</span>Type</span> ann] (</span>Type</span> ann) </span>-- new!
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>, </span>Functor</span>)
</span></code></pre>
Elaborating a module</h3>
Elaborating a module involves:</p>

Elaborate each function</li>
Push it's type into the State</code></li>
Elaborate the main</code> expression</li>
</ul>
elaborateModule </span>::
</span>  </span>forall ann</span>.
</span>  </span>Module </span>ann </span>->
</span>  </span>Either</span> (</span>TypeError </span>ann</span>) (</span>Module</span> (</span>Type </span>ann</span>))
</span>elaborateModule (</span>Module</span> {mdFunctions, mdExpr}) = runTypecheckM (</span>TypecheckEnv</span> mempty) $ </span>do
</span>  </span>-- typecheck all functions...
</span>  fns <-
</span>    traverse
</span>      ( \fn -> </span>do
</span>          </span>-- typecheck function
</span>          elabFn <- elaborateFunction fn
</span>          </span>-- add it to State
</span>          storeFunction (fnFunctionName elabFn) (fnAnn elabFn)
</span>          </span>-- return it
</span>          pure elabFn
</span>      )
</span>      mdFunctions
</span>  
</span>  </span>-- typecheck `expr`, and wrap everything back together
</span>  </span>Module</span> fns <$> infer mdExpr
</span></code></pre>
</p>
Updating the interpreter</h2>
We won't go into the interpreter changes today, they work in the same way as
the typechecker,
storing variables in the Reader</code> env and functions in the State</code>. The code
lives
here</a>.</p>
To the IR!</h2>
Here is an expression:</p>
function </span>sum</span>(</span>a:</span> Integer, b: Integer) {
</span>  </span>a</span> + b
</span>}
</span>
</span>sum</span>(20, 22)
</span></code></pre>
Here is the LLVN output for it. Hopefully it's not too brutal.</p>
; ModuleID = 'example'
</span>
</span>declare external ccc  void @printint(i32)
</span>
</span>define external ccc  i32 @sum(i32  %a_0, i32  %b_0)    {
</span>  %1 = add   i32 %a_0, %b_0
</span>  ret i32 %1
</span>}
</span>
</span>define external ccc  i32 @main()    {
</span>  %1 =  call ccc  i32  @sum(i32  20, i32  22)
</span>  call ccc  void  @printint(i32  %1)
</span>  ret i32 0
</span>}
</span></code></pre>
; ModuleID = 'example'
</span></code></pre>
A comment, lol.</p>

declare external ccc  void @printint(i32)
</span></code></pre>
We define our output function from our standard library.</p>

define external ccc  i32 @sum(i32  %a_0, i32  %b_0)    {
</span></code></pre>
Define the function. The first i32</code> is the return type. %a_0</code> is the first
argument with type i32</code>, and %b_0</code> is the second argument, with type i32</code>.</p>

  %1 = add   i32 %a_0, %b_0
</span></code></pre>
Body of the sum</code> function, add %a_0</code> and %b_0</code> and assign the result to
%1</code>.</p>

  ret i32 %1
</span></code></pre>
Return %1</code> from the function.</p>
}
</span></code></pre>
End of sum</code> function.</p>

define external ccc  i32 @main()    {
</span></code></pre>
This defines the main</code> function, the entry point to our application.</p>

%1 =  call ccc  i32  @sum(i32  20, i32  22)
</span></code></pre>
Body of the main</code> function - this calls the sum</code> function, passing it 20</code>
amd 22</code> as args. The result is stored in %1</code>.</p>

call ccc  void  @printint(i32  %1)
</span></code></pre>
Pass the result (%1</code>) to the printint</code> function in our standard library.</p>

ret i32 0
</span></code></pre>
Return the value 0</code> to show the program successfully completed.</p>

}
</span></code></pre>
Nice closing bracket. Time for a rest.</p>

</p>
Generating IR from Haskell</h2>
Adding functions and variables means that our IR generation also becomes
stateful. We're going to define a couple more types:</p>
data </span>OutputState </span>= </span>OutputState
</span>  { osFunctions :: </span>Map FunctionName LLVM</span>.</span>Operand</span>,
</span>    </span>osVars </span>:: Map Identifier LLVM</span>.</span>Operand
</span>  }
</span></code></pre>
It also means something can go wrong:</p>
data </span>OutputError
</span>  = </span>CantFindVar Identifier
</span>  | </span>CantFindFunction FunctionName
</span>  | </span>NonFunctionType</span> (</span>Type ()</span>)
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>)
</span></code></pre>
Both these errors shouldn't</em> happen if the typechecking is working, however
it's nice to capture them properly rather than just throwing with error</code>.</p>
It means we also need a similar set of functions for adding and looking up
functions and variables, which can be found
here</a> and are hopefully unsurprising.</p>
A lot of our implementation are various "turn things into LLVM" functions:</p>
typeToLLVM </span>:: Type </span>ann </span>-> LLVM</span>.</span>Type
</span>typeToLLVM (</span>TPrim</span> _ </span>TBool</span>) = </span>LLVM</span>.i1
</span>typeToLLVM (</span>TPrim</span> _ </span>TInt</span>) = </span>LLVM</span>.i32
</span>typeToLLVM (</span>TFunction</span> _ tyArgs tyRet) =
</span>  </span>LLVM</span>.</span>FunctionType</span> (typeToLLVM tyRet) (typeToLLVM <$> tyArgs) </span>False
</span></code></pre>
functionNameToLLVM </span>:: FunctionName -> LLVM</span>.</span>Name
</span>functionNameToLLVM (</span>FunctionName</span> fnName) =
</span>  </span>LLVM</span>.</span>Name</span> (fromString (</span>T</span>.unpack fnName))
</span></code></pre>
functionArgToLLVM </span>::
</span>  (</span>ArgumentName</span>, </span>Type</span> (</span>Type </span>ann</span>)) </span>->
</span>  (</span>LLVM</span>.</span>Type</span>, </span>LLVM</span>.</span>ParameterName</span>)
</span>functionArgToLLVM (</span>ArgumentName</span> argName, ty) =
</span>  </span>let</span> llvmType = typeToLLVM (getOuterTypeAnnotation ty)
</span>      paramName = </span>LLVM</span>.</span>ParameterName</span> (fromString (</span>T</span>.unpack argName))
</span>   </span>in</span> (llvmType, paramName)
</span></code></pre>
Now we can create IR for each function in our module. We put each function
variable in State</code> so that we can look them up when generating expressions:</p>
functionToLLVM </span>::
</span>  ( </span>LLVM</span>.</span>MonadModuleBuilder </span>m</span>,
</span>    </span>MonadFix </span>m</span>,
</span>    </span>MonadState OutputState </span>m</span>,
</span>    </span>MonadError OutputError </span>m
</span>  ) </span>=>
</span>  </span>Function</span> (</span>Type </span>ann</span>) </span>->
</span>  </span>m </span>()
</span>functionToLLVM (</span>Function</span> {fnAnn, fnFunctionName, fnBody, fnArgs}) = </span>do
</span>  </span>-- get llvm type of function
</span>  retType <- </span>case</span> fnAnn </span>of
</span>    </span>TFunction</span> _ _ tyRet -> pure $ typeToLLVM tyRet
</span>    _ -> throwError (</span>NonFunctionType</span> (fnAnn $> </span>()</span>))
</span>
</span>  </span>let</span> argTypes = functionArgToLLVM <$> fnArgs
</span>      functionName = functionNameToLLVM fnFunctionName
</span>
</span>  </span>-- create the LLVM function
</span>  llvmFunction <- </span>LLVM</span>.function functionName argTypes retType $ \args -> </span>do
</span>    </span>-- save the args in the environment
</span>    saveArgs
</span>      ( </span>M</span>.fromList $
</span>          zipWith
</span>            ( \(</span>ArgumentName</span> argName, _) arg ->
</span>                (</span>Identifier</span> argName, arg)
</span>            )
</span>            fnArgs
</span>            args
</span>      )
</span>
</span>    </span>-- build the LLVM AST for our expression
</span>    ourExpression <- exprToLLVM fnBody
</span>
</span>    </span>-- return result
</span>    </span>LLVM</span>.ret ourExpression
</span>  
</span>  </span>-- save reference to this function in our State to lookup in other
</span>  </span>-- expressions
</span>  saveFunction fnFunctionName llvmFunction
</span></code></pre>
We have two new cases in exprToLLVM</code>, for EVar</code> and EApply</code>. These somewhat
echo the implementation in the typechecker above. For EVar</code>, we lookup the
LLVM IR in our State</code>.</p>
exprToLLVM (</span>EVar</span> _ var) =
</span>  lookupArg var
</span></code></pre>
And for EApply</code>, we lookup the function in State</code>, then use LLVM's call</code> to
pass all the arguments to it.</p>
exprToLLVM (</span>EApply</span> _ fnName args) = </span>do
</span>  irFunc <- lookupFunction fnName
</span>  irArgs <- traverse exprToLLVM args
</span>  </span>LLVM</span>.call irFunc ((,</span>[]</span>) <$> irArgs)
</span></code></pre>
Finally, we bring it all together in the top level moduleToLLVM</code> function,
which takes our typechecked Module</code> and creates an LLVM module.</p>
-- | given our `Module` type, turn it into an LLVM module
</span>moduleToLLVM </span>:: Module</span> (</span>Type </span>ann</span>) </span>-> Either OutputError LLVM</span>.</span>Module
</span>moduleToLLVM (</span>Module</span> {mdExpr = expr, mdFunctions}) =
</span>  flip evalStateT (</span>OutputState</span> mempty mempty) $ </span>LLVM</span>.buildModuleT "</span>example</span>" $ </span>do
</span>    </span>-- get the printing function for our `expr`'s return type
</span>    printFn <- printFunction (getOuterAnnotation expr)
</span>
</span>    </span>-- create all our functions
</span>    traverse_ functionToLLVM mdFunctions
</span>
</span>    </span>-- create a function called `main` that will be the entry point to our
</span>    </span>-- program
</span>    </span>LLVM</span>.function "</span>main</span>" </span>[] LLVM</span>.i32 $ \_ -> </span>do
</span>      </span>-- build the LLVM AST for our expression
</span>      ourExpression <- exprToLLVM expr
</span>
</span>      </span>-- print our result to stdout
</span>      _ <- </span>LLVM</span>.call printFn [(ourExpression, </span>[]</span>)]
</span>
</span>      </span>-- return success exit code of `0`
</span>      </span>LLVM</span>.ret (</span>LLVM</span>.int32 </span>0</span>)
</span></code></pre>
You can see all of the LLVM generation code
here</a>.</p>

Well, well, well, if it's not the end of the article</h3>
Congratulations, you are all functional programming language implementation experts now. Hopefully you found that somewhat interesting and/or useful.
Next time we'll be adding basic product types and pattern matching. Great!</p>
Make sense? If not, get in touch</a>!</p>
Further reading:</p>
llvm reference</a></p>
llvm-calc</a></p>


Compiling a functional language to LLVM, part 2
Unknown — Thu, 23 Feb 2023 00:00:00 +0000
Welcome to part 2 of this series in compiling functional languages to LLVM. In
part 1</a> we created a very simple
calculator that let us add, subtract and multiply integers like 1 + 1</code> or 6 * (5 - 2)</code>.</p>
Today we're going to spice things up a touch by adding some basic control flow.
By the end of today we're going to be writing sweet syntax such as:</p>
2</span> + 2 == 5
</span>
</span>if </span>6</span> == 6 then False else True
</span></code></pre>
What's new then?</h2>
To make our dreams come true, we're going to two new
syntactic features:</p>


if</code> expressions</p>
</li>

an ==</code> infix operator</p>
</li>
</ul>
Let's do that now!</p>
-- | operators for combining expressions
</span>data </span>Op
</span>  = </span>OpAdd
</span>  | </span>OpMultiply
</span>  | </span>OpSubtract
</span>  | </span>OpEquals </span>-- this is new! 
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>)
</span>
</span>-- | Expressions, decorated with some unknown `ann`
</span>data </span>Expr</span> ann
</span>  = </span>EPrim</span> ann </span>Prim </span>-- this `Prim` used to always be `Int`
</span>  | </span>EInfix</span> ann </span>Op</span> (</span>Expr</span> ann) (</span>Expr</span> ann)
</span>  | </span>EIf</span> ann (</span>Expr</span> ann) (</span>Expr</span> ann) (</span>Expr</span> ann) </span>-- this is new!
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>, </span>Functor</span>, </span>Foldable</span>, </span>Traversable</span>)
</span></code></pre>
Our EIf</code> constructor takes three Expr ann</code> as arguments. The first is the
predicate</code>, ie, the thing that must evaluate to True</code> or False</code>, and the
other two are expressions to be evaluated on the then</code> and else</code> branches.
For all of this to make any sense, these will need to be the same type.</p>
Types?</h2>
Previously we sort of glossed over the idea of types, because every value in
our calculator was either an Integer</code> (ie, 1</code>, 42</code>) or an expression that would eventually
evaluate into an Integer</code> (like 1 + 1</code>, 6 * 12</code>).</p>
However, the expression 1 == 1</code> doesn't resolve to an Integer</code>, it can only
be True</code> or False</code>, ie a Boolean</code> type. (it is true that we could express
this with an Integer</code> but if we start cutting corners this early in the game
we'll never get anywhere). This means we'll need to extend our Prim</code> type to also describe Boolean</code> values as
well as Integer</code>s.</p>
-- | types of basic values
</span>data </span>Prim
</span>  = </span>PInt Integer
</span>  | </span>PBool Bool
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>)
</span></code></pre>
However this means we are in danger of our users being able to make silly mistakes like if 27 then False else 6</code>? How can we stop this? This can only mean one thing: we are going to need
to write a bidirectional type checker.</p>
Bidirect what?</h3>
A bidirectional type checker is a way of working which types parts of an
expression has, and identifying parts that don't make sense. What makes it
"bidirectional" is that it works in two "modes":</p>

infer</code> mode: given an expression, give me the type</li>
check</code> mode: given an expression and the type we think it has, give me the
type</li>
</ul>
The broad idea is when we don't know anything about an expression, we infer</code>
what types it has, but as we learn more, we use that information to help us
work the rest out. Although we could arguably get away with just an infer</code> mode for a language
this simple, we will need this special two-way magic in future.</p>
Enough waffle, let's see some code, and then talk about it.</p>
Code</h3>
Firstly, we need a type for types. We'll call it Type</code>. We are adding an ann</code>
type argument to it, so that we can attach source code locations etc. This will
be helpful for showing our user helpful errors, which we will be doing today:</p>
data </span>TypePrim </span>= </span>TBool </span>| </span>TInt
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>)
</span>
</span>-- the `ann` is used to attach source code location etc
</span>data </span>Type</span> ann
</span>  = </span>TPrim</span> ann </span>TypePrim
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>, </span>Functor</span>)
</span></code></pre>
Things go wrong</h3>
Any old typechecker can tell you when things are going well, but the ones that
are really worth their salt are the ones that tell you helpfully what is going
wrong. We will need these ones:</p>
data </span>TypeError</span> ann
</span>  = </span>PredicateIsNotBoolean</span> ann (</span>Type</span> ann)
</span>  | </span>InfixTypeMismatch Op</span> [(</span>Type</span> ann, </span>Type</span> ann)]
</span>  | </span>TypeMismatch</span> (</span>Type</span> ann) (</span>Type</span> ann)
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>)
</span></code></pre>
The meat of the thing</h3>
Therefore, the point of the typechecker is to take Expr ann</code> (ie, an Expr</code>
carrying around some ann</code> that does not concern us), and turn it into either
TypeError ann</code> or Expr (Type ann)</code>.</p>
Expr (Type ann)</code> means that we'll have "decorated" each part of the Expr</code>
with it's type. We'll take whatever ann</code> was in there and put it in the Type</code>
instead. For example:</p>
oneWhichIsAnInteger </span>:: Expr</span> (</span>Type </span>())
</span>oneWhichIsAnInteger = </span>EPrim</span> (</span>TPrim () TInt</span>) (</span>PInt 1</span>)
</span></code></pre>
The entire typechecker lives
here</a>.
Let's go through the key parts:</p>

-- | this is the function we run
</span>elaborate </span>:: Expr </span>ann </span>-> Either</span> (</span>TypeError </span>ann</span>) (</span>Expr</span> (</span>Type </span>ann</span>))
</span>elaborate = infer </span>-- start with `infer` because we know nothing
</span></code></pre>
elaborate</code> is the function the typechecker exports. It takes an untypechecked
Expr ann</code> and returns either Expr (Type ann)</code> or an excuse. It starts by
running infer</code>, which we'll see shortly.</p>

typeFromPrim </span>:: </span>ann </span>-> Prim -> Type </span>ann
</span>typeFromPrim ann (</span>PInt</span> _) = </span>TPrim</span> ann </span>TInt </span>-- It's an Integer!
</span>typeFromPrim ann (</span>PBool</span> _) = </span>TPrim</span> ann </span>TBool </span>-- It's a Boolean!
</span></code></pre>
The most basic type inference we can do is looking at a primitive value. As it
stands in our language, there is one number type and one boolean type, so we
can unambiguously work out the type just by looking at the value.</p>

inferIf </span>:: </span>ann </span>-> Expr </span>ann </span>-> Expr </span>ann </span>-> Expr </span>ann </span>-> Either</span> (</span>TypeError </span>ann</span>) (</span>Expr</span> (</span>Type </span>ann</span>))
</span>inferIf ann predExpr thenExpr elseExpr = </span>do
</span>  predA <- infer predExpr
</span>  </span>case</span> getOuterAnnotation predA </span>of
</span>    (</span>TPrim</span> _ </span>TBool</span>) -> pure </span>()
</span>    otherType -> throwError (</span>PredicateIsNotBoolean</span> ann otherType)
</span>  thenA <- infer thenExpr
</span>  elseA <- check (getOuterAnnotation thenA) elseExpr
</span>  pure (</span>EIf</span> (getOuterAnnotation elseA) predA thenA elseA)
</span></code></pre>
This is how if</code> works. We infer</code> the type of the predicate, then use
getOuterAnnotation</code> to get the Type ann</code> out of it. We then case match on it
to see if it's a Boolean</code> or not, "throwing" an error if not.</p>

inferInfix </span>::
</span>  </span>ann </span>->
</span>  </span>Op ->
</span>  </span>Expr </span>ann </span>->
</span>  </span>Expr </span>ann </span>->
</span>  </span>Either</span> (</span>TypeError </span>ann</span>) (</span>Expr</span> (</span>Type </span>ann</span>))
</span>inferInfix ann </span>OpEquals</span> a b = </span>do
</span>  elabA <- infer a
</span>  elabB <- infer b
</span>  ty <- </span>case</span> (getOuterAnnotation elabA, getOuterAnnotation elabB) </span>of
</span>    (</span>TPrim</span> _ tA, </span>TPrim</span> _ tB)
</span>      | tA == tB ->
</span>          </span>-- if the types are the same, then great! it's a bool!
</span>          pure (</span>TPrim</span> ann </span>TBool</span>)
</span>    (otherA, otherB) ->
</span>      </span>-- otherwise, error!
</span>      throwError (</span>TypeMismatch</span> otherA otherB)
</span>  pure (</span>EInfix</span> ty </span>OpEquals</span> elabA elabB)
</span></code></pre>
When typechecking ==</code>, we want to make sure both sides have the same type,
"throwing" an error if not.</p>

inferInfix ann op a b = </span>do
</span>  elabA <- infer a
</span>  elabB <- infer b
</span>  </span>-- all the other infix operators need to be Int -> Int -> Int
</span>  ty <- </span>case</span> (getOuterAnnotation elabA, getOuterAnnotation elabB) </span>of
</span>    (</span>TPrim</span> _ </span>TInt</span>, </span>TPrim</span> _ </span>TInt</span>) ->
</span>      </span>-- if the types are the same, then great! it's an int!
</span>      pure (</span>TPrim</span> ann </span>TInt</span>)
</span>    (</span>TPrim</span> _ </span>TInt</span>, other) ->
</span>      throwError
</span>        ( </span>InfixTypeMismatch
</span>            op
</span>            [ ( </span>TPrim</span> (getOuterTypeAnnotation other) </span>TInt</span>,
</span>                other
</span>              )
</span>            ]
</span>        )
</span>    (other, </span>TPrim</span> _ </span>TInt</span>) ->
</span>      throwError
</span>        ( </span>InfixTypeMismatch
</span>            op
</span>            [ ( </span>TPrim</span> (getOuterTypeAnnotation other) </span>TInt</span>,
</span>                other
</span>              )
</span>            ]
</span>        )
</span>    (otherA, otherB) ->
</span>      </span>-- otherwise, error!
</span>      throwError
</span>        ( </span>InfixTypeMismatch
</span>            op
</span>            [ (</span>TPrim</span> (getOuterTypeAnnotation otherA) </span>TInt</span>, otherA),
</span>              (</span>TPrim</span> (getOuterTypeAnnotation otherB) </span>TInt</span>, otherB)
</span>            ]
</span>        )
</span>  pure (</span>EInfix</span> ty op elabA elabB)
</span></code></pre>
Here are the other operators. Both the arguments should be Integer</code> and the
return type is Integer</code>, otherwise we construct and return an error type. It
seems like a lot of work to be so specific, but look how helpful our errors
are!</p>
</p>
</p>
</p>
</p>
</p>
</p>
</p>
</p>
</p>
You can see all the error rendering code
here</a>.</p>

infer </span>:: Expr </span>ann </span>-> Either</span> (</span>TypeError </span>ann</span>) (</span>Expr</span> (</span>Type </span>ann</span>))
</span>infer (</span>EPrim</span> ann prim) =
</span>  pure (</span>EPrim</span> (typeFromPrim ann prim) prim)
</span>infer (</span>EIf</span> ann predExpr thenExpr elseExpr) =
</span>  inferIf ann predExpr thenExpr elseExpr
</span>infer (</span>EInfix</span> ann op a b) =
</span>  inferInfix ann op a b
</span></code></pre>
That's how we put infer</code> together, easy!</p>

check </span>:: Type </span>ann </span>-> Expr </span>ann </span>-> Either</span> (</span>TypeError </span>ann</span>) (</span>Expr</span> (</span>Type </span>ann</span>))
</span>check ty expr = </span>do
</span>  exprA <- infer expr
</span>  </span>if</span> void (getOuterAnnotation exprA) == void ty
</span>    </span>then</span> pure (expr $> ty)
</span>    </span>else</span> throwError (</span>TypeMismatch</span> ty (getOuterAnnotation exprA))
</span></code></pre>
Lastly, here's check</code>. We only use it when comparing arms of if</code> statements,
but soon this will become more interesting.</p>
You can see all of the typechecker code
here</a>.</p>

Interpreting our new friends</h2>
Before heading back into LLVM land, let's update our manual interpreter so we
can understand what's needed here.</p>
Firstly, it's now possible that our interpreter can fail. This will only happen
if our typechecker is not working as expected, but we should make a proper
error type for it anyway because we are good programmers who care about our
users.</p>
data </span>InterpreterError</span> ann
</span>  = </span>NonBooleanPredicate</span> ann (</span>Expr</span> ann)
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>)
</span></code></pre>
Interpreting infix expressions is a little bit more complicated, as our pattern
matches have to make sure we're looking at the right Prim</code> values. The
eagle-eyed may notice that a broken typechecker could send this into a loop.
Can you see where?</p>
interpretInfix </span>::
</span>  (</span>MonadError</span> (</span>InterpreterError </span>ann</span>) </span>m</span>) </span>=>
</span>  </span>ann </span>->
</span>  </span>Op ->
</span>  </span>Expr </span>ann </span>->
</span>  </span>Expr </span>ann </span>->
</span>  </span>m</span> (</span>Expr </span>ann</span>)
</span>interpretInfix ann </span>OpAdd</span> (</span>EPrim</span> _ (</span>PInt</span> a)) (</span>EPrim</span> _ (</span>PInt</span> b)) =
</span>  pure $ </span>EPrim</span> ann (</span>PInt </span>$ a + b)
</span>interpretInfix ann </span>OpSubtract</span> (</span>EPrim</span> _ (</span>PInt</span> a)) (</span>EPrim</span> _ (</span>PInt</span> b)) =
</span>  pure $ </span>EPrim</span> ann (</span>PInt </span>$ a - b)
</span>interpretInfix ann </span>OpMultiply</span> (</span>EPrim</span> _ (</span>PInt</span> a)) (</span>EPrim</span> _ (</span>PInt</span> b)) =
</span>  pure $ </span>EPrim</span> ann (</span>PInt </span>$ a * b)
</span>interpretInfix ann </span>OpEquals</span> (</span>EPrim</span> _ a) (</span>EPrim</span> _ b) =
</span>  pure $ </span>EPrim</span> ann (</span>PBool </span>$ a == b)
</span>interpretInfix ann op a b = </span>do
</span>  iA <- interpret a
</span>  iB <- interpret b
</span>  interpretInfix ann op iA iB
</span></code></pre>
We ended up with a MonadError</code> constraint above - why's that? It's because the
main interpret</code> function can now "explode" if we try and match a non-predicate
in an if statement. Our typechecker should</em> stop this happening of course.</p>
-- | just keep reducing the thing until the smallest thing
</span>interpret </span>::
</span>  ( </span>MonadError</span> (</span>InterpreterError </span>ann</span>) </span>m
</span>  ) </span>=>
</span>  </span>Expr </span>ann </span>->
</span>  </span>m</span> (</span>Expr </span>ann</span>)
</span>interpret (</span>EPrim</span> ann p) = pure (</span>EPrim</span> ann p)
</span>interpret (</span>EInfix</span> ann op a b) =
</span>  interpretInfix ann op a b
</span>interpret (</span>EIf</span> ann predExpr thenExpr elseExpr) = </span>do
</span>  predA <- interpret predExpr
</span>  </span>case</span> predA </span>of
</span>    (</span>EPrim</span> _ (</span>PBool True</span>)) -> interpret thenExpr
</span>    (</span>EPrim</span> _ (</span>PBool False</span>)) -> interpret elseExpr
</span>    other -> throwError (</span>NonBooleanPredicate</span> ann other)
</span></code></pre>
We interpret if statements by reducing the predicate down to a boolean, then
taking a peek, and then interpreting the appropriate branch. If we don't need a
branch, there's no need to interpret it!</p>
You can see all of the interpreter code
here</a>.</p>
OK, LLVM time</h2>
I feel like I'm rushing through all this, and maybe copy pasta-ing an entire
typechecker in the preamble was somewhat undisclined of me.</p>
BUT, here we go.</p>
Digression</h3>
Firstly, we'll add a new function to our C "standard library":</p>
void </span>printbool</span>(</span>int </span>b</span>) {
</span>  </span>printf</span>(b ? "</span>True</span>" : "</span>False</span>");
</span>}
</span></code></pre>
It will take an LLVM boolean, and print either True</code> or False</code> depending on
whether it is 0</code> or not.</p>
To the IR!</h3>
We're going to start by looking at the LLVM IR for the following arbitrary
expression:</p>
if </span>2</span> == 1 then True else False 
</span></code></pre>
; ModuleID = 'example'
</span>
</span>declare external ccc  void @printbool(i1)
</span>
</span>define external ccc  i32 @main()    {
</span>  %1 = icmp eq i32 2, 1
</span>  %2 = alloca i1
</span>  br i1 %1, label %then_0, label %else_0
</span>then_0:
</span>  store   i1 1, i1* %2
</span>  br label %done_0
</span>else_0:
</span>  store   i1 0, i1* %2
</span>  br label %done_0
</span>done_0:
</span>  %3 = load   i1, i1* %2
</span>   call ccc  void  @printbool(i1  %3)
</span>  ret i32 0
</span>}
</span></code></pre>
What a ride! Let's take it line by line.</p>

; ModuleID = 'example'
</span></code></pre>
Once again, let's ease ourselves in with a code comment.</p>

declare external ccc  void @printbool(i1)
</span></code></pre>
Declaration for the new function in our standard library. It takes an i1</code> (a
boolean, stored as 0</code> or 1</code>) and returns void</code>.</p>

define external ccc  i32 @main()    {
</span></code></pre>
We define the main</code> function, which is the entry point of our program. It
takes no arguments, and returns an i32</code> integer value (which becomes the exit
code).</p>

%1 = icmp eq i32 2, 1
</span></code></pre>
Here we are making a new variable, %1</code>, by comparing two integers, 2</code> and
1</code>, using eq</code>. This is our 2 == 1</code> expression, and maps across quite neatly.</p>

%2 = alloca i1
</span></code></pre>
To make control flow works, we are going to need to jump to different places.
However, LLVM has no way of passing a value back between sections. Therefore,
we are going to create a mutable placeholder for the result, and each branch
will be responsible for storing the result here. alloca</code> is broadly "allocate
memory" and i1</code> is the LLVM type for a Boolean</code>.</p>

br i1 %1, label %then_0, label %else_0
</span></code></pre>
This is where we do the branching. br</code> takes an i1</code> value for the predicate,
and then two labels for blocks that we'll jump to depending on the value of the predicate.
Therefore if %1</code> is 1</code> we'll jump to then_0</code>, otherwise we'll jump to
else_0</code>. We'll define these shortly.</p>

then_0:
</span>  store   i1 1, i1* %2
</span>  br label %done_0
</span></code></pre>
This defines a block labelled then_0</code>. We will "jump" here in the "then" case
of the if statement. We store 1</code> in the %2</code> variable, and then jump to the
done_0</code> block.</p>

else_0:
</span>  store   i1 0, i1* %2
</span>  br label %done_0
</span></code></pre>
This defines a block labelled else_0</code>. We will "jump" here in the "else" case.
Once again, we store 0</code> in the %2</code> variable, and then jump to done_0</code>.</p>

done_0:
</span>  %3 = load   i1, i1* %2
</span></code></pre>
This introduces a new block called done_0</code>. As our if construct is an
expression, we always need to return something, so ee jump here when the
then</code> or expr</code> branches are finishing doing their business, and load whatever
they stored in %2</code>.</p>

call ccc  void  @printbool(i1  %3)
</span></code></pre>
Call the printbool</code> function from our standard library with the loaded value.</p>

ret i32 0
</span></code></pre>
As our program succeeded, we return a 0</code>, this becomes our exit code.</p>

}
</span></code></pre>
As a little palette cleanser, a nice closing brace.</p>
Generating it from Haskell</h3>
Now we have Boolean</code> as well as Integer</code> values, we'll need to represent them
in LLVM. We'll use a bit</code> which is a 1-bit LLVM number to represent
Boolean</code>s.</p>
primToLLVM </span>:: Prim -> LLVM</span>.</span>Operand
</span>primToLLVM (</span>PInt</span> i) = </span>LLVM</span>.int32 (fromIntegral i)
</span>primToLLVM (</span>PBool True</span>) = </span>LLVM</span>.bit </span>1
</span>primToLLVM (</span>PBool False</span>) = </span>LLVM</span>.bit </span>0
</span></code></pre>
Now we'll need to choose the right printing function:</p>
-- import the correct output function from our standard library
</span>-- depending on the output type of our expression
</span>printFunction </span>::</span> (</span>LLVM</span>.</span>MonadModuleBuilder </span>m</span>) </span>=> Type </span>ann </span>-> </span>m </span>LLVM</span>.</span>Operand
</span>printFunction (</span>TPrim</span> _ </span>TInt</span>) = </span>LLVM</span>.extern "</span>printint</span>" [</span>LLVM</span>.i32] </span>LLVM</span>.void
</span>printFunction (</span>TPrim</span> _ </span>TBool</span>) = </span>LLVM</span>.extern "</span>printbool</span>" [</span>LLVM</span>.i1] </span>LLVM</span>.void
</span></code></pre>
The most interesting part is if</code> expressions. We use the RecursiveDo</code>
extension, which gives us the mdo</code> syntax. This lets us use bindings before
they are created. This will allow us to use thenBlock</code> and elseBlock</code> before
they're defined. We create IR for the predExpr</code>, then pass it to
LLVM.condBr</code>, which will then jump to the appropriate block depending on the
value.</p>
ifToLLVM </span>::
</span>  (</span>LLVM</span>.</span>MonadIRBuilder </span>m</span>, </span>LLVM</span>.</span>MonadModuleBuilder </span>m</span>, </span>MonadFix </span>m</span>) </span>=>
</span>  </span>Type </span>ann </span>->
</span>  </span>Expr</span> (</span>Type </span>ann</span>) </span>->
</span>  </span>Expr</span> (</span>Type </span>ann</span>) </span>->
</span>  </span>Expr</span> (</span>Type </span>ann</span>) </span>->
</span>  </span>m </span>LLVM</span>.</span>Operand
</span>ifToLLVM tyReturn predExpr thenExpr elseExpr = mdo
</span>  </span>-- create IR for predicate
</span>  irPred <- exprToLLVM predExpr
</span>
</span>  </span>-- make variable for return value
</span>  irReturnValue <- </span>LLVM</span>.alloca (typeToLLVM tyReturn) </span>Nothing 0
</span>
</span>  </span>-- this does the switching
</span>  </span>-- we haven't created these blocks yet but RecursiveDo lets us do this with
</span>  </span>-- MonadFix magic
</span>  </span>LLVM</span>.condBr irPred thenBlock elseBlock
</span>
</span>  </span>-- create a block for the 'then` branch
</span>  thenBlock <- </span>LLVM</span>.block `</span>LLVM</span>.named` "</span>then</span>"
</span>  </span>-- create ir for the then branch
</span>  irThen <- exprToLLVM thenExpr
</span>  </span>-- store the result in irResultValue
</span>  </span>LLVM</span>.store irReturnValue </span>0</span> irThen
</span>  </span>-- branch back to the 'done' block
</span>  </span>LLVM</span>.br doneBlock
</span>
</span>  </span>-- create a block for the 'else' branch
</span>  elseBlock <- </span>LLVM</span>.block `</span>LLVM</span>.named` "</span>else</span>"
</span>  </span>-- create ir for the else branch
</span>  irElse <- exprToLLVM elseExpr
</span>  </span>-- store the result in irReturnValue
</span>  </span>LLVM</span>.store irReturnValue </span>0</span> irElse
</span>  </span>-- branch back to the `done` block
</span>  </span>LLVM</span>.br doneBlock
</span>
</span>  </span>-- create a block for 'done' that we always branch to
</span>  doneBlock <- </span>LLVM</span>.block `</span>LLVM</span>.named` "</span>done</span>"
</span>  </span>-- load the result and return it
</span>  </span>LLVM</span>.load irReturnValue </span>0
</span></code></pre>
To work out which kind of type to alloca</code>, we take the return type and use it
to work which LLVM type to use.</p>
typeToLLVM </span>:: Type </span>ann </span>-> LLVM</span>.</span>Type
</span>typeToLLVM (</span>TPrim</span> _ </span>TBool</span>) = </span>LLVM</span>.i1
</span>typeToLLVM (</span>TPrim</span> _ </span>TInt</span>) = </span>LLVM</span>.i32
</span></code></pre>
You can see all of the LLVM conversion code
here</a>.</p>

Well that's that</h3>
Congratulations, you are all bidirectional type checking experts now. Hopefully that was
somewhat helpful. Next time we'll be adding basic functions and variables.
Great!</p>
Make sense? If not, get in touch</a>!</p>
Further reading:</p>
llvm reference</a></p>
llvm-calc</a></p>


Compiling a functional language to LLVM, part 1
Unknown — Wed, 08 Feb 2023 00:00:00 +0000
Recently I thought it would be good to start compiling the small functional
language mimsa</a> I've been messing
around with for the last few years to LLVM. There's a few really helpful
resources - Joseph Morag's Micro-C</a>
series, and Mapping High Level Concepts to LLVM
IR</a> in
particular, but neither go into converting functional programming paradigms
such as pattern matching, lambdas and ADTs in much depth.</p>
So, here we're going to give it a go. The plan is that we start with an
entirely working but tiny language, get it all working, and then as we add
features to the language, we'll also add a typechecker and introduce more LLVM
concepts. The source code for the whole working calculator, along with a basic repl, can be found
at llvm-calc</a>.</p>
Our language</h2>
The first iteration of our language is going to be the most basic of
calculators. Here is a valid program in our language:</p>
1</span> + 2 * (1 + 100) </span>-</span> 100
</span></code></pre>
Here are the datatypes for our language. We will use this to represent our
programs internally.</p>
data </span>Expr</span> ann
</span>  = </span>-- | An integer value
</span>    </span>EPrim</span> ann </span>Int
</span>  | </span>-- | Two values combined with an operator
</span>    </span>EInfix</span> ann </span>Op</span> (</span>Expr</span> ann) (</span>Expr</span> ann)
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>, </span>Functor</span>, </span>Foldable</span>, </span>Traversable</span>)
</span>
</span>-- | Operators for combining integers
</span>data </span>Op </span>= </span>OpAdd </span>| </span>OpMultiply </span>| </span>OpSubtract
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>)
</span></code></pre>
Here's some example values:</p>
-- | the number `1`
</span>one </span>:: Expr </span>()
</span>one = </span>EPrim () 1
</span>
</span>-- | the expression `2 + 3`
</span>twoPlusTwo </span>:: Expr </span>()
</span>twoPlusTwo = </span>EInfix () OpAdd</span> (</span>EPrim () 2</span>) (</span>EPrim () 3</span>)
</span></code></pre>
We call datatypes like Expr</code> Abstract Syntax Trees</em> (or ASTs).</p>
You may notice the ann</code> type variable. We'll use this to "decorate" items in
our AST. For now, we'll just use ()</code>.</p>
Parsing text into AST terms</h2>
Although we could provide our compiler as a Haskell library and ask our users
to manually create Expr</code> values for us, it'd be much nicer to be able to read
input from a user.</p>
This process is called parsing</em>, and looks something like this:</p>
parseInput </span>:: Text -> Either ParseError</span> (</span>Expr </span>())
</span></code></pre>
Given some user input, parsing returns either a valid Expr</code> or a (hopefully)
helpful error.</p>
The whole parser can be seen
here</a>. We'll not go into too much depth as there are already lots of great references
on parsing, but a few details are worth noting:</p>
Which library?</h3>
We'll be using a library called
megaparsec</a>. It's fast, it's got a great
tutorial</a>, and it generates errors that we can render nicely with the diagnose</a> library.</p>
</p>
Dealing with whitespace</h3>
Although some languages make whitespace meaningful, we won't be bothering with
any of that for now. However we would like to allow our users some flexibility
with how they lay out their code. 1+1</code> and   1    + 1</code> should mean the same thing. That means we either need a lot of code like this:</p>
parseInfix </span>:: Parser Int
</span>parseInfix = </span>do
</span>  _ <- space0 </span>-- this accepts 0 or more spaces 
</span>  a <- parseInt
</span>  _ <- space0 </span>-- space between number and operator
</span>  op <- parseOp
</span>  <- <- space0 </span>-- space between operator and second number
</span>  b <- parseInt
</span>  pure (</span>Infix</span> op a b)
</span></code></pre>
...or we need a neat way of automating this. megaparsec</code> has a handy thing
called a lexeme</code>. This is a sort of rule that says
"when eating this value, also eat all the whitespace before it". When you see
myLexeme</code> in the code, this means we're wrapping a parser with
whitespace-eating powers. This is
covered in much better detail in the
megaparsec tutorial</a>.</p>
Parsing infixes</h3>
One problem with parser combinator libraries is that it's easy to get into an
infinite loop. megaparsec</code> has a bunch of useful helpers for this, in
particular, support for Operator</code>.</p>
-- | to make infix stuff like easier, `megaparsec` provides
</span>-- the `Operator` type
</span>table </span>::</span> [[</span>Operator Parser</span> (</span>Expr Annotation</span>)]]
</span>table =
</span>  [ [binary "</span>*</span>" (</span>EInfix</span> mempty </span>OpMultiply</span>)],
</span>    [ binary "</span>+</span>" (</span>EInfix</span> mempty </span>OpAdd</span>),
</span>      binary "</span>-</span>" (</span>EInfix</span> mempty </span>OpSubtract</span>)
</span>    ]
</span>  ]
</span></code></pre>
A nice part of the the above code is that by putting *</code> in a group before +</code>
and -</code>, we have defined operator precidence and so 6 * 1 + 1</code> equals 7</code> rather
than 12</code> (which we'd get from 6 * (1 + 1)</code>).</p>
Source code location</h3>
You may have noticed the ann</code> type variable in our Expr</code> type. This allows us
to "decorate" our AST nodes. In parsing, it's useful to decorate each node with
it's location in the code.</p>
We use the following datatype for this:</p>
data </span>Annotation </span>= </span>Location Int Int
</span>  </span>deriving</span> stock (</span>Eq</span>, </span>Ord</span>, </span>Show</span>)
</span></code></pre>
The two Int</code> values are "character number we start at" and "length of the
string". Therefore parsing " 100" should return:</p>
parseResult </span>:: Expr Annotation
</span>parseResult = </span>EPrim</span> (</span>Location 1 3</span>) </span>100
</span></code></pre>
We won't be using these values today as our language is so limited that it's
pretty difficult to break, but as we add multiple types (and thus, the
possibility of type errors) we'll use them to show the user where they did a
boo boo.</p>
A simple interpreter</h2>
Before we get stuck into LLVM</code>, it's good to be able to evaluate our language
internally. Although it's pretty clear how this calculator should work, it
will be useful to compare our own simple interpreter with the LLVM output as
things get more complicated.</p>
You can view the full code
here</a>.
As you can see, there isn't very much of it:</p>
interpret </span>::
</span>  </span>Expr </span>ann </span>->
</span>  </span>Expr </span>ann
</span>interpret (</span>EPrim</span> ann p) = 
</span>  </span>-- don't do anything with these
</span>  </span>EPrim</span> ann p
</span>interpret (</span>EInfix</span> ann op a b) =
</span>  </span>-- attempt to simplify these 
</span>  interpretInfix ann op a b
</span>
</span>interpretInfix </span>::
</span>  </span>ann </span>->
</span>  </span>Op ->
</span>  </span>Expr </span>ann </span>->
</span>  </span>Expr </span>ann </span>->
</span>  </span>Expr </span>ann
</span>interpretInfix ann </span>OpAdd</span> (</span>EPrim</span> _ a) (</span>EPrim</span> _ b) =
</span>  </span>-- add the int values
</span>  </span>EPrim</span> ann (a + b)
</span>interpretInfix ann </span>OpSubtract</span> (</span>EPrim</span> _ a) (</span>EPrim</span> _ b) =
</span>  </span>-- subtract the int values
</span>  </span>EPrim</span> ann (a - b)
</span>interpretInfix ann </span>OpMultiply</span> (</span>EPrim</span> _ a) (</span>EPrim</span> _ b) =
</span>  </span>-- multiply the int values
</span>  </span>EPrim</span> ann (a * b)
</span>interpretInfix ann op a b = 
</span>  </span>-- one of our arguments isn't yet a number
</span>  </span>-- so simplify the leaves and try again
</span>  interpretInfix ann op (interpret a) (interpret b)
</span></code></pre>
When we see an EInfix</code> value, we look for EPrim</code> values inside and add</code> / subtract</code> / multiply</code> them. If they're
not EPrim</code> values yet, then they must be nested expressions, so we interpret</code> them
and try again.</p>
</p>
Enough nonsense, let's do some compiling</h2>
Hopefully we understand what our small language is now, so let's get down to
the business of turning it into real life native code.</p>
What is LLVM</h3>
LLVM stands for Low Level Virtual Machine. The idea is that higher level languages compile into LLVM, and then LLVM is turned into whatever local version of assembly is required. This means that by using LLVM, your programs will work on lots of architectures without you needing to understand a tremendous amount about them. As somebody who understands pretty much nothing about any processor architecture, this is very appealing indeed. If you need further persuading, Rust</code>, Swift</code> and GHC</code> can all compile to
LLVM.</p>
LLVM is part of the clang</code> C compiler, and as a result, it's very C shaped.
It's got a bunch of number types, structs, and arrays, functions, and enough pointers to have a
very bad time.</p>
Our "runtime"</h3>
In order to do things</em> our language will need a runtime, This is a bunch of helper code written in something that be compiled to the target
language. Because we'll be compiling using clang</code>, we'll use C</code>. I don't know much about C</code>, but what I can tell you is that this file contains a single function called printint</code>, that takes an int</code> and prints
it to stdout</code>.</p>
#include </span><</span>stdio.h</span>>
</span>#include </span><</span>stdlib.h</span>>
</span>
</span>void </span>printint</span>(</span>int </span>i</span>) {
</span>  </span>printf</span>("</span>%d</span>", i);
</span>}
</span></code></pre>
This is the only C</code> you'll need to see today. I'm sorry about that. Onwards!</p>
Our first LLVM module</h3>
LLVM is organised in modules</a>.</p>
To start us off, here is the IR (Intermediate Representation) for printing the number 42</code> to stdout</code>.</p>
; ModuleID = 'calc'
</span>
</span>declare external ccc i32 @printint(i32)
</span>
</span>define external ccc i32 @main()    {
</span>  %1 =  call ccc i32 @printint(i32  42)
</span>  ret i32 0
</span>}
</span></code></pre>
Let's take this apart line by line:</p>

; ModuleID = 'calc'
</span></code></pre>
This is a comment. See, LLVM is easy.</p>

declare external ccc i32 @printint(i32)
</span></code></pre>
This declares an external function we'd like to use. In this case it's the
printint</code> function from our standard library defined above. It
takes a single argument, an i32</code>, and returns an i32</code>.</p>

define external ccc i32 @main() {
</span></code></pre>
This defines a function called main</code> that takes no arguments and returns a
single i32</code>.</p>
The ccc</code> part is the "calling convention". This defines the manner in which
LLVM will generate the function code. There are absolutely loads of these</a>, many
designs to optimise specific languages. We'll keep to ccc</code> for now, but may
want to change our minds when we start doing tail calls.</p>

%1 =  call ccc i32 @printint(i32  42)
</span></code></pre>
This line of defines a variable %1</code>, and sets it the result of calling the
printint</code> function we imported above. We pass the printint</code> function a single
argument, an i32</code> value of 42</code>. This will print the number 42</code> to stdout.</p>

ret i32 0
</span></code></pre>
Functions in LLVM</code> must return something (although that thing can be null</code>).
This line returns an i32</code> value of 0</code>. Because this is the main</code> function of
our program, this is what will be returned to the operating system as our exit
code. 0</code> means "great job, everything went fine".</p>

}
</span></code></pre>
This is a closing curly brace. LLVM</code> is like C</code>, we have to specifically
end our functions. No great hardship though.</p>

Compiling and running our hand-baked module</h3>
To check that the code above does what we say it does, and to check we've got
everything installed that we need, let's write the LLVM to a file called
module.ll</code>, the C code to runtime.c</code>, and then compile it using clang</code>.</p>
clang -Wno-override-module -lm</span> module.ll runtime.c</span> -o</span> a.out 
</span></code></pre>
This should output an executable called a.out</code>. If we run it, we should see
this:</p>
./a.out
</span>42
</span></code></pre>
Hooray!</p>
Compiling our programming language to LLVM</h2>
OK. So now we've had a taste of the raw power available to us, let's get down
to business. Although we could just create raw LLVM IR by hand, instead we will use the following
libraries:</p>
llvm-hs-pure</a> - a set of
types for LLVM IR, along with some helpful building functions.</p>
llvm-hs-pretty</a> - a
prettyprinter for llvm-hs-pure</code>.</p>
We'll use the datatypes in llvm-hs-pure</code> to create modules, then use llvm-hs-pretty</code> to render these to files and then compile by hand. This means that when we
invariably generate LLVM errors, we'll at least we able to look at the error
and reference the code we've given it to try and work out what went wrong.</p>
Shut up and show me some Haskell code</h3>
The whole module can be seen
here</a>, but let's look at the highlights:</p>

primToLLVM </span>:: Int -> LLVM</span>.</span>Operand
</span>primToLLVM i = </span>LLVM</span>.int32 (fromIntegral i)
</span></code></pre>
This function creates integer literals from our EPrim</code> constructors, using
the int32</a> function.
This returns an Operand</code> (an LLVM value, broadly) that we can pass to other LLVM functions. We'll
expand this function to include more types as we need them.</p>

exprToLLVM </span>::
</span>  ( </span>LLVM</span>.</span>MonadIRBuilder </span>m</span>,
</span>    </span>LLVM</span>.</span>MonadModuleBuilder </span>m
</span>  ) </span>=>
</span>  </span>Expr </span>ann </span>->
</span>  </span>m </span>LLVM</span>.</span>Operand
</span>exprToLLVM (</span>EPrim</span> _ prim) = 
</span>  pure $ primToLLVM prim
</span>exprToLLVM (</span>EInfix</span> _ </span>OpAdd</span> a b) = </span>do
</span>  lhs <- exprToLLVM a
</span>  rhs <- exprToLLVM b
</span>  </span>LLVM</span>.add lhs rhs
</span>exprToLLVM (</span>EInfix</span> _ </span>OpSubtract</span> a b) = </span>do
</span>  lhs <- exprToLLVM a
</span>  rhs <- exprToLLVM b
</span>  </span>LLVM</span>.sub lhs rhs
</span>exprToLLVM (</span>EInfix</span> _ </span>OpMultiply</span> a b) = </span>do
</span>  lhs <- exprToLLVM a
</span>  rhs <- exprToLLVM b
</span>  </span>LLVM</span>.mul lhs rhs
</span></code></pre>
Here we compile our Expr</code> into and take care of adding /
subtracting / multiplying integers.</p>
Because we're using the MonadIRBuilder</code>
and MonadModuleBuilder</code>, it's almost as if we're writing code to do the
interpreting by hand, as all the actual code output is plumbed away in the
monad. If you squint, it looks very similar to the interpreter we wrote earlier, so if you
understand that, you pretty much understand this.</p>

-- | given our `Expr` type, turn it into an LLVM module
</span>toLLVM </span>:: Expr </span>ann </span>-> LLVM</span>.</span>Module
</span>toLLVM expr =
</span>  </span>LLVM</span>.buildModule "</span>example</span>" $ </span>do
</span>    </span>-- import `printint` from our standard library
</span>    </span>-- it takes an `i32` and returns an `i32`
</span>    printInt <- </span>LLVM</span>.extern "</span>printint</span>" [</span>LLVM</span>.i32] </span>LLVM</span>.i32
</span>
</span>    </span>-- create a function called `main` that will be the entry point to our
</span>    </span>-- program
</span>    </span>LLVM</span>.function "</span>main</span>" </span>[] LLVM</span>.i32 $ \_ -> </span>do
</span>      </span>-- build the LLVM AST for our expression
</span>      ourExpression <- exprToLLVM expr
</span>
</span>      </span>-- print our result to stdout
</span>      _ <- </span>LLVM</span>.call printInt [(ourExpression, </span>[]</span>)]
</span>
</span>      </span>-- return success exit code of `0`
</span>      </span>LLVM</span>.ret (</span>LLVM</span>.int32 </span>0</span>)
</span></code></pre>
Finally, we wrap up our compiled Expr</code> and turn it into a
module. We are going to import printint</code> from our standard library, output the
response of our computation to stdout, and then return exit code 0</code>.</p>
Let's look at the generated LLVM for 6 * 8 - 3</code>:</p>
; ModuleID = 'example'
</span>
</span>declare external ccc i32 @printint(i32)
</span>
</span>define external ccc i32 @main() {
</span>  %1 = mul   i32 6, 8
</span>  %2 = sub   i32 %1, 3
</span>  %3 =  call ccc  i32  @printint(i32  %2)
</span>  ret i32 0
</span>}
</span></code></pre>
Hopefully, nothing too surprising.</p>
Running our code</h2>
As with earlier, our little compiler works by pretty printing the LLVM module
we created, then running clang</code> to compile it into an executable. I pretty
much stole the compiling code from
Micro-C</a> (thanks/sorry, Joseph!).
You can see our slightly tattered version
here</a> if for some reason you don't believe any of this actually works.</p>
Well that's that</h3>
Congratulations, you are all low-level compiler experts now. Hopefully that was
somewhat helpful. Next time we'll be adding the equality operator and some basic control flow.
Exciting!</p>
Make sense? If not, get in touch</a>!</p>
Further reading:</p>
llvm reference</a></p>
llvm-calc</a></p>


Hindley Milner typechecking by example
Unknown — Sun, 24 Jul 2022 00:00:00 +0000
So I've been getting really interested in typechecking, and well, the best way
to learn is to try and explain it in words, so here we go.</p>
There are many kinds of typechecking, but today I want to explain a variation
on Hindley Milner (I've also seen it called Damas Milner, please feel free to
ping with the actual truth, fact fans). This kind of type system is the kind
you'll find under OCaml, Elm, Haskell and Purescript, although each language has their own variations (and in the case of Haskell, a terrifying number of extensions to it).</p>
A working example</h2>
We're going to start by typechecking the simplest stuff, and then build up
features as we go. There are three stages to our algorithm, Elaboration</code>,
Unification</code> and Substitution</code>. We'll introduce them as we need them.</p>

🥚 Elaboration 🥚</strong></p>
Here go through the expression we'd like to typecheck, marking each
part of the AST with the thing we think it is (and if we don't know, we sort of guess). We'll also produce
a set of constraints about the types we've worked out (a constraint is
something like "I don't know a</code> or b</code> are but I know they're the same
thing"</strong>)</p>
</blockquote>
Literals</h3>
Literals are static values declared in code. Our toy language has the
Boolean</code>, Integer</code> and String</code> types. As this means there is no ambiguity
between them, we can work out their types in the Elaboration</code> stage alone.</p>
</p>
The values are on the left in black, the types on the right in blue. No weird surprises here, hopefully.</p>
Let bindings</h3>
It is nice to be able to give things names, so we should have some let bindings
in our language. These allow us to introduce a new concept - the typechecking
environment. A let binding has two sub-expressions - the first is the one
that gets "bound" and assigned to the name, and then the body, which can refer
to the bound expression by name.</p>
</p>
In this example, our environment (shown in green) is initially empty, but as we were able to
elaborate the type of a</code> as Integer</code>, the environment when typechecking the
body also includes a == Integer</code>. However, this has no effect on the type of
the whole expression, as the body of the let binding is True</code> which we know is of type Boolean</code>.</p>
Variable</h3>
It's all well and good making variables, but it's even more useful to refer to
them later. Given a typechecking environment that already knows about b</code>, we
can look it up:</p>
</p>
If it's not there, we
throw a type error and tell the user they've made a typo or something. If it
is, then we return the type from the environment.</p>
If / Then / Else</h3>
An if statement in our language is an expression, meaning it must return
something from both the then</code> and the else</code> branch. It contains three
sub-expressions, one for the predicate we are testing (which must be of type
Boolean</code>), one for the then</code> branch, and one for the else</code> branch.</p>
</p>
Because each of these sub-expressions are literal values, we can elaborate their
values as we did above. The return type is Integer</code>, as that is the type we
have worked out for the then</code> branch (it could as well be the type of the
else</code> branch, they should be the same).</p>
How do we ensure all our rules work out? That's the job of the constraints that
we have generated (shown in red). We have one that ensures the type of True</code> matches
Boolean</code>, and another that ensures the types of the then</code> and else</code> branches are the same.</p>

🥚 Unification 🥚</strong></p>
Now that we have constraints, we need to check they make sense. Unification in the context of typechecking is about smashing two things
together and seeing what we learn.</p>
The outcome of unification is either a type error or a set of substitutions, such as "replace all c</code> values with String</code>"</strong>.</p>
</blockquote>
Here the two things are the same in both cases, so everything is fine and we
learn nothing new.</p>
</p>
Lambda</h3>
A lambda is a function abstraction. When elaborating lambdas, we don't know what the type of the argument will be. Different type systems have different approaches to this problem.
One solution is to make the programmer annotate the argument with a type (ie,
\(a: String) -> ...</code>). However, Hindley Milner typechecking is all about
minimising type annotations, so instead we'll guess it. We do this by creating a fresh unknown type variable called a
"unification variable". Each of these should be unique within the typechecking,
so they often use numbers with an internal counter to generate fresh ones.
We're going to use the unimaginative unknown-1</code>.</p>
</p>
Then, when we elaborate the body of the lambda, we add a == unknown-1</code> to the
environment, which makes typechecking the variable a</code> straightforward, making
the type of the whole lambda unknown-1 -> unknown-1</code> (the -></code> meaning "a
function from a to b")</p>
Function application</h3>
Elaboration</h4>
What's the use in functions if we can't apply values to them? Given the id</code> function has already been defined, let's apply a value to it.</p>
</p>
Since the function type is unknown-1 -> unknown-1</code>, we apply Boolean</code> to it,
by creating a constraint between the first unknown-1</code> and Boolean</code>. Then the
return type from elaboration is the second half of the function type (also
unknown-1</code>).</p>
Surely it should be Boolean</code> though right? No, but also, yes, but also, it's
complicated...</p>
Unifying our new constraint</h4>
Let's look at the constraint we've generated during elaboration.</p>
</p>
As we briefly mentioned earlier, we unify values to learn things about them. Because unknown-1</code> is a unification variable, it represents an unknown thing that we are trying to find out more about.
Unifying it with Boolean</code> tells us unknown-1</code> is actually Boolean</code>, and therefore we can substitute any instance of unknown-1</code> for Boolean</code>.</p>
Apply the substitution</h4>
We apply a substitution by changing all instances of one thing in a type for another. Applying a substitution to the result of elaboration gives us our final type,
Boolean</code></p>
</p>

🥚 Substitution 🥚</strong></p>
Assuming we had no type errors in the previous step, then
subsitution is the process of taking all the things we have learned and
applying them to both to expression and to the other substitutions.</p>
For example, if we have learned "a</code> is an Integer</code>"</strong> then we can change any a</code>
values in our expression to Integer</code>, and also change the substitution "c</code>
is a pair of a</code> and b</code>"</strong> into "c</code> is a pair of Integer</code> and b</code>"</strong>.</p>
</blockquote>
A bigger example</h3>
To see Hindley Milner typechecking in action, here is a slightly bigger
example. Here we'll see how we can get full type inference without a type
annotation in sight.</p>
</p>
We start by elaborating the function argument, a</code>. We have no idea what it is,
so we create a unification variable, unknown-1</code>, and use that instead.</p>
Then we move onto the body of the lambda, an if expression. The predicate
expression is a</code>. Fortunately, we already have the type for a</code> in the type
environment - so we can grab it. We don't know what unknown-1</code> is yet, but we
have another piece of information on our side - the predicate for an if</code> must
be a Boolean</code>. We express this by creating a new constraint unknown-1 == Boolean</code>.</p>
The then</code> and else</code> expressions are both literals, so we can infer those
quite simply, making Integer</code> the return type of the if</code> expression. There is
also another constraint here, that both branches should have the same type -
Integer == Integer</code>.</p>
Unifying our new constraints</h4>
We have two contraints from elaboration.</p>
First Integer == Integer</code>, which teaches us nothing (but does type check).</p>
</p>
Secondly unknown-1 == Boolean</code> gives us a substitution.</p>
Apply the substitution</h4>
</p>
So, therefore, the type of \a -> if a then 1 else 2</code> is Boolean -> Integer</code>.</p>
That's all folks</h3>
The writing that is, that is the end of the writing. There is a bunch more to
Hindley Milner typechecking, we've neatly sidestepped any complicated
polymorphism, however rest assured that it doesn't make things too</em> much
complicated which is nice. I might write about that in future, so given the
glacial pace of my writing, look forward to a sequel in 2024.</p>
Make sense? If not, get in touch</a>!</p>
Further reading:</p>
giml</a></p>
Write you a Haskell</a></p>
mimsa</a></p>


What the hell is a content addressed language
Unknown — Tue, 28 Dec 2021 00:00:00 +0000
Over the last year and a half I haven't really written much stuff, because I
have been working on a small content-addressed programming language called
mimsa</a>. I'm not really sure why I am doing this, other than that I watched a
neat tutorial about how typecheckers worked</a>, and then got somewhat carried away.</p>
I has sat down to write about my recent implementation of property testing in said
lang, then realised that before I can do that I should probably provide some
context.</p>
So, what IS a content-addressed language?</h3>
According to Unison</a>, the language that pioneered
this concept, this means "code is immutable and identified by its content".</p>
Let's take that apart a bit:</p>
Say I have a function for adding two numbers:</p>
add </span>:: Int -> Int -> Int
</span>add a b = a + b
</span></code></pre>
Instead of just dumping this in a text file, I would "save" this function. In
the mimsa</code> repl, I would do this:</p>
:> :bind add = \a -> \b -> a + b
</span>Bound</span> add.
</span></code></pre>
This has saved the expression \a -> \b -> a + b</code> in the project, and pointed add</code>
to refer to said expression.</p>
Let's use our new function:</p>
:> add </span>1 3
</span>4 </span>:: </span>Int
</span>
</span>:> add </span>2 2
</span>4 </span>:: </span>Int
</span></code></pre>
Hopefully, no surprises there.</p>
Let's make a new function that uses add</code>:</p>
:> bind add3 = add </span>3
</span></code></pre>
This has saved the expression add 3</code> in the DB, and pointed add3</code> at it. More
importantly, it has also remembered exactly which add</code> function it used (more
on this shortly).</p>

Like haskell</code> or elm</code>, mimsa</code> functions only take one argument, so
applying 3</code> to add</code> (which has type Int -> Int -> Int</code>) returns a new
function with type Int -> Int</code>.</p>
</blockquote>
Again, let's test it and check for surprises:</p>
:> add3 </span>2
</span>5 </span>:: </span>Int
</span>
</span>:> add3 </span>0
</span>3 </span>:: </span>Int
</span></code></pre>
All seems well.</p>
Now what if we decide to make add</code> evil? We are allowed to rebind it, so let's
do that:</p>
:> bind add = \a -> \b -> a + b + </span>1
</span>Updated</span> binding </span>of</span> add.
</span></code></pre>
Now when we use add</code> we'll get wonky answers as expected.</p>
:> add </span>2 2
</span>5 </span>:: </span>Int
</span>
</span>:> add </span>0 0
</span>1 </span>:: </span>Int
</span></code></pre>
However, look what happens when we use add3</code>:</p>
:> add3 </span>1
</span>4 </span>:: </span>Int
</span></code></pre>
We still get the original correct result.</p>
So, what has happened here?</h3>
The answer is in how mimsa</code> expressions are stored. When we stored add</code>, we
stored not only the expression \a -> \b -> a + b</code> , but the fact that
add</code> has no dependencies. Internally, it would look a bit like this:</p>
-- | Distinct type for our hashes, a wrapper around Text
</span>newtype </span>ExpressionHash
</span>  = </span>ExpressionHash Text
</span>
</span>-- | Simplified version of our StoreExpression type
</span>data </span>StoreExpression </span>= 
</span>  </span>StoreExpression</span> {
</span>    </span>-- | the code for this expression
</span>    </span>expression </span>:: Text</span>,
</span>    </span>-- | a map from the names of dependencies we've used to their hashes
</span>    </span>dependencies </span>:: Map Name ExpressionHash
</span>  }
</span>
</span>-- how our `add` expression is stored internally
</span>addExpression </span>:: StoreExpression
</span>addExpression = 
</span>  </span>StoreExpression
</span>    { expression = "</span>\\</span>a -> </span>\\</span>b -> a + b</span>",
</span>      dependencies = mempty
</span>    }
</span></code></pre>
Once we've made the addExpression</code>, we can create a hash of it, which
we'll pretend looks like "abc123"</code> in hexadecimal. Then when we bind</code> the
name add</code> to it, we can store it in the project:</p>
-- | Simplified version of our Project type
</span>data </span>Project
</span>  = </span>Project 
</span>      { </span>-- | map from names like `add` to hashes
</span>        </span>bindings </span>:: Map Name ExpressionHash</span>,
</span>        </span>-- | map from hashes to expressions
</span>        </span>store </span>:: Map ExpressionHash StoreExpression
</span>      }
</span>
</span>projectWithAdd </span>:: Project
</span>projectWithAdd = </span>Project
</span>  { bindings: fromList [("</span>add</span>", "</span>abc123</span>")],
</span>    store: fromList [("</span>abc123</span>", addExpression)]
</span>  }
</span></code></pre>
Now when we create add3</code>, the following happens:</p>
add3Expression </span>:: StoreExpression
</span>add3Expression =
</span>  </span>StoreExpression
</span>    { expression = "</span>add 3</span>",
</span>      dependencies = fromList [("</span>add</span>", "</span>abc123</span>")]
</span>    }
</span></code></pre>
When evaluating add 3</code>, mimsa</code> has looked in the project for something called
add</code>, found it, and then saved that it is needed in this expression. Because
we refer to add</code> by a hash of it's content, this is what makes it "content
addressed".</p>
Assuming add3</code> has a hash of "def456"</code>, our project would look like this now:</p>
projectWithAddAndAdd3 </span>:: Project
</span>projectWithAddAndAdd3 = </span>Project
</span>  { bindings: fromList [
</span>      ("</span>add</span>", "</span>abc123</span>"), 
</span>      ("</span>add3</span>", "</span>def456</span>")
</span>    ],
</span>    store: fromList [
</span>      ("</span>abc123</span>", addExpression),
</span>      ("</span>def456</span>", add3Expression)
</span>    ] 
</span>  }
</span></code></pre>
Now, when we come to update add</code> and make it evil, we create the following:</p>
evilAddExpression </span>:: StoreExpression
</span>evilAddExpression = 
</span>  </span>StoreExpression
</span>    { expression =  "</span>\\</span>a -> </span>\\</span>b -> a + b + 1</span>",
</span>      dependencies = mempty
</span>    }
</span></code></pre>
Assuming it has a hash of "ghi789"</code>, then the project looks like this:</p>
projectWithAddAndAdd3 </span>:: Project
</span>projectWithAddAndAdd3 = </span>Project
</span>  { bindings: fromList [
</span>      ("</span>add</span>", "</span>ghi789</span>"), 
</span>      ("</span>add3</span>", "</span>def456</span>")
</span>    ],
</span>    store: fromList [
</span>      ("</span>abc123</span>", addExpression),
</span>      ("</span>def456</span>", add3Expression),
</span>      ("</span>ghi789</span>", evilAddExpression)
</span>    ] 
</span>  }
</span></code></pre>
The project has been updated, but note we haven't deleted any items from the
store</code>. All that has been updated in the project is the binding for add</code>.
This means any new uses of add</code> will use the new broken
function, but add3</code> is completely unaffected. If you did want add3</code> to adopt
the new terrible behaviour, it would be a case of binding it again, where it
would use the broken add</code> function from the project.</p>
Why would you do this?</h3>
Maximum cachability</h4>
Because any of the expressions we can created don't change once created, they
don't need reparsing or typechecking (or transpiling to JS, etc) over and over. add</code> will have the type
Int -> Int -> Int</code> forever, meaning that the idea of a slow build is kinda
removed.</p>
No namespacing issues</h4>
In many languages conflicting names of packages or imports can cause issues. We
might want to use function A from package version 1.1 but function B from
package version 1.3. Most package managers won't let you do this (or they let
it sort of happens sometimes, but weird stuff happens with globals interacting, I'm looking at you React). Expressions
in a content-addressed language refer to each other by hashes rather than names,
so function A and function B will have no idea about one another unless they
depend on one another somehow, and everything works great.</p>
Granular code sharing</h4>
Because of the above, the idea of the package as the unit of shared
functionality is somewhat obselete. Unison Share</a>
demonstrates what it could be like if we shared smaller units instead.</p>
Tests don't need running over and over</h4>
If we test that add 1 3 == 4</code>, and I know that add</code> is not going to change,
then I can keep this test result around and don't need to run it again. When
add</code> is rebound, we can make a copy of the test and run it on the new
implementation to see if the same test still passes. Property tests, it turns
out, aren't quite so simple, but I'll come to that in a later post.</p>
Doesn't this mean that most developer tools that are built assuming programming means text files and diffs to said files are all unusable here?</h3>
Ahem.</p>
That's all the words</h3>
That's some context of what content-addressed languages are, at least, my weird
understanding of them anyway. The actual implementation in mimsa</code> is more
complicated than above (for instance, we store the raw AST rather than the
text syntax so we can change the syntax without breaking the expressions, and
store the history of name bindings rather than just the newest one) but
hopefully it gives you a clue about what is going on under the hood.</p>
Make sense? If not, get in touch</a>!</p>
Further reading:</p>
Unison - the big idea</a></p>
mimsa</a></p>


Property testing a content-addressed language
Unknown — Tue, 28 Dec 2021 00:00:00 +0000
So in the last post</a> I quickly introduced the project I've been working on for a
while called mimsa</a>. The reason I did this was so that I could write this post
about recently adding property tests to the language, and what was good/bad
about that, so without further ado here are many words:</p>
Tests in mimsa</h3>
So, for context, unit tests work as follows in mimsa</code>:</p>

We create a (broken) add</code> function:</li>
</ul>
:> :bind add = \a -> \b -> a + b + </span>1
</span>Bound</span> add.
</span></code></pre>

We create a unit tests that confirms that add</code> is indeed broken:</li>
</ul>
:> :addTest "</span>2 + 2 == 4</span>" add </span>2 2 </span>== </span>4
</span>--- FAIL --- 2 + 2 == 4
</span></code></pre>

We update add</code> to a working implementation, and now the test passes:</li>
</ul>
:> :bind add = \a -> \b -> a + b
</span>Updated</span> binding </span>of</span> add.
</span>+++ </span>PASS </span>+++ </span>2 </span>+ </span>2 </span>== </span>4 
</span></code></pre>
What is really neat is that what looks like one test being run twice</strong> is
actually two tests being run once each</strong>.</p>
Why? The reason is immutability - once the first test is
created it can't be changed. It also doesn't need re-running - it always has
the same arguments, and it's only dependency, the original add</code> function,
never changes, so the test stands as a static assertion of the behaviour of
said function.</p>
And where does the second test come from? When we bind a new version of add</code>, it stands to reason we might
want to run the same tests on it, therefore a new copy of any test is created
that uses the new add</code> function as it's dependency.</p>

A really nice property of testing in this way is that we could also make it
run in reverse. If I add another test to the new add</code> function there is no
reason not to auto-create versions of it for the old add</code> bindings too. This
is super helpful when finding a new regression, as we can write a new test for
old code to find out when said regression occurred, a sort of super-powered
git bisect. I say could</em> here because I have not done this yet because I am
lazy.</p>
</blockquote>
Property testing, a recap</h3>
Property testing is a kind of testing where instead of confirming our code
works against known good values we confirms that it obeys certain rules.</p>
A non-property test could be add 2 2 == 4</code> - we know this should be the answer
because we have checked on a calculator that 2 + 2</code> does indeed equal 4</code>.</p>
A property test might be add 0 a == a</code>, given any a</code>. When this is run by
quickcheck</a> or
fast-check</a> the property testing
framework will run the test with loads and loads of different values for a</code>,
and return all the ones that break it (in this case, none of them). If the
tests all pass then we know the property adding zero to a number returns the same
number</strong> holds.</p>
Property testing is very useful for finding edge cases in functions, and used
well, can be a lot more thorough than unit tests, for not a lot more effort.</p>
The current implementation</h3>
For a unit test to be valid in mimsa</code>, it must have the type Boolean</code> (There
is a lot wrong with this, as it doesn't let you see what went wrong, but we
can't just go around making things "good" all the time).</p>
Therefore this are the simplest possible tests:</p>
:> :addTest "</span>true</span>" </span>True
</span>+++ </span>PASS </span>+++ true
</span>
</span>:> :addTest "</span>false</span>" </span>False
</span>--- FAIL --- false
</span></code></pre>
To make a property test, we provide an expression with the type something -> Boolean</code>, like:</p>
:> :addTest "</span>or true is always true</span>" \bool -> or bool </span>True
</span>+++ </span>PASS </span>+++ or true is always true
</span></code></pre>
What's happened here?</p>
The mimsa</code> typechecker has inferred that bool</code> must be a Boolean</code>, generated
a big bucket of booleans, and then checked that each time or bool True == True</code>. This returns True</code> everytime so the test passes.</p>

The or</code> function has type Boolean -> Boolean -> Boolean</code> and looks something like \a -> \b -> if a then True else b</code>. It is
similar to the ||</code> operator in most programming languages.</p>
</blockquote>
Let's try another:</p>
:> :addTest "</span>and true is always true</span>" \bool -> and bool </span>True
</span>--- FAIL --- and true is always true
</span>Failing</span> inputs:
</span> - </span>False
</span></code></pre>
This property test has failed, and it's telling us that when you pass False</code>
to the test function, it does not return True</code>. The and</code> function here is
equivalent to &&</code>, so this makes sense, as False && True</code> equals False</code>.</p>
As the input is a Boolean</code> there are only two inputs, and the mimsa</code> property
test generates 1000</code> sample inputs, it's fairly likely we'll get both a False</code>
and a True</code> input.</p>
Breaking it</h3>
However, it's not too difficult to make a less definitive test:</p>
:> :bind flakyTest = 
</span>  \val -> match val with 
</span>    (</span>Just</span> (</span>Just</span> (</span>Just</span> (</span>Just True</span>)))) -> </span>False 
</span>  | _ -> </span>True
</span>Bound</span> flakyTest.
</span>
</span>:> :addTest "</span>Flaky</span>" flakyTest
</span>+++ </span>PASS </span>+++ </span>Flaky
</span>
</span>:> :addTest "</span>Flaky 2</span>" flakyTest
</span>--- FAIL --- Flaky 2
</span>Failing</span> inputs:
</span> - </span>Just</span> (</span>Just</span> (</span>Just</span> (</span>Just True</span>)))
</span></code></pre>
Because the input type here would be Maybe (Maybe (Maybe (Maybe Boolean)))</code> there are a lot of potential inputs,
and it's quite possible that Just (Just (Just (Just True)))</code> is not amongst
the generated values.</p>
Another type of flaky test can be generated like this:</p>
:> :addTest "</span>flaky string</span>" \str -> not (str == "</span>dog</span>")
</span>+++ </span>PASS </span>+++ flaky string
</span></code></pre>
It passes every time I have tried it, although as a statement it makes no
sense - there is no string that equals "dog"</em>. This kind of test is hard just
because there are so many potential strings out there that a total search of
the space is close to impossible.</p>
The problems / solutions</h3>
Simple tests could be non-deterministic and aren't:</h4>
\bool -> and bool </span>True
</span></code></pre>
This could be two unit tests that are run once and never again, however as a
property test it must be run over and over. This is the least of the problems
but worth mentioning.</p>
Complex finite tests become flaky</h4>
\val -> match val with
</span>    (</span>Just</span> (</span>Just</span> (</span>Just</span> (</span>Just True</span>)))) -> </span>False
</span>  | _ -> </span>True
</span></code></pre>
Given that a Maybe</code> is either Nothing</code> or the value inside, and Boolean</code> can
be 1 of 2 values, there are 1 + 1 + 1 + 1 + 2 == 6</code> potential inputs here.
It doesn't seem out of the question to auto-generate all the possible values
here and run tests against them all. This would ensure a) the same results each
time and b) that we could cache the results once and never run them again.</p>
However, if the input type contains an Int</code>, String</code>, Array</code> or any recursive
type then generating a complete set of inputs is no longer practical.</p>

A recursive type is one that contains itself. For instance, a linked list is
defined in mimsa</code> as type List a = Nil | Cons a (List a)</code>. The second List a</code> argument to Cons</code> means "and another list" so this datatype can grow and
grow and grow.</p>
</blockquote>
String and number spaces just too huge</h4>
\str -> not (str == "</span>dog</span>")
</span></code></pre>
Due to the way the mimsa</code> web client works, we can't really fall back to brute
forcing an absolute shit ton of inputs for String</code> and Int</code> inputs. However,
we have access to the AST when running the test. Would it be so terrible to add all of the string and number literals found in the
expression into the test values? For instance, if we used the input "dog"</code>
above we'd find the breaking case immediately.</p>
No more words</h3>
That is the end of the words. It's a bit of a braindump, and pretty much only
for my own benefit, but I hope it is perhaps vaguely interesting. Who knows?</p>
Make sense? If not, get in touch</a>!</p>
Further reading:</p>
quickcheck</a></p>
fast-check</a></p>
mimsa</a></p>


Newtypes for Cheap
Unknown — Sat, 28 Mar 2020 00:00:00 +0000
So previously we've spoken about the idea of a newtype</code> in Haskell. A
newtype</code> is a wrapper you can put around a value to distinguish it from other
items. It's common to give value that has it's own domain meaning it's own
newtype</code>, for instance:</p>
newtype </span>Firstname </span>= </span>Firstname</span> { getFirstname :: </span>String</span> }
</span>  </span>deriving</span> (</span>Eq</span>, </span>Ord</span>, </span>Show</span>)
</span>
</span>newtype </span>Surname </span>= </span>Surname</span> { getSurname :: </span>String</span> }
</span>  </span>deriving</span> (</span>Eq</span>, </span>Ord</span>, </span>Show</span>)
</span></code></pre>
We create values as such:</p>
first </span>:: Firstname
</span>first = </span>Firstname </span>"</span>Bobby</span>"
</span>
</span>last </span>:: Surname
</span>last = </span>Surname </span>"</span>Davehead</span>"
</span></code></pre>
And unwrap them to use like this:</p>
fullName </span>:: Firstname -> Surname -> String
</span>fullName first' last' = getFirstname first' <> " " <> getSurname last'
</span>-- fullName first last == "Bobby Davehead"
</span></code></pre>
This would stop different bits of names, that would usually be stored as
strings, getting mixed up. It's neat. What's really nice about it though, as although
these look like records with a single item inside, and in code we treat them as
such, as runtime that shit gets erased and really it's just a String</code> being
passed around for #performance</code>.</p>
They have two benefits:</p>


Firstly, if you are a goof like me, you get this wrong all the time and put
arguments in the wrong order and generally make a mess of things from
10x-ing all the time, and this makes such terrible errors a little trickier to
make.</p>
</li>

Secondly, and much more usefully, it allows us to practice Alexis King's
Parse, don't
validate</a>
pattern. It's well worth reading in full, but the very tl;dr is - if I check a
String</code> to see if it's a valid name, I should return a type that tells me
that fact, so I a) don't have to check again and b) don't mix it up with the
unchecked version.</p>
</li>
</ul>
Anyway. It all sounds like good stuff, and I have been thinking about the same
patterns in Typescript as that's a place I often find myself these days.</p>
Prior art</h3>
Now a good place to start when trying to reproduce any Haskell / Purescript
concept in Typescript is to crack open gcanti's
Github</a> where, as usual, he does not disappoint:
newtype-ts</a> is a pretty full featured
library for this built on top of his monocle-ts</code> lens library.</p>
Now this is all very well, but does sort of require everybody working on your
codebase to buy in (especially as it requires you to use modify</code> from
monocle-ts</code> to change the values inside, and to explicitly wrap</code> and unwrap</code>
them). If everybody is into this, go for it, I am a big fan of the fp-ts</code>
stack and swear by io-ts</code> at the moment. However, I often need something cheap and hacky, that doesn't leak complexity throughout the codebase.</p>
Fortunately, good man and Habito colleague Mateusz (who I cannot find any links to on
the internet, somebody please help me remedy this), came up with a neat way of
tagging types for cheap, which I'd like to share today.</p>
The 10x solution</h3>
Here is the whole library:</p>
type </span>Nominal<T> = {
</span>    </span>readonly </span>symbol</span>: T
</span>}
</span>
</span>export type </span>Tagged<Tag </span>extends </span>string, A> = A & Nominal<Tag>
</span></code></pre>
This means we can make unique tagged versions of regular datatypes like so:</p>
type </span>Firstname = Tagged<"</span>Firstname</span>", string>
</span>
</span>type </span>Surname = Tagged<"</span>Surname</span>", string>
</span>
</span>type </span>Age = Tagged<"</span>Age</span>", number>
</span></code></pre>
The great thing is that when the Javascript is generated from this, we just
end up with plain string</code> and number</code> values.</p>
Now, let's see what these buy us:</p>
Stopping idiots like me mixing stuff up</h3>
The most basic use is just tagging our types with as</code>:</p>
const </span>first </span>= "</span>Bobby</span>" </span>as </span>Firstname
</span>
</span>const </span>surname </span>= "</span>Davehead</span>" </span>as </span>Surname
</span>
</span>const </span>functionThatNeedsSpecificallyFirstname </span>= (</span>firstname</span>: Firstname): string </span>=>
</span>    `</span>Hello, person whose first name is very much ${</span>firstname</span>}</span>`
</span></code></pre>
Now, we can make sure only the right tagged value:</p>
functionThatNeedsSpecificallyFirstname</span>(</span>first</span>) </span>// ok!
</span>
</span>functionThatNeedsSpecificallyFirstname</span>(</span>surname</span>) </span>// type error!
</span></code></pre>
When you have a function like apiCall(url: string, token: string, accountId: string) => ...</code> this really helps to stop you messing stupid things up.</p>
Now, how about that parsing stuff mentioned earlier?</p>
Parse, don't validate</h3>
So, we can also use this tactic to tag data that we have validated, so that we
know certain properties about it have been validated.</p>
Say we have a Person</code> type, because I lack imagination:</p>
interface </span>Person {
</span>  </span>firstname</span>: string
</span>  </span>surname</span>: string
</span>  </span>age</span>: number
</span>}
</span></code></pre>
Now, we want to check a few properties about these things to make sure they're
not terrible.</p>
The naive version of this looks something like:</p>
const </span>isValidPerson </span>= (</span>person</span>: Person): boolean </span>=> 
</span>  (</span>person</span>.</span>firstname</span>.length > </span>0 </span>&& </span>person</span>.</span>firstname</span>.length < </span>100</span>)
</span>  && (</span>person</span>.</span>surname</span>.length > </span>0 </span>&& </span>person</span>.</span>surname</span>.length < </span>50</span>)
</span>  && (</span>person</span>.</span>age </span>>= </span>0 </span>&& </span>person</span>.</span>age </span>< </span>120</span>)
</span></code></pre>
Before using Person</code> anywhere, you could check it made sense:</p>
if </span>(</span>isValidPerson</span>(</span>person</span>)) {
</span>  </span>doThingWithPerson</span>(</span>person</span>)
</span>} </span>else </span>{
</span>  </span>throw </span>"</span>Person is not valid</span>"
</span>}
</span></code></pre>
...and throw an error if it isn't. The thing is, it's nicer to do validation on the boundaries of
our app and then know afterwards that things are OK. What if we could use our Tagged</code> type
to help us?</p>
Let's rewrite our validation functions:</p>
const </span>validateFirstname </span>= (</span>rawString</span>: string): Firstname | null </span>=> 
</span>    (</span>rawString</span>.length > </span>0 </span>&& </span>rawString</span>.length < </span>100</span>) 
</span>       ? </span>rawString </span>as </span>Firstname : </span>null
</span>
</span>const </span>validateSurname </span>= (</span>rawString</span>: string): Surname | null </span>=> 
</span>    (</span>rawString</span>.length > </span>0 </span>&& </span>rawString</span>.length < </span>50</span>) 
</span>       ? </span>rawString </span>as </span>Surname : </span>null
</span>
</span>const </span>validateAge </span>= (</span>rawAge</span>: number): Age | null </span>=> 
</span>    (</span>rawAge </span>>=</span>0 </span>&& </span>rawAge </span>< </span>120</span>) ? </span>rawAge </span>as </span>Age : </span>null
</span>
</span>interface </span>ValidPerson {
</span>    </span>firstname</span>: Firstname
</span>    </span>surname</span>: Surname
</span>    </span>age</span>: Age
</span>}
</span>
</span>const </span>validatePerson </span>= (</span>person</span>: Person): ValidPerson | null </span>=> </span>{
</span>    </span>const </span>firstname </span>= </span>validateFirstname</span>(</span>person</span>.</span>firstname</span>)
</span>    </span>const </span>surname </span>= </span>validateSurname</span>(</span>person</span>.</span>surname</span>)
</span>    </span>const </span>age </span>= </span>validateAge</span>(</span>person</span>.</span>age</span>)
</span>
</span>    </span>return </span>(</span>firstname </span>&& </span>surname </span>&& </span>age</span>) ?  {
</span>        </span>firstname</span>, </span>surname</span>, </span>age
</span>    } : </span>null
</span>}
</span></code></pre>
It looks a bit more verbose, but that's mostly because I've broken each
validation function out. What it means is that we can take our raw Person</code>
data, run the validator and get a ValidPerson</code> (because it's valid) or null</code>
(it wasn't valid).</p>
const </span>badPerson </span>= </span>validatePerson</span>({ firstname: "", surname: "", age: -</span>1 </span>})
</span>// null
</span>
</span>const </span>goodPerson </span>= </span>validatePerson</span>({ firstname: "</span>Tom</span>", surname: "</span>Hanks</span>", age: </span>50 </span>})
</span>// { firstname: "Tom", surname: "Hanks", age: 50 }
</span></code></pre>
We can then pass ValidPerson</code> around the rest of the codebase, knowing that
the values are Good and Valid and not needing to check them again.</p>
Disclaimer</h3>
Now, the disadvantage with such a technique is that there's nothing stopping me
just using as</code> to change, say a Firstname</code> into a Surname</code> and cheating the
whole thing.</p>

</span>const </span>giveMeFirstName </span>= (</span>thanks</span>: Firstname): Firstname </span>=> </span>thanks
</span>
</span>const </span>surname</span>: "</span>whoa</span>" as Surname
</span>
</span>giveMeFirstName</span>(</span>surname </span>as </span>Firstname) </span>// cheating!
</span></code></pre>
However, if that's really a problem in your codebase (and I would
delicately suggest that what you have there is more a social and not a coding
problem) - then perhaps it's time to go all in on newtype-ts</code> or similar.</p>
Make sense? No? Don't care? Let me know!</a></p>


Contract testing with Typescript
Unknown — Sun, 23 Feb 2020 00:00:00 +0000
Hello. In our last article</a> we described how to generate test cases for contract
testing in Haskell. This time, we are going to look at generating the front end
portion of these in Typescript</code>. This will probably be a lot briefer because I
am a very lazy person at heart.</p>
First, some rambling</h3>
The main differences with the type system of Haskell</code> or Purescript</code> compared
to that of Typescript</code> is that typeclasses allow the types of things to affect
the code that is generated or used. That's how a newtype</code> like Sum</code> or
Product</code> can change the Monoid</code> function used to combine two values, even
though both are just Int</code> values underneath.</p>
The same thing applied to our arbitrary</code> instances - we set a type, derived
the necessary instances, and then all the code was generated for us.</p>
Typescript</code> is different. Because all the type info is destroyed at runtime,
we have to create run-time (or value level</code>) descriptions of our types, and
then derive the types</code> from those. Make sense? No? Doesn't really matter
anyway.</p>
</p>
Some datatypes</h3>
Fortunately, generating run-time validators and types for them is exactly what
the excellent io-ts</a> is for. It allows to
create validators for our datatypes using runtime functions, but then also
derive types from that. Let's see an example:</p>
import </span>* </span>as </span>t </span>from </span>'</span>io-ts</span>'
</span>
</span>export const </span>PetShape </span>= </span>t</span>.</span>type</span>({
</span>  petName: </span>t</span>.</span>string
</span>})
</span>
</span>export const </span>UserShape </span>= </span>t</span>.</span>type</span>({
</span>  userId: </span>t</span>.</span>number</span>,
</span>  name: </span>t</span>.</span>string</span>,
</span>  pets: </span>t</span>.</span>array</span>(</span>PetShape</span>)
</span>})
</span>
</span>type </span>Pet = t.TypeOf<typeof PetShape>
</span>
</span>export type </span>User = t.TypeOf<typeof UserShape>
</span></code></pre>
Here we have defined Pet</code> and User</code> and created validators for them both.
What does this mean?</p>
const </span>userJson </span>= { userId: </span>1</span>, name: "</span>Frank</span>", pets: [] }
</span>
</span>const </span>ok </span>= </span>UserShape</span>.</span>decode</span>(</span>userJson</span>))
</span>// ok == Right with a User type inside
</span>
</span>const </span>badUserJson </span>= { blah: "</span>dfgdfgdgf</span>" }
</span>
</span>const </span>no </span>= </span>UserShape</span>.</span>decode</span>(</span>badUserJson</span>)
</span>// no == Left with an error message
</span></code></pre>
This means that we can validate JSON we receive into our application and ensure
that when Typescript says we are talking about a User</code>, we really are.</p>
</p>
Reading sample JSON</h3>
Therefore, hopefully you can work out how we're going to check our generated
backend responses from earlier.</p>
import </span>{ </span>either </span>} </span>from </span>'</span>fp-ts</span>'
</span>import </span>* </span>as </span>path </span>from </span>'</span>path</span>'
</span>import </span>* </span>as </span>fs </span>from </span>'</span>fs</span>'
</span>
</span>// get array of nums 0...99
</span>const </span>rangeArr </span>= [...</span>Array</span>(</span>100</span>).</span>keys</span>()];
</span>
</span>// path to wherever our responses are saved
</span>const </span>outputPath </span>= '</span>./responses/user/</span>'
</span>
</span>describe</span>('</span>Read contract tests</span>', () </span>=> </span>{
</span>  </span>test</span>('</span>Write sample responses from files</span>', () </span>=> </span>{
</span>    </span>rangeArr</span>.</span>forEach</span>(</span>index </span>=> </span>{
</span>      </span>// construct the path
</span>      </span>const </span>filename </span>= </span>path</span>.</span>resolve</span>(`</span>${</span>outputPath</span>}${</span>index</span>}.json</span>`)
</span>      </span>// read the file and turn it into a JS object
</span>      </span>const </span>file </span>= JSON.</span>parse</span>(</span>fs</span>.</span>readFileSync</span>(</span>filename</span>, "</span>utf8</span>"))
</span>      </span>// assert whether it validates properly
</span>      </span>expect</span>(</span>either</span>.</span>isRight</span>(</span>UserShape</span>.</span>decode</span>(</span>file</span>))).</span>toBeTruthy</span>()
</span>    })
</span>  })
</span>})
</span></code></pre>
This Jest</code> test loads each .json</code> file from a given folder and checks that it
decodes correctly with our UserShape</code> validator. If they do, then we know, at
least for this particular endpoint, that our frontend and backend agree with
one another.</p>
</p>
Generating sample JSON</h3>
What has traditionally been a bit harder in Typescript</code> in generating
arbitrary</code> responses. Since we can't use out types to inform which values are
made, we have to be a bit creative.</p>
But that's hard work. What if somebody else had already solved this and we
could just piggyback off their great work?</p>
Enter fast-check</a> and
io-ts-fast-check</a>.</p>
fast-check</code> is a property testing tool for Typescript</code>. Essentially, for our
purposes, it's QuickCheck</code>. io-ts-fast-check</code> is the secret sauce that says
"if you can give me a validator, I can generate you random values that satisfy
it."</p>
Therefore, we can use it to create our random front end requests, ready for our
backend to decode and validate. Great!</p>
import </span>* </span>as </span>fc </span>from </span>'</span>fast-check</span>'
</span>import </span>* </span>as </span>fs </span>from </span>'</span>fs</span>'
</span>import </span>* </span>as </span>path </span>from </span>'</span>path</span>'
</span>import </span>{ </span>getArbitrary </span>} </span>from </span>'</span>fast-check-io-ts</span>';
</span>import </span>{ </span>either </span>} </span>from </span>'</span>fp-ts</span>'
</span>
</span>// this creates a fast-check `Arbitrary` from our `User` validator
</span>const </span>userArbitrary </span>= </span>getArbitrary</span>(</span>UserShape</span>)
</span>
</span>// this takes an output folder and an Arbitrary, and fills the folder with 100
</span>// json example files 
</span>export const </span>generate </span>= <A>(</span>outputPath</span>: string, </span>arb</span>: fc.Arbitrary<A>) </span>=> </span>{
</span>  </span>fc</span>.</span>sample</span>(</span>arb</span>, </span>100</span>).</span>map</span>(</span>a </span>=> </span>JSON.</span>stringify</span>(</span>a</span>)).</span>map</span>((</span>json</span>, </span>index</span>) </span>=> </span>{
</span>    </span>// construct file path for saving the file
</span>    </span>const </span>filename </span>= </span>path</span>.</span>resolve</span>(`</span>${</span>outputPath</span>}${</span>index</span>}.json</span>`)
</span>    </span>// save that goddamn file
</span>    </span>fs</span>.</span>writeFileSync</span>(</span>filename</span>, </span>json</span>)
</span>  })
</span>}
</span>
</span>// example of use
</span>generate</span>('</span>./requests/users</span>', </span>userArbitrary</span>)
</span></code></pre>
</p>
Great stuff!</h3>
Now we can read our sample requests into the backend and see that everything is
fine. Running tests like this before each deploy of either front or back end
service is a great way to make sure nothing will explode. Source code is
available here</a> if you
can't get it to do what you want for some reason.</p>
Make sense? No? Yes? Let me know!</a></p>


Contract testing with Quickcheck
Unknown — Sat, 22 Feb 2020 00:00:00 +0000
Hello. I hope you are well. Over the last few months I have been trying out a
method for generating Contract Tests</code> between services using Arbitrary</code>
instances from Quickcheck</a> which I thought it might be good to share. It's not particularly clever, which is
partially what I like about it, and as a result I may not have been the first
to come up with it. If I have therefore somewhat stolen your thunder please
accept my apologies in advance and then maybe do some reading around SEO.</p>
What is Contract Testing anyway?</h3>
Contract Testing is a way of checking that two services that are going to
communicate agree on what is going to be sent and received between the two.
There is a good intro to the concept on the Pact
website</a> - which is itself a contract testing tool. It
is a good tool - HOWEVER it takes a lot of work and I am lazy so there what I
am going to describe is hopefully less work.</p>
For example, a frontend says "I am going to call /users/horse/1000</code> - is that cool?"
and the contract test confirms that the backend is indeed "cool" with that,
shows what kind of thing it would return from that call, to which the frontend
confirms it is also "cool" with that.</p>
</p>
What is Quickcheck?</h3>
Quickcheck is a Haskell library that does a thing called Property Testing. It has since been ported to many other languages. A nice intro lives here
at School of
Haskell</a> - the tldr is that it lets us test properties about our programs by randomly generating examples and seeing if they fit rules that we define.</p>
So, what is your so-called idea then?</h3>
OK. So one of the main concepts behind QuickCheck is the Arbitrary</code> typeclass.
Any datatype with an instance of this typeclass is able to generate random
example values that can be used for testing.</p>
module </span>ContractTests </span>where
</span>
</span>import </span>Data.Aeson
</span>import </span>GHC.Generics
</span>import </span>Test.QuickCheck.Arbitrary
</span>
</span>data </span>Horse
</span>  = </span>BigHorse
</span>  | </span>SmallHorse
</span>  </span>deriving</span> (</span>Generic</span>, </span>FromJSON</span>)
</span>
</span>instance Arbitrary Horse where
</span>  arbitrary =
</span>    oneof
</span>      [ pure </span>BigHorse</span>,
</span>        pure </span>SmallHorse
</span>      ]
</span></code></pre>
This datatype Horse</code> describes the two kinds of horse, BigHorse</code> and SmallHorse</code>. As is hopefully hand-wavingly evident, when the arbitrary</code> function is run it returns one of BigHorse</code> or SmallHorse</code>.</p>
</p>
If we can make one Horse</code>, then surely we can make a load of them? Indeed!
This is what the instance for List</code> look like - the Arbitrary a =></code>
constraint means that if we can make any Arbitrary</code> value, we can make a list
of them.</p>
instance Arbitrary </span>a </span>=> Arbitrary</span> [</span>a</span>] </span>where
</span>  ...
</span></code></pre>
The Quickcheck library defines instances for most basic types, as well as most
collections, therefore it is quite simple to build Arbitrary</code> instances for
our request and response datatypes - and that is exactly what we're going to
do.</p>
An example</h3>
Let's think about a nice simple API. It receives POST</code> requests in JSON</code> format that translate into a datatype that looks like this:</p>
data </span>APIRequest
</span>  = </span>APIRequest
</span>      { name      :: </span>String
</span>      , age       :: </span>Int
</span>      , horseSize :: </span>Horse
</span>      }
</span></code></pre>
Assuming that the requests are OK, it returns a response shaped like this
(again, sent over the wire in JSON</code> format).</p>
data </span>APIResponse
</span>  = </span>APIResponse
</span>      { weight :: </span>Int
</span>      , goodHorse :: </span>Bool
</span>      }
</span></code></pre>
These types are shown in Haskell</code>, but the equivalent pair will also exist in
the frontend, and it's the compatibility between the two pairs that we will be checking.</p>
Our testing is going to work like this:</p>

Our frontend will generate 100 example APIRequest</code> values</li>
Each one will be turned into JSON</li>
Each piece of JSON is saved into a file</li>
Our backend will decode each piece of JSON and see if it makes sense</li>
If it does - great!</li>
</ol>
Then, for responses, we do the same thing in reverse:</p>

Our backend will generate 100 example APIResponse</code> values</li>
Each one will be turned into JSON</li>
Each piece of JSON is saved into a file</li>
Our frontend will decode each piece of JSON and see if it makes sense</li>
If it does - great!</li>
</ol>
Essentially, a contract between two services is a complete set of these for each endpoint. In this article I will explain the Haskell</code> part of this, and will follow with the front end portion in the next one.</p>
</p>
Creating the sample responses</h3>
We're going to need to add some typeclass instances for our APIResponse</code> type first, so let's change it to the following:</p>
import </span>Test.QuickCheck.Arbitrary.Generic
</span>
</span>data </span>APIResponse
</span>  = </span>APIResponse
</span>      { weight :: </span>Int</span>,
</span>        </span>goodHorse </span>:: Bool
</span>      }
</span>  </span>deriving</span> (</span>Generic</span>, </span>ToJSON</span>)
</span>
</span>instance Arbitrary APIResponse where
</span>  arbitrary = genericArbitrary
</span></code></pre>
genericArbitrary</code> is provided by the generic-arbitrary</code> package which allows Arbitrary</code> instances to be created for any datatype with a Generic</code> instance. (For more intro on the idea of generics, the Hackage</a> page is a good start.)</p>
ToJSON</code> is provided by Aeson</code>, the excellent package for all dealings with JSON, and deserves a whole post of it's own. For our purposes, all we need to know is that for any datatype with a Generic</code> instance, we can derive a free typeclass for turning it to and from JSON.</p>
The special sauce for all of this action is the generate</code> function from
Test.QuickCheck.Gen</code>, which generates any number of values for a given
Arbitrary</code> instance. We use this with a bunch of other housekeeping functions to take these 100
items and turn them into 100 files. I have broken this down into a bunch of
functions so that it's hopefully easier to follow.</p>
Firstly, a couple of helpers for adding index numbers to lists...</p>
indexList </span>::</span> [</span>a</span>] </span>-></span> [(</span>Int</span>, </span>a</span>)]
</span>indexList as =
</span>  </span>List</span>.zip [</span>1 </span>..] as
</span>
</span>-- indexList ['A', 'B'] == [(1, 'A'), (2, 'B')]
</span></code></pre>
...and creating a file path using said index...</p>
createPath </span>:: String -> Int -> String
</span>createPath path index =
</span>  "</span>./</span>" <> path <> "</span>/</span>" <> (show index) <> "</span>.json</span>"
</span>
</span>-- createPath "output" 1 == "./output/1.json"
</span></code></pre>
Next, we will make our functions for generating instances and saving them to
files. This first function uses a Proxy</code> (from
Data.Proxy</a>)
to pass the type we would like to generate (as such). We have chosen 100</code> as
it is as good a number as any.</p>
getResponses </span>::</span> (</span>Arbitrary </span>a</span>) </span>=> Proxy </span>a </span>-> IO</span> [</span>a</span>]
</span>getResponses _ = generate $ vector </span>100
</span></code></pre>
This next function takes our list of randomised values, turns them to JSON, and pops them in a Tuple</code> along with an index.</p>
listToJSON </span>::</span> (</span>ToJSON </span>a</span>) </span>=></span> [</span>a</span>] </span>-></span> [(</span>Int</span>, </span>BS</span>.</span>ByteString</span>)]
</span>listToJSON = (indexList . jsonifyList)
</span>  </span>where
</span>    jsonifyList = fmap encode
</span></code></pre>
Finally, we put them together along with some glue code (using writeFile</code> from
Data.ByteString.Lazy</code>) to save the generated JSON</code> files.</p>
contractWrite </span>::
</span>  (</span>ToJSON </span>a</span>, </span>Arbitrary </span>a</span>) </span>=>
</span>  </span>Proxy </span>a </span>->
</span>  </span>String ->
</span>  </span>IO </span>()
</span>contractWrite arbType srcPath = </span>do
</span>  </span>let</span> saveFile = \path (index, json) ->
</span>        </span>BS</span>.writeFile (createPath path index) json
</span>  responses <- listToJSON <$> (getResponses arbType)
</span>  mapM_ (saveFile srcPath) responses
</span></code></pre>
To use it with our datatype, we use a Proxy</code> as such to pass it the type we
want (in our case, APIResponse</code>, but the same code will work for any type with
Arbitrary</code> and ToJSON</code> instances)</p>
contractWriteAPIResponses </span>:: String -> IO </span>()
</span>contractWriteAPIResponses srcPath =
</span>  contractWrite (</span>Proxy </span>:: </span>Proxy APIResponse</span>) srcPath
</span></code></pre>
If we crack this open in ghci</code> we can run contractWriteAPIResponses "sample"</code>, and it will create files called 1.json</code>, 2.json</code> (up to 100.json</code>) in the sample</code> folder in the current working directory.</p>
Our frontend tests can now read these and make sure that they understand them.
But how do we make sure our backend understands the front end requests?</p>
</p>
Reading the sample requests</h3>
Assuming that our front end has also created some sample requests in a similar fashion, reading them and checking they are decodable is a simpler affair.</p>
Given a path that points to a folder full of 100 json files, we can write code to attempt to read them. We are reusing the createPath</code> function from above, but other than, this should do it.</p>
This function takes a Proxy</code> for our decoding type, a path and an index, and
tries to decode the file it finds.</p>
testFile </span>:: FromJSON </span>a </span>=> Proxy </span>a </span>-> String -> Int -> IO</span> (</span>Maybe </span>a</span>)
</span>testFile _ path i = </span>do
</span>  str <- </span>BS</span>.readFile (createPath path i)
</span>  </span>case</span> eitherDecode str </span>of
</span>    </span>Left</span> e -> putStrLn (show e) >>= \_ -> pure </span>Nothing
</span>    </span>Right</span> b -> pure (</span>Just</span> b)
</span></code></pre>
Here we take a path to the folder full of files and attempt to read 100</code>
numbered .json</code> files in it.</p>
contractRead </span>:: FromJSON </span>a </span>=> Proxy </span>a </span>-> String -> IO Int
</span>contractRead arbType srcPath = </span>do
</span>  maybeFound <- mapM (testFile arbType srcPath) [</span>1 </span>.. </span>100</span>]
</span>  pure $ length $ catMaybes maybeFound
</span></code></pre>
And here we put it all together using our APIRequest</code> type.</p>
contractReadAPIRequest </span>:: String -> IO Int
</span>contractReadAPIRequest srcPath =
</span>  contractRead (</span>Proxy </span>:: </span>Proxy APIRequest</span>) srcPath
</span></code></pre>
Cracking open ghci</code> and running contractRead "sample"</code> will attempt to read 100 numbered .json</code> files in the sample</code> folder.</p>
Digression 1.</h3>
Note we have used a Proxy</code> type here to pass the type around. An alternative way to do this could be a mixture of TypeApplications</code> and ScopedTypeVariables</code> but in the spirit of #simplehaskell</code> we'll avoid them.</p>
Digression 2.</h3>
Whilst preaching simplicity, it seems enjoyably hypocritical to point out in
the same breath that we needn't have made a standalone instance of arbitrary</code>
each time, and it's actually a great opportunity to crack open DerivingVia</code>.</p>
An alternative method could looks something like this, and save up to 15
characters per datatype.</p>
-- this newtype can derive Arbitrary via Generic, so we use Deriving Via to
</span>-- steal it's powers!
</span>newtype </span>GenericArb</span> a
</span>  = </span>GenericArb</span> {getGenericArb :: a}
</span>  </span>deriving</span> (</span>Generic</span>)
</span>
</span>instance</span> (</span>Generic </span>a</span>, </span>Arbitrary </span>a</span>) </span>=> Arbitrary</span> (</span>GenericArb </span>a</span>) </span>where
</span>  arbitrary = genericArbitrary
</span>
</span>data </span>APIRequest2
</span>  = </span>APIRequest2
</span>      { name2 :: </span>String</span>,
</span>        </span>age2 </span>:: Int</span>,
</span>        </span>horseSize2 </span>:: Horse
</span>      }
</span>  </span>deriving</span> (</span>Generic</span>, </span>FromJSON</span>)
</span>  </span>deriving</span> (</span>Arbitrary</span>) via (</span>GenericArb APIRequest2</span>)
</span>
</span>data </span>APIResponse2
</span>  = </span>APIResponse2
</span>      { weight2 :: </span>Int</span>,
</span>        </span>goodHorse2 </span>:: Bool
</span>      }
</span>  </span>deriving</span> (</span>Generic</span>, </span>ToJSON</span>)
</span>  </span>deriving</span> (</span>Arbitrary</span>) via (</span>GenericArb APIResponse2</span>)
</span></code></pre>
Make sense?</h3>
No. Thought not. Regardless, I'll follow up with how to great the front end
part. I'll be using Typescript</code> because quite frankly if you understand this
then doing it in Purescript</code> isn't wildly different.</p>


The Genius Of Concrete
Unknown — Wed, 09 Oct 2019 00:00:00 +0000
Note: I have taken a break from whatever it is that I usually crap on about to
do some opinions</em>. Beware.</p>
Whimsical Story</h3>
When I was much younger I was what you might call "quite a trying child". Apparently, a thing I liked was to ask lots of questions.</p>
One that I remember very clearly was this:</p>
"Where do washing machines come from?"</strong></p>
(A reasonable, if somewhat tangental question I suppose. I can't remember why I
was interested.)</p>
"A washing machine"</strong>, they told me, "is made in a washing-machine-making-machine."</strong></p>
Very well, I thought. But that wasn't enough.</p>
"So where do the washing-machine-making-machines come from?"</strong></p>
(That'll fox them.)</p>
"Ahh, well you see"</strong>, the reply went "those washing-machine-making-machines are
made by washing-machine-making-machine-making-machines"</strong></p>
This went on as you might predict. I won't bore you with what was obviously some sort of early lesson in the dangers of
unsupervised recursion, but as you can imagine, it was machine-making-machines
all the way down in my dreams for months after that.</p>
</p>
Anyway. There was a point to this. Or at least I thought there was when I
couldn't get to sleep and decided I needed to get up and write all this down.</p>
Abstractions</h3>
So when using the computers and things, we generally start with very concrete
problems, such as "how we make a washing machine"</strong>, and then later, "also, how can we put another light on this machine machine that
blinks when the washing is ready?"</strong>.</p>
Now, being close to the metal, as such, the manual manufacturer of said washing machine
is not going to have too much trouble (crudely, perhaps) adding such a light and making it work. After all,
they are equipped with washing machine making tools (hammer? wrench?
screwdriver? bear with me here) for the job.</p>
But is the true work of an engineer?</h3>
The trouble is, nobody makes washing machines by hand anymore, at least not for
long. Once the maker has gotten the hang of things they think "this work is
very manual and perhaps somewhat beneath me now, surely we can make this easier?"</strong></p>
Soon enough, their days with the hammer, the wrench and the
screwdriver are wasted, as they have constructed the washing-machine-maker</strong>.</p>
</p>
We are all very pleased about this development.</h3>
It really is good stuff. We're making washing machines at a much quicker pace
now, and soon somebody hires in some consultants who point out that we could be
Scaling A Lot Better if we abstract further. Soon enough, they're right - and
through a mixture of capitalism and boredom the  washing-machine-making-machine-maker</strong> is born.</p>
</p>
Nice.</h3>
One thing we notice in making the even bigger machine is that many of the parts
in the big machine aren't as specialised as we thought, and we replace them
with a combination of more general parts that are tried and tested. This is
generally agreed to be good engineering practice, plus additionally the tried and tested stuff breaks less and is cheaper, so
everybody involved is having a positive time.</p>
It's not long until somebody points out that with a little tweaking, we can expand and have a higher level machine called the washing-machine-and-also-fridge-making-machine-maker-machine-maker</strong> that is also capable of making something that may at one point end up making a fridge as well. Business is booming.</p>
</p>
Oh shit.</h3>
But wait. A new requirement has been found.</p>
The washing machine needs Another Light on it. This one is a new colour, not
found in washing machines or fridges. The customer bought one of our first
fridges and was impressed with how quickly they had worked for him. However now
changing the washing machine isn't a job for a hammer, a wrench or a
screwdriver anymore, it's going to require changes to the
washing-machine-and-also-fridge-making-machine-maker-machine-maker</strong> to
change the washing-machine-making-machine-maker</strong> to construct a  washing-machine-maker</strong> that will output the required washing-machine</strong>.</p>
It'd probably be quicker to knock it all down and start over, but now we've got
a shitload of fridges to worry about too.</p>
</p>
Get to the point, you goddamn meandering jerk.</h3>
My point here is that the recursive levels of washing machine creating
abstractions here are taking us further and further from our real aim here,
which in this already stretched allegory seems to be "maintain an ability to
add lights to washing machines in a timely manner as and when users of said
machine take an interest in such."</strong></p>
These building blocks, they're all very well, but why did we really start this?
Was it because we needed to? Or because we were bored of building fridges?</p>
Let's talk about concrete.</h3>
So. Concrete is shit.</p>
(That is to say - it has very little value. I don't know what it's made of, and looking it up now on
Wikipedia would seem somewhat insincere, but I'm pretty sure it's not made of
actual shit)</p>
However, I am pretty confident you can make things out of it.</p>
Hole in the floor? Pour that shit in!</strong></p>
Need a wall? Slop that shit up!</strong></p>
Got it wrong? Smash that shit to pieces!</strong></p>
(People can visit the Barbican all they like, it does not change the fact that nobody in human history has been or ever will be emotionally attached to the stuff.)</p>
</p>
Let's not be mistaken - our collection of recursive white goods factories are very nice. They may be the solution sometimes.
But what I think bothers me most about them is just how much emotional investment we end up having in them. When they're wrong,
we don't abandon ship, but instead save our precious work, bending it to our new needs, however grossly deformed the result.</p>
So, What Am I Suggesting?</h3>
How about just being boring? Would that be so wrong?</p>
Sure, concrete code is boring code to write, and nobody wants to be bored, or worse, boring by association with it.</p>
It is easy to understand though (and even easier to delete) because it's not wrapped up in 5 other levels of
abstraction. Do you really need to solve the meta-problem of your problem? Perhaps! I'm not
suggesting there aren't generalised problems worth solving, but check you're
not just doing it because your actual problem isn't interesting enough.</p>
Don't wrap your self-worth up in your cleverness. That way lies, at best, sadness, and at worst, singletons.</p>
Solve the thing, have a nice time, go home.</p>
There'll be another problem tomorrow, and this time you might be ready to
solve it rather than label it "scope creep" for not fitting yesterday's
solution.</p>
If your work ends up getting thrown away (it will), fine.</p>
It was made of shit anyway.</p>


Free like pizza, not like jazz
Unknown — Sat, 07 Sep 2019 00:00:00 +0000
When I first started working at a Serious Software Place</em>, I remember being very excited about the idea of testing things and dependency injection and purity and all such things. One day, I was spouting about this (presuming, I suppose, that everybody else was also so new to and thus enamoured with the topic), as well as these Functors</code> I had been reading about, and one of the more senior engineers said, "Well (raises eyebrows suggestively)</em>...you're going to LOVE</strong> Free Monads!".</p>
Now, many people that know me would agree I am a fairly jaded man, but I have to admit that even my interest was piqued. However, it's taken me absolutely fucking ages to work out what they are and how they relate to this original promise, and I think</em> they do, just not how I thought.</p>
The Intuition For Free Monads</h3>
So, the thing that took me the longest time to lose was this assumption I had made that a Free Monad</code> was a wild monad, from the edges of abstract math. It's Ornette Coleman! It's John Zorn! It's a saxophone played with a hoover! It can do anything, at any time! Needless to say, this was a very exciting idea, so I set out to read about, framing everything I read with this wild (but admittedly very attractive) mis-assumption. Needless to say, I was very confused and wasted a lot of time that I could have spent doing fun things instead.</p>
The reality is that the Free</code> in Free Monad</code> is not free like "jazz"</em> or "thinking"</em>, but free as in "pizza, at a tech meetup, knowing that of course the real price is listening through the following recruitment messages"</em>. They are still very good, but (in my humble opinion, etc)</em>, not half as fun as I had originally promised myself they would be.</p>
With this crushing piece of disappointment aside, let's look at what they actually are.</p>
Dogs Disguised As People By Way Of Wearing A Coat And Hat</h3>
</p>
Let's start with the idea of a Functor</code>. If this is confusing to you I have written a vague explanation</a> and so have much more competent</a> people</a> which are probably worth digesting before we go on.</p>
A functor is a data structure which contains some other data, and we can "map over" the data inside it to change that without fucking up the functor itself. For example, we can use the map</code> function on a Maybe</code> value, and it will change the a</code> on a Just</code>, and do nothing on Nothing</code>.</p>
data </span>Maybe
</span>  = </span>Just</span> a
</span>  | </span>Nothing
</span>
</span>fmap (+</span>1</span>) (</span>Just 1</span>) </span>-- Just 2
</span>fmap (+</span>1</span>) </span>Nothing  </span>-- Nothing
</span></code></pre>
Now, there is already a Monad</code> instance for Maybe</code>, and this means we can use do notation</code> and all sorts of great stuff with it, like this:</p>
-- get the first item of the first list
</span>-- and the first item of the second list
</span>-- and then smash them together using append
</span>-- from their semigroup instance
</span>firstAndSecondCombine 
</span>  :: (</span>Semigroup</span> a) 
</span>  => [a] 
</span>  -> [a] 
</span>  -> </span>Maybe</span> a
</span>firstAndSecondCombine firstList secondList = </span>do
</span>  a <- first' firstList
</span>  b <- first' secondList
</span>  pure (a <> b)
</span>
</span>-- helper that returns the first item of a list if it exists
</span>first' </span>::</span> [</span>a</span>] </span>-> Maybe </span>a
</span>first' stuff 
</span>    = </span>case</span> stuff </span>of
</span>        (x:_) -> </span>Just</span> x
</span>        _     -> </span>Nothing
</span></code></pre>
Let's try them with the Product</code> monoid (which multiplies its contents together when combined)</em>, to satisfy ourselves that this function does a thing that we vaguely like and approve of.</p>
This fails as it should....</p>
nah </span>:: Maybe</span> (</span>Product Int</span>)
</span>nah = firstAndSecondCombine </span>[] []
</span>-- nah == Nothing
</span></code></pre>
...and this gives us an answer.</p>
yeah </span>:: Maybe</span> (</span>Product Int</span>)
</span>yeah = firstAndSecondCombine 
</span>          [</span>Product 10</span>, </span>Product 11</span>]
</span>          [</span>Product 20</span>, </span>Product 5</span>]
</span>-- yeah == Just (Product 200)
</span></code></pre>
(Isn't Monoid</code> such a nice thing?)</em></p>
That Didn't Mention Dogs Or Hats, What Gives?</h3>
Ahh shit, yes.</p>
So.</p>
What if there isn't a Monad</code> instance? Or we want to write programs like this, but don't want to commit to using Maybe</code>? (or perhaps Maybe</code> is TOO</strong> safe, and we want the option of throwing loads of exceptions instead). Could this be a job for...a Free Monad</code>?</p>
(note for readers with subtext disabled in their browser: yes)</em></p>
OK. Let's make a datatype that's like Maybe</code>, but isn't.</p>
data </span>MoybeF</span> a
</span>  = </span>Jost</span> a
</span>  | </span>Nothong
</span></code></pre>
Let's make an instance of Functor</code> for it to prove there is no funny business at hand.</p>
instance Functor MoybeF where
</span>  fmap _ </span>Nothong  </span>= </span>Nothong
</span>  fmap f (</span>Jost</span> a) = </span>Jost</span> (f a)
</span></code></pre>
Map the f</code> function over an a</code> if there is one, if not, do nothing. Good?</p>
Still No Dogs, What Gives?</h3>
Right. In this example, MoybeF</code> is our dog. It's a plain old functor that doesn't really do anything except contain an a</code> inside Jost</code>, or contain nothing at all inside Nothong</code>. What Free</code> does for us (and by that, I mean Free</code> from Control.Monad.Free</a>) is gives us a coat to wrap about this Functor</code> to let us use it like a Monad</code>.</p>
(In this tenuous analogy, the Monad</code> represents a human adult, or at least some impression of one)</em></p>
-- Free turns MoybeF (a mere functor)
</span>-- into Moybe (a mighty monad)
</span>type </span>Moybe</span> a = </span>Free MoybeF</span> a
</span></code></pre>
(An aside: this metaphor felt a lot more powerful in my mind, but a cursory image search came up with a lot less than I had expected, and quite frankly this picture creeps me the fuck out).</em></p>
</p>
OK. So now, by use of the liftF</code> functor from Control.Monad.Free</code>, we can change any MoybeF</code> value into a Moybe</code> monad value instead. Let's define some helper functions that do this:</p>
-- lift a into the Moybe monad
</span>jost </span>:: </span>a </span>-> Moybe </span>a 
</span>jost = liftF . </span>Jost
</span>
</span>-- create an empty Moybe value
</span>nothong </span>:: Moybe </span>a
</span>nothong = liftF </span>Nothong
</span></code></pre>
Now, we can redefine our function from above to our our new exciting Moybe</code> type too!</p>
-- get first item (if there is one)
</span>fFirst' </span>::</span> [</span>a</span>] </span>-> Moybe </span>a
</span>fFirst' stuff 
</span>    = </span>case</span> stuff </span>of
</span>        (x:_) -> jost x
</span>        _     -> nothong
</span></code></pre>
(We could just have used liftF</code> directly, and avoided the helpers, but this way hopefully we can see better how equivalent the two first'</code> functions are)</p>
Now, let's remake our list smashing function from earlier using Moybe</code>....</p>
fFirstAndSecondCombine 
</span>  :: (</span>Semigroup</span> a) 
</span>  => [a] 
</span>  -> [a] 
</span>  -> </span>Moybe</span> a
</span>fFirstAndSecondCombine as bs = </span>do
</span>  a <- fFirst' as
</span>  b <- fFirst' bs
</span>  pure (a <> b)
</span></code></pre>
Hopefully, you can see it's pretty much the same. But how do we use it? If we run fFirstAndSecondCombine [] []</code>, for instance, what we get back is a MoybeF</code> again. So what the hell use is that? I went to all of this trouble to create a Monad</code> (admittedly as cheaply as possible) - but it doesn't do anything!</p>
Interpreting The Computation</h3>
So what is MoybeF</code>? Essentially, it's a data structure describing a monadic computation. Therefore, if we want to turn into something that does things, we need to interpret</em> it.</p>
Let's turn it back into our original Maybe</code> computation:</p>
interpretMaybe </span>:: Moybe </span>a </span>-> Maybe </span>a
</span>interpretMaybe
</span>  = foldFree interpret
</span>  </span>where
</span>    </span>interpret </span>:: MoybeF </span>a </span>-> Maybe </span>a
</span>    interpret prog'
</span>      = </span>case</span> prog' </span>of
</span>          </span>Jost</span> a  -> </span>Just</span> a
</span>          </span>Nothong </span>-> </span>Nothing
</span></code></pre>
As you can see, we're just substituting Jost</code> for Just</code> and Nothong</code> for the inferior Nothing</code>.</p>
Now we can use our function to actually do things like before:</p>
ans2 </span>:: Maybe</span> (</span>Product Int</span>)
</span>ans2 = interpretMaybe (fFirstAndSecondCombine [</span>Product 10</span>] [</span>Product 5</span>, </span>Product 20</span>])
</span>-- ans2 == Just (Product 200)
</span>
</span>ans3 </span>:: Maybe</span> (</span>Product Int</span>)
</span>ans3 = interpretMaybe (fFirstAndSecondCombine </span>[]</span> [</span>Product 5</span>, </span>Product 20</span>])
</span>-- ans3 == Nothing
</span></code></pre>
I See That Once Again We're Doing Something Easy The Difficult Way</h3>
OK, fair point. Where is the value in all this indirection?</p>
How about if we want to interpret this computation differently? Perhaps we need to return an Either</code> instead? Changing the interpreter is pretty straightforward:</p>
interpretEither </span>:: Moybe </span>a </span>-> Either String </span>a
</span>interpretEither
</span>  = foldFree interpret
</span>  </span>where
</span>    </span>interpret </span>:: MoybeF </span>a </span>-> Either String </span>a
</span>    interpret prog'
</span>      = </span>case</span> prog' </span>of
</span>          </span>Jost</span> a  -> </span>Right</span> a
</span>          </span>Nothong </span>-> </span>Left </span>"</span>Nah, that didn't work</span>"
</span>
</span>ans4 </span>:: Either String</span> (</span>Product Int</span>)
</span>ans4 = interpretEither (fFirstAndSecondCombine [</span>Product 10</span>] [</span>Product 5</span>, </span>Product 20</span>])
</span>-- ans4 == Right (Product 200)
</span>
</span>ans5 </span>:: Either String</span> (</span>Product Int</span>)
</span>ans5 = interpretEither (fFirstAndSecondCombine </span>[]</span> [</span>Product 5</span>, </span>Product 20</span>])
</span>-- ans5 == Left "Nah, that didn't work"
</span></code></pre>
Is This...A Domain Specific Language?</h3>
That's right. One of the main strengths of Free</code> is in creating small little sub-languages for writing logic, that can be interpreted in a number of different ways (such as "what even is this doing?"</em> and "i don't understand this code"</em>)</p>
How Does This Relate To Testing?</h3>
So, this example is pointedly very simple indeed, and involve swapping one pure thing for another, but a much more common use of this pattern is to take some code that does effectful things (like save files, write to a database, etc) and write them in a way where they can be run in the program using IO</code>, but then testing by turning them into something pure like Writer</code>, and looking at the output.</p>
Do You Have An Example Of Exactly That, Preferably Centered About Reading And Writing To A Terminal Window, Perchance?</h3>
Why yes, I do.</p>
So ConsoleF</code> is a Functor</code> with two commands for input and output from a terminal.</p>
data </span>ConsoleF</span> next
</span>  = </span>Write String</span> next
</span>  | </span>Read</span> (</span>String </span>-> next)
</span>
</span>instance Functor ConsoleF where
</span>    fmap f (</span>Write</span> s next) = </span>Write</span> s (f next)
</span>    fmap f (</span>Read</span> next)    = </span>Read</span> (f . next)
</span></code></pre>
We power it up into a Free Monad</code>...</p>
type </span>Console</span> a = </span>Free ConsoleF</span> a
</span></code></pre>
...and then we write our helpers with liftF</code>...</p>
-- write to the console
</span>fWrite </span>:: String -> Console </span>()
</span>fWrite str = liftF $ </span>Write</span> str </span>()
</span>
</span>-- await user input
</span>fRead </span>:: Console String
</span>fRead = liftF $ </span>Read</span> id
</span></code></pre>
...then we write our program with it...</p>
consoleProg </span>:: Console </span>()
</span>consoleProg = </span>do
</span>    fWrite "</span>What is your name?</span>"
</span>    a <- fRead
</span>    fWrite $ "</span>Sure? </span>" ++ a
</span>    b <- fRead
</span>    fWrite "</span>Great.</span>"
</span></code></pre>
...then we interpret in IO</code> to make a working program...</p>
interpretIO </span>:: Console </span>a </span>-> IO </span>a
</span>interpretIO
</span>  = foldFree interpret
</span>  </span>where
</span>    </span>interpret </span>:: ConsoleF </span>a </span>-> IO </span>a
</span>    interpret prog'
</span>      = </span>case</span> prog' </span>of
</span>          </span>Write</span> s a -> </span>Prelude</span>.putStrLn s >> pure a
</span>          </span>Read</span> a    -> a <$> </span>Prelude</span>.getLine
</span></code></pre>
...then we interpret it in Writer</code> for testing...</p>
interpretWrite </span>:: Console </span>a </span>-> Writer</span> [</span>String</span>] </span>a
</span>interpretWrite = foldFree interpretConsoleWrite
</span>  </span>where
</span>    interpretConsoleWrite prog'
</span>      = </span>case</span> prog' </span>of
</span>          </span>Write</span> s a -> </span>do
</span>            _ <- tell [s]
</span>            pure a
</span>          </span>Read</span> a -> </span>do
</span>            _ <- tell ["</span>[wait for input]</span>"]
</span>            pure (a "</span>[user input]</span>")
</span></code></pre>
...run it...</p>
output </span>::</span> [</span>String</span>]
</span>output = (snd . runWriter . interpretWrite ) consoleProg
</span>-- output == ["What is your name?","[wait for input]","Sure? [user input]","[wait for input]","Great."]
</span></code></pre>
...and we go home for a nice sit down.</p>
Isn't This The Point Of Typeclasses?</h3>
Aye, some would say so</a>. But what's the point of Haskell if there isn't 10 ways of doing the same thing, and endless bloody fights to the death about the minor differences between them?</p>
That Is True, You Are So Right. Any Other Helpful Links?</h3>
The thing that finally made all this click for me was this video by Nate Faubion</a>. Once I did understand it wasn't about jazz, this by Matt Parsons</a> was really great too.</p>


Mr Migration
Unknown — Sun, 14 Jul 2019 00:00:00 +0000
A few weeks ago I gave a talk at London Haskell that was basically an advert for a data migrating library I haven't even finished yet. However, I managed on the whole to hide this fact and some people even came up afterwards and asked me how the library was performing in production to which of course I said "very well indeed, because of course i am very good at computers" and quickly changed the subject.</p>
What follows is basically the crap from my slides, occasionally turned from bullet lists into sentences where I realised I had overused that particular presentation device a little much.</p>
Sitting comfortable? Then we shall begin...</p>
In The Beginning...</h3>
...we had server side applications.</p>


If the code agrees with the DB schema...</p>
</li>

Deploy!</p>
</li>

Great!</strong></p>
</li>
</ul>
Then Came Javascript...</h3>


Suddenly all our data was spread around the place</p>
</li>

Things didn't necessarily agree with one another</p>
</li>

There was sometimes JQuery</em>.</p>
</li>
</ul>
And at some point we land at</p>
The Traditional Backend / Frontend Monolith</h3>


When the back end changes...</p>
</li>

Change the front end too.</p>
</li>

Deploy everything together</strong></p>
</li>

(did you forget to update the DB schema?)</p>
</li>

DO THAT QUICKLY</strong></p>
</li>

Forget about the past</p>
</li>

YOLO</strong></p>
</li>
</ul>
So...</h3>
What could possibly go wrong with this?</p>
</p>
Problem One</h3>
Company A</code> have found that DB schema changes make changing the application more difficult than they would like. Therefore they choose to use event sourcing</strong>. As the application changes, the DB schemas keep up, but they are soon left with an event table full of various historical versions of JSON data.</p>

What is this data? Do they still understand it?</em></li>
</ul>
Problem Two</h3>
Company B</code> decide their code is so good that they are going to create a public API</strong>. Other companies decide to use this API, and annoyingly want it not to change at random. Therefore the API owners make promises not to change their API (even though they bloody love changing their API because they are 10x hackers who just can't stop delivering business value).</p>

How can they make changes to this without breaking everything?</em></li>
</ul>
Problem Three</h3>
Company C</code> have noticed that large monoliths take ages to deploy</em>. They would also like to decouple teams to maximise parallelisation of work. They adopt a microservice architecture</strong>. Suddenly, services that talk to one another aren't guaranteed to have versions or interfaces that match, so a old service can be receiving requests from a very old service that hasn't been updated.</p>

How will they cope with communicating with any number of historical deployments?</em></li>
</ul>
A concrete example</h3>
Here's a data type that we use in our business critical application. It is called OldUser</code>, which we never really questioned at the time.</p>
data </span>OldUser
</span>  = </span>OldUser 
</span>    { firstName :: </span>String
</span>    , surname   :: </span>String
</span>    , pet       :: </span>String
</span>    , age       :: </span>Int
</span>    }
</span></code></pre>
Business is going pretty well, I can't imagine my meeting this afternoon will go badly...</p>
Oh no!</h3>
</p>
Pivot immediately</h3>
Apparently we can increase profitability by 30%</em> by using newtypes properly.</p>
newtype </span>Name
</span>  = </span>Name</span> { getName :: </span>Text</span>.</span>Text</span> }
</span></code></pre>
And replacing String</code> selections of pet</code> types with a more restrictive sum type.</p>
data </span>OldPet
</span>  = </span>OldDog
</span>  | </span>OldCat
</span>  | </span>NoPet
</span></code></pre>
These changes took all night, but you really pulled through there.</p>
data </span>NewUser
</span>  = </span>NewUser
</span>    { newFirstName :: </span>Name
</span>    , newSurname   :: </span>Name
</span>    , newPet       :: </span>OldPet
</span>    , newAge       :: </span>Int
</span>    }
</span></code></pre>
Great job.</p>
Hold On Though</h3>
Business is obviously booming now, but what are we going to do about:</p>


Third parties that will insist on using OldUser</code> in their API calls for the
next 18 months</p>
</li>

Stored JSON data with the old data shape</p>
</li>
</ul>
What options do we have?</h3>

As well as developing new code, we keep old code</strong> for dealing with the old data</strong></li>
</ol>

This seems fine...</li>
...till you're fixing bugs in the old system too</li>
Shit! More fixes! Now you're got an new-old system as well as the new-new one.</li>
More fixes again! Now we have a new-old-new-old system to maintain as well as your main one, which is a new-new-new system by now? It may have been superceded too. Oh dear.</li>
</ul>

Or migrate the old datatypes</strong> to the new datatypes</strong> and keep one set of logic.</li>
</ol>

Logic stays in new code</li>
Bug fixes in business logic happen once</li>
Logic of migration separated from business logic</li>
</ul>
Decision time</h3>
If you choose Option 1</code>, you are on your own. However, if you have chosen Option 2</code>, read on...</p>
</p>
Functions we will need: migrate</h3>
The first thing we'll need is a function to convert our old terrible datatype</em> into our new incredible exciting datatype</em>, in this case OldUser</code> to NewUser</code>.</p>
migrate </span>:: OldUser -> NewUser
</span></code></pre>
Actually. Let's be realistic about this, and account for the idea that this operation could fail, as life is a bin.</p>
migrate </span>:: OldUser -> Maybe NewUser
</span></code></pre>
Functions we will need: parse</h3>
We'll also need some functions for decoding JSON, as I have made the somewhat brazen assumption this is a REST API that only receives JSON payloads. We'll use functions from the Aeson</code> library because it is reasonably ubiquitous.</p>
This function will attempt converting some JSON</code> into an OldUser</code></p>
parseOldUser </span>:: JSON -> Maybe OldUser
</span>parseOldUser json
</span>  = parseMaybe (parseJSON json)
</span></code></pre>
And this very similar function will try and convert from JSON</code> into a NewUser</code>.</p>
parseNewUser </span>:: JSON -> Maybe NewUser
</span>parseNewUser
</span>  = parseMaybe . parseJSON
</span></code></pre>
Putting it together</h3>
We can then make a function that takes some JSON</code>, and then tries to decode it into a NewUser</code>. If it can't decode it into a NewUser</code>, it tries to parse it into an OldUser</code>, and if that succeeds, it uses some sort of migrate</code> function to turn OldUser</code> into a NewUser</code>.</p>
Said function looks something like this:</p>
parseSomeKindOfUser </span>:: JSON -> Maybe NewUser
</span>parseSomeKindOfUser json
</span>   =   parseNewUser json
</span>  <|> (parseOldUser json >>= migrate)
</span></code></pre>
(The <|></code> operator comes from the Alternative</code> typeclass, and works sort of like the ||</code> function. The intuition is try this OR try this</code>)</p>
Does it scale though?</h3>
It seems to do the job, with a couple of datatypes, however it's easy to see how it could get out of hand...</p>
thing = parse a
</span>    <|> parse b >>= migrate
</span>    <|> parse c >>= migrate >>= migrate
</span>    <|> parse d >>= migrate >>= migrate >>= migrate
</span>    <|> parse e >>= migrate >>= migrate >>= migrate >>= migrate
</span>    <|> parse f >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate
</span>    <|> parse g >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate
</span>    <|> parse h >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate
</span>    <|> parse i >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate
</span>    <|> parse j >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate
</span>    <|> parse k >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate
</span>    <|> parse l >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate 
</span>    <|> parse m >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate >>= migrate
</span></code></pre>
So this method is a no?</h3>
I don't think so. But writing all of that is a bit much. Hopefully right now you are asking "Why can't I get the compiler to do this for me?".</p>
</p>
Good Point.</h3>
OK! Let's give it a smash. We start by making a typeclass and using it to version tag our datatype.</p>
class </span>Versioned</span> (</span>label</span> :: </span>Symbol</span>) (</span>num</span> :: </span>Nat</span>) </span>where
</span>  </span>type</span> num </span>`</span>VersionOf</span>`</span> label :: </span>Type
</span></code></pre>
(This VersionOf</code> type here is an associated type family</code> - a type level function that is scoped to only work inside the typeclass it is defined in.)</p>
The typeclass defines a function we can use to find a datatype from the label</code> and the num</code>. For example, we can make a label called "User"</code>, and make OldUser</code> version 1</code> of it:</p>
instance Versioned</span> "</span>User</span>" 1 </span>where
</span>  </span>type </span>1 </span>`</span>VersionOf</span>` </span>"</span>User</span>" = </span>OldUser
</span></code></pre>
We'll also define an instance for NewUser</code>, and make that version 2</code> of it.</p>
instance Versioned</span> "</span>User</span>" 2 </span>where
</span>  </span>type </span>2 </span>`</span>VersionOf</span>` </span>"</span>User</span>" = </span>NewUser
</span></code></pre>
Linking versions together</h3>
Next we make a typeclass for migrations that uses our VersionOf</code> type function:</p>
class </span>Migratable</span> (</span>label</span> :: </span>Symbol</span>) (</span>num</span> :: </span>Nat</span>) </span>where
</span>  fromPrevious
</span>    :: (num - </span>1</span>) </span>`</span>VersionOf</span>`</span> label
</span>    -> </span>Maybe</span> (num </span>`</span>VersionOf</span>`</span> label)
</span></code></pre>
It lets us define a function from the previous version of a datatype to the current one, so let's use it to migrate OldUser</code> to NewUser</code>.</p>
instance Migratable</span> "</span>User</span>" 2 </span>where
</span>  </span>fromPrevious </span>:: OldUser -> Maybe NewUser
</span>  fromPrevious older
</span>    = </span>Just </span>$ </span>NewUser 
</span>              { newFirstName = </span>Name</span> (</span>Text</span>.pack (firstName older))
</span>              , newSurname   = </span>Name</span> (</span>Text</span>.pack (surname older))
</span>              , newPet       = readPet (pet older)
</span>              , newAge       = age older
</span>              }
</span>    </span>where
</span>      readPet s
</span>        | s == "</span>dog</span>" = </span>OldDog
</span>        | s == "</span>cat</span>" = </span>OldCat
</span>        | otherwise  = </span>NoPet
</span></code></pre>
Problem: Migrating from old JSON versions</h3>
Once we've defined instances of the Versioned</code> and Migratable</code> typeclasses for our data, the Data.Migratable</code> library functions start doing helpful things. It provides a version of migrate</code> function we defined concretely earlier, but with a much more exciting (confusing) type signature.</p>
migrate 
</span>  :: earliest </span>`</span>VersionOf</span>`</span> label 
</span>  -> </span>Maybe</span> (target </span>`</span>VersionOf</span>`</span> label)
</span></code></pre>
It means "I can take the earliest</code> version of label</code> and Maybe</code> return you the target</code> version of label</code>". We use type applications</em> to pass versions</code> and a label</code> to convert an old datatype to a new one.</p>
oldToNew </span>:: OldUser -> Maybe NewUser
</span>oldToNew = migrate @</span>1</span> @</span>2</span> @"</span>User</span>"
</span></code></pre>
Going from version 1</code> to 2</code> means we've just done a shitload of work for a single conversion, but the same function will recursively convert through as many versions of the datatype as you like:</p>
veryOldToVeryNew </span>:: OldUser -> Maybe VeryNewUser
</span>veryOldToVeryNew = migrate @</span>1</span> @</span>100</span> @"</span>User</span>"
</span></code></pre>
Solution: parseJSONVia</h3>
The Data.Migratable</code> library also provides us parseJSONVia</code>, with the following exciting type signature:</p>
parseJSONVia
</span>  :: </span>JSON 
</span>  -> </span>Maybe</span> (target </span>`</span>VersionOf</span>`</span> label)
</span></code></pre>
We could use to try converting from both OldUser</code> and NewUser</code> like this:</p>
parseSomeKindOfUser 
</span>  :: </span>JSON 
</span>  -> </span>Maybe NewUser
</span>parseSomeKindOfUser 
</span>  = parseJSONVia @"</span>User</span>" @</span>1</span> @</span>2
</span></code></pre>
Underneath, this is doing our parse</code> and migrate</code> pattern under thge good</p>
thing = parse @</span>NewUser
</span>    <|> parse @</span>OldUser </span>>>= migrate
</span></code></pre>
A note on Type Applications</h3>
To understand how to pass the types to the parseJSONVia</code> function, we need to look at the Schema</code> typeclass that provides this functionality:</p>
class </span>Schema</span> (</span>label</span> :: </span>Symbol</span>) (</span>earliest</span> :: </span>Nat</span>) (</span>target</span> :: </span>Nat</span>) </span>where
</span>  </span>parseJSONVia </span>:: JSON</span>.</span>Value -> JSON</span>.</span>Parser</span> (</span>target</span> `</span>VersionOf</span>` </span>label</span>)
</span></code></pre>
When we use it, we are passing it types in the order they appear in the class declaration.</p>
parseJSONVia @"</span>User</span>" @</span>1</span> @</span>2
</span></code></pre>
Therefore, we are passing the type-level symbol "User"</code> as the first argument label</code>, then a type-level natural number 1</code> as the starting version earliest</code>, and finally another type-level natural 2</code> as the target version target</code>.</p>
Problem: Uniqueness checking</h3>
Uniqueness checking is another feature of Data.Migratable</code>. Let's say that we have this data type Info</code>:</p>
data </span>Info
</span>  = </span>Info 
</span>      { amount: </span>Pounds</span> }
</span></code></pre>
Then, after another hard pivot, we change the units:</p>
data </span>NewInfo
</span>  = </span>NewInfo
</span>      { amount :: </span>Pennies</span> }
</span></code></pre>
In our static typed ivory tower, we are fine, but our clients keep sending us
this:</p>
{ "</span>amount</span>": </span>100 </span>}
</span></code></pre>
What is it? 100 pennies? 100 pounds? How can we stop this confusion?</p>
Solution: Checking for duplicates with QuickCheck</h3>
Data.Migratable</code> provides us with the matchAll</code> function:</p>
matchAll </span>:: IO</span> (</span>Either</span> [</span>MatchError</span>] [</span>Integer</span>])
</span></code></pre>


It uses QuickCheck</code> and it's Arbitrary</code> instances to generate random JSON</code>
values for each datatype</p>
</li>

Then tries to load each generated value as each version of the datatype</p>
</li>

And tells us how many version of a datatype each generated instance is able
to decode</p>
</li>

If it's one each - we're going to have a good time:</p>
</li>
</ul>
describe "</span>Uses Arbitrary to generate said tests</span>" $ </span>do
</span>  it "</span>Checks if our datatypes will get confused</span>" $ </span>do
</span>    found <- matchAll @</span>1</span> @</span>4</span> @"</span>User</span>"
</span>    found </span>`</span>shouldBe</span>` </span>Right</span> [</span>1</span>,</span>2</span>,</span>3</span>,</span>4</span>]
</span></code></pre>

But if our JSON</code> representations are non-unique, we'll know:</li>
</ul>
describe "</span>Our Pennies and Pounds schema</span>" $ </span>do
</span>  it "</span>Spots our problematic matching schema</span>" $ </span>do
</span>    found <- matchAll @</span>1</span> @</span>2</span> @"</span>Same</span>"
</span>    found </span>`</span>shouldBe</span>` </span>Left</span> [</span>Duplicates 1</span> [</span>2</span>,</span>1</span>], </span>Duplicates 2</span> [</span>2</span>,</span>1</span>]]
</span></code></pre>

And we can fix our data types to ensure uniqueness.</li>
</ul>
data </span>Info
</span>  = </span>Info 
</span>      { amountPounds :: </span>Pounds</span> }
</span>
</span>data </span>NewInfo
</span>  = </span>NewInfo
</span>      { amountPennies :: </span>Pennies</span> }
</span></code></pre>

Good job.</li>
</ul>
Problem: getting a FromJSON instance</h3>
The Aeson</code> library works by making datatypes define instances of the FromJSON</code> typeclass, and packages like Servant</code> allow us to automagically create web servers that use these types. Can we still use all this good stuff?</p>
Solution: FromJSON instance around a newtype wrapper</h3>
newtype </span>APIUser
</span>  = </span>APIUser</span> { getAPIUser :: </span>WhateverTheNewestUserTypeIsTheseDays</span> }
</span></code></pre>
...and using parseJSONVia</code> to create a FromJSON</code> instance for that datatype...</p>
instance JSON</span>.</span>FromJSON APIUser where
</span>  parseJSON a
</span>    = </span>APIUser </span><$> parseJSONVia @"</span>User</span>" @</span>1</span> @</span>4</span> a
</span></code></pre>
...we can make a Servant</code> server that can read any of our historical datatypes.</p>
type </span>ExcellentApi </span>=
</span>  "</span>user</span>" :> </span>Get</span> '[</span>JSON</span>] [</span>APIUser</span>] 
</span></code></pre>
Great job!</p>
Problem: Mistakes in our datatypes</h3>
What if we make "mistakes" in our types - like removing a piece of data we later decide we need? Here is a first version of some data.</p>
data </span>Dog
</span>  = </span>Dog</span> { name :: </span>String
</span>        , age  :: </span>Int
</span>        }
</span>
</span>instance Versioned</span> "</span>Dog</span>" 1 </span>where
</span>  </span>type </span>1 </span>`</span>VersionOf</span>` </span>"</span>Dog</span>" = </span>Dog
</span></code></pre>
This is the second version of the datatype, where we remove age</code>.</p>
data </span>AgelessDog
</span>  = </span>AgelessDog
</span>      { name :: </span>String</span> }
</span>
</span>instance Versioned</span> "</span>Dog</span>" 2 </span>where
</span>  </span>type </span>2 </span>`</span>VersionOf</span>` </span>"</span>Dog</span>" = </span>AgelessDog
</span></code></pre>
Oops. We needed that. It's back in version 3</code>.</p>
data </span>WithAgeDog
</span>  = </span>WithAgeDog
</span>      { name :: </span>String
</span>      , age  :: </span>Int
</span>      , tail :: </span>Bool
</span>      }
</span>
</span>instance Versioned</span> "</span>Dog</span>" 3 </span>where
</span>  </span>type </span>3 </span>`</span>VersionOf</span>` </span>"</span>Dog</span>" = </span>WithAgeDog
</span></code></pre>
However, this means any version 1</code> piece of data will convert through version 2</code> and lose everything on the way.</p>
Solution: multiple import paths</h3>
Let's change our declarations...</p>
data </span>Dog
</span>  = </span>Dog</span> { name :: </span>String
</span>        , age  :: </span>Int
</span>        }
</span>
</span>instance Versioned</span> "</span>Dog</span>" 1 </span>where
</span>  </span>type </span>1 </span>`</span>VersionOf</span>` </span>"</span>Dog</span>" = </span>Dog
</span>
</span>instance Versioned</span> "</span>AgeDog</span>" 1 </span>where
</span>  </span>type </span>1 </span>`</span>VersionOf</span>` </span>"</span>AgeDog</span>" = </span>Dog
</span></code></pre>
(We've ignored the middle one for now - it is the same)</p>
data </span>WithAgeDog
</span>  = </span>WithAgeDog
</span>      { name :: </span>String
</span>      , age  :: </span>Int
</span>      , tail :: </span>Bool
</span>      }
</span>
</span>instance Versioned</span> "</span>Dog</span>" 3 </span>where
</span>  </span>type </span>3 </span>`</span>VersionOf</span>` </span>"</span>Dog</span>" = </span>WithAgeDog
</span>
</span>instance Versioned</span> "</span>AgeDog</span>" 2 </span>where
</span>  </span>type </span>2 </span>`</span>VersionOf</span>` </span>"</span>AgeDog</span>" = </span>WithAgeDog
</span></code></pre>
Then our parsing function becomes (something like)</p>
parseSomeKindOfDog </span>:: JSON -> Maybe WithAgeDog
</span>parseSomeKindOfDog json
</span>  =  parseJSONVia @"</span>AgeDog</span>" @</span>1</span> @</span>2</span> json
</span> <|> parseJSONVia @"</span>Dog</span>" @</span>1</span> @</span>3</span> json
</span></code></pre>
How does it work?</p>


First, we try the lossless path</p>
</li>

Failing that, we try the lossy path to pick up any AgeLessDog</code> values.</p>
</li>
</ul>
OK. Sum up what you've said and stop selling me your crappy non-existent library</h3>
So hopefully, this technique should let you:</p>


Define migrations outside the main logic code, throw those into a file and forget about them forever until the next migration.</p>
</li>

Use simple ADTs for my types if one feels like it.</p>
</li>

Avoid historical code making new code more complicated.</p>
</li>
</ul>
But does it work?</h3>
Who knows? See the code at
https://github.com/danieljharvey/migratable</a> and decide for yourself. I mean, the tests pass, but what does that really tell us.</p>
Addendum</h3>
After the talk, somebody suggested that it's all very well accepting old JSON data version in an API, but really you'd need to provide the response in the old format too. This was a really annoyingly good point, so this is the next feature I am working on for the library - the plan so far is to create a kind of opposite of the Migratable</code> typeclass for responses, that goes from newer to older versions instead.</p>


Refine, fine, fine
Unknown — Fri, 05 Jul 2019 00:00:00 +0000
About a month ago I gave a talk about Refined</code> types at a React meetup.
Needless to say, it was a resounding success so I thought I would share an
adapted version of the slides so that you can all learn to be as learned as me
when it comes to such a topic.</p>
Let's start by listing some things that we as programmers generally agree we don't particularly like:</p>
Runtime errors caused by Javascript YOLO</h3>
Here is some classic code written in the Javascript programming language:</p>
function </span>makeBig</span>(</span>thing</span>) {
</span>  </span>return </span>thing</span>.</span>toUpperCase</span>()
</span>}
</span></code></pre>
At a casual glance, it would appear to be some rather convoluted code for
making a string uppercase.</p>
Therefore, this seems fine:</p>
makeBig</span>('</span>horse</span>') </span>// 'HORSE'
</span></code></pre>
But this isn't so great:</p>
makeBig</span>(</span>12</span>) </span>// Error: toUpperCase is not defined
</span></code></pre>
What happened? Well it wasn't really a function for making strings uppercase,
it was a function that takes any piece of data, then makes it uppercase if it's
a string, and just breaks weirdly with anything else.</p>
Another thing we don't really like doing as programmers is...</p>
Overly defensive code around user input</h3>
So if your start in programming involved more than a sprinkling of PHP, then
you'll be used to starting all your functions with the manual typechecking dance</code>.</p>
function </span>printName</span>(</span>name</span>) {
</span>  </span>if </span>(</span>name </span>&& </span>name</span>.length > </span>0 </span>&& typeof </span>name </span>=== '</span>string</span>') </span>then </span>{
</span>    </span>return </span>name
</span>  } </span>else </span>{
</span>    </span>return </span>"</span>No name!</span>"
</span>}
</span></code></pre>
Defense against the dark arts</h3>
Another favourite is manually checking our values to check basic mathematical
operators aren't going to explode the whole computer.</p>
function </span>divide</span>(</span>a</span>, </span>b</span>) {
</span>  </span>if </span>(</span>b </span>== </span>0 </span>|| </span>isNaN</span>(</span>a</span>) || </span>isNaN</span>(</span>b</span>)) </span>then </span>{
</span>    </span>return </span>0</span>; </span>// would have caused error
</span>  } </span>else </span>{
</span>    </span>return </span>a </span>/ </span>b
</span>  }
</span>}
</span>
</span></code></pre>
How far does something like Typescript get us?</h3>
So we can change our weird uppercasing function...</p>
function </span>makeBig</span>(</span>thing</span>) {
</span>  </span>return </span>thing</span>.</span>toUpperCase</span>()
</span>}
</span></code></pre>
...to only take a string like we intended.</p>
function </span>makeBig</span>(</span>thing</span>: string) {
</span>  </span>return </span>thing</span>.</span>toUpperCase</span>()
</span>}
</span></code></pre>
Let's give it a smash:</p>
makeBig</span>('</span>horse</span>') </span>// 'HORSE'
</span></code></pre>
Excellent stuff.</p>
And now, if we try and do some wild type stupidity, our code doesn't even compile:</p>
makeBig</span>(</span>12</span>) 
</span>// Argument of type '6' is not assignable to parameter of type 'string'.
</span></code></pre>
+1</p>
What about this potentially malformed user input?</h3>
This Wild West Cowboy Javascript...</p>
function </span>printName</span>(</span>name</span>) {
</span>  </span>if </span>(</span>name </span>&& </span>name</span>.length > </span>0 </span>&& typeof </span>name </span>=== '</span>string</span>') </span>then </span>{
</span>    </span>return </span>name
</span>  } </span>else </span>{
</span>    </span>return </span>"</span>No name!</span>"
</span>}
</span></code></pre>
...gets a string type, which means we don't have to check that name</code> exists...</p>
function </span>printName</span>(</span>name</span>: string) {
</span>  </span>if </span>(</span>name</span>.length > </span>0</span>) </span>then </span>{
</span>    </span>return </span>name
</span>  } </span>else </span>{
</span>    </span>return </span>"</span>No name!</span>"
</span>}
</span></code></pre>
...but we still need to check whether name</code> is long enough and return a default if not.</p>
What about that classic divide by zero problem?</h3>
What can basic types give us here?</p>
function </span>divide</span>(</span>a</span>, </span>b</span>) {
</span>  </span>if </span>(</span>b </span>== </span>0 </span>|| </span>isNaN</span>(</span>a</span>) || </span>isNaN</span>(</span>b</span>)) </span>then </span>{
</span>    </span>return </span>0</span>; </span>// would have caused error
</span>  } </span>else </span>{
</span>    </span>return </span>a </span>/ </span>b
</span>  }
</span>}
</span></code></pre>
We can get rid of the number checks...</p>
function </span>divide</span>(</span>a</span>: number, </span>b</span>: number) {
</span>  </span>if </span>(</span>b </span>== </span>0</span>) </span>then </span>{
</span>    </span>return </span>0</span>; </span>// would have caused error
</span>  } </span>else </span>{
</span>    </span>return </span>a </span>/ </span>b
</span>  }
</span>}
</span></code></pre>
...but we've still got to check for that zero value. Better, but not great. What if I told you we could do better than this?</p>
Refined</h3>
Enter Refined</code> types. A Refined type looks like this:</p>
newtype </span>Refined</span> predicate value = </span>Refined</span> value
</span></code></pre>
As it is a newtype</code> it is a wrapper around a value that is used for type
purposes at compile time but then erased at run time (so when the program runs,
Refined 100</code> is just 100</code> as far as memory etc is concerned)</p>
value</code> is the type of actual data we are refining, for example Int</code> or Number</code>.</p>
predicate</code> is a type that lets us better describe the value</code>.</p>
The most interesting thing to note here is that predicate</code> only exists on the type side (ie before the =</code>) and not after - this makes it a phantom type</code> which is only used to add contextual information. Let's see what that actually means...</p>
Making Refined values</h3>
There are a few ways to make Refined</code> values, especially in the Haskell
library - we'll concentrate on two. I'm going to use the types from the
Purescript version because a) they're simpler and b) I made them and am thus
less likely to get it wrong.</p>
refine 
</span>  :: value 
</span>  -> </span>Either RefinedError</span> (</span>Refined</span> predicate value)
</span></code></pre>
This is the regular way to make Refined</code> value - you pass it a plain value and
it returns either Left</code> with a RefinedError</code> describing the problem, or Right</code> with
the Refined</code> value inside.</p>
unsafeRefine 
</span>  :: value 
</span>  -> </span>Refined</span> predicate value
</span></code></pre>
This ignores the predicate</code> and leaves it to the programmer to go full YOLO
and decide whether the predicate will be fine. I have used this to make
Monoid</code> classes where I want to add two positive numbers without checking
that the outcome will still be positive.</p>
Id</h3>
The most basic predicate is id</code>, which doesn't really do anything.</p>
Refined Id Int
</span></code></pre>
It's named after the id</code> (or identity</code>) function - the function that returns whatever it
receives, basically doing nothing.</p>
identity </span>:: </span>x </span>-> </span>x
</span>identity x = x
</span></code></pre>
For example, any value that is a value Int</code> can be made into a valid Refined Id Int</code>.</p>
id1 </span>:: Either RefinedError</span> (</span>Refined Id Int</span>)
</span>id1 = refine </span>11233
</span>-- id1 == Right (Refined 11233)
</span></code></pre>
id2 </span>:: Either RefinedError</span> (</span>Refined Id Int</span>)
</span>id2 = refine (-</span>213123</span>)
</span>-- id2 == Right (Refined (-213123)
</span></code></pre>
Positive</h3>
The Positive</code> predicate, which only allows numbers over 0.</p>
Refined Positive Int
</span></code></pre>
This refinement would pass the predicate:</p>
positive1 </span>:: Either RefinedError</span> (</span>Refined Positive Int</span>)
</span>positive1 = refine </span>10
</span>-- positive1 == Right (Refined 10)
</span></code></pre>
This clearly very negative number clearly won't fly. Nice try, ding dongs!</p>
positive2 </span>:: Either RefinedError</span> (</span>Refined Positive Int</span>)
</span>positive2 = refine (-</span>10</span>)
</span>-- positive2 == Left (GreaterThanError 0 (-10))
</span></code></pre>
From</h3>
We can be even more specific with these types too. The From</code> predicate takes an integer and only allows values equal to or above
it.</p>
Refined</span> (</span>From D10</span>) </span>Int
</span></code></pre>
(A note here - that D10</code> is a type-level 10</code>. It is provided by the purescript-typelevel</a> package.)</p>
Therefore this 9</code> is clearly taking the piss and totally won't refine</code>.</p>
from1 </span>:: Either RefinedError</span> (</span>Refined</span> (</span>From D10</span>) </span>Int</span>)
</span>from1 = refine </span>9
</span>-- from1 == Left (FromError 10 9) 
</span></code></pre>
However this 100</code> is cool with me, and will happily refine</code>.</p>
from2 </span>:: Either RefinedError</span> (</span>Refined</span> (</span>From D10</span>) </span>Int</span>)
</span>from2 = refine </span>100
</span>-- from2 == Right (Refined 100)
</span></code></pre>
To</h3>
Hopefully it should be fairly intuitive how the To</code> predicate works...</p>
to1 </span>:: Either RefinedError</span> (</span>Refined</span> (</span>To D20</span>) </span>Int</span>)
</span>to1 = refine </span>21
</span>-- to1 == Left (ToError 20 21)
</span></code></pre>
to2 </span>:: Either RefinedError</span> (</span>Refined</span> (</span>To D20</span>) </span>Int</span>)
</span>to2 = refine </span>17
</span>-- to2 == Right (Refined 17)
</span></code></pre>
SizeEqualTo, SizeGreaterThan, SizeLessThan</h3>
Refinements don't have to just be about numbers - we can use them on foldable</code>
structures too, such as Lists</code>. The refinements let us be specific about sizes
of said structure. Therefore we could make a non-empty List</code> of Boolean</code>
values with Refined (SizeGreaterThan D0) (List Boolean)</code>.</p>
Refined</span> (</span>SizeGreaterThan 3</span>) (</span>List Number</span>)
</span></code></pre>
Therefore this list does not refine</code>...</p>
size1 </span>:: Refined RefinedError</span> (</span>Refined</span> (</span>SizeGreaterThan D3</span>) (</span>List Number</span>))
</span>size1 = refine [</span>1</span>, </span>2</span>]
</span>-- size1 == Left (SizeGreaterThanError 3 [1, 2])
</span></code></pre>
...but this one is fine.</p>
size2 </span>:: Refined RefinedError</span> (</span>Refined</span> (</span>SizeGreaterThan D3</span>) (</span>List Number</span>))
</span>size2 = refine [</span>1</span>, </span>2</span>, </span>3</span>, </span>4</span>]
</span>-- size2 == Right (Refined [1, 2, 3, 4])
</span></code></pre>
And, Or</h3>
These type signatures are starting to get pretty hefty, but we can do better
than that - we've also got And</code> and Or</code> for combining them.</p>
Let's only allow whole numbers from 1</code> to 100</code>...</p>
Refined</span> ((</span>From D1</span>) </span>And</span> (</span>To D100</span>)) </span>Int
</span></code></pre>
Or indeed, allow all whole numbers EXCEPT 1</code> to 100</code>.</p>
Refined</span> ((</span>To D0</span>) </span>Or</span> (</span>From D101</span>)) </span>Int
</span></code></pre>
This type describes the roll of a dice.</p>
type </span>Dice </span>= </span>Refined</span> ((</span>From D1</span>) </span>And</span> (</span>To D6</span>)) </span>Int
</span></code></pre>
Or this one, which describes the first bunch of prime numbers, and is all a bit silly
to be honest.</p>
type </span>Prime 
</span>  = </span>Refined 
</span>      (</span>Or</span> (</span>Equal D2</span>) 
</span>        (</span>Or</span> (</span>Equal D3</span>) 
</span>          (</span>Or</span> (</span>Equal D5</span>) 
</span>            (</span>Or</span> (</span>Equal D7</span>) 
</span>              (</span>Or</span> (</span>Equal D11</span>) 
</span>                (</span>Or</span> (</span>Equal D13</span>) (</span>Equal D17</span>))
</span>              )
</span>            )
</span>          )
</span>        )
</span>      ) </span>Int
</span></code></pre>
Back to our stupid contrived problems...</h3>
Now with the power of Refined</code> types, our defensive printName</code> function is pretty much unnecessary...</p>
type </span>Name </span>= </span>Refined</span> (</span>SizeFrom 1</span>) </span>String
</span>
</span>printName </span>:: Name -> String
</span>printName name = unrefine name
</span></code></pre>
Plus we can make a type to make division safe from fear, at last..</p>
type </span>Divide </span>= </span>Refined</span> (</span>Not</span> (</span>Equal 0</span>)) </span>Number
</span>
</span>divide </span>:: Number -> Divide -> Number
</span>divide a b = a / (unrefine b)
</span></code></pre>
Automatic JSON validation</h3>
So let's say we have this data type using Refined</code>...</p>
type </span>AlcoholUser
</span>  = { name :: </span>Refined</span> (</span>SizeFrom 1</span>) </span>String
</span>    , age  :: </span>Refined</span> (</span>From 18</span>) </span>Int
</span>    }
</span></code></pre>
...if we want to use it as an API request, sounds like a lot of work right?
Maybe not! Because refined</code> instances have fromJSON</code> and toJSON</code> instances
for Aeson</code> (or for Argonaut</code> in Purescript) then we can automatically decode
them from JSON</code> and make the decoding fail if the predicate</code> does not pass.</p>
This way, anywhere in our app, name</code> will always be non-empty. and age</code> will
always be 18</code> or more.</p>
Well, shit.</h3>
Yep. For more details, check out the Refined Haskell
library</a> or indeed the
purescript-refined</a>
library which I ported from the Haskell one.</p>


A game in Purescript (Part 2 - Effect and Aff)
Unknown — Sun, 31 Mar 2019 00:00:00 +0000
Good morning and/or evening. I found myself defaulting to starting with an apology for the amount of time since my last post, then I caught myself and reminded myself that It's My Blog And I Can Post Whenever I Feel Like It Actually</em>. So with that in mind, let's continue to today's main course, at exactly the rambling pace
of my choosing.</p>
</p>
As I may have mentioned, my current timesink of choice is a Purescript re-write of a browser game I wrote a couple of years back called It Is The Egg</a>. It is going pretty OK, all told, I've gotten all the awful fiddly stuff like rendering sorted so now I am free to remake the game logic in nice pure functions and generally have a good time. For those of that don't spend their free time ignoring their loved ones and instead writing terrible games in a functional programming style, a few notes on the vague architecture that I have settled on.</p>
It falls into three parts:</p>

Admin</li>
Rendering</li>
Logic</li>
</ul>
Admin</h3>
The admin of the game is everything that needs setting up at the start. Images need loading, level files need loading, window events need setting, and we need to start a game loop that will run everything all the other parts. All of this stuff is very effectful</em> as it involves interacting with the real actual world, the thing that functional programmers are rightly terrified of. This is mostly the layer that we will be discussing today. This layer is difficult to test, so don't.</p>
Rendering</h3>
Much like in the React architecture, the Rendering layer is only concerned with receiving the current state of the game, and displaying it on the screen. We will come back to this later when we talk about working with the HTML Canvas in Purescript, and how we use buffering to keep things (vaguely) smooth. The Rendering layer only has access to a) the current game state and b) the previous game state, so that we can do a few optimisations to avoid unnecessary work. It has no way of changing the game state in any way. This layer, because of it's need to write to the canvas, is also effectful</em>, and difficult to test so try and keep it as thin as possible.</p>
Logic</h3>
The Logic layer is run every "turn" of the game and is a function that takes the current game state, any input that has been received since the last turn, and uses this to compute the next game state to pass to Rendering layer. Everything in the Logic layer is pure functions, and is very easy to test, therefore this should have lots of tests because we all good programmers who appreciate software craftsmanship. Anybody that has written Redux reducers should find this very familiar.</p>
(Anybody vaguely familiar with design patterns in Haskell might be thinking "shit, this sounds a lot like Matt Parsons' Three Layer Haskell Cake</a> pattern, this could be pretty awkward" - and yes - it is indeed pretty similar, and shamelessly so.)</p>
</p>
So today we're going to talk about the game setup part, and on the way, discover, as I did, the actual difference between Purescript's Effect</code> and Aff</code> and how to operate the two of them.</p>
Firstly, some background</h3>
Whilst any Haskell programming must start with a function such as this:</p>
main </span>:: IO </span>()
</span>main = </span>do
</span>  putStrLn "</span>Hello world!</span>"
</span></code></pre>
(The type signature IO ()</code> means "this returns a function that does some IO and returns nothing of interest")</p>
The Purescript equivalent is this, taken from the default program generated by Pulp</code>.</p>
main </span>:: Effect Unit
</span>main = </span>do
</span>  log "</span>Hello sailor!</span>"
</span></code></pre>
This program uses console.log</code> to write out a friendly message, and returns nothing of interest. The Effect</code> type is like Haskell's IO</code>, meaning "this function does something effectful</em>" and Unit</code> is the same as ()</code>, meaning "nothing", but Purescript prefers it written using words which is arguably easier to understand.</p>
There is a more subtle difference though - Haskell's IO is blocking - meaning we can write code like this, no problem:</p>
main </span>:: IO </span>()
</span>main = </span>do
</span>  putStrLn "</span>Hello, what is your name?</span>"
</span>  name <- readLine
</span>  putStrLn ("</span>Greetings, </span>" ++ name)
</span></code></pre>
When we run this program approximate this will happen:</p>
Hello,</span> what is your name?
</span>> Mr </span>Horse   </span># user input
</span>Greetings,</span> Mr Horse
</span></code></pre>
The program greets the user, ask them their name, read the response, and use that name in the reply. The type signature for readLine</code> is IO String</code>, meaning a function that does some IO and returns a String</code>. It does not specify when said string will arrive. If the user sits and waits for 100 years to type a response, the program will happily sit and do absolutely nothing else, obediently waiting for the user before continuing with the program.</p>
</p>
Purescript, however, is built on top of Javascript, and some of you may be lucky enough to remember first getting stung by the concepts of callbacks etc when first moving to writing front end code. It's equivalent function to readLine</code>, looks something like this:</p>
readLine
</span>  :: (</span>String </span>-> </span>Effect Unit</span>)
</span>  -> </span>Effect Unit
</span></code></pre>
Hopefully what should be bothering you is that this function returns Effect Unit</code> - ie, with no String</code> to be seen. What's going on? Well - the actual return is happening in the the callback function, which is the first argument - (String -> Effect Unit)</code>. This function will immediately return Effect Unit</code> but then send the String</code> to the callback whenever the user sees fit to provide on. Therefore we can write the original greeting function in this new style as thus:</p>
main </span>:: Effect Unit
</span>main = </span>do
</span>  log "</span>Hello, what is your name?</span>"
</span>  readLine (\name -> </span>do
</span>    log ("</span>Greetings, </span>" ++ name)
</span>  )
</span></code></pre>
This seems pretty OK, however if we end up asking a lot of questions, we're going to end in a classic Javascript anti-pattern, the Pyramid Of Death.</p>
bigChat </span>:: Effect Unit
</span>bigChat
</span>  = </span>do
</span>      log "</span>What is your name?</span>"
</span>      _ <- readLine
</span>        (\name -> </span>do
</span>          log "</span>What?</span>"
</span>          _ <- readLine
</span>            (\what -> </span>do
</span>              log "</span>Are those your hands?</span>"
</span>              _ <- readLine
</span>                (\hands -> </span>do
</span>                  log "</span>Have you washed them recently?</span>"
</span>                  _ <- readLine
</span>                    (\clean -> </span>do
</span>                      log "</span>I see.</span>"
</span>                  pure unit)
</span>              pure unit)
</span>          pure unit)
</span>      pure unit
</span></code></pre>
Not ideal.</p>
What has this got to do with eggs?</h3>
Sure, sure. Coming back round to our game, we have a similar problem. The game is tile based and so before we can dream of drawing anything we're going to need to load a big pile of images.</p>
</p>
As we can see in the Purescript Canvas Docs</a> we are going to need a CanvasImageSource</code> to draw a sprite onto the canvas:</p>
drawImage </span>:: Context2D -> CanvasImageSource -> Number -> Number -> Effect Unit
</span></code></pre>
How do we load one? With this tryLoadImage</code> function.</p>
tryLoadImage </span>:: String -></span> (</span>Maybe CanvasImageSource -> Effect Unit</span>) </span>-> Effect Unit
</span></code></pre>
It takes a String</code> (the path to the image), a callback function (that will be passed Maybe CanvasImageSource</code>), and then returns Effect Unit</code>. This is very similar to readLine</code>, so if we want to load lots of images we are going to end up with a weird pyramid of callbacks and generally a bad mess.</p>
Enter Aff</h3>
Aff</a> is the asynchronous effect monad for Purescript. It allows to sequence async events without using callbacks, and we're going to use it to load loads of images. First we are going to need to wrap our Effect</code> function to make an Aff</code> function.</p>
tryLoadImageAff </span>::
</span>  </span>String ->
</span>  </span>Aff CanvasImageSource
</span>tryLoadImageAff path = makeAff wrappedFn
</span>  </span>where
</span>    wrappedFn done = </span>do
</span>      tryLoadImage path (\maybeImage -> </span>case</span> maybeImage </span>of
</span>        </span>Just</span> canvasImage -> done (</span>Right</span> canvasImage))
</span>        </span>Nothing          </span>-> done (</span>Left</span> (error "</span>Could not load </span>" <> path))
</span>      )
</span>    pure mempty </span>-- return empty cancellation function
</span></code></pre>
How does this work then?</p>
Firstly, it probably helps to look at the type signature for makeAff</code>:</p>
makeAff </span>:: </span>forall a</span>. ((</span>Either Error </span>a </span>-> Effect Unit</span>) </span>-> Effect Canceler</span>) </span>-> Aff </span>a
</span></code></pre>
OK. It's a bit weird. The a</code> can be whatever item we're trying to move around, let's replace it with CanvasImageSource</code>:</p>
makeAff </span>::</span> ((</span>Either Error CanvasImageSource -> Effect Unit</span>) </span>-> Effect Canceler</span>) </span>-> Aff CanvasImageSource
</span></code></pre>
This function takes a function that returns an Effect Canceler</code>, and returns an Aff</code> function that returns a CanvasImageSource</code>. The (Either Error CanvasImageSource -> Effect Unit)</code> function will actually be passed to you, to use as the callback for the Effect</code> function you are wrapping.</p>
Let's look closer at wrappedFn</code>, with a type signature added for clarity.</p>
wrappedFn
</span>  :: (</span>Either Error CanvasImageSource </span>-> </span>Effect Unit</span>)
</span>  -> </span>Effect Canceler
</span>wrappedFn done = </span>do
</span>  tryLoadImage path (\maybeImage -> </span>case</span> maybeImage </span>of
</span>    </span>Just</span> canvasImage -> done (</span>Right</span> canvasImage))
</span>    </span>Nothing          </span>-> done (</span>Left</span> (error "</span>Could not load </span>" <> path))
</span>  )
</span>  pure mempty
</span></code></pre>
It is passed done</code> - which takes an Either</code> holding either an Error</code> for failure, or a CanvasImageSource</code> if all went well.</p>
The callback in tryLoadImage</code> gives us a Maybe</code> so we pattern match on that, add a helpful Error</code> if things go wrong, or return the CanvasImageSource</code> if it all works.</p>
Finally, it creates an Effect Canceler</code> with pure mempty</code> - which just returns a Canceler</code> that does nothing.</p>
Using our exciting new function</h3>
</p>
Now instead of using callbacks, we can use regular monad binds to get our images out.</p>
loadLots </span>:: Aff</span> (</span>Array CanvasImageSource</span>)
</span>loadLots = </span>do
</span>  file1 <- tryLoadImageAff "</span>./static/images/brick.png</span>"
</span>  file2 <- tryLoadImageAff "</span>./static/images/tile.png</span>"
</span>  file3 <- tryLoadImageAff "</span>./static/images/egg.png</span>"
</span>  pure [file1, file2, file3]
</span></code></pre>
And even better than that, if we take an array of file paths...</p>
paths </span>:: Array String
</span>paths = [ "</span>./static/images/brick.png</span>"
</span>        , "</span>./static/images/tile.png</span>"
</span>        , "</span>./static/images/egg.png</span>"
</span>        , "</span>./static/images/egg2.png</span>"
</span>        , "</span>./static/images/egg3.png</span>"
</span>        ]
</span></code></pre>
...we can use traverse to turn an array of paths into an array of CanvasImageSource</code>.</p>
loadImages </span>:: Array String -> Aff</span> (</span>Array CanvasImageSource</span>)
</span>loadImages paths
</span>  = traverse tryLoadImageAff paths
</span></code></pre>
loadImages</code> takes our list of file paths, and returns an Aff</code> containing an Array</code> of CanvasImageSource</code>. traverse</code> runs our function on each item in the array, then turns the types inside out so we can Aff (Array CanvasImageSource)</code> instead of Array (Aff CanvasImageSource)</code>.</p>
Constructing this Aff</code> doesn't do anything until we actually run it, which we can do with runAff</code>.</p>
runAff_ </span>:: </span>forall a</span>. (</span>Either Error </span>a </span>-> Effect Unit</span>) </span>-> Aff </span>a </span>-> Effect Unit
</span></code></pre>
It takes a callback, the Aff</code> we have constructed, and then returns Effect Unit</code>. Our whole image loading program would thus look like this:</p>
main </span>:: Effect Unit
</span>main = </span>do
</span>  </span>let</span> imageAff
</span>        = loadImages paths
</span>      callback
</span>        = (\images -> </span>case</span> images </span>of
</span>            </span>Left</span> a  -> log a
</span>            </span>Right</span> a -> log $ show (length a) <> "</span> images loaded!</span>"
</span>          )
</span>  runAff_ callback imageAff
</span></code></pre>
This will attempt to load the files, and then either log out the error message or the number of files loaded! Magic! Next time, we'll grab these images and print them all over the screen in an exciting manner. For now though, this is quite enough.</p>
Further reading:</p>
Graphics.Canvas</a></p>
Effect.Aff</a></p>


Typeclasses - Monad
Unknown — Mon, 18 Mar 2019 00:00:00 +0000
The Monad</code> is one of the most infamous things around Haskell, and indeed functional programming, and so writing tutorials around them has become something of a cliche. Let me be clear - I really did try and avoid writing one, but it's gotten to the point that it's difficult to talk about the other more interesting stuff without at least mentioning it.</p>
To try and avoid falling into the regular pitfalls, we are instead going to define the simplest possible Monad</code>, and then look at some examples of them in action. Hopefully you'll see that Monads</code> aren't that complicated or interesting - it's actually the properties of the different datatypes that provide all the different behaviours and make it interesting.</p>
Id</h3>
So. This is Id</code>.</p>
newtype </span>Id</span> a
</span>  = </span>Id</span> { getId :: a}
</span></code></pre>
It is a container that contains any value that we give it.</p>
val </span>:: Id Int
</span>val = </span>Id 7
</span></code></pre>
Which we can take out at any time with getId</code>.</p>
plainVal </span>:: Int
</span>plainVal = getId val
</span>-- plainVal = 7
</span></code></pre>
Every Monad</code> must first be a Functor</code>, so let's define that for Id</code>.</p>
instance Functor Id where
</span>  fmap f (</span>Id</span> a) = </span>Id</span> (f a)
</span>
</span>doubled </span>:: Id Int
</span>doubled = fmap (\*</span>2</span>) val
</span>-- doubled == Id 14
</span></code></pre>
It must also be an Applicative</code>.</p>
instance Applicative Id where
</span>  pure = </span>Id
</span>  (</span>Id</span> f) <*> (</span>Id</span> a) = </span>Id</span> (f a)
</span>
</span>idValue </span>:: Id String
</span>idValue = pure "</span>Hello!</span>"
</span>-- idValue = Id "Hello!"
</span>
</span>getLength </span>:: Id Int
</span>getLength = </span>Id</span> length <\*> </span>Id </span>"</span>Dogs</span>"
</span>-- getLength == Id 4
</span></code></pre>
Great stuff. Now we've got Functor</code> and Applicative</code>, we only need one more function to make a Monad</code> instance, and thats bind</code> (or >>=</code>). Bind</code> takes an Id a</code> value, and a function of signature (a -> Id b)</code> that takes the value inside, does something to it, and adds another layer of Id</code>. It then removes the extra layer, leaving us with Id b</code>. In some places it's called flatMap</code>, as it maps over the value and then flattens it.</p>
For Id</code>, it takes the value out, and then runs the function on it.</p>
instance Monad Id where
</span>  (</span>Id</span> m) >>= k = k m
</span></code></pre>
Pretty dull. Let's plop a few bind</code> functions together. We're using Do Notation, which is a way of making using Monad</code> values easier.</p>
doubleAndWrap </span>:: Int -> Id Int
</span>doubleAndWrap i
</span>  = pure (i \* </span>2</span>)
</span>
</span>-- doubleAndWrap 1 = Id 2
</span>
</span>doubleAFewTimes </span>:: Int -> Id Int
</span>doubleAFewTimes i = </span>do
</span>  j <- doubleAndWrap i
</span>  k <- doubleAndWrap j
</span>  l <- doubleAndWrap k
</span>  doubleAndWrap l
</span>
</span>-- doubleAFewTimes 10 = 160
</span></code></pre>
OK! Not very interesting to be honest. Id</code> doesn't really do</em> anything other than make adding numbers up more confusing. Let's look at other Monad</code> instances and try and see what they do.</p>
Maybe</h3>
We're going to use the Maybe</code> monad to chain together a head</code>-type function that returns the first item if</em> it's there.</p>
firstItem </span>::</span> [</span>a</span>] </span>-> Maybe </span>a
</span>firstItem </span>[] </span>= </span>Nothing
</span>firstItem (a:\_) = </span>Just</span> a
</span>
</span>head3 </span>::</span> [[[</span>a</span>]]] </span>-> Maybe </span>a
</span>head3 aaas = </span>do
</span>aas <- firstItem aaas
</span>as <- firstItem aas
</span>a <- firstItem as
</span>pure a
</span>
</span>-- head3 []          -- Nothing
</span>-- head3 [[[1,2,3]]] -- Just 1
</span></code></pre>
Note that as soon as we get a Nothing</code>, the calculation stops, as such.</p>
Either</h3>
We're going to use Either</code> to do some string validation. Here is our error type:</p>
data </span>Error
</span>  = </span>TooLong
</span>  | </span>ContainsHorse
</span>  | </span>IsEmpty
</span>  </span>deriving</span> (</span>Show</span>, </span>Eq</span>, </span>Ord</span>)
</span></code></pre>
And here are a series of string validation functions that all return either Right String</code> if the string is OK, or Left Error</code> if not.</p>
isEmpty </span>:: String -> Either Error String
</span>isEmpty s
</span>  = </span>if</span> null s
</span>  </span>then </span>Left IsEmpty
</span>  </span>else </span>Right</span> s
</span>
</span>tooLong </span>:: String -> Either Error String
</span>tooLong s
</span>  = </span>if</span> length s > </span>10
</span>  </span>then </span>Left TooLong
</span>  </span>else </span>Right</span> s
</span>
</span>containsHorse </span>:: String -> Either Error String
</span>containsHorse s
</span>  = </span>if </span>"</span>horse</span>" </span>`</span>isInfixOf</span>`</span> s
</span>  </span>then </span>Left ContainsHorse
</span>  </span>else </span>Right</span> s
</span></code></pre>
This validate</code> function chains all the validations, returning either the String</code> or the first Error</code>.</p>
validate </span>:: String -> Either Error String
</span>validate s = </span>do
</span>  t <- isEmpty s
</span>  u <- tooLong t
</span>  containsHorse u
</span>
</span>-- validate ""                   == Left IsEmpty
</span>-- validate "bah horse"          == Left ContainsHorse
</span>-- validate "really long string" == Left TooLong
</span>-- validate "Hello"              == Right "Hello"
</span></code></pre>
List</h3>
The List</code> monad is interesting because the flattening effect of bind</code> means functions that turn values into more lists get flattened into one big list.</p>
moreList </span>:: Int -></span> [</span>Int</span>]
</span>moreList a = [a - </span>1</span>, a, a + </span>1</span>]
</span>-- moreList 1 == [0, 1, 2]
</span>
</span>lotsMoreList </span>:: Int -></span> [</span>Int</span>]
</span>lotsMoreList a = </span>do
</span>  b <- moreList a
</span>  moreList b
</span>-- lotsMoreList 1 == [-1,0,1,0,1,2,1,2,3]
</span></code></pre>
Reader</h3>
The Reader</code> monad is used to pass configuration around a program. Here we will define a type for Config</code> and a value for it.</p>
data </span>Config
</span>  = </span>Config</span> { ipAddress :: </span>String
</span>           , name :: </span>String
</span>           }
</span>
</span>config </span>:: Config
</span>config = </span>Config</span> { ipAddress = "</span>127.0.0.1</span>"
</span>                , name = "</span>localhost</span>"
</span>                }
</span></code></pre>
These functions use the Config</code> value in the Reader</code> to make strings, using the ask</code> function to access the config.</p>
printName </span>:: Reader Config String
</span>printName = </span>do
</span>  config <- ask
</span>  pure ("</span>the name is </span>" <> name config)
</span>
</span>printIp </span>:: Reader Config String
</span>printIp = </span>do
</span>  config <- ask
</span>  pure ("</span>The ip address is </span>" <> ipAddress config)
</span></code></pre>
The configReader</code> function shows how we can combine different Reader</code> instances with bind</code></p>
configReader </span>:: Reader Config String
</span>configReader = </span>do
</span>  ip <- printIp
</span>  name <- printName
</span>  pure (ip <> "</span>, </span>" <> name)
</span>
</span>withConfig </span>:: String
</span>withConfig = runReader configReader config
</span>-- withConfig == "The ip address is 127.0.0.1, the name is localhost"
</span></code></pre>
Writer</h3>
The Writer</code> monad accumulates a log as it does computations, by using the tell</code> function to add items.</p>
addOne </span>:: Int -> Writer String Int
</span>addOne i = </span>do
</span>  tell "</span>Add one </span>"
</span>  pure (i + </span>1</span>)
</span>
</span>timesTwo </span>:: Int -> Writer String Int
</span>timesTwo i = </span>do
</span>  tell "</span>times two </span>"
</span>  pure (i \* </span>2</span>)
</span>
</span>maths </span>:: Int -> Writer String Int
</span>maths i = </span>do
</span>  j <- addOne i
</span>  k <- timesTwo j
</span>  pure k
</span>-- runWriter maths 10 == (22, "Add one times two")
</span></code></pre>
IO</h3>
The IO</code> monad is a very interesting one. Each time we run bind</code>, the value that comes out can be affected by stuff like user input, system time, or other side effects. This is how we can write effectful code in a relatively safe manner. This is how we write code like this that actually interacts with users.</p>
things </span>:: IO Unit
</span>things = </span>do
</span>  \_ <- putStrLn "</span>Hello! What is your name?</span>"
</span>  name <- readLn
</span>  putStrLn ("</span>Hello, </span>" ++ name)
</span></code></pre>
That is all. I feel this somewhat rushes things a lot, and there is a lot to chew on, but hopefully these examples will help you build up an intuition for how these work.</p>
Further Reading:</p>
You've Been Using Monads</a></p>
Lots More Of This Kind Of Thing</a></p>


Datatypes - Either
Unknown — Sun, 17 Mar 2019 00:00:00 +0000
It's one thing to understand typeclasses individually, but another to see them in context. This is the second in a series looking at some common datatypes and see how their instances of the main typeclasses act. We started with one of the simplest, Maybe</code>, and now we move onto it's slightly more powerful cousin Either</code>.</p>
One thing or the other thing</h3>
Here is the data definition for Either</code>. We have used deriving</code> to auto-generate instances of the Eq</code>, Ord</code> and Show</code> typeclasses as we don't need anything special going on with them.</p>
data </span>Either</span> a b
</span>  = </span>Left</span> a
</span>  | </span>Right</span> b
</span>  </span>deriving</span> (</span>Eq</span>, </span>Ord</span>, </span>Show</span>)
</span></code></pre>
Whilst Maybe</code> only had one type parameter, a</code>, Either</code> has both a</code> and b</code>. If we use the Left</code> constructor, it holds an a</code>, or the Right</code> constructor holds a b</code>.</p>
Here, we are returning either a Left String</code> with some harsh words, or a Right Int</code> with a nice answer to an easy sum.</p>
incrementOrTellMeOff </span>:: Int -> Either String Int
</span>incrementOrTellMeOff i
</span>  = </span>if</span> i == </span>6
</span>    </span>then</span> (</span>Left </span>"</span>I hate the number six, why have you done this?</span>")
</span>    </span>else</span> (</span>Right</span> (i + </span>1</span>))
</span>
</span>incrementOrTellMeOff </span>1 </span>-- Right 2
</span>incrementOrTellMeOff </span>6 </span>-- Left "I hate the number six, why have you done this?"
</span></code></pre>
Functor</h3>
Next we'll define a functor</code> instance for Either</code>. The important intuition here is that the function f</code> that is provided will only be run on a value inside Right</code>. Anything held in a Left</code> will be returned untouched.</p>
instance Functor</span> (</span>Either </span>a</span>) </span>where
</span>  fmap f (</span>Right</span> b) = </span>Right</span> (f b) </span>-- run the function over Right
</span>  fmap _ (</span>Left</span> a)  = </span>Left</span> a      </span>-- ignore the function for Left
</span>
</span>fmap (+</span>1</span>) (</span>Right 1</span>) </span>-- Right 2
</span>fmap (+</span>1</span>) (</span>Left 1</span>)  </span>-- Left 1
</span></code></pre>
The Functor</code> typeclass is only allowed to affect one type parameter, so anything held in a Left</code> will be returned untouched, so if we want to run functions over that, we'll need...</p>
Bifunctor</h3>
This instance allows us to map over the left, right or indeed both sides of a datatype. We define it with the bimap</code> function which takes a function for each side.</p>
instance Bifunctor Either where
</span>  bimap f _ (</span>Left</span> a)  = </span>Left</span> (f a)
</span>  bimap _ g (</span>Right</span> b) = </span>Right</span> (g b)
</span>
</span>bimap (+</span>1</span>) (+</span>100</span>) (</span>Left 1</span>)   </span>-- Left 2
</span>bimap (+</span>1000</span>) (+</span>1</span>) (</span>Right 1</span>) </span>-- Right 2
</span>first (+</span>1</span>) (</span>Right 1</span>)         </span>-- Right 1
</span>first (+</span>1</span>) (</span>Left 1</span>)          </span>-- Left 2
</span>second (+</span>1</span>) (</span>Left 1</span>)         </span>-- Left 1
</span></code></pre>
Just defining bimap</code> also means we get the first</code> function which just maps over the Left</code> side, and the second</code> function which just maps over the Right</code> (so it's basically fmap</code> with another name).</p>
Applicative</h3>
The applicative</code> instance for Either</code> has two functions, pure</code> and <*></code> (also called ap</code>). We use pure</code> to define a default instance of the datatype, so we just take the value and wrap it in Right</code>. The <*></code> function is used to apply a function inside a Right</code> to a value wrapped in another Right</code>. However, if we hit a Left</code> we return the first one immediately and stop computing.</p>
instance Applicative</span> (</span>Either </span>a</span>) </span>where
</span>  pure a = </span>Right</span> a
</span>  (</span>Right</span> f) <*> (</span>Right</span> a) = </span>Right</span> (f a)
</span>  (</span>Right</span> f) <*> (</span>Left</span> a)  = </span>Left</span> a
</span>  (</span>Left</span> a)  <*> \_        = </span>Left</span> a
</span>
</span>Right</span> (+</span>1</span>) <*> </span>Right 1 </span>-- Right 2
</span>Right</span> (+</span>1</span>) <*> </span>Left 1  </span>-- Left 1
</span>Left 10    </span><*> </span>Right 1 </span>-- Left 10
</span>Left 2     </span><*> </span>Left 3  </span>-- Left 2
</span></code></pre>
Sometimes, this behaviour is not what we want as we might want to collect together all of the Left</code> values rather than just the first one found. For this there is a variation on Either</code> called Validation</code>, which we'll look at in future.</p>
Monad</h3>
The monad</code> instance for Either</code> provides us with >>=</code> (or bind</code>). The behaviour is much like the Applicative</code> above or indeed the Monad</code> instance for Maybe</code> - as soon as an error is found (ie, a Left</code>) we return that error value and shortcircuit the computation, as such.</p>
instance Monad</span> (</span>Either </span>a</span>) </span>where
</span>  </span>Right</span> a >>= k = k a
</span>  </span>Left</span> e >>= \_ = </span>Left</span> e
</span>
</span>Right 10 </span>>>= \a -> </span>Right</span> (a + </span>1</span>))      </span>-- Right 11
</span>Left </span>"</span>oh no</span>" >>= \a -> </span>Right</span> (a + </span>1</span>))  </span>-- Left "oh no"
</span></code></pre>
Semigroup</h3>
This semigroup</code> instance for Either</code> differs from the standard one in Data.Either</code> as, like our Semigroup</code> instance for Maybe</code> it has a constraint allowing us to combine Semigroup</code> values inside. I like this better, having nested Semigroup</code> values all magically combining is very enjoyable to my mind.</p>
instance</span> (</span>Semigroup </span>a</span>) </span>=> Semigroup</span> (</span>Either </span>e a</span>) </span>where
</span>  (</span>Right</span> a) <> (</span>Right</span> b) = </span>Right</span> (a <> b)
</span>  (</span>Left</span> a)  <> (</span>Left</span> b)  = </span>Left</span> a
</span>  (</span>Left</span> a)  <> b         = b
</span>  a         <> (</span>Left</span> b)  = a
</span>
</span>Right</span> [</span>1</span>,</span>2</span>,</span>3</span>] <> </span>Right</span> [</span>4</span>,</span>5</span>,</span>6</span>] </span>-- Right [1,2,3,4,5,6]
</span>Right</span> [</span>1</span>,</span>2</span>,</span>3</span>] <> </span>Left 1        </span>-- Right [1,2,3]
</span>Left 1 </span><> </span>Right</span> [</span>4</span>,</span>5</span>,</span>6</span>]        </span>-- Right [4,5,6]
</span>Left 1 </span><> </span>Left 2               </span>-- Left 1
</span></code></pre>
Monoid</h3>
Sadly, because Either</code> has two type parameters rather than Maybe</code>'s one, we can't have a Monoid</code> instance as we won't know which value to put in Left</code> to represent nothingness. Oh well.</p>
Foldable</h3>
If we'd like to extract our value out of this Either</code> context at some point we can use foldable</code>. Note that we still provide a default a</code> in the Left</code> version of the function - the Left</code> values might be a different type to the Right</code> ones so there's no guarantee they'll be helpful in our fold, hence we still provide a default value.</p>
instance Foldable</span> (</span>Either </span>e</span>) </span>where
</span>  foldr \_ a (</span>Left</span> e) = a
</span>  foldr f a (</span>Right</span> b) = f b a
</span>
</span>foldr </span>(+) </span>1</span> (</span>Left 10</span>)  </span>-- 1
</span>foldr </span>(+) </span>1</span> (</span>Right 10</span>) </span>-- 11
</span></code></pre>
Alternative</h3>
For the same reasons that defining mempty</code> is impossible for Monoid</code>, we can't define Alternative</code> for Either</code> because it's just too messy. I'm sorry.</p>
MonadPlus</h3>
As I'm sure we all remember, MonadPlus</code> is just Alternative</code> with a more dynamic sounding name, so we don't get this one either.</p>
Traversable</h3>
The traversable</code> instance for Either</code> is very similar to Maybe</code>. If traverse</code> is run on a Left</code> it wraps said Left</code> and it's value inside whichever Applicative</code> it is used with (the pure</code> function coming from the other type rather than from Either</code>). If we traverse</code> a Right</code> value then the provided function f</code> is run on the Right</code> values the same way in which they worked on Just</code>. Note if we have several Left</code> values, the shortcircuiting behaviour means we only get the first one back, shown here by using the sequence</code> function (which is just traverse id</code>, fact fans).</p>
instance Traversable</span> (</span>Either </span>e</span>) </span>where
</span>  traverse \_ (</span>Left</span> e) = pure (</span>Left</span> e)
</span>  traverse f (</span>Right</span> a) = fmap </span>Right</span> (f a)
</span>
</span>sequence [</span>Right 1</span>, </span>Right 2</span>] </span>-- Right [1,2]
</span>sequence [</span>Left 1</span>, </span>Right 1</span>]  </span>-- Left 1
</span></code></pre>
If you are ever trying to turn a List</code> of Maybe</code> values into a Maybe List</code>, or indeed turn any pair of Applicatives</code> inside out, then sequence</code> is probably what you are looking for. It's magic, honestly.</p>
MonadFail</h3>
It turns out MonadFail</code> is quite fussy about things, and so because the e</code> in Either e a</code> can be a String</code>, but might not be, we can't define it. What a pain in the arse, all told.</p>
Right, right, right, right.</h3>
Anyway, that's some things. Tldr; Either</code> isn't too dissimilar to Maybe</code> when everything is going well, and a bit different when errors start happening. Also, Either</code> has way less instances than I thought, which was somewhat a relief I have to admit. I can't decide whether to do List</code> or something jazzier like Reader</code> next, but it'll be something like that. Please note these aren't the same definitions as you'll find in the Haskell Prelude, as I have tried to write them with an emphasis on clarity/simplicity (or indeed go completely off-piste with Semigroup</code>.) By all means check out the originals on Hackage</a>.</p>
If having skim-read this post you find yourself with strong feelings about it (positive or otherwise) I'd appreciate you shouting them at my face via the usual channels</a>. It's lonely down here in the soupy bottom of this old council bin.</p>
That's all.</p>
Further reading:</p>
Data.Either</a></p>


Typeclasses - Profunctor
Unknown — Tue, 12 Mar 2019 00:00:00 +0000
Hello. Let's make a box for putting functions in...</p>
newtype </span>FuncBox</span> b c
</span>  = </span>FuncBox</span> { runFuncBox :: b -> c }
</span></code></pre>
...and a function...</p>
length </span>:: String -> Int
</span>length s = foldl' (\c _ -> c+</span>1</span>) </span>0</span> s
</span></code></pre>
...and then let's put a function in this box:</p>
length' </span>:: FuncBox String Int
</span>length' = </span>FuncBox</span> length
</span></code></pre>
Great. A function in a box. You may be concerned that something interesting is going on here, so just to assure you that it's not, let's run the function using runFuncBox</code>, to reassure ourselves that this box is doing no funny business and we're really just unwrapping that newtype</code>.</p>
length'' </span>:: Int
</span>length'' = runFuncBox length' "</span>dog</span>"
</span>-- length'' == 3
</span></code></pre>
OK. Good stuff. We now have a very longwinded way of running the length</code> function. Good stuff. Big day.</p>
</p>
The plot thickens</h3>
Now what if want to run this weird function, but instead of having a String</code> to hand, we only have an Animal</code>...</p>
data </span>Animal </span>= </span>Horse </span>| </span>Dog </span>| </span>Cat
</span>  </span>deriving</span> (</span>Show</span>)
</span></code></pre>
I can see you there. You're getting excited and jumping straight for our old pal Contravariant</a> aren't you. But wait! That's not an entirely terrible decision but it turns out there are other problems that we must also solve.</p>
Oh no</h3>
That's right. Heartbreaking, it also turns out that our somewhat contrived API can output numbers, but instead only lists full of a delicous datatype called Egg</code>.</p>
data </span>Egg </span>= </span>Egg
</span></code></pre>
We can turn any Int</code> into an [Egg]</code> using this excellent function.</p>
repeatEgg </span>:: Int -></span> [</span>Egg</span>]
</span>repeatEgg s
</span>  = replicate s </span>Egg
</span>
</span>threeEggs </span>:: List Egg
</span>threeEggs = repeatEgg </span>3
</span>-- threeEggs == [Egg, Egg, Egg]
</span></code></pre>
OK. So somehow we need to turn an Animal</code> into a List</code> of Egg</code>. We could contramap</code> over our input to turn Animal</code> into String</code>, run the original length</code> function, and then fmap</code> over the result to turn Int</code> into [Egg]</code>. That could work. But what if we could solve this problem using a typeclass, that would be pretty fucking snazzy wouldn't it?</p>
Hold on, he's only gone and done it</h3>
Looks like a job for our new friend Profunctor</code> I reckon. Let's have a wee look in ghci</code> and see what what the hell it's deal is.</p>
import</span> Data.Profunctor
</span>Data.Profunctor</span>> :i Profunctor
</span></code></pre>
class </span>Profunctor</span> (</span>p</span> :: _ -> _ -> \*) </span>where
</span>    </span>dimap </span>::</span> (</span>a </span>-> </span>b</span>) </span>-></span> (</span>c </span>-> </span>d</span>) </span>-> </span>p b c </span>-> </span>p a d
</span>    </span>lmap </span>::</span> (</span>a </span>-> </span>b</span>) </span>-> </span>p b c </span>-> </span>p a c
</span>    </span>rmap </span>::</span> (</span>b </span>-> </span>c</span>) </span>-> </span>p a b </span>-> </span>p a c
</span>    {-# </span>MINIMAL</span> dimap | lmap, rmap #-}
</span></code></pre>
Look at that! It gives a Contravariant</code> with the lmap</code> function, and a regular Functor</code> with rmap</code>, or everything smashed together in this new exciting dimap</code> function. Let's look at that a little closer.</p>
dimap </span>::</span> (</span>a </span>-> </span>b</span>) </span>-></span> (</span>c </span>-> </span>d</span>) </span>-> </span>p b c </span>-> </span>p a d
</span></code></pre>
That's pretty beastly, let's put in some real concrete things.</p>
dimap
</span>  :: (</span>Animal </span>-> </span>String</span>)   </span>-- function to go at the start
</span>  -> (</span>Int </span>-> [</span>Egg</span>])       </span>-- function to go at the end
</span>  -> </span>FuncBox String Int   </span>-- original container
</span>  -> </span>FuncBox Animal</span> [</span>Egg</span>] </span>-- exciting new container
</span></code></pre>
OK. Let's implement it for our FuncBox</code>.</p>
Instances, binstances, dinstances</h3>
import </span>Data.Profunctor
</span>
</span>instance Profunctor FuncBox where
</span>  dimap before after (</span>FuncBox</span> f)
</span>    = </span>FuncBox</span> (after . f . before)
</span></code></pre>
That's all really. The .</code> is function composition, so therefore our function unwraps the original function and calls it f</code>, then returns a new FuncBox</code> which runs the before</code> function (ie, the a -> b</code> one), then the original f</code> function, and finally the after</code> function (c -> d</code>). The resulting FuncBox</code> can be used exactly as before, and nobody using it knows how secretly clever it is.</p>
Let's use it to make our all important function for turning an Animal</code> in to a [Egg]</code>, using our length'</code> and repeatEgg</code> functions from earlier.</p>
dimapped </span>:: FuncBox Animal</span> [</span>Egg</span>]
</span>dimapped
</span>= dimap show repeatEgg length'
</span></code></pre>
This gives us a new FuncBox</code> that turns Animal</code> into [Egg]</code>, but of course we all know that underneath the hood this function it's converting Animal -> String -> Int -> [Egg]</code>. Let's see it in action:</p>
test </span>::</span> [</span>Egg</span>]
</span>test = runFuncBox dimapped </span>Dog
</span>-- test == [Egg, Egg, Egg]
</span>
</span>test2 </span>:: Int
</span>test2 = runFuncBox dimapped </span>Horse
</span>-- test2 == [Egg, Egg, Egg, Egg, Egg]
</span></code></pre>
Brilliant. What an absolutely useful non-waste-of-time. OK. So these are stupid examples, but hopefully they give you a rough idea what a Profunctor</code> is under the hood. You often hear of their use in Lenses, as using dimap</code> on a function for changing two small things can make it into a function that changes a small thing inside a much bigger thing, and they compose in the same nice way.</p>
Good stuff.</p>
Feel free to shout your brains about how stupid and wrong I am via the usual channels</a>.</p>
Further reading:</p>
Easier lenses</a></p>
Data.Profunctor</a></p>


Datatypes - Maybe
Unknown — Sun, 17 Feb 2019 00:00:00 +0000
It's one thing to understand typeclasses individually, but another to see them in context. This is the first in a series where we'll look at some common datatypes and see how their instances of the main typeclasses act. We're starting with one of the simplest, Maybe</code>, and I hope this will help you get a feel for the way it acts. The plan is to move onto Either</code>, List</code> and then Reader</code>, Writer</code> and State</code>.</p>
It Really Meant Nothing, Frank</h3>
Let's start with a definition. We have used deriving</code> to auto-generate instances of the Eq</code>, Ord</code> and Show</code> typeclasses as we don't need anything special going on with them.</p>
data </span>Maybe</span> a = </span>Just</span> a | </span>Nothing
</span>  </span>deriving</span> (</span>Eq</span>, </span>Ord</span>, </span>Show</span>)
</span></code></pre>
As is hopefully apparently, Maybe</code> can either be a Just</code> with an a</code> wrapped inside, or Nothing</code> which holds no value.</p>
noNinePlease </span>:: Int -> Maybe Int
</span>noNinePlease i
</span>  = </span>if</span> i == </span>9
</span>    </span>then </span>Nothing
</span>    </span>else </span>Just</span> i
</span>
</span>noNinePlease </span>8 </span>-- Just 8
</span>noNinePlease </span>9 </span>-- Nothing
</span></code></pre>
Functor</h3>
Next we'll define a functor</code> instance for Maybe</code>. Essentially, if there is a value inside, let's run the provided function over it, and if not, return the same Nothing</code>.</p>
instance Functor Maybe where
</span>  fmap f (</span>Just</span> a) = </span>Just</span> (f a)
</span>  fmap _ </span>Nothing  </span>= </span>Nothing
</span>
</span>fmap (+</span>1</span>) (</span>Just 1</span>) </span>-- Just 2
</span>fmap (+</span>1</span>) </span>Nothing  </span>-- Nothing
</span></code></pre>
Applicative</h3>
The applicative</code> instance for Maybe</code> has two functions, pure</code> and <*></code> (also called ap</code>). We use pure</code> to define a default instance of the datatype, so we just take the value and wrap it in Just</code>. The <*></code> function is used to apply a function inside a Just</code> to a value wrapped in another Just</code>. Therefore, if either of those are a Nothing</code>, that's not going to work, so we return Nothing</code>.</p>
instance Applicative Maybe where
</span>  pure a = </span>Just</span> a
</span>  (</span>Just</span> f) <*> (</span>Just</span> a) = </span>Just</span> (f a)
</span>  _        <*> _        = </span>Nothing
</span>
</span>pure </span>1                </span>-- Just 1
</span>Just</span> (+</span>1</span>) <*> </span>Just 1  </span>-- Just 2
</span>Just</span> (+</span>1</span>) <*> </span>Nothing </span>-- Nothing
</span></code></pre>
Monad</h3>
The monad</code> instance for Maybe</code> has only one additional function, >>=</code> (or bind</code>). The most important thing in the Maybe</code> case is that if we start with a Nothing</code>, then we don't bother doing anything, allowing the computation to be shortcircuited, as such.</p>
instance Monad Maybe where
</span>  (</span>Just</span> a) >>= k   = k a
</span>  </span>Nothing  </span>>>= _   = </span>Nothing
</span>
</span>Just 1 </span>>>= (\a -> </span>Just</span> (a + </span>1</span>))  </span>-- Just 2
</span>Nothing </span>>>= (\a -> </span>Just</span> (a + </span>1</span>)) </span>-- Nothing
</span></code></pre>
Semigroup</h3>
The semigroup</code> instance for Maybe</code> is used to combine multiple Maybe</code> values together. An important thing to note is the constraint Semigroup a</code> - this means that for two Maybe</code> values to be combined, the values inside must also have a semigroup</code> instance, allowing them to be combined as well.</p>
instance</span> (</span>Semigroup </span>a</span>) </span>=> Semigroup</span> (</span>Maybe </span>a</span>) </span>where
</span>  (</span>Just</span> a) <> (</span>Just</span> b) = </span>Just</span> (a <> b)
</span>  </span>Nothing  </span><> a        = a
</span>  a        <> </span>Nothing  </span>= a
</span>
</span>Just</span> [</span>1</span>,</span>2</span>,</span>3</span>] <> </span>Just</span> [</span>4</span>,</span>5</span>,</span>6</span>] </span>-- Just [1,2,3,4,5,6]
</span>Nothing </span><> </span>Just</span> [</span>1</span>,</span>2</span>,</span>3</span>]      </span>-- Just [1,2,3]
</span>Just</span> [</span>1</span>,</span>2</span>,</span>3</span>] <> </span>Nothing      </span>-- Just [1,2,3]
</span>Nothing </span><> </span>Nothing           </span>-- Nothing
</span></code></pre>
Monoid</h3>
Notice that when a Just</code> is combined with a Nothing</code>, we still get a Just</code> value. This is because Nothing</code> is our empty</code> element, meaning that when it is combined to any value it does not change it. Defining this upgrades our semigroup</code> instance into an exciting Monoid</code>.</p>
instance</span> (</span>Semigroup </span>a</span>) </span>=> Monoid</span> (</span>Maybe </span>a</span>) </span>where
</span>  mempty = </span>Nothing
</span>
</span>mempty </span>-- Nothing
</span></code></pre>
Foldable</h3>
Now carrying all these wrapped values around is great, but at some point we may want to extract values from these Maybe</code> values, so we use foldable</code>. Note the a</code> in the Nothing</code> version of the function - this makes the user of the typeclass provide a default value so that we don't end up without a value for Nothing</code>.</p>
instance Foldable Maybe where
</span>  foldr _ a </span>Nothing  </span>= a
</span>  foldr f a (</span>Just</span> b) = f b a
</span>
</span>foldr </span>(+) </span>1 Nothing   </span>-- 1
</span>foldr </span>(+) </span>1</span> (</span>Just 10</span>) </span>-- 11
</span></code></pre>
Alternative</h3>
A good intuition for the Alternative</code> typeclass is that it's a like the or</code> operator ||</code>. Therefore it can be used to return the first out of a list of values that is wrapped in Just</code>.</p>
instance Alternative Maybe where
</span>  empty                 = </span>Nothing
</span>  (</span>Just</span> a) <|> _        = </span>Just</span> a
</span>  </span>Nothing  </span><|> (</span>Just</span> b) = </span>Just</span> b
</span>  </span>Nothing  </span><|> </span>Nothing  </span>= </span>Nothing
</span>
</span>Nothing </span><|> </span>Nothing </span>-- Nothing
</span>Just 1 </span><|> </span>Just 2   </span>-- Just 1
</span>Nothing </span><|> </span>Just 2  </span>-- Just 2
</span></code></pre>
MonadPlus</h3>
Since we're on a roll with defining typeclasses, let's plop in a quick instance of MonadPlus</code>, which is basically Alternative</code> with a different name, with mzero</code> replacing empty</code> and mplus</code> replacing <|></code>.</p>
instance MonadPlus Maybe where
</span>  mzero = </span>Nothing
</span>
</span>  mplus (</span>Just</span> a) _ = </span>Just</span> a
</span>  mplus (</span>Nothing</span>) (</span>Just</span> b) = </span>Just</span> b
</span>  mplus _ _ = </span>Nothing
</span>
</span>
</span>Nothing </span>`</span>mplus</span>` </span>Nothing </span>-- Nothing
</span>Just 1 </span>`</span>mplus</span>` </span>Nothing  </span>-- Just 1
</span>Nothing </span>`</span>mplus</span>` </span>Just 2  </span>-- Just 2
</span>mzero                   </span>-- Nothing
</span></code></pre>
Traversable</h3>
The traversable</code> instance for Maybe</code> isn't too unusual, if traverse</code> is run on a Nothing</code> it wraps a Nothing</code> inside whichever Applicative</code> it is used with (the pure</code> function coming from the other type rather than from Maybe</code>). If we traverse</code> a Just</code> value then the provided function f</code> is run on the value inside Just</code> which wraps the a</code> in an applicative</code> functor, and we then use fmap</code> to make the value inside a Just</code>.</p>
instance Traversable Maybe where
</span>  traverse _ </span>Nothing  </span>= pure </span>Nothing
</span>  traverse f (</span>Just</span> a) = fmap </span>Just</span> (f a)
</span>
</span>traverse (\a -> [a,a]) </span>Nothing   </span>-- [Nothing]
</span>traverse (\a -> [a,a]) (</span>Just 10</span>) </span>-- [Just 10, Just 10]
</span></code></pre>
MonadFail</h3>
The MonadFail</code> typeclass hasn't come up before, but it's a very generic way of allowing all computations to fail in a similar way. The fail</code> function has the type signature String -> m a</code>. However because we cannot carry around any values inside Nothing</code> we simply discard the String</code> and return Nothing</code>. The usefulness of this typeclass will become much more apparent with Either</code> and monad transformer stacks. (what? - we'll come to it...)</p>
instance MonadFail Maybe where
</span>  fail _ = </span>Nothing
</span>
</span>Just </span>"</span>yes</span>" >>= fail </span>-- Nothing
</span></code></pre>
Just "a great job"</h3>
Anyway. This is quite a laborious post but I hope it is somewhat helpful. I intend to do similar ones for Either</code> and List</code> next. Please note these aren't the same definitions as you'll find in the Haskell Prelude, as I have tried to write them with an emphasis on clarity/simplicity. If you are a purist, or just bloody hate clarity, by all means check out the originals on Hackage</a>.</p>
If having skim-read this post you find yourself with strong feelings about it (positive or otherwise) I'd appreciate you shouting them at my face via the usual channels</a>. It's lonely out here in the bleak abyss of South East London.</p>
That's all.</p>
Further reading:</p>
Data.Maybe</a></p>


A game in Purescript (Part 1 - Semigroups)
Unknown — Sun, 17 Feb 2019 00:00:00 +0000
Hello! I hope you are well. It has been a little while between posts as I keep starting things and then not finishing them.</p>
My most recent distraction has been remaking a game that I wrote a year or two back called It Is The Egg</a>, which is an HTML canvas game where eggs roll around and generally have a nice time. I wanted to add more levels and features but I have no strong desire to write Typescript in my free time, so I have made the somewhat foolish and time-sucking decision to port it over to Purescript.</p>
</p>
So far I've learned a few things, listed thus:</p>

Rewriting an entire game takes a while actually.</li>
Using Purescript means about 30% of the LOC it took in Typescript</li>
A lot of the problems have already been solved by other people</li>
Abstractions are helpful</li>
</ol>
Anyhow, I figured concrete useful examples are the most difficult thing to find when explaining functional programming, and since I stumbled across a few in this process I figured I'd share some. Today I'm going to example how to describe positions and movement using a semigroup</code>.</p>
Meaningless? Possibly! Perhaps some examples...</p>
So we have a Player</code> type - it describes one of the eggs onscreen. The eggs have a position</code> onscreen, and a direction</code> that they are currently moving in.</p>
type </span>Player
</span>  = { position  :: </span>Coord
</span>    , direction :: </span>Coord
</span>    }
</span></code></pre>
This is the Coord</code> type. The eagle-eyed might notice it's a newtype</code> rather than a type</code> - the reason for this will be explained shortly.</p>
newtype </span>Coord </span>= </span>Coord
</span>    { x       :: </span>Int
</span>    , y       :: </span>Int
</span>    , offsetX :: </span>Int
</span>    , offsetY :: </span>Int
</span>    }
</span></code></pre>
The game board is a grid, so position</code> is a Coord</code> where x</code> and y</code> describe the current square the Player</code> is in, and any movement away from the center is described by offsetX</code> and offsetY</code>. Once a players position</code> offset goes over a certain boundary, we increase or decrease x</code> or y</code> and set offsetX</code> or offsetY</code> back to zero.</p>
The position</code> for the pink egg in the above screenshot would look something like this:</p>
position </span>:: Coord
</span>position
</span>  = </span>Coord</span> { x:       </span>3
</span>          , y:       </span>2
</span>          , offsetX: </span>0
</span>          , offsetY: </span>32
</span>          }
</span></code></pre>
The direction</code> is also a Coord</code>, where we use x</code> and y</code> to express which direction the player is headed. Our pink egg above is falling downwards, which would look like this:</p>
falling </span>:: Coord
</span>falling
</span>  = </span>Coord</span> { x: </span>0
</span>          , y: </span>1
</span>          , offsetX: </span>0
</span>          , offsetY: </span>0
</span>          }
</span></code></pre>
The offsetX</code> and offsetY</code> don't really have much use in this context, but that's fine.</p>
So what's the use in expressing two slightly different things in the same data type and also what about that newtype</code> and why have we not mentioned semigroup</code> yet?</p>
An abridged version of each game turn goes as follows.</p>

Look around to see if we are still able to move in direction we want to</li>
If not, change direction</li>
Move the player in whichever direction we're now decided on</li>
</ol>
Looking around the board</h3>
OK. So firstly we need to check around the board to see if we are allowed to carry on moving where we are moving. Without going into the whole mechanics of the game board, let's say we have a function that tells us whether a certain Coord</code> on the board is a place we are allowed to go.</p>
canMove </span>:: Coord -> Boolean
</span></code></pre>
What this function does is none of our business at this point - all we need to know is whether the square we intend to move into is happy with our decision to do so.</p>
My first implementation followed the original logic and looked something like this:</p>
canIMoveNext </span>:: Player -> Boolean
</span>canIMoveNext player@{ position: </span>Coord</span> pos, direction: </span>Coord</span> dir }
</span>  | dir.x < </span>0 </span>= canMove ( </span>Coord </span>$ pos { x = pos.x - </span>1</span> } )
</span>  | dir.x > </span>0 </span>= canMove ( </span>Coord </span>$ pos { x = pos.x + </span>1</span> } )
</span>  | dir.y < </span>0 </span>= canMove ( </span>Coord </span>$ pos { y = pos.y - </span>1</span> } )
</span>  | dir.y > </span>0 </span>= canMove ( </span>Coord </span>$ pos { y = pos.y + </span>1</span> } )
</span>  | otherwise       = true
</span></code></pre>
"If we are moving left then look to the current square but with x reduced once but if we're looking right then look to the current square but with x increased but if we're looking up....".</p>
Quite a laborious thing to read really, and it says nothing of it's intentions.</p>
(If you are not familiar with guard</code> syntax, think of this as very similar to select case</code> statement in Javascript.)</p>
Stand back, I am going to use Maths.</h3>
OK, so we made that Coord</code> a newtype</code> for a reason right? Let's add some typeclass instances to it and get it working for us for a change.</p>
First we must please the gods of boilerplate by deriving some standard instances of Eq</code>, Ord</code> and Show</code>. Purescript needs this to be a little more explicit that Haskell does, sadly.</p>
derive </span>newtype instance </span>eqCoord</span> :: </span>Eq Coord
</span>derive </span>newtype instance </span>ordCoord</span> :: </span>Ord Coord
</span>derive </span>newtype instance </span>showCoord</span> :: </span>Show Coord
</span></code></pre>
derive newtype instance</code> means "You know how you're a newtype</code> wrapped around something, can you just copy whatever the thing inside does? Ace, thanks."</p>
This means we can now compare and order things, which is helpful although not the main point here.</p>
Let's define a semigroup</code>!</p>
instance </span>semigroupCoord</span> :: </span>Semigroup Coord where
</span>  append (</span>Coord</span> fst) (</span>Coord</span> snd)
</span>    = </span>Coord</span> { x: fst.x + snd.x
</span>            , y: fst.y + snd.y
</span>            , offsetX: fst.offsetX + snd.offsetX
</span>            , offsetY: fst.offsetY + snd.offsetY
</span>            }
</span></code></pre>
(Notice that unlike Haskell, Purescript likes us to give our instances names, hence we have chosen the olympically dull semigroupCoord</code>. It could be pintsOfCream</code> or indepedenceDayIsPrettyUnderatedAsFarAsBlockbustersGo</code>, go absolutely wild if you like.)</p>
So what does this append</code> function we have defined do then?</p>
It takes two Coord</code> values (fst</code> and snd</code> in this case) - adds up x</code>, y</code>, offsetX</code> and offsetY</code> - then makes and returns a new Coord</code>. Therefore we can do stuff like add a position</code> and a direction</code> together.</p>
In the above example of our pink egg, and our position</code> and falling</code> values defined above, we can check whether we're OK to keep falling downwards as such.</p>
canIMoveDown </span>:: Boolean
</span>canIMoveDown = canMove (position <> falling)
</span>-- canIMoveDown == true (according to the picture)
</span></code></pre>
(Note we're using <></code> which is another name for the append</code> function, we could just as easily have written canMove (append position falling)</code> but I think the little <></code> looks nicer.)</p>
Looking around the board with Maths</h3>
Back to our implementation of canIMoveNext</code>, here is the new version that combines our player's direction</code> and position</code> in a nice tidy way.</p>
canIMoveTwo </span>:: Player -> Boolean
</span>canIMoveTwo player
</span>  = canMove (player.position <> player.direction)
</span></code></pre>
Nice.</p>
Changing direction</h3>
What if our egg hits a wall or something? What should we do then? It should be as easy as reversing the direction</code>, right?</p>
invert </span>:: Coord -> Coord
</span>invert (</span>Coord</span> coord)
</span>  = </span>Coord</span> { x: (-</span>1</span>) * coord.x
</span>          , y: (-</span>1</span>) * coord.y
</span>          , offsetX: (-</span>1</span>) * coord.offsetX
</span>          , offsetY: (-</span>1</span>) * coord.offsetY
</span>          }
</span></code></pre>
Therefore we can use it on our player like thus:</p>
turnAround </span>:: Player -> Player
</span>turnAround player
</span>  = player { direction = invert player.direction }
</span></code></pre>
And wrap up the entire logic for the turn like this:</p>
updateDirection </span>:: Player -> Player
</span>updateDirection player
</span>  = </span>if</span> canMove player.position
</span>    </span>then</span> player
</span>    </span>else</span> turnAround player
</span></code></pre>
(Readers with a keen eye will notice we did not use anything particularly clever or typeclass based here, I just included it for completeness.)</p>
</p>
Actually moving that egg around</h3>
Let's get back to moving the egg around. Once we've worked out that our egg is moving somewhere it is allowed to, we need to actually update the offsetX</code> and offsetY</code> in it's position</code> so that's in the new location and ready to go through all this hell again. As web browsers are flaky at best, instead of moving by a set amount the actually amount to increment the change depends on how much time has passed since the last frame. Therefore we need a function that takes the amount to move and a Player</code>, and returns a new Player</code> that has moved in some way.</p>
Here, in a similar manner to our earlier function, is something like my original painful version.</p>
incrementPlayerPosition </span>:: Int -> Player -> Player
</span>incrementPlayerPosition moveAmount player@{ position: </span>Coord</span> pos, direction: </span>Coord</span> dir }
</span>  = player { position = newPosition }
</span>  </span>where
</span>    newPosition
</span>      | dir.x < </span>0 </span>= </span>Coord </span>$ pos { offsetX = pos.offsetX - moveAmount }
</span>      | dir.x > </span>0 </span>= </span>Coord </span>$ pos { offsetX = pos.offsetX + moveAmount }
</span>      | dir.y < </span>0 </span>= </span>Coord </span>$ pos { offsetY = pos.offsetY - moveAmount }
</span>      | dir.y > </span>0 </span>= </span>Coord </span>$ pos { offsetY = pos.offsetY + moveAmount }
</span>      | otherwise = </span>Coord</span> pos
</span></code></pre>
It should work but it's a bit terrifying. Let's break it up and get some of that sweet semigroup</code> magic working for us.</p>
Firstly, a helper function - this takes an Int</code> and a Coord</code> and creates a new Coord</code> that describes the movement we want the egg to do.</p>
createMoveCoord </span>:: Int -> Coord -> Coord
</span>createMoveCoord amount (</span>Coord</span> coord)
</span>  = </span>Coord</span> { x: </span>0
</span>          , y: </span>0
</span>          , offsetX: amount * coord.x
</span>          , offsetY: amount * coord.y
</span>          }
</span></code></pre>
Therefore if we take the falling</code> value from earlier, and a moving amount of 20</code>, it would create something like this:</p>
downMove </span>:: Coord
</span>downMove
</span>  = </span>Coord</span> { x: </span>0
</span>          , y: </span>0
</span>          , offsetX: </span>0
</span>          , offsetY: </span>20
</span>          }
</span></code></pre>
With our helpful helper function in hand, and a dash of <></code>, we can now rewrite our move function like thus:</p>
incrementPlayerDirection </span>:: Int -> Player -> Player
</span>incrementPlayerDirection amount player
</span>  = player { position = newPosition }
</span>  </span>where
</span>    </span>newPosition </span>:: Coord
</span>    newPosition
</span>      = player.position <> moveCoord
</span>
</span>    </span>moveCoord </span>:: Coord
</span>    moveCoord
</span>      = createMoveCoord amount player.direction
</span></code></pre>
So here we're creating a Coord</code> for the movement (called moveCoord</code>) - and then using the <></code> function to combine it with the current position</code> to make a new Coord</code> called newPosition</code>, and then making a new Player</code> with that position</code>.</p>
Putting it all together</h3>
Now we've created all our functions, we can plop them together like this to do the whole move:</p>
doMove </span>:: Int -> Player -> Player
</span>doMove amount
</span>  = updateDirection
</span>  >>> incrementPlayerDirection amount
</span></code></pre>
Easy as pie.</p>
"But I thought we'd actually draw one of those attractive looking eggs and instead we've just done some shitty maths", I hear you say. OK, OK, sure, I get it, you want adventure, you want action. We'll come to it soon, I promise.</p>


IO, IO, it's off to test we go
Unknown — Sun, 27 Jan 2019 00:00:00 +0000
Let's say we have a function that uses the IO</code> monad that we want to test. Now you may be aware that IO</code> is the place in which all the bad things happen that aren't supposed to happen in Haskell. Things like Database Connections</em>, and Mutable Global Variables</em> and (worst of all) Actual User Interactions</em>. It doesn't bear thinking about to be honest.</p>
However, mock dramatics aside, IO</code> is the part of our code where Side Effects</em> happen, meaning stuff is a lot more difficult to write tests for, given our functions may not always return the things we expect them to. Last time, we spoke about polymorphism</a> - and this seems like a nice opportunity to expand on that and use our new polymorphic powers to make some code easier to test.</p>
Contrived example</h3>
Here is some code that uses getCurrentTime</code> from the Data.Time.Clock</code> library to fetch the current system time and then work out whether it is time to stop working and eat some lunch.</p>
import qualified </span>Data.Time.Clock     </span>as </span>Clock
</span>import qualified </span>Data.Time.Calendar  </span>as </span>Cal
</span>import qualified </span>Data.Time.LocalTime </span>as </span>Time
</span>
</span>getHour </span>:: Clock</span>.</span>UTCTime -> Int
</span>getHour = </span>Time</span>.todHour
</span>        . </span>Time</span>.timeToTimeOfDay
</span>        . </span>Clock</span>.utctDayTime
</span>
</span>isItLunchTime </span>:: IO Bool
</span>isItLunchTime
</span>  = lunchCheck <$> getHour <$> </span>Clock</span>.getCurrentTime
</span>    </span>where
</span>      lunchCheck hr = hr >= </span>12</span> && hr <= </span>14
</span></code></pre>
The getHour</code> function is a simple pure function helper - mainly we'll be looking at isItLunchTime</code>. Let's look at the type signature again:</p>
isItLunchTime </span>:: IO Bool
</span></code></pre>
This function has no inputs, and the IO Bool</code> return type means that it will return True</code> or False</code>, wrapped in the IO</code> type to remind us that evil has been done and the gods of referential transparency have not been appeased.</p>
If you are thinking something like "can we not just extract the pure functions, test those, and not bother about the rest?", then Don't Read On because although that's Not A Terrible Idea we're absolutely Not Doing That.</p>
Injection-based solution</h3>
In other languages, the solution to making stuff more testable is to use Dependency Injection</code> to pass in any functions that use side effects, allowing mock versions to be passed in when testing.</p>
This version of the function lets us pass in a time fetching function (such as getCurrentTime</code>) instead.</p>
injectableLunch </span>:: IO Clock</span>.</span>UTCTime -> IO Bool
</span>injectableLunch getCurrentTime
</span>  = lunchCheck <$> getHour <$> getCurrentTime
</span>    </span>where
</span>      lunchCheck hr = hr >= </span>12</span> && hr <= </span>14
</span></code></pre>
Now, instead of calling isItLunchTime</code>, we'd call injectableLunch Clock.getCurrentTime</code>. It's still not much more testable though because of that IO</code> though. Does it need to be IO</code> though? What if we generalise the type signature though? Instead of IO</code>, let's just use any old Monad</code> and see if that works.</p>
testableLunch </span>::</span> (</span>Monad </span>m</span>) </span>=> </span>m </span>Clock</span>.</span>UTCTime -> </span>m </span>Bool
</span>testableLunch getCurrentTime
</span>  = lunchCheck <$> getHour <$> getCurrentTime
</span>    </span>where
</span>      lunchCheck hr = hr >= </span>12</span> && hr <= </span>14
</span></code></pre>
Because we're not actually running any functions that require the IO</code> monad (ie, readFile</code>, putStrLn</code>) any monad is totally fine for this function. So long as the Monad m</code> of our passed in time-getting function matches the Monad m</code> of the return value, then this function is having a Great Time.</p>
As a slight detour, let's make some fake UTCTime</code> values for testing:</p>
baseTestTime </span>:: Clock</span>.</span>UTCTime
</span>baseTestTime
</span>  = </span>Clock</span>.</span>UTCTime
</span>      { </span>Clock</span>.utctDay     = </span>Cal</span>.</span>ModifiedJulianDay 12000
</span>      , </span>Clock</span>.utctDayTime = </span>0
</span>      }
</span>
</span>lunchTestTime </span>:: Clock</span>.</span>UTCTime
</span>lunchTestTime
</span>  = baseTestTime { </span>Clock</span>.utctDayTime = </span>44000</span> }
</span></code></pre>
Excellent. What a nice couple of examples. For more information about what these do, check out the time</a> library.</p>
Now we have some test values, we can then make functions to test our testableLunch</code> function with a safer Monad like Identity</code>. Identity</code> is the Do Nothing monad, it has no special characteristics and does nothing for any particular interest.</p>
testNotLunch </span>:: Identity Bool
</span>testNotLunch = testableLunch (pure baseTestTime)
</span>-- Identity False
</span></code></pre>
testIsLunch </span>:: Identity Bool
</span>testIsLunch = testableLunch (pure lunchTestTime)
</span>-- Identity True
</span></code></pre>
(What's pure</code>? It's just a function that wraps a value inside the default Monad context, so in this case, turns "dog"</code> into Identity "dog"</code> etc)</p>
Then when we want to export the function for use with IO</code>, we can export this:</p>
isItLunchTime3 </span>:: IO Bool
</span>isItLunchTime3 = testableLunch </span>Clock</span>.getCurrentTime
</span></code></pre>
Seems pretty OK. What about a more idiomatic Haskell approach using our pal typeclasses?</p>
Testing IO with a typeclass</h3>
Another way to do this is capture the idea of "Monad That Knows What The Time Is" using a typeclass.</p>
Let's call ours MonadTime</code>, because we lack imagination:</p>
class </span>Monad </span>m</span> => </span>MonadTime </span>m </span>where
</span>  </span>getTheTimePlease </span>:: </span>m </span>Clock</span>.</span>UTCTime
</span></code></pre>
Note the constraint - we can only make instances of MonadTime</code> for things that are already an instance of Monad</code>. By writing instances of MonadTime</code> for IO</code> and Identity</code>, we can tell Haskell what to do when it's asked for the time.</p>
instance MonadTime Identity where
</span>  getTheTimePlease = pure lunchTestTime
</span>
</span>instance MonadTime IO where
</span>  getTheTimePlease = </span>Clock</span>.getCurrentTime
</span></code></pre>
Identity</code> will return a static value, and IO</code> will use the actual function.</p>
Here's our new version of the lunch function. Notice we've changed our constraint from Monad m</code></p>
classyLunch </span>::</span> (</span>MonadTime </span>m</span>) </span>=> </span>m </span>Bool
</span>classyLunch
</span>  = lunchCheck <$> getHour <$> getTheTimePlease
</span>    </span>where
</span>      lunchCheck hr = hr >= </span>12</span> && hr <= </span>14
</span></code></pre>
Now, depending on the context in which we use classyLunch</code>, it'll do different things.</p>
testClassyLunch </span>:: Identity Bool
</span>testClassyLunch = classyLunch
</span>
</span>ioClassyLunch </span>:: IO Bool
</span>ioClassyLunch = classyLunch
</span></code></pre>
Hooray! Our contrived function is now testable and also ready for production. Great stuff.</p>
This concept of different typeclasses for Monads is a key part of what is called mtl</code> style of code, which we will come to once we've looked at Monad Transformers.</p>
Further reading:</p>
Time library</a></p>
Better IO testing through Monads</a></p>


Why The Hell Should I Care About Polymorphism?
Unknown — Mon, 21 Jan 2019 00:00:00 +0000
Let's talk about type signatures.</p>
hello </span>:: String -> Int -> String
</span></code></pre>
Pretty clear what is going on, right? Seems fine. What about this lad?</p>
wtflol </span>::</span> (</span>Show </span>a</span>, </span>Num </span>b</span>) </span>=> </span>a </span>-></span> [</span>a</span>] </span>-> </span>b </span>-></span> (</span>a</span>, </span>b</span>)
</span></code></pre>
That's pretty unhelpful to be honest.</p>
What are these letters doing in our types when we wanted, well, types?</p>
Let's work up from a simple one to a stupid one and maybe learn something along the way. Good? Great.</p>
Probably the worst function ever</h3>
Here is a type signature for a mysterious function:</p>
spooky </span>:: </span>a </span>-> </span>a
</span></code></pre>
Given any a</code>, and knowing nothing about that a</code>, what is the only thing that we can do with it?</p>
If you guessed "just return it", then yes, you were right. It's the classic identity</code> function.</p>
identity </span>:: </span>a </span>-> </span>a
</span>identity a = a
</span>-- identity 10 == 10
</span></code></pre>
What do you think this function does?</p>
mystery </span>:: </span>a </span>-> </span>b </span>-> </span>a
</span></code></pre>
Since we don't know anything about b</code>, and the function returns an a</code>, then all we can do is ignore the b</code> altogether. This is called the const</code> function, and is used when we have to want to make a map</code> function do not very much at all.</p>
const </span>:: </span>a </span>-> </span>b </span>-> </span>a
</span>const a _ = a
</span>-- const "dog" 100 == "dog"
</span></code></pre>
Hopefully the pattern you are seeing here is that if we know nothing about our variables, then there is actually very little we can do with them.</p>
Lists of mysterious things</h3>
A place most people come across polymorphism quite early on in their Haskell careers is in stuff like lists. Instead of one function that works on List String</code>, and another one List Int</code>, and another on List (Maybe Tuple (Int, String))</code> we can use polymorphism to act upon the structure of the list itself but not the items inside.</p>
With this in mind, and given that [a]</code> means a List</code> that is full of zero or more a</code> values, what possible things could this function do to our [a]</code>?</p>
thing </span>::</span> [</span>a</span>] </span>-></span> [</span>a</span>]
</span></code></pre>
According to the function search engine Hoogle</a> - not a huge amount. It lists four functions that match this signature - and two of them throw exceptions if passed an empty list so they're not the kind of functions that we like to spend our time with. This leaves:</p>


cycle</code> - this repeats the list of values infinitely.</p>
</li>

reverse</code> - reverses the order of the list.</p>
</li>
</ol>
The important thing is that since we don't know anything about what the hell a</code> is, all the functions can do is mess around with the ordering a bit, as is their right, I suppose. How can we find out more about these a</code> and b</code> values without concretely specifying what they are?</p>
Constraints</h3>
If there's anything going on before the =></code> in a type signature, there's a good chance it's a constraint</code>. These are rules that apply to each type they refer to. Here, we are using a constraint on a</code>, that says "I don't care what a</code> is, so long as it has a Show</code> instance".</p>
showTheList </span>:: Show </span>a </span>=></span> [</span>a</span>] </span>-> String
</span>showTheList </span>[]       </span>= ""
</span>showTheList (a : as) = show a ++ "</span>, </span>" ++ showTheList as
</span>-- showTheList [1,2,3] == "1, 2, 3, "
</span></code></pre>
Therefore, the only thing we can really do to these a</code> values is show</code> them, as we don't know anything else about it.</p>
We can do something similar with the Num</code> typeclass (which is the typeclass of numbers).</p>
addStuffUp </span>:: Num </span>a </span>=></span> [</span>a</span>] </span>-> </span>a
</span>addStuffUp </span>[]       </span>= </span>0
</span>addStuffUp (a : as) = a + addStuffUp as
</span>-- addStuffUp [1,2,3] == 6
</span></code></pre>
Here, the constraint means we don't mind which kind of number we are passed - since they all implement +</code> so we can add them together.</p>
We can have as many constraints as we like on our variables (often multiple ones on the same value, such as (Show a, Ord a) =></code> for things that can be sorted and eventually turned into strings) - and can use any typeclass to do the restraining.</p>
I hope this makes sense. This started melting into something about IO testing, but I have decided to spin that into a separate post before this one spirals out of control, so let's stop for now. Thanks.</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Polymorphism for Dummies</a></p>
Polymorphism in Haskell</a></p>


Typeclasses - Bifunctor
Unknown — Sun, 13 Jan 2019 00:00:00 +0000
Let's talk about things that could be one thing, or indeed could be another thing altogether.</p>
data </span>Things</span> a b = </span>This</span> a | </span>That</span> b
</span></code></pre>
This could be a This</code> with an a</code> inside, like a String</code>.</p>
thisEgg </span>:: Things String Int
</span>thisEgg = </span>This </span>"</span>Egg</span>"
</span></code></pre>
Or indeed a That</code> with a b</code> inside, like an Int</code>.</p>
thatNumber </span>:: Things String Int
</span>thatNumber = </span>That 68
</span></code></pre>
Now hopefully you are now thinking - "Oh please, I do hope we map a function over one of these values soon" - and worry not, we absolutely bloody can.</p>
Mappity Mappity Map</h3>
Let's really push the boat out, and add one to the value inside.</p>
First we'll need a Functor</a> instance. Hopefully nothing too surprising here.</p>
instance Functor</span> (</span>Things </span>a</span>) </span>where
</span>  fmap f (</span>That</span> b) = </span>That</span> (f b)
</span>  fmap _ (</span>This</span> a) = </span>This</span> a
</span></code></pre>
Now we can map away to our heart's content:</p>
biggerNumber </span>:: Things String Int
</span>biggerNumber = fmap addOne (</span>That 68</span>)
</span>-- biggerNumber == That 69
</span></code></pre>
Nice.</p>
But what about `This "Egg"``? I'd like to get at that egg. Perhaps eat it.</p>
eat </span>:: String -> String
</span>eat s = "</span>The </span>" ++ s ++ "</span> was delicious!</span>"
</span></code></pre>
Can we do that with Functor</code>?</p>
doesntWork </span>:: Things String Int
</span>doesntWork = fmap eat thisEgg
</span>-- ERROR: Couldn't match type ‘[Char]’ with ‘Int’
</span></code></pre>
I'm afraid not. Looking back at our Functor</code> instance we can see that the fmap</code> function only lets us map over the values inside That</code>, leaving poor This</code> and our lonely egg very much map-less. But fear not! We have another weapon at hand that will let us get at it.</p>
Enter....Bifunctor!</code></p>
(cue lightning, thunder, explosions and sounds of a large crowd who are clearly quite impressed).</p>
Definition</h3>
Let's ask ghci</code> what's up.</p>
> </span>import </span>Data.bifunctor
</span>> :i </span>Bifunctor
</span></code></pre>
class </span>Bifunctor</span> (</span>p</span> :: * -> * -> *) </span>where
</span>  </span>first </span>::</span> (</span>a </span>-> </span>b</span>) </span>-> </span>p a c </span>-> </span>p b c
</span>  </span>second </span>::</span> (</span>b </span>-> </span>c</span>) </span>-> </span>p a b </span>-> </span>p a c
</span>  </span>bimap </span>::</span> (</span>a </span>-> </span>b</span>) </span>-></span> (</span>c </span>-> </span>d</span>) </span>-> </span>p a c </span>-> </span>p b d
</span>  {-# </span>MINIMAL</span> bimap | first, second #-}
</span></code></pre>
Ok. Three functions in here, and it looks like we can make something a Bifunctor</code> by implementing instances of both first</code> and second</code> or just bimap</code>.</p>
Let's take a look at them.</p>


first :: (a -> b) -> p a c -> p b c</code> - this takes a Bifunctor</code> that may contain some a</code> and c</code> values, and a function that turns an a</code> into some sort of b</code>. It then runs the function on the a</code> value, turning it into a b</code> value. Sort of like doing an fmap</code> over the a</code> inside This</code> from earlier. Pretty nice. Tl;dr - it's fmap</code> but over the left value.</p>
</li>

second :: (b -> c) -> p a b -> p a c</code> - this takes a Bifunctor</code> with an a</code> and a b</code> and a function that turns the b</code> values into c</code> values. In the case of our Things</code> datatype of This</code> and That</code>, this let's us get at the That</code> values, which we could anyway so big whoop. Tl;dr - it's our pal fmap</code> again.</p>
</li>

bimap :: (a -> b) -> (c -> d) -> p a c -> p b d</code> - this takes a Bifunctor</code> that may contain a</code> and c</code> values, and runs a function over both sides. It's doing first</code> and second</code> at the same time.</p>
</li>
</ol>
OK. If you understand Functor</code> there's hopefully nothing out of the ordinary going on here. Let's slop an instance together and get to work on that delicious egg.</p>
Instances</h3>
Laziness dictates that we should define bimap</code> because it is one function instead of two.</p>
instance Bifunctor Things where
</span>  bimap f _ (</span>This</span> a) = </span>This</span> (f a)
</span>  bimap _ g (</span>That</span> b) = </span>That</span> (g b)
</span></code></pre>
Seems fairly sensible hopefully. Let's give it a spin.</p>
delicious </span>:: Things String Int
</span>delicious = first eat (</span>This </span>"</span>Egg</span>")
</span>-- delicious = This "The Egg was delicious!"
</span></code></pre>
Hooray! Although we defined bimap</code> we got first</code> for free, and that egg was pretty nice.</p>
We can still map over the right hand value too!</p>
doesWork </span>:: Things String Int
</span>doesWork = second addOne (</span>That 68</span>)
</span>-- doesWork == That 69
</span></code></pre>
Again, nice.</p>
Tuples, Pooples</h3>
Although our Things</code> example is about sum</code> types, we can also use it on product</code> types like a Tuple</code>, and use Bifunctor</code> to mess with either value as we please.</p>
twoThings </span>::</span> (</span>Int</span>, </span>String</span>)
</span>twoThings = (</span>100</span>, "</span>Dogs</span>")
</span></code></pre>
Now, we could go ahead and show you first</code> and second</code> but I think you can work out what's going to happen, so let's go absolutely bonkers and race straight to bimap</code>.</p>
(but first, a helper function. Nothing untoward - it merely returns the first thing you give it and ignores the second.)</p>
myConst </span>:: </span>a </span>-> </span>b </span>-> </span>a
</span>myConst a _ = a
</span></code></pre>
Now we can turn our Tuple</code> into a bestselling novel.</p>
oneBestSeller </span>::</span> (</span>Int</span>, </span>String</span>)
</span>oneBestSeller = bimap (+</span>1</span>) (myConst "</span>Dalmations</span>") twoThings
</span>-- oneBestSeller = (101, "Dalmations")
</span></code></pre>
I Bet You Did Not See That Coming.</p>
For a bonus point, why not try and define first</code> and second</code> for Tuple</code> types using bimap</code> and myConst</code>? Go on. You'll have a great time, I absolutely promise.</p>
That's all, folks</h3>
So although helpful with Tuple</code> and Either</code> types, Bifunctor</code> isn't particularly mindblowing, but comes into it's own when we combine it with Contravariant</a> to make Profunctor</code>. More on that in the future though!</p>
Further reading:</p>
The Extended Functor Family (video)</a></p>
Data.Bifunctor</a></p>


Typeclasses - Alternative
Unknown — Sun, 06 Jan 2019 00:00:00 +0000
Let's think about things that may or may not happen (again, I know, I'm sorry).</p>
data </span>Perhaps</span> a = </span>Yeah</span> a | </span>Nope </span>deriving</span> (</span>Eq</span>)
</span></code></pre>
A classic datatype, that we can use for expressing either Some Sort Of Value</em> or The Entire Concept Of Failure</em>. We can use it when getting the first item of a list, which may or may not actually exist.</p>
first </span>::</span> [</span>a</span>] </span>-> Perhaps </span>a
</span>first (a:_) = </span>Yeah</span> a
</span>first _     = </span>Nope
</span></code></pre>
If there IS a first item in the list we get the item wrapped in a Yeah</code>, if not we get Nope</code>.</p>
We can make another very similar function for getting the second item as well...</p>
second </span>::</span> [</span>a</span>] </span>-> Perhaps </span>a
</span>second (_:b:_) = </span>Yeah</span> b
</span>second _       = </span>Nope
</span></code></pre>
Now let's say that for some entirely incomprehensible reason, we'd like the second item in the list, if not, the first item. What would that function look like?</p>
First solution</h3>
naiveImplementation </span>::</span> [</span>a</span>] </span>-> Perhaps </span>a
</span>naiveImplementation as = </span>case</span> second as </span>of
</span>  </span>Yeah</span> s -> </span>Yeah</span> s
</span>  </span>Nope   </span>-> first as
</span></code></pre>
Does it work?</p>
emptyList </span>:: Perhaps Int
</span>emptyList = naiveImplementation </span>[]
</span>-- emptyList == Nope
</span>
</span>oneItemList </span>:: Perhaps Int
</span>oneItemList = naiveImplementation [</span>1</span>]
</span>-- oneItemList == Yeah 1
</span>
</span>twoItemList </span>:: Perhaps Int
</span>twoItemList = naiveImplementation [</span>1</span>,</span>2</span>]
</span>-- oneItemList == Yeah 2
</span></code></pre>
It bloody does! Lovely stuff. Let's all go home and put our feet up, we've nailed it.</p>
OK. But hang on, that naiveImplementation</code> function does seem a bit much though, especially if we start adding more cases to it. Plus that name kinda suggests, well, that the function might not represent the best way to go about this.</p>
What if there was a typeclass that was designed to make things like this easier to deal with?</p>
Let's meet Alternative</code>!</p>
Definition</h3>
What does ghci</code> have to say about this so-called Alternative</code>?</p>
Prelude</span>> </span>import </span>Control.Applicative
</span>Prelude</span>> :i </span>Alternative
</span></code></pre>
class </span>Applicative </span>f</span> => </span>Alternative</span> (</span>f</span> :: * -> *) </span>where
</span>  </span>empty </span>:: </span>f a
</span>  </span>(<|>) </span>:: </span>f a </span>-> </span>f a </span>-> </span>f a
</span>  {-# </span>MINIMAL</span> empty, (<|>) #-}
</span></code></pre>
OK. So the most interesting thing is that any Alternative</code> first needs to be a valid instance of Applicative</a> first.</p>
Secondly, we can get one just by defining empty</code> and <|></code>. What are those then?</p>


empty</code> is the identity</em> element. This is a bit like the mempty</code> in Monoid</a> - it is a value that when added to the datatype, does nothing to it.</p>
</li>

<|></code> is sort of an or</code> for data types. Given two values, it returns the first valid</em> one, as such. What valid</em> means depends on the datatype, but usually that value won't be the same as empty</code>.</p>
</li>
</ol>
If you're looking at this and thinking "This Seems Very Similar To A Monoid" then, yes, it sort of does, consisting as it does of one Smash Things Together</em> function and one Sort Of Nothingy</em> value.</p>
Let's define it for our exciting Perhaps</code> type.</p>
Instances</h3>
Before we can have an Applicative</code> we'll need a Functor</a> instance. This one runs the function over the value if it's there, if not, it does nothing at all.</p>
instance Functor Perhaps where
</span>  fmap f (</span>Yeah</span> a) = </span>Yeah</span> (f a)
</span>  fmap _ _        = </span>Nope
</span></code></pre>
OK. Great stuff. Let's make an Applicative</code> instance next. The pure</code> instance just wraps whatever it's passed in a Yeah</code>. The <*></code> (or apply</code>) function is written so that if we have a function inside f</code> and a value in a</code> then we'll get the function f</code> applied to a</code> and wrapped in Yeah</code>, if not we'll get a Nope</code>.</p>
instance Applicative Perhaps where
</span>  pure a = </span>Yeah</span> a
</span>  (</span>Yeah</span> f) <*> (</span>Yeah</span> a) = </span>Yeah</span> (f a)
</span>  _        <*> _        = </span>Nope
</span></code></pre>
Yeah? Yeah.</p>
OK. Here is the exciting part:</p>
instance Alternative Perhaps where
</span>    empty             = </span>Nope
</span>    </span>Yeah</span> x  <|> _     = </span>Yeah</span> x
</span>    _       <|> y     = y
</span></code></pre>
Look at that! An exciting Alternative</code> instance. Nope</code> is our empty</code> (or identity</em>) value, and our <|></code> function returns the first value if it's a Yeah</code> (which represents valid</em> data in the context of our Perhaps</code> datatype), if not it returns whatever the second value is.</p>
Let's use it to make some contrived code ever so slightly smaller and more difficult to understand.</p>
Better Solution</h3>
Here is our Get The Second Item, Or If That Doesn't Work Out Then Let's Settle For The First Item</em> function.</p>
getPreferred </span>::</span> [</span>a</span>] </span>-> Perhaps </span>a
</span>getPreferred as = second as <|> first as
</span></code></pre>
Much easier to understand! It almost looks like second || first</code>, which I like a lot.</p>
Don't trust me?</p>
notFound </span>:: Perhaps Int
</span>notFound = getPreferred </span>[]
</span>-- notFound == Nope
</span>
</span>found1 </span>:: Perhaps Int
</span>found1 = getPreferred [</span>1</span>]
</span>-- found1 == Yeah 1
</span>
</span>found2 </span>:: Perhaps Int
</span>found2 = getPreferred [</span>1</span>,</span>2</span>]
</span>-- found2 = Yeah 2
</span></code></pre>
See! And you doubted me!</p>
Now, that seems like a lot of instance writing for not much, but often the place you'll find Alternative</code> is in stuff like routing for front end applications. Let's have a look at something like that:</p>
Routing Example</h3>
Here's a datatype to describe all the pages in a completely fictional and somewhat limited website...</p>
data </span>Route </span>= </span>Index
</span>           | </span>Gallery
</span>           | </span>Contact
</span>           | </span>Complaints
</span>           | </span>Help </span>deriving</span> (</span>Eq</span>, </span>Show</span>)
</span></code></pre>
...some type aliases to make the type signatures we're about to write easier to understand...</p>
type </span>Url </span>= </span>String
</span>type </span>Match </span>= </span>String
</span></code></pre>
...and a (rather basic) function for taking the passed url</code> and matching it to the page we want to be looking at:</p>
matches </span>:: Match -> Route -> Url -> Perhaps Route
</span>matches match route url = </span>if</span> isInfixOf match' url'
</span>                        </span>then </span>Yeah</span> route
</span>                        </span>else </span>Nope </span>where
</span>                          match' = toLower <$> match
</span>                          url'   = toLower <$> url
</span></code></pre>
What's going on here?</p>


First, it converts our match</code> and url</code> strings to lowercase by mapping toLower</code> from Data.Char</code> over.</p>
</li>

Then, it uses isInfixOf</code> from Data.List</code> which returns a Boolean</code> telling us whether the match</code> string can be found inside the url</code> string.</p>
</li>

If so, return the passed Route</code> wrapped in a Yeah</code>, if not, return Nope</code>.</p>
</li>
</ol>
Good stuff!</p>
And now here is our actual logic, that uses the matches</code> function to find out where we should navigate to in our excellent website.</p>
matchRoute </span>:: Url -> Perhaps Route
</span>matchRoute url = matches "</span>gallery</span>" </span>Gallery</span> url
</span>             <|> matches "</span>contact</span>" </span>Contact</span> url
</span>             <|> matches "</span>complaints</span>" </span>Complaints</span> url
</span>             <|> matches "</span>help</span>" </span>Help</span> url
</span></code></pre>
Assuming we always want to navigate somewhere, we can also make a wrapper function that returns a default Route</code> if we do not find a valid one.</p>
matchRouteDefault </span>:: Url -> Route
</span>matchRouteDefault url =
</span>  </span>case</span> matchRoute url </span>of
</span>    </span>Yeah</span> route -> route
</span>    _          -> </span>Index
</span></code></pre>
Let's use it to navigate to the Gallery</code>, which I have no doubt is a very good example of the genre.</p>
findGallery </span>:: Route
</span>findGallery = matchRouteDefault "</span>http://internet.com/gallery</span>"
</span>-- findGallery == Gallery
</span></code></pre>
Or default to the Index</code> when we're passed a load of old rubbish.</p>
findDefault </span>:: Route
</span>findDefault = matchRouteDefault "</span>http://internet.com/rubbish</span>"
</span>-- findDefault == Index
</span></code></pre>
We're basically front end development experts now. Great stuff.</p>
Wrapping Up</h3>
The Control.Applicative</code> documentation describes Alternative</code> as a "a Monoid on applicative functors"</em>, and perhaps I could have just led with that and saved us all a bunch of trouble. This kind of typeclass mainly gives us a nicer syntax so that we can bend our code to closer match the domain we are working in, which is generally a Good Thing in my book.</p>
(You may notice we've done a lot of work here defining Perhaps</code> when we could have just used Maybe</code> and saved ourselves writing a lot of instances but it's my blog and I can do what I want.)</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Control.Applicative</a></p>
Alternative and MonadPlus</a></p>


Why The Hell Should I Care About Typeclasses?
Unknown — Sat, 05 Jan 2019 00:00:00 +0000
So recently I have become one of those jerks that has sailed through Read A Couple Of Chapters Of A Book About Haskell</em>, by way of Snuck Maybe Types Into My Work Project</em> to arrive at full-blown Good Morning Sir/Madam, Have You Got A Spare Moment To Talk About Monads™?</em>. That is to say, by selfishly forcing these concepts upon my colleagues I have ended up spending a lot of my working life explaining them and why I think they are good to stop everybody hating me for making their lives unnecessary complicated. In doing so, I think I have come across one of the main conceptual stumbling blocks, which I hope to make less-stumble-able.</p>
So the problem, as I see it, isn't grasping what a Monad</code> is (it's a burrito, it's a poster tube, it's a snobby waste of time, easy!), or even what a Functor</code> is (it's mappable, right?), but whether they are even "things" at all. It's one thing to see words like Monad</code>, Functor</code>, Monoid</code> or Traversable</code> around the place but it's a little unclear how to make, or god forbid, actually use one in something approaching real life code. Are they objects? Do I make a new Monad</code> object just like I'd make a new Promise</code>?</p>
const </span>response </span>= new Monad(</span>ajaxUrl</span>)
</span></code></pre>
Is is a Functor</code> a method I can run on something to increase the amount of maths?</p>
const </span>makeProgramFaster </span>= </span>response</span>.</span>Functor</span>("</span>MAXIMISE DATA</span>")
</span></code></pre>
The short answer is "no", and the long answer, well, that's also "no", followed by "ok, let me tell you what typeclasses are and hopefully the other stuff will sort of get cleared up along the way."</p>
Maths is sadness</h3>
Reading about type theory, particularly materials written from a very mathematical perspective, can often make it feel even worse, with explanations that feel so broad and simple that they feel either a) meaningless or b) like they must contain some unseen trap we mere mortals do not understand.</p>
</p>
Anyhow, I thought perhaps a better approach here is to explain what these things are not and work from there. Because the aim here is to end up with some real life knowledge we can use to write real code, instead of using examples from the world of computers, let's use them from the world of crime dramas, because I have been watching a lot of those recently.</p>
Time for a tenuous analogy</h3>
So we have a police officer. In this case, it's Detective Sergeant Kate Fleming from Jed Mercurio's surprisingly gripping Line Of Duty series (I too struggled with the series title's almost Clancy-ian levels of Really Must We Spell This Out, do persevere with it though, it really is OK, you probably only need to watch the first couple of seasons to follow this article)</p>
</p>
DS Kate Fleming</strong> is a Police Officer</code> in AC-12, a unit in the police force somewhere in London that investigates Bent Coppers</code> and makes sure there is no Dodgy Dealings</em> or Underhand Business</em>. DS Kate Fleming</strong> was not born a police officer, but certainly displays all the characteristics of one - she Catches Criminals</em>, Likes A Pint</em>, and Her Marriage Is In Tatters</em> because of course she is Married To The Job</em>.</p>
![DC Nigel "Nige" Morton, a human man](/images/typeclass4.png "DC Nigel "Nige" Morton, a human man")</p>
Here is another Police Officer</code> - in this case Detective Constable Nigel "Nige" Morton</strong>, played by 90s lad hero and renowned bounding frown Neil Morrissey. "Nige"</strong> was also not born a copper, but he is certainly one now as he Likes A Pint</em> and also, to some extent, Catches Criminals</em>. "Nige"</strong>, however, is a bit of a sneaky prick, and has been known from time to time to take a few backhanders in exchange for leaking information to the press and to other criminals. Therefore, to some extent, as well being a Police Officer</code>, "Nige"</strong> is a Bent Copper</code> because of his Underhand Business</em> and Dodgy Dealings</em>.</p>
How does this relate to typeclasses then?</h3>
DS Kate Fleming</strong> is not a typeclass.</p>
DC Nigel "Nige" Morton</strong> is also not a typeclass.</p>
Liking A Pint</em> is not a typeclass.</p>
Neither is Underhand Business</em>.</p>
Typeclass examples</h3>
So what are?</p>

Human Person</code></li>
</ul>
Both DS Kate Fleming</strong> and DC Nigel "Nige" Morton</strong> can have instances of the typeclass Human Person</code>, because they Breath</em>, Eat</em> and Poo</em>. They are 'lawful' instances of Human Person</code> because I am too lazy to think of a reason that they are not.</p>

Police Officer</code></li>
</ul>
DS Kate Fleming</strong> can be an instance of the typeclass of Police Officer</code> because she Catches Criminals</em> and Likes A Pint</em>. She is also a 'lawful' instance, we can say, because as well as this, she does no Underhand Business</em> or Dodgy Dealings</em>.</p>
DC Nigel "Nige" Morton</strong> is, to the innocent eye, an instance of the typeclass Police Officer</code>. He also Likes A Pint</em>, Catches Criminals</em>, and although he is seen to have a marriage earlier in the show, later he is seen to be mowing his lawn in a solitary fashion shot through a lens tinged with regret. However, he is not a 'lawful' instance of the typeclass Police Officer</code>, because of his Underhand Business</em> or Dodgy Dealings</em>.</p>

Bent Copper</code></li>
</ul>
DS Kate Fleming</strong> is not in the typeclass Bent Copper</code>, because (spoiler alert!) throughout the show she is seen to behave in a moral fashion befitting an officer working for AC-12, the anti-corruption unit at the centre of the whole show.</p>
DC Nigel "Nige" Morton</strong> however is in the typeclass Bent Copper</code>, exactly because of his Underhand Business</em>, Dodgy Dealings</em> and Perhaps Not Really Needing That Walking Stick But Claiming Disability Benefits Regardless</em>. He is probably also a lawful instance of Bent Copper</code> (although I understand at this juncture that this makes the whole analogy somewhat confusing) - simply because Bent Coppers Don't Really Have Rules, And If They Did, Playing By Them Would Somewhat Defeat The Point.</em></p>

Anti-Corruption Police Officer</code></li>
</ul>
DS Kate Fleming</strong> is also in this typeclass because she Nicks Bent Coppers</em>, whilst DC Nigel "Nige" Morton</strong> is not because he wouldn't Dob In One Of Our Own</em>. Clear? As mud? Great.</p>
Back to stupid code</h3>
So how does this relate to computers and showing our colleagues how incredibly intellectual we are?</p>
</p>
Let's take an array. That's a thing you have probably used.</p>
const </span>arr </span>= [</span>1</span>, </span>2</span>, </span>2</span>, </span>4</span>, </span>65</span>, </span>7</span>]
</span></code></pre>
arr</strong> is not a typeclass, it is an object (or more broadly, a value).</p>
A Functor</code> is a typeclass though, and arr</strong> can be an instance of Functor</code>.</p>
The rules of a 'lawful' Functor</code> is that we can run a Map function over the contents of the array and afterward The Length Of The Array Remains The Same</em> and It's Still An Array</em> and Basically Nothing Really Weird Has Happened</em>.</p>
arr</span>.</span>map</span>(</span>x </span>=> </span>x</span>)
</span>// arr == [1, 2, 2, 4, 65, 7]
</span></code></pre>
As you see here, our array is the same length and the function has been applied to each item without any Funny Business</em>. To tie it back to our police-based analogy - if DS Kate Fleming</strong> was given some important evidence to take back to the station, this result constitutes the evidence arriving at the station untampered for some forensic analysis that will pull the case together in the final nail-biting moments of the series.</p>
However, what if DC Nigel "Nige" Morton</strong> was given that same evidence? That's a nice 65</code> value in there, surely nobody would notice if he snuck it for himself? Surely he's Done His Bit Over The Years And Deserves It</em>, after all.</p>
var </span>nigesFilthyPocket </span>= []
</span>
</span>arr</span>.</span>map</span>(</span>x </span>=> </span>{
</span>  </span>if </span>(</span>x </span>< </span>65</span>) {
</span>    </span>return </span>x
</span>  } </span>else </span>{
</span>    </span>nigesFilthyPocket</span>.</span>push</span>(</span>x</span>)
</span>    </span>return </span>0
</span>  }
</span>})
</span>// arr == [1, 2, 2, 4, 0, 7]
</span></code></pre>
If you can follow this code (and forgive the use of a mutable variable in an article that is, despite severely beating around the bush about the fact, written about the subject of functional programming) I think we can all agree that "Nige"</strong> here is a bit of a swine.</p>
</p>
"Nige"</strong>'s horrible law-breaking evidence-stealing map</code> function does not make a 'lawful' Functor</code>, as it breaks the Basically Nothing Really Weird Has Happened</em> rule above by doing a massive side-effect and mutating an outside variable when it should just be doing nothing outside of the arr</strong>. However, if there is a TotallyAwfulFunctor</code> typeclass, this would make an excellent instance of it.</p>
OK, I'm exhausted, please, tell me, what is a typeclass?</h3>
Sure.</p>
</p>
Objects and datatypes can be made instances of the typeclass Functor</code>, provided they implement map</em> without any funny business. These could be arrays, tree structure, Maybe</code> and Either</code>, and loads more. You can map</em> over them all and expect the same behaviour.</p>
People are instances of the typeclass Human Being</code>, as in general they implement the Breath</em>, Eat</em> and Poo</em> functions. (todo: add javascript example)</p>
Anything that can be compared to another thing to check whether it is the same or not can be an instance of the typeclass Eq</code>.</p>
Many objects and datatypes can be made instances of the typeclass Monad</code>, if they are also lawful Functors</code> and Applicative Functors</code> and implement bind</em> and return</em> functions. (What? Not now...)</p>
Therefore...</p>
A typeclass is a way of categorising things based not on what they are but what they can and can't do.</h3>
(Thanks Riku</a> for helping me put that more succinctly. You may find it hard to believe that I have a tendency to ramble).</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Typeclassopedia</a></p>
More about Typeclasses</a></p>


Typeclasses - Monoid
Unknown — Fri, 04 Jan 2019 00:00:00 +0000
In an exciting previous episode, we talked about the Semigroup</a> type class that is used for smashing two things together.</p>
Today we're going to talk about the Monoid</code> typeclass, which is a way of generalising a collection of things that can be combined together. Seems very similar, but the important difference between combining two things, and combining any number of things, is that that number of things might be zero things.</p>
Therefore as well as the append</code> function <></code> we will need a way of expressing what no items looks like. Seems weird? Yeah, it kind of is. Some examples may help.</p>
Combining Lists</h3>
We need to combine a List</code> of other List</code> values, and we're all functional programmers, so let's go ahead and make a function for doing that.</p>
combineList </span>::</span> [[</span>a</span>]] </span>-></span> [</span>a</span>]
</span>combineList (a:as) = a ++ (combineList as)
</span></code></pre>
If we use it on an actual value, then great job.</p>
great </span>::</span> [</span>Int</span>]
</span>great = combineList [[</span>1</span>,</span>2</span>,</span>3</span>],[</span>4</span>,</span>5</span>,</span>6</span>]]
</span>-- great == [1,2,3,4,5,6]
</span></code></pre>
But what about if we use it on an empty list?</p>
error </span>::</span> [</span>Int</span>]
</span>error = combineList </span>[]
</span></code></pre>
Ahh shit! We get this:</p>
uncaught exception: </span>PatternMatchFail
</span></code></pre>
That's not great. Looks like we're going to need an empty value to use for empty lists.</p>
combineList1 </span>::</span> [[</span>a</span>]] </span>-></span> [</span>a</span>]
</span>combineList1 </span>[] </span>= </span>[]
</span>combineList1 (a:as) = a ++ (combineList1 as)
</span></code></pre>
ok </span>::</span> [</span>Int</span>]
</span>ok = combineList1 </span>[]
</span>-- ok == []
</span></code></pre>
So here the empty value is []</code> - and having this value is what means we have a Monoid</code> as well as a Semigroup</code>.</p>
Definition</h3>
What does ghci</code> say about Monoid</code>?</p>
Prelude</span>> :i Monoid
</span></code></pre>
class </span>Semigroup </span>a</span> => </span>Monoid </span>a </span>where
</span>  </span>mempty </span>:: </span>a
</span>  </span>mappend </span>:: </span>a </span>-> </span>a </span>-> </span>a
</span>  </span>mconcat </span>::</span> [</span>a</span>] </span>-> </span>a
</span>  {-# </span>MINIMAL</span> mempty #-}
</span></code></pre>
OK. So firstly, whatever we want to make a Monoid</code> must also be a Semigroup</code>.</p>
(Incidentally, the terminology of the relationship between these two is that Semigroup</code> is a superclass</code> of Monoid</code>, meaning anything that is a Monoid</code> is also a Semigroup</code>. Conversely Monoid</code> is a subclass</code> of Semigroup</code>. You'll notice many of these relationships amongst Haskell classes, like between Eq</code> and Ord</code>, and between Functor</code> and Applicative</code>. More words! More confusion! Great!)</p>
Secondly, the only function we need to define (because of MINIMAL</code>) is mempty</code> - which defines our empty element (we also need mappend</code>, but this is the same as <></code> and is supplied by our Semigroup</code> unless we have a burning desire to write another one).</p>
Therefore, if we take a Semigroup</code> and plop an mempty</code> function on it too we can have a Monoid</code>. Clear as mud!</p>
More about mempty</h3>
The important test for this mempty</code> value is that when we mappend</code> it onto our Monoid</code> it does nothing whatsoever.</p>
Here's an empty element for List</code>...</p>
emptyList </span>::</span> [</span>Int</span>]
</span>emptyList = </span>[]
</span></code></pre>
...and here it combined with another List</code> and achieving absolutely nothing.</p>
addNothing </span>::</span> [</span>Int</span>]
</span>addNothing = [</span>1</span>,</span>2</span>,</span>3</span>] ++ emptyList
</span>-- addNothing == [1,2,3]
</span></code></pre>
Defining a List Monoid</h3>
So we need to make a List Monoid</code> then?</p>

An operation called mappend</code> for combining two values - here ++</code> will do the trick.</li>
An empty value called mempty</code> - here we would use []</code>.</li>
</ol>
Here goes:</p>
instance Semigroup</span> [</span>a</span>] </span>where
</span>  a <> b = a ++ b
</span>
</span>instance Monoid</span> [</span>a</span>] </span>where
</span>  mempty = </span>[]
</span></code></pre>
Great stuff!</p>
We get mconcat for free</h3>
Once we've defined that, we get mconcat</code> (or rather our nice combineList1</code>) for free! All it does is a fold, starting with mempty</code> and then applying mappend</code> to each element in the list. Great!</p>
Combining Numbers</h3>
The empty element is interesting on our number Semigroup</code> instances from before too.</p>
Addition works like this, with an empty element of 0</code>.</p>
newtype </span>MySum</span> a = </span>MySum</span> {
</span>    </span>getMySum </span>:: </span>a
</span>}
</span>
</span>instance</span> (</span>Num </span>a</span>) </span>=> Semigroup</span> (</span>MySum </span>a</span>) </span>where
</span>    </span>MySum</span> a <> </span>MySum</span> b = </span>MySum</span> (a + b)
</span>
</span>instance</span> (</span>Num </span>a</span>) </span>=> Monoid</span> (</span>MySum </span>a</span>) </span>where
</span>    mempty = </span>MySum 0
</span>
</span>ten </span>:: Int
</span>ten = getMySum $ </span>MySum 1 </span><> </span>MySum 7 </span><> </span>MySum 2
</span>-- ten == 10
</span></code></pre>
Why zero? Because adding 0 to a number does nothing!</p>
Multiplication is not the same though.</p>
newtype </span>MyProduct</span> a = </span>MyProduct</span> {
</span>    </span>getMyProduct </span>:: </span>a
</span>}
</span>
</span>instance</span> (</span>Num </span>a</span>) </span>=> Semigroup</span> (</span>MyProduct </span>a</span>) </span>where
</span>    </span>MyProduct</span> a <> </span>MyProduct</span> b = </span>MyProduct</span> (a * b)
</span>
</span>instance</span> (</span>Num </span>a</span>) </span>=> Monoid</span> (</span>MyProduct </span>a</span>) </span>where
</span>    mempty = </span>MyProduct 1
</span>
</span>sixtySix </span>:: Int
</span>sixtySix = getMyProduct $ </span>MyProduct 11 </span><> </span>MyProduct 2 </span><> </span>MyProduct 3
</span>-- sixtySix == 66
</span></code></pre>
Here the mempty</code> value must be 1, because multiplying anything by 1</code> changes nothing.</p>
So What Does It All Mean?</h3>
This all seems a lot of work to get a free mconcat</code> function, but the Monoid</code> typeclass really comes into it's own when used with stuff like Foldable</a>. Just by adding this empty value we get a hell of a lot more "for free", as such.</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Data.Monoid on Hackage</a></p>
5 minutes to Monoids</a></p>
Monoids tour on School of Haskell</a></p>


Typeclasses - Semigroup
Unknown — Thu, 03 Jan 2019 00:00:00 +0000
Let's think about things that can be put together.</p>
Here's two lists, combined into one big list.</p>
list </span>::</span> [</span>Int</span>]
</span>list = [</span>1</span>,</span>2</span>,</span>3</span>] ++ [</span>4</span>,</span>5</span>,</span>6</span>]
</span>-- list == [1,2,3,4,5,6]
</span></code></pre>
Great!</p>
What about two strings combined into one large excellent string?</p>
string </span>:: String
</span>string = "</span>Great</span>" ++ "</span> Stuff</span>"
</span>-- string == "Great Stuff"
</span></code></pre>
Sure! Seems great. String</code> is actually a List</code> of Char</code> so really that's just the same thing happening twice there. So what's Semigroup</code> got to do with this? Semigroup</code> is the generalisation of combining things together. How is it defined?</p>
Definition</h3>
Prelude</span>> :i </span>Semigroup
</span></code></pre>
...gets us...</p>
class </span>Semigroup </span>a </span>where
</span>  </span>(<>) </span>:: </span>a </span>-> </span>a </span>-> </span>a
</span>  {-# </span>MINIMAL</span> (<>) #-}
</span></code></pre>
So by the looks we can just define it with the <></code> function.</p>
Therefore we could write our string concat function as "Great" <> "Job"</code> or combine lists like [1,2,3] <> [4,5,6]</code>.</p>
It doesn't just involve putting sets of things together.</p>
Maybe Semigroup</h3>
Let's define our own datatype MyMaybe</code> which you may notice is very similar to Maybe</code>. The Semigroup</code> instance can be used to combine two of them.</p>
data </span>MyMaybe</span> a = </span>Yeah</span> a | </span>Nope
</span></code></pre>
What's interesting about this one is that by insisting that the value inside is also a Semigroup</code>, we can do some exciting multi-level combining.</p>
instance</span> (</span>Semigroup </span>a</span>) </span>=> Semigroup</span> (</span>MyMaybe </span>a</span>) </span>where
</span>  (</span>Yeah</span> a) <> (</span>Yeah</span> b) = </span>Yeah</span> (a <> b)
</span>  a        <> </span>Nope     </span>= a
</span>  </span>Nope     </span><> b        = b
</span></code></pre>
Let's see it at work.</p>
nah </span>:: MyMaybe String
</span>nah = </span>Nope </span><> </span>Nope
</span>-- nah == Nope
</span></code></pre>
Sure.</p>
first </span>:: MyMaybe String
</span>first = </span>Yeah </span>"</span>Totally</span>" <> </span>Nope
</span>-- first == Yeah "Totally"
</span></code></pre>
Plausible.</p>
second </span>:: MyMaybe String
</span>second = </span>Nope </span><> </span>Yeah </span>"</span>Great</span>"
</span>-- second == Yeah "Great"
</span></code></pre>
OK.</p>
And the more interesting one...</p>
both </span>:: MyMaybe String
</span>both = </span>Yeah </span>"</span>Totally</span>" <> </span>Yeah </span>"</span>Great</span>"
</span>-- both = Yeah "TotallyGreat"
</span></code></pre>
What happened here? We combined two MyMaybe</code> values AND the String</code> values inside them as well, without really putting much effort in whatsoever. Great job, Semigroup</code>.</p>
Sum Semigroup</h3>
We can also use this pattern to describe combining numbers. Integers, for instance, can form several Monoids. One is addition. Let's build a newtype</a> so that we can make a Semigroup</code> instance.</p>
newtype </span>MySum</span> a = </span>MySum</span> {
</span>    </span>getMySum </span>:: </span>a
</span>}
</span></code></pre>
Here is a Semigroup</code> instance, it uses pattern matching to take the original values out, adds them together, them wraps them in another MySum</code> instance.</p>
instance</span> (</span>Num </span>a</span>) </span>=> Semigroup</span> (</span>MySum </span>a</span>) </span>where
</span>    </span>MySum</span> a <> </span>MySum</span> b = </span>MySum</span> (a + b)
</span></code></pre>
We can create several MySum</code> instances, and then combine them together with <></code>.</p>
ten </span>:: MySum Int
</span>ten = </span>MySum 1 </span><> </span>MySum 7 </span><> </span>MySum 2
</span>-- ten == MySum 10
</span></code></pre>
Or we could use the getMySum</code> function in the newtype to unwrap it.</p>
anotherTen </span>:: Int
</span>anotherTen = getMySum $ </span>MySum 1 </span><> </span>MySum 7 </span><> </span>MySum 2
</span>-- anotherTen == 10
</span></code></pre>
(This is obviously quite an overwrought way to add 3 numbers together)</p>
Product Semigroup</h3>
We could also combine numbers by multiplying them together.</p>
newtype </span>MyProd</span> a = </span>MyProd</span> {
</span>    </span>getMyProd </span>:: </span>a
</span>}
</span></code></pre>
instance</span> (</span>Num </span>a</span>) </span>=> Semigroup</span> (</span>MyProd </span>a</span>) </span>where
</span>    </span>MyProd</span> a <> </span>MyProd</span> b = </span>MyProd</span> (a * b)
</span></code></pre>
sixtySix </span>:: Prod Int
</span>sixtySix = </span>MyProd 11 </span><> </span>MyProd 2 </span><> </span>MyProd 3
</span>-- sixtySix = Prod 66
</span></code></pre>
anotherSixtySix </span>:: Int
</span>anotherSixtySix = getMyProd $ </span>MyProd 11 </span><> </span>MyProd 2 </span><> </span>MyProd 3
</span>-- anotherSixtySix = 66
</span></code></pre>
So, yes.</h3>
Hopefully you get the idea of what's going on here. A Semigroup</code> is a nice way of describing things we can smash together, and it becomes even better when we extend it into Monoid</code>, that gets us a load of Foldable</code> stuff for free. We'll come to that soon...</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Data.Semigroup</a></p>


My First Haskell Project - Part 1
Unknown — Wed, 26 Dec 2018 00:00:00 +0000
I have not always found it clear how to get started with Haskell, and I have a small library I want to make as an experiment so I figured I'd document the process as a sort of Getting Started. The tiny library I wish to make is for reading environment variables, which can be used for database connections or similar. I use MacOS but will try not to make anything too platform specific, and link to docs where info for other systems can be found where possible.</p>
First, let's assume we have nothing Haskell-based on the system whatsoever, and start by installing Stack.</p>
On MacOS this is as easy as running</p>
brew</span> install stack
</span></code></pre>
but for other systems you will need to look at the Stack docs</a>.</p>
Assuming that's all gone swimmingly, let's start a new project, which we will call simple-env</code>.</p>
stack</span> new simple-env
</span></code></pre>
This will create a new folder called simple-env</code> containing the following:</p>
.gitignore
</span>ChangeLog.md
</span>LICENSE
</span>README.md
</span>Setup.hs
</span>app
</span>package.yaml
</span>simple-env.cabal
</span>src
</span>stack.yaml
</span>test
</span></code></pre>
Looks great. There are two files here that describe our project... simple-env.cabal</code> generated by Cabal, and package.yaml</code> generated by Stack. Don't make the mistake I made and change the Cabal one directly - instead use package.yaml</code> as the source of truth and allow Stack to auto-generate sensible .cabal</code> files.</p>
Here is our default package.yaml</code> file:</p>
name</span>: </span>simple-env
</span>version</span>: </span>0.1.0.0
</span>github</span>: "</span>githubuser/simple-env</span>"
</span>license</span>: </span>BSD3
</span>author</span>: "</span>Author name here</span>"
</span>maintainer</span>: "</span>example@example.com</span>"
</span>copyright</span>: "</span>2018 Author name here</span>"
</span>
</span>extra-source-files</span>:
</span>  - </span>README.md
</span>  - </span>ChangeLog.md
</span>
</span># Metadata used when publishing your package
</span># synopsis:            Short description of your package
</span># category:            Web
</span>
</span># To avoid duplicated efforts in documentation and dealing with the
</span># complications of embedding Haddock markup inside cabal files, it is
</span># common to point users to the README.md file.
</span>description</span>: </span>Please see the README on GitHub at <https://github.com/githubuser/simple-env#readme>
</span>
</span>dependencies</span>:
</span>  - </span>base >= 4.7 && < 5
</span>
</span>library</span>:
</span>  </span>source-dirs</span>: </span>src
</span>
</span>executables</span>:
</span>  </span>simple-env-exe</span>:
</span>    </span>main</span>: </span>Main.hs
</span>    </span>source-dirs</span>: </span>app
</span>    </span>ghc-options</span>:
</span>      - </span>-threaded
</span>      - </span>-rtsopts
</span>      - </span>-with-rtsopts=-N
</span>    </span>dependencies</span>:
</span>      - </span>simple-env
</span>
</span>tests</span>:
</span>  </span>simple-env-test</span>:
</span>    </span>main</span>: </span>Spec.hs
</span>    </span>source-dirs</span>: </span>test
</span>    </span>ghc-options</span>:
</span>      - </span>-threaded
</span>      - </span>-rtsopts
</span>      - </span>-with-rtsopts=-N
</span>    </span>dependencies</span>:
</span>      - </span>simple-env
</span></code></pre>
If you're familar with the Javascript world, this isn't a million miles away from a package.json</code> file.</p>
We aren't going to need any new libraries for our project, but it seems sensible to explain how that's done. Let's install contravariant</a> package, because why not.</p>
Let's add it to here:</p>
dependencies</span>:
</span>  - </span>base >= 4.7 && < 5
</span></code></pre>
so we have</p>
dependencies</span>:
</span>  - </span>base >= 4.7 && < 5
</span>  - </span>contravariant
</span></code></pre>
We don't mind what version in this case - Stack will choose us a sensible one that fits with our other dependencies, that's what it's for.</p>
Let's run</p>
stack</span> build
</span></code></pre>
and watch the action.</p>
The first time you run this on any given project, Stack will download the GHC compiler and all the libraries so you may wish to take a break and go and read War and Peace or something. After the initial wait subsequent builds will be very quick, but this one is a bit of a stinker.</p>
Ok. Great, we have filled our hard drive with nonsense and we are ready to Haskell.</p>
What else have we got in this folder?</p>
Firstly, we have the app</code> folder which contains one file, Main.hs</code>. This is the entry-point to our application, and looks like this:</p>
module </span>Main </span>where
</span>
</span>import </span>Lib
</span>
</span>main </span>:: IO </span>()
</span>main = someFunc
</span></code></pre>
When a Haskell program is run the main</code> function in a module called Main</code> is run, and then it is responsible for everything else that happens. Therefore we can deduce that this program is importing someFunc</code> from somewhere and running that. Seems plausible. Let's run it and see what happens.</p>
If we look back in package.yaml</code> we have a section that looks like this:</p>
executables</span>:
</span>  </span>simple-env-exe</span>:
</span>    </span>main</span>: </span>Main.hs
</span>    </span>source-dirs</span>: </span>app
</span>    </span>ghc-options</span>:
</span>      - </span>-threaded
</span>      - </span>-rtsopts
</span>      - </span>-with-rtsopts=-N
</span>    </span>dependencies</span>:
</span>      - </span>simple-env
</span></code></pre>
What it telling us? Well, a bunch of things, but two that stick out.</p>

Firstly, yes, our assumptions were correct - our main source directory is app</code> and the main file is Main.hs</code>.</li>
Secondly, that our executable file is called simple-env-exe</code></li>
</ol>
Let's run it then!</p>
stack</span> exec simple-env-exe
</span></code></pre>
It should just print "someFunc" to the screen and exit, which is admittedly quite underwhelming.</p>
We can do better than this.</p>
So it looks like someFunc</code> is a function in src/Lib.hs</code>. The whole file looks like this. Let's start work in here.</p>
module </span>Lib
</span>    ( </span>someFunc
</span>    ) </span>where
</span>
</span>someFunc </span>:: IO </span>()
</span>someFunc = putStrLn "</span>someFunc</span>"
</span></code></pre>
Our library is going to extract environment variables so they can be used in programs. This is helpful for stuff like database credentials that we don't want to save in version control.</p>
Here is the MVP version:</p>
module </span>Lib
</span>    ( </span>someFunc
</span>    ) </span>where
</span>
</span>import           </span>System.Environment (</span>lookupEnv</span>)
</span>
</span>someFunc </span>:: IO </span>()
</span>someFunc = </span>do
</span>    testValue <- lookupEnv "</span>TEST_VALUE</span>"
</span>    putStrLn (showResult testValue)
</span>
</span>showResult </span>:: Maybe String -> String
</span>showResult maybeValue = </span>case</span> maybeValue </span>of
</span>    </span>Just</span> value -> "</span>TEST_VALUE</span>" ++ "</span>: </span>" ++ value
</span>    _          -> "</span>TEST_VALUE could not found!</span>"
</span></code></pre>
Let's take this apart a bit.</p>
import           </span>System.Environment (</span>lookupEnv</span>)
</span></code></pre>
Firstly, we have an import. We are using the lookupEnv</code> function from System.Environment. If we look in the docs for it in Hackage</a> we can see it has the following type signature:</p>
lookupEnv </span>:: String -> IO</span> (</span>Maybe String</span>)
</span></code></pre>
This means we need to give it a String</code> (the name of the environment variable we wish to check for) and it will return a Maybe String</code>. This means if it CAN find a String</code> it will return it, if not, it won't explode or anything, which is handy. However, that Maybe String</code> is wrapped in an IO</code>. What does this mean?</p>
It means that this function needs to do interaction with the outside world, therefore it must also be run from another IO</code> function using bind</code>. Think of IO</code> like the electricity that allows access to side-effects and the outside world. It's where the problems are most likely to come from, so Haskell forces us to be very explicit about where it is and more importantly, where it isn't. Our main</code> functions have access to IO</code>, and they must pass the IO</code>-ness to wherever else needs it.</p>
Opinionated note: IO</code> is one of the more complicated parts of Haskell, and it's somewhat unfortunate for adoption of the language that we have to deal with it in the first lines of any program. I would wager that this is why so many tutorials and books start with hacking in the ghci</code> repl instead, as it saves having to have The IO Chat. I am a firm believer in uncomfortable truths, moreso if they are explained terribly like this, but if you are starting out, feel utterly free just to accept this part is a bit weird, learn to live with it, and come back to in depth later. The IO</code> concept really is quite a good thing, it just presents something of a Learning Kerb.</p>
We also have a helper function called showResult</code>.</p>
showResult </span>:: Maybe String -> String
</span>showResult maybeValue = </span>case</span> maybeValue </span>of
</span>    </span>Just</span> value -> "</span>TEST_VALUE</span>" ++ "</span>: </span>" ++ value
</span>    _          -> "</span>TEST_VALUE could not found!</span>"
</span></code></pre>
This function just takes our Maybe String</code> and turns it into a String</code> ready for us to print to the console. It uses pattern matching of the maybeValue</code> to display either the result (value</code>) that the environment variable was set to, or a fallback message. Therefore we should get:</p>
showResult (</span>Just </span>"</span>horses</span>")
</span>-- "TEST_VALUE: horses"
</span>
</span>showResult (</span>Nothing</span>)
</span>-- "TEST_VALUE could not be found!
</span></code></pre>
Pretty OK, huh?</p>
OK, lastly the glue function, someFunc</code>.</p>
someFunc </span>:: IO </span>()
</span>someFunc = </span>do
</span>    testValue <- lookupEnv "</span>TEST_VALUE</span>"
</span>    putStrLn (showResult testValue)
</span></code></pre>
What's the deal here? Ok. So firstly, the Do</code> - it says that we're starting some Do notation</code> which allows us to write in a slightly more imperative style. Like the IO</code> concept in general it's a bit of a heavy concept to throw at beginners in the first few lines so let's also make a mental note to just nod and come back to the concept later. Again, it is a pretty neat thing, but confusing to start with.</p>
Moving on, this line is more interesting:</p>
testValue <- lookupEnv "</span>TEST_VALUE</span>"
</span></code></pre>
So as discussed earlier, our lookupEnv</code> takes a String</code> (in this case "TEST_VALUE") and returns Maybe String</code> wrapped in IO</code>. This <-</code> pulls it out of the IO</code> so that in effect, this line is setting testValue</code> to Maybe String</code>. If lookupEnv</code> finds an environment variable called "TEST_VALUE" then testValue</code> will be Just "whatever_the_value_was"</code>, but if it fails, it'll be Nothing</code>. Note that we were only able to even use the lookupEnv</code> function because someFunc</code> is also an IO</code> function, so in effect we have passed the IO</code> power along to lookupEnv</code> to let it do it's magic.</p>
Great stuff. We have done a thing. Now let's tell our wonderful user all about it.</p>
putStrLn (showResult testValue)
</span></code></pre>
OK. So this line just takes testValue</code> (a Maybe String</code>), uses showResult</code> to turn it into a nice String</code> that tells us what happened, and then uses putStrLn</code> (put string line) to show it on the screen. putStrLn</code> is another IO</code> action, with this type signature:</p>
putStrLn </span>:: String -> IO </span>()
</span></code></pre>
This means it takes a String</code>, and then returns ()</code> (unit, the nothing value) inside an IO</code>. Again, it must be run inside another IO</code> context to get it's "power", as such. Also, the fact it returns ()</code> is helpful - our someFunc</code> is of type IO ()</code> meaning it should also return nothing, so putStrLn</code> is also doing that for us. Tidy.</p>
Great stuff.</p>
Let's try our program.</p>
stack</span> build
</span>stack</span> exec simple-env-exe
</span></code></pre>
Assuming you've not got an environment variable called "TEST_VALUE" set you should see:</p>
stack</span> exec simple-env-exe
</span>"</span>TEST_VALUE could not found!</span>"
</span></code></pre>
Let's set one (assuming you're in Bash or Zsh):</p>
export </span>TEST_VALUE</span>="</span>horses!</span>"
</span></code></pre>
...and run the program again.</p>
stack</span> exec simple-env-exe
</span>"</span>TEST_VALUE: horses!</span>"
</span></code></pre>
Great stuff. It's not much of a library, but it's a start. Next time we'll make a nicer API for fetching multiple variables at once so it's actually a bit more helpful for our users.</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
The Haskell Stack Tool</a></p>
System.Environment</a></p>
Intro to IO</a></p>
System.IO</a></p>
Learn You A Haskell: IO</a></p>


Typeclasses - Traversable
Unknown — Sat, 22 Dec 2018 00:00:00 +0000
Let's think about Trees.</p>
data </span>MyTree</span> a = </span>Leaf</span> a | </span>Branch</span> (</span>MyTree</span> a) (</span>MyTree</span> a)
</span></code></pre>
A tree can be either a Leaf</code> with contains some of value, or a Branch that has two slots for either another Branch</code> or perhaps a Leaf</code>.</p>
We can build up a tree like this:</p>
sampleTree </span>:: MyTree Int
</span>sampleTree = </span>Branch</span> (</span>Branch</span> (</span>Leaf 2</span>) (</span>Leaf 3</span>)) (</span>Branch</span> (</span>Leaf 5</span>) (</span>Leaf 2</span>))
</span></code></pre>
So if you remember way back when when we talked about foldable</a>, we can very easily teach this MyTree</code> type we have created to fold over itself and do handy things.</p>
instance Foldable MyTree where
</span>  foldMap f (</span>Branch</span> l r) = (foldMap f l) <> (foldMap f r)
</span>  foldMap f (</span>Leaf</span> a) = f a
</span></code></pre>
Then we can ask it to do helpful things like add up all the values in the tree.</p>
sampleTreeTotal </span>:: Int
</span>sampleTreeTotal = getSum $ foldMap </span>Sum</span> sampleTree
</span>-- sampleTreeTotal == 12
</span></code></pre>
Great!</p>
This is all very well and good, but what if our tree contains more complex types that just a number? It is entirely plausible to end up with a bunch of optional values like this:</p>
maybeTree </span>:: MyTree</span> (</span>Maybe Int</span>)
</span>maybeTree = </span>Branch</span> (</span>Branch</span> (</span>Leaf </span>$ </span>Just 2</span>) (</span>Leaf </span>$ </span>Just 3</span>)) (</span>Branch</span> (</span>Leaf </span>$ </span>Just 5</span>) (</span>Leaf </span>$ </span>Just 2</span>))
</span></code></pre>
We could add up all the values without too much trouble, but what if we want to remove all the Just</code> and Nothing</code> from the MyTree</code> but keep the structure intact? Enter Traversal</code>!</p>
Traversable</h3>
What does ghci</code> have to say about it?</p>
*</span>Main</span>> :i </span>Traversable
</span></code></pre>
class</span> (</span>Functor </span>t</span>, </span>Foldable </span>t</span>) => </span>Traversable</span> (</span>t</span> :: * -> *) </span>where
</span>  </span>traverse </span>:: Applicative </span>f </span>=></span> (</span>a </span>-> </span>f b</span>) </span>-> </span>t a </span>-> </span>f</span> (</span>t b</span>)
</span>  </span>sequenceA </span>:: Applicative </span>f </span>=> </span>t</span> (</span>f a</span>) </span>-> </span>f</span> (</span>t a</span>)
</span>  {-# </span>MINIMAL</span> traverse | sequenceA #-}
</span></code></pre>
A few things here:</p>

The (Functor t, Foldable t) =></code> part means we'll need to create Foldable</code> and Functor</code> instances for our datatype before it's allowed to be Traversable</code> too.</li>
The Applicative f =></code> part means whichever other type we use it with must have an instance of Applicative</code>. Fortunately many useful typeclasses are.</li>
We can implement either traverse</code> or sequenceA</code> and the rest will sort itself out.</li>
</ol>
We'll choose traverse</code> for our example.</p>
Firstly, let's make a Functor</code> instance for MyTree</code>. Nothing untoward here, we just recurse through the tree and run f</code> on any a</code>s we find laying around. We'll not need to use this directly ourselves but it be used internally by other functions.</p>
instance Functor MyTree where
</span>  fmap f (</span>Branch</span> l r) = </span>Branch</span> (fmap f l) (fmap f r)
</span>  fmap f (</span>Leaf</span> a) = </span>Leaf</span> (f a)
</span></code></pre>
Now let's implement a Traversable</code> instance for MyTree</code>.</p>
instance Traversable MyTree where
</span>  traverse f (</span>Branch</span> l r) = </span>Branch </span><$> (traverse f l) <*> (traverse f r)
</span>  traverse f (</span>Leaf</span> a) = </span>Leaf </span><$> f a
</span></code></pre>
A few notes here:</p>

<$></code> is the infix version of fmap</code>. (+1) <$> Just 2</code> is the same as fmap (+1) Just 2</code>. Writing it this way shows us how similar it is to the functor</code> instance.</li>
<*></code> is the infix version of apply</code> from Applicative</code>. Our Applicative f =></code> constraint means this is supplied by whichever Applicative</code> we are using in this function. As we will see, this means different applicatives give us very different outcomes.</li>
</ol>
It's perhaps not the most intuitive thing to look at and understand, so let's try using and see what's up. Although we've implemented the typeclass using traverse</code>, the more intuitive function it provides us is sequence</code>, which is sort of a "swap the types around" function. Let's try it with a few different instances of Applicative</code> to get a feel for it.</p>
Maybe</h3>
Although we just casually used Maybe</code>, earlier, let's clarify what it is. The type definition looks something like this:</p>
data </span>Maybe</span> a = </span>Just</span> a | </span>Nothing
</span></code></pre>
It is just for holding a value that might be there (Just "i am a value"</code>) or expressing a lack of value (Nothing</code>). Let's put some in our MyTree</code>.</p>
maybeTree </span>:: MyTree</span> (</span>Maybe Int</span>)
</span>maybeTree = </span>Branch</span> (</span>Branch</span> (</span>Leaf </span>$ </span>Just 2</span>) (</span>Leaf </span>$ </span>Just 3</span>)) (</span>Branch</span> (</span>Leaf </span>$ </span>Just 5</span>) (</span>Leaf </span>$ </span>Just 2</span>))
</span></code></pre>
...and use sequence</code> to pull them out and wrap the whole thing in a Maybe</code> instead.</p>
justTree </span>:: Maybe</span> (</span>MyTree Int</span>)
</span>justTree = sequence maybeTree
</span>-- justTree == Just (Branch (Branch (Leaf 2) (Leaf 3)) (Branch (Leaf 5) (Leaf 2)))
</span></code></pre>
What's gone on here then? All of the Just</code> values inside the tree have gone, but have been replaced with a single Just</code> at the start. If you squint, it kind of looks like we've turned the types inside out, and we kind of have. If this seems a bit odd to comprehend, it might remind you of this javascript:</p>
const </span>promise1 </span>= </span>Promise</span>.</span>resolve</span>("</span>yeah</span>")
</span>const </span>promise2 </span>= </span>Promise</span>.</span>resolve</span>("</span>great</span>")
</span>
</span>Promise</span>.</span>all</span>([</span>promise1</span>, </span>promise2</span>]).</span>then</span>(</span>as </span>=> </span>{
</span>  </span>console</span>.</span>log</span>(</span>as</span>); </span>// ["yeah", "great"]
</span>})
</span></code></pre>
Here we can taken an array of Promises, and returned a single Promise returning an array of values. However, what happens if one of those promises fails?</p>
const </span>promise1 </span>= </span>Promise</span>.</span>resolve</span>("</span>yeah</span>")
</span>const </span>promise2 </span>= </span>Promise</span>.</span>reject</span>("</span>great</span>")
</span>
</span>Promise</span>.</span>all</span>([</span>promise1</span>, </span>promise2</span>]).</span>then</span>(</span>as </span>=> </span>{
</span>  </span>// never happens!
</span>}).</span>catch</span>(() </span>=> </span>{
</span>  </span>console</span>.</span>log</span>('</span>everything went terribly wrong</span>')
</span>})
</span></code></pre>
It short circuits and fails! Going back to our tree, let's try putting a Nothing</code> in there and see how that changes things.</p>
nothingTree </span>:: Maybe</span> (</span>MyTree Int</span>)
</span>nothingTree = sequence </span>Branch</span> (</span>Leaf Nothing</span>) (</span>Leaf </span>$ </span>Just 3</span>))
</span>-- nothingTree == Nothing
</span></code></pre>
Ok! So the same behaviour! Why is that though? There's nothing in our MyTree</code> structure that does any checking of these sorts of things.</p>
The key here is in how apply</code> (or <*></code>) is implemented in Maybe</code> itself:</p>
instance Applicative Maybe where
</span>    pure = </span>Just
</span>
</span>    </span>Just</span> f  <*> m      = fmap f m
</span>    </span>Nothing </span><*> _      = </span>Nothing
</span></code></pre>
Basically, as soon as we find any Nothing</code>, whatever we're doing becomes Nothing</code>, so therefore Maybe</code> is giving us our same short-circuiting behaviour from the javascript Promise.</p>
Good? Great. Let's look at another.</p>
List</h3>
List</code> is another interesting Applicative</code> in that it treats every list like a set of possibilities.</p>
It's defined as something like this:</p>
data </span>List</span> a = </span>Cons</span> a (</span>List</span> a) | </span>Nil
</span></code></pre>
Look what happens when we sequence</code> this small tree that contains a List</code> in each of it's leaves...</p>
invertedListTree </span>::</span> [</span>MyTree Int</span>]
</span>invertedListTree = sequence </span>Branch</span> (</span>Leaf</span> [</span>1</span>,</span>2</span>]) (</span>Leaf</span> [</span>3</span>,</span>4</span>])
</span>{-
</span>invertedListTree ==
</span>  [ Branch (Leaf 1) (Leaf 3)
</span>  , Branch (Leaf 1) (Leaf 4)
</span>  , Branch (Leaf 2) (Leaf 3)
</span>  , Branch (Leaf 2) (Leaf 4)
</span>  ]
</span>-}
</span></code></pre>
It returns a List</code> of every possible MyTree Int</code> that could be made using the items in each list. If you look at the page on applicative</a> - particularly the applicativeList</code> - this may make more sense.</p>
This sequence</code> function we are using is merely traverse id</code> by the way - so we can start to mess with it even more by using traverse</code> with different functions. By passing the reverse</code> function, we can get the same thing but backwards...</p>
reversedListTree </span>::</span> [</span>MyTree Int</span>]
</span>reversedListTree = traverse reverse listTree
</span>{-
</span>reversedListTree ==
</span>  [ Branch (Leaf 2) (Leaf 4)
</span>  , Branch (Leaf 2) (Leaf 3)
</span>  , Branch (Leaf 1) (Leaf 4)
</span>  , Branch (Leaf 1) (Leaf 3)
</span>]
</span>-}
</span></code></pre>
(Why? I don't know, it's difficult coming up with useful examples all the time, give me a break.)</p>
What about Either</code>?</p>
Either</h3>
Either</code> is used to express a value that could be one of two things. It's datatype looks something like:</p>
data </span>Either</span> a b = </span>Left</span> a | </span>Right</span> b
</span></code></pre>
Left</code> usually expresses an error or something, whilst Right</code> expresses everything being somewhat Hunky Dory.</p>
What happens when all the values are Right</code>?</p>
rightTree </span>:: Either String</span> (</span>MyTree Int</span>)
</span>rightTree = sequence </span>Branch</span> (</span>Leaf </span>$ </span>Right 100</span>) (</span>Leaf </span>$ </span>Right 200</span>)
</span>-- rightTree == Right (Branch (Leaf 100) (Leaf 200))
</span></code></pre>
OK, that seems reasonable, just like the Maybe</code> really.</p>
What about if we throw a Left</code> in there?</p>
failsTree </span>:: Either String</span> (</span>MyTree Int</span>)
</span>failsTree = sequence $ </span>Branch</span> (</span>Leaf </span>$ </span>Right 1</span>) (</span>Leaf </span>$ </span>Left </span>"</span>2</span>")
</span>-- failsTree == Left "2"
</span></code></pre>
OK - we get the Left</code> value back, which seems reasonable (especially looking at the type signature of our new structure).</p>
What about if there are multiple Left</code> values inside?</p>
failsTree2 </span>:: Either String</span> (</span>MyTree Int</span>)
</span>failsTree2 = sequence $ </span>Branch</span> (</span>Leaf </span>$ </span>Left </span>"</span>1</span>") (</span>Branch</span> (</span>Leaf </span>$ </span>Left </span>"</span>2</span>") (</span>Leaf </span>$ </span>Left </span>"</span>3</span>"))
</span>-- failsTree2 == Left "1"
</span></code></pre>
Oh. That seems somewhat counterintuitive. Even though we have many Left</code> items in our tree, when we sequence</code> them we only get the first one back. If you want to know why - sure - it's because of the way Either</code> implements the <*></code> function. Is there an alterntaive in which we get more of the Left</code> items back? Yes - see the bonus item at the bottom of the page.</p>
So what does this mean?</h3>
Basically (lol), what these examples hopefully start to show is that traverse</code> let's us combine different types together. Whilst Foldable</code> used a Monoid</code> instance to combine values together with <></code>, Traversable</code> lets us combine them together using their Applicative</code> instance and <*></code>. Applicative</code> is a pretty powerful typeclass that let's us do a lot of wild shit, so Traversable</code> ends up pretty powerful as a result. A lot of the Lens</code> package uses Traversable</code>, so understanding this gives you a much better idea of what's doing.</p>
There are plenty of Traversable</code> instances in the wild to play with, so try smashing a few things together and see what happens. In case it's not entirely obvious, that's basically all I did in writing this article.</p>
Anyhow, that's enough for now I think.</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Data.Traversable</a></p>
Bonus item: Validation</h3>
If you were enjoying the Either</code> example but wondering if there's a way to gather all of the Left</code> values in a tree, then, firstly, yes, and secondly, it's done using a different datatype called Validation</code>. We won't go into it in depth now, but it's much like an Either</code> that let's you collect Left</code> items together.</p>
validationTree </span>:: MyTree</span> (</span>Validation</span> [</span>String</span>] </span>Int</span>)
</span>validationTree = </span>Branch</span> (</span>Leaf </span>$ </span>Success 100</span>) (</span>Branch</span> (</span>Leaf </span>$ </span>Failure</span> ["</span>2</span>"]) (</span>Leaf </span>$ </span>Failure</span> ["</span>3</span>"]))
</span></code></pre>
collectFails </span>:: Validation</span> [</span>String</span>] (</span>MyTree Int</span>)
</span>collectFails = traverse id validationTree
</span>-- collectFails == Failure ["2","3"]
</span></code></pre>


Why The Hell Should I Care About Newtypes?
Unknown — Wed, 19 Dec 2018 00:00:00 +0000
Good question. What are newtypes</code>?</p>
You see them in Haskell a lot. Here's one.</p>
newtype </span>Dog</span> a = </span>Dog</span> { getDog :: a }
</span></code></pre>
We can make a Dog</code> as a container for a thing (in this case, a String</code>)</p>
frank </span>:: Dog String
</span>frank = </span>Dog </span>"</span>Frank</span>"
</span>-- frank == Dog "Frank"
</span></code></pre>
Or we can unwrap it again and lose nothing along the way (this means the types String</code> and Dog String</code> are isomorphic</code> in maths terms)</p>
name </span>:: String
</span>name = getDog frank
</span>-- name == "Frank"
</span></code></pre>
In short, they are basically the same thing. Once compiled in fact, they're exactly the same, so there's no cost to all this, computationally.</p>
itsTheSame </span>:: Bool
</span>itsTheSame = "</span>Frank</span>" == getDog (</span>Dog </span>"</span>Frank</span>")
</span></code></pre>
So why do this?</p>
Well, the nice thing about a newtype</code> is that we can use it to pass data around with a bit more contextual information about what it means.</p>
Let's calculate a salary. That seems like a plausible thing to do with a computer.</p>
calculateSalaryBad </span>:: Int -> Int
</span>calculateSalaryBad months = months * </span>1000
</span></code></pre>
This function takes a number of months, and calculates how much this person should get paid, based on a salary of 1000</code> (of some unknown unit) a month.</p>
But what happens if we give it an invalid number of months?</p>
badAmount = calculateSalaryBad (-</span>100</span>)
</span>-- badAmount == -100000
</span></code></pre>
That's crazy talk! Surely this weird minus payment will send even the most well-meaning of accountants into a spin.</p>
Let's improve it a bit by checking if the number is negative.</p>
calculateSalaryBetter </span>::</span> (</span>Num </span>a</span>, </span>Ord </span>a</span>) </span>=> </span>a </span>-> Maybe </span>a
</span>calculateSalaryBetter i = </span>if</span> i < </span>0
</span>                        </span>then </span>Nothing
</span>                        </span>else </span>Just</span> (i * </span>1000</span>)
</span></code></pre>
Note that we're introducing the Ord</code> typeclass here, as we need to compare amounts. We don't mind what a</code> is as long as it is both a valid number (ie, in the Num</code> typeclass) and is orderable (ie, the Ord</code> typeclass).</p>
So now if we try this on a stupid amount, we get Nothing</code></p>
safeAmount = calculateSalaryBetter (-</span>100</span>)
</span>-- safeAmount = Nothing
</span></code></pre>
OK. Good stuff. That should stop the accounts department crying into their sensibly priced but ultimately unsatisfying packed lunches.</p>
The thing is, when we run this, we get this Just</code> wrapped around things.</p>
anAmount = calculateSalaryBetter </span>12
</span>-- anAmount == Just 12000
</span></code></pre>
This is fine in isolation, but if we wanted to do a lot of calculations here we don't want to be wrapping and unwrapping Maybe</code> values all over the place. It means mixing up our validation logic with our actual business logic or whatever, and that's Bad.</p>
What about a nice newtype</code> solution?</p>
newtype </span>PositiveNum</span> a = </span>PositiveNum</span> { getPositiveNum :: a } </span>deriving</span> (</span>Eq</span>, </span>Show</span>)
</span></code></pre>
Nothing to write home about so far, but the trick here is that Haskell allows us to export the type PositiveNum</code> but not the constructor PositiveNum</code>. That means that instead we can provide a function for making a PositiveNum</code> that does some validation. This means that, outside our module itself, there is no way to create a PositiveNum</code> that doesn't make sense.</p>
makePositiveNum </span>::</span> (</span>Num </span>a</span>, </span>Ord </span>a</span>) </span>=> </span>a </span>-> Maybe</span> (</span>PositiveNum </span>a</span>)
</span>makePositiveNum i
</span>    | i < </span>0 </span>= </span>Nothing
</span>    | otherwise = </span>Just</span> (</span>PositiveNum</span> i)
</span></code></pre>
It comes wrapped in a Maybe</code>, sure, but only one. It can be used over and over without needing validation, and once it is available it can be unwrapped with a quick getPositiveNum</code>.</p>
num </span>:: Int
</span>num = getPositiveNum (</span>PositiveNum 10</span>)
</span>-- num == 10
</span></code></pre>
Great stuff.</p>
Let's make a nicer salary calculator.</p>
calculateSalary </span>::</span> (</span>Num </span>a</span>) </span>=> PositiveNum </span>a </span>-> </span>a
</span>calculateSalary months = </span>1000</span> * (getPositiveNum months)
</span></code></pre>
Pretty OK. Let's bring it all together. First our library functions:</p>
makePositiveNum </span>::</span> (</span>Num </span>a</span>, </span>Ord </span>a</span>) </span>=> </span>a </span>-> Maybe</span> (</span>PositiveNum </span>a</span>)
</span>makePositiveNum i
</span>    | i < </span>0 </span>= </span>Nothing
</span>    | otherwise = </span>Just</span> (</span>PositiveNum</span> i)
</span>
</span>zero </span>::</span> (</span>Num </span>a</span>) </span>=> PositiveNum </span>a
</span>zero = </span>PositiveNum 0
</span></code></pre>
We've added zero</code> that just makes a default PositiveNum</code> with a value of 0</code> here, to use as a fallback if the value is ridiculous.</p>
Now we have a function for getting a PositiveNum</code> for our number of months:</p>
months </span>::</span> (</span>Num </span>a</span>, </span>Ord </span>a</span>) </span>=> </span>a </span>-> PositiveNum </span>a
</span>months i = fromMaybe zero (makePositiveNum i)
</span>
</span>yes </span>:: PositiveNum Int
</span>yes = months </span>12
</span>-- yes = PositiveNum 12
</span>
</span>nope </span>:: PositiveNum Int
</span>nope = months (-</span>12</span>)
</span>-- nope = PositiveNum 0
</span></code></pre>
Which we can use as follows:</p>
total = calculateSalary (months </span>12</span>)
</span>-- total == 12000
</span></code></pre>
Nice. By pushing all of the validation concerns into the months</code> function, our actual function is nice and simple and easy to understand. Also we have a nice re-usable tool, PositiveNum</code> that can be used across our project everytime we need some guarantees about a value.</p>
Bonus credit: Functor instance for a newtype</code>.</h3>
We can treat newtypes</code> like any other type, and create typeclass instances for them. For instance, we could create a functor</code> instance for PositiveNum</code> and do calculations inside it by mapping instead.</p>
instance Functor PositiveNum where
</span>    fmap f (</span>PositiveNum</span> i) = </span>PositiveNum</span> (f i)
</span></code></pre>
This lets us change the value inside PositiveNum</code> with an fmap</code> function.</p>
calculateSalaryClever </span>::</span> (</span>Num </span>a</span>) </span>=> PositiveNum </span>a </span>-> PositiveNum </span>a
</span>calculateSalaryClever = fmap (*</span>1000</span>)
</span>-- calculateSalaryClever 2 == PositiveNum 2000
</span></code></pre>
Or the same, but unwrap it afterwards:</p>
calculateSalaryClever2 </span>::</span> (</span>Num </span>a</span>) </span>=> PositiveNum </span>a </span>-> </span>a
</span>calculateSalaryClever2 i = getPositiveNum (fmap (*</span>1000</span>) i)
</span>-- calculateSalaryClever2 20 == 20000
</span></code></pre>
That seems pretty OK to me. Anyway, that's enough things, time for bed.</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Newtype in Haskell Wiki</a></p>
Newtypes aren't as cool as you think</a></p>


Why The Hell Should I Care About Lens? (Part 2)
Unknown — Tue, 18 Dec 2018 00:00:00 +0000
So last time we looked at lens</a> and saw had to jump into record-shaped structures and change things around like big hacker professionals. However we didn't try to change anything with a sum type</code> in it, like Either</code> or Maybe</code> or something. What can we use for that? Only a bloody Prism</code>, apparently.</p>
Here's an example sum type that can either contain a dog's name or it's age, and is in no way utterly contrived.</p>
data </span>DogFact </span>= </span>DogName String </span>| </span>DogAge Int
</span></code></pre>
Here are some examples of it is in use. Here it is valiantly holding a dog's name, a String</code>, with the DogName</code> constructor.</p>
spruceBruce </span>:: DogFact
</span>spruceBruce = </span>DogName </span>"</span>Spruce Bruce</span>"
</span></code></pre>
Great!</p>
And here, instead, is a dog's age, stored as an Int</code> inside DogAge</code>.</p>
oldDog </span>:: DogFact
</span>oldDog = </span>DogAge 100
</span></code></pre>
Excellent stuff, I'm sure you'll agree.</p>
Now, we could start making all our getters and settings by hand again like this...</p>
getDogNameFromDogFact </span>:: DogFact -> Maybe String
</span>getDogNameFromDogFact (</span>DogName</span> s) = </span>Just</span> s
</span>getDogNameFromDogFact _           = </span>Nothing
</span>
</span>getDogAgeFromDogFact </span>:: DogFact -> Maybe Int
</span>getDogAgeFromDogFact (</span>DogAge</span> s) = </span>Just</span> s
</span>getDogAgeFromDogFact _          = </span>Nothing
</span></code></pre>
...but I'm sure it's clear it's soon going to get quite verbose and we should probably use something more clever instead.</p>
Enter Prism</code>! (the crowd goes wild, etc.)</p>
A Prism</code> is like a Lens</code>, except it let's you peek into a particular part of a sum type</code>. Therefore we can make one Prism</code> that is interested in the name of dogs...</p>
dogNamePrism </span>:: Prism</span>' </span>DogFact String
</span>dogNamePrism = prism' </span>DogName</span> (\e -> </span>case</span> e </span>of
</span>                                </span>DogName</span> a -> </span>Just</span> a
</span>                                _         -> </span>Nothing</span>)
</span></code></pre>
...and another which only cares about the age of dogs...</p>
dogAgePrism </span>:: Prism</span>' </span>DogFact Int
</span>dogAgePrism = prism' </span>DogAge</span> (\e -> </span>case</span> e </span>of
</span>                              </span>DogAge</span> b -> </span>Just</span> b
</span>                              _        -> </span>Nothing</span>)
</span></code></pre>
OK. So how do we use them?</p>
In lens</code>, we had view</code> for peeking inside, set</code> for changing values, and over</code> for mapping over the values inside. What has Prism</code> got going on?</p>
preview</h3>
Unlike lens</code> which has set</code>, prism</code> has a good pal called preview</code> that it uses for checking out values. It returns the result inside a Maybe</code> as the value is not guaranteed to actually be there.</p>
dogAge </span>:: Maybe Int
</span>dogAge = preview dogAgePrism (</span>DogAge 100</span>)
</span>-- dogAge == Just 100
</span></code></pre>
That seems reasonable.</p>
What about running that on spruceBruce</code> (that is built from a DogName</code>)?</p>
notDogAge </span>:: Maybe Int
</span>notDogAge = preview dogAgePrism spruceBruce
</span>-- notDogAge == Nothing
</span></code></pre>
No dice. Zero dice. A complete lack of dice. No age, no int</code>, sorry.</p>
Maybe our dogNamePrism</code> can help though...?</p>
dogName </span>:: Maybe String
</span>dogName = preview dogNamePrism spruceBruce
</span>-- dogName == Just "Spruce Bruce"
</span></code></pre>
Yes! Good stuff. Does he work on ages though?</p>
notDogName </span>:: Maybe String
</span>notDogName = preview dogNamePrism (</span>DogAge 69</span>)
</span>-- notDogName == Nothing
</span></code></pre>
No. Damn.</p>
set</h3>
In lens</code> we used set</code> for changing the value of something nested. How does that work here?</p>
youngerDog </span>:: DogFact
</span>youngerDog = set dogAgePrism </span>27</span> (</span>DogAge 100</span>)
</span>-- youngerDog == DogAge 27
</span></code></pre>
All seems well here, pretty similar to a regular lens</code>. How about we give our dog a name instead of an age?</p>
noNewName </span>:: DogFact
</span>noNewName = set dogNamePrism "</span>Nice Name</span>" (</span>DogAge 100</span>)
</span>-- noNewName == DogAge 100
</span></code></pre>
What's happened here? Where is the name? We've ended up with exactly what we started with! How the hell do we give the dog a name? I must admit this confused me for quite a while, until I realised that Prism</code> is doing exactly as it should - letting us get at the values inside a sum type without changing it's structure.</p>
Therefore we can change one DogName</code> for another...</p>
newDogName </span>:: </span>dogFact
</span>newDogName = set dogNamePrism "</span>Excellent Bruce</span>" (</span>DogName </span>"</span>Steve</span>")
</span>-- newDogName == DogName "Excellent Bruce"
</span></code></pre>
...but not change the name of DogAge</code>.</p>
noNewDogName </span>:: </span>dogFact
</span>noNewDogName = set dogNamePrism "</span>Good Old Nigel</span>" (</span>DogAge 400</span>)
</span>-- noNewDogName == DogAge 400
</span></code></pre>
over</h3>
As well as inheriting set</code> from lens</code> the prism</code> also has over</code>, that lets us map a function over nested value.</p>
stillQuiteOldDog </span>:: DogFact
</span>stillQuiteOldDog = over dogAgePrism (-</span>1</span>) oldDog
</span>-- stillQuiteOldDog == DogAge 99
</span></code></pre>
When you think about how mapping a function doesn't change the structure around the value (hello, functor</code>) then the behaviour of set</code> that initially confused me so much seems a lot more reasonable. The over</code> function just lets us muddle around with whatever is inside our chosen sum type, should it be there to muddle around with. As such. Clear as mud, right?</p>
Composition</h3>
Ok. So like all these examples, the one above is quite simple so that you can see what's going on, but like all abstractions, it can leave us thinking "thanks pal, but this all seems a little bit much like hard work, surely". But what makes it all worthwhile is when we combine a Prism</code> with other optics to make a giant super-optic. Remember our example from part one?</p>
appData </span>:: AppConfig
</span>appData = </span>AppConfig</span> {
</span>    count = </span>Right 100
</span>  , title = "</span>Hello</span>"
</span>  , dbConfig = </span>DbConfig</span> {
</span>      ipAddress = "</span>127.0.0.1</span>"
</span>    , thePort = </span>8080
</span>  }
</span>}
</span></code></pre>
What if we wanted to change what's inside count</code>? That would be nice, wouldn't it.</p>
First, let's make a prism</code> for count</code>.</p>
countIntPrism </span>:: Prism</span>' (</span>Either Error Int</span>) </span>Int
</span>countIntPrism = prism' </span>Right</span> (\e -> </span>case</span> e </span>of
</span>                               </span>Right</span> b -> </span>Just</span> b
</span>                               _       -> </span>Nothing</span>)
</span></code></pre>
...and a lens</code> for getting a count</code> out of the main appConfig</code>...</p>
countLens </span>:: Lens</span>' </span>AppConfig</span> (</span>Either String Int</span>)
</span>countLens = lens count (\app newVal -> app { count = newVal } )
</span></code></pre>
...and then we can compose them together to make a new thing.</p>
fullCountInt </span>:: Traversal</span>' </span>AppConfig Int
</span>fullCountInt = countLens . countIntPrism
</span></code></pre>
Let's use it to grab that count</code> value...</p>
initialCount </span>:: Maybe Int
</span>initialCount = preview fullCountInt appData
</span>-- initialCount == Just 100
</span></code></pre>
Great job!</p>
And we can use it to change things too! With set</code>!</p>
changedCount </span>:: </span>appConfig
</span>changedCount = set fullCountInt </span>1000</span> appData
</span>-- changedCount = AppConfig
</span>--  { value = Right 1000
</span>--  , title = "Hello!!!"
</span>--  , dbConfig = DbConfig
</span>--    { ipAddress = "127.0.0.1"
</span>--    , thePort = 8080
</span>--    }
</span>--  }
</span></code></pre>
And over</code>!</p>
incrementedCount </span>:: </span>appConfig
</span>incrementedCount = set fullCountInt (+</span>1</span>) appData
</span>-- incrementedCount = AppConfig
</span>--  { value = Right 101
</span>--  , title = "Hello!!!"
</span>--  , dbConfig = DbConfig
</span>--    { ipAddress = "127.0.0.1"
</span>--    , thePort = 8080
</span>--    }
</span>--  }
</span></code></pre>
All our friends are here!</p>
You might notice the new type Traversal</code> that has been produced by combining a Lens</code> and a Prism</code>. That's an interesting thing in itself, but we'll come to that another time.</p>
That's quite enough.</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Lens by example - Prisms</a></p>


Typeclasses - Foldable
Unknown — Mon, 03 Dec 2018 00:00:00 +0000
Let's think about sets of things that we want to make into one thing.</p>
A classic example might be a list of numbers that we want to add up.</p>
In Javascript we might do something like this:</p>
const </span>added </span>= [</span>1</span>, </span>2</span>, </span>3</span>, </span>4</span>].</span>reduce</span>((</span>total</span>, </span>item</span>) </span>=> </span>{
</span>  </span>return </span>total </span>+ </span>item</span>;
</span>}, </span>0</span>);
</span>// added == 10
</span></code></pre>
Or perhaps we could get the maximum of the same list.</p>
const </span>maxNo </span>= [</span>1</span>, </span>2</span>, </span>3</span>, </span>4</span>].</span>reduce</span>((</span>highest</span>, </span>item</span>) </span>=> </span>{
</span>  </span>return </span>highest </span>> </span>item </span>? </span>highest </span>: </span>item</span>;
</span>}, </span>0</span>);
</span>// maxNo == 4
</span></code></pre>
Definition</h3>
So in Haskell we have the very similar foldr</code> with the following signature:</p>
Prelude</span>> :i </span>Foldable
</span></code></pre>
class </span>Foldable</span> (</span>t</span> :: * -> *) </span>where
</span>  </span>foldMap </span>:: Monoid </span>m </span>=></span> (</span>a </span>-> </span>m</span>) </span>-> </span>t a </span>-> </span>m
</span>  </span>foldr </span>::</span> (</span>a </span>-> </span>b </span>-> </span>b</span>) </span>-> </span>b </span>-> </span>t a </span>-> </span>b
</span>  {-# </span>MINIMAL</span> foldMap | foldr #-}
</span></code></pre>
(there is actually loads more but these are the key ones)</p>
foldr </span>:: Foldable </span>t </span>=></span> (</span>a </span>-> </span>b </span>-> </span>b</span>) </span>-> </span>b </span>-> </span>t a </span>-> </span>b
</span>foldMap </span>::</span> (</span>Foldable </span>t</span>, </span>Monoid </span>m</span>) </span>=></span> (</span>a </span>-> </span>m</span>) </span>-> </span>t a </span>-> </span>m
</span></code></pre>
Here are the above JS functions using foldr</code>.</p>
added </span>:: Int
</span>added = foldr (\a b -> a + b) </span>0</span> [</span>1</span>,</span>2</span>,</span>3</span>,</span>4</span>]
</span>-- added = 10
</span></code></pre>
maxNo </span>:: Int
</span>maxNo = foldr (\a b -> </span>if</span> a > b </span>then</span> a </span>else</span> b) </span>0</span> [</span>1</span>,</span>2</span>,</span>3</span>,</span>4</span>]
</span>-- maxNo = 4
</span></code></pre>
Not hugely different from the Javascript equivalent really. If you squint you can see the combining function, the initial value, and the data itself.</p>
foldMap</code> works a little differently. Instead of taking a custom combining function and using that to combine the items together, it takes a a -> m</code> function (where the m</code> in question is any Monoid</code> instance). It uses this to turn each item into a Monoid</code>, and then uses the <></code> and mempty</code> functions for that Monoid to combine the items.</p>
Here's a newtype</code> I made earlier: MySum</code>. It's Monoid</code> instance adds numbers together when combined.</p>
newtype </span>MySum</span> a = </span>MySum</span> { getMySum :: a }
</span>
</span>-- Semigroup instance
</span>instance</span> (</span>Num </span>a</span>) </span>=> Semigroup</span> (</span>MySum </span>a</span>) </span>where
</span>    </span>MySum</span> a <> </span>MySum</span> b = </span>MySum</span> (a + b)
</span>
</span>-- Monoid instance
</span>instance</span> (</span>Num </span>a</span>) </span>=> Monoid</span> (</span>MySum </span>a</span>) </span>where
</span>    mempty = </span>MySum 0
</span></code></pre>
Now we can use foldMap</code> with the MySum</code> constructor to add up a list of numbers.</p>
addTwo </span>:: MySum Int
</span>addTwo = foldMap </span>MySum</span> [</span>1</span>,</span>2</span>,</span>3</span>,</span>4</span>]
</span>-- addTwo = MySum 10
</span></code></pre>
Great stuff! Now our answer is still wrapped up in a MySum</code>, but it's easy enough to take it out.</p>
addTwoUnwrapped </span>:: MySum Int
</span>addTwoUnwrapped = getMySum $ foldMap </span>MySum</span> [</span>1</span>,</span>2</span>,</span>3</span>,</span>4</span>]
</span>-- addTwoUnwrapped = 10
</span></code></pre>
Excellent!</p>
This seems laborious, but actually MySum</code> isn't my invention, I've just stolen a thing called Sum</code> that comes with the Haskell Prelude. Therefore we can just do getSum $ foldMap Sum [1,2,3,4,5,6]</code> to Monoidally combine the list items.</p>
It also provides a similar invention for multiplying numbers called Product</code> that works like this:</p>
twentyFour </span>:: Int
</span>twentyFour = getProduct $ foldMap </span>Product</span> [</span>1</span>,</span>2</span>,</span>3</span>,</span>4</span>]
</span>-- twentyFour == 24
</span></code></pre>
Folding can also capture logic, here we are using foldMap</code> to check all of a list is true.</p>
newtype </span>MyAll </span>= </span>MyAll</span> { getMyAll :: </span>Bool</span> }
</span>
</span>instance Semigroup MyAll where
</span>    </span>MyAll</span> a <> </span>MyAll</span> b = </span>MyAll</span> (a && b)
</span>
</span>instance Monoid MyAll where
</span>    mempty = </span>MyAll True
</span>
</span>allOfThem </span>:: Bool
</span>allOfThem = getMyAll $ foldMap </span>MyAll</span> [</span>True</span>,</span>True</span>,</span>True</span>]
</span>-- allOfThem == True
</span>
</span>notAll </span>:: Bool
</span>notAll = getMyAll $ foldMap </span>MyAll</span> [</span>False</span>, </span>True</span>, </span>True</span>]
</span>-- notAll == False
</span></code></pre>
(I have also stolen MyAll</code>, it is usually called just All</code>. You can see the pattern here.)</p>
We could also very easily make a MyAny</code> type which uses or (ie, ||</code>) which we could use to return a True</code> whenever a single one of a collection of Bool</code>s happens to be True</code>. You might want to have a think about what the mempty</code> value would be for that to work though. That's up to you.</p>
Anyhow. I'm bored of typing now so I guess this is it for this one.</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Data.Foldable</a></p>


Typeclasses - Applicative
Unknown — Sat, 17 Nov 2018 00:00:00 +0000
In my learning of Haskell and all the associated mathematical stuff attached to it, one of the tougher conceptual cookies to crack has been the Applicative Functor.</p>
Coming from a background of fairly functional Javascript, functor is a very easy sell - it's array.map</code>. Easy. If there's a thing in the box, do something to the thing, if there's nothing in the box, don't freak out about the lack of things or explode. Great!</p>
increase </span>:: Int -> Int
</span>increase i = i + </span>1
</span>
</span>-- fmap increase [1,2,3] == [2,3,4]
</span></code></pre>
These functions can even return lists of their own...</p>
moreList </span>:: Int -></span> [</span>Int</span>]
</span>moreList a = [a -</span>1</span>, a, a + </span>1</span>]
</span></code></pre>
listOfLists </span>::</span> [[</span>Int</span>]]
</span>listOfLists = fmap moreList [</span>1</span>,</span>2</span>,</span>3</span>]
</span>-- listOfLists = [[0,1,2], [1,2,3], [2,3,4]]
</span></code></pre>
Trying to understand the actual point of an Applicative Functor, especially to my Javascript-addled mind, was much trickier. The first explanations I heard were something like:</p>
"Oh, applicative? It's for taking a function that in a box, and a value in a box, and then combining them to make a new value which is also in a box"</h4>
Now I am all up for putting values in boxes. Bloody love it. But functions? What are you playing at? Ridiculous talk.</p>
Could it help us with our list changing exercise? Sort of...</p>
minusOne </span>:: Int -> Int
</span>minusOne i = i - </span>1
</span>
</span>doNothing </span>:: Int -> Int
</span>doNothing = id
</span>
</span>plusOne </span>:: Int -> Int
</span>plusOne i = i + </span>1
</span>
</span>applicativeList </span>::</span> [</span>Int</span>]
</span>applicativeList = [minusOne, doNothing, plusOne] <*> [</span>1</span>,</span>2</span>,</span>3</span>]
</span>-- applicativeList == [0,1,2,1,2,3,2,3,4]
</span></code></pre>
OK, so instead of a list of lists, we have one list (and one new terrifyingly meaningless infix operator, <*></code>, wonderful). Seems like a lot more work too, and we could probably just have used concat</code> on the result and saved ourselves a whole load of intellectual soup. Sure. I get it. Terrible example. I've let us both down. I'm sorry.</p>
Let's see if we can find a slightly more helpful example.</p>
data </span>CalcFace</span> a = </span>CalcFace</span> [</span>String</span>] a </span>deriving</span> (</span>Eq</span>, </span>Show</span>)
</span></code></pre>
This data type is for describing calculations. The a</code> contains the current total, and the [String]</code> is used to describe what is happening. We've deriving standard Eq</code> and Show</code> instances for it, plus making our own fairly basic Functor</code> instance that, as you might expected, maps the function f</code> over any a</code> inside the datatype and leaves everything else alone like a good functor should.</p>
instance Functor CalcFace where
</span>   fmap f (</span>CalcFace</span> names a) = </span>CalcFace</span> names $ f a
</span></code></pre>
We also have this function, which we can use to print out the answer with our working.</p>
showCalculation </span>::</span> (</span>Show </span>a</span>) </span>=> CalcFace </span>a </span>-> String
</span>showCalculation (</span>CalcFace</span> names a) =
</span>        concat parts ++ "</span> equals </span>" ++ show a </span>where
</span>        parts = intersperse " " names
</span></code></pre>
Let's try it out.</p>
one </span>:: CalcFace Int
</span>one = </span>CalcFace</span> ["</span>1</span>"] </span>1
</span>
</span>showCalculation one
</span>-- == "1 equals 1"
</span></code></pre>
Seems very reasonable.</p>
Let's try some mapping.</p>
two </span>:: CalcFace Int
</span>two = fmap (+</span>1</span>) one
</span>
</span>showCalculation two
</span>-- == "1 equals 2"
</span></code></pre>
Not so good. The answer is correct as we ran a +1</code> function over the 1</code> to get 2</code>, however we were unable to add anything to our log and thus the string output makes no sense. Perhaps Functor</code> is not powerful enough for our task.</p>
Let's give Applicative a go. Here's one of those functions in a box we were talking about. This time we can also include a description of what the function does.</p>
addOne </span>:: CalcFace</span> (</span>Int -> Int</span>)
</span>addOne = </span>CalcFace</span> ["</span>add 1</span>"] (+</span>1</span>)
</span></code></pre>
We'll need an Applicative</code> instance for our datatype too. What does that look like?</p>
Prelude</span>> :i </span>Applicative
</span></code></pre>
class </span>Functor </span>f</span> => </span>Applicative</span> (</span>f</span> :: * -> *) </span>where
</span>  </span>pure </span>:: </span>a </span>-> </span>f a
</span>  </span>(<*>) </span>:: f (a -> b) -> f a -> f b
</span>  </span>GHC</span>.</span>Base</span>.liftA2 :: (a -> b -> c) -> f a -> f b -> f c
</span>  </span>(*>) </span>:: f a -> f b -> f b
</span>  </span>(<*) </span>:: f a -> f b -> f a
</span>  {-# </span>MINIMAL</span> pure, ((<*>) | liftA2) #-}
</span></code></pre>
There's some pretty interesting jumping off points in there (such as the whole concept of lifting</code>, but we'll come back to that), but fortunately we only need to implement two functions for this typeclass.</p>

pure</code> - which takes an a</code> value and returns a sort of default value for that datatype. This is used internally in constructing new values.</li>
<*></code> (called apply</code> IRL) - this takes one wrapped function and one wrapped value and combines them.</li>
</ol>
Confused? Me too! Let's give it a pop.</p>
instance Applicative CalcFace where
</span>    pure a = </span>CalcFace []</span> a
</span>    (</span>CalcFace</span> operation f) <*> (</span>CalcFace</span> value a) =
</span>        </span>CalcFace</span> newNames (f a) </span>where
</span>            newNames = value <> operation
</span></code></pre>
OK. So pure</code> is reasonably straightforward - it just makes the most basic CalcFace</code> imaginable and puts whatever a</code> we pass inside it. The other function is a bit trickier though. Basically we are taking the function f</code> and applying to a</code>, but also taking the [String]</code> called operation</code> and plopping it on the end of the [String]</code> named value</code>.</p>
Seems weird? Sure. Let's see it in action though.</p>
oneAddOne </span>:: CalcFace Int
</span>oneAddOne = addOne <*> one
</span>
</span>-- showCalculation oneAddOne == "1 add 1 equals 2"
</span></code></pre>
Nice!</p>
oneAddOneAddOne </span>:: CalcFace Int
</span>oneAddOneAddOne = addOne <*> oneAddOne
</span>
</span>-- showCalculation oneAddOneAddOne == "1 add 1 add 1 equals 3"
</span></code></pre>
Great stuff. The key here is that not only have we acted upon the values, the way that functor</code> did, but we have also done something to the structure of the datatype too (in this case, adding to the list of operations). This seems trivial when the operators are just basic mathematics, but if the functions we are running are multiple database operations and calls to other servers, then you've got yourself the start of tidy little pure functional logging solution there, son.</p>
Anyway. This barely scratches the surface, but hopefully gives you the start of an intuition for these things. Applicative does lots of things. Go find them!</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Functors, Applicative and Monads in Pictures</a></p>


Typeclasses - Contravariant
Unknown — Sat, 17 Nov 2018 00:00:00 +0000
Let's think about Predicates.</p>
newtype </span>Preddy</span> a = </span>Preddy</span> { getPreddy :: a -> </span>Bool</span> }
</span></code></pre>
What the hell is this?</p>
OK. So it's a newtype</code>. What is basically does is let's us take some sort of value (here, any function from a -> Bool</code>) and make a new type out of it so we can give it typeclasses and do magic shit to it.</p>
So let's say we have a basic function that takes a number and let's us know whether that number is over 3.</p>
threePred </span>:: Int -> Bool
</span>threePred i = i > </span>3
</span></code></pre>
Great!</p>
To put this into a newtype</code> (our Preddy</code> one, to be exact) - we do this:</p>
overThree </span>:: Preddy Int
</span>overThree = </span>Preddy</span> threePred
</span></code></pre>
The type has changed - the a</code> in a -> Bool</code> is Int</code> so we get Preddy Int</code>. We don't need to specify the Bool</code> anywhere because that's sort of implicit in the Preddy</code>-ness.</p>
OK. I get it, you're worried. My function is gone for ever. Can I get it out again? Sure.</p>
isOverThree </span>:: Int -> Bool
</span>isOverThree = getPreddy overThree
</span></code></pre>
threePred</code> and isOverThree</code> are completely the same thing. So now we're comfortable this newtype</code> thing is basically doing nothing awful to our code, what it is good for?</p>
Oh yeah. We said earlier. Because Preddy</code> is a datatype of it's own we can make typeclass instances for it. Let's make a Contravariant</code> instance, for no other reason than this being the name of the post and we're a long way into it without doing anything particularly useful.</p>
What will we need for doing that then?</p>
Prelude</span>> :i </span>Contravariant
</span></code></pre>
If are typing along with all this and get an error, please skip to the bottom of the page for some useful links, however if you have the contravariant</code> library floating around or are just happy to take my word for it then GREAT! You'll see this:</p>
class </span>Contravariant</span> (</span>f</span> :: * -> *) </span>where
</span>  </span>contramap </span>::</span> (</span>a </span>-> </span>b</span>) </span>-> </span>f b </span>-> </span>f a
</span>  </span>(>$) </span>:: </span>b </span>-> </span>f b </span>-> </span>f a
</span>  {-# </span>MINIMAL</span> contramap #-}
</span></code></pre>
The key thing to look when starting out is this MINIMAL</code> part - as it means the only functions we need to worry about for the time being.</p>
So, contramap</code> is it. What does this do?</p>
It takes a function from (a -> b)</code> and then it takes an f b</code> and returns an f a</code>. Sure.</p>
What?</p>
Are you out of your fucking mind? How do I turn b</code> into a</code> using (a -> b)</code>?</p>
Is this...a backwards functor? Can I implement undo on all my functions? Is the special magic Haskell sauce I've been waiting for?</p>
So it turns out no.</p>
nameLength </span>:: String -> Int
</span>nameLength ""      = </span>0
</span>nameLength (x: xs) = </span>1 </span>+ nameLength xs
</span></code></pre>
So a regular functor</code> is actually a covariant functor</code> which I guess means forwards functor. When we map over it, we changing what happens after it. Hence if I have a Maybe String</code> and fmap</code> a String -> Int</code> function like nameLength</code> over it I get a Maybe Int</code> and all is well in the world.</p>
However our pal Preddy</code>, unbeknownst to him, is about to become a contravariant functor</code> which sort of means backwards. What this means is if he's waiting for an Int</code> to see if it's over 3, we can contramap</code> that same String -> Int</code> function nameLength</code> over it, and instead Preddy</code> is waiting for a String</code> so he can tell you whether the String</code> has over 3 characters. The map happens beforehand, basically. That's how an (a -> b)</code> function turns a Preddy b</code> (predicate waiting for a b</code>) into a Preddy a</code> (predicate waiting for an a</code>).</p>
Seems weird? Sure. Let's look at an example.</p>
instance Contravariant Preddy where
</span>  contramap f (</span>Preddy</span> p) = </span>Preddy</span> (p . f)
</span></code></pre>
This looks a lot like fmap</code>, except our new f</code> function happens BEFORE the p</code> function that is already in there.</p>
nameLengthOverThree </span>:: Preddy String
</span>nameLengthOverThree = contramap nameLength overThree
</span></code></pre>
Here we've turned our Preddy Int</code> function overThree</code> into a Preddy String</code> function using a String -> Int</code> function and contramap</code>.</p>
Let's use it!</p>
nameIsOverThree </span>:: String -> Bool
</span>nameIsOverThree = getPreddy nameLengthOverThree
</span>-- nameIsOverThree "Lou" == False
</span>-- nameIsOverThree "Doug" == True
</span></code></pre>
Great! Now we can use it to see if words are Just Too Long.</p>
All this wrapping and unwrapping seems a lot of work for that, but what if we start using contramap</code> for more?</p>
data </span>Person </span>= </span>Person</span> { name :: </span>String</span>, age :: </span>Int</span> } </span>deriving</span> (</span>Show</span>)
</span>
</span>steve </span>:: Person
</span>steve = </span>Person</span> { name = "</span>Steve</span>", age = </span>100</span> }
</span>
</span>lou </span>:: Person
</span>lou = </span>Person</span> { name = "</span>Lou</span>", age = </span>69</span> }
</span></code></pre>
Here are Steve and Lou. They are, at least syntactically, people.</p>
Let's use mathematics to judge whether their names are too long.</p>
personTooLong </span>:: Person -> Bool
</span>personTooLong = getPreddy personPreddy </span>where
</span>  personPreddy = contramap (nameLength . name) overThree
</span>
</span>-- personTooLong steve == True
</span>-- personTooLong lou == False
</span></code></pre>
Excellent! That will show them.</p>
You will note that here we've somewhat rushed and combined the contramap</code>-ing and unwrapping into one function. This was mostly to show that when you come to use these things, it doesn't need to be quite as laborious as our broken down examples above. Hopefully you can follow, the key thing is that (nameLength . name)</code> means "put the value into name</code> and the pass the result to nameLength</code>".</p>
Contravariant doesn't show up a huge amount on it's own, but it comes into it's own as part of Profunctor</code> (lightning flashes, thunder, excitement!) which no doubt we'll flop towards at some unspecified future moment.</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
The Extended Functor Family (video)</a></p>
Data.Functor.Contravariant</a></p>
NOTE: If you happened to get this error:</p>
<interactive>:</span>1</span>:</span>1</span>: error: </span>Not </span>in</span> scope: ‘</span>Contravariant</span>’
</span></code></pre>
...then you will need to install the contravariant</code> package from Hackage. I'm not going to go into Haskell package management at this point but here is a good starting point: Practical Haskell - Getting Started</a>. It's all going to be fine, I promise. The documentation isn't great but the tools are pretty nice.</p>


Typeclasses - Functor
Unknown — Fri, 16 Nov 2018 00:00:00 +0000
Let's think about things that might or might not happen.</p>
data </span>Perhaps</span> a = </span>Yeah</span> a | </span>Nah
</span></code></pre>
Perhaps is a datatype that we can also use as a container for other data (by holding it inside a nice Yeah</code>), or to show that we have no data with Nah</code>.</p>
Let's put things in it.</p>
john </span>:: Perhaps String
</span>john = </span>Yeah </span>"</span>John</span>"
</span></code></pre>
Great job. John is having a nice time there. How might we express an absence of John?</p>
nope </span>:: Perhaps String
</span>nope = </span>Nah
</span></code></pre>
OK. No Johns here.</p>
So what if we have a function that receives something wrapped in a Perhaps</code> and wants to do stuff with it.</p>
I guess we have pattern matching, so we can use this to pull stuff out and do things with it. Let's add some question marks to this name, because that is always a valuable thing to do.</p>
questionAdd </span>:: Perhaps String -> Perhaps String
</span>questionAdd </span>Nah         </span>= </span>Nah
</span>questionAdd (</span>Yeah</span> name) = </span>Yeah</span> (name ++ "</span>???</span>")
</span>-- questionAdd Nah  = Nah
</span>-- questionAdd john = Yeah "John???"
</span></code></pre>
Ok. Seems good. What about adding a simple exclaimation point instead? (Remembering of course that anybody more than one at any point is a sure sign of insanity.)</p>
exclaimAdd </span>:: Perhaps String -> Perhaps String
</span>exclaimAdd </span>Nah         </span>= </span>Nah
</span>exclaimAdd (</span>Yeah</span> name) = </span>Yeah</span> (name ++ "</span>!</span>")
</span>-- exclaimAdd Nah  = Nah
</span>-- exclaimAdd john = Yeah "John!"
</span></code></pre>
Ok. Sure. So far, so functional. Feels like we're repeating ourselves though. What if we could abstract out away the unwrapping-and-then-wrapping-again and the function itself? Well sure we can! That typeclass is called Functor</code>. Let's open ghci and take a look.</p>
Prelude</span>> :i </span>Functor
</span></code></pre>
Here's the definition:</p>
class </span>Functor</span> (</span>f</span> :: * -> *) </span>where
</span>  </span>fmap </span>::</span> (</span>a </span>-> </span>b</span>) </span>-> </span>f a </span>-> </span>f b
</span>  </span>(<$) </span>:: </span>a </span>-> </span>f b </span>-> </span>f a
</span>  {-# </span>MINIMAL</span> fmap #-}
</span></code></pre>
Looks like we can implement it by just using fmap</code>. And that type signature kind of looks like what we want (if we squint very hard indeed). It's saying take a function of any a</code> to any b</code> (ie, (a -> b)</code>) and then pass me a functor with an a</code> in it (ie, f a</code>) and I will return the same functor but with the b</code> from your function in it (ie, f b</code>). So basically fmap</code> is the "unwrapping-and-then-wrapping-again" we talked about earlier. Sounds good. Let's implement it.</p>
instance Functor Perhaps where
</span>  fmap _ </span>Nah      </span>= </span>Nah
</span>  fmap f (</span>Yeah</span> a) = </span>Yeah</span> (f a)
</span></code></pre>
Looks great. The first thing you'll notice is that the fmap</code> for Nah</code> doesn't do anything. That's because although our Yeah</code> can contains some a</code>, our Nah</code> contains nothing at all so cares very little for our a -> b</code> function. However, look! The second line is unwrapping the a</code> from the Yeah</code>, and then making a new Yeah b</code> (because we make a b</code> by running f</code>, which is our a -> b</code> function). Therefore we can throw any old function at this and we should have a Nice Time.</p>
This function for instance, is used on a String</code> to make the caller look somewhat unhinged.</p>
exclaim </span>:: String -> String
</span>exclaim str = str ++ "</span>!!!!!!!!!!!!</span>"
</span>-- exclaim "Horse" == "Horse!!!!!!!!!!!!"
</span></code></pre>
But using our new Functor</code> instance means we can run it on our poor friend john</code> from earlier, even though he is wrapped up in all that Yeah</code>.</p>
veryJohn </span>:: Perhaps String
</span>veryJohn = fmap exclaim john
</span>-- veryJohn == Yeah "John!!!!!!!!!!!!"
</span></code></pre>
Sorry John.</p>
What if we run the same function over a Nah</code>? Does everything explode?</p>
stillNope </span>:: Perhaps String
</span>stillNope = fmap exclaim nope
</span>-- stillNope = Nah
</span></code></pre>
Nah. Seems fine. Nah</code> ignores the function altogether, as it has no a</code> in it, so no interest.</p>
Ok. So this seems pretty great. There is one thing to know about Functor</code> however that can be a little bit brain bending at first, and that's the idea that they can be "lawful". That is to say, that when you fmap</code> over something, it doesn't also break that thing, and that it unwraps and wraps in the right way. Haskell's type system can help you make sure your fmap</code> has the right types, but it can't enforce that your Functor</code> makes sense I'm afraid. That's up to you.</p>
The first law is called Identity. It means that if you fmap</code> using an Identity function, nothing will change. This is a trick I suppose - the Identity function looks like this:</p>
identity </span>:: </span>a </span>-> </span>a
</span>identity a = a
</span>-- this is also called id in the Prelude
</span></code></pre>
So running it on anything does nothing - the Identity law is basically checking the Functor</code> is up to no funny business. Our Perhaps functor is OK, but what about this chancer?</p>
data </span>Poohoops</span> a = </span>Yerp</span> a | </span>Nerp </span>deriving</span> (</span>Eq</span>, </span>Show</span>)
</span>
</span>instance Functor Poohoops where
</span>    fmap _ </span>Nerp     </span>= </span>Nerp
</span>    fmap f (</span>Yeah</span> a) = </span>Nerp
</span></code></pre>
If we fmap identity Nerp</code> we get Nerp</code>, so that all seems fine. However, if we fmap identity Yeah "Detroit"</code> then we also get Nerp</code> which is an absolute bloody disaster. This functor is broken. Put it straight in the bin, and set the bin on fire.</p>
The second law is called Composition. It means that if we fmap</code> one function over our Functor</code> and then fmap</code> a second function over the result, it would be the same as combining the two functions and doing a single fmap</code>.</p>
I'm sorry. What?</p>
OK, let's have an example of that.</p>
Therefore, if as well as our rather worrying "exclaim" function, we have one for shouting as well (don't be distracted by the <$></code> for now, we'll come to it in future...)</p>
capitalise </span>:: String -> String
</span>capitalise str = toUpper <$> str
</span>-- capitalise "Horse" == "HORSE"
</span></code></pre>
...we can combine it to make one terrifying function...</p>
shouting </span>:: Perhaps String -> PerhapsString
</span>shouting p = fmap (capitalise . exclaim) p
</span>-- shouting (Yeah "Bruce") == Yeah "BRUCE!!!!!!!!!!!!"
</span></code></pre>
...which is exactly the same as this:</p>
shouting2 </span>:: Perhaps String -> PerhapsString
</span>shouting2 p = fmap capitalise (fmap exclaim p)
</span>-- shouting2 (Yeah "Bruce") == Yeah "BRUCE!!!!!!!!!!!!"
</span></code></pre>
The Composition law just makes sure these are the same thing, so again, no funny business can take place.</p>
compositionLaw </span>:: Bool
</span>compositionLaw = fmap (capitalise . exclaim) (</span>Yeah </span>"</span>Bruce</span>")
</span>              == fmap capitalise (fmap exclaim (</span>Yeah </span>"</span>Bruce</span>"))
</span>-- compositionLaw == True
</span>-- ie, either way of doing this ends up the same
</span></code></pre>
Anyway. This is just one introduction to a kind of functor</code>. In short, hand-wavey terms:</p>
"A functor is a thing that lets you safely crap around with the values inside it without breaking the thing itself"</h4>
A few important notes and disclaimers:</p>


There doesn't have to be just one a</code> in the functor for this pattern to work. Another goto example for this is List</code>, which can have absolutely loads in. In that case, the fmap</code> runs the (a -> b)</code> function on every item in the list, like array.map</code> from Javascript, so it takes [a]</code> and turns it into [b]</code>.</p>
</li>

There are functor instances for many datatypes such as IO</code> where the a</code> inside might represents a value that isn't there yet (like perhaps it will come from some user input etc). Therefore doing fmap</code> on such a datatype is just saying "change the a</code> inside to b</code> whenever it happens to turn up", like "when the user types their name, change the string to have lots of exclamation marks so they look like a weirdo when we later print it back for them" or similar. This kind of idea can get a bit brain bending but once it settles it's sort of magical to know you can crap around with the future just like you're working with an array.</p>
</li>
</ol>

The Perhaps</code> data type we have invented is really called Maybe</code> and it's all over the place. More on that another time, perhaps.</li>
</ol>
That's quite enough for now.</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Functors, Applicative and Monads in Pictures</a></p>


Typeclasses - Show
Unknown — Sun, 11 Nov 2018 00:00:00 +0000
Let's think about things.</p>
data </span>Thing </span>= </span>Thing1 </span>| </span>Thing2
</span></code></pre>
Seems great so far. Let's try and look at one in ghci</code>.</p>
Prelude</span>> show </span>Thing1
</span></code></pre>
Oh shit!</p>
• </span>No </span>instance </span>for</span> (</span>Show Thing</span>) </span>arising from a use of</span> ‘</span>show</span>’
</span>• </span>In</span> the expression: show </span>Thing1
</span>    </span>In</span> an equation for ‘it’: it = show </span>Thing1
</span></code></pre>
Totally bogus!</p>
So what's the problem? So for something to be shown in the console, we need to know how to convert it into a String. This is a pretty common thing to be able to do, so we have a typeclass for it, called Show</code>. Let's check it out in ghci</code>.</p>
Prelude</span>> :i </span>Show
</span></code></pre>
class </span>Show </span>a </span>where
</span>  </span>showsPrec </span>:: Int -> </span>a </span>-> ShowS
</span>  </span>show </span>:: </span>a </span>-> String
</span>  </span>showList </span>::</span> [</span>a</span>] </span>-> ShowS
</span>  {-# </span>MINIMAL</span> showsPrec | show #-}
</span></code></pre>
A few more things than expected, tbh. Fortunately, that {-# MINIMAL showsPrec | show #-}</code> means we can just define show</code>, which takes any value of a type and turns it into a String</code>.</p>
Let's make another data type.</p>
data </span>BetterThing </span>= </span>Better1 </span>| </span>Better2
</span></code></pre>
This time, we'll create an instance of Show</code> for it.</p>
instance Show BetterThing where
</span>    show </span>Better1 </span>= "</span>Better thing 1</span>"
</span>    show </span>Better2 </span>= "</span>The other even better thing</span>"
</span></code></pre>
Now we can show</code> it as much as we like.</p>
showBetter1 </span>:: String
</span>showBetter1 = show </span>Better1
</span>-- showBetter1 = "Better thing 1"
</span></code></pre>
showBetter2 </span>:: String
</span>showBetter2 = show </span>Better2
</span>-- showBetter2 = "The other even better thing"
</span></code></pre>
Great! What if we don't need particularly clever string output? Just the name of the type would be fine. Can we cheat and derive one?</p>
data </span>LazyThing </span>= </span>Lazy </span>| </span>Crazy </span>| </span>Other </span>deriving</span> (</span>Show</span>)
</span></code></pre>
Nothing seemed to complain there. Good stuff!</p>
showLazy </span>:: String
</span>showLazy = show </span>Lazy
</span>-- showLazy == "Lazy"
</span></code></pre>
Success! And, so, as one would expect...</p>
showCrazy </span>:: String
</span>showCrazy = show </span>Crazy
</span>-- showCrazy == "Crazy"
</span></code></pre>
That's better, but is there anything a bit more interesting we could do with this? Sure thing! What about a data type for creating HTML markup?</p>
type </span>Href </span>= </span>String
</span>
</span>data </span>HTMLTree </span>= </span>Div</span> [</span>HTMLTree</span> a]
</span>              | </span>Title String
</span>              | </span>P String
</span>              | </span>A Href</span> [</span>HTMLTree</span> a]
</span></code></pre>
That type</code> alias for Href</code> just means it's a normal string, but it makes the intent a bit clearer. So this little markup type has four kinds of element.</p>

Div</code> has no content of it's own but is also a wrapper for a list of HTMLTree a</code> elements.</li>
Title</code> also takes a String</code> and has no child elements.</li>
P</code> takes a String</code> and has no child elements.</li>
A</code> takes an Href</code> (an alias for String</code>) and a list of children of type HTMLTree a</code>.</li>
</ol>
Let's put it to work making an internet website.</p>
website </span>:: Tree String
</span>website = </span>Div
</span>        [ </span>Title </span>"</span>My interesting website</span>"
</span>        , </span>P </span>"</span>Item of interest</span>"
</span>        , </span>A </span>"</span>http://danieljharvey.github.io</span>" [ </span>P </span>"</span>Home</span>" ]
</span>        , </span>Div</span> [ </span>P </span>"</span>Sub-item</span>"
</span>              , </span>P </span>"</span>Another sub-item</span>"
</span>              ]
</span>        ]
</span></code></pre>
Looks like the beginnings of a world beating internet business to me. How can Show</code> help us though?</p>
instance</span> (</span>Show </span>a</span>) </span>=> Show</span> (</span>Tree </span>a</span>) </span>where
</span>    show (</span>Div</span> as) = "</span><div></span>" ++ concatSubtags as ++ "</span></div></span>"
</span>    show (</span>A</span> href as) = "</span><a href='</span>" ++ href ++ "</span>'></span>"
</span>                     ++ concatSubtags as ++ "</span></a></span>"
</span>    show (</span>P</span> a) = "</span><p></span>" ++ a ++ "</span></p></span>"
</span>    show (</span>Title</span> a) = "</span><h1></span>" ++ a ++ "</span></h1></span>"
</span>
</span>-- utility function for showing child items
</span>concatSubtags </span>::</span> (</span>Show </span>a</span>) </span>=></span> [</span>Tree </span>a</span>] </span>-> String
</span>concatSubtags as = concat $ fmap show as
</span></code></pre>
By defining a show</code> function for each of our tags (and recursively calling show</code> for tags with child elements) we can generate HTML markup using one easy function:</p>
Prelude</span>> show website
</span></code></pre>
Hooray! A website!</p>
<</span>div</span>>
</span>  <</span>h1</span>>My interesting website</</span>h1</span>>
</span>  <</span>p</span>>Item of interest</</span>p</span>>
</span>  <</span>a </span>href</span>="</span>http://danieljharvey.github.io</span>"> <</span>p</span>>Website</</span>p</span>> </</span>a</span>>
</span>  <</span>div</span>>
</span>    <</span>p</span>>Sub-item</</span>p</span>>
</span>    <</span>p</span>>Another sub-item</</span>p</span>>
</span>  </</span>div</span>>
</span></</span>div</span>>
</span></code></pre>
(Actually it comes out in one big line, and then I added the line breaks to fit it on the page. Oh, the lies!)</p>
It could do with a bit of sprucing up, and a few more tags, but in my by no means humble opinion we're on our way to creating the next React-beater. Great job, show</code>.</p>
(Incidentally, although this is a more fun example of show</code>, I'd probably recommend just using a normal function for this kind of thing. Something classic like renderTree :: (Show a) => Tree a -> String</code> maybe. This isn't strictly what the Show</code> typeclass is for. There is also another type class called Read</code> whose job is to turn the String</code> output of show</code> back into the original data type, and so making a clever show</code> instance you're somewhat implicitly promising that you can turn it back somehow. This could end up being a Bad Time, and that's exactly the kind of time we don't want to have.)</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Text.Show</a></p>


Typeclasses - Eq
Unknown — Sat, 03 Nov 2018 00:00:00 +0000
Let's think about horses. There are three kinds of Horse:</p>
data </span>Horse </span>= </span>SmallHorse </span>| </span>LargeHorse </span>| </span>OtherHorse
</span></code></pre>
Let's make a function to check whether two Horses are in fact equivalently sized.</p>
isSameHorse </span>:: Horse -> Horse -> Bool
</span>isSameHorse first second = first == second
</span></code></pre>
Looks like a classic. Let's run it!</p>
isSameHorse </span>SmallHorse LargeHorse
</span></code></pre>
Shit!</p>
• </span>No </span>instance </span>for</span> (</span>Eq Horse</span>) </span>arising from a use of</span> ‘==’
</span>• </span>In</span> the expression: first == second
</span>    </span>In</span> an equation for ‘isSameHorse’:
</span>        isSameHorse first second = first == second
</span></code></pre>
That's terrible news. What's wrong here? Apparently, we need to make an instance of the Eq</code> (short for 'equality') typeclass for Horse</code> before they can be compared. What's the Eq</code> typeclass?</p>
We can find out more by firing up ghci</code>, the GHC repl.</p>
You should see a prompt with the following:</p>
Prelude</span>>
</span></code></pre>
If we enter :info Eq</code>, we get the following:</p>
class </span>Eq </span>a </span>where
</span>  </span>(==) </span>:: </span>a </span>-> </span>a </span>-> Bool
</span>  </span>(/=) </span>:: </span>a </span>-> </span>a </span>-> Bool
</span>  {-# </span>MINIMAL</span> (==) | (/=) #-}
</span></code></pre>
It shows there are two functions in the Eq</code> typeclass, ==</code> and /=</code> (equals and not-equals), and that a "minimal" definition of Eq</code> only needs one of those.</p>
Let's start again and make a better horse.</p>
data </span>BetterHorse </span>= </span>Tiny </span>| </span>Average </span>| </span>Huge
</span></code></pre>
Let's not make the same mistake this time - let's make an instance of the Eq</code> typeclass for them. We are going to implement ==</code> which has a type of a -> a -> Bool</code>.</p>
instance Eq BetterHorse where
</span>    </span>Tiny </span>== </span>Tiny </span>= </span>True
</span>    </span>Average </span>== </span>Average </span>= </span>True
</span>    </span>Huge </span>== </span>Huge </span>= </span>True
</span>    _ == _ = </span>False
</span></code></pre>
OK, seems fine. We've listed all the times two BetterHorse</code> are the same and used _ == _ = False</code> to mean "anything else is not equal" to save ourselves listing every alternative.</p>
isSameBetterHorse </span>:: BetterHorse -> BetterHorse -> Bool
</span>isSameBetterHorse first second = first == second
</span></code></pre>
Now our BetterHorse</code> comparing function works. Let's give it a go.</p>
nope </span>:: Bool
</span>nope = isSameBetterHorse </span>Tiny Huge
</span>-- nope = False
</span></code></pre>
yep </span>:: Bool
</span>yep = isSameBetterHorse </span>Average Average
</span>-- yep = True
</span></code></pre>
All seems to be fine here. We even get the /=</code> function for free by defining ==</code>.</p>
nice </span>:: Bool
</span>nice = </span>Average </span>/= </span>Tiny
</span>-- nice = True
</span></code></pre>
If you're thinking "this seems laborious", you'd be right. Fortunately, for basic data types like this, we can simply auto-generate an Eq</code> instance in the data definition like this:</p>
data </span>LazyHorse </span>= </span>LazyTiny </span>| </span>LazyOther </span>deriving</span> (</span>Eq</span>)
</span></code></pre>
workingNow = </span>LazyTiny </span>== </span>LazyTiny
</span>-- workingNow == True
</span></code></pre>
Great!</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Data.Eq</a></p>


Typeclasses - Ord
Unknown — Sat, 03 Nov 2018 00:00:00 +0000
Let's think about moods. Psychologists all agree there are only 5 real emotional states.</p>
data </span>Mood </span>= </span>Awful </span>| </span>QuiteBad </span>| </span>OK </span>| </span>Good </span>| </span>Great
</span></code></pre>
Which one is better? Is Great</code> better than Awful</code>?</p>
broken </span>:: Bool
</span>broken = </span>Awful </span>< </span>Great
</span></code></pre>
Shit!</p>
• </span>No </span>instance </span>for</span> (</span>Ord Mood</span>) </span>arising from a use of</span> ‘<’
</span>• </span>In</span> the expression: </span>Awful </span>< </span>Great
</span>    </span>In</span> an equation for ‘broken’: broken = </span>Awful </span>< </span>Great
</span></code></pre>
These cannot be ordered! We need to implement the Ord</code> typeclass (short for "ordering") so that we can compare these values and sort them.</p>
What will we need to do that then?</p>
We can find out more by firing up ghci</code>, the GHC repl.</p>
You should see a prompt with the following:</p>
Prelude</span>>
</span></code></pre>
Prelude</code> is telling us that we've loaded the Haskell Prelude, a standard library of functions. Ord</code> is part of that, so let's get some info.</p>
Enter :info Ord</code> into the repl (and press enter). You should see something like this:</p>
class </span>Eq </span>a</span> => </span>Ord </span>a </span>where
</span>  </span>compare </span>:: </span>a </span>-> </span>a </span>-> Ordering
</span>  </span>(<) </span>:: </span>a </span>-> </span>a </span>-> Bool
</span>  </span>(<=) </span>:: </span>a </span>-> </span>a </span>-> Bool
</span>  </span>(>) </span>:: </span>a </span>-> </span>a </span>-> Bool
</span>  </span>(>=) </span>:: </span>a </span>-> </span>a </span>-> Bool
</span>  </span>max </span>:: </span>a </span>-> </span>a </span>-> </span>a
</span>  </span>min </span>:: </span>a </span>-> </span>a </span>-> </span>a
</span>  {-# </span>MINIMAL</span> compare | (<=) #-}
</span></code></pre>
This is a list of functions that the Ord</code> typeclass implements. Looks like hard work. What's interesting here?</p>
Firstly - the Eq a =></code> constraint means that we can only define an Ord</code> instance for something that has an Eq</code> instance. I guess if we can't tell if two values are the same, how can we dream of putting them in some sort of order?</p>
Secondly - the slighly cryptic {-# MINIMAL compare | (<=) #-}</code> line is telling us that we can define Ord</code> by either defining the compare</code> or <=</code> functions. Haskell can generate the other functions by using either of these ones. That's great news because hard work is hard and we don't want to do hard work.</p>
data </span>SuperMood </span>= </span>Worse </span>| </span>PrettyAverage </span>| </span>Fine </span>deriving</span> (</span>Eq</span>)
</span></code></pre>
We're auto-generating the Eq</code> because why have a bad time. Let's make our Ord</code> instance.</p>
instance Ord SuperMood where
</span>    _ <= </span>Fine </span>= </span>True
</span>    </span>Worse </span><= </span>PrettyAverage </span>= </span>True
</span>    _ <= _ = </span>False
</span></code></pre>
We're implementing it in terms of <=</code> as it returns a Bool</code> which is more straightforward than the Ordering</code> datatype that compare</code> uses).</p>

_ <= Fine = True</code> means that all values are equal to or less than Fine</code>.</li>
Worse <= PrettyAverage = True</code> means that Worse</code> is less than or equal to PrettyAverage</code>.</li>
_ <= _ = False</code> means any other combination returns False</code>.</li>
</ol>
Even though we've only implemented one function, since the others can defined using it we get all of them for free:</p>
yep </span>:: Bool
</span>yep = </span>Worse </span>< </span>PrettyAverage
</span>-- yep = True
</span></code></pre>
yep2 </span>:: Bool
</span>yep2 = </span>Fine </span>>= </span>Worse
</span>-- yep2 = True
</span></code></pre>
yep3 </span>:: Bool
</span>yep3 = </span>Fine </span>>= </span>Fine
</span>-- yep2 = True
</span></code></pre>
nope </span>:: Bool
</span>nope = </span>Fine </span>< </span>Fine
</span>-- nope = False
</span></code></pre>
We also get to use any function that requires an Ord</code> instance for free, like sort</code> from Data.List</code>, which has the following type signature:</p>
sort </span>:: Ord </span>a </span>=></span> [</span>a</span>] </span>-></span> [</span>a</span>]
</span></code></pre>
This means "if you pass me a list of any a</code> which is orderable, I can return you a sorted list". Thanks!</p>
import </span>Data.List
</span>
</span>moods </span>::</span> [</span>SuperMood</span>]
</span>moods = [</span>Fine</span>, </span>Fine</span>, </span>Worse</span>, </span>PrettyAverage</span>]
</span>
</span>sorted </span>::</span> [</span>SuperMood</span>]
</span>sorted = sort moods
</span>-- sorted = [Worse, PrettyAverage, Fine, Fine]
</span></code></pre>
Great job!</p>
Still seems like hard work though, can we auto generate this typeclass too? Yes!</p>
data </span>LazyMood </span>= </span>Sloppy
</span>              | </span>Ploppy
</span>              | </span>Poopy
</span>              | </span>Nicey </span>deriving</span> (</span>Eq</span>, </span>Ord</span>)
</span>
</span>lazySorted </span>::</span> [</span>LazyMood</span>]
</span>lazySorted = sort [</span>Nicey</span>, </span>Poopy</span>, </span>Ploppy</span>, </span>Sloppy</span>]
</span>-- lazySorted = [Sloppy, Ploppy, Poopy, Nicey]
</span></code></pre>
Nice.</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Data.Ord</a></p>


Why The Hell Should I Care About Do Notation?
Unknown — Tue, 30 Oct 2018 00:00:00 +0000
Do notation is a strange thing. You first see it in examples of IO ()</code> with something like:</p>
main </span>:: IO </span>()
</span>main = </span>do
</span>    firstName <- getLine
</span>    surname <- getLine
</span>    print ("</span>Hello </span>" ++ firstName ++ " " ++ surname)
</span></code></pre>
And all seems well! This functional programming seems fine! But what's going on here?</p>
Actually what's really going on here is</p>
main2 </span>:: IO </span>()
</span>main2 = getLine
</span>    >>= (\firstName -> getLine
</span>    >>= (\surname ->
</span>        print ("</span>Hello </span>" ++ firstName ++ " " ++ surname)))
</span></code></pre>
OK. That's a little scarier. Quite a lot of weird arrows and stuff. What's this mean then?</p>
So getStrLn</code> is a function that returns an IO String</code>, which means a string wrapped in the IO monad</code>. With a bit of hand-waving, the >>=</code> (bind) function runs it, unwraps the String</code> inside and passes it into the anonymous function (the one starting with (\firstName -> ...)</code>). This function runs it AGAIN and passes the unwrapped result into the next function. As you can see, the layers could get quite deep, hence the do notation which aims to make everything clearer.</p>
So is do notation it just an IO</code> thing?</p>
No!</p>
Here's an example with Maybe. safeHead</code> is a function that returns the first item of a list wrapped in a Just</code>, which means that if there isn't a first item, instead of crapping out and ruining everything we return a Nothing</code> which is easier to cope with.</p>
safeHead </span>::</span> [</span>a</span>] </span>-> Maybe </span>a
</span>safeHead </span>[]    </span>= </span>Nothing
</span>safeHead (a:_) = </span>Just</span> a
</span></code></pre>
And here is a function that does it twice with do notation. Note not an IO ()</code> in sight!</p>
safeHeadTwice </span>::</span> [[</span>a</span>]] </span>-> Maybe </span>a
</span>safeHeadTwice aas = </span>do
</span>    as <- safeHead aas
</span>    a <- safeHead as
</span>    return a
</span></code></pre>
What does this do? Well it takes a list of lists, and returns the first value of the first list inside. Therefore there are two potential points of failure, that being, the entire input being an empty list, or the first list inside the main input being an empty list. Let's desugar it!</p>
safeHeadTwice2 </span>::</span> [[</span>a</span>]] </span>-> Maybe </span>a
</span>safeHeadTwice2 aas = safeHead aas
</span>            >>= (\as -> safeHead as
</span>            >>= (\a -> return a))
</span></code></pre>
There is probably a shorter way to write this one to be fair.</p>
safeHeadTwiceShort </span>::</span> [[</span>a</span>]] </span>-> Maybe </span>a
</span>safeHeadTwiceShort a = safeHead a >>= safeHead
</span></code></pre>
OK, so in this case, do notation</code> doesn't look so great. Oh well. Remember: clever things are interesting but they're not always good.</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Do Notation in Wikibooks</a></p>
A Fistful of Monads</a></p>


Why The Hell Should I Care About Lens? (Part 1)
Unknown — Tue, 30 Oct 2018 00:00:00 +0000
Lenses are a thing that Haskell people talk about a lot. They bloody love a lens. Everywhere you go, lens, lens, lens. What is lens? Should we, mere mortals, care?</p>
Let's try and find out what the big deal is.</p>
So.</p>
Immutability is great, but it does mean that updating a value that lives deep within a big data structure can become an utter pain in the arse. Let's define a data structure:</p>
data </span>AppConfig </span>= </span>AppConfig</span> { value    :: </span>Either String Int
</span>                           , title    :: </span>String
</span>                           , dbConfig :: </span>DbConfig
</span>                           } </span>deriving</span> (</span>Show</span>)
</span></code></pre>
It contains DbConfig</code> which looks like this:</p>
data </span>DbConfig </span>= </span>DbConfig</span> { ipAddress :: </span>String
</span>                         , thePort   :: </span>Int
</span>                         } </span>deriving</span> (</span>Show</span>)
</span></code></pre>
And here is an example of the data:</p>
appData </span>:: AppConfig
</span>appData = </span>AppConfig</span> {
</span>    value = </span>Right 100
</span>  , title = "</span>Hello</span>"
</span>  , dbConfig = </span>DbConfig</span> {
</span>      ipAddress = "</span>127.0.0.1</span>"
</span>    , thePort = </span>8080
</span>  }
</span>}
</span></code></pre>
How would we get data from this structure in something like javascript?</p>
const </span>thePort </span>= </span>appData</span>.</span>dbConfig</span>.</span>thePort</span>; </span>// easy!
</span></code></pre>
It's not too bad in Haskell either, as it auto creates selector functions for records like thus:</p>
getPort </span>:: AppConfig -> Int
</span>getPort app = thePort (dbConfig app)
</span></code></pre>
(This could also be written as thePort $ dbConfig app</code> but lets keep things simple.)</p>
That all seems well and fine, but how would we change the port in this app config? In mutable JS-land, this would be easy, something like:</p>
appData</span>.</span>dbConfig</span>.</span>thePort </span>= </span>appData</span>.</span>dbConfig</span>.</span>thePort </span>+ </span>1</span>;
</span></code></pre>
Ignoring for a moment that we have ruined the original object and probably confused anything that depends on it, this is OK, and nicely concise. The immutable way is a bit wordier though...</p>
const </span>newAppData </span>= {
</span>  ...</span>appData</span>,
</span>  dbConfig: {
</span>    ...</span>appData</span>.</span>dbConfig</span>,
</span>    thePort: </span>appData</span>.</span>dbConfig</span>.</span>thePort </span>+ </span>1
</span>  }
</span>};
</span></code></pre>
And this will only get worse as the levels get deeper. Haskell has a similar problem with deep updates in records, here's the equivalent code:</p>
incrementPort </span>:: AppConfig -> AppConfig
</span>incrementPort app =
</span>    app { dbConfig = (dbConfig app) { thePort = oldPort + </span>1</span>} }
</span>        </span>where</span> oldPort = getPort app
</span></code></pre>
The worst thing about the code above is that the only really relevant part is thePort = oldPort + 1</code>. Urgh. What's the solution then? Lens!</p>
A lens captures the idea of both a getter</code> and a setter</code> of a piece of data and a sub-part of it. Here is one for getting title</code> from an AppConfig</code>.</p>
titleLens </span>:: Lens</span>' </span>AppConfig String
</span>titleLens = lens title (\app new -> app { title = new } )
</span></code></pre>
We can get the title of the app using view</code>:</p>
title = view titleLens appData
</span>
</span>-- title = "Hello"
</span></code></pre>
We can change the app's title using set</code>:</p>
newApp = set titleLens "</span>New Title</span>" appData
</span>
</span>-- newApp = AppConfig
</span>--  { value = Right 100
</span>--  , title = "New Title"
</span>--  , dbConfig = DbConfig
</span>--    { ipAddress = "127.0.0.1"
</span>--    , thePort = 8080
</span>--    }
</span>--  }
</span></code></pre>
Lastly, we can map over the app's title using over</code>:</p>
newApp = over titleLens (\a -> a ++ "</span>!!!</span>") appData
</span>
</span>-- newApp = AppConfig
</span>--  { value = Right 100
</span>--  , title = "Hello!!!"
</span>--  , dbConfig = DbConfig
</span>--    { ipAddress = "127.0.0.1"
</span>--    , thePort = 8080
</span>--    }
</span>--  }
</span></code></pre>
OK. All so well and good, but this does not solve our deep structure update problem. How might we change thePort</code> inside dbConfig</code> in the same way?</p>
By composing Lenses!</p>
This lens gets us the DbConfig</code> inside AppConfig</code>:</p>
dbConfigLens </span>:: Lens</span>' </span>AppConfig DbConfig
</span>dbConfigLens = lens dbConfig (\app db -> app { dbConfig = db })
</span></code></pre>
And this one gets us thePort</code> inside DbConfig</code>:</p>
portLens </span>:: Lens</span>' </span>DbConfig Int
</span>portLens = lens thePort (\db port -> db { thePort = port } )
</span></code></pre>
But by composing them together we get a lens that takes us from AppConfig</code> all the way to thePort</code>:</p>
fullPortLens </span>:: Lens</span>' </span>AppConfig Int
</span>fullPortLens = dbConfigLens . portLens
</span></code></pre>
(Function composition with the .</code> operator usually means that the right-hand function is run first, and then the left. With lenses, it makes more sense if we read from left to right, so if you squint it looks a little like javascript: fullPort = dbConfig.port</code>. Kind of. Just nod and let's not mention this again.)</p>
Let's use them to look at the port!</p>
port = view fullPortLens appData
</span>-- port = 8080
</span></code></pre>
To choose a new port!</p>
newApp = set fullPortLens </span>9090</span> appData
</span>-- newApp = AppConfig
</span>--  { value = Right 100
</span>--  , title = "Hello"
</span>--  , dbConfig = DbConfig
</span>--    { ipAddress = "127.0.0.1"
</span>--    , thePort = 9090
</span>--    }
</span>--  }
</span></code></pre>
Or to increment the port by 1</code>, for some reason!</p>
newApp = over fullPortLens (+</span>1</span>) appData
</span>-- newApp = AppConfig
</span>--  { value = Right 100
</span>--  , title = "Hello"
</span>--  , dbConfig = DbConfig
</span>--    { ipAddress = "127.0.0.1"
</span>--    , thePort = 8081
</span>--    }
</span>--  }
</span></code></pre>
Look at all the things we've done with not too much code. We are now surely mighty hackers. A small disclaimer, the family of things that Lens</code> is a part of are called Optics</code>, and Lens</code> is only the beginning. Next time, we'll look at another variation on Lens</code> called Prism</code>, and see how it let's us interact with that Either</code> type we've conveniently ignored in these examples.</p>
Make sense? If not, why not get in touch</a>?</p>
Further reading:</p>
Thinking in Ramda: Lenses</a></p>
A Little Lens Starter Tutorial</a></p>


Why The Hell Should I Care About Total Functions?
Unknown — Sun, 21 Oct 2018 00:00:00 +0000
I recently read a piece of useful advice on Twitter about total functions which I enjoyed. The advice (which I will definitely accurately source at some point in the future, lol) goes something like this:</p>
"You start making your functions total by adding Maybe, but then you move onto removing Maybe."</h4>
Like all my favourite advice this sounds like it doesn't make any sense, so I figured I'd try and get to the bottom of this.</p>
Firstly, to clarify, a total function is a function that:</p>

Always returns some valid data (rather than just when it feels like doing so) and</li>
Does not go into an infinite loop.</li>
</ol>
Let's start with a non-total function. The canonical example is Head from the Haskell Prelude, which returns you the first item in a list, and looks something like this:</p>
head </span>::</span> [</span>a</span>] </span>-> </span>a
</span>head (x: xs) = x
</span></code></pre>
If we pass along a list like [1,2,3]</code>, we get 1</code> back, all great.</p>
But what if we pass it an empty list - []</code> ?</p>
If you guessed "giant heartbreaking error"- then correct! Exactly the type of thing we were told would never ever happen again once we submitted to a life of functional purity. So what's the deal here?</p>
Well, firstly, some history - this function was there when Haskell was still growing up and learning what to do in the world, and it's very difficult to go and change something that is used in a million libraries, so it's still there but should be left well alone.</p>
So what is the Proper Way To Do Things then?</p>
It's to use a total version of the function, of course! Perhaps something like this:</p>
safeHead </span>::</span> [</span>a</span>] </span>-> Maybe </span>a
</span>safeHead </span>[] </span>= </span>Nothing
</span>safeHead (x: xs) = </span>Just</span> x
</span></code></pre>
Now what happens? If we pass it [1,2,3]</code> we get 'Just 1` back (the first item wrapped in a Maybe type). Great!</p>
And what about if we use the empty list []</code> ? We get Nothing</code>, which is certainly not an error.</p>
So far, so total, great stuff.</p>
However, our function is currently responsible for two things:</p>

Checking the inputs are even correct</li>
Getting the first value</li>
</ol>
Ideally, we should be able to use types to make sure this doesn't happen, and make validating that data Somebody Else's Problem.</p>
Therefore, let's start by creating a new datatype...</p>
data </span>NonEmpty</span> a = </span>NonEmpty</span> a [a]
</span></code></pre>
It contains a first value and a list, therefore ensuring there is always a first value. What does this to do to our head function then?</p>
nonEmptyHead </span>:: NonEmpty </span>a </span>-> </span>a
</span>nonEmptyHead (</span>NonEmpty</span> x _) = x
</span></code></pre>
Because the data type cannot be empty, our head function is guaranteed to return a value and is thus total.</p>
But we've got a list! How do we get one of these new fangled data types? Let's make a helper function...</p>
createNonEmpty </span>::</span> [</span>a</span>] </span>-> Maybe</span> (</span>NonEmpty </span>a</span>)
</span>createNonEmpty </span>[] </span>= </span>Nothing
</span>createNonEmpty (x : xs) = </span>Just</span> (</span>NonEmpty</span> x xs)
</span></code></pre>
A function like this allows us to turn a regular list into a NonEmpty list, by returning a Just NonEmpty</code> for a list with one or more items, or a Nothing</code> if the original List is empty. This still means we have a possibility of failure (expressed by the Maybe), however our head</code> function expects that to be dealt with elsewhere before it gets involved with the data, and is thus total whilst always returning a value.</p>
Like all somewhat trivial examples, perhaps this seems like a lot of work for nothing (plus the overhead of dealing with a new datatype) - however this concept of doing a piece of validation once, capturing it in the type, and then having a much simpler time dealing with it onwards is very powerful indeed.</p>
(btw, Haskell actually has a NonEmpty list type, in Data.List.NonEmpty</code>, but it's more fun to make our own)</p>
Anyway, that's quite enough for now I feel.</p>
Make sense? If not, get in touch</a>!</p>
Further reading:</p>
Are your functions total?</a></p>
Data.Maybe</a></p>
Data.List.NonEmpty</a></p>

Let's write a database (part 4)

What's next?</h2> Next time we're doing ordering, which is marginally more exciting, but not that exciting tbh.</p>

Let's write a database (part 3)

What's next?</h2> Haven't really decided yet actually. Perhaps some nice optimisations? Let's see what takes our fancy.</p> Make sense? If not, get in touch</a>!</p>

Let's write a database (part 2)

Changes to our query functions</h2> Previously we just returned a big pile of rows from each query function, but now each one returns a QueryStep</code> type:</p>

What's next?</h2> OK, we've got all our ducks in a row, next time we'll do the joins, I promise.</p> Make sense? If not, get in touch</a>!</p>

Let's write a database (part 1)

So, let's do it?</h2> OK. So what we're going to do in part 1 is:</p>

What's next?</h2> If you've made it this far without being furious about my use of unwrap()</code>, then in part two we're going to add some JOINS.</p>

llvm-calc is dead, long live wasm-calc

Compiling a functional language to LLVM, part 3

OK, lets get concrete</h2> We're going to need some new datatypes to express all the new things we want to do.</p>

Function</h3> Firstly, we have a Function</code> type.</p>

Elaborating a module</h3> Elaborating a module involves:</p>

Updating the interpreter</h2> We won't go into the interpreter changes today, they work in the same way as the typechecker, storing variables in the Reader</code> env and functions in the State</code>. The code lives here</a>.</p>

Well, well, well, if it's not the end of the article</h3> Congratulations, you are all functional programming language implementation experts now. Hopefully you found that somewhat interesting and/or useful. Next time we'll be adding basic product types and pattern matching. Great!</p>

Compiling a functional language to LLVM, part 2

What's new then?</h2> To make our dreams come true, we're going to two new syntactic features:</p>

OK, LLVM time</h2> I feel like I'm rushing through all this, and maybe copy pasta-ing an entire typechecker in the preamble was somewhat undisclined of me.</p> BUT, here we go.</p> Digression</h3> Firstly, we'll add a new function to our C "standard library":</p>

Digression</h3> Firstly, we'll add a new function to our C "standard library":</p>

Well that's that</h3> Congratulations, you are all bidirectional type checking experts now. Hopefully that was somewhat helpful. Next time we'll be adding basic functions and variables. Great!</p>

Compiling a functional language to LLVM, part 1

A simple interpreter</h2> Before we get stuck into LLVM</code>, it's good to be able to evaluate our language internally. Although it's pretty clear how this calculator should work, it will be useful to compare our own simple interpreter with the LLVM output as things get more complicated.</p>

Compiling and running our hand-baked module</h3> To check that the code above does what we say it does, and to check we've got everything installed that we need, let's write the LLVM to a file called module.ll</code>, the C code to runtime.c</code>, and then compile it using clang</code>.</p>

Compiling our programming language to LLVM</h2> OK. So now we've had a taste of the raw power available to us, let's get down to business. Although we could just create raw LLVM IR by hand, instead we will use the following libraries:</p>

Hindley Milner typechecking by example

A working example</h2> We're going to start by typechecking the simplest stuff, and then build up features as we go. There are three stages to our algorithm, Elaboration</code>, Unification</code> and Substitution</code>. We'll introduce them as we need them.</p>

What the hell is a content addressed language

Granular code sharing</h4> Because of the above, the idea of the package as the unit of shared functionality is somewhat obselete. Unison Share</a> demonstrates what it could be like if we shared smaller units instead.</p>

Property testing a content-addressed language

No more words</h3> That is the end of the words. It's a bit of a braindump, and pretty much only for my own benefit, but I hope it is perhaps vaguely interesting. Who knows?</p> Make sense? If not, get in touch</a>!</p> Further reading:</p> quickcheck</a></p> fast-check</a></p> mimsa</a></p>

Newtypes for Cheap

Contract testing with Typescript

Contract testing with Quickcheck

Make sense?</h3> No. Thought not. Regardless, I'll follow up with how to great the front end part. I'll be using Typescript</code> because quite frankly if you understand this then doing it in Purescript</code> isn't wildly different.</p>

The Genius Of Concrete

Free like pizza, not like jazz

What's next?</h2>
Next time we're doing ordering, which is marginally more exciting, but not that exciting tbh.</p>
Make sense? If not, get in touch</a>!</p>

`What's next?</h2> Haven't really decided yet actually. Perhaps some nice optimisations? Let's see what takes our fancy.</p> Make sense? If not, get in touch</a>!</p>`

What's next?</h2>
OK, we've got all our ducks in a row, next time we'll do the joins, I promise.</p>
Make sense? If not, get in touch</a>!</p>

What's next?</h2>
If you've made it this far without being furious about my use of `unwrap()</code>, then in part two we're going to add some JOINS.</p>`
`Make sense? If not,` `get in touch</a>!</p>`

OK, lets get concrete</h2>
We're going to need some new datatypes to express all the new things we want to do.</p>

Updating the interpreter</h2>
We won't go into the interpreter changes today, they work in the same way as the typechecker, storing variables in the `Reader</code> env and functions in the State</code>. The code lives here</a>.</p>`

Granular code sharing</h4>
Because of the above, the idea of the package as the unit of shared functionality is somewhat obselete. Unison Share</a> demonstrates what it could be like if we shared smaller units instead.</p>

`No more words</h3> That is the end of the words. It's a bit of a braindump, and pretty much only for my own benefit, but I hope it is perhaps vaguely interesting. Who knows?</p> Make sense? If not, get in touch</a>!</p> Further reading:</p> quickcheck</a></p> fast-check</a></p> mimsa</a></p>`

Make sense?</h3>
No. Thought not. Regardless, I'll follow up with how to great the front end part. I'll be using `Typescript</code> because quite frankly if you understand this then doing it in Purescript</code> isn't wildly different.</p>`