Data.MSF.Util

(source)

Various utility combinators.

A note on arrow operators: Arrow operators in this module are
of the form `i>o`, where `i` is either `>`, `^`, `!`, or `?`.
and `o` is either `>`, `^`, `!`, or `-`. Each of these symbols
describe a different type of arrow-like function at the
corresponding end of the operator:

The following table lists the meaning of symbols

| Symbol      | Meaning                  | Example                    |
|-------------|--------------------------|----------------------------|
| `>`         | An MSF                   | arr (*2) >>> arrM printLn  |
| `^`         | a pure function          | (*2) ^>> printLn           |
| `!`         | an effectful computation | arr (*2) >>! printLn       |

In addition, symbol `?` corresponds to an event stream input, and
symbol `-` describes fanning out to a list of sinks:

```idris example
when (> 10) ?>- [ arrM printLn, put ]
```

Definitions

(>>^) : MSF m i o -> (o -> o2) -> MSF m i o2

  Sequencing of an MSF and a pure function

Visibility: export
Fixity Declaration: infixr operator, level 1

(^>>) : (i -> i2) -> MSF m i2 o -> MSF m i o

  Sequencing of a pure function and an MSF

Visibility: export
Fixity Declaration: infixr operator, level 1

(>>!) : MSF m i o -> (o -> m o2) -> MSF m i o2

  Sequencing of an MSF and an effectful computation

Visibility: export
Fixity Declaration: infixr operator, level 1

(!>>) : (i -> m i2) -> MSF m i2 o -> MSF m i o

  Sequencing of an effectful computation and an MSF

Visibility: export
Fixity Declaration: infixr operator, level 1

fan_ : FanList m i os -> MSF m i ()

  Like `fan` but discards the results.
  This is mainly useful for broadcasting to data sinks
  (streaming functions that do not produce any interesting
  output).
  
  TODO: Should we require a proof here that `os` is a list
        of `Unit`?

Visibility: export

(>>-) : MSF m i x -> FanList m x os -> MSF m i ()

  Broadcasting an MSF to a list of sinks

Visibility: export
Fixity Declaration: infixr operator, level 1

(^>-) : (i -> x) -> FanList m x os -> MSF m i ()

  Broadcasting a pure function to a list of sinks

Visibility: export
Fixity Declaration: infixr operator, level 1

(!>-) : (i -> m x) -> FanList m x os -> MSF m i ()

  Broadcasting an effectful computation to a list of sinks

Visibility: export
Fixity Declaration: infixr operator, level 1

firstArg : MSF m (HList [x, i]) o -> x -> MSF m i o

  Extract the first argument from an MSF taking a pair
  of input values.

Visibility: export

secondArg : MSF m (HList [i, x]) o -> x -> MSF m i o

  Extract the second argument from an MSF taking a pair
  of input values.

Visibility: export

hd : MSF m (HList (i :: t)) i

  Extract the first value of an n-ary product

Visibility: export

tl : MSF m (HList (i :: t)) (HList t)

  Extract the tail of an n-ary product

Visibility: export

snd : MSF m (HList (i :: (i2 :: t))) i2

  Extract the second value of an n-ary product

Visibility: export

swap : MSF m (HList [a, b]) (HList [b, a])

  Swaps a pair of input values

Visibility: export

either : MSF m (Either i1 i2) (HSum [i1, i2])

  Convert an `Either` input to a binary sum, which
  can then be sequenced with a call to `choice` or `collect`.

Visibility: export

ifLeft : Monoid o => MSF m i o -> MSF m (Either i a) o

  Run the given MSF only if the input is a `Left`.

Visibility: export

ifRight : Monoid o => MSF m i o -> MSF m (Either a i) o

  Run the given MSF only if the input is a `Right`.

Visibility: export

maybe : MSF m (Maybe i) (HSum [i, ()])

  Convert an `Maybe` input to a binary sum, which
  can then be sequenced with a call to `choice` or `collect`.

Visibility: export

ifJust : Monoid o => MSF m i o -> MSF m (Maybe i) o

  Run the given MSF only if the input is a `Just`.

Visibility: export

ifNothing : Monoid o => MSF m () o -> MSF m (Maybe i) o

  Run the given MSF only if the input is a `Nothing`.

Visibility: export

