Read, Review, Refactor https://queertypes.com/atom.xml Allele Dev allele.dev@gmail.com 2020-04-02T00:00:00Z A Typed Socket API https://queertypes.com/posts/60-a-typed-socket-api.html 2017-12-02T00:00:00Z 2017-12-02T00:00:00Z After wanting to for some time, I decided to finally get around to putting together a typed layer over the Haskell network library. This post goes into the techniques I used to make that happen, how it works and looks, and what the current short-comings are.

Singletons and phantom types are involved! For the code written in this post, the following language extensions are assumed to be enabled:

Contents

Network Sockets

Working with sockets was often a bit of an adventure. There’s a particular order to things, which, while well-documented, wasn’t always clear. For example, to create a client socket that communicate using TCP, you’d have to:

  • initialize a socket of family Inet4 with Stream packet type
  • allocate a network address structure
  • connect the socket
  • send/receive as needed

Haskell code to achieve this looks like this:

To create a server socket is a bit more involved. The steps are the same up to the point where we allocate a network address structure. After that, the steps are:

  • bind the server socket to a local port and address
  • set the socket to start listening
  • in a loop:
    • wait for the socket to accept connections
    • recv/send to connections that arrive (possibly in a new thread)

The code looks like this, without a loop:

While seemingly relatively straight-forward (but perhaps only if one has read network socket documentation a lot), there’s some room for error. For example, one might:

  • try to send/recv from a socket that is closed or unconnected
  • try to listen on a server socket that is not yet bound
  • try to accept connections on a server socket before starting to listen

And if we consider the broader socket API, there’s also room for error around sockets that have shutdown their ability to send or receive. There’s also some very particular rules around sending or receiving with UDP sockets when using the recvFrom/sendTo interfaces.

Lots of details. All documented in a few places. But!! We can do a little better with types. That’s my motivation for this effort, and the rest of this post goes into the design and implementation of such an API.

Capturing State (Machine) Assumptions as Types

Working with the socket API, there’s at least 4 bits of intrinsic state to them that determine how they work:

  • status: unconnected, closed, connected, listening, bound, etc.
  • protocol/type: stream/tcp, datagram/udp, etc.
  • family: inetv4, inetv6, unix, etc.
  • shutdown state: fully-open, blocked from sending, blocked from receiving, blocked

Here’s a snippet of the current socket APIs type signatures:

What I’d like to point out is that once we call socket, we have a Socket, but our types tell us nothing about that Socket. Further, when we call connect or bind or listen or close, we lose information. Changes are happening to that socket, but all we get back is an empty void, IO (). We know an effect has happened! But - we forget the nature of that effect.

IO (), for when you want to throw away information.

Fortunately, Haskell is one of those languages where we can track these sorts of changes in the types themselves. So, what would a type-enhanced socket type look like?

Here’s one possible design:

It’s nothing more than a newtype wrapper around the socket library, with several phantom types. They’re so-called phantom types, because they don’t affect the in-memory or run-time representation of our data structures. They spookily vanish once the program begins to run.

Now let’s look at the definitions for the each of these phantom types:

Nothing too surprising yet. This is still pretty cozy Haskell. Now, how do we get from that data type definition to a typed socket API? There’s the challenge.

Let’s consider the socket function. It’s original form is:

If we just map the original socket function over to the new socket type, it’d look something like:

However, we know a bit more than that about the state of a newly created socket. This means we can refine our type signature a step further:

Initializing a socket always gives one with a socket status of Unconnected and a shutdown status of Available. And so we initialize our socket state machine! We’re using DataKinds here to promote the data definitions to the type-level.

So what would the implementation look like? Here it is:

That’s it!

However, there’s two shortcomings here:

  • we didn’t determine the family phantom type from the arguments
  • we didn’t determine the protocol phantom from the arguments

We should be able to do such a thing. And to do that, we turn to a technique known as singletons! In the next section, we’ll work through the machinery needed to connect types and values.

Singletons Mean 1-to-1

Before we get to the details of the technique, we’ll start from the end. The final form of the socket function type signature looks like this:

Since the last version presented, we’ve:

  • removed all the function arguments
  • added two constraints

With singleton types, it was possible to do all this and still have a reasonable implementation. After all, if the user specifies what types they want for the family and protocol, shouldn’t we be able to produce the values that match that?

That’s dependently-typed programming in Haskell.

We’ll need four specific tools to connect types and values:

  • GADTs: generalized algebraic data types - they help Haskell’s type inferencer solve for what we need
  • DataKinds: lifting values types to the kind level
  • Scoped Type Variables: being able to use types declared in the type signature as types in the implementation
  • type classes: “generating” values from type

Before we delve into the details, here’s the full implementation of the socket function in its final form:

I’ve at least six things to explain here:

  • socketFamily
  • socketFamily1
  • SocketFamily1 (yeah, dependent types in Haskell are a party of repetition!)
  • socketProtocol
  • sockProto1
  • SocketProtocol1 (we really need to convince the type-checker of things)

Let’s start with all the socket family biz. Keep in mind, we want to go from a type SocketFamily given as f to a value NS.SocketFamily that the lower-level socket function can consume.

First, a GADT mirror for the SocketFamily data type:

This gives us values that connect the type-level SocketFamily to the value-level. That’s step one.

The next step, a type class to give us a unique value from a SocketFamily type:

Between the GADT and the type-class, we’ve come most of the way. The final step, is a forgetful function giving us our NS.SocketFamily, so-called because it forgets its phantoms:

And that’s a singleton! The steps, in summary:

  1. define a data type to represent your valid states, to be used as a kind
  2. define a GADT to mirror the type at the value-level, indexed by the kind
  3. define a type-class to give us one of those GADTs from a the type
  4. map from the GADT to whatever you’d like to map to

This is the simplest version of the singleton technique. It involves a lot of repetitive code, to be sure. It’s also a topic of active research, with nifty ways of mirroring even more complex structures between the type- and value-levels.

For more details and a couple of papers, check out the singletons library, which uses template-haskell to automate a lot of this!

Now, we look at the socket protocol side:

It’s a nearly identical dance.

With those two pieces, we’ve fully implemented socket:

That was An Effort.

In the next section, we’ll look at the rest of the typed socket API.

Coloring in the State Machine

So far, we have a nifty socket data type and a means to initialize our socket. However, we still want to like, be able to do a lot more with those sockets. After all, the goal is to have a usable sockets library!

Here’s an overview of the remainder of the API that affects socket state. We’ll use this to detail the last few techniques:

The simplest operations here are connect, listen, bind, and accept. The implementations of these are strictly pass-throughs to the lower-level API, and all we do is update the types to reflect the changes. There’s still a bit of power here. For example, looking at bind, we require that a socket be in an Unconnected state before this’ll compile. This is where the safety of the API comes from - we place strong requirements on the data we introduce before we allow a change to be made.

Let’s look at close:

There’s two new things at work here:

  1. Closeable, a type family (a type function)
  2. an adorable squiggle that means - these two must be equal

Closeable itself is comfortable to write:

For every status a socket could be in, we indicate whether it makes sense to close it. Technically, there’s no harm in closing a socket that’s already been closed. But, we can prevent even that bit of waste by marking that as an invalid state.

If we try to close a socket that’s already been closed, we’ll get this sort of error:

It is not at all a particularly helpful type error. As of GHC 8.0, there’s a means to make type errors more helpful, but that technique is not covered in this post. For now, it’ll suffice to say - the error is prevented and highlighted.

To close up our discussion on close, here’s the full implementation (which mirrors bind and friends):

Now, let’s talk about the shutdown commands:

Four new type functions are introduced:

  • CanShutdownReceive
  • CanShutdownSend
  • CanShutdownBoth
  • Shutdown

