-- 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.0.1


-- | 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 <a>location</a>. 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 <tt>addDependentfile</tt> 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 <tt>addDependentfile</tt> 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 <tt>addDependentfile</tt> 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 <tt>addDependentfile</tt> 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 <tt>addDependentfile</tt> is invoked on
--   the target file.
qReadFileString :: FilePath -> Q String

-- | Runs the <a>Q</a> 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 <tt>qAddDependentFile</tt>.
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 <a>Name</a> of a <a>TyVarBndr</a>
tyVarBndrName :: TyVarBndr -> Name
appsT :: Type -> [Type] -> Type

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

-- | Given a <a>Type</a>, returns a <a>Just</a> 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 (<a>PromotedT</a>).
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 (<a>PromotedT</a>).
expectTyCon2 :: Name -> Type -> Q (Type, Type)

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

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

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

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

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

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

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

-- | Utility to convert <a>Data.Typeable</a> <a>TypeRep</a> to a
--   <a>Type</a>. 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 <a>lift</a>-ed TH data. For
--   example, you could do
--   
--   <pre>
--   main = print $(lift [ExpLifter [e| 1 + 1 |],  ExpLifter [e| 2 |]])
--   </pre>
--   
--   Here, <a>lift</a> is working on a value of type <tt>[ExpLifter]</tt>.
--   The code generated by <a>lift</a> constructs a list with the
--   <a>ExpLifter</a> expressions providing the element values.
--   
--   Without <a>ExpLifter</a>, <a>lift</a> tends to just generate code
--   involving data construction. With <a>ExpLifter</a>, you can put more
--   complicated expression into this construction.
data ExpLifter
ExpLifter :: ExpQ -> ExpLifter
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:
--   
--   <ul>
--   <li>Getting info about a <tt>data</tt> or <tt>newtype</tt>
--   declaration, via <a>DataType</a>, <a>reifyDataType</a>, and
--   <a>DataCon</a>. This is useful for writing something which generates
--   declarations based on a datatype, one of the most common uses of
--   Template Haskell.</li>
--   <li>Getting nicely structured info about a named type. See
--   <a>TypeInfo</a> and <a>reifyType</a>. This does not yet support
--   reifying typeclasses, primitive type constructors, or type variables
--   (<a>TyVarI</a>).</li>
--   </ul>
--   
--   Currently, this module supports reifying simplified versions of the
--   following <a>Info</a> constructors:
--   
--   <ul>
--   <li><a>TyConI</a> with <a>DataD</a> and <a>NewtypeD</a> (becomes a
--   <a>DataType</a> value)</li>
--   <li><a>FamilyI</a> becomes a <a>DataFamily</a> or <a>TypeFamily</a>
--   value.</li>
--   <li><a>DataConI</a> becomes a <a>DataCon</a> value.</li>
--   </ul>
--   
--   In the future it will hopefully also have support for the remaining
--   <a>Info</a> constructors, <a>ClassI</a>, <a>ClassOpI</a>,
--   <a>PrimTyConI</a>, <a>VarI</a>, and <a>TyVarI</a>.
module TH.ReifySimple
data TypeInfo

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

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

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

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

-- | Simplified info about a <a>DataD</a>. Omits deriving, strictness, kind
--   info, and whether it's <tt>data</tt> or <tt>newtype</tt>.
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
--   <a>DataType</a> representation.
reifyDataType :: Name -> Q DataType
infoToDataType :: Info -> Maybe DataType

-- | Simplified info about a <a>Con</a>. Omits deriving, strictness, and
--   kind info. This is much nicer than consuming <a>Con</a> 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 <a>DataCon</a> given the <a>Name</a> and <a>Type</a> of a
--   data-constructor. Note that the result the function type is *not*
--   checked to match the provided <a>Name</a>.
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 <a>DataFamily</a>
--   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
--   <a>TypeInst</a> representation.
reifyTypeFamily :: Name -> Q TypeFamily
infoToTypeFamily :: Info -> Maybe TypeFamily

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

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


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

-- | Implementation used for <a>runDeriver</a>.
makeStorableInst :: Cxt -> Type -> Q [Dec]
instance TH.Derive.Internal.Deriver (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
--   <tt>deriving</tt> clauses.
--   
--   For exmaple, <a>TH.Derive.Storable</a> defines a <a>Deriver</a> for
--   <tt>Storable</tt>. This allows us to use <a>derive</a> to generate an
--   instance for Storable:
--   
--   <pre>
--   data X = X Int Float
--   
--   $($(derive [d|
--       instance Deriving (Storable X)
--       |]))
--   </pre>
--   
--   In particular, note the use of double splicing, <tt>$($(derive [d| ...
--   |]))</tt>. The inner <tt>$(derive [d| ... |])</tt> expression
--   generates code which invokes the <a>runDeriver</a> method with
--   appropriate arguments. The outer <tt>$( ... $)</tt> 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:
--   
--   <ul>
--   <li>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.</li>
--   <li>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.</li>
--   <li>It allows the user to specify methods. With <a>Instantiator</a>s,
--   the user can provide values which can be used in the definition of the
--   generated instance. This is a bit like having <a>Instance
--   Templates</a>. We don't have pretty ways of writing these quite yet,
--   but I have worked on something <a>similar in the past</a>.</li>
--   <li>Using compile-time dispatch allows for concise specification of a
--   multiple of instances you'd like derived.</li>
--   <li>In the case of use of a <a>Deriver</a>s, the user doesn't need to
--   know about anything but <a>derive</a> and the name of the class they
--   want. (and the <a>Deriver</a> instance must be in scope one way or
--   another)</li>
--   </ul>
module TH.Derive

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

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

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

-- | Useful function for defining <a>Instantiator</a> instances. It uses
--   <a>Data</a> to generically replace references to the methods with
--   plain <a>Name</a>s. 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
