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


-- | A simple HTTP server framework
--   
--   A simple HTTP server framework
@package firefly
@version 0.1.0.0

module Web.Firefly.Types

-- | The main application definiton monad, sequence your route handlers
--   and/or middleware in this monad
type App a = ReaderT ReqContext (ExceptT Response IO) a

-- | Handler is an alias for <a>App</a>, currently provided for semantic
--   reasons, but the two may diverge in the future.
type Handler a = App a

-- | A regex pattern for route matching.
type Pattern = Text

-- | A route as Text
type Route = Text

-- | A map of case insensitive header names to all provided values for that
--   header.
type HeaderMap = Map (CI Text) [Text]

-- | A map of query parameter names to all values provided for that
--   parameter
type MultiQueryMap = Map Text [Text]

-- | A map of query parameter names to the last-provided value for that
--   parameter
type QueryMap = Map Text Text

-- | A request or response's Content-Type value
type ContentType = Text

-- | Context provided when handling any request
data ReqContext
ReqContext :: Text -> Request -> ReqContext
[requestBody] :: ReqContext -> Text
[request] :: ReqContext -> Request

module Web.Firefly.Internal.Utils
toBS :: Text -> ByteString
toLBS :: Text -> ByteString
fromBS :: ByteString -> Text
fromLBS :: ByteString -> Text
mkHeader :: Text -> Text -> Header
convertHeaders :: RequestHeaders -> HeaderMap
fromHeaderMap :: HeaderMap -> ResponseHeaders
qsToList :: Query -> [(Text, Maybe Text)]
convertQueries :: Query -> MultiQueryMap

-- | Get last occurrance of each query param
simpleQuery :: Query -> QueryMap

module Web.Firefly.Request

-- | Calls through to <a>rawPathInfo</a>; returns the full path of the
--   current request (without the query string)
getPath :: ReqReader m => m Text

-- | Calls through to <a>pathInfo</a>. Returns the path's individual
--   <a>/</a> separated chunks. '
getPathInfo :: ReqReader m => m [Text]

-- | Gets the HTTP method of the current request
getMethod :: ReqReader m => m Text

-- | Calls through to <a>rawQueryString</a>; returns the full path of the
--   current request (without the query string)
getQueryString :: ReqReader m => m Text

-- | Get the last set value for each query
--   
--   If a query is set without a value (e.g. "/?key") it will appear in the
--   map with a value of <tt>""</tt>
getQueries :: ReqReader m => m QueryMap

-- | Gets all key/values from the query string
getQueriesMulti :: ReqReader m => m MultiQueryMap

-- | Get the value for a given query. A query which was passed without a
--   value (e.g. "/?key") will return <tt>Just ""</tt>
getQuery :: ReqReader m => Text -> m (Maybe Text)

-- | Gets all values provided for a given query key
getQueryMulti :: ReqReader m => Text -> m [Text]

-- | Gets the headers of the request
getHeaders :: ReqReader m => m HeaderMap

-- | Gets full body of the request
getBody :: ReqReader m => m Text

-- | Gets a map of cookies sent with the request.
getCookies :: ReqReader m => m (Map Text [Text])

-- | Get all values set for a specific cookie
getCookieMulti :: ReqReader m => Text -> m [Text]

-- | Get the value for a cookie if it is set
getCookie :: ReqReader m => Text -> m (Maybe Text)

-- | Calls through to <a>isSecure</a>
isSecure :: ReqReader m => m Bool

-- | Exposes the underlying <a>Request</a>.
waiRequest :: ReqReader m => m Request

module Web.Firefly.Response

-- | This class represents all types which can be converted into a valid
--   <a>Response</a>. Feel free to implement additional instances for your
--   own data-types.
class ToResponse c
toResponse :: ToResponse c => c -> Response

-- | A simple newtype wrapper you can use to wrap values, signifying they
--   should be JSON encoded sent with the "application/json" Content-Type.
newtype Json a
Json :: a -> Json a

-- | Respond to the client immediately. Any statements following this one
--   in the App or Handler Monads will not be run.
respond :: ToResponse r => r -> App ()
instance GHC.Show.Show a => GHC.Show.Show (Web.Firefly.Response.Json a)
instance Web.Firefly.Response.ToResponse GHC.Base.String
instance Web.Firefly.Response.ToResponse Data.Text.Internal.Text
instance Web.Firefly.Response.ToResponse Text.Blaze.Html.Html
instance Web.Firefly.Response.ToResponse Data.Aeson.Types.Internal.Value
instance Data.Aeson.Types.ToJSON.ToJSON a => Web.Firefly.Response.ToResponse (Web.Firefly.Response.Json a)
instance Web.Firefly.Response.ToResponse Network.Wai.Internal.Response
instance Web.Firefly.Response.ToResponse b => Web.Firefly.Response.ToResponse (b, Network.HTTP.Types.Status.Status)
instance Web.Firefly.Response.ToResponse b => Web.Firefly.Response.ToResponse (b, Network.HTTP.Types.Status.Status, Web.Firefly.Types.HeaderMap)

