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


-- | Semigroup actions, groups, and torsors.
--   
--   Acts and torsors model types which can be transformed under the action
--   of another type.
--   
--   A prototypical example is affine space, which has an action by
--   translation: given any two points in affine space, there is a unique
--   translation that brings one to the other.
--   
--   This can be useful in a library keeping track of time: on top of
--   needing to keep track of units, one also needs to distinguish between
--   absolute time (time stamps) and relative time (time differences). The
--   operations one expects in this situation are:
--   
--   <ul>
--   <li>Addition and subtraction of time differences: time differences
--   form a (commutative) group.</li>
--   <li>Translation of an absolute time by a time difference: there is an
--   action of relative time on absolute time.</li>
--   <li>Given two absolute times, one can obtain the time difference
--   between them: absolute time is a torsor under relative time.</li>
--   </ul>
--   
--   This library provides a convenient framework which helps to avoid
--   mixing up these two different notions.
--   
--   A fleshed out example is available at
--   <a>Acts.Examples.MusicalIntervals</a>, which showcases the use of
--   actions and torsors in the context of musical intervals and harmony.
--   It also demonstrates common usage patterns of this library, such as
--   how to automatically derive instances.
--   
--   See also the <a>project readme</a>, which includes a simple example
--   with 2D affine space.
@package acts
@version 0.3.0.0


-- | An <a>Act</a> of a semigroup &lt;math&gt; on a type &lt;math&gt; gives
--   a way to transform terms of type &lt;math&gt; by terms of type
--   &lt;math&gt;, in a way that is compatible with the semigroup operation
--   on &lt;math&gt;.
--   
--   In the special case that there is a unique way of going from one term
--   of type &lt;math&gt; to another through a transformation by a term of
--   type &lt;math&gt;, we say that &lt;math&gt; is a torsor under
--   &lt;math&gt;.
--   
--   For example, the plane has an action by translations. Given any two
--   points, there is a unique translation that takes the first point to
--   the second. Note that an unmarked plane (like a blank piece of paper)
--   has no designated origin or reference point, whereas the set of
--   translations is a plane with a given origin (the zero translation).
--   This is the distinction between an affine space (an unmarked plane)
--   and a vector space. Enforcing this distinction in the types can help
--   to avoid confusing absolute points with translation vectors.
--   
--   Simple <a>Act</a> and <a>Torsor</a> instances can be derived through
--   self-actions:
--   
--   <pre>
--   &gt; newtype Seconds   = Seconds { getSeconds :: Double }
--   &gt;   deriving ( Act TimeDelta, Torsor TimeDelta )
--   &gt;     via TimeDelta
--   &gt; newtype TimeDelta = TimeDelta { timeDeltaInSeconds :: Seconds }
--   &gt;   deriving ( Semigroup, Monoid, Group )
--   &gt;     via Sum Double
--   </pre>
module Data.Act

-- | A left <b>act</b> (or left <b>semigroup action</b>) of a semigroup
--   <tt>s</tt> on <tt>x</tt> consists of an operation
--   
--   <pre>
--   (•) :: s -&gt; x -&gt; x
--   </pre>
--   
--   such that:
--   
--   <pre>
--   a • ( b • x ) = ( a &lt;&gt; b ) • x
--   </pre>
--   
--   In case <tt>s</tt> is also a <a>Monoid</a>, we additionally require:
--   
--   <pre>
--   mempty • x = x
--   </pre>
--   
--   The synonym <tt> act = (•) </tt> is also provided.
class Semigroup s => Act s x

-- | Left action of a semigroup.
(•) :: Act s x => s -> x -> x

-- | Left action of a semigroup.
act :: Act s x => s -> x -> x
infixr 5 •
infixr 5 `act`

-- | Transport an act:
--   
transportAction :: (a -> b) -> (b -> a) -> (g -> b -> b) -> g -> a -> a

-- | Trivial act of a semigroup on any type (acting by the identity).
newtype Trivial a
Trivial :: a -> Trivial a
[getTrivial] :: Trivial a -> a

-- | A left <b>torsor</b> consists of a <i>free</i> and <i>transitive</i>
--   left action of a group on an inhabited type.
--   
--   This precisely means that for any two terms <tt>x</tt>, <tt>y</tt>,
--   there exists a <i>unique</i> group element <tt>g</tt> taking
--   <tt>x</tt> to <tt>y</tt>, which is denoted <tt> y &lt;-- x </tt> (or
--   <tt> x --&gt; y </tt>, but the left-pointing arrow is more natural
--   when working with left actions).
--   
--   That is <tt> y &lt;-- x </tt> is the <i>unique</i> element satisfying:
--   
--   <pre>
--   ( y &lt;-- x ) • x = y
--   </pre>
--   
--   Note the order of composition of <tt>&lt;--</tt> and <tt>--&gt;</tt>
--   with respect to <tt>&lt;&gt;</tt>:
--   
--   <pre>
--   ( z &lt;-- y ) &lt;&gt; ( y &lt;-- x ) = z &lt;-- x
--   </pre>
--   
--   <pre>
--   ( y --&gt; z ) &lt;&gt; ( x --&gt; y ) = x --&gt; z
--   </pre>
class (Group g, Act g x) => Torsor g x

-- | Unique group element effecting the given transition
(<--) :: Torsor g x => x -> x -> g

-- | Unique group element effecting the given transition
(-->) :: Torsor g x => x -> x -> g
infix 7 -->
infix 7 <--

