 DownloadSIREN -- a Simple, Recursive, and Nimble template engine.
This library contains two classes; Snippet and Templet.
While Snippet is the workhorse, which does the parsing and recursion, Templet adds a few very usable features like including files and processing blocks.
A variable (var) is the concept to give a name to a piece of text. Snippet collects these var's in a (key, value) structured associative array.
> Technically a var exists by name and can exhibit its text (content).
The text itself may contain embedded var's. These are delimited by curly braces.
Parsing is the process of substituting these embedded var's with the content they identify. This is done recusively.
Example. $pangram = 'The quick brown fox jumps over the lazy dog.'
setVar('somename', $pangram); // defines the var 'somename'
setVar('myvar', '{somename}'); // defines the var 'myvar'
parse ('output', 'myvar'); // loads 'myVar' and substitutes embedded var's
echo ( getVar('output') ); // displays the result, stored as var 'output'
> For more examples, see demo.php.
Snippet is 'limited' to basic text lines. These can be chunks of HTML, SQL commands, nifty code lines as formatting rules, etc. Usage in three ways:
-
feed a small text and it's variables, than parse and quit,
-
feed a lot of variables (f.i. data items), than feed a small text and parse, repeat the parsing unlimited with ever changing text,
-
simulate a foreach by appending to the same var.
Templet joins the fun with
-
loading files as large texts with lots of embedded variables,
-
add (unlimited) hierachies of text's as nested template blocks,
-
simulate several foreach by appending blocks to their respective var's,
-
feature template files with a theme.
Syntax reference.
What's a var?
* syntax: {[$|?]var} where var is [text]{var}[text]
* where text is '-.:_[\w\d\]' repeated zero or more times
* example: ['a' => 'x', 'b' => 'y', 'c' => 'z', 'ayc' => 'final', 'A' => '{c}']
* {b} becomes 'y'
* a{b}c becomes 'ayc'
: {a{b}c} becomes {ayc} then becomes 'final'
* {A} becomes {c} then becomes 'z'
* A{A}A becomes A{c}A then becomes 'AzA'
: {A{A}A} becomes {A{c}A} then becomes '{AzA}' then becomes orphan
*
* gotcha: while '{a}{b}' is a correct specification, '{{a}{b}}' is not !
What's a block?
* syntax: <!?- BEGIN blockname ?->
* < specific text >
* <!?- END blockname ?->
* Blocks can be nested unlimited, as long as the blocknames are unique.
What's that '$' and '?'
A marker may start with a single '$', saying that the var is a global PHP variable. In stead of finding the var in the known var's, Snippet wil look for $GLOBALS['var'].
A marker may start with a single '?', saying that the var must not exist AND that is not an error if it doesn't. Existing var's will be replaced, and otherwise ignored /the var is never an orphan!).
Manifest (overview)
Snippet
new Snippet($orphans) // keep, remove, comment
setVar($var, $value, $append) // single, multiple items, optional bool $append
setVarData($var, $value, $append) // single, multiple items, optional bool $append
getVar($var) // returns value or empty string
contains($var) // returns true/false indicating the existence of $var
unsetVar($var) // delete $var from collection
parse($sink, $source, $append) // parse $source into $sink, optional bool $append
tidy($var, $orphans) // returns cleaned value of $var, optional orphans handling
getOrphans($var) // return array of unrecognised var's
Parse uses a recursive PCRE pattern to locate a var. Substitution occurs recursively by parsing its contents.
Templet extends Snippet
new Templet($themeDir, $orphans) // base theme directory, optional orphans handling
setTheme($themeDir, $orphans)
setFile($var, $value) // $value contains a valid filename relative to themeDir
setLazyMode($bool) // true for lazyLoad (load on reference; otherwise on setFile)
setFailMode($bool) // true for failSilent (ignore file not found)
setBlock($parent, $var, $ref) // var $parent contains a block named $var which is replaced
// by a var named $ref with value of the separated block
Parsing detects automaticly that a var is declared a file or is declared a block.
<a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" /></a><br />All Siren documentation is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.
|
