-- 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.1.0.2

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

-- | The Routes of a web-application are a list of mappings from a
--   <a>RoutePattern</a> to a handler function.
type Routes appEnv = [(RoutePattern, WebbyM appEnv ())]

-- | 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 ())

-- | 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
requestBodyLength :: WebbyM appEnv (Maybe Int64)
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 -> Routes appEnv -> IO Application

-- | 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