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


-- | Monadic Getters and Folds
--   
--   This package contains combinators and types for working with monadic
--   getters and folds as split off from the original lens package.
@package lens-action
@version 0.1.0.1


module Control.Lens.Action.Internal

-- | An <a>Effective</a> <a>Functor</a> ignores its argument and is
--   isomorphic to a <a>Monad</a> wrapped around a value.
--   
--   That said, the <a>Monad</a> is possibly rather unrelated to any
--   <a>Applicative</a> structure.
class (Monad m, Functor f, Contravariant f) => Effective m r f | f -> m r
effective :: Effective m r f => m r -> f a
ineffective :: Effective m r f => f a -> m r

-- | Wrap a monadic effect with a phantom type argument.
newtype Effect m r a
Effect :: m r -> Effect m r a
getEffect :: Effect m r a -> m r
instance (Monad m, Monoid r) => Applicative (Effect m r)
instance (Apply m, Semigroup r) => Apply (Effect m r)
instance (Monad m, Monoid r) => Monoid (Effect m r a)
instance (Apply m, Semigroup r) => Semigroup (Effect m r a)
instance Monad m => Effective m r (Effect m r)
instance Contravariant (Effect m r)
instance Functor (Effect m r)
instance Effective m r f => Effective m r (AlongsideRight f b)
instance Effective m r f => Effective m r (AlongsideLeft f b)
instance Effective Identity r (Const r)
instance Effective m r f => Effective m (Dual r) (Backwards f)


module Control.Lens.Action.Type

-- | An <a>Action</a> is a <tt>Getter</tt> enriched with access to a
--   <tt>Monad</tt> for side-effects.
--   
--   Every <tt>Getter</tt> can be used as an <a>Action</a>.
--   
--   You can compose an <a>Action</a> with another <a>Action</a> using
--   (<a>.</a>) from the <tt>Prelude</tt>.
type Action m s a = forall f r. Effective m r f => (a -> f a) -> s -> f s

-- | A <a>MonadicFold</a> is a <tt>Fold</tt> enriched with access to a
--   <tt>Monad</tt> for side-effects.
--   
--   A <a>MonadicFold</a> can use side-effects to produce parts of the
--   structure being folded (e.g. reading them from file).
--   
--   Every <tt>Fold</tt> can be used as a <a>MonadicFold</a>, that simply
--   ignores the access to the <tt>Monad</tt>.
--   
--   You can compose a <a>MonadicFold</a> with another <a>MonadicFold</a>
--   using (<a>.</a>) from the <tt>Prelude</tt>.
type MonadicFold m s a = forall f r. (Effective m r f, Applicative f) => (a -> f a) -> s -> f s
type RelevantMonadicFold m s a = forall f r. (Effective m r f, Apply f) => (a -> f a) -> s -> f s

-- | An <a>IndexedAction</a> is an <tt>IndexedGetter</tt> enriched with
--   access to a <tt>Monad</tt> for side-effects.
--   
--   Every <tt>Getter</tt> can be used as an <a>Action</a>.
--   
--   You can compose an <a>Action</a> with another <a>Action</a> using
--   (<a>.</a>) from the <tt>Prelude</tt>.
type IndexedAction i m s a = forall p f r. (Indexable i p, Effective m r f) => p a (f a) -> s -> f s

-- | An <a>IndexedMonadicFold</a> is an <tt>IndexedFold</tt> enriched with
--   access to a <tt>Monad</tt> for side-effects.
--   
--   Every <tt>IndexedFold</tt> can be used as an
--   <a>IndexedMonadicFold</a>, that simply ignores the access to the
--   <tt>Monad</tt>.
--   
--   You can compose an <a>IndexedMonadicFold</a> with another
--   <a>IndexedMonadicFold</a> using (<a>.</a>) from the <tt>Prelude</tt>.
type IndexedMonadicFold i m s a = forall p f r. (Indexable i p, Effective m r f, Applicative f) => p a (f a) -> s -> f s
type IndexedRelevantMonadicFold i m s a = forall p f r. (Indexable i p, Effective m r f, Apply f) => p a (f a) -> s -> f s

-- | An <a>IndexPreservingAction</a> can be used as a <a>Action</a>, but
--   when composed with an <tt>IndexedTraversal</tt>, <tt>IndexedFold</tt>,
--   or <tt>IndexedLens</tt> yields an <a>IndexedMonadicFold</a>,
--   <a>IndexedMonadicFold</a> or <a>IndexedAction</a> respectively.
type IndexPreservingAction m s a = forall p f r. (Conjoined p, Effective m r f) => p a (f a) -> p s (f s)

