data-easy 0.4 → 0.5

raw patch · 2 files changed

+271/−31 lines, 2 filesdep ~basePVP ok

version bump matches the API change (PVP)

Dependency ranges changed: base

API changes (from Hackage documentation)

Files

• data-easy.cabal +2/−3
• src/Data/Easy.hs +269/−28

@@ -1,5 +1,5 @@ name:                data-easy-version:             0.4+version:             0.5 synopsis:            Consistent set of utility functions for Maybe, Either, List, Monoids. description:         Easy to use set of utility functions, implementing a Data.Maybe like                      interface for other common types, like Either, List, Bool, Tuple, @@ -29,8 +29,7 @@   -- other-modules:             -- Other library packages from which modules are imported.-  build-depends   : base          >= 4.6 && < 4.8-                  , either        >= 4.1.1+  build-depends   : base          >= 4.6 && < 4.9                   , safe          >= 0.3.3                   , containers    >= 0.5.0.0   

@@ -4,13 +4,6 @@ -- @'Bool'@ counterparts to the functions originally defined in -- "Data.Maybe", whenever applicable. ----- Most functions of "Data.Maybe" are re-exported, so you may import just this--- module instead. The only exception(s) are partial functions such as--- fromJust. Here, the safer alternatives from the "Safe" package are--- prefered (and imported) instead. All functions that take a default value--- as a replacement for an invalid value usually accept it as their first--- parameter, inline with the convention followed by the "Safe" package.--- -- This module also adds some extra useful functions, that can be found -- in otherwise disperse packages, pages, mailing lists, etc. -- A relevant link will be included whenever appropriate, or just a simple@@ -41,8 +34,8 @@ -- -- @utility-ht@ : <http://hackage.haskell.org/package/utility-ht> ----- Note that "Safe" and @either@ (the "Data.Either.Combinators" module) are--- re-exported by this module. Please notify me if you think I'm missing+-- Note that the "Safe" module is re-exported by this module.+-- Please notify me if you think I'm missing -- some other library. -- -- For monad related functions, check my other related module,@@ -55,13 +48,7 @@ -- module Data.Easy   ( -- * Module exports-    module Data.Maybe-  , module Data.Either-  , module Data.Either.Combinators-  , module Data.Tuple-  , module Data.Ord-  , module Data.Function-  , module Safe+    module Safe    -- * Additional functions @@ -73,8 +60,23 @@   , monoidToMaybe    -- ** Either-  -- | Many of the functions are already defined in either "Data.Either" or-  -- "Data.Either.Combinators" from the "either" package.+  -- | Copied most of the functions from "Data.Either.Combinators",+  -- from the "either" package. This package has a huge import list,+  -- unnecessary for such simple combinators.+  , fromLeft+  , fromRight+  , fromLeft'+  , fromRight'+  , mapBoth+  , mapLeft+  , mapRight+  , whenLeft+  , whenRight+  , unlessLeft+  , unlessRight+  , leftToMaybe+  , rightToMaybe+   , fromRightNote   , fromLeftNote   , fromEither@@ -263,14 +265,15 @@  import Data.Maybe import Data.Either-#if __GLASGOW_HASKELL__ >= 707-import Data.Either.Combinators hiding (isLeft,isRight)-#else-import Data.Either.Combinators-#endif-import Data.Tuple-import Data.Ord-import Data.Function+-- #if __GLASGOW_HASKELL__ >= 707+-- import Data.Either.Combinators hiding (isLeft,isRight)+-- #else+-- import Data.Either.Combinators+-- #endif+import Control.Applicative+{-import Data.Tuple-}+{-import Data.Ord-}+{-import Data.Function-} import Data.Monoid import Safe import qualified Data.List as L@@ -296,6 +299,243 @@ -- Either -------------------------------------------------------------------- ------------------------------------------------------------------------------ +-- From Data.Either.Combinators ----------------------------------------------++-- ---------------------------------------------------------------------------+-- Functions over Either++-- | Extracts the element out of a 'Left' and+-- throws an error if its argument take the form  @'Right' _@.+--+-- Using @Control.Lens@:+--+-- @+-- 'fromLeft'' x ≡ x^?!_Left+-- @+--+-- >>> fromLeft' (Left 12)+-- 12+fromLeft' :: Either a b -> a+fromLeft' (Right _) = error "Data.Easy.fromLeft: Argument takes form 'Right _'" -- yuck+fromLeft' (Left x)  = x++-- | Extracts the element out of a 'Right' and+-- throws an error if its argument take the form @'Left' _@.+--+-- Using @Control.Lens@:+--+-- @+-- 'fromRight'' x ≡ x^?!_Right+-- @+--+-- >>> fromRight' (Right 12)+-- 12+fromRight' :: Either a b -> b+fromRight' (Left _)  = error "Data.Easy.fromRight: Argument takes form 'Left _'" -- yuck+fromRight' (Right x) = x++-- | The 'mapBoth' function takes two functions and applies the first if iff the value+-- takes the form @'Left' _@ and the second if the value takes the form @'Right' _@.+--+-- Using @Data.Bifunctor@:+--+-- @+-- 'mapBoth' = bimap+-- @+--+-- Using @Control.Arrow@:+--+-- @+-- 'mapBoth' = ('Control.Arrow.+++')+-- @+--+-- >>> mapBoth (*2) (*3) (Left 4)+-- Left 8+--+-- >>> mapBoth (*2) (*3) (Right 4)+-- Right 12+mapBoth :: (a -> c) -> (b -> d) -> Either a b -> Either c d+mapBoth f _ (Left x)  = Left (f x)+mapBoth _ f (Right x) = Right (f x)++-- | The 'mapLeft' function takes a function and applies it to an Either value+-- iff the value takes the form @'Left' _@.+--+-- Using @Data.Bifunctor@:+--+-- @+-- 'mapLeft' = first+-- @+--+-- Using @Control.Arrow@:+--+-- @+-- 'mapLeft' = ('Control.Arrow.left')+-- @+--+-- Using @Control.Lens@:+--+-- @+-- 'mapLeft' = over _Left+-- @+--+-- >>> mapLeft (*2) (Left 4)+-- Left 8+--+-- >>> mapLeft (*2) (Right "hello")+-- Right "hello"+mapLeft :: (a -> c) -> Either a b -> Either c b+mapLeft f = mapBoth f id++-- | The 'mapRight' function takes a function and applies it to an Either value+-- iff the value takes the form @'Right' _@.+--+-- Using @Data.Bifunctor@:+--+-- @+-- 'mapRight' = second+-- @+--+-- Using @Control.Arrow@:+--+-- @+-- 'mapRight' = ('Control.Arrow.right')+-- @+--+-- Using @Control.Lens@:+--+-- @+-- 'mapRight' = over _Right+-- @+--+-- >>> mapRight (*2) (Left "hello")+-- Left "hello"+--+-- >>> mapRight (*2) (Right 4)+-- Right 8+mapRight :: (b -> c) -> Either a b -> Either a c+mapRight = mapBoth id++-- | The 'whenLeft' function takes an 'Either' value and a function which returns a monad.+-- The monad is only executed when the given argument takes the form @'Left' _@, otherwise+-- it does nothing.+--+-- Using @Control.Lens@:+--+-- @+-- 'whenLeft' ≡ forOf_ _Left+-- @+--+-- >>> whenLeft (Left 12) print+-- 12+whenLeft :: Applicative m => Either a b -> (a -> m ()) -> m ()+whenLeft (Left x) f = f x+whenLeft _        _ = pure ()++-- | The 'whenRight' function takes an 'Either' value and a function which returns a monad.+-- The monad is only executed when the given argument takes the form @'Right' _@, otherwise+-- it does nothing.+--+-- Using @Data.Foldable@:+--+-- @+-- 'whenRight' ≡ 'forM_'+-- @+--+-- Using @Control.Lens@:+--+-- @+-- 'whenRight' ≡ forOf_ _Right+-- @+--+-- >>> whenRight (Right 12) print+-- 12+whenRight :: Applicative m => Either a b -> (b -> m ()) -> m ()+whenRight (Right x) f = f x+whenRight _         _ = pure ()++-- | A synonym of 'whenRight'.+unlessLeft :: Applicative m => Either a b -> (b -> m ()) -> m ()+unlessLeft = whenRight++-- | A synonym of 'whenLeft'.+unlessRight :: Applicative m => Either a b -> (a -> m ()) -> m ()+unlessRight = whenLeft++-- | Extract the left value or a default.+--+-- @+-- 'fromLeft' ≡ 'either' 'id'+-- @+--+-- >>> fromLeft "hello" (Right 42)+-- "hello"+--+-- >>> fromLeft "hello" (Left "world")+-- "world"+fromLeft :: a -> Either a b -> a+fromLeft _ (Left x) = x+fromLeft x _ = x++-- | Extract the right value or a default.+--+-- @+-- 'fromRight' b ≡ 'either' b 'id'+-- @+--+-- >>> fromRight "hello" (Right "world")+-- "world"+--+-- >>> fromRight "hello" (Left 42)+-- "hello"+fromRight :: b -> Either a b -> b+fromRight _ (Right x) = x+fromRight x _ = x++-- | Maybe get the 'Left' side of an 'Either'.+--+-- @+-- 'leftToMaybe' ≡ 'either' 'Just' ('const' 'Nothing')+-- @+--+-- Using @Control.Lens@:+--+-- @+-- 'leftToMaybe' ≡ preview _Left+-- 'leftToMaybe' x ≡ x^?_Left+-- @+--+-- >>> leftToMaybe (Left 12)+-- Just 12+--+-- >>> leftToMaybe (Right 12)+-- Nothing+leftToMaybe :: Either a b -> Maybe a+leftToMaybe = either Just (const Nothing)++-- | Maybe get the 'Right' side of an 'Either'.+--+-- @+-- 'rightToMaybe' ≡ 'either' ('const' 'Nothing') 'Just'+-- @+--+-- Using @Control.Lens@:+--+-- @+-- 'rightToMaybe' ≡ preview _Right+-- 'rightToMaybe' x ≡ x^?_Right+-- @+--+-- >>> rightToMaybe (Left 12)+-- Nothing+--+-- >>> rightToMaybe (Right 12)+-- Just 12+rightToMaybe :: Either a b -> Maybe b+rightToMaybe = either (const Nothing) Just++-- New functions / Renamed functions -----------------------------------------+ -- | Force a right value, or otherwise fail with provided error message -- -- > fromRightNote err = either (error err) id@@ -310,7 +550,8 @@  -- | Force a right value, providing a default value if the Either is Left fromEither :: b -> Either a b -> b-fromEither = fromRight+fromEither _ (Right x) = x+fromEither x _ = x  -- | Extract the first element of a list as a Right value, or else use the -- default value provided as a Left value@@ -361,7 +602,7 @@ -- @ -- eitherToMaybe :: Either a b -> Maybe b-eitherToMaybe = rightToMaybe+eitherToMaybe = either (const Nothing) Just   -- | eitherToMonoid extract the right sided monoid into a single monoid