external/perl/Text-Template-1.46/lib/Text/Template/Preprocess.pm

   1
   2 package Text::Template::Preprocess;
   3 use Text::Template;
   4 @ISA = qw(Text::Template);
   5 $Text::Template::Preprocess::VERSION = 1.46;
   6
   7 sub fill_in {
   8   my $self = shift;
   9   my (%args) = @_;
  10   my $pp = $args{PREPROCESSOR} || $self->{PREPROCESSOR} ;
  11   if ($pp) {
  12     local $_ = $self->source();
  13 #    print "# fill_in: before <$_>\n";
  14     &$pp;
  15 #    print "# fill_in: after <$_>\n";
  16     $self->set_source_data($_);
  17   }
  18   $self->SUPER::fill_in(@_);
  19 }
  20
  21 sub preprocessor {
  22   my ($self, $pp) = @_;
  23   my $old_pp = $self->{PREPROCESSOR};
  24   $self->{PREPROCESSOR} = $pp if @_ > 1;  # OK to pass $pp=undef
  25   $old_pp;
  26 }
  27
  28 1;
  29
  30
  31 =head1 NAME
  32
  33 Text::Template::Preprocess - Expand template text with embedded Perl
  34
  35 =head1 VERSION
  36
  37 This file documents C<Text::Template::Preprocess> version B<1.46>
  38
  39 =head1 SYNOPSIS
  40
  41  use Text::Template::Preprocess;
  42
  43  my $t = Text::Template::Preprocess->new(...);  # identical to Text::Template
  44
  45  # Fill in template, but preprocess each code fragment with pp().
  46  my $result = $t->fill_in(..., PREPROCESSOR => \&pp);
  47
  48  my $old_pp = $t->preprocessor(\&new_pp);
  49
  50 =head1 DESCRIPTION
  51
  52 C<Text::Template::Preprocess> provides a new C<PREPROCESSOR> option to
  53 C<fill_in>.  If the C<PREPROCESSOR> option is supplied, it must be a
  54 reference to a preprocessor subroutine.  When filling out a template,
  55 C<Text::Template::Preprocessor> will use this subroutine to preprocess
  56 the program fragment prior to evaluating the code.
  57
  58 The preprocessor subroutine will be called repeatedly, once for each
  59 program fragment.  The program fragment will be in C<$_>.  The
  60 subroutine should modify the contents of C<$_> and return.
  61 C<Text::Template::Preprocess> will then execute contents of C<$_> and
  62 insert the result into the appropriate part of the template.
  63
  64 C<Text::Template::Preprocess> objects also support a utility method,
  65 C<preprocessor()>, which sets a new preprocessor for the object.  This
  66 preprocessor is used for all subsequent calls to C<fill_in> except
  67 where overridden by an explicit C<PREPROCESSOR> option.
  68 C<preprocessor()> returns the previous default preprocessor function,
  69 or undefined if there wasn't one.  When invoked with no arguments,
  70 C<preprocessor()> returns the object's current default preprocessor
  71 function without changing it.
  72
  73 In all other respects, C<Text::Template::Preprocess> is identical to
  74 C<Text::Template>.
  75
  76 =head1 WHY?
  77
  78 One possible purpose:  If your files contain a lot of JavaScript, like
  79 this:
  80
  81
  82         Plain text here...
  83         { perl code }
  84         <script language=JavaScript>
  85               if (br== "n3") {
  86                   // etc.
  87               }
  88         </script>
  89         { more perl code }
  90         More plain text...
  91
  92 You don't want C<Text::Template> to confuse the curly braces in the
  93 JavaScript program with executable Perl code.  One strategy:
  94
  95         sub quote_scripts {
  96           s(<script(.*?)</script>)(q{$1})gsi;
  97         }
  98
  99 Then use C<PREPROCESSOR =E<gt> \&quote_scripts>.  This will transform
 100
 101
 102
 103 =head1 SEE ALSO
 104
 105 L<Text::Template>
 106
 107 =head1 AUTHOR
 108
 109
 110 Mark Jason Dominus, Plover Systems
 111
 112 Please send questions and other remarks about this software to
 113 C<mjd-perl-template+@plover.com>
 114
 115 You can join a very low-volume (E<lt>10 messages per year) mailing
 116 list for announcements about this package.  Send an empty note to
 117 C<mjd-perl-template-request@plover.com> to join.
 118
 119 For updates, visit C<http://www.plover.com/~mjd/perl/Template/>.
 120
 121 =head1 LICENSE
 122
 123     Text::Template::Preprocess version 1.46
 124     Copyright 2013 Mark Jason Dominus
 125
 126     This program is free software; you can redistribute it and/or
 127     modify it under the terms of the GNU General Public License as
 128     published by the Free Software Foundation; either version 2 of the
 129     License, or (at your option) any later version.  You may also can
 130     redistribute it and/or modify it under the terms of the Perl
 131     Artistic License.
 132
 133     This program is distributed in the hope that it will be useful,
 134     but WITHOUT ANY WARRANTY; without even the implied warranty of
 135     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 136     GNU General Public License for more details.
 137
 138     You should have received copies of the GNU General Public License
 139     along with this program; if not, write to the Free Software
 140     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 141
 142
 143 =cut
 144