-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | process and route HTTP requests and generate responses on top of WAI
--   
@package respond
@version 1.0.0


-- | types and tools for making responses
module Web.Respond.Types.Response

-- | the type of the responder callback that is handed to a WAI
--   <a>Application</a>
type Responder = Response -> IO ResponseReceived

-- | contains both the content type header value and the body.
type ResponseBody = (MediaType, ByteString)

-- | instances of this class produce content-negotiated response bodies.
--   
--   if you're in a situation where there are performance concerns around
--   building a lazy bytestring for the response, you should consider
--   instead building <a>Response</a>s by hand (i.e. by using the WAI
--   functions).
class ToResponseBody a
toResponseBody :: ToResponseBody a => a -> ByteString -> Maybe ResponseBody

-- | pair of media type to match and a function that produces a builder for
--   a value
type MediaTypeMatcher a = (MediaType, a -> ByteString)

-- | converts a media type matcher into a pair of media type and response
--   body...
--   
--   yes, what it does is duplicate the media type and apply the builder to
--   the value
prepMediaTypeMatcher :: a -> MediaTypeMatcher a -> (MediaType, ResponseBody)

-- | find the media type matcher that matches the passed Accept header
--   value, and use it to produce a ResponseBuilder for the passed value.
--   fail with Nothing if no builder can be found given the header. see
--   <a>prepMediaTypeMatcher</a>
matchToContentTypes :: [MediaTypeMatcher a] -> a -> ByteString -> Maybe ResponseBody

-- | try to match using <tt>matchToContents</tt>; if that fails, use the
--   response body generated by the defaul matcher (first input)
matchToContentTypesDefault :: MediaTypeMatcher a -> [MediaTypeMatcher a] -> a -> ByteString -> ResponseBody

-- | the content type parameter charset=utf-8
charsetUtf8 :: (ByteString, ByteString)

-- | takes a text producer and produces a media type matcher that'll encode
--   the text as utf-8 and annotate the content type with that parameter
--   
--   you can use this in <a>matchToContentTypes</a> and render your type
--   into lazy Text; this will make sure it gets encoded.
textUtf8 :: MediaType -> (a -> Text) -> MediaTypeMatcher a

-- | take a ResponseBody instance and turn it into a response
mkResponseForBody :: Status -> ResponseHeaders -> ResponseBody -> Response

-- | try to produce a Response object for an instance of ToResponseBody.
--   the last input must be the value of the accept header
mkResponse :: ToResponseBody a => Status -> ResponseHeaders -> a -> ByteString -> Maybe Response

-- | make a MediaTypeMatcher that produces JSON
jsonMatcher :: ToJSON a => MediaTypeMatcher a

-- | matches only if client accepts "application/json"
matchAcceptJson :: ToJSON a => a -> ByteString -> Maybe ResponseBody

-- | builds an html matcher
htmlMatcher :: (a -> ByteString) -> MediaTypeMatcher a

-- | matches only html acceptance
matchAcceptHtml :: (a -> ByteString) -> a -> ByteString -> Maybe ResponseBody
textPlainMatcher :: (a -> ByteString) -> MediaTypeMatcher a
matchTextPlain :: (a -> ByteString) -> a -> ByteString -> Maybe ResponseBody
instance ToResponseBody Value


-- | contains the ErrorReport data type and tools for constructing error
--   reports, along with the ReportableError typeclass.
module Web.Respond.Types.Errors

-- | an error report is something that can be sent back as a response
--   without having to worry about it too much.
data ErrorReport
ErrorReport :: Text -> Maybe Text -> Maybe Value -> ErrorReport

-- | the reason for the error. should describe the type of error that
--   occurred to the api consumer.
erReason :: ErrorReport -> Text

-- | a message that might explain why the error occurred.
erMessage :: ErrorReport -> Maybe Text

-- | any details about the error that could be useful
erDetails :: ErrorReport -> Maybe Value

-- | the ErrorReport json representation has the fields "reason",
--   "message", and "details". Absent message and details values are
--   represented as null in json.

-- | constructor for the simplest error report
simpleErrorReport :: Text -> ErrorReport

-- | constructor for error report with reason and message
errorReportWithMessage :: Text -> Text -> ErrorReport

-- | constructor for error report with reason and details
errorReportWithDetails :: ToJSON d => Text -> d -> ErrorReport

-- | error report with all the fixings
fullErrorReport :: ToJSON d => Text -> Text -> d -> ErrorReport

-- | construct a single-key json object if the value is present
single :: ToJSON a => Text -> Maybe a -> Value

-- | format a Status into a single string.
--   
--   for example, "200 OK", or "404 Not Found"
statusFormat :: Format Status

