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


-- | Derive Template Haskell's <tt>Lift</tt> class for datatypes using
--   <tt>TemplateHaskell</tt>. The functionality in this package has
--   largely been subsumed by the <tt>DeriveLift</tt> language extension,
--   which is available in GHC 8.0 and later versions. As such, this
--   package is only useful as a way to backport bugfixes to
--   <tt>DeriveLift</tt> in later GHC versions back to older GHCs.
--   
--   The following libraries are related:
--   
--   <ul>
--   <li>The <a>th-orphans</a> package provides instances for
--   <tt>template-haskell</tt> syntax types.</li>
--   <li>The <a>th-lift-instances</a> package provides <tt>Lift</tt>
--   instances for types in <tt>base</tt>, <tt>text</tt>,
--   <tt>bytestring</tt>, <tt>vector</tt>, etc. Some of these instances are
--   only provided for old versions of their respective libraries, as the
--   same <tt>Lift</tt> instances are also present upstream on newer
--   versions.</li>
--   </ul>
@package th-lift
@version 0.8.7


-- | Helper functions used in code that <a>Language.Haskell.TH.Lift</a>
--   generates.
--   
--   Note: this is an internal module, and as such, the API presented here
--   is not guaranteed to be stable, even between minor releases of this
--   library.
module Language.Haskell.TH.Lift.Internal

-- | A type-restricted version of <a>error</a> that ensures
--   <tt>makeLift</tt> always returns a value of type <tt>q <a>Exp</a></tt>
--   (where <tt>q</tt> is an instance of <a>Quote</a>), even when used on
--   an empty datatype.
errorQuoteExp :: Quote q => String -> q Exp

-- | This is a cargo-culted version of <tt>unsafeSpliceCoerce</tt> from the
--   <tt>th-compat</tt> library, which has been copied here to avoid
--   incurring a library dependency.
unsafeSpliceCoerce :: forall a m. Quote m => m Exp -> Code m a

module Language.Haskell.TH.Lift
deriveLift :: Name -> Q [Dec]

-- | Derive <a>Lift</a> instances for many datatypes.
deriveLiftMany :: [Name] -> Q [Dec]

-- | Obtain <a>Info</a> values through a custom reification function. This
--   is useful when generating instances for datatypes that have not yet
--   been declared.
deriveLift' :: [Role] -> Info -> Q [Dec]
deriveLiftMany' :: [([Role], Info)] -> Q [Dec]

-- | Generates a lambda expresson which behaves like <a>lift</a> (without
--   requiring a <a>Lift</a> instance). Example:
--   
--   <pre>
--   newtype Fix f = In { out :: f (Fix f) }
--   
--   instance Lift (f (Fix f)) =&gt; Lift (Fix f) where
--     lift = $(makeLift ''Fix)
--   </pre>
--   
--   This can be useful when <a>deriveLift</a> is not clever enough to
--   infer the correct instance context, such as in the example above.
makeLift :: Name -> Q Exp

-- | Like <a>makeLift</a>, but using a custom reification function.
makeLift' :: Info -> Q Exp

-- | A <a>Lift</a> instance can have any of its values turned into a
--   Template Haskell expression. This is needed when a value used within a
--   Template Haskell quotation is bound outside the Oxford brackets
--   (<tt>[| ... |]</tt> or <tt>[|| ... ||]</tt>) but not at the top level.
--   As an example:
--   
--   <pre>
--   add1 :: Int -&gt; Code Q Int
--   add1 x = [|| x + 1 ||]
--   </pre>
--   
--   Template Haskell has no way of knowing what value <tt>x</tt> will take
--   on at splice-time, so it requires the type of <tt>x</tt> to be an
--   instance of <a>Lift</a>.
--   
--   A <a>Lift</a> instance must satisfy <tt>$(lift x) ≡ x</tt> and
--   <tt>$$(liftTyped x) ≡ x</tt> for all <tt>x</tt>, where <tt>$(...)</tt>
--   and <tt>$$(...)</tt> are Template Haskell splices. It is additionally
--   expected that <tt><a>lift</a> x ≡ <a>unTypeCode</a> (<a>liftTyped</a>
--   x)</tt>.
--   
--   <a>Lift</a> instances can be derived automatically by use of the
--   <tt>-XDeriveLift</tt> GHC language extension:
--   
--   <pre>
--   {-# LANGUAGE DeriveLift #-}
--   module Foo where
--   
--   import Language.Haskell.TH.Syntax
--   
--   data Bar a = Bar1 a (Bar a) | Bar2 String
--     deriving Lift
--   </pre>
--   
--   Representation-polymorphic since <i>template-haskell-2.16.0.0</i>.
--   
--   This is exposed both from the <tt>template-haskell-lift</tt> and
--   <tt>template-haskell</tt> packages. Consider importing it from the
--   more stable <tt>template-haskell-lift</tt> if you don't need the full
--   breadth of the <tt>template-haskell</tt> interface.
class Lift (t :: TYPE r)

-- | Turn a value into a Template Haskell expression, suitable for use in a
--   splice.
lift :: (Lift t, Quote m) => t -> m Exp
($dmlift) :: forall m. (Lift t, r ~ LiftedRep, Quote m) => t -> m Exp

-- | Turn a value into a Template Haskell typed expression, suitable for
--   use in a typed splice.
liftTyped :: forall (m :: Type -> Type). (Lift t, Quote m) => t -> Code m t
