Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 115 lines (66 sloc) 4.174 kb
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
1 # Ring
2
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
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 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
7 ## Synopsis
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
8
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
9 A "Hello World" Ring handler:
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
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 Mark McGranaghan Doc and example tweaks.
authored
22 (defn wrap-upcase [app]
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
23 (fn [req]
24 (let [orig-resp (app req)]
25 (assoc orig-resp :body (.toUpperCase (:body orig-resp))))))
26
f2f4229 Mark McGranaghan Doc and example tweaks.
authored
27 (def upcase-app (wrap-upcase app))
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
28
29 (run-jetty upcase-app {:port 8080})
30
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
31 ## Quick Start
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
32
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
33 To see some working examples, first pull in Ring's dependencies using [Leiningen](http://github.com/technomancy/leiningen):
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
34
2c378d9 Mark McGranaghan Leiningen dependency management.
authored
35 $ lein deps
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
36
37 To see a live "Hello World" Ring app, run:
38
f2f4229 Mark McGranaghan Doc and example tweaks.
authored
39 $ clj example/hello_world.clj
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
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
2c378d9 Mark McGranaghan Leiningen dependency management.
authored
43 Note that your `clj` script needs to add the `src` directory and the jars in `lib` to your classpath.
44
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
45 To see a more sophisticated Ring app, run:
46
f2f4229 Mark McGranaghan Doc and example tweaks.
authored
47 $ clj example/wrapping.clj
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
48
49 * 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).
50 * 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.
51 * 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.
52
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
53 ## Available Libraries
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
54
55 ### ring-core
56
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
57 * `ring.middleware.file`: Middleware that serves static files out of a public directory.
58 * `ring.middleware.file-info`: Middleware that augments response headers with info about File responses.
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
59 * `ring.middleware.static`: Middleware that serves static files with specified prefixes out of a public directory.
60
61 ### ring-devel
62
63 * `ring.handler.dump`: Handler that dumps request maps as HTML responses for debugging.
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
64 * `ring.middleware.lint`: Linter for the Ring interface, ensures compliance with the Ring spec.
65 * `ring.middleware.reload`: Middleware to automatically reload selected libs before each requests, minimizing server restarts.
66 * `ring.middleware.stacktrace`: Middleware that catches exceptions and displays readable stacktraces for debugging.
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
67
68 ### ring-servlet
69
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
70 * `ring.util.servlet`: Utilities for interfacing with Java Servlets.
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
71
72 ### ring-jetty-adapter
73
74 * `ring.adapter.jetty`: Adapter for the Jetty webserver.
75
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
76 ### ring-httpcore-adapter
77
78 * `ring.adapter.httpcore`: Adapter for the Apache HttpCore webserver.
79
80 ## Leiningen Usage
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
81
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
82 To include one of the above libraries in your Leiningen project, for example `ring-core`, add the following to your `:dependences`:
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
83
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
84 [ring/ring-core "0.2.0-SNAPSHOT"]
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
85
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
86 or to depend on all of the available Ring libraries, add:
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
87
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
88 [ring/ring "0.2.0-SNAPSHOT"]
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
89
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
90 ## Development
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
91
f2f4229 Mark McGranaghan Doc and example tweaks.
authored
92 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 Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
93
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
94 To run the Ring unit tests, first navigate to the appropriate project and then:
95
96 $ lein deps
f2f4229 Mark McGranaghan Doc and example tweaks.
authored
97 $ lein test
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
98
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
99 ## Thanks
100
101 This project borrows heavily from Ruby's Rack and Python's WSGI; thanks to those communities for their work.
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
102
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
103 Thanks also to the following Ring contributors:
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
104
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
105 * James Reeves
106 * Christophe Grand
107 * Richard Newman
108 * Seth Buntin
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
109
f6dcce4 Mark McGranaghan Refine the README for new project structure, add thanks.
authored
110 ## License
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
111
f2f4229 Mark McGranaghan Doc and example tweaks.
authored
112 Copyright (c) 2009-2010 Mark McGranaghan and released under an MIT license.
c1b417e Mark McGranaghan Convert readme to markdown, add simple example code to readme.
authored
113
fd30ea0 Seth Buntin update README with new instructions; add subproject jar files to gitigno...
sethtrain authored
114 Clojure logo by Tom Hickey.
Something went wrong with that request. Please try again.