| 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 |
|