Building a Qompose File

The structure of a Qompose file is very simple. It starts with a single file that you can put as much or as little are you need in. Within a Qompose token file are as many or as few "tokens" are you need. "Tokens" are the key to Qompose's templating ability. Each Qompose file declares a number of tokens. The first token is the page you're requesting and defaults to the blank token if you don't specify one on the command line. Tokens can and will often contain references to other tokens, and the substitution continues in a nested manner until the top-level token is finished.

Tokens are declared with the following syntax:

|token name|description|content

The vertical bar at the start is how the Qompose engine knows it is a (new) token. It must be in column 1. The description is optional (currently it is not used but a future version may use it). And the content section is not limited to the end of the line. Content may continue indefinitely; newline characters are inserted on each line boundary of the content. The next token is heralded by a | in column 1. If you repeat a token, Qompose doesn't complain. In fact, having multiple values for a token is a major feature. They just accumulate in a list in the order they were declared.

To make things easier, Qompose files may have comments. Comments are marked by a # in column 1 and are ignored by Qompose. Comments may even appear within a token's content (and are automatically removed) with no ill-effect. Qompose also skips over blank lines.

Qompose also supports a small number of directives:

-include filename includes another Qompose file in this point in the current file
-cd directory changes the current directory of the Qompose engine

The -include directive is very powerful and is really the key to successfully templating with Qompose. It enables you to put common HTML elements into one file that all other Qompose files reference. Moreover, -include files can be nested as far as you want (but remember that Qompose does not detect loops). It is important to realize that where you -include is vital because it affects the order of token lists. Declaring tokens with the same name as in an included file before the -include will effectively override tokens in the included file. Declaring such tokens after the -include will add to the end of the list.

In the rare occasion you need to start normal text with one of the above-mentioned sentinel characters, you can escape it with a leading backslash (\). (A literal backslash at the start of the line also has to be escaped.) You can also escape the newline character at the end of the line with the same character (this is very useful for building long RPN sequences). It only works at the very start and the very end of the line.

Token expansion

To embed tokens, there must, of course, be a way to reference them. To do this, you use a $. With one exception, all dynamic content within tokens in Qompose begin with a $. (The one exception is discussed below.) To emit a simple dollar sign, double it: $$. To embed a token, use the following:

$token name.

Note the trailing period. Token references may appear anywhere in token content. Non-existant tokens are silently ignored.

But this is only of limited usefulness because this format doesn't do any token de-referencing in the content of the newly referenced token. To do that, you have to use what is called a pre-command:

$-token name. enable recursive expansion of this token
$<token name. reads a file given by the content of this token and inserts it here (note: this is going to go away RSN in favour of a more powerful technique for inserting files)
$!token name. references but doesn't output this token - this is usually used with the + post command

And if you have pre-commands, it is natural to have post-commands, too.

$token name+. increments this token's list so the next reference to it returns the next value
$token name-. decrements this token's list so the next reference to it returns the prior value
$token name?. selects the content of this token at random from the list

Normally, when replacing a token you get the current content. If you declare multiple tokens of the same name, you will get the first one declared. So how do you get the later values? That's what the + and - post-commands are for. They cycle the list of the specified token so that the next reference will return the next or previous value declared. Note that this operation is always done after the token is dereferenced. If you somehow need to increment or decrement a token's list before derefencing it, you will need to do a $!token+.$-token. which is slightly cumbersome. It also suggests you haven't really structured your data properly in order to use post-increment.

Token names themselves may be anything that doesn't interfere with the formatting characters for Qompose to declare or find your token. That means the cannot have a | or a . in them, nor may they begin with a $ a < a - or a !. Don't play with these characters in token names; you will probably find Qompose will mis-interpret your file if you do.

As well as the values you declare, any other values given in the URL are available as $1., $2. etc. This permits you to build URLs that take parameters.

> Next: Parse Time Calculation