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


-- | Haskell web framework inspired by Ruby's Sinatra, using WAI and Warp
--   
--   A Haskell web framework inspired by Ruby's Sinatra, using WAI and
--   Warp.
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import Web.Scotty
--   
--   main = scotty 3000 $
--     get "/:word" $ do
--       beam &lt;- captureParam "word"
--       html $ mconcat ["&lt;h1&gt;Scotty, ", beam, " me up!&lt;/h1&gt;"]
--   </pre>
--   
--   Scotty is the cheap and cheerful way to write RESTful, declarative web
--   applications.
--   
--   <ul>
--   <li>A page is as simple as defining the verb, url pattern, and Text
--   content.</li>
--   <li>It is template-language agnostic. Anything that returns a Text
--   value will do.</li>
--   <li>Conforms to WAI Application interface.</li>
--   <li>Uses very fast Warp webserver by default.</li>
--   </ul>
--   
--   As for the name: Sinatra + Warp = Scotty.
--   
--   <ul>
--   <li><i>WAI</i> <a>http://hackage.haskell.org/package/wai</a></li>
--   <li><i>Warp</i> <a>http://hackage.haskell.org/package/warp</a></li>
--   </ul>
@package scotty
@version 0.20.1

module Web.Scotty.Internal.Types
data Options
Options :: Int -> Settings -> Options

-- | 0 = silent, 1(def) = startup banner
[verbose] :: Options -> Int

-- | Warp <a>Settings</a> Note: to work around an issue in warp, the
--   default FD cache duration is set to 0 so changes to static files are
--   always picked up. This likely has performance implications, so you may
--   want to modify this for production servers using
--   <tt>setFdCacheDuration</tt>.
[settings] :: Options -> Settings
defaultOptions :: Options
newtype RouteOptions
RouteOptions :: Maybe Kilobytes -> RouteOptions
[maxRequestBodySize] :: RouteOptions -> Maybe Kilobytes
defaultRouteOptions :: RouteOptions
type Kilobytes = Int
type Middleware m = Application m -> Application m
type Application m = Request -> m Response
data BodyChunkBuffer
BodyChunkBuffer :: Bool -> [ByteString] -> BodyChunkBuffer

-- | whether we've reached the end of the stream yet
[hasFinishedReadingChunks] :: BodyChunkBuffer -> Bool
[chunksReadSoFar] :: BodyChunkBuffer -> [ByteString]

