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]
- mkRouteData :: String -> [ResourceTree String] -> Q [Dec]
- mkRouteDispatch :: String -> [ResourceTree String] -> Q [Dec]
- mkRouteSubDispatch :: [ResourceTree a] -> Q Exp
- routeDispatch :: Routable master master => master -> Middleware
- 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 master = HandlerS master 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
- 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
- type HandlerMM master a = HandlerM master master a
- runHandlerM :: HandlerM sub master () -> HandlerS sub master
- request :: HandlerM sub master Request
- reqHeader :: ByteString -> HandlerM sub master (Maybe ByteString)
- 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 master master ByteString
- jsonBody :: FromJSON a => HandlerM master 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 ()
- 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 ()
- setCookie :: SetCookie -> HandlerM sub master ()
- getCookie :: ByteString -> HandlerM sub master (Maybe ByteString)
- getCookies :: HandlerM sub master Cookies
Quasi Quoters
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.
Parse Routes declared inline
parseRoutesFile :: FilePath -> Q Exp Source
Parse routes declared in a file
parseRoutesNoCheck :: QuasiQuoter Source
Same as parseRoutes
, but performs no overlap checking.
Parse routes declared inline, without checking for overlaps
parseRoutesFileNoCheck :: FilePath -> Q Exp Source
Parse routes declared in a file, without checking for overlaps
Template Haskell methods
mkRoute :: String -> [ResourceTree String] -> Q [Dec] Source
Generates all the things needed for efficient routing,
including your application's Route
datatype, and
RenderRoute
, ParseRoute
, and RouteAttr
instances, and
Routable
instance
mkRouteData :: String -> [ResourceTree String] -> Q [Dec] Source
Generates everything except Routable
instance and dispatch function
mkRouteDispatch :: String -> [ResourceTree String] -> Q [Dec] Source
Generates a Routable
instance and dispatch function
mkRouteSubDispatch :: [ResourceTree a] -> Q Exp Source
Dispatch
routeDispatch :: Routable master master => master -> Middleware Source
Generates the application middleware from a Routable
master datatype
URL rendering and parsing
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 master = HandlerS master 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.
class Eq (Route a) => RenderRoute a where Source
The type-safe URLs associated with a site argument.
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
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 is wraps the remaining application.
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
type HandlerMM master a = HandlerM master master a Source
A HandlerMM is a HandlerM Monad for use with a top level site (where the sub and master datatypes are the same)
HandlerM Monad specialised for top level sites (no subsites)
runHandlerM :: HandlerM sub master () -> HandlerS sub master Source
Run HandlerM, resulting in a Handler
Run a HandlerM to get a Handler
Access the request data
reqHeader :: ByteString -> HandlerM sub master (Maybe ByteString) 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 (Case insensitive)
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 master master ByteString Source
Get the request body as a lazy bytestring. However consumes the entire body at once.
TODO: Implement streaming. Prevent clash with direct use of requestBody
Consume and return the request body as a lazy bytestring
jsonBody :: FromJSON a => HandlerM master 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
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
Add a cookie to the response
getCookie :: ByteString -> HandlerM sub master (Maybe ByteString) Source
Get a particular cookie
Get a cookie from the request
getCookies :: HandlerM sub master Cookies Source
Get all cookies
Get all cookies from the request