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


-- | Haskell MBTiles client.
--   
--   Read and manipulate MBTiles files and associated metadata.
@package mbtiles
@version 0.6.0.0


-- | This module provides support for reading, writing, and updating an
--   mbtiles database, as well as reading metadata from the database.
--   
--   There is also support for creating a pool of connections to an mbtiles
--   database and streaming tiles.
--   
--   See the associated README.md for basic usage examples.
module Database.Mbtiles

-- | MbtilesT monad that will run actions on an MBTiles file.
data MbtilesT m a

-- | Type specialization of <a>MbtilesT</a> to IO.
type MbtilesIO a = MbtilesT IO a

-- | MBTiles files contain metadata in one of their tables. This is a type
--   alias for a mapping between the metadata key and the metadata value.
type MbtilesMeta = HashMap Text Text

-- | Data type representing various errors that could occur when opening
--   and validating an MBTiles file.
data MBTilesError

-- | The MBTiles file does not exist.
DoesNotExist :: MBTilesError

-- | The MBTiles schema is invalid according to the spec.
InvalidSchema :: MBTilesError

-- | The MBTiles <tt>metadata</tt> table is invalid.
InvalidMetadata :: MBTilesError

-- | The MBTiles <tt>tiles</tt> table is invaid.
InvalidTiles :: MBTilesError

-- | Newtype wrapper around map zoom level.
newtype Z
Z :: Int -> Z

-- | Newtype wrapper around a tile's x-coordinate.
newtype X
X :: Int -> X

-- | Newtype wrapper around a tile's y-coordinate.
newtype Y
Y :: Int -> Y

-- | Data type that represents an entire row from an MBTiles database.
data Tile a
Tile :: Int -> Int -> Int -> a -> Tile a

-- | The column of this tile.
[tileColumn] :: Tile a -> Int

-- | The row of this tile.
[tileRow] :: Tile a -> Int

-- | The zoom level of this tile.
[zoomlevel] :: Tile a -> Int

-- | The data associated with this tile.
[tileData] :: Tile a -> a

-- | Typeclass representing data types that can be turned into a lazy
--   ByteString and stored as tile data.
class ToTile a
toTile :: ToTile a => a -> ByteString

-- | Typeclass representing data types into which raw tile data can be
--   converted.
class FromTile a
fromTile :: FromTile a => ByteString -> a

-- | Given a path to an MBTiles file, run the <a>MbtilesT</a> action. This
--   will open a connection to the MBTiles file, run the action, and then
--   close the connection. Some validation will be performed first. Of
--   course, we will check if the MBTiles file actually exists. If it does,
--   we need to validate its schema according to the MBTiles spec.
runMbtilesT :: (MonadIO m) => FilePath -> MbtilesT m a -> m (Either MBTilesError a)

-- | Specialized version of <a>runMbtilesT</a> to run in the IO monad.
runMbtiles :: FilePath -> MbtilesIO a -> IO (Either MBTilesError a)

-- | A pool of connections to an MBTiles database.
type MbtilesPool = Pool MbtilesData

-- | Given a path to an MBTiles file, create a connection pool to an
--   MBTiles database. This will perform the same validation as
--   <a>runMbtilesT</a>.
getMbtilesPool :: (MonadIO m) => FilePath -> m (Either MBTilesError MbtilesPool)

-- | Given access to an <a>MbtilesPool</a>, run an action against that
--   pool.
runMbtilesPoolT :: (MonadBaseControl IO m) => MbtilesPool -> MbtilesT m a -> m a

-- | Given a <a>Z</a>, <a>X</a>, and <a>Y</a> parameters, return the
--   corresponding tile data, if it exists.
getTile :: (MonadIO m, FromTile a) => Z -> X -> Y -> MbtilesT m (Maybe a)

-- | Write new tile data to the tile at the specified <a>Z</a>, <a>X</a>,
--   and <a>Y</a> parameters. This function assumes that the tile does not
--   already exist.
writeTile :: (MonadIO m, ToTile a) => Z -> X -> Y -> a -> MbtilesT m ()

-- | Batch write new tile data to the tile at the specified <a>Z</a>,
--   <a>X</a>, and <a>Y</a> parameters. This function assumes that the
--   tiles do not already exist.
writeTiles :: (MonadIO m, ToTile a) => [(Z, X, Y, a)] -> MbtilesT m ()

-- | Update existing tile data for the tile at the specified <a>Z</a>,
--   <a>X</a>, and <a>Y</a> parameters. This function assumes that the tile
--   does already exist.
updateTile :: (MonadIO m, ToTile a) => Z -> X -> Y -> a -> MbtilesT m ()

-- | Batch update tile data for the tiles at the specified <a>Z</a>,
--   <a>X</a>, and <a>Y</a> parameters. This function assumes that the
--   tiles do already exist.
updateTiles :: (MonadIO m, ToTile a) => [(Z, X, Y, a)] -> MbtilesT m ()

-- | Returns the <a>MbtilesMeta</a> that was found in the MBTiles file.
--   This returns all of the currently available metadata for the MBTiles
--   database.
getMetadata :: (MonadIO m) => MbtilesT m MbtilesMeta

-- | Helper function for getting the specified name of the MBTiles from
--   metadata.
getName :: (MonadIO m) => MbtilesT m Text

-- | Helper function for getting the type of the MBTiles from metadata.
getType :: (MonadIO m) => MbtilesT m Text

-- | Helper function for getting the version of the MBTiles from metadata.
getVersion :: (MonadIO m) => MbtilesT m Text

-- | Helper function for getting the description of the MBTiles from
--   metadata.
getDescription :: (MonadIO m) => MbtilesT m Text

-- | Helper function for getting the format of the MBTiles from metadata.
getFormat :: (MonadIO m) => MbtilesT m Text

-- | A <a>TileStream</a> data type contains information about how to stream
--   tiles from the MBTiles database and is used in the same manner as an
--   SQLite prepared statement.
data TileStream

-- | Create a <a>TileStream</a> data type that will be used to stream tiles
--   from the MBTiles database. When streaming is complete, you must call
--   <a>endTileStream</a> to clean up the <a>TileStream</a> resource. Tiles
--   are streamed from the database in an ordered fashion, where they are
--   sorted by zoom level, then tile column, then tile row, in ascending
--   order.
startTileStream :: (MonadIO m) => MbtilesT m TileStream

-- | Close a given <a>TileStream</a> when streaming is complete.
endTileStream :: (MonadIO m) => TileStream -> MbtilesT m ()

-- | Receive the next <a>Tile</a> from the <a>TileStream</a>.
nextTile :: (MonadIO m, FromTile a) => TileStream -> MbtilesT m (Maybe (Tile a))
