Control.Plan

This module exports the Plan Applicative.

>>> :{
    let example :: Plan String [Int] IO () ()
        example = 
            step "a" (step "b" (foretell [1] *> plan (threadDelay 1e6)) 
                      *>
                      step "c" (foretell [2] *> plan (threadDelay 1e6))) 
            *>
            step "d" (step "e" (foretell [3] *> plan (threadDelay 1e6)) 
                      *>
                      step "f" (foretell [4] *> plan (threadDelay 1e6)))
    in 
    bifoldMap id (foldMap Prelude.show) (getSteps example)
    :}
"ab1c2de3f4"

Some possible use cases:

• Inspect the steps of an existing Plan from ghci using getSteps, toForest and drawForest, as a form of documentation.
• If your script requires files that must be already present in the file system, use foretell to annotate each Plan action that requires a file, then get the global list of files using getSteps and foldMap, and check that they all exist before running the Plan with runPlan.
• Get progress updates for your script by declaring (possibly nested) steps with step, running the Plan with runPlan, and providing a notification callback with onTick, probably using completedness,toForest and drawForest to render the updates.
• Run a Plan with runPlan, use instants an toForest on the resulting Timeline to get the durations of each step, then use zipSteps on the same Plan and run it again. Now whenever a step finishes we can know if it took more or less than in the previous execution.

Constructing plans

data Plan s w m i o

A computation that takes inputs of type i and produces outputs of type o working in the underlying monad m. The Applicative instance cares only about the outputs, the Arrow instance cares about both inputs and outputs.

Parts of the computation can be labeled as steps with tags of type s.

Computations can have monoidal resource annotations of type w.

The structure of steps and the monoidal annotations can be inspected before executing the Plan.

Instances

(Semigroup w, Monoid w, Monad m) => Category (Plan s w m :: * -> * -> *)

Defined in Control.Plan.Core

Methods

id :: Plan s w m a a

(.) :: Plan s w m b c -> Plan s w m a b -> Plan s w m a c

(Semigroup w, Monoid w, Monad m) => Arrow (Plan s w m)

Defined in Control.Plan.Core

Methods

arr :: (b -> c) -> Plan s w m b c

first :: Plan s w m b c -> Plan s w m (b, d) (c, d)

second :: Plan s w m b c -> Plan s w m (d, b) (d, c)

(***) :: Plan s w m b c -> Plan s w m b' c' -> Plan s w m (b, b') (c, c')

(&&&) :: Plan s w m b c -> Plan s w m b c' -> Plan s w m b (c, c')

(Semigroup w, Monoid w, Monad m) => Profunctor (Plan s w m)

Defined in Control.Plan.Core

Methods

dimap :: (a -> b) -> (c -> d) -> Plan s w m b c -> Plan s w m a d

lmap :: (a -> b) -> Plan s w m b c -> Plan s w m a c

rmap :: (b -> c) -> Plan s w m a b -> Plan s w m a c

