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


-- | Type-safe, non-relational, multi-backend persistence.
--   
--   Hackage documentation generation is not reliable. For up to date
--   documentation, please see:
--   <a>http://www.stackage.org/package/persistent-template</a>.
@package persistent-template
@version 2.8.2


-- | This module provides the tools for defining your database schema and
--   using it to generate Haskell data types and migrations.
module Database.Persist.TH

-- | Converts a quasi-quoted syntax into a list of entity definitions, to
--   be used as input to the template haskell generation code (mkPersist).
persistWith :: PersistSettings -> QuasiQuoter

-- | Apply <a>persistWith</a> to <a>upperCaseSettings</a>.
persistUpperCase :: QuasiQuoter

-- | Apply <a>persistWith</a> to <a>lowerCaseSettings</a>.
persistLowerCase :: QuasiQuoter

-- | Same as <a>persistWith</a>, but uses an external file instead of a
--   quasiquotation. The recommended file extension is
--   <tt>.persistentmodels</tt>.
persistFileWith :: PersistSettings -> FilePath -> Q Exp

-- | Same as <a>persistFileWith</a>, but uses several external files
--   instead of one. Splitting your Persistent definitions into multiple
--   modules can potentially dramatically speed up compile times.
--   
--   The recommended file extension is <tt>.persistentmodels</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Split your Persistent definitions into multiple files
--   (<tt>models1</tt>, <tt>models2</tt>), then create a new module for
--   each new file and run <a>mkPersist</a> there:
--   
--   <pre>
--   -- Model1.hs
--   <a>share</a>
--       [<a>mkPersist</a> <a>sqlSettings</a>]
--       $(<a>persistFileWith</a> <a>lowerCaseSettings</a> "models1")
--   </pre>
--   
--   <pre>
--   -- Model2.hs
--   <a>share</a>
--       [<a>mkPersist</a> <a>sqlSettings</a>]
--       $(<a>persistFileWith</a> <a>lowerCaseSettings</a> "models2")
--   </pre>
--   
--   Use <a>persistManyFileWith</a> to create your migrations:
--   
--   <pre>
--   -- Migrate.hs
--   <a>share</a>
--       [<a>mkMigrate</a> "migrateAll"]
--       $(<a>persistManyFileWith</a> <a>lowerCaseSettings</a> ["models1.persistentmodels","models2.persistentmodels"])
--   </pre>
--   
--   Tip: To get the same import behavior as if you were declaring all your
--   models in one file, import your new files <tt>as Name</tt> into
--   another file, then export <tt>module Name</tt>.
--   
--   This approach may be used in the future to reduce memory usage during
--   compilation, but so far we've only seen mild reductions.
--   
--   See <a>persistent#778</a> and <a>persistent#791</a> for more details.
persistManyFileWith :: PersistSettings -> [FilePath] -> Q Exp

-- | Create data types and appropriate <a>PersistEntity</a> instances for
--   the given <a>EntityDef</a>s. Works well with the persist quasi-quoter.
mkPersist :: MkPersistSettings -> [EntityDef] -> Q [Dec]

-- | Settings to be passed to the <a>mkPersist</a> function.
data MkPersistSettings

-- | Which database backend we're using.
--   
--   When generating data types, each type is given a generic version-
--   which works with any backend- and a type synonym for the commonly used
--   backend. This is where you specify that commonly used backend.
mpsBackend :: MkPersistSettings -> Type

-- | Create generic types that can be used with multiple backends. Good for
--   reusable code, but makes error messages harder to understand. Default:
--   False.
mpsGeneric :: MkPersistSettings -> Bool

-- | Prefix field names with the model name. Default: True.
mpsPrefixFields :: MkPersistSettings -> Bool

