Skip to content
Newer
Older
100644 146 lines (99 sloc) 5.03 KB
10f925f @fukamachi appended README.
authored
1 # Clack - Web Application Environment for Common Lisp
af0a542 @fukamachi first commit.
authored
2
10f925f @fukamachi appended README.
authored
3 Clack is a Web Application Environment for Common Lisp inspired by Python's WSGI and Ruby's Rack. Your awesome framework should base on this.
c076020 @fukamachi rewrote README.
authored
4
af0a542 @fukamachi first commit.
authored
5 ## Usage
6
8080e91 @fukamachi deleted middleware.
authored
7 (defpackage simple-app
9fb9fb1 @fukamachi rewrote README.
authored
8 (:use :cl :clack :clack.handler.hunchentoot))
1ffc108 @fukamachi wrote Usage to README.
authored
9
8080e91 @fukamachi deleted middleware.
authored
10 (in-package :simple-app)
1ffc108 @fukamachi wrote Usage to README.
authored
11
8080e91 @fukamachi deleted middleware.
authored
12 (defvar app
c3572be @fukamachi appended README.
authored
13 #'(lambda (req)
14 '(200 (:content-type "text/plain") ("Hello, Clack!"))))
1ffc108 @fukamachi wrote Usage to README.
authored
15
8080e91 @fukamachi deleted middleware.
authored
16 (run app)
1ffc108 @fukamachi wrote Usage to README.
authored
17
7585b07 @fukamachi renamed 'Slinky' -> 'Clack'.
authored
18 Now access [http://localhost:8080/](http://localhost:8080/) and Clack show you "Hello, Clack!".
1ffc108 @fukamachi wrote Usage to README.
authored
19
c3572be @fukamachi appended README.
authored
20 ## Application
21
22 Clack Application is a lambda. It takes exactly one argument, the "Request", and returns the "Response" as a list containing exactly three values.
23
24 (defvar app
25 #'(lambda (req)
26 '(200 (:content-type "text/plain") ("Hello, World"))))
27
28 ### The Request
29
30 The Request is a list containing at least the following keys and corresponding values.
31
32 * <code>:request-method</code> (Required, Keyword): The HTTP request method, must be one of <code>:GET</code>, <code>:HEAD</code>, <code>:OPTIONS</code>, <code>:PUT</code>, <code>:POST</code>, or <code>:DELETE</code>.
33 * <code>:script-name</code> (Required, String): The initial portion of the request URL's path, corresponding to the application. This may be an empty string if the application corresponds to the server's root URI. If this key is not empty, it must start with a forward slash (<code>/</code>).
34 * <code>:path-info</code> (Required, String): The remainder of the request URL's path. This may be an empty string if the request URL targets the application root and does no have a trailing slash.
35 * <code>:query-string</code> (Optional, String): The portion of the request URL that follows the <code>?</code>, if any. This key may be empty, but must always be present, even if empty.
36 * <code>:server-name</code> (Required, String): The resolved server name, or the server IP address.
37 * <code>:server-port</code> (Required, Integer): The port on which the request is being handled.
38 * <code>:request-uri</code> (Required, String): The request URI. Must start with "/".
39 * <code>:server-protocol</code> (Required, Keyword)
40 * <code>:http-server</code> (Required, Keyword): The name of Clack Handler, such as <code>:hunchentoot</code>.
41 * Other <code>:http-*</code> keys: These keys correspond to the client-supplied HTTP request headers. The presence or absence of these keys should correspond to the presence or absence of the appropriate HTTP header in the request.
42
43 ### Response
44
45 Applications must return a response as a list containing three values.
46
47 * Status (Required, Integer): An HTTP status code. This must be an integer greater than or equal to 100, and should be an HTTP status code as documented in RFC 2616.
48 * Headers (Required, Property List): An HTTP headers. This must be a property list of key/value pairs.
49 * Body (Optional, List or Pathname): The response body. This is either a list or a pathname. If it is a list of strings, Handler should output it with #\NewLine for each elements. The body can instead be a pathname for serving static files.
50
9fb9fb1 @fukamachi rewrote README.
authored
51 ## Handler
52
c3572be @fukamachi appended README.
authored
53 Clack Applications run via Clack Handlers, which are in turn responsible for implementing the HTTP protocol and abstracting the server.
54
55 Now Clack Applications works on Hunchentoot and Apache, by using following handler.
56
9fb9fb1 @fukamachi rewrote README.
authored
57 * clack.handler.hunchentoot
58 * clack.handler.apache
59
c3572be @fukamachi appended README.
authored
60 If you hope them to run on other server (such as tpd2), you can write a handler for it easily.
10f925f @fukamachi appended README.
authored
61
5c0cd38 @fukamachi appended README abount Middleware.
authored
62 ## Middleware
63
b678d00 @fukamachi appended README about Middleware.
authored
64 ### Use Middleware
65
a5b478f @fukamachi fixed styles of README.
authored
66 #### clack.middleware.static
b678d00 @fukamachi appended README about Middleware.
authored
67
68 (defpackage simple-app
9fb9fb1 @fukamachi rewrote README.
authored
69 (:use :cl
70 :clack
71 :clack.handler.hunchentoot
72 :clack.middleware.static))
b678d00 @fukamachi appended README about Middleware.
authored
73
74 (in-package :simple-app)
75
76 (defvar app
77 (lambda (req)
78 '(200 (:content-type "text/plain") ("Hello, Clack!"))))
79
80 (run
81 (builder
82 (<clack-middleware-static>
83 :urls '(#p"favicon.ico" #p"404.html")
84 :root #p"/public/")
85 app))
86
87 ### How to write Middleware?
8592927 @fukamachi fixed middleware example at README.
authored
88
89 (defpackage clack.middleware.example
e64a51e @fukamachi rewrote README's example about Middleware.
authored
90 (:use :cl :clack)
91 (:export :<simple-middleware>))
5c0cd38 @fukamachi appended README abount Middleware.
authored
92
8592927 @fukamachi fixed middleware example at README.
authored
93 (in-package :clack.middleware.example)
5c0cd38 @fukamachi appended README abount Middleware.
authored
94
95 (defclass <simple-middleware> (<middleware>) ())
a5b478f @fukamachi fixed styles of README.
authored
96 (defmethod call ((this <simple-middleware>) req)
e64a51e @fukamachi rewrote README's example about Middleware.
authored
97 `(200 (:content-type "text/html")
98 ,(cons "Hello, Clack Middleware!<br />"
a5b478f @fukamachi fixed styles of README.
authored
99 (nth 2 (call-next this req)))))
8592927 @fukamachi fixed middleware example at README.
authored
100
101 (defpackage simple-app
9fb9fb1 @fukamachi rewrote README.
authored
102 (:use :cl
103 :clack
104 :clack.handler.hunchentoot
105 :clack.middleware.example))
5c0cd38 @fukamachi appended README abount Middleware.
authored
106
8592927 @fukamachi fixed middleware example at README.
authored
107 (in-package :simple-app)
108
109 (defvar app
110 (lambda (req)
111 '(200 (:content-type "text/plain") ("Hello, Clack!"))))
5c0cd38 @fukamachi appended README abount Middleware.
authored
112
e64a51e @fukamachi rewrote README's example about Middleware.
authored
113 (run (builder <simple-middleware> app))
114
115 And you should get following response in time.
116
117 Hello, Clack Middleware!
118 Hello, Clack!
5c0cd38 @fukamachi appended README abount Middleware.
authored
119
10f925f @fukamachi appended README.
authored
120 ## Handler
121
750775b @fukamachi refactored.
authored
122 ## Response
123
124 (status headers body)
125
126 * status (integer)
127 * headers (plist)
128 * body (cons or pathname)
129
c076020 @fukamachi rewrote README.
authored
130 ## Dependency
131
10f925f @fukamachi appended README.
authored
132 * CL-PPCRE
308f031 @fukamachi added specification about request to README.
authored
133 * CL-FAD
134 * local-time
10f925f @fukamachi appended README.
authored
135 * Alexandria
136 * SPLIT-SEQUENCE
308f031 @fukamachi added specification about request to README.
authored
137 * Anaphora
138 * metabang-bind
139 * Hunchentoot
140 * modlisp
c076020 @fukamachi rewrote README.
authored
141
af0a542 @fukamachi first commit.
authored
142 ## License
143
144 Copyright (c) 2011 Eitarow Fukamachi
145 Licensed under the LLGPL License.
Something went wrong with that request. Please try again.