File: recursion.md

Howto use recursion in SIREN using simple PHP

Basic requirements are a text containing (named) markers and an array that maps these markers to replacement text. The text itself has a name too and is also contained in the array. What SIREN does is scan the text, detect the marker, extract its name and replace it with the corresponding text found in the array. In SIREN the (named) markers are called variables and they have a (mapped) value (replacement text).

Example 1.  Regular usage, no recursion. 
The text 'My name is {firstName} {middleName} {lastName)'  
The array {'firstName' => 'Martin', 'lastName' => 'King', middleName => 'Luther']  
    $snippet = new Snippet();  
    $snippet->setVar('text', 'My name is {firstName} {middleName} {lastName)');  
    $snippet->setVar('firstName',  'Martin');  
    $snippet->setVar('middleName', 'Luther');  
    $snippet->setVar('lastName',   'King');  
echo $snippet->parse('output', 'text');  // My name is Martin Luther King   

Let's adjust the example with a more sophisticated example: define a variable 'fullName' that has embedded the individual name parts. Punctuation could be added.

Example 2.  Basic usage, no recursion.
The text 'My name is {fullName}'  
    $snippet->setVar('fullName', '{firstName} {middleName} {lastName}');  
echo $snippet->parse('output', 'text');  // My name is {firstName} {middleName} {lastName}   
echo $snippet->parse('final', 'output'); // My name is Martin Luther King   

So far so good. We've embedded some variables in the value of the variable 'fullName'. And in simple cases like this one, and without recursion we can and must parse the text twice. But this is dropping a dependency into your code. A dependency on the structure of the main variable 'fullName' and the embedded variables with their respective values. However with recursion, this example would reduce to

echo $snippet->parse('final', 'text');  // My name is Martin Luther King 

And this makes sense since we rather would define

$snippet->setVar('fullName', '{lastName}, {firstName} {middleName}';

to have an output like 'My name is King, Martin Luther'.

This shows that SIREN replaces the variable 'fullName' with text that embeds a few other variables, which is detected by SIREN, and results in replacing those embedded variables with their respective values. All in one go.

Example 3.  Advanced usage, no recursion.
The text 'I am greeting you on behalf of {someHuman}'    
    $snippet->setVar('someHuman', '{fullName}');  
    $snippet->setVar('fullName', '{firstName} {middleName} {lastName}');  
echo $snippet->parse('pass1', 'text');    // I am greeting you on behalf of {fullName}   
echo $snippet->parse('pass2', 'pass1');   // I am greeting you on behalf of {firstName} {middleName} {lastName}   
echo $snippet->parse('output', 'pass2');  // I am greeting you on behalf of Martin Luther King   

In above example we need to parse the text three times. This is the case where recursion comes in very handy,and this example would reduce to

    echo $snippet->parse('output','text'); // I am greeting you on behalf of Martin Luther King   

because SIREN detects that the replaced text of a variable contains embedded variables and parses them automatically, detects that ...... etc.

# 1. So, in example 2 'fullName' is replaced by '{firstName} {middleName} {lastName}' is replaced by their final values # 2. And, in example 3, 'someHuman' is replaced by '{fullName}', is replaced again by, using recursion, see (1)

Real benefit is found when you abstract your templates with symbolic variables. Like the date needs different formats depending on the locale, the name must be written differently depending on the audience. Americans are used to 'Martin Luther King' or 'Martin L. King', and europeans merely use 'King, Martin Luther' or 'King, M.L.'.

Example 4.  Setup for a variable format of fullName  
    $snippet->setVar('firstName', 'Martin'};  
    $snippet->setVar('middleName', 'Luther'};  
    $snippet->setVar('lastName', 'King'};  
    $snippet->setVar('initials', 'M.L.'};  
    $snippet->setVar('shortMiddleName', 'L.'};  
if (audienceIsAmerican) {  
    $snippet->setVar('fullName', '{firstName} {middleName} {lastName}');  
} elseif(audienceIsEuropean){  
    $snippet->setVar('fullName', '{lastName}, {initials}');  
} else {  
    $snippet->setVar('fullName', '{lastName}, {firstName}');  
}  

Than, there is also a difference in usage of a fullName, a commonName and a officialName.

Example 5.  Setup for a variable format of people's name  
if (audienceIsAmerican) {  
    $snippet->setVar('fullName', '{firstName} {middleName} {lastName}');  
    $snippet->setVar('commonName', '{firstName} {shortMiddleName} {lastName}');  
    $snippet->setVar('officialName', '{lastName}, {firstName} {shortMiddleName} ');  
} elseif(audienceIsEuropean){  
    $snippet->setVar('fullName', '{lastName}, {initials}');  
    $snippet->setVar('commonName', '{lastName}, {firstName} {shortMiddleName}');  
    $snippet->setVar('officialName', '{lastName}, {initials}');  
} else {  
    $snippet->setVar('fullName', '{lastName}, {firstName}');  
    $snippet->setVar('commonName', '{firstName} {lastName} {middleName}');  
    $snippet->setVar('officialName', '{lastName}, {initials}');  
}

In above examples, one could use the variables 'fullName', 'commonName' and 'officialName' at will in the templates, getting every time a correct spelling. It's a matter of assigning the right variables, and the design of the result is separated from your coding. And there is more. Suppose the legal department does not allow the free usage and wants the choice of name-format should be in the code.

Example 6.  Setup for a variable format of people's name, fixed in the script  
if (invoicePrinting) {  
    $snippet->setVar('typeOf', 'official');  
} elseif(letterPrinting){  
    $snippet->setVar('typeOf', 'common');  
} else {  
    $snippet->setVar('typeOf', 'full');  
}
The template text must now be: 'My name is {{typeOf}Name}.'

# 3. So, in example 6, the variable {typeOf}Name is first replaced by 'fullName', 'commonName' or 'officialName' and the resulting variable is recursive replaced.

In SIREN the depth of the recursion can be set:

• NONE: limit recursion to simple replacements; see examples 1 - 3
• BASIC: limit recursion to variable names; see example 6
• AUTO: decend into files and blocks by default (templet class)
• DEEP: full recursion: all variables act as template components; see examples 4 - 6

For more fine examples see demo.php.