The techniques are very similar to what we did for close. Below are the relevant implementations for the first three type functions:

It turns out that trying to shut down sockets that aren’t in at least a connected or listening state will cause an exception. We’ve prevented that now.

The last function is the one that performs the actual state transition:

Unapologetically, we leverage the types of the shutdown commands from the underlying network library to complete this type function, and also take the time to prevent all inefficient or invalid states.

That’s the core of things! Next up, we’ll see how this affects the design of sending and receiving data over sockets.

Sending and Receiving, but Only When it Makes Sense

The goal here is to only send or receive when it makes sense. In particular:

  • a request to send/receive data over a disconnected TCP socket should never happen
  • a request to sendTo/recvFrom should never happen over a connected socket
  • we only send or receive if the relevant socket portion hasn’t been shutdown

Here’s the API to achieve that:

CanSend and CanReceive are simple enough, and currently depend only on the socket shutdown status:

The rest of the constraints are encoded in the type signature itself. Both the required protocol and the required socket state are specified, and only by passing in a socket with the appropriate state will a program compile.

Type inference saves us all and makes this possible.

As it’s given, this API is slightly over-preventative. Namely, it’s valid to use recvFrom/sendTo with a TCP socket, as long as it’s disconnected. Furthermore, it’s also fine to use send/recv with a UDP socket, also as long as it’s connected. The remaining cases throw errors. The nuanced version of this state machine gives us little gain, as it’s reasonable to expect to use TCP sockets mainly when connected and UDP sockets mainly when disconnected.

I want to highlight one last thing before moving on to the next section. Take a look at recvFrom and sendTo and their SockAddr argument:

This is a different structure than the one given by the underlying library with a touch of added safety.

Safer Socket Address Initialization

The underlying library uses the following socket address data structure:

The problem here, is that there’s nothing preventing us from using a SockAddrInet with say, a Unix socket. Which, would throw an error. Or slightly more likely, an Inet6 structure with an Inet4 socket.

To address this, the fix is simple enough - we use a GADT version!

The most important bit here is the SocketFamily phantom type and how it affects the return type at each branch of this GADT. We reuse the SocketFamily type from earlier so we can relate socket instances to socket address structures.

Now if we look at a function like bind:

It becomes impossible to pass in a socket address structure that isn’t of the same socket family as the socket being used. With that, our goal is achieved… mostly!

There’s actually a hack I’d like to talk about here. Let’s look at recvFrom, including its implementation:

In every function except this one, the type parameter f occurs in the argument types. This made our lives easy - we could depend on the user to pass it what we needed without needing to communicate between the type and value levels.

However, here, recvFrom returns a SockAddr f. Worse yet, the underlying NSB.recvFrom returns the original NS.SockAddr structure, with no type information!

So we have to relate the two somehow, and convince the type-checker that it’s okay. This wasn’t easy, and I ended up with the following “proof”:

I’ll explain. When doing a pattern match, Haskell’s type-checker is able to refine what it knows. From the left side of the pattern match arrow (including any type-level data), it’s able to learn a lot about what should be on the right. So, that’s the why of needing to generate a SocketFamily1 object which carries the type-level data to associate the two - it convinces the type checker this all makes sense and we’re not just pulling a SockAddrInet6 'Inet6 out of thin air.

However, we aren’t able to convince the type-checker these are all the valid cases. It insists that we haven’t covered, say, NS.SockAddrUnix, InetV4, which we know make no sense, and the type-checker would even reject!

So that’s that. A lil hack.

With that out of the way, let’s talk about making this API nicer to use.

Making it Nicer to Use

Let’s take a look at the socket function:

We’d use it look this to create a TCP4 client:

Which is … actually really tedious. As a user, we have to remember to type all that out in the correct order, or get scolded by the compiler. It’s really cool that we don’t have to pass in any arguments to get the sort of socket we want, but it came at quite the cost in usability.

We can do better - a lot better. I introduce several helper functions below:

Their implementations are the easiest - type-inference handles 99% of the work. We just need to be careful about the type signatures. And like magic, our client socket code now becomes much nicer:

Another usability pattern, is that we’d like functions to automatically create our sockets and also close them, even if errors come up. There’s a very powerful function hiding in Haskell’s Control.Exception standard prelude module: bracket!

Using bracket, we can write some pretty simple helpers:

The way the with helpers work is like this:

In the next two sections, we’ll write a simple echo client and server using this library, and then test it all!

The Client Meows and the Server Echoes

First, the client:

Now the server:

And that’s network programming in Haskell!

Testing It

To go one step further, I’ll show how such a library could be tested. I used the echo server example above as a test case to make sure I didn’t break anything while doing the typed layer.

I’ll make use of the nice hspec library.

Conceptually, the test seems like it should be this simple:

and as long as both finish, all’s well? Right?

Herein we encounter all the loveliness and nuance of network programming. There’s immediately three things wrong with this test suite:

  1. in runServer, we’ll block on accept. The client will never connect. The suite never ends. Eternal uncertainty!!
  2. Even if by bad magic we made it to runClient, we don’t actually check things are being echoed. Let’s fix that.
  3. Finally, between runs of our test suite, if any errors came up, our server would fail to rebind to that port and address because there’s a special TIME_WAIT mechanism where the operating system holds on to sockets after closure to ensure clean termination.

Wow. Yeah. Welcome to network programming!

I’ll skip ahead to the solutions, and just say that a bit of concurrency and setting a socket option goes most of the way:

That’s the whole test! The main changes needed were:

  • adding a mutex (a Haskell MVar) to make the client wait til the server is ready
  • creating the server on a separate thread
  • setting an option that allows the server to rebind in future test suite runs
  • checking that echoing actually works with shouldBe in the client

Socket Options and Socket Wishes

This brings us close to the end. Our last bit of adventure involves thinking about socket options. Turns out, there’s a lot of them!

Here’s the typed socket function for setting options as of right now:

As you can see, we’re not doing any of the property tracking in the types we did with socket status, protocol, and family. We’re just, running the effects.

The problem here is more complicated, because we want to track all the options we’ve enabled so far, which would be a type-level list.

Something like:

This is not a completely terrible endeavor just yet. It becomes harder if we’d like to also track the values we set options to, and to possibly reconsider how this interacts with the rest of our current API.

Some options are boolean-valued (on, or off). Some take integers. Some take time-structures. It’s an adventure for another time!

Lacking Linearity Leaves Limitations

We catch a wide class of errors with this new API design. However, there’s still one major weakness to this approach because of the limitations of the type system we’re working in.

What happens if we throw some threading into the mix??

We were able to close the server socket in the main thread, and as a result, the type-state will be inconsistent in the child thread. The server will actually be closed but will have a type like SSocket f p 'Listening sh.

Welp.

This is a limitation of the type-system, and there’s naught we can to help the compiler help us.

Fortunately, extensions to the Haskell type-system are being worked on that will allow it to encode these sorts of constraints. Constraints that make it possible to say, “I’ve handed this resource off to another thread. Please make no further modifications on this thread!”. That’s linear types - things can be “consumed”.

Here’s the haskell paper detailing how this system would work.

Closing

And that’s that! Phantom types, singletons, to the type-level and back to the value-level again.

If you’re interested in seeing the full implementation, you can check it out on gitlab.

I’m looking for new work, so send me an email if you’d like to work with me on making reliable systems for all.

Thanks for reading!

]]> Applicatives and Alternatives https://queertypes.com/posts/59-applicatives-alternatives.html 2017-04-21T00:00:00Z 2017-04-21T00:00:00Z Introduction

This post is a tutorial on applicative functors (applicatives) and alternatives - what they are, how they’re used, and how to build an intuition for them.

It’s going to be extremely practical. It’s going to be all Haskell. We’ll build stuff along the way so that it makes more sense.