-- | Generate <tt>ToJSON</tt>/<tt>FromJSON</tt> instances for each model
--   types. If it's <tt>Nothing</tt>, no instances will be generated.
--   Default:
--   
--   <pre>
--   Just EntityJSON
--       { entityToJSON = 'keyValueEntityToJSON
--       , entityFromJSON = 'keyValueEntityFromJSON
--       }
--   </pre>
mpsEntityJSON :: MkPersistSettings -> Maybe EntityJSON

-- | Instead of generating normal field accessors, generator lens-style
--   accessors.
--   
--   Default: False
mpsGenerateLenses :: MkPersistSettings -> Bool

-- | Automatically derive these typeclass instances for all record and key
--   types.
--   
--   Default: []
mpsDeriveInstances :: MkPersistSettings -> [Name]
data EntityJSON
EntityJSON :: Name -> Name -> EntityJSON

-- | Name of the <tt>toJSON</tt> implementation for <tt>Entity a</tt>.
[entityToJSON] :: EntityJSON -> Name

-- | Name of the <tt>fromJSON</tt> implementation for <tt>Entity a</tt>.
[entityFromJSON] :: EntityJSON -> Name

-- | Create an <tt>MkPersistSettings</tt> with default values.
mkPersistSettings :: Type -> MkPersistSettings

-- | Use the <tt>SqlPersist</tt> backend.
sqlSettings :: MkPersistSettings

-- | Creates a single function to perform all migrations for the entities
--   defined here. One thing to be aware of is dependencies: if you have
--   entities with foreign references, make sure to place those definitions
--   after the entities they reference.
mkMigrate :: String -> [EntityDef] -> Q [Dec]

-- | Save the <tt>EntityDef</tt>s passed in under the given name.
mkSave :: String -> [EntityDef] -> Q [Dec]

-- | Generate a <a>DeleteCascade</a> instance for the given
--   <tt>EntityDef</tt>s.
mkDeleteCascade :: MkPersistSettings -> [EntityDef] -> Q [Dec]

-- | Creates a declaration for the <tt>[<a>EntityDef</a>]</tt> from the
--   <tt>persistent</tt> schema. This is necessary because the Persistent
--   QuasiQuoter is unable to know the correct type of ID fields, and
--   assumes that they are all Int64.
--   
--   Provide this in the list you give to <a>share</a>, much like
--   <tt><a>mkMigrate</a></tt>.
--   
--   <pre>
--   <a>share</a> [<a>mkMigrate</a> "migrateAll", <a>mkEntityDefList</a> "entityDefs"] [...]
--   </pre>
mkEntityDefList :: String -> [EntityDef] -> Q [Dec]

-- | Apply the given list of functions to the same <tt>EntityDef</tt>s.
--   
--   This function is useful for cases such as:
--   
--   <pre>
--   &gt;&gt;&gt; share [mkSave "myDefs", mkPersist sqlSettings] [persistLowerCase|...|]
--   </pre>
share :: [[EntityDef] -> Q [Dec]] -> [EntityDef] -> Q [Dec]

-- | Automatically creates a valid <a>PersistField</a> instance for any
--   datatype that has valid <a>Show</a> and <a>Read</a> instances. Can be
--   very convenient for <a>Enum</a> types.
derivePersistField :: String -> Q [Dec]

-- | Automatically creates a valid <a>PersistField</a> instance for any
--   datatype that has valid <a>ToJSON</a> and <a>FromJSON</a> instances.
--   For a datatype <tt>T</tt> it generates instances similar to these:
--   
--   <pre>
--   instance PersistField T where
--       toPersistValue = PersistByteString . L.toStrict . encode
--       fromPersistValue = (left T.pack) . eitherDecodeStrict' &lt;=&lt; fromPersistValue
--   instance PersistFieldSql T where
--       sqlType _ = SqlString
--   </pre>
derivePersistFieldJSON :: String -> Q [Dec]

