Safe Haskell | None |
---|
It should be noted that most of the code snippets below depend on the OverloadedStrings language pragma.
- scotty :: Port -> ScottyM () -> IO ()
- scottyApp :: ScottyM () -> IO Application
- scottyOpts :: Options -> ScottyM () -> IO ()
- data Options = Options {}
- middleware :: Middleware -> ScottyM ()
- get :: Action action => RoutePattern -> action -> ScottyM ()
- post :: Action action => RoutePattern -> action -> ScottyM ()
- put :: Action action => RoutePattern -> action -> ScottyM ()
- delete :: Action action => RoutePattern -> action -> ScottyM ()
- addroute :: Action action => StdMethod -> RoutePattern -> action -> ScottyM ()
- matchAny :: Action action => RoutePattern -> action -> ScottyM ()
- notFound :: ActionM () -> ScottyM ()
- capture :: String -> RoutePattern
- regex :: String -> RoutePattern
- function :: (Request -> Maybe [Param]) -> RoutePattern
- literal :: String -> RoutePattern
- class Action a
- request :: ActionM Request
- reqHeader :: Text -> ActionM Text
- body :: ActionM ByteString
- param :: Parsable a => Text -> ActionM a
- params :: ActionM [Param]
- jsonData :: FromJSON a => ActionM a
- files :: ActionM [File]
- status :: Status -> ActionM ()
- header :: Text -> Text -> ActionM ()
- redirect :: Text -> ActionM a
- text :: Text -> ActionM ()
- html :: Text -> ActionM ()
- file :: FilePath -> ActionM ()
- json :: ToJSON a => a -> ActionM ()
- source :: Source (ResourceT IO) (Flush Builder) -> ActionM ()
- raise :: Text -> ActionM a
- rescue :: ActionM a -> (Text -> ActionM a) -> ActionM a
- next :: ActionM a
- type Param = (Text, Text)
- class Parsable a where
- parseParam :: Text -> Either Text a
- parseParamList :: Text -> Either Text [a]
- readEither :: Read a => Text -> Either Text a
- data ScottyM a
- data ActionM a
- data RoutePattern
- type File = (Text, FileInfo ByteString)
scotty-to-WAI
scottyApp :: ScottyM () -> IO ApplicationSource
Turn a scotty application into a WAI Application
, which can be
run with any WAI handler.
scottyOpts :: Options -> ScottyM () -> IO ()Source
Run a scotty application using the warp server, passing extra options.
Defining Middleware and Routes
Middleware
and routes are run in the order in which they
are defined. All middleware is run first, followed by the first
route that matches. If no route matches, a 404 response is given.
middleware :: Middleware -> ScottyM ()Source
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.
addroute :: Action action => StdMethod -> RoutePattern -> action -> ScottyM ()Source
Define a route with a StdMethod
, Text
value representing the path spec,
and a body (Action
) which modifies the response.
addroute GET "/" $ text "beam me up!"
The path spec can include values starting with a colon, which are interpreted
as captures. These are named wildcards that can be looked up with param
.
addroute GET "/foo/:bar" $ do v <- param "bar" text v
>>>
curl http://localhost:3000/foo/something
something
matchAny :: Action action => RoutePattern -> action -> ScottyM ()Source
Add a route that matches regardless of the HTTP verb.
notFound :: ActionM () -> ScottyM ()Source
Specify an action to take if nothing else is found. Note: this _always_ matches, so should generally be the last route specified.
Route Patterns
capture :: String -> RoutePatternSource
Standard Sinatra-style route. Named captures are prepended with colons. This is the default route type generated by OverloadedString routes. i.e.
get (capture "/foo/:bar") $ ...
and
{-# LANGUAGE OverloadedStrings #-} ... get "/foo/:bar" $ ...
are equivalent.
regex :: String -> RoutePatternSource
Match requests using a regular expression. Named captures are not yet supported.
get (regex "^/f(.*)r$") $ do path <- param "0" cap <- param "1" text $ mconcat ["Path: ", path, "\nCapture: ", cap]
>>>
curl http://localhost:3000/foo/bar
Path: /foo/bar Capture: oo/ba
function :: (Request -> Maybe [Param]) -> RoutePatternSource
Build a route based on a function which can match using the entire Request
object.
Nothing
indicates the route does not match. A Just
value indicates
a successful match, optionally returning a list of key-value pairs accessible
by param
.
get (function $ \req -> Just [("version", T.pack $ show $ httpVersion req)]) $ do v <- param "version" text v
>>>
curl http://localhost:3000/
HTTP/1.1
literal :: String -> RoutePatternSource
Build a route that requires the requested path match exactly, without captures.
Defining Actions
An action (executed when a route matches) can either be an ActionM
computation, or
a function with an argument for each capture in the route. For example:
get "/lambda/:foo/:bar" $ \ a b -> do text $ mconcat [a,b]
is elaborated by Scotty to:
get "/lambda/:foo/:bar" $ do a <- param "foo" b <- param "bar" text $ mconcat [a,b]
Accessing the Request, Captures, and Query Parameters
body :: ActionM ByteStringSource
Get the request body.
param :: Parsable a => Text -> ActionM aSource
Get a parameter. First looks in captures, then form data, then query parameters.
jsonData :: FromJSON a => ActionM aSource
Parse the request body as a JSON object and return it. Raises an exception if parse is unsuccessful.
Modifying the Response and Redirecting
header :: Text -> Text -> ActionM ()Source
Set one of the response headers. Will override any previously set value for that header. Header names are case-insensitive.
redirect :: Text -> ActionM aSource
Redirect to given URL. Like throwing an uncatchable exception. Any code after the call to redirect will not be run.
redirect "http://www.google.com"
OR
redirect "/foo/bar"
Setting Response Body
Note: only one of these should be present in any given route
definition, as they completely replace the current Response
body.
text :: Text -> ActionM ()Source
Set the body of the response to the given Text
value. Also sets "Content-Type"
header to "text/plain".
html :: Text -> ActionM ()Source
Set the body of the response to the given Text
value. Also sets "Content-Type"
header to "text/html".
file :: FilePath -> ActionM ()Source
Send a file as the response. Doesn't set the "Content-Type" header, so you probably
want to do that on your own with header
.
json :: ToJSON a => a -> ActionM ()Source
Set the body of the response to the JSON encoding of the given value. Also sets "Content-Type" header to "application/json".
source :: Source (ResourceT IO) (Flush Builder) -> ActionM ()Source
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 header
.
Exceptions
raise :: Text -> ActionM aSource
Throw an exception, which can be caught with rescue
. Uncaught exceptions
turn into HTTP 500 responses.
rescue :: ActionM a -> (Text -> ActionM a) -> ActionM aSource
Catch an exception thrown by raise
.
raise "just kidding" `rescue` (\msg -> text msg)
Abort execution of this action and continue pattern matching routes.
Like an exception, any code after next
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 next
.
get "/foo/:number" $ do n <- param "number" unless (all isDigit n) $ next text "a number" get "/foo/:bar" $ do bar <- param "bar" text "not a number"
Parsing Parameters
Minimum implemention: parseParam
parseParam :: Text -> Either Text aSource
Take a Text
value and parse it as a
, or fail with a message.
parseParamList :: Text -> Either Text [a]Source
Default implementation parses comma-delimited lists.
parseParamList t = mapM parseParam (T.split (== ',') t)
Parsable Bool | |
Parsable Char | Overrides default |
Parsable Double | |
Parsable Float | |
Parsable Int | |
Parsable Integer | |
Parsable () | Checks if parameter is present and is null-valued, not a literal '()'.
If the URI requested is: '/foo?bar=()&baz' then |
Parsable ByteString | |
Parsable Text | |
Parsable a => Parsable [a] |
Types
Monad ActionM | |
Functor ActionM | |
MonadIO ActionM | |
MonadError ActionError ActionM | |
MonadReader ActionEnv ActionM | |
MonadState Response ActionM | |
Action (ActionM a) |
type File = (Text, FileInfo ByteString)Source