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


-- | Applicative/Arrow for resource estimation and progress tracking.
--   
--   This module contains a writer-like Applicative for giving monoidal
--   annotations to underlying computations. The annotations are available
--   before running the computations. It also allows tagging different
--   parts of a computation as separate steps, so that progress
--   notifications can be emitted during execution. Optional steps are
--   allowed.
@package plan-applicative
@version 2.0.0.1


-- | Prefer using the main module. If you manipulate the internals of
--   <a>Plan</a> to add fake steps, bad things might happen.
module Control.Plan.Core

-- | A computation that takes inputs of type <tt>i</tt> and produces
--   outputs of type <tt>o</tt> working in the underlying monad <tt>m</tt>.
--   The <a>Applicative</a> instance cares only about the outputs, the
--   <a>Arrow</a> instance cares about both inputs and outputs.
--   
--   Parts of the computation can be labeled as steps with tags of type
--   <tt>s</tt>.
--   
--   Computations can have monoidal resource annotations of type
--   <tt>w</tt>.
--   
--   The structure of steps and the monoidal annotations can be inspected
--   before executing the <a>Plan</a>.
data Plan s w m i o
Plan :: (Steps s w) -> (Star (Stream (Of Tick') m) i o) -> Plan s w m i o

-- | A <a>Forest</a> of steps tags of type <tt>s</tt> interspersed with
--   monoidal annotations of type <tt>w</tt>.
data Steps s w
Steps :: !(Seq (w, s, Mandatoriness, Steps s w)) -> w -> Steps s w
data Mandatoriness
Skippable :: Mandatoriness
Mandatory :: Mandatoriness

-- | <a>bifoldMap</a> allows extracting the steps and the annotations
--   together.

-- | A catamorphism on <a>Steps</a>, that "destroys" the <a>Steps</a> value
--   from the leaves upwards.
--   
--   Unlike <a>foldMap</a> or <a>bifoldMap</a>, it allows a more structured
--   analysis of the annotations, by preserving their relationship with the
--   hierarchy of steps.
foldSteps :: ([(w, s, Mandatoriness, r)] -> w -> r) -> Steps s w -> r
foldSteps' :: (Seq (w, s, Mandatoriness, r) -> w -> r) -> Steps s w -> r

-- | Adapt the <tt>Step</tt> value inside a <a>Plan</a> without extracting
--   it.
bimapSteps :: (s -> s') -> (w -> w') -> Plan s w m i o -> Plan s' w' m i o

-- | Use a lens setter to "zoom" the monoidal annotations of a <a>Plan</a>
--   into a wider monoidal context.
zoomSteps :: Monoid w' => ((w -> Identity w) -> w' -> Identity w') -> Plan s w m i o -> Plan s w' m i o

-- | Change the underlying monad of a <a>Plan</a>.
hoistPlan :: Monad m => (forall x. m x -> n x) -> Plan s w m i o -> Plan s w n i o
data Tick'
Skipped' :: Tick'
Started' :: Tick'
Finished' :: Tick'

-- | Inspect a plan without executing it.
getSteps :: Plan s w m i o -> Steps s w

-- | Decorate each step tag with its mandatoriness. Useful in combination
--   with <a>toForest</a>.
mandatoriness :: Steps s w -> Steps (Mandatoriness, s) w

-- | Declare a step by wrapping an existing plan (which may contain
--   substeps).
step :: (Monoid w, Monad m) => s -> Plan s w m i o -> Plan s w m i o

-- | Declare an optional step by wrapping an existing arrow plan. The step
--   will only be executed when the input is <a>Just</a>.
--   
--   This function only makes sense when using the <a>Arrow</a> instance of
--   <a>Plan</a>, because for <a>Applicative</a>s an effect cannot depend
--   on previously obtained values.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let example :: Plan String () IO () ()
--           example = proc () -&gt; do 
--               i &lt;- step "reading" (plan (readMaybe @Int &lt;$&gt; getLine)) -&lt; () 
--               skippable "writing" (kplan print) -&lt; i
--       in  putStr . drawForest . fmap (fmap show) . toForest . mandatoriness . getSteps $ example
--       :}
--   (Mandatory,"reading")
--   
--   (Skippable,"writing")
--   </pre>
skippable :: (Monoid w, Monad m) => s -> Plan s w m i o -> Plan s w m (Maybe i) ()

-- | Declare a monoidal annotation. The annotation can be later inspected
--   without having to run the <a>Plan</a>.
--   
--   Usually the annotations will represent resources that the <a>Plan</a>
--   is expected to require.
foretell :: (Monad m) => w -> Plan s w m i ()

-- | Lift a monadic action to a <a>Plan</a>. The input type remains
--   polymorphic.
plan :: (Monoid w, Monad m) => m o -> Plan s w m i o

-- | Lift an <a>IO</a> action to a <a>Plan</a>. The input type remains
--   polymorphic.
planIO :: (Monoid w, MonadIO m) => IO o -> Plan s w m i o

-- | Lift a Kleisli arrow to a <a>Plan</a>.
kplan :: (Monoid w, Monad m) => (i -> m o) -> Plan s w m i o

-- | Lift a Kleisli arrow working in <a>IO</a> to a <a>Plan</a>.
kplanIO :: (Monoid w, MonadIO m) => (i -> IO o) -> Plan s w m i o
zipSteps' :: Forest a -> Steps r w -> Maybe (Steps (a, r) w)

-- | Pair each step tag <tt>s</tt> inside a <a>Plan</a> with the
--   corresponding element of the <a>Forest</a>.
--   
--   If the forest doesn't have the same structure as the steps, the
--   function fails with <a>Nothing</a>.
--   
--   This function can be useful to annotate each step tag with some
--   information, for example the time duration of the step in a previous
--   execution of the plan. See <a>Timeline</a>, <a>instants</a>, and
--   <a>toForest</a>.
zipSteps :: Forest s' -> Plan s w m i o -> Maybe (Plan (s', s) w m i o)

