-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A typeclass and set of functions for working with newtypes.
--   
--   Per Conor McBride, the <a>Newtype</a> typeclass represents the packing
--   and unpacking of a <tt>newtype</tt>, and allows you to operate under
--   that <tt>newtype</tt> with functions such as <a>ala</a>. See
--   <a>Control.Newtype</a> for documentation and examples.
@package newtype
@version 0.2.2.0


-- | The <a>Newtype</a> typeclass and related functions: <a>op</a>,
--   <a>ala</a>, <a>ala'</a>, <a>under</a>. Primarly pulled from Conor
--   McBride's Epigram work. Some examples:
--   
--   <pre>
--   &gt;&gt;&gt; ala Sum foldMap [1,2,3,4] -- foldMaps the list ala the Sum newtype
--   10
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; ala Product foldMap [1,2,3,4] -- foldMaps the list ala the Product newtype
--   24
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; ala Endo foldMap [(+1), (+2), (subtract 1), (*2)] 3 -- foldMaps the list ala the Endo newtype
--   8
--   </pre>
--   
--   NB: <a>foldMap</a> is a generalized <tt>mconcatMap</tt> which is a
--   generalized <a>concatMap</a>.
--   
--   This package includes <a>Newtype</a> 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 <i>any</i>
--   <tt>newtype</tt> and you should definitely define your own
--   <a>Newtype</a> instances for the power of this library. For example,
--   see "<tt><a>ala</a> Cont <a>traverse</a></tt>", with the proper
--   <a>Newtype</a> instance for <tt>Cont</tt>.
module Control.Newtype

-- | Given a <tt>newtype</tt> <tt>n</tt>, we will always have the same
--   unwrapped type <tt>o</tt>, meaning we can represent this with a fundep
--   <tt>n -&gt; o</tt>.
--   
--   Any instance of this class just needs to let <a>pack</a> equal to the
--   newtype's constructor, and let <a>unpack</a> destruct the
--   <tt>newtype</tt> with pattern matching.
--   
--   Starting with <tt>newtype-0.2.2.0</tt>, default method implementations
--   are provided using <a>Data.Coerce</a> for GHC 7.8 (i.e.
--   <tt>base-4.7.0.0</tt>) and later, i.e.:
--   
--   <pre>
--   <a>pack</a>   = <a>coerce</a>
--   <a>unpack</a> = <a>coerce</a>
--   </pre>
--   
--   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
--   
--   <pre>
--   build-depends: newtype ^&gt;= 0.2.2.0
--   </pre>
--   
--   In your <tt>.cabal</tt> package description.
class Newtype n o | n -> o
pack :: Newtype n o => o -> n
unpack :: Newtype n o => n -> o
pack :: (Newtype n o, Coercible o n) => o -> n
unpack :: (Newtype n o, Coercible n o) => n -> o

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

-- | 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
--   <i>hof</i> (higher-order function) you passed.
--   
--   The reason for the signature of the hof is due to <a>ala</a> not
--   caring about structure. To illustrate why this is important, another
--   function in this package is <a>under</a>. It is not extremely useful;
--   <tt>under2</tt> might be more useful (with e.g., <a>mappend</a>), but
--   then we already digging the trench of "What about <tt>under3</tt>?
--   <tt>under4</tt>?". 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'

-- | This is the original function seen in Conor McBride's work. The way it
--   differs from the <a>ala</a> function in this package, is that it
--   provides an extra hook into the "packer" passed to the hof. However,
--   this normally ends up being <a>id</a>, so <a>ala</a> wraps this
--   function and passes <a>id</a> 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'

-- | A very simple operation involving running the function "under" the
--   newtype. Suffers from the problems mentioned in the <a>ala</a>
--   function's documentation.
under :: (Newtype n o, Newtype n' o') => (o -> n) -> (n -> n') -> o -> o'

-- | The opposite of <a>under</a>. I.e., take a function which works on the
--   underlying types, and switch it to a function that works on the
--   newtypes.
over :: (Newtype n o, Newtype n' o') => (o -> n) -> (o -> o') -> n -> n'

-- | <a>under</a> lifted into a <a>Functor</a>.
underF :: (Newtype n o, Newtype n' o', Functor f) => (o -> n) -> (f n -> f n') -> f o -> f o'

-- | <a>over</a> lifted into a <a>Functor</a>.
overF :: (Newtype n o, Newtype n' o', Functor f) => (o -> n) -> (f o -> f o') -> f n -> f n'
instance Control.Newtype.Newtype Data.Semigroup.Internal.All GHC.Types.Bool
instance Control.Newtype.Newtype Data.Semigroup.Internal.Any GHC.Types.Bool
instance Control.Newtype.Newtype (Data.Semigroup.Internal.Sum a) a
instance Control.Newtype.Newtype (Data.Semigroup.Internal.Product a) a
instance Control.Newtype.Newtype (Control.Arrow.Kleisli m a b) (a -> m b)
instance Control.Newtype.Newtype (Control.Applicative.WrappedMonad m a) (m a)
instance Control.Newtype.Newtype (Control.Applicative.WrappedArrow a b c) (a b c)
instance Control.Newtype.Newtype (Control.Applicative.ZipList a) [a]
instance Control.Newtype.Newtype (Data.Functor.Const.Const a x) a
instance Control.Newtype.Newtype (Data.Semigroup.Internal.Endo a) (a -> a)
instance Control.Newtype.Newtype (Data.Monoid.First a) (GHC.Maybe.Maybe a)
instance Control.Newtype.Newtype (Data.Monoid.Last a) (GHC.Maybe.Maybe a)
instance Control.Arrow.ArrowApply a => Control.Newtype.Newtype (Control.Arrow.ArrowMonad a b) (a () b)
instance Control.Newtype.Newtype (Data.Fixed.Fixed a) GHC.Integer.Type.Integer
instance Control.Newtype.Newtype (Data.Semigroup.Internal.Dual a) a
instance Control.Newtype.Newtype (Data.Semigroup.Internal.Alt f a) (f a)
instance Control.Newtype.Newtype (Data.Ord.Down a) a
instance Control.Newtype.Newtype (Data.Functor.Identity.Identity a) a
instance Control.Newtype.Newtype (Data.Functor.Compose.Compose f g a) (f (g a))
instance Control.Newtype.Newtype (Data.Monoid.Ap f a) (f a)