/ring forked from ring-clojure/ring

Permalink
ring/README.md
Newer
Older
Raw Normal view History
100644 121 lines (73 sloc) 4.81 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.static`: Serve static files with specified prefixes out of a public directory.
63 * `ring.middleware.file-info`: Augment response headers with info about File responses.
67989da @weavejester Added new libraries to README
weavejester authored Mar 5, 2011
64 * `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
65 * `ring.middleware.params`: Parse query and form params.
4bc4619 @mmcgrana Rename ring.util.multipart to multipart-params.
authored Feb 28, 2010
66 * `ring.middleware.multipart-params`: Parse multipart params.
4e630cc @weavejester Release 0.2.3.
weavejester authored Jun 16, 2010
67 * `ring.middleware.keyword-params`: Convert string param keys to keywords.
531fbf4 @weavejester Release 0.3.2.
weavejester authored Oct 11, 2010
68 * `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
69 * `ring.middleware.cookies`: Manage browser cookies.
70 * `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
71 * `ring.middleware.flash`: Adds flash message support to sessions.
59b0a0e @mmcgrana README typo.
authored Feb 25, 2010
72 * `ring.util.response`: Generate Ring responses.
67989da @weavejester Added new libraries to README
weavejester authored Mar 5, 2011
73 * `ring.util.codec`: Encode and decode string data.
74 * `ring.util.mime-type`: Guess the mime-type from a file extension.
75
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
76 ### ring-devel
77
8a352f9 @mmcgrana Fill out library descriptions.
authored Feb 24, 2010
78 * `ring.handler.dump`: Dumps request maps as HTML responses for debugging.
79 * `ring.middleware.lint`: Lint requests and responses to ensure compliance with the Ring spec.
80 * `ring.middleware.reload`: Automatically reload selected libs before each request.
81 * `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
82
83 ### ring-servlet
84
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
85 * `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
86
87 ### ring-jetty-adapter
88
89 * `ring.adapter.jetty`: Adapter for the Jetty webserver.
90
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
91 ## Leiningen Usage
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
92
b5909c9 @weavejester Release 0.3.6.
weavejester authored Feb 16, 2011
93 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
94
9149d47 @weavejester Release 0.3.8
weavejester authored Apr 23, 2011
95 [ring/ring-core "0.3.8"]
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
96
9c6c621 @mmcgrana Re-introduce ring/ring artifact.
authored Mar 17, 2010
97 To include all of them, add:
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
98
9149d47 @weavejester Release 0.3.8
weavejester authored Apr 23, 2011
99 [ring "0.3.8"]
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
100
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
101 ## Development
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
102
2e9f334 @mmcgrana Clarify that patch submission should flow through the Ring group.
authored Jul 18, 2010
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 @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
106
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
107 To run the Ring unit tests, first navigate to the appropriate project and then:
108
109 $ lein deps
f2f4229 @mmcgrana Doc and example tweaks.
authored Feb 23, 2010
110 $ lein test
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
111
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
112 ## Thanks
113
114 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
115
f6dcce4 @mmcgrana Refine the README for new project structure, add thanks.
authored Feb 24, 2010
116 ## License
c1b417e @mmcgrana Convert readme to markdown, add simple example code to readme.
authored Sep 7, 2009
117
9149d47 @weavejester Release 0.3.8
weavejester authored Apr 23, 2011
118 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
119
fd30ea0 @sethtrain update README with new instructions; add subproject jar files to giti…
sethtrain authored Feb 24, 2010
120 Clojure logo by Tom Hickey.