Debian Codegraph @

README

raw
1 NAME
2 Filter::Template - a source filter for inline code templates (macros)
3
4 VERSION
5 version 1.043
6
7 SYNOPSIS
8 use Filter::Template;
9
10 # use Filter::Template ( isa => 'SomeModule' );
11
12 template max (one,two) {
13 ((one) > (two) ? (one) : (two))
14 }
15
16 print {% max $one, $two %}, "\n";
17
18 const PI 3.14159265359
19
20 print "PI\n"; # Constants are expanded inside strings.
21 print "HAPPINESS\n"; # Also expanded due to naive parser.
22
23 enum ZERO ONE TWO
24 enum 12 TWELVE THIRTEEN FOURTEEN
25 enum + FIFTEEN SIXTEEN SEVENTEEN
26
27 # Prints numbers, due to naive parser.
28 print "ZERO ONE TWO TWELVE THIRTEEN FOURTEEN FIFTEEN SIXTEEN SEVENTEEN\n";
29
30 if ($expression) { # include
31 ... lines of code ...
32 } # include
33
34 unless ($expression) { # include
35 ... lines of code ...
36 } elsif ($expression) { # include
37 ... lines of code ...
38 } else { # include
39 ... lines of code ...
40 } # include
41
42 DESCRIPTION
43 Filter::Template is a Perl source filter that provides simple inline
44 source code templates. Inlined source code can be significantly faster
45 than subroutines, especially for small-scale functions like accessors
46 and mutators. On the other hand, they are more difficult to maintain and
47 use. Choose your trade-offs wisely.
48
49 Templates
50 Code templates are defined with the "template" statement, which looks a
51 lot like "sub". Because this is a naive source filter, however, the open
52 brace must be on the same line as the "template" keyword. Furthermore,
53 the first closing brace in column zero ends a macro body.
54
55 template oops {
56 die "Oops";
57 }
58
59 Templates are inserted into a program using a simple syntax that was
60 adapted from other template libraries. It was chosen to be compatible
61 with the Perl syntax highlighting of common text editors.
62
63 This inserts the body of "template oops".
64
65 {% oops %}
66
67 Templates can have parameters. The syntax for template parameters was
68 based on prototypes for Perl subroutines. The two main differences are
69 that parameters are named, and sigils are not used.
70
71 template sum_2 (parameter_0, parameter_1) {
72 print( parameter_0 + parameter_1, "\n" );
73 }
74
75 To insert a template with parameters, simply list the parameters after
76 the template name.
77
78 {% sum_2 $base, $increment %}
79
80 At expansion time, occurrences of the parameter names within the
81 template are replaced with the source code provided in the template
82 invocation. In the previous example, "sum_2" literally expands to
83
84 print( $base + $increment, "\n" );
85
86 and is then compiled by Perl.
87
88 Constants and Enumerations
89 Filter::Template also defines "const" and "enum" keywords. They are
90 essentially simplified templates without parameters.
91
92 "const" defines a constant that is replaced before compile time. Unlike
93 Perl's native constants, these are not demoted to function calls when
94 Perl is run in debugging or profiling mode.
95
96 const CONSTANT_NAME 'constant value'
97 const ANOTHER_CONSTANT 23
98
99 Enumerations are like constants but several sequential integers can be
100 defined in one statement. Enumerations start from zero by default:
101
102 enum ZEROTH FIRST SECOND
103
104 If the first parameter of an enumeration is a number, then the
105 enumerated constants will start with that value:
106
107 enum 10 TENTH ELEVENTH TWELFTH
108
109 Enumerations may not span lines, but they can be continued. If the first
110 enumeration parameter is the plus sign, then constants will start where
111 the previous enumeration left off.
112
113 enum 13 THIRTEENTH FOURTEENTH FIFTEENTH
114 enum + SIXTEENTH SEVENTEENTH EIGHTEENTH
115
116 Conditional Code Inclusion (#ifdef)
117 The preprocessor supports something like cpp's #if/#else/#endif by
118 usurping a bit of Perl's conditional syntax. The following conditional
119 statements will be evaluated at compile time if they are followed by the
120 comment "# include":
121
122 if (EXPRESSION) { # include
123 BLOCK;
124 } elsif (EXPRESSION) { # include
125 BLOCK;
126 } else { # include
127 BLOCK;
128 } # include
129
130 unless (EXPRESSION) { # include
131 BLOCK;
132 } # include
133
134 The code in each conditional statement's BLOCK will be included or
135 excluded in the compiled code depending on the outcome of its
136 EXPRESSION.
137
138 Conditional includes are nestable, but else and elsif must be on the
139 same line as the previous block's closing brace, as they are in the
140 previous example.
141
142 Filter::Template::UseBytes uses conditional code to define different
143 versions of a {% use_bytes %} macro depending whether the "bytes" pragma
144 exists.
145
146 IMPORTING TEMPLATES
147 Filter::Template can import templates defined by another class. For
148 example, this invocation imports the "use_bytes" template:
149
150 use Filter::Template ( isa => 'Filter::Template::UseBytes' );
151
152 Imported templates can be redefined in the current namespace.
153
154 Note: If the imported templates require additional Perl modules, any
155 code which imports them must also "use" those modules.
156
157 DEBUGGING
158 Filter::Template has three debugging constants which will only take
159 effect if they are defined before the module is first used.
160
161 To trace source filtering in general, and to see the resulting code and
162 operations performed on each line, define:
163
164 sub Filter::Template::DEBUG () { 1 }
165
166 To trace template invocations as they happen, define:
167
168 sub Filter::Template::DEBUG_INVOKE () { 1 }
169
170 To see template, constant, and enum definitions, define:
171
172 sub Filter::Template::DEBUG_DEFINE () { 1 }
173
174 To see warnings when a template or constant is redefined, define:
175
176 sub Filter::Template::DEFINE () { 1 }
177
178 CAVEATS
179 Source filters are line-based, and so is the template language. The only
180 constructs that may span lines are template definitions, and those must
181 span lines.
182
183 Filter::Template does not parse perl. The regular expressions that
184 detect and replace code are simplistic and may not do the right things
185 when parsing challenging Perl syntax. Constants are replaced within
186 strings, for example.
187
188 The regexp optimizer makes silly subexpressions like /(?:|m)/. That
189 could be done better as /m?/ or /(?:jklm)?/ if the literal is longer
190 than a single character.
191
192 The regexp optimizer does not optimize (?:x|y|z) as character classes.
193
194 The regexp optimizer is based on code in Ilya Zakharevich's Text::Trie.
195 Better regexp optimizers were released afterwards, and Filter::Template
196 should use one of them.
197
198 LINKS
199 BUG TRACKER
200 https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=Filter-Templat
201 e
202
203 REPOSITORY
204 http://github.com/rcaputo/filter-template
205 http://gitorious.org/filter-template
206
207 OTHER RESOURCES
208 http://search.cpan.org/dist/Filter-Template/
209
210 SEE ALSO
211 Text::Trie, PAR, Filter::Template::UseBytes.
212
213 AUTHOR & COPYRIGHT
214 Filter::Template is Copyright 2000-2013 Rocco Caputo. Some parts are
215 Copyright 2001 Matt Cashner. All rights reserved. Filter::Template is
216 free software; you may redistribute it and/or modify it under the same
217 terms as Perl itself.
218
219 Filter::Template was previously known as POE::Preprocessor.
220