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


-- | A super-simple web server framework
--   
--   A super-simple, easy to use web server framework inspired by Scotty.
--   The goals of the project are: (1) Be easy to use (2) Allow graceful
--   exception handling (3) Parse request parameters easily and in a typed
--   manner.
@package webby
@version 0.2.0

module Webby

-- | The main monad transformer stack used in the web-framework.
--   
--   The type of a handler for a request is `WebbyM appEnv ()`. The
--   <tt>appEnv</tt> parameter is used by the web application to store an
--   (read-only) environment. For e.g. it can be used to store a database
--   connection pool.
data WebbyM appEnv a
data RoutePattern

-- | Create a route for a user-provided HTTP request method, pattern and
--   handler function.
mkRoute :: Method -> Text -> WebbyM appEnv () -> (RoutePattern, WebbyM appEnv ())

-- | Create a route for a POST request method, given the path pattern and
--   handler.
post :: Text -> WebbyM appEnv () -> (RoutePattern, WebbyM appEnv ())

-- | Create a route for a GET request method, given the path pattern and
--   handler.
get :: Text -> WebbyM appEnv () -> (RoutePattern, WebbyM appEnv ())

-- | Create a route for a PUT request method, given the path pattern and
--   handler.
put :: Text -> WebbyM appEnv () -> (RoutePattern, WebbyM appEnv ())

-- | Create a route for a DELETE request method, given path pattern and
--   handler.
delete :: Text -> WebbyM appEnv () -> (RoutePattern, WebbyM appEnv ())

-- | Captures are simply extracted path elements in a HashMap
type Captures = HashMap Text Text

-- | Retrieve all path captures
captures :: WebbyM appEnv Captures

-- | Retrieve a particular capture (TODO: extend?)
getCapture :: FromHttpApiData a => Text -> WebbyM appEnv a
flag :: Text -> WebbyM appEnv Bool
header :: HeaderName -> WebbyM appEnv (Maybe Text)
headers :: WebbyM appEnv [Header]
jsonData :: FromJSON a => WebbyM appEnv a
param :: FromHttpApiData a => Text -> WebbyM appEnv (Maybe a)
param_ :: FromHttpApiData a => Text -> WebbyM appEnv a
params :: WebbyM appEnv [(Text, Text)]
request :: WebbyM appEnv Request

-- | Return the raw request body as a lazy bytestring
requestBodyLBS :: WebbyM appEnv LByteString
requestBodyLength :: WebbyM appEnv (Maybe Int64)

-- | Returns an action that returns successive chunks of the rquest body.
--   It returns an empty bytestring after the request body is consumed.
getRequestBodyChunkAction :: WebbyM appEnv (WebbyM appEnv ByteString)
setStatus :: Status -> WebbyM appEnv ()
addHeader :: Header -> WebbyM appEnv ()
setHeader :: Header -> WebbyM appEnv ()
blob :: ByteString -> WebbyM appEnv ()
json :: ToJSON b => b -> WebbyM appEnv ()
text :: Text -> WebbyM appEnv ()
stream :: StreamingBody -> WebbyM appEnv ()

-- | Use this function, to create a WAI application. It takes a
--   user/application defined <tt>appEnv</tt> data type and a list of
--   routes. If none of the requests match a request, a default 404
--   response is returned.
mkWebbyApp :: appEnv -> [(RoutePattern, WebbyM appEnv ())] -> IO Application

-- | The WAI application.
--   
--   Note that, since WAI 3.0, this type is structured in continuation
--   passing style to allow for proper safe resource handling. This was
--   handled in the past via other means (e.g., <tt>ResourceT</tt>). As a
--   demonstration:
--   
--   <pre>
--   app :: Application
--   app req respond = bracket_
--       (putStrLn "Allocating scarce resource")
--       (putStrLn "Cleaning up")
--       (respond $ responseLBS status200 [] "Hello World")
--   </pre>
type Application = Request -> Response -> IO ResponseReceived -> IO ResponseReceived

-- | The reader environment used by the web framework. It is parameterized
--   by the application's environment data type.
data WEnv appEnv

-- | Retrieve the app environment given to the application at
--   initialization.
getAppEnv :: WebbyM appEnv appEnv
runAppEnv :: ReaderT appEnv (WebbyM appEnv) a -> WebbyM appEnv a
finish :: WebbyM appEnv a

-- | Various kinds of errors thrown by this library - these can be caught
--   by handler code.
data WebbyError
WebbyJSONParseError :: Text -> WebbyError
WebbyParamParseError :: Text -> Text -> WebbyError
[wppeParamName] :: WebbyError -> Text
[wppeErrMsg] :: WebbyError -> Text
WebbyMissingCapture :: Text -> WebbyError