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


-- | Functions to desugar Template Haskell
--   
--   This package provides the Language.Haskell.TH.Desugar module, which
--   desugars Template Haskell's rich encoding of Haskell syntax into a
--   simpler encoding. This desugaring discards surface syntax information
--   (such as the use of infix operators) but retains the original meaning
--   of the TH code. The intended use of this package is as a preprocessor
--   for more advanced code manipulation tools. Note that the input to any
--   of the ds... functions should be produced from a TH quote, using the
--   syntax [| ... |]. If the input to these functions is a hand-coded TH
--   syntax tree, the results may be unpredictable. In particular, it is
--   likely that promoted datatypes will not work as expected.
@package th-desugar
@version 1.14


-- | An <a>OMap</a> behaves much like a <a>Map</a>, with all the same
--   asymptotics, but also remembers the order that keys were inserted.
--   
--   This module offers a simplified version of the <a>Data.Map.Ordered</a>
--   API that assumes left-biased indices everywhere and uses a different
--   <a>Semigroup</a> instance (the one in this module uses
--   <tt>(<a>&lt;&gt;</a>) = <a>union</a></tt>) and <a>Monoid</a> instance
--   (the one in this module uses <tt><a>mappend</a> = <a>union</a></tt>).
module Language.Haskell.TH.Desugar.OMap

-- | An ordered map whose <a>insertPre</a>, <a>insertPost</a>,
--   <a>intersection</a>, <a>intersectionWithKey</a>, <a>union</a>, and
--   <a>unionWithKey</a> operations are biased towards leftmost indices
--   when when breaking ties between keys.
newtype OMap k v
OMap :: Bias L (OMap k v) -> OMap k v
empty :: forall k v. OMap k v
singleton :: k -> v -> OMap k v

-- | The value's index will be lower than the indices of the values in the
--   <tt>OSet</tt>.
insertPre :: Ord k => k -> v -> OMap k v -> OMap k v

