Copyright	(c) Joe Canero 2017
License	BSD3
Maintainer	jmc41493@gmail.com
Stability	experimental
Portability	POSIX
Safe Haskell	None
Language	Haskell2010

Database.Mbtiles

Contents

Types
Typeclasses
The MbtilesT monad transformer
- Pooling
Mbtiles read/write functionality
Mbtiles metadata functionality
Streaming tiles

Description

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.

Synopsis

data MbtilesT m a
type MbtilesIO a = MbtilesT IO a
type MbtilesMeta = HashMap Text Text
data MBTilesError
- = DoesNotExist
- | InvalidSchema
- | InvalidMetadata
- | InvalidTiles
newtype Z = Z Int
newtype X = X Int
newtype Y = Y Int
data Tile a = Tile {
- tileColumn :: Int
- tileRow :: Int
- zoomlevel :: Int
- tileData :: a
}
class ToTile a where
- toTile :: a -> ByteString
class FromTile a where
- fromTile :: ByteString -> a
runMbtilesT :: MonadIO m => FilePath -> MbtilesT m a -> m (Either MBTilesError a)
runMbtiles :: FilePath -> MbtilesIO a -> IO (Either MBTilesError a)
type MbtilesPool = Pool MbtilesData
getMbtilesPool :: MonadIO m => FilePath -> m (Either MBTilesError MbtilesPool)
runMbtilesPoolT :: MonadBaseControl IO m => MbtilesPool -> MbtilesT m a -> m a
getTile :: (MonadIO m, FromTile a) => Z -> X -> Y -> MbtilesT m (Maybe a)
writeTile :: (MonadIO m, ToTile a) => Z -> X -> Y -> a -> MbtilesT m ()
writeTiles :: (MonadIO m, ToTile a) => [(Z, X, Y, a)] -> MbtilesT m ()
updateTile :: (MonadIO m, ToTile a) => Z -> X -> Y -> a -> MbtilesT m ()
updateTiles :: (MonadIO m, ToTile a) => [(Z, X, Y, a)] -> MbtilesT m ()
getMetadata :: MonadIO m => MbtilesT m MbtilesMeta
getName :: MonadIO m => MbtilesT m Text
getType :: MonadIO m => MbtilesT m Text
getVersion :: MonadIO m => MbtilesT m Text
getDescription :: MonadIO m => MbtilesT m Text
getFormat :: MonadIO m => MbtilesT m Text
data TileStream
startTileStream :: MonadIO m => MbtilesT m TileStream
endTileStream :: MonadIO m => TileStream -> MbtilesT m ()
nextTile :: (MonadIO m, FromTile a) => TileStream -> MbtilesT m (Maybe (Tile a))

Types

data MbtilesT m a #

MbtilesT monad that will run actions on an MBTiles file.

Instances

MonadTrans MbtilesT #
Instance details Defined in Database.Mbtiles.Types Methods lift :: Monad m => m a -> MbtilesT m a #
Monad m => Monad (MbtilesT m) #
Instance details Defined in Database.Mbtiles.Types Methods (>>=) :: MbtilesT m a -> (a -> MbtilesT m b) -> MbtilesT m b # (>>) :: MbtilesT m a -> MbtilesT m b -> MbtilesT m b # return :: a -> MbtilesT m a # fail :: String -> MbtilesT m a #
Functor m => Functor (MbtilesT m) #
Instance details Defined in Database.Mbtiles.Types Methods fmap :: (a -> b) -> MbtilesT m a -> MbtilesT m b # (<$) :: a -> MbtilesT m b -> MbtilesT m a #
Applicative m => Applicative (MbtilesT m) #
Instance details Defined in Database.Mbtiles.Types Methods pure :: a -> MbtilesT m a # (<>) :: MbtilesT m (a -> b) -> MbtilesT m a -> MbtilesT m b # liftA2 :: (a -> b -> c) -> MbtilesT m a -> MbtilesT m b -> MbtilesT m c # (>) :: MbtilesT m a -> MbtilesT m b -> MbtilesT m b # (<*) :: MbtilesT m a -> MbtilesT m b -> MbtilesT m a #
MonadIO m => MonadIO (MbtilesT m) #
Instance details Defined in Database.Mbtiles.Types Methods liftIO :: IO a -> MbtilesT m a #

type MbtilesIO a = MbtilesT IO a #

Type specialization of MbtilesT to IO.

type MbtilesMeta = HashMap Text Text #

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.

data MBTilesError #

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

Constructors

DoesNotExist	The MBTiles file does not exist.
InvalidSchema	The MBTiles schema is invalid according to the spec.
InvalidMetadata	The MBTiles `metadata` table is invalid.
InvalidTiles	The MBTiles `tiles` table is invaid.

Instances

Eq MBTilesError #
Instance details Defined in Database.Mbtiles.Types Methods (==) :: MBTilesError -> MBTilesError -> Bool # (/=) :: MBTilesError -> MBTilesError -> Bool #
Show MBTilesError #
Instance details Defined in Database.Mbtiles.Types Methods showsPrec :: Int -> MBTilesError -> ShowS # show :: MBTilesError -> String # showList :: [MBTilesError] -> ShowS #

newtype Z #

Newtype wrapper around map zoom level.

Constructors

Z Int

Instances

ToField Z #
Instance details Defined in Database.Mbtiles.Types Methods toField :: Z -> SQLData #

newtype X #

Newtype wrapper around a tile's x-coordinate.

Constructors

X Int

Instances

ToField X #
Instance details Defined in Database.Mbtiles.Types Methods toField :: X -> SQLData #

newtype Y #

Newtype wrapper around a tile's y-coordinate.

Constructors

Y Int

Instances