-- | The key part of having two MVars is that we can "clone" the BodyInfo
--   to create a copy where the index is reset to 0, but the chunk cache is
--   the same. Passing a cloned BodyInfo into each matched route allows
--   them each to start from the first chunk if they call bodyReader.
--   
--   Introduced in (#308)
data BodyInfo
BodyInfo :: MVar Int -> MVar BodyChunkBuffer -> IO ByteString -> BodyInfo

-- | index into the stream read so far
[bodyInfoReadProgress] :: BodyInfo -> MVar Int
[bodyInfoChunkBuffer] :: BodyInfo -> MVar BodyChunkBuffer

-- | can be called to get more chunks
[bodyInfoDirectChunkRead] :: BodyInfo -> IO ByteString
data ScottyState m
ScottyState :: [Middleware] -> [BodyInfo -> Middleware m] -> Maybe (ErrorHandler m) -> RouteOptions -> ScottyState m
[middlewares] :: ScottyState m -> [Middleware]
[routes] :: ScottyState m -> [BodyInfo -> Middleware m]
[handler] :: ScottyState m -> Maybe (ErrorHandler m)
[routeOptions] :: ScottyState m -> RouteOptions
defaultScottyState :: ScottyState m
addMiddleware :: Middleware -> ScottyState m -> ScottyState m
addRoute :: (BodyInfo -> Middleware m) -> ScottyState m -> ScottyState m
setHandler :: Maybe (ErrorHandler m) -> ScottyState m -> ScottyState m
updateMaxRequestBodySize :: RouteOptions -> ScottyState m -> ScottyState m
newtype ScottyT m a
ScottyT :: State (ScottyState m) a -> ScottyT m a
[runS] :: ScottyT m a -> State (ScottyState m) a

-- | Internal exception mechanism used to modify the request processing
--   flow.
--   
--   The exception constructor is not exposed to the user and all
--   exceptions of this type are caught and processed within the
--   <tt>runAction</tt> function.
data ActionError

-- | Redirect
AERedirect :: Text -> ActionError

-- | Stop processing this route and skip to the next one
AENext :: ActionError

-- | Stop processing the request
AEFinish :: ActionError
tryNext :: MonadUnliftIO m => m a -> m Bool

-- | E.g. when a parameter is not found in a query string (400 Bad Request)
--   or when parsing a JSON body fails (422 Unprocessable Entity)
data StatusError
StatusError :: Status -> Text -> StatusError

-- | Specializes a <a>Handler</a> to the <a>ActionT</a> monad
type ErrorHandler m = Handler (ActionT m) ()

-- | Thrown e.g. when a request is too large
data ScottyException
RequestException :: ByteString -> Status -> ScottyException
type Param = (Text, Text)
type File = (Text, FileInfo ByteString)
data ActionEnv
Env :: Request -> [Param] -> [Param] -> [Param] -> IO ByteString -> IO ByteString -> [File] -> TVar ScottyResponse -> ActionEnv
[envReq] :: ActionEnv -> Request
[envCaptureParams] :: ActionEnv -> [Param]
[envFormParams] :: ActionEnv -> [Param]
[envQueryParams] :: ActionEnv -> [Param]
[envBody] :: ActionEnv -> IO ByteString
[envBodyChunk] :: ActionEnv -> IO ByteString
[envFiles] :: ActionEnv -> [File]
[envResponse] :: ActionEnv -> TVar ScottyResponse
getResponse :: MonadIO m => ActionEnv -> m ScottyResponse
modifyResponse :: MonadIO m => (ScottyResponse -> ScottyResponse) -> ActionT m ()
data BodyPartiallyStreamed
BodyPartiallyStreamed :: BodyPartiallyStreamed
data Content
ContentBuilder :: Builder -> Content
ContentFile :: FilePath -> Content
ContentStream :: StreamingBody -> Content
ContentResponse :: Response -> Content
data ScottyResponse
SR :: Status -> ResponseHeaders -> Content -> ScottyResponse
[srStatus] :: ScottyResponse -> Status
[srHeaders] :: ScottyResponse -> ResponseHeaders
[srContent] :: ScottyResponse -> Content
setContent :: Content -> ScottyResponse -> ScottyResponse
setHeaderWith :: ([(HeaderName, ByteString)] -> [(HeaderName, ByteString)]) -> ScottyResponse -> ScottyResponse
setStatus :: Status -> ScottyResponse -> ScottyResponse

-- | The default response has code 200 OK and empty body
defaultScottyResponse :: ScottyResponse
newtype ActionT m a
ActionT :: ReaderT ActionEnv m a -> ActionT m a
[runAM] :: ActionT m a -> ReaderT ActionEnv m a

-- | catches either ActionError (thrown by <tt>next</tt>) or
--   <a>StatusError</a> (thrown if e.g. a query parameter is not found)
tryAnyStatus :: MonadUnliftIO m => m a -> m Bool
data RoutePattern
Capture :: Text -> RoutePattern
Literal :: Text -> RoutePattern
Function :: (Request -> Maybe [Param]) -> RoutePattern
instance GHC.Show.Show Web.Scotty.Internal.Types.ActionError
instance GHC.Show.Show Web.Scotty.Internal.Types.StatusError
instance GHC.Show.Show Web.Scotty.Internal.Types.ScottyException
instance GHC.Show.Show Web.Scotty.Internal.Types.BodyPartiallyStreamed
instance Control.Monad.IO.Unlift.MonadUnliftIO m => Control.Monad.IO.Unlift.MonadUnliftIO (Web.Scotty.Internal.Types.ActionT m)
instance Control.Monad.Trans.Control.MonadTransControl Web.Scotty.Internal.Types.ActionT
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Web.Scotty.Internal.Types.ActionT m)
instance Control.Monad.Base.MonadBase b m => Control.Monad.Base.MonadBase b (Web.Scotty.Internal.Types.ActionT m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Web.Scotty.Internal.Types.ActionT m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Web.Scotty.Internal.Types.ActionT m)
instance Control.Monad.Trans.Class.MonadTrans Web.Scotty.Internal.Types.ActionT
instance GHC.Base.Monad m => Control.Monad.Reader.Class.MonadReader Web.Scotty.Internal.Types.ActionEnv (Web.Scotty.Internal.Types.ActionT m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Web.Scotty.Internal.Types.ActionT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Web.Scotty.Internal.Types.ActionT m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Web.Scotty.Internal.Types.ActionT m)
instance GHC.Base.Functor m => GHC.Base.Functor (Web.Scotty.Internal.Types.ActionT m)
instance GHC.Base.Monad (Web.Scotty.Internal.Types.ScottyT m)
instance GHC.Base.Applicative (Web.Scotty.Internal.Types.ScottyT m)
instance GHC.Base.Functor (Web.Scotty.Internal.Types.ScottyT m)
instance Data.String.IsString Web.Scotty.Internal.Types.RoutePattern
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Web.Scotty.Internal.Types.ScottyT m a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Web.Scotty.Internal.Types.ScottyT m a)
instance Data.Default.Class.Default (Web.Scotty.Internal.Types.ScottyState m)
instance Control.Monad.IO.Unlift.MonadUnliftIO m => Control.Monad.Error.Class.MonadError Web.Scotty.Internal.Types.StatusError (Web.Scotty.Internal.Types.ActionT m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.Fail.MonadFail (Web.Scotty.Internal.Types.ActionT m)
instance Control.Monad.IO.Unlift.MonadUnliftIO m => GHC.Base.Alternative (Web.Scotty.Internal.Types.ActionT m)
instance Control.Monad.IO.Unlift.MonadUnliftIO m => GHC.Base.MonadPlus (Web.Scotty.Internal.Types.ActionT m)
instance (GHC.Base.Monad m, GHC.Base.Semigroup a) => GHC.Base.Semigroup (Web.Scotty.Internal.Types.ActionT m a)
instance (GHC.Base.Monad m, GHC.Base.Monoid a) => GHC.Base.Monoid (Web.Scotty.Internal.Types.ActionT m a)
instance Data.Default.Class.Default Web.Scotty.Internal.Types.ScottyResponse
instance GHC.Exception.Type.Exception Web.Scotty.Internal.Types.BodyPartiallyStreamed
instance GHC.Exception.Type.Exception Web.Scotty.Internal.Types.ScottyException
instance GHC.Exception.Type.Exception Web.Scotty.Internal.Types.StatusError
instance GHC.Exception.Type.Exception Web.Scotty.Internal.Types.ActionError
instance Data.Default.Class.Default Web.Scotty.Internal.Types.RouteOptions
instance Data.Default.Class.Default Web.Scotty.Internal.Types.Options


-- | It should be noted that most of the code snippets below depend on the
--   OverloadedStrings language pragma.
--   
--   The functions in this module allow an arbitrary monad to be embedded
--   in Scotty's monad transformer stack in order that Scotty be combined
--   with other DSLs.
--   
--   Scotty is set up by default for development mode. For production
--   servers, you will likely want to modify <a>settings</a> and the
--   <a>defaultHandler</a>. See the comments on each of these functions for
--   more information.
module Web.Scotty.Trans

-- | Run a scotty application using the warp server. NB: scotty p ===
--   scottyT p id
scottyT :: (Monad m, MonadIO n) => Port -> (m Response -> IO Response) -> ScottyT m () -> n ()

-- | Turn a scotty application into a WAI <a>Application</a>, which can be
--   run with any WAI handler. NB: scottyApp === scottyAppT id
scottyAppT :: (Monad m, Monad n) => (m Response -> IO Response) -> ScottyT m () -> n Application

-- | Run a scotty application using the warp server, passing extra options.
--   NB: scottyOpts opts === scottyOptsT opts id
scottyOptsT :: (Monad m, MonadIO n) => Options -> (m Response -> IO Response) -> ScottyT m () -> n ()

-- | Run a scotty application using the warp server, passing extra options,
--   and listening on the provided socket. NB: scottySocket opts sock ===
--   scottySocketT opts sock id
scottySocketT :: (Monad m, MonadIO n) => Options -> Socket -> (m Response -> IO Response) -> ScottyT m () -> n ()
data Options
Options :: Int -> Settings -> Options

-- | 0 = silent, 1(def) = startup banner
[verbose] :: Options -> Int

-- | Warp <a>Settings</a> Note: to work around an issue in warp, the
--   default FD cache duration is set to 0 so changes to static files are
--   always picked up. This likely has performance implications, so you may
--   want to modify this for production servers using
--   <tt>setFdCacheDuration</tt>.
[settings] :: Options -> Settings
defaultOptions :: Options

-- | Use given middleware. Middleware is nested such that the first
--   declared is the outermost middleware (it has first dibs on the request
--   and last action on the response). Every middleware is run on each
--   request.
middleware :: Middleware -> ScottyT m ()

-- | get = <a>addroute</a> <a>GET</a>
get :: MonadUnliftIO m => RoutePattern -> ActionT m () -> ScottyT m ()

-- | post = <a>addroute</a> <a>POST</a>
post :: MonadUnliftIO m => RoutePattern -> ActionT m () -> ScottyT m ()

-- | put = <a>addroute</a> <a>PUT</a>
put :: MonadUnliftIO m => RoutePattern -> ActionT m () -> ScottyT m ()

-- | delete = <a>addroute</a> <a>DELETE</a>
delete :: MonadUnliftIO m => RoutePattern -> ActionT m () -> ScottyT m ()

-- | patch = <a>addroute</a> <a>PATCH</a>
patch :: MonadUnliftIO m => RoutePattern -> ActionT m () -> ScottyT m ()

-- | options = <a>addroute</a> <a>OPTIONS</a>
options :: MonadUnliftIO m => RoutePattern -> ActionT m () -> ScottyT m ()

-- | Define a route with a <a>StdMethod</a>, <a>Text</a> value representing
--   the path spec, and a body (<tt>Action</tt>) which modifies the
--   response.
--   
--   <pre>
--   addroute GET "/" $ text "beam me up!"
--   </pre>
--   
--   The path spec can include values starting with a colon, which are
--   interpreted as <i>captures</i>. These are named wildcards that can be
--   looked up with <a>captureParam</a>.
--   
--   <pre>
--   addroute GET "/foo/:bar" $ do
--       v &lt;- captureParam "bar"
--       text v
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; curl http://localhost:3000/foo/something
--   something
--   </pre>
--   
--   NB: the <a>RouteOptions</a> and the exception handler of the
--   newly-created route will be copied from the previously-created routes.
addroute :: MonadUnliftIO m => StdMethod -> RoutePattern -> ActionT m () -> ScottyT m ()

-- | Add a route that matches regardless of the HTTP verb.
matchAny :: MonadUnliftIO m => RoutePattern -> ActionT m () -> ScottyT m ()

-- | Specify an action to take if nothing else is found. Note: this
--   _always_ matches, so should generally be the last route specified.
notFound :: MonadUnliftIO m => ActionT m () -> ScottyT m ()

-- | Set global size limit for the request body. Requests with body size
--   exceeding the limit will not be processed and an HTTP response 413
--   will be returned to the client. Size limit needs to be greater than 0,
--   otherwise the application will terminate on start.
setMaxRequestBodySize :: Kilobytes -> ScottyT m ()

-- | Standard Sinatra-style route. Named captures are prepended with
--   colons. This is the default route type generated by OverloadedString
--   routes. i.e.
--   
--   <pre>
--   get (capture "/foo/:bar") $ ...
--   </pre>
--   
--   and
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   ...
--   get "/foo/:bar" $ ...
--   </pre>
--   
--   are equivalent.
capture :: String -> RoutePattern

-- | Match requests using a regular expression. Named captures are not yet
--   supported.
--   
--   <pre>
--   get (regex "^/f(.*)r$") $ do
--      path &lt;- param "0"
--      cap &lt;- param "1"
--      text $ mconcat ["Path: ", path, "\nCapture: ", cap]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; curl http://localhost:3000/foo/bar
--   Path: /foo/bar
--   Capture: oo/ba
--   </pre>
regex :: String -> RoutePattern

-- | Build a route based on a function which can match using the entire
--   <a>Request</a> object. <a>Nothing</a> indicates the route does not
--   match. A <a>Just</a> value indicates a successful match, optionally
--   returning a list of key-value pairs accessible by <a>param</a>.
--   
--   <pre>
--   get (function $ \req -&gt; Just [("version", T.pack $ show $ httpVersion req)]) $ do
--       v &lt;- param "version"
--       text v
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; curl http://localhost:3000/
--   HTTP/1.1
--   </pre>
function :: (Request -> Maybe [Param]) -> RoutePattern

-- | Build a route that requires the requested path match exactly, without
--   captures.
literal :: String -> RoutePattern

-- | Get the <a>Request</a> object.
request :: Monad m => ActionT m Request

-- | Get a request header. Header name is case-insensitive.
header :: Monad m => Text -> ActionT m (Maybe Text)

-- | Get all the request headers. Header names are case-insensitive.
headers :: Monad m => ActionT m [(Text, Text)]

-- | Get the request body.
body :: MonadIO m => ActionT m ByteString

-- | Get an IO action that reads body chunks
--   
--   <ul>
--   <li>This is incompatible with <a>body</a> since <a>body</a> consumes
--   all chunks.</li>
--   </ul>
bodyReader :: Monad m => ActionT m (IO ByteString)

-- | Get a parameter. First looks in captures, then form data, then query
--   parameters.
--   
--   <ul>
--   <li>Raises an exception which can be caught by <a>rescue</a> if
--   parameter is not found.</li>
--   <li>If parameter is found, but <a>parseParam</a> fails to parse to the
--   correct type, <a>next</a> is called. This means captures are somewhat
--   typed, in that a route won't match if a correctly typed capture cannot
--   be parsed.</li>
--   </ul>

-- | <i>Deprecated: (#204) Not a good idea to treat all parameters
--   identically. Use captureParam, formParam and queryParam instead. </i>
param :: (Parsable a, MonadIO m) => Text -> ActionT m a

-- | Get all parameters from capture, form and query (in that order).

-- | <i>Deprecated: (#204) Not a good idea to treat all parameters
--   identically. Use captureParams, formParams and queryParams instead.
--   </i>
params :: Monad m => ActionT m [Param]

-- | Get a capture parameter.
--   
--   <ul>
--   <li>Raises an exception which can be caught by <a>rescue</a> if
--   parameter is not found. If the exception is not caught, scotty will
--   return a HTTP error code 500 ("Internal Server Error") to the
--   client.</li>
--   <li>If the parameter is found, but <a>parseParam</a> fails to parse to
--   the correct type, <a>next</a> is called.</li>
--   </ul>
captureParam :: (Parsable a, Monad m) => Text -> ActionT m a

-- | Get a form parameter.
--   
--   <ul>
--   <li>Raises an exception which can be caught by <a>rescue</a> if
--   parameter is not found. If the exception is not caught, scotty will
--   return a HTTP error code 400 ("Bad Request") to the client.</li>
--   <li>This function raises a code 400 also if the parameter is found,
--   but <a>parseParam</a> fails to parse to the correct type.</li>
--   </ul>
formParam :: (Parsable a, Monad m) => Text -> ActionT m a

-- | Get a query parameter.
--   
--   <ul>
--   <li>Raises an exception which can be caught by <a>rescue</a> if
--   parameter is not found. If the exception is not caught, scotty will
--   return a HTTP error code 400 ("Bad Request") to the client.</li>
--   <li>This function raises a code 400 also if the parameter is found,
--   but <a>parseParam</a> fails to parse to the correct type.</li>
--   </ul>
queryParam :: (Parsable a, Monad m) => Text -> ActionT m a

-- | Get capture parameters
captureParams :: Monad m => ActionT m [Param]

-- | Get form parameters
formParams :: Monad m => ActionT m [Param]

-- | Get query parameters
queryParams :: Monad m => ActionT m [Param]

-- | Parse the request body as a JSON object and return it.
--   
--   If the JSON object is malformed, this sets the status to 400 Bad
--   Request, and throws an exception.
--   
--   If the JSON fails to parse, this sets the status to 422 Unprocessable
--   Entity.
--   
--   These status codes are as per
--   <a>https://www.restapitutorial.com/httpstatuscodes.html</a>.
jsonData :: (FromJSON a, MonadIO m) => ActionT m a

-- | Get list of uploaded files.
files :: Monad m => ActionT m [File]

-- | Set the HTTP response status.
status :: MonadIO m => Status -> ActionT m ()

-- | Add to the response headers. Header names are case-insensitive.
addHeader :: MonadIO m => Text -> Text -> ActionT m ()

-- | Set one of the response headers. Will override any previously set
--   value for that header. Header names are case-insensitive.
setHeader :: MonadIO m => Text -> Text -> ActionT m ()

-- | Redirect to given URL. Like throwing an uncatchable exception. Any
--   code after the call to redirect will not be run.
--   
--   <pre>
--   redirect "http://www.google.com"
--   </pre>
--   
--   OR
--   
--   <pre>
--   redirect "/foo/bar"
--   </pre>
redirect :: Monad m => Text -> ActionT m a

-- | Set the body of the response to the given <a>Text</a> value. Also sets
--   "Content-Type" header to "text/plain; charset=utf-8" if it has not
--   already been set.
text :: MonadIO m => Text -> ActionT m ()

-- | Set the body of the response to the given <a>Text</a> value. Also sets
--   "Content-Type" header to "text/html; charset=utf-8" if it has not
--   already been set.
html :: MonadIO m => Text -> ActionT m ()

-- | Send a file as the response. Doesn't set the "Content-Type" header, so
--   you probably want to do that on your own with <a>setHeader</a>.
--   Setting a status code will have no effect because Warp will overwrite
--   that to 200 (see <a>sendResponse</a>).
file :: MonadIO m => FilePath -> ActionT m ()

-- | Set the body of the response to the JSON encoding of the given value.
--   Also sets "Content-Type" header to "application/json; charset=utf-8"
--   if it has not already been set.
json :: (ToJSON a, MonadIO m) => a -> ActionT m ()

-- | Set the body of the response to a Source. Doesn't set the
--   "Content-Type" header, so you probably want to do that on your own
--   with <a>setHeader</a>.
stream :: MonadIO m => StreamingBody -> ActionT m ()

-- | Set the body of the response to the given <a>ByteString</a> value.
--   Doesn't set the "Content-Type" header, so you probably want to do that
--   on your own with <a>setHeader</a>.
raw :: MonadIO m => ByteString -> ActionT m ()

-- | Nest a whole WAI application inside a Scotty handler. See Web.Scotty
--   for further documentation
nested :: MonadIO m => Application -> ActionT m ()

-- | Throw a "500 Server Error" <a>StatusError</a>, which can be caught
--   with <a>rescue</a>.
--   
--   Uncaught exceptions turn into HTTP 500 responses.
raise :: MonadIO m => Text -> ActionT m a

-- | Throw a <a>StatusError</a> exception that has an associated HTTP error
--   code and can be caught with <a>rescue</a>.
--   
--   Uncaught exceptions turn into HTTP responses corresponding to the
--   given status.
raiseStatus :: Monad m => Status -> Text -> ActionT m a

-- | Throw an exception which can be caught within the scope of the current
--   Action with <a>rescue</a> or <a>catch</a>.
--   
--   If the exception is not caught locally, another option is to implement
--   a global <a>Handler</a> (with <tt>defaultHandler</tt>) that defines
--   its interpretation and a translation to HTTP error codes.
--   
--   Uncaught exceptions turn into HTTP 500 responses.
throw :: (MonadIO m, Exception e) => e -> ActionT m a

-- | Catch an exception e.g. a <a>StatusError</a> or a user-defined
--   exception.
--   
--   <pre>
--   raise JustKidding `rescue` (\msg -&gt; text msg)
--   </pre>
rescue :: (MonadUnliftIO m, Exception e) => ActionT m a -> (e -> ActionT m a) -> ActionT m a

-- | Abort execution of this action and continue pattern matching routes.
--   Like an exception, any code after <a>next</a> is not executed.
--   
--   NB : Internally, this is implemented with an exception that can only
--   be caught by the library, but not by the user.
--   
--   As an example, these two routes overlap. The only way the second one
--   will ever run is if the first one calls <a>next</a>.
--   
--   <pre>
--   get "/foo/:bar" $ do
--     w :: Text &lt;- captureParam "bar"
--     unless (w == "special") next
--     text "You made a request to /foo/special"
--   
--   get "/foo/:baz" $ do
--     w &lt;- captureParam "baz"
--     text $ "You made a request to: " &lt;&gt; w
--   </pre>
next :: Monad m => ActionT m a

-- | Finish the execution of the current action. Like throwing an
--   uncatchable exception. Any code after the call to finish will not be
--   run.
--   
--   <i>Since: 0.10.3</i>
finish :: Monad m => ActionT m a

-- | Global handler for user-defined exceptions.
defaultHandler :: Monad m => ErrorHandler m -> ScottyT m ()

-- | Catch any synchronous IO exceptions
liftAndCatchIO :: MonadIO m => IO a -> ActionT m a

-- | E.g. when a parameter is not found in a query string (400 Bad Request)
--   or when parsing a JSON body fails (422 Unprocessable Entity)
data StatusError
StatusError :: Status -> Text -> StatusError
type Param = (Text, Text)

-- | Minimum implemention: <a>parseParam</a>
class Parsable a

-- | Take a <a>Text</a> value and parse it as <tt>a</tt>, or fail with a
--   message.
parseParam :: Parsable a => Text -> Either Text a

-- | Default implementation parses comma-delimited lists.
--   
--   <pre>
--   parseParamList t = mapM parseParam (T.split (== ',') t)
--   </pre>
parseParamList :: Parsable a => Text -> Either Text [a]

-- | Useful for creating <a>Parsable</a> instances for things that already
--   implement <a>Read</a>. Ex:
--   
--   <pre>
--   instance Parsable Int where parseParam = readEither
--   </pre>
readEither :: Read a => Text -> Either Text a
data RoutePattern
type File = (Text, FileInfo ByteString)
type Kilobytes = Int

-- | Specializes a <a>Handler</a> to the <a>ActionT</a> monad
type ErrorHandler m = Handler (ActionT m) ()

-- | Generalized version of <a>Handler</a>
data () => Handler (m :: Type -> Type) a
Handler :: (e -> m a) -> Handler (m :: Type -> Type) a
data ScottyT m a
data ActionT m a
data ScottyState m
defaultScottyState :: ScottyState m


-- | This module provides utilities for adding cookie support inside
--   <tt>scotty</tt> applications. Most code has been adapted from
--   'scotty-cookie'.
--   
--   <h2>Example</h2>
--   
--   A simple hit counter that stores the number of page visits in a
--   cookie:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import Control.Monad
--   import Data.Monoid
--   import Data.Maybe
--   import qualified Data.Text.Lazy as TL
--   import qualified Data.Text.Lazy.Read as TL (decimal)
--   import Web.Scotty (scotty, html)
--   import Web.Scotty.Cookie (getCookie, setSimpleCookie)
--   
--   main :: IO ()
--   main = scotty 3000 $
--       get "/" $ do
--           hits &lt;- liftM (fromMaybe "0") $ <a>getCookie</a> "hits"
--           let hits' =
--                 case TL.decimal hits of
--                   Right n -&gt; TL.pack . show . (+1) $ (fst n :: Integer)
--                   Left _  -&gt; "1"
--           <a>setSimpleCookie</a> "hits" $ TL.toStrict hits'
--           html $ mconcat [ "&lt;html&gt;&lt;body&gt;"
--                          , hits'
--                          , "&lt;/body&gt;&lt;/html&gt;"
--                          ]
--   </pre>
module Web.Scotty.Cookie

-- | Set a cookie, with full access to its options (see <a>SetCookie</a>)
setCookie :: MonadIO m => SetCookie -> ActionT m ()

-- | <a>makeSimpleCookie</a> and <a>setCookie</a> combined.
setSimpleCookie :: MonadIO m => Text -> Text -> ActionT m ()

-- | Lookup one cookie name
getCookie :: Monad m => Text -> ActionT m (Maybe Text)

-- | Returns all cookies
getCookies :: Monad m => ActionT m CookiesText

-- | Browsers don't directly delete a cookie, but setting its expiry to a
--   past date (e.g. the UNIX epoch) ensures that the cookie will be
--   invalidated (whether and when it will be actually deleted by the
--   browser seems to be browser-dependent).
deleteCookie :: MonadIO m => Text -> ActionT m ()

-- | Textual cookies. Functions assume UTF8 encoding.
type CookiesText = [(Text, Text)]

-- | Construct a simple cookie (an UTF-8 string pair with default cookie
--   options)
makeSimpleCookie :: Text -> Text -> SetCookie

-- | Data type representing the key-value pair to use for a cookie, as well
--   as configuration options for it.
--   
--   <h4>Creating a SetCookie</h4>
--   
--   <a>SetCookie</a> does not export a constructor; instead, use
--   <a>defaultSetCookie</a> and override values (see
--   <a>http://www.yesodweb.com/book/settings-types</a> for details):
--   
--   <pre>
--   import Web.Cookie
--   :set -XOverloadedStrings
--   let cookie = <a>defaultSetCookie</a> { <a>setCookieName</a> = "cookieName", <a>setCookieValue</a> = "cookieValue" }
--   </pre>
--   
--   <h4>Cookie Configuration</h4>
--   
--   Cookies have several configuration options; a brief summary of each
--   option is given below. For more information, see <a>RFC 6265</a> or
--   <a>Wikipedia</a>.
data () => SetCookie

-- | A minimal <a>SetCookie</a>. All fields are <a>Nothing</a> or
--   <a>False</a> except <tt><a>setCookieName</a> = "name"</tt> and
--   <tt><a>setCookieValue</a> = "value"</tt>. You need this to construct a
--   <a>SetCookie</a>, because it does not export a constructor.
--   Equivalently, you may use <a>def</a>.
defaultSetCookie :: SetCookie

-- | The name of the cookie. Default value: <tt>"name"</tt>
setCookieName :: SetCookie -> ByteString

-- | The value of the cookie. Default value: <tt>"value"</tt>
setCookieValue :: SetCookie -> ByteString

-- | The URL path for which the cookie should be sent. Default value:
--   <tt>Nothing</tt> (The browser defaults to the path of the request that
--   sets the cookie).
setCookiePath :: SetCookie -> Maybe ByteString

-- | The time at which to expire the cookie. Default value:
--   <tt>Nothing</tt> (The browser will default to expiring a cookie when
--   the browser is closed).
setCookieExpires :: SetCookie -> Maybe UTCTime

-- | The maximum time to keep the cookie, in seconds. Default value:
--   <tt>Nothing</tt> (The browser defaults to expiring a cookie when the
--   browser is closed).
setCookieMaxAge :: SetCookie -> Maybe DiffTime

-- | The domain for which the cookie should be sent. Default value:
--   <tt>Nothing</tt> (The browser defaults to the current domain).
setCookieDomain :: SetCookie -> Maybe ByteString

-- | Marks the cookie as "HTTP only", i.e. not accessible from Javascript.
--   Default value: <tt>False</tt>
setCookieHttpOnly :: SetCookie -> Bool

-- | Instructs the browser to only send the cookie over HTTPS. Default
--   value: <tt>False</tt>
setCookieSecure :: SetCookie -> Bool

-- | The "same site" policy of the cookie, i.e. whether it should be sent
--   with cross-site requests. Default value: <tt>Nothing</tt>
setCookieSameSite :: SetCookie -> Maybe SameSiteOption

-- | Data type representing the options for a <a>SameSite cookie</a>
data () => SameSiteOption

-- | Directs the browser to send the cookie for cross-site requests.
sameSiteNone :: SameSiteOption

-- | Directs the browser to send the cookie for <a>safe requests</a> (e.g.
--   <tt>GET</tt>), but not for unsafe ones (e.g. <tt>POST</tt>)
sameSiteLax :: SameSiteOption

-- | Directs the browser to not send the cookie for <i>any</i> cross-site
--   request, including e.g. a user clicking a link in their email to open
--   a page on your site.
sameSiteStrict :: SameSiteOption


-- | It should be noted that most of the code snippets below depend on the
--   OverloadedStrings language pragma.
--   
--   Scotty is set up by default for development mode. For production
--   servers, you will likely want to modify <a>settings</a> and the
--   <a>defaultHandler</a>. See the comments on each of these functions for
--   more information.
module Web.Scotty

-- | Run a scotty application using the warp server.
scotty :: Port -> ScottyM () -> IO ()

-- | Turn a scotty application into a WAI <a>Application</a>, which can be
--   run with any WAI handler.
scottyApp :: ScottyM () -> IO Application

-- | Run a scotty application using the warp server, passing extra options.
scottyOpts :: Options -> ScottyM () -> IO ()

-- | Run a scotty application using the warp server, passing extra options,
--   and listening on the provided socket. This allows the user to provide,
--   for example, a Unix named socket, which can be used when reverse HTTP
--   proxying into your application.
scottySocket :: Options -> Socket -> ScottyM () -> IO ()
data Options
Options :: Int -> Settings -> Options

-- | 0 = silent, 1(def) = startup banner
[verbose] :: Options -> Int

-- | Warp <a>Settings</a> Note: to work around an issue in warp, the
--   default FD cache duration is set to 0 so changes to static files are
--   always picked up. This likely has performance implications, so you may
--   want to modify this for production servers using
--   <tt>setFdCacheDuration</tt>.
[settings] :: Options -> Settings
defaultOptions :: Options

-- | Use given middleware. Middleware is nested such that the first
--   declared is the outermost middleware (it has first dibs on the request
--   and last action on the response). Every middleware is run on each
--   request.
middleware :: Middleware -> ScottyM ()

-- | get = <a>addroute</a> <tt>GET</tt>
get :: RoutePattern -> ActionM () -> ScottyM ()

-- | post = <a>addroute</a> <tt>POST</tt>
post :: RoutePattern -> ActionM () -> ScottyM ()

-- | put = <a>addroute</a> <tt>PUT</tt>
put :: RoutePattern -> ActionM () -> ScottyM ()

-- | delete = <a>addroute</a> <tt>DELETE</tt>
delete :: RoutePattern -> ActionM () -> ScottyM ()

-- | patch = <a>addroute</a> <tt>PATCH</tt>
patch :: RoutePattern -> ActionM () -> ScottyM ()

-- | options = <a>addroute</a> <tt>OPTIONS</tt>
options :: RoutePattern -> ActionM () -> ScottyM ()

-- | Define a route with a <a>StdMethod</a>, <a>Text</a> value representing
--   the path spec, and a body (<tt>Action</tt>) which modifies the
--   response.
--   
--   <pre>
--   addroute GET "/" $ text "beam me up!"
--   </pre>
--   
--   The path spec can include values starting with a colon, which are
--   interpreted as <i>captures</i>. These are named wildcards that can be
--   looked up with <a>param</a>.
--   
--   <pre>
--   addroute GET "/foo/:bar" $ do
--       v &lt;- param "bar"
--       text v
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; curl http://localhost:3000/foo/something
--   something
--   </pre>
addroute :: StdMethod -> RoutePattern -> ActionM () -> ScottyM ()

-- | Add a route that matches regardless of the HTTP verb.
matchAny :: RoutePattern -> ActionM () -> ScottyM ()

-- | Specify an action to take if nothing else is found. Note: this
--   _always_ matches, so should generally be the last route specified.
notFound :: ActionM () -> ScottyM ()

-- | Nest a whole WAI application inside a Scotty handler. Note: You will
--   want to ensure that this route fully handles the response, as there is
--   no easy delegation as per normal Scotty actions. Also, you will have
--   to carefully ensure that you are expecting the correct routes, this
--   could require stripping the current prefix, or adding the prefix to
--   your application's handlers if it depends on them. One potential
--   use-case for this is hosting a web-socket handler under a specific
--   route.
nested :: Application -> ActionM ()

-- | Set global size limit for the request body. Requests with body size
--   exceeding the limit will not be processed and an HTTP response 413
--   will be returned to the client. Size limit needs to be greater than 0,
--   otherwise the application will terminate on start.
setMaxRequestBodySize :: Kilobytes -> ScottyM ()

-- | Standard Sinatra-style route. Named captures are prepended with
--   colons. This is the default route type generated by OverloadedString
--   routes. i.e.
--   
--   <pre>
--   get (capture "/foo/:bar") $ ...
--   </pre>
--   
--   and
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   ...
--   get "/foo/:bar" $ ...
--   </pre>
--   
--   are equivalent.
capture :: String -> RoutePattern

-- | Match requests using a regular expression. Named captures are not yet
--   supported.
--   
--   <pre>
--   get (regex "^/f(.*)r$") $ do
--      path &lt;- param "0"
--      cap &lt;- param "1"
--      text $ mconcat ["Path: ", path, "\nCapture: ", cap]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; curl http://localhost:3000/foo/bar
--   Path: /foo/bar
--   Capture: oo/ba
--   </pre>
regex :: String -> RoutePattern

-- | Build a route based on a function which can match using the entire
--   <a>Request</a> object. <a>Nothing</a> indicates the route does not
--   match. A <a>Just</a> value indicates a successful match, optionally
--   returning a list of key-value pairs accessible by <a>param</a>.
--   
--   <pre>
--   get (function $ \req -&gt; Just [("version", pack $ show $ httpVersion req)]) $ do
--       v &lt;- param "version"
--       text v
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; curl http://localhost:3000/
--   HTTP/1.1
--   </pre>
function :: (Request -> Maybe [Param]) -> RoutePattern

-- | Build a route that requires the requested path match exactly, without
--   captures.
literal :: String -> RoutePattern

-- | Get the <a>Request</a> object.
request :: ActionM Request

-- | Get a request header. Header name is case-insensitive.
header :: Text -> ActionM (Maybe Text)

-- | Get all the request headers. Header names are case-insensitive.
headers :: ActionM [(Text, Text)]

-- | Get the request body.
body :: ActionM ByteString

-- | Get an IO action that reads body chunks
--   
--   <ul>
--   <li>This is incompatible with <a>body</a> since <a>body</a> consumes
--   all chunks.</li>
--   </ul>
bodyReader :: ActionM (IO ByteString)

-- | Get a parameter. First looks in captures, then form data, then query
--   parameters.
--   
--   <ul>
--   <li>Raises an exception which can be caught by <a>rescue</a> if
--   parameter is not found.</li>
--   <li>If parameter is found, but <tt>parseParam</tt> fails to parse to
--   the correct type, <a>next</a> is called. This means captures are
--   somewhat typed, in that a route won't match if a correctly typed
--   capture cannot be parsed.</li>
--   </ul>

-- | <i>Deprecated: (#204) Not a good idea to treat all parameters
--   identically. Use captureParam, formParam and queryParam instead. </i>
param :: Parsable a => Text -> ActionM a

-- | Get all parameters from capture, form and query (in that order).

-- | <i>Deprecated: (#204) Not a good idea to treat all parameters
--   identically. Use captureParams, formParams and queryParams instead.
--   </i>
params :: ActionM [Param]

-- | Get a capture parameter.
--   
--   <ul>
--   <li>Raises an exception which can be caught by <a>rescue</a> if
--   parameter is not found. If the exception is not caught, scotty will
--   return a HTTP error code 500 ("Internal Server Error") to the
--   client.</li>
--   <li>If the parameter is found, but <tt>parseParam</tt> fails to parse
--   to the correct type, <a>next</a> is called.</li>
--   </ul>
captureParam :: Parsable a => Text -> ActionM a

-- | Get a form parameter.
--   
--   <ul>
--   <li>Raises an exception which can be caught by <a>rescue</a> if
--   parameter is not found. If the exception is not caught, scotty will
--   return a HTTP error code 400 ("Bad Request") to the client.</li>
--   <li>This function raises a code 400 also if the parameter is found,
--   but <tt>parseParam</tt> fails to parse to the correct type.</li>
--   </ul>
formParam :: Parsable a => Text -> ActionM a

-- | Get a query parameter.
--   
--   <ul>
--   <li>Raises an exception which can be caught by <a>rescue</a> if
--   parameter is not found. If the exception is not caught, scotty will
--   return a HTTP error code 400 ("Bad Request") to the client.</li>
--   <li>This function raises a code 400 also if the parameter is found,
--   but <tt>parseParam</tt> fails to parse to the correct type.</li>
--   </ul>
queryParam :: Parsable a => Text -> ActionM a

-- | Get capture parameters
captureParams :: ActionM [Param]

-- | Get form parameters
formParams :: ActionM [Param]

-- | Get query parameters
queryParams :: ActionM [Param]

-- | Parse the request body as a JSON object and return it. Raises an
--   exception if parse is unsuccessful.
jsonData :: FromJSON a => ActionM a

-- | Get list of uploaded files.
files :: ActionM [File]

-- | Set the HTTP response status. Default is 200.
status :: Status -> ActionM ()

-- | Add to the response headers. Header names are case-insensitive.
addHeader :: Text -> Text -> ActionM ()

-- | Set one of the response headers. Will override any previously set
--   value for that header. Header names are case-insensitive.
setHeader :: Text -> Text -> ActionM ()

-- | Redirect to given URL. Like throwing an uncatchable exception. Any
--   code after the call to redirect will not be run.
--   
--   <pre>
--   redirect "http://www.google.com"
--   </pre>
--   
--   OR
--   
--   <pre>
--   redirect "/foo/bar"
--   </pre>
redirect :: Text -> ActionM a

-- | Set the body of the response to the given <a>Text</a> value. Also sets
--   "Content-Type" header to "text/plain; charset=utf-8" if it has not
--   already been set.
text :: Text -> ActionM ()

-- | Set the body of the response to the given <a>Text</a> value. Also sets
--   "Content-Type" header to "text/html; charset=utf-8" if it has not
--   already been set.
html :: Text -> ActionM ()

-- | Send a file as the response. Doesn't set the "Content-Type" header, so
--   you probably want to do that on your own with <a>setHeader</a>.
file :: FilePath -> ActionM ()

-- | Set the body of the response to the JSON encoding of the given value.
--   Also sets "Content-Type" header to "application/json; charset=utf-8"
--   if it has not already been set.
json :: ToJSON a => a -> ActionM ()

-- | Set the body of the response to a StreamingBody. Doesn't set the
--   "Content-Type" header, so you probably want to do that on your own
--   with <a>setHeader</a>.
stream :: StreamingBody -> ActionM ()

-- | Set the body of the response to the given <a>ByteString</a> value.
--   Doesn't set the "Content-Type" header, so you probably want to do that
--   on your own with <a>setHeader</a>.
raw :: ByteString -> ActionM ()

-- | Throw a "500 Server Error" <a>StatusError</a>, which can be caught
--   with <a>rescue</a>.
--   
--   Uncaught exceptions turn into HTTP 500 responses.
raise :: Text -> ActionM a

-- | Throw a <a>StatusError</a> exception that has an associated HTTP error
--   code and can be caught with <a>rescue</a>.
--   
--   Uncaught exceptions turn into HTTP responses corresponding to the
--   given status.
raiseStatus :: Status -> Text -> ActionM a

-- | Throw an exception which can be caught within the scope of the current
--   Action with <a>rescue</a> or <tt>catch</tt>.
--   
--   If the exception is not caught locally, another option is to implement
--   a global <a>Handler</a> (with <a>defaultHandler</a>) that defines its
--   interpretation and a translation to HTTP error codes.
--   
--   Uncaught exceptions turn into HTTP 500 responses.
throw :: Exception e => e -> ActionM a

-- | Catch an exception e.g. a <a>StatusError</a> or a user-defined
--   exception.
--   
--   <pre>
--   raise JustKidding `rescue` (\msg -&gt; text msg)
--   </pre>
rescue :: Exception e => ActionM a -> (e -> ActionM a) -> ActionM a

-- | Abort execution of this action and continue pattern matching routes.
--   Like an exception, any code after <a>next</a> is not executed.
--   
--   NB : Internally, this is implemented with an exception that can only
--   be caught by the library, but not by the user.
--   
--   As an example, these two routes overlap. The only way the second one
--   will ever run is if the first one calls <a>next</a>.
--   
--   <pre>
--   get "/foo/:bar" $ do
--     w :: Text &lt;- captureParam "bar"
--     unless (w == "special") next
--     text "You made a request to /foo/special"
--   
--   get "/foo/:baz" $ do
--     w &lt;- captureParam "baz"
--     text $ "You made a request to: " &lt;&gt; w
--   </pre>
next :: ActionM ()

-- | Abort execution of this action. Like an exception, any code after
--   <a>finish</a> is not executed.
--   
--   As an example only requests to <tt>/foo/special</tt> will include in
--   the response content the text message.
--   
--   <pre>
--   get "/foo/:bar" $ do
--     w :: Text &lt;- captureParam "bar"
--     unless (w == "special") finish
--     text "You made a request to /foo/special"
--   </pre>
--   
--   <i>Since: 0.10.3</i>
finish :: ActionM a

-- | Global handler for user-defined exceptions.
defaultHandler :: ErrorHandler IO -> ScottyM ()

-- | Like <tt>liftIO</tt>, but catch any IO exceptions and turn them into
--   Scotty exceptions.
liftAndCatchIO :: IO a -> ActionM a

-- | E.g. when a parameter is not found in a query string (400 Bad Request)
--   or when parsing a JSON body fails (422 Unprocessable Entity)
data StatusError
StatusError :: Status -> Text -> StatusError
type Param = (Text, Text)

-- | Minimum implemention: <a>parseParam</a>
class Parsable a

-- | Take a <a>Text</a> value and parse it as <tt>a</tt>, or fail with a
--   message.
parseParam :: Parsable a => Text -> Either Text a

-- | Default implementation parses comma-delimited lists.
--   
--   <pre>
--   parseParamList t = mapM parseParam (T.split (== ',') t)
--   </pre>
parseParamList :: Parsable a => Text -> Either Text [a]

-- | Useful for creating <a>Parsable</a> instances for things that already
--   implement <a>Read</a>. Ex:
--   
--   <pre>
--   instance Parsable Int where parseParam = readEither
--   </pre>
readEither :: Read a => Text -> Either Text a
type ScottyM = ScottyT IO
type ActionM = ActionT IO
data RoutePattern
type File = (Text, FileInfo ByteString)
type Kilobytes = Int

-- | Generalized version of <a>Handler</a>
data () => Handler (m :: Type -> Type) a
Handler :: (e -> m a) -> Handler (m :: Type -> Type) a
data ScottyState m
defaultScottyState :: ScottyState m