-- | An <tt>IndexPreservingFold</tt> can be used as a <tt>Fold</tt>, but
--   when composed with an <tt>IndexedTraversal</tt>, <tt>IndexedFold</tt>,
--   or <tt>IndexedLens</tt> yields an <tt>IndexedFold</tt> respectively.
type IndexPreservingMonadicFold m s a = forall p f r. (Conjoined p, Effective m r f, Applicative f) => p a (f a) -> p s (f s)
type IndexPreservingRelevantMonadicFold m s a = forall p f r. (Conjoined p, Effective m r f, Apply f) => p a (f a) -> p s (f s)


module Control.Lens.Action

-- | An <a>Action</a> is a <tt>Getter</tt> enriched with access to a
--   <tt>Monad</tt> for side-effects.
--   
--   Every <tt>Getter</tt> can be used as an <a>Action</a>.
--   
--   You can compose an <a>Action</a> with another <a>Action</a> using
--   (<a>.</a>) from the <tt>Prelude</tt>.
type Action m s a = forall f r. Effective m r f => (a -> f a) -> s -> f s

-- | Construct an <a>Action</a> from a monadic side-effect.
--   
--   <pre>
--   &gt;&gt;&gt; ["hello","world"]^!folded.act (\x -&gt; [x,x ++ "!"])
--   ["helloworld","helloworld!","hello!world","hello!world!"]
--   </pre>
--   
--   <pre>
--   <a>act</a> :: <a>Monad</a> m =&gt; (s -&gt; m a) -&gt; <a>Action</a> m s a
--   <a>act</a> sma afb a = <a>effective</a> (sma a <a>&gt;&gt;=</a> <a>ineffective</a> <a>.</a> afb)
--   </pre>
act :: Monad m => (s -> m a) -> IndexPreservingAction m s a

-- | A self-running <a>Action</a>, analogous to <a>join</a>.
--   
--   <pre>
--   <a>acts</a> ≡ <a>act</a> <a>id</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; (1,"hello")^!_2.acts.to succ
--   "ifmmp"
--   </pre>
--   
--   <pre>
--   &gt; (1,getLine)^!!_2.acts.folded.to succ
--   aa
--   "bb"
--   </pre>
acts :: IndexPreservingAction m (m a) a

-- | Perform an <a>Action</a>.
--   
--   <pre>
--   <a>perform</a> ≡ <a>flip</a> (<a>^!</a>)
--   </pre>
perform :: Monad m => Acting m a s a -> s -> m a

-- | Perform an <a>Action</a> and modify the result.
--   
--   <pre>
--   <a>performs</a> :: <a>Monad</a> m =&gt; <a>Acting</a> m e s a -&gt; (a -&gt; e) -&gt; s -&gt; m e
--   </pre>
performs :: (Profunctor p, Monad m) => Over p (Effect m e) s t a b -> p a e -> s -> m e

-- | Apply a <a>Monad</a> transformer to an <a>Action</a>.
liftAct :: (MonadTrans trans, Monad m) => Acting m a s a -> IndexPreservingAction (trans m) s a

-- | Perform an <a>Action</a>.
--   
--   <pre>
--   &gt;&gt;&gt; ["hello","world"]^!folded.act putStrLn
--   hello
--   world
--   </pre>
(^!) :: Monad m => s -> Acting m a s a -> m a

-- | Perform a <a>MonadicFold</a> and collect all of the results in a list.
--   
--   <pre>
--   &gt;&gt;&gt; ["ab","cd","ef"]^!!folded.acts
--   ["ace","acf","ade","adf","bce","bcf","bde","bdf"]
--   </pre>
--   
--   <pre>
--   &gt; [1,2]^!!folded.act (i -&gt; putStr (show i ++ ": ") &gt;&gt; getLine).each.to succ
--   1: aa
--   2: bb
--   "bbcc"
--   </pre>
(^!!) :: Monad m => s -> Acting m [a] s a -> m [a]

-- | Perform a <a>MonadicFold</a> and collect the leftmost result.
--   
--   <i>Note:</i> this still causes all effects for all elements.
--   
--   <pre>
--   &gt;&gt;&gt; [Just 1, Just 2, Just 3]^!?folded.acts
--   Just (Just 1)
--   
--   &gt;&gt;&gt; [Just 1, Nothing]^!?folded.acts
--   Nothing
--   </pre>
(^!?) :: Monad m => s -> Acting m (Leftmost a) s a -> m (Maybe a)

-- | An <a>IndexedAction</a> is an <tt>IndexedGetter</tt> enriched with
--   access to a <tt>Monad</tt> for side-effects.
--   
--   Every <tt>Getter</tt> can be used as an <a>Action</a>.
--   
--   You can compose an <a>Action</a> with another <a>Action</a> using
--   (<a>.</a>) from the <tt>Prelude</tt>.
type IndexedAction i m s a = forall p f r. (Indexable i p, Effective m r f) => p a (f a) -> s -> f s