-- | i am not sure what the type means, but you pass this a default string
--   and a format for a thing, and it gives you a formatter for maybe that
--   thing.
maybeFormat :: m -> Holey Builder Builder (a -> m) -> Holey m r (Maybe a -> r)

-- | build a format for an error report
errorReportFormat :: Format Text -> Format Text -> Format Value -> Format ErrorReport
boolFormat :: Format Bool
mkIndent :: Int64 -> Builder

-- | format a JSON value in a simple way. let Aeson handle the formatting.
simpleJsonValue :: Format Value

-- | the plaintext error report format
--   
--   tries to be somewhat yaml
plaintextErrorReportFormat :: Holey Builder b (Status -> ErrorReport -> b)

-- | renders error report as plain text
renderPlainTextErrorReport :: Status -> ErrorReport -> Text
pFormat :: Buildable a => Int64 -> Format a

-- | the html format
htmlErrorReportFormat :: Holey Builder b (Status -> ErrorReport -> b)

-- | renders error report as HTML
renderHTMLErrorReport :: Status -> ErrorReport -> Text

-- | type class for responses that report errors.
class ReportableError e
reportError :: ReportableError e => Status -> e -> ByteString -> ResponseBody
reportAsErrorReport :: (a -> ErrorReport) -> Status -> a -> ByteString -> ResponseBody

-- | this instance constructs an <a>ErrorReport</a> for the exception and
--   uses <a>reportAsErrorReport</a>

-- | newtype wrapper for the error messages produced while parsing json so
--   we can have a ReportableError instance for it.
newtype JsonParseError
JsonParseError :: String -> JsonParseError
jsonParseErrorMsg :: JsonParseError -> String
instance Eq JsonParseError
instance Show JsonParseError
instance ReportableError JsonParseError
instance ReportableError UnicodeException
instance ReportableError ErrorReport
instance ToJSON ErrorReport


-- | defines the <a>FromBody</a> typeclass and instances for
--   
--   <ul>
--   <li>lazy Text</li>
--   <li>lazy extracted json</li>
--   <li>strict extracted json</li>
--   </ul>
module Web.Respond.Types.Request

-- | something that can be pulled from the body, restricted to a
--   ReportableError type.
class ReportableError e => FromBody e a | a -> e
fromBody :: FromBody e a => ByteString -> Either e a
newtype TextBody
TextBody :: Text -> TextBody
getTextBody :: TextBody -> Text
newtype TextBodyS
TextBodyS :: Text -> TextBodyS
getTextBodyS :: TextBodyS -> Text

-- | newtype for things that should be encoded as or parsed as Json.
--   
--   the FromBody instance uses <a>eitherDecode</a> - the lazy version.
newtype Json a
Json :: a -> Json a
getJson :: Json a -> a

-- | newtype for things that should be encoded as or parsed as Json.
--   
--   the <a>FromBody</a> instance uses the immediate <a>eitherDecode'</a>
--   parser.
newtype JsonS a
JsonS :: a -> JsonS a
getJsonS :: JsonS a -> a
instance Eq TextBody
instance Show TextBody
instance Eq TextBodyS
instance Show TextBodyS
instance ToJSON a => ToResponseBody (JsonS a)
instance FromJSON a => FromBody JsonParseError (JsonS a)
instance ToJSON a => ToResponseBody (Json a)
instance FromJSON a => FromBody JsonParseError (Json a)
instance FromBody UnicodeException TextBodyS
instance FromBody UnicodeException TextBody


-- | tools for consuming request path
module Web.Respond.Types.Path

-- | stores the path and how much of it has been consumed
data PathConsumer
PathConsumer :: Seq Text -> [Text] -> PathConsumer

-- | the consumed part of the path.
_pcConsumed :: PathConsumer -> Seq Text

-- | the unconsumed part
_pcUnconsumed :: PathConsumer -> [Text]
pcUnconsumed :: Lens' PathConsumer [Text]
pcConsumed :: Lens' PathConsumer (Seq Text)

-- | build a path consumer starting with nothing consumed
mkPathConsumer :: [Text] -> PathConsumer

-- | get the next path element
pcGetNext :: PathConsumer -> Maybe Text

-- | move forward in the path
pcConsumeNext :: PathConsumer -> PathConsumer
getFullPath :: PathConsumer -> [Text]
instance Eq PathConsumer
instance Show PathConsumer


-- | These are some tools for working with HLists; this is relevant when
--   you are using path extractors.
module Web.Respond.HListUtils

-- | this type family represents functions that can take all of the
--   elements of an HList.

