A jazzy, minimal web framework for Haskell, inspired by Sinatra. https://github.com/wellecks/coltrane
|Latest on Hackage:||0.1.0.0|
This package is not currently in any snapshots. If you're interested in using it, we recommend adding it to Stackage Nightly. Doing so will make builds more reliable, and allow stackage.org to host generated Haddocks.
####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."
You can create variables in your paths, which can be accessed
-- 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
-- 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 ++ "."
Coltrane provides helper functions for
##Content Type Helpers
Coltrane provides helper functions for
htmlFile to load HTML from a file:
get (Literal "/index") $ do htmlFile "index.html"
Catch errors with
catchError and throw exceptions with
put (Literal "/trouble") $ do (throwError "catch me") `catchError` (\err -> text $ err ++ " if you can.")
##Accessing the Request Data
Access the WAI Request object with
get (Literal "/showpath") $ do req <- request html (show $ pathInfo req)
##Modifying the Response
Change the response status code with
get (Literal "/changestatus") $ do setStatus status203 text "Changed on a Moment's Notice"
Add an HTTP header with
get (Literal "/addcookie") $ do addHeader hCookie "ascension" html "Headers up"
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:
ColtraneApp: a monad that stores the application’s state. Specifically, it stores the user-specified routes that are then used by the router.
Route: a method, path, and Handler.
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.
HandlerState: describes the state held by the HandlerM.
####Coltrane.hs This file contains the core functionality of the framework. It contains:
Which functions are visible to the user.
The router, which matches a registered route with an incoming request, and runs the corresponding handler.
Functions: router, route
The matcher, which is used by the router to perform the actual route matching. Matches literal strings, regular expressions, and parses url variables.
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
Response modifiers. Changes the response state within a handler. Specifically, changes the headers, the body, and the status.
Functions: setBody, setStatus, setHeader, addHeader.
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:
$ cabal install warp==220.127.116.11 $ cabal install wai-extra==18.104.22.168 $ 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/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:
$ cabal install warp==22.214.171.124 $ cabal install wai-extra==126.96.36.199 $ cabal install wai==2.0.0 $ cabal install blaze-html==0.6.1.1
$ :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==188.8.131.52
warp: a haskell web server used by WAI.
cabal install warp==184.108.40.206
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