libghc-lens-action-doc 0.2.2-1 / usr / share / doc / libghc-lens-action-doc / html / lens-action.txt

-- 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.2.2


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 Control.Lens.Action.Internal.Effective m r f => Control.Lens.Action.Internal.Effective m (Data.Monoid.Dual r) (Control.Applicative.Backwards.Backwards f)
instance Control.Lens.Action.Internal.Effective Data.Functor.Identity.Identity r (Data.Functor.Const.Const r)
instance Control.Lens.Action.Internal.Effective m r f => Control.Lens.Action.Internal.Effective m r (Control.Lens.Internal.Getter.AlongsideLeft f b)
instance Control.Lens.Action.Internal.Effective m r f => Control.Lens.Action.Internal.Effective m r (Control.Lens.Internal.Getter.AlongsideRight f b)
instance GHC.Base.Functor (Control.Lens.Action.Internal.Effect m r)
instance Data.Functor.Contravariant.Contravariant (Control.Lens.Action.Internal.Effect m r)
instance GHC.Base.Monad m => Control.Lens.Action.Internal.Effective m r (Control.Lens.Action.Internal.Effect m r)
instance (Data.Functor.Bind.Class.Apply m, Data.Semigroup.Semigroup r) => Data.Semigroup.Semigroup (Control.Lens.Action.Internal.Effect m r a)
instance (GHC.Base.Monad m, GHC.Base.Monoid r) => GHC.Base.Monoid (Control.Lens.Action.Internal.Effect m r a)
instance (Data.Functor.Bind.Class.Apply m, Data.Semigroup.Semigroup r) => Data.Functor.Bind.Class.Apply (Control.Lens.Action.Internal.Effect m r)
instance (GHC.Base.Monad m, GHC.Base.Monoid r) => GHC.Base.Applicative (Control.Lens.Action.Internal.Effect m r)


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
infixr 8 ^!

-- | 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]
infixr 8 ^!!

-- | 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)
infixr 8 ^!?

-- | 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)
infixr 8 ^@!

-- | 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)]
infixr 8 ^@!!

-- | 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))
infixr 8 ^@!?

-- | 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 Data.Profunctor.Unsafe.Profunctor (Control.Lens.Action.Reified.ReifiedMonadicFold m)
instance Data.Profunctor.Strong.Strong (Control.Lens.Action.Reified.ReifiedMonadicFold m)
instance Data.Profunctor.Choice.Choice (Control.Lens.Action.Reified.ReifiedMonadicFold m)
instance Control.Category.Category (Control.Lens.Action.Reified.ReifiedMonadicFold m)
instance Control.Arrow.Arrow (Control.Lens.Action.Reified.ReifiedMonadicFold m)
instance Control.Arrow.ArrowChoice (Control.Lens.Action.Reified.ReifiedMonadicFold m)
instance Control.Arrow.ArrowApply (Control.Lens.Action.Reified.ReifiedMonadicFold m)
instance GHC.Base.Functor (Control.Lens.Action.Reified.ReifiedMonadicFold m s)
instance Data.Functor.Bind.Class.Apply (Control.Lens.Action.Reified.ReifiedMonadicFold m s)
instance GHC.Base.Applicative (Control.Lens.Action.Reified.ReifiedMonadicFold m s)
instance GHC.Base.Alternative (Control.Lens.Action.Reified.ReifiedMonadicFold m s)
instance Data.Functor.Bind.Class.Bind (Control.Lens.Action.Reified.ReifiedMonadicFold m s)
instance GHC.Base.Monad (Control.Lens.Action.Reified.ReifiedMonadicFold m s)
instance Control.Monad.Reader.Class.MonadReader s (Control.Lens.Action.Reified.ReifiedMonadicFold m s)
instance GHC.Base.MonadPlus (Control.Lens.Action.Reified.ReifiedMonadicFold m s)
instance Data.Semigroup.Semigroup (Control.Lens.Action.Reified.ReifiedMonadicFold m s a)
instance GHC.Base.Monoid (Control.Lens.Action.Reified.ReifiedMonadicFold m s a)
instance Data.Functor.Alt.Alt (Control.Lens.Action.Reified.ReifiedMonadicFold m s)
instance Data.Functor.Plus.Plus (Control.Lens.Action.Reified.ReifiedMonadicFold m s)