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


-- | Ties the knot on data structures that reference each other by unique keys.
--   
--   Please see the README on GitHub at
--   <a>https://github.com/pkamenarsky/knit#readme</a>
@package knit
@version 0.2.0.0

module Generics.Eot.Datatype

-- | Type for meta information about ADTs.
data Datatype
Datatype :: String -> [Constructor] -> Datatype

-- | unqualified name of the type
[datatypeName] :: Datatype -> String
[constructors] :: Datatype -> [Constructor]
data Constructor
Constructor :: String -> Fields -> Constructor
[constructorName] :: Constructor -> String
[fields] :: Constructor -> Fields

-- | Type that represents meta information about fields of one constructor.
data Fields

-- | Record constructor, containing the list of the selector names.
Selectors :: [String] -> Fields

-- | Constructor with fields, but without selector names. The argument
--   gives the number of fields.
NoSelectors :: Int -> Fields

-- | Constructor without fields.
NoFields :: Fields
class GenericDatatype (a :: * -> *)
datatypeC :: GenericDatatype a => Proxy a -> Datatype
class GenericConstructors (a :: * -> *)
getConstructors :: GenericConstructors a => Proxy a -> [Constructor]
getFields :: GenericFields a => Proxy a -> Fields
class GenericFields (a :: * -> *)
getFieldsC :: GenericFields a => Proxy a -> [Maybe String]
getField :: forall c f. Selector c => Proxy (S1 c (Rec0 f)) -> Maybe String
instance GHC.Classes.Eq Generics.Eot.Datatype.Datatype
instance GHC.Show.Show Generics.Eot.Datatype.Datatype
instance GHC.Classes.Eq Generics.Eot.Datatype.Constructor
instance GHC.Show.Show Generics.Eot.Datatype.Constructor
instance GHC.Classes.Eq Generics.Eot.Datatype.Fields
instance GHC.Show.Show Generics.Eot.Datatype.Fields
instance (GHC.Generics.Constructor c, Generics.Eot.Datatype.GenericFields f) => Generics.Eot.Datatype.GenericConstructors (GHC.Generics.C1 c f)
instance (Generics.Eot.Datatype.GenericFields a, Generics.Eot.Datatype.GenericFields b) => Generics.Eot.Datatype.GenericFields (a GHC.Generics.:*: b)
instance GHC.Generics.Selector c => Generics.Eot.Datatype.GenericFields (GHC.Generics.S1 c (GHC.Generics.Rec0 f))
instance Generics.Eot.Datatype.GenericFields GHC.Generics.U1
instance (GHC.Generics.Datatype c, Generics.Eot.Datatype.GenericConstructors f) => Generics.Eot.Datatype.GenericDatatype (GHC.Generics.D1 c f)
instance (Generics.Eot.Datatype.GenericConstructors a, Generics.Eot.Datatype.GenericConstructors b) => Generics.Eot.Datatype.GenericConstructors (a GHC.Generics.:+: b)
instance Generics.Eot.Datatype.GenericConstructors GHC.Generics.V1

module Generics.Eot.Eot
class HasEotG (a :: * -> *) where {
    type family EotG a :: *;
}
toEotG :: HasEotG a => a x -> EotG a
fromEotG :: HasEotG a => EotG a -> a x
data Named (a :: Symbol) field
Named :: field -> Named field
instance GHC.Show.Show field => GHC.Show.Show (Generics.Eot.Eot.Unnamed field)
instance GHC.Show.Show field => GHC.Show.Show (Generics.Eot.Eot.Named a field)
instance (Generics.Eot.Eot.HasFieldsG a, Generics.Eot.Eot.HasFieldsG b, Generics.Eot.Eot.Concat (Generics.Eot.Eot.Fields a) (Generics.Eot.Eot.Fields b)) => Generics.Eot.Eot.HasFieldsG (a GHC.Generics.:*: b)
instance Generics.Eot.Eot.Concat as bs => Generics.Eot.Eot.Concat (a, as) bs
instance Generics.Eot.Eot.Concat () bs
instance Generics.Eot.Eot.HasFieldsG (GHC.Generics.S1 ('GHC.Generics.MetaSel 'GHC.Maybe.Nothing x y z) (GHC.Generics.Rec0 f))
instance GHC.TypeLits.KnownSymbol name => Generics.Eot.Eot.HasFieldsG (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just name) x y z) (GHC.Generics.Rec0 f))
instance Generics.Eot.Eot.HasFieldsG f => Generics.Eot.Eot.HasConstructorsG (GHC.Generics.C1 c f)
instance Generics.Eot.Eot.HasFieldsG GHC.Generics.U1
instance (Generics.Eot.Eot.HasConstructorsG a, Generics.Eot.Eot.HasConstructorsG b, Generics.Eot.Eot.Normalize (Generics.Eot.Eot.Constructors a) (Generics.Eot.Eot.Constructors b)) => Generics.Eot.Eot.HasConstructorsG (a GHC.Generics.:+: b)
instance Generics.Eot.Eot.Normalize b c => Generics.Eot.Eot.Normalize (Data.Either.Either a b) c
instance Generics.Eot.Eot.Normalize Data.Void.Void b
instance Generics.Eot.Eot.HasConstructorsG f => Generics.Eot.Eot.HasEotG (GHC.Generics.D1 c f)
instance Generics.Eot.Eot.HasConstructorsG GHC.Generics.V1