-- | A given step might not have been reached yet. It it has been reached,
--   either it has been skipped at a certain time, or started at a certain
--   time. If if has been started, maybe it has already finished, too.
--   
--   This function can be used in combination with <a>toForest</a> and
--   <a>drawForest</a> to render the state of each step for a <a>Tick</a>.
completedness :: Tick s t -> Tick (Maybe (Either t (t, Maybe t)), s) t
contextCompletedness :: (t -> (Either t (t, Maybe t))) -> Context s t -> Context (Maybe (Either t (t, Maybe t)), s) t
adapt :: Timeline (Either t (t, t), s) t -> Timeline (Maybe (Either t (t, Maybe t)), s) t
progressCompletedness :: t -> Progress s t -> (Progress (Maybe (Either t (t, Maybe t)), s) t, Maybe (Either t (t, Maybe t)))

-- | Forget that there is a plan, get the underlying monadic action.
unliftPlan :: Monad m => Plan s w m () o -> m o

-- | Forget that there is a plan, get the underlying Kleisli arrow.
unliftKPlan :: Monad m => Plan s w m i o -> i -> m o

-- | A <a>Forest</a> of steps tags of type <tt>s</tt> interspersed with
--   measurements of type <tt>t</tt>.
data Timeline s t
Timeline :: !(Seq (t, s, Either (Forest s) (Timeline s t))) -> t -> Timeline s t

-- | <a>Timeline</a>s always have at least one measurement. <a>extract</a>
--   gives the final measurement.

-- | Decorate each step tag with either the time the step was skipped, or
--   the time it was started and finished. Useful in combination with
--   <a>toForest</a>.
instants :: Timeline s t -> Timeline (Either t (t, t), s) t

-- | A catamorphism on <a>Timeline</a>s, that "destroys" the
--   <a>Timeline</a> value from the leaves upwards.
foldTimeline :: ([(t, s, Either (Forest s) r)] -> t -> r) -> Timeline s t -> r
foldTimeline' :: (Seq (t, c, Either (Forest c) r) -> t -> r) -> Timeline c t -> r

-- | Represents how far we are along a sequence of sibling steps.
--   
--   For the already completed steps, a <a>Timeline</a> of measurements is
--   provided. <a>extract</a> for the <a>Timeline</a> returns the starting
--   measurement of the current step.
data Context s t
Context :: Timeline s t -> s -> Forest s -> Context s t
[completed] :: Context s t -> Timeline s t
[current] :: Context s t -> s
[pending] :: Context s t -> Forest s

-- | Represents some kind of progress through the <a>Steps</a> of a
--   <a>Plan</a> while the plan executes.
--   
--   The ascending list of contexts provides the current position of the
--   execution along the hierarchy of steps.
--   
--   If the plan only has a linear sequence of steps, the list will have
--   only one <a>Context</a>.
data Tick s t
Tick :: (NonEmpty (Context s t)) -> (Progress s t) -> Tick s t

