{-# LANGUAGE DeriveDataTypeable #-}{-# LANGUAGE OverloadedStrings #-}{-# LANGUAGE FlexibleInstances #-}{-# LANGUAGE FlexibleContexts #-}{- |
To work with concrete objects, use the following modules:
* "Database.CouchDB.Conduit.DB"
* "Database.CouchDB.Conduit.View"
* "Database.CouchDB.Conduit.Explicit"
* "Database.CouchDB.Conduit.Generic"
* "Database.CouchDB.Conduit.LowLevel"
For complete documentation about The Couch DB HTTP API see
<http://wiki.apache.org/couchdb/Complete_HTTP_API_Reference>
-}moduleDatabase.CouchDB.Conduit(-- * Document paths and revisions #path#-- $pathPath,mkPath,Revision,-- * CouchDB Connection #connection#CouchConnection,def,couchHost,couchPort,couchManager,couchDB,-- * Runtime enviroment and errors #runtime#-- $runtimeMonadCouch(..),CouchError(..),runCouch,withCouchConnection,)whereimportControl.Monad.Trans.Reader(ReaderT,ask,runReaderT)importControl.Exception(Exception)importControl.Monad.Trans.Class(lift)importData.Conduit(ResourceIO,ResourceT,runResourceT)importqualifiedNetwork.HTTP.ConduitasHimportqualifiedNetwork.HTTP.TypesasHTimportData.Generics(Typeable)importData.Default(Default(def))importqualifiedData.ByteStringasBimportqualifiedData.Text.EncodingasTEimportqualifiedBlaze.ByteString.BuilderasBLB------------------------------------------------------------------------------- Paths------------------------------------------------------------------------------- $path -- As a rule, full path to document in CouchDB is just URL path. But there is -- one subtlety. For example, document ids /can/ contain slashes. But, -- to work with such objects, path fragments must be escaped.-- -- > database/doc%2Fname---- But, fo non-document items such as views, attachments e.t.c., slashes-- between path fragments /must not/ be escaped. While slashes in path -- fragments /must/ be escaped.-- -- > database/_design/my%2Fdesign/_view/my%2Fview-- | Represents a path or path fragment.typePath=B.ByteString-- | Represents a revision of a CouchDB Document. typeRevision=B.ByteString-- | Make correct path from escaped fragments. Filter empty fragments.---- > mkPath ["db", "", "doc/with/slashes"]-- > db/doc%2Fwith%2FslashesmkPath::[Path]-- ^ Path fragments be escaped. ->PathmkPath=BLB.toByteString.HT.encodePathSegments.mapTE.decodeUtf8.filter(/="")------------------------------------------------------------------------------- Connection------------------------------------------------------------------------------- | Represents a single connection to CouchDB server. The constructor for this -- data type is not exposed. Instead, you should use either the 'def' method -- to retrieve a default instance.dataCouchConnection=CouchConnection{couchHost::B.ByteString-- ^ Hostname. Default value is \"localhost\",couchPort::Int-- ^ Port. 5984 by default.,couchManager::MaybeH.Manager-- ^ Connection 'Manager'. 'Nothing' by default. If you need to use-- your 'H.Manager' (for connection pooling for example), set it to-- 'Just' 'H.Manager'.,couchDB::Path-- ^ Database name. This value is prepended to 'Path' to form the full -- path in all requests.-- -- By default is 'B.empty'. This makes it possible to access -- different databases through a single connection. But, in this -- case, all requests must be preceded by the database name with -- unescaped slash. See 'Path' for details.}instanceDefaultCouchConnectionwheredef=CouchConnection"localhost"5984NothingB.empty------------------------------------------------------------------------------- Runtime------------------------------------------------------------------------------- $runtime-- All functions to access CouchDB require a 'MonadCouch' instance to -- access the connection information. 'ReaderT' is an instance of -- 'MonadCouch', and /runCouch/ runs a sequence of database actions using -- 'ReaderT' and 'ResourceT'.-- -- If your db code is part of a larger monad, it makes sense to just make the -- larger monad an instance of 'MonadCouch' and skip the intermediate ReaderT, -- since then performance is improved by eliminating one monad from the final -- transformer stack.-- | A monad which allows access to the connection.classResourceIOm=>MonadCouchmwherecouchConnection::mCouchConnectioninstance(ResourceIOm)=>MonadCouch(ReaderTCouchConnectionm)wherecouchConnection=ask-- | A Couch DB Error. If the error comes from http, the http status code -- is also given. Non-http errors include things like errors -- parsing the response.dataCouchError=CouchError(MaybeInt)Stringderiving(Show,Typeable)instanceExceptionCouchError-- | Run a sequence of CouchDB actions. This function is a combination of -- 'withCouchConnection', 'runReaderT' and 'runResourceT'.-- -- If you create your own instance of 'MonadCouch', use 'withCouchConnection'. runCouch::ResourceIOm=>CouchConnection-- ^ Couch connection->ResourceT(ReaderTCouchConnectionm)a-- ^ CouchDB actions->marunCouchc=withCouchConnectionc.runReaderT.runResourceT-- | Connect to a CouchDB server, call the supplied function, and then close -- the connection.-- -- > withCouchConnection def {couchDB = "db"} . runReaderT . runResourceT $ do-- > ... -- actionswithCouchConnection::ResourceIOm=>CouchConnection-- ^ Couch connection->(CouchConnection->ma)-- ^ Function to run->mawithCouchConnectionc@(CouchConnection__mayMan_)f=casemayManof-- Allocate manager with helperNothing->H.withManager$\m->lift$f$c{couchManager=Justm}_->fc