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


-- | Type-safe datatype-database mapping library.
--   
--   This library analyzes database tables and creates corresponding
--   datatypes and their mappings for Groundhog
--   <a>https://www.fpcomplete.com/user/lykahb/groundhog</a>. See examples
--   at
--   <a>https://github.com/lykahb/groundhog/tree/master/groundhog-inspector/examples</a>.
@package groundhog-inspector
@version 0.8.0.2


-- | A library for creating datatypes and Groundhog mappings from a
--   database schema. The mappings match the database structure so if you
--   run migration for the generated mappings, no changes to schema should
--   be suggested. The generated Haskell identifiers may sometimes conflict
--   with each other and with Haskell keywords. If that happens, adjust
--   <a>ReverseNamingStyle</a>.
module Database.Groundhog.Inspector

-- | Returns tables from a passed schema and tables which they reference.
--   If you call collectTables several times with different filtering
--   functions, it is better to call <a>followReferencedTables</a>
--   afterwards manually to ensure that no dependencies are missing
--   
--   <pre>
--   let filterRefs (schema, tableName) = schema /= "audit"
--   publicTables  &lt;- collectTables filterRefs (Just "public")
--   websiteTables &lt;- collectTables filterRefs (Just "website")
--   let allTables = publicTables &lt;&gt; websiteTables
--   </pre>
collectTables :: (PersistBackend m, SchemaAnalyzer (Conn m)) => (QualifiedName -> Bool) -> Maybe String -> m (Map QualifiedName TableInfo)

-- | It supplies the names for the haskell datatypes
data ReverseNamingStyle
ReverseNamingStyle :: (QualifiedName -> String) -> (QualifiedName -> String) -> (QualifiedName -> String -> String) -> (QualifiedName -> Reference -> String) -> (QualifiedName -> [UniqueDefInfo] -> UniqueDefInfo) -> (QualifiedName -> UniqueDefInfo -> String) -> (QualifiedName -> Int -> UniqueDefInfo -> String) -> ReverseNamingStyle

-- | Create name of the datatype. Parameters: table name.
[mkEntityName] :: ReverseNamingStyle -> QualifiedName -> String

-- | Create name of the constructor. Parameters: table name.
[mkConstructorName] :: ReverseNamingStyle -> QualifiedName -> String

-- | Create name of the field. Parameters: table name, column name.
[mkFieldName] :: ReverseNamingStyle -> QualifiedName -> String -> String

-- | Create name for unique key field. It creates record name both for
--   one-column and composite keys. Parameters: table name, reference.
[mkKeyFieldName] :: ReverseNamingStyle -> QualifiedName -> Reference -> String

-- | There can be several uniques with the same columns (one primary key
--   and multiple constraints and indexes). The function must return a
--   stable name regardless of the list order.
[mkChooseReferencedUnique] :: ReverseNamingStyle -> QualifiedName -> [UniqueDefInfo] -> UniqueDefInfo

-- | Create name for phantom unique key used to parametrise <a>Key</a>.
--   Parameters: table name, unique key definition.
[mkUniqueKeyPhantomName] :: ReverseNamingStyle -> QualifiedName -> UniqueDefInfo -> String

-- | Create name of unique in mapping. Parameters: table name, unique
--   number, unique key definition.
[mkUniqueName] :: ReverseNamingStyle -> QualifiedName -> Int -> UniqueDefInfo -> String
defaultReverseNamingStyle :: ReverseNamingStyle

-- | It looks for the references to the tables not contained in the passed
--   map. If there are such references and the reference filter function
--   returns True, the corresponding TableInfo is fetched and included into
--   the map. The references for the newly added tables are processed in
--   the same way. This function can be useful if your set of tables is
--   created not by <a>collectTables</a>.
followReferencedTables :: (PersistBackend m, SchemaAnalyzer (Conn m)) => (QualifiedName -> Bool) -> Map QualifiedName TableInfo -> m (Map QualifiedName TableInfo)

-- | Confuguration datatype generation
data DataCodegenConfig
DataCodegenConfig :: Bool -> (Column -> Type) -> DataCodegenConfig

-- | The unique key phantoms can be generated by groundhog-inspector when
--   creating mappings or by groundhog-th when processing mappings. Set
--   this to False in case you have declaration collisions. They may happen
--   if the mappings are passed to groundhog-th on the fly.
[generateUniqueKeysPhantoms] :: DataCodegenConfig -> Bool

-- | Creates a Haskell type. Typically this function analyzes column
--   nullability and its DB type
[mkType] :: DataCodegenConfig -> Column -> Type
defaultDataCodegenConfig :: DataCodegenConfig

-- | Returns declarations for the mapped datatype and auxiliary
--   declarations like unique key phantom datatypes
generateData :: DataCodegenConfig -> ReverseNamingStyle -> Map QualifiedName TableInfo -> Map QualifiedName (Dec, [Dec])

-- | It pretty-prints Template Haskell declaration into compilable Haskell
--   code
showData :: Dec -> String
defaultMkType :: Column -> Type

-- | It uses Sqlite type affinity to find the corresponding Haskell type
sqliteMkType :: Column -> Type
generateMapping :: (PersistBackend m, SchemaAnalyzer (Conn m)) => ReverseNamingStyle -> Map QualifiedName TableInfo -> m (Map QualifiedName PSEntityDef)

-- | The mappings created by <a>generateMapping</a> contain a lot of
--   setttings. This function makes the settings more compact by
--   eliminating settings which are default for the passed
--   <a>NamingStyle</a>.
minimizeMapping :: NamingStyle -> Dec -> PSEntityDef -> PSEntityDef

-- | It pretty-prints the mapping settings as JSON. Package groundhog-th
--   accepts JSON and YAML which is a more human-readable superset of JSON.
--   You can use a third-party tool to convert JSON to YAML.
showMappings :: [PSEntityDef] -> ByteString
