/ring forked from ring-clojure/ring

Permalink
ring/README.md
Newer
Older
Raw Normal view History
100644 117 lines (68 sloc) 4.22 KB
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
1 # Ring
2
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
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 Feb 24, 2010
7 ## Synopsis
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
8
8ca2df9 @mmcgrana Simple running of Readme examples.
authored Mar 17, 2010
9 "Hello World" in Ring:
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
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 Feb 23, 2010
22 (defn wrap-upcase [app]
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
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 Feb 23, 2010
27 (def upcase-app (wrap-upcase app))
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
28
29 (run-jetty upcase-app {:port 8080})
30
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
31 ## Quick Start
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
32
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
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 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
8ca2df9 @mmcgrana Simple running of Readme examples.
authored Mar 17, 2010
39 $ java -cp "lib/*" clojure.main 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
43 To see a more sophisticated Ring app, run:
44
8ca2df9 @mmcgrana Simple running of Readme examples.
authored Mar 17, 2010
45 $ java -cp "lib/*" clojure.main example/wrapping.clj
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
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 Mar 17, 2010
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 Feb 24, 2010
56 ## Available Libraries
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
57
58 ### ring-core
59
8a352f9 @mmcgrana Fill out library descriptions.
authored Feb 24, 2010
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 @mmcgrana Rename ring.util.multipart to multipart-params.
authored Feb 28, 2010
64 * `ring.middleware.multipart-params`: Parse multipart params.
a977eba @mmcgrana Note r.m.keyword-params in README.
authored Mar 3, 2010
65 * 'ring.middleware.keyword-params`: Convert string param keys to keywords.
8a352f9 @mmcgrana Fill out library descriptions.
authored Feb 24, 2010
66 * `ring.middleware.cookies`: Manage browser cookies.
67 * `ring.middleware.session`: Manage user sessions. Memory and cookie session stores are available by default.
59b0a0e @mmcgrana README typo.
authored Feb 25, 2010
68 * `ring.util.response`: Generate Ring responses.
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
69
70 ### ring-devel
71
8a352f9 @mmcgrana Fill out library descriptions.
authored Feb 24, 2010
72 * `ring.handler.dump`: Dumps request maps as HTML responses for debugging.
73 * `ring.middleware.lint`: Lint requests and responses to ensure compliance with the Ring spec.
74 * `ring.middleware.reload`: Automatically reload selected libs before each request.
75 * `ring.middleware.stacktrace`: Catch exceptions and displays readable stacktraces for debugging.
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
76
77 ### ring-servlet
78
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
79 * `ring.util.servlet`: Utilities for interfacing with Java Servlets.
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
80
81 ### ring-jetty-adapter
82
83 * `ring.adapter.jetty`: Adapter for the Jetty webserver.
84
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
85 ### ring-httpcore-adapter
86
87 * `ring.adapter.httpcore`: Adapter for the Apache HttpCore webserver.
88
89 ## Leiningen Usage
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
90
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
91 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 giti…
sethtrain authored Feb 24, 2010
92
998bd11 @mmcgrana Release 0.2.0.
authored Mar 28, 2010
93 [ring/ring-core "0.2.0"]
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
94
9c6c621 @mmcgrana Re-introduce ring/ring artifact.
authored Mar 17, 2010
95 To include all of them, add:
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
96
998bd11 @mmcgrana Release 0.2.0.
authored Mar 28, 2010
97 [ring/ring "0.2.0"]
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
98
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
99 ## Development
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
100
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
101 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
102
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
103 To run the Ring unit tests, first navigate to the appropriate project and then:
104
105 $ lein deps
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
106 $ lein test
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
107
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
108 ## Thanks
109
110 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 giti…
sethtrain authored Feb 24, 2010
111
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
112 ## License
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
113
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
114 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
115
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
116 Clojure logo by Tom Hickey.