overhang provides convenience combinators for clean, "hanging" lambdas and depends only on base. The gist of this library is offering variants of functions with parameter orders more conducive to finishing off the function call with a lambda. When using Data.Foldable, sometimes we reach for for_ / forM_ instead of traverse / mapM_ so we that can define the Applicative / Monad computation right there in a lambda instead of making a separate function. That is the guiding principle of this library.

This package contains a single module and is intended to be imported qualified so that function intents are clear. The Getting Started section walks through a concrete example.

Suppose we need to do something with an Either String [Word16] value:

main :: IO ()
main = do
  result <- readSamples someCd :: IO (Either String [Word16])
  -- do some stuff...

We have a few choices. One choice is explicit pattern matching:

main :: IO ()
main = do
  result <- readSamples someCd :: IO (Either String [Word16])
  case result of
    Left errString -> do
      putStrLn "R.I.P. to the CD, can't even play my hits!"
      putStrLn $ "Failure: " <> errString
      exitFailure
    Right samples -> playOnRepeat samples

Another option is to use the either function from Data.Either:

main :: IO ()
main = do
  result <- readSamples someCd :: IO (Either String [Word16])
  either (\errString -> do
             putStrLn "R.I.P. to the CD, can't even play my hits!"
             putStrLn $ "Failure: " <> errString
             exitFailure)
         playOnRepeat
         result

We have gotten rid of explicit pattern matching, but the code doesn't exactly look nice (subjective!), particularly in the handler for the Left case.

A third option is to use the ExceptT monad transformer:

main :: IO ()
main = do
  result <- runExceptT $ do
    samples <- ExceptT (readSamples someCd) :: ExceptT String IO [Word16]
    liftIO (playOnRepeat samples)
  -- Now what?  We'll pattern match, but this feels like extra work...
  case result of
    Left errString -> do
      putStrLn "R.I.P. to the CD, can't even play my hits!"
      putStrLn $ "Failure: " <> errString
      exitFailure
    Right () -> pure ()

That was not super fun and arguably the least readable of all the examples so far. For me, it is often the case when I'm processing an Either a b value that I have a teensy bit of work to do on one of the cases, and a bit more work to do on the other case.

What if we switched the parameters around to either and gave it a new name, like onLeft?

import qualified Overhang

main :: IO ()
main = do
  result <- readSamples someCd :: IO (Either String [Word16])
  Overhang.onLeft result playOnRepeat $ \errString -> do
    putStrLn "R.I.P. to the CD, can't even play my hits!"
    putStrLn $ "Failure: " <> errString
    exitFailure

Tada! We have gotten rid of explicit pattern matching just like we did with either, and depending on who you ask, the code is much more readable.

In the example, we were only dealing with a single Either value. Sometimes we have to deal with Eithers of Eitherss, Eithers of Maybes and so on. overhang can help in these cases when we just want to neatly process the structures and not pull in a large (but way more powerful!) dependency like lens.