home *** CD-ROM | disk | FTP | other *** search
/ PC Open 93 / PC Open 93 CD 1.bin / internet / AmphetaDesk / lib / Text / Template / Preprocess.pm
Encoding:
Perl POD Document  |  2002-03-25  |  4.2 KB  |  145 lines
  1.  
  2. package Text::Template::Preprocess;
  3. use Text::Template;
  4. @ISA = qw(Text::Template);
  5. $Text::Template::Preprocess::VERSION = 1.43;
  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.43>
  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> \"e_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.43
  124.     Copyright (C) 2001 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.  
  145.