-- 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.1.0.16


-- | 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.
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. <a>toTime</a> and
--   <a>fromTime</a> are also provided for convenience in converting
--   between <tt>Time</tt> and other numeric types.
data Time

-- | Convert any value of a <a>Real</a> type (including <tt>Int</tt>,
--   <tt>Integer</tt>, <tt>Rational</tt>, <tt>Float</tt>, and
--   <tt>Double</tt>) to a <a>Time</a>.
toTime :: Real a => a -> Time

-- | Convert a <a>Time</a> to a value of any <a>Fractional</a> type (such
--   as <tt>Rational</tt>, <tt>Float</tt>, or <tt>Double</tt>).
fromTime :: Fractional a => Time -> a

-- | 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. <a>toDuration</a> and <a>fromDuration</a>
--   are also provided for convenience in converting between
--   <tt>Duration</tt>s and other numeric types.
data Duration

-- | Convert any value of a <a>Real</a> type (including <tt>Int</tt>,
--   <tt>Integer</tt>, <tt>Rational</tt>, <tt>Float</tt>, and
--   <tt>Double</tt>) to a <a>Duration</a>.
toDuration :: Real a => a -> Duration

-- | Convert a <a>Duration</a> to any other <a>Fractional</a> type (such as
--   <tt>Rational</tt>, <tt>Float</tt>, or <tt>Double</tt>).
fromDuration :: Fractional a => Duration -> a

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

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

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

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

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

-- | 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 -> (Time -> a) -> Dynamic a
era :: Dynamic a -> Era
runDynamic :: Dynamic a -> Time -> a

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

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

-- | Shift a <a>Dynamic</a> value by a certain duration.
shiftDynamic :: Duration -> 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 -> Time -> (Time -> 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 -> 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

-- | 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 -> 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 -> 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 -> Time -> 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.
stretchTo :: Duration -> 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 -> 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 -> 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 Eq Time
instance Ord Time
instance Show Time
instance Read Time
instance Enum Time
instance Num Time
instance Fractional Time
instance Real Time
instance RealFrac Time
instance AdditiveGroup Time
instance Eq Duration
instance Ord Duration
instance Show Duration
instance Read Duration
instance Enum Duration
instance Num Duration
instance Fractional Duration
instance Real Duration
instance RealFrac Duration
instance AdditiveGroup Duration
instance Semigroup Era
instance Show Era
instance Functor Dynamic
instance Functor Active
instance Apply Active
instance Applicative Active
instance (Monoid a, Semigroup a) => Monoid (Active a)
instance Semigroup a => Semigroup (Active a)
instance Newtype (MaybeApply f a) (Either (f a) a)
instance Newtype (Active a) (MaybeApply Dynamic a)
instance Semigroup a => Semigroup (Dynamic a)
instance Apply Dynamic
instance AffineSpace Time
instance VectorSpace Duration
instance Newtype Duration Rational
instance InnerSpace Time
instance VectorSpace Time
instance Newtype Time Rational
