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

-- | A minimalist web framework for the WAI server interface
--   
--   Simple is "framework-less" web framework for Haskell web applications
--   based on the WAI server interface (e.g. for use with the warp server).
--   Simple does not enforce a particular structure or paradigm for web
--   applications. Rather, Simple contains tools to help you create your
--   own patterns (or re-create existing ones). Simple is minimalist,
--   providing a lightweight base - the most basic Simple app is little
--   more than a WAI Application with some routing logic. Everything
--   else (e.g. authentication, controllers, persistence, caching etc') is
--   provided in composable units, so you can include only the ones you
--   need in your app, and easily replace with your own components.
--   
--   To get started, create an app skeleton with the smpl utility:
--   
--   
--   $ cabal install simple
--   $ smpl create my_app_name
--   $ cd my_app_name
--   $ smpl
--   
--   
--   See Web.Simple for a more detailed introduction.
@package simple
@version 0.11.1

-- | This module defines some convenience functions for creating responses.
module Web.Simple.Responses

-- | Creates a 200 (OK) Response with the given content-type and
--   resposne body
ok :: ContentType -> ByteString -> Response

-- | Creates a 200 (OK) Response with content-type "text/html" and
--   the given resposne body
okHtml :: ByteString -> Response

-- | Creates a 200 (OK) Response with content-type
--   "application/json" and the given resposne body
okJson :: ByteString -> Response

-- | Creates a 200 (OK) Response with content-type "application/xml"
--   and the given resposne body
okXml :: ByteString -> Response

-- | Given a URL returns a 301 (Moved Permanently) Response
--   redirecting to that URL.
movedTo :: String -> Response

-- | Given a URL returns a 303 (See Other) Response redirecting to
--   that URL.
redirectTo :: ByteString -> Response

-- | Returns a 400 (Bad Request) Response.
badRequest :: Response

-- | Returns a 401 (Authorization Required) Response requiring basic
--   authentication in the given realm.
requireBasicAuth :: String -> Response

-- | Returns a 403 (Forbidden) Response.
forbidden :: Response

-- | Returns a 404 (Not Found) Response.
notFound :: Response

-- | Returns a 500 (Server Error) Response.
serverError :: ByteString -> Response

-- | ControllerT provides a convenient syntax for writting
--   Application code as a Monadic action with access to an HTTP
--   request as well as app specific data (e.g. a database connection pool,
--   app configuration etc.) This module also defines some helper functions
--   that leverage this feature. For example, redirectBack reads the
--   underlying request to extract the referer and returns a redirect
--   response:
--   
--   
--   myControllerT = do
--     ...
--     if badLogin then
--       redirectBack
--       else
--         ...
--   
--   
module Web.Simple.Controller.Trans

-- | The ControllerT Monad is both a State-like monad which, when run,
--   computes either a Response or a result. Within the ControllerT
--   Monad, the remainder of the computation can be short-circuited by
--   responding with a Response.
newtype ControllerT s m a
ControllerT :: (s -> Request -> m (Either Response a, s)) -> ControllerT s m a
[runController] :: ControllerT s m a -> s -> Request -> m (Either Response a, s)
hoistEither :: Monad m => Either Response a -> ControllerT s m a

-- | Extract the request
request :: Monad m => ControllerT s m Request

-- | Modify the request for the given computation
localRequest :: Monad m => (Request -> Request) -> ControllerT s m a -> ControllerT s m a

-- | Extract the application-specific state
controllerState :: Monad m => ControllerT s m s
putState :: Monad m => s -> ControllerT s m ()

-- | Convert the controller into an Application
controllerApp :: Monad m => s -> ControllerT s m a -> SimpleApplication m

-- | Provide a response
--   
--   
--   respond r >>= f === respond r
--   
respond :: Monad m => Response -> ControllerT s m a

-- | Lift an application to a controller
fromApp :: Monad m => (Request -> m Response) -> ControllerT s m ()

-- | Matches on the hostname from the Request. The route only
--   succeeds on exact matches.
routeHost :: Monad m => ByteString -> ControllerT s m a -> ControllerT s m ()

-- | Matches if the path is empty.
--   
--   Note that this route checks that pathInfo is empty, so it works
--   as expected in nested contexts that have popped components from the
--   pathInfo list.
routeTop :: Monad m => ControllerT s m a -> ControllerT s m ()

-- | Matches on the HTTP request method (e.g. GET, POST,
--   PUT)
routeMethod :: Monad m => StdMethod -> ControllerT s m a -> ControllerT s m ()

-- | Matches if the request's Content-Type exactly matches the given string
routeAccept :: Monad m => ByteString -> ControllerT s m a -> ControllerT s m ()

-- | Routes the given URL pattern. Patterns can include directories as well
--   as variable patterns (prefixed with :) to be added to
--   queryString (see routeVar)
--   
--   
--   
- /posts/:id
--   
- /posts/:id/new
--   
- /:date/posts/:category/new
--   
routePattern :: Monad m => Text -> ControllerT s m a -> ControllerT s m ()

-- | Matches if the first directory in the path matches the given
--   ByteString
routeName :: Monad m => Text -> ControllerT s m a -> ControllerT s m ()

-- | Always matches if there is at least one directory in pathInfo
--   but and adds a parameter to queryString where the key is the
--   first parameter and the value is the directory consumed from the path.
routeVar :: Monad m => Text -> ControllerT s m a -> ControllerT s m ()

-- | Looks up the parameter name in the request's query string and returns
--   the Parseable value or Nothing.
--   
--   For example, for a request with query string: "?foo=bar&baz=7",
--   queryParam "foo" would return Just "bar", but
--   queryParam "zap" would return Nothing.
queryParam :: (Monad m, Parseable a) => ByteString -> ControllerT s m (Maybe a)

-- | Like queryParam, but throws an exception if the parameter is
--   not present.
queryParam' :: (Monad m, Parseable a) => ByteString -> ControllerT s m a

-- | Selects all values with the given parameter name
queryParams :: (Monad m, Parseable a) => ByteString -> ControllerT s m [a]

-- | The class of types into which query parameters may be converted
class Parseable a
parse :: Parseable a => ByteString -> a

-- | Like queryParam, but further processes the parameter value with
--   read. If that conversion fails, an exception is thrown.
readQueryParam :: (Monad m, Read a) => ByteString -> ControllerT s m (Maybe a)

-- | Like readQueryParam, but throws an exception if the parameter
--   is not present.
readQueryParam' :: (Monad m, Read a) => ByteString -> ControllerT s m a

-- | Like queryParams, but further processes the parameter values
--   with read. If any read-conversion fails, an exception is
--   thrown.
readQueryParams :: (Monad m, Read a) => ByteString -> ControllerT s m [a]
readParamValue :: (Monad m, Read a) => ByteString -> Text -> ControllerT s m a

-- | Returns the value of the given request header or Nothing if it
--   is not present in the HTTP request.
requestHeader :: Monad m => HeaderName -> ControllerT s m (Maybe ByteString)

-- | Redirect back to the referer. If the referer header is not present
--   redirect to root (i.e., /).
redirectBack :: Monad m => ControllerT s m ()

-- | Redirect back to the referer. If the referer header is not present
--   fallback on the given Response.
redirectBackOr :: Monad m => Response -> ControllerT s m ()

-- | Like Application, but with m as the underlying monad
type SimpleApplication m = Request -> m Response

-- | Like Application, but with m as the underlying monad
type SimpleMiddleware m = SimpleApplication m -> SimpleApplication m
guard :: Monad m => Bool -> ControllerT s m a -> ControllerT s m ()
guardM :: Monad m => ControllerT s m Bool -> ControllerT s m a -> ControllerT s m ()
guardReq :: Monad m => (Request -> Bool) -> ControllerT s m a -> ControllerT s m ()
data ControllerException
ControllerException :: String -> ControllerException
err :: String -> ControllerT s m a
instance GHC.Base.Functor m => GHC.Base.Functor (Web.Simple.Controller.Trans.ControllerT s m)
instance (GHC.Base.Monad m, GHC.Base.Functor m) => GHC.Base.Applicative (Web.Simple.Controller.Trans.ControllerT s m)
instance GHC.Base.Monad m => GHC.Base.Monad (Web.Simple.Controller.Trans.ControllerT s m)
instance (GHC.Base.Functor m, GHC.Base.Monad m) => GHC.Base.Alternative (Web.Simple.Controller.Trans.ControllerT s m)
instance GHC.Base.Monad m => GHC.Base.MonadPlus (Web.Simple.Controller.Trans.ControllerT s m)
instance Control.Monad.Trans.Class.MonadTrans (Web.Simple.Controller.Trans.ControllerT s)
instance GHC.Base.Monad m => Control.Monad.State.Class.MonadState s (Web.Simple.Controller.Trans.ControllerT s m)
instance GHC.Base.Monad m => Control.Monad.Reader.Class.MonadReader Network.Wai.Internal.Request (Web.Simple.Controller.Trans.ControllerT s m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Web.Simple.Controller.Trans.ControllerT s m)
instance (GHC.Base.Applicative m, GHC.Base.Monad m, Control.Monad.Base.MonadBase m m) => Control.Monad.Base.MonadBase m (Web.Simple.Controller.Trans.ControllerT s m)
instance Control.Monad.Trans.Control.MonadBaseControl m m => Control.Monad.Trans.Control.MonadBaseControl m (Web.Simple.Controller.Trans.ControllerT s m)
instance Web.Simple.Controller.Trans.Parseable Data.ByteString.Internal.ByteString
instance Web.Simple.Controller.Trans.Parseable GHC.Base.String
instance Web.Simple.Controller.Trans.Parseable Data.Text.Internal.Text
instance GHC.Show.Show Web.Simple.Controller.Trans.ControllerException
instance GHC.Exception.Exception Web.Simple.Controller.Trans.ControllerException

-- | Controller provides a convenient syntax for writting
--   Application code as a Monadic action with access to an HTTP
--   request as well as app specific data (e.g. a database connection pool,
--   app configuration etc.) This module also defines some helper functions
--   that leverage this feature. For example, redirectBack reads the
--   underlying request to extract the referer and returns a redirect
--   response:
--   
--   
--   myController = do
--     ...
--     if badLogin then
--       redirectBack
--       else
--         ...
--   
--   
module Web.Simple.Controller

-- | The Controller Monad is both a State-like monad which, when run,
--   computes either a Response or a result. Within the Controller
--   Monad, the remainder of the computation can be short-circuited by
--   responding with a Response.
type Controller s = ControllerT s IO

-- | The ControllerT Monad is both a State-like monad which, when run,
--   computes either a Response or a result. Within the ControllerT
--   Monad, the remainder of the computation can be short-circuited by
--   responding with a Response.
newtype ControllerT s m a
ControllerT :: (s -> Request -> m (Either Response a, s)) -> ControllerT s m a
[runController] :: ControllerT s m a -> s -> Request -> m (Either Response a, s)

-- | Convert the controller into an Application
controllerApp :: s -> Controller s a -> Application

-- | Extract the application-specific state
controllerState :: Controller s s
putState :: s -> Controller s ()

-- | Extract the request
request :: Controller s Request

-- | Modify the request for the given computation
localRequest :: (Request -> Request) -> Controller s a -> Controller s a

-- | Provide a response
--   
--   
--   respond r >>= f === respond r
--   
respond :: Response -> Controller s a

-- | Returns the value of the given request header or Nothing if it
--   is not present in the HTTP request.
requestHeader :: HeaderName -> Controller s (Maybe ByteString)

-- | Matches on the hostname from the Request. The route only
--   succeeds on exact matches.
routeHost :: ByteString -> Controller s a -> Controller s ()

-- | Matches if the path is empty.
--   
--   Note that this route checks that pathInfo is empty, so it works
--   as expected in nested contexts that have popped components from the
--   pathInfo list.
routeTop :: Controller s a -> Controller s ()

-- | Matches on the HTTP request method (e.g. GET, POST,
--   PUT)
routeMethod :: StdMethod -> Controller s a -> Controller s ()

-- | Matches if the request's Content-Type exactly matches the given string
routeAccept :: ByteString -> Controller s a -> Controller s ()

-- | Routes the given URL pattern. Patterns can include directories as well
--   as variable patterns (prefixed with :) to be added to
--   queryString (see routeVar)
--   
--   
--   
- /posts/:id
--   
- /posts/:id/new
--   
- /:date/posts/:category/new
--   
routePattern :: Text -> Controller s a -> Controller s ()

-- | Matches if the first directory in the path matches the given
--   ByteString
routeName :: Text -> Controller s a -> Controller s ()

-- | Always matches if there is at least one directory in pathInfo
--   but and adds a parameter to queryString where the key is the
--   first parameter and the value is the directory consumed from the path.
routeVar :: Text -> Controller s a -> Controller s ()

-- | The class of types into which query parameters may be converted
class Parseable a

-- | Looks up the parameter name in the request's query string and returns
--   the Parseable value or Nothing.
--   
--   For example, for a request with query string: "?foo=bar&baz=7",
--   queryParam "foo" would return Just "bar", but
--   queryParam "zap" would return Nothing.
queryParam :: Parseable a => ByteString -> Controller s (Maybe a)

-- | Like queryParam, but throws an exception if the parameter is
--   not present.
queryParam' :: Parseable a => ByteString -> Controller s a

-- | Selects all values with the given parameter name
queryParams :: Parseable a => ByteString -> Controller s [a]

-- | Like queryParam, but further processes the parameter value with
--   read. If that conversion fails, an exception is thrown.
readQueryParam :: Read a => ByteString -> Controller s (Maybe a)

-- | Like readQueryParam, but throws an exception if the parameter
--   is not present.
readQueryParam' :: Read a => ByteString -> Controller s a

-- | Like queryParams, but further processes the parameter values
--   with read. If any read-conversion fails, an exception is
--   thrown.
readQueryParams :: Read a => ByteString -> Controller s [a]

-- | Parses a HTML form from the request body. It returns a list of
--   Params as well as a list of Files, which are pairs
--   mapping the name of a file form field to a FileInfo
--   pointing to a temporary file with the contents of the upload.
--   
--   
--   myControllerT = do
--     (prms, files) <- parseForm
--     let mPicFile = lookup "profile_pic" files
--     case mPicFile of
--       Just (picFile) -> do
--         sourceFile (fileContent picFile) $$
--           sinkFile ("images/" ++ (fileName picFile))
--         respond $ redirectTo "/"
--       Nothing -> redirectBack
--   
parseForm :: Controller s ([Param], [(ByteString, FileInfo ByteString)])

-- | Redirect back to the referer. If the referer header is not present
--   redirect to root (i.e., /).
redirectBack :: Controller s a

-- | Redirect back to the referer. If the referer header is not present
--   fallback on the given Response.
redirectBackOr :: Response -> Controller s a
data ControllerException

-- | Reads and returns the body of the HTTP request.
body :: Controller s ByteString
hoistEither :: Either Response a -> Controller s a

module Web.Simple.Controller.Exception
onException :: Controller s a -> Controller s b -> Controller s a
finally :: Controller s a -> Controller s b -> Controller s a
bracket :: Controller s a -> (a -> Controller s b) -> (a -> Controller s c) -> Controller s c
handle :: Exception e => (e -> Controller s a) -> Controller s a -> Controller s a

module Web.Simple.Static
serveStatic :: FilePath -> Controller a ()

-- | Provides HTTP Basic Authentication.
module Web.Simple.Auth

-- | An AuthRouter authenticates a Request and, if
--   successful, forwards the Request to the Routeable.
type AuthRouter r a = (Request -> ByteString -> ByteString -> Controller r (Maybe Request)) -> Controller r a -> Controller r a

-- | An AuthRouter that uses HTTP basic authentication to
--   authenticate a request in a particular realm.
basicAuthRoute :: String -> AuthRouter r a

-- | A Route that uses HTTP basic authentication to authenticate a
--   request for a realm with the given username ans password. The request
--   is rewritten with an 'X-User' header containing the authenticated
--   username before being passed to the next Route.
basicAuth :: String -> ByteString -> ByteString -> Controller r a -> Controller r a

-- | Wraps an AuthRouter to take a simpler authentication function
--   (that just just takes a username and password, and returns True
--   or False). It also adds an "X-User" header to the
--   Request with the authenticated user's name (the first argument
--   to the authentication function).
authRewriteReq :: AuthRouter r a -> (ByteString -> ByteString -> Controller r Bool) -> Controller r a -> Controller r a

