{-# LANGUAGE CPP                    #-}
{-# LANGUAGE FlexibleInstances      #-}
{-# LANGUAGE FunctionalDependencies #-}
{-# LANGUAGE MultiParamTypeClasses  #-}
{-# LANGUAGE TypeFamilies           #-}
#if __GLASGOW_HASKELL__ >= 704
{-# LANGUAGE DefaultSignatures      #-}
#endif

{-# OPTIONS_GHC -fno-warn-unused-imports #-}

{- |
Module : Control.Newtype
SPDX-License-Identifier : BSD-3-Clause

The 'Newtype' typeclass and related functions: 'op', 'ala', 'ala'', 'under'. Primarly pulled from Conor McBride's Epigram work. Some examples:

>>> ala Sum foldMap [1,2,3,4] -- foldMaps the list ala the Sum newtype
10

>>> ala Product foldMap [1,2,3,4] -- foldMaps the list ala the Product newtype
24

>>> ala Endo foldMap [(+1), (+2), (subtract 1), (*2)] 3 -- foldMaps the list ala the Endo newtype
8

NB: 'Data.Foldable.foldMap' is a generalized @mconcatMap@ which is a generalized 'concatMap'.

This package includes 'Newtype' instances for all the (non-GHC\/foreign) newtypes in base (as seen in the examples). However, there are neat things you can do with this with /any/ @newtype@ and you should definitely define your own 'Newtype' instances for the power of this library. For example, see \"@'ala' Cont 'traverse'@\", with the proper 'Newtype' instance for @Cont@.

-}
module Control.Newtype
    ( Newtype(..)
    , op
    , ala
    , ala'
    , under
    , over
    , underF
    , overF
    ) where

import           Control.Applicative
import           Control.Arrow
import           Data.Fixed
import           Data.Functor.Compose
import           Data.Functor.Identity
import           Data.Monoid
import           Data.Ord

#if !MIN_VERSION_base(4,7,0)
-- necessary evil for 'Newtype Fixed'
import           Unsafe.Coerce         (unsafeCoerce)
#else
import           Data.Coerce
#endif

-- | Given a @newtype@ @n@, we will always have the same unwrapped type @o@, meaning we can represent this with a fundep @n -> o@.
--
-- Any instance of this class just needs to let 'pack' equal to the newtype's constructor, and let 'unpack' destruct the @newtype@ with pattern matching.
--
-- Starting with @newtype-0.2.2.0@, default method implementations are provided using "Data.Coerce" for GHC 7.8 (i.e. @base-4.7.0.0@) and later, i.e.:
--
-- @
-- 'pack'   = 'coerce'
-- 'unpack' = 'coerce'
-- @
--
-- When omitting the method definitions with GHC 7.4 and 7.6 a compile error will be triggered.
--
-- Consequently, if your code relies on these default methods make sure to state
--
-- > build-depends: newtype ^>= 0.2.2.0
--
-- In your @.cabal@ package description.
class Newtype n o | n -> o where
  pack :: o -> n

  unpack :: n -> o

#if  __GLASGOW_HASKELL__ >= 704
  default pack :: Coercible o n => o -> n
  pack = o -> n
coerce

  default unpack :: Coercible n o => n -> o
  unpack = n -> o
coerce
#endif

#if __GLASGOW_HASKELL__ >= 704 && !MIN_VERSION_base(4,7,0)
-- Hack: We define a dummy 'Coercible' class to force a
-- missing-instance compile error when methods are not explicitly
-- defined
class Coercible o n

coerce :: a -> b
coerce = undefined
#endif

{- TODO: for newtype-0.3

This would be nice, but it breaks in odd ways with GHC < 7.
Oh, and it also makes the instances an extra line longer. :(
class Newtype n where
  type Orig n
  pack :: Orig n -> n
  unpack :: n -> Orig n
-}

-- |
-- This function serves two purposes:
--
-- 1. Giving you the unpack of a @newtype@ without you needing to remember the name.
--
-- 2. Showing that the first parameter is /completely ignored/ on the value level, meaning the only reason you pass in the constructor is to provide type information. Typeclasses sure are neat.
op :: Newtype n o => (o -> n) -> n -> o
op :: (o -> n) -> n -> o
op o -> n
_ = n -> o
forall n o. Newtype n o => n -> o
unpack

-- | The workhorse of the package. Given a pack and a \"higher order function\", it handles the packing and unpacking, and just sends you back a regular old function, with the type varying based on the /hof/ (higher-order function) you passed.
--
-- The reason for the signature of the hof is due to 'ala' not caring about structure. To illustrate why this is important, another function in this package is 'under'. It is not extremely useful; @under2@ might be more useful (with e.g., 'mappend'), but then we already digging the trench of \"What about @under3@? @under4@?\". The solution utilized here is to just hand off the \"packer\" to the hof. That way your structure can be imposed in the hof, whatever you may want it to be (e.g., List, Traversable).
ala :: (Newtype n o, Newtype n' o') => (o -> n) -> ((o -> n) -> b -> n') -> (b -> o')
ala :: (o -> n) -> ((o -> n) -> b -> n') -> b -> o'
ala o -> n
pa (o -> n) -> b -> n'
hof = (o -> n) -> ((o -> n) -> b -> n') -> (o -> o) -> b -> o'
forall n o n' o' a b.
(Newtype n o, Newtype n' o') =>
(o -> n) -> ((a -> n) -> b -> n') -> (a -> o) -> b -> o'
ala' o -> n
pa (o -> n) -> b -> n'
hof o -> o
forall a. a -> a
id

-- | This is the original function seen in Conor McBride's work. The way it differs from the 'ala' function in this package, is that it provides an extra hook into the \"packer\" passed to the hof. However, this normally ends up being 'id', so 'ala' wraps this function and passes 'id' as the final parameter by default. If you want the convenience of being able to hook right into the hof, you may use this function.
ala' :: (Newtype n o, Newtype n' o') => (o -> n) -> ((a -> n) -> b -> n') -> (a -> o) -> (b -> o')
ala' :: (o -> n) -> ((a -> n) -> b -> n') -> (a -> o) -> b -> o'
ala' o -> n
_ (a -> n) -> b -> n'
hof a -> o
f = n' -> o'
forall n o. Newtype n o => n -> o
unpack (n' -> o') -> (b -> n') -> b -> o'
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (a -> n) -> b -> n'
hof (o -> n
forall n o. Newtype n o => o -> n
pack (o -> n) -> (a -> o) -> a -> n
forall b c a. (b -> c) -> (a -> b) -> a -> c
. a -> o
f)

-- | A very simple operation involving running the function \"under\" the newtype. Suffers from the problems mentioned in the 'ala' function's documentation.
under :: (Newtype n o, Newtype n' o') => (o -> n) -> (n -> n') -> (o -> o')
under :: (o -> n) -> (n -> n') -> o -> o'
under o -> n
_ n -> n'
f = n' -> o'
forall n o. Newtype n o => n -> o
unpack (n' -> o') -> (o -> n') -> o -> o'
forall b c a. (b -> c) -> (a -> b) -> a -> c
. n -> n'
f (n -> n') -> (o -> n) -> o -> n'
forall b c a. (b -> c) -> (a -> b) -> a -> c
. o -> n
forall n o. Newtype n o => o -> n
pack

-- | The opposite of 'under'. I.e., take a function which works on the underlying types, and switch it to a function that works on the newtypes.
--
-- @since 0.2
over :: (Newtype n o, Newtype n' o') => (o -> n) -> (o -> o') -> (n -> n')
over :: (o -> n) -> (o -> o') -> n -> n'
over o -> n
_ o -> o'
f = o' -> n'
forall n o. Newtype n o => o -> n
pack (o' -> n') -> (n -> o') -> n -> n'
forall b c a. (b -> c) -> (a -> b) -> a -> c
. o -> o'
f (o -> o') -> (n -> o) -> n -> o'
forall b c a. (b -> c) -> (a -> b) -> a -> c
. n -> o
forall n o. Newtype n o => n -> o
unpack

-- | 'under' lifted into a 'Functor'.
--
-- @since 0.2
underF :: (Newtype n o, Newtype n' o', Functor f) => (o -> n) -> (f n -> f n') -> (f o -> f o')
underF :: (o -> n) -> (f n -> f n') -> f o -> f o'
underF o -> n
_ f n -> f n'
f = (n' -> o') -> f n' -> f o'
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap n' -> o'
forall n o. Newtype n o => n -> o
unpack (f n' -> f o') -> (f o -> f n') -> f o -> f o'
forall b c a. (b -> c) -> (a -> b) -> a -> c
. f n -> f n'
f (f n -> f n') -> (f o -> f n) -> f o -> f n'
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (o -> n) -> f o -> f n
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap o -> n
forall n o. Newtype n o => o -> n
pack

-- | 'over' lifted into a 'Functor'.
--
-- @since 0.2
overF :: (Newtype n o, Newtype n' o', Functor f) => (o -> n) -> (f o -> f o') -> (f n -> f n')
overF :: (o -> n) -> (f o -> f o') -> f n -> f n'
overF o -> n
_ f o -> f o'
f = (o' -> n') -> f o' -> f n'
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap o' -> n'
forall n o. Newtype n o => o -> n
pack (f o' -> f n') -> (f n -> f o') -> f n -> f n'
forall b c a. (b -> c) -> (a -> b) -> a -> c
. f o -> f o'
f (f o -> f o') -> (f n -> f o) -> f n -> f o'
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (n -> o) -> f n -> f o
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap n -> o
forall n o. Newtype n o => n -> o
unpack

instance Newtype All Bool where
  pack :: Bool -> All
pack = Bool -> All
All
  unpack :: All -> Bool
unpack (All Bool
a) = Bool
a

instance Newtype Any Bool where
  pack :: Bool -> Any
pack = Bool -> Any
Any
  unpack :: Any -> Bool
unpack (Any Bool
a) = Bool
a

instance Newtype (Sum a) a where
  pack :: a -> Sum a
pack = a -> Sum a
forall a. a -> Sum a
Sum
  unpack :: Sum a -> a
unpack (Sum a
a) = a
a

instance Newtype (Product a) a where
  pack :: a -> Product a
pack = a -> Product a
forall a. a -> Product a
Product
  unpack :: Product a -> a
unpack (Product a
a) = a
a

-- | @since 0.2
instance Newtype (Kleisli m a b) (a -> m b) where
  pack :: (a -> m b) -> Kleisli m a b
pack = (a -> m b) -> Kleisli m a b
forall (m :: * -> *) a b. (a -> m b) -> Kleisli m a b
Kleisli
  unpack :: Kleisli m a b -> a -> m b
unpack (Kleisli a -> m b
a) = a -> m b
a

instance Newtype (WrappedMonad m a) (m a) where
  pack :: m a -> WrappedMonad m a
pack = m a -> WrappedMonad m a
forall (m :: * -> *) a. m a -> WrappedMonad m a
WrapMonad
  unpack :: WrappedMonad m a -> m a
unpack (WrapMonad m a
a) = m a
a

instance Newtype (WrappedArrow a b c) (a b c) where
  pack :: a b c -> WrappedArrow a b c
pack = a b c -> WrappedArrow a b c
forall (a :: * -> * -> *) b c. a b c -> WrappedArrow a b c
WrapArrow
  unpack :: WrappedArrow a b c -> a b c
unpack (WrapArrow a b c
a) = a b c
a

instance Newtype (ZipList a) [a] where
  pack :: [a] -> ZipList a
pack = [a] -> ZipList a
forall a. [a] -> ZipList a
ZipList
  unpack :: ZipList a -> [a]
unpack (ZipList [a]
a) = [a]
a

instance Newtype (Const a x) a where
  pack :: a -> Const a x
pack = a -> Const a x
forall k a (b :: k). a -> Const a b
Const
  unpack :: Const a x -> a
unpack (Const a
a) = a
a

instance Newtype (Endo a) (a -> a) where
  pack :: (a -> a) -> Endo a
pack = (a -> a) -> Endo a
forall a. (a -> a) -> Endo a
Endo
  unpack :: Endo a -> a -> a
unpack (Endo a -> a
a) = a -> a
a

instance Newtype (First a) (Maybe a) where
  pack :: Maybe a -> First a
pack = Maybe a -> First a
forall a. Maybe a -> First a
First
  unpack :: First a -> Maybe a
unpack (First Maybe a
a) = Maybe a
a

instance Newtype (Last a) (Maybe a) where
  pack :: Maybe a -> Last a
pack = Maybe a -> Last a
forall a. Maybe a -> Last a
Last
  unpack :: Last a -> Maybe a
unpack (Last Maybe a
a) = Maybe a
a

instance ArrowApply a => Newtype (ArrowMonad a b) (a () b) where
  pack :: a () b -> ArrowMonad a b
pack = a () b -> ArrowMonad a b
forall (a :: * -> * -> *) b. a () b -> ArrowMonad a b
ArrowMonad
  unpack :: ArrowMonad a b -> a () b
unpack (ArrowMonad a () b
a) = a () b
a

-- | @since 0.2.1.0
instance Newtype (Fixed a) Integer where
#if MIN_VERSION_base(4,7,0)
  pack :: Integer -> Fixed a
pack = Integer -> Fixed a
forall k (a :: k). Integer -> Fixed a
MkFixed
  unpack :: Fixed a -> Integer
unpack (MkFixed Integer
x) = Integer
x
#else
  -- 'Fixed' is a newtype, but its constructor wasn't exported before base-4.7.0
  pack = unsafeCoerce
  unpack = unsafeCoerce
#endif

-- | @since 0.2.1.0
instance Newtype (Dual a) a where
  pack :: a -> Dual a
pack = a -> Dual a
forall a. a -> Dual a
Dual
  unpack :: Dual a -> a
unpack (Dual a
a) = a
a

#if MIN_VERSION_base(4,8,0)
-- | __NOTE__: Type & instance only available with @base ≥ 4.8.0@
--
-- @since 0.2.1.0
instance Newtype (Alt f a) (f a) where
  pack :: f a -> Alt f a
pack = f a -> Alt f a
forall k (f :: k -> *) (a :: k). f a -> Alt f a
Alt
  unpack :: Alt f a -> f a
unpack (Alt f a
x) = f a
x
#endif

#if MIN_VERSION_base(4,6,0)
-- | __NOTE__: Type & instance only available with @base ≥ 4.6.0@
--
-- @since 0.2.1.0
instance Newtype (Down a) a where
  pack :: a -> Down a
pack = a -> Down a
forall a. a -> Down a
Down
  unpack :: Down a -> a
unpack (Down a
a) = a
a
#endif

-- | @since 0.2.1.0
instance Newtype (Identity a) a where
  pack :: a -> Identity a
pack = a -> Identity a
forall a. a -> Identity a
Identity
  unpack :: Identity a -> a
unpack (Identity a
a) = a
a

-- | @since 0.2.1.0
instance Newtype (Compose f g a) (f (g a)) where
  pack :: f (g a) -> Compose f g a
pack = f (g a) -> Compose f g a
forall k k1 (f :: k -> *) (g :: k1 -> k) (a :: k1).
f (g a) -> Compose f g a
Compose
  unpack :: Compose f g a -> f (g a)
unpack (Compose f (g a)
x) = f (g a)
x

#if MIN_VERSION_base(4,12,0)
-- | __NOTE__: Type & instance only available with @base ≥ 4.12.0@
--
-- @since 0.2.1.0
instance Newtype (Ap f a) (f a) where
  pack :: f a -> Ap f a
pack = f a -> Ap f a
forall k (f :: k -> *) (a :: k). f a -> Ap f a
Ap
  unpack :: Ap f a -> f a
unpack (Ap f a
x) = f a
x
#endif

-- TODO
--  Data.Semigroup
--  Data.Functor.Contravariant