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


-- | Various extra monoid-related definitions and utilities
--   
--   Various extra monoid-related definitions and utilities, such as monoid
--   actions, monoid coproducts, "deletable" monoids, "split" monoids, and
--   "cut" monoids.
@package monoid-extras
@version 0.3.2.4


-- | Convenience alias for the combination of <tt>Monoid</tt> and
--   <tt>Semigroup</tt> constraints.
module Data.Monoid.WithSemigroup

-- | The <tt>Monoid'</tt> class is a synonym for things which are instances
--   of both <a>Semigroup</a> and <a>Monoid</a>. Ideally, the <a>Monoid</a>
--   class itself will eventually include a <a>Semigroup</a> superclass and
--   we can get rid of this.
class (Semigroup m, Monoid m) => Monoid' m
instance (Semigroup m, Monoid m) => Monoid' m


-- | A type for representing values with an additional bit saying whether
--   the value is "just a recommendation" (to be used only if nothing
--   better comes along) or a "committment" (to certainly be used,
--   overriding merely recommended values), along with corresponding
--   <tt>Semigroup</tt> and <tt>Monoid</tt> instances.
module Data.Monoid.Recommend

-- | A value of type <tt>Recommend a</tt> consists of a value of type
--   <tt>a</tt> wrapped up in one of two constructors. The
--   <tt>Recommend</tt> constructor indicates a "non-committal
--   recommendation"---that is, the given value should be used if no
--   other/better values are available. The <tt>Commit</tt> constructor
--   indicates a "commitment"---a value which should definitely be used,
--   overriding any <tt>Recommend</tt>ed values.
data Recommend a
Recommend :: a -> Recommend a
Commit :: a -> Recommend a

-- | Extract the value of type <tt>a</tt> wrapped in <tt>Recommend a</tt>.
getRecommend :: Recommend a -> a
instance (Semigroup a, Monoid a) => Monoid (Recommend a)
instance Semigroup a => Semigroup (Recommend a)


-- | Make semigroup under <a>min</a> or <a>max</a> into monoids by
--   adjoining an element corresponding to infinity (positive or negative,
--   respectively). These types are similar to <tt>Option (Min a)</tt> and
--   <tt>Option (Max a)</tt> respectively, except that the <a>Ord</a>
--   instance matches the <a>Monoid</a> instance.
module Data.Monoid.Inf
data Inf p a
Infinity :: Inf p a
Finite :: a -> Inf p a
type PosInf a = Inf Pos a
type NegInf a = Inf Neg a
minimum :: Ord a => [a] -> PosInf a
maximum :: Ord a => [a] -> NegInf a
posInfty :: PosInf a
negInfty :: NegInf a
posFinite :: a -> PosInf a
negFinite :: a -> NegInf a
instance Eq a => Eq (Inf p a)
instance Show a => Show (Inf p a)
instance Read a => Read (Inf p a)
instance Functor (Inf p)
instance Foldable (Inf p)
instance Traversable (Inf p)
instance Ord a => Monoid (Inf Neg a)
instance Ord a => Monoid (Inf Pos a)
instance Ord a => Semigroup (Inf Neg a)
instance Ord a => Semigroup (Inf Pos a)
instance Ord a => Ord (Inf Neg a)
instance Ord a => Ord (Inf Pos a)


-- | The monoid of endomorphisms over any <a>Category</a>.
module Data.Monoid.Endomorphism

-- | An <a>Endomorphism</a> in a given <a>Category</a> is a morphism from
--   some object to itself. The set of endomorphisms for a particular
--   object form a monoid, with composition as the combining operation and
--   the identity morphism as the identity element.
newtype Endomorphism k a
Endomorphism :: k a a -> Endomorphism k a
getEndomorphism :: Endomorphism k a -> k a a
instance (Category k, Groupoid k) => Group (Endomorphism k a)
instance Category k => Monoid (Endomorphism k a)
instance Semigroupoid k => Semigroup (Endomorphism k a)