-- | empty HList (useful for keeping other modules from needing to add
--   several language extensions).
type HList0 = HList []

-- | HList with one element.
type HList1 a = HList '[a]

-- | uncurrys a function by applying it to the elements of the HList.
hListUncurry :: HListElim ts a -> HList ts -> a

-- | uncurrys the function by applying it to the HList, then returns the
--   result of that uncurrying as a single-element HList. useful for
--   transforming PathExtractors.
hListMapTo1 :: HListElim ts a -> HList ts -> HList1 a


-- | Provides a runner for a Warp server to run an app with some hopefully
--   sensible middleware (such as request logging).
module Web.Respond.DefaultServer

-- | sets up the app using <a>prepApp</a> then uses <a>run</a> to run it.
runWaiApp :: Port -> LoggerSet -> Application -> IO ()

-- | combines the application with the middleware created by
--   <a>mkMiddleware</a>
prepApp :: LoggerSet -> Application -> IO Application

-- | combines gzip middleware and request logging middleware
--   
--   see <a>gzip</a>; uses the default values for it.
--   
--   the request logger is set up with the format <a>Apache</a>
--   <a>FromSocket</a>, and uses the <a>LoggerSet</a> as the destination.
--   see <a>mkRequestLogger</a>.
mkMiddleware :: LoggerSet -> IO Middleware


-- | <h1>navigating the types modules</h1>
--   
--   there are a bunch of type-defining modules here; hopefully you can
--   find what you want
--   
--   <h2><a>Web.Respond.Types.Path</a></h2>
--   
--   this module defines <a>PathConsumer</a> and several functions for
--   working with that type
--   
--   <h2><a>Web.Respond.Types.Response</a></h2>
--   
--   defines the types <a>Responder</a>, <a>ResponseBody</a>, and
--   <a>MediaTypeMatcher</a>; also defines the typeclass
--   <a>ToResponseBody</a>. provides tools for implementing instances of
--   the <a>ToResponseBody</a> by matching against Accept headerst
--   
--   <h2><a>Web.Respond.Types.Errors</a></h2>
--   
--   defines the typeclass <a>ReportableError</a>, similar to
--   <a>ToResponseBody</a> except with a fallback <a>ResponseBody</a> when
--   unable to match the Accept header. also defines the <a>ErrorReport</a>
--   datatype, and implements <a>ReportableError</a> for it, defining the
--   formats for rendering it to a response. provides an instance of
--   <a>ReportableError</a> for unicode errors.
--   
--   <h2><a>Web.Respond.Types.Request</a></h2>
--   
--   defines the <a>FromBody</a> typeclass along with - <a>TextBody</a>
--   newtype, with an appropriate <a>FromBody</a> instance - <a>Json</a>
--   and <a>JsonS</a> newtypes, with appropriate <a>FromBody</a> and
--   <a>ToResponseBody</a> instances
module Web.Respond.Types


-- | you build your api using this stuff.
module Web.Respond.Monad

-- | this class is the api for building your handler.
class (Functor m, MonadIO m) => MonadRespond m
respond :: MonadRespond m => Response -> m ResponseReceived
getRequest :: MonadRespond m => m Request
getHandlers :: MonadRespond m => m FailureHandlers
withHandlers :: MonadRespond m => (FailureHandlers -> FailureHandlers) -> m a -> m a
getPath :: MonadRespond m => m PathConsumer
withPath :: MonadRespond m => (PathConsumer -> PathConsumer) -> m a -> m a

-- | RespondT is a monad transformer that provides an implementation of
--   MonadRespond. you build your application using this.
data RespondT m a

-- | run the RespondT action with failure handlers and request information.
runRespondT :: RespondT m a -> FailureHandlers -> Request -> Responder -> m a
mapRespondT :: (m a -> n b) -> RespondT m a -> RespondT n b

-- | record containing responders that request matching tools can use when
--   failures occur.
data FailureHandlers
FailureHandlers :: (forall m. MonadRespond m => [StdMethod] -> Method -> m ResponseReceived) -> (forall m. MonadRespond m => m ResponseReceived) -> (forall e m. (MonadRespond m, ReportableError e) => e -> m ResponseReceived) -> (forall e m. (MonadRespond m, ReportableError e) => e -> m ResponseReceived) -> (forall e m. (MonadRespond m, ReportableError e) => e -> m ResponseReceived) -> (forall e m. (MonadRespond m, ReportableError e) => e -> m ResponseReceived) -> (forall m. MonadRespond m => m ResponseReceived) -> FailureHandlers

-- | what to do if the request method is not supported
_unsupportedMethod :: FailureHandlers -> forall m. MonadRespond m => [StdMethod] -> Method -> m ResponseReceived

