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

   1
   2 package Text::Template::Preprocess;
   3 $Text::Template::Preprocess::VERSION = '1.56';
   4 # ABSTRACT: Expand template text with embedded Perl
   5
   6 use strict;
   7 use warnings;
   8
   9 use Text::Template;
  10 our @ISA = qw(Text::Template);
  11
  12 sub 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
  32 sub 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
  42 1;
  43
  44 __END__
  45
  46 =pod
  47
  48 =encoding UTF-8
  49
  50 =head1 NAME
  51
  52 Text::Template::Preprocess - Expand template text with embedded Perl
  53
  54 =head1 VERSION
  55
  56 version 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
  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.
  76
  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.
  82
  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.
  91
  92 In all other respects, C<Text::Template::Preprocess> is identical to
  93 C<Text::Template>.
  94
  95 =head1 WHY?
  96
  97 One possible purpose:  If your files contain a lot of JavaScript, like
  98 this:
  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
 110 You don't want C<Text::Template> to confuse the curly braces in the
 111 JavaScript program with executable Perl code.  One strategy:
 112
 113         sub quote_scripts {
 114           s(<script(.*?)</script>)(q{$1})gsi;
 115         }
 116
 117 Then use C<PREPROCESSOR =E<gt> \&quote_scripts>.  This will transform
 118
 119 =head1 SEE ALSO
 120
 121 L<Text::Template>
 122
 123 =head1 SOURCE
 124
 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>
 127
 128 =head1 BUGS
 129
 130 Please report any bugs or feature requests on the bugtracker website
 131 L<https://github.com/mschout/perl-text-template/issues>
 132
 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
 135 feature.
 136
 137 =head1 AUTHOR
 138
 139 Mark Jason Dominus, Plover Systems
 140
 141 Please send questions and other remarks about this software to
 142 C<mjd-perl-template+@plover.com>
 143
 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.
 147
 148 For updates, visit C<http://www.plover.com/~mjd/perl/Template/>.
 149
 150 =head1 COPYRIGHT AND LICENSE
 151
 152 This software is copyright (c) 2013 by Mark Jason Dominus <mjd@cpan.org>.
 153
 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.
 156
 157 =cut