-- | Produce code similar to the following:
--   
--   <pre>
--   instance PersistEntity e =&gt; PersistField e where
--      toPersistValue = entityToPersistValueHelper
--      fromPersistValue = entityFromPersistValueHelper ["col1", "col2"]
--      sqlType _ = SqlString
--   </pre>
persistFieldFromEntity :: MkPersistSettings -> EntityDef -> Q [Dec]
lensPTH :: (s -> a) -> (s -> b -> t) -> Lens s t a b

parseReferences :: PersistSettings -> Text -> Q Exp

-- | Takes a list of (potentially) independently defined entities and
--   properly links all foreign keys to reference the right
--   <a>EntityDef</a>, tying the knot between entities.
--   
--   Allows users to define entities indepedently or in separate modules
--   and then fix the cross-references between them at runtime to create a
--   <a>Migration</a>.
embedEntityDefs :: [EntityDef] -> [EntityDef]

-- | Render an error message based on the <tt>tableName</tt> and
--   <tt>fieldName</tt> with the provided message.
fieldError :: Text -> Text -> Text -> Text

-- | This class is used to ensure that functions requring at least one
--   unique key are not called with records that have 0 unique keys. The
--   quasiquoter automatically writes working instances for appropriate
--   entities, and generates <tt>TypeError</tt> instances for records that
--   have 0 unique keys.
class PersistEntity record => AtLeastOneUniqueKey record
requireUniquesP :: AtLeastOneUniqueKey record => record -> NonEmpty (Unique record)

-- | This class is used to ensure that <a>upsert</a> is only called on
--   records that have a single <a>Unique</a> key. The quasiquoter
--   automatically generates working instances for appropriate records, and
--   generates <tt>TypeError</tt> instances for records that have 0 or
--   multiple unique keys.
class PersistEntity record => OnlyOneUniqueKey record
onlyUniqueP :: OnlyOneUniqueKey record => record -> Unique record
instance GHC.Show.Show Database.Persist.TH.FTTypeConDescr
instance GHC.Show.Show Database.Persist.TH.EntityDefSqlTypeExp
instance GHC.Show.Show Database.Persist.TH.SqlTypeExp
instance Language.Haskell.TH.Syntax.Lift Database.Persist.TH.FieldsSqlTypeExp
instance Language.Haskell.TH.Syntax.Lift Database.Persist.TH.FieldSqlTypeExp
instance Language.Haskell.TH.Syntax.Lift Database.Persist.TH.EntityDefSqlTypeExp
instance Language.Haskell.TH.Syntax.Lift Database.Persist.TH.SqlTypeExp
instance Language.Haskell.TH.Syntax.Lift Database.Persist.Types.Base.ReferenceDef
instance Language.Haskell.TH.Syntax.Lift Database.Persist.Types.Base.EmbedEntityDef
instance Language.Haskell.TH.Syntax.Lift Database.Persist.Types.Base.EmbedFieldDef
instance Language.Haskell.TH.Syntax.Lift Database.Persist.Types.Base.EntityDef
instance Language.Haskell.TH.Syntax.Lift Database.Persist.Types.Base.FieldDef
instance Language.Haskell.TH.Syntax.Lift Database.Persist.Types.Base.UniqueDef
instance Language.Haskell.TH.Syntax.Lift Database.Persist.Types.Base.CompositeDef
instance Language.Haskell.TH.Syntax.Lift Database.Persist.Types.Base.ForeignDef
instance Language.Haskell.TH.Syntax.Lift Database.Persist.Types.Base.HaskellName
instance Language.Haskell.TH.Syntax.Lift Database.Persist.Types.Base.DBName
instance Language.Haskell.TH.Syntax.Lift Database.Persist.Types.Base.FieldType
instance Language.Haskell.TH.Syntax.Lift Database.Persist.Types.Base.PersistFilter
instance Language.Haskell.TH.Syntax.Lift Database.Persist.Types.Base.PersistUpdate
instance Language.Haskell.TH.Syntax.Lift Database.Persist.Types.Base.SqlType