Raw text mode

This mode of the parser simply accumulates text until some special character is encountered. The following special characters can influence parsing raw text:

• { (open bracket) — Enter Lisp mode. A single Lisp token is read, then the closing bracket } is expected, however there are some tricky things here too (see “entering Lisp mode” below).

• } (close bracket) — Stop raw mode and return to the parser a “strcat” expression with the contents.

• ~ (tilde) — The tilde is only special if immediately followed by a newline, and the effect is to suppress it. The tilde itself is not included in the output.

• ; (semicolon) — The semicolon is special only when it's in the first column of a line; the whole line will be treated as a comment and discarded from the output.

• \ (backslash) — The backslash is only special if followed by one of the other special characters above, and it's meant to include the following character literally. The backslash itself is discarded from the output in this case. So for example if you need to include a semicolon at the start of the line, you'd write \;, or if you need a literal tilde at the end of the line, \~. Note that if the backslash is not followed by one of the above characters, it's not special at all and will be included in the output as it is. To get two backslashes you'd simply write \\ — instead of writing four backslashes.

Entering Lisp mode

The character following the opening bracket might have some special implications too:

• \ (backslash) — if present, the result of the following Lisp expression will be escaped according to the current output mode (i.e. HTML).

• . (dot) — if present then we read a directive that is interpreted at parse time. For now we only support a single directive (see below).

• [ (square open paren) — a Lisp expression could be either a symbol, or a form. In case it's a symbol I think it's obvious to assume that the template writer wants the value of the variable to be inserted in the output. In case of a form, however, we can't take a guess. Forms starting with the normal (round) parens will insert the result in the output, while forms starting with square parens will not. In fact, the following two lines are equivalent:

  {[foo]}
  {(progn (foo) nil)}

  The square bracket is simply a shortcut provided by the parser to force the expression return NIL, in which case nothing goes into the output.

Directives

Only one parser directive is supported for now:

.SYNTAX — allows you to modify the start/end special characters (which are initially the brackets). For example:

{(+ 1 2)}
{.SYNTAX "[" "]"}
{(+ 1 2)}
[(+ 1 2)]

Will output:

3
{(+ 1 2)}
3

I'm using this trick in these pages in order to make it easier to type examples in the standard syntax. Note that you can use pretty much any character, they don't have to be brackets or pairs—just make sure to not use one of the characters that are special in raw mode, as well as some characters that you really need in Lisp mode, such as round brackets or the quote/backquotes. Example:

{.SYNTAX "@" "@"}
@(list 'foo 'bar)@
@(strcat 'foo 'bar 'baz)@
{(list 'foo 'bar)}             <!-- literal -->
{(strcat 'foo 'bar 'baz)}

; to change it back we have to use the new sign now:
@.SYNTAX "{" "}"@
{(strcat 'foo 'bar 'baz)}

Note that even though .SYNTAX takes string arguments, the special tokens are characters (so don't try to use a longer string as it won't work, at least for now).