Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 120 lines (72 sloc) 4.837 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
8ca2df9 @mmcgrana Simple running of Readme examples.
authored
9 "Hello World" in Ring:
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
10
11 (use 'ring.adapter.jetty)
4e630cc @weavejester Release 0.2.3.
weavejester authored
12
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
13 (defn app [req]
14 {:status 200
15 :headers {"Content-Type" "text/html"}
16 :body "Hello World from Ring"})
4e630cc @weavejester Release 0.2.3.
weavejester authored
17
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
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))))))
4e630cc @weavejester Release 0.2.3.
weavejester authored
26
f2f4229 @mmcgrana Doc and example tweaks.
authored
27 (def upcase-app (wrap-upcase app))
4e630cc @weavejester Release 0.2.3.
weavejester authored
28
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
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
8ca2df9 @mmcgrana Simple running of Readme examples.
authored
39 $ java -cp "lib/*" clojure.main 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
43 To see a more sophisticated Ring app, run:
44
8ca2df9 @mmcgrana Simple running of Readme examples.
authored
45 $ java -cp "lib/*" clojure.main example/wrapping.clj
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
46
47 * 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).
48 * 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.
49 * 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.
59f2867 @mmcgrana Point to new gh-pages hosted docs.
authored
50
51
52 ## Documentation
53
54 * [Ring namespace and function docs](http://mmcgrana.github.com/ring/)
55
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
56 ## Available Libraries
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
57
58 ### ring-core
59
8a352f9 @mmcgrana Fill out library descriptions.
authored
60 * `ring.middleware.file`: Serve static files out of a public directory.
9149d47 @weavejester Release 0.3.8
weavejester authored
61 * `ring.middleware.resource`: Serve static classpath resources.
8a352f9 @mmcgrana Fill out library descriptions.
authored
62 * `ring.middleware.file-info`: Augment response headers with info about File responses.
67989da @weavejester Added new libraries to README
weavejester authored
63 * `ring.middleware.content-type`: Augment response headers with a content-type based on the file extension.
8a352f9 @mmcgrana Fill out library descriptions.
authored
64 * `ring.middleware.params`: Parse query and form params.
4bc4619 @mmcgrana Rename ring.util.multipart to multipart-params.
authored
65 * `ring.middleware.multipart-params`: Parse multipart params.
4e630cc @weavejester Release 0.2.3.
weavejester authored
66 * `ring.middleware.keyword-params`: Convert string param keys to keywords.
531fbf4 @weavejester Release 0.3.2.
weavejester authored
67 * `ring.middleware.nested-params`: Convert a flat map of parameters into a nested map of parameters.
8a352f9 @mmcgrana Fill out library descriptions.
authored
68 * `ring.middleware.cookies`: Manage browser cookies.
69 * `ring.middleware.session`: Manage user sessions. Memory and cookie session stores are available by default.
4e630cc @weavejester Release 0.2.3.
weavejester authored
70 * `ring.middleware.flash`: Adds flash message support to sessions.
59b0a0e @mmcgrana README typo.
authored
71 * `ring.util.response`: Generate Ring responses.
67989da @weavejester Added new libraries to README
weavejester authored
72 * `ring.util.codec`: Encode and decode string data.
73 * `ring.util.mime-type`: Guess the mime-type from a file extension.
74
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
75 ### ring-devel
76
8a352f9 @mmcgrana Fill out library descriptions.
authored
77 * `ring.handler.dump`: Dumps request maps as HTML responses for debugging.
78 * `ring.middleware.lint`: Lint requests and responses to ensure compliance with the Ring spec.
3b06648 @weavejester Release 1.0.0-beta1
weavejester authored
79 * `ring.middleware.reload`: Automatically reload modified namespaces before each request.
8a352f9 @mmcgrana Fill out library descriptions.
authored
80 * `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
81
82 ### ring-servlet
83
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
84 * `ring.util.servlet`: Utilities for interfacing with Java Servlets.
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
85
86 ### ring-jetty-adapter
87
88 * `ring.adapter.jetty`: Adapter for the Jetty webserver.
89
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
90 ## Leiningen Usage
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
91
b5909c9 @weavejester Release 0.3.6.
weavejester authored
92 To include one of the above libraries in your Leiningen project, for example `ring-core`, add the following to your `:dependencies`:
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
93
d2b9783 @weavejester Release 1.0.0-RC5
weavejester authored
94 [ring/ring-core "1.0.0-RC5"]
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
95
9c6c621 @mmcgrana Re-introduce ring/ring artifact.
authored
96 To include all of them, add:
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
97
d2b9783 @weavejester Release 1.0.0-RC5
weavejester authored
98 [ring "1.0.0-RC5"]
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 ## Development
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
101
2e9f334 @mmcgrana Clarify that patch submission should flow through the Ring group.
authored
102 Ring is being actively developed; you can track its progress on the [GitHub page](http://github.com/mmcgrana/ring) page and on the [Google Group](http://groups.google.com/group/ring-clojure).
103
104 To submit a patch, please post your corresponding GitHub branch to the Ring Google Group. This allows your changes to be seen and discussed by all Ring developers. If you are attempting something substantial, consider posting to the Google Group first with your idea.
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
105
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
106 To run the Ring unit tests, first navigate to the appropriate project and then:
107
108 $ lein deps
f2f4229 @mmcgrana Doc and example tweaks.
authored
109 $ lein test
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 ## Thanks
112
113 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
114
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored
115 ## License
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
116
9149d47 @weavejester Release 0.3.8
weavejester authored
117 Copyright (c) 2009-2011 Mark McGranaghan and released under an MIT license.
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored
118
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
119 Clojure logo by Tom Hickey.
Something went wrong with that request. Please try again.