Safe Haskell  None 

Language  Haskell98 
Higher LevelDB provides a rich monadic API for working with leveldb (http://code.google.com/p/leveldb) databases. It uses
the leveldbhaskell bindings to the C++ library. The LevelDBT transformer is
a Reader that maintains a database context with the open database as well as
default read and write options. It also manages a concept called a KeySpace, which is a bucket
scheme that provides a low (storage) overhead named identifier to segregate data. Finally it wraps a ResourceT
which is required for use of leveldbhaskell functions.
The other major feature is the scan function and its ScanQuery structure that provides a map / fold abstraction over the Iterator exposed by leveldbhaskell.
 type Key = ByteString
 type Value = ByteString
 type Item = (Key, Value)
 type KeySpace = ByteString
 type KeySpaceId = ByteString
 get :: MonadLevelDB m => Key > m (Maybe Value)
 put :: MonadLevelDB m => Key > Value > m ()
 delete :: MonadLevelDB m => Key > m ()
 runBatch :: MonadLevelDB m => WriterT WriteBatch m () > m ()
 putB :: MonadLevelDB m => Key > Value > WriterT WriteBatch m ()
 deleteB :: MonadLevelDB m => Key > WriterT WriteBatch m ()
 scan :: MonadLevelDB m => Key > ScanQuery a b > m b
 data ScanQuery a b = ScanQuery {}
 queryItems :: ScanQuery Item [Item]
 queryList :: ScanQuery a [a]
 queryBegins :: ScanQuery a b
 queryCount :: Num a => ScanQuery a a
 withKeySpace :: MonadLevelDB m => KeySpace > m a > m a
 withOptions :: MonadLevelDB m => RWOptions > m a > m a
 withSnapshot :: MonadLevelDB m => m a > m a
 forkLevelDB :: MonadLevelDB m => LevelDB () > m ThreadId
 class (Monad m, MonadThrow m, MonadIO m, Applicative m, MonadResource m) => MonadLevelDB m where
 data LevelDBT m a
 type LevelDB a = LevelDBT IO a
 mapLevelDBT :: (m a > n b) > LevelDBT m a > LevelDBT n b
 runLevelDB :: (MonadThrow m, MonadUnliftIO m) => FilePath > Options > RWOptions > KeySpace > LevelDBT m a > m a
 runLevelDB' :: (MonadThrow m, MonadUnliftIO m) => FilePath > Options > RWOptions > KeySpace > LevelDBT m a > ResourceT m a
 runCreateLevelDB :: (MonadThrow m, MonadUnliftIO m) => FilePath > KeySpace > LevelDBT m a > m a
 runResourceT :: MonadUnliftIO m => ResourceT m a > m a
 data Options :: * = Options {
 blockRestartInterval :: !Int
 blockSize :: !Int
 cacheSize :: !Int
 comparator :: !(Maybe Comparator)
 compression :: !Compression
 createIfMissing :: !Bool
 errorIfExists :: !Bool
 maxOpenFiles :: !Int
 paranoidChecks :: !Bool
 writeBufferSize :: !Int
 filterPolicy :: !(Maybe (Either BloomFilter FilterPolicy))
 data ReadOptions :: * = ReadOptions {
 verifyCheckSums :: !Bool
 fillCache :: !Bool
 useSnapshot :: !(Maybe Snapshot)
 data WriteOptions :: * = WriteOptions {}
 type RWOptions = (ReadOptions, WriteOptions)
 type WriteBatch = [BatchOp]
 def :: Default a => a
 class Monad m => MonadThrow (m :: * > *)
 class MonadIO m => MonadUnliftIO (m :: * > *)
Introduction
Operations take place within a MonadLevelDB
which is built with the LevelDBT transformer; the most
basic type would be LevelDBT
IO
which is type aliased as LevelDB
. The basic operations are
the same as the underlying leveldbhaskell versions except that the DB and Options arguments are
passed along by the LevelDB Reader, and the keys are automatically qualified with the KeySpaceId.
{# LANGUAGE OverloadedStrings #} import Database.LevelDB.Higher runCreateLevelDB "/tmp/mydb" "MyKeySpace" $ do put "key:1" "this is a value" get "key:1" Just "this is a value"
Basic types
type Key = ByteString Source #
type Value = ByteString Source #
type KeySpace = ByteString Source #
A KeySpace is similar concept to a "bucket" in other libraries and database systems. The ByteString for KeySpace can be arbitrarily long without performance impact because the system maps the KeySpace name to a 4byte KeySpaceId internally which is preprended to each Key. KeySpaces are cheap and plentiful and indeed with this library you cannot escape them (you can supply an empty ByteString to use a default KeySpace, but it is still used). One intended use case is to use the full Key of a "parent" as the KeySpace of its children (instance data in a timeseries for example). This lets you scan over a rangebased key without passing over any unneeded items.
type KeySpaceId = ByteString Source #
Basic operations
get :: MonadLevelDB m => Key > m (Maybe Value) Source #
Get a value from the current DB and KeySpace.
delete :: MonadLevelDB m => Key > m () Source #
Delete an entry from the current DB and KeySpace.
Batch operations
runBatch :: MonadLevelDB m => WriterT WriteBatch m () > m () Source #
Write a batch of operations  use the write
and deleteB
functions to
add operations to the batch list.
putB :: MonadLevelDB m => Key > Value > WriterT WriteBatch m () Source #
deleteB :: MonadLevelDB m => Key > WriterT WriteBatch m () Source #
Scans
:: MonadLevelDB m  
=> Key  Key at which to start the scan. 
> ScanQuery a b  query functions to execute  see 
> m b 
Scan the keyspace, applying functions and returning results.
Look at the documentation for ScanQuery
for more information.
This is essentially a fold left that will run until the scanWhile
condition is met or the iterator is exhausted. All the results will be
copied into memory before the function returns.
Structure containing functions used within the scan
function. You may want to start
with one of the builder/helper funcions such as queryItems
, which is defined as:
queryItems = queryBegins { scanInit = [] , scanMap = id , scanFold = (:) }
queryItems :: ScanQuery Item [Item] Source #
A basic ScanQuery helper; this query will find all keys that begin the Key argument
supplied to scan, and returns them in a list of Item
.
Does not require any function overrides.
queryList :: ScanQuery a [a] Source #
a ScanQuery helper with defaults for queryBegins and a list result; requires a map function e.g.:
scan "encodedvalues:" queryList { scanMap = \(_, v) > decode v }
queryBegins :: ScanQuery a b Source #
queryCount :: Num a => ScanQuery a a Source #
a ScanQuery helper to count items beginning with Key argument.
Context modifiers
withKeySpace :: MonadLevelDB m => KeySpace > m a > m a Source #
Use a local keyspace for the operation. e.g.:
runCreateLevelDB "/tmp/mydb" "MyKeySpace" $ do put "somekey" "somevalue" withKeySpace "Other KeySpace" $ do put "somekey" "someother value" get "somekey" Just "somevalue"
withOptions :: MonadLevelDB m => RWOptions > m a > m a Source #
Local Read/Write Options for the action.
withSnapshot :: MonadLevelDB m => m a > m a Source #
Run a block of get operations based on a single snapshot taken at the beginning of the action. The snapshot will be automatically released when complete.
This means that you can do put operations in the same block, but you will not see those changes inside this computation.
forkLevelDB :: MonadLevelDB m => LevelDB () > m ThreadId Source #
Fork a LevelDBT IO action and return ThreadId into the current monad.
This uses resourceForkIO
to handle the reference counting and cleanup resources
when the last thread exits.
Monadic Types and Operations
class (Monad m, MonadThrow m, MonadIO m, Applicative m, MonadResource m) => MonadLevelDB m where Source #
MonadLevelDB class used by all the public functions in this module.
withDBContext :: (DBContext > DBContext) > m a > m a Source #
Override context for an action  only usable internally for functions
like withKeySpace
and withOptions
.
liftLevelDB :: LevelDBT IO a > m a Source #
Lift a LevelDBT IO action into the current monad.
(Monad m, MonadLevelDB m) => MonadLevelDB (ListT m) Source #  
(Monad m, MonadLevelDB m) => MonadLevelDB (MaybeT m) Source #  
(MonadThrow m, MonadUnliftIO m) => MonadLevelDB (LevelDBT m) Source #  
(Monad m, MonadLevelDB m) => MonadLevelDB (ExceptT e m) Source #  
(Monad m, MonadLevelDB m) => MonadLevelDB (StateT s m) Source #  
(Monad m, MonadLevelDB m) => MonadLevelDB (StateT s m) Source #  
(Monoid w, MonadLevelDB m) => MonadLevelDB (WriterT w m) Source #  
(Monoid w, MonadLevelDB m) => MonadLevelDB (WriterT w m) Source #  
(Monad m, MonadLevelDB m) => MonadLevelDB (IdentityT * m) Source #  
(Monad m, MonadLevelDB m) => MonadLevelDB (ContT * r m) Source #  
(Monad m, MonadLevelDB m) => MonadLevelDB (ReaderT * r m) Source #  
(Monoid w, MonadLevelDB m) => MonadLevelDB (RWST r w s m) Source #  
(Monoid w, MonadLevelDB m) => MonadLevelDB (RWST r w s m) Source #  
LevelDBT Transformer provides a context for database operations provided in this module.
This transformer has the same constraints as ResourceT
as it wraps
ResourceT
along with a DBContext
Reader
.
If you aren't building a custom monad stack you can just use the LevelDB
alias.
MonadTrans LevelDBT Source #  
MonadBase b m => MonadBase b (LevelDBT m) Source #  
Monad m => Monad (LevelDBT m) Source #  
Functor m => Functor (LevelDBT m) Source #  
Applicative m => Applicative (LevelDBT m) Source #  
MonadIO m => MonadIO (LevelDBT m) Source #  
MonadThrow m => MonadThrow (LevelDBT m) Source #  
MonadCatch m => MonadCatch (LevelDBT m) Source #  
MonadMask m => MonadMask (LevelDBT m) Source #  
MonadUnliftIO m => MonadResource (LevelDBT m) Source #  
(MonadThrow m, MonadUnliftIO m) => MonadLevelDB (LevelDBT m) Source #  
type LevelDB a = LevelDBT IO a Source #
alias for LevelDBT IO  useful if you aren't building a custom stack.
mapLevelDBT :: (m a > n b) > LevelDBT m a > LevelDBT n b Source #
Map/transform the monad below the LevelDBT
:: (MonadThrow m, MonadUnliftIO m)  
=> FilePath  path to DB to open/create 
> Options  database options to use 
> RWOptions  default read/write ops; use 
> KeySpace  Bucket in which Keys will be unique 
> LevelDBT m a  The actions to execute 
> m a 
Build a context and execute the actions; uses a ResourceT
internally.
tip: you can use the Data.Default (def) method to specify default options e.g.
runLevelDB "/tmp/mydb" def (def, def{sync = true}) "My Keyspace" $ do
:: (MonadThrow m, MonadUnliftIO m)  
=> FilePath  path to DB to open/create 
> Options  database options to use 
> RWOptions  default read/write ops; use 
> KeySpace  Bucket in which Keys will be unique 
> LevelDBT m a  The actions to execute 
> ResourceT m a 
Same as runLevelDB
but doesn't call runResourceT
. This gives you the option
to manage that yourself
:: (MonadThrow m, MonadUnliftIO m)  
=> FilePath  path to DB to open/create 
> KeySpace  Bucket in which Keys will be unique 
> LevelDBT m a  The actions to execute 
> m a 
A helper for runLevelDB using default Options
except createIfMissing=True
Reexports
runResourceT :: MonadUnliftIO m => ResourceT m a > m a #
Unwrap a ResourceT
transformer, and call all registered release actions.
Note that there is some reference counting involved due to resourceForkIO
.
If multiple threads are sharing the same collection of resources, only the
last call to runResourceT
will deallocate the resources.
NOTE Since version 1.2.0, this function will throw a
ResourceCleanupException
if any of the cleanup functions throw an
exception.
Since: 0.3.0
Options when opening a database
Options  

data ReadOptions :: * #
Options for read operations
ReadOptions  

data WriteOptions :: * #
Options for write operations
WriteOptions  

type RWOptions = (ReadOptions, WriteOptions) Source #
type WriteBatch = [BatchOp] #
class Monad m => MonadThrow (m :: * > *) #
A class for monads in which exceptions may be thrown.
Instances should obey the following law:
throwM e >> x = throwM e
In other words, throwing an exception shortcircuits the rest of the monadic computation.
MonadThrow []  
MonadThrow Maybe  
MonadThrow IO  
MonadThrow Q  
MonadThrow STM  
(~) * e SomeException => MonadThrow (Either e)  
MonadThrow m => MonadThrow (ListT m)  
MonadThrow m => MonadThrow (ResourceT m)  
MonadThrow m => MonadThrow (MaybeT m)  Throws exceptions into the base monad. 
MonadThrow m => MonadThrow (LevelDBT m) #  
(Error e, MonadThrow m) => MonadThrow (ErrorT e m)  Throws exceptions into the base monad. 
MonadThrow m => MonadThrow (ExceptT e m)  Throws exceptions into the base monad. 
MonadThrow m => MonadThrow (StateT s m)  
MonadThrow m => MonadThrow (StateT s m)  
(MonadThrow m, Monoid w) => MonadThrow (WriterT w m)  
(MonadThrow m, Monoid w) => MonadThrow (WriterT w m)  
MonadThrow m => MonadThrow (IdentityT * m)  
MonadThrow m => MonadThrow (ContT * r m)  
MonadThrow m => MonadThrow (ReaderT * r m)  
(MonadThrow m, Monoid w) => MonadThrow (RWST r w s m)  
(MonadThrow m, Monoid w) => MonadThrow (RWST r w s m)  
class MonadIO m => MonadUnliftIO (m :: * > *) #
Monads which allow their actions to be run in IO
.
While MonadIO
allows an IO
action to be lifted into another
monad, this class captures the opposite concept: allowing you to
capture the monadic context. Note that, in order to meet the laws
given below, the intuition is that a monad must have no monadic
state, but may have monadic context. This essentially limits
MonadUnliftIO
to ReaderT
and IdentityT
transformers on top of
IO
.
Laws. For any value u
returned by askUnliftIO
, it must meet the
monad transformer laws as reformulated for MonadUnliftIO
:
unliftIO u . return = return
unliftIO u (m >>= f) = unliftIO u m >>= unliftIO u . f
The third is a currently nameless law which ensures that the current context is preserved.
askUnliftIO >>= (u > liftIO (unliftIO u m)) = m
If you have a name for this, please submit it in a pull request for great glory.
Since: 0.1.0.0
MonadUnliftIO IO  
MonadUnliftIO m => MonadUnliftIO (ResourceT m)  Since: 1.1.10 
MonadUnliftIO m => MonadUnliftIO (IdentityT * m)  
MonadUnliftIO m => MonadUnliftIO (ReaderT * r m)  