1Template::Alloy::Parse(U3s)er Contributed Perl DocumentatTieomnplate::Alloy::Parse(3)
2
3
4

NAME

6       Template::Alloy::Parse - Common parsing role for creating AST from
7       templates
8

DESCRIPTION

10       The Template::Alloy::Parse role is reponsible for storing the majority
11       of directive parsing code, as well as for delegating to the TT, HTE,
12       Tmpl, and Velocity roles for finding variables and directives.
13

ROLE METHODS

15       parse_tree
16           Used by load_tree.  This is the main grammar engine of the program.
17           It delegates to the syntax found in $self->{'SYNTAX'} (defaults to
18           'alloy') and calls the function found in the $SYNTAX hashref.  The
19           majority of these syntaxes use methods found in the $DIRECTIVES
20           hashref to parse different DIRECTIVE types for each particular
21           syntax.
22
23           A template that looked like the following:
24
25               Foo
26               [%- GET foo -%]
27               [%- GET bar -%]
28               Bar
29
30           would parse to the following AST:
31
32               [
33                   'Foo',
34                   ['GET', 6, 15, ['foo', 0]],
35                   ['GET', 22, 31, ['bar', 0]],
36                   'Bar',
37               ]
38
39           The "GET" words represent the directive used.  The 6, 15 represent
40           the beginning and ending characters of the directive in the
41           document.  The remaining items are the variables necessary for
42           running the particular directive.
43
44       parse_expr
45           Used to parse a variable, an expression, a literal string, or a
46           number.  It returns a parsed variable tree.  Samples of parsed
47           variables can be found in the VARIABLE PARSE TREE section.
48
49               my $str = "1 + 2 * 3";
50               my $ast = $self->parse_expr(\$str);
51               # $ast looks like [[undef, '+', 1, [[undef, '*', 2, 3], 0]], 0]
52
53       "parse_args"
54           Allow for the multitudinous ways that TT parses arguments.  This
55           allows for positional as well as named arguments.  Named arguments
56           can be separated with a "=" or "=>", and positional arguments
57           should be separated by " " or ",".  This only returns an array of
58           parsed variables.  To get the actual values, you must call
59           play_expr on each value.
60
61       "dump_parse_tree"
62           This method allows for returning a string of perl code representing
63           the AST of the parsed tree.
64
65           It is mainly used for testing.
66
67       "dump_parse_expr"
68           This method allows for returning a Data::Dumper dump of a parsed
69           variable.  It is mainly used for testing.
70
71       "parse_*"
72           Methods by these names are used by parse_tree to parse the
73           template.  These are the grammar.  They are used by all of the
74           various template syntaxes Unless otherwise mentioned, these methods
75           are not exposed via the role.
76

VARIABLE PARSE TREE

78       Template::Alloy parses templates into an tree of operations (an AST or
79       abstract syntax tree).  Even variable access is parsed into a tree.
80       This is done in a manner somewhat similar to the way that TT operates
81       except that nested variables such as foo.bar|baz contain the '.' or '|'
82       in between each name level.  Operators are parsed and stored as part of
83       the variable (it may be more appropriate to say we are parsing a term
84       or an expression).
85
86       The following table shows a variable or expression and the
87       corresponding parsed tree (this is what the parse_expr method would
88       return).
89
90           one                [ 'one',  0 ]
91           one()              [ 'one',  [] ]
92           one.two            [ 'one',  0, '.', 'two',  0 ]
93           one|two            [ 'one',  0, '|', 'two',  0 ]
94           one.$two           [ 'one',  0, '.', ['two', 0 ], 0 ]
95           one(two)           [ 'one',  [ ['two', 0] ] ]
96           one.${two().three} [ 'one',  0, '.', ['two', [], '.', 'three', 0], 0]
97           2.34               2.34
98           "one"              "one"
99           1 + 2              [ [ undef, '+', 1, 2 ], 0]
100           a + b              [ [ undef, '+', ['a', 0], ['b', 0] ], 0 ]
101           "one"|length       [ [ undef, '~', "one" ], 0, '|', 'length', 0 ]
102           "one $a two"       [ [ undef, '~', 'one ', ['a', 0], ' two' ], 0 ]
103           [0, 1, 2]          [ [ undef, '[]', 0, 1, 2 ], 0 ]
104           [0, 1, 2].size     [ [ undef, '[]', 0, 1, 2 ], 0, '.', 'size', 0 ]
105           ['a', a, $a ]      [ [ undef, '[]', 'a', ['a', 0], [['a', 0], 0] ], 0]
106           {a  => 'b'}        [ [ undef, '{}', 'a', 'b' ], 0 ]
107           {a  => 'b'}.size   [ [ undef, '{}', 'a', 'b' ], 0, '.', 'size', 0 ]
108           {$a => b}          [ [ undef, '{}', ['a', 0], ['b', 0] ], 0 ]
109           a * (b + c)        [ [ undef, '*', ['a', 0], [ [undef, '+', ['b', 0], ['c', 0]], 0 ]], 0 ]
110           (a + b)            [ [ undef, '+', ['a', 0], ['b', 0] ]], 0 ]
111           (a + b) * c        [ [ undef, '*', [ [undef, '+', ['a', 0], ['b', 0] ], 0 ], ['c', 0] ], 0 ]
112           a ? b : c          [ [ undef, '?', ['a', 0], ['b', 0], ['c', 0] ], 0 ]
113           a || b || c        [ [ undef, '||', ['a', 0], [ [undef, '||', ['b', 0], ['c', 0] ], 0 ] ], 0 ]
114           ! a                [ [ undef, '!', ['a', 0] ], 0 ]
115
116       Some notes on the parsing.
117
118           Operators are parsed as part of the variable and become part of the variable tree.
119
120           Operators are stored in the variable tree using an operator identity array which
121           contains undef as the first value, the operator, and the operator arguments.  This
122           allows for quickly descending the parsed variable tree and determining that the next
123           node is an operator.
124
125           Parenthesis () can be used at any point in an expression to disambiguate precedence.
126
127           "Variables" that appear to be literal strings or literal numbers
128           are returned as the literal (no operator tree).
129
130       The following perl can be typed at the command line to view the parsed
131       variable tree:
132
133           perl -e 'use Template::Alloy; print Template::Alloy->dump_parse_expr("foo.bar + 2")."\n"'
134
135       Also the following can be included in a template to view the output in
136       a template:
137
138           [% USE cet = Template::Alloy %]
139           [%~ cet.dump_parse_expr('foo.bar + 2').replace('\s+', ' ') %]
140

AUTHOR

142       Paul Seamons <paul@seamons.com>
143

LICENSE

145       This module may be distributed under the same terms as Perl itself.
146
147
148
149perl v5.36.0                      2022-07-22         Template::Alloy::Parse(3)
Impressum