respond-1.1.0: process and route HTTP requests and generate responses on top of WAI

Safe HaskellNone




This module provides the tools you need to match the path of a request, extract data from it, and connect matches to Respond actions.


matching paths to actions

newtype PathMatcher a Source

the PathMatcher makes it easy to provide actions for different paths. you use matchPath to run it.

you can use this as a monad, but tbh you probably just want to use the Applicative and especially Alternative instances.



matchPath :: MonadRespond m => PathMatcher (m ResponseReceived) -> m ResponseReceived Source

run a path matcher containing a respond action against the current path. uses the currently installed unmatched path handler if the match fails.

see handleUnmatchedPath

transforming path matchers

matchPathWithMethod :: MonadRespond m => StdMethod -> PathMatcher (m ResponseReceived) -> PathMatcher (m ResponseReceived) Source

wrap the action within a path matcher with matchOnlyMethod; this way all paths below this can be restricted to a single method properly.

extracting path elements

newtype PathExtractor l Source

the path extractor matches the path and extracts values; it is useful for building PathMatchers. it is built on both MState and Maybe - if it succeeds, it can modify the state to represent the path it has consumed.

asPathExtractor :: Maybe a -> PathExtractor a Source

takes a Maybe and makes it into a path extractor

type PathExtractor0 = PathExtractor HList0 Source

a path extractor that extracts nothing, just matches

type PathExtractor1 a = PathExtractor (HList1 a) Source

a path extractor that extracts a single value from the path

using path extractors

path :: MonadRespond m => PathExtractor (HList l) -> HListElim l (m a) -> PathMatcher (m a) Source

create a PathMatcher by providing a path extractor and an action that consumes the extracted elements.

note that HListElim is just a function from the types extracted to something else

path ((value :: PathExtractor1 String) </> seg "whatever" </> (value :: PathExtractor1 Integer)) $ \string integer -> -- some action

useNextPathState :: MonadRespond m => HListElim l (m a) -> Maybe (HList l) -> PathConsumer -> Maybe (m a) Source

an action that runs the action (HListElim l (m a)) with the new path consumer state if an extracted value is provided.

this mainly exists for the use of path.

pathEndOrSlash :: MonadRespond m => m a -> PathMatcher (m a) Source

a simple matcher for being at the end of the path.

pathEndOrSlash = path endOrSlash

pathLastSeg :: MonadRespond m => Text -> m a -> PathMatcher (m a) Source

a simple matcher for the last segment of a path

pathLastSeg s = path (seg s </> endOrSlash)

(</>) :: PathExtractor (HList l) -> PathExtractor (HList r) -> PathExtractor (HList (HAppendList l r)) Source

combine two path extractors in sequence.

useful path extractors

pathEnd :: PathExtractor0 Source

match only when the PathConsumer in the path state has no unconsumed elements.

singleSegExtractor :: (Text -> Maybe (HList a)) -> PathExtractor (HList a) Source

build a path matcher that runs an extractor function on a single element and then advances the path state if it matched.

unitExtractor :: (Text -> Maybe ()) -> PathExtractor0 Source

build an extractor from a function that does not produce any real value

predicateExtractor :: (Text -> Bool) -> PathExtractor0 Source

convert a predicate into a PathExtractor0

slashEnd :: PathExtractor0 Source

WAI represents a trailing slash by having a null text as the last element in the list. this matches it. it's just

slashEnd = predicateExtractor null

endOrSlash :: PathExtractor0 Source

best way to match the path end. it's just

endOrSlash = pathEnd <|> slashEnd

seg :: Text -> PathExtractor0 Source

require that a segment be a certain string.

singleItemExtractor :: (Text -> Maybe a) -> PathExtractor1 a Source

an extractor that takes a single path element and produces a single value

value :: PathPiece a => PathExtractor1 a Source

if you have a PathPiece instance for some type, you can extract it from the path.

extract while matching methods

pathMethod :: MonadRespond m => StdMethod -> PathExtractor (HList l) -> HListElim l (m ResponseReceived) -> PathMatcher (m ResponseReceived) Source

path extraction matcher transformed with matchPath

pathGET :: MonadRespond m => PathExtractor (HList l) -> HListElim l (m ResponseReceived) -> PathMatcher (m ResponseReceived) Source

path extraction matcher with action wrapped so that it only matches GET method


mayWhen :: a -> Bool -> Maybe a Source

utility method for conditionally providing a value

usePath :: MonadRespond m => PathConsumer -> m a -> m a Source

run the inner action with a set path state.

usePath = withPath . const

getConsumedPath :: MonadRespond m => m (Seq Text) Source

get the part of the path that's been consumed so far.

getConsumedPath = _pcConsumed <$> getPath

getUnconsumedPath :: MonadRespond m => m [Text] Source

get the part of the path that has yet to be consumed.

getUnconsumedPath = _pcUnconsumed <$> getPath

getNextSegment :: MonadRespond m => m (Maybe Text) Source

get the next unconsumed path segment if there is one

getNextSegment = headMay <$> getUnconsumedPath

withNextSegmentConsumed :: MonadRespond m => m a -> m a Source

run the inner action with the next path segment consumed.

withNextSegmentConsumed = withPath pcConsumeNext

things you can get out of paths

newtype Natural Source

natural numbers starting with 1. you can get this out of a path.


Natural Integer