Web.Respond.Path

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

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.

Constructors

PathMatcher

Fields

runPathMatcher :: PathConsumer -> Maybe a

Instances

Alternative PathMatcher

Monad PathMatcher

Functor PathMatcher

Applicative PathMatcher

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

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)

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

matchPathWithGET :: MonadRespond m => PathMatcher (m ResponseReceived) -> PathMatcher (m ResponseReceived)

pathWithMethod GET

extracting path elements

newtype PathExtractor l

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.

Constructors

PathExtractor

Fields

runPathExtractor :: MaybeT (State PathConsumer) l

Instances

Alternative PathExtractor

Monad PathExtractor

Functor PathExtractor

MonadPlus PathExtractor

Applicative PathExtractor

MonadState PathConsumer PathExtractor

asPathExtractor :: Maybe a -> PathExtractor a

takes a Maybe and makes it into a path extractor

type PathExtractor0 = PathExtractor HList0

a path extractor that extracts nothing, just matches

type PathExtractor1 a = PathExtractor (HList1 a)

a path extractor that extracts a single value from the path

using path extractors

pathExtract :: PathExtractor a -> PathConsumer -> (Maybe a, PathConsumer)

runs a PathExtractor against a PathConsumer.

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

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)

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)

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

pathEndOrSlash = path endOrSlash

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

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

combine two path extractors in sequence.

useful path extractors

pathEnd :: PathExtractor0

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

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

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

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

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

convert a predicate into a PathExtractor0

slashEnd :: PathExtractor0

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

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

endOrSlash = pathEnd <|> slashEnd

seg :: Text -> PathExtractor0

require that a segment be a certain string.

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

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

value :: PathPiece a => PathExtractor1 a

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)

path extraction matcher transformed with matchPath

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

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

utilities

mayWhen :: a -> Bool -> Maybe a

utility method for conditionally providing a value

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

run the inner action with a set path state.

usePath = withPath . const

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

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

getConsumedPath = _pcConsumed <$> getPath

getUnconsumedPath :: MonadRespond m => m [Text]

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

getUnconsumedPath = _pcUnconsumed <$> getPath

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

get the next unconsumed path segment if there is one

getNextSegment = headMay <$> getUnconsumedPath

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

run the inner action with the next path segment consumed.

withNextSegmentConsumed = withPath pcConsumeNext

things you can get out of paths

newtype Natural

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

Constructors

Natural Integer

Instances

Eq Natural

Show Natural

PathPiece Natural