persistent-template-2.1.4: Type-safe, non-relational, multi-backend persistence.

Safe Haskell | None
Language | Haskell98

Database.Persist.TH

Contents

- Parse entity defs
- Turn `EntityDef`s into types
- Various other TH functions
- Internal

Description

This module provides utilities for creating backends. Regular users do not need to use this module.

Synopsis

- persistWith :: PersistSettings -> QuasiQuoter
- persistUpperCase :: QuasiQuoter
- persistLowerCase :: QuasiQuoter
- persistFileWith :: PersistSettings -> FilePath -> Q Exp
- mkPersist :: MkPersistSettings -> [EntityDef] -> Q [Dec]
- data MkPersistSettings
- mpsBackend :: MkPersistSettings -> Type
- mpsGeneric :: MkPersistSettings -> Bool
- mpsPrefixFields :: MkPersistSettings -> Bool
- mpsEntityJSON :: MkPersistSettings -> Maybe EntityJSON
- mpsGenerateLenses :: MkPersistSettings -> Bool
- data EntityJSON = EntityJSON {
  - entityToJSON :: Name
  - entityFromJSON :: Name
  }
- mkPersistSettings :: Type -> MkPersistSettings
- sqlSettings :: MkPersistSettings
- sqlOnlySettings :: MkPersistSettings
- mkMigrate :: String -> [EntityDef] -> Q [Dec]
- mkSave :: String -> [EntityDef] -> Q [Dec]
- mkDeleteCascade :: MkPersistSettings -> [EntityDef] -> Q [Dec]
- share :: [[EntityDef] -> Q [Dec]] -> [EntityDef] -> Q [Dec]
- derivePersistField :: String -> Q [Dec]
- derivePersistFieldJSON :: String -> Q [Dec]
- persistFieldFromEntity :: MkPersistSettings -> EntityDef -> Q [Dec]
- packPTH :: String -> Text
- lensPTH :: (s -> a) -> (s -> b -> t) -> Lens s t a b

# Parse entity defs

persistWith :: PersistSettings -> QuasiQuoter

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

persistUpperCase :: QuasiQuoter

Apply `persistWith` to `upperCaseSettings`.

persistLowerCase :: QuasiQuoter

Apply `persistWith` to `lowerCaseSettings`.

persistFileWith :: PersistSettings -> FilePath -> Q Exp

Same as `persistWith`, but uses an external file instead of a quasiquotation.

# Turn `EntityDef`s into types

mkPersist :: MkPersistSettings -> [EntityDef] -> Q [Dec]

Create data types and appropriate `PersistEntity` instances for the given `EntityDef`s. Works well with the persist quasi-quoter.

data MkPersistSettings

Settings to be passed to the `mkPersist` function.

mpsBackend :: MkPersistSettings -> Type

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.

mpsGeneric :: MkPersistSettings -> Bool

Create generic types that can be used with multiple backends. Good for reusable code, but makes error messages harder to understand. Default: True.

mpsPrefixFields :: MkPersistSettings -> Bool

Prefix field names with the model name. Default: True.

mpsEntityJSON :: MkPersistSettings -> Maybe EntityJSON

Generate `ToJSON`/`FromJSON` instances for each model types. If it's `Nothing`, no instances will be generated. Default:

     Just EntityJSON
         { entityToJSON = 'keyValueEntityToJSON
         , entityFromJSON = 'keyValueEntityFromJSON
         }

mpsGenerateLenses :: MkPersistSettings -> Bool

Instead of generating normal field accessors, generator lens-style accessors.

Default: False

Since 1.3.1

data EntityJSON

Constructors

EntityJSON |
Fields entityToJSON :: Name Name of the `toJSON` implementation for `Entity a`. entityFromJSON :: Name Name of the `fromJSON` implementation for `Entity a`.

mkPersistSettings

Arguments

:: Type | Value for `mpsBackend`
-> MkPersistSettings |

Create an `MkPersistSettings` with default values.

sqlSettings :: MkPersistSettings

Use the `SqlPersist` backend.

sqlOnlySettings :: MkPersistSettings

Deprecated: use sqlSettings

Same as `sqlSettings`.

Since 1.1.1

# Various other TH functions

mkMigrate :: String -> [EntityDef] -> Q [Dec]

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.

mkSave :: String -> [EntityDef] -> Q [Dec]

Save the `EntityDef`s passed in under the given name.

mkDeleteCascade :: MkPersistSettings -> [EntityDef] -> Q [Dec]

Generate a `DeleteCascade` instance for the given `EntityDef`s.

share :: [[EntityDef] -> Q [Dec]] -> [EntityDef] -> Q [Dec]

Apply the given list of functions to the same `EntityDef`s.

This function is useful for cases such as:

    >>> share [mkSave "myDefs", mkPersist sqlSettings] [persistLowerCase|...|]

derivePersistField :: String -> Q [Dec]

Automatically creates a valid `PersistField` instance for any datatype that has valid `Show` and `Read` instances. Can be very convenient for `Enum` types.

derivePersistFieldJSON :: String -> Q [Dec]

Automatically creates a valid `PersistField` instance for any datatype that has valid `ToJSON` and `FromJSON` instances. For a datatype `T` it generates instances similar to these:

       instance PersistField T where
           toPersistValue = PersistByteString . L.toStrict . encode
           fromPersistValue = (left T.pack) . eitherDecodeStrict' <=< fromPersistValue
       instance PersistFieldSql T where
           sqlType _ = SqlString

persistFieldFromEntity :: MkPersistSettings -> EntityDef -> Q [Dec]

produce code similar to the following:

      instance PersistEntity e => PersistField e where
         toPersistValue = PersistMap $ zip columNames (map toPersistValue . toPersistFields)
         fromPersistValue (PersistMap o) =
             let columns = HM.fromList o
             in fromPersistValues $ map (name ->
               case HM.lookup name columns of
                 Just v -> v
                 Nothing -> PersistNull
         fromPersistValue x = Left $ "Expected PersistMap, received: " ++ show x
         sqlType _ = SqlString

# Internal

packPTH :: String -> Text

lensPTH :: (s -> a) -> (s -> b -> t) -> Lens s t a b