1 

     2 package Text::Template::Preprocess;

     3 use Text::Template;

     4 @ISA = qw(Text::Template);

     5 $Text::Template::Preprocess::VERSION = 1.44;

     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.44>

    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.44

   124     Copyright (C) 2003 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