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


-- | sqlite-simple snaplet for the Snap Framework
--   
--   This snaplet provides support for using the SQLite database with a
--   Snap Framework application via the sqlite-simple package. It also
--   includes an authentication backend.
--   
--   See
--   <a>https://github.com/nurpax/snaplet-sqlite-simple/tree/master/example</a>
--   for an example project that demonstrates the use of this snaplet. It
--   implements a stand-alone application with a login screen that persists
--   user information in a SQLite database and allows a logged in user to
--   save comments. Querying and listing comments demonstrates how a user
--   of snaplet-sqlite-simple might relate Snaplet.Auth based AuthUsers to
--   his own tables.
@package snaplet-sqlite-simple
@version 0.4.1


-- | This snaplet makes it simple to use a SQLite database from your Snap
--   application and is based on the sqlite-simple library
--   (<a>http://hackage.haskell.org/package/sqlite-simple</a>). Now, adding
--   a database to your web app takes just two simple steps.
--   
--   First, include this snaplet in your application's state.
--   
--   <pre>
--   data App = App
--       { ... -- Other state needed in your app
--       , _db :: Snaplet Sqlite
--       }
--   </pre>
--   
--   Next, call the sqliteInit from your application's initializer.
--   
--   <pre>
--   appInit = makeSnaplet ... $ do
--       ...
--       d &lt;- nestSnaplet "db" db sqliteInit
--       return $ App ... d
--   </pre>
--   
--   Now you can use any of the sqlite-simple wrapper functions defined in
--   this module anywhere in your application handlers. For instance:
--   
--   <pre>
--   postHandler :: Handler App App ()
--   postHandler = do
--       posts &lt;- with db $ query_ "select * from blog_post"
--       ...
--   </pre>
--   
--   Optionally, if you find yourself doing many database queries, you can
--   eliminate some of the boilerplate by defining a HasSqlite instance for
--   your application.
--   
--   <pre>
--   instance HasSqlite (Handler b App) where
--     getSqliteState = with db get
--   </pre>
--   
--   With this code, our postHandler example no longer requires the
--   <a>with</a> function:
--   
--   <pre>
--   postHandler :: Handler App App ()
--   postHandler = do
--       posts &lt;- query_ "select * from blog_post"
--       ...
--   </pre>
--   
--   The first time you run an application with the sqlite-simple snaplet,
--   a configuration file <tt>devel.cfg</tt> is created in the
--   <tt>snaplets/sqlite-simple</tt> directory underneath your project
--   root. It specifies how to connect to your Sqlite database. Edit this
--   file and modify the values appropriately and you'll be off and
--   running.
--   
--   If you want to have out-of-the-box authentication, look at the
--   documentation for the <a>Snap.Snaplet.Auth.Backends.Sqlite</a> module.
module Snap.Snaplet.SqliteSimple

-- | The state for the sqlite-simple snaplet. To use it in your app include
--   this in your application state and use <a>sqliteInit</a> to initialize
--   it.
data Sqlite
Sqlite :: MVar Connection -> Sqlite

-- | Function for retrieving the database connection
sqliteConn :: Sqlite -> MVar Connection

-- | Instantiate this typeclass on 'Handler b YourAppState' so this snaplet
--   can find the connection source. If you need to have multiple instances
--   of the sqlite snaplet in your application, then don't provide this
--   instance and leverage the default instance by using "<tt>with
--   dbLens</tt>" in front of calls to snaplet-sqlite-simple functions.
class MonadCatchIO m => HasSqlite m
getSqliteState :: HasSqlite m => m Sqlite

-- | Initialize the snaplet
sqliteInit :: SnapletInit b Sqlite

-- | Convenience function for executing a function that needs a database
--   connection.
--   
--   <i>Multi-threading considerations</i>: The database connection is
--   mutexed such that only a single thread can read or write at any given
--   time. This means we lose database access parallelism. Please see
--   <a>https://github.com/nurpax/snaplet-sqlite-simple/issues/5</a> for
--   more information.
withSqlite :: HasSqlite m => (Connection -> IO b) -> m b

-- | See <a>query</a>
--   
--   See also <a>withSqlite</a> for notes on concurrent access.
query :: (HasSqlite m, ToRow q, FromRow r) => Query -> q -> m [r]

-- | See <a>query_</a>
--   
--   See also <a>withSqlite</a> for notes on concurrent access.
query_ :: (HasSqlite m, FromRow r) => Query -> m [r]

-- | See also <a>withSqlite</a> for notes on concurrent access.
execute :: (HasSqlite m, ToRow q, MonadCatchIO m) => Query -> q -> m ()

-- | See also <a>withSqlite</a> for notes on concurrent access.
execute_ :: (HasSqlite m, MonadCatchIO m) => Query -> m ()

-- | Connection to an open database.
data Connection :: *

-- | A query string. This type is intended to make it difficult to
--   construct a SQL query by concatenating string fragments, as that is an
--   extremely common way to accidentally introduce SQL injection
--   vulnerabilities into an application.
--   
--   This type is an instance of <a>IsString</a>, so the easiest way to
--   construct a query is to enable the <tt>OverloadedStrings</tt> language
--   extension and then simply write the query in double quotes.
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import Database.SQLite.Simple
--   
--   q :: Query
--   q = "select ?"
--   </pre>
--   
--   The underlying type is a <tt>Text</tt>, and literal Haskell strings
--   that contain Unicode characters will be correctly transformed to
--   UTF-8.
data Query :: *

-- | A single-value "collection".
--   
--   This is useful if you need to supply a single parameter to a SQL
--   query, or extract a single column from a SQL result.
--   
--   Parameter example:
--   
--   <pre>
--   query c "select x from scores where x &gt; ?" (<a>Only</a> (42::Int))
--   </pre>
--   
--   Result example:
--   
--   <pre>
--   xs &lt;- query_ c "select id from users"
--   forM_ xs $ \(<a>Only</a> id) -&gt; {- ... -}
--   </pre>
newtype Only a :: * -> *
Only :: a -> Only a
fromOnly :: Only a -> a

-- | Exception thrown if a <a>Query</a> was malformed. This may occur if
--   the number of '<tt>?</tt>' characters in the query string does not
--   match the number of parameters provided.
data FormatError :: *

-- | Exception thrown if conversion from a SQL value to a Haskell value
--   fails.
data ResultError :: *

-- | A composite type to parse your custom data structures without having
--   to define dummy newtype wrappers every time.
--   
--   <pre>
--   instance FromRow MyData where ...
--   </pre>
--   
--   <pre>
--   instance FromRow MyData2 where ...
--   </pre>
--   
--   then I can do the following for free:
--   
--   <pre>
--   res &lt;- query' c <a>...</a>
--   forM res $ \(MyData{..} :. MyData2{..}) -&gt; do
--     ....
--   </pre>
data (:.) h t :: * -> * -> *
(:.) :: h -> t -> :. h t

-- | A collection type that can be turned into a list of SQLData elements.
class ToRow a
toRow :: ToRow a => a -> [SQLData]

-- | A collection type that can be converted from a sequence of fields.
--   Instances are provided for tuples up to 10 elements and lists of any
--   length.
--   
--   Note that instances can defined outside of sqlite-simple, which is
--   often useful. For example, here's an instance for a user-defined pair:
--   
--   <pre>
--   data User = User { name :: String, fileQuota :: Int }
--   
--   instance <a>FromRow</a> User where
--        fromRow = User &lt;$&gt; <a>field</a> &lt;*&gt; <a>field</a>
--   </pre>
--   
--   The number of calls to <a>field</a> must match the number of fields
--   returned in a single row of the query result. Otherwise, a
--   <a>ConversionFailed</a> exception will be thrown.
--   
--   Note the caveats associated with user-defined implementations of
--   <a>fromRow</a>.
class FromRow a
fromRow :: FromRow a => RowParser a
field :: FromField a => RowParser a
instance MonadCatchIO m => HasSqlite (ReaderT Sqlite m)
instance MonadCatchIO m => HasSqlite (ReaderT (Snaplet Sqlite) m)
instance HasSqlite (Handler b Sqlite)


-- | This module allows you to use the auth snaplet with your user database
--   stored in a SQLite database. When you run your application with this
--   snaplet, a config file will be copied into the the
--   <tt>snaplets/sqlite-auth</tt> directory. This file contains all of the
--   configurable options for the snaplet and allows you to change them
--   without recompiling your application.
--   
--   To use this snaplet in your application enable the session, sqlite,
--   and auth snaplets as follows:
--   
--   <pre>
--   data App = App
--       { ... -- your own application state here
--       , _sess :: Snaplet SessionManager
--       , _db   :: Snaplet Sqlite
--       , _auth :: Snaplet (AuthManager App)
--       }
--   </pre>
--   
--   Then in your initializer you'll have something like this:
--   
--   <pre>
--   d &lt;- nestSnaplet "db" db sqliteInit
--   a &lt;- nestSnaplet "auth" auth $ initSqliteAuth sess d
--   </pre>
--   
--   If you have not already created the database table for users, it will
--   automatically be created for you the first time you run your
--   application.
module Snap.Snaplet.Auth.Backends.SqliteSimple

-- | Initializer for the sqlite backend to the auth snaplet.
initSqliteAuth :: SnapletLens b SessionManager -> Snaplet Sqlite -> SnapletInit b (AuthManager b)
instance IAuthBackend SqliteAuthManager
instance ToField Password
instance FromRow AuthUser
instance FromField Password
instance FromField UserId