libghc-active-doc 0.2.0.8-1build1 / usr / share / doc / libghc-active-doc / html / active.txt

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


-- | Abstractions for animation
--   
--   <a>Active</a> abstraction for animated things with finite start and
--   end times.
@package active
@version 0.2.0.8


-- | Inspired by the work of Kevin Matlage and Andy Gill (<i>Every</i>
--   <i>Animation Should Have a Beginning, a Middle, and an End</i>, Trends
--   in Functional Programming, 2010.
--   <a>http://ittc.ku.edu/csdl/fpg/node/46</a>), this module defines a
--   simple abstraction for working with time-varying values. A value of
--   type <tt>Active a</tt> is either a constant value of type <tt>a</tt>,
--   or a time-varying value of type <tt>a</tt> (<i>i.e.</i> a function
--   from time to <tt>a</tt>) 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 stripped-down 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
--   (<a>http://projects.haskell.org/diagrams</a>), but the hope is that it
--   may find more general utility.
--   
--   There are two basic ways to create an <tt>Active</tt> value. The first
--   is to use <a>mkActive</a> to create one directly, by specifying a
--   start and end time and a function of time. More indirectly, one can
--   use the <a>Applicative</a> instance together with the unit interval
--   <a>ui</a>, which takes on values from the unit interval from time 0 to
--   time 1, or <a>interval</a>, which creates an active over an arbitrary
--   interval.
--   
--   For example, to create a value of type <tt>Active Double</tt> which
--   represents one period of a sine wave starting at time 0 and ending at
--   time 1, we could write
--   
--   <pre>
--   mkActive 0 1 (\t -&gt; sin (fromTime t * tau))
--   </pre>
--   
--   or
--   
--   <pre>
--   (sin . (*tau)) &lt;$&gt; ui
--   </pre>
--   
--   <a>pure</a> can also be used to create <tt>Active</tt> values which
--   are constant and have no start or end time. For example,
--   
--   <pre>
--   mod &lt;$&gt; (floor &lt;$&gt; interval 0 100) &lt;*&gt; pure 7
--   </pre>
--   
--   cycles repeatedly through the numbers 0-6.
--   
--   Note that the "idiom bracket" notation supported by the SHE
--   preprocessor (<a>http://personal.cis.strath.ac.uk/~conor/pub/she/</a>,
--   <a>http://hackage.haskell.org/package/she</a>) can make for somewhat
--   more readable <a>Applicative</a> code. For example, the above example
--   can be rewritten using SHE as
--   
--   <pre>
--   {-# OPTIONS_GHC -F -pgmF she #-}
--   
--   ... (| mod (| floor (interval 0 100) |) ~7 |)
--   </pre>
--   
--   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 <a>Active</a> values.
module Data.Active

-- | An abstract type for representing <i>points in time</i>. Note that
--   literal numeric values may be used as <tt>Time</tt>s, thanks to the
--   the <a>Num</a> and <a>Fractional</a> instances.
data Time n

-- | A convenient wrapper function to convert a numeric value into a time.
toTime :: n -> Time n

-- | A convenient unwrapper function to turn a time into a numeric value.
fromTime :: Time n -> n

-- | An abstract type representing <i>elapsed time</i> between two points
--   in time. Note that durations can be negative. Literal numeric values
--   may be used as <tt>Duration</tt>s thanks to the <a>Num</a> and
--   <a>Fractional</a> instances.
data Duration n

-- | A convenient wrapper function to convert a numeric value into a
--   duration.
toDuration :: n -> Duration n

-- | A convenient unwrapper function to turn a duration into a numeric
--   value.
fromDuration :: Duration n -> n

-- | An <tt>Era</tt> is a concrete span of time, that is, a pair of times
--   representing the start and end of the era. <tt>Era</tt>s form a
--   semigroup: the combination of two <tt>Era</tt>s is the smallest
--   <tt>Era</tt> which contains both. They do not form a <a>Monoid</a>,
--   since there is no <tt>Era</tt> which acts as the identity with respect
--   to this combining operation.
--   
--   <tt>Era</tt> is abstract. To construct <tt>Era</tt> values, use
--   <a>mkEra</a>; to deconstruct, use <a>start</a> and <a>end</a>.
data Era n

-- | Create an <a>Era</a> by specifying start and end <a>Time</a>s.
mkEra :: Time n -> Time n -> Era n

-- | Get the start <a>Time</a> of an <a>Era</a>.
start :: Era n -> Time n

-- | Get the end <a>Time</a> of an <a>Era</a>.
end :: Era n -> Time n

-- | Compute the <a>Duration</a> of an <a>Era</a>.
duration :: Num n => Era n -> Duration n

-- | A <tt>Dynamic a</tt> can be thought of as an <tt>a</tt> value that
--   changes over the course of a particular <a>Era</a>. It's envisioned
--   that <tt>Dynamic</tt> will be mostly an internal implementation detail
--   and that <a>Active</a> will be most commonly used. But you never know
--   what uses people might find for things.
data Dynamic a
Dynamic :: Era Rational -> (Time Rational -> a) -> Dynamic a
[era] :: Dynamic a -> Era Rational
[runDynamic] :: Dynamic a -> Time Rational -> a

-- | Create a <a>Dynamic</a> from a start time, an end time, and a
--   time-varying value.
mkDynamic :: Time Rational -> Time Rational -> (Time Rational -> a) -> Dynamic a

-- | Fold for <a>Dynamic</a>.
onDynamic :: (Time Rational -> Time Rational -> (Time Rational -> a) -> b) -> Dynamic a -> b

-- | Shift a <a>Dynamic</a> value by a certain duration.
shiftDynamic :: Duration Rational -> Dynamic a -> Dynamic a

-- | There are two types of <tt>Active</tt> values:
--   
--   <ul>
--   <li>An <a>Active</a> can simply be a <a>Dynamic</a>, that is, a
--   time-varying value with start and end times.</li>
--   <li>An <a>Active</a> value can also be a constant: a single value,
--   constant across time, with no start and end times.</li>
--   </ul>
--   
--   The addition of constant values enable <a>Monoid</a> and
--   <a>Applicative</a> instances for <a>Active</a>.
data Active a

-- | Create a dynamic <a>Active</a> from a start time, an end time, and a
--   time-varying value.
mkActive :: Time Rational -> Time Rational -> (Time Rational -> a) -> Active a

-- | Create an <a>Active</a> value from a <a>Dynamic</a>.
fromDynamic :: Dynamic a -> Active a

-- | Test whether an <a>Active</a> value is constant.
isConstant :: Active a -> Bool

-- | Test whether an <a>Active</a> value is <a>Dynamic</a>.
isDynamic :: Active a -> Bool

-- | Fold for <a>Active</a>s. Process an 'Active a', given a function to
--   apply if it is a pure (constant) value, and a function to apply if it
--   is a <a>Dynamic</a>.
onActive :: (a -> b) -> (Dynamic a -> b) -> Active a -> b

-- | Modify an <a>Active</a> value using a case analysis to see whether it
--   is constant or dynamic.
modActive :: (a -> b) -> (Dynamic a -> Dynamic b) -> Active a -> Active b

-- | Interpret an <a>Active</a> value as a function from time.
runActive :: Active a -> Time Rational -> a

-- | Get the <a>Era</a> of an <a>Active</a> value (or <a>Nothing</a> if it
--   is a constant/pure value).
activeEra :: Active a -> Maybe (Era Rational)

-- | Set the era of an <a>Active</a> value. Note that this will change a
--   constant <a>Active</a> into a dynamic one which happens to have the
--   same value at all times.
setEra :: Era Rational -> Active a -> Active a

-- | <tt>atTime t a</tt> is an active value with the same behavior as
--   <tt>a</tt>, shifted so that it starts at time <tt>t</tt>. If
--   <tt>a</tt> is constant it is returned unchanged.
atTime :: Time Rational -> Active a -> Active a

-- | Get the value of an <tt>Active a</tt> at the beginning of its era.
activeStart :: Active a -> a

-- | Get the value of an <tt>Active a</tt> at the end of its era.
activeEnd :: Active a -> a

-- | <tt>ui</tt> represents the <i>unit interval</i>, which takes on the
--   value <tt>t</tt> at time <tt>t</tt>, and has as its era
--   <tt>[0,1]</tt>. It is equivalent to <tt><a>interval</a> 0 1</tt>, and
--   can be visualized as follows:
--   
--   
--   On the x-axis is time, and the value that <tt>ui</tt> takes on is on
--   the y-axis. The shaded portion represents the era. Note that the value
--   of <tt>ui</tt> (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 <a>fmap</a>
--   affects all values, both inside and outside the era. To manipulate
--   values outside the era specifically, see <a>clamp</a> and <a>trim</a>.
--   
--   To alter the <i>values</i> that <tt>ui</tt> takes on without altering
--   its era, use its <a>Functor</a> and <a>Applicative</a> instances. For
--   example, <tt>(*2) &lt;$&gt; ui</tt> varies from <tt>0</tt> to
--   <tt>2</tt> over the era <tt>[0,1]</tt>. To alter the era, you can use
--   <a>stretch</a> or <a>shift</a>.
ui :: Fractional a => Active a

-- | <tt>interval a b</tt> is an active value starting at time <tt>a</tt>,
--   ending at time <tt>b</tt>, and taking the value <tt>t</tt> at time
--   <tt>t</tt>.
interval :: Fractional a => Time Rational -> Time Rational -> Active a

-- | <tt>stretch s act</tt> "stretches" the active <tt>act</tt> so that it
--   takes <tt>s</tt> times as long (retaining the same start time).
stretch :: Rational -> Active a -> Active a

-- | <tt>stretchTo d</tt> <a>stretch</a>es an <a>Active</a> so it has
--   duration <tt>d</tt>. Has no effect if (1) <tt>d</tt> is non-positive,
--   or (2) the <a>Active</a> value is constant, or (3) the <a>Active</a>
--   value has zero duration. [AJG: conditions (1) and (3) no longer true:
--   to consider changing]
stretchTo :: Duration Rational -> Active a -> Active a

-- | <tt>a1 `during` a2</tt> <a>stretch</a>es and <a>shift</a>s <tt>a1</tt>
--   so that it has the same era as <tt>a2</tt>. Has no effect if either of
--   <tt>a1</tt> or <tt>a2</tt> are constant.
during :: Active a -> Active a -> Active a

-- | <tt>shift d act</tt> shifts the start time of <tt>act</tt> by duration
--   <tt>d</tt>. Has no effect on constant values.
shift :: Duration Rational -> Active a -> Active a

-- | Reverse an active value so the start of its era gets mapped to the end
--   and vice versa. For example, <tt>backwards <a>ui</a></tt> can be
--   visualized as
--   
backwards :: Active a -> Active a

-- | Take a "snapshot" of an active value at a particular time, resulting
--   in a constant value.
snapshot :: Time Rational -> Active a -> Active a

-- | "Clamp" an active value so that it is constant before and after its
--   era. Before the era, <tt>clamp a</tt> takes on the value of <tt>a</tt>
--   at the start of the era. Likewise, after the era, <tt>clamp a</tt>
--   takes on the value of <tt>a</tt> at the end of the era. <tt>clamp</tt>
--   has no effect on constant values.
--   
--   For example, <tt>clamp <a>ui</a></tt> can be visualized as
--   
--   
--   See also <a>clampBefore</a> and <a>clampAfter</a>, which clamp only
--   before or after the era, respectively.
clamp :: Active a -> Active a

-- | "Clamp" an active value so that it is constant before the start of its
--   era. For example, <tt>clampBefore <a>ui</a></tt> can be visualized as
--   
--   
--   See the documentation of <a>clamp</a> for more information.
clampBefore :: Active a -> Active a

-- | "Clamp" an active value so that it is constant after the end of its
--   era. For example, <tt>clampBefore <a>ui</a></tt> can be visualized as
--   
--   
--   See the documentation of <a>clamp</a> for more information.
clampAfter :: Active a -> Active a

-- | "Trim" an active value so that it is empty outside its era.
--   <tt>trim</tt> has no effect on constant values.
--   
--   For example, <tt>trim <a>ui</a></tt> can be visualized as
--   
--   
--   Actually, <tt>trim ui</tt> is not well-typed, since it is not
--   guaranteed that <tt>ui</tt>'s values will be monoidal (and usually
--   they won't be)! But the above image still provides a good intuitive
--   idea of what <tt>trim</tt> is doing. To make this precise we could
--   consider something like <tt>trim (First . Just <a>$</a> ui)</tt>.
--   
--   See also <a>trimBefore</a> and <tt>trimActive</tt>, which trim only
--   before or after the era, respectively.
trim :: Monoid a => Active a -> Active a

-- | "Trim" an active value so that it is empty <i>before</i> the start of
--   its era. For example, <tt>trimBefore <a>ui</a></tt> can be visualized
--   as
--   
--   
--   See the documentation of <a>trim</a> for more details.
trimBefore :: Monoid a => Active a -> Active a

-- | "Trim" an active value so that it is empty <i>after</i> the end of its
--   era. For example, <tt>trimAfter <a>ui</a></tt> can be visualized as
--   
--   
--   See the documentation of <a>trim</a> for more details.
trimAfter :: Monoid a => Active a -> Active a

-- | <tt>a1 `after` a2</tt> produces an active that behaves like
--   <tt>a1</tt> but is shifted to start at the end time of <tt>a2</tt>. If
--   either <tt>a1</tt> or <tt>a2</tt> are constant, <tt>a1</tt> is
--   returned unchanged.
after :: Active a -> Active a -> Active a

-- | Sequence/overlay two <a>Active</a> values: shift the second to start
--   immediately after the first (using <a>after</a>), then compose them
--   (using <a>&lt;&gt;</a>).
(->>) :: Semigroup a => Active a -> Active a -> Active a

-- | "Splice" two <a>Active</a> values together: shift the second to start
--   immediately after the first (using <a>after</a>), and produce the
--   value which acts like the first up to the common end/start point, then
--   like the second after that. If both are constant, return the first.
(|>>) :: Active a -> Active a -> Active a

-- | Splice together a list of active values using <a>|&gt;&gt;</a>. The
--   list must be nonempty.
movie :: [Active a] -> Active a

-- | Create an <tt>Active</tt> which takes on each value in the given list
--   in turn during the time <tt>[0,1]</tt>, with each value getting an
--   equal amount of time. In other words, <tt>discrete</tt> 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 <tt>discrete</tt> on the empty list.
discrete :: [a] -> Active a

-- | <tt>simulate r act</tt> simulates the <a>Active</a> value
--   <tt>act</tt>, 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 <tt>r</tt>, which denotes the "frame rate",
--   that is, the number of snapshots per unit time.
--   
--   If the <a>Active</a> value is constant (and thus has no start or end
--   times), a list of length 1 is returned, containing the constant value.
simulate :: Rational -> Active a -> [a]
instance (Data.Functor.Bind.Class.MaybeApply f1 a1 ~ t0) => Control.Lens.Wrapped.Rewrapped (Data.Functor.Bind.Class.MaybeApply f0 a0) t0
instance Control.Lens.Wrapped.Wrapped (Data.Functor.Bind.Class.MaybeApply f0 a0)
instance Data.Semigroup.Semigroup a => Data.Semigroup.Semigroup (Data.Active.Active a)
instance (GHC.Base.Monoid a, Data.Semigroup.Semigroup a) => GHC.Base.Monoid (Data.Active.Active a)
instance (Data.Active.Active a1 ~ t0) => Control.Lens.Wrapped.Rewrapped (Data.Active.Active a0) t0
instance Control.Lens.Wrapped.Wrapped (Data.Active.Active a0)
instance GHC.Base.Applicative Data.Active.Active
instance Data.Functor.Bind.Class.Apply Data.Active.Active
instance GHC.Base.Functor Data.Active.Active
instance GHC.Base.Functor Data.Active.Dynamic
instance GHC.Classes.Ord n => Data.Semigroup.Semigroup (Data.Active.Era n)
instance GHC.Show.Show n => GHC.Show.Show (Data.Active.Era n)
instance (Data.Active.Duration n1 ~ t0) => Control.Lens.Wrapped.Rewrapped (Data.Active.Duration n0) t0
instance Control.Lens.Wrapped.Wrapped (Data.Active.Duration n0)
instance GHC.Base.Applicative Data.Active.Duration
instance Linear.Vector.Additive Data.Active.Duration
instance GHC.Num.Num n => Data.Semigroup.Semigroup (Data.Active.Duration n)
instance GHC.Num.Num n => GHC.Base.Monoid (Data.Active.Duration n)
instance Data.Functor.Bind.Class.Apply Data.Active.Dynamic
instance Data.Semigroup.Semigroup a => Data.Semigroup.Semigroup (Data.Active.Dynamic a)
instance GHC.Base.Functor Data.Active.Duration
instance GHC.Real.RealFrac n => GHC.Real.RealFrac (Data.Active.Duration n)
instance GHC.Real.Real n => GHC.Real.Real (Data.Active.Duration n)
instance GHC.Real.Fractional n => GHC.Real.Fractional (Data.Active.Duration n)
instance GHC.Num.Num n => GHC.Num.Num (Data.Active.Duration n)
instance GHC.Enum.Enum n => GHC.Enum.Enum (Data.Active.Duration n)
instance GHC.Read.Read n => GHC.Read.Read (Data.Active.Duration n)
instance GHC.Show.Show n => GHC.Show.Show (Data.Active.Duration n)
instance GHC.Classes.Ord n => GHC.Classes.Ord (Data.Active.Duration n)
instance GHC.Classes.Eq n => GHC.Classes.Eq (Data.Active.Duration n)
instance (Data.Active.Time n1 ~ t0) => Control.Lens.Wrapped.Rewrapped (Data.Active.Time n0) t0
instance Control.Lens.Wrapped.Wrapped (Data.Active.Time n0)
instance Linear.Affine.Affine Data.Active.Time
instance GHC.Base.Functor Data.Active.Time
instance GHC.Real.RealFrac n => GHC.Real.RealFrac (Data.Active.Time n)
instance GHC.Real.Real n => GHC.Real.Real (Data.Active.Time n)
instance GHC.Real.Fractional n => GHC.Real.Fractional (Data.Active.Time n)
instance GHC.Num.Num n => GHC.Num.Num (Data.Active.Time n)
instance GHC.Enum.Enum n => GHC.Enum.Enum (Data.Active.Time n)
instance GHC.Read.Read n => GHC.Read.Read (Data.Active.Time n)
instance GHC.Show.Show n => GHC.Show.Show (Data.Active.Time n)
instance GHC.Classes.Ord n => GHC.Classes.Ord (Data.Active.Time n)
instance GHC.Classes.Eq n => GHC.Classes.Eq (Data.Active.Time n)