-- | what to do if the request path has no matches
_unmatchedPath :: FailureHandlers -> forall m. MonadRespond m => m ResponseReceived

-- | what to do if the body failed to parse
_bodyParseFailed :: FailureHandlers -> forall e m. (MonadRespond m, ReportableError e) => e -> m ResponseReceived

-- | what to do when authentication fails
_authFailed :: FailureHandlers -> forall e m. (MonadRespond m, ReportableError e) => e -> m ResponseReceived

-- | what to do when authorization fails
_accessDenied :: FailureHandlers -> forall e m. (MonadRespond m, ReportableError e) => e -> m ResponseReceived

-- | what to do when an exception has been caught
_caughtException :: FailureHandlers -> forall e m. (MonadRespond m, ReportableError e) => e -> m ResponseReceived

-- | what to do when no media type is acceptable
_unacceptableResponse :: FailureHandlers -> forall m. MonadRespond m => m ResponseReceived
unsupportedMethod :: MonadRespond m_aytI => Getter FailureHandlers ([StdMethod] -> Method -> m_aytI ResponseReceived)
unmatchedPath :: MonadRespond m_aytJ => Getter FailureHandlers (m_aytJ ResponseReceived)
bodyParseFailed :: (MonadRespond m_aytL, ReportableError e_aytK) => Getter FailureHandlers (e_aytK -> m_aytL ResponseReceived)
authFailed :: (MonadRespond m_aytN, ReportableError e_aytM) => Getter FailureHandlers (e_aytM -> m_aytN ResponseReceived)
accessDenied :: (MonadRespond m_aytP, ReportableError e_aytO) => Getter FailureHandlers (e_aytO -> m_aytP ResponseReceived)
caughtException :: (MonadRespond m_aytR, ReportableError e_aytQ) => Getter FailureHandlers (e_aytQ -> m_aytR ResponseReceived)
unacceptableResponse :: MonadRespond m_aytS => Getter FailureHandlers (m_aytS ResponseReceived)
instance Functor m => Functor (RespondT m)
instance Applicative m => Applicative (RespondT m)
instance Monad m => Monad (RespondT m)
instance Monad m => MonadReader RespondData (RespondT m)
instance MonadLogger m => MonadLogger (RespondT m)
instance MonadBaseControl b m => MonadBaseControl b (RespondT m)
instance MonadTransControl RespondT
instance MonadBase b m => MonadBase b (RespondT m)
instance MonadCatch m => MonadCatch (RespondT m)
instance MonadThrow m => MonadThrow (RespondT m)
instance MonadIO m => MonadIO (RespondT m)
instance MonadTrans RespondT
instance (Functor m, MonadIO m) => MonadRespond (RespondT m)
instance MonadRespond m => MonadRespond (MaybeT m)
instance MonadRespond m => MonadRespond (ExceptT e m)


-- | utilities and defaults for sending responses.
module Web.Respond.Response
findHeader :: MonadRespond m => HeaderName -> m (Maybe ByteString)
findHeaderDefault :: MonadRespond m => HeaderName -> ByteString -> m ByteString

-- | get the value of the Accept header, falling back to "*/*" if it was
--   not sent in the request
getAcceptHeader :: MonadRespond m => m ByteString

-- | responding with an empty body means not having to worry about the
--   Accept header.
respondEmptyBody :: MonadRespond m => Status -> ResponseHeaders -> m ResponseReceived

-- | respond by getting the information from a <a>ResponseBody</a>
respondUsingBody :: MonadRespond m => Status -> ResponseHeaders -> ResponseBody -> m ResponseReceived

-- | respond by using the ToResponseBody instance for the value and
--   determining if it can be converted into an acceptable response body.
--   
--   calls <a>handleUnacceptableResponse</a> if an acceptable content type
--   cannot be produced..
respondWith :: (MonadRespond m, ToResponseBody a) => Status -> ResponseHeaders -> a -> m ResponseReceived

-- | respond with no additional headers
respondStdHeaders :: (MonadRespond m, ToResponseBody a) => Status -> a -> m ResponseReceived

-- | respond with 200 Ok
respondOk :: (MonadRespond m, ToResponseBody a) => a -> m ResponseReceived

-- | respond using a ReportableError to generate the response body.
respondReportError :: (MonadRespond m, ReportableError e) => Status -> ResponseHeaders -> e -> m ResponseReceived

-- | respond that something was not found
respondNotFound :: (MonadRespond m, ReportableError e) => e -> m ResponseReceived

