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

-- | Collection of useful functions for use with Template Haskell
--   
--   Collection of useful functions for use with Template Haskell
@package th-utilities
@version 0.2.5.2

-- | A compat module to take fixed points in Q.
module TH.FixQ
fixQ :: (a -> Q a) -> Q a

-- | This module provides Template Haskell utilities for loading files
--   based on paths relative to the root of your Cabal package.
--   
--   Normally when building a cabal package, GHC is run with its current
--   directory set at the package's root directory. This allows using
--   relative paths to refer to files. However, this becomes problematic
--   when you want to load modules from multiple projects, such as when
--   using "stack ghci".
--   
--   This solves the problem by getting the current module's filepath from
--   TH via location. It then searches upwards in the directory tree
--   for a .cabal file, and makes the provided path relative to the folder
--   it's in.
module TH.RelativePaths

-- | Reads a file as a strict ByteString. The path is specified relative to
--   the package's root directory, and addDependentfile is invoked
--   on the target file.
qReadFileBS :: FilePath -> Q ByteString

-- | Reads a file as a lazy ByteString. The path is specified relative to
--   the package's root directory, and addDependentfile is invoked
--   on the target file.
qReadFileLBS :: FilePath -> Q ByteString

-- | Reads a file as a strict Text. The path is specified relative to the
--   package's root directory, and addDependentfile is invoked on
--   the target file.
qReadFileText :: FilePath -> Q Text

-- | Reads a file as a lazy Text. The path is specified relative to the
--   package's root directory, and addDependentfile is invoked on
--   the target file.
qReadFileLazyText :: FilePath -> Q Text

-- | Reads a file as a String. The path is specified relative to the
--   package's root directory, and addDependentfile is invoked on
--   the target file.
qReadFileString :: FilePath -> Q String

-- | Runs the Q action, temporarily setting the current working
--   directory to the root of the cabal package.
withCabalPackageWorkDir :: Q a -> Q a

-- | This utility takes a path that's relative to your package's cabal
--   file, and resolves it to an absolute location.
--   
--   Note that this utility does _not_ invoke qAddDependentFile.
pathRelativeToCabalPackage :: FilePath -> Q FilePath

-- | Given the path to a file or directory, search parent directories for a
--   .cabal file.
findCabalFile :: FilePath -> IO (Maybe FilePath)

-- | Miscellaneous Template Haskell utilities, added as needed by packages
--   in the th-utilities repo and elsewhere.
module TH.Utilities

-- | Get the Name of a TyVarBndr
tyVarBndrName :: TyVarBndr_ flag -> Name
appsT :: Type -> [Type] -> Type

-- | Breaks a type application like A b c into [A, b, c]. In other
--   words, it descends leftwards down AppT constructors, and yields
--   a list of the results.
unAppsT :: Type -> [Type]

-- | Given a list of types, produce the type of a tuple of those types.
--   This is analogous to tupE and tupP.
--   
--   
--   tupT [[t|Int|], [t|Char|], [t|Bool]] = [t| (Int, Char, Bool) |]
--   
--   
--   @since FIXME
tupT :: [Q Type] -> Q Type

