{-# LANGUAGE Rank2Types #-} {-# LANGUAGE ScopedTypeVariables #-} -- | -- Module : Control.Auto.Run -- Description : Various utilities for running and unrolling 'Auto's, both -- interactively and non-interactively. -- Copyright : (c) Justin Le 2015 -- License : MIT -- Maintainer : justin@jle.im -- Stability : unstable -- Portability : portable -- -- This module provides utilities for "running" and "unrolling" 'Auto's. -- You'll find "enhanced" versions of 'stepAuto', mechanisms for running -- 'Auto's "interactively" inside 'IO', monadic and non-monadic -- "self-runners" (provide the handlers, and the 'Auto' just recursively -- runs intself), and finally, ways of "unrolling" the underlying 'Monad' -- of 'Auto's into more manageable and composable and easy to work with -- forms. -- module Control.Auto.Run ( -- * Special 'stepAuto' versions. -- ** Streaming over lists streamAuto , streamAuto' , overList , overList' -- ** Running over one item repetitively , stepAutoN , stepAutoN' , evalAutoN , evalAutoN' -- * Running "interactively" , interactAuto , interactRS , interactM -- ** Helpers , duringRead , bindRead -- * Generalized "self-runners" , run , runM -- * Running on concurrent channels , runOnChan , runOnChanM -- * Running on as a ListT-compatible stream , streamAutoEffects , toEffectStream ) where import Control.Applicative import Control.Auto.Core import Control.Auto.Interval import Control.Concurrent import Control.Monad hiding (mapM, mapM_) import Control.Monad.Trans.Class import Data.Functor.Identity import Data.Maybe import Data.Profunctor import Prelude hiding (interact, mapM, mapM_) import Text.Read hiding (lift) -- | Streams the 'Auto' over a list of inputs; that is, "unwraps" the @[a] -- -> m [b]@ inside. Streaming is done in the context of the underlying -- monad; when done consuming the list, the result is the list of outputs -- updated/next 'Auto' in the context of the underlying monad. -- -- Basically just steps the 'Auto' by feeding in every item in the list and -- pops out the list of results and the updated/next 'Auto', monadically -- chaining the steppings. -- -- See 'overList'' for a simpler example; the following example uses -- effects from 'IO' to demonstrate the monadic features of 'overList'. -- -- >>> let a = arrM print *> sumFrom 0 :: Auto IO Int Int -- >>> (ys, a') <- overList a [1..5] -- 1 -- IO effects -- 2 -- 3 -- 4 -- 5 -- >>> ys -- [1,3,6,10,15] -- >>> (ys', _) <- overList a' [11..15] -- 11 -- IO effects -- 12 -- 13 -- 14 -- 15 -- >>> ys' -- [26,38,51,65,80] -- -- @a@ is like @'sumFrom' 0@, except at every step, prints the input item -- to stdout as a side-effect. Note that in executing we get the updated -- @a'@, which ends up with an accumulator of 15. Now, when we stream -- @a'@, we pick up were we left off (from 15) on the results. -- overList :: Monad m => Auto m a b -- ^ the 'Auto' to run -> [a] -- ^ list of inputs to step the 'Auto' with -> m ([b], Auto m a b) -- ^ list of outputs and the updated 'Auto' overList a [] = return ([], a) overList a (x:xs) = do (y, a') <- stepAuto a x (ys, a'') <- overList a' xs return (y:ys, a'') -- | Streams an 'Auto'' over a list of inputs; that is, "unwraps" the @[a] -- -> [b]@ inside. When done comsuming the list, returns the outputs and -- the updated/next 'Auto''. -- -- >>> let (ys, updatedSummer) = overList' (sumFrom 0) [1..5] -- >>> ys -- [1, 3, 6, 10, 15] -- >>> let (ys', _) = streamAuto' updatedSummer [1..5] -- >>> ys' -- [16, 18, 21, 25, 30] -- -- If you wanted to stream over an infinite list then you don't care about -- the 'Auto'' at the end, and probably want 'streamAuto''. -- overList' :: Auto' a b -- ^ the 'Auto'' to run -> [a] -- ^ list of inputs to step the 'Auto'' with -> ([b], Auto' a b) -- ^ list of outputs and the updated 'Auto'' overList' a [] = ([], a) overList' a (x:xs) = let (y, a') = stepAuto' a x (ys, a'') = overList' a' xs in (y:ys, a'') -- | Stream an 'Auto' over a list, returning the list of results. Does -- this "lazily" (over the Monad), so with most Monads, this should work -- fine with infinite lists. (That is, @'streamAuto' ('arrM' f)@ behaves -- exactly like @'mapM' f@, and you can reason with 'Auto's as if you'd -- reason with @mapM@ on an infinite list) -- -- Note that, conceptually, this turns an @'Auto' m a b@ into an @[a] -> -- m [b]@. -- -- See 'streamAuto'' for a simpler example; here is one taking advantage of -- monadic effects: -- -- >>> let a = arrM print *> sumFrom 0 :: Auto IO Int Int -- >>> ys <- streamAuto a [1..5] -- 1 -- IO effects -- 2 -- 3 -- 4 -- 5 -- >>> ys -- [1,3,6,10,15] -- the result -- -- @a@ here is like @'sumFrom' 0@, except at every step, prints the input -- item to stdout as a side-effect. -- -- Note that we use "stream" here slightly differently than in libraries -- like /pipes/ or /conduit/. We don't stream over the @m@ Monad (like -- @IO@)...we stream over the __input elements__. Using 'streamAuto' on an -- infinite list allows you to "stop", for example, to find the -- result...but it will still sequence all the *effects*. -- -- For example: -- -- >>> take 10 <$> streamAuto (arrM print *> id) [1..] -- -- Will execute 'print' on every element before "returning" with [1..10]. -- -- >>> flip runState 0 $ take 10 <$> streamAuto (arrM (modify . (+)) *> id) [1..] -- ([1,2,3,4,5,6,7,8,9,10], .... (never terminates) -- -- This will immediately return the "result", and you can bind to the -- result with `(>>=)`, but it'll never return a "final state", because the -- final state involves executing all of the 'modify's. -- -- In other words, we stream /values/, not /effects/. You would analyze -- this behavior the same way you would look at something like 'mapM'. -- -- If you want to stream effects, you can use 'streamAutoEffects' or -- 'toEffectStream', and use an effects streaming library like /pipes/ (or -- anything with /ListT/)...this will give the proper streaming of effects -- with resource handling, handling infinite streams in finite space with -- finite effects, etc. -- streamAuto :: Monad m => Auto m a b -- ^ 'Auto' to stream -> [a] -- ^ input stream -> m [b] -- ^ output stream streamAuto _ [] = return [] streamAuto a (x:xs) = do (y, a') <- stepAuto a x ys <- streamAuto a' xs return (y:ys) -- | Stream an 'Auto'' over a list, returning the list of results. Does -- this lazily, so this should work fine with (and is actually somewhat -- designed for) infinite lists. -- -- Note that conceptually this turns an @'Auto'' a b@ into an @[a] -> [b]@ -- -- >>> streamAuto' (arr (+3)) [1..10] -- [4,5,6,7,8,9,10,11,12,13] -- >>> streamAuto' (sumFrom 0) [1..5] -- [1,3,6,10,15] -- >>> streamAuto' (productFrom 1) . streamAuto' (sumFrom 0) $ [1..5] -- [1,3,18,180,2700] -- >>> streamAuto' (productFrom 1 . sumFrom 0) $ [1..5] -- [1,3,18,180,2700] -- >>> streamAuto' id [1..5] -- [1,2,3,4,5] -- streamAuto' :: Auto' a b -- ^ 'Auto'' to stream -> [a] -- ^ input stream -> [b] -- ^ output stream streamAuto' _ [] = [] streamAuto' a (x:xs) = let (y, a') = stepAuto' a x ys = streamAuto' a' xs in y:ys -- | Streams (in the context of the underlying monad) the given 'Auto' with -- a stream of constant values as input, a given number of times. After -- the given number of inputs, returns the list of results and the -- next/updated 'Auto', in the context of the underlying monad. -- -- prop> stepAutoN n a0 x = overList a0 (replicate n x) -- -- See 'stepAutoN'' for a simpler example; here is one taking advantage of -- monadic effects: -- -- >>> let a = arrM print *> sumFrom 0 :: Auto IO Int Int -- >>> (ys, a') <- stepAutoN 5 a 3 -- 3 -- IO effects -- 3 -- 3 -- 3 -- 3 -- >>> ys -- [3,6,9,12,15] -- the result -- >>> (ys'', _) <- stepAutoN 5 a' 5 -- 5 -- IO effects -- 5 -- 5 -- 5 -- 5 -- >>> ys'' -- [20,25,30,35,50] -- the result -- -- @a@ here is like @'sumFrom' 0@, except at every step, prints the input -- item to stdout as a side-effect. -- stepAutoN :: Monad m => Int -- ^ number of times to step the 'Auto' -> Auto m a b -- ^ the 'Auto' to run -> a -- ^ the repeated input -> m ([b], Auto m a b) -- ^ list of outputs and the updated 'Auto' stepAutoN n a0 x = go (max n 0) a0 where go 0 a = return ([], a) go i a = do (y , a') <- stepAuto a x (ys, a'') <- go (i - 1) a' return (y:ys, a'') -- | Streams the given 'Auto'' with a stream of constant values as input, -- a given number of times. After the given number of inputs, returns the -- list of results and the next/updated 'Auto'. -- -- prop> stepAutoN' n a0 x = overList' a0 (replicate n x) -- -- >>> let (ys, a') = stepAutoN' 5 (sumFrom 0) 3 -- >>> ys -- [3,6,9,12,15] -- >>> let (ys', _) = stepAutoN' 5 a' 5 -- >>> ys' -- [20,25,30,35,40] -- stepAutoN' :: Int -- ^ number of times to step the 'Auto'' -> Auto' a b -- ^ the 'Auto'' to run -> a -- ^ the repeated input -> ([b], Auto' a b) -- ^ list of outputs and the updated 'Auto'' stepAutoN' n a0 x = runIdentity (stepAutoN n a0 x) -- | Streams (in the context of the underlying monad) the given 'Auto' with -- a stream of constant values as input, a given number of times. After -- the given number of inputs, returns the list of results in the context -- of the underlying monad. -- -- Like 'stepAutoN', but drops the "next 'Auto'". Only returns the list -- of results. -- -- >>> let a = arrM print *> sumFrom 0 :: Auto IO Int Int -- >>> ys <- evalAutoN 5 a 3 -- 3 -- IO effects -- 3 -- 3 -- 3 -- 3 -- >>> ys -- [3,6,9,12,15] -- the result -- -- @a@ here is like @'sumFrom' 0@, except at every step, prints the input -- item to stdout as a side-effect. evalAutoN :: Monad m => Int -- ^ number of times to step the 'Auto' -> Auto m a b -- ^ the 'Auto' to run -> a -- ^ the repeated input -> m [b] -- ^ list of outputs evalAutoN n a0 = liftM fst . stepAutoN n a0 -- | Streams the given 'Auto'' with a stream of constant values as input, -- a given number of times. After the given number of inputs, returns the -- list of results and the next/updated 'Auto'. -- -- Like 'stepAutoN'', but drops the "next 'Auto''". Only returns the list -- of results. -- -- >>> evalAutoN' 5 (sumFrom 0) 3 -- [3,6,9,12,15] -- evalAutoN' :: Int -- ^ number of times to step the 'Auto'' -> Auto' a b -- ^ the 'Auto'' to run -> a -- ^ the repeated input -> [b] -- ^ list of outputs and the updated 'Auto'' evalAutoN' n a0 = fst . stepAutoN' n a0 -- execAutoN :: Monad m -- => Int -- -> Auto m a b -- -> a -- -> m (Auto m a b) -- execAutoN n a0 = liftM snd . stepAutoN n a0 -- execAutoN' :: Int -- -> Auto' a b -- -> a -- -> Auto' a b -- execAutoN' n a0 = snd . stepAutoN' n a0 -- | Heavy duty abstraction for "self running" an 'Auto'. Give a starting -- input action, a (possibly side-effecting) function from an output to -- the next input to feed in, and the 'Auto', and you get a feedback -- loop that constantly feeds back in the result of the function applied to -- the previous output. "Stops" when the "next input" function returns -- 'Nothing'. -- -- Note that the none of the results are actually returned from the loop. -- Instead, if you want to process the results, they must be utilized in -- the "side-effects' of the "next input" function. (ie, a write to -- a file, or an accumulation to a state). -- run :: Monad m => m a -- ^ action to retrieve starting input -> (b -> m (Maybe a)) -- ^ handling output and next input in @m@ -> Auto m a b -- ^ 'Auto' -> m (Auto m a b) -- ^ return the ran/updated 'Auto' in @m@ run = runM id -- | A generalized version of 'run' where the 'Monad' you are "running" the -- 'Auto' in is different than the 'Monad' underneath the 'Auto'. You just -- need to provide the natural transformation. runM :: (Monad m, Monad m') => (forall c. m' c -> m c) -- ^ natural transformation from @m'@ (the Auto monad) to @m@ (the running monad) -> m a -- ^ action to retrieve starting input -> (b -> m (Maybe a)) -- ^ handling output and next input in @m@ -> Auto m' a b -- ^ 'Auto' in monad @m'@ -> m (Auto m' a b) -- ^ return the resulting/run Auto in @m@ runM nt x0 f a = do (y, a') <- nt . stepAuto a =<< x0 x1 <- f y case x1 of -- TODO: optimize for no return x Just x -> runM nt (return x) f a' Nothing -> return a' -- | Run an 'Auto'' "interactively". Every step grab a string from stdin, -- and feed it to the 'Interval''. If the 'Interval'' is "off", ends the -- session; if it is "on", then prints the output value to stdout and -- repeat all over again. -- -- If your 'Auto' outputs something other than a 'String', you can use -- 'fmap' to transform the output into a 'String' en-route (like @'fmap' -- 'show'@). -- -- If your 'Auto' takes in something other than a 'String', you can 'lmap' -- a function to convert the input 'String' to whatever intput your 'Auto' -- expects. -- -- You can use 'duringRead' or 'bindRead' if you have an 'Auto'' or -- 'Interval'' that takes something 'read'able, to chug along until you -- find something non-readable; there's also 'interactRS' which handles -- most of that for you. -- -- Outputs the final 'Interval'' when the interaction terminates. interactAuto :: Interval' String String -- ^ 'Interval'' to run interactively -> IO (Interval' String String) -- ^ final 'Interval'' after it all interactAuto = interactM (return . runIdentity) f where f (Just str) = True <$ putStrLn str f Nothing = return False -- | Like 'interact', but instead of taking @'Interval'' 'String' -- 'String'@, takes any @'Interval'' a b@ as long as @a@ is 'Read' and @b@ -- is 'Show'. -- -- Will "stop" if either (1) the input is not 'read'-able or (2) the -- 'Interval'' turns off. -- -- Outputs the final 'Auto'' when the interaction terminates. interactRS :: (Read a, Show b) => Interval' a b -- ^ 'Interval'' to run interactively -> IO (Interval' String String) -- ^ final 'Interval'' after it all interactRS = interactAuto . bindRead . fmap (fmap show) -- | Like 'interact', but much more general. You can run it with an 'Auto' -- of any underlying 'Monad', as long as you provide the natural -- transformation from that 'Monad' to 'IO'. -- -- The 'Auto' can any @'Maybe' b@; you have to provide -- a function to "handle" it yourself; a @b -> 'IO' 'Bool'@. You can print -- the result, or write the result to a file, etc.; the 'Bool' parameter -- determines whether or not to "continue running", or to stop and return -- the final updated 'Auto'. interactM :: Monad m => (forall c. m c -> IO c) -- ^ natural transformation from the underlying 'Monad' of the 'Auto' to 'IO' -> (b -> IO Bool) -- ^ function to "handle" each succesful 'Auto' output -> Auto m String b -- ^ 'Auto' to run "interactively" -> IO (Auto m String b) -- ^ final 'Auto' after it all interactM nt f = runM nt getLine f' where f' y = do cont <- f y if cont then Just <$> getLine else return Nothing -- | Turn an 'Auto' that takes a "readable" @a@ and outputs a @b@ into an -- 'Auto' that takes a 'String' and outputs a @'Maybe' b@. When the -- 'String' is successfuly readable as the @a@, it steps the 'Auto' and -- outputs a succesful 'Just' result; when it isn't, it outputs a 'Nothing' -- on that step. -- -- >>> let a0 = duringRead (accum (+) (0 :: Int)) -- >>> let (y1, a1) = stepAuto' a0 "12" -- >>> y1 -- Just 12 -- >>> let (y2, a2) = stepAuto' a1 "orange" -- >>> y2 -- Nothing -- >>> let (y3, _ ) = stepAuto' a2 "4" -- >>> y3 -- Just 16 -- -- See 'interact' for neat use cases. duringRead :: (Monad m, Read a) => Auto m a b -- ^ 'Auto' taking in a readable @a@, outputting @b@ -> Interval m String b -- ^ 'Auto' taking in 'String', outputting @'Maybe' b@ duringRead = lmap readMaybe . during -- | Like 'duringRead', but the original 'Auto' would output a @'Maybe' b@ -- instead of a @b@. Returns 'Nothing' if either the 'String' fails to -- parse or if the original 'Auto' returned 'Nothing'; returns 'Just' if -- the 'String' parses and the original 'Auto' returned 'Just'. -- -- See 'interact' for neat use cases. bindRead :: (Monad m, Read a) => Interval m a b -- ^ 'Auto' taking in a readable @a@, outputting @'Maybe' b@ -> Interval m String b -- ^ 'Auto' taking in 'String', outputting @'Maybe' b@ bindRead = lmap readMaybe . bindI -- | A generalized version of 'runOnChan' that can run on any @'Auto' m@; -- all that is required is a natural transformation from the underyling -- 'Monad' @m@ to 'IO'. runOnChanM :: Monad m => (forall c. m c -> IO c) -- ^ natural transformation from the -- underling 'Monad' of the -- 'Auto' to 'IO' -> (b -> IO Bool) -- ^ function to "handle" each -- succesful 'Auto' output; -- result is whether or not to -- continue. -> Chan a -- ^ 'Chan' queue to pull input from. -> Auto m a b -- ^ 'Auto' to run -> IO (Auto m a b) -- ^ final 'Auto' after it all, when -- the handle resturns 'False' runOnChanM nt f chan = go where go a0 = do x <- readChan chan (y, a1) <- nt $ stepAuto a0 x cont <- f y if cont then go a1 else return a1 -- | Runs the 'Auto'' in IO with inputs read from a 'Chan' queue, from -- "Control.Concurrency.Chan". It'll block until the 'Chan' has a new -- input, run the 'Auto' with the received input, process the output with -- the given handling function, and start over if the handling function -- returns 'True'. runOnChan :: (b -> IO Bool) -- ^ function to "handle" each -- succesful 'Auto' output; -- result is whether or not to -- continue. -> Chan a -- ^ 'Chan' queue to pull input from. -> Auto' a b -- ^ 'Auto'' to run -> IO (Auto' a b) -- ^ final 'Auto' after it all, when -- the handle resturns 'False' runOnChan = runOnChanM (return . runIdentity) -- | Turns an @Auto m' a b@ and an "input producer" @m a@ into a "ListT -- compatible effectful stream", as described at -- <http://www.haskellforall.com/2014/11/how-to-build-library-agnostic-streaming.html> -- -- Any library that offers a "@ListT@" type can use this result...and -- usually turn it into an effectful stream. -- -- For example, the /pipes/ library offers @runListT@ so you can run this, -- constantly pulling out @a@s from the stream using the @m a@, feeding -- it in, and moving forward, all with the effect stream manipulation tools -- and resource handling of /pipes/. -- -- This is useful because /auto/, the library, mainly provides tools for -- working with transformers for /value/ streams, and not effect streams or -- streams of effects. Using this, you can potentially have the best of -- both worlds. toEffectStream :: (Monad m, MonadTrans t, MonadPlus (t m), Monad m') => (forall c. m' c -> m c) -- ^ function to change the underyling monad from @m'@ to @m@ -> m a -- ^ action to generate inputs -> Auto m' a b -- ^ Auto to run as an effectful stream -> t m b -- ^ @ListT@-compatible type toEffectStream nt getInp = go where go a0 = do (y, a1) <- lift $ do x <- getInp nt $ stepAuto a0 x return y `mplus` go a1 -- | Turns an @Auto m' a b@ with a list of inputs into a "ListT compatible -- effectful stream", as described at -- <http://www.haskellforall.com/2014/11/how-to-build-library-agnostic-streaming.html> -- -- Any library that offers a "@ListT@" type can use this result...and -- usually turn it into an effectful stream. -- -- For example, the /pipes/ library offers @runListT@ so you can run this, -- running the 'Auto' over the input list, all with the effect stream -- manipulation tools and resource handling of /pipes/. -- -- This is useful because /auto/, the library, mainly provides tools for -- working with transformers for /value/ streams, and not effect streams or -- streams of effects. Using this, you can potentially have the best of -- both worlds. streamAutoEffects :: (Monad m, MonadTrans t, MonadPlus (t m), Monad m') => (forall c. m' c -> m c) -> [a] -> Auto m' a b -> t m b streamAutoEffects nt = go where go [] _ = mzero go (x:xs) a0 = do (y, a1) <- lift . nt $ stepAuto a0 x return y `mplus` go xs a1