-- | <tt>generics-eot</tt> tries to be a library for datatype generic
--   programming that is easy to understand. "eot" stands for "eithers of
--   tuples".
--   
--   A tutorial on how to use <tt>generics-eot</tt> can be found here:
--   <a>https://generics-eot.readthedocs.io/</a>.
module Generics.Eot

-- | An instance (<tt><a>HasEot</a> a</tt>) allows us to
--   
--   <ul>
--   <li>convert values of an arbitrary algebraic datatype <tt>a</tt> to
--   and from a generic representation (<tt><a>Eot</a> a</tt>) (see
--   <a>toEot</a> and <a>fromEot</a>).</li>
--   <li>extract meta information about the type <tt>a</tt> (see
--   <a>datatype</a>).</li>
--   </ul>
--   
--   Once an algebraic datatype has an instance for <a>Generic</a> it
--   automatically gets one for <a>HasEot</a>.
class HasEot a where {
    
    -- | <a>Eot</a> is a type level function that maps arbitrary ADTs to
    --   isomorphic generic representations. Here's an example:
    --   
    --   <pre>
    --   data Foo = A Int Bool | B String
    --   </pre>
    --   
    --   would be mapped to:
    --   
    --   <pre>
    --   Either (Int, (Bool, ())) (Either (String, ()) Void)
    --   </pre>
    --   
    --   These representations follow these rules:
    --   
    --   <ul>
    --   <li>The choice between constructors is mapped to right-nested
    --   <a>Either</a>s.</li>
    --   <li>There's always a so-called end-marker <a>Void</a>. It's an invalid
    --   choice (and <a>Void</a> is uninhabited to make sure you don't
    --   accidentally create such a value). So e.g. <tt>data Foo = A</tt> would
    --   be mapped to <tt>Either () Void</tt>, and a type with no constructors
    --   is mapped to <tt>Void</tt>.</li>
    --   <li>The fields of one constructor are mapped to right-nested
    --   tuples.</li>
    --   <li>Again there's always an end-marker, this time of type <tt>()</tt>.
    --   A constructor with three fields <tt>a</tt>, <tt>b</tt>, <tt>c</tt> is
    --   mapped to <tt>(a, (b, (c, ())))</tt>, one field <tt>a</tt> is mapped
    --   to <tt>(a, ())</tt>, and no fields are mapped to <tt>()</tt> (just the
    --   end-marker).</li>
    --   </ul>
    --   
    --   These rules (and the end-markers) are necessary to make sure generic
    --   functions know exactly which parts of the generic representation are
    --   field types and which parts belong to the generic skeleton.
    type family Eot a :: *;
}

-- | Convert a value of type <tt>a</tt> to its generic representation.
toEot :: HasEot a => a -> Eot a

-- | Convert a value in a generic representation to <tt>a</tt> (inverse of
--   <a>toEot</a>).
fromEot :: HasEot a => Eot a -> a

-- | Extract meta information about the ADT.
datatype :: HasEot a => Proxy a -> Datatype
data Named (a :: Symbol) field
Named :: field -> Named field

-- | Type for meta information about ADTs.
data Datatype
Datatype :: String -> [Constructor] -> Datatype

-- | unqualified name of the type
[datatypeName] :: Datatype -> String
[constructors] :: Datatype -> [Constructor]
data Constructor
Constructor :: String -> Fields -> Constructor
[constructorName] :: Constructor -> String
[fields] :: Constructor -> Fields

-- | Type that represents meta information about fields of one constructor.
data Fields

-- | Record constructor, containing the list of the selector names.
Selectors :: [String] -> Fields

-- | Constructor with fields, but without selector names. The argument
--   gives the number of fields.
NoSelectors :: Int -> Fields

-- | Constructor without fields.
NoFields :: Fields

-- | Representable types of kind <tt>*</tt>. This class is derivable in GHC
--   with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from</a> . <a>to</a> ≡ <tt>id</tt>
--   <a>to</a> . <a>from</a> ≡ <tt>id</tt>
--   </pre>
class Generic a

-- | <a>Proxy</a> is a type that holds no data, but has a phantom parameter
--   of arbitrary type (or even kind). Its use is to provide type
--   information, even though there is no value available of that type (or
--   it may be too costly to create one).
--   
--   Historically, <tt><a>Proxy</a> :: <a>Proxy</a> a</tt> is a safer
--   alternative to the <tt>'undefined :: a'</tt> idiom.
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy (Void, Int -&gt; Int)
--   Proxy
--   </pre>
--   
--   Proxy can even hold types of higher kinds,
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy Either
--   Proxy
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy Functor
--   Proxy
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy complicatedStructure
--   Proxy
--   </pre>
data Proxy (t :: k) :: forall k. () => k -> Type
Proxy :: Proxy

-- | Uninhabited data type
data Void

-- | Since <a>Void</a> values logically don't exist, this witnesses the
--   logical reasoning tool of "ex falso quodlibet".
--   
--   <pre>
--   &gt;&gt;&gt; let x :: Either Void Int; x = Right 5
--   
--   &gt;&gt;&gt; :{
--   case x of
--       Right r -&gt; r
--       Left l  -&gt; absurd l
--   :}
--   5
--   </pre>
absurd :: () => Void -> a
instance (GHC.Generics.Generic a, Generics.Eot.ImpliedByGeneric a c f) => Generics.Eot.HasEot a