{-# LANGUAGE Safe #-}
{- arch-tag: Either utilities
Copyright (c) 2004-2011 John Goerzen <jgoerzen@complete.org>

All rights reserved.

For license and copyright information, see the file LICENSE
-}

{- |
   Module     : Data.Either.Utils
   Copyright  : Copyright (C) 2004-2011 John Goerzen
   SPDX-License-Identifier: BSD-3-Clause

   Stability  : stable
   Portability: portable

Utilities for working with the Either data type

-}
module Data.Either.Utils
    (
     maybeToEither,
     forceEither,
     forceEitherMsg,
     eitherToMonadError,
     fromLeft, fromRight, fromEither
) where

import Control.Monad.Except ( MonadError(..) )

{- | 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 :: forall e (m :: * -> *) a. MonadError e m => e -> Maybe a -> m a
maybeToEither e
errorval Maybe a
Nothing   = e -> m a
forall e (m :: * -> *) a. MonadError e m => e -> m a
throwError e
errorval
maybeToEither e
_ (Just a
normalval) = a -> m a
forall (m :: * -> *) a. Monad m => a -> m a
return a
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 :: forall e a. Show e => Either e a -> a
forceEither (Left e
x)  = [Char] -> a
forall a. HasCallStack => [Char] -> a
error (e -> [Char]
forall a. Show a => a -> [Char]
show e
x)
forceEither (Right a
x) = a
x

{- | Like 'forceEither', but can raise a specific message with the error. -}
forceEitherMsg :: Show e => String -> Either e a -> a
forceEitherMsg :: forall e a. Show e => [Char] -> Either e a -> a
forceEitherMsg [Char]
msg (Left e
x) = [Char] -> a
forall a. HasCallStack => [Char] -> a
error ([Char] -> a) -> [Char] -> a
forall a b. (a -> b) -> a -> b
$ [Char]
msg [Char] -> [Char] -> [Char]
forall a. [a] -> [a] -> [a]
++ [Char]
": " [Char] -> [Char] -> [Char]
forall a. [a] -> [a] -> [a]
++ e -> [Char]
forall a. Show a => a -> [Char]
show e
x
forceEitherMsg [Char]
_ (Right a
x)  = a
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 :: forall e (m :: * -> *) a. MonadError e m => Either e a -> m a
eitherToMonadError (Left e
x)  = e -> m a
forall e (m :: * -> *) a. MonadError e m => e -> m a
throwError e
x
eitherToMonadError (Right a
x) = a -> m a
forall (m :: * -> *) a. Monad m => a -> m a
return a
x


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

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

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