-- | an action that gets the currently installed unsupported method handler
--   and applies it to the arguments
handleUnsupportedMethod :: MonadRespond m => [StdMethod] -> Method -> m ResponseReceived

-- | an action that gets the installed unmatched path handler and uses it
handleUnmatchedPath :: MonadRespond m => m ResponseReceived

-- | get and use handler for unacceptable response types
handleUnacceptableResponse :: MonadRespond m => m ResponseReceived

-- | generic handler-getter for things that use ErrorReports
useHandlerForReport :: (MonadRespond m, ReportableError e) => (FailureHandlers -> e -> m ResponseReceived) -> e -> m ResponseReceived

-- | an action that gets the installed body parse failure handler and
--   applies it
handleBodyParseFailure :: (MonadRespond m, ReportableError e) => e -> m ResponseReceived

-- | get and use installed auth failed handler
handleAuthFailed :: (MonadRespond m, ReportableError e) => e -> m ResponseReceived

-- | get and use access denied handler
handleAccessDenied :: (ReportableError e, MonadRespond m) => e -> m ResponseReceived

-- | get and use handler for caught exceptions.
handleCaughtException :: (ReportableError e, MonadRespond m) => e -> m ResponseReceived

-- | get a specific handler.
--   
--   <pre>
--   getHandler = (&lt;$&gt; getHandlers)
--   </pre>
getHandler :: MonadRespond m => (FailureHandlers -> a) -> m a

-- | a way to use Maybe values to produce 404s
maybeNotFound :: (ReportableError e, MonadRespond m) => e -> (a -> m ResponseReceived) -> Maybe a -> m ResponseReceived

-- | catch Exceptions using MonadCatch, and use
--   <a>handleCaughtException</a> to respond with an error report.
catchRespond :: (MonadCatch m, MonadRespond m, ReportableError r, Exception e) => (e -> r) -> m ResponseReceived -> m ResponseReceived


-- | utilities and defaults for sending responses.
module Web.Respond.DefaultHandlers

-- | default failure handlers. uses the defaultXHandler for each field
defaultHandlers :: FailureHandlers

-- | default unsupported method handler sends back an EmptyBody with status
--   405 and an Allowed header listing the allowed methods in the first
--   path
defaultUnsupportedMethodHandler :: MonadRespond m => [StdMethod] -> Method -> m ResponseReceived

-- | respond with status404 and nothing else
defaultUnmatchedPathHandler :: MonadRespond m => m ResponseReceived

-- | respond with status 400 and a message about the body parse failure
defaultBodyParseFailureHandler :: (MonadRespond m, ReportableError e) => e -> m ResponseReceived

-- | respond with 401
defaultAuthFailedHandler :: (MonadRespond m, ReportableError e) => e -> m ResponseReceived

-- | respond with 403
defaultAccessDeniedHandler :: (MonadRespond m, ReportableError e) => e -> m ResponseReceived

-- | respond with 500
defaultCaughtExceptionHandler :: (MonadRespond m, ReportableError e) => e -> m ResponseReceived

-- | respond with 406
defaultUnacceptableResponseHandler :: MonadRespond m => m ResponseReceived


-- | contains the tools to build and run a RespondT app
module Web.Respond.Run

-- | build an <a>Application</a> from a <a>RespondT</a> router stack.
respondApp :: MonadIO m => FailureHandlers -> (forall a. m a -> IO a) -> RespondT m ResponseReceived -> Application

-- | it's <a>respondApp</a> with <a>defaultHandlers</a> passed in.
respondAppDefault :: MonadIO m => (forall a. m a -> IO a) -> RespondT m ResponseReceived -> Application

-- | serve a RespondT router app using <a>runWaiApp</a> on
--   <a>respondApp</a>.
serveRespond :: MonadIO m => Port -> LoggerSet -> FailureHandlers -> (forall a. m a -> IO a) -> RespondT m ResponseReceived -> IO ()

-- | serve a RespondT router app using <a>runWaiApp</a> on
--   <a>respondAppDefault</a>
serveRespondDefault :: MonadIO m => Port -> LoggerSet -> (forall a. m a -> IO a) -> RespondT m ResponseReceived -> IO ()

-- | RespondT stacked on top of IO; the simplest stack for handlers.
type RespondM a = RespondT IO a

-- | build an Application out of a RespondM handler.
simpleRespondApp :: FailureHandlers -> RespondM ResponseReceived -> Application

-- | build an Application out of a RespondM handler using the default error
--   handlers
simpleRespondAppDefault :: RespondM ResponseReceived -> Application

-- | serve a RespondM handler
serveSimpleRespond :: Port -> LoggerSet -> FailureHandlers -> RespondM ResponseReceived -> IO ()