-- | Construct an <a>IndexedAction</a> from a monadic side-effect.
iact :: Monad m => (s -> m (i, a)) -> IndexedAction i m s a

-- | Perform an <a>IndexedAction</a>.
--   
--   <pre>
--   <a>iperform</a> ≡ <a>flip</a> (<a>^@!</a>)
--   </pre>
iperform :: Monad m => IndexedActing i m (i, a) s a -> s -> m (i, a)

-- | Perform an <a>IndexedAction</a> and modify the result.
iperforms :: Monad m => IndexedActing i m e s a -> (i -> a -> e) -> s -> m e

-- | Perform an <a>IndexedAction</a>.
(^@!) :: Monad m => s -> IndexedActing i m (i, a) s a -> m (i, a)

-- | Obtain a list of all of the results of an <a>IndexedMonadicFold</a>.
(^@!!) :: Monad m => s -> IndexedActing i m [(i, a)] s a -> m [(i, a)]

-- | Perform an <a>IndexedMonadicFold</a> and collect the <a>Leftmost</a>
--   result.
--   
--   <i>Note:</i> this still causes all effects for all elements.
(^@!?) :: Monad m => s -> IndexedActing i m (Leftmost (i, a)) s a -> m (Maybe (i, a))

-- | A <a>MonadicFold</a> is a <tt>Fold</tt> enriched with access to a
--   <tt>Monad</tt> for side-effects.
--   
--   A <a>MonadicFold</a> can use side-effects to produce parts of the
--   structure being folded (e.g. reading them from file).
--   
--   Every <tt>Fold</tt> can be used as a <a>MonadicFold</a>, that simply
--   ignores the access to the <tt>Monad</tt>.
--   
--   You can compose a <a>MonadicFold</a> with another <a>MonadicFold</a>
--   using (<a>.</a>) from the <tt>Prelude</tt>.
type MonadicFold m s a = forall f r. (Effective m r f, Applicative f) => (a -> f a) -> s -> f s

-- | An <a>IndexedMonadicFold</a> is an <tt>IndexedFold</tt> enriched with
--   access to a <tt>Monad</tt> for side-effects.
--   
--   Every <tt>IndexedFold</tt> can be used as an
--   <a>IndexedMonadicFold</a>, that simply ignores the access to the
--   <tt>Monad</tt>.
--   
--   You can compose an <a>IndexedMonadicFold</a> with another
--   <a>IndexedMonadicFold</a> using (<a>.</a>) from the <tt>Prelude</tt>.
type IndexedMonadicFold i m s a = forall p f r. (Indexable i p, Effective m r f, Applicative f) => p a (f a) -> s -> f s

-- | Used to evaluate an <a>Action</a>.
type Acting m r s a = LensLike (Effect m r) s s a a

-- | Used to evaluate an <a>IndexedAction</a>.
type IndexedActing i m r s a = Over (Indexed i) (Effect m r) s s a a

-- | An <a>Effective</a> <a>Functor</a> ignores its argument and is
--   isomorphic to a <a>Monad</a> wrapped around a value.
--   
--   That said, the <a>Monad</a> is possibly rather unrelated to any
--   <a>Applicative</a> structure.
class (Monad m, Functor f, Contravariant f) => Effective m r f | f -> m r


module Control.Lens.Action.Reified

-- | Reify a <a>MonadicFold</a> so it can be stored safely in a container.
newtype ReifiedMonadicFold m s a
MonadicFold :: MonadicFold m s a -> ReifiedMonadicFold m s a
runMonadicFold :: ReifiedMonadicFold m s a -> MonadicFold m s a
instance Plus (ReifiedMonadicFold m s)
instance Alt (ReifiedMonadicFold m s)
instance Monoid (ReifiedMonadicFold m s a)
instance Semigroup (ReifiedMonadicFold m s a)
instance MonadPlus (ReifiedMonadicFold m s)
instance MonadReader s (ReifiedMonadicFold m s)
instance Monad (ReifiedMonadicFold m s)
instance Bind (ReifiedMonadicFold m s)
instance Alternative (ReifiedMonadicFold m s)
instance Applicative (ReifiedMonadicFold m s)
instance Apply (ReifiedMonadicFold m s)
instance Functor (ReifiedMonadicFold m s)
instance ArrowApply (ReifiedMonadicFold m)
instance ArrowChoice (ReifiedMonadicFold m)
instance Arrow (ReifiedMonadicFold m)
instance Category (ReifiedMonadicFold m)
instance Choice (ReifiedMonadicFold m)
instance Strong (ReifiedMonadicFold m)
instance Profunctor (ReifiedMonadicFold m)
