errors-1.0: Simplified error handling

Update

I just released a quick patch changing a dependency from the EitherT package to the Either package. What this means is that if you already installed version 1.0 and upgrade to 1.1, you will have two packages exporting conflicting modules for Control.Monad.Trans.Either. The fix is very simple. Just type:

ghc-pkg hide EitherT

Which will hide the EitherT package so it does not conflict.

I tried to make this fix as rapidly as possible to mitigate the damage. I apologize, but somebody notified me that either is a higher quality dependency for the EitherT type.

Introduction

This post marks the release of errors-1.0, a package designed to fill all the gaps in type-safe error handling. I target this package specifically towards Haskell programmers that prefer to use Maybe and Either for type-safe exception handling, yet get frustrated by thousands of paper-cuts every time some convenient function is missing.

Now, all those pain points are gone, and instead of an import list that looks something like this:

import Control.Monad.Trans.Either
import Data.Maybe
import Safe
...

You now can just import:

import Control.Error

Utility Functions

Control.Error re-exports Control.Error.Util, which provides some very useful utility functions:

hush       :: Either a b -> Maybe b
note       :: a -> Maybe b -> Either a b
hushT      :: Monad m => EitherT a m b -> MaybeT m b
noteT      :: Monad m => a -> MaybeT m b -> EitherT a m b

liftMaybe  :: Monad m => Maybe b    -> MaybeT m b
liftEither :: Monad m => Either a b -> EitherT a m b

I'm pretty sure every experienced Haskell programmer has desired either the hush or note functions at some point and ended up either in-lining it into their code or defining it in some sort of Util module of their project.

It's quite frustrating, actually. We frequently encounter code that uses a mixture of Maybe or Either and want to combine them both within the same monad, but when we search using Hoogle or Hayoo for a function like hush, we get just one result:

Precis.Utils.ControlOperators.suppress :: Either e a -> Maybe a

This exemplifies one such utility function that the precis package wrote to scratch its own itch. Who would want to make the precis package a dependency for such a trivial function, especially when the precis package has nothing to do with error-handling?

I also couldn't even find an equivalent to the note function, although perhaps that's just because my Hoogle-fu isn't strong enough. However, I find it surprising that such a useful conversion function does not reside in some standard location on Hackage. Well, now it officially resides in the errors package.

Teaching

Also, most Haskell aficionados know that liftMaybe and liftEither are easy to write:

liftMaybe  = MaybeT  . return
liftEither = EitherT . return

However, many beginners to Haskell don't know how to lift a Maybe to a MaybeT and would benefit from the above function. Imagine a beginner Hoogling for:

(Monad m) => Maybe a -> MaybeT m a

... and instead of getting a bunch of almost-correct matches, they get an exact match and they can click the link to the liftMaybe function, consult the source code and have an "AHA!" moment where they learn a bit more about how monad transformers work. I'll wager there are many Haskell beginners right now that give up on using Maybes within MaybeT because they don't even know it's possible to do so. Well, now they do.

Social Confirmation

I designed the errors library to encourage type-safe error-handling style in Haskell, showing beginners that they can use the type system to handle errors painlessly, without using out-of-band language features like Control.Exception.

While I have nothing against Control.Exception, I'm worried that the proliferation of libraries revolving around it along with the absence of high-quality and instructive Either/EitherT libraries might lead beginners to believe that Haskell does not have a type-safe, simple, and easy way to handle errors. They might even lose interest in the language because they mistakenly feel it does not live up to their expectations of elegance and simplicity. After all, how can functional programming be so great if it can't do something as simple as error handling elegantly?

A recent post on reddit emphasizes that we shouldn't take for granted that beginners even know how to integrate high quality Maybe/Either code in complicated applications. All the expert knowledge of how to seamlessly inter-convert the various error-handling styles types gets locked away in people's pet utility libraries. This package solves that problem by providing easily accessible source code that beginner's can use and learn from.

More importantly, I designed the library to encourage beginners to use the type-safe error-handling style by providing a sort of social confirmation that is lacking on Hackage. The lack of a type-safe error handling ecosystem acts like a social cue to beginners that perhaps they are going down the wrong path and should reconsider. After all, if Either is supposedly the right way to handle errors, why does it seem like nobody cares about it enough to create a proper package covering common use cases? Well, now they know at least one person cares.

Scripting

Control.Error also exports Control.Error.Script, which covers the common use case of simple scripting:

type Script a = EitherT String IO a

The entire module provides a way to convert between Control.Exception and EitherT, so that people who prefer to not use Control.Exception now have a standard way to interface it with EitherT-style code. The most important function in the module is:

{- NOTE: This has been renamed to "scriptIO" and "tryIO" now resides in
         Control.Error.Util and only catches IO exceptions -}
tryIO :: IO a -> Script a

... which is like lift except that it also catches exceptions and translates them into Lefts. It also provides convenience functions to bind Maybes and Eithers within the monad:

tryMaybe :: String -> Maybe a -> Script a
tryEither :: Either String r -> Script r

These seem a little bit cumbersome to use at first, since you'd have to take all your favorite partial functions and convert them to Maybe or Either first and then pass them to tryMaybe/tryEither ... or do you?

Fortunately for you, this library has "batteries included", and Control.Error also exports the Control.Error.Safe module which wraps all your favorite partial functions both in the Either and EitherT monad.

