Copyright | (c) Anupam Jain 2013 |
---|---|
License | MIT (see the file LICENSE) |
Maintainer | ajnsit@gmail.com |
Stability | experimental |
Portability | non-portable (uses ghc extensions) |
Safe Haskell | None |
Language | Haskell2010 |
This package provides typesafe URLs for Wai applications.
- parseRoutes :: QuasiQuoter
- parseRoutesFile :: FilePath -> Q Exp
- parseRoutesNoCheck :: QuasiQuoter
- parseRoutesFileNoCheck :: FilePath -> Q Exp
- mkRoute :: String -> [ResourceTree String] -> Q [Dec]
- mkRouteSub :: String -> String -> [ResourceTree String] -> Q [Dec]
- routeDispatch :: Routable master master => master -> Middleware
- showRoute :: RenderRoute master => Route master -> Text
- showRouteQuery :: RenderRoute master => Route master -> [(Text, Text)] -> Text
- readRoute :: ParseRoute master => Text -> Maybe (Route master)
- showRouteMaster :: RenderRoute master => HandlerM sub master (Route master -> Text)
- showRouteQueryMaster :: RenderRoute master => HandlerM sub master (Route master -> [(Text, Text)] -> Text)
- readRouteMaster :: ParseRoute master => HandlerM sub master (Text -> Maybe (Route master))
- showRouteSub :: RenderRoute master => HandlerM sub master (Route sub -> Text)
- showRouteQuerySub :: RenderRoute master => HandlerM sub master (Route sub -> [(Text, Text)] -> Text)
- readRouteSub :: ParseRoute sub => HandlerM sub master (Text -> Maybe (Route master))
- type Handler sub = forall master. RenderRoute master => HandlerS sub master
- type HandlerS sub master = Env sub master -> App sub
- class Routable sub master where
- dispatcher :: HandlerS sub master
- class Eq (Route a) => RenderRoute a where
- class RenderRoute a => ParseRoute a where
- class RenderRoute a => RouteAttrs a where
- routeAttrs :: Route a -> Set Text
- data RequestData master
- waiReq :: RequestData master -> Request
- nextApp :: RequestData master -> Application
- runNext :: App master
- type RouteM = F RouterF
- data DefaultMaster = DefaultMaster
- handler :: HandlerS DefaultMaster DefaultMaster -> RouteM ()
- catchall :: Application -> RouteM ()
- defaultAction :: Application -> RouteM ()
- middleware :: Middleware -> RouteM ()
- route :: Routable master master => master -> RouteM ()
- waiApp :: RouteM () -> Application
- toWaiApp :: Monad m => RouteM () -> m Application
- type HandlerM sub master a = HandlerMI sub master IO a
- runHandlerM :: HandlerM sub master () -> HandlerS sub master
- mountedAppHandler :: Application -> HandlerS sub master
- request :: HandlerM sub master Request
- isWebsocket :: HandlerM sub master Bool
- reqHeader :: Text -> HandlerM sub master (Maybe Text)
- reqHeaders :: HandlerM sub master RequestHeaders
- maybeRootRoute :: HandlerM sub master (Maybe (Route master))
- maybeRoute :: HandlerM sub master (Maybe (Route sub))
- routeAttrSet :: RouteAttrs sub => HandlerM sub master (Set Text)
- rootRouteAttrSet :: RouteAttrs master => HandlerM sub master (Set Text)
- master :: HandlerM sub master master
- sub :: HandlerM sub master sub
- rawBody :: HandlerM sub master ByteString
- textBody :: HandlerM master master Text
- jsonBody :: FromJSON a => HandlerM sub master (Either String a)
- header :: HeaderName -> ByteString -> HandlerM sub master ()
- status :: Status -> HandlerM sub master ()
- file :: FilePath -> HandlerM sub master ()
- filepart :: FilePath -> FilePart -> HandlerM sub master ()
- stream :: StreamingBody -> HandlerM sub master ()
- raw :: ByteString -> HandlerM sub master ()
- rawBuilder :: Builder -> HandlerM sub master ()
- json :: ToJSON a => a -> HandlerM sub master ()
- plain :: Text -> HandlerM sub master ()
- html :: Text -> HandlerM sub master ()
- css :: Text -> HandlerM sub master ()
- javascript :: Text -> HandlerM sub master ()
- asContent :: ByteString -> Text -> HandlerM sub master ()
- next :: HandlerM sub master ()
- getParams :: HandlerM sub master [(Text, Text)]
- getParam :: Text -> HandlerM sub master (Maybe Text)
- getQueryParams :: HandlerM sub master [(Text, Text)]
- getQueryParam :: Text -> HandlerM sub master (Maybe Text)
- getPostParams :: HandlerM sub master [(Text, Text)]
- getPostParam :: Text -> HandlerM sub master (Maybe Text)
- getFileParams :: HandlerM sub master [(Text, FileInfo)]
- getFileParam :: Text -> HandlerM sub master (Maybe FileInfo)
- setCookie :: SetCookie -> HandlerM sub master ()
- getCookie :: Text -> HandlerM sub master (Maybe Text)
- getCookies :: HandlerM sub master CookiesText
- reqVault :: HandlerM sub master Vault
- lookupVault :: Key a -> HandlerM sub master (Maybe a)
- updateVault :: (Vault -> Vault) -> HandlerM sub master ()
- data Env sub master = Env {
- envMaster :: master
- envSub :: sub
- envToMaster :: Route sub -> Route master
- data RequestData master
- waiReq :: RequestData master -> Request
- nextApp :: RequestData master -> Application
- currentRoute :: RequestData master -> Maybe (Route master)
- runNext :: App master
- module Network.HTTP.Types.Status
- module Network.Wai.Middleware.RequestLogger
- module Network.Wai.Application.Static
Declaring Routes using Template Haskell
parseRoutes :: QuasiQuoter Source
A quasi-quoter to parse a string into a list of Resource
s. Checks for
overlapping routes, failing if present; use parseRoutesNoCheck
to skip the
checking. See documentation site for details on syntax.
parseRoutesFile :: FilePath -> Q Exp Source
Parse routes declared in a file
parseRoutesNoCheck :: QuasiQuoter Source
Same as parseRoutes
, but performs no overlap checking.
parseRoutesFileNoCheck :: FilePath -> Q Exp Source
Same as parseRoutesFile, but performs no overlap checking.
mkRoute :: String -> [ResourceTree String] -> Q [Dec] Source
Generates all the things needed for efficient routing.
Including your application's Route
datatype,
RenderRoute
, ParseRoute
, RouteAttrs
, and Routable
instances.
Use this for everything except subsites
mkRouteSub :: String -> String -> [ResourceTree String] -> Q [Dec] Source
Same as mkRoute, but for subsites
Dispatch
routeDispatch :: Routable master master => master -> Middleware Source
Generates the application middleware from a Routable
master datatype
URL rendering and parsing
showRouteQuery :: RenderRoute master => Route master -> [(Text, Text)] -> Text Source
Render a Route
and Query parameters to Text
readRoute :: ParseRoute master => Text -> Maybe (Route master) Source
Read a route from Text Returns Nothing if Route reading failed. Just route otherwise
showRouteMaster :: RenderRoute master => HandlerM sub master (Route master -> Text) Source
Get the route rendering function for the master site
showRouteQueryMaster :: RenderRoute master => HandlerM sub master (Route master -> [(Text, Text)] -> Text) Source
Get the route rendering function for the master site
readRouteMaster :: ParseRoute master => HandlerM sub master (Text -> Maybe (Route master)) Source
Get the route parsing function for the master site
showRouteSub :: RenderRoute master => HandlerM sub master (Route sub -> Text) Source
Get the route rendering function for the subsite
showRouteQuerySub :: RenderRoute master => HandlerM sub master (Route sub -> [(Text, Text)] -> Text) Source
Get the route rendering function for the subsite
readRouteSub :: ParseRoute sub => HandlerM sub master (Text -> Maybe (Route master)) Source
Get the route parsing function for the subsite
Application Handlers
type Handler sub = forall master. RenderRoute master => HandlerS sub master Source
A Handler
generates an App from the master datatype
Generated Datatypes
class Routable sub master where Source
A Routable
instance can be used in dispatching.
An appropriate instance for your site datatype is
automatically generated by mkRoute
.
dispatcher :: HandlerS sub master Source
Used internally. However needs to be exported for TH to work.
A RenderRoute
instance for your site datatype is automatically generated by mkRoute
class RenderRoute a => ParseRoute a where Source
A ParseRoute
instance for your site datatype is automatically generated by mkRoute
class RenderRoute a => RouteAttrs a where Source
:: Route a | |
-> Set Text | A set of attributes associated with the route. |
A RouteAttrs
instance for your site datatype is automatically generated by mkRoute
Accessing Raw Request Data
data RequestData master Source
An abstract representation of the request data. You can get the wai request object by using waiReq
waiReq :: RequestData master -> Request Source
Extract the wai Request
object from RequestData
nextApp :: RequestData master -> Application Source
Extract the next Application in the stack
Run the next application in the stack
Route Monad makes it easy to compose routes together
data DefaultMaster Source
handler :: HandlerS DefaultMaster DefaultMaster -> RouteM () Source
Add a wai-routes handler
Add a wai-routes handler
catchall :: Application -> RouteM () Source
Catch all routes and process them with the supplied application. Note: As expected from the name, no request proceeds past a catchall.
Catch all routes with the supplied application
defaultAction :: Application -> RouteM () Source
Synonym of catchall
. Kept for backwards compatibility
A synonym for catchall
, kept for backwards compatibility
middleware :: Middleware -> RouteM () Source
Add a middleware to the application Middleware are ordered so the one declared earlier wraps the ones later
Add another middleware to the app
route :: Routable master master => master -> RouteM () Source
Add a route to the application. Routes are ordered so the one declared earlier is matched first.
Add another routed middleware to the app
waiApp :: RouteM () -> Application Source
Convert a RouteM monad into a wai application. Note: We ignore the return type of the monad
Convert a RouteM to a wai Application
toWaiApp :: Monad m => RouteM () -> m Application Source
Similar to waiApp but returns the app in an arbitrary monad Kept for backwards compatibility
Similar to waiApp, but result is wrapped in a monad. Kept for backwards compatibility
HandlerM Monad makes it easy to build a handler
runHandlerM :: HandlerM sub master () -> HandlerS sub master Source
Run HandlerM, resulting in a Handler
Run a HandlerM to get a Handler
mountedAppHandler :: Application -> HandlerS sub master Source
Convert a full wai application to a Handler A bit like subsites, but at a higher level.
Convert a full wai application to a HandlerS
Access the request data
isWebsocket :: HandlerM sub master Bool Source
Is this a websocket request
Is this a websocket request
reqHeader :: Text -> HandlerM sub master (Maybe Text) Source
Get a particular request header (Case insensitive)
Get a particular request header (case insensitive)
reqHeaders :: HandlerM sub master RequestHeaders Source
Get all request headers as raw case-insensitive bytestrings
Get all request headers (case insensitive)
maybeRootRoute :: HandlerM sub master (Maybe (Route master)) Source
Get the current root route
Access the current route for root route
maybeRoute :: HandlerM sub master (Maybe (Route sub)) Source
Get the current route
Access the current route
routeAttrSet :: RouteAttrs sub => HandlerM sub master (Set Text) Source
Get the current route attributes
Access the current route attributes as a set
rootRouteAttrSet :: RouteAttrs master => HandlerM sub master (Set Text) Source
Get the attributes for the current root route
Access the current root route attributes as a set
Access the master datatype
Access the sub datatype
rawBody :: HandlerM sub master ByteString Source
Get the request body as a bytestring. Consumes the entire body into memory at once.
TODO: Implement streaming. Prevent clash with direct use of requestBody
Consume and return the request body as ByteString
textBody :: HandlerM master master Text Source
Get the request body as a Text. However consumes the entire body at once.
TODO: Implement streaming. Prevent clash with direct use of requestBody
Consume and return the request body as Text
jsonBody :: FromJSON a => HandlerM sub master (Either String a) Source
Parse the body as a JSON object
Consume and return the request body as JSON
header :: HeaderName -> ByteString -> HandlerM sub master () Source
Add a header to the application response TODO: Differentiate between setting and adding headers
Add a header to the response
Set the response status
Send a file as response
Send a part of a file as response
stream :: StreamingBody -> HandlerM sub master () Source
Stream the response
Stream a response
raw :: ByteString -> HandlerM sub master () Source
Set the response body
Set the raw response body
rawBuilder :: Builder -> HandlerM sub master () Source
Set the response body as a builder
Set the raw response body as a ByteString Builder
json :: ToJSON a => a -> HandlerM sub master () Source
Set the body of the response to the JSON encoding of the given value. Also sets "Content-Type" header to "application/json".
Set the json response body
plain :: Text -> HandlerM sub master () Source
Set the body of the response to the given Text
value. Also sets "Content-Type"
header to "text/plain".
Set the plain text response body
html :: Text -> HandlerM sub master () Source
Set the body of the response to the given Text
value. Also sets "Content-Type"
header to "text/html".
Set the html response body
css :: Text -> HandlerM sub master () Source
Set the body of the response to the given Text
value. Also sets "Content-Type"
header to "text/css".
Set the css response body
javascript :: Text -> HandlerM sub master () Source
Set the body of the response to the given Text
value. Also sets "Content-Type"
header to "text/javascript".
Set the javascript response body
asContent :: ByteString -> Text -> HandlerM sub master () Source
Sets the content-type header to the given Bytestring (look in Network.Wai.Middleware.Routes.ContentTypes for examples) And sets the body of the response to the given Text
Set the contentType and a Text
body
Run the next application in the stack
getParams :: HandlerM sub master [(Text, Text)] Source
Get all params (query or post, NOT file) Duplicate parameters are preserved
Get all params (query or post, not file)
Get a particular param (query or post, not file)
getQueryParams :: HandlerM sub master [(Text, Text)] Source
Get all Query params
Get all query params
Get a particular query param
getPostParams :: HandlerM sub master [(Text, Text)] Source
Get all Post params
Get all post params
Get a particular post param
getFileParams :: HandlerM sub master [(Text, FileInfo)] Source
Get all File params
Get all file params
getFileParam :: Text -> HandlerM sub master (Maybe FileInfo) Source
Get a particular File param
Get a particular file param
Add a cookie to the response
Get a cookie from the request
getCookies :: HandlerM sub master CookiesText Source
Get all cookies
Get all cookies from the request
Access the vault from the request
lookupVault :: Key a -> HandlerM sub master (Maybe a) Source
Lookup a key in the request vault
updateVault :: (Vault -> Vault) -> HandlerM sub master () Source
Update the request vault
Bare Handlers
data RequestData master Source
An abstract representation of the request data. You can get the wai request object by using waiReq
waiReq :: RequestData master -> Request Source
Extract the wai Request
object from RequestData
nextApp :: RequestData master -> Application Source
Extract the next Application in the stack
currentRoute :: RequestData master -> Maybe (Route master) Source
Extract the current Route
from RequestData
Run the next application in the stack
module Network.HTTP.Types.Status