forked from ring-clojure/ring
-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
A lot of the information in the README can be put in the wiki instead. Now the README contains a brief overview, installation instructions, and a link to the API docs and wiki.
- Loading branch information
1 parent
b25e0e9
commit e965929
Showing
1 changed file
with
23 additions
and
96 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,119 +1,46 @@ | ||
| # Ring | ||
|
|
||
| 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. | ||
| 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. | ||
|
|
||
| The `SPEC` file at the root of this distribution for provides a complete description of the Ring interface. | ||
| The [SPEC][1] file at the root of this distribution for provides a | ||
| complete description of the Ring interface. | ||
|
|
||
| ## Synopsis | ||
| [1]: https://github.com/mmcgrana/ring/blob/master/SPEC | ||
|
|
||
| "Hello World" in Ring: | ||
| ## Libraries | ||
|
|
||
| (use 'ring.adapter.jetty) | ||
| * ring-core - essential functions for handling parameters, cookies and more | ||
| * ring-devel - functions for developing and debugging Ring applications | ||
| * ring-servlet - construct Java servlets from Ring handlers | ||
| * ring-jetty-adapter - a Ring adapter that uses the Jetty webserver | ||
|
|
||
| (defn app [req] | ||
| {:status 200 | ||
| :headers {"Content-Type" "text/html"} | ||
| :body "Hello World from Ring"}) | ||
| ## Installation | ||
|
|
||
| (run-jetty app {:port 8080}) | ||
|
|
||
| Adding simple middleware: | ||
|
|
||
| (defn wrap-upcase [app] | ||
| (fn [req] | ||
| (let [orig-resp (app req)] | ||
| (assoc orig-resp :body (.toUpperCase (:body orig-resp)))))) | ||
|
|
||
| (def upcase-app (wrap-upcase app)) | ||
|
|
||
| (run-jetty upcase-app {:port 8080}) | ||
|
|
||
| ## Quick Start | ||
|
|
||
| To see some working examples, first pull in Ring's dependencies using [Leiningen](http://github.com/technomancy/leiningen): | ||
|
|
||
| $ lein deps | ||
|
|
||
| To see a live "Hello World" Ring app, run: | ||
|
|
||
| $ java -cp "lib/*" clojure.main example/hello_world.clj | ||
|
|
||
| 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. | ||
|
|
||
| To see a more sophisticated Ring app, run: | ||
|
|
||
| $ java -cp "lib/*" clojure.main example/wrapping.clj | ||
|
|
||
| * 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). | ||
| * 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. | ||
| * 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. | ||
|
|
||
|
|
||
| ## Documentation | ||
|
|
||
| * [Ring namespace and function docs](http://mmcgrana.github.com/ring/) | ||
|
|
||
| ## Available Libraries | ||
|
|
||
| ### ring-core | ||
|
|
||
| * `ring.middleware.file`: Serve static files out of a public directory. | ||
| * `ring.middleware.resource`: Serve static classpath resources. | ||
| * `ring.middleware.file-info`: Augment response headers with info about File responses. | ||
| * `ring.middleware.content-type`: Augment response headers with a content-type based on the file extension. | ||
| * `ring.middleware.params`: Parse query and form params. | ||
| * `ring.middleware.multipart-params`: Parse multipart params. | ||
| * `ring.middleware.keyword-params`: Convert string param keys to keywords. | ||
| * `ring.middleware.nested-params`: Convert a flat map of parameters into a nested map of parameters. | ||
| * `ring.middleware.cookies`: Manage browser cookies. | ||
| * `ring.middleware.session`: Manage user sessions. Memory and cookie session stores are available by default. | ||
| * `ring.middleware.flash`: Adds flash message support to sessions. | ||
| * `ring.util.response`: Generate Ring responses. | ||
| * `ring.util.codec`: Encode and decode string data. | ||
| * `ring.util.mime-type`: Guess the mime-type from a file extension. | ||
|
|
||
| ### ring-devel | ||
|
|
||
| * `ring.handler.dump`: Dumps request maps as HTML responses for debugging. | ||
| * `ring.middleware.lint`: Lint requests and responses to ensure compliance with the Ring spec. | ||
| * `ring.middleware.reload`: Automatically reload modified namespaces before each request. | ||
| * `ring.middleware.stacktrace`: Catch exceptions and displays readable stacktraces for debugging. | ||
|
|
||
| ### ring-servlet | ||
|
|
||
| * `ring.util.servlet`: Utilities for interfacing with Java Servlets. | ||
|
|
||
| ### ring-jetty-adapter | ||
|
|
||
| * `ring.adapter.jetty`: Adapter for the Jetty webserver. | ||
|
|
||
| ## Leiningen Usage | ||
|
|
||
| To include one of the above libraries in your Leiningen project, for example `ring-core`, add the following to your `:dependencies`: | ||
| To include one of the above libraries, for example `ring-core`, add | ||
| the following to your `:dependencies`: | ||
|
|
||
| [ring/ring-core "1.0.2"] | ||
|
|
||
| To include all of them, add: | ||
| To include all of them: | ||
|
|
||
| [ring "1.0.2"] | ||
|
|
||
| ## Development | ||
|
|
||
| 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). | ||
|
|
||
| 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. | ||
|
|
||
| To run the Ring unit tests, first navigate to the appropriate project and then: | ||
| ## Documentation | ||
|
|
||
| $ lein deps | ||
| $ lein test | ||
| * [Wiki](https://github.com/mmcgrana/ring/wiki) | ||
| * [API Docs](http://mmcgrana.github.com/ring) | ||
|
|
||
| ## Thanks | ||
|
|
||
| This project borrows heavily from Ruby's Rack and Python's WSGI; thanks to those communities for their work. | ||
| This project borrows heavily from Ruby's Rack and Python's WSGI; | ||
| thanks to those communities for their work. | ||
|
|
||
| ## License | ||
|
|
||
| Copyright (c) 2009-2011 Mark McGranaghan and released under an MIT license. | ||
| Copyright (c) 2009-2012 Mark McGranaghan and released under an MIT license. | ||
|
|
||
| Clojure logo by Tom Hickey. |