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


-- | Boring and Absurd types
--   
--   <ul>
--   <li><tt>Boring</tt> types are isomorphic to <tt>()</tt>.</li>
--   <li><tt>Absurd</tt> types are isomorphic to <tt>Void</tt>.</li>
--   </ul>
--   
--   See <a>What does () mean in Haskell -answer by Conor McBride</a>
@package boring
@version 0.2


-- | <a>Boring</a> and <a>Absurd</a> classes. One approach.
--   
--   Different approach would be to have
--   
--   <pre>
--   -- none-one-tons semiring
--   data NOT = None | One | Tons
--   
--   type family Cardinality (a :: *) :: NOT
--   
--   class Cardinality a ~ None =&gt; Absurd a where ...
--   class Cardinality a ~ One  =&gt; Boring a where ...
--   </pre>
--   
--   This would make possible to define more instances, e.g.
--   
--   <pre>
--   instance (Mult (Cardinality a) (Cardinality b) ~ None) =&gt; Absurd (a, b) where ...
--   </pre>
--   
--   <h3>Functions</h3>
--   
--   Function is an exponential:
--   
--   <pre>
--   Cardinality (a -&gt; b) ~ Exponent (Cardinality b) (Cardinality a)
--   </pre>
--   
--   or shortly <tt>|a -&gt; b| = |b| ^ |a|</tt>. This gives us possible
--   instances:
--   
--   <ul>
--   <li><tt>|a| = 0 =&gt; |a -&gt; b| = m ^ 0 = 1</tt>, i.e.
--   <tt><a>Absurd</a> a =&gt; <a>Boring</a> (a -&gt; b)</tt>, or</li>
--   <li><tt>|b| = 1 =&gt; |a -&gt; b| = 1 ^ n = 1</tt>, i.e.
--   <tt><a>Boring</a> b =&gt; <a>Boring</a> (a -&gt; b)</tt>.</li>
--   </ul>
--   
--   Both instances are <a>Boring</a>, but we chose to define the latter.
--   
--   <h3>Note about adding instances</h3>
--   
--   At this moment this module misses a lot of instances, please make a
--   patch to add more. Especially, if the package is already in the
--   transitive dependency closure.
--   
--   E.g. any possibly empty container <tt>f</tt> has <tt><a>Absurd</a> a
--   =&gt; <a>Boring</a> (f a)</tt>
module Data.Boring