-- | serve a RespondM handler using the default error handlers
serveSimpleRespondDefault :: Port -> LoggerSet -> RespondM ResponseReceived -> IO ()


-- | contains various matching utilities
module Web.Respond.Request

-- | gets the body as a lazy ByteString using lazy IO (see
--   <a>lazyRequestBody</a>)
getBodyLazy :: MonadRespond m => m ByteString

-- | gets the body as a lazy ByteString using <i>strict</i> IO (see
--   <a>strictRequestBody</a>)
getBodyStrict :: MonadRespond m => m ByteString

-- | use a FromBody instance to parse the body. uses <a>getBodyLazy</a> to
--   lazily load the body data.
extractBodyLazy :: (ReportableError e, FromBody e a, MonadRespond m) => m (Either e a)

-- | uses a FromBody instance to parse the body. uses <a>getBodyStrict</a>
--   to load the body strictly.
extractBodyStrict :: (ReportableError e, FromBody e a, MonadRespond m) => m (Either e a)

-- | extracts the body using <a>extractBodyLazy</a>. runs the inner action
--   only if the body could be loaded and parseda using the FromBody
--   instance; otherwise responds with the reportable error by calling
--   <a>handleBodyParseFailure</a>.
withRequiredBody :: (ReportableError e, FromBody e a, MonadRespond m) => (a -> m ResponseReceived) -> m ResponseReceived

-- | extracts the body using <a>extractBodyStrict</a>. runs the inner
--   action only if the body could be loaded and parseda using the FromBody
--   instance; otherwise responds with the reportable error by calling
--   <a>handleBodyParseFailure</a>.
withRequiredBody' :: (ReportableError e, FromBody e a, MonadRespond m) => (a -> m ResponseReceived) -> m ResponseReceived

-- | authenticate uses the result of the authentication action (if it
--   succssfully produced a result) to run the inner action function.
--   otherwise, it uses <a>handleAuthFailed</a>.
authenticate :: (MonadRespond m, ReportableError e) => m (Either e a) -> (a -> m ResponseReceived) -> m ResponseReceived

-- | reauthenticate tries to use a prior authentication value to run the
--   inner action; if it's not availalble, it falls back to
--   <a>authenticate</a> to apply the auth action and run the inner action.
reauthenticate :: (MonadRespond m, ReportableError e) => Maybe a -> m (Either e a) -> (a -> m ResponseReceived) -> m ResponseReceived

-- | if given an error report value , respond immediately using
--   <tt>handleDenied</tt>. otherwise, run the inner route.
authorize :: (ReportableError e, MonadRespond m) => Maybe e -> m ResponseReceived -> m ResponseReceived

-- | if the bool is true, run the inner. otherwise, handleDenied the
--   report.
authorizeBool :: (ReportableError e, MonadRespond m) => e -> Bool -> m ResponseReceived -> m ResponseReceived

-- | authorize using an Either; if it's Left, fail using
--   <tt>handleDenied</tt> on the contained ReportableError. if it's right,
--   run the inner action using the contained value,
authorizeE :: (ReportableError e, MonadRespond m) => Either e a -> (a -> m ResponseReceived) -> m ResponseReceived

-- | selects action by accept header
routeAccept :: MonadRespond m => m a -> [(MediaType, m a)] -> m a

-- | defends the inner routes by first checking the Accept header and
--   failing if it cannot accept any media type in the list
checkAccepts :: MonadRespond m => [MediaType] -> m ResponseReceived -> m ResponseReceived


-- | contains MethodMatcher and associated tools for routing based on the
--   HTTP request method.
module Web.Respond.Method

-- | Map from method to thing. use it as a monoid.
--   
--   <pre>
--   onGET action1 &lt;&gt; onPUT action2
--   </pre>
newtype MethodMatcher a
MethodMatcher :: Map StdMethod a -> MethodMatcher a
getMethodMatcher :: MethodMatcher a -> Map StdMethod a

-- | look up the request method in the MethodMatcher map and run the
--   action; fall back on <a>handleUnsupportedMethod</a> if the method
--   cannot be parsed or is not in the map.
matchMethod :: MonadRespond m => MethodMatcher (m ResponseReceived) -> m ResponseReceived

-- | map a StdMethod to a thing.
onMethod :: StdMethod -> a -> MethodMatcher a
onGET :: a -> MethodMatcher a
onPOST :: a -> MethodMatcher a
onHEAD :: a -> MethodMatcher a
onPUT :: a -> MethodMatcher a
onDELETE :: a -> MethodMatcher a
onTRACE :: a -> MethodMatcher a
onCONNECT :: a -> MethodMatcher a
onOPTIONS :: a -> MethodMatcher a
onPATCH :: a -> MethodMatcher a

