SSTemplateParser
class SSTemplateParser extends Parser implements TemplateParser
This is the parser for the SilverStripe template language. It gets called on a string and uses a php-peg parser to match that string against the language structure, building up the PHP code to execute that structure as it parses
The $result array that is built up as part of the parsing (see thirdparty/php-peg/README.md for more on how parsers build results) has one special member, 'php', which contains the php equivalent of that part of the template tree.
Some match rules generate alternate php, or other variations, so check the per-match documentation too.
Terms used:
Marked: A string or lookup in the template that has been explictly marked as such - lookups by prepending with "$" (like $Foo.Bar), strings by wrapping with single or double quotes ('Foo' or "Foo")
Bare: The opposite of marked. An argument that has to has it's type inferred by usage and 2.4 defaults.
Example of using a bare argument for a loop block: <% loop Foo %>
Block: One of two SS template structures. The special characters "<%" and "%>" are used to wrap the opening and (required or forbidden depending on which block exactly) closing block marks.
Open Block: An SS template block that doesn't wrap any content or have a closing end tag (in fact, a closing end tag is forbidden)
Closed Block: An SS template block that wraps content, and requires a counterpart <% end_blockname %> tag
Angle Bracket: angle brackets "<" and ">" are used to eat whitespace between template elements N: eats white space including newlines (using in legacy _t support)
Methods
Allow the injection of new closed & open block callables
Override the function that constructs the result arrays to also prepare a 'php' item in the array
Set the closed blocks that the template parser should use
Set the open blocks that the template parser should use
Add a closed block callable to allow <% name %><% end_name %> syntax
Add a closed block callable to allow <% name %> syntax
No description
No description
No description
No description
No description
No description
No description
Values are bare words in templates, but strings in PHP. We rely on PHP's type conversion to back-convert strings to numbers when needed.
No description
No description
No description
No description
No description
The basic generated PHP of LookupStep and LastLookupStep is the same, except that LookupStep calls 'obj' to get the next ViewableData in the sequence, and LastLookupStep calls different methods (XML_val, hasValue, obj) depending on the context the lookup is used in.
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
If we get a bare value, we don't know enough to determine exactly what php would be the translation, because we don't know if the position of use indicates a lookup or a string argument.
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
As mentioned in the parser comment, block handling is kept fairly generic for extensibility. The match rule builds up two important elements in the match result array: 'ArgumentCount' - how many arguments were passed in the opening tag 'Arguments' an array of the Argument match rule result arrays
No description
No description
This is an example of a block handler function. This one handles the loop tag.
The closed block handler for with blocks
No description
No description
No description
No description
This is an open block handler, for the <% debug %> utility tag
This is an open block handler, for the <% base_tag %> tag
This is an open block handler, for the <% current_page %> tag
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
The TopTemplate also includes the opening stanza to start off the template
No description
We convert text
Compiles some passed template source code into the php code that will execute as per the template source.
Compiles some file that contains template source code, and returns the php code that will execute as per that source
Details
at line 89
__construct(array $closedBlocks = array(), array $openBlocks = array())
Allow the injection of new closed & open block callables
at line 99
construct($matchrule, $name, $arguments = null)
Override the function that constructs the result arrays to also prepare a 'php' item in the array
at line 116
setClosedBlocks(array $closedBlocks)
Set the closed blocks that the template parser should use
This method will delete any existing closed blocks, please use addClosedBlock if you don't want to overwrite
at line 132
setOpenBlocks(array $openBlocks)
Set the open blocks that the template parser should use
This method will delete any existing open blocks, please use addOpenBlock if you don't want to overwrite
at line 146
addClosedBlock(string $name, callable $callable)
Add a closed block callable to allow <% name %><% end_name %> syntax
at line 158
addOpenBlock(string $name, callable $callable)
Add a closed block callable to allow <% name %> syntax
at line 194
match_Template($stack = array())
at line 442
Template_STR($res, $sub)
at line 449
match_Word($stack = array())
at line 461
match_NamespacedWord($stack = array())
at line 473
match_Number($stack = array())
at line 485
match_Value($stack = array())
at line 497
match_CallArguments($stack = array())
at line 550
CallArguments_Argument($res, $sub)
Values are bare words in templates, but strings in PHP. We rely on PHP's type conversion to back-convert strings to numbers when needed.
at line 562
match_Call($stack = array())
at line 620
match_LookupStep($stack = array())
at line 653
match_LastLookupStep($stack = array())
at line 667
match_Lookup($stack = array())
at line 743
Lookup__construct($res)
at line 754
Lookup_AddLookupStep($res, $sub, $method)
The basic generated PHP of LookupStep and LastLookupStep is the same, except that LookupStep calls 'obj' to get the next ViewableData in the sequence, and LastLookupStep calls different methods (XML_val, hasValue, obj) depending on the context the lookup is used in.
at line 767
Lookup_LookupStep($res, $sub)
at line 772
Lookup_LastLookupStep($res, $sub)
at line 781
match_Translate($stack = array())
at line 894
match_InjectionVariables($stack = array())
at line 939
match_Entity($stack = array())
at line 951
Translate__construct($res)
at line 956
Translate_Entity($res, $sub)
at line 961
Translate_Default($res, $sub)
at line 966
Translate_Context($res, $sub)
at line 971
Translate_InjectionVariables($res, $sub)
at line 976
Translate__finalise($res)
at line 981
InjectionVariables__construct($res)
at line 986
InjectionVariables_InjectionName($res, $sub)
at line 991
InjectionVariables_Argument($res, $sub)
at line 996
InjectionVariables__finalise($res)
at line 1007
match_SimpleInjection($stack = array())
at line 1032
match_BracketInjection($stack = array())
at line 1059
match_Injection($stack = array())
at line 1090
Injection_STR($res, $sub)
at line 1097
match_DollarMarkedLookup($stack = array())
at line 1110
DollarMarkedLookup_STR($res, $sub)
at line 1117
match_QuotedString($stack = array())
at line 1153
match_FreeString($stack = array())
at line 1169
match_Argument($stack = array())
at line 1280
Argument_DollarMarkedLookup($res, $sub)
If we get a bare value, we don't know enough to determine exactly what php would be the translation, because we don't know if the position of use indicates a lookup or a string argument.
Instead, we record 'ArgumentMode' as a member of this matches results node, which can be: - lookup if this argument was unambiguously a lookup (marked as such) - string is this argument was unambiguously a string (marked as such, or impossible to parse as lookup) - default if this argument needs to be handled as per 2.4
In the case of 'default', there is no php member of the results node, but instead 'lookup_php', which should be used by the parent if the context indicates a lookup, and 'string_php' which should be used if the context indicates a string
at line 1286
Argument_QuotedString($res, $sub)
at line 1292
Argument_Lookup($res, $sub)
at line 1304
Argument_FreeString($res, $sub)
at line 1312
match_ComparisonOperator($stack = array())
at line 1423
match_Comparison($stack = array())
at line 1456
Comparison_Argument($res, $sub)
at line 1469
Comparison_ComparisonOperator($res, $sub)
at line 1476
match_PresenceCheck($stack = array())
at line 1519
PresenceCheck_Not($res, $sub)
at line 1524
PresenceCheck_Argument($res, $sub)
at line 1538
match_IfArgumentPortion($stack = array())
at line 1569
IfArgumentPortion_STR($res, $sub)
at line 1576
match_BooleanOperator($stack = array())
at line 1604
match_IfArgument($stack = array())
at line 1653
IfArgument_IfArgumentPortion($res, $sub)
at line 1658
IfArgument_BooleanOperator($res, $sub)
at line 1665
match_IfPart($stack = array())
at line 1708
match_ElseIfPart($stack = array())
at line 1751
match_ElsePart($stack = array())
at line 1786
match_If($stack = array())
at line 1842
If_IfPart($res, $sub)
at line 1850
If_ElseIfPart($res, $sub)
at line 1858
If_ElsePart($res, $sub)
at line 1868
match_Require($stack = array())
at line 1929
Require_Call($res, $sub)
at line 1944
match_CacheBlockArgument($stack = array())
at line 2041
CacheBlockArgument_DollarMarkedLookup($res, $sub)
at line 2046
CacheBlockArgument_QuotedString($res, $sub)
at line 2051
CacheBlockArgument_Lookup($res, $sub)
at line 2058
match_CacheBlockArguments($stack = array())
at line 2106
CacheBlockArguments_CacheBlockArgument($res, $sub)
at line 2120
match_CacheBlockTemplate($stack = array())
at line 2338
match_UncachedBlock($stack = array())
at line 2491
UncachedBlock_Template($res, $sub)
at line 2499
match_CacheRestrictedTemplate($stack = array())
at line 2747
CacheRestrictedTemplate_CacheBlock($res, $sub)
at line 2753
CacheRestrictedTemplate_UncachedBlock($res, $sub)
at line 2765
match_CacheBlock($stack = array())
at line 3001
CacheBlock__construct($res)
at line 3006
CacheBlock_CacheBlockArguments($res, $sub)
at line 3011
CacheBlock_Condition($res, $sub)
at line 3016
CacheBlock_CacheBlock($res, $sub)
at line 3021
CacheBlock_UncachedBlock($res, $sub)
at line 3026
CacheBlock_CacheBlockTemplate($res, $sub)
at line 3063
match_OldTPart($stack = array())
at line 3173
match_N($stack = array())
at line 3184
OldTPart__construct($res)
at line 3189
OldTPart_QuotedString($res, $sub)
at line 3199
OldTPart_CallArguments($res, $sub)
at line 3204
OldTPart__finalise($res)
at line 3211
match_OldTTag($stack = array())
at line 3236
OldTTag_OldTPart($res, $sub)
at line 3243
match_OldSprintfTag($stack = array())
at line 3296
OldSprintfTag__construct($res)
at line 3301
OldSprintfTag_OldTPart($res, $sub)
at line 3306
OldSprintfTag_CallArguments($res, $sub)
at line 3313
match_OldI18NTag($stack = array())
at line 3344
OldI18NTag_STR($res, $sub)
at line 3351
match_NamedArgument($stack = array())
at line 3381
NamedArgument_Name($res, $sub)
at line 3386
NamedArgument_Value($res, $sub)
at line 3405
match_Include($stack = array())
at line 3482
Include__construct($res)
at line 3487
Include_Template($res, $sub)
at line 3492
Include_NamedArgument($res, $sub)
at line 3497
Include__finalise($res)
at line 3516
match_BlockArguments($stack = array())
at line 3565
match_NotBlockTag($stack = array())
at line 3720
match_ClosedBlock($stack = array())
at line 3828
ClosedBlock__construct($res)
As mentioned in the parser comment, block handling is kept fairly generic for extensibility. The match rule builds up two important elements in the match result array: 'ArgumentCount' - how many arguments were passed in the opening tag 'Arguments' an array of the Argument match rule result arrays
Once a block has successfully been matched against, it will then look for the actual handler, which should be on this class (either defined or extended on) as ClosedBlock_Handler_Name(&$res), where Name is the tag name, first letter captialized (i.e Control, Loop, With, etc).
This function will be called with the match rule result array as it's first argument. It should return the php result of this block as it's return value, or throw an error if incorrect arguments were passed.
at line 3833
ClosedBlock_BlockArguments($res, $sub)
at line 3844
ClosedBlock__finalise($res)
at line 3862
ClosedBlock_Handle_Loop($res)
This is an example of a block handler function. This one handles the loop tag.
at line 3893
ClosedBlock_Handle_With($res)
The closed block handler for with blocks
at line 3914
match_OpenBlock($stack = array())
at line 3976
OpenBlock__construct($res)
at line 3981
OpenBlock_BlockArguments($res, $sub)
at line 3992
OpenBlock__finalise($res)
at line 4010
OpenBlock_Handle_Debug($res)
This is an open block handler, for the <% debug %> utility tag
at line 4031
OpenBlock_Handle_Base_tag($res)
This is an open block handler, for the <% base_tag %> tag
at line 4042
OpenBlock_Handle_Current_page($res)
This is an open block handler, for the <% current_page %> tag
at line 4052
match_MismatchedEndBlock($stack = array())
at line 4079
MismatchedEndBlock__finalise($res)
at line 4088
match_MalformedOpenTag($stack = array())
at line 4166
MalformedOpenTag__finalise($res)
at line 4174
match_MalformedCloseTag($stack = array())
at line 4231
MalformedCloseTag__finalise($res)
at line 4240
match_MalformedBlock($stack = array())
at line 4274
match_Comment($stack = array())
at line 4325
Comment__construct($res)
at line 4333
match_TopTemplate($stack = array())
at line 4605
TopTemplate__construct($res)
The TopTemplate also includes the opening stanza to start off the template
at line 4619
match_Text($stack = array())
at line 4826
Text__finalise($res)
We convert text
at line 4865
string
compileString(string $string, string $templateName = "", bool $includeDebuggingComments = false, bool $topTemplate = true)
Compiles some passed template source code into the php code that will execute as per the template source.
at line 4944
mixed|string
compileFile($template)
Compiles some file that contains template source code, and returns the php code that will execute as per that source