ToField Y #
Instance details Defined in Database.Mbtiles.Types Methods toField :: Y -> SQLData #

data Tile a #

Data type that represents an entire row from an MBTiles database.

Constructors

Tile
Fields tileColumn :: Int The column of this tile. tileRow :: Int The row of this tile. zoomlevel :: Int The zoom level of this tile. tileData :: a The data associated with this tile.

Instances

Functor Tile #
Instance details Defined in Database.Mbtiles.Types Methods fmap :: (a -> b) -> Tile a -> Tile b # (<$) :: a -> Tile b -> Tile a #
Eq a => Eq (Tile a) #
Instance details Defined in Database.Mbtiles.Types Methods (==) :: Tile a -> Tile a -> Bool # (/=) :: Tile a -> Tile a -> Bool #
Ord a => Ord (Tile a) #
Instance details Defined in Database.Mbtiles.Types Methods compare :: Tile a -> Tile a -> Ordering # (<) :: Tile a -> Tile a -> Bool # (<=) :: Tile a -> Tile a -> Bool # (>) :: Tile a -> Tile a -> Bool # (>=) :: Tile a -> Tile a -> Bool # max :: Tile a -> Tile a -> Tile a # min :: Tile a -> Tile a -> Tile a #
Show a => Show (Tile a) #
Instance details Defined in Database.Mbtiles.Types Methods showsPrec :: Int -> Tile a -> ShowS # show :: Tile a -> String # showList :: [Tile a] -> ShowS #
FromTile a => FromRow (Tile a) #
Instance details Defined in Database.Mbtiles.Types Methods fromRow :: RowParser (Tile a) #

Typeclasses

class ToTile a where #

Typeclass representing data types that can be turned into a lazy ByteString and stored as tile data.

Methods

toTile :: a -> ByteString #

Instances

ToTile ByteString #
Instance details Defined in Database.Mbtiles.Types Methods toTile :: ByteString -> ByteString0 #
ToTile ByteString #
Instance details Defined in Database.Mbtiles.Types Methods toTile :: ByteString -> ByteString #

class FromTile a where #

Typeclass representing data types into which raw tile data can be converted.

Methods

fromTile :: ByteString -> a #

Instances

FromTile ByteString #
Instance details Defined in Database.Mbtiles.Types Methods fromTile :: ByteString0 -> ByteString #
FromTile ByteString #
Instance details Defined in Database.Mbtiles.Types Methods fromTile :: ByteString -> ByteString #

The MbtilesT monad transformer

runMbtilesT :: MonadIO m => FilePath -> MbtilesT m a -> m (Either MBTilesError a) #

Given a path to an MBTiles file, run the MbtilesT 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.

runMbtiles :: FilePath -> MbtilesIO a -> IO (Either MBTilesError a) #

Specialized version of runMbtilesT to run in the IO monad.

Pooling

type MbtilesPool = Pool MbtilesData #

A pool of connections to an MBTiles database.

getMbtilesPool :: MonadIO m => FilePath -> m (Either MBTilesError MbtilesPool) #

Given a path to an MBTiles file, create a connection pool to an MBTiles database. This will perform the same validation as runMbtilesT.

runMbtilesPoolT :: MonadBaseControl IO m => MbtilesPool -> MbtilesT m a -> m a #

Given access to an MbtilesPool, run an action against that pool.

Mbtiles read/write functionality

getTile :: (MonadIO m, FromTile a) => Z -> X -> Y -> MbtilesT m (Maybe a) #

Given a Z, X, and Y parameters, return the corresponding tile data, if it exists.

writeTile :: (MonadIO m, ToTile a) => Z -> X -> Y -> a -> MbtilesT m () #

Write new tile data to the tile at the specified Z, X, and Y parameters. This function assumes that the tile does not already exist.

writeTiles :: (MonadIO m, ToTile a) => [(Z, X, Y, a)] -> MbtilesT m () #

Batch write new tile data to the tile at the specified Z, X, and Y parameters. This function assumes that the tiles do not already exist.

updateTile :: (MonadIO m, ToTile a) => Z -> X -> Y -> a -> MbtilesT m () #

Update existing tile data for the tile at the specified Z, X, and Y parameters. This function assumes that the tile does already exist.

updateTiles :: (MonadIO m, ToTile a) => [(Z, X, Y, a)] -> MbtilesT m () #

Batch update tile data for the tiles at the specified Z, X, and Y parameters. This function assumes that the tiles do already exist.

Mbtiles metadata functionality

getMetadata :: MonadIO m => MbtilesT m MbtilesMeta #

Returns the MbtilesMeta that was found in the MBTiles file. This returns all of the currently available metadata for the MBTiles database.

getName :: MonadIO m => MbtilesT m Text #

Helper function for getting the specified name of the MBTiles from metadata.

getType :: MonadIO m => MbtilesT m Text #

Helper function for getting the type of the MBTiles from metadata.

getVersion :: MonadIO m => MbtilesT m Text #

Helper function for getting the version of the MBTiles from metadata.

getDescription :: MonadIO m => MbtilesT m Text #

Helper function for getting the description of the MBTiles from metadata.

getFormat :: MonadIO m => MbtilesT m Text #

Helper function for getting the format of the MBTiles from metadata.

Streaming tiles

data TileStream #

A TileStream 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.

startTileStream :: MonadIO m => MbtilesT m TileStream #

Create a TileStream data type that will be used to stream tiles from the MBTiles database. When streaming is complete, you must call endTileStream to clean up the TileStream 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.

endTileStream :: MonadIO m => TileStream -> MbtilesT m () #

Close a given TileStream when streaming is complete.

nextTile :: (MonadIO m, FromTile a) => TileStream -> MbtilesT m (Maybe (Tile a)) #

Receive the next Tile from the TileStream.