The following imports are assumed to be in scope for this post:

All code used in this post is available here.

Let’s start with some informal definitions.

An applicative is an abstraction that lets us express function composition in a context. Applicative composition only succeeds if each independent component in the computation succeeds. Rules for what success looks like vary from context to context. Its interface looks like this.

Notably, all applicative functors must also be functors. We won’t cover functors here, but it suffices to say that they’re an abstraction for applying context-free functions to context-embedded values.

pure is sometimes called lift because it lifts a pure value of type a into the context f. <*> is our applicative composition operator. It allows us to chain together contextual computations.

An alternative is an abstraction that builds on applicatives. Like it sounds, it allows to express the idea of trying something else in case something fails. Composition of alternatives take the first success. Its interface looks like this:

empty is our failure value, to represent a failure of all alternatives. <|> is our composition operator, for chaining together alternatives.

With those definitions out of the way -

Let’s build our first applicative! To do so, we’ll look at the Option type.

Option Types; Optional Contexts

An Option or Maybe type allows us to express the idea of nullability safely. It looks like this:

We either have Some value of type a or we have None.

Here’s the applicative (and functor) implementation for Option:

The only way a computation for Option can succeed is if we have Some value along all paths. The moment we encounter a None, we abort.

Let’s look at the implementation of Alternative for Option now:

In this case, we succeed as long as some computational path results in Some. We fail only if all paths fail.

I’ll provide some examples next. A few notes:

  • <$> is fmap, or, the means to apply a pure function in a context
  • :{ is used in the Haskell REPL to indicate multi-line input
  • :} terminates multi-line input

Here’s how what we’ve written looks like in use:

The examples above all use integers, but we could easily use any other type. Furthermore, notice that we can chain as many computations as we need, like with add3. This is much more convenient than pattern matching on the spot every time, like:

It is also less error-prone that using if-expressions, like so:

Alternatives and applicatives (and functors!) capture this logic for us so we don’t have to repeat ourselves. All of the above to say:

Let’s look at a new context type now: Xor

Xor - Success or Failing With Informational Errors

Xor (or it’s Haskell analogue, Either) is a type used to store simple error information in the case of a failure. It looks like this:

The XLeft branch is typically used to capture an error. The XRight branch is our success path.

Here’s the implementation of Applicative for Xor:

As before, the only way to get to a success is to have successes all along the way.

Xor does not admit an Alternative instance. This is because, there is no reasonable definition of Alternative’s empty. If the left-branch type a was a Monoid, then it’d be possible to define, but it still wouldn’t be very interesting. We’ll elide that for now and show a more reasonable error-capturing type in the next section that allows for alternatives.

For the examples involving Xor, we’ll first define a simple error data type with a few helper functions:

Now for some examples:

Next, let’s look at an extension to the Xor type - the Validation type.

Validation - Keeping Track of All The Errors

Validation is a very handy type for any form of validation where you’d like to keep track of all errors that occur, instead of throwing them away. It looks fairly similar to Xor, even:

Exchange Validation with Xor, Failure with XLeft, and Success with XRight and we’re right back to the last section! However, we’ll see that how we implement Applicative and Alternative can make a big difference.

Here’s the Applicative implementation:

The biggest change so far is that we require the error type to implement the Monoid interface, which, expresses things that can be concatenated/merged/etc via the <> operator. Instead of keeping only the first error encounterd, we keep them all. We’ll see how this works more closely with some examples soon.

Here’s the implementation for Alternative:

Nothing changed here compared to Xor.

Before getting to examples, let’s define some convenient functions around our NumberError data type from before:

And some examples:

These examples are mostly silly, mainly for showing the mechanics, but the Validation type is incredibly useful for giving thorough feedback to users when validating complex input. It often comes up in the context of web form validation (if working in a language like Purescript) where you want to check that all fields have sensible values, and if not, reporting what fields aren’t valid and why.

I’ll list two implementations below:

Conclusion

As this post has already gotten kind of long, I’ll leave several other amazing bits out of it for this time. The most useful bits I’m not bringing up, are that applicatives and alternatives can be used for:

As a small example of applicatives and alternatives for parsing, here’s a bit of code from one of my projects that uses the attoparsec library noted above:

The goal is to parse a string that looks like "#SELECTABLE:YES" or "#SELECTABLE:NO", and having done so, wrap it in a type that differentiates it from a plain boolean type.

*> is an applicative operator that performs parse sequencing, but discards the left-hand side. $> is a functor operator that performs the effect to the left, and if successful, lifts the right-hand side into the current context.

startTag matches the "#SELECTABLE: portion, and parseSelect looks for either a "yes" or a "no" in a case-insensitive fashion.

Probably the most interesting bit here is that I had the ability to specify alternative, valid parses using <|> in parseSelect. This comes in handy for parsing any sort of enumerated type, say, the error return code from a web API you’re consuming.

Concluding For Real

Anyway, that’s all! I hope this helped clarify what applicatives and alternatives are, and how you might use them. Even though this post is Haskell-centric, the core ideas can be expressed in other programming languages. Ultimately, applicatives and alternatives are just a safe, broad interface for composing computations with context and assigning rules to those contexts.

Updates/Edits

]]> Reading Types (in progress!!) https://queertypes.com/posts/58-reading-types.html 2017-04-21T00:00:00Z 2017-04-21T00:00:00Z This post is about reading type signatures. It assumes you’ve never written Haskell (or a similar language) before. If you’ve written in such a language before, it’s likely this material will be familiar to you. This post is not for you.

It doesn’t assume you’ve used a typed programming language before. I’ll define things carefully and take care with jargon. I’ll give priority to concrete examples, so that you can use this to build things. It’s important to me that this can be a post you can come back to if you want to get more comfortable with typed programming and have the time and energy for it.

Types and type systems are powerful tools, and I want to make them a little easier to use. They’re great for communication, for expression, for correctness, for program maintenance, and peformance. The problem is, how do we use them well?

All examples will be given using the Haskell programming language. It’s pretty easy to install nowadays, and the syntax is pretty clean for talking about type system things.

What are types?

Types are, a lot of things. If I were to give an overarching definition, they’re at the very least, a way to describe the shapes of data and programs.

There’s a lot of context, often times left unsaid when folks talk about “types”, unqualified.

Some people talk about types and think of storage types. These describe how much space certain pieces of program take up in memory, and possibly, how that data is interpreted. Think: integers, longs, unsigned integers, floats, arrays, C.

Some people talk about types, and object-oriented design comes to mind. These sorts of types are one system for classifying data that mixes state, scope, and behavior together, and talks about types in terms of hierarchies of capabilities. These are known as sub-type systems. Think: Java, C Sharp, classes. This post is not about these systems.

Others still, talk about functional programming, and algebraic types, and a bunch of other things, sometimes of a very mathematical nature. There’s talk of how to compose things, how functions interact, and about side-effects and types to describe them. Think: Haskell, Elm, monads, and the like. This post is about these sorts of type systems, and how to understand and think about them. Let’s call them, algebraic data types.

Further still, some folks talk about types for proving whole programs adhere to specs. At this point, we’ve wandered into dependent types, provers, and type theory. While these systems can be extremely expressive, they’re outside the scope of this post. We’re starting small, to be able to read and make sense of things we can use right now.

There’s also the distinction between dynamic and static types. When I talk about dynamic type systems here, I’m talking about Python, Ruby, Racket, Javascript, Erlang, and others like them, who check the types of data at run-time. Some are more strict than others. Static type systems run all their checks at compile time, before a program is ever run. That’s what languages like Java, C, C++, Rust, Haskell, and OCaml do. Like the dynamic case, there’s sharp differences about what sorts of things each of these languages can check, some strictly more expressive than others.

