Lines Matching refs:the
7 # You may copy and distribute this program under the
90 # are tainted, all the others become tainted too as a result of
91 # sharing the expression with them. We install $source separately
103 # in which the template data is embedded in the object itself.
357 # Big fat magic here: Fix it so that the user-specified package
358 # is the default one available in the safe compartment.
401 # If the value of the filled-in text really was undef,
553 # install the variables into the specified package,
660 # Note that this is *faster* than using the default delimiters
684 `fill in' a template, you evaluate the little programs and replace
688 modify the template without modifying the program. You can separate
689 the formatting details from the main code, and put the formatting
690 parts of the program into the template. That prevents code bloat and
695 Here's an example of a template, which we'll suppose is stored in the
724 Here is a complete program that transforms the example
725 template into the example result, and prints it out:
750 they build it so that a string like C<%%VAR%%> is replaced with the
751 value of C<$VAR>. Then they realize the need extra formatting, so
757 crippled. If you need to do something the author hasn't thought of,
762 code in your template, with C<{> at the beginning and C<}> at the end.
763 If you want a variable interpolated, you write it the way you would in
764 Perl. If you need to make a loop, you can use any of the Perl loop
765 constructions. All the Perl built-in functions are available.
771 The C<Text::Template> module scans the template source. An open brace
772 C<{> begins a program fragment, which continues until the matching
773 close brace C<}>. When the template is filled in, the program
774 fragments are evaluated, and each one is replaced with the resulting
775 value to yield the text that is returned.
788 failure code and a warning about where the problem is. Backslashes
794 The backslash inside the string is passed through to Perl unchanged,
795 so the C<\n> really does turn into a newline. See the note at the end
796 for details about the way backslashes work. Backslash processing is
797 I<not> done when you specify alternative delimiters with the
801 are evaluated the usual way. The result of the last statement
802 executed will be evaluated in scalar context; the result of this
803 statement is a string, which is interpolated into the template in
804 place of the program fragment itself.
822 The value of C<$x> set in the first line will persist into the next
823 fragment that begins on the third line, and the values of C<$diff> and
824 C<$more> set in the second fragment will persist and be interpolated
825 into the last line. The output will look something like this:
832 That is all the syntax there is.
836 There is one special trick you can play in a template. Here is the
838 into the template, and you want the template to generate a bulleted
841 Here is a list of the things I have got for you since 1907:
849 Here is a list of the things I have got for you since 1907:
857 Here we construct the list in a variable called C<$blist>, which we
858 return at the end. This is a little cumbersome. There is a shortcut.
861 Anything you append to this variable will appear in the output of the
862 template. Also, if you use C<$OUT> in a program fragment, the normal
863 behavior, of replacing the fragment with its return value, is
864 disabled; instead the fragment is replaced with the value of C<$OUT>.
865 This means that you can write the template above like this:
867 Here is a list of the things I have got for you since 1907:
873 C<$OUT> is reinitialized to the empty string at the start of each
876 invoking the special behavior.
880 All C<Text::Template> functions return C<undef> on failure, and set the
892 C<undef> and sets C<$Text::Template::ERROR> if it can't create the
893 template object. C<SOURCE> says where the template source code will
894 come from. C<TYPE> says what kind of object the source is.
900 This reads the template from the specified file. The filename is
901 opened with the Perl C<open> command, so it can be a pipe or anything
904 The C<TYPE> can also be C<STRING>, in which case the C<SOURCE> should
908 SOURCE => "This is the actual template!" );
910 The C<TYPE> can be C<ARRAY>, in which case the source should be a
912 is the template:
915 SOURCE => [ "This is ", "the actual",
920 The C<TYPE> can be FILEHANDLE, in which case the source should be an
921 open filehandle (such as you got from the C<FileHandle> or C<IO::*>
923 C<Text::Template> will read the text from the filehandle up to
924 end-of-file, and that text is the template:
930 If you omit the C<TYPE> attribute, it's taken to be C<FILE>.
931 C<SOURCE> is required. If you omit it, the program will abort.
933 The words C<TYPE> and C<SOURCE> can be spelled any of the following ways:
950 string is the string that signals the beginning of each program
951 fragment, and the second string is the string that signals the end of
956 You may also add a C<ENCODING> option. If this option is present, and the
957 C<SOURCE> is a C<FILE>, then the data will be decoded from the given encoding
958 using the L<Encode> module. You can use any encoding that L<Encode> recognizes.
971 evaluate the Perl code in the file. (It is afraid that a malicious
972 person might have tampered with the file.)
976 C<UNTAINT =E<gt> 1> in the call to C<new>. This will tell
978 come from a file, as long as the filename itself is considered
990 This option is passed along to the C<fill_in> call unless it is
991 overridden in the arguments to C<fill_in>. See L<C<PREPEND> feature
996 This option is passed along to the C<fill_in> call unless it is
997 overridden in the arguments to C<fill_in>. See L<C<BROKEN>> below.
1005 Loads all the template text from the template's source, parses and
1007 sets C<$Text::Template::ERROR>. If the template is already compiled,
1011 (see below) compiles the template if it isn't compiled already.
1021 Fills in a template. Returns the resulting text if successful.
1025 write the key names in any of the six usual styles as above; this
1036 so you might like to avoid them and use the capitalized versions.
1045 C<PACKAGE> specifies the name of a package in which the program
1046 fragments should be evaluated. The default is to use the package from
1049 The value of the variable x is {$x}.
1051 If you use C<$template-E<gt>fill_in(PACKAGE =E<gt> 'R')> , then the C<$x> in
1052 the template is actually replaced with the value of C<$R::x>. If you
1053 omit the C<PACKAGE> option, C<$x> will be replaced with the value of
1054 the C<$x> variable in the package that actually called C<fill_in>.
1058 back into the main program. Evaluating the template in a private
1061 See the section at the end on `Security'.
1079 We want to pass in an array which will be assigned to the array
1086 had a variable named C<$item_no> in scope in your program at the point
1087 you called C<fill_in>, its value would be clobbered by the act of
1088 filling out the template. The problem is the same as if you had
1089 written a subroutine that used those variables in the same way that
1090 the template does. (C<$OUT> is special in templates and is always
1093 One solution to this is to make the C<$item_no> variable private to the
1094 template by declaring it with C<my>. If the template does this, you
1097 But if you use the C<PACKAGE> option, you will probably be safe even
1098 if the template does I<not> declare its variables with C<my>:
1103 In this case the template will clobber the variable C<$Q::item_no>,
1104 which is not related to the one your program was using.
1106 Templates cannot affect variables in the main program that are
1107 declared with C<my>, unless you give the template references to those
1112 You may not want to put the template variables into a package.
1127 will fill out the template and use C<"The King"> as the value of
1128 C<$recipient> and the list of items as the value of C<@items>. Note
1129 that we pass an array reference, but inside the template it appears as
1134 pass a reference to the object, C<\$self> instead. Since we've passed
1135 a reference to a scalar, inside the template the object appears as
1139 want to skip to the next section.
1141 Suppose the key in the hash is I<key> and the value is I<value>.
1147 If the I<value> is C<undef>, then any variables named C<$key>,
1152 If the I<value> is a string or a number, then C<$key> is set to that
1153 value in the template.
1159 If the I<value> is a reference to an array, then C<@key> is set to
1160 that array. If the I<value> is a reference to a hash, then C<%key> is
1170 have almost exactly the same effect. (The difference is that in the
1171 former case, the value is copied, and in the latter case it is
1176 In particular, if you want the template to get an object or any kind,
1181 If you do this, the template will have a variable C<$database_handle>
1182 which is the database handle object. If you leave out the C<\>, the
1183 template will have a hash C<%database_handle>, which exposes the
1184 internal structure of the database handle object; you don't want that.
1188 Normally, the way this works is by allocating a private package,
1189 loading all the variables into the package, and then filling out the
1191 allocated each time. However, if you I<also> use the C<PACKAGE>
1192 option, C<Text::Template> loads the variables into the package you
1193 specified, and they stay there after the call returns. Subsequent
1194 calls to C<fill_in> that use the same package will pick up the values
1197 If the argument of C<HASH> is a reference to an array instead of a
1198 reference to a hash, then the array should contain a list of hashes
1199 whose contents are loaded into the template package one after the
1201 of variables. For example, one set of variables might be the defaults
1202 for a fill-in form, and the second set might be the user inputs, which
1203 override the defaults when they are present:
1207 You can also use this to set two variables with the same name:
1220 If any of the program fragments fails to compile or aborts for any
1221 reason, and you have set the C<BROKEN> option to a function reference,
1222 C<Text::Template> will invoke the function. This function is called
1223 the I<C<BROKEN> function>. The C<BROKEN> function will tell
1226 If the C<BROKEN> function returns C<undef>, C<Text::Template> will
1227 immediately abort processing the template and return the text that it
1232 If the C<BROKEN> function returns any other value, that value will be
1233 interpolated into the template as if that value had been the return
1234 value of the program fragment to begin with. For example, if the
1235 C<BROKEN> function returns an error string, the error string will be
1236 interpolated into the output of the template in place of the program
1237 fragment that cased the error.
1245 (Note that the format of this message has changed slightly since
1246 version 1.31.) The return value of the C<BROKEN> function is
1247 interpolated into the template at the place the error occurred, so
1256 If you specify a value for the C<BROKEN> attribute, it should be a
1257 reference to a function that C<fill_in> can call instead of the
1260 C<fill_in> will pass a hash to the C<broken> function.
1267 The source code of the program fragment that failed
1271 The text of the error message (C<$@>) generated by eval.
1273 The text has been modified to omit the trailing newline and to include
1274 the name of the template file (if there was one). The line number
1275 counts from the beginning of the template, not from the beginning of
1276 the failed program fragment.
1280 The line number of the template at which the program fragment began.
1288 If you supply the C<BROKEN_ARG> option to C<fill_in>, the value of the
1289 option is passed to the C<BROKEN> function whenever it is called. The
1290 default C<BROKEN> function ignores the C<BROKEN_ARG>, but you can
1291 write a custom C<BROKEN> function that uses the C<BROKEN_ARG> to get
1294 The C<BROKEN> function could also use the C<BROKEN_ARG> as a reference
1296 communicate back to the caller. For example:
1317 If one of the program fragments in the template fails, it will call
1318 the C<BROKEN> function, C<my_broken>, and pass it the C<BROKEN_ARG>,
1320 message into C<$error> this way. Then the function that called
1326 If you give C<fill_in> a C<FILENAME> option, then this is the file name that
1327 you loaded the template source from. This only affects the error message that
1328 is given for template errors. If you loaded the template from C<foo.txt> for
1329 example, and pass C<foo.txt> as the C<FILENAME> parameter, errors will look
1332 Note that this does NOT have anything to do with loading a template from the
1350 compartment object from the C<Safe> package. All evaluation of
1352 for full details about such compartments and how to restrict the
1355 If you use the C<PACKAGE> option with C<SAFE>, the package you specify
1356 will be placed into the safe compartment and evaluation will take
1359 If not, C<SAFE> operation is a little different from the default.
1361 fragments occurs in the package from which the template was invoked.
1362 But in C<SAFE> mode the evaluation occurs inside the safe compartment
1363 and cannot affect the calling package. Normally, if you use C<HASH>
1364 without C<PACKAGE>, the hash variables are imported into a private,
1366 without C<PACKAGE>, the hash variables will just be loaded into the
1367 root namespace of the C<Safe> compartment.
1373 C<Text::Template> print out the text as it is generated instead of
1374 making it into a big string and returning the string. If you supply
1375 the C<OUTPUT> option to C<fill_in>, the value should be a filehandle.
1381 fills in the C<$template> as usual, but the results are immediately
1382 printed to STDOUT. This may result in the output appearing more
1385 If you use C<OUTPUT>, the return value from C<fill_in> is still true on
1386 success and false on failure, but the complete text is not returned to
1387 the caller.
1391 You can have some Perl code prepended automatically to the beginning
1398 of two strings. The first string is the string that signals the
1399 beginning of each program fragment, and the second string is the
1400 string that signals the end of each program fragment. See
1403 If you specify C<DELIMITERS> in the call to C<fill_in>, they override
1404 any delimiters you set when you created the template object with
1415 the same template more than once.
1418 string, which contains the template, and a list of options, which are
1419 passed to C<fill_in> as above. It constructs the template object for
1420 you, fills it in as specified, and returns the results. It returns
1438 Notice how we included the template in-line in the program by using a
1439 `here document' with the C<E<lt>E<lt>> notation.
1444 is described in the next section.
1449 been just an imported function, so that you could omit the
1450 C<Text::Template-E<gt>> in the example above. But I made the mistake
1454 not a method and you can omit the C<Text::Template-E<gt>> and just say
1465 at the top of your program. You should probably use
1474 The C<...> are passed to C<fill_in> as above. The filename is the
1475 name of the file that contains the template you want to fill in. It
1476 returns the result text. or C<undef>, as usual.
1478 If you are going to fill in the same file more than once in the same
1479 program you should use the longer C<new> / C<fill_in> sequence instead.
1480 It will be a lot faster because it only has to read and parse the file
1495 from the template. I wrote one for you. In the template, you can say
1499 If that is too verbose, here is a trick. Suppose the template package
1500 that you are going to be mentioning in the C<fill_in> call is package
1501 C<Q>. Then in the main program, write
1505 This imports the C<_load_text> function into package C<Q> with the
1511 to insert the text from the named file at that point. If you are
1512 using the C<HASH> option instead, just put C<include =E<gt>
1513 \&Text::Template::_load_text> into the hash instead of importing it
1518 in the template itself:
1522 You can do the same importing trick if this is too much to type.
1533 The text C<The King> doesn't get into the form letter. Why not?
1534 Because C<$recipient> is a C<my> variable, and the whole point of
1535 C<my> variables is that they're private and inaccessible except in the
1537 scope, so the template can't see C<$recipient>.
1539 If that's not the behavior you want, don't use C<my>. C<my> means a
1540 private variable, and in this case you don't want the variable to be
1541 private. Put the variables into package variables in some other
1542 package, and use the C<PACKAGE> option to C<fill_in>:
1547 or pass the names and values in a hash with the C<HASH> option:
1553 All variables are evaluated in the package you specify with the
1556 worry that evaluation of the little programs will creep out into the
1577 in them. If you're worried, or you can't trust the person who wrote
1578 the template, use the C<SAFE> option.
1581 clobbering local variables in the C<fill_in> function itself. These
1585 actually how C<$OUT> works.) I can fix this, but it will make the
1592 to generate TeX output, the choice of braces as the program fragment
1594 you can change the choice of delimiters to something other than curly
1597 In either the C<new()> call or the C<fill_in()> call, you can specify
1598 an alternative set of delimiters with the C<DELIMITERS> option. For
1605 tried for regexes, but it complicates the lexical analysis too much.)
1606 Note also that C<DELIMITERS> disables the special meaning of the
1607 backslash, so if you want to include the delimiters in the literal
1612 absolutely must have a program fragment that mentions one of the
1629 Because the parsing of templates is simplified by the absence of
1630 backslash escapes, using alternative C<DELIMITERS> may speed up the
1637 undeclared variables and the like. But each code fragment is a
1638 separate lexical scope, so you have to turn on C<strict> at the top of
1654 Because we didn't put C<use strict> at the top of the second fragment,
1655 it was only active in the first fragment, and we didn't get any
1656 C<strict> checking in the second fragment. Then we misspelled C<$foo>
1657 and the error wasn't caught.
1661 added to the beginning of each program fragment.
1667 option; the statements will be prepended to each program fragment for
1668 that one call only. Suppose that the C<fill_in> call included a
1672 option, and that the template looked like this:
1685 The code in the second fragment would fail, because C<$boo> has not
1687 write it explicitly, because the C<PREPEND> option added it for you
1690 There are three other ways to do this. At the time you create the
1692 in which case the statements will be prepended each time you fill in
1693 that template. If the C<fill_in> call has its own C<PREPEND> option,
1694 this overrides the one specified at the time you created the
1695 template. Finally, you can make the class method call
1700 attach the perl statements to the beginning of each program fragment,
1703 An alternative to adding "use strict;" to the PREPEND option, you can
1704 pass STRICT => 1 to fill_in when also passing the HASH option.
1706 Suppose that the C<fill_in> call included both
1711 options, and that the template looked like this:
1724 The code in the second fragment would fail, because C<$boo> has not
1726 write it explicitly, because the C<STRICT> option added it for you
1727 automatically. Any variable referenced in the template that is not in the
1732 This section is technical, and you should skip it on the first few
1736 It could come from the C<PREPEND> option in the C<fill_in> call, from
1737 the C<PREPEND> option in the C<new> call that created the template
1738 object, or from the argument of the C<always_prepend> call.
1739 C<Text::Template> looks for these three things in order and takes the
1751 in a hash variable named C<%GLOBAL_PREPEND> under the key
1753 prepend, it first looks in the template object itself, and if not, it
1754 looks in C<$GLOBAL_PREPEND{I<class>}> where I<class> is the class to
1755 which the template object belongs. If it doesn't find any value, it
1767 putting C<Derived-E<gt>always_prepend('')> at the top of your module.
1770 C<prepend_text> that is used to look up the appropriate text to be
1779 > How do I change the template identifier?
1781 Jennifer is worried about the braces in the JavaScript being taken as
1782 the delimiters of the Perl program fragments. Of course, disaster
1786 then use the C<DELIMITERS> option. However, if you can't do this for
1802 and it'll come out of the template engine the way you want.
1814 So now here's the trick: In Perl, C<q{...}> is the same as C<'...'>.
1840 People sometimes try to put an initialization section at the top of
1847 Then they complain because there is a C<17> at the top of the output
1851 value, and that in Perl the return value of a code block is the value
1852 of the last expression that was evaluated, which in this case is 17.
1854 and have the recipient filled in.
1856 To prevent the 17 from appearing in the output is very simple:
1863 Now the last expression evaluated yields the empty string, which is
1864 invisible. If you don't like the way this looks, use
1879 The output format of the default C<BROKEN> subroutine has changed
1882 Starting in version 1.10, the C<$OUT> variable is arrogated for a
1887 Between versions 0.1b and 1.00 the behavior of the \ metacharacter
1888 changed. In 0.1b, \\ was special everywhere, and the template
1890 the code to Perl for evaluation. The rule now is more complicated but
1891 probably more convenient. See the section on backslash processing,
1896 In C<Text::Template> beta versions, the backslash was special whenever
1899 generate a backslash, because the code passed to Perl for evaluation
1905 generated the letter C<n>.
1908 exactly the old rule, because I did not like the idea of having to
1920 is I<not> evaluated, because the C<\> before the braces signals that
1921 they should be taken literally. The result in the output looks like this:
1929 because C<Text::Template> thinks that the code ends at the first C<}>,
1930 and then gets upset when it sees the second one. To make this work
1936 the evaluated code. If you really want a C<\> in the evaluated code,
1944 disabled if you use the C<DELIMITERS> option to specify alternative
1949 In the past some people have fretted about `violating the package
1950 boundary' by examining a variable inside the C<Text::Template>
1952 the published, official interface to this package. It is perfectly OK
1956 C<TTerror> that returns the current value of the C<$ERROR> variable.
1979 form input controls that retain their values from one page to the
1983 It's totally straightforward. Just call the C<CGI> functions from
1984 inside the template:
1995 It may be useful to preprocess the program fragments before they are
2001 the result text. For this, subclass and replace the C<append_text_to_result>
2004 handle - a filehandle to which to print the desired output
2006 text - the text that will be appended
2007 type - where the text came from: TEXT for literal text, PROG for code
2018 Many thanks to the following people for offering support,
2019 encouragement, advice, bug reports, and all the other good stuff.
2311 for telling me how to do the C<Safe> support (I spent two years
2317 helping me figure out the Right Thing, and, especially, for talking me
2318 out of adding any new syntax. These discussions resulted in the
2329 The line number information will be wrong if the template's lines are
2336 There are not quite enough tests in the test suite.
2345 Please report any bugs or feature requests on the bugtracker website
2349 patch to an existing test-file that illustrates the bug or desired
2361 the same terms as the Perl 5 programming language system itself.