-- | The value's index will be higher than the indices of the values in the
--   <tt>OSet</tt>.
insertPost :: Ord k => OMap k v -> k -> v -> OMap k v
union :: forall k v. Ord k => OMap k v -> OMap k v -> OMap k v
unionWithKey :: Ord k => (k -> v -> v -> v) -> OMap k v -> OMap k v -> OMap k v
delete :: forall k v. Ord k => k -> OMap k v -> OMap k v
filterWithKey :: Ord k => (k -> v -> Bool) -> OMap k v -> OMap k v
(\\) :: forall k v v'. Ord k => OMap k v -> OMap k v' -> OMap k v
intersection :: forall k v v'. Ord k => OMap k v -> OMap k v' -> OMap k v
intersectionWithKey :: Ord k => (k -> v -> v' -> v'') -> OMap k v -> OMap k v' -> OMap k v''
null :: forall k v. OMap k v -> Bool
size :: forall k v. OMap k v -> Int
member :: forall k v. Ord k => k -> OMap k v -> Bool
notMember :: forall k v. Ord k => k -> OMap k v -> Bool
lookup :: forall k v. Ord k => k -> OMap k v -> Maybe v

-- | A 0-based index, much like the indices used by lists' <a>!!</a>
--   operation. All indices are with respect to insertion order.
type Index = Int
lookupIndex :: forall k v. Ord k => k -> OMap k v -> Maybe Index
lookupAt :: forall k v. Index -> OMap k v -> Maybe (k, v)
fromList :: Ord k => [(k, v)] -> OMap k v
assocs :: forall k v. OMap k v -> [(k, v)]
toAscList :: forall k v. OMap k v -> [(k, v)]
toMap :: forall k v. OMap k v -> Map k v
instance GHC.Classes.Ord k => Data.Traversable.Traversable (Language.Haskell.TH.Desugar.OMap.OMap k)
instance (GHC.Show.Show k, GHC.Show.Show v) => GHC.Show.Show (Language.Haskell.TH.Desugar.OMap.OMap k v)
instance (GHC.Classes.Ord k, GHC.Read.Read k, GHC.Read.Read v) => GHC.Read.Read (Language.Haskell.TH.Desugar.OMap.OMap k v)
instance (GHC.Classes.Ord k, GHC.Classes.Ord v) => GHC.Classes.Ord (Language.Haskell.TH.Desugar.OMap.OMap k v)
instance (GHC.Classes.Eq k, GHC.Classes.Eq v) => GHC.Classes.Eq (Language.Haskell.TH.Desugar.OMap.OMap k v)
instance GHC.Base.Functor (Language.Haskell.TH.Desugar.OMap.OMap k)
instance Data.Foldable.Foldable (Language.Haskell.TH.Desugar.OMap.OMap k)
instance (Data.Data.Data k, Data.Data.Data v, GHC.Classes.Ord k) => Data.Data.Data (Language.Haskell.TH.Desugar.OMap.OMap k v)
instance GHC.Classes.Ord k => GHC.Base.Semigroup (Language.Haskell.TH.Desugar.OMap.OMap k v)
instance GHC.Classes.Ord k => GHC.Base.Monoid (Language.Haskell.TH.Desugar.OMap.OMap k v)


-- | An <a>OMap</a> behaves much like a <a>Map</a>, with all the same
--   asymptotics, but also remembers the order that keys were inserted.
--   
--   This module offers a simplified version of the
--   <a>Data.Map.Ordered.Strict</a> API that assumes left-biased indices
--   everywhere and uses a different <a>Semigroup</a> instance (the one in
--   this module uses <tt>(<a>&lt;&gt;</a>) = <a>union</a></tt>) and
--   <a>Monoid</a> instance (the one in this module uses <tt><a>mappend</a>
--   = <a>union</a></tt>).
module Language.Haskell.TH.Desugar.OMap.Strict

-- | An ordered map whose <a>insertPre</a>, <a>insertPost</a>,
--   <a>intersection</a>, <a>intersectionWithKey</a>, <a>union</a>, and
--   <a>unionWithKey</a> operations are biased towards leftmost indices
--   when when breaking ties between keys.
newtype OMap k v
OMap :: Bias L (OMap k v) -> OMap k v
empty :: forall k v. OMap k v
singleton :: k -> v -> OMap k v

-- | The value's index will be lower than the indices of the values in the
--   <tt>OSet</tt>.
insertPre :: Ord k => k -> v -> OMap k v -> OMap k v

-- | The value's index will be higher than the indices of the values in the
--   <tt>OSet</tt>.
insertPost :: Ord k => OMap k v -> k -> v -> OMap k v
union :: forall k v. Ord k => OMap k v -> OMap k v -> OMap k v
unionWithKey :: Ord k => (k -> v -> v -> v) -> OMap k v -> OMap k v -> OMap k v
delete :: forall k v. Ord k => k -> OMap k v -> OMap k v
filterWithKey :: Ord k => (k -> v -> Bool) -> OMap k v -> OMap k v
(\\) :: forall k v v'. Ord k => OMap k v -> OMap k v' -> OMap k v
intersection :: forall k v v'. Ord k => OMap k v -> OMap k v' -> OMap k v
intersectionWithKey :: Ord k => (k -> v -> v' -> v'') -> OMap k v -> OMap k v' -> OMap k v''
null :: forall k v. OMap k v -> Bool
size :: forall k v. OMap k v -> Int
member :: forall k v. Ord k => k -> OMap k v -> Bool
notMember :: forall k v. Ord k => k -> OMap k v -> Bool
lookup :: forall k v. Ord k => k -> OMap k v -> Maybe v

-- | A 0-based index, much like the indices used by lists' <a>!!</a>
--   operation. All indices are with respect to insertion order.
type Index = Int
lookupIndex :: forall k v. Ord k => k -> OMap k v -> Maybe Index
lookupAt :: forall k v. Index -> OMap k v -> Maybe (k, v)
fromList :: Ord k => [(k, v)] -> OMap k v
assocs :: forall k v. OMap k v -> [(k, v)]
toAscList :: forall k v. OMap k v -> [(k, v)]
toMap :: forall k v. OMap k v -> Map k v


-- | An <a>OSet</a> behaves much like a <a>Set</a>, with all the same
--   asymptotics, but also remembers the order that values were inserted.
--   
--   This module offers a simplified version of the <a>Data.Set.Ordered</a>
--   API that assumes left-biased indices everywhere.
module Language.Haskell.TH.Desugar.OSet

-- | An ordered set whose <a>insertPre</a>, <a>insertPost</a>,
--   <a>intersection</a>, and <a>union</a> operations are biased towards
--   leftmost indices when when breaking ties between keys.
data OSet a
empty :: forall a. OSet a
singleton :: a -> OSet a

-- | The element's index will be lower than the indices of the elements in
--   the <a>OSet</a>.
insertPre :: Ord a => a -> OSet a -> OSet a

-- | The element's index will be higher than the indices of the elements in
--   the <a>OSet</a>.
insertPost :: Ord a => OSet a -> a -> OSet a
union :: forall a. Ord a => OSet a -> OSet a -> OSet a
null :: forall a. OSet a -> Bool
size :: forall a. OSet a -> Int
member :: Ord a => a -> OSet a -> Bool
notMember :: Ord a => a -> OSet a -> Bool
delete :: Ord a => a -> OSet a -> OSet a
filter :: Ord a => (a -> Bool) -> OSet a -> OSet a
(\\) :: forall a. Ord a => OSet a -> OSet a -> OSet a
intersection :: forall a. Ord a => OSet a -> OSet a -> OSet a

-- | A 0-based index, much like the indices used by lists' <a>!!</a>
--   operation. All indices are with respect to insertion order.
type Index = Int
lookupIndex :: Ord a => a -> OSet a -> Maybe Index
lookupAt :: forall a. Index -> OSet a -> Maybe a
fromList :: Ord a => [a] -> OSet a
toAscList :: forall a. OSet a -> [a]
toSet :: forall a. OSet a -> Set a
instance GHC.Show.Show a => GHC.Show.Show (Language.Haskell.TH.Desugar.OSet.OSet a)
instance (GHC.Classes.Ord a, GHC.Read.Read a) => GHC.Read.Read (Language.Haskell.TH.Desugar.OSet.OSet a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Language.Haskell.TH.Desugar.OSet.OSet a)
instance GHC.Classes.Ord a => GHC.Base.Monoid (Language.Haskell.TH.Desugar.OSet.OSet a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Language.Haskell.TH.Desugar.OSet.OSet a)
instance Data.Foldable.Foldable Language.Haskell.TH.Desugar.OSet.OSet
instance (Data.Data.Data a, GHC.Classes.Ord a) => Data.Data.Data (Language.Haskell.TH.Desugar.OSet.OSet a)
instance GHC.Classes.Ord a => GHC.Base.Semigroup (Language.Haskell.TH.Desugar.OSet.OSet a)


-- | Capture-avoiding substitutions on <a>DType</a>s
module Language.Haskell.TH.Desugar.Subst

-- | A substitution is just a map from names to types
type DSubst = Map Name DType

-- | Capture-avoiding substitution on types
substTy :: Quasi q => DSubst -> DType -> q DType
substForallTelescope :: Quasi q => DSubst -> DForallTelescope -> q (DSubst, DForallTelescope)
substTyVarBndrs :: Quasi q => DSubst -> [DTyVarBndr flag] -> q (DSubst, [DTyVarBndr flag])

-- | Computes the union of two substitutions. Fails if both subsitutions
--   map the same variable to different types.
unionSubsts :: DSubst -> DSubst -> Maybe DSubst
unionMaybeSubsts :: [Maybe DSubst] -> Maybe DSubst

-- | Ignore kind annotations in <tt>matchTy</tt>?
data IgnoreKinds
YesIgnore :: IgnoreKinds
NoIgnore :: IgnoreKinds

-- | <tt>matchTy ign tmpl targ</tt> matches a type template <tt>tmpl</tt>
--   against a type target <tt>targ</tt>. This returns a Map from names of
--   type variables in the type template to types if the types indeed match
--   up, or <tt>Nothing</tt> otherwise. In the <tt>Just</tt> case, it is
--   guaranteed that every type variable mentioned in the template is
--   mapped by the returned substitution.
--   
--   The first argument <tt>ign</tt> tells <tt>matchTy</tt> whether to
--   ignore kind signatures in the template. A kind signature in the
--   template might mean that a type variable has a more restrictive kind
--   than otherwise possible, and that mapping that type variable to a type
--   of a different kind could be disastrous. So, if we don't ignore kind
--   signatures, this function returns <tt>Nothing</tt> if the template has
--   a signature anywhere. If we do ignore kind signatures, it's possible
--   the returned map will be ill-kinded. Use at your own risk.
matchTy :: IgnoreKinds -> DType -> DType -> Maybe DSubst


-- | The functions in this module convert desugared Template Haskell back
--   into proper Template Haskell.
module Language.Haskell.TH.Desugar.Sweeten
expToTH :: DExp -> Exp
matchToTH :: DMatch -> Match
patToTH :: DPat -> Pat
decsToTH :: [DDec] -> [Dec]

-- | This returns a list of <tt>Dec</tt>s because GHC 7.6.3 does not have a
--   one-to-one mapping between <a>DDec</a> and <tt>Dec</tt>.
decToTH :: DDec -> Dec

-- | Sweeten a <a>DLetDec</a>.
letDecToTH :: DLetDec -> Dec
typeToTH :: DType -> Type
conToTH :: DCon -> Con
foreignToTH :: DForeign -> Foreign
pragmaToTH :: DPragma -> Pragma
ruleBndrToTH :: DRuleBndr -> RuleBndr
clauseToTH :: DClause -> Clause
tvbToTH :: DTyVarBndr flag -> TyVarBndr_ flag
cxtToTH :: DCxt -> Cxt
predToTH :: DPred -> Pred
derivClauseToTH :: DDerivClause -> [DerivClause]
patSynDirToTH :: DPatSynDir -> PatSynDir
typeArgToTH :: DTypeArg -> TypeArg


-- | Expands type synonyms and type families in desugared types. See also
--   the package th-expand-syns for doing this to non-desugared types.
module Language.Haskell.TH.Desugar.Expand

-- | Expand all type synonyms and type families in the desugared abstract
--   syntax tree provided, where type family simplification is on a "best
--   effort" basis. Normally, the first parameter should have a type like
--   <a>DExp</a> or <a>DLetDec</a>.
expand :: (DsMonad q, Data a) => a -> q a

-- | Expands all type synonyms in a desugared type. Also expands open type
--   family applications. (In GHCs before 7.10, this part does not work if
--   there are any variables.) Attempts to expand closed type family
--   applications, but aborts the moment it spots anything strange, like a
--   nested type family application or type variable.
expandType :: DsMonad q => DType -> q DType

-- | Expand all type synonyms and type families in the desugared abstract
--   syntax tree provided, where type family simplification is on a "better
--   than best effort" basis. This means that it will try so hard that it
--   will sometimes do the wrong thing. Specifically, any kind parameters
--   to type families are ignored. So, if we have
--   
--   <pre>
--   type family F (x :: k) where
--     F (a :: *) = Int
--   </pre>
--   
--   <a>expandUnsoundly</a> will expand <tt>F 'True</tt> to <tt>Int</tt>,
--   ignoring that the expansion should only work for type of kind
--   <tt>*</tt>.
--   
--   This function is useful because plain old <a>expand</a> will simply
--   fail to expand type families that make use of kinds. Sometimes, the
--   kinds are benign and we want to expand anyway. Use this function in
--   that case.
expandUnsoundly :: (DsMonad q, Data a) => a -> q a


-- | Desugars full Template Haskell syntax into a smaller core syntax for
--   further processing.
module Language.Haskell.TH.Desugar

-- | Corresponds to TH's <tt>Exp</tt> type. Note that <tt>DLamE</tt> takes
--   names, not patterns.
data DExp
DVarE :: Name -> DExp
DConE :: Name -> DExp
DLitE :: Lit -> DExp
DAppE :: DExp -> DExp -> DExp
DAppTypeE :: DExp -> DType -> DExp
DLamE :: [Name] -> DExp -> DExp
DCaseE :: DExp -> [DMatch] -> DExp
DLetE :: [DLetDec] -> DExp -> DExp
DSigE :: DExp -> DType -> DExp
DStaticE :: DExp -> DExp

-- | Declarations as used in a <tt>let</tt> statement.
data DLetDec
DFunD :: Name -> [DClause] -> DLetDec
DValD :: DPat -> DExp -> DLetDec
DSigD :: Name -> DType -> DLetDec
DInfixD :: Fixity -> Name -> DLetDec
DPragmaD :: DPragma -> DLetDec

-- | Corresponds to TH's <tt>Pat</tt> type.
data DPat
DLitP :: Lit -> DPat
DVarP :: Name -> DPat
DConP :: Name -> [DType] -> [DPat] -> DPat
DTildeP :: DPat -> DPat
DBangP :: DPat -> DPat
DSigP :: DPat -> DType -> DPat
DWildP :: DPat

-- | Corresponds to TH's <tt>Type</tt> type, used to represent types and
--   kinds.
data DType
DForallT :: DForallTelescope -> DType -> DType
DConstrainedT :: DCxt -> DType -> DType
DAppT :: DType -> DType -> DType
DAppKindT :: DType -> DKind -> DType
DSigT :: DType -> DKind -> DType
DVarT :: Name -> DType
DConT :: Name -> DType
DArrowT :: DType
DLitT :: TyLit -> DType
DWildCardT :: DType

-- | The type variable binders in a <tt>forall</tt>.
data DForallTelescope

-- | A visible <tt>forall</tt> (e.g., <tt>forall a -&gt; {...}</tt>). These
--   do not have any notion of specificity, so we use <tt>()</tt> as a
--   placeholder value in the <a>DTyVarBndr</a>s.
DForallVis :: [DTyVarBndrUnit] -> DForallTelescope

-- | An invisible <tt>forall</tt> (e.g., <tt>forall a {b} c -&gt;
--   {...}</tt>), where each binder has a <a>Specificity</a>.
DForallInvis :: [DTyVarBndrSpec] -> DForallTelescope

-- | Kinds are types. Corresponds to TH's <tt>Kind</tt>
type DKind = DType

-- | Corresponds to TH's <tt>Cxt</tt>
type DCxt = [DPred]

-- | Predicates are types. Corresponds to TH's <tt>Pred</tt>
type DPred = DType

-- | Corresponds to TH's <tt>TyVarBndr</tt>
data DTyVarBndr flag
DPlainTV :: Name -> flag -> DTyVarBndr flag
DKindedTV :: Name -> flag -> DKind -> DTyVarBndr flag

-- | Corresponds to TH's <tt>TyVarBndrSpec</tt>
type DTyVarBndrSpec = DTyVarBndr Specificity

-- | Corresponds to TH's <tt>TyVarBndrUnit</tt>
type DTyVarBndrUnit = DTyVarBndr ()
data () => Specificity

-- | <pre>
--   a
--   </pre>
SpecifiedSpec :: Specificity

-- | <pre>
--   {a}
--   </pre>
InferredSpec :: Specificity

-- | Corresponds to TH's <tt>Match</tt> type.
data DMatch
DMatch :: DPat -> DExp -> DMatch

-- | Corresponds to TH's <tt>Clause</tt> type.
data DClause
DClause :: [DPat] -> DExp -> DClause

-- | Corresponds to TH's <tt>Dec</tt> type.
data DDec
DLetDec :: DLetDec -> DDec
DDataD :: NewOrData -> DCxt -> Name -> [DTyVarBndrUnit] -> Maybe DKind -> [DCon] -> [DDerivClause] -> DDec
DTySynD :: Name -> [DTyVarBndrUnit] -> DType -> DDec
DClassD :: DCxt -> Name -> [DTyVarBndrUnit] -> [FunDep] -> [DDec] -> DDec

-- | Note that the <tt>Maybe [DTyVarBndrUnit]</tt> field is dropped
--   entirely when sweetened, so it is only useful for functions that
--   directly consume <tt>DDec</tt>s.
DInstanceD :: Maybe Overlap -> Maybe [DTyVarBndrUnit] -> DCxt -> DType -> [DDec] -> DDec
DForeignD :: DForeign -> DDec
DOpenTypeFamilyD :: DTypeFamilyHead -> DDec
DClosedTypeFamilyD :: DTypeFamilyHead -> [DTySynEqn] -> DDec
DDataFamilyD :: Name -> [DTyVarBndrUnit] -> Maybe DKind -> DDec
DDataInstD :: NewOrData -> DCxt -> Maybe [DTyVarBndrUnit] -> DType -> Maybe DKind -> [DCon] -> [DDerivClause] -> DDec
DTySynInstD :: DTySynEqn -> DDec
DRoleAnnotD :: Name -> [Role] -> DDec

-- | Note that the <tt>Maybe [DTyVarBndrUnit]</tt> field is dropped
--   entirely when sweetened, so it is only useful for functions that
--   directly consume <tt>DDec</tt>s.
DStandaloneDerivD :: Maybe DDerivStrategy -> Maybe [DTyVarBndrUnit] -> DCxt -> DType -> DDec
DDefaultSigD :: Name -> DType -> DDec
DPatSynD :: Name -> PatSynArgs -> DPatSynDir -> DPat -> DDec
DPatSynSigD :: Name -> DPatSynType -> DDec
DKiSigD :: Name -> DKind -> DDec
DDefaultD :: [DType] -> DDec

-- | Corresponds to TH's <tt>DerivClause</tt> type.
data DDerivClause
DDerivClause :: Maybe DDerivStrategy -> DCxt -> DDerivClause

-- | Corresponds to TH's <tt>DerivStrategy</tt> type.
data DDerivStrategy

-- | A "standard" derived instance
DStockStrategy :: DDerivStrategy

-- | <pre>
--   -XDeriveAnyClass
--   </pre>
DAnyclassStrategy :: DDerivStrategy

-- | <pre>
--   -XGeneralizedNewtypeDeriving
--   </pre>
DNewtypeStrategy :: DDerivStrategy

-- | <pre>
--   -XDerivingVia
--   </pre>
DViaStrategy :: DType -> DDerivStrategy

-- | Corresponds to TH's <a>PatSynDir</a> type
data DPatSynDir

-- | <pre>
--   pattern P x {&lt;-} p
--   </pre>
DUnidir :: DPatSynDir

-- | <pre>
--   pattern P x {=} p
--   </pre>
DImplBidir :: DPatSynDir

-- | <pre>
--   pattern P x {&lt;-} p where P x = e
--   </pre>
DExplBidir :: [DClause] -> DPatSynDir

-- | Corresponds to TH's <a>PatSynType</a> type
type DPatSynType = DType

-- | Varieties of allowed instance overlap.
data () => Overlap

-- | May be overlapped by more specific instances
Overlappable :: Overlap

-- | May overlap a more general instance
Overlapping :: Overlap

-- | Both <a>Overlapping</a> and <a>Overlappable</a>
Overlaps :: Overlap

-- | Both <a>Overlapping</a> and <a>Overlappable</a>, and pick an arbitrary
--   one if multiple choices are available.
Incoherent :: Overlap

-- | A pattern synonym's argument type.
data () => PatSynArgs

-- | <pre>
--   pattern P {x y z} = p
--   </pre>
PrefixPatSyn :: [Name] -> PatSynArgs

-- | <pre>
--   pattern {x P y} = p
--   </pre>
InfixPatSyn :: Name -> Name -> PatSynArgs

-- | <pre>
--   pattern P { {x,y,z} } = p
--   </pre>
RecordPatSyn :: [Name] -> PatSynArgs

-- | Is it a <tt>newtype</tt> or a <tt>data</tt> type?
data NewOrData
Newtype :: NewOrData
Data :: NewOrData

-- | Corresponds to TH's <a>TypeFamilyHead</a> type
data DTypeFamilyHead
DTypeFamilyHead :: Name -> [DTyVarBndrUnit] -> DFamilyResultSig -> Maybe InjectivityAnn -> DTypeFamilyHead

-- | Corresponds to TH's <a>FamilyResultSig</a> type
data DFamilyResultSig
DNoSig :: DFamilyResultSig
DKindSig :: DKind -> DFamilyResultSig
DTyVarSig :: DTyVarBndrUnit -> DFamilyResultSig

-- | Injectivity annotation
data () => InjectivityAnn
InjectivityAnn :: Name -> [Name] -> InjectivityAnn

-- | Corresponds to TH's <a>Con</a> type. Unlike <a>Con</a>, all
--   <a>DCon</a>s reflect GADT syntax. This is beneficial for
--   <tt>th-desugar</tt>'s since it means that all data type declarations
--   can support explicit return kinds, so one does not need to represent
--   them with something like <tt><a>Maybe</a> <a>DKind</a></tt>, since
--   Haskell98-style data declaration syntax isn't used. Accordingly, there
--   are some differences between <a>DCon</a> and <a>Con</a> to keep in
--   mind:
--   
--   <ul>
--   <li>Unlike <a>ForallC</a>, where the meaning of the <a>TyVarBndr</a>s
--   changes depending on whether it's followed by
--   <a>GadtC</a>/<a>RecGadtC</a> or not, the meaning of the
--   <a>DTyVarBndr</a>s in a <a>DCon</a> is always the same: it is the list
--   of universally <i>and</i> existentially quantified type variables.
--   Note that it is not guaranteed that one set of type variables will
--   appear before the other.</li>
--   <li>A <a>DCon</a> always has an explicit return type.</li>
--   </ul>
data DCon

-- | The GADT result type
DCon :: [DTyVarBndrSpec] -> DCxt -> Name -> DConFields -> DType -> DCon

-- | A list of fields either for a standard data constructor or a record
--   data constructor.
data DConFields
DNormalC :: DDeclaredInfix -> [DBangType] -> DConFields
DRecC :: [DVarBangType] -> DConFields

-- | <a>True</a> if a constructor is declared infix. For normal ADTs, this
--   means that is was written in infix style. For example, both of the
--   constructors below are declared infix.
--   
--   <pre>
--   data Infix = Int <a>Fixity</a> Int | Int :*: Int
--   </pre>
--   
--   Whereas neither of these constructors are declared infix:
--   
--   <pre>
--   data Prefix = Prefix Int Int | (:+:) Int Int
--   </pre>
--   
--   For GADTs, detecting whether a constructor is declared infix is a bit
--   trickier, as one cannot write a GADT constructor "infix-style" like
--   one can for normal ADT constructors. GHC considers a GADT constructor
--   to be declared infix if it meets the following three criteria:
--   
--   <ol>
--   <li>Its name uses operator syntax (e.g., <tt>(:*:)</tt>).</li>
--   <li>It has exactly two fields (without record syntax).</li>
--   <li>It has a programmer-specified fixity declaration.</li>
--   </ol>
--   
--   For example, in the following GADT:
--   
--   <pre>
--   infixl 5 :**:, :&amp;&amp;:, :^^:, <tt>ActuallyPrefix</tt>
--   data InfixGADT a where
--     (:**:) :: Int -&gt; b -&gt; InfixGADT (Maybe b) -- Only this one is infix
--     ActuallyPrefix :: Char -&gt; Bool -&gt; InfixGADT Double
--     (:&amp;&amp;:) :: { infixGADT1 :: b, infixGADT2 :: Int } -&gt; InfixGADT <a>b</a> :: Int -&gt; Int -&gt; Int -&gt; InfixGADT Int
--     (:!!:) :: Char -&gt; Char -&gt; InfixGADT Char
--   </pre>
--   
--   Only the <tt>(:**:)</tt> constructor is declared infix. The other
--   constructors are not declared infix, because:
--   
--   <ul>
--   <li><tt>ActuallyPrefix</tt> does not use operator syntax (criterion
--   1).</li>
--   <li><tt>(:&amp;&amp;:)</tt> uses record syntax (criterion 2).</li>
--   <li><tt>(:^^:)</tt> does not have exactly two fields (criterion
--   2).</li>
--   <li><tt>(:!!:)</tt> does not have a programmer-specified fixity
--   declaration (criterion 3).</li>
--   </ul>
type DDeclaredInfix = Bool

-- | Corresponds to TH's <tt>BangType</tt> type.
type DBangType = (Bang, DType)

-- | Corresponds to TH's <tt>VarBangType</tt> type.
type DVarBangType = (Name, Bang, DType)
data () => Bang

-- | <pre>
--   C { {-# UNPACK #-} !}a
--   </pre>
Bang :: SourceUnpackedness -> SourceStrictness -> Bang
data () => SourceUnpackedness

-- | <pre>
--   C a
--   </pre>
NoSourceUnpackedness :: SourceUnpackedness

-- | <pre>
--   C { {-# NOUNPACK #-} } a
--   </pre>
SourceNoUnpack :: SourceUnpackedness

-- | <pre>
--   C { {-# UNPACK #-} } a
--   </pre>
SourceUnpack :: SourceUnpackedness
data () => SourceStrictness

-- | <pre>
--   C a
--   </pre>
NoSourceStrictness :: SourceStrictness

-- | <pre>
--   C {~}a
--   </pre>
SourceLazy :: SourceStrictness

-- | <pre>
--   C {!}a
--   </pre>
SourceStrict :: SourceStrictness

-- | Corresponds to TH's <tt>Foreign</tt> type.
data DForeign
DImportF :: Callconv -> Safety -> String -> Name -> DType -> DForeign
DExportF :: Callconv -> String -> Name -> DType -> DForeign

-- | Corresponds to TH's <tt>Pragma</tt> type.
data DPragma
DInlineP :: Name -> Inline -> RuleMatch -> Phases -> DPragma
DSpecialiseP :: Name -> DType -> Maybe Inline -> Phases -> DPragma
DSpecialiseInstP :: DType -> DPragma
DRuleP :: String -> Maybe [DTyVarBndrUnit] -> [DRuleBndr] -> DExp -> DExp -> Phases -> DPragma
DAnnP :: AnnTarget -> DExp -> DPragma
DLineP :: Int -> String -> DPragma
DCompleteP :: [Name] -> Maybe Name -> DPragma
DOpaqueP :: Name -> DPragma

-- | Corresponds to TH's <tt>RuleBndr</tt> type.
data DRuleBndr
DRuleVar :: Name -> DRuleBndr
DTypedRuleVar :: Name -> DType -> DRuleBndr

-- | Corresponds to TH's <tt>TySynEqn</tt> type (to store type family
--   equations).
data DTySynEqn
DTySynEqn :: Maybe [DTyVarBndrUnit] -> DType -> DType -> DTySynEqn

-- | Corresponds to TH's <tt>Info</tt> type.
data DInfo
DTyConI :: DDec -> Maybe [DInstanceDec] -> DInfo

-- | The <tt>Maybe Name</tt> stores the name of the enclosing definition
--   (datatype, for a data constructor; class, for a method), if any
DVarI :: Name -> DType -> Maybe Name -> DInfo
DTyVarI :: Name -> DKind -> DInfo

-- | The <tt>Int</tt> is the arity; the <tt>Bool</tt> is whether this tycon
--   is unlifted.
DPrimTyConI :: Name -> Int -> Bool -> DInfo
DPatSynI :: Name -> DPatSynType -> DInfo
type DInstanceDec = -- | Guaranteed to be an instance declaration DDec

-- | Role annotations
data () => Role

-- | <pre>
--   nominal
--   </pre>
NominalR :: Role

-- | <pre>
--   representational
--   </pre>
RepresentationalR :: Role

-- | <pre>
--   phantom
--   </pre>
PhantomR :: Role

-- | <pre>
--   _
--   </pre>
InferR :: Role
data () => AnnTarget
ModuleAnnotation :: AnnTarget
TypeAnnotation :: Name -> AnnTarget
ValueAnnotation :: Name -> AnnTarget

-- | This class relates a TH type with its th-desugar type and allows
--   conversions back and forth. The functional dependency goes only one
--   way because we define the following instances on old versions of GHC:
--   
--   <pre>
--   instance <a>Desugar</a> <a>TyVarBndrSpec</a> <a>DTyVarBndrSpec</a>
--   instance <a>Desugar</a> <a>TyVarBndrUnit</a> <a>DTyVarBndrUnit</a>
--   </pre>
--   
--   Prior to GHC 9.0, <a>TyVarBndrSpec</a> and <a>TyVarBndrUnit</a> are
--   simply type synonyms for <a>TyVarBndr</a>, so making the functional
--   dependencies bidirectional would cause these instances to be rejected.
class Desugar th ds | ds -> th
desugar :: (Desugar th ds, DsMonad q) => th -> q ds
sweeten :: Desugar th ds => ds -> th

-- | Desugar an expression
dsExp :: DsMonad q => Exp -> q DExp

-- | Desugar arbitrary <tt>Dec</tt>s
dsDecs :: DsMonad q => [Dec] -> q [DDec]

-- | Desugar a type
dsType :: DsMonad q => Type -> q DType

-- | Desugar <tt>Info</tt>
dsInfo :: DsMonad q => Info -> q DInfo

-- | Desugar a pattern, along with processing a (desugared) expression that
--   is the entire scope of the variables bound in the pattern.
dsPatOverExp :: DsMonad q => Pat -> DExp -> q (DPat, DExp)

-- | Desugar multiple patterns. Like <a>dsPatOverExp</a>.
dsPatsOverExp :: DsMonad q => [Pat] -> DExp -> q ([DPat], DExp)

-- | Desugar a pattern, returning a list of (Name, DExp) pairs of extra
--   variables that must be bound within the scope of the pattern
dsPatX :: DsMonad q => Pat -> q (DPat, [(Name, DExp)])

-- | Desugar <tt>Dec</tt>s that can appear in a <tt>let</tt> expression.
--   See the documentation for <a>dsLetDec</a> for an explanation of what
--   the return type represents.
dsLetDecs :: DsMonad q => [Dec] -> q ([DLetDec], DExp -> DExp)

-- | Desugar a <a>TyVarBndr</a>.
dsTvb :: DsMonad q => TyVarBndr_ flag -> q (DTyVarBndr flag)

-- | Desugar a <a>TyVarBndrSpec</a>.
dsTvbSpec :: DsMonad q => TyVarBndrSpec -> q DTyVarBndrSpec

-- | Desugar a <a>TyVarBndrUnit</a>.
dsTvbUnit :: DsMonad q => TyVarBndrUnit -> q DTyVarBndrUnit

-- | Desugar a <tt>Cxt</tt>
dsCxt :: DsMonad q => Cxt -> q DCxt

-- | Desugar a single <tt>Con</tt>.
--   
--   Because we always desugar <tt>Con</tt>s to GADT syntax (see the
--   documentation for <a>DCon</a>), it is not always possible to desugar
--   with just a <a>Con</a> alone. For instance, we must desugar:
--   
--   <pre>
--   data Foo a = forall b. MkFoo b
--   </pre>
--   
--   To this:
--   
--   <pre>
--   data Foo a :: Type where
--     MkFoo :: forall a b. b -&gt; Foo a
--   </pre>
--   
--   If our only argument was <tt>forall b. MkFoo b</tt>, it would be
--   somewhat awkward to figure out (1) what the set of universally
--   quantified type variables (<tt>[a]</tt>) was, and (2) what the return
--   type (<tt>Foo a</tt>) was. For this reason, we require passing these
--   as arguments. (If we desugar an actual GADT constructor, these
--   arguments are ignored.)
dsCon :: DsMonad q => [DTyVarBndrUnit] -> DType -> Con -> q [DCon]

-- | Desugar a <tt>Foreign</tt>.
dsForeign :: DsMonad q => Foreign -> q DForeign

-- | Desugar a <tt>Pragma</tt>.
dsPragma :: DsMonad q => Pragma -> q DPragma

-- | Desugar a <tt>RuleBndr</tt>.
dsRuleBndr :: DsMonad q => RuleBndr -> q DRuleBndr

-- | Desugaring a pattern also returns the list of variables bound in
--   as-patterns and the values they should be bound to. This variables
--   must be brought into scope in the "body" of the pattern.
type PatM q = WriterT [(Name, DExp)] q

-- | Desugar a <tt>Pred</tt>, flattening any internal tuples
dsPred :: DsMonad q => Pred -> q DCxt

-- | Desugar a pattern.
dsPat :: DsMonad q => Pat -> PatM q DPat

-- | Desugar a single <tt>Dec</tt>, perhaps producing multiple <a>DDec</a>s
dsDec :: DsMonad q => Dec -> q [DDec]

-- | Desugar a <a>DataD</a> or <a>NewtypeD</a>.
dsDataDec :: DsMonad q => NewOrData -> Cxt -> Name -> [TyVarBndrUnit] -> Maybe Kind -> [Con] -> [DerivingClause] -> q [DDec]

-- | Desugar a <a>DataInstD</a> or a <a>NewtypeInstD</a>.
dsDataInstDec :: DsMonad q => NewOrData -> Cxt -> Name -> Maybe [TyVarBndrUnit] -> [TypeArg] -> Maybe Kind -> [Con] -> [DerivingClause] -> q [DDec]

-- | A backwards-compatible type synonym for the thing representing a
--   single derived class in a <tt>deriving</tt> clause. (This is a
--   <tt>DerivClause</tt>, <tt>Pred</tt>, or <tt>Name</tt> depending on the
--   GHC version.)
type DerivingClause = DerivClause

-- | Desugar a <tt>DerivingClause</tt>.
dsDerivClause :: DsMonad q => DerivingClause -> q DDerivClause

-- | Desugar a single <a>Dec</a> that can appear in a <tt>let</tt>
--   expression. This produces the following output:
--   
--   <ul>
--   <li>One or more <a>DLetDec</a>s (a single <a>Dec</a> can produce
--   multiple <a>DLetDec</a>s in the event of a value declaration that
--   binds multiple things by way of pattern matching.</li>
--   <li>A function of type <tt><a>DExp</a> -&gt; <a>DExp</a></tt>, which
--   should be applied to the expression immediately following the
--   <a>DLetDec</a>s. This function prepends binding forms for any implicit
--   params that were bound in the argument <a>Dec</a>. (If no implicit
--   params are bound, this is simply the <a>id</a> function.)</li>
--   </ul>
--   
--   For instance, if the argument to <a>dsLetDec</a> is the <tt>?x =
--   42</tt> part of this expression:
--   
--   <pre>
--   let { ?x = 42 } in ?x
--   </pre>
--   
--   Then the output is:
--   
--   <ul>
--   <li><pre>let new_x_val = 42</pre></li>
--   <li><pre>\z -&gt; <a>bindIP</a> @"x" new_x_val z</pre></li>
--   </ul>
--   
--   This way, the expression <tt>let { new_x_val = 42 } in <a>bindIP</a>
--   @"x" new_x_val (<a>ip</a> @"x")</tt> can be formed. The implicit param
--   binders always come after all the other <a>DLetDec</a>s to support
--   parallel assignment of implicit params.
dsLetDec :: DsMonad q => Dec -> q ([DLetDec], DExp -> DExp)

-- | Desugar a list of matches for a <tt>case</tt> statement
dsMatches :: DsMonad q => Name -> [Match] -> q [DMatch]

-- | Desugar a <tt>Body</tt>
dsBody :: DsMonad q => Body -> [Dec] -> DExp -> q DExp

-- | Desugar guarded expressions
dsGuards :: DsMonad q => [(Guard, Exp)] -> DExp -> q DExp

-- | Desugar the <tt>Stmt</tt>s in a <tt>do</tt> expression
dsDoStmts :: forall q. DsMonad q => Maybe ModName -> [Stmt] -> q DExp

-- | Desugar the <tt>Stmt</tt>s in a list or monad comprehension
dsComp :: DsMonad q => [Stmt] -> q DExp

-- | Desugar clauses to a function definition
dsClauses :: DsMonad q => MatchContext -> [Clause] -> q [DClause]

-- | Desugar a <tt>BangType</tt>.
dsBangType :: DsMonad q => BangType -> q DBangType

-- | Desugar a <tt>VarBangType</tt>.
dsVarBangType :: DsMonad q => VarBangType -> q DVarBangType

-- | Desugar a <tt>TypeFamilyHead</tt>
dsTypeFamilyHead :: DsMonad q => TypeFamilyHead -> q DTypeFamilyHead

-- | Desugar a <tt>FamilyResultSig</tt>
dsFamilyResultSig :: DsMonad q => FamilyResultSig -> q DFamilyResultSig

-- | Desugar a <tt>PatSynDir</tt>. (Available only with GHC 8.2+)
dsPatSynDir :: DsMonad q => Name -> PatSynDir -> q DPatSynDir

-- | Desugar a <a>TypeArg</a>.
dsTypeArg :: DsMonad q => TypeArg -> q DTypeArg

-- | Expand all type synonyms and type families in the desugared abstract
--   syntax tree provided, where type family simplification is on a "best
--   effort" basis. Normally, the first parameter should have a type like
--   <a>DExp</a> or <a>DLetDec</a>.
expand :: (DsMonad q, Data a) => a -> q a

-- | Expands all type synonyms in a desugared type. Also expands open type
--   family applications. (In GHCs before 7.10, this part does not work if
--   there are any variables.) Attempts to expand closed type family
--   applications, but aborts the moment it spots anything strange, like a
--   nested type family application or type variable.
expandType :: DsMonad q => DType -> q DType

-- | Reify a declaration, warning the user about splices if the reify
--   fails. The warning says that reification can fail if you try to reify
--   a type in the same splice as it is declared.
reifyWithWarning :: (Quasi q, MonadFail q) => Name -> q Info

-- | Add a list of declarations to be considered when reifying local
--   declarations.
withLocalDeclarations :: DsMonad q => [Dec] -> DsM q a -> q a

-- | Like <a>reify</a>, but safer and desugared. Uses local declarations
--   where available.
dsReify :: DsMonad q => Name -> q (Maybe DInfo)

-- | Like <a>reifyType</a>, but safer and desugared. Uses local
--   declarations where available.
dsReifyType :: DsMonad q => Name -> q (Maybe DType)

-- | Like <tt>reify</tt> from Template Haskell, but looks also in any
--   not-yet-typechecked declarations. To establish this list of
--   not-yet-typechecked declarations, use <a>withLocalDeclarations</a>.
--   Returns <a>Nothing</a> if reification fails. Note that no inferred
--   type information is available from local declarations; bottoms may be
--   used if necessary.
reifyWithLocals_maybe :: DsMonad q => Name -> q (Maybe Info)

-- | Like <a>reifyWithLocals_maybe</a>, but throws an exception upon
--   failure, warning the user about separating splices.
reifyWithLocals :: DsMonad q => Name -> q Info

-- | Like <a>reifyWithLocals_maybe</a>, but for fixities. Note that a
--   return value of <tt>Nothing</tt> might mean that the name is not in
--   scope, or it might mean that the name has no assigned fixity. (Use
--   <a>reifyWithLocals_maybe</a> if you really need to tell the
--   difference.)
reifyFixityWithLocals :: DsMonad q => Name -> q (Maybe Fixity)

-- | Like <a>reifyWithLocals_maybe</a> but for types and kinds. Note that a
--   return value of <tt>Nothing</tt> might mean that the name is not in
--   scope, or it might mean that the full type of the name cannot be
--   determined. (Use <a>reifyWithLocals_maybe</a> if you really need to
--   tell the difference.)
reifyTypeWithLocals_maybe :: DsMonad q => Name -> q (Maybe Type)

-- | Like <a>reifyTypeWithLocals_maybe</a>, but throws an exception upon
--   failure, warning the user about separating splices.
reifyTypeWithLocals :: DsMonad q => Name -> q Type

-- | Like <a>lookupValueName</a> from Template Haskell, but looks also in
--   <tt>Names</tt> of not-yet-typechecked declarations. To establish this
--   list of not-yet-typechecked declarations, use
--   <a>withLocalDeclarations</a>. Returns <a>Nothing</a> if no value with
--   the same name can be found.
lookupValueNameWithLocals :: DsMonad q => String -> q (Maybe Name)

-- | Like <a>lookupTypeName</a> from Template Haskell, but looks also in
--   <tt>Names</tt> of not-yet-typechecked declarations. To establish this
--   list of not-yet-typechecked declarations, use
--   <a>withLocalDeclarations</a>. Returns <a>Nothing</a> if no type with
--   the same name can be found.
lookupTypeNameWithLocals :: DsMonad q => String -> q (Maybe Name)

-- | Like TH's <tt>lookupValueName</tt>, but if this name is not bound,
--   then we assume it is declared in the current module.
--   
--   Unlike <a>mkDataName</a>, this also consults the local declarations in
--   scope when determining if the name is currently bound.
mkDataNameWithLocals :: DsMonad q => String -> q Name

-- | Like TH's <tt>lookupTypeName</tt>, but if this name is not bound, then
--   we assume it is declared in the current module.
--   
--   Unlike <a>mkTypeName</a>, this also consults the local declarations in
--   scope when determining if the name is currently bound.
mkTypeNameWithLocals :: DsMonad q => String -> q Name

-- | Determines a <a>Name</a>'s <a>NameSpace</a>. If the <a>NameSpace</a>
--   is attached to the <a>Name</a> itself (i.e., it is unambiguous), then
--   that <a>NameSpace</a> is immediately returned. Otherwise, reification
--   is used to lookup up the <a>NameSpace</a> (consulting local
--   declarations if necessary).
--   
--   Note that if a <a>Name</a> lives in two different <tt>NameSpaces</tt>
--   (which can genuinely happen--for instance, <tt><a>mkName</a>
--   "=="</tt>, where <tt>==</tt> is both a function and a type family),
--   then this function will simply return whichever <a>NameSpace</a> is
--   discovered first via reification. If you wish to find a <a>Name</a> in
--   a particular <a>NameSpace</a>, use the
--   <a>lookupValueNameWithLocals</a> or <a>lookupTypeNameWithLocals</a>
--   functions.
reifyNameSpace :: DsMonad q => Name -> q (Maybe NameSpace)

-- | A <a>DsMonad</a> stores some list of declarations that should be
--   considered in scope. <a>DsM</a> is the prototypical inhabitant of
--   <a>DsMonad</a>.
class (Quasi m, MonadFail m) => DsMonad m

-- | Produce a list of local declarations.
localDeclarations :: DsMonad m => m [Dec]

-- | A convenient implementation of the <a>DsMonad</a> class. Use by
--   calling <a>withLocalDeclarations</a>.
data DsM q a

-- | Remove all nested pattern-matches within this expression. This also
--   removes all <tt>DTildePa</tt>s and <tt>DBangPa</tt>s. After this is
--   run, every pattern is guaranteed to be either a <tt>DConPa</tt> with
--   bare variables as arguments, a <tt>DLitPa</tt>, or a <tt>DWildPa</tt>.
scExp :: DsMonad q => DExp -> q DExp

-- | Like <a>scExp</a>, but for a <a>DLetDec</a>.
scLetDec :: DsMonad q => DLetDec -> q DLetDec

-- | Compute the free variables of a <a>DType</a>.
fvDType :: DType -> OSet Name

-- | Extract the term variables bound by a <a>DPat</a>.
--   
--   This does <i>not</i> extract any type variables bound by pattern
--   signatures.
extractBoundNamesDPat :: DPat -> OSet Name

-- | Apply one <a>DExp</a> to a list of arguments
applyDExp :: DExp -> [DExp] -> DExp

-- | Convert a <a>DPat</a> to a <a>DExp</a>. Fails on <a>DWildP</a>.
dPatToDExp :: DPat -> DExp

-- | Remove all wildcards from a pattern, replacing any wildcard with a
--   fresh variable
removeWilds :: DsMonad q => DPat -> q DPat

-- | Extract the <tt>TyVarBndr</tt>s and constructors given the
--   <tt>Name</tt> of a type
getDataD :: DsMonad q => String -> Name -> q ([TyVarBndrUnit], [Con])

-- | From the name of a data constructor, retrive the datatype definition
--   it is a part of.
dataConNameToDataName :: DsMonad q => Name -> q Name

-- | From the name of a data constructor, retrieve its definition as a
--   <tt>Con</tt>
dataConNameToCon :: DsMonad q => Name -> q Con

-- | Check if a name occurs anywhere within a TH tree.
nameOccursIn :: Data a => Name -> a -> Bool

-- | Extract all Names mentioned in a TH tree.
allNamesIn :: Data a => a -> [Name]

-- | If the declaration passed in is a <a>DValD</a>, creates new,
--   equivalent declarations such that the <a>DPat</a> in all <a>DValD</a>s
--   is just a plain <tt>DVarPa</tt>. Other declarations are passed through
--   unchanged. Note that the declarations that come out of this function
--   are rather less efficient than those that come in: they have many more
--   pattern matches.
flattenDValD :: Quasi q => DLetDec -> q [DLetDec]

-- | Produces <a>DLetDec</a>s representing the record selector functions
--   from the provided <a>DCon</a>s.
--   
--   Note that if the same record selector appears in multiple
--   constructors, <a>getRecordSelectors</a> will return only one binding
--   for that selector. For example, if you had:
--   
--   <pre>
--   data X = X1 {y :: Symbol} | X2 {y :: Symbol}
--   </pre>
--   
--   Then calling <a>getRecordSelectors</a> on <tt>[X1, X2]</tt> will
--   return:
--   
--   <pre>
--   [ DSigD y (DAppT (DAppT DArrowT (DConT X)) (DConT Symbol))
--   , DFunD y [ DClause [DConP X1 [DVarP field]] (DVarE field)
--             , DClause [DConP X2 [DVarP field]] (DVarE field) ] ]
--   </pre>
--   
--   instead of returning one binding for <tt>X1</tt> and another binding
--   for <tt>X2</tt>.
--   
--   <a>getRecordSelectors</a> does not attempt to filter out "naughty"
--   record selectors—that is, records whose field types mention
--   existentially quantified type variables that do not appear in the
--   constructor's return type. Here is an example of a naughty record
--   selector:
--   
--   <pre>
--   data Some :: (Type -&gt; Type) -&gt; Type where
--     MkSome :: { getSome :: f a } -&gt; Some f
--   </pre>
--   
--   GHC itself will not allow the use of <tt>getSome</tt> as a top-level
--   function due to its type <tt>f a</tt> mentioning the existential
--   variable <tt>a</tt>, but <a>getRecordSelectors</a> will return it
--   nonetheless. Ultimately, this design choice is a practical one, as
--   detecting which type variables are existential in Template Haskell is
--   difficult in the general case.
getRecordSelectors :: DsMonad q => [DCon] -> q [DLetDec]

-- | Like TH's <tt>lookupTypeName</tt>, but if this name is not bound, then
--   we assume it is declared in the current module.
mkTypeName :: Quasi q => String -> q Name

-- | Like TH's <tt>lookupDataName</tt>, but if this name is not bound, then
--   we assume it is declared in the current module.
mkDataName :: Quasi q => String -> q Name

-- | Like newName, but even more unique (unique across different splices),
--   and with unique <tt>nameBase</tt>s. Precondition: the string is a
--   valid Haskell alphanumeric identifier (could be upper- or lower-case).
newUniqueName :: Quasi q => String -> q Name

-- | Make a tuple <a>DExp</a> from a list of <a>DExp</a>s. Avoids using a
--   1-tuple.
mkTupleDExp :: [DExp] -> DExp

-- | Make a tuple <a>DPat</a> from a list of <a>DPat</a>s. Avoids using a
--   1-tuple.
mkTupleDPat :: [DPat] -> DPat

-- | If decs is non-empty, delcare them in a let:
maybeDLetE :: [DLetDec] -> DExp -> DExp

-- | If matches is non-empty, make a case statement; otherwise make an
--   error statement
maybeDCaseE :: MatchContext -> DExp -> [DMatch] -> DExp

-- | Convert a list of <a>DPat</a> arguments and a <a>DExp</a> body into a
--   <a>DLamE</a>. This is needed since <a>DLamE</a> takes a list of
--   <a>Name</a>s for its bound variables instead of <a>DPat</a>s, so some
--   reorganization is needed.
mkDLamEFromDPats :: Quasi q => [DPat] -> DExp -> q DExp

-- | Extract the degree of a tuple
tupleDegree_maybe :: String -> Maybe Int

-- | Extract the degree of a tuple name
tupleNameDegree_maybe :: Name -> Maybe Int

-- | Extract the degree of an unboxed sum
unboxedSumDegree_maybe :: String -> Maybe Int

-- | Extract the degree of an unboxed sum name
unboxedSumNameDegree_maybe :: Name -> Maybe Int

-- | Extract the degree of an unboxed tuple
unboxedTupleDegree_maybe :: String -> Maybe Int

-- | Extract the degree of an unboxed tuple name
unboxedTupleNameDegree_maybe :: Name -> Maybe Int

-- | Returns <a>True</a> if the argument <a>Name</a> is that of <a>Type</a>
--   (or <tt>*</tt> or <a>★</a>, to support older GHCs).
isTypeKindName :: Name -> Bool

-- | The <a>Name</a> of the kind <a>Type</a>. 2. The kind <tt>*</tt> on
--   older GHCs.
typeKindName :: Name

-- | Get an implicit param constraint (<tt>IP name a</tt>, which is the
--   desugared form of <tt>(?name :: a)</tt>) from an explicit value.
--   
--   This function is only available with GHC 8.0 or later.
bindIP :: forall name a r. a -> (IP name a => r) -> r

-- | Create new kind variable binder names corresponding to the return kind
--   of a data type. This is useful when you have a data type like:
--   
--   <pre>
--   data Foo :: forall k. k -&gt; Type -&gt; Type where ...
--   </pre>
--   
--   But you want to be able to refer to the type <tt>Foo a b</tt>.
--   <a>mkExtraDKindBinders</a> will take the kind <tt>forall k. k -&gt;
--   Type -&gt; Type</tt>, discover that is has two visible argument kinds,
--   and return as a result two new kind variable binders <tt>[a :: k, b ::
--   Type]</tt>, where <tt>a</tt> and <tt>b</tt> are fresh type variable
--   names.
--   
--   This expands kind synonyms if necessary.
mkExtraDKindBinders :: forall q. DsMonad q => DKind -> q [DTyVarBndrUnit]

-- | Convert a <a>DTyVarBndr</a> into a <a>DType</a>
dTyVarBndrToDType :: DTyVarBndr flag -> DType

-- | Set the flag in a list of <a>DTyVarBndr</a>s. This is often useful in
--   contexts where one needs to re-use a list of <a>DTyVarBndr</a>s from
--   one flag setting to another flag setting. For example, in order to
--   re-use the <a>DTyVarBndr</a>s bound by a <a>DDataD</a> in a
--   <a>DForallT</a>, one can do the following:
--   
--   <pre>
--   case x of
--     <a>DDataD</a> _ _ _ tvbs _ _ _ -&gt;
--       <a>DForallT</a> (<a>DForallInvis</a> (<a>changeDTVFlags</a> <a>SpecifiedSpec</a> tvbs)) ...
--   </pre>
changeDTVFlags :: newFlag -> [DTyVarBndr oldFlag] -> [DTyVarBndr newFlag]

-- | Take a list of <a>DType</a>s, find their free variables, and sort them
--   in reverse topological order to ensure that they are well scoped. In
--   other words, the free variables are ordered such that:
--   
--   <ol>
--   <li>Whenever an explicit kind signature of the form <tt>(A :: K)</tt>
--   is encountered, the free variables of <tt>K</tt> will always appear to
--   the left of the free variables of <tt>A</tt> in the returned
--   result.</li>
--   <li>The constraint in (1) notwithstanding, free variables will appear
--   in left-to-right order of their original appearance.</li>
--   </ol>
--   
--   On older GHCs, this takes measures to avoid returning explicitly bound
--   kind variables, which was not possible before <tt>TypeInType</tt>.
toposortTyVarsOf :: [DType] -> [DTyVarBndrUnit]

-- | The list of arguments in a function <a>Type</a>.
data FunArgs

-- | No more arguments.
FANil :: FunArgs

-- | A series of <tt>forall</tt>ed type variables followed by a dot (if
--   <a>ForallInvis</a>) or an arrow (if <a>ForallVis</a>). For example,
--   the type variables <tt>a1 ... an</tt> in <tt>forall a1 ... an. r</tt>.
FAForalls :: ForallTelescope -> FunArgs -> FunArgs

-- | A series of constraint arguments followed by <tt>=&gt;</tt>. For
--   example, the <tt>(c1, ..., cn)</tt> in <tt>(c1, ..., cn) =&gt; r</tt>.
FACxt :: Cxt -> FunArgs -> FunArgs

-- | An anonymous argument followed by an arrow. For example, the
--   <tt>a</tt> in <tt>a -&gt; r</tt>.
FAAnon :: Type -> FunArgs -> FunArgs

-- | The type variable binders in a <tt>forall</tt>. This is not used by
--   the TH AST itself, but this is used as an intermediate data type in
--   <a>FAForalls</a>.
data ForallTelescope

-- | A visible <tt>forall</tt> (e.g., <tt>forall a -&gt; {...}</tt>). These
--   do not have any notion of specificity, so we use <tt>()</tt> as a
--   placeholder value in the <a>TyVarBndr</a>s.
ForallVis :: [TyVarBndrUnit] -> ForallTelescope

-- | An invisible <tt>forall</tt> (e.g., <tt>forall a {b} c -&gt;
--   {...}</tt>), where each binder has a <a>Specificity</a>.
ForallInvis :: [TyVarBndrSpec] -> ForallTelescope

-- | A <i>visible</i> function argument type (i.e., one that must be
--   supplied explicitly in the source code). This is in contrast to
--   <i>invisible</i> arguments (e.g., the <tt>c</tt> in <tt>c =&gt;
--   r</tt>), which are instantiated without the need for explicit user
--   input.
data VisFunArg

-- | A visible <tt>forall</tt> (e.g., <tt>forall a -&gt; a</tt>).
VisFADep :: TyVarBndrUnit -> VisFunArg

-- | An anonymous argument followed by an arrow (e.g., <tt>a -&gt; r</tt>).
VisFAAnon :: Type -> VisFunArg

-- | Filter the visible function arguments from a list of <a>FunArgs</a>.
filterVisFunArgs :: FunArgs -> [VisFunArg]

-- | Reconstruct an arrow <a>Type</a> from its argument and result types.
ravelType :: FunArgs -> Type -> Type

-- | Decompose a function <a>Type</a> into its arguments (the
--   <a>FunArgs</a>) and its result type (the 'Type).
unravelType :: Type -> (FunArgs, Type)

-- | The list of arguments in a function <a>DType</a>.
data DFunArgs

-- | No more arguments.
DFANil :: DFunArgs

-- | A series of <tt>forall</tt>ed type variables followed by a dot (if
--   <a>ForallInvis</a>) or an arrow (if <a>ForallVis</a>). For example,
--   the type variables <tt>a1 ... an</tt> in <tt>forall a1 ... an. r</tt>.
DFAForalls :: DForallTelescope -> DFunArgs -> DFunArgs

-- | A series of constraint arguments followed by <tt>=&gt;</tt>. For
--   example, the <tt>(c1, ..., cn)</tt> in <tt>(c1, ..., cn) =&gt; r</tt>.
DFACxt :: DCxt -> DFunArgs -> DFunArgs

-- | An anonymous argument followed by an arrow. For example, the
--   <tt>a</tt> in <tt>a -&gt; r</tt>.
DFAAnon :: DType -> DFunArgs -> DFunArgs

-- | A <i>visible</i> function argument type (i.e., one that must be
--   supplied explicitly in the source code). This is in contrast to
--   <i>invisible</i> arguments (e.g., the <tt>c</tt> in <tt>c =&gt;
--   r</tt>), which are instantiated without the need for explicit user
--   input.
data DVisFunArg

-- | A visible <tt>forall</tt> (e.g., <tt>forall a -&gt; a</tt>).
DVisFADep :: DTyVarBndrUnit -> DVisFunArg

-- | An anonymous argument followed by an arrow (e.g., <tt>a -&gt; r</tt>).
DVisFAAnon :: DType -> DVisFunArg

-- | Filter the visible function arguments from a list of <a>DFunArgs</a>.
filterDVisFunArgs :: DFunArgs -> [DVisFunArg]

-- | Reconstruct an arrow <a>DType</a> from its argument and result types.
ravelDType :: DFunArgs -> DType -> DType

-- | Decompose a function <a>DType</a> into its arguments (the
--   <a>DFunArgs</a>) and its result type (the 'DType).
unravelDType :: DType -> (DFunArgs, DType)

-- | An argument to a type, either a normal type (<a>TANormal</a>) or a
--   visible kind application (<a>TyArg</a>).
--   
--   <a>TypeArg</a> is useful when decomposing an application of a
--   <a>Type</a> to its arguments (e.g., in <a>unfoldType</a>).
data TypeArg
TANormal :: Type -> TypeArg
TyArg :: Kind -> TypeArg

-- | Apply one <a>Type</a> to a list of arguments.
applyType :: Type -> [TypeArg] -> Type

-- | Filter the normal type arguments from a list of <a>TypeArg</a>s.
filterTANormals :: [TypeArg] -> [Type]

-- | Decompose an applied type into its individual components. For example,
--   this:
--   
--   <pre>
--   Proxy @Type Char
--   </pre>
--   
--   would be unfolded to this:
--   
--   <pre>
--   (<a>ConT</a> ''Proxy, [<a>TyArg</a> (<a>ConT</a> ''Type), <a>TANormal</a> (<a>ConT</a> ''Char)])
--   </pre>
unfoldType :: Type -> (Type, [TypeArg])

-- | An argument to a type, either a normal type (<a>DTANormal</a>) or a
--   visible kind application (<a>DTyArg</a>).
--   
--   <a>DTypeArg</a> does not appear directly in the <tt>th-desugar</tt>
--   AST, but it is useful when decomposing an application of a
--   <a>DType</a> to its arguments.
data DTypeArg
DTANormal :: DType -> DTypeArg
DTyArg :: DKind -> DTypeArg

-- | Apply one <a>DType</a> to a list of arguments
applyDType :: DType -> [DTypeArg] -> DType

-- | Filter the normal type arguments from a list of <a>DTypeArg</a>s.
filterDTANormals :: [DTypeArg] -> [DType]

-- | Decompose an applied type into its individual components. For example,
--   this:
--   
--   <pre>
--   Proxy @Type Char
--   </pre>
--   
--   would be unfolded to this:
--   
--   <pre>
--   (<a>DConT</a> ''Proxy, [<a>DTyArg</a> (<a>DConT</a> ''Type), <a>DTANormal</a> (<a>DConT</a> ''Char)])
--   </pre>
unfoldDType :: DType -> (DType, [DTypeArg])

-- | Extract the names bound in a <tt>Stmt</tt>
extractBoundNamesStmt :: Stmt -> OSet Name

-- | Extract the names bound in a <tt>Dec</tt> that could appear in a
--   <tt>let</tt> expression.
extractBoundNamesDec :: Dec -> OSet Name

-- | Extract the names bound in a <tt>Pat</tt>
extractBoundNamesPat :: Pat -> OSet Name
instance Language.Haskell.TH.Desugar.Desugar Language.Haskell.TH.Syntax.Exp Language.Haskell.TH.Desugar.AST.DExp
instance Language.Haskell.TH.Desugar.Desugar Language.Haskell.TH.Syntax.Type Language.Haskell.TH.Desugar.AST.DType
instance Language.Haskell.TH.Desugar.Desugar Language.Haskell.TH.Syntax.Cxt Language.Haskell.TH.Desugar.AST.DCxt
instance Language.Haskell.TH.Desugar.Desugar (Language.Haskell.TH.Syntax.TyVarBndr flag) (Language.Haskell.TH.Desugar.AST.DTyVarBndr flag)
instance Language.Haskell.TH.Desugar.Desugar [Language.Haskell.TH.Syntax.Dec] [Language.Haskell.TH.Desugar.AST.DDec]
instance Language.Haskell.TH.Desugar.Desugar Language.Haskell.TH.Desugar.Util.TypeArg Language.Haskell.TH.Desugar.Core.DTypeArg


-- | Defines <tt>Lift</tt> instances for the desugared language. This is
--   defined in a separate module because it also must define <tt>Lift</tt>
--   instances for several TH types, which are orphans and may want another
--   definition downstream.
module Language.Haskell.TH.Desugar.Lift
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DExp
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DPat
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DType
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DForallTelescope
instance Language.Haskell.TH.Syntax.Lift flag => Language.Haskell.TH.Syntax.Lift (Language.Haskell.TH.Desugar.AST.DTyVarBndr flag)
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DMatch
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DClause
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DLetDec
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DDec
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DDerivClause
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DCon
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DConFields
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DForeign
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DPragma
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DRuleBndr
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DTySynEqn
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DPatSynDir
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.NewOrData
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DDerivStrategy
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DTypeFamilyHead
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.AST.DFamilyResultSig
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.Util.TypeArg
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.Core.DTypeArg
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.Util.FunArgs
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.Core.DFunArgs
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.Util.VisFunArg
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.Core.DVisFunArg
instance Language.Haskell.TH.Syntax.Lift Language.Haskell.TH.Desugar.Util.ForallTelescope
