1
2package Text::Template::Preprocess;
3$Text::Template::Preprocess::VERSION = '1.56';
4# ABSTRACT: Expand template text with embedded Perl
5
6use strict;
7use warnings;
8
9use Text::Template;
10our @ISA = qw(Text::Template);
11
12sub fill_in {
13    my $self   = shift;
14    my (%args) = @_;
15
16    my $pp     = $args{PREPROCESSOR} || $self->{PREPROCESSOR};
17
18    if ($pp) {
19        local $_ = $self->source();
20        my $type = $self->{TYPE};
21
22        #    print "# fill_in: before <$_>\n";
23        &$pp;
24
25        #    print "# fill_in: after <$_>\n";
26        $self->set_source_data($_, $type);
27    }
28
29    $self->SUPER::fill_in(@_);
30}
31
32sub preprocessor {
33    my ($self, $pp) = @_;
34
35    my $old_pp = $self->{PREPROCESSOR};
36
37    $self->{PREPROCESSOR} = $pp if @_ > 1;    # OK to pass $pp=undef
38
39    $old_pp;
40}
41
421;
43
44__END__
45
46=pod
47
48=encoding UTF-8
49
50=head1 NAME
51
52Text::Template::Preprocess - Expand template text with embedded Perl
53
54=head1 VERSION
55
56version 1.56
57
58=head1 SYNOPSIS
59
60 use Text::Template::Preprocess;
61
62 my $t = Text::Template::Preprocess->new(...);  # identical to Text::Template
63
64 # Fill in template, but preprocess each code fragment with pp().
65 my $result = $t->fill_in(..., PREPROCESSOR => \&pp);
66
67 my $old_pp = $t->preprocessor(\&new_pp);
68
69=head1 DESCRIPTION
70
71C<Text::Template::Preprocess> provides a new C<PREPROCESSOR> option to
72C<fill_in>.  If the C<PREPROCESSOR> option is supplied, it must be a
73reference to a preprocessor subroutine.  When filling out a template,
74C<Text::Template::Preprocessor> will use this subroutine to preprocess
75the program fragment prior to evaluating the code.
76
77The preprocessor subroutine will be called repeatedly, once for each
78program fragment.  The program fragment will be in C<$_>.  The
79subroutine should modify the contents of C<$_> and return.
80C<Text::Template::Preprocess> will then execute contents of C<$_> and
81insert the result into the appropriate part of the template.
82
83C<Text::Template::Preprocess> objects also support a utility method,
84C<preprocessor()>, which sets a new preprocessor for the object.  This
85preprocessor is used for all subsequent calls to C<fill_in> except
86where overridden by an explicit C<PREPROCESSOR> option.
87C<preprocessor()> returns the previous default preprocessor function,
88or undefined if there wasn't one.  When invoked with no arguments,
89C<preprocessor()> returns the object's current default preprocessor
90function without changing it.
91
92In all other respects, C<Text::Template::Preprocess> is identical to
93C<Text::Template>.
94
95=head1 WHY?
96
97One possible purpose:  If your files contain a lot of JavaScript, like
98this:
99
100        Plain text here...
101        { perl code }
102        <script language=JavaScript>
103     	      if (br== "n3") {
104	  	  // etc.
105	      }
106        </script>
107        { more perl code }
108        More plain text...
109
110You don't want C<Text::Template> to confuse the curly braces in the
111JavaScript program with executable Perl code.  One strategy:
112
113        sub quote_scripts {
114          s(<script(.*?)</script>)(q{$1})gsi;
115        }
116
117Then use C<PREPROCESSOR =E<gt> \&quote_scripts>.  This will transform
118
119=head1 SEE ALSO
120
121L<Text::Template>
122
123=head1 SOURCE
124
125The development version is on github at L<https://https://github.com/mschout/perl-text-template>
126and may be cloned from L<git://https://github.com/mschout/perl-text-template.git>
127
128=head1 BUGS
129
130Please report any bugs or feature requests on the bugtracker website
131L<https://github.com/mschout/perl-text-template/issues>
132
133When submitting a bug or request, please include a test-file or a
134patch to an existing test-file that illustrates the bug or desired
135feature.
136
137=head1 AUTHOR
138
139Mark Jason Dominus, Plover Systems
140
141Please send questions and other remarks about this software to
142C<mjd-perl-template+@plover.com>
143
144You can join a very low-volume (E<lt>10 messages per year) mailing
145list for announcements about this package.  Send an empty note to
146C<mjd-perl-template-request@plover.com> to join.
147
148For updates, visit C<http://www.plover.com/~mjd/perl/Template/>.
149
150=head1 COPYRIGHT AND LICENSE
151
152This software is copyright (c) 2013 by Mark Jason Dominus <mjd@cpan.org>.
153
154This is free software; you can redistribute it and/or modify it under
155the same terms as the Perl 5 programming language system itself.
156
157=cut
158