-- | shortcut for when you want to run an inner action for just one http
--   method
--   
--   <pre>
--   matchOnlyMethod m = matchMethod . onMethod m
--   </pre>
matchOnlyMethod :: MonadRespond m => StdMethod -> m ResponseReceived -> m ResponseReceived

-- | shortcut for <a>matchOnlyMethod</a> GET
matchGET :: MonadRespond m => m ResponseReceived -> m ResponseReceived
instance Monoid (MethodMatcher a)


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

-- | the PathMatcher makes it easy to provide actions for different paths.
--   you use <a>matchPath</a> to run it.
--   
--   you can use this as a monad, but tbh you probably just want to use the
--   <a>Applicative</a> and especially <a>Alternative</a> instances.
newtype PathMatcher a
PathMatcher :: (PathConsumer -> Maybe a) -> PathMatcher a
runPathMatcher :: PathMatcher a -> PathConsumer -> Maybe a

-- | run a path matcher containing a respond action against the current
--   path. uses the currently installed unmatched path handler if the match
--   fails.
--   
--   see <a>handleUnmatchedPath</a>
matchPath :: MonadRespond m => PathMatcher (m ResponseReceived) -> m ResponseReceived

-- | wrap the action within a path matcher with <a>matchOnlyMethod</a>;
--   this way all paths below this can be restricted to a single method
--   properly.
matchPathWithMethod :: MonadRespond m => StdMethod -> PathMatcher (m ResponseReceived) -> PathMatcher (m ResponseReceived)

-- | <tt>pathWithMethod</tt> GET
matchPathWithGET :: MonadRespond m => PathMatcher (m ResponseReceived) -> PathMatcher (m ResponseReceived)

-- | 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.
newtype PathExtractor l
PathExtractor :: MaybeT (State PathConsumer) l -> PathExtractor l
runPathExtractor :: PathExtractor l -> MaybeT (State PathConsumer) l

-- | takes a Maybe and makes it into a path extractor
asPathExtractor :: Maybe a -> PathExtractor a

-- | a path extractor that extracts nothing, just matches
type PathExtractor0 = PathExtractor HList0

-- | a path extractor that extracts a single value from the path
type PathExtractor1 a = PathExtractor (HList1 a)

-- | runs a <a>PathExtractor</a> against a <a>PathConsumer</a>.
pathExtract :: PathExtractor a -> PathConsumer -> (Maybe a, PathConsumer)