-- | <a>Boring</a> types which contains one thing, also <a>boring</a>.
--   There is nothing interesting to be gained by comparing one element of
--   the boring type with another, because there is nothing to learn about
--   an element of the boring type by giving it any of your attention.
--   
--   <i>Boring Law:</i>
--   
--   <pre>
--   <a>boring</a> == x
--   </pre>
--   
--   <i>Note:</i> This is different class from <tt>Default</tt>.
--   <tt>Default</tt> gives you <i>some</i> value, <tt>Boring</tt> gives
--   you an unique value.
--   
--   Also note, that we cannot have instances for e.g. <a>Either</a>, as
--   both <tt>(<a>Boring</a> a, <a>Absurd</a> b) =&gt; Either a b</tt> and
--   <tt>(<a>Absurd</a> a, <a>Boring</a> b) =&gt; Either a b</tt> would be
--   valid instances.
--   
--   Another useful trick, is that you can rewrite computations with
--   <a>Boring</a> results, for example <tt>foo :: Int -&gt; ()</tt>,
--   <b>if</b> you are sure that <tt>foo</tt> is <b>total</b>.
--   
--   <pre>
--   {-# RULES "less expensive" foo = boring #-}
--   </pre>
--   
--   That's particularly useful with equality <tt>:~:</tt> proofs.
class Boring a
boring :: Boring a => a
boring :: (Boring a, Generic a, GBoring (Rep a)) => a

-- | The <a>Absurd</a> type is very exciting, because if somebody ever
--   gives you a value belonging to it, you know that you are already dead
--   and in Heaven and that anything you want is yours.
--   
--   Similarly as there are many <a>Boring</a> sums, there are many
--   <a>Absurd</a> products, so we don't have <a>Absurd</a> instances for
--   tuples.
class Absurd a
absurd :: Absurd a => a -> b
absurd :: (Absurd a, Generic a, GAbsurd (Rep a)) => a -> b

-- | A helper class to implement <a>Generic</a> derivation of
--   <a>Boring</a>.
--   
--   Technically we could do (avoiding <tt>QuantifiedConstraints</tt>):
--   
--   <pre>
--   type GBoring f = (Boring (f V.Void), Functor f)
--   
--   gboring :: forall f x. GBoring f =&gt; f x
--   gboring = vacuous (boring :: f V.Void)
--   </pre>
--   
--   but separate class is cleaner.
--   
--   <pre>
--   &gt;&gt;&gt; data B2 = B2 () () deriving (Show, Generic)
--   
--   &gt;&gt;&gt; instance Boring B2
--   
--   &gt;&gt;&gt; boring :: B2
--   B2 () ()
--   </pre>
class GBoring f

-- | A helper class to implement of <a>Generic</a> derivation of
--   <a>Absurd</a>.
--   
--   <pre>
--   type GAbsurd f = (Absurd (f ()), Functor f)
--   
--   gabsurd :: forall f x y. GAbsurd f =&gt; f x -&gt; y
--   gabsurd = absurd . void
--   </pre>
class GAbsurd f

-- | If <a>Absurd</a> is uninhabited then any <a>Functor</a> that holds
--   only values of type <a>Absurd</a> is holding no values.
vacuous :: (Functor f, Absurd a) => f a -> f b

-- | There is a field for every type in the <a>Absurd</a>. Very zen.
--   
--   <pre>
--   <a>devoid</a> :: <a>Absurd</a> s =&gt; Over p f s s a b
--   </pre>
--   
--   type Over p f s t a b = p a (f b) -&gt; s -&gt; f t
devoid :: Absurd s => p a (f b) -> s -> f s

-- | We can always retrieve a <a>Boring</a> value from any type.
--   
--   <pre>
--   <a>united</a> :: <a>Boring</a> a =&gt; Lens' s a
--   </pre>
united :: (Boring a, Functor f) => (a -> f a) -> s -> f s
instance Data.Boring.Absurd a => Data.Boring.Boring [a]
instance Data.Boring.Absurd a => Data.Boring.Boring (GHC.Maybe.Maybe a)
instance Data.Boring.Absurd Data.Void.Void
instance (Data.Boring.Absurd a, Data.Boring.Absurd b) => Data.Boring.Absurd (Data.Either.Either a b)
instance Data.Boring.Absurd a => Data.Boring.Absurd (GHC.Base.NonEmpty a)
instance Data.Boring.Absurd a => Data.Boring.Absurd (Data.Functor.Identity.Identity a)
instance Data.Boring.Absurd (f (g a)) => Data.Boring.Absurd (Data.Functor.Compose.Compose f g a)
instance (Data.Boring.Absurd (f a), Data.Boring.Absurd (g a)) => Data.Boring.Absurd (Data.Functor.Sum.Sum f g a)
instance Data.Boring.Absurd b => Data.Boring.Absurd (Data.Functor.Const.Const b a)
instance Data.Boring.Absurd a => Data.Boring.Absurd (Data.Tagged.Tagged b a)
instance Data.Boring.Absurd (GHC.Generics.V1 p)
instance Data.Boring.Absurd c => Data.Boring.Absurd (GHC.Generics.K1 i c p)
instance Data.Boring.Absurd (f p) => Data.Boring.Absurd (GHC.Generics.M1 i c f p)
instance (Data.Boring.Absurd (f p), Data.Boring.Absurd (g p)) => Data.Boring.Absurd ((GHC.Generics.:+:) f g p)
instance Data.Boring.Absurd p => Data.Boring.Absurd (GHC.Generics.Par1 p)
instance Data.Boring.Absurd (f p) => Data.Boring.Absurd (GHC.Generics.Rec1 f p)
instance Data.Boring.Absurd (f (g p)) => Data.Boring.Absurd ((GHC.Generics.:.:) f g p)
instance Data.Boring.Absurd c => Data.Boring.GAbsurd (GHC.Generics.K1 i c)
instance Data.Boring.GAbsurd GHC.Generics.V1
instance Data.Boring.GAbsurd f => Data.Boring.GAbsurd (GHC.Generics.M1 i c f)
instance (Data.Boring.GAbsurd f, Data.Boring.GAbsurd g) => Data.Boring.GAbsurd (f GHC.Generics.:+: g)
instance Data.Boring.Boring ()
instance Data.Boring.Boring b => Data.Boring.Boring (a -> b)
instance Data.Boring.Boring (Data.Proxy.Proxy a)
instance Data.Boring.Boring a => Data.Boring.Boring (Data.Functor.Const.Const a b)
instance Data.Boring.Boring b => Data.Boring.Boring (Data.Tagged.Tagged a b)
instance Data.Boring.Boring a => Data.Boring.Boring (Data.Functor.Identity.Identity a)
instance Data.Boring.Boring (f (g a)) => Data.Boring.Boring (Data.Functor.Compose.Compose f g a)
instance (Data.Boring.Boring (f a), Data.Boring.Boring (g a)) => Data.Boring.Boring (Data.Functor.Product.Product f g a)
instance (Data.Boring.Boring a, Data.Boring.Boring b) => Data.Boring.Boring (a, b)
instance (Data.Boring.Boring a, Data.Boring.Boring b, Data.Boring.Boring c) => Data.Boring.Boring (a, b, c)
instance (Data.Boring.Boring a, Data.Boring.Boring b, Data.Boring.Boring c, Data.Boring.Boring d) => Data.Boring.Boring (a, b, c, d)
instance (Data.Boring.Boring a, Data.Boring.Boring b, Data.Boring.Boring c, Data.Boring.Boring d, Data.Boring.Boring e) => Data.Boring.Boring (a, b, c, d, e)
instance (a GHC.Types.~ b) => Data.Boring.Boring (a Data.Type.Equality.:~: b)
instance (a ~ b) => Data.Boring.Boring (a Data.Type.Equality.:~~: b)
instance Data.Typeable.Internal.Typeable a => Data.Boring.Boring (Data.Typeable.Internal.TypeRep a)
instance Data.Boring.Boring (GHC.Generics.U1 p)
instance Data.Boring.Boring c => Data.Boring.Boring (GHC.Generics.K1 i c p)
instance Data.Boring.Boring (f p) => Data.Boring.Boring (GHC.Generics.M1 i c f p)
instance (Data.Boring.Boring (f p), Data.Boring.Boring (g p)) => Data.Boring.Boring ((GHC.Generics.:*:) f g p)
instance Data.Boring.Boring p => Data.Boring.Boring (GHC.Generics.Par1 p)
instance Data.Boring.Boring (f p) => Data.Boring.Boring (GHC.Generics.Rec1 f p)
instance Data.Boring.Boring (f (g p)) => Data.Boring.Boring ((GHC.Generics.:.:) f g p)
instance Data.Boring.Boring c => Data.Boring.GBoring (GHC.Generics.K1 i c)
instance Data.Boring.GBoring GHC.Generics.U1
instance Data.Boring.GBoring f => Data.Boring.GBoring (GHC.Generics.M1 i c f)
instance (Data.Boring.GBoring f, Data.Boring.GBoring g) => Data.Boring.GBoring (f GHC.Generics.:*: g)