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

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

Methods

id :: cat a a

(.) :: cat b c -> cat a b -> cat a c

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

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')

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

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 => (b -> c) -> Plan s w m a b -> Plan s w m a c

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

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

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

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

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

(*>) :: 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 :: (Monoid w, Monad m) => m o -> Plan s w m i o

Lift a monadic action to a Plan. The input type remains polymorphic.

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

Lift an IO action to a Plan. The input type remains polymorphic.

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

Lift a Kleisli arrow to a Plan.

kplanIO :: (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" (kplan 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

Bifunctor Steps

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

Bitraversable Steps

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.

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

Sylvan Steps

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

Methods

toForest :: Steps n a -> Forest n

Functor (Steps s)

Methods

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

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

Foldable (Steps s)

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)

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 s, Eq w) => Eq (Steps s w)

Methods

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

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

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

Methods

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

show :: Steps s w -> String

showList :: [Steps s w] -> ShowS

Monoid w => Monoid (Steps s w)

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

Methods

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

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

Ord Mandatoriness

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

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.

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.

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

Bifunctor Tick

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

Bitraversable Tick

Methods

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

Bifoldable Tick

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

Sylvan Tick

Methods

toForest :: Tick n a -> Forest n

Functor (Tick s)

Methods

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

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

Foldable (Tick s)

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)

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 s, Eq t) => Eq (Tick s t)

Methods

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

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

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

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

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)

Methods

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

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

Foldable (Context s)

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)

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)

Methods

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

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

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

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

Bifunctor Progress

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

Bitraversable Progress

Methods

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

Bifoldable Progress

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

Sylvan Progress

Methods

toForest :: Progress n a -> Forest n

Functor (Progress s)

Methods

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

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

Foldable (Progress s)

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)

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 t, Eq s) => Eq (Progress s t)

Methods

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

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

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

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

Bifunctor Timeline

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

Bitraversable Timeline

Methods

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

Bifoldable Timeline

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

Sylvan Timeline

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

Methods

toForest :: Timeline n a -> Forest n

Functor (Timeline s)

Methods

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

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

Foldable (Timeline s)

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)

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.

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 s, Eq t) => Eq (Timeline s t)

Methods

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

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

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

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.

Running arrow plans

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

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

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)

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

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

Methods

toForest :: Progress n a -> Forest n

Sylvan Tick

Methods

toForest :: Tick n a -> Forest n

Sylvan Timeline

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

Methods

toForest :: Timeline n a -> Forest n

Sylvan Steps

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

Methods

toForest :: Steps n a -> Forest n

Sylvan (Clown * * (Compose * * [] Tree))

A Forest is a Sylvan for which no annotations exist.

Methods

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

Re-exports

bimap :: Bifunctor p => forall a b c d. (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

bifoldMap :: Bifoldable p => forall m a b. 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

bitraverse :: Bitraversable t => forall f a c b d. 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 elements produced from sequencing the actions.

bitraverse f g ≡ bisequenceA . bimap f g

For a version that ignores the results, see bitraverse_.

extract :: Comonad w => forall a. 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 => forall m n b. 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)

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.