Speaking of expressivity - I use this term in a strict sense, which I’ll make more clear with the rest of this post, this post about reading and understanding types. An expressive type system is one that let’s you say more about your data, without much hassle. These are the best sorts of type systems for communicating intent about your programs and data.

That’s “types”. “Types”, as it turns out, can mean a lot of different things to different people.

Type signatures: what can it do?

Given all the definitions up to this point, let’s talk about something more concrete: type signatures.

A type signature is a description of a function:

  • what it’s name is
  • what parameters it takes and their shapes
  • the shape of what it returns

A lot of information can be packed into a small space. Type signatures are the first place to look to try to understand a function.

Type signatures are the main thing we’ll be working to understand how to read.

Here’s a type signature now:

add is a function that takes two Int arguments and returns an Int. More generally:

Of course, different languages have different ways of expressing types signatures. Here’s add in C:

Here’s add in Scala:

We’ll look at far more interesting type signatures later as we build on what we know.

Simple and primitive types

Primitive types are those provided by a language that are closest to what might be stored on a machine. Things like:

  • integral types: 1, -1, 10
  • decimal types, doubles and floats: 1.0, 2.31212, 3.1415926
  • text: “cat”, “girls”, “are”, “great”, “actually”, “”
  • bytes: [0x01, 0x05, 0x19]
  • bool: true, false
  • unit: () – literally the type that only has one value, ()

In Haskell, these types are:

  • Int
  • Integer (to represent numbers that are too big to fit in a register)
  • Float
  • Double
  • String (sort of - it’s a doubly-linked list of characters)
  • Text
  • ByteString
  • Bool
  • ()

Function types: passing around functions

There are also types that can express functions, specifically, functions as arguments to other functions.

Let’s look at an example:

This is almost add, but with more power. It now takes a function paramter that let’s us turn an integer into a string. Looking immediately below, we have such a function handy. Let’s go even more concrete for a moment. Here’s the definition of addAndShow:

That’s all there is to that one. Below, I’ll show what a definition of showInt might look like. A few notes before I get to it:

  • such a function is already provided by the standard library: show
  • it introduces a lot of new syntax
  • the implementation is recursive
  • it’s not necessary to understand what function types mean

With that said, for the curious:

It is important to note also that at this point, we don’t have enough tools to give really precise types. Notably, let’s look at another function that fits (Int -> String), but doesn’t do what we’d hope:

This definition does satisfy the given type signature. Sure. But! This warning is here specifically to emphasize the limits of what we can express at this point. We know that:

  • we have one and only one argument: an Int
  • it returns a String - never anything else
  • no side-effects will be performed (more on that later)

Reading type signatures and designing types is every bit as much about what functions can do as it is about what functions cannot do. Keep this in mind as we proceed.

Let’s expand what we can express with types in the next section.

Product types: records, structs, and more

Sum types: tagged variants, enumerations, and more

Composing types: sums and products together

Type inference: the compiler can work with you

Polymorphism: types for more general functions

An example: types for optional data

Another example: types for tracking success and failure

ADTs: abstract and algebraic

Recursive types

Another kind of polymorphism: traits and typeclasses

Types for tracking effects

Types of a higher kind, or, type signatures for types

Writing types to be read - communicating effectively

Where to next?

]]> Smaller Types, Happier Programs https://queertypes.com/posts/57-small-types.html 2017-01-06T00:00:00Z 2017-01-06T00:00:00Z This post will be all about a simple technique for making programs a little easier to maintain. It’s all about the size of types.

Most code examples will be given using Haskell. When an example uses another programming language, I’ll call that out before showing the example.

The advice is focused on languages that have a compile-time type-check step, but can be informally adopted to make maintenance of dynamically-typed programs (Javascript, Python, Ruby, etc.) a little easier.

The Size of Types

When I talk about the size of types, I’m talking about how many values a given type can represent. A few examples:

  • boolean: true or false, a type of size 2
  • 32-bit integer: 2^32 possible values, a type of size 2^32
  • a string, encoded as a byte array: 2^8 * n, n being the length of the string
    • a type of infinite size, for our calculations

These examples are all primitive types. Fortunately, most programming languages offer at least some form of abstraction over these primitive types. Leveraging those abstractions will allow us to craft types that are smaller than the primitive types, and can therefore more accurately describe our domain of interest.

In particular, I want to talk about algebraic data types. They’re called as such because in a sense I’ll make clear soon, they allow us to add to and multiply a type space to meet our needs as precisely as possible.

For example, a sum type Color:

This type has 3 values, or variants: Red, Green, Blue. It’s a sum type, because each variant adds 1 one more value to the size of the type. With that, Color is a type of size 3. This is a reliable fact as long as implicit conversion isn’t something to watch for in your programming language of choice. More on that later.

In Scala, this might look like:

Most mainstream languages have basic support for sum types, via enumerations. However, sum types become particularly interesting when used with product types. A product type might look something like:

An AreaColor has 2 * 3 possible values. Let’s enumerate them.

Most mainstream languages have excellent support for product types. You may have heard them referred to by the names, “struct”, “record”, or the like. The components of the product type multiply together to give the new type size.

Here’s where most mainstream programming languages falter: being able to combine sum and product types conveniently.

Here’s an example of the two used together:

PaletteCommand is a toy example of the sorts of concepts that can be expressed when you have algebraic data types.

It’s very powerful being able to conveniently combine sum and product types. So much so, that without this ability, it becomes very easy for the complexity of a program to multiply. This is what I meant when I said 2 years ago that “In languages lacking sum types, the complexity of a program can only multiply”. ref

Now we have just enough of the basics of calculating the size of types so that we can talk about dealing with how to resolve design problems.

Stringly-Typed and Work Arounds

One of the most common design problems that one might encounter when working with existing code is that everything will be expressed and encoded as a string, e.g., a so-called stringly-typed code base. This can happen in any programming language. After all, strings are nearly always provided as a primitive type. It might come up in the context of retrieving data from a database to affect control flows, as messages from a queuing system, as commands from a network-connected client, or even as commands from a command line interface.

Below, I’ll show some of the trouble with relying on strings to handle program control flow.

Let’s write a function, colorToInt, that given a string, returns a numeric representation of that color:

And an example of where this goes wrong:

This will raise an exception. Our colorToInt function doesn’t know how to handle "Red". A first-pass at fixing this might be something like:

Now, our former example works alright. But what about:

These all return 3, which amounts to an unknown color value. A third and common pass might throw an exception:

This will catch all typos. But - how does it fare in the face of program updates?

Let’s assume we have a morbidify function defined deep in our system. It’s worked for a long time, and no one’s thought about it for months because there’s been other priorities in mind.

New requirements come in: Red in no longer supported and now we need to add Cyan.

We remember to update colorToInt3:

But somewhere in the system, the following call occurs:

Suddenly, this call will start to fail. Given the nature of the code, one that performs a side-effect on behalf of the system, it is very unlikely that tests will have been written for this. If we’re somewhat fortunate, someone thought to add some logging to morbidify, so at least the problem will be detected and can be explained. If we’re not so lucky…

Well, the good news is we can do much better than this. Let’s talk about it next.

A Solution: Smol Types

Many of the problems we ran into the last section were because the size of string types is far too large. Let’s see how using sum types can make the situation better. First, we start with a few definitions:

Let’s play around with this a little. First, our failing examples from before:

This gives us a compile-time error, noting that we expect a Color but got a String

This gives us a compile-time error, noting that the value Reed is unknown.

Let’s add support for Cyan:

And a small test program:

This gives us a compile-time warning that Cyan wasn’t handled in colorToInt4. This is a cool thing known as exhaustivity analysis, a super helpful thing a few languages containing full support for sum types can do.

Let’s remove support for Red and Cyan:

