Network.Wai.Middleware.Routes

This package provides typesafe URLs for Wai applications.

Quasi Quoters

parseRoutes :: QuasiQuoter

A quasi-quoter to parse a string into a list of Resources. 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

Parse routes declared in a file

parseRoutesNoCheck :: QuasiQuoter

Same as parseRoutes, but performs no overlap checking.

Parse routes declared inline, without checking for overlaps

parseRoutesFileNoCheck :: FilePath -> Q Exp

Parse routes declared in a file, without checking for overlaps

Template Haskell methods

mkRoute :: String -> [ResourceTree String] -> Q [Dec]

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]

Generates everything except Routable instance and dispatch function

mkRouteDispatch :: String -> [ResourceTree String] -> Q [Dec]

Generates a Routable instance and dispatch function

mkRouteSubDispatch :: [ResourceTree a] -> Q Exp

Dispatch

routeDispatch :: Routable master master => master -> Middleware

Generates the application middleware from a Routable master datatype

URL rendering and parsing

showRoute :: RenderRoute master => Route master -> Text

Renders a Route as Text

showRouteQuery :: RenderRoute master => Route master -> [(Text, Text)] -> Text

Render a Route and Query parameters to Text

readRoute :: ParseRoute master => Text -> Maybe (Route master)

Read a route from Text Returns Nothing if Route reading failed. Just route otherwise

Application Handlers

type Handler master = HandlerS master master

A Handler generates an App from the master datatype

type HandlerS sub master = Env sub master -> App sub

Generated Datatypes

class Routable sub master where

A Routable instance can be used in dispatching. An appropriate instance for your site datatype is automatically generated by mkRoute.

Methods

dispatcher :: HandlerS sub master

Used internally. However needs to be exported for TH to work.

class Eq (Route a) => RenderRoute a where

Associated Types

data Route a

The type-safe URLs associated with a site argument.

Methods

renderRoute

Arguments

:: Route a

-> ([Text], [(Text, Text)])

The path of the URL split on forward slashes, and a list of query parameters with their associated value.

A RenderRoute instance for your site datatype is automatically generated by mkRoute

class RenderRoute a => ParseRoute a where

Methods

parseRoute

Arguments

:: ([Text], [(Text, Text)])

The path of the URL split on forward slashes, and a list of query parameters with their associated value.

-> Maybe (Route a)

A ParseRoute instance for your site datatype is automatically generated by mkRoute

class RenderRoute a => RouteAttrs a where

Methods

routeAttrs

Arguments

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

An abstract representation of the request data. You can get the wai request object by using waiReq

waiReq :: RequestData master -> Request

Extract the wai Request object from RequestData

nextApp :: RequestData master -> Application

Extract the next Application in the stack

runNext :: App master

Run the next application in the stack

Run the next application in the stack

Route Monad makes it easy to compose routes together

type RouteM = F RouterF

catchall :: Application -> RouteM ()

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

Synonym of catchall. Kept for backwards compatibility

A synonym for catchall, kept for backwards compatibility

middleware :: Middleware -> RouteM ()

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

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

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

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 HandlerM sub master a = HandlerMI sub master IO a

The HandlerM Monad

runHandlerM :: HandlerM sub master () -> HandlerS sub master

Run HandlerM, resulting in a Handler

Run a HandlerM to get a Handler

request :: HandlerM sub master Request

Get the request

Access the request data

maybeRootRoute :: HandlerM sub master (Maybe (Route master))

Get the current root route

Access the current route for root route

maybeRoute :: HandlerM sub master (Maybe (Route sub))

Get the current route

Access the current route

routeAttrSet :: RouteAttrs sub => HandlerM sub master (Set Text)

Get the current route attributes

Access the current route attributes as a set

rootRouteAttrSet :: RouteAttrs master => HandlerM sub master (Set Text)

Get the attributes for the current root route

Access the current root route attributes as a set

master :: HandlerM sub master master

Get the master

Access the master datatype

header :: HeaderName -> ByteString -> HandlerM sub master ()

Add a header to the application response TODO: Differentiate between setting and adding headers

Add a header to the response

status :: Status -> HandlerM sub master ()

Set the response status

Set the response status

file :: FilePath -> HandlerM sub master ()

Set the response body to a file

Send a file as response

raw :: ByteString -> HandlerM sub master ()

Set the response body TODO: Add functions to append to body, and also to flush body contents

Set the raw response body

json :: ToJSON a => a -> HandlerM sub master ()

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

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

Set the body of the response to the given Text value. Also sets "Content-Type" header to "text/html".

Set the html response body

next :: HandlerM sub master ()

Run the next application

Run the next application in the stack

rawBody :: HandlerM master master ByteString

Get the request body as a lazy bytestring Get the body as a Lazy bytestring EXPERIMENTAL. Consumes the entire body 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)

Consume and return the request body as JSON