Copyright  (c) 2011 Brent Yorgey 

License  BSDstyle (see LICENSE) 
Maintainer  byorgey@cis.upenn.edu 
Safe Haskell  None 
Language  Haskell2010 
Inspired by the work of Kevin Matlage and Andy Gill (Every
Animation Should Have a Beginning, a Middle, and an End, Trends
in Functional Programming,
2010. http://kufpg.github.io/files/Matlage10BeginningMiddleEnd.pdf), this module defines a
simple abstraction for working with timevarying values. A value
of type Active a
is either a constant value of type a
, or a
timevarying value of type a
(i.e. a function from time to
a
) with specific start and end times. Since active values
have start and end times, they can be aligned, sequenced,
stretched, or reversed.
In a sense, this is sort of like a strippeddown version of functional reactive programming (FRP), without the reactivity.
The original motivating use for this library is to support making animations with the diagrams framework (http://projects.haskell.org/diagrams), but the hope is that it may find more general utility.
There are two basic ways to create an Active
value. The first is
to use mkActive
to create one directly, by specifying a start and
end time and a function of time. More indirectly, one can use the
Applicative
instance together with the unit interval ui
, which
takes on values from the unit interval from time 0 to time 1, or
interval
, which creates an active over an arbitrary interval.
For example, to create a value of type Active Double
which
represents one period of a sine wave starting at time 0 and ending
at time 1, we could write
mkActive 0 1 (\t > sin (fromTime t * tau))
or
(sin . (*tau)) <$> ui
pure
can also be used to create Active
values which are
constant and have no start or end time. For example,
mod <$> (floor <$> interval 0 100) <*> pure 7
cycles repeatedly through the numbers 06.
Note that the "idiom bracket" notation supported by the SHE
preprocessor (http://personal.cis.strath.ac.uk/~conor/pub/she/,
http://hackage.haskell.org/package/she) can make for somewhat
more readable Applicative
code. For example, the above example
can be rewritten using SHE as
{# OPTIONS_GHC F pgmF she #} ... ( mod ( floor (interval 0 100) ) ~7 )
There are many functions for transforming and composing active values; see the documentation below for more details.
With careful handling, this module should be suitable to generating
deep embeddings if Active
values.
Synopsis
 data Time n
 toTime :: n > Time n
 fromTime :: Time n > n
 data Duration n
 toDuration :: n > Duration n
 fromDuration :: Duration n > n
 data Era n
 mkEra :: Time n > Time n > Era n
 start :: Era n > Time n
 end :: Era n > Time n
 duration :: Num n => Era n > Duration n
 data Dynamic a = Dynamic {}
 mkDynamic :: Time Rational > Time Rational > (Time Rational > a) > Dynamic a
 onDynamic :: (Time Rational > Time Rational > (Time Rational > a) > b) > Dynamic a > b
 shiftDynamic :: Duration Rational > Dynamic a > Dynamic a
 data Active a
 mkActive :: Time Rational > Time Rational > (Time Rational > a) > Active a
 fromDynamic :: Dynamic a > Active a
 isConstant :: Active a > Bool
 isDynamic :: Active a > Bool
 onActive :: (a > b) > (Dynamic a > b) > Active a > b
 modActive :: (a > b) > (Dynamic a > Dynamic b) > Active a > Active b
 runActive :: Active a > Time Rational > a
 activeEra :: Active a > Maybe (Era Rational)
 setEra :: Era Rational > Active a > Active a
 atTime :: Time Rational > Active a > Active a
 activeStart :: Active a > a
 activeEnd :: Active a > a
 ui :: Fractional a => Active a
 interval :: Fractional a => Time Rational > Time Rational > Active a
 stretch :: Rational > Active a > Active a
 stretchTo :: Duration Rational > Active a > Active a
 during :: Active a > Active a > Active a
 shift :: Duration Rational > Active a > Active a
 backwards :: Active a > Active a
 snapshot :: Time Rational > Active a > Active a
 clamp :: Active a > Active a
 clampBefore :: Active a > Active a
 clampAfter :: Active a > Active a
 trim :: Monoid a => Active a > Active a
 trimBefore :: Monoid a => Active a > Active a
 trimAfter :: Monoid a => Active a > Active a
 after :: Active a > Active a > Active a
 (>>) :: Semigroup a => Active a > Active a > Active a
 (>>) :: Active a > Active a > Active a
 movie :: [Active a] > Active a
 discrete :: [a] > Active a
 simulate :: Rational > Active a > [a]
Representing time
Time and duration
An abstract type for representing points in time. Note that
literal numeric values may be used as Time
s, thanks to the the
Num
and Fractional
instances.
Instances
Functor Time #  
Affine Time #  
Enum n => Enum (Time n) #  
Defined in Data.Active  
Eq n => Eq (Time n) #  
Fractional n => Fractional (Time n) #  
Num n => Num (Time n) #  
Ord n => Ord (Time n) #  
Read n => Read (Time n) #  
Real n => Real (Time n) #  
Defined in Data.Active toRational :: Time n > Rational #  
RealFrac n => RealFrac (Time n) #  
Show n => Show (Time n) #  
Wrapped (Time n) #  
Time n1 ~ t => Rewrapped (Time n2) t #  
Defined in Data.Active  
type Diff Time #  
Defined in Data.Active  
type Unwrapped (Time n) #  
Defined in Data.Active 
An abstract type representing elapsed time between two points
in time. Note that durations can be negative. Literal numeric
values may be used as Duration
s thanks to the Num
and
Fractional
instances.
Instances
toDuration :: n > Duration n #
A convenient wrapper function to convert a numeric value into a duration.
fromDuration :: Duration n > n #
A convenient unwrapper function to turn a duration into a numeric value.
Eras
An Era
is a concrete span of time, that is, a pair of times
representing the start and end of the era. Era
s form a
semigroup: the combination of two Era
s is the smallest Era
which contains both. They do not form a Monoid
, since there is
no Era
which acts as the identity with respect to this
combining operation.
Era
is abstract. To construct Era
values, use mkEra
; to
deconstruct, use start
and end
.
Dynamic values
A Dynamic a
can be thought of as an a
value that changes over
the course of a particular Era
. It's envisioned that Dynamic
will be mostly an internal implementation detail and that
Active
will be most commonly used. But you never know what
uses people might find for things.
Instances
Functor Dynamic #  
Apply Dynamic # 

Semigroup a => Semigroup (Dynamic a) # 

mkDynamic :: Time Rational > Time Rational > (Time Rational > a) > Dynamic a #
Create a Dynamic
from a start time, an end time, and a
timevarying value.
onDynamic :: (Time Rational > Time Rational > (Time Rational > a) > b) > Dynamic a > b #
Fold for Dynamic
.
shiftDynamic :: Duration Rational > Dynamic a > Dynamic a #
Shift a Dynamic
value by a certain duration.
Active values
For working with timevarying values, it is convenient to have an
Applicative
instance: <*>
lets us apply timevarying
functions to timevarying values; pure
allows treating constants
as timevarying values which do not vary. However, as explained in
its documentation, Dynamic
cannot be made an instance of
Applicative
since there is no way to implement pure
. The
problem is that all Dynamic
values must have a finite start and
end time. The solution is to adjoin a special constructor for
pure/constant values with no start or end time, giving us Active
.
There are two types of Active
values:
 An
Active
can simply be aDynamic
, that is, a timevarying value with start and end times.  An
Active
value can also be a constant: a single value, constant across time, with no start and end times.
The addition of constant values enable Monoid
and Applicative
instances for Active
.
Instances
Functor Active #  
Applicative Active #  
Apply Active #  
Semigroup a => Semigroup (Active a) #  Active values over a type with a 
(Monoid a, Semigroup a) => Monoid (Active a) #  
Wrapped (Active a) #  
Active a1 ~ t => Rewrapped (Active a2) t #  
Defined in Data.Active  
type Unwrapped (Active a) #  
Defined in Data.Active 
mkActive :: Time Rational > Time Rational > (Time Rational > a) > Active a #
Create a dynamic Active
from a start time, an end time, and a
timevarying value.
isConstant :: Active a > Bool #
Test whether an Active
value is constant.
modActive :: (a > b) > (Dynamic a > Dynamic b) > Active a > Active b #
Modify an Active
value using a case analysis to see whether it
is constant or dynamic.
atTime :: Time Rational > Active a > Active a #
atTime t a
is an active value with the same behavior as a
,
shifted so that it starts at time t
. If a
is constant it is
returned unchanged.
activeStart :: Active a > a #
Get the value of an Active a
at the beginning of its era.
Combinators
Special active values
ui :: Fractional a => Active a #
ui
represents the unit interval, which takes on the value t
at time t
, and has as its era [0,1]
. It is equivalent to
, and can be visualized as follows:interval
0 1
On the xaxis is time, and the value that ui
takes on is on the
yaxis. The shaded portion represents the era. Note that the
value of ui
(as with any active) is still defined outside its
era, and this can make a difference when it is combined with
other active values with different eras. Applying a function
with fmap
affects all values, both inside and outside the era.
To manipulate values outside the era specifically, see clamp
and trim
.
To alter the values that ui
takes on without altering its
era, use its Functor
and Applicative
instances. For example,
(*2) <$> ui
varies from 0
to 2
over the era [0,1]
. To
alter the era, you can use stretch
or shift
.
interval :: Fractional a => Time Rational > Time Rational > Active a #
interval a b
is an active value starting at time a
, ending at
time b
, and taking the value t
at time t
.
Transforming active values
stretch :: Rational > Active a > Active a #
stretch s act
"stretches" the active act
so that it takes
s
times as long (retaining the same start time).
shift :: Duration Rational > Active a > Active a #
shift d act
shifts the start time of act
by duration d
.
Has no effect on constant values.
backwards :: Active a > Active a #
Reverse an active value so the start of its era gets mapped to
the end and vice versa. For example, backwards
can be
visualized asui
snapshot :: Time Rational > Active a > Active a #
Take a "snapshot" of an active value at a particular time, resulting in a constant value.
Working with values outside the era
clamp :: Active a > Active a #
"Clamp" an active value so that it is constant before and after
its era. Before the era, clamp a
takes on the value of a
at
the start of the era. Likewise, after the era, clamp a
takes
on the value of a
at the end of the era. clamp
has no effect
on constant values.
For example, clamp
can be visualized asui
See also clampBefore
and clampAfter
, which clamp only before
or after the era, respectively.
clampBefore :: Active a > Active a #
clampAfter :: Active a > Active a #
trim :: Monoid a => Active a > Active a #
"Trim" an active value so that it is empty outside its era.
trim
has no effect on constant values.
For example, trim
can be visualized asui
Actually, trim ui
is not welltyped, since it is not guaranteed
that ui
's values will be monoidal (and usually they won't be)!
But the above image still provides a good intuitive idea of what
trim
is doing. To make this precise we could consider something
like trim (First . Just $ ui)
.
See also trimBefore
and trimActive
, which trim only before or
after the era, respectively.
trimBefore :: Monoid a => Active a > Active a #
Composing active values
after :: Active a > Active a > Active a #
a1 `after` a2
produces an active that behaves like a1
but is
shifted to start at the end time of a2
. If either a1
or a2
are constant, a1
is returned unchanged.
movie :: [Active a] > Active a #
Splice together a list of active values using >>
. The list
must be nonempty.
Discretization
Create an Active
which takes on each value in the given list in
turn during the time [0,1]
, with each value getting an equal
amount of time. In other words, discrete
creates a "slide
show" that starts at time 0 and ends at time 1. The first
element is used prior to time 0, and the last element is used
after time 1.
It is an error to call discrete
on the empty list.
simulate :: Rational > Active a > [a] #
simulate r act
simulates the Active
value act
, returning a
list of "snapshots" taken at regular intervals from the start
time to the end time. The interval used is determined by the
rate r
, which denotes the "frame rate", that is, the number
of snapshots per unit time.
If the Active
value is constant (and thus has no start or end
times), a list of length 1 is returned, containing the constant
value.