Introduction.

Though PHP has extensive templating capabilities, a respectable number of template engines exist, starting with PhpLib, Smarty and Twig, to name a few. The design of SIREN is based on the idea that the use of boilerplates often doesn't require a full blown templating subsystem, and needs on the other hand smart and robust algorithms.

The approach of SIREN is that the tasks can be divided into replacing text, loading external content, processing logic, and caching. These tasks are implemented in different classes that extends each other in a smart OO manner.

Snippet:
the workhorse for text replacements. Features recursion of replacement.
Templet:
adds the loading of external files and features nesting blocks.
Template:
adds logic capabilities and comment intelligence. Compiles the template in native PHP.
Stencil:
does the caching of templet files and nested blocks.

The name SIREN comes from the bird-like creatures that Odysseus met on his odyssee home. These creatures sang beautifully, causing addiction. Whenever they start to sing collectively, the very event may be called a SIRENADE.

Markers and Variables.

It's all about text and placeholders. The use of a placeholder in a text is to replace them later on with (standard) text. Notaries often use the technique to avoid typo's in the final text, that will become a legal document. Well, there are much more uses, but that goes beyond our scope here.

Such a placeholder is called a 'marker'. Placeholders can be identified, markers will be named. Text containing markers is called 'template text', or just 'template'.
The processing of such template (read: replacing the markers with other text) consists of scanning for markers in the text, extracting their name(s) and replacing them with specific text, identified by their name. This is essential. Such a marker and respective text, is called a variable with a value. A templateVariable with a value.
So, a placeholder == a marker == a variable. They all have names (axioma). And a value. But where are these values registerd, defined, stored?
It is not so smart to have these values embedded somehow in the same template text. Most 'systems' use an external storage to contain these values identified by a variable name. In PHP we'll use an associative array: $myVariables = array('name' => 'text', 'key' => 'value', .....);

Replacing vs Executing?

Besides markers in the template text, we also can distinguish common directives. Be it a formfeed for a new page, or a paragraph to start a new block. This kind of directives, or parameters, cannot be replaced but need an action. Imagine directives as commands to the (external) renderer, f.i. a simple printer.
The example is misplaced, but it shows what is needed to understand: directives have neither a name, nor a value. They must be executed.

And this is exactly what SIRENADE does with logic. Well, not precisely. SIRENADE transforms the logic directives into native PHP code and replaces the logic directives with that transformation. Think of it as a dynamic value. After replacing the logic with native PHP code, SIRENADE invokes the PHP interpreter to do the dirty work. We refer to this feature as 'compiling'.

varNames vs varValues

As agreed, a variable has a Name and has a Value, and Names will be somehow replaced by its Value. Within our Logic, a varName is referenced as Identifier, while a varValue represent a Scalar. Remember this, and:

  1. myVar is a variable with a Name (myVar) and
  2. {myVar} represents a Value,
  3. Logic 'operates' on Identifiers,
  4. Scalars don't execute.

Logic.

The syntax of mentioned logic directives is quite simple, and resembles that of variables: they are surrounded by acculades ('{' and '}'). Some directives differ by being surrounded by xml-delimters ('<' and '>')
To distinguish them from the variable syntax, there are some meta characters used:

Basicly, a logic directive consists of (besides the surroundig meta characters, of a head and a body: [head] \s+ [body]
The type of directive is identified by [head], and the [body] can be nill, a var (myVar of {myVar}), or an expression. ASP logic, however, is treated differently, because it forms a coding style.
SIRENADE removes the meta characters and splits the logic string into [head] and [body] and calls the transformation process. See the file default.inc.php in the directory ,/logic.

Gotcha!
While variables can be recursive in SIREN, logic directives cannot !!
Though you can embed (recursive) variables into logic or set the value of a variable to contain logic. But you can't have them both at the same time. Be warned !!

Native Logic.

It is perfectly oke to mix template text with native PHP, which on their turn contain embedded variables. Supported is the PHP tag and its short tag (for echoing).

Simple Logic.

Is intended to apply logic on variables using their Names.

While its name suggests simplicity, this type of logic has a sophisticated twist.
{!if variable}
tests if the varName does exist
{!while variable}
runs as long as the varName is a valid one
(!loop scalar}
loops scalar times
(!break scalar)
break out from whil or loop, scalar levels
{!continue}
perform the next iteration of while or loop
{!inc variable scalar}
increments the value of variable with scalar
{!dec variable scalar}
decrements the value of variable with scalar
{!set variable scalar}
sets the value of variable to scalar
{!unset variable}
destroys the variable
By replacing variables with their values, the meaning changes.
(!if {variable}}
test if the varValue is not empty
{!while {variable)}
runs as long as the varValue is not empty
{!inc {variable} scalar}
increments the varValue with scalar
{!dec {variable} scalar}
decrements the varValue with scalar
{!set {variable} scalar}
sets the varValue to scalar
{!unset {variable}}
clears the varValue

Advanced Logic.

Is intended to apply logic on scalars, i.e. on varValues. This means that when {myVar} is the subject, the varValue of myVar is operated on. Implied is that a variable -as such- cannot be used.

Scope functions.

ASP tags.