bool : (i -> Bool) -> MSF m i (HSum [i, i])

  Convert an input to a binary sum, depending on whether
  the given predicate returns `True` or `False`. The result
  can then be sequenced with a call to `choice` or `collect`.

Visibility: export

ifTrue : Monoid o => (i -> Bool) -> MSF m i o -> MSF m i o

  Run the given MSF only if the predicate holds for the input.

Visibility: export

ifFalse : Monoid o => (i -> Bool) -> MSF m i o -> MSF m i o

  Run the given MSF only if the predicate does not hold for the input.

Visibility: export

ifIs : Eq i => Monoid o => i -> MSF m i o -> MSF m i o

  Run the given MSF only if the input equlas the given value

Visibility: export

ifIsNot : Eq i => Monoid o => i -> MSF m i o -> MSF m i o

  Run the given MSF only if the input does not equal the given value

Visibility: export

feedback_ : s -> MSF m (HList [s, i]) s -> MSF m i ()

  Uses the given value as a seed for feeding back output
  of the MSF back to its input.

Visibility: export

iPre : o -> MSF m o o

  Delay a stream by one sample.

Visibility: export

accumulateWith : (i -> o -> o) -> o -> MSF m i o

  Applies a function to the input and an accumulator,
  outputting the updated accumulator.

Visibility: export

count : Num n => MSF m i n

  Counts the number of scans of the signal function.

Visibility: export

appendFrom : Semigroup v => v -> MSF m v v

  Accumulate the inputs, starting from an initial value.

Visibility: export

append : Monoid n => MSF m n n

  Accumulate the inputs, starting from `neutral`

Visibility: export

mealy : (i -> s -> HList [s, o]) -> s -> MSF m i o

  Applies a transfer function to the input and an accumulator,
  returning the updated accumulator and output.

Visibility: export

unfold : (s -> HList [s, o]) -> s -> MSF m i o

  Unfolds a function over an initial state
  value.

Visibility: export

repeatedly : (o -> o) -> o -> MSF m i o

  Generates output using a step-wise generation function and an initial
  value. Version of 'unfold' in which the output and the new accumulator
  are the same.

Visibility: export

cycle : (vs : List o) -> {auto 0 _ : NonEmpty vs} -> MSF m i o

  Cycles through the given non-empty list of values.

Visibility: export

observeWith : MSF m i () -> MSF m i i

  Observe input values through the given sink.

Visibility: export

withEffect : (i -> m ()) -> MSF m i i

  Run the given effectful computation on each input.

Visibility: export

runEffect : m () -> MSF m i i

  Run the given monadic action on each input.

Visibility: export

never : MSF m i (Event o)

  The empty event stream that never fires an event

Visibility: export

hold : o -> MSF m (Event o) o

  Convert an event stream to a streaming function
  holding the value of the last event fired starting
  from the given initial value.

Visibility: export

ntimes : Nat -> o -> MSF m i (Event o)

  Fire the given event `n` times.

Visibility: export

once : o -> MSF m i (Event o)

  Fire the given event exactly once on the first
  evaluation step.

Visibility: export

when : (i -> Bool) -> MSF m i (Event i)

  Fire an event whenever the given predicate holds.

Visibility: export

when_ : (i -> Bool) -> MSF m i (Event ())

  Like `when` but discard the input.

Visibility: export

is : Eq i => i -> MSF m i (Event i)

  Fire an event whenever the input equals the given value.

Visibility: export

isNot : Eq i => i -> MSF m i (Event i)

  Fire an event whenever the input does not equal the given value.

Visibility: export

whenLeft : MSF m (Either a b) (Event a)

  Fire an event if the input is a `Left`.

Visibility: export

whenRight : MSF m (Either a b) (Event b)

  Fire an event if the input is a `Right`.

Visibility: export

whenJust : MSF m (Maybe a) (Event a)

  Fire an event if the input is a `Just`.

Visibility: export

whenNothing : MSF m (Maybe a) (Event ())

  Fire an event if the input is a `Nothing`.

Visibility: export

event : MSF m (Event i) (HSum [i, ()])

  Convert an `Event` input to a binary sum, which
  can then be sequenced with a call to `choice` or `collect`.

Visibility: export

ifEvent : Monoid o => MSF m i o -> MSF m (Event i) o

  Run the given MSF only if the input fired an event.