-- | Frank is a Sinatra-inspired DSL (see http://www.sinatrarb.com)
--   for creating routes. It is composable with all ToApplication
--   types, but is designed to be used with Controllers. Each verb
--   (get, post, put, etc') takes a URL pattern of the
--   form "/dir/:paramname/dir" (see routePattern for details) and a
--   ToApplication:
--   
--   
--   main :: IO ()
--   main = run 3000 $ controllerApp () $ do
--     get "/" $ do
--       req <- request
--       respond $ okHtml $ fromString $
--         "Welcome Home " ++ (show $ serverName req)
--     get "/user/:id" $ do
--       userId <- queryParam "id" >>= fromMaybe ""
--       respond $ ok "text/json" $ fromString $
--         "{\"myid\": " ++ (show userId) ++ "}"
--     put "/user/:id" $ do
--       ...
--   
module Web.Frank

-- | Matches the GET method on the given URL pattern
get :: Monad m => Text -> ControllerT s m a -> ControllerT s m ()

-- | Matches the POST method on the given URL pattern
post :: Monad m => Text -> ControllerT s m a -> ControllerT s m ()

-- | Matches the PUT method on the given URL pattern
put :: Monad m => Text -> ControllerT s m a -> ControllerT s m ()

-- | Matches the DELETE method on the given URL pattern
delete :: Monad m => Text -> ControllerT s m a -> ControllerT s m ()

-- | Matches the OPTIONS method on the given URL pattern
options :: Monad m => Text -> ControllerT s m a -> ControllerT s m ()

module Web.Simple.Templates
class Monad m => HasTemplates m hs where defaultLayout = return Nothing viewDirectory = return "views" functionMap = return defaultFunctionMap getTemplate = defaultGetTemplate layoutObject = defaultLayoutObject

-- | The layout to use by default. Layouts are just templates that embed
--   views. They are rendered with the a global object containing the
--   rendered view in the "yield" field, and the object the view was
--   rendered with in the "page" field. By default, no template is used.
defaultLayout :: HasTemplates m hs => ControllerT hs m (Maybe Template)

-- | The directory to look for views passed to render. This defaults
--   to "views", so
--   
--   
--   render "index.html.tmpl" ...
--   
--   
--   will look for a view template in "views/index.html.tmpl".
viewDirectory :: HasTemplates m hs => ControllerT hs m FilePath

-- | A map of pure functions that can be called from within a template. See
--   FunctionMap and Function for details.
functionMap :: HasTemplates m hs => ControllerT hs m FunctionMap

-- | Function to use to get a template. By default, it looks in the
--   viewDirectory for the given file name and compiles the file
--   into a template. This can be overriden to, for example, cache compiled
--   templates in memory.
getTemplate :: HasTemplates m hs => FilePath -> ControllerT hs m Template

-- | The Value passed to a layout given the rendered view template
--   and the value originally passed to the view template. By default,
--   produces an Object with "yield", containing the rendered view,
--   and "page", containing the value originally passed to the view.
layoutObject :: (HasTemplates m hs, ToJSON pageContent, ToJSON pageVal) => pageContent -> pageVal -> ControllerT hs m Value

-- | Renders a view template with the default layout and a global used to
--   evaluate variables in the template.
render :: (HasTemplates m hs, Monad m, ToJSON a) => FilePath -> a -> ControllerT hs m ()

-- | Same as render but without a template.
renderPlain :: (HasTemplates m hs, ToJSON a) => FilePath -> a -> ControllerT hs m ()

-- | Render a view using the layout named by the first argument.
renderLayout :: (HasTemplates m hs, ToJSON a) => FilePath -> FilePath -> a -> ControllerT hs m ()

-- | Same as renderLayout but uses already compiled layouts.
renderLayoutTmpl :: (HasTemplates m hs, ToJSON a) => Template -> Template -> a -> ByteString -> ControllerT hs m ()
defaultGetTemplate :: (HasTemplates m hs, MonadIO m) => FilePath -> ControllerT hs m Template
defaultFunctionMap :: FunctionMap
defaultLayoutObject :: (HasTemplates m hs, ToJSON pageContent, ToJSON pageVal) => pageContent -> pageVal -> ControllerT hs m Value

-- | O(n*log n) Construct a map with the supplied mappings. If the
--   list contains duplicate mappings, the later mappings take precedence.
fromList :: (Eq k, Hashable k) => [(k, v)] -> HashMap k v

-- | A funcation that's callable from inside a template
newtype Function :: *
Function :: ([Value] -> Value) -> Function
[call] :: Function -> [Value] -> Value
class ToFunction a
toFunction :: ToFunction a => a -> Function
type FunctionMap = HashMap Identifier Function

-- | REST is a DSL for creating routes using RESTful HTTP verbs. See
--   http://en.wikipedia.org/wiki/Representational_state_transfer
module Web.REST

-- | Type used to encode a REST controller.
data REST m s
REST :: ControllerT s m () -> ControllerT s m () -> ControllerT s m () -> ControllerT s m () -> ControllerT s m () -> ControllerT s m () -> ControllerT s m () -> REST m s
[restIndex] :: REST m s -> ControllerT s m ()
[restShow] :: REST m s -> ControllerT s m ()
[restCreate] :: REST m s -> ControllerT s m ()
[restUpdate] :: REST m s -> ControllerT s m ()
[restDelete] :: REST m s -> ControllerT s m ()
[restEdit] :: REST m s -> ControllerT s m ()
[restNew] :: REST m s -> ControllerT s m ()
type RESTController m r = RESTControllerM m r ()
rest :: Monad m => RESTControllerM m r a -> REST m r
routeREST :: Monad m => REST m s -> ControllerT s m ()

-- | GET /
index :: ControllerT s m () -> RESTController m s

-- | GET /:id
show :: ControllerT s m () -> RESTController m s

-- | POST /
create :: ControllerT s m () -> RESTController m s

-- | PUT /:id
update :: ControllerT s m () -> RESTController m s

-- | DELETE /:id
delete :: ControllerT s m () -> RESTController m s

-- | GET /:id/edit
edit :: ControllerT s m () -> RESTController m s

-- | GET /new
new :: ControllerT s m () -> RESTController m s

-- | Simple is based on WAI - an standard interface for
--   communicating between web servers (like warp) and web applications.
--   You can use Simple completely independently (and of course, use
--   any WAI server to run it). Alternatively, you can embed existing
--   existing WAI applications inside an app built with Simple, and
--   embed an app built with simple in another WAI app.
--   
--   All the components in Simple are designed to be small and
--   simple enough to understand, replaceable, and work as well
--   independantly as they do together.
module Web.Simple
