Either monad

Let’s talk monads again. And this time, I will show you the either monad. We’ll use it to model a process whose steps can fail; and we wish to abort the process whenever a step fails (and return the failures) and we wish to continue the process if the step succeeds.

The practical application is to use the either monad is code that prepares some HTTP requests, sends the requests and then parses the responses. In pseudo-code, we have:

prepare:        S => Either[Errors, Payload] 
request:  Payload => Either[Errors, Payload]
parse:    Payload => Either[Errors, R]

Where S is some starting type and R is the final return type. As you can probably tell, the entire operation is

op:   S => Either[Errors, R]

We now want to bind the three steps into the final op: the either monad will allow a value on the right to flow through the operation, while a value on the left will stop the process and immediately be returned. Still keeping with pseudo-code, we assemble the beast as

op(source: S) = prepare(source) >>= request >>= parse

The notion of a workflow helps; indeed, the operation op is best imagined as simple operation followed by decision:

Adding some type annotations will make the flow of values even clearer:

Right. Let’s turn on the real syntax and type up some almost complete Scala code:

import scalaz._
import Scalaz._

sealed trait Failure
case class ServiceUnavailable(message: String) extends Failure
case class TheSonsOfKhanAreRebelling() extends Failure
// and more to taste

case class Payload(contentType: String, body: String)

case class Input(...)
case class ParserSettings(...)

def work(input: Input, parserSettings: ParserSettings): 
  Either[Seq[Failure], Integer] = {

  def prepare(input: Input): Either[Seq[Failure], Payload] = {
    // do some work, ultimately hopefully
    Right(Payload("application/json", "..."))
  }

  def request(payload: Payload): Either[Seq[Failure], Payload] = {
    // prepare request
    val httpClient = new DefaultHttpClient()
    val post = new HttpPost("/location/to/post")

    // make the entity
    val entity = new StringEntity(payload.body)
    entity.setContentType(payload.contentType)
    post.setEntity(entity)

    // perform the post
    try {
      httpClient.execute(new HttpHost("localhost", 80, "http"), 
        post, new ResponseHandler[Either[Seq[Failure], Payload] {
        def handleResponse(response: HttpResponse) = {
          val entity = response.getEntity
          // process the input, ultimately returning
          Right(Payload("application/json", "...")
        }
      })
    } catch {
      case e: Exception => Left(ServiceUnavailable(e.getMessage) :: Nil)
    }
  }

  def parse(parserSettings: ParserSettings)
           (payload: Payload): Either[Seq[Failure], Integer] = {
    // use the parserSettings, but ultimately, parse and
    // somehow calculate, returning from the payload
    Right(42)
  }

  // We now have the three steps. Let's bind them together.
  prepare(input) >>= request >>= parse(parserSettings)
}

And so, using the either monad in Scalaz 6, we have bound together our functions into a workflow-like structure. The behaviour of the either monad (either monad because the return type of the steps is Either[_, _]) stops & returns whenever a step returns a value on the left and continues to the next step, passing the returned value on the right from the previous step to it.

The end result is nicely readable code and less work for you to propagate—in this particular case—failures.