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


-- | Profunctors
--   
--   Profunctors
@package profunctors
@version 4.0.1


module Data.Profunctor.Trace

-- | Coend of <a>Profunctor</a> from <tt>Hask -&gt; Hask</tt>.
data Trace f
Trace :: f a a -> Trace f


-- | For a good explanation of profunctors in Haskell see Dan Piponi's
--   article:
--   
--   <a>http://blog.sigfpe.com/2011/07/profunctors-in-haskell.html</a>
--   
--   This module includes <i>unsafe</i> composition operators that are
--   useful in practice when it comes to generating optimal core in GHC.
--   
--   If you import this module you are taking upon yourself the obligation
--   that you will only call the operators with <tt>#</tt> in their names
--   with functions that are operationally identity such as
--   <tt>newtype</tt> constructors or the field accessor of a
--   <tt>newtype</tt>.
--   
--   If you are ever in doubt, use <a>rmap</a> or <a>lmap</a>.
module Data.Profunctor.Unsafe

-- | Formally, the class <a>Profunctor</a> represents a profunctor from
--   <tt>Hask</tt> -&gt; <tt>Hask</tt>.
--   
--   Intuitively it is a bifunctor where the first argument is
--   contravariant and the second argument is covariant.
--   
--   You can define a <a>Profunctor</a> by either defining <a>dimap</a> or
--   by defining both <a>lmap</a> and <a>rmap</a>.
--   
--   If you supply <a>dimap</a>, you should ensure that:
--   
--   <pre>
--   <a>dimap</a> <a>id</a> <a>id</a> ≡ <a>id</a>
--   </pre>
--   
--   If you supply <a>lmap</a> and <a>rmap</a>, ensure:
--   
--   <pre>
--   <a>lmap</a> <a>id</a> ≡ <a>id</a>
--   <a>rmap</a> <a>id</a> ≡ <a>id</a>
--   </pre>
--   
--   If you supply both, you should also ensure:
--   
--   <pre>
--   <a>dimap</a> f g ≡ <a>lmap</a> f <a>.</a> <a>rmap</a> g
--   </pre>
--   
--   These ensure by parametricity:
--   
--   <pre>
--   <a>dimap</a> (f <a>.</a> g) (h <a>.</a> i) ≡ <a>dimap</a> g h <a>.</a> <a>dimap</a> f i
--   <a>lmap</a> (f <a>.</a> g) ≡ <a>lmap</a> g <a>.</a> <a>lmap</a> f
--   <a>rmap</a> (f <a>.</a> g) ≡ <a>rmap</a> f <a>.</a> <a>rmap</a> g
--   </pre>
class Profunctor p where dimap f g = lmap f . rmap g lmap f = dimap f id rmap = dimap id #. = \ f -> \ p -> p `seq` rmap f p .# = \ p -> p `seq` \ f -> lmap f p
dimap :: Profunctor p => (a -> b) -> (c -> d) -> p b c -> p a d
lmap :: Profunctor p => (a -> b) -> p b c -> p a c
rmap :: Profunctor p => (b -> c) -> p a b -> p a c
(#.) :: Profunctor p => (b -> c) -> p a b -> p a c
(.#) :: Profunctor p => p b c -> (a -> b) -> p a c
instance Functor w => Profunctor (Cokleisli w)
instance Monad m => Profunctor (Kleisli m)
instance Profunctor (Tagged *)
instance Profunctor (->)


-- | For a good explanation of profunctors in Haskell see Dan Piponi's
--   article:
--   
--   <a>http://blog.sigfpe.com/2011/07/profunctors-in-haskell.html</a>
--   
--   For more information on strength and costrength, see:
--   
--   <a>http://comonad.com/reader/2008/deriving-strength-from-laziness/</a>
module Data.Profunctor

-- | Formally, the class <a>Profunctor</a> represents a profunctor from
--   <tt>Hask</tt> -&gt; <tt>Hask</tt>.
--   
--   Intuitively it is a bifunctor where the first argument is
--   contravariant and the second argument is covariant.
--   
--   You can define a <a>Profunctor</a> by either defining <a>dimap</a> or
--   by defining both <a>lmap</a> and <a>rmap</a>.
--   
--   If you supply <a>dimap</a>, you should ensure that:
--   
--   <pre>
--   <a>dimap</a> <a>id</a> <a>id</a> ≡ <a>id</a>
--   </pre>
--   
--   If you supply <a>lmap</a> and <a>rmap</a>, ensure:
--   
--   <pre>
--   <a>lmap</a> <a>id</a> ≡ <a>id</a>
--   <a>rmap</a> <a>id</a> ≡ <a>id</a>
--   </pre>
--   
--   If you supply both, you should also ensure:
--   
--   <pre>
--   <a>dimap</a> f g ≡ <a>lmap</a> f <a>.</a> <a>rmap</a> g
--   </pre>
--   
--   These ensure by parametricity:
--   
--   <pre>
--   <a>dimap</a> (f <a>.</a> g) (h <a>.</a> i) ≡ <a>dimap</a> g h <a>.</a> <a>dimap</a> f i
--   <a>lmap</a> (f <a>.</a> g) ≡ <a>lmap</a> g <a>.</a> <a>lmap</a> f
--   <a>rmap</a> (f <a>.</a> g) ≡ <a>rmap</a> f <a>.</a> <a>rmap</a> g
--   </pre>
class Profunctor p where dimap f g = lmap f . rmap g lmap f = dimap f id rmap = dimap id #. = \ f -> \ p -> p `seq` rmap f p .# = \ p -> p `seq` \ f -> lmap f p
dimap :: Profunctor p => (a -> b) -> (c -> d) -> p b c -> p a d
lmap :: Profunctor p => (a -> b) -> p b c -> p a c
rmap :: Profunctor p => (b -> c) -> p a b -> p a c

-- | Generalizing upstar of a strong <a>Functor</a>
--   
--   Minimal complete definition: <a>first'</a> or <a>second'</a>
--   
--   <i>Note:</i> Every <a>Functor</a> in Haskell is strong.
class Profunctor p => Strong p where first' = dimap swap swap . second' second' = dimap swap swap . first'
first' :: Strong p => p a b -> p (a, c) (b, c)
second' :: Strong p => p a b -> p (c, a) (c, b)

-- | The generalization of <a>DownStar</a> of a "costrong" <a>Functor</a>
--   
--   Minimal complete definition: <a>left'</a> or <a>right'</a>
--   
--   <i>Note:</i> We use <a>traverse</a> and <a>extract</a> as approximate
--   costrength as needed.
class Profunctor p => Choice p where left' = dimap (either Right Left) (either Right Left) . right' right' = dimap (either Right Left) (either Right Left) . left'
left' :: Choice p => p a b -> p (Either a c) (Either b c)
right' :: Choice p => p a b -> p (Either c a) (Either c b)

-- | Lift a <a>Functor</a> into a <a>Profunctor</a> (forwards).
newtype UpStar f d c
UpStar :: (d -> f c) -> UpStar f d c
runUpStar :: UpStar f d c -> d -> f c

-- | Lift a <a>Functor</a> into a <a>Profunctor</a> (backwards).
newtype DownStar f d c
DownStar :: (f d -> c) -> DownStar f d c
runDownStar :: DownStar f d c -> f d -> c

-- | Wrap an arrow for use as a <a>Profunctor</a>.
newtype WrappedArrow p a b
WrapArrow :: p a b -> WrappedArrow p a b
unwrapArrow :: WrappedArrow p a b -> p a b
newtype Forget r a b
Forget :: (a -> r) -> Forget r a b
runForget :: Forget r a b -> a -> r
instance Monoid r => Choice (Forget r)
instance ArrowChoice p => Choice (WrappedArrow p)
instance Choice (Tagged *)
instance Traversable w => Choice (DownStar w)
instance Comonad w => Choice (Cokleisli w)
instance Applicative f => Choice (UpStar f)
instance Monad m => Choice (Kleisli m)
instance Choice (->)
instance Strong (Forget r)
instance Arrow p => Strong (WrappedArrow p)
instance Functor m => Strong (UpStar m)
instance Monad m => Strong (Kleisli m)
instance Strong (->)
instance Traversable (Forget r a)
instance Foldable (Forget r a)
instance Functor (Forget r a)
instance Profunctor (Forget r)
instance Arrow p => Profunctor (WrappedArrow p)
instance ArrowLoop p => ArrowLoop (WrappedArrow p)
instance ArrowApply p => ArrowApply (WrappedArrow p)
instance ArrowChoice p => ArrowChoice (WrappedArrow p)
instance ArrowZero p => ArrowZero (WrappedArrow p)
instance Arrow p => Arrow (WrappedArrow p)
instance Category p => Category (WrappedArrow p)
instance Functor (DownStar f a)
instance Functor f => Profunctor (DownStar f)
instance Functor f => Functor (UpStar f a)
instance Functor f => Profunctor (UpStar f)


module Data.Profunctor.Rep

-- | A <a>Profunctor</a> <tt>p</tt> is <a>Representable</a> if there exists
--   a <a>Functor</a> <tt>f</tt> such that <tt>p d c</tt> is isomorphic to
--   <tt>d -&gt; f c</tt>.
class (Functor (Rep p), Profunctor p) => Representable p where type family Rep p :: * -> *
tabulate :: Representable p => (d -> Rep p c) -> p d c
rep :: Representable p => p d c -> d -> Rep p c

-- | <a>tabulate</a> and <a>rep</a> form two halves of an isomorphism.
--   
--   This can be used with the combinators from the <tt>lens</tt> package.
--   
--   <pre>
--   <a>tabulated</a> :: <a>Representable</a> p =&gt; <tt>Iso'</tt> (d -&gt; <a>Rep</a> p c) (p d c)
--   </pre>
tabulated :: (Representable p, Representable q) => Iso (d -> Rep p c) (d' -> Rep q c') (p d c) (q d' c')

-- | A <a>Profunctor</a> <tt>p</tt> is <a>Corepresentable</a> if there
--   exists a <a>Functor</a> <tt>f</tt> such that <tt>p d c</tt> is
--   isomorphic to <tt>f d -&gt; c</tt>.
class (Functor (Corep p), Profunctor p) => Corepresentable p where type family Corep p :: * -> *
cotabulate :: Corepresentable p => (Corep p d -> c) -> p d c
corep :: Corepresentable p => p d c -> Corep p d -> c

-- | <a>cotabulate</a> and <a>corep</a> form two halves of an isomorphism.
--   
--   This can be used with the combinators from the <tt>lens</tt> package.
--   
--   <pre>
--   <a>tabulated</a> :: <a>Corep</a> f p =&gt; <tt>Iso'</tt> (f d -&gt; c) (p d c)
--   </pre>
cotabulated :: (Corepresentable p, Corepresentable q) => Iso (Corep p d -> c) (Corep q d' -> c') (p d c) (q d' c')
instance Functor f => Corepresentable (DownStar f)
instance Corepresentable (Tagged *)
instance Functor w => Corepresentable (Cokleisli w)
instance Corepresentable (->)
instance Functor f => Representable (UpStar f)
instance (Monad m, Functor m) => Representable (Kleisli m)
instance Representable (->)


module Data.Profunctor.Composition

-- | <tt><a>Procompose</a> p q</tt> is the <a>Profunctor</a> composition of
--   the <a>Profunctor</a>s <tt>p</tt> and <tt>q</tt>.
--   
--   For a good explanation of <a>Profunctor</a> composition in Haskell see
--   Dan Piponi's article:
--   
--   <a>http://blog.sigfpe.com/2011/07/profunctors-in-haskell.html</a>
data Procompose p q d c
Procompose :: p d a -> q a c -> Procompose p q d c
procomposed :: Category p => Procompose p p a b -> p a b

-- | <tt>(-&gt;)</tt> functions as a lax identity for <a>Profunctor</a>
--   composition.
--   
--   This provides an <a>Iso</a> for the <tt>lens</tt> package that
--   witnesses the isomorphism between <tt><a>Procompose</a> (-&gt;) q d
--   c</tt> and <tt>q d c</tt>, which is the left identity law.
--   
--   <pre>
--   <a>idl</a> :: <a>Profunctor</a> q =&gt; Iso' (<a>Procompose</a> (-&gt;) q d c) (q d c)
--   </pre>
idl :: Profunctor q => Iso (Procompose (->) q d c) (Procompose (->) r d' c') (q d c) (r d' c')

-- | <tt>(-&gt;)</tt> functions as a lax identity for <a>Profunctor</a>
--   composition.
--   
--   This provides an <a>Iso</a> for the <tt>lens</tt> package that
--   witnesses the isomorphism between <tt><a>Procompose</a> q (-&gt;) d
--   c</tt> and <tt>q d c</tt>, which is the right identity law.
--   
--   <pre>
--   <a>idr</a> :: <a>Profunctor</a> q =&gt; Iso' (<a>Procompose</a> q (-&gt;) d c) (q d c)
--   </pre>
idr :: Profunctor q => Iso (Procompose q (->) d c) (Procompose r (->) d' c') (q d c) (r d' c')

-- | <a>Profunctor</a> composition generalizes <a>Functor</a> composition
--   in two ways.
--   
--   This is the first, which shows that <tt>exists b. (a -&gt; f b, b
--   -&gt; g c)</tt> is isomorphic to <tt>a -&gt; f (g c)</tt>.
--   
--   <pre>
--   <a>upstars</a> :: <a>Functor</a> f =&gt; Iso' (<a>Procompose</a> (<a>UpStar</a> f) (<a>UpStar</a> g) d c) (<a>UpStar</a> (<a>Compose</a> f g) d c)
--   </pre>
upstars :: Functor f => Iso (Procompose (UpStar f) (UpStar g) d c) (Procompose (UpStar f') (UpStar g') d' c') (UpStar (Compose f g) d c) (UpStar (Compose f' g') d' c')

-- | This is a variant on <a>upstars</a> that uses <a>Kleisli</a> instead
--   of <a>UpStar</a>.
--   
--   <pre>
--   <a>kleislis</a> :: <a>Monad</a> f =&gt; Iso' (<a>Procompose</a> (<a>Kleisli</a> f) (<a>Kleisli</a> g) d c) (<a>Kleisli</a> (<a>Compose</a> f g) d c)
--   </pre>
kleislis :: Monad f => Iso (Procompose (Kleisli f) (Kleisli g) d c) (Procompose (Kleisli f') (Kleisli g') d' c') (Kleisli (Compose f g) d c) (Kleisli (Compose f' g') d' c')

-- | <a>Profunctor</a> composition generalizes <a>Functor</a> composition
--   in two ways.
--   
--   This is the second, which shows that <tt>exists b. (f a -&gt; b, g b
--   -&gt; c)</tt> is isomorphic to <tt>g (f a) -&gt; c</tt>.
--   
--   <pre>
--   <a>downstars</a> :: <a>Functor</a> f =&gt; Iso' (<a>Procompose</a> (<a>DownStar</a> f) (<a>DownStar</a> g) d c) (<a>DownStar</a> (<a>Compose</a> g f) d c)
--   </pre>
downstars :: Functor g => Iso (Procompose (DownStar f) (DownStar g) d c) (Procompose (DownStar f') (DownStar g') d' c') (DownStar (Compose g f) d c) (DownStar (Compose g' f') d' c')

-- | This is a variant on <a>downstars</a> that uses <a>Cokleisli</a>
--   instead of <a>DownStar</a>.
--   
--   <pre>
--   <a>cokleislis</a> :: <a>Functor</a> f =&gt; Iso' (<a>Procompose</a> (<a>Cokleisli</a> f) (<a>Cokleisli</a> g) d c) (<a>Cokleisli</a> (<a>Compose</a> g f) d c)
--   </pre>
cokleislis :: Functor g => Iso (Procompose (Cokleisli f) (Cokleisli g) d c) (Procompose (Cokleisli f') (Cokleisli g') d' c') (Cokleisli (Compose g f) d c) (Cokleisli (Compose g' f') d' c')
instance (Choice p, Choice q) => Choice (Procompose p q)
instance (Strong p, Strong q) => Strong (Procompose p q)
instance (Corepresentable p, Corepresentable q) => Corepresentable (Procompose p q)
instance (Representable p, Representable q) => Representable (Procompose p q)
instance Profunctor q => Functor (Procompose p q a)
instance (Profunctor p, Profunctor q) => Profunctor (Procompose p q)


module Data.Profunctor.Rift

-- | This represents the right Kan lift of a <a>Profunctor</a> <tt>q</tt>
--   along a <a>Profunctor</a> <tt>p</tt> in a limited version of the
--   2-category of Profunctors where the only object is the category Hask,
--   1-morphisms are profunctors composed and compose with Profunctor
--   composition, and 2-morphisms are just natural transformations.
newtype Rift p q a b
Rift :: (forall x. p x a -> q x b) -> Rift p q a b
runRift :: Rift p q a b -> forall x. p x a -> q x b

-- | The 2-morphism that defines a right Kan lift.
--   
--   Note: When <tt>f</tt> is left adjoint to <tt><a>Rift</a> f
--   (-&gt;)</tt> then <a>decomposeRift</a> is the <tt>counit</tt> of the
--   adjunction.
decomposeRift :: Procompose q (Rift q p) a b -> p a b
precomposeRift :: Profunctor q => Procompose (Rift p (->)) q a b -> Rift p q a b
instance p ~ q => Category (Rift p q)
instance Profunctor q => Functor (Rift p q a)
instance (Profunctor p, Profunctor q) => Profunctor (Rift p q)


module Data.Profunctor.Collage

-- | The cograph of a <a>Profunctor</a>.
data Collage k b a
L :: (b -> b') -> Collage k (L b) (L b')
R :: (a -> a') -> Collage k (R a) (R a')
C :: k b a -> Collage k (L b) (R a)
instance Profunctor k => Ob (Collage k) (R a)
instance Profunctor k => Ob (Collage k) (L a)
instance Profunctor k => Semigroupoid (Collage k)