-- | The execution of a <a>Plan</a> can make progress by skipping a step,
--   starting a step, or finishing a step.
data Progress s t

-- | Provides the substeps that were skipped.
Skipped :: (Forest s) -> Progress s t

-- | Provides the substeps that will be executed next.
Started :: (Forest s) -> Progress s t

-- | Provides a <a>Timeline</a> of measurements for the completed substeps.
--   <a>extract</a> for the <a>Timeline</a> gives the finishing measurement
--   for the current step.
Finished :: (Timeline s t) -> Progress s t

-- | Specify a monadic callback for processing each <a>Tick</a> update.
onTick :: Monad m => (tick -> m ()) -> Stream (Of tick) m r -> m r

-- | Runs a plan that doesn't need input. It returns a <a>Stream</a> of
--   <a>Tick</a> updates that are emitted every time the execution advances
--   through the <a>Steps</a>.
--   
--   For each <a>Tick</a> update, a monadic measurement of type <tt>t</tt>
--   is taken. Usually the measurement consists in getting the current
--   time.
--   
--   When the execution finishes, a <a>Timeline</a> with the measurements
--   for each <a>Tick</a> is returned, along with the result value.
--   
--   Even if the plan didn't have any steps, the <a>Timeline</a> will
--   contain a measurement taken when the computation finished.
runPlan :: Monad m => m t -> Plan s w m () o -> Stream (Of (Tick s t)) m (Timeline s t, o)

-- | Like <a>runPlan</a>, but for <a>Arrow</a>-like <a>Plan</a>s that take
--   inputs.
runKPlan :: Monad m => m t -> Plan s w m i o -> i -> Stream (Of (Tick s t)) m (Timeline s t, o)
data RunState s t
RunState :: !(Seq (t, s, Either (Forest s) (Timeline s t))) -> !(Forest s) -> ![Context s t] -> RunState s t

-- | Instances of <a>Sylvan</a> are <a>Forest</a>s with nodes of type
--   <tt>n</tt>, interspersed with annotations of type <tt>a</tt>, and
--   perhaps some other extra information.
--   
--   They must satisfy
--   
--   <pre>
--   bifoldMap f (\_ -&gt; mempty) s == foldMap (foldMap f) (toForest s)
--   </pre>
class (Bitraversable l) => Sylvan l

-- | Forget about the annotations and return the underlying <a>Forest</a>.
toForest :: Sylvan l => l n a -> Forest n

-- | <a>toForest</a> forgets about the annotations and returns a
--   <a>Forest</a> of step tags.

-- | <a>toForest</a> forgets about the measurements and returns a
--   <a>Forest</a> of step tags.