-- | A group's inversion anti-automorphism corresponds to an isomorphism to
--   the opposite group.
--   
--   The inversion allows us to obtain a left action from a right action
--   (of the same group); the equivalent operation is not possible for
--   general semigroups.
anti :: Group g => g -> Dual g

-- | Given
--   
--   <ul>
--   <li>&lt;math&gt; acting on &lt;math&gt;,</li>
--   <li>&lt;math&gt; a torsor under &lt;math&gt;,</li>
--   <li>a map &lt;math&gt;,</li>
--   </ul>
--   
--   this function returns the unique element &lt;math&gt; making the
--   following diagram commute:
--   
intertwiner :: forall h g a b. (Act g a, Torsor h b) => g -> (a -> b) -> a -> h

-- | Newtype for the action on a type through its <a>Finitary</a> instance.
--   
--   <pre>
--   data ABCD = A | B | C | D
--     deriving stock    ( Eq, Generic )
--     deriving anyclass Finitary
--     deriving ( Act ( Sum ( Finite 4 ) ), Torsor ( Sum ( Finite 4 ) ) )
--       via Finitely ABCD
--   </pre>
--   
--   Sizes are checked statically. For instance if we had instead written:
--   
--   <pre>
--   deriving ( Act ( Sum ( Finite 3 ) ), Torsor ( Sum ( Finite 3 ) ) )
--     via Finitely ABCD
--   </pre>
--   
--   we would have gotten the error messages:
--   
--   <pre>
--   * No instance for (Act (Sum (Finite 3)) (Finite 4))
--   * No instance for (Torsor (Sum (Finite 3)) (Finite 4))
--   </pre>
newtype Finitely a
Finitely :: a -> Finitely a
[getFinitely] :: Finitely a -> a
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Act.Finitely a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Act.Finitely a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Act.Finitely a)
instance GHC.Generics.Generic1 Data.Act.Finitely
instance GHC.Generics.Generic (Data.Act.Finitely a)
instance Data.Data.Data a => Data.Data.Data (Data.Act.Finitely a)
instance GHC.Read.Read a => GHC.Read.Read (Data.Act.Finitely a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Act.Finitely a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Act.Trivial a)
instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Data.Act.Trivial a)
instance GHC.Enum.Enum a => GHC.Enum.Enum (Data.Act.Trivial a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Act.Trivial a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Act.Trivial a)
instance GHC.Generics.Generic1 Data.Act.Trivial
instance GHC.Generics.Generic (Data.Act.Trivial a)
instance Data.Data.Data a => Data.Data.Data (Data.Act.Trivial a)
instance GHC.Read.Read a => GHC.Read.Read (Data.Act.Trivial a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Act.Trivial a)
instance Data.Act.Act Data.Semigroup.Internal.Any GHC.Types.Bool
instance Data.Act.Act Data.Semigroup.Internal.All GHC.Types.Bool
instance Data.Act.Act s a => Data.Act.Act s (Data.Functor.Const.Const a b)
instance (Data.Group.Group g, Data.Act.Torsor g (Data.Finite.Internal.Finite n), Data.Finitary.Finitary a, n GHC.Types.~ Data.Finitary.Cardinality a) => Data.Act.Torsor g (Data.Act.Finitely a)
instance Data.Group.Group g => Data.Act.Torsor g g
instance GHC.Num.Num a => Data.Act.Torsor (Data.Semigroup.Internal.Sum a) a
instance (GHC.Base.Semigroup s, Data.Act.Act s (Data.Finite.Internal.Finite n), Data.Finitary.Finitary a, n GHC.Types.~ Data.Finitary.Cardinality a) => Data.Act.Act s (Data.Act.Finitely a)
instance GHC.Base.Semigroup s => Data.Act.Act s (Data.Act.Trivial a)
instance GHC.Base.Semigroup s => Data.Act.Act s s
instance GHC.Num.Num a => Data.Act.Act (Data.Semigroup.Internal.Sum a) a
instance GHC.Num.Num a => Data.Act.Act (Data.Semigroup.Internal.Product a) a
instance Data.Act.Act () x
instance (Data.Act.Act s1 x1, Data.Act.Act s2 x2) => Data.Act.Act (s1, s2) (x1, x2)
instance (Data.Act.Act s1 x1, Data.Act.Act s2 x2, Data.Act.Act s3 x3) => Data.Act.Act (s1, s2, s3) (x1, x2, x3)
instance (Data.Act.Act s1 x1, Data.Act.Act s2 x2, Data.Act.Act s3 x3, Data.Act.Act s4 x4) => Data.Act.Act (s1, s2, s3, s4) (x1, x2, x3, x4)
instance (Data.Act.Act s1 x1, Data.Act.Act s2 x2, Data.Act.Act s3 x3, Data.Act.Act s4 x4, Data.Act.Act s5 x5) => Data.Act.Act (s1, s2, s3, s4, s5) (x1, x2, x3, x4, x5)
instance (Data.Act.Act s x, GHC.Base.Functor f) => Data.Act.Act s (Data.Monoid.Ap f x)
instance (GHC.Base.Semigroup s, Data.Act.Act s a) => Data.Act.Act (Data.Semigroup.Internal.Dual s) (Data.Functor.Contravariant.Op b a)
instance (GHC.Base.Semigroup s, Data.Act.Act s a, Data.Act.Act t b) => Data.Act.Act (Data.Semigroup.Internal.Dual s, t) (a -> b)
instance (Data.Group.Group g, Data.Act.Act g a) => Data.Act.Act g (Data.Semigroup.Internal.Endo a)