A. The Whys of BRL

A.1 Why not HTML-like syntax?

Many web template engines enclose program code in something that looks like an HTML tag. CFML takes this to an extreme by making most of its language constructs look like HTML tags. This may make for some comfort for someone used to HTML, but that comfort goes away as one recognizes the fundamental cognitive difference between markup and programming code. Writing a web page and programming a computer to write a web page are two different mental activities, and a different syntax helps one switch back and forth between them.

Another argument for HTML-like syntax is the hope of having valid SGML pages for the template source code. I have yet to see an actual SGML or XML tool for manipulating such source code. More important than valid source code is valid output. A valid source file might produce invalid output or vice versa.

HTML-like code, e.g. <%=name%> likes <%=color%>, if brought up as source code in a browser, shows up only as the word "likes". The BRL code [name] likes [color] shows up completely, and is more useful for assessing what the output might look like. Square brackets are used just as they are in English.

A.2 Why Scheme?

BRL is a syntactic descendant of cgiemail, a program written in 1995 to allow non-programmers to specify the exact format of e-mail messages sent from HTML forms. Its template language began very simply. One would write the literal text of an e-mail message, putting [inputname] wherever an HTML input's value should go. Over time, more functionality was added. One could name an input with a required- prefix to indicate that an error should be signaled if that input was left blank. One could use [$VAR] to put in a CGI environment variable. Text could fill a given number of columns with C-like [%-9.9s,inputname].

As more functionality got added and more special characters were used, I could see my simple template system potentially evolving into a programming language that looked like line noise. A function should be spelled out rather than having its own special character. I wanted to preserve the simple [inputname] syntax, and just have one special character that indicated a function name rather than a variable name would follow. I also wanted to have a means of combining functions.

So, perusing my keyboard for that one special character I happened on the parens and remembered Scheme from a Computer Science course 10 years earlier. That syntax turned out to be a perfect fit. Scheme's syntax looks a lot like an imperative sentence in English, but with less ambiguous grouping: (verb object1 object2 ...). And as a bonus, the simple [inputname] syntax would also work, as a variable name all by itself is a valid Scheme expression.

Scheme's simple syntax for defining procedures is also very helpful in web application development. Rapid prototyping is possible by creating little procedures as needed within an individual page. It is then trivial to move from quick prototype to MVC separation,(11) often just by cutting code from an individual page and pasting it into `sitedefs.scm'.

As a contrasting example, Java has such a large overhead for moving code out of an individual JSP page and into a Java bean that it is unlikely that a programmer will spend the effort. This problem has motivated the creation of systems that force MVC separation from the start (e.g. webmacro), making rapid prototyping more difficult. Thanks to Scheme, BRL does not have this RAD vs MVC dilemma.

Some programmers dislike Scheme because mathematical expressions tend to look very different from how they would normally be written. This is of little importance to BRL because math is rarely used in web pages, and when it is used it tends to be simple.

Some programmers think they will have a hard time switching from the verb(object1, object2, ...); syntax that they use in other popular languages. However, a good programmer doesn't usually take long to adjust to an unfamiliar syntax. It may actually be less confusing to switch back and forth between dissimilar syntaxes than to switch back and forth between syntaxes that are similar but not identical, e.g. between PHP and Perl.

A.3 Why ]string[?

Even for someone accustomed to Scheme, one aspect of BRL's syntax is confusing. An expression like (string-length ]string[) looks like mismatched parentheses. Yet there is good reason to allow this syntax.

In other compiled template systems like JSP, literal text outside of delimiters is converted into print statements. These are combined with the statements inside the delimiters to produce source code that is compiled. This allows for interesting uses of the template system, e.g.

<% for (i=0; i<10; i++) { %> <li> <%=name[i]%> likes <%=color[i]%> <% } %>

The concise template syntax is used with flow constructs such as loops and conditionals. Note that the <% } %> looks mismatched, but makes sense when you know how things work. It's also nice for a non-programmer looking through the code and simply scanning for %> to see where the programming stops and the HTML starts. In BRL 1, something like this JSP example was not possible. You could conditionalize around regular Scheme syntax, but not around syntax that included the [ and ] delimiters.

BRL 2 (described in this manual), thanks to Scheme, is able to take this concept one step further.

Its concise template syntax can be used not only with flow constructs, but within any language construct. Unlike any other template language, BRL lets the same syntax to be used to construct not only the HTML page to be output, but also e-mail messages, complex SQL queries, or anything else that mixes static and dynamic content.

For this reason, one cannot treat BRL as Yet-Another-Language Server Pages. One's thinking has to be adjusted. As a starting point, one might look at the JSP example above and imagine [ and ] in place of <% and %>, and (brl and ) in place of { and }. Then spend some time looking at the e-mail example in this manual (see section 4.7 Sending e-mail). A relatively small investment of time acclimating to BRL syntax will repay handsomely in a powerfully expressive tool for writing dynamic web pages.