-- 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
--   
--   import Data.Monoid (mconcat)
--   
--   main = scotty 3000 $ do
--     get "/:word" $ do
--       beam &lt;- param "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.5.0


-- | 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.
module Web.Scotty.Trans

-- | Run a scotty application using the warp server. NB: 'scotty p' ===
--   'scottyT p id id'
scottyT :: (Monad m, MonadIO n) => Port -> (forall a. m a -> n a) -> (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: <tt>scottyApp</tt> === 'scottyAppT id
--   id'
scottyAppT :: (Monad m, Monad n) => (forall a. m a -> n a) -> (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 id'
scottyOptsT :: (Monad m, MonadIO n) => Options -> (forall a. m a -> n a) -> (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>
settings :: Options -> Settings

-- | 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 :: Monad m => Middleware -> ScottyT m ()

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

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

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

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

-- | patch = <a>addroute</a> <a>PATCH</a>
patch :: MonadIO 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>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 :: MonadIO m => StdMethod -> RoutePattern -> ActionT m () -> ScottyT m ()

-- | Add a route that matches regardless of the HTTP verb.
matchAny :: MonadIO 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 :: MonadIO m => ActionT m () -> 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.
reqHeader :: Monad m => Text -> ActionT m (Maybe Text)

-- | Get the request body.
body :: Monad m => ActionT m 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>read</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>
param :: (Parsable a, Monad m) => Text -> ActionT m a

-- | Get all parameters from capture, form and query (in that order).
params :: Monad m => ActionT m [Param]

-- | Parse the request body as a JSON object and return it. Raises an
--   exception if parse is unsuccessful.
jsonData :: (FromJSON a, Monad m) => ActionT m a

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

-- | Set the HTTP response status. Default is 200.
status :: Monad m => Status -> ActionT m ()

-- | Add to the response headers. Header names are case-insensitive.
addHeader :: Monad 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 :: Monad 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".
text :: Monad 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".
html :: Monad 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 <tt>header</tt>.
file :: Monad 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".
json :: (ToJSON a, Monad 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 <tt>header</tt>.
source :: Monad m => Source (ResourceT IO) (Flush Builder) -> 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 <tt>header</tt>.
raw :: Monad m => ByteString -> ActionT m ()

-- | Throw an exception, which can be caught with <a>rescue</a>. Uncaught
--   exceptions turn into HTTP 500 responses.
raise :: Monad m => Text -> ActionT m a

-- | Catch an exception thrown by <a>raise</a>.
--   
--   <pre>
--   raise "just kidding" `rescue` (\msg -&gt; text msg)
--   </pre>
rescue :: Monad m => ActionT m a -> (Text -> 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.
--   
--   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/:number" $ do
--     n &lt;- param "number"
--     unless (all isDigit n) $ next
--     text "a number"
--   
--   get "/foo/:bar" $ do
--     bar &lt;- param "bar"
--     text "not a number"
--   </pre>
next :: Monad m => ActionT m a
type Param = (Text, Text)

-- | Minimum implemention: <a>parseParam</a>
class Parsable a where parseParamList t = mapM parseParam (split (== ',') t)
parseParam :: Parsable a => Text -> Either Text a
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 a = ScottyT IO a
type ActionM a = ActionT IO a
data RoutePattern
type File = (Text, FileInfo ByteString)
data ScottyT m a
data ActionT m a


-- | It should be noted that most of the code snippets below depend on the
--   OverloadedStrings language pragma.
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 ()
data Options
Options :: Int -> Settings -> Options

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

-- | Warp <a>Settings</a>
settings :: Options -> Settings

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

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

-- | 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.
reqHeader :: Text -> ActionM (Maybe Text)

-- | Get the request body.
body :: ActionM 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>read</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>
param :: Parsable a => Text -> ActionM a

-- | Get all parameters from capture, form and query (in that order).
params :: 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".
text :: Text -> ActionM ()

-- | Set the body of the response to the given <a>Text</a> value. Also sets
--   "Content-Type" header to "text/html".
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 <tt>header</tt>.
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".
json :: ToJSON a => a -> ActionM ()

-- | 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 <tt>header</tt>.
source :: Source (ResourceT IO) (Flush Builder) -> 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 <tt>header</tt>.
raw :: ByteString -> ActionM ()

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

-- | Catch an exception thrown by <a>raise</a>.
--   
--   <pre>
--   raise "just kidding" `rescue` (\msg -&gt; text msg)
--   </pre>
rescue :: ActionM a -> (Text -> 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.
--   
--   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/:number" $ do
--     n &lt;- param "number"
--     unless (all isDigit n) $ next
--     text "a number"
--   
--   get "/foo/:bar" $ do
--     bar &lt;- param "bar"
--     text "not a number"
--   </pre>
next :: ActionM a
type Param = (Text, Text)

-- | Minimum implemention: <a>parseParam</a>
class Parsable a where parseParamList t = mapM parseParam (split (== ',') t)
parseParam :: Parsable a => Text -> Either Text a
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 a = ScottyT IO a
type ActionM a = ActionT IO a
data RoutePattern
type File = (Text, FileInfo ByteString)
