coltrane: A jazzy, minimal web framework for Haskell, inspired by Sinatra.

[ bsd3, library, web ] [ Propose Tags ]

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.


[Skip to Readme]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 0.1.0.0
Dependencies base (>=4.6 && <4.7), bytestring (>=0.10 && <0.11), HTTP (>=4000.2 && <4000.3), http-types (>=0.8 && <0.9), HUnit (>=1.2 && <1.3), mtl (>=2.1 && <2.2), regex-compat (>=0.95 && <0.96), text (>=0.11 && <0.12), wai (>=2.0 && <2.1), wai-extra (>=2.0 && <2.1), warp (>=2.0 && <2.1) [details]
License BSD-3-Clause
Copyright (c) 2013 Sean Welleck
Author Sean Welleck
Maintainer Sean Welleck
Category Web
Home page https://github.com/wellecks/coltrane
Source repo head: git clone https://github.com/wellecks/coltrane.git
Uploaded by wellecks at 2013-12-25T05:14:22Z
Distributions
Reverse Dependencies 1 direct, 0 indirect [details]
Downloads 1152 total (3 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Successful builds reported [all 2 reports]

Readme for coltrane-0.1.0.0

[back to package description]

#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.

Use Coltrane for concise webapps...

import Coltrane
import ColtraneTypes

main = coltrane Warp 8000 $ do
         get (Literal "/hello") $ do
              html "Hello World!"

... 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. Reading through these types first will help to understand the structure of the framework.

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:

  1. Which functions are visible to the user.

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

    Functions: router, route

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

    Functions: matchesPath

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

    Functions: addroute, addroutes, get, post, put, delete

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

    Functions: setBody, setStatus, setHeader, addHeader.

  6. Request retrieval. Retrieve parameters and the request object.

    Functions: param, request.

####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 Dependencies:

  $ cabal install warp==2.0.0.1
  $ cabal install wai-extra==2.0.0.1
  $ cabal install wai==2.0.0

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 Dependencies

$ cabal install warp==2.0.0.1
$ cabal install wai-extra==2.0.0.1
$ cabal install wai==2.0.0
$ cabal install blaze-html==0.6.1.1

Run It

$ :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 **): An HTML combinator library that allows you to quickly write HTML within Haskell code.

cabal install blaze-html