/ring forked from ring-clojure/ring

Permalink
ring/README.md
Newer
Older
Raw Normal view History
100644 118 lines (69 sloc) 4.27 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)
4e630cc @weavejester Release 0.2.3.
weavejester authored Jun 16, 2010
12
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
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 Jun 16, 2010
17
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
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))))))
4e630cc @weavejester Release 0.2.3.
weavejester authored Jun 16, 2010
26
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
27 (def upcase-app (wrap-upcase app))
4e630cc @weavejester Release 0.2.3.
weavejester authored Jun 16, 2010
28
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
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.
4e630cc @weavejester Release 0.2.3.
weavejester authored Jun 16, 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.
4e630cc @weavejester Release 0.2.3.
weavejester authored Jun 16, 2010
68 * `ring.middleware.flash`: Adds flash message support to sessions.
59b0a0e @mmcgrana README typo.
authored Feb 25, 2010
69 * `ring.util.response`: Generate Ring responses.
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
70
71 ### ring-devel
72
8a352f9 @mmcgrana Fill out library descriptions.
authored Feb 24, 2010
73 * `ring.handler.dump`: Dumps request maps as HTML responses for debugging.
74 * `ring.middleware.lint`: Lint requests and responses to ensure compliance with the Ring spec.
75 * `ring.middleware.reload`: Automatically reload selected libs before each request.
76 * `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
77
78 ### ring-servlet
79
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
80 * `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
81
82 ### ring-jetty-adapter
83
84 * `ring.adapter.jetty`: Adapter for the Jetty webserver.
85
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
86 ### ring-httpcore-adapter
87
88 * `ring.adapter.httpcore`: Adapter for the Apache HttpCore webserver.
89
90 ## Leiningen Usage
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
91
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
92 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
93
4e630cc @weavejester Release 0.2.3.
weavejester authored Jun 16, 2010
94 [ring/ring-core "0.2.3"]
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
95
9c6c621 @mmcgrana Re-introduce ring/ring artifact.
authored Mar 17, 2010
96 To include all of them, add:
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
97
4e630cc @weavejester Release 0.2.3.
weavejester authored Jun 16, 2010
98 [ring/ring "0.2.3"]
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
99
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
100 ## Development
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
101
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
102 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
103
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
104 To run the Ring unit tests, first navigate to the appropriate project and then:
105
106 $ lein deps
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
107 $ lein test
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
108
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
109 ## Thanks
110
111 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
112
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
113 ## License
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
114
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
115 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
116
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
117 Clojure logo by Tom Hickey.