(#.) :: Coercible c b => q b c -> Plan s w m a b -> Plan s w m a c

(.#) :: Coercible b a => Plan s w m b c -> q a b -> Plan s w m a c

Monad m => Functor (Plan s w m i)

Defined in Control.Plan.Core

Methods

fmap :: (a -> b) -> Plan s w m i a -> Plan s w m i b

(<$) :: a -> Plan s w m i b -> Plan s w m i a

(Semigroup w, Monoid w, Monad m) => Applicative (Plan s w m i)

Defined in Control.Plan.Core

Methods

pure :: a -> Plan s w m i a

(<*>) :: Plan s w m i (a -> b) -> Plan s w m i a -> Plan s w m i b

liftA2 :: (a -> b -> c) -> Plan s w m i a -> Plan s w m i b -> Plan s w m i c

(*>) :: Plan s w m i a -> Plan s w m i b -> Plan s w m i b

(<*) :: Plan s w m i a -> Plan s w m i b -> Plan s w m i a

plan :: (Semigroup w, Monoid w, Monad m) => m o -> Plan s w m i o

Lift a monadic action to a Plan. The input type i remains polymorphic, usually it will become ().

plan' :: (Semigroup w, Monoid w, Monad m) => (i -> m o) -> Plan s w m i o

Lift a Kleisli arrow to a Plan.

planIO :: (Semigroup w, Monoid w, MonadIO m) => IO o -> Plan s w m i o

Lift an IO action to a Plan. The input type i remains polymorphic, usually it will become ().

planIO' :: (Semigroup w, Monoid w, MonadIO m) => (i -> IO o) -> Plan s w m i o

Lift a Kleisli arrow working in IO to a Plan.

Declaring steps and annotations

step :: (Monoid w, Monad m) => s -> Plan s w m i o -> Plan s w m i o

Declare a step by wrapping an existing plan (which may contain substeps).

skippable :: (Monoid w, Monad m) => s -> Plan s w m i o -> Plan s w m (Maybe i) ()

Declare an optional step by wrapping an existing arrow plan. The step will only be executed when the input is Just.

This function only makes sense when using the Arrow instance of Plan, because for Applicatives an effect cannot depend on previously obtained values.

>>> :{
    let example :: Plan String () IO () ()
        example = proc () -> do 
            i <- step "reading" (plan (readMaybe @Int <$> getLine)) -< () 
            skippable "writing" (plan' print) -< i
    in  putStr . drawForest . fmap (fmap show) . toForest . mandatoriness . getSteps $ example
    :}
(Mandatory,"reading")

(Skippable,"writing")

foretell :: Monad m => w -> Plan s w m i ()

Declare a monoidal annotation. The annotation can be later inspected without having to run the Plan.

Usually the annotations will represent resources that the Plan is expected to require.

Analyzing plans

getSteps :: Plan s w m i o -> Steps s w

Inspect a plan without executing it.

data Steps s w

A Forest of steps tags of type s interspersed with monoidal annotations of type w.

Instances

Bitraversable Steps

Defined in Control.Plan.Core

Methods

bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> Steps a b -> f (Steps c d)

Bifoldable Steps

bifoldMap allows extracting the steps and the annotations together.

Defined in Control.Plan.Core

Methods

bifold :: Monoid m => Steps m m -> m

bifoldMap :: Monoid m => (a -> m) -> (b -> m) -> Steps a b -> m

bifoldr :: (a -> c -> c) -> (b -> c -> c) -> c -> Steps a b -> c

bifoldl :: (c -> a -> c) -> (c -> b -> c) -> c -> Steps a b -> c

Bifunctor Steps

Defined in Control.Plan.Core

Methods

bimap :: (a -> b) -> (c -> d) -> Steps a c -> Steps b d

first :: (a -> b) -> Steps a c -> Steps b c

second :: (b -> c) -> Steps a b -> Steps a c

Sylvan Steps

toForest forgets about the annotations and returns a Forest of step tags.

Defined in Control.Plan.Core

Methods

toForest :: Steps n a -> Forest n

Functor (Steps s)

Defined in Control.Plan.Core

Methods

fmap :: (a -> b) -> Steps s a -> Steps s b

(<$) :: a -> Steps s b -> Steps s a

Foldable (Steps s)

Defined in Control.Plan.Core

Methods

fold :: Monoid m => Steps s m -> m

foldMap :: Monoid m => (a -> m) -> Steps s a -> m

foldr :: (a -> b -> b) -> b -> Steps s a -> b

foldr' :: (a -> b -> b) -> b -> Steps s a -> b

foldl :: (b -> a -> b) -> b -> Steps s a -> b

foldl' :: (b -> a -> b) -> b -> Steps s a -> b

foldr1 :: (a -> a -> a) -> Steps s a -> a

foldl1 :: (a -> a -> a) -> Steps s a -> a

toList :: Steps s a -> [a]

null :: Steps s a -> Bool

length :: Steps s a -> Int

elem :: Eq a => a -> Steps s a -> Bool

maximum :: Ord a => Steps s a -> a

minimum :: Ord a => Steps s a -> a

sum :: Num a => Steps s a -> a

product :: Num a => Steps s a -> a

Traversable (Steps s)

Defined in Control.Plan.Core

Methods

traverse :: Applicative f => (a -> f b) -> Steps s a -> f (Steps s b)

sequenceA :: Applicative f => Steps s (f a) -> f (Steps s a)

mapM :: Monad m => (a -> m b) -> Steps s a -> m (Steps s b)

sequence :: Monad m => Steps s (m a) -> m (Steps s a)

(Eq w, Eq s) => Eq (Steps s w)

Defined in Control.Plan.Core

Methods

(==) :: Steps s w -> Steps s w -> Bool

(/=) :: Steps s w -> Steps s w -> Bool

(Show w, Show s) => Show (Steps s w)

Defined in Control.Plan.Core

Methods

showsPrec :: Int -> Steps s w -> ShowS

show :: Steps s w -> String

showList :: [Steps s w] -> ShowS

Semigroup w => Semigroup (Steps s w)

Defined in Control.Plan.Core

Methods

(<>) :: Steps s w -> Steps s w -> Steps s w

sconcat :: NonEmpty (Steps s w) -> Steps s w

stimes :: Integral b => b -> Steps s w -> Steps s w

(Semigroup w, Monoid w) => Monoid (Steps s w)

Defined in Control.Plan.Core

Methods

mempty :: Steps s w

mappend :: Steps s w -> Steps s w -> Steps s w

mconcat :: [Steps s w] -> Steps s w

mandatoriness :: Steps s w -> Steps (Mandatoriness, s) w

Decorate each step tag with its mandatoriness. Useful in combination with toForest.

data Mandatoriness

Constructors

Skippable

Mandatory

Instances

Eq Mandatoriness

Defined in Control.Plan.Core

Methods

(==) :: Mandatoriness -> Mandatoriness -> Bool

(/=) :: Mandatoriness -> Mandatoriness -> Bool

Ord Mandatoriness

Defined in Control.Plan.Core

Methods

compare :: Mandatoriness -> Mandatoriness -> Ordering

(<) :: Mandatoriness -> Mandatoriness -> Bool

(<=) :: Mandatoriness -> Mandatoriness -> Bool

(>) :: Mandatoriness -> Mandatoriness -> Bool

(>=) :: Mandatoriness -> Mandatoriness -> Bool

max :: Mandatoriness -> Mandatoriness -> Mandatoriness

min :: Mandatoriness -> Mandatoriness -> Mandatoriness

Show Mandatoriness

Defined in Control.Plan.Core

Methods

showsPrec :: Int -> Mandatoriness -> ShowS

show :: Mandatoriness -> String

showList :: [Mandatoriness] -> ShowS

foldSteps

Arguments

:: ([(w, s, Mandatoriness, r)] -> w -> r)

A function that consumes a list of step tags of type s, surrounded and interleaved with annotations of type w. Each step is also annotated with its mandatoriness and with the result r of consuming its substeps, if there were any.

-> Steps s w

-> r

A catamorphism on Steps, that "destroys" the Steps value from the leaves upwards.

Unlike foldMap or bifoldMap, it allows a more structured analysis of the annotations, by preserving their relationship with the hierarchy of steps.

Adapting plans

Sometimes, we might need to mix Plans for which step tags and annotations are of different types. These functions help with that.

bimapSteps :: (s -> s') -> (w -> w') -> Plan s w m i o -> Plan s' w' m i o

Adapt the Step value inside a Plan without extracting it.

zoomSteps :: Monoid w' => ((w -> Identity w) -> w' -> Identity w') -> Plan s w m i o -> Plan s w' m i o

Use a lens setter to "zoom" the monoidal annotations of a Plan into a wider monoidal context.

zipSteps :: Forest s' -> Plan s w m i o -> Maybe (Plan (s', s) w m i o)

Pair each step tag s inside a Plan with the corresponding element of the Forest.

If the forest doesn't have the same structure as the steps, the function fails with Nothing.

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 Timeline, instants, and toForest.

hoistPlan :: Monad m => (forall x. m x -> n x) -> Plan s w m i o -> Plan s w n i o

Change the underlying monad of a Plan.

Running plans

unliftPlan :: Monad m => Plan s w m () o -> m o

Forget that there is a plan, get the underlying monadic action.

unliftPlan' :: Monad m => Plan s w m i o -> i -> m o

Forget that there is a plan, get the underlying Kleisli arrow.

runPlan

Arguments

:: Monad m

=> m t

Monadic measurement to be taken on each tick.

-> Plan s w m () o

Plan without input.

-> Stream (Of (Tick s t)) m (Timeline s t, o)

Runs a plan that doesn't need input. It returns a Stream of Tick updates that are emitted every time the execution advances through the Steps.

For each Tick update, a monadic measurement of type t is taken. Usually the measurement consists in getting the current time.

When the execution finishes, a Timeline with the measurements for each Tick is returned, along with the result value.

Even if the plan didn't have any steps, the Timeline will contain a measurement taken when the computation finished.

runPlan'

Arguments

:: Monad m

=> m t

Monadic measurement to be taken on each tick.

-> Plan s w m i o

Plan that takes input.

-> i

-> Stream (Of (Tick s t)) m (Timeline s t, o)

Like runPlan, but for Arrow-like Plans that take inputs.

onTick :: Monad m => (tick -> m ()) -> Stream (Of tick) m r -> m r

Specify a monadic callback for processing each Tick update.

data Tick s t

Represents some kind of progress through the Steps of a Plan 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 Context.

Constructors

Tick (NonEmpty (Context s t)) (Progress s t)

Instances

Bitraversable Tick

Defined in Control.Plan.Core

Methods

bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> Tick a b -> f (Tick c d)

Bifoldable Tick

Defined in Control.Plan.Core

Methods

bifold :: Monoid m => Tick m m -> m

bifoldMap :: Monoid m => (a -> m) -> (b -> m) -> Tick a b -> m

bifoldr :: (a -> c -> c) -> (b -> c -> c) -> c -> Tick a b -> c

bifoldl :: (c -> a -> c) -> (c -> b -> c) -> c -> Tick a b -> c

Bifunctor Tick

Defined in Control.Plan.Core

Methods

bimap :: (a -> b) -> (c -> d) -> Tick a c -> Tick b d

first :: (a -> b) -> Tick a c -> Tick b c

second :: (b -> c) -> Tick a b -> Tick a c

Sylvan Tick

Defined in Control.Plan.Core

Methods

toForest :: Tick n a -> Forest n

Functor (Tick s)

Defined in Control.Plan.Core

Methods

fmap :: (a -> b) -> Tick s a -> Tick s b

(<$) :: a -> Tick s b -> Tick s a

Foldable (Tick s)

Defined in Control.Plan.Core

Methods

fold :: Monoid m => Tick s m -> m

foldMap :: Monoid m => (a -> m) -> Tick s a -> m

foldr :: (a -> b -> b) -> b -> Tick s a -> b

foldr' :: (a -> b -> b) -> b -> Tick s a -> b

foldl :: (b -> a -> b) -> b -> Tick s a -> b

foldl' :: (b -> a -> b) -> b -> Tick s a -> b

foldr1 :: (a -> a -> a) -> Tick s a -> a

foldl1 :: (a -> a -> a) -> Tick s a -> a

toList :: Tick s a -> [a]

null :: Tick s a -> Bool

length :: Tick s a -> Int

elem :: Eq a => a -> Tick s a -> Bool

maximum :: Ord a => Tick s a -> a

minimum :: Ord a => Tick s a -> a

sum :: Num a => Tick s a -> a

product :: Num a => Tick s a -> a

Traversable (Tick s)

Defined in Control.Plan.Core

Methods

traverse :: Applicative f => (a -> f b) -> Tick s a -> f (Tick s b)

sequenceA :: Applicative f => Tick s (f a) -> f (Tick s a)

mapM :: Monad m => (a -> m b) -> Tick s a -> m (Tick s b)

sequence :: Monad m => Tick s (m a) -> m (Tick s a)

(Eq t, Eq s) => Eq (Tick s t)

Defined in Control.Plan.Core

Methods

(==) :: Tick s t -> Tick s t -> Bool

(/=) :: Tick s t -> Tick s t -> Bool

(Show t, Show s) => Show (Tick s t)

Defined in Control.Plan.Core

Methods

showsPrec :: Int -> Tick s t -> ShowS

show :: Tick s t -> String

showList :: [Tick s t] -> ShowS

completedness :: Tick s t -> Tick (Maybe (Either t (t, Maybe t)), 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 toForest and drawForest to render the state of each step for a Tick.

data Context s t

Represents how far we are along a sequence of sibling steps.

For the already completed steps, a Timeline of measurements is provided. extract for the Timeline returns the starting measurement of the current step.

Constructors

Context

Fields

• completed :: Timeline s t
• current :: s
• pending :: Forest s

Instances

Bifunctor Context

Defined in Control.Plan.Core

Methods

bimap :: (a -> b) -> (c -> d) -> Context a c -> Context b d

first :: (a -> b) -> Context a c -> Context b c

second :: (b -> c) -> Context a b -> Context a c

Functor (Context s)

Defined in Control.Plan.Core

Methods

fmap :: (a -> b) -> Context s a -> Context s b

(<$) :: a -> Context s b -> Context s a

Foldable (Context s)

Defined in Control.Plan.Core

Methods

fold :: Monoid m => Context s m -> m

foldMap :: Monoid m => (a -> m) -> Context s a -> m

foldr :: (a -> b -> b) -> b -> Context s a -> b

foldr' :: (a -> b -> b) -> b -> Context s a -> b

foldl :: (b -> a -> b) -> b -> Context s a -> b

foldl' :: (b -> a -> b) -> b -> Context s a -> b

foldr1 :: (a -> a -> a) -> Context s a -> a

foldl1 :: (a -> a -> a) -> Context s a -> a

toList :: Context s a -> [a]

null :: Context s a -> Bool

length :: Context s a -> Int

elem :: Eq a => a -> Context s a -> Bool

maximum :: Ord a => Context s a -> a

minimum :: Ord a => Context s a -> a

sum :: Num a => Context s a -> a

product :: Num a => Context s a -> a

Traversable (Context s)

Defined in Control.Plan.Core

Methods

traverse :: Applicative f => (a -> f b) -> Context s a -> f (Context s b)

sequenceA :: Applicative f => Context s (f a) -> f (Context s a)

mapM :: Monad m => (a -> m b) -> Context s a -> m (Context s b)

sequence :: Monad m => Context s (m a) -> m (Context s a)

(Eq t, Eq s) => Eq (Context s t)

Defined in Control.Plan.Core

Methods

(==) :: Context s t -> Context s t -> Bool

(/=) :: Context s t -> Context s t -> Bool

(Show t, Show s) => Show (Context s t)

Defined in Control.Plan.Core

Methods

showsPrec :: Int -> Context s t -> ShowS

show :: Context s t -> String

showList :: [Context s t] -> ShowS

data Progress s t

The execution of a Plan can make progress by skipping a step, starting a step, or finishing a step.

Constructors

Skipped (Forest s)

Provides the substeps that were skipped.

Started (Forest s)

Provides the substeps that will be executed next.

Finished (Timeline s t)

Provides a Timeline of measurements for the completed substeps. extract for the Timeline gives the finishing measurement for the current step.

Instances

Bitraversable Progress

Defined in Control.Plan.Core

Methods

bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> Progress a b -> f (Progress c d)

Bifoldable Progress

Defined in Control.Plan.Core

Methods

bifold :: Monoid m => Progress m m -> m

bifoldMap :: Monoid m => (a -> m) -> (b -> m) -> Progress a b -> m

bifoldr :: (a -> c -> c) -> (b -> c -> c) -> c -> Progress a b -> c

bifoldl :: (c -> a -> c) -> (c -> b -> c) -> c -> Progress a b -> c

Bifunctor Progress

Defined in Control.Plan.Core

Methods

bimap :: (a -> b) -> (c -> d) -> Progress a c -> Progress b d

first :: (a -> b) -> Progress a c -> Progress b c

second :: (b -> c) -> Progress a b -> Progress a c

Sylvan Progress

Defined in Control.Plan.Core

Methods

toForest :: Progress n a -> Forest n

Functor (Progress s)

Defined in Control.Plan.Core

Methods

fmap :: (a -> b) -> Progress s a -> Progress s b

(<$) :: a -> Progress s b -> Progress s a

Foldable (Progress s)

Defined in Control.Plan.Core

Methods

fold :: Monoid m => Progress s m -> m

foldMap :: Monoid m => (a -> m) -> Progress s a -> m

foldr :: (a -> b -> b) -> b -> Progress s a -> b

foldr' :: (a -> b -> b) -> b -> Progress s a -> b

foldl :: (b -> a -> b) -> b -> Progress s a -> b

foldl' :: (b -> a -> b) -> b -> Progress s a -> b

foldr1 :: (a -> a -> a) -> Progress s a -> a

foldl1 :: (a -> a -> a) -> Progress s a -> a

toList :: Progress s a -> [a]

null :: Progress s a -> Bool

length :: Progress s a -> Int

elem :: Eq a => a -> Progress s a -> Bool

maximum :: Ord a => Progress s a -> a

minimum :: Ord a => Progress s a -> a

sum :: Num a => Progress s a -> a

product :: Num a => Progress s a -> a

Traversable (Progress s)

Defined in Control.Plan.Core

Methods

traverse :: Applicative f => (a -> f b) -> Progress s a -> f (Progress s b)

sequenceA :: Applicative f => Progress s (f a) -> f (Progress s a)

mapM :: Monad m => (a -> m b) -> Progress s a -> m (Progress s b)

sequence :: Monad m => Progress s (m a) -> m (Progress s a)

(Eq s, Eq t) => Eq (Progress s t)

Defined in Control.Plan.Core

Methods

(==) :: Progress s t -> Progress s t -> Bool

(/=) :: Progress s t -> Progress s t -> Bool

(Show s, Show t) => Show (Progress s t)

Defined in Control.Plan.Core

Methods

showsPrec :: Int -> Progress s t -> ShowS

show :: Progress s t -> String

showList :: [Progress s t] -> ShowS

data Timeline s t

A Forest of steps tags of type s interspersed with measurements of type t.

Instances

Bitraversable Timeline

Defined in Control.Plan.Core

Methods

bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> Timeline a b -> f (Timeline c d)

Bifoldable Timeline

Defined in Control.Plan.Core

Methods

bifold :: Monoid m => Timeline m m -> m

bifoldMap :: Monoid m => (a -> m) -> (b -> m) -> Timeline a b -> m

bifoldr :: (a -> c -> c) -> (b -> c -> c) -> c -> Timeline a b -> c

bifoldl :: (c -> a -> c) -> (c -> b -> c) -> c -> Timeline a b -> c

Bifunctor Timeline

Defined in Control.Plan.Core

Methods

bimap :: (a -> b) -> (c -> d) -> Timeline a c -> Timeline b d

first :: (a -> b) -> Timeline a c -> Timeline b c

second :: (b -> c) -> Timeline a b -> Timeline a c

Sylvan Timeline

toForest forgets about the measurements and returns a Forest of step tags.

Defined in Control.Plan.Core

Methods

toForest :: Timeline n a -> Forest n

Functor (Timeline s)

Defined in Control.Plan.Core

Methods

fmap :: (a -> b) -> Timeline s a -> Timeline s b

(<$) :: a -> Timeline s b -> Timeline s a

Foldable (Timeline s)

Defined in Control.Plan.Core

Methods

fold :: Monoid m => Timeline s m -> m

foldMap :: Monoid m => (a -> m) -> Timeline s a -> m

foldr :: (a -> b -> b) -> b -> Timeline s a -> b

foldr' :: (a -> b -> b) -> b -> Timeline s a -> b

foldl :: (b -> a -> b) -> b -> Timeline s a -> b

foldl' :: (b -> a -> b) -> b -> Timeline s a -> b

foldr1 :: (a -> a -> a) -> Timeline s a -> a

foldl1 :: (a -> a -> a) -> Timeline s a -> a

toList :: Timeline s a -> [a]

null :: Timeline s a -> Bool

length :: Timeline s a -> Int

elem :: Eq a => a -> Timeline s a -> Bool

maximum :: Ord a => Timeline s a -> a

minimum :: Ord a => Timeline s a -> a

sum :: Num a => Timeline s a -> a

product :: Num a => Timeline s a -> a

Traversable (Timeline s)

Defined in Control.Plan.Core

Methods

traverse :: Applicative f => (a -> f b) -> Timeline s a -> f (Timeline s b)

sequenceA :: Applicative f => Timeline s (f a) -> f (Timeline s a)

mapM :: Monad m => (a -> m b) -> Timeline s a -> m (Timeline s b)

sequence :: Monad m => Timeline s (m a) -> m (Timeline s a)

Comonad (Timeline s)

Timelines always have at least one measurement. extract gives the final measurement.

Defined in Control.Plan.Core

Methods

extract :: Timeline s a -> a

duplicate :: Timeline s a -> Timeline s (Timeline s a)

extend :: (Timeline s a -> b) -> Timeline s a -> Timeline s b

(Eq t, Eq s) => Eq (Timeline s t)

Defined in Control.Plan.Core

Methods

(==) :: Timeline s t -> Timeline s t -> Bool

(/=) :: Timeline s t -> Timeline s t -> Bool

(Show t, Show s) => Show (Timeline s t)

Defined in Control.Plan.Core

Methods

showsPrec :: Int -> Timeline s t -> ShowS

show :: Timeline s t -> String

showList :: [Timeline s t] -> ShowS

instants :: Timeline s t -> Timeline (Either t (t, t), 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 toForest.

foldTimeline

Arguments

:: ([(t, s, Either (Forest s) r)] -> t -> r)

A function that consumes a list of step tags of type s, surrounded and interleaved with measurements of type t. Each step is also annotated with either its substeps, if it the step was skipped, or the results of consuming the substeps, if it was executed.

-> Timeline s t

-> r

A catamorphism on Timelines, that "destroys" the Timeline value from the leaves upwards.

The Sylvan typeclass

class Bitraversable l => Sylvan l where

Instances of Sylvan are Forests with nodes of type n, interspersed with annotations of type a, and perhaps some other extra information.

They must satisfy

bifoldMap f (\_ -> mempty) s == foldMap (foldMap f) (toForest s)

Minimal complete definition

toForest

Methods

toForest :: l n a -> Forest n

Forget about the annotations and return the underlying Forest.

Instances

Sylvan Progress

Defined in Control.Plan.Core

Methods

toForest :: Progress n a -> Forest n

Sylvan Tick

Defined in Control.Plan.Core

Methods

toForest :: Tick n a -> Forest n

Sylvan Timeline

toForest forgets about the measurements and returns a Forest of step tags.

Defined in Control.Plan.Core

Methods

toForest :: Timeline n a -> Forest n

Sylvan Steps

toForest forgets about the annotations and returns a Forest of step tags.

Defined in Control.Plan.Core

Methods

toForest :: Steps n a -> Forest n

Sylvan (Clown (Compose [] Tree) :: * -> * -> *)

A Forest is a Sylvan for which no annotations exist.

Defined in Control.Plan.Core

Methods

toForest :: Clown (Compose [] Tree) n a -> Forest n

Re-exports

bimap :: Bifunctor p => (a -> b) -> (c -> d) -> p a c -> p b d

Map over both arguments at the same time.

bimap f g ≡ first f . second g

Examples

>>> bimap toUpper (+1) ('j', 3)
('J',4)

>>> bimap toUpper (+1) (Left 'j')
Left 'J'

>>> bimap toUpper (+1) (Right 3)
Right 4

bifoldMap :: (Bifoldable p, Monoid m) => (a -> m) -> (b -> m) -> p a b -> m

Combines the elements of a structure, given ways of mapping them to a common monoid.

bifoldMap f g
     ≡ bifoldr (mappend . f) (mappend . g) mempty

Since: base-4.10.0.0

bitraverse :: (Bitraversable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f (t c d)

Evaluates the relevant functions at each element in the structure, running the action, and builds a new structure with the same shape, using the results produced from sequencing the actions.

bitraverse f g ≡ bisequenceA . bimap f g

For a version that ignores the results, see bitraverse_.

Since: base-4.10.0.0

extract :: Comonad w => w a -> a

extract . fmap f = f . extract

Besides its usefulness with Timeline, extract lets you get the head of a NonEmpty or the second element of a tuple.

hoist :: (MFunctor t, Monad m) => (forall a. m a -> n a) -> t m b -> t n b

Lift a monad morphism from m to n into a monad morphism from (t m) to (t n)

The first argument to hoist must be a monad morphism, even though the type system does not enforce this

effects :: Monad m => Stream (Of a) m r -> m r

Reduce a stream, performing its actions but ignoring its elements.

>>> rest <- S.effects $ S.splitAt 2 $ each [1..5]
>>> S.print rest
3
4
5

effects should be understood together with copy and is subject to the rules

S.effects . S.copy       = id
hoist S.effects . S.copy = id

The similar effects and copy operations in Data.ByteString.Streaming obey the same rules.

effects lets you ignore all the update notifications while running a plan, when you are only interested in the final Timeline and the result.

Deprecated functions

kplan :: (Semigroup w, Monoid w, Monad m) => (i -> m o) -> Plan s w m i o

Deprecated: Use plan' instead.

kplanIO :: (Semigroup w, Monoid w, MonadIO m) => (i -> IO o) -> Plan s w m i o

Deprecated: Use planIO' instead.

unliftKPlan :: Monad m => Plan s w m i o -> i -> m o

Deprecated: Use unliftPlan' instead.

runKPlan

Arguments

:: Monad m

=> m t

Monadic measurement to be taken on each tick.

-> Plan s w m i o

Plan that takes input.

-> i

-> Stream (Of (Tick s t)) m (Timeline s t, o)

Deprecated: Use runPlan' instead.