-- | A <a>Forest</a> is a <a>Sylvan</a> for which no annotations exist.
instance (GHC.Show.Show s, GHC.Show.Show t) => GHC.Show.Show (Control.Plan.Core.Tick s t)
instance (GHC.Classes.Eq s, GHC.Classes.Eq t) => GHC.Classes.Eq (Control.Plan.Core.Tick s t)
instance Data.Traversable.Traversable (Control.Plan.Core.Tick s)
instance Data.Foldable.Foldable (Control.Plan.Core.Tick s)
instance GHC.Base.Functor (Control.Plan.Core.Tick s)
instance (GHC.Show.Show t, GHC.Show.Show s) => GHC.Show.Show (Control.Plan.Core.Progress s t)
instance (GHC.Classes.Eq t, GHC.Classes.Eq s) => GHC.Classes.Eq (Control.Plan.Core.Progress s t)
instance Data.Traversable.Traversable (Control.Plan.Core.Progress s)
instance Data.Foldable.Foldable (Control.Plan.Core.Progress s)
instance GHC.Base.Functor (Control.Plan.Core.Progress s)
instance (GHC.Show.Show t, GHC.Show.Show s) => GHC.Show.Show (Control.Plan.Core.Context s t)
instance (GHC.Classes.Eq t, GHC.Classes.Eq s) => GHC.Classes.Eq (Control.Plan.Core.Context s t)
instance Data.Traversable.Traversable (Control.Plan.Core.Context s)
instance Data.Foldable.Foldable (Control.Plan.Core.Context s)
instance GHC.Base.Functor (Control.Plan.Core.Context s)
instance (GHC.Show.Show s, GHC.Show.Show t) => GHC.Show.Show (Control.Plan.Core.Timeline s t)
instance (GHC.Classes.Eq s, GHC.Classes.Eq t) => GHC.Classes.Eq (Control.Plan.Core.Timeline s t)
instance Data.Traversable.Traversable (Control.Plan.Core.Timeline s)
instance Data.Foldable.Foldable (Control.Plan.Core.Timeline s)
instance GHC.Base.Functor (Control.Plan.Core.Timeline s)
instance GHC.Base.Monad m => GHC.Base.Functor (Control.Plan.Core.Plan s w m i)
instance GHC.Show.Show Control.Plan.Core.Tick'
instance GHC.Enum.Enum Control.Plan.Core.Tick'
instance GHC.Classes.Ord Control.Plan.Core.Tick'
instance GHC.Classes.Eq Control.Plan.Core.Tick'
instance (GHC.Show.Show s, GHC.Show.Show w) => GHC.Show.Show (Control.Plan.Core.Steps s w)
instance (GHC.Classes.Eq s, GHC.Classes.Eq w) => GHC.Classes.Eq (Control.Plan.Core.Steps s w)
instance Data.Traversable.Traversable (Control.Plan.Core.Steps s)
instance Data.Foldable.Foldable (Control.Plan.Core.Steps s)
instance GHC.Base.Functor (Control.Plan.Core.Steps s)
instance GHC.Classes.Ord Control.Plan.Core.Mandatoriness
instance GHC.Classes.Eq Control.Plan.Core.Mandatoriness
instance GHC.Show.Show Control.Plan.Core.Mandatoriness
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => GHC.Base.Applicative (Control.Plan.Core.Plan s w m i)
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => Control.Category.Category (Control.Plan.Core.Plan s w m)
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => Control.Arrow.Arrow (Control.Plan.Core.Plan s w m)
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => Data.Profunctor.Unsafe.Profunctor (Control.Plan.Core.Plan s w m)
instance Data.Bifunctor.Bifunctor Control.Plan.Core.Steps
instance Data.Bifoldable.Bifoldable Control.Plan.Core.Steps
instance Data.Bitraversable.Bitraversable Control.Plan.Core.Steps
instance GHC.Base.Monoid w => GHC.Base.Monoid (Control.Plan.Core.Steps s w)
instance Data.Bifunctor.Bifunctor Control.Plan.Core.Timeline
instance Data.Bifoldable.Bifoldable Control.Plan.Core.Timeline
instance Data.Bitraversable.Bitraversable Control.Plan.Core.Timeline
instance Control.Comonad.Comonad (Control.Plan.Core.Timeline s)
instance Data.Bifunctor.Bifunctor Control.Plan.Core.Context
instance Data.Bifunctor.Bifunctor Control.Plan.Core.Tick
instance Data.Bifoldable.Bifoldable Control.Plan.Core.Tick
instance Data.Bitraversable.Bitraversable Control.Plan.Core.Tick
instance Control.Plan.Core.Sylvan Control.Plan.Core.Tick
instance Control.Plan.Core.Sylvan Control.Plan.Core.Progress
instance Data.Bifunctor.Bifunctor Control.Plan.Core.Progress
instance Data.Bifoldable.Bifoldable Control.Plan.Core.Progress
instance Data.Bitraversable.Bitraversable Control.Plan.Core.Progress
instance Control.Plan.Core.Sylvan Control.Plan.Core.Steps
instance Control.Plan.Core.Sylvan Control.Plan.Core.Timeline
instance Control.Plan.Core.Sylvan (Data.Bifunctor.Clown.Clown (Data.Functor.Compose.Compose [] Data.Tree.Tree))


