← Back to branch summary

~ubuntu-branches/ubuntu/quantal/libtemplate-perl/quantal

« back to all changes in this revision

Viewing changes to lib/Template.pm

  • Committer: Package Import Robot
  • Author(s): Benjamin Mako Hill
  • Date: 2012-04-08 19:06:29 UTC
  • mfrom: (0.7.1) (0.5.2) (5.1.3 sid)
  • Revision ID: package-import@ubuntu.com-20120408190629-wbcbs2ea39mex6lt
Tags: 2.24-1
http://bugs.debian.org/664561
https://launchpad.net/bugs/688836
* New upstream release (Closes: #664561)
* Bump Standards-Version to 3.9.3
* Changed to the short description to mention the term "Template
  Toolkit". (LP: #688836)

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/Template.pm
3
3
# Template
4
4
#
5
5
# DESCRIPTION
6
 
#   Module implementing a simple, user-oriented front-end to the Template 
 
6
#   Module implementing a simple, user-oriented front-end to the Template
7
7
#   Toolkit.
8
8
#
9
9
# AUTHOR
10
10
#   Andy Wardley   <abw@wardley.org>
11
11
#
12
12
# COPYRIGHT
13
 
#   Copyright (C) 1996-2009 Andy Wardley.  All Rights Reserved.
 
13
#   Copyright (C) 1996-2012 Andy Wardley.  All Rights Reserved.
14
14
#
15
15
#   This module is free software; you can redistribute it and/or
16
16
#   modify it under the same terms as Perl itself.
26
26
 
27
27
use Template::Config;
28
28
use Template::Constants;
29
 
use Template::Provider;  
 
29
use Template::Provider;
30
30
use Template::Service;
31
31
use File::Basename;
32
32
use File::Path;
33
33
use Scalar::Util qw(blessed);
34
34
 
35
 
our $VERSION = '2.22';
 
35
our $VERSION = '2.24';
36
36
our $ERROR   = '';
37
37
our $DEBUG   = 0;
38
38
our $BINMODE = 0 unless defined $BINMODE;
45
45
#------------------------------------------------------------------------
46
46
# process($input, \%replace, $output)
47
47
#
48
 
# Main entry point for the Template Toolkit.  The Template module 
 
48
# Main entry point for the Template Toolkit.  The Template module
49
49
# delegates most of the processing effort to the underlying SERVICE
50
 
# object, an instance of the Template::Service class.  
 
50
# object, an instance of the Template::Service class.
51
51
#------------------------------------------------------------------------
52
52
 
53
53
sub process {
58
58
 
59
59
    $options->{ binmode } = $BINMODE
60
60
        unless defined $options->{ binmode };
61
 
    
62
 
    # we're using this for testing in t/output.t and t/filter.t so 
 
61
 
 
62
    # we're using this for testing in t/output.t and t/filter.t so
63
63
    # don't remove it if you don't want tests to fail...
64
64
    $self->DEBUG("set binmode\n") if $DEBUG && $options->{ binmode };
65
65
 
66
66
    $output = $self->{ SERVICE }->process($template, $vars);
67
 
    
 
67
 
68
68
    if (defined $output) {
69
69
        $outstream ||= $self->{ OUTPUT };
70
70
        unless (ref $outstream) {
71
71
            my $outpath = $self->{ OUTPUT_PATH };
72
72
            $outstream = "$outpath/$outstream" if $outpath;
73
 
        }   
 
73
        }
74
74
 
75
75
        # send processed template to output stream, checking for error
76
76
        return ($self->error($error))
77
77
            if ($error = &_output($outstream, \$output, $options));
78
 
        
 
78
 
79
79
        return 1;
80
80
    }
81
81
    else {
100
100
#------------------------------------------------------------------------
101
101
# context()
102
102
#
103
 
# Returns a reference to the the CONTEXT object withint the SERVICE 
 
103
# Returns a reference to the the CONTEXT object withint the SERVICE
104
104
# object.
105
105
#------------------------------------------------------------------------
106
106
 
109
109
    return $self->{ SERVICE }->{ CONTEXT };
110
110
}
111
111
 
 
112
sub template {
 
113
    shift->context->template(@_);
 
114
}
 
115
 
112
116
 
113
117
#========================================================================
114
118
#                     -- PRIVATE METHODS --
124
128
    my $debug = $config->{ DEBUG };
125
129
    $config->{ DEBUG } = Template::Constants::debug_flags($self, $debug)
126
130
        || return if defined $debug && $debug !~ /^\d+$/;
127
 
    
 
131
 
128
132
    # prepare a namespace handler for any CONSTANTS definition
129
133
    if (my $constants = $config->{ CONSTANTS }) {
130
134
        my $ns  = $config->{ NAMESPACE } ||= { };
133
137
            || return $self->error(Template::Config->error);
134
138
        $ns->{ $cns } = $constants;
135
139
    }
136
 
    
 
140
 
137
141
    $self->{ SERVICE } = $config->{ SERVICE }
138
142
        || Template::Config->service($config)
139
143
        || return $self->error(Template::Config->error);
140
 
    
 
144
 
141
145
    $self->{ OUTPUT      } = $config->{ OUTPUT } || \*STDOUT;
142
146
    $self->{ OUTPUT_PATH } = $config->{ OUTPUT_PATH };
143
147
 
153
157
    my ($where, $textref, $options) = @_;
154
158
    my $reftype;
155
159
    my $error = 0;
156
 
    
 
160
 
157
161
    # call a CODE reference
158
162
    if (($reftype = ref($where)) eq 'CODE') {
159
163
        &$where($$textref);
161
165
    # print to a glob (such as \*STDOUT)
162
166
    elsif ($reftype eq 'GLOB') {
163
167
        print $where $$textref;
164
 
    }   
 
168
    }
165
169
    # append output to a SCALAR ref
166
170
    elsif ($reftype eq 'SCALAR') {
167
171
        $$where .= $$textref;
185
189
            # strip file name and line number from error raised by die()
186
190
            ($error = $@) =~ s/ at \S+ line \d+\n?$//;
187
191
        }
188
 
        elsif (open(FP, ">$where")) { 
 
192
        elsif (open(FP, ">$where")) {
189
193
            # binmode option can be 1 or a specific layer, e.g. :utf8
190
194
            my $bm = $options->{ binmode  };
191
 
            if ($bm && $bm eq 1) { 
 
195
            if ($bm && $bm eq 1) {
192
196
                binmode FP;
193
197
            }
194
 
            elsif ($bm){ 
 
198
            elsif ($bm){
195
199
                binmode FP, $bm;
196
200
            }
197
201
            print FP $$textref;
218
222
 
219
223
Template - Front-end module to the Template Toolkit
220
224
 
221
 
=head1 SYNOPSIS 
 
225
=head1 SYNOPSIS
222
226
 
223
227
    use Template;
224
 
    
 
228
 
225
229
    # some useful options (see below for full list)
226
230
    my $config = {
227
231
        INCLUDE_PATH => '/search/path',  # or list ref
228
232
        INTERPOLATE  => 1,               # expand "$var" in plain text
229
 
        POST_CHOMP   => 1,               # cleanup whitespace 
 
233
        POST_CHOMP   => 1,               # cleanup whitespace
230
234
        PRE_PROCESS  => 'header',        # prefix each template
231
235
        EVAL_PERL    => 1,               # evaluate Perl code blocks
232
236
    };
233
 
    
 
237
 
234
238
    # create Template object
235
239
    my $template = Template->new($config);
236
 
    
 
240
 
237
241
    # define template variables for replacement
238
242
    my $vars = {
239
243
        var1  => $value,
242
246
        var4  => \&code,
243
247
        var5  => $object,
244
248
    };
245
 
    
 
249
 
246
250
    # specify input filename, or file handle, text reference, etc.
247
251
    my $input = 'myfile.html';
248
 
    
 
252
 
249
253
    # process input template, substituting variables
250
254
    $template->process($input, $vars)
251
255
        || die $template->error();
314
318
    # file handle (GLOB)
315
319
    $tt->process(\*DATA)
316
320
        || die $tt->error(), "\n";
317
 
    
 
321
 
318
322
    __END__
319
323
    [% INCLUDE header %]
320
 
    This is a template defined in the __END__ section which is 
 
324
    This is a template defined in the __END__ section which is
321
325
    accessible via the DATA "file handle".
322
326
    [% INCLUDE footer %]
323
327
 
350
354
    my $output = '';
351
355
    $tt->process('welcome.tt2', $vars, \$output)
352
356
        || die $tt->error(), "\n";
353
 
    
 
357
 
354
358
    print "output: $output\n";
355
359
 
356
360
In an Apache/mod_perl handler:
357
361
 
358
362
    sub handler {
359
363
        my $req = shift;
360
 
        
 
364
 
361
365
        # ...your code here...
362
 
        
 
366
 
363
367
        # direct output to Apache::Request via $req->print($output)
364
368
        $tt->process($file, $vars, $req) || do {
365
369
            $req->log_reason($tt->error());
378
382
    # either: hash reference of options
379
383
    $tt->process($infile, $vars, $outfile, { binmode => 1 })
380
384
        || die $tt->error(), "\n";
381
 
    
 
385
 
382
386
    # or: list of name, value pairs
383
387
    $tt->process($infile, $vars, $outfile, binmode => 1)
384
388
        || die $tt->error(), "\n";
385
389
 
386
 
Alternately, the C<binmode> argument can specify a particular IO layer such 
 
390
Alternately, the C<binmode> argument can specify a particular IO layer such
387
391
as C<:utf8>.
388
392
 
389
393
    $tt->process($infile, $vars, $outfile, binmode => ':utf8')
390
394
        || die $tt->error(), "\n";
391
395
 
392
 
The C<OUTPUT> configuration item can be used to specify a default output 
 
396
The C<OUTPUT> configuration item can be used to specify a default output
393
397
location other than C<\*STDOUT>.  The C<OUTPUT_PATH> specifies a directory
394
398
which should be prefixed to all output locations specified as filenames.
395
399
 
398
402
        OUTPUT_PATH => '/tmp',
399
403
    ...
400
404
    }) || die Template->error(), "\n";
401
 
    
 
405
 
402
406
    # use default OUTPUT (sub is called)
403
407
    $tt->process('welcome.tt2', $vars)
404
408
        || die $tt->error(), "\n";
405
 
        
 
409
 
406
410
    # write file to '/tmp/welcome.html'
407
411
    $tt->process('welcome.tt2', $vars, 'welcome.html')
408
412
        || die $tt->error(), "\n";
435
439
then the C<error()> method can be called to return an object of this class.
436
440
The L<type()|Template::Exception#type()> and
437
441
L<info()|Template::Exception#info()> methods can called on the object to
438
 
retrieve the error type and information string, respectively. The 
 
442
retrieve the error type and information string, respectively. The
439
443
L<as_string()|Template::Exception#as_string()>
440
444
method can be called to return a string of the form C<$type - $info>. This
441
445
method is also overloaded onto the stringification operator allowing the
457
461
=head2 context()
458
462
 
459
463
The L<Template::Service> module uses a core L<Template::Context> object for
460
 
runtime processing of templates.  This method returns a reference to 
 
464
runtime processing of templates.  This method returns a reference to
461
465
that object and is equivalent to C<< $template-E<gt>service-E<gt>context() >>.
462
466
 
 
467
=head2 template($name)
 
468
 
 
469
This method is a simple wrapper around the L<Template::Context> method of the
 
470
same name.  It returns a compiled template for the source provided as an
 
471
argument.
 
472
 
463
473
=head1 CONFIGURATION SUMMARY
464
474
 
465
 
The following list gives a short summary of each Template Toolkit 
 
475
The following list gives a short summary of each Template Toolkit
466
476
configuration option.  See L<Template::Manual::Config> for full details.
467
477
 
468
478
=head2 Template Style and Parsing Options
469
479
 
470
480
=head3 START_TAG, END_TAG
471
481
 
472
 
Define tokens that indicate start and end of directives 
 
482
Define tokens that indicate start and end of directives
473
483
(default: 'C<[%>' and 'C<%]>').
474
484
 
475
485
=head3 TAG_STYLE
521
531
 
522
532
=head3 AUTO_RESET
523
533
 
524
 
Enabled by default causing C<BLOCK> definitions to be reset each time a 
 
534
Enabled by default causing C<BLOCK> definitions to be reset each time a
525
535
template is processed.  Disable to allow C<BLOCK> definitions to persist.
526
536
 
527
537
=head3 RECURSION
594
604
 
595
605
=head3 LOAD_PERL
596
606
 
597
 
Flag to indicate regular Perl modules should be loaded if a named plugin 
 
607
Flag to indicate regular Perl modules should be loaded if a named plugin
598
608
can't be found  (default: 0).
599
609
 
600
610
=head3 FILTERS
730
740
    [% BLOCK hello %]
731
741
       Hello World
732
742
    [% END %]
733
 
    
 
743
 
734
744
    [% INCLUDE hello %]
735
745
 
736
746
=head2 FOREACH
744
754
 
745
755
=head2 WHILE
746
756
 
747
 
The block enclosed between C<WHILE> and C<END> block is processed while 
 
757
The block enclosed between C<WHILE> and C<END> block is processed while
748
758
the specified condition is true.
749
759
 
750
760
    [% WHILE condition %]
890
900
        tag comments out the entire directive
891
901
    %]
892
902
 
 
903
=head1 SOURCE CODE REPOSITORY
 
904
 
 
905
The source code for the Template Toolkit is held in a public git repository
 
906
on Github: L<https://github.com/abw/Template2>
 
907
 
893
908
=head1 AUTHOR
894
909
 
895
910
Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/>
896
911
 
897
912
=head1 VERSION
898
913
 
899
 
Template Toolkit version 2.20_1, released April 2009.
 
914
Template Toolkit version 2.23, released January 2012.
900
915
 
901
916
=head1 COPYRIGHT
902
917
 
903
 
Copyright (C) 1996-2009 Andy Wardley.  All Rights Reserved.
 
918
Copyright (C) 1996-2012 Andy Wardley.  All Rights Reserved.
904
919
 
905
920
This module is free software; you can redistribute it and/or
906
921
modify it under the same terms as Perl itself.