/ring forked from ring-clojure/ring

Permalink
ring/README.md
Newer
Older
Raw Normal view History
100644 120 lines (70 sloc) 4.53 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
7b8f6bc @weavejester Release 0.3.0-RC1.
weavejester authored Sep 9, 2010
94 [ring/ring-core "0.3.0-RC1"]
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
7b8f6bc @weavejester Release 0.3.0-RC1.
weavejester authored Sep 9, 2010
98 [ring "0.3.0-RC1"]
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
2e9f334 @mmcgrana Clarify that patch submission should flow through the Ring group.
authored Jul 18, 2010
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 Sep 7, 2009
105
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
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 Feb 23, 2010
109 $ lein test
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
110
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
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 giti…
sethtrain authored Feb 24, 2010
114
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
115 ## License
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
116
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
117 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
118
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
119 Clojure logo by Tom Hickey.