/ring forked from ring-clojure/ring

Permalink
ring/README.md
Newer
Older
Raw Normal view History
100644 120 lines (72 sloc) 4.72 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.
9149d47 @weavejester Release 0.3.8
weavejester authored Apr 23, 2011
61 * `ring.middleware.resource`: Serve static classpath resources.
8a352f9 @mmcgrana Fill out library descriptions.
authored Feb 24, 2010
62 * `ring.middleware.file-info`: Augment response headers with info about File responses.
67989da @weavejester Added new libraries to README
weavejester authored Mar 5, 2011
63 * `ring.middleware.content-type`: Augment response headers with a content-type based on the file extension.
8a352f9 @mmcgrana Fill out library descriptions.
authored Feb 24, 2010
64 * `ring.middleware.params`: Parse query and form params.
4bc4619 @mmcgrana Rename ring.util.multipart to multipart-params.
authored Feb 28, 2010
65 * `ring.middleware.multipart-params`: Parse multipart params.
4e630cc @weavejester Release 0.2.3.
weavejester authored Jun 16, 2010
66 * `ring.middleware.keyword-params`: Convert string param keys to keywords.
531fbf4 @weavejester Release 0.3.2.
weavejester authored Oct 11, 2010
67 * `ring.middleware.nested-params`: Convert a flat map of parameters into a nested map of parameters.
8a352f9 @mmcgrana Fill out library descriptions.
authored Feb 24, 2010
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 Jun 16, 2010
70 * `ring.middleware.flash`: Adds flash message support to sessions.
59b0a0e @mmcgrana README typo.
authored Feb 25, 2010
71 * `ring.util.response`: Generate Ring responses.
67989da @weavejester Added new libraries to README
weavejester authored Mar 5, 2011
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 giti…
sethtrain authored Feb 24, 2010
75 ### ring-devel
76
8a352f9 @mmcgrana Fill out library descriptions.
authored Feb 24, 2010
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 Oct 9, 2011
79 * `ring.middleware.reload`: Automatically reload modified namespaces before each request.
8a352f9 @mmcgrana Fill out library descriptions.
authored Feb 24, 2010
80 * `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
81
82 ### ring-servlet
83
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
84 * `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
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 Feb 24, 2010
90 ## Leiningen Usage
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
91
b5909c9 @weavejester Release 0.3.6.
weavejester authored Feb 16, 2011
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 giti…
sethtrain authored Feb 24, 2010
93
13c0999 @weavejester Release 1.0.1
weavejester authored Dec 18, 2011
94 [ring/ring-core "1.0.1"]
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
13c0999 @weavejester Release 1.0.1
weavejester authored Dec 18, 2011
98 [ring "1.0.1"]
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
9149d47 @weavejester Release 0.3.8
weavejester authored Apr 23, 2011
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 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.