Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 859 lines (507 sloc) 21.31 kb
a6c46eb @nicferrier updated the README a little
authored
1 = Elnode =
b040865 README
nferrier authored
2
a6c46eb @nicferrier updated the README a little
authored
3 An attempt to make an EmacsLISP clone of node.js.
b040865 README
nferrier authored
4
5
156a7f8 @nicferrier why would you use Elnode?
authored
6 == Rationale ==
7
8 Elnode should be used for making small, personal web services or for
9 developing a first draft of a web service you may later do in Clojure
10 or Node.js or some other web framework.
11
12 Emacs is a very good LISP programming environment as well as a great
13 editor. Now that Emacs 24 has lexical scope EmacsLISP is a very
14 powerful language. A webserver framework inside such a powerful LISP
15 environment therefore makes sense.
16
17
a6c46eb @nicferrier updated the README a little
authored
18 == Installation ==
b040865 README
nferrier authored
19
c238791 @nicferrier fix syntax
authored
20 Elnode is now packaged in [[http://marmalade-repo.org/packages/elnode|marmalade]].
336155f updates to the README.
nferrier authored
21
a6c46eb @nicferrier updated the README a little
authored
22 For dealing with package repositories check out the
74302c6 @nicferrier another syntax fix
authored
23 [[http://www.emacswiki.org/emacs/ELPA|Emacs Wiki]] but the short version
a6c46eb @nicferrier updated the README a little
authored
24 is to add the following to your {{{.emacs}}} or your
25 {{{.emacs.d/init.el}}}:
e9c6d09 @nicferrier brief installation instructions
authored
26
a6c46eb @nicferrier updated the README a little
authored
27 {{{
28 (add-to-list
29 'package-archives
30 '("marmalade" . "http://marmalade-repo.org/packages/"))
31 }}}
e9c6d09 @nicferrier brief installation instructions
authored
32
e785598 @nicferrier forgot how to *actually* install Elnode from marmalade
authored
33 And then do:
34
35 {{{
36 M-x list-packages
37 }}}
38
39 find Elnode in the list and press {{{i}}} or {{{ENTER}}} to install it.
40
a6c46eb @nicferrier updated the README a little
authored
41 If you don't want to use packages you can just install {{{elnode.el}}}
42 on your {{{load-path}}} somewhere and:
e9c6d09 @nicferrier brief installation instructions
authored
43
44 {{{
a6c46eb @nicferrier updated the README a little
authored
45 (require 'elnode)
e9c6d09 @nicferrier brief installation instructions
authored
46 }}}
47
a6c46eb @nicferrier updated the README a little
authored
48 == Out of the box ==
49
50 When Elnode initializes it automatically starts a webserver.
e9c6d09 @nicferrier brief installation instructions
authored
51
52 If you:
53
54 {{{
55 M-x customize-group
56 elnode
57 }}}
58
59 you can alter a number of variables pertaining to the default configuration.
60
61 You can also just ignore it and write your own servers.
62
63
336155f updates to the README.
nferrier authored
64 == How does it work? ==
65
88e6d81 @nicferrier small change
authored
66 You can define a handler function:
336155f updates to the README.
nferrier authored
67
68 {{{
69 (defun nicferrier-handler (httpcon)
70 "Demonstration function"
71 (elnode-http-start httpcon "200" '("Content-type" . "text/html"))
72 (elnode-http-return httpcon "<html><b>HELLO!</b></html>")
73 )
74 }}}
75
76 And then start the server:
77
78 {{{
95709bf @nicferrier changes from maacl
authored
79 (elnode-start 'nicferrier-handler 8010 "localhost")
336155f updates to the README.
nferrier authored
80 }}}
81
82 You can also start the server interactively... you still have to pass
69573eb about start and stop
nferrier authored
83 it a handler function and a port.
84
85 === Stopping the server ===
86
87 If you can remember the port you started your server on then you'll be
88 able to stop it, like:
89
90 {{{
939d57a @nicferrier fixing the elnode-stop
authored
91 (elnode-stop 8010)
69573eb about start and stop
nferrier authored
92 }}}
93
a6c46eb @nicferrier updated the README a little
authored
94 You can also stop interactively:
95
96 {{{
97 M-x elnode-stop
98 }}}
99
100
336155f updates to the README.
nferrier authored
101
9f894a5 doc changes, auto-generated in part.
nferrier authored
102 == API ==
6748de0 Updated README with info about HTTP API.
nferrier authored
103
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
104 === elnode-cached httpcon ===
105
106 [[elnode-docroot-for]] calls this when the resources was cached.
107
108 By default it just calls [[elnode-send-status]] with 304.
109
110
111 === elnode-cached-p httpcon target-file ===
112
113 Is the specified //target-file// older than the //httpcon//?
114
115
12e340b @nicferrier more wikidoc fixes
authored
116 === elnode-child-process httpcon program &rest args ===
1af9303 improve the README and make a multi-dispatcher
nferrier authored
117
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
118 Run the specified //program// asynchronously sending output to //httpcon//.
6748de0 Updated README with info about HTTP API.
nferrier authored
119
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
120 //program// is the path to the program to run, to be resolved by
121 [[start-process]] in the usual way.
122
123 //args// is a list of arguments to pass to the program.
6748de0 Updated README with info about HTTP API.
nferrier authored
124
9f894a5 doc changes, auto-generated in part.
nferrier authored
125 It is NOT POSSIBLE to run more than one process at a time
126 directed at the same http connection.
1af9303 improve the README and make a multi-dispatcher
nferrier authored
127
128
12e340b @nicferrier more wikidoc fixes
authored
129 === elnode-defer-now handler ===
5b6f31a @nicferrier updated the API doc in the README
authored
130
131 The function you call to defer processing of the current socket.
132
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
133 Pass in the current //handler//.
5b6f31a @nicferrier updated the API doc in the README
authored
134
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
135 FIXME: We could capture the current handler somehow? I think the
5b6f31a @nicferrier updated the API doc in the README
authored
136 point is that whatever signals elnode-defer should be getting
137 control back when the deferred is re-processed.
138
139
12e340b @nicferrier more wikidoc fixes
authored
140 === elnode-defer-or-do guard &rest body ===
5b6f31a @nicferrier updated the API doc in the README
authored
141
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
142 Test //guard// and defer if it succeeds and //body// if it doesn't.
143
144 [[httpcon]] is captured in this macro which means the macro can
145 only be expanded where there is an inscope [[httpcon]].
146
147
148 === elnode-deferred-queue arg ===
149
150 Message the length of the deferred queue.
151
152
153 === elnode-deferred-queue-stop ===
154
155 Stop any running deferred queue processor.
5b6f31a @nicferrier updated the API doc in the README
authored
156
157
12e340b @nicferrier more wikidoc fixes
authored
158 === elnode-dispatcher httpcon url-mapping-table &optional function-404 ===
1af9303 improve the README and make a multi-dispatcher
nferrier authored
159
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
160 Dispatch the //httpcon// to the correct function based on the //url-mapping-table//.
1af9303 improve the README and make a multi-dispatcher
nferrier authored
161
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
162 //url-mapping-table// is an alist of:
97e397c improvements to HTTP API
nferrier authored
163
fd21832 update the generated doc for pre's.
nferrier authored
164 {{{
9f894a5 doc changes, auto-generated in part.
nferrier authored
165 (url-regex . function-to-dispatch)
fd21832 update the generated doc for pre's.
nferrier authored
166 }}}
97e397c improvements to HTTP API
nferrier authored
167
9f894a5 doc changes, auto-generated in part.
nferrier authored
168 To map the root url you should use:
97e397c improvements to HTTP API
nferrier authored
169
fd21832 update the generated doc for pre's.
nferrier authored
170 {{{
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
171 "^$"
fd21832 update the generated doc for pre's.
nferrier authored
172 }}}
97e397c improvements to HTTP API
nferrier authored
173
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
174 To ensure paths end in /, [[elnode-dispatcher]] uses
175 [[elnode-normalize-path]]. To map another url you should use:
97e397c improvements to HTTP API
nferrier authored
176
fd21832 update the generated doc for pre's.
nferrier authored
177 {{{
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
178 "^path/$" or "^path/sub-path/$"
fd21832 update the generated doc for pre's.
nferrier authored
179 }}}
97e397c improvements to HTTP API
nferrier authored
180
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
181 An example server setup:
97e397c improvements to HTTP API
nferrier authored
182
fd21832 update the generated doc for pre's.
nferrier authored
183 {{{
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
184 (defun my-server (httpcon)
185 (elnode-dispatcher
186 httpcon
187 '(("^$" . root-view)
188 ("^1/$" . view-1))))
0391674 @nicferrier fix a problem with wikidoc
authored
189 }}}
336155f updates to the README.
nferrier authored
190
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
191 If //function-404// is non-nil then it is called when no regexp is
192 matched.
193
194
195 === elnode-docroot-for doc-root with target-file-var on httpcon do &rest handling ===
196
197 Docroot protection for Elnode handlers.
198
199 Test the path requested in //httpcon// is safely under the //doc-root//
200 specified, bind the //target-file-var// to the resulting expanded
201 file name and execute the //handling// code.
202
203 For example:
204
205 {{{
206 (elnode-docroot-for
207 "~/work"
208 with file-var
209 on httpcon
210 do
211 (elnode-send-file httpcon file-var))
212 }}}
213
214 checks any resource requested in //httpcon// is a file under the
215 doc-root "~/work" and if it is, binds the resulting file name
216 to FILE-VAR and calls the code following //do// (which sends the file
217 to the //httpcon//).
218
219 When a file is not found (or not safe to return) [[elnode-not-found]] is called.
220
221 When a file is cached on the client (when a client sends a
222 conditional GET for the file that shows the client has an up to
223 date copy) then [[elnode-cached]] is called.
a2dcba7 @nicferrier fixed wikidoc
authored
224
225
12e340b @nicferrier more wikidoc fixes
authored
226 === elnode-error msg &rest args ===
6748de0 Updated README with info about HTTP API.
nferrier authored
227
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
228 Log //msg// with //args// as an error.
336155f updates to the README.
nferrier authored
229
5b6f31a @nicferrier updated the API doc in the README
authored
230 This function is available for handlers to call. It is also used
231 by elnode iteslf.
1af9303 improve the README and make a multi-dispatcher
nferrier authored
232
9f894a5 doc changes, auto-generated in part.
nferrier authored
233 There is only one error log, in the future there may be more.
1af9303 improve the README and make a multi-dispatcher
nferrier authored
234
235
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
236 === elnode-get-targetfile httpcon docroot ===
237
238 Get the targetted file from the //httpcon//.
239
240 Attempts to resolve the matched path of the //httpcon// against the
241 //docroot//.
242
243 The resulting file is NOT checked for existance or safety.
244
245
12e340b @nicferrier more wikidoc fixes
authored
246 === elnode-hostpath-default-handler httpcon ===
5b6f31a @nicferrier updated the API doc in the README
authored
247
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
248 A default hostpath handler.
5b6f31a @nicferrier updated the API doc in the README
authored
249
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
250 This uses the [[elnode-hostpath-default-table]] for the match
251 table. It calls [[elnode-hostpath-dispatcher]] with
252 [[elnode-hostpath-default-table]].
5b6f31a @nicferrier updated the API doc in the README
authored
253
254
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
255 === elnode-hostpath-dispatcher httpcon hostpath-mapping-table &rest --cl-rest-- ===
5b6f31a @nicferrier updated the API doc in the README
authored
256
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
257 Dispatch //httpcon// to a handler based on the //hostpath-mapping-table//.
5b6f31a @nicferrier updated the API doc in the README
authored
258
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
259 //hostpath-mapping-table// has a regex of the host and the path slash
260 separated, thus:
5b6f31a @nicferrier updated the API doc in the README
authored
261
262 {{{
263 ("^localhost/pastebin.*" . pastebin-handler)
0391674 @nicferrier fix a problem with wikidoc
authored
264 }}}
5b6f31a @nicferrier updated the API doc in the README
authored
265
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
266 FUNCTION-404 should be a 404 handling function, by default it's
267 [[elnode-send-404]].
268
269 LOG-NAME is an optional log-name.
270
271 (fn (//httpcon// //hostpath-mapping-table// &key (FUNCTION-404 (quote elnode-send-404)) (LOG-NAME "elnode")))
a2dcba7 @nicferrier fixed wikidoc
authored
272
273
12e340b @nicferrier more wikidoc fixes
authored
274 === elnode-http-cookie httpcon name ===
5b6f31a @nicferrier updated the API doc in the README
authored
275
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
276 Return the cookie value for //httpcon// specified by //name//.
277
278
279 === elnode-http-header httpcon name &optional convert ===
280
281 Get the header specified by //name// from the //httpcon//.
282
283 HEADER may be a string or a symbol. If //name// is a symbol it is
284 case insensitve.
285
286 If optional //convert// is specified it may specify a conversion,
287 currently supported conversions are:
288
289 {{{
290 :time - to convert a time value properly
291 }}}
292
293
294
295 === elnode-http-mapping httpcon &optional part ===
296
297 Return the match on the //httpcon// that resulted in the current handler.
298
299 With //part// it returns a specific part of the match , by default
300 //part// is 0.
301
302 This results only from a call via [[elnode-dispatcher]].
1af9303 improve the README and make a multi-dispatcher
nferrier authored
303
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
304 It returns the string which matched your url-mapping, with the
305 match-data attached. So given the mapping:
1af9303 improve the README and make a multi-dispatcher
nferrier authored
306
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
307 {{{
308 ("static/\(.*\)" . my-handler)
309 }}}
1af9303 improve the README and make a multi-dispatcher
nferrier authored
310
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
311 and the request:
312
313 {{{
314 /static/somedir/somefile.jpg
315 }}}
316
317 The following is true inside the handler:
318
319 {{{
320 (equals "/somedir/somefile.jpg"
321 (match-string 1 (elnode-http-mapping httpcon)))
322 }}}
323
324 The function [[elnode-test-path]] uses this facility to work out a
325 target path.
37a8014 include info about the webserver.
nferrier authored
326
327
12e340b @nicferrier more wikidoc fixes
authored
328 === elnode-http-method httpcon ===
37a8014 include info about the webserver.
nferrier authored
329
5b6f31a @nicferrier updated the API doc in the README
authored
330 Get the PATHINFO of the request.
331
332
12e340b @nicferrier more wikidoc fixes
authored
333 === elnode-http-param httpcon name ===
5b6f31a @nicferrier updated the API doc in the README
authored
334
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
335 Get the named parameter from the request.
5b6f31a @nicferrier updated the API doc in the README
authored
336
337
12e340b @nicferrier more wikidoc fixes
authored
338 === elnode-http-params httpcon ===
9f894a5 doc changes, auto-generated in part.
nferrier authored
339
340 Get an alist of the parameters in the request.
341
342 If the method is a GET then the parameters are from the url. If
343 the method is a POST then the parameters may come from either the
344 url or the POST body or both:
345
fd21832 update the generated doc for pre's.
nferrier authored
346 {{{
9f894a5 doc changes, auto-generated in part.
nferrier authored
347 POST /path?a=b&x=y
348 a=c
fd21832 update the generated doc for pre's.
nferrier authored
349 }}}
9f894a5 doc changes, auto-generated in part.
nferrier authored
350
351 would result in:
352
fd21832 update the generated doc for pre's.
nferrier authored
353 {{{
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
354 '(('a' 'b' 'c')('x' . 'y'))
0391674 @nicferrier fix a problem with wikidoc
authored
355 }}}
9f894a5 doc changes, auto-generated in part.
nferrier authored
356
a2dcba7 @nicferrier fixed wikidoc
authored
357
358
12e340b @nicferrier more wikidoc fixes
authored
359 === elnode-http-pathinfo httpcon ===
9f894a5 doc changes, auto-generated in part.
nferrier authored
360
5b6f31a @nicferrier updated the API doc in the README
authored
361 Get the PATHINFO of the request.
9f894a5 doc changes, auto-generated in part.
nferrier authored
362
363
12e340b @nicferrier more wikidoc fixes
authored
364 === elnode-http-query httpcon ===
9f894a5 doc changes, auto-generated in part.
nferrier authored
365
5b6f31a @nicferrier updated the API doc in the README
authored
366 Get the QUERY of the request.
9f894a5 doc changes, auto-generated in part.
nferrier authored
367
368
12e340b @nicferrier more wikidoc fixes
authored
369 === elnode-http-return httpcon &optional data ===
9f894a5 doc changes, auto-generated in part.
nferrier authored
370
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
371 End the response on //httpcon// optionally sending //data// first.
9f894a5 doc changes, auto-generated in part.
nferrier authored
372
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
373 //httpcon// is the http connection which must have had the headers
5b6f31a @nicferrier updated the API doc in the README
authored
374 sent with [[elnode-http-start]]
9f894a5 doc changes, auto-generated in part.
nferrier authored
375
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
376 //data// must be a string, it's just passed to [[elnode-http-send]].
9f894a5 doc changes, auto-generated in part.
nferrier authored
377
378
12e340b @nicferrier more wikidoc fixes
authored
379 === elnode-http-send-string httpcon str ===
9f894a5 doc changes, auto-generated in part.
nferrier authored
380
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
381 Send the string to the HTTP connection.
9f894a5 doc changes, auto-generated in part.
nferrier authored
382
383 This is really only a placeholder function for doing transfer-encoding.
384
385
12e340b @nicferrier more wikidoc fixes
authored
386 === elnode-http-start httpcon status &rest header ===
9f894a5 doc changes, auto-generated in part.
nferrier authored
387
388 Start the http response on the specified http connection.
389
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
390 //httpcon// is the HTTP connection being handled.
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
391 //status// is the HTTP status, eg: 200 or 404
392 //header// is a sequence of (header-name . value) pairs.
9f894a5 doc changes, auto-generated in part.
nferrier authored
393
394 For example:
395
fd21832 update the generated doc for pre's.
nferrier authored
396 {{{
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
397 (elnode-http-start httpcon "200" '("Content-type" . "text/html"))
0391674 @nicferrier fix a problem with wikidoc
authored
398 }}}
9f894a5 doc changes, auto-generated in part.
nferrier authored
399
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
400 The status and the header are also stored on the process as meta
401 data. This is done mainly for testing infrastructure.
a2dcba7 @nicferrier fixed wikidoc
authored
402
403
12e340b @nicferrier more wikidoc fixes
authored
404 === elnode-http-version httpcon ===
5b6f31a @nicferrier updated the API doc in the README
authored
405
406 Get the PATHINFO of the request.
407
9f894a5 doc changes, auto-generated in part.
nferrier authored
408
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
409 === elnode-init ===
9f894a5 doc changes, auto-generated in part.
nferrier authored
410
5b6f31a @nicferrier updated the API doc in the README
authored
411 Bootstraps the elnode environment when the Lisp is loaded.
9f894a5 doc changes, auto-generated in part.
nferrier authored
412
5b6f31a @nicferrier updated the API doc in the README
authored
413 It's useful to have elnode start automatically... on Lisp
414 load. If the variable [[elnode-init-port]] is set then this
415 function will launch a server on it.
9f894a5 doc changes, auto-generated in part.
nferrier authored
416
5b6f31a @nicferrier updated the API doc in the README
authored
417 The server is started with [[elnode-hostpath-default-handler]] as
418 the handler and listening on [[elnode-init-host]]
9f894a5 doc changes, auto-generated in part.
nferrier authored
419
420
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
421 === elnode-list-buffers ===
9f894a5 doc changes, auto-generated in part.
nferrier authored
422
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
423 List the current buffers being managed by Elnode.
424
425
426 === elnode-log-access logname httpcon ===
427
428 Log the HTTP access in buffer //logname//.
429
430 This function is available for handlers to call. It is also used
431 by elnode iteslf.
432
433
434 === elnode-make-redirecter location &optional type ===
435
436 Make a handler that will redirect to //location//.
437
438 Optionally, use the specified //type// as the status code, eg:
439
440 {{{
441 (elnode-make-redirect "http://somehost.com/" 301)
442 }}}
443
444
445
446 === elnode-make-send-file filename &rest --cl-rest-- ===
447
448 Make a handler that will serve a single //filename//.
449
450 If the //filename// is relative then it is resolved against the
451 package's [[load-file-name]].
452
453 Optionally mime-types and other additional keyword arguments may be
454 specified and are passed through, see [[elnode-send-file]] for
455 details.
456
457 (fn (//filename// &key PREAMBLE MIME-TYPES))
458
459
460 === elnode-method &rest method-mappings ===
461
462 Map the HTTP method.
463
464 Write code like this:
465
466 {{{
467 (elnode-method
468 (GET
469 (code)
470 (more code))
471 (POST
472 (different code)
473 (evenmorecode)))
474 }}}
475
5b6f31a @nicferrier updated the API doc in the README
authored
476
477
12e340b @nicferrier more wikidoc fixes
authored
478 === elnode-normalize-path httpcon handler ===
5b6f31a @nicferrier updated the API doc in the README
authored
479
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
480 A decorator for //handler// that normalizes paths to have a trailing slash.
9f894a5 doc changes, auto-generated in part.
nferrier authored
481
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
482 This checks the //httpcon// path for a trailing slash and sends a 302
7053d2b @nicferrier more doc and README fixes
authored
483 to the slash trailed url if there is none.
9f894a5 doc changes, auto-generated in part.
nferrier authored
484
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
485 Otherwise it calls //handler//.
9f894a5 doc changes, auto-generated in part.
nferrier authored
486
487
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
488 === elnode-not-found httpcon target-file ===
489
490 [[elnode-docroot-for]] calls this when the doc was not found.
491
492 You can override this in tests to have interesting effects. By
493 default it just calls [[elnode-send-404]].
494
495
496 === elnode-send-400 httpcon &optional msg ===
497
498 Sends a Bad Request error to the //httpcon//.
499
500 Optionally include //msg//.
501
502
503 === elnode-send-404 httpcon &optional msg ===
504
505 Sends a Not Found error to the //httpcon//.
506
507 Optionally include //msg//.
508
9f894a5 doc changes, auto-generated in part.
nferrier authored
509
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
510 === elnode-send-500 httpcon &optional msg ===
9f894a5 doc changes, auto-generated in part.
nferrier authored
511
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
512 Sends a Server Error to the //httpcon//.
9f894a5 doc changes, auto-generated in part.
nferrier authored
513
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
514 Optionally include //msg//.
9f894a5 doc changes, auto-generated in part.
nferrier authored
515
516
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
517 === elnode-send-file httpcon targetfile &optional mime-types &rest --cl-rest-- ===
9f894a5 doc changes, auto-generated in part.
nferrier authored
518
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
519 Send the //targetfile// to the //httpcon//.
9f894a5 doc changes, auto-generated in part.
nferrier authored
520
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
521 If the //targetfile// is relative then resolve it via the current
522 [[load-file-name]] or [[buffer-file-name]] or [[default-directory]].
9f894a5 doc changes, auto-generated in part.
nferrier authored
523
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
524 WARNING: this resolution order is likely to change because,
525 especially when developing [[default-directory]] can be quite
526 random (change buffer, change [[default-directory]]).
9f894a5 doc changes, auto-generated in part.
nferrier authored
527
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
528 //mime-types// is an optional alist of MIME type mappings to help
529 resolve the type of a file.
9f894a5 doc changes, auto-generated in part.
nferrier authored
530
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
531 Optionally you may specify extra keyword arguments:
9f894a5 doc changes, auto-generated in part.
nferrier authored
532
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
533 :PREAMBLE a string of data to send before the file.
9f894a5 doc changes, auto-generated in part.
nferrier authored
534
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
535 :PREAMBLE is most useful for prefixing syntax to some other file,
536 for example you could prefix an XML file with XSL transformation
537 statements so a compliant user-agent will transform the XML.
538
539 (fn (//httpcon// //targetfile// &optional //mime-types// &key PREAMBLE))
540
541
542 === elnode-send-json httpcon data &optional content-type ===
543
544 Send a 200 OK to the //httpcon// along with //data// as JSON.
545
546 If //content-type// is specified then it is used as the HTTP Content
547 Type of the response.
548
549
550 === elnode-send-redirect httpcon location &optional type ===
551
552 Sends a redirect to //location//.
553
554 If //type// is non-nil, use it as a status code. Defaults to 302 -
555 permanent redirect.
556
557
558 === elnode-send-status httpcon status &optional msg ===
559
560 A generic handler to send //status// to //httpcon//.
561
562 Sends an HTTP response with //status// to the //httpcon//. An HTML body
563 is sent by looking up the //status// in the [[elnode-default-response]]
564 table.
565
566 Optionally include //msg//.
567
568
569 === elnode-start request-handler &rest --cl-rest-- ===
570
571 Start a server using //request-handler//.
572
573 //request-handler// will handle requests on PORT on HOST (which is
574 'localhost' by default).
575
576 //request-handler// is a function which is called with the request.
577 The function is called with one argument, which is the
9f894a5 doc changes, auto-generated in part.
nferrier authored
578 http-connection.
579
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
580 You can use functions such as [[elnode-http-start]] and
581 [[elnode-http-send-body]] to send the http response.
9f894a5 doc changes, auto-generated in part.
nferrier authored
582
583 Example:
584
fd21832 update the generated doc for pre's.
nferrier authored
585 {{{
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
586 (defun nic-server (httpcon)
587 (elnode-http-start httpcon 200 '(("Content-Type: text/html")))
588 (elnode-http-return httpcon "<html><b>BIG!</b></html>")
589 )
590 (elnode-start 'nic-server)
fd21832 update the generated doc for pre's.
nferrier authored
591 }}}
9f894a5 doc changes, auto-generated in part.
nferrier authored
592
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
593 Now visit http://127.0.0.1:8000
594
595 If PORT is non-nil, then run server on PORT, otherwise default to
596 8000.
9f894a5 doc changes, auto-generated in part.
nferrier authored
597
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
598 If HOST is non-nil, then run the server on the specified local IP
599 address, otherwise use localhost. A few names are predefined:
9f894a5 doc changes, auto-generated in part.
nferrier authored
600
fd21832 update the generated doc for pre's.
nferrier authored
601 {{{
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
602 "localhost" is 127.0.0.1
603 "*" is 0.0.0.0
fd21832 update the generated doc for pre's.
nferrier authored
604 }}}
9f894a5 doc changes, auto-generated in part.
nferrier authored
605
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
606 Additionally, you may specifiy an IP address, e.g "1.2.3.4"
607
608 Note that although HOST may be specified, elnode does not
609 disambiguate on running servers by HOST. So you cannot start two
610 elnode servers on the same port on different hosts.
9f894a5 doc changes, auto-generated in part.
nferrier authored
611
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
612 (fn (//request-handler// &key PORT (HOST "localhost") (DEFER-MODE :managed)))
9f894a5 doc changes, auto-generated in part.
nferrier authored
613
614
12e340b @nicferrier more wikidoc fixes
authored
615 === elnode-stop port ===
9f894a5 doc changes, auto-generated in part.
nferrier authored
616
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
617 Stop the elnode server attached to //port//.
9f894a5 doc changes, auto-generated in part.
nferrier authored
618
619
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
620 === elnode-test-call path &rest --cl-rest-- ===
9f894a5 doc changes, auto-generated in part.
nferrier authored
621
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
622 Fake a call to elnode with the //path//.
9f894a5 doc changes, auto-generated in part.
nferrier authored
623
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
624 In addition you can specify some extra HTTP stuff:
9f894a5 doc changes, auto-generated in part.
nferrier authored
625
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
626 {{{
627 :method one of GET, POST, DELETE, etc...
628 :parameters POST parameters, will be turned into a POST body
629 :headers any specific headers you require, you may override
630 test-call headers.
631 }}}
9f894a5 doc changes, auto-generated in part.
nferrier authored
632
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
633 For example:
634
635 {{{
636 (elnode-test-call "/wiki/test")
637 }}}
638
639 or:
640
641 {{{
642 (elnode-test-call "/wiki/test"
643 :method "POST"
644 :parameters '(("a" . 10)))
645 }}}
646
647 For header and parameter names, strings MUST be used currently.
648
649 (fn (//path// &key (METHOD "GET") (PARAMETERS (quote nil)) (HEADERS (quote nil))))
650
651
652 === elnode-test-handler httpcon ===
653
654 A simple handler for testing 'elnode-test-call
655
656
657 === elnode-test-path httpcon docroot handler &optional failure ===
658
659 DEPRECATED.
660
661 Check that the path in the //httpcon// is above the //docroot//.
662
663 Call //failure//-//handler// (falling back to 'enode-send-404') on failure
664 and //handler// on success.
665
666 //handler// is called with these arguments: //httpcon//, //docroot// and
667 TARGETFILE. TARGETFILE is the absolute filename for the
668 resource being requested (and is, obviously, safely below the
669 //docroot//).
670
671 This is used by [[elnode--webserver-handler-proc]] in the webservers
9f894a5 doc changes, auto-generated in part.
nferrier authored
672 that it creates... but it's also meant to be generally useful for
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
673 other handler writers.
674
675 This function use [[elnode-http-mapping]] to establish a
676 targetfile, allowing URL mappings to look like this:
677
678 {{{
679 "prefix/\(.*\)$"
680 }}}
681
682 Only the grouped part will be used to resolve the targetfile.
683
684
685 === elnode-time-encode time-str ===
686
687 Basic //time-str// to time encoding.
688
689
690 === elnode-trim str ===
691
692 Trim off whitespace.
693
694
695 === elnode-trunc data ===
696
697 Truncate and clean //data//.
698
699
700 === elnode-wait-for-exit process ===
701
702 Wait for //process// status to go to 'exit.
9f894a5 doc changes, auto-generated in part.
nferrier authored
703
704
12e340b @nicferrier more wikidoc fixes
authored
705 === elnode-webserver httpcon ===
5b6f31a @nicferrier updated the API doc in the README
authored
706
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
707 A simple webserver that serves documents out of [[elnode-webserver-docroot]].
5b6f31a @nicferrier updated the API doc in the README
authored
708
709 This is just an example of an elnode webserver, but it may be all
710 that is needed most of the time.
711
712 See [[elnode-webserver-handler-maker]] for more possibilities for
713 making webserver functions.
714
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
715 //httpcon// is the HTTP connection to the user agent.
5b6f31a @nicferrier updated the API doc in the README
authored
716
717
12e340b @nicferrier more wikidoc fixes
authored
718 === elnode-webserver-handler-maker &optional docroot extra-mime-types ===
9f894a5 doc changes, auto-generated in part.
nferrier authored
719
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
720 Make a webserver handler possibly with the //docroot// and //extra-mime-types//.
9f894a5 doc changes, auto-generated in part.
nferrier authored
721
722 Returns a proc which is the handler. The handler serves files out
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
723 of the docroot and marks them with the content types that Emacs
9f894a5 doc changes, auto-generated in part.
nferrier authored
724 knows about. You can add extra content types for the webserver
725 just by supplying an alist of mime-types and extensions for
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
726 //extra-mime-types//.
9f894a5 doc changes, auto-generated in part.
nferrier authored
727
728 The webserver handler also creates file indexes.
729
5b6f31a @nicferrier updated the API doc in the README
authored
730 The webserver uses [[elnode-test-path]] to make sure that the
bce354b @nicferrier updated README via http://marmalade-repo.org/packages/wikidoc
authored
731 request does not go above the //docroot//.
37a8014 include info about the webserver.
nferrier authored
732
733
0a759c2 @nicferrier updated the README with the latest API. cl functions break documentation...
authored
734 === elnode-wiki-handler httpcon wikiroot ===
735
736 A low level handler for Wiki operations.
737
738 Send the Wiki page requested, which must be a file existing under
739 the //wikiroot//, back to the //httpcon//.
740
741
742 === elnode-wiki-send httpcon wikipage &optional pageinfo ===
743
744 A very low level Wiki handler.
745
746 Sends the //wikipage// to the //httpcon//.
747
748 If //pageinfo// is specified it's the HTTP path to the Wiki page.
749
750
751 === elnode-wikiserver httpcon ===
752
753 Serve Wiki pages from [[elnode-wikiserver-wikiroot]].
754
755 //httpcon// is the request.
756
757 The Wiki server is only available if the [[creole]] package is
758 provided. Otherwise it will just error.
759
760
761 === elnode-wikiserver-test ===
762
763 Test whether we should serve Wiki or not.
764
765
766 === elnode-worker-elisp output-stream bindings &rest body ===
767
768 Evaluate the //body// in a child Emacs connected to //output-stream//.
769
770 The //bindings// are let-form variable assignments which are
771 serialized for the child Emacs. Unless a variable from the
772 parent is explicitly stated here it will NOT be accessible in the
773 child Emacs.
774
775 The child Emacs has a [[load-path]] exactly as the [[load-path]] of
776 the parent Emacs at execution.
777
778 The created child Emacs process is returned. It's possible to
779 kill the child Emacs process or do other things to it directly.
780 This could be very dangerous however, you should know what you
781 are doing before attempting it.
782
783 The //output-stream// could be a buffer, a function or another
784 process.
785
786 If the //output-stream// is another process it may have a process
787 property [[:send-string-function]] evaluating to a function to send
788 data to that process. The function should take the same
789 arguments as the standard Emacs Lisp [[process-send-string]].
790
791 Furthermore, if the //output-stream// is another process, when the
792 child Emacs finishes an EOF is sent to that process. If the
793 //output-stream// process has a process property [[:send-eof-function]]
794 then that is used to send the EOF. The function should take the
795 same arguments as the standard Emacs Lisp [[process-send-eof]].
796
797 An example:
798
799 {{{
800 (elnode-worker-elisp http-connection
801 ((path (path-function)))
802 (require 'creole)
803 (creole-wiki path))
804 }}}
805
806 Presuming http-connection is a process (in the manner of Elnode,
807 for example) this will cause a child Emacs to be created, within
808 which [[path]] (which is serialized from the value of the parent
809 Emacs' [[path-function]]) will be loaded and converted from
810 WikiCreole to HTML and then sent to the standard output stream.
811 The child's standard output stream is connected directly to the
812 [[http-connection]]. In this case, presumably the
813 [[http-connection]] would have functions attached to the properties
814 [[:send-string-function]] and [[:send-eof-function]] to do HTTP
815 chunk encoding and to end the HTTP connection correctly.
816
817
818 === elnode-worker-last-code ===
819
820 Put the last worker code in a file for later use.
821
822 When testing it's good to be able to capture the last lisp made
823 by [[elnode-worker-elisp]] for manipulating manually.
824
825
826
1af9303 improve the README and make a multi-dispatcher
nferrier authored
827
a2dcba7 @nicferrier fixed wikidoc
authored
828
4464986 updates to the README to include info on dispatching and process calling
nferrier authored
829 == But... ==
830
831 There's always a but.
832
9f894a5 doc changes, auto-generated in part.
nferrier authored
833 Here's a list of buts:
4464986 updates to the README to include info on dispatching and process calling
nferrier authored
834
9f894a5 doc changes, auto-generated in part.
nferrier authored
835 * the HTTP parsing isn't great, it uses too many regexs
836 * we don't parse any data sent through POST other than form-data
837 * the error handling is absolute rubbish
1af9303 improve the README and make a multi-dispatcher
nferrier authored
838
7edc2af @nicferrier suggestions for stuff to do
authored
839 == To Do? ==
840
841 If you're playing with elnode but you can't think of anything to do with it...
842
843 * an elpa repository written with elnode
ff5d553 @nicferrier fix the creole formatting
authored
844 ** turn the package list into html
845 ** allow packages to be downloaded from elnode
846 ** upload of packages will require fixing the request management a little
7edc2af @nicferrier suggestions for stuff to do
authored
847 * an emacsclient with elnode
ff5d553 @nicferrier fix the creole formatting
authored
848 ** write a command line client that submits data to the server over HTTP
849 ** it should interact with the emacs user in the same way that emacs server does
7edc2af @nicferrier suggestions for stuff to do
authored
850 * a simple wiki engine with elnode
ff5d553 @nicferrier fix the creole formatting
authored
851 ** maybe using a command line wiki templating tool
9228f4d @nicferrier another little README syntax fix
authored
852 * alter {{{elnode-webserver-handler-maker}}} to do indexing better
7053d2b @nicferrier more doc and README fixes
authored
853 ** take an optional index producing function?
854 ** take keyword flags that set the behaviour?
93f1d62 @nicferrier added browse-current-buffer as a TODO
authored
855 ** eg: {{{:doindexes 't }}}
856 * browse-current-buffer
857 ** start an elnode server on some random port exposing the current buffer
858 ** automatically open a browser on the server
Something went wrong with that request. Please try again.