-- | Given a list of types, produce the type of a promoted tuple of those
--   types. This is analogous to tupE and tupP.
--   
--   
--   promotedTupT [[t|3|], [t| 'True|], [t|Bool]] = [t| '(3, 'True, Bool) |]
--   
--   
--   @since FIXME
promotedTupT :: [Q Type] -> Q Type

-- | Given a Type, returns a Just value if it's a named type
--   constructor applied to arguments. This value contains the name of the
--   type and a list of arguments.
typeToNamedCon :: Type -> Maybe (Name, [Type])

-- | Expect the provided type to be an application of a regular type to one
--   argument, otherwise fail with a message. This will also work if the
--   name is a promoted data constructor (PromotedT).
expectTyCon1 :: Name -> Type -> Q Type

-- | Expect the provided type to be an application of a regular type to two
--   arguments, otherwise fail with a message. This will also work if the
--   name is a promoted data constructor (PromotedT).
expectTyCon2 :: Name -> Type -> Q (Type, Type)

-- | Given a type, construct the expression (Proxy :: Proxy ty).
proxyE :: TypeQ -> ExpQ

-- | Like the everywhere generic traversal strategy, but skips over
--   strings. This can aid performance of TH traversals quite a bit.
everywhereButStrings :: Data a => (forall b. Data b => b -> b) -> a -> a

-- | Like the everywhereM generic traversal strategy, but skips over
--   strings. This can aid performance of TH traversals quite a bit.
everywhereButStringsM :: (Data a, Monad m) => GenericM m -> a -> m a

-- | Make a Name with a NameS or NameQ flavour, from a
--   Name with any NameFlavour. This may change the meaning
--   of names.
toSimpleName :: Name -> Name

-- | Construct a plain name (mkName) based on the given name. This
--   is useful for cases where TH doesn't expect a unique name.
dequalify :: Name -> Name

-- | Apply dequalify to every type variable.
dequalifyTyVars :: Data a => a -> a

-- | Get the free type variables of a Type.
freeVarsT :: Type -> [Name]

-- | Utility to conveniently handle change to InstanceD API in
--   template-haskell-2.11.0
plainInstanceD :: Cxt -> Type -> [Dec] -> Dec

-- | Utility to conveniently handle change to InstanceD API in
--   template-haskell-2.11.0
fromPlainInstanceD :: Dec -> Maybe (Cxt, Type, [Dec])

-- | Utility to convert Data.Typeable TypeRep to a
--   Type. Note that this function is known to not yet work for many
--   cases, but it does work for normal user datatypes. In future versions
--   this function might have better behavior.
typeRepToType :: TypeRep -> Q Type

-- | Hack to enable putting expressions inside lift-ed TH data. For
--   example, you could do
--   
--   
--   main = print $(lift [ExpLifter [e| 1 + 1 |],  ExpLifter [e| 2 |]])
--   
--   
--   Here, lift is working on a value of type [ExpLifter].
--   The code generated by lift constructs a list with the
--   ExpLifter expressions providing the element values.
--   
--   Without ExpLifter, lift tends to just generate code
--   involving data construction. With ExpLifter, you can put more
--   complicated expression into this construction.
--   
--   Note that this cannot be used in typed quotes, because
--   liftTyped will throw an exception. This is because this hack is
--   incompatible with the type of liftTyped, as it would require
--   the generated code to have type ExpLifter.
data ExpLifter
ExpLifter :: (forall (m :: Type -> Type). Quote m => m Exp) -> ExpLifter

-- | Print splices generated by a TH splice (the printing will happen
--   during compilation, as a GHC warning). Useful for debugging.
--   
--   For instance, you can dump splices generated with makeLenses
--   by replacing a top-level invocation of makeLenses in your
--   code with:
--   
--   
--   dumpSplices $ makeLenses ''Foo
--   
dumpSplices :: DecsQ -> DecsQ
instance Language.Haskell.TH.Syntax.Lift TH.Utilities.ExpLifter

-- | Utilities for reifying simplified datatype info. It omits details that
--   aren't usually relevant to generating instances that work with the
--   datatype. This makes it easier to use TH to derive instances.
--   
--   The "Simple" in the module name refers to the simplicity of the
--   datatypes, not the module itself, which exports quite a few things
--   which are useful in some circumstance or another. I anticipate that
--   the most common uses of this will be the following APIs:
--   
--   
--   
- Getting info about a data or newtype
--   declaration, via DataType, reifyDataType, and
--   DataCon. This is useful for writing something which generates
--   declarations based on a datatype, one of the most common uses of
--   Template Haskell.
--   
- Getting nicely structured info about a named type. See
--   TypeInfo and reifyType. This does not yet support
--   reifying typeclasses, primitive type constructors, or type variables
--   (TyVarI).
--   
--   
--   Currently, this module supports reifying simplified versions of the
--   following Info constructors:
--   
--   
--   
- TyConI with DataD and NewtypeD (becomes a
--   DataType value)
--   
- FamilyI becomes a DataFamily or TypeFamily
--   value.
--   
- DataConI becomes a DataCon value.
--   
--   
--   In the future it will hopefully also have support for the remaining
--   Info constructors, ClassI, ClassOpI,
--   PrimTyConI, VarI, and TyVarI.
module TH.ReifySimple
data TypeInfo

-- | Reifies a Name as a TypeInfo, and calls fail if
--   this doesn't work. Use reify with infoToType if you want
--   to handle the failure case more gracefully.
--   
--   This does not yet support reifying typeclasses, primitive type
--   constructors, or type variables (TyVarI).
reifyType :: Name -> Q TypeInfo

-- | Convert an Info into a TypeInfo if possible, and
--   otherwise yield Nothing. Needs to run in Q so that
infoToType :: Info -> Q (Maybe TypeInfo)

-- | Reifies type info, but instead of yielding a LiftedDataConInfo,
--   will instead yield Nothing.
reifyTypeNoDataKinds :: Name -> Q (Maybe TypeInfo)

-- | Convert an 'Info into a TypeInfo if possible. If it's a data
--   constructor, instead of yielding LiftedDataConInfo, it will
--   instead yield Nothing.
infoToTypeNoDataKinds :: Info -> Maybe TypeInfo

-- | Simplified info about a DataD. Omits deriving, strictness, kind
--   info, and whether it's data or newtype.
data DataType
DataType :: Name -> [Name] -> Cxt -> [DataCon] -> DataType
[dtName] :: DataType -> Name
[dtTvs] :: DataType -> [Name]
[dtCxt] :: DataType -> Cxt
[dtCons] :: DataType -> [DataCon]

-- | Reify the given data or newtype declaration, and yields its
--   DataType representation.
reifyDataType :: Name -> Q DataType
infoToDataType :: Info -> Maybe DataType

-- | Simplified info about a Con. Omits deriving, strictness, and
--   kind info. This is much nicer than consuming Con directly,
--   because it unifies all the constructors into one.
data DataCon
DataCon :: Name -> [Name] -> Cxt -> [(Maybe Name, Type)] -> DataCon
[dcName] :: DataCon -> Name
[dcTvs] :: DataCon -> [Name]
[dcCxt] :: DataCon -> Cxt
[dcFields] :: DataCon -> [(Maybe Name, Type)]

-- | Reify the given data constructor.
reifyDataCon :: Name -> Q DataCon
infoToDataCon :: Info -> Maybe DataCon

-- | Creates a DataCon given the Name and Type of a
--   data-constructor. Note that the result the function type is *not*
--   checked to match the provided Name.
typeToDataCon :: Name -> Type -> DataCon

-- | Simplified info about a data family. Omits deriving, strictness, and
--   kind info.
data DataFamily
DataFamily :: Name -> [Name] -> [DataInst] -> DataFamily
[dfName] :: DataFamily -> Name
[dfTvs] :: DataFamily -> [Name]
[dfInsts] :: DataFamily -> [DataInst]

-- | Simplified info about a data family instance. Omits deriving,
--   strictness, and kind info.
data DataInst
DataInst :: Name -> Cxt -> [Type] -> [DataCon] -> DataInst
[diName] :: DataInst -> Name
[diCxt] :: DataInst -> Cxt
[diParams] :: DataInst -> [Type]
[diCons] :: DataInst -> [DataCon]

-- | Reify the given data family, and yield its DataFamily
--   representation.
reifyDataFamily :: Name -> Q DataFamily
infoToDataFamily :: Info -> Maybe DataFamily

-- | Simplified info about a type family. Omits kind info and injectivity
--   info.
data TypeFamily
TypeFamily :: Name -> [Name] -> [TypeInst] -> TypeFamily
[tfName] :: TypeFamily -> Name
[tfTvs] :: TypeFamily -> [Name]
[tfInsts] :: TypeFamily -> [TypeInst]

-- | Simplified info about a type family instance. Omits nothing.
data TypeInst
TypeInst :: Name -> [Type] -> Type -> TypeInst
[tiName] :: TypeInst -> Name
[tiParams] :: TypeInst -> [Type]
[tiType] :: TypeInst -> Type

-- | Reify the given type family instance declaration, and yields its
--   TypeInst representation.
reifyTypeFamily :: Name -> Q TypeFamily
infoToTypeFamily :: Info -> Maybe TypeFamily

-- | Convert a Con to a list of DataCon. The result is a list
--   because GadtC and RecGadtC can define multiple
--   constructors.
conToDataCons :: Con -> [DataCon]

-- | Like reifyDataType, but takes a Type instead of just the
--   Name of the datatype. It expects a normal datatype argument
--   (see typeToNamedCon).
reifyDataTypeSubstituted :: Type -> Q DataType
instance GHC.Internal.Data.Data.Data TH.ReifySimple.DataCon
instance GHC.Internal.Data.Data.Data TH.ReifySimple.DataFamily
instance GHC.Internal.Data.Data.Data TH.ReifySimple.DataInst
instance GHC.Internal.Data.Data.Data TH.ReifySimple.DataType
instance GHC.Internal.Data.Data.Data TH.ReifySimple.TypeFamily
instance GHC.Internal.Data.Data.Data TH.ReifySimple.TypeInst
instance GHC.Classes.Eq TH.ReifySimple.DataCon
instance GHC.Classes.Eq TH.ReifySimple.DataFamily
instance GHC.Classes.Eq TH.ReifySimple.DataInst
instance GHC.Classes.Eq TH.ReifySimple.DataType
instance GHC.Classes.Eq TH.ReifySimple.TypeFamily
instance GHC.Classes.Eq TH.ReifySimple.TypeInst
instance GHC.Internal.Generics.Generic TH.ReifySimple.DataCon
instance GHC.Internal.Generics.Generic TH.ReifySimple.DataFamily
instance GHC.Internal.Generics.Generic TH.ReifySimple.DataInst
instance GHC.Internal.Generics.Generic TH.ReifySimple.DataType
instance GHC.Internal.Generics.Generic TH.ReifySimple.TypeFamily
instance GHC.Internal.Generics.Generic TH.ReifySimple.TypeInst
instance GHC.Classes.Ord TH.ReifySimple.DataCon
instance GHC.Classes.Ord TH.ReifySimple.DataFamily
instance GHC.Classes.Ord TH.ReifySimple.DataInst
instance GHC.Classes.Ord TH.ReifySimple.DataType
instance GHC.Classes.Ord TH.ReifySimple.TypeFamily
instance GHC.Classes.Ord TH.ReifySimple.TypeInst
instance GHC.Internal.Show.Show TH.ReifySimple.DataCon
instance GHC.Internal.Show.Show TH.ReifySimple.DataFamily
instance GHC.Internal.Show.Show TH.ReifySimple.DataInst
instance GHC.Internal.Show.Show TH.ReifySimple.DataType
instance GHC.Internal.Show.Show TH.ReifySimple.TypeFamily
instance GHC.Internal.Show.Show TH.ReifySimple.TypeInst

-- | Implementation of a Storable deriver for data types. This works
--   for any non-recursive datatype which has Storable fields.
--   
--   Most users won't need to import this module directly. Instead, use
--   derive / Deriving to create Storable instances.
module TH.Derive.Storable

-- | Implementation used for runDeriver.
makeStorableInst :: Cxt -> Type -> Q [Dec]
instance TH.Derive.Internal.Deriver (GHC.Internal.Foreign.Storable.Storable a)

-- | This module implements a system for registering and using typeclass
--   derivers and instantiators. This allows you to derive instances for
--   typeclasses beyond GHC's ability to generate instances in
--   deriving clauses.
--   
--   For example, TH.Derive.Storable defines a Deriver for
--   Storable. This allows us to use derive to generate an
--   instance for Storable:
--   
--   
--   data X = X Int Float
--   
--   $($(derive [d|
--       instance Deriving (Storable X)
--       |]))
--   
--   
--   In particular, note the use of double splicing, $($(derive [d| ...
--   |])). The inner $(derive [d| ... |]) expression
--   generates code which invokes the runDeriver method with
--   appropriate arguments. The outer $( ... $) then runs that
--   code in order to generate the resulting instances. This is how it does
--   dispatch at compile time.
--   
--   There are a number of advantages of re-using instance syntax in this
--   way:
--   
--   
--   
- It allows the user to specify constraints. Similarly to GHC's need
--   for standalone deriving, it is sometimes very difficult for TH to
--   figure out appropriate superclass constraints.
--   
- The instance gets thoroughly checked by GHC (syntax, kind, and
--   type checking). This means that you get reasonably nice error messages
--   when you misuse these.
--   
- It allows the user to specify methods. With Instantiators,
--   the user can provide values which can be used in the definition of the
--   generated instance. This is a bit like having Instance
--   Templates. We don't have pretty ways of writing these quite yet,
--   but I have worked on something similar in the past.
--   
- Using compile-time dispatch allows for concise specification of a
--   multiple of instances you'd like derived.
--   
- In the case of use of a Derivers, the user doesn't need to
--   know about anything but derive and the name of the class they
--   want. (and the Deriver instance must be in scope one way or
--   another)
--   
module TH.Derive

-- | This is the primary function for users of TH.Derive. See the
--   module documentation for usage info.
derive :: DecsQ -> ExpQ

-- | This class has no instances. Its only purpose is usage within the
--   [d| ... |] quote provided to derive. Usage such as
--   instance Deriving (Foo X) indicates that you would like to
--   use the Deriver registered for Foo a.
class Deriving cls

-- | Instances of Deriver describe a default way of creating an
--   instance for a particular typeclass. For example, if I wanted to write
--   something that derives Eq instances, I would write a
--   instance Deriver (Eq a).
class Deriver cls
runDeriver :: Deriver cls => Proxy cls -> Cxt -> Type -> Q [Dec]
class Instantiator inst
runInstantiator :: Instantiator inst => Proxy inst -> Cxt -> Type -> [Dec] -> Q [Dec]

-- | Useful function for defining Instantiator instances. It uses
--   Data to generically replace references to the methods with
--   plain Names. This is handy when you are putting the definitions
--   passed to the instantiator in a where clause. It is also useful so
--   that you can reference the class methods from AST quotes involved in
--   the definition of the instantiator.
dequalifyMethods :: Data a => Name -> a -> Q a