-- | A monoid transformer that allows deleting information from a
--   concatenation of monoidal values.
module Data.Monoid.Deletable

-- | If <tt>m</tt> is a <a>Monoid</a>, then <tt>Deletable m</tt>
--   (intuitively speaking) adds two distinguished new elements <tt>[</tt>
--   and <tt>]</tt>, such that an occurrence of [ "deletes" everything from
--   it to the next ]. For example,
--   
--   <pre>
--   abc[def]gh == abcgh
--   </pre>
--   
--   This is all you really need to know to <i>use</i> <tt>Deletable m</tt>
--   values; to understand the actual implementation, read on.
--   
--   To properly deal with nesting and associativity we need to be able to
--   assign meanings to things like <tt>[[</tt>, <tt>][</tt>, and so on.
--   (We cannot just define, say, <tt>[[ == [</tt>, since then <tt>([[)] ==
--   [] == id</tt> but <tt>[([]) == [id == [</tt>.) Formally, elements of
--   <tt>Deletable m</tt> are triples of the form (r, m, l) representing
--   words <tt>]^r m [^l</tt>. When combining two triples (r1, m1, l1) and
--   (r2, m2, l2) there are three cases:
--   
--   <ul>
--   <li>If l1 == r2 then the [s from the left and ]s from the right
--   exactly cancel, and we are left with (r1, m1 &lt;&gt; m2, l2).</li>
--   <li>If l1 &lt; r2 then all of the [s cancel with some of the ]s, but
--   m1 is still inside the remaining ]s and is deleted, yielding (r1 + r2
--   - l1, m2, l2)</li>
--   <li>The remaining case is symmetric with the second.</li>
--   </ul>
data Deletable m
Deletable :: Int -> m -> Int -> Deletable m

-- | Project the wrapped value out of a <a>Deletable</a> value.
unDelete :: Deletable m -> m

-- | Inject a value into a <a>Deletable</a> wrapper. Satisfies the property
--   
--   <pre>
--   unDelete . toDeletable === id
--   </pre>
toDeletable :: m -> Deletable m

-- | A "left bracket", which causes everything between it and the next
--   right bracket to be deleted.
deleteL :: Monoid m => Deletable m

-- | A "right bracket", denoting the end of the section that should be
--   deleted.
deleteR :: Monoid m => Deletable m
instance Functor Deletable
instance (Semigroup m, Monoid m) => Monoid (Deletable m)
instance Semigroup m => Semigroup (Deletable m)


-- | The <tt>Cut</tt> monoid transformer introduces "cut points" such that
--   all values between any two cut points are thrown away. That is,
--   
--   <pre>
--   a b c | d e | f g h i | j k  ==  a b c | j k
--   </pre>
module Data.Monoid.Cut

-- | A value of type <tt>Cut m</tt> is either a single <tt>m</tt>, or a
--   pair of <tt>m</tt>'s separated by a divider. The divider represents a
--   "cut point".
--   
--   <tt>Cut</tt> is similar to <a>Data.Monoid.Split</a>, but split keeps
--   only the rightmost divider and accumulates all values, whereas cut
--   always keeps the leftmost and rightmost divider, coalescing them into
--   one and throwing away all the information in between.
--   
--   <tt>Split</tt> uses the asymmetric constructor <tt>:|</tt>, and
--   <tt>Cut</tt> the symmetric constructor <tt>:||:</tt>, to emphasize the
--   inherent asymmetry of <tt>Split</tt> and symmetry of <tt>Cut</tt>.
--   <tt>Split</tt> keeps only the rightmost split and combines everything
--   on the left; <tt>Cut</tt> keeps the outermost splits and throws away
--   everything in between.
data Cut m
Uncut :: m -> Cut m
(:||:) :: m -> m -> Cut m

-- | A convenient name for <tt>mempty :||: mempty</tt>, so composing with
--   <tt>cut</tt> introduces a cut point. For example, <tt>Uncut a &lt;&gt;
--   cut &lt;&gt; Uncut b == a :||: b</tt>.
cut :: Monoid m => Cut m
instance Show m => Show (Cut m)
instance (Semigroup m, Monoid m) => Monoid (Cut m)
instance Semigroup m => Semigroup (Cut m)


-- | Monoid and semigroup actions.
module Data.Monoid.Action

-- | Type class for monoid (and semigroup) actions, where monoidal values
--   of type <tt>m</tt> "act" on values of another type <tt>s</tt>.
--   Instances are required to satisfy the laws
--   
--   <ul>
--   <li><pre>act mempty = id</pre></li>
--   <li><pre>act (m1 `<a>mappend</a>` m2) = act m1 . act m2</pre></li>
--   </ul>
--   
--   Semigroup instances are required to satisfy the second law but with
--   (<a>&lt;&gt;</a>) instead of <a>mappend</a>. Additionally, if the type
--   <tt>s</tt> has any algebraic structure, <tt>act m</tt> should be a
--   homomorphism. For example, if <tt>s</tt> is also a monoid we should
--   have <tt>act m mempty = mempty</tt> and <tt>act m (s1 `<a>mappend</a>`
--   s2) = (act m s1) `<a>mappend</a>` (act m s2)</tt>.
--   
--   By default, <tt>act = const id</tt>, so for a type <tt>M</tt> which
--   should have no action on anything, it suffices to write
--   
--   <pre>
--   instance Action M s
--   </pre>
--   
--   with no method implementations.
--   
--   It is a bit awkward dealing with instances of <tt>Action</tt>, since
--   it is a multi-parameter type class but we can't add any functional
--   dependencies---the relationship between monoids and the types on which
--   they act is truly many-to-many. In practice, this library has chosen
--   to have instance selection for <tt>Action</tt> driven by the
--   <i>first</i> type parameter. That is, you should never write an
--   instance of the form <tt>Action m SomeType</tt> since it will overlap
--   with instances of the form <tt>Action SomeMonoid t</tt>. Newtype
--   wrappers can be used to (awkwardly) get around this.
class Action m s where act = const id
act :: Action m s => m -> s -> s
instance Action (Endo a) a
instance Action m s => Action (Option m) s
instance Action () l


-- | The coproduct of two monoids.
module Data.Monoid.Coproduct

-- | <tt>m :+: n</tt> is the coproduct of monoids <tt>m</tt> and
--   <tt>n</tt>. Values of type <tt>m :+: n</tt> consist of alternating
--   lists of <tt>m</tt> and <tt>n</tt> values. The empty list is the
--   identity, and composition is list concatenation, with appropriate
--   combining of adjacent elements when possible.
data (:+:) m n

-- | Injection from the left monoid into a coproduct.
inL :: m -> m :+: n

-- | Injection from the right monoid into a coproduct.
inR :: n -> m :+: n

-- | Prepend a value from the left monoid.
mappendL :: m -> m :+: n -> m :+: n

-- | Prepend a value from the right monoid.
mappendR :: n -> m :+: n -> m :+: n

-- | <tt>killL</tt> takes a value in a coproduct monoid and sends all the
--   values from the left monoid to the identity.
killL :: Monoid n => m :+: n -> n

-- | <tt>killR</tt> takes a value in a coproduct monoid and sends all the
--   values from the right monoid to the identity.
killR :: Monoid m => m :+: n -> m

-- | Take a value from a coproduct monoid where the left monoid has an
--   action on the right, and "untangle" it into a pair of values. In
--   particular,
--   
--   <pre>
--   m1 &lt;&gt; n1 &lt;&gt; m2 &lt;&gt; n2 &lt;&gt; m3 &lt;&gt; n3 &lt;&gt; ...
--   </pre>
--   
--   is sent to
--   
--   <pre>
--   (m1 &lt;&gt; m2 &lt;&gt; m3 &lt;&gt; ..., (act m1 n1) &lt;&gt; (act (m1 &lt;&gt; m2) n2) &lt;&gt; (act (m1 &lt;&gt; m2 &lt;&gt; m3) n3) &lt;&gt; ...)
--   </pre>
--   
--   That is, before combining <tt>n</tt> values, every <tt>n</tt> value is
--   acted on by all the <tt>m</tt> values to its left.
untangle :: (Action m n, Monoid m, Monoid n) => m :+: n -> (m, n)
instance (Action m r, Action n r) => Action (m :+: n) r
instance Monoid (m :+: n)
instance Semigroup (m :+: n)


-- | Heterogeneous lists of monoids.
module Data.Monoid.MList
type (:::) a l = (Option a, l)
(*:) :: a -> l -> a ::: l

-- | Type class for heterogeneous monoidal lists, with a single method
--   allowing construction of an empty list.
class MList l
empty :: MList l => l

-- | The relation <tt>l :&gt;: a</tt> holds when <tt>a</tt> is the type of
--   an element in <tt>l</tt>. For example, <tt>(Char ::: Int ::: Bool :::
--   Nil) :&gt;: Int</tt>.
class (:>:) l a
inj :: :>: l a => a -> l
get :: :>: l a => l -> Option a
alt :: :>: l a => (Option a -> Option a) -> l -> l

-- | <tt>SM</tt>, an abbreviation for "single monoid" (as opposed to a
--   heterogeneous list of monoids), is only used internally to help guide
--   instance selection when defining the action of heterogeneous monoidal
--   lists on each other.
newtype SM m
SM :: m -> SM m
instance [overlap ok] (Action a a', Action (SM a) l) => Action (SM a) (Option a', l)
instance [overlap ok] Action (SM a) ()
instance [overlap ok] (Action (SM a) l2, Action l1 l2) => Action (a, l1) l2
instance [overlap ok] t :>: a => (b ::: t) :>: a
instance [overlap ok] MList t => (a ::: t) :>: a
instance [overlap ok] MList l => MList (a ::: l)
instance [overlap ok] MList ()


-- | Sometimes we want to accumulate values from some monoid, but have the
--   ability to introduce a "split" which separates values on either side.
--   Only the rightmost split is kept. For example,
--   
--   <pre>
--   a b c | d e | f g h == a b c d e | f g h
--   </pre>
--   
--   In the diagrams graphics framework this is used when accumulating
--   transformations to be applied to primitive diagrams: the
--   <tt>freeze</tt> operation introduces a split, since only
--   transformations occurring outside the freeze should be applied to
--   attributes.
module Data.Monoid.Split

-- | A value of type <tt>Split m</tt> is either a single <tt>m</tt>, or a
--   pair of <tt>m</tt>'s separated by a divider. Single <tt>m</tt>'s
--   combine as usual; single <tt>m</tt>'s combine with split values by
--   combining with the value on the appropriate side; when two split
--   values meet only the rightmost split is kept, with both the values
--   from the left split combining with the left-hand value of the right
--   split.
--   
--   <a>Data.Monoid.Cut</a> is similar, but uses a different scheme for
--   composition. <tt>Split</tt> uses the asymmetric constructor
--   <tt>:|</tt>, and <tt>Cut</tt> the symmetric constructor <tt>:||:</tt>,
--   to emphasize the inherent asymmetry of <tt>Split</tt> and symmetry of
--   <tt>Cut</tt>. <tt>Split</tt> keeps only the rightmost split and
--   combines everything on the left; <tt>Cut</tt> keeps the outermost
--   splits and throws away everything in between.
data Split m
M :: m -> Split m
(:|) :: m -> m -> Split m

-- | A convenient name for <tt>mempty :| mempty</tt>, so <tt>M a &lt;&gt;
--   split &lt;&gt; M b == a :| b</tt>.
split :: Monoid m => Split m

-- | "Unsplit" a split monoid value, combining the two values into one (or
--   returning the single value if there is no split).
unsplit :: Semigroup m => Split m -> m
instance Show m => Show (Split m)
instance Action m n => Action (Split m) n
instance (Semigroup m, Monoid m) => Monoid (Split m)
instance Semigroup m => Semigroup (Split m)
