Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 121 lines (71 sloc) 4.727 kb
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
1 # Ring
2
c1b417e Mark McGranaghan 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 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
7 ## Synopsis
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
8
8ca2df9 Mark McGranaghan Simple running of Readme examples.
authored
9 "Hello World" in Ring:
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
10
11 (use 'ring.adapter.jetty)
4e630cc James Reeves Release 0.2.3.
weavejester authored
12
c1b417e Mark McGranaghan 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 James Reeves Release 0.2.3.
weavejester authored
17
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
18 (run-jetty app {:port 8080})
19
20 Adding simple middleware:
21
f2f4229 Mark McGranaghan Doc and example tweaks.
authored
22 (defn wrap-upcase [app]
c1b417e Mark McGranaghan 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 James Reeves Release 0.2.3.
weavejester authored
26
f2f4229 Mark McGranaghan Doc and example tweaks.
authored
27 (def upcase-app (wrap-upcase app))
4e630cc James Reeves Release 0.2.3.
weavejester authored
28
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
29 (run-jetty upcase-app {:port 8080})
30
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
31 ## Quick Start
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
32
f6dcce4 Mark McGranaghan 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 Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
34
2c378d9 Mark McGranaghan Leiningen dependency management.
authored
35 $ lein deps
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
36
37 To see a live "Hello World" Ring app, run:
38
8ca2df9 Mark McGranaghan Simple running of Readme examples.
authored
39 $ java -cp "lib/*" clojure.main example/hello_world.clj
c1b417e Mark McGranaghan 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 Mark McGranaghan Simple running of Readme examples.
authored
45 $ java -cp "lib/*" clojure.main example/wrapping.clj
c1b417e Mark McGranaghan 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 Mark McGranaghan 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 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
56 ## Available Libraries
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
57
58 ### ring-core
59
8a352f9 Mark McGranaghan Fill out library descriptions.
authored
60 * `ring.middleware.file`: Serve static files out of a public directory.
61 * `ring.middleware.static`: Serve static files with specified prefixes out of a public directory.
62 * `ring.middleware.file-info`: Augment response headers with info about File responses.
63 * `ring.middleware.params`: Parse query and form params.
4bc4619 Mark McGranaghan Rename ring.util.multipart to multipart-params.
authored
64 * `ring.middleware.multipart-params`: Parse multipart params.
4e630cc James Reeves Release 0.2.3.
weavejester authored
65 * `ring.middleware.keyword-params`: Convert string param keys to keywords.
531fbf4 James Reeves Release 0.3.2.
weavejester authored
66 * `ring.middleware.nested-params`: Convert a flat map of parameters into a nested map of parameters.
8a352f9 Mark McGranaghan Fill out library descriptions.
authored
67 * `ring.middleware.cookies`: Manage browser cookies.
68 * `ring.middleware.session`: Manage user sessions. Memory and cookie session stores are available by default.
4e630cc James Reeves Release 0.2.3.
weavejester authored
69 * `ring.middleware.flash`: Adds flash message support to sessions.
59b0a0e Mark McGranaghan README typo.
authored
70 * `ring.util.response`: Generate Ring responses.
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
71
72 ### ring-devel
73
8a352f9 Mark McGranaghan Fill out library descriptions.
authored
74 * `ring.handler.dump`: Dumps request maps as HTML responses for debugging.
75 * `ring.middleware.lint`: Lint requests and responses to ensure compliance with the Ring spec.
76 * `ring.middleware.reload`: Automatically reload selected libs before each request.
77 * `ring.middleware.stacktrace`: Catch exceptions and displays readable stacktraces for debugging.
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
78
79 ### ring-servlet
80
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
81 * `ring.util.servlet`: Utilities for interfacing with Java Servlets.
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
82
83 ### ring-jetty-adapter
84
85 * `ring.adapter.jetty`: Adapter for the Jetty webserver.
86
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
87 ### ring-httpcore-adapter
88
89 * `ring.adapter.httpcore`: Adapter for the Apache HttpCore webserver.
90
91 ## Leiningen Usage
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
92
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
93 To include one of the above libraries in your Leiningen project, for example `ring-core`, add the following to your `:dependences`:
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
94
00cae9b James Reeves Release 0.3.4.
weavejester authored
95 [ring/ring-core "0.3.4"]
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
96
9c6c621 Mark McGranaghan Re-introduce ring/ring artifact.
authored
97 To include all of them, add:
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
98
00cae9b James Reeves Release 0.3.4.
weavejester authored
99 [ring "0.3.4"]
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
100
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
101 ## Development
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
102
2e9f334 Mark McGranaghan Clarify that patch submission should flow through the Ring group.
authored
103 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).
104
105 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 Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
106
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
107 To run the Ring unit tests, first navigate to the appropriate project and then:
108
109 $ lein deps
f2f4229 Mark McGranaghan Doc and example tweaks.
authored
110 $ lein test
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
111
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
112 ## Thanks
113
114 This project borrows heavily from Ruby's Rack and Python's WSGI; thanks to those communities for their work.
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
115
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
116 ## License
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
117
f2f4229 Mark McGranaghan Doc and example tweaks.
authored
118 Copyright (c) 2009-2010 Mark McGranaghan and released under an MIT license.
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
119
fd30ea0 Seth Buntin 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.