-- | This module exports the <a>Plan</a> Applicative.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let example :: Plan String [Int] IO () ()
--           example = 
--               step "a" (step "b" (foretell [1] *&gt; plan (threadDelay 1e6)) 
--                         *&gt;
--                         step "c" (foretell [2] *&gt; plan (threadDelay 1e6))) 
--               *&gt;
--               step "d" (step "e" (foretell [3] *&gt; plan (threadDelay 1e6)) 
--                         *&gt;
--                         step "f" (foretell [4] *&gt; plan (threadDelay 1e6)))
--       in 
--       bifoldMap id (foldMap Prelude.show) (getSteps example)
--       :}
--   "ab1c2de3f4"
--   </pre>
--   
--   Some possible use cases:
--   
--   <ul>
--   <li>Inspect the steps of an existing <a>Plan</a> from <tt>ghci</tt>
--   using <a>getSteps</a>, <a>toForest</a> and <a>drawForest</a>, as a
--   form of documentation.</li>
--   <li>If your script requires files that must be already present in the
--   file system, use <a>foretell</a> to annotate each <a>Plan</a> action
--   that requires a file, then get the global list of files using
--   <a>getSteps</a> and <a>foldMap</a>, and check that they all exist
--   before running the <a>Plan</a> with <a>runPlan</a>.</li>
--   <li>Get progress updates for your script by declaring (possibly
--   nested) steps with <a>step</a>, running the <a>Plan</a> with
--   <a>runPlan</a>, and providing a notification callback with
--   <a>onTick</a>, probably using <a>completedness</a>,<a>toForest</a> and
--   <a>drawForest</a> to render the updates.</li>
--   <li>Run a <a>Plan</a> with <a>runPlan</a>, use <a>instants</a> an
--   <a>toForest</a> on the resulting <a>Timeline</a> to get the durations
--   of each step, then use <a>zipSteps</a> on the same <a>Plan</a> and run
--   it again. Now whenever a step finishes we can know if it took more or
--   less than in the previous execution.</li>
--   </ul>
module Control.Plan

-- | A computation that takes inputs of type <tt>i</tt> and produces
--   outputs of type <tt>o</tt> working in the underlying monad <tt>m</tt>.
--   The <a>Applicative</a> instance cares only about the outputs, the
--   <a>Arrow</a> instance cares about both inputs and outputs.
--   
--   Parts of the computation can be labeled as steps with tags of type
--   <tt>s</tt>.
--   
--   Computations can have monoidal resource annotations of type
--   <tt>w</tt>.
--   
--   The structure of steps and the monoidal annotations can be inspected
--   before executing the <a>Plan</a>.
data Plan s w m i o

-- | Lift a monadic action to a <a>Plan</a>. The input type remains
--   polymorphic.
plan :: (Monoid w, Monad m) => m o -> Plan s w m i o

-- | Lift an <a>IO</a> action to a <a>Plan</a>. The input type remains
--   polymorphic.
planIO :: (Monoid w, MonadIO m) => IO o -> Plan s w m i o

-- | Lift a Kleisli arrow to a <a>Plan</a>.
kplan :: (Monoid w, Monad m) => (i -> m o) -> Plan s w m i o

-- | Lift a Kleisli arrow working in <a>IO</a> to a <a>Plan</a>.
kplanIO :: (Monoid w, MonadIO m) => (i -> IO o) -> Plan s w m i o

-- | Declare a step by wrapping an existing plan (which may contain
--   substeps).
step :: (Monoid w, Monad m) => s -> Plan s w m i o -> Plan s w m i o

-- | Declare an optional step by wrapping an existing arrow plan. The step
--   will only be executed when the input is <a>Just</a>.
--   
--   This function only makes sense when using the <a>Arrow</a> instance of
--   <a>Plan</a>, because for <a>Applicative</a>s an effect cannot depend
--   on previously obtained values.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let example :: Plan String () IO () ()
--           example = proc () -&gt; do 
--               i &lt;- step "reading" (plan (readMaybe @Int &lt;$&gt; getLine)) -&lt; () 
--               skippable "writing" (kplan print) -&lt; i
--       in  putStr . drawForest . fmap (fmap show) . toForest . mandatoriness . getSteps $ example
--       :}
--   (Mandatory,"reading")
--   
--   (Skippable,"writing")
--   </pre>
skippable :: (Monoid w, Monad m) => s -> Plan s w m i o -> Plan s w m (Maybe i) ()

-- | Declare a monoidal annotation. The annotation can be later inspected
--   without having to run the <a>Plan</a>.
--   
--   Usually the annotations will represent resources that the <a>Plan</a>
--   is expected to require.
foretell :: (Monad m) => w -> Plan s w m i ()

-- | Inspect a plan without executing it.
getSteps :: Plan s w m i o -> Steps s w

-- | A <a>Forest</a> of steps tags of type <tt>s</tt> interspersed with
--   monoidal annotations of type <tt>w</tt>.
data Steps s w

