WATERSHED is a term used to describe a time in television schedules during which it is permissible to show television programmes which have 'adult content'. Adult content can be generally defined as having nudity, explicit sexual intercourse, graphic violence, strong language, or drug references or use.
Watershed is a down and dirty way of producing HTML with lisp. Its goal is to be the fasted possible path from static html to dynamicly generated webpage.
Using watershed templates to make a deadline is something like solving a war with chemical weapons: It may solve the problem temporarily, but it will cause you and your neighbors problems down the road and the rest of the "civilized" international community will look down on you for doing it.
The problem is, of course, that using watershed means writing "throwaway code" and creating a website that will be almost completely impossible to maintain or change at a later date.
You have been warned.
Instead of embedding
<?php ... ?> elements in HTML like php, watershed simply uses
) to switch in and out of Common Lisp from HTML.
The following php file:
<html> <head> <title>test</title> </head> <body> <?php echo '<p>Hello World</p>'; ?> </body> </html>
is like the following watershed file:
<html> <head> <title>test</title> </head> <body> (format *html-output* "<p>Hello World</p>") </body> </html>
(of course you'd want to use one of the template functions, not
FORMAT to write
stuff to the client's browser...)
The "special operators"
XML switch back back to html/xml mode.
So you could use something like:
<html> <head> <title>test</title> </head> <body> (let ((place "World")) ;; in lisp mode (html <!-- back in html mode --> <p>(format *html-output* "Hello ~A" place)</p> )) </body> </html>
Use the escape character
\\ to insert literal
IN-PACKAGE forms, so just put one somewhere near the
top of your watershed file like you would with a ".lisp" file.
The default package inside watersehd templates is the
:WATERSHED and exports nothing.
Watershed assumes template files are encoded in UTF-8.
Watershed should come with "watershed-mode.el" which automatically switches a between lisp mode and some other mode--by default html-mode--according to watershed semantics. So the buffer starts in html-mode, when the point enters a sexp it switches to lisp-mode, when it enters an HTML or XML operator it switches back to HTML mode, etc... This enables you to use tab-completion, M-., function signitures, etc, inside templates.
It should also come with "superior-watershed-mode.el" which provides the elisp
WATERSHED-COMPILE-BUFFER, which compiles a watershed template buffer with
with SLIME (like
SLIME-COMPILE-FILE except no fasl involved) and displays the notes.
note: I have not used watershed since switching to Djula, the slime/emacs funcionality is currently broken if I remember correctly :-/ --Nick
utf-8 breaks my SLIME/Emacs
Put this in your .emacs file:
(set-language-environment "UTF-8") (setq slime-net-coding-system 'utf-8-unix)
Variable bound to a character output stream when rendering templates. Write characters to this to send stuff to the user's browser.
*HTML-OUTPUT*, html-escaping it on the way out
THING to a string then html-escapes it.
*HTML-OUTPUT*, url-encoding it on the way out.
Note: assumes UTF-8 so be careful if seen around HUNCHENTOOT:URL-DECODE,
which probably assumes LATIN-1 by default (see
THING to a string then url-encodes it.
_Note: assumes UTF-8 so be careful if seen around `HUNCHENTOOT:URL-DECODE`, which probably assumes LATIN-1 by default (see `HUCHENTOOT:*DEFAULT-EXTERNAL-FORAT*`)._
Function. Returns the url-decoded version of
_Note: assumes UTF-8 so be careful if seen around
probably assumes LATIN-1 by default (see
HTML (&REST HTML)
Macro/special-operator. When used in normal code,
HTML is a macro that writes
any literal strings you give it to
When seen in a watershed template, HTML sends the parser back into non-lisp mode
mode until the appropriate closing
XML (&REST XML)
Macro/special-operator. Synonym for
HTML for the other type of people in the
COMPILE-WATERSHED-TEMPLATE (path &key (type :template) (enctype :utf-8) (compile t) to-bytes)
Function. Returns a thunk (0-argument function) that, when called, renders the
watershed template pointed to by the file designator
EQL to the keyword:
PATH is assumed to be a watershed template
PATH is assumed to contain lisp code (without template semantics).
When the function is called, the lisp code will be evaluated with
bound to a string-output-stream, so all the template API should work (except
XML will just be macros and not "special operators").
PATH' is assumed to contain lisp code (without template semantics). When the function is called, the lisp code will be evaluated.HTML-OUTPUT
will _not_ be bound, so none of the template API that depends onHTML-OUTPUT` will work.
:LISP-NO-BUFFERall understand top-level
IN-PACKAGEforms, so just use them like you would in a normal ".lisp" file.
The default package is
COMPILE-WATERSHED-TEMPLATE just returns the lisp
source code of this function, not a compiled function.
T, the funtion returns UTF-8 bytes instead of a string when