    {- arch-tag: Euither utilities
    Copyright (C) 2004-2006 John Goerzen <jgoerzen@complete.org>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
    -}

    {- |
       Module     : Data.Either.Utils
       Copyright  : Copyright (C) 2004-2006 John Goerzen
       License    : GNU GPL, version 2 or above

       Maintainer : John Goerzen <jgoerzen@complete.org>
       Stability  : provisional
       Portability: portable

    Utilities for working with the Either data type

    Copyright (c) 2004 John Goerzen, jgoerzen\@complete.org
    -}
    module Data.Either.Utils
        (
         maybeToEither,
         forceEither,
         forceEitherMsg,
         eitherToMonadError,
         fromLeft, fromRight, fromEither
    ) where
    import Control.Monad.Error

    {- | Converts a Maybe value to an Either value, using the supplied parameter
    as the Left value if the Maybe is Nothing.

    This function can be interpreted as:

    @maybeToEither :: e -> Maybe a -> Either e a@

    Its definition is given as it is so that it can be used in the Error and related monads.

    -}
    maybeToEither :: MonadError e m =>
                     e                      -- ^ (Left e) will be returned if the Maybe value is Nothing
                  -> Maybe a                -- ^ (Right a) will be returned if this is (Just a)
                  -> m a
    maybeToEither errorval Nothing = throwError errorval
    maybeToEither _ (Just normalval) = return normalval

    {- | Pulls a "Right" value out of an Either value.  If the Either value is
    Left, raises an exception with "error". -}
    forceEither :: Show e => Either e a -> a
    forceEither (Left x) = error (show x)
    forceEither (Right x) = x

    {- | Like 'forceEither', but can raise a specific message with the error. -}
    forceEitherMsg :: Show e => String -> Either e a -> a
    forceEitherMsg msg (Left x) = error $ msg ++ ": " ++ show x
    forceEitherMsg _ (Right x) = x

    {- | Takes an either and transforms it into something of the more generic
    MonadError class. -}
    eitherToMonadError :: MonadError e m => Either e a -> m a
    eitherToMonadError (Left x) = throwError x
    eitherToMonadError (Right x) = return x

    -- | Take a Left to a value, crashes on a Right
    fromLeft :: Either a b -> a
    fromLeft (Left a) = a
    fromLeft _ = error "Data.Either.Utils.fromLeft: Right"

    -- | Take a Right to a value, crashes on a Left
    fromRight :: Either a b -> b
    fromRight (Right a) = a
    fromRight _ = error "Data.Either.Utils.fromRight: Left"

    -- | Take an Either, and return the value inside it
    fromEither :: Either a a -> a
    fromEither (Left a) = a
    fromEither (Right a) = a