-- | Decorate each step tag with its mandatoriness. Useful in combination
--   with <a>toForest</a>.
mandatoriness :: Steps s w -> Steps (Mandatoriness, s) w
data Mandatoriness
Skippable :: Mandatoriness
Mandatory :: Mandatoriness

-- | A catamorphism on <a>Steps</a>, that "destroys" the <a>Steps</a> value
--   from the leaves upwards.
--   
--   Unlike <a>foldMap</a> or <a>bifoldMap</a>, it allows a more structured
--   analysis of the annotations, by preserving their relationship with the
--   hierarchy of steps.
foldSteps :: ([(w, s, Mandatoriness, r)] -> w -> r) -> Steps s w -> r

-- | Adapt the <tt>Step</tt> value inside a <a>Plan</a> without extracting
--   it.
bimapSteps :: (s -> s') -> (w -> w') -> Plan s w m i o -> Plan s' w' m i o

-- | Use a lens setter to "zoom" the monoidal annotations of a <a>Plan</a>
--   into a wider monoidal context.
zoomSteps :: Monoid w' => ((w -> Identity w) -> w' -> Identity w') -> Plan s w m i o -> Plan s w' m i o

-- | Pair each step tag <tt>s</tt> inside a <a>Plan</a> with the
--   corresponding element of the <a>Forest</a>.
--   
--   If the forest doesn't have the same structure as the steps, the
--   function fails with <a>Nothing</a>.
--   
--   This function can be useful to annotate each step tag with some
--   information, for example the time duration of the step in a previous
--   execution of the plan. See <a>Timeline</a>, <a>instants</a>, and
--   <a>toForest</a>.
zipSteps :: Forest s' -> Plan s w m i o -> Maybe (Plan (s', s) w m i o)

-- | Change the underlying monad of a <a>Plan</a>.
hoistPlan :: Monad m => (forall x. m x -> n x) -> Plan s w m i o -> Plan s w n i o

-- | Forget that there is a plan, get the underlying monadic action.
unliftPlan :: Monad m => Plan s w m () o -> m o

-- | Runs a plan that doesn't need input. It returns a <a>Stream</a> of
--   <a>Tick</a> updates that are emitted every time the execution advances
--   through the <a>Steps</a>.
--   
--   For each <a>Tick</a> update, a monadic measurement of type <tt>t</tt>
--   is taken. Usually the measurement consists in getting the current
--   time.
--   
--   When the execution finishes, a <a>Timeline</a> with the measurements
--   for each <a>Tick</a> is returned, along with the result value.
--   
--   Even if the plan didn't have any steps, the <a>Timeline</a> will
--   contain a measurement taken when the computation finished.
runPlan :: Monad m => m t -> Plan s w m () o -> Stream (Of (Tick s t)) m (Timeline s t, o)

-- | Specify a monadic callback for processing each <a>Tick</a> update.
onTick :: Monad m => (tick -> m ()) -> Stream (Of tick) m r -> m r

-- | Represents some kind of progress through the <a>Steps</a> of a
--   <a>Plan</a> while the plan executes.
--   
--   The ascending list of contexts provides the current position of the
--   execution along the hierarchy of steps.
--   
--   If the plan only has a linear sequence of steps, the list will have
--   only one <a>Context</a>.
data Tick s t
Tick :: (NonEmpty (Context s t)) -> (Progress s t) -> Tick s t

-- | A given step might not have been reached yet. It it has been reached,
--   either it has been skipped at a certain time, or started at a certain
--   time. If if has been started, maybe it has already finished, too.
--   
--   This function can be used in combination with <a>toForest</a> and
--   <a>drawForest</a> to render the state of each step for a <a>Tick</a>.
completedness :: Tick s t -> Tick (Maybe (Either t (t, Maybe t)), s) t

-- | Represents how far we are along a sequence of sibling steps.
--   
--   For the already completed steps, a <a>Timeline</a> of measurements is
--   provided. <a>extract</a> for the <a>Timeline</a> returns the starting
--   measurement of the current step.
data Context s t
Context :: Timeline s t -> s -> Forest s -> Context s t
[completed] :: Context s t -> Timeline s t
[current] :: Context s t -> s
[pending] :: Context s t -> Forest s

-- | The execution of a <a>Plan</a> can make progress by skipping a step,
--   starting a step, or finishing a step.
data Progress s t

