Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 121 lines (72 sloc) 4.423 kb
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
1 # Ring
2
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
3 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.
4
5 The `SPEC` file at the root of this distribution for provides a complete description of the Ring interface.
6
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
7 ## Synopsis
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
8
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
9 A "Hello World" Ring handler:
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
10
11 (use 'ring.adapter.jetty)
12
13 (defn app [req]
14 {:status 200
15 :headers {"Content-Type" "text/html"}
16 :body "Hello World from Ring"})
17
18 (run-jetty app {:port 8080})
19
20 Adding simple middleware:
21
f2f4229 @mmcgrana Doc and example tweaks.
authored
22 (defn wrap-upcase [app]
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
23 (fn [req]
24 (let [orig-resp (app req)]
25 (assoc orig-resp :body (.toUpperCase (:body orig-resp))))))
26
f2f4229 @mmcgrana Doc and example tweaks.
authored
27 (def upcase-app (wrap-upcase app))
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
28
29 (run-jetty upcase-app {:port 8080})
30
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
31 ## Quick Start
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
32
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
33 To see some working examples, 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
34
2c378d9 @mmcgrana Leiningen dependency management.
authored
35 $ lein deps
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
36
37 To see a live "Hello World" Ring app, run:
38
f2f4229 @mmcgrana Doc and example tweaks.
authored
39 $ clj example/hello_world.clj
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
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
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
45 To see a more sophisticated Ring app, run:
46
f2f4229 @mmcgrana Doc and example tweaks.
authored
47 $ clj example/wrapping.clj
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
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
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
53 ## Available Libraries
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
54
55 ### ring-core
56
8a352f9 @mmcgrana Fill out library descriptions.
authored
57 * `ring.middleware.file`: Serve static files out of a public directory.
58 * `ring.middleware.static`: Serve static files with specified prefixes out of a public directory.
59 * `ring.middleware.file-info`: Augment response headers with info about File responses.
60 * `ring.middleware.params`: Parse query and form params.
4bc4619 @mmcgrana Rename ring.util.multipart to multipart-params.
authored
61 * `ring.middleware.multipart-params`: Parse multipart params.
8a352f9 @mmcgrana Fill out library descriptions.
authored
62 * `ring.middleware.cookies`: Manage browser cookies.
63 * `ring.middleware.session`: Manage user sessions. Memory and cookie session stores are available by default.
59b0a0e @mmcgrana README typo.
authored
64 * `ring.util.response`: Generate Ring responses.
28dd65c @mmcgrana Start sketching ring.util.{request,response}.
authored
65 * `ring.util.request`: Parse Ring requests.
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
66
67 ### ring-devel
68
8a352f9 @mmcgrana Fill out library descriptions.
authored
69 * `ring.handler.dump`: Dumps request maps as HTML responses for debugging.
70 * `ring.middleware.lint`: Lint requests and responses to ensure compliance with the Ring spec.
71 * `ring.middleware.reload`: Automatically reload selected libs before each request.
72 * `ring.middleware.stacktrace`: Catch exceptions and displays readable stacktraces for debugging.
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
73
74 ### ring-servlet
75
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
76 * `ring.util.servlet`: Utilities for interfacing with Java Servlets.
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
77
78 ### ring-jetty-adapter
79
80 * `ring.adapter.jetty`: Adapter for the Jetty webserver.
81
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
82 ### ring-httpcore-adapter
83
84 * `ring.adapter.httpcore`: Adapter for the Apache HttpCore webserver.
85
86 ## Leiningen Usage
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
87
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
88 To include one of the above libraries in your Leiningen project, for example `ring-core`, add the following to your `:dependences`:
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
89
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
90 [ring/ring-core "0.2.0-SNAPSHOT"]
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
91
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
92 or to depend on all of the available Ring libraries, add:
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
93
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
94 [ring/ring "0.2.0-SNAPSHOT"]
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
95
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
96 ## Development
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
97
f2f4229 @mmcgrana Doc and example tweaks.
authored
98 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
99
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
100 To run the Ring unit tests, first navigate to the appropriate project and then:
101
102 $ lein deps
f2f4229 @mmcgrana Doc and example tweaks.
authored
103 $ lein test
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
104
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
105 ## Thanks
106
107 This project borrows heavily from Ruby's Rack and Python's WSGI; thanks to those communities for their work.
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
108
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
109 Thanks also to the following Ring contributors:
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
110
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
111 * James Reeves
112 * Christophe Grand
113 * Richard Newman
114 * Seth Buntin
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
115
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
116 ## License
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
117
f2f4229 @mmcgrana Doc and example tweaks.
authored
118 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
119
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
120 Clojure logo by Tom Hickey.
Something went wrong with that request. Please try again.