/ring forked from ring-clojure/ring

Permalink
ring/README.markdown
Newer
Older
Raw Normal view History
100644 87 lines (56 sloc) 3.58 KB
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
1 Ring is a Clojure web applications library inspired by Python's WSGI and Ruby's Rack. By abstracting the details of HTTP into a simple, unified API, Ring allows web applications to be constructed of modular components that can be shared among a variety of applications, web servers, and web frameworks.
2
3 The `SPEC` file at the root of this distribution for provides a complete description of the Ring interface.
4
5 Examples
6 --------
7
8 A Ring handler:
9
10 (use 'ring.adapter.jetty)
11
12 (defn app [req]
13 {:status 200
14 :headers {"Content-Type" "text/html"}
15 :body "Hello World from Ring"})
16
17 (run-jetty app {:port 8080})
18
19 Adding simple middleware:
20
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
21 (defn wrap-upcase [app]
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
22 (fn [req]
23 (let [orig-resp (app req)]
24 (assoc orig-resp :body (.toUpperCase (:body orig-resp))))))
25
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
26 (def upcase-app (wrap-upcase app))
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
27
28 (run-jetty upcase-app {:port 8080})
29
30 Quick Start
31 -----------
32
2c378d9 @mmcgrana Leiningen dependency management.
authored Jan 17, 2010
33 First, pull in Ring's dependencies using [Leiningen](http://github.com/technomancy/leiningen):
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
34
2c378d9 @mmcgrana Leiningen dependency management.
authored Jan 17, 2010
35 $ lein deps
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
36
37 To see a live "Hello World" Ring app, run:
38
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
39 $ clj example/hello_world.clj
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
40
41 Now visit `http://localhost:8080/` in your browser; the Ring app will respond to your request with a simple HTML page indicating the time of day.
42
2c378d9 @mmcgrana Leiningen dependency management.
authored Jan 17, 2010
43 Note that your `clj` script needs to add the `src` directory and the jars in `lib` to your classpath.
44
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
45 To see a more sophisticated Ring app, run:
46
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
47 $ clj example/wrapping.clj
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
48
49 * If you request `http://localhost:8080/` in your browser the `ring.handler.dump` handler will respond with an HTML page representing the request map that it received (see the `SPEC` for details on the request map).
50 * If you request `http://localhost:8080/clojure.png`, the `ring.middleware.file` middleware will detect that there is a `clojure.png` file in the app's `public` directory and return that image as a response.
51 * If you request `http://localhost:8080/error`, the app will produce an error that will be caught by the `ring.middleware.stacktrace` middleware, which will in turn return a readable stacktrace as the HTML response.
52
53 Included Libs
54 -------------
55
56 * `ring.adapter.jetty`: Adapter for the Jetty webserver.
57 * `ring.adapter.httpcore`: Adapter for the Apache HttpCore webserver.
58 * `ring.middleware.file`: Middleware that serves static files out of a public directory.
59 * `ring.middleware.file-info`: Middleware that augments response headers with info about File responses.
60 * `ring.middleware.lint`: Linter for the Ring interface, ensures compliance with the Ring spec.
61 * `ring.middleware.reload`: Middleware to automatically reload selected libs before each requests, minimizing server restarts.
62 * `ring.middleware.stacktrace`: Middleware that catches exceptions and displays readable stacktraces for debugging.
63 * `ring.middleware.static`: Middleware that serves static files with specified prefixes out of a public directory.
64 * `ring.handler.dump`: Handler that dumps request maps as HTML responses for debugging.
65 * `ring.util.servlet`: Utilities for interfacing with Java Servlets.
66 * `ring.example.*`: Various example Ring apps.
67
68 Development
69 -----------
70
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
71 Ring is being actively developed; you can track its progress and contribute at the project's [GitHub page](http://github.com/mmcgrana/ring) and [Google Group](http://groups.google.com/group/ring-clojure).
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
72
73 To run all the Ring unit tests:
74
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
75 $ lein test
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
76
77 Thanks
78 ------
79
80 This project borrows heavily from Ruby's Rack and Python's WSGI, and I thank the communities developing and supporting those projects.
81
82 License
83 -------
84
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
85 Copyright (c) 2009-2010 Mark McGranaghan and released under an MIT license.
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
86
87 Clojure logo by Tom Hickey.