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


-- | A <a>Group</a> is a <a>Monoid</a> for which the monoid operation can
--   be undone.
--   
--   That is, &lt;math&gt; is a group if each &lt;math&gt; has an inverse
--   element &lt;math&gt; such that
--   
--   &lt;math&gt;
--   
--   Such inverses are necessarily unique.
--   
--   In Haskell, groups are mostly useful to describe objects possessing
--   certain symmetries (such as translation or rotation).
--   
--   To automatically derive <a>Group</a> instances, you can:
--   
--   <ul>
--   <li>Use <tt>DerivingVia</tt> to coerce an existing instance:</li>
--   </ul>
--   
--   <pre>
--   &gt; newtype Seconds   = Seconds { getSeconds :: Double }
--   &gt; newtype TimeDelta = TimeDelta { timeDeltaInSeconds :: Seconds }
--   &gt;   deriving ( Semigroup, Monoid, Group )
--   &gt;     via Sum Double
--   </pre>
--   
--   <ul>
--   <li>Use <a>Generic</a> and <a>Generically</a>:</li>
--   </ul>
--   
--   <pre>
--   &gt; data MyRecord
--   &gt;   = MyRecord
--   &gt;   { field1 :: Sum Double
--   &gt;   , field2 :: Product Double
--   &gt;   , field3 :: Ap [] ( Sum Int, Sum Int )
--   &gt;   }
--   &gt;   deriving Generic
--   &gt;   deriving ( Semigroup, Monoid, Group )
--   &gt;     via Generically MyRecord
--   </pre>
module Data.Group

-- | A <a>Group</a> is a <a>Monoid</a> with inverses:
--   
--   <ul>
--   <li><pre> inverse g &lt;&gt; g = g &lt;&gt; inverse g =
--   mempty</pre></li>
--   <li><pre> inverse (g &lt;&gt; h) = inverse h &lt;&gt; inverse
--   g</pre></li>
--   </ul>
class Monoid g => Group g

-- | Group inversion anti-homomorphism.
inverse :: Group g => g -> g

-- | Take the <tt>n</tt>-th power of an element.
gtimes :: (Group g, Integral n) => n -> g -> g

-- | The inverse anti-automorphism of a group lifts to a isomorphism with
--   the opposite group.
anti :: Group g => g -> Dual g

-- | Reflexive property <a>Dual</a> (should be included in base, maybe
--   under another name).
reflexive :: Dual (Dual a) -> a

-- | Data type to keep track of a pair of inverse elements.
data Isom a
(:|:) :: a -> Dual a -> Isom a
[to] :: Isom a -> a
[from] :: Isom a -> Dual a
infix 7 :|:
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Group.Isom a)
instance GHC.Generics.Generic1 Data.Group.Isom
instance GHC.Generics.Generic (Data.Group.Isom a)
instance Data.Data.Data a => Data.Data.Data (Data.Group.Isom a)
instance GHC.Read.Read a => GHC.Read.Read (Data.Group.Isom a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Group.Isom a)
instance Data.Group.Group a => Data.Group.Group (r -> a)
instance Data.Group.Group a => Data.Group.Group (GHC.Types.IO a)
instance Data.Group.Group a => Data.Group.Group (GHC.ST.ST s a)
instance Data.Group.Group a => Data.Group.Group (Data.Ord.Down a)
instance Data.Group.Group a => Data.Group.Group (Data.Functor.Identity.Identity a)
instance Data.Group.Group a => Data.Group.Group (Data.Functor.Const.Const a b)
instance Data.Group.Group a => Data.Group.Group (Data.Functor.Contravariant.Op a b)
instance Data.Group.Group (f p) => Data.Group.Group (GHC.Generics.Rec1 f p)
instance Data.Group.Group (f p) => Data.Group.Group (GHC.Generics.M1 i c f p)
instance Data.Group.Group g => Data.Group.Group (GHC.Generics.K1 i g p)
instance Data.Group.Group g => Data.Group.Group (GHC.Generics.Par1 g)
instance Data.Group.GGroup f => Data.Group.GGroup (GHC.Generics.Rec1 f)
instance Data.Group.GGroup f => Data.Group.GGroup (GHC.Generics.M1 i c f)
instance (GHC.Generics.Generic g, GHC.Base.Monoid (GHC.Generics.Rep g ()), Data.Group.GGroup (GHC.Generics.Rep g)) => Data.Group.Group (Generic.Data.Internal.Generically.Generically g)
instance Data.Group.GGroup GHC.Generics.U1
instance Data.Group.Group g => Data.Group.GGroup (GHC.Generics.K1 i g)
instance (Data.Group.GGroup f1, Data.Group.GGroup f2) => Data.Group.GGroup (f1 GHC.Generics.:*: f2)
instance (TypeError ...) => Data.Group.GGroup GHC.Generics.V1
instance (TypeError ...) => Data.Group.GGroup (f1 GHC.Generics.:+: f2)
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Data.Group.Isom a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Data.Group.Isom a)
instance GHC.Base.Monoid a => Data.Group.Group (Data.Group.Isom a)
instance Data.Group.Group ()
instance GHC.Num.Num a => Data.Group.Group (Data.Semigroup.Internal.Sum a)
instance GHC.Real.Fractional a => Data.Group.Group (Data.Semigroup.Internal.Product a)
instance Data.Group.Group a => Data.Group.Group (Data.Semigroup.Internal.Dual a)
instance (Data.Group.Group a, GHC.Base.Applicative f) => Data.Group.Group (Data.Monoid.Ap f a)
instance Data.Group.Group (Data.Proxy.Proxy p)
instance (Data.Group.Group g1, Data.Group.Group g2) => Data.Group.Group (g1, g2)
instance (Data.Group.Group g1, Data.Group.Group g2, Data.Group.Group g3) => Data.Group.Group (g1, g2, g3)
instance (Data.Group.Group g1, Data.Group.Group g2, Data.Group.Group g3, Data.Group.Group g4) => Data.Group.Group (g1, g2, g3, g4)
instance (Data.Group.Group g1, Data.Group.Group g2, Data.Group.Group g3, Data.Group.Group g4, Data.Group.Group g5) => Data.Group.Group (g1, g2, g3, g4, g5)
instance Data.Group.Group (GHC.Generics.U1 p)
instance (Data.Group.Group (f1 p), Data.Group.Group (f2 p)) => Data.Group.Group ((GHC.Generics.:*:) f1 f2 p)


-- | 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 `act`
infixr 5 •

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

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