2 package Text::Template::Preprocess;
3 $Text::Template::Preprocess::VERSION = '1.56';
4 # ABSTRACT: Expand template text with embedded Perl
10 our @ISA = qw(Text::Template);
16 my $pp = $args{PREPROCESSOR} || $self->{PREPROCESSOR};
19 local $_ = $self->source();
20 my $type = $self->{TYPE};
22 # print "# fill_in: before <$_>\n";
25 # print "# fill_in: after <$_>\n";
26 $self->set_source_data($_, $type);
29 $self->SUPER::fill_in(@_);
35 my $old_pp = $self->{PREPROCESSOR};
37 $self->{PREPROCESSOR} = $pp if @_ > 1; # OK to pass $pp=undef
52 Text::Template::Preprocess - Expand template text with embedded Perl
60 use Text::Template::Preprocess;
62 my $t = Text::Template::Preprocess->new(...); # identical to Text::Template
64 # Fill in template, but preprocess each code fragment with pp().
65 my $result = $t->fill_in(..., PREPROCESSOR => \&pp);
67 my $old_pp = $t->preprocessor(\&new_pp);
71 C<Text::Template::Preprocess> provides a new C<PREPROCESSOR> option to
72 C<fill_in>. If the C<PREPROCESSOR> option is supplied, it must be a
73 reference to a preprocessor subroutine. When filling out a template,
74 C<Text::Template::Preprocessor> will use this subroutine to preprocess
75 the program fragment prior to evaluating the code.
77 The preprocessor subroutine will be called repeatedly, once for each
78 program fragment. The program fragment will be in C<$_>. The
79 subroutine should modify the contents of C<$_> and return.
80 C<Text::Template::Preprocess> will then execute contents of C<$_> and
81 insert the result into the appropriate part of the template.
83 C<Text::Template::Preprocess> objects also support a utility method,
84 C<preprocessor()>, which sets a new preprocessor for the object. This
85 preprocessor is used for all subsequent calls to C<fill_in> except
86 where overridden by an explicit C<PREPROCESSOR> option.
87 C<preprocessor()> returns the previous default preprocessor function,
88 or undefined if there wasn't one. When invoked with no arguments,
89 C<preprocessor()> returns the object's current default preprocessor
90 function without changing it.
92 In all other respects, C<Text::Template::Preprocess> is identical to
97 One possible purpose: If your files contain a lot of JavaScript, like
102 <script language=JavaScript>
110 You don't want C<Text::Template> to confuse the curly braces in the
111 JavaScript program with executable Perl code. One strategy:
114 s(<script(.*?)</script>)(q{$1})gsi;
117 Then use C<PREPROCESSOR =E<gt> \"e_scripts>. This will transform
125 The development version is on github at L<https://https://github.com/mschout/perl-text-template>
126 and may be cloned from L<git://https://github.com/mschout/perl-text-template.git>
130 Please report any bugs or feature requests on the bugtracker website
131 L<https://github.com/mschout/perl-text-template/issues>
133 When submitting a bug or request, please include a test-file or a
134 patch to an existing test-file that illustrates the bug or desired
139 Mark Jason Dominus, Plover Systems
141 Please send questions and other remarks about this software to
142 C<mjd-perl-template+@plover.com>
144 You can join a very low-volume (E<lt>10 messages per year) mailing
145 list for announcements about this package. Send an empty note to
146 C<mjd-perl-template-request@plover.com> to join.
148 For updates, visit C<http://www.plover.com/~mjd/perl/Template/>.
150 =head1 COPYRIGHT AND LICENSE
152 This software is copyright (c) 2013 by Mark Jason Dominus <mjd@cpan.org>.
154 This is free software; you can redistribute it and/or modify it under
155 the same terms as the Perl 5 programming language system itself.