This will give us two compile-time errors:

  • we mention Cyan in main when we’ve never defined it
  • we mention Red in colorToInt4 when we’ve not defined it

This is the basic premise behind using small types as a tool for making programs easier to maintain. If the size of our types is as small as possible, while still fully expressing our domain, errors cannot be represented.

Now let’s talk about caveats and things to watch for.

Implicits Ruin Everything

Implicit conversion. Sometimes, we try as hard as we can, and the programming languages we use try to be as helpful as they can, and things Just Go Wrong.

This is particularly notable in Java and Scala, where toString is defined over all types.

The problem arises when interfacing with legacy code, where most of the types are still the infinitely-sized String instead of our constrained Color. We might pass in a Color to such a legacy function, and expect the compiler to flag us somehow, but it silently gets converted to a String. Where we expected to be able to reason about a type that is at most size 3, we’re back to the land of infinites.

Another problematic conversion that is fairly common, is one of most primitive types to Bool. This will sometimes come up in control paths, where an if-statement is used to determine what’s to be done next, rather than a switch. The problem here is that we’re defined fine-grained control with our type, say Color, of size 3, but we’ve shrunken down to something that can only express 2 paths, Bool.

Another common implicit conversion to watch for is that of enumeration to integer. This happens in C, and when using regular enumerations (rather than enum class) in C++.

For languages (frequently object-oriented languages) that have a notion of value and reference types, and of nulls, beware of the possibility of null inhabiting your type. It is entirely possible in Scala and Java for null to be a member of our Color type, and still cause us trouble.

There’s a few other forms of implicit conversion to worry about. It all depends on your domain and the programming language you’re working with. They’re beyond the scope of this post.

In sum, watch out for:

  • implicit string conversions, particularly in Java and Scala
  • implicit conversion to Bool at control paths
  • implicit conversion from enumeration to integer, particularly in C and C++
  • nulls, because they break everything

It’s worthwhile to keep in mind the danger of implicit conversions when relying on the size of types to design your programs.

In Practice

To wrap up, I’ll leave you with a few practical tips.

Make the types at the core of your program as small as possible.

The best time to shrink a type is as early as possible. By this I mean, if you’re interfacing with the outside world, say, reading an environment variable or parsing some user input, that is the time to determine whether the input is valid and make a value of your small type or return some form of error. Either and Maybe types are lovely here.

The best time to grow your types again is when outputing at the boundaries of your programs. Serialize them as needed, and send them off to the database as a String field or as a response to a client command as a part of a JSON blob.

Sometimes, there’ll be data that really needs to be a String or an Int, and can’t be shrunk. This will be safe to do as long as no control paths depend on the shapes of the values contained in the String or Int. If you notice the flow of your program start to depend on what’s in those strings or integers, it might be time to consider shrinking to a more representative type.

That’s the basic idea.

Topics Not Covered

We’ve covered a lot in this post. However, there’s still a whole lot more to explore when it comes to using the size of types to design programs. Here’s a selection of things I didn’t cover that might be of interest:

  • size of polymorphic types:
  • size of functions and their compositions
  • size of subtypes (Scala, Java, etc.):
  • size of constrained types:
  • typed holes
  • limits of exhaustivity analysis
  • reasoning about the size of effectful functions:
  • using the size of types for automated linting and static analysis

Anyway, enjoy your small types. ❤

]]> Writing a Search DSL, Part 1 https://queertypes.com/posts/56-writing-a-search-dsl-1.html 2016-01-27T00:00:00Z 2016-01-27T00:00:00Z Hi, readers!

This will be a series of posts covering the development of a Domain Specific Language for search. I’ll dive into the design, testing, and implementation of parsing and evaluation. This will include both pure evaluation and compilation to express queries for an external data store (*SQL, Elastic Search, etc.).

In part 1, I’ll cover why someone might want to use a DSL, as well as the design and implementation of the DSL core.

Motivation

Why would you want to implement a DSL?

Focusing on search, you might want to expose search functionality to users. This might be a public-facing, HTTP API that allows users to look up other user details and posts, like Twitter’s Search API. You might be part of a team at a large Cloud Services provider, putting together a search engine for users to review logs regarding infrastrcuture. This might an internal feature, an enhancement to existing developer tools to facilitate handling customer support requests.

Search is a wide space!

The main reasons to pursue a DSL as a solution are:

  • You need a precise language for describing allowed operations
  • The language must be expressive and relevant
  • Extensions to the language should be possible to meet changing needs
  • The system should be helpful, letting users know if something was incorrect
  • The backend should be swappable
  • The frontend should be swappable
  • The system needs to be well understood, with no edge cases

Essentially, DSL approaches to solving problems bring the capabilities of language design theory to your problem space.

It’s notable that command line tools like grep, sed, awk, and find are themselves DSLs. A surprising number of problems can be approached with language design techniques in mind.

While there are many benefits to such an approach, it is not without costs. The primary costs are knowledge and time - knowing enough about language design, parsing, and the domain to bring together the pieces, and having enough time to make it all work.

This series of posts aims to address the knowledge part of the cost, by demonstrating what this process looks like from start to finish.

Let’s get into it!

The Language

We’re going to start with a simple search language and build on it in later posts. Let’s first specify a few parts of the language, enough to perform some interesting searches:

  • operations: <, >, ==, >=, <=
  • types: int, bool, str
  • variables/identifiers
  • basic type-operation constraints: Ordering, Equality
  • logical combinators: and

This allows for expressions like:

confidential == false
  count > 10 and ip == "10.0.8.0"
  date >= "2010-10-12" and date <= "2010-11-12"

Future extensions to the language could happen along any of the above axes: more operations, more types, more type constraints, more logical combinators.

For a convenient implementation, the limiting factor is how much the host programming language’s type system can accommodate. I’ll be using Haskell in this series, but any language that allows for algebraic data types should be enough to reproduce this work. It’s entirely possible to develop a DSL solution in other languages, but there’ll be more testing to do.

Let’s implement the language core.

We’d like to support all of <, >, ==, >=, <=. Let’s add those in:

Next, we’ll add support for types and values:

Notice that we’re maintaining both type-level and value-level information, and maintain a distinction between the two levels.

Next up, support for variables:

This is a fairly straightforward approach. We don’t have to worry about bindings or scope. We leave the declaration of allowed variables to the search engine provider, to be exposed via documentation.

Next up: type constraints!

Next, the logical combinator and. I’ll also introduce how binary operations are represented at this stage:

This little recursive data type captures the essence of our language. Let’s break it down:

  • And Expr Expr: and combines two expressions
  • BinOpL Op Var Literal: a binary Op with a Var on the Left and a Literal
  • BinOpR Op Literal Var: a binary Op with a Var on the Right and a Literal

With this construction, we’ve ruled out some cases:

  • An expression can never consist of two literals: 1 < 2
  • An expression can never consist of two vars: date == date, ip > date
  • A single expression will never have more than one operator

Here’s the language as a whole, for convenient reading:

Closing

That’s all I’m going to cover for now - the core of the language. In the next post, I’ll build a parser for this language and write some tests for that parser.

If you’d like to get a head start, the source for the search DSL is availaible in this GitLab repo.

Thanks for reading!

Contributing

If you enjoy my works:

  • I’m currently available for hire: resume
  • I welcome donations to my Patreon
]]> Terms and Boundaries for my Works https://queertypes.com/posts/55-queer-types-terms.html 2015-10-17T00:00:00Z 2015-10-17T00:00:00Z This is a short document highlighting what I can do, what I am willing to do, and under what terms.

If you’d like to help me, please consider donating to my Patreon.

What I Can Do

I write Haskell, primarily. I’ve written quite a bit of it. You can see a sampling of that work on my Gitlab. You may also turn to my resume for additional pointers.

