File: siren.usage.md

Introduction

A lot of template engines just replace markers in a text by other text. The concept of boilerplate is their base feature. SIREN adds recursion to these markers, and inherently allows for (recursive) markers in the boilerplate text. In SIREN, markers are called variables, and they have a value that will replace the markers. So, intuitively a variable stands for its value in template texts.

Not just for Templates

The Snippet class, being the workhorse of SIREN, has no bias for HTML, XML, or whatever. Its engine lacks any sophisticated feature and focusses on strings only. This makes Snippet an ideal utility to generate structured texts. Like texts that must adhere some structure, say some syntax. A beautyfull example on SQL statements can be found in the directory examples.

Benefits

Benefits of SIREN include:

• It is very easy: no kowledge of programming necessary.
• It is very fast: it beats loading of files easily.
• It uses recursion: it makes defining markers an intuitive task.

Template Variable Naming Conventions

Template variables follow a flexible naming convention. A variable name may consist of letters, digits, one or more underscore, period, dash or square brackets. A variable name must be delimited by curly brackets:

Show {my_template_variable} right here  
Your id is {vip.customer.order}  
The spreadsheet cell a15b contains {a15b}   

If a variable name is invalid, aka does not match the convention above, the complete marker is left as is. However, and now recursion comes into action, a variable name can be 'nested':

{{type}.customer} where {type} is first replaced, f.i. by 'vip'  
{vip.{relation}} where {relation} is first replaced, f.i. by 'customer'  
{{a15b}} where the spreadsheet cell is first replaced by its value, giving a new variable named to whatever the content of that cell contains  

So far so good: using recursive variables results in new variable names, which will have a value too. What if that (new) value contains a valid variable name, that is replaced and forms a new variable name that is nested again? Well, intuitively recursion repeats itself on that newly formed variable:

{{type}.{relation}} replaces {type}, than {relation}, and finally {vip.customer}  
{a15b} contains {d21e}, meaning a link to another cell in the spreadsheet  

What this means, is that the recursive replacement task processes the complete text until all variables are detected and replaced. And SIREN does that in one go. Invalid variable names, and not recognised variables as well, are left as is. After processing one can tell Snippet to keep those variables in the resulting text, have them removed, or to comment them out as HTML comments.

Have a look at the demo.php file in the root directory.

Not naming, but an extended feature!

A variable name can start with a dollar sign or a question mark. This changes the meaning of a variable:

• $ : the variable is looked for in the global space, like `$myvar := $GLOBALS['myVar']`
• ? : the variable may or may not exist; if it does not exist the marker is deleted and wil not be recognised as an orphan.

Usage

• setVar($varName, $varvalue) defines a variable and its value
• getVar($varname) retrieves the valuze of a defined variable
• parse($newVarName, $varName) parses recursively a defined variable and stores it as a new variable $newVarName

• tidy($varName, $parameter) cleans the variable and returns the results

  $snippet->setVar('text', '{{type}.{relation}}');

  $snippet->setVar('type', 'vip'); $snippet->setVar('relation', 'customer'; $snippet->setVar('vip.customer', 'you are a vip');

  $snippet->parse('result', 'text'); echo tidy('result', 'keep')

Advanced Usage

Snippet contains a mechanism to throttle the recursion depth. The reason is that often variables contain values from the outside, i.e. data out of control by the designer, which may or may not contain the marker delimiters '{' or '}'. Recursion can be limited to a 'match' on variable name (basic), avoiding recursion in the value of recognised variables. For debugging purposes there is the setting 'raw' and 'none'. Default is smart recursion, triggerd by 'auto'. Unlimited recursion is restored by the setting 'deep'. To escape recursive parsing of the value, regardless of recursionDepth, one can set the value of a variable as non-parsable.

$snippet->setDepth($setting) for 'none', basic', 'auto', 'deep'  
$snippet->setVarData($varName, $value) defines a variable with non-parsable value  

Finally, some general methods are available:

$nippet->contains($varName) returns true/false to show existence of a variable  
$nippet->getVars() returns the full array af variables with their values  
$snippet->clear() clears the values of all variables  
$snippet->clearVar($varName) clears the value of a variable  
$snippet->unsetVar($varname) unsets a variable  
$snippet->getOrphans($varName) returns all not-recognised variables within the variable  

Tip 'n Tricks

The setVar method has three forms:

• setVar($varName, $varValue); regular form: single variable, single value
• setVar($varNamesArray); advanced form: associative array of key => value
• setVar($varName, $varValueArray); very advanced form: single variable with multiple values

The advanced form causes the definition for every key with its respective value. The very advanced form results in variables that contain references using square brackets, a bit like you would code them in php. Please note tha square brackets are valid characters in the variable name.

$myArray = ['a' =>'A', 'b' => 'B'];  
setVar($myArray); results in two variables, named a and b, with values 'A' and 'B'  
$myArray = ['EU' => 'Europe', 'A' => 'Africa'];  
setVar('continent', $myArray); results in two variables named continent[EU] and continent[A],
                                 with the values 'Europe' and 'Africa'  

Please note the absence of quotes in the variable names in above example.

The getVar call has two forms:

getVar($varName) returns the value of the variable  
getVar($varNamesArray) return all values of the named variables  

This array is definitely a simple array with numeric keys.

Gotcha's

• So, setting variables using setVar($myArray) would work, while getVar($myArray) would NOT work. Instead use getVar( array_keys($myArray) ).
• Same goes for clearVar($myArray). One easily mistakes here when processing data from mySql as rows: setVar($row) and clearVar(array_keys($row)).