Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A jazzy Haskell web framework.
Haskell
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
extra
.gitignore
Coltrane.hs
ColtraneTests.hs
ColtraneTypes.hs
LICENSE
README.md
Setup.hs
coltrane.cabal

README.md

Coltrane

A Minimal Web Framework for Haskell

Sean Welleck | Yuanfeng Peng

Coltrane is a minimal web framework for Haskell, inspired by Ruby's Sinatra framework. Coltrane lets you write simple web applications in just a few lines of Haskell code.

Install Coltrane using cabal...

$ cabal install coltrane

...then use Coltrane to write concise webapps...

import Coltrane
import ColtraneTypes

app :: ColtraneApp ()
app = get (Literal "/hello") $ do
           html "Hello World!"

main = coltrane Warp 8000 app

... and all that jazz.

$ main
$ == Coltrane has taken the stage ..
$ >> playing on port 8000

Coltrane was built as a final project for CIS552: Advanced Programming, and is now open-sourced!

Routes

A route consists of a method, a path, and a handler. A path can be:

  • string literal
get (Literal "/album") $ do
         text "A Love Supreme"
  • regular expression
get (RegExp mkRegex "^(/[0-9]+)") $ do
         text "I like numbers."

Path variables

You can create variables in your paths, which can be accessed using the param function:

-- e.g. handles a request to /jazz
get (Literal "/:item") $ do
    item <- param ":item"
    html "My favorite thing is: " ++ item

-- e.g. handles a request to /miles/davis
get (Literal "/:first/:last") $ do
    fname <- param ":first"
    lname <- param ":last"
    html "John Coltrane, featuring " ++ fname ++ " " ++ lname

GET and POST parameters

You can also access parameters from GET and POST requests using the param function.

-- e.g. handles a GET request to /submit?venue=village
get (Literal "/submit") $ do
    venue <- param "venue"
    html "Live at " ++ venue ++ "."

-- e.g. handles a POST request to /submit with venue=village as a parameter
post (Literal "/submit") $ do
    venue <- param "venue"
    html "Live at " ++ venue ++ "."

HTTP Methods

Coltrane provides helper functions for get, post, put, delete.

Content Type Helpers

Coltrane provides helper functions for text, html, json, file.

HTML Files

Use htmlFile to load HTML from a file:

get (Literal "/index") $ do
    htmlFile "index.html"

Exceptions

Catch errors with catchError and throw exceptions with throwError:

put (Literal "/trouble") $ do
    (throwError "catch me")
    `catchError`
    (\err -> text $ err ++ " if you can.")

Accessing the Request Data

Access the WAI Request object with request:

get (Literal "/showpath") $ do 
    req <- request 
    html (show $ pathInfo req)

Modifying the Response

Change the response status code with setStatus:

get (Literal "/changestatus") $ do
    setStatus status203
    text "Changed on a Moment's Notice"

Add an HTTP header with addHeader:

get (Literal "/addcookie") $ do
    addHeader hCookie "ascension"
    html "Headers up."

Alternatively, setHeader modifies an existing header's value, or adds a new header if it doesn't exist.


Files

ColtraneTypes.hs

This file contains the types used in the library.

Notable types include:

  1. ColtraneApp: a monad that stores the application's state. Specifically, it stores the user-specified routes that are then used by the router.

  2. Route: a method, path, and Handler.

  3. HandlerM: A monad for processing a request and building a response. Stores information that is used and modified within a route handler, and is able to throw and catch errors. Specifically, contains the request, the parameters, and the response state. Intuitively, a Handler consists of 'building' a response state that is then turned into a response and sent to the server.

  4. HandlerState: describes the state held by the HandlerM.

Coltrane.hs

This file contains the core functionality of the framework. It contains functions for:

  • The router, which matches a registered route with an incoming request, and runs the corresponding handler.

  • The matcher, which is used by the router to perform the actual route matching. Matches literal strings, regular expressions, and parses url variables.

  • Routing helpers. Associates a Path and a Handler to create a route, which is added to the ColtraneApp state.

  • Response modifiers. Changes the response state within a handler. Specifically, changes the headers, the body, and the status.

  • Request retrieval. Retrieve parameters and the request object.

ColtraneTests.hs

Contains all of the tests, as well as examples of how to use the framework. In order to run the tests, the server must be running, so do the following:

Install:

  $ cabal install coltrane

GHCI one (running the server)

  $ :load ColtraneTests
  $ main

GHCI two (running the tests)

  $ :load ColtraneTests
  $ runTests

Note that the server is running on port 9000, so you can navigate to pages in the browser, e.g.:

  • http://localhost:9000
  • http://localhost:9000/hello
  • http://localhost:9000/param/firstname/lastname (replace firstname and lastname as desired)

Extra Files

website.hs

A sample web app built using Coltrane and the Blaze HTML library. Hopefully it's an example of how easy and concise it is to build a web app using the framework!

To run in ghci:

Install

$ cabal install coltrane

Run

$ :load website.hs. 
$ main

Then navigate to http://localhost:8000 in a web browser.


Libraries Used & Dependencies

wai: A Middleware library that provides a common interface between Coltrane and the underlying web servers. http://hackage.haskell.org/package/wai

cabal install wai==2.0.0

wai-extra: Provides additional tools for use with wai. We use it to parse parameters from a Request body. http://hackage.haskell.org/package/wai-extra

cabal install wai-extra==2.0.0.1

warp: a haskell web server used by WAI.

cabal install warp==2.0.0.1

Network.HTTP: A simple HTTP interface. Also contains some common types used in web-related libraries, such as StdMethod, and HeaderName. We also use this library to generate requests and responses for testing.

blaze-html (** only used by the sample website.hs as a demonstration **): An HTML combinator library that allows you to quickly write HTML within Haskell code.

cabal install blaze-html
Something went wrong with that request. Please try again.