I specialize in backend and systems work. I’m comfortable with implementing components of projects, as well as full projects.

I can also teach, write, and draw. I use a combination of those skills to communicate, express ideas, and make concepts more accessible.

I am an intersectional feminist. This means that my works try to take into account the needs of all people, but especially those that are being hurt by our current systems.

Terms of my Works

  • I will not work on secret or proprietary software
  • I will not work on secret or proprietary research
  • I will not patent my original works
  • I will enforce a code of conduct on my projects
  • I will work on software projects available to all
  • I will work on software with licensing approved by OSI
  • I will release my own software under such licenses
  • I will create other works under the CC-BY license
  • I may refuse to work on projects with toxic maintainers or communities
  • Consent first: our terms must be mutually agreeable
  • I expect to be paid for my labor
  • None of the above is negotiable
]]> Notes on - Name and Marker Change in Austin, TX https://queertypes.com/posts/54-name-marker-change-austin-tx.html 2015-10-16T00:00:00Z 2015-10-16T00:00:00Z I went to a free workshop today focused on the process needed to change one’s name and gender marker in Austin, TX. It turned out that it was a bit more than that! The very brief of it:

  • They gave a short overview of the program
  • They paired me with legal students
  • They began the process of filling out the relevant petitions
  • They made copies of necessary documents
  • They gave me a take-home list of docs I still needed
  • They’ll keep in touch during the process and help guide it to completion

I asked about support for non-binary gender identities. As I expected, there is no such support in the United States of America. You pretty much choose M or F. It’s amazing how much pressure this puts on individuals to “sort” into the binary. More on that some other time.

Here’s the sorts of documents needed for completing the process:

  • Social security card
  • Birth certificate
  • Letter from therapist
  • Letter from physician
  • State issued ID
  • Fingerprint card

There seems to be additional documentation needed if you’ve changed your name before or if you’ve got a criminal record.

They reassured listeners that the judges in Austin, TX would not have an adversarial hearing. That’s to say, they won’t ask you why you’re doing this, what your gender is, etc. They’ll review your petition beforehand, and then you just need to be present in order to answer questions about missing documentation or documentation that needs clarification.

Another detail: as a resident of TX, you can choose any county in TX to undertake the procedure. Austin, TX rates favorably, based on information I overheard at the workshop. Also, if you were born in TX, but then move to another state, you can still complete this process in TX, even as a non-resident.

The expected fees for the full process are around $300-$400. These fees can be waived if you show that you’d be unable to pay them.

The most tedious process really seems to be about the aftermath - everything ELSE you need to change after getting legal recognition from the local government. For me, that amounts to at least:

  • Marriage license
  • Lease
  • Vehicle registration
  • Social security
  • Driver’s license
  • Business ownership
  • Bank accounts
  • Credit reporting agencies

That’s the gist of things. The Q hosted the workshop, and they seem pretty great.

So with that, my name will be Allele Dev in probably about three to four months, and my gender marker will be F.

]]> Queer Types - The Business https://queertypes.com/posts/53-announcing-queer-types.html 2015-10-16T00:00:00Z 2015-10-16T00:00:00Z I started my own business yesterday: Queer Types! I’m writing about it here to tell the story of how Queer Types came to be, and what it is.

Tech & Capitalism: do you wanna have a bad time?

I’ve worked in tech for almost three years now. The first year was the best, and things gradually went down hill from there. A few factors were at play in that decline.

My awareness of myself and the world around me was really low in 2012. Honestly, I didn’t know much about who I was, what I believed in, or where I was going. I just knew I had to get out of college, and that getting paid was a Good Thing.

At the time, I had no idea I was trans. I didn’t even know it was a thing I could be. I’m suspect I had some white, male-passing privilege helping me along. By the time April 2014 rolled around, I knew I was trans - I was out soon after that. Things gradually got worse at work, as I presented more and more femme, especially in 2014. 2015 was better, in this regard. Still, for every job after my first, I was the only woman on the teams I was assigned to. It’s really alienating to be the only trans person, the only woman, the only X - in any team situation.

Awareness - that spiked pretty quickly after I realized I was trans. I learned about all the different ways people are marginalized and oppressed, that there are irrefutable, intersectional systems that keep people down. Twitter played a significant role in my awareness increasing over time. I saw painful situations unfolding in real time. I listened carefully to people expressing their lived experiences. The first few months of analyzing my privilege were very uncomfortable. It still can be uncomfortable when I run into something I haven’t introspected on before. That got easier. It gets easier.

I couldn’t help but see those structures of oppression paralleled in every job I had. Expectations of long hours, more hours than my health could handle. Credit being taken by company “leadership” for the efforts of the workers. Blame being put on the workers when things didn’t work out as planned. Punishment for the workers when they spoke up about things being shitty, unrealistic, or unreasonable. I didn’t spend much time blaming individual actors, except for a few particularly toxic examples. The non-toxic participants were caught up in these sytems, and they need to make a living, too. My goals were fundamentally misaligned with things like Delivering Business Value, Minimum Viable Products, Profits. I’m not suited to quietly working in companies that want to keep to the exploitative status quo.

In a sense, all that time I’d been working (n+1) jobs: the 1 salaried, the remaining n, unpaid labor. Things like: writing articles about tech, taking extra time and care to ensure the things I made in my day job were of high quality and maintainable, publishing and maintaining open source libraries, crafting tutorials, following and reporting on tech trends. Others have written about all this before, several people, at different times - Unpaid Labor.

Taking inspiration from articles like this one on wages in tech, or this one, and realizing I couldn’t end Capitalism over night or escape it, I decided to seek my own path. I wanted to find a way to: work on my terms, with my ethics and capabilities in mind, and make it sustainable. If anything, that’s the origin story for Queer Types, at least three years in the making.

Queer Types: Setting Goals and Boundaries

I want to use the skills I have to help make the world a better place. I also want it to be on my terms.

Some terms I’ve set for myself:

  • I will not work on secret or proprietary software

I’ve spent enough time rebuilding CRUD app #37. At large, it’s also notable that we have more than 5 SQL databases, more than 4 web browsers, probably more than 20 text editors, and so on. There’s a lot of repetition, and for what?

I can understand the need for customization and tailoring tools for specific problems. However, what we have as a consequence of copyright and profit-driven-development is a rebuilding of the same fundamental things, over and over again. This is not a technical problem, this is a socioeconomic problem.

I want to avoid contributing to that senseless duplication.

  • I will not work on secret or proprietary research

Similarly, for research. Knowledge should flow as freely as possible. It’s easier than ever now, too.

  • I will work on software projects available to all

Generally, this means that the source is available and the licensing aligns with the goal of keeping the projects available to all.

  • I will make all my written works freely available

As with software. Yes, this includes books I intend to write.

  • I expect to be paid

See the origin story in the previous section. That I want to provide freely available works doesn’t mean I’ll allow myself to be exploited. I have to live, too. I do not condone Unpaid Labor, especially in a society that still thinks it’s right for people to have to Earn Their Right to Live.

  • Consent first

I’ll be working with others. I’ll respect their terms, too, and if they align, we can work together.

Queer Types: What Will it Do

Phrased differently, what can I do? I can write software, technical articles, tutorials, and books. I can also teach, make art, and consult.

So, keeping the terms and boundaries above in mind, I hope to offer the following services through Queer Types:

  • Technical writing
  • Technical workshops
  • Written tutorials
  • Software: implementation, design, testing, benchmarking
  • Drawing: cute things, technical things, cute & technical things
  • Awareness & advocacy

Notably, for drawings, this would go great with Patreon-acquired funding as a reward. You like what I do, I write you a small program, and then send you a hand-made drawing involving that program. We celebrate, because things are cute, and we both learn things. This line of thinking was inspired by sailorhg’s work on Bubble Sort zines. There’s no reason tech can’t be cute. ❤