-- | Provides the substeps that were skipped.
Skipped :: (Forest s) -> Progress s t

-- | Provides the substeps that will be executed next.
Started :: (Forest s) -> Progress s t

-- | Provides a <a>Timeline</a> of measurements for the completed substeps.
--   <a>extract</a> for the <a>Timeline</a> gives the finishing measurement
--   for the current step.
Finished :: (Timeline s t) -> Progress s t

-- | A <a>Forest</a> of steps tags of type <tt>s</tt> interspersed with
--   measurements of type <tt>t</tt>.
data Timeline s t

-- | Decorate each step tag with either the time the step was skipped, or
--   the time it was started and finished. Useful in combination with
--   <a>toForest</a>.
instants :: Timeline s t -> Timeline (Either t (t, t), s) t

-- | A catamorphism on <a>Timeline</a>s, that "destroys" the
--   <a>Timeline</a> value from the leaves upwards.
foldTimeline :: ([(t, s, Either (Forest s) r)] -> t -> r) -> Timeline s t -> r

-- | Forget that there is a plan, get the underlying Kleisli arrow.
unliftKPlan :: Monad m => Plan s w m i o -> i -> m o

-- | Like <a>runPlan</a>, but for <a>Arrow</a>-like <a>Plan</a>s that take
--   inputs.
runKPlan :: Monad m => m t -> Plan s w m i o -> i -> Stream (Of (Tick s t)) m (Timeline s t, o)

-- | Instances of <a>Sylvan</a> are <a>Forest</a>s with nodes of type
--   <tt>n</tt>, interspersed with annotations of type <tt>a</tt>, and
--   perhaps some other extra information.
--   
--   They must satisfy
--   
--   <pre>
--   bifoldMap f (\_ -&gt; mempty) s == foldMap (foldMap f) (toForest s)
--   </pre>
class (Bitraversable l) => Sylvan l

-- | Forget about the annotations and return the underlying <a>Forest</a>.
toForest :: Sylvan l => l n a -> Forest n

-- | Map over both arguments at the same time.
--   
--   <pre>
--   <a>bimap</a> f g ≡ <a>first</a> f <a>.</a> <a>second</a> g
--   </pre>
bimap :: Bifunctor p => forall a b c d. (a -> b) -> (c -> d) -> p a c -> p b d

-- | Combines the elements of a structure, given ways of mapping them to a
--   common monoid.
--   
--   <pre>
--   <a>bifoldMap</a> f g ≡ <a>bifoldr</a> (<a>mappend</a> . f) (<a>mappend</a> . g) <a>mempty</a>
--   </pre>
bifoldMap :: Bifoldable p => forall m a b. Monoid m => (a -> m) -> (b -> m) -> p a b -> m

-- | Evaluates the relevant functions at each element in the structure,
--   running the action, and builds a new structure with the same shape,
--   using the elements produced from sequencing the actions.
--   
--   <pre>
--   <a>bitraverse</a> f g ≡ <a>bisequenceA</a> . <a>bimap</a> f g
--   </pre>
--   
--   For a version that ignores the results, see <a>bitraverse_</a>.
bitraverse :: Bitraversable t => forall (f :: * -> *) a c b d. Applicative f => (a -> f c) -> (b -> f d) -> t a b -> f (t c d)

-- | <pre>
--   <a>extract</a> . <a>fmap</a> f = f . <a>extract</a>
--   </pre>
extract :: Comonad w => forall a. w a -> a

-- | Lift a monad morphism from <tt>m</tt> to <tt>n</tt> into a monad
--   morphism from <tt>(t m)</tt> to <tt>(t n)</tt>
hoist :: MFunctor t => forall (m :: * -> *) (n :: * -> *) b. Monad m => (forall a. m a -> n a) -> t m b -> t n b

-- | Reduce a stream, performing its actions but ignoring its elements.
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- S.effects $ S.splitAt 2 $ each [1..5]
--   
--   &gt;&gt;&gt; S.print rest
--   3
--   4
--   5
--       'effects' should be understood together with 'copy' and is subject to the rules
--   </pre>
--   
--   <pre>
--   S.effects . S.copy       = id
--   hoist S.effects . S.copy = id
--   </pre>
--   
--   The similar <tt>effects</tt> and <tt>copy</tt> operations in
--   <tt>Data.ByteString.Streaming</tt> obey the same rules.
effects :: Monad m => Stream (Of a) m r -> m r