-- | create a <a>PathMatcher</a> by providing a path extractor and an
--   action that consumes the extracted elements.
--   
--   note that <a>HListElim</a> is just a function from the types extracted
--   to something else
--   
--   <pre>
--   path ((value :: PathExtractor1 String) &lt;/&gt; seg "whatever" &lt;/&gt; (value :: PathExtractor1 Integer)) $ \string integer -&gt; -- some action
--   </pre>
path :: MonadRespond m => PathExtractor (HList l) -> HListElim l (m a) -> PathMatcher (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 <a>path</a>.
useNextPathState :: MonadRespond m => HListElim l (m a) -> Maybe (HList l) -> PathConsumer -> Maybe (m a)

-- | a simple matcher for being at the end of the path.
--   
--   <pre>
--   pathEndOrSlash = path endOrSlash
--   </pre>
pathEndOrSlash :: MonadRespond m => m a -> PathMatcher (m a)

-- | a simple matcher for the last segment of a path
--   
--   <pre>
--   pathLastSeg s = path (seg s &lt;/&gt; endOrSlash)
--   </pre>
pathLastSeg :: MonadRespond m => Text -> m a -> PathMatcher (m a)

-- | combine two path extractors in sequence.
(</>) :: PathExtractor (HList l) -> PathExtractor (HList r) -> PathExtractor (HList (HAppendList l r))

-- | match only when the PathConsumer in the path state has no unconsumed
--   elements.
pathEnd :: PathExtractor0

-- | build a path matcher that runs an extractor function on a single
--   element and then advances the path state if it matched.
singleSegExtractor :: (Text -> Maybe (HList a)) -> PathExtractor (HList a)

-- | build an extractor from a function that does not produce any real
--   value
unitExtractor :: (Text -> Maybe ()) -> PathExtractor0

-- | convert a predicate into a <a>PathExtractor0</a>
predicateExtractor :: (Text -> Bool) -> PathExtractor0

-- | WAI represents a trailing slash by having a null text as the last
--   element in the list. this matches it. it's just
--   
--   <pre>
--   slashEnd = <a>predicateExtractor</a> <a>null</a>
--   </pre>
slashEnd :: PathExtractor0

-- | best way to match the path end. it's just
--   
--   <pre>
--   endOrSlash = <a>pathEnd</a> <a>&lt;|&gt;</a> <a>slashEnd</a>
--   </pre>
endOrSlash :: PathExtractor0

-- | require that a segment be a certain string.
seg :: Text -> PathExtractor0

-- | an extractor that takes a single path element and produces a single
--   value
singleItemExtractor :: (Text -> Maybe a) -> PathExtractor1 a

-- | if you have a <a>PathPiece</a> instance for some type, you can extract
--   it from the path.
value :: PathPiece a => PathExtractor1 a

-- | path extraction matcher transformed with <a>matchPath</a>
pathMethod :: MonadRespond m => StdMethod -> PathExtractor (HList l) -> HListElim l (m ResponseReceived) -> PathMatcher (m ResponseReceived)

-- | path extraction matcher with action wrapped so that it only matches
--   GET method
pathGET :: MonadRespond m => PathExtractor (HList l) -> HListElim l (m ResponseReceived) -> PathMatcher (m ResponseReceived)

-- | utility method for conditionally providing a value
mayWhen :: a -> Bool -> Maybe a

-- | run the inner action with a set path state.
--   
--   <pre>
--   usePath = withPath . const
--   </pre>
usePath :: MonadRespond m => PathConsumer -> m a -> m a

-- | get the part of the path that's been consumed so far.
--   
--   <pre>
--   getConsumedPath = _pcConsumed &lt;$&gt; getPath
--   </pre>
getConsumedPath :: MonadRespond m => m (Seq Text)

-- | get the part of the path that has yet to be consumed.
--   
--   <pre>
--   getUnconsumedPath = _pcUnconsumed &lt;$&gt; getPath
--   </pre>
getUnconsumedPath :: MonadRespond m => m [Text]

-- | get the next unconsumed path segment if there is one
--   
--   <pre>
--   getNextSegment = headMay &lt;$&gt; getUnconsumedPath
--   </pre>
getNextSegment :: MonadRespond m => m (Maybe Text)

-- | run the inner action with the next path segment consumed.
--   
--   <pre>
--   withNextSegmentConsumed = withPath pcConsumeNext
--   </pre>
withNextSegmentConsumed :: MonadRespond m => m a -> m a

-- | natural numbers starting with 1. you can get this out of a path.
newtype Natural
Natural :: Integer -> Natural
instance Functor PathExtractor
instance Applicative PathExtractor
instance Monad PathExtractor
instance Alternative PathExtractor
instance MonadState PathConsumer PathExtractor
instance MonadPlus PathExtractor
instance Eq Natural
instance Show Natural
instance PathPiece Natural
instance Monad PathMatcher
instance Alternative PathMatcher
instance Applicative PathMatcher
instance Functor PathMatcher


-- | <h1>how to navigate the modules</h1>
--   
--   this module re-exports all of the modules that make up this library,
--   so hopefully this can tell you where to find what you're looking for.
--   
--   <h2>fundamental modules</h2>
--   
--   <h3><a>Web.Respond.Types</a></h3>
--   
--   various types and classes are exported in this module
--   
--   <h3><a>Web.Respond.Monad</a></h3>
--   
--   the monad transformer and monadic interface for building a routing
--   structure
--   
--   <h2>running a router</h2>
--   
--   <h3><a>Web.Respond.Run</a> </h3>
--   
--   contains functions that build WAI appliciations and run them in warp
--   servers
--   
--   <h3><a>Web.Respond.DefaultServer</a></h3>
--   
--   defines the default setup for the Warp server
--   
--   <h2>sending responses</h2>
--   
--   <h3><a>Web.Respond.Response</a></h3>
--   
--   functions for building responses using classes in
--   <a>Web.Respond.Types</a> and sending them as <a>MonadRespond</a>
--   actions
--   
--   <h3><a>Web.Respond.DefaultHandlers</a></h3>
--   
--   defines the default set of <tt>RequestErrorHandlers</tt> used by
--   <a>Web.Respond.Run</a>
--   
--   <h2>processing and routing</h2>
--   
--   <h3><a>Web.Respond.Request</a></h3>
--   
--   contains request body processing tools and
--   authentication/authorization tools
--   
--   <h3><a>Web.Respond.Method</a></h3>
--   
--   contains request method matching tools
--   
--   <h3><a>Web.Respond.Path</a></h3>
--   
--   contains path matching tools
--   
--   <h3><a>Web.Respond.HListUtils</a></h3>
--   
--   you'll want to use these with the path matching tools
module Web.Respond