Lines Matching full:template
2 # Text::Template.pm
9 # If in doubt, write to mjd-perl-template+@plover.com for a license.
12 package Text::Template;
13 $Text::Template::VERSION = '1.56';
14 # ABSTRACT: Expand template text with embedded Perl
26 my %GLOBAL_PREPEND = ('Text::Template' => '');
29 $Text::Template::VERSION;
102 # Convert template objects of various types to type STRING,
103 # in which the template data is embedded in the object itself.
284 $t = $GLOBAL_PREPEND{'Text::Template'};
309 my $fi_filename = _param('filename', %fi_a) || $fi_self->{FILENAME} || 'template';
474 Text::Template->fill_this_in($string, @_);
479 my $templ = Text::Template->new(TYPE => 'FILE', SOURCE => $fn, @_) or return undef;
536 $s =~ s/^Text::Template:://;
540 my $hash = $Text::Template::{ $s . "::" };
548 delete $Text::Template::{ $s . "::" };
610 Text::Template - Expand template text with embedded Perl
618 use Text::Template;
621 $template = Text::Template->new(TYPE => 'FILE', SOURCE => 'filename.tmpl');
622 $template = Text::Template->new(TYPE => 'ARRAY', SOURCE => [ ... ] );
623 $template = Text::Template->new(TYPE => 'FILEHANDLE', SOURCE => $fh );
624 $template = Text::Template->new(TYPE => 'STRING', SOURCE => '...' );
625 $template = Text::Template->new(PREPEND => q{use strict;}, ...);
627 # Use a different template file syntax:
628 $template = Text::Template->new(DELIMITERS => [$open, $close], ...);
631 $text = $template->fill_in(); # Replaces `{$recipient}' with `King'
635 $text = $template->fill_in(PACKAGE => T);
643 $text = $template->fill_in(HASH => $hash, ...);
649 # Call &callback in case of programming errors in template
650 $text = $template->fill_in(BROKEN => \&callback, BROKEN_ARG => $ref, ...);
653 $text = $template->fill_in(SAFE => $compartment, ...);
656 $success = $template->fill_in(OUTPUT => \*FILEHANDLE, ...);
658 # Parse template with different template file syntax:
659 $text = $template->fill_in(DELIMITERS => [$open, $close], ...);
663 $text = $template->fill_in(PREPEND => q{use strict 'vars';}, ...);
665 use Text::Template 'fill_in_string';
673 use Text::Template 'fill_in_file';
677 Text::Template->always_prepend(q{use strict 'vars';});
682 filling in templates generally. A `template' is a piece of text that
684 `fill in' a template, you evaluate the little programs and replace
687 You can store a template in a file outside your program. People can
688 modify the template without modifying the program. You can separate
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
709 The result of filling in this template is a string, which might look
725 template into the example result, and prints it out:
727 use Text::Template;
729 my $template = Text::Template->new(SOURCE => 'formletter.tmpl')
730 or die "Couldn't construct template: $Text::Template::ERROR";
741 my $result = $template->fill_in(HASH => \%vars);
744 else { die "Couldn't fill in template: $Text::Template::ERROR" }
748 When people make a template module like this one, they almost always
754 little template language.
761 C<Text::Template> templates are programmed in I<Perl>. You embed Perl
762 code in your template, with C<{> at the beginning and C<}> at the end.
769 =head2 Template Parsing
771 The C<Text::Template> module scans the template source. An open brace
773 close brace C<}>. When the template is filled in, the program
779 out this template:
787 If you have an unmatched brace, C<Text::Template> will return a
790 a template like this:
803 statement is a string, which is interpolated into the template in
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
847 One way to do it is with a template like this:
862 template. Also, if you use C<$OUT> in a program fragment, the normal
865 This means that you can write the template above like this:
874 program fragment. It is private to C<Text::Template>, so
875 you can't use a variable named C<$OUT> in your template without
880 All C<Text::Template> functions return C<undef> on failure, and set the
881 variable C<$Text::Template::ERROR> to contain an explanation of what
882 went wrong. For example, if you try to create a template from a file
883 that does not exist, C<$Text::Template::ERROR> will contain something like:
889 $template = Text::Template->new( TYPE => ..., SOURCE => ... );
891 This creates and returns a new template object. C<new> returns
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
898 Text::Template->new( TYPE => 'FILE', SOURCE => $filename );
900 This reads the template from the specified file. The filename is
907 Text::Template->new( TYPE => 'STRING',
908 SOURCE => "This is the actual template!" );
912 is the template:
914 Text::Template->new( TYPE => 'ARRAY',
916 " template!",
923 C<Text::Template> will read the text from the filehandle up to
924 end-of-file, and that text is the template:
926 # Read template source code from STDIN:
927 Text::Template->new ( TYPE => 'FILEHANDLE',
961 Text::Template->new(
975 tell C<Text::Template> that a certain file is trustworthy by supplying
977 C<Text::Template> to disable taint checks on template code that has
979 trustworthy. It will also disable taint checks on template code that
1003 $template->compile()
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.
1019 $template->fill_in(OPTIONS);
1021 Fills in a template. Returns the resulting text if successful.
1022 Otherwise, returns C<undef> and sets C<$Text::Template::ERROR>.
1047 which C<fill_in> was called. For example, consider this template:
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
1057 template makes changes to variables, those changes will be propagated
1058 back into the main program. Evaluating the template in a private
1059 package helps prevent this. The template can still modify variables
1083 $template->fill_in();
1088 filling out the template. The problem is the same as if you had
1090 the template does. (C<$OUT> is special in templates and is always
1094 template by declaring it with C<my>. If the template does this, you
1098 if the template does I<not> declare its variables with C<my>:
1101 $template->fill_in(PACKAGE => 'Q');
1103 In this case the template will clobber the variable C<$Q::item_no>,
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.
1119 $template->fill_in(
1127 will fill out the template and use C<"The King"> as the value of
1129 that we pass an array reference, but inside the template it appears as
1135 a reference to a scalar, inside the template the object appears as
1153 value in the template.
1176 In particular, if you want the template to get an object or any kind,
1179 $template->fill_in(HASH => { database_handle => \$dbh, ... });
1181 If you do this, the template will have a variable C<$database_handle>
1183 template will have a hash C<%database_handle>, which exposes the
1190 template as if you had specified that package. A new package is
1192 option, C<Text::Template> loads the variables into the package you
1199 whose contents are loaded into the template package one after the
1205 $template->fill_in(HASH => [\%defaults, \%user_input]);
1209 $template->fill_in(
1222 C<Text::Template> will invoke the function. This function is called
1224 C<Text::Template> what to do next.
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
1233 interpolated into the template as if that value had been the return
1236 interpolated into the output of the template in place of the program
1239 If you don't specify a C<BROKEN> function, C<Text::Template> supplies
1243 template line 37''
1247 interpolated into the template at the place the error occurred, so
1248 that this template:
1254 (3+4)*5 = Program fragment delivered error ``syntax error at template line 1''
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
1280 The line number of the template at which the program fragment began.
1308 $template->fill_in(
1317 If one of the program fragments in the template fails, it will call
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
1330 like C<... at foo.txt line N> rather than C<... at template line N>.
1332 Note that this does NOT have anything to do with loading a template from the
1337 my $template = Text::Template->new(
1341 $template->fill_in(FILENAME => 'foo.txt') or die $Text::Template::ERROR;
1361 fragments occurs in the package from which the template was invoked.
1371 If your template is going to generate a lot of text that you are just
1373 C<Text::Template> print out the text as it is generated instead of
1379 $template->fill_in(OUTPUT => \*STDOUT, ...);
1381 fills in the C<$template> as usual, but the results are immediately
1404 any delimiters you set when you created the template object with
1413 The basic way to fill in a template is to create a template object and
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
1421 C<undef> and sets C<$Text::Template::ERROR> if it couldn't generate
1430 $text = Text::Template->fill_this_in( <<'EOM', PACKAGE => Q);
1438 Notice how we included the template in-line in the program by using a
1443 in C<Text::Template>. You should use C<fill_in_string> instead. It
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
1463 use Text::Template 'fill_in_string';
1475 name of the file that contains the template you want to fill in. It
1491 into your template. VoilE<agrave>.
1495 from the template. I wrote one for you. In the template, you can say
1497 {Text::Template::_load_text(filename)}
1499 If that is too verbose, here is a trick. Suppose the template package
1503 *Q::include = \&Text::Template::_load_text;
1506 name C<include>. From then on, any template that you fill in with
1513 \&Text::Template::_load_text> into the hash instead of importing it
1517 want to include one template within another? Just use C<fill_in_file>
1518 in the template itself:
1520 {Text::Template::fill_in_file(filename)}
1536 scope in which they're declared. The template is not part of that
1537 scope, so the template can't see C<$recipient>.
1560 against a template that says
1578 the template, use the C<SAFE> option.
1591 Lorenzo Valdettaro pointed out that if you are using C<Text::Template>
1608 text of your template file, you are out of luck---it is up to you to
1659 C<Text::Template> version 1.22 and higher has a new feature to make
1672 option, and that the template looked like this:
1691 template object with C<new>, you can also supply a C<PREPEND> option,
1693 that template. If the C<fill_in> call has its own C<PREPEND> option,
1695 template. Finally, you can make the class method call
1697 Text::Template->always_prepend('perl statements');
1699 If you do this, then call calls to C<fill_in> for I<any> template will
1711 options, and that the template looked like this:
1727 automatically. Any variable referenced in the template that is not in the
1737 the C<PREPEND> option in the C<new> call that created the template
1739 C<Text::Template> looks for these three things in order and takes the
1742 In a subclass of C<Text::Template>, this last possibility is
1743 ambiguous. Suppose C<S> is a subclass of C<Text::Template>. Should
1745 Text::Template->always_prepend(...);
1750 The C<always_prepend> value for C<Text::Template> is normally stored
1752 C<Text::Template>. When C<Text::Template> looks to see what text to
1753 prepend, it first looks in the template object itself, and if not, it
1755 which the template object belongs. If it doesn't find any value, it
1756 looks in C<$GLOBAL_PREPEND{'Text::Template'}>. This means that
1759 Text::Template->always_prepend(...);
1766 your objects ignore C<Text::Template::always_prepend> calls by simply
1779 > How do I change the template identifier?
1785 strings that you can use in your template instead of curly braces, and
1802 and it'll come out of the template engine the way you want.
1805 works, first consider what happens if you put this into a template:
1888 changed. In 0.1b, \\ was special everywhere, and the template
1896 In C<Text::Template> beta versions, the backslash was special whenever
1903 In C<Text::Template> versions 1.00 through 1.10, there was a bug:
1929 because C<Text::Template> thinks that the code ends at the first C<}>,
1943 Starting with C<Text::Template> version 1.20, backslash processing is
1947 =head2 A short note about C<$Text::Template::ERROR>
1950 boundary' by examining a variable inside the C<Text::Template>
1951 package. Don't feel this way. C<$Text::Template::ERROR> is part of
1959 use Text::Template 'TTerror';
1961 my $template = Text::Template->new(SOURCE => $filename);
1962 unless ($template) {
1964 die "Couldn't make template: $err; aborting";
1969 use Text::Template;
1971 my $template = Text::Template->new(SOURCE => $filename)
1972 or die "Couldn't make template: $Text::Template::ERROR; aborting";
1976 =head2 Sticky Widgets in Template Files
1981 into their template output.
1984 inside the template:
1996 evaluated. See C<Text::Template::Preprocess> for more details.
1998 =head2 Automatic postprocessing of template hunks
2326 by template evaluation. They all begin with C<fi_>, so avoid those
2329 The line number information will be wrong if the template's lines are
2340 The development version is on github at L<https://https://github.com/mschout/perl-text-template>
2341 and may be cloned from L<git://https://github.com/mschout/perl-text-template.git>
2346 L<https://github.com/mschout/perl-text-template/issues>