Visibility: export

(?>-) : MSF m i (Event x) -> FanList m x os -> MSF m i ()

  Broadcast an event to a list of sinks.

Visibility: export
Fixity Declaration: infixr operator, level 1

(?>>) : Monoid o => MSF m i (Event x) -> MSF m x o -> MSF m i o

  Run the given MSF if the input stream fires and event.

Visibility: export
Fixity Declaration: infixr operator, level 1

ifNoEvent : Monoid o => MSF m () o -> MSF m (Event i) o

  Run the given MSF only if the input fired no event.

Visibility: export

onChange : Eq i => MSF m i (Event i)

  Fire an event whenever the input value changed.
  Always fires on first input.

Visibility: export

onEvent : MSF m (HList [a, Event e]) (Event a)

  Fires the first input as an event whenever the
  second input fires.

Visibility: export

onEventWith : (a -> e -> b) -> MSF m (HList [a, Event e]) (Event b)

  Combines the first input with the event fired by the
  second input.

Visibility: export

leftOnEvent : MSF m (HList [Either a b, Event e]) (Event a)

  Combines an input event stream with a stream function
  holding an `Either` trying to extract a `Left` whenever
  an event is fired.

Visibility: export

rightOnEvent : MSF m (HList [Either a b, Event e]) (Event b)

  Combines an input event stream with a stream function
  holding an `Either` trying to extract a `Right` whenever
  an event is fired.

Visibility: export

justOnEvent : MSF m (HList [Maybe a, Event e]) (Event a)

  Combines an input event stream with a stream function
  holding a `Maybe` trying to extract the value from a `Just` whenever
  an event is fired.

Visibility: export

unionWith : (o -> o -> o) -> MSF m i (Event o) -> MSF m i (Event o) -> MSF m i (Event o)

  Fires an event whenever one of the two given
  event streams fire. Uses the given function
  to combine simultaneously occuring events.

Visibility: export

unionL : MSF m i (Event o) -> MSF m i (Event o) -> MSF m i (Event o)

  Left-biased union of event streams.
  In case of simultaneously occuring events, the
  event from the first event stream is fired.
  
  This is the same behavior as `(<|>)` from
  the MSFs `Alternative` implementation

Visibility: export

unionR : MSF m i (Event o) -> MSF m i (Event o) -> MSF m i (Event o)

  Right-biased union of event streams.
  In case of simultaneously occuring events, the
  event from the second event stream is fired.

Visibility: export

union : Semigroup o => MSF m i (Event o) -> MSF m i (Event o) -> MSF m i (Event o)

  Union of event streams using a `Semigroup` to
  merge values in case of simultaneously occuring events.
  
  This is an alias for `(<+>)`.

Visibility: export

(<|>) : Alternative f => MSF m i (f o) -> MSF m i (f o) -> MSF m i (f o)

Visibility: export
Fixity Declaration: infixr operator, level 2

filter : (o -> Bool) -> MSF m (Event o) (Event o)

  Filters an event stream, letting pass only values,
  fow which the given predicate holds.

Visibility: export

mapMaybe : (i -> Maybe o) -> MSF m (Event i) (Event o)

  Filters an event stream, letting pass only values,
  fow which the given function returns a `Just`.

Visibility: export

proj : (0 t : k) -> Elem t ks => MSF m (Any f ks) (Event (f t))

  Sum projection: Fires an event if a value of the given type can
  be extracted from the input sum.

Visibility: export

observeEvent : MSF m i () -> MSF m (Event i) (Event i)

  Observe an event throught the given sink.

Visibility: export

accumulateWithE : (i -> o -> o) -> o -> MSF m (Event i) (Event o)

  Applies a function to the input and an accumulator,
  outputting the updated accumulator whenever an
  event is fire.

Visibility: export

countE : MSF m (Event i) (Event Nat)

  Count the number of occurences of an event

Visibility: export

0 Fun : List Type -> Type -> Type

  N-ary function type calculated from a list of n types.

Visibility: public export

uncurryNP : Fun is o -> HList is -> o

  Converts an n-ary function to one taking an n-ary
  product as input.

Visibility: export

np : Fun is o -> MSF m (HList is) o

  Alias for `arr . uncurryNP`.

Visibility: export