scotty-0.4.6: Haskell web framework inspired by Ruby's Sinatra, using WAI and Warp

Safe HaskellNone




It should be noted that most of the code snippets below depend on the OverloadedStrings language pragma.



scotty :: Port -> ScottyM () -> IO ()Source

Run a scotty application using the warp server.

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.

data Options Source




verbose :: Int

0 = silent, 1(def) = startup banner

settings :: Settings

Warp Settings


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.

get :: Action action => RoutePattern -> action -> ScottyM ()Source

get = addroute GET

post :: Action action => RoutePattern -> action -> ScottyM ()Source

post = addroute POST

put :: Action action => RoutePattern -> action -> ScottyM ()Source

put = addroute PUT

delete :: Action action => RoutePattern -> action -> ScottyM ()Source

delete = addroute DELETE

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

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") $ ...


 {-# 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/

literal :: String -> RoutePatternSource

Build a route that requires the requested path match exactly, without captures.

Defining Actions

class Action a Source

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]


Action (ActionM a) 
(Parsable a, Action b) => Action (a -> b) 

Accessing the Request, Captures, and Query Parameters

reqHeader :: Text -> ActionM TextSource

Get a request header. Header name is case-insensitive.

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.

  • Raises an exception which can be caught by rescue if parameter is not found.
  • If parameter is found, but read fails to parse to the correct type, next is called. This means captures are somewhat typed, in that a route won't match if a correctly typed capture cannot be parsed.

params :: ActionM [Param]Source

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

jsonData :: FromJSON a => ActionM aSource

Parse the request body as a JSON object and return it. Raises an exception if parse is unsuccessful.

files :: ActionM [File]Source

Get list of uploaded files.

Modifying the Response and Redirecting

status :: Status -> ActionM ()Source

Set the HTTP response status. Default is 200.

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


 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.


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)

next :: ActionM aSource

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

class Parsable a whereSource

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 parseParamList to parse String.

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 baz will parse as (), where bar will not.

Parsable ByteString 
Parsable Text 
Parsable a => Parsable [a] 

readEither :: Read a => Text -> Either Text aSource

Useful for creating Parsable instances for things that already implement Read. Ex:

 instance Parsable Int where parseParam = readEither