module Web.Firefly.Handler

-- | Run a handler on a matching route. The handler may return any type
--   which implements <a>ToResponse</a>
--   
--   If a route matches any actions following it in the App monad will not
--   be run.
--   
--   Route patterns support pcre regex but do not yet support url
--   parameters.
--   
--   In the following example if we call <tt>helloHarry</tt> then the
--   <tt>helloHandler</tt> will run, but NOT the helloHarryHandler since a
--   matching route ceases further execution. For this reason the order you
--   define your routes in matters.
--   
--   <pre>
--   app :: App ()
--   app = do
--     route "/" indexHandler
--     route "/hello.*" helloHandler
--     route "/helloHarry" helloHarryHandler
--   </pre>
route :: (ToResponse r) => Pattern -> Handler r -> App ()

module Web.Firefly

-- | Run an http server on the given port.
--   
--   <pre>
--   -- Run app on port 3000
--   main :: IO ()
--   main = run 3000 app
--   </pre>
run :: Port -> App () -> IO ()

-- | The main application definiton monad, sequence your route handlers
--   and/or middleware in this monad
type App a = ReaderT ReqContext (ExceptT Response IO) a

-- | Handler is an alias for <a>App</a>, currently provided for semantic
--   reasons, but the two may diverge in the future.
type Handler a = App a

-- | Run a handler on a matching route. The handler may return any type
--   which implements <a>ToResponse</a>
--   
--   If a route matches any actions following it in the App monad will not
--   be run.
--   
--   Route patterns support pcre regex but do not yet support url
--   parameters.
--   
--   In the following example if we call <tt>helloHarry</tt> then the
--   <tt>helloHandler</tt> will run, but NOT the helloHarryHandler since a
--   matching route ceases further execution. For this reason the order you
--   define your routes in matters.
--   
--   <pre>
--   app :: App ()
--   app = do
--     route "/" indexHandler
--     route "/hello.*" helloHandler
--     route "/helloHarry" helloHarryHandler
--   </pre>
route :: (ToResponse r) => Pattern -> Handler r -> App ()

-- | Calls through to <a>rawPathInfo</a>; returns the full path of the
--   current request (without the query string)
getPath :: ReqReader m => m Text

-- | Calls through to <a>pathInfo</a>. Returns the path's individual
--   <a>/</a> separated chunks. '
getPathInfo :: ReqReader m => m [Text]

-- | Gets the HTTP method of the current request
getMethod :: ReqReader m => m Text

-- | Calls through to <a>rawQueryString</a>; returns the full path of the
--   current request (without the query string)
getQueryString :: ReqReader m => m Text

-- | Get the last set value for each query
--   
--   If a query is set without a value (e.g. "/?key") it will appear in the
--   map with a value of <tt>""</tt>
getQueries :: ReqReader m => m QueryMap

-- | Gets all key/values from the query string
getQueriesMulti :: ReqReader m => m MultiQueryMap

-- | Get the value for a given query. A query which was passed without a
--   value (e.g. "/?key") will return <tt>Just ""</tt>
getQuery :: ReqReader m => Text -> m (Maybe Text)

-- | Gets all values provided for a given query key
getQueryMulti :: ReqReader m => Text -> m [Text]

-- | Gets the headers of the request
getHeaders :: ReqReader m => m HeaderMap

-- | Gets full body of the request
getBody :: ReqReader m => m Text

-- | Gets a map of cookies sent with the request.
getCookies :: ReqReader m => m (Map Text [Text])

-- | Get all values set for a specific cookie
getCookieMulti :: ReqReader m => Text -> m [Text]

-- | Get the value for a cookie if it is set
getCookie :: ReqReader m => Text -> m (Maybe Text)

-- | Calls through to <a>isSecure</a>
isSecure :: ReqReader m => m Bool

-- | Exposes the underlying <a>Request</a>.
waiRequest :: ReqReader m => m Request

-- | This class represents all types which can be converted into a valid
--   <a>Response</a>. Feel free to implement additional instances for your
--   own data-types.
class ToResponse c
toResponse :: ToResponse c => c -> Response

-- | Respond to the client immediately. Any statements following this one
--   in the App or Handler Monads will not be run.
respond :: ToResponse r => r -> App ()

-- | A simple newtype wrapper you can use to wrap values, signifying they
--   should be JSON encoded sent with the "application/json" Content-Type.
newtype Json a
Json :: a -> Json a

-- | Run actions before your handlers and/or perform actions following the
--   response.
--   
--   <tt>after</tt> will only be run if a response is provided from some
--   handler
addMiddleware :: App Request -> (Response -> App Response) -> App () -> App ()