The Either variants close a gaping hole in the safe library, where the only way you could attach a descriptive error message was using exceptions (again, this is the kind of social cue I'm talking about). Also, the EitherT variants are incredibly useful within the Script monad, where you can now seamlessly bind all your favorite error-handling functions of all types in the same monad:

import Control.Error
import System.Environment

main = runScript $ do
    as <- tryIO getArgs
    (file, n) <- case as of
        [file, n'] -> do
            n <- tryRead "Could not parse LINENUM" n'
            return (file, n)
        _ -> throwT "Usage: MYPROGRAM FILE LINENUM"
    str <- tryIO $ readFile file
    line <- tryAt "Line not found" (lines str) n
    tryIO $ putStrLn line

Notice the pattern? Everything that can be bound in the Script monad begins with the prefix try. A future release of the library will also provide versions with the default error messages (i.e. "Prelude.read: no parse"), but I just haven't decided what to name those versions, yet.

Also, notice that you don't have to import Control.Monad.Trans since for the special case of the Script monad the tryIO function serves the role of lift. The compiler error for the lack of Control.Monad.Trans is a nice reminder that you used lift instead of tryIO by mistake.

Why not ErrorT?

I'm a huge fan of the transformers package, with one major exception: ErrorT.

The first reason is that ErrorT comes with the additional baggage of the Error class, which really has no place in a proper EitherT implementation. I don't know how many times I've tried using that type, got hit by the Error class constraint, and threw up my hands in disgust and went back to EitherT (provided by the appropriately-named EitherT package and re-exported by Control.Error).

However, there is a deeper reason that I'm basing my library on EitherT and not ErrorT, which is the implementation of catchError and throwError.

For the longest time, I never appreciated that throw and catch in any Either-like block are actually return and (>>=) in the dual Either monad (the one with the type variables swapped). I missed this because the types of catchError and throwError I would see in every library were never made fully polymorphic:

-- The non-monad-transformer versions, for simplicity
throwError :: e -> Either e r
catchError :: Either e r -> (e -> Either e r) -> Either e r

If I generalized the two above function signatures to be fully polymorphic, you'd have something that looks remarkably like the signatures for return and (>>=):

throwE/return :: a -> Either a r
catchE/(>>=)  :: Either a r -> (a -> Either b r) -> Either b r

In fact, if you just used a newtype to swap the type variables, you'd have something that works exactly like a monad:

newtype EitherR r e = EitherR { runEitherR :: Either e r }

return :: a -> EitherR r a
return :: a ->         m a
return = throwE -- except with newtypes

(>>=)  :: EitherR r a -> (a -> EitherR r b) -> EitherR r b
(>>=)  ::         m a -> (a ->         m b) ->         m b
(>>=) = catchE -- except with newtypes

So now we have the ability to not only throw and catch exceptional values, but to even change the type of the exceptional value. I like to call this the "success" monad (after ehird's term for it, since he was the one who pointed out this awesome symmetry to me). In this monad, each statement is an exception handler and the monad terminates when you "throw" a successful result:

runEitherRT $ do
    e2 <- ioExceptionHandler e1
    bool <- arithmeticExceptionhandler e2
    when bool $ lift $ putStrLn "DEBUG: Something happened"
    succeed () -- the dual of "throw"
    -- Statements beyond here will not be evaluated
    notEvaluated

If any handler succeeds (by returning a Right result), the entire monad terminates with the successful result.

Laws for throwE and catchE

In fact, since throwE and catchE are just return and (>>=) in disguise, we can use the monad laws to state the behavior that throwE and catchE are expected to satisfy:

-- return x >>= f = f x
throwE x `catchE` f = f x

-- m >>= return = m
m `catchE` throwE = m

-- (m >>= f) >>= g = m >>= (\x -> f x >>= g)
(m `catchE` f) `catchE` g = m `catchE` (\e -> f e `catchE` g)

If you spend a moment to think about all of those laws they all make intuitive sense. They each say, respectively:

• If you throw a value, the catch block processes it
• If your catch block just rethrows the error, it's the same as not catching in the first place
• Catch blocks are associative

These laws exactly match our intuition for how throwE and catchE should behave!

If all of this excites you, then you'll love Data.EitherR, which is one of the modules exported by Control.Error. It provides all the machinery necessary for working in the EitherR monad and also provides the convenience functions for the generalized throw and catch:

throwE :: e -> Either e r
catchE :: Either a r -> (a -> Either b r) -> Either b r

These are just newtype wrappers around the return and (>>=) in the success monad. If all you want is throwE and catchE, then you never need to actually use EitherR directly and the above functions are sufficient.

Also, technically you could just use Either itself to implement the "success" monad by just reversing the convention for the type variables and use throwE and catchE to implement the error monad. However, the main reason you might not want to do that is to not confuse other people who are familiar with the traditional convention for Either. People will understand your code better if you stick to Either for code that terminates on errors and EitherR for code that terminates on successes.

Additionally, if you want to actually switch between both monads in your code and use ordinary do notation for each one, then the EitherR and EitherRT newtypes will be absolutely essential to convert between both monads.

Simplicity

There's one last thing that's nice about Control.Error: it re-exports Data.Either and Data.Maybe. It's just one nice little feature that helps trim down your import list.

I always enjoy coming up with compelling and interesting Haskell code examples in as few lines as possible, and keeping the import list clean is just one of those "nice" things when showing people from other languages how clean and simple Haskell can be. My rule of thumb is that if you really want to impress other people with Haskell, then show them how much power you can fit clearly and expressively into a single 80x24 terminal window, including all imports and extensions.

Conclusions

Hopefully this library will help shrink up a lot of people's utility modules and encourage the Either/EitherT style of error-handling. Let me know if there is a feature that you think is missing from this library, because the goal of this library is to make error handling as simple and painless as possible.