mmcgrana/ring

c1b417e Convert readme to markdown, add simple example code to readme. mmcgrana authored Sep 7, 2009
	1	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.
	2
	3	The `SPEC` file at the root of this distribution for provides a complete description of the Ring interface.
	4
	5	Examples
	6	--------
	7
	8	A Ring handler:
	9
	10	(use 'ring.adapter.jetty)
	11
	12	(defn app [req]
	13	{:status 200
	14	:headers {"Content-Type" "text/html"}
	15	:body "Hello World from Ring"})
	16
	17	(run-jetty app {:port 8080})
	18
	19	Adding simple middleware:
	20
	21	(defn with-upcase [app]
	22	(fn [req]
	23	(let [orig-resp (app req)]
	24	(assoc orig-resp :body (.toUpperCase (:body orig-resp))))))
	25
	26	(def upcase-app (with-upcase app))
	27
	28	(run-jetty upcase-app {:port 8080})
	29
	30	Quick Start
	31	-----------
	32
	33	First clone the Ring source and download Ring's dependencies:
	34
	35	git clone git://github.com/mmcgrana/ring.git
	36	cd ring
	37	ant deps
	38
	39	To see a live "Hello World" Ring app, run:
	40
	41	java -Djava.ext.dirs=deps clojure.main src/ring/example/hello_world.clj
	42
	43	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.
	44
	45	To see a more sophisticated Ring app, run:
	46
	47	java -Djava.ext.dirs=deps clojure.main src/ring/example/wrapping.clj
	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
	53	Included Libs
	54	-------------
	55
	56	* `ring.adapter.jetty`: Adapter for the Jetty webserver.
	57	* `ring.adapter.httpcore`: Adapter for the Apache HttpCore webserver.
	58	* `ring.middleware.file`: Middleware that serves static files out of a public directory.
	59	* `ring.middleware.file-info`: Middleware that augments response headers with info about File responses.
	60	* `ring.middleware.lint`: Linter for the Ring interface, ensures compliance with the Ring spec.
	61	* `ring.middleware.reload`: Middleware to automatically reload selected libs before each requests, minimizing server restarts.
	62	* `ring.middleware.stacktrace`: Middleware that catches exceptions and displays readable stacktraces for debugging.
	63	* `ring.middleware.static`: Middleware that serves static files with specified prefixes out of a public directory.
	64	* `ring.handler.dump`: Handler that dumps request maps as HTML responses for debugging.
	65	* `ring.util.servlet`: Utilities for interfacing with Java Servlets.
	66	* `ring.example.*`: Various example Ring apps.
	67
	68	Development
	69	-----------
	70
	71	Ring is being actively developed; you can track its progress and contribute at the project's [GitHub](http://github.com/mmcgrana/ring) page.
	72
	73	To run all the Ring unit tests:
	74
	75	java -Djava.ext.dirs=deps clojure.main test/ring/run.clj
	76
	77	You can learn more about Ring's dependencies at the following sites:
	78
	79	* `clojure.jar`, `clojure-contrib.jar`: [clojure.org](http://clojure.org)
	80	* `jetty-6.1.14.jar`, `jetty-util-6.1.14.jar`, `servlet-api-2.5-6.1.14.jar`: [mortbay.org/jetty](http://www.mortbay.org/jetty)
	81	* `httpcore-4.0.jar`, `httpcore-nio-4.0.jar`: [hc.apache.org](http://hc.apache.org/httpcomponents-core/index.html)
	82	* `commons-io-1.4.jar`: [commons.apache.org/io](http://commons.apache.org/io/)
	83	* `clj-html.jar`, `clj-html-helpers.jar`, `clj-stacktrace.jar`, `clj-unit`: [github.com/mmcgrana](http://github.com/mmcgrana)
	84
	85	Thanks
	86	------
	87
	88	This project borrows heavily from Ruby's Rack and Python's WSGI, and I thank the communities developing and supporting those projects.
	89
	90	License
	91	-------
	92
	93	Copyright (c) 2009 Mark McGranaghan and released under an MIT license.
	94
	95	Clojure logo by Tom Hickey.

1

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.

2

3

The `SPEC` file at the root of this distribution for provides a complete description of the Ring interface.

4

5

Examples

6

--------

7

8

A Ring handler:

9

10

(use 'ring.adapter.jetty)

11

12

(defn app [req]

13

{:status 200

14

:headers {"Content-Type" "text/html"}

15

:body "Hello World from Ring"})

16

17

(run-jetty app {:port 8080})

18

19

Adding simple middleware:

20

21

(defn with-upcase [app]

22

(fn [req]

23

(let [orig-resp (app req)]

24

(assoc orig-resp :body (.toUpperCase (:body orig-resp))))))

25

26

(def upcase-app (with-upcase app))

27

28

(run-jetty upcase-app {:port 8080})

29

30

Quick Start

31

-----------

32

33

First clone the Ring source and download Ring's dependencies:

34

35

git clone git://github.com/mmcgrana/ring.git

36

cd ring

37

ant deps

38

39

To see a live "Hello World" Ring app, run:

40

41

java -Djava.ext.dirs=deps clojure.main src/ring/example/hello_world.clj

42

43

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.

44

45

To see a more sophisticated Ring app, run:

46

47

java -Djava.ext.dirs=deps clojure.main src/ring/example/wrapping.clj

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

53

Included Libs

54

-------------

55

56

* `ring.adapter.jetty`: Adapter for the Jetty webserver.

57

* `ring.adapter.httpcore`: Adapter for the Apache HttpCore webserver.

58

* `ring.middleware.file`: Middleware that serves static files out of a public directory.

59

* `ring.middleware.file-info`: Middleware that augments response headers with info about File responses.

60

* `ring.middleware.lint`: Linter for the Ring interface, ensures compliance with the Ring spec.

61

* `ring.middleware.reload`: Middleware to automatically reload selected libs before each requests, minimizing server restarts.

62

* `ring.middleware.stacktrace`: Middleware that catches exceptions and displays readable stacktraces for debugging.

63

* `ring.middleware.static`: Middleware that serves static files with specified prefixes out of a public directory.

64

* `ring.handler.dump`: Handler that dumps request maps as HTML responses for debugging.

65

* `ring.util.servlet`: Utilities for interfacing with Java Servlets.

66

* `ring.example.*`: Various example Ring apps.

67

68

Development

69

-----------

70

71

Ring is being actively developed; you can track its progress and contribute at the project's [GitHub](http://github.com/mmcgrana/ring) page.

72

73

To run all the Ring unit tests:

74

75

java -Djava.ext.dirs=deps clojure.main test/ring/run.clj

76

77

You can learn more about Ring's dependencies at the following sites:

78

79

* `clojure.jar`, `clojure-contrib.jar`: [clojure.org](http://clojure.org)

80

* `jetty-6.1.14.jar`, `jetty-util-6.1.14.jar`, `servlet-api-2.5-6.1.14.jar`: [mortbay.org/jetty](http://www.mortbay.org/jetty)

81

* `httpcore-4.0.jar`, `httpcore-nio-4.0.jar`: [hc.apache.org](http://hc.apache.org/httpcomponents-core/index.html)

82

* `commons-io-1.4.jar`: [commons.apache.org/io](http://commons.apache.org/io/)

83

* `clj-html.jar`, `clj-html-helpers.jar`, `clj-stacktrace.jar`, `clj-unit`: [github.com/mmcgrana](http://github.com/mmcgrana)

84

85

Thanks

86

------

87

88

This project borrows heavily from Ruby's Rack and Python's WSGI, and I thank the communities developing and supporting those projects.

89

90

License

91

-------

92

93

94

95

Clojure logo by Tom Hickey.

mmcgrana/ring forked from ring-clojure/ring