On tech work specifically, I have no intention of covering the full software market. I know my specialties and preferences. I love typed, functional programming. I like backend and systems work, and I want to like frontend work. Technology-wise, this amounts to work involving some mix of:

  • Linux
  • Haskell
  • PureScript
  • Idris
  • Rust, maybe

Projects like Support JSON errors for PureScript (or other error reporting enhancements), improvements to cabal or stack, and other infrastructural/library work around any of the above languages, would be suitable for me.

Finance Models: Attempting Ethical Sustainability

So then, what do I do, and how do I maintain my terms and beliefs while I’m at it? It’s still a bit of an open problem, to be honest. My first two plans, both with short-comings:

  • Start a Patreon for my month-to-month efforts
  • Start a KickStarter/IndieGogo campaign for book work

Patreon mostly works, especially for requesting donations in exchange for cute things. The primary shortcoming is in the allocation of my resources (hours I can work per month) to various “rewards” tiers for larger scope work.

For example, I can create a reward tier for $1200/month that serves as a promise to a particular funder that I will work on a mutually-agreed project for 4 days. If I introduced more levels (more money, more promised days), the limit system fails me, because it works in terms of rewards given, rather than the global hours-I-can-work-per-month resource. Example:

  • 10 slots: $600/month for 2d of project work
  • 5 slots: $1200/month for 4d of project work

I can end up overcommitted with:

  • 4 instances of $600/month: 8d of work
  • 4 instances of $1200/month: 20d of work
  • Total: 28d of work

Also, things like:

  • Negotiating projects with potential funders (accept/reject/clarify/allocate)
  • Scheduling/managing projects (in progress/outcome reporting/pending)

would have to happen out-of-band. Might be a worthwhile weekend project to scrap together a site that interacts with a service like Stripe for payment processing but also gives me (and funders) the ability to visibly negotiate and track projects. I dunno. Open problem!

The IndieGogo campaign may be the best short term path. I have plans to write an accessible book on Haskell Web Development. I’d ask for $20000 as a minimum marker for writing such a book over a period of 3 months. That’d cover the cost of living for longer than 3 months, and there’d likely be weekly chapter releases, so funders can watch the book grow over time. Stretch goals would cover additional topics, additional mediums (screen casts?), and possibly an additional book (anything past the $60,000 mark).

Keeping with the previous section on my terms, the book would be freely available. It’d be akin to Real World Haskell or PureScript by Example - people can choose to pay for print copies, and Amazon/LeanPub/etc. can provide them, but the sources to build PDFs/etc. and run code will always be available in some source control repo. Also akin to the Bandcamp model for artists, where some works are offered on a “Name Your Price” basis: you can download it for free if you like, but if you’re able, donations are welcome.

Another possibility for funding would be to look towards something like Ruby Together. It seems that the Industrial Haskell Group is the closest analogue to this in Haskell land. It doesn’t sound anywhere near as appealing or welcoming as the Ruby Together effort. Maybe there’s room for another such organization? I don’t know. More open problems!

Closing

That’s the gist of it. I don’t want to work in our current systems, I want to set my boundaries, and I have a plan.

Next steps: figure out funding. You’ll all hear about that part pretty soon.

Long term goals: end capitalism?

]]> GHC base Library Changes - 7.8 to 7.10 https://queertypes.com/posts/52-ghc-changes.html 2015-10-04T00:00:00Z 2015-10-04T00:00:00Z While organizing old notes, I happened upon a file titled ghc-base-78-to-710.diff. The information inside turned out to be pretty interesting. I figured I’d throw it up here in case it’s of use to anyone.

Below is a summary of all the changes to the base library from GHC 7.8 to 7.10, by module, in diff format:

Control.Monad
  + (<$!>) :: Monad m => (a -> b) -> m a -> m b
  - class Monad m
  + class Applicative m => Monad m
  - class Monad m => MonadPlus m
  + class (Alternative m, Monad m) => MonadPlus m
  - foldM :: Monad m => (a -> b -> m a) -> a -> [b] -> m a
  + foldM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b
  - foldM_ :: Monad m => (a -> b -> m a) -> a -> [b] -> m ()
  + foldM_ :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m ()
  - forM :: Monad m => [a] -> (a -> m b) -> m [b]
  + forM :: (Traversable t, Monad m) => t a -> (a -> m b) -> m (t b)
  - forM_ :: Monad m => [a] -> (a -> m b) -> m ()
  + forM_ :: (Foldable t, Monad m) => t a -> (a -> m b) -> m ()
  - guard :: MonadPlus m => Bool -> m ()
  + guard :: (Alternative f) => Bool -> f ()
  - mapM :: Monad m => (a -> m b) -> [a] -> m [b]
  + mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b)
  - mapM_ :: Monad m => (a -> m b) -> [a] -> m ()
  + mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m ()
  - msum :: MonadPlus m => [m a] -> m a
  + msum :: (Foldable t, MonadPlus m) => t (m a) -> m a
  - sequence :: Monad m => [m a] -> m [a]
  + sequence :: (Traversable t, Monad m) => t (m a) -> m (t a)
  - sequence_ :: Monad m => [m a] -> m ()
  + sequence_ :: (Foldable t, Monad m) => t (m a) -> m ()
  - unless :: Monad m => Bool -> m () -> m ()
  + unless :: (Applicative f) => Bool -> f () -> f ()
  - when :: Monad m => Bool -> m () -> m ()
  + when :: (Applicative f) => Bool -> f () -> f ()
  
  Data.Bits
  + countLeadingZeros :: FiniteBits b => b -> Int
  + countTrailingZeros :: FiniteBits b => b -> Int
  + toIntegralSized :: (Integral a, Integral b, Bits a, Bits b) => a -> Maybe b
  
  Data.Monoid
  + Alt :: f a -> Alt f a
  + getAlt :: Alt f a -> f a
  + newtype Alt f a
  
  Data.List
  - all :: (a -> Bool) -> [a] -> Bool
  + all :: Foldable t => (a -> Bool) -> t a -> Bool
  - and :: [Bool] -> Bool
  + and :: Foldable t => t Bool -> Bool
  - any :: (a -> Bool) -> [a] -> Bool
  + any :: Foldable t => (a -> Bool) -> t a -> Bool
  - concat :: [[a]] -> [a]
  + concat :: Foldable t => t [a] -> [a]
  - concatMap :: (a -> [b]) -> [a] -> [b]
  + concatMap :: Foldable t => (a -> [b]) -> t a -> [b]
  - elem :: Eq a => a -> [a] -> Bool
  + elem :: (Foldable t, Eq a) => a -> t a -> Bool
  - find :: (a -> Bool) -> [a] -> Maybe a
  + find :: Foldable t => (a -> Bool) -> t a -> Maybe a
  - foldl :: (b -> a -> b) -> b -> [a] -> b
  + foldl :: Foldable t => (b -> a -> b) -> b -> t a -> b
  - foldl' :: (b -> a -> b) -> b -> [a] -> b
  + foldl' :: Foldable t => (b -> a -> b) -> b -> t a -> b
  - foldl1 :: (a -> a -> a) -> [a] -> a
  + foldl1 :: Foldable t => (a -> a -> a) -> t a -> a
  - foldr :: (a -> b -> b) -> b -> [a] -> b
  + foldr :: Foldable t => (a -> b -> b) -> b -> t a -> b
  - foldr1 :: (a -> a -> a) -> [a] -> a
  + foldr1 :: Foldable t => (a -> a -> a) -> t a -> a
  + isSubsequenceOf :: (Eq a) => [a] -> [a] -> Bool
  - length :: [a] -> Int
  + length :: Foldable t => t a -> Int
  - mapAccumL :: (acc -> x -> (acc, y)) -> acc -> [x] -> (acc, [y])
  + mapAccumL :: Traversable t => (a -> b -> (a, c)) -> a -> t b -> (a, t c)
  - mapAccumR :: (acc -> x -> (acc, y)) -> acc -> [x] -> (acc, [y])
  + mapAccumR :: Traversable t => (a -> b -> (a, c)) -> a -> t b -> (a, t c)
  - maximum :: Ord a => [a] -> a
  + maximum :: (Foldable t, Ord a) => t a -> a
  - maximumBy :: (a -> a -> Ordering) -> [a] -> a
  + maximumBy :: Foldable t => (a -> a -> Ordering) -> t a -> a
  - minimum :: Ord a => [a] -> a
  + minimum :: (Foldable t, Ord a) => t a -> a
  - minimumBy :: (a -> a -> Ordering) -> [a] -> a
  + minimumBy :: Foldable t => (a -> a -> Ordering) -> t a -> a
  - notElem :: Eq a => a -> [a] -> Bool
  + notElem :: (Foldable t, Eq a) => a -> t a -> Bool
  - null :: [a] -> Bool
  + null :: Foldable t => t a -> Bool
  - or :: [Bool] -> Bool
  + or :: Foldable t => t Bool -> Bool
  - product :: Num a => [a] -> a
  + product :: (Foldable t, Num a) => t a -> a
  + scanl' :: (b -> a -> b) -> b -> [a] -> [b]
  + sortOn :: Ord b => (a -> b) -> [a] -> [a]
  - sum :: Num a => [a] -> a
  + sum :: (Foldable t, Num a) => t a -> a
  + uncons :: [a] -> Maybe (a, [a])
  
  Foreign.Marshal.Alloc
  + calloc :: Storable a => IO (Ptr a)
  + callocBytes :: Int -> IO (Ptr a)
  
  Foreign.Marshal.Utils
  + fillBytes :: Ptr a -> Word8 -> Int -> IO ()
  
  Foreign.Marshal.Array
  + callocArray :: Storable a => Int -> IO (Ptr a)
  + callocArray0 :: Storable a => Int -> IO (Ptr a)
  
  Control.Exception.Base
  + AllocationLimitExceeded :: AllocationLimitExceeded
  + data AllocationLimitExceeded
  + displayException :: Exception e => e -> String
  
  Control.Exception
  + AllocationLimitExceeded :: AllocationLimitExceeded
  + data AllocationLimitExceeded
  + displayException :: Exception e => e -> String
  
  Prelude
  + (*>) :: Applicative f => f a -> f b -> f b
  + (<*) :: Applicative f => f a -> f b -> f a
  + (<*>) :: Applicative f => f (a -> b) -> f a -> f b
  - all :: (a -> Bool) -> [a] -> Bool
  + all :: Foldable t => (a -> Bool) -> t a -> Bool
  - and :: [Bool] -> Bool
  + and :: Foldable t => t Bool -> Bool
  - any :: (a -> Bool) -> [a] -> Bool
  + any :: Foldable t => (a -> Bool) -> t a -> Bool
  - class Monad m
  + class Applicative m => Monad m
  + class Monoid a
  + class Functor f => Applicative f
  + class Foldable t
  + class (Functor t, Foldable t) => Traversable t
  - concat :: [[a]] -> [a]
  + concat :: Foldable t => t [a] -> [a]
  - concatMap :: (a -> [b]) -> [a] -> [b]
  + concatMap :: Foldable t => (a -> [b]) -> t a -> [b]
  + data Word :: *
  - elem :: Eq a => a -> [a] -> Bool
  + elem :: (Foldable t, Eq a) => a -> t a -> Bool
  + foldMap :: (Foldable t, Monoid m) => (a -> m) -> t a -> m
  - foldl :: (b -> a -> b) -> b -> [a] -> b
  + foldl :: Foldable t => (b -> a -> b) -> b -> t a -> b
  - foldl1 :: (a -> a -> a) -> [a] -> a
  + foldl1 :: Foldable t => (a -> a -> a) -> t a -> a
  - foldr :: (a -> b -> b) -> b -> [a] -> b
  + foldr :: Foldable t => (a -> b -> b) -> b -> t a -> b
  - foldr1 :: (a -> a -> a) -> [a] -> a
  + foldr1 :: Foldable t => (a -> a -> a) -> t a -> a
  - length :: [a] -> Int
  + length :: Foldable t => t a -> Int
  - mapM :: Monad m => (a -> m b) -> [a] -> m [b]
  + mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b)
  - mapM_ :: Monad m => (a -> m b) -> [a] -> m ()
  + mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m ()
  + mappend :: Monoid a => a -> a -> a
  - maximum :: Ord a => [a] -> a
  + maximum :: (Foldable t, Ord a) => t a -> a
  + mconcat :: Monoid a => [a] -> a
  + mempty :: Monoid a => a
  - minimum :: Ord a => [a] -> a
  + minimum :: (Foldable t, Ord a) => t a -> a
  - notElem :: Eq a => a -> [a] -> Bool
  + notElem :: (Foldable t, Eq a) => a -> t a -> Bool
  - null :: [a] -> Bool
  + null :: Foldable t => t a -> Bool
  - or :: [Bool] -> Bool
  + or :: Foldable t => t Bool -> Bool
  - product :: Num a => [a] -> a
  + product :: (Foldable t, Num a) => t a -> a
  + pure :: Applicative f => a -> f a
  - sequence :: Monad m => [m a] -> m [a]
  + sequence :: (Traversable t, Monad m) => t (m a) -> m (t a)
  + sequenceA :: (Traversable t, Applicative f) => t (f a) -> f (t a)
  - sequence_ :: Monad m => [m a] -> m ()
  + sequence_ :: (Foldable t, Monad m) => t (m a) -> m ()
  - sum :: Num a => [a] -> a
  + sum :: (Foldable t, Num a) => t a -> a
  + traverse :: (Traversable t, Applicative f) => (a -> f b) -> t a -> f (t b)
  
  Data.Function
  + (&) :: a -> (a -> b) -> b
  
  Control.Monad.Instances
  - class Monad m
  + class Applicative m => Monad m
  
  Data.Coerce
  - coerce :: Coercible k a b => a -> b
  + coerce :: Coercible * a b => a -> b
  
  Data.Version
  + makeVersion :: [Int] -> Version
  
  Data.Complex
  - cis :: RealFloat a => a -> Complex a
  + cis :: Floating a => a -> Complex a
  - conjugate :: RealFloat a => Complex a -> Complex a
  + conjugate :: Num a => Complex a -> Complex a
  - imagPart :: RealFloat a => Complex a -> a
  + imagPart :: Complex a -> a
  - mkPolar :: RealFloat a => a -> a -> Complex a
  + mkPolar :: Floating a => a -> a -> Complex a
  - realPart :: RealFloat a => Complex a -> a
  + realPart :: Complex a -> a
  
  Data.Foldable
  + length :: Foldable t => t a -> Int
  + null :: Foldable t => t a -> Bool
  
  System.Exit
  + die :: String -> IO a
  
  Numeric.Natural
  + data Natural
  
  Data.Bifunctor
  + bimap :: Bifunctor p => (a -> b) -> (c -> d) -> p a c -> p b d
  + class Bifunctor p
  + first :: Bifunctor p => (a -> b) -> p a c -> p b c
  + second :: Bifunctor p => (b -> c) -> p a b -> p a c
  
  Data.Functor.Identity
  + Identity :: a -> Identity a
  + newtype Identity a
  + runIdentity :: Identity a -> a
  
  Data.Void
  + absurd :: Void -> a
  + data Void
  + vacuous :: Functor f => f Void -> f a
]]>