Debian Codegraph @

bench/perl/Template/Provider.pm

raw
1 #============================================================= -*-Perl-*-
2 #
3 # Template::Provider
4 #
5 # DESCRIPTION
6 # This module implements a class which handles the loading, compiling
7 # and caching of templates. Multiple Template::Provider objects can
8 # be stacked and queried in turn to effect a Chain-of-Command between
9 # them. A provider will attempt to return the requested template,
10 # an error (STATUS_ERROR) or decline to provide the template
11 # (STATUS_DECLINE), allowing subsequent providers to attempt to
12 # deliver it. See 'Design Patterns' for further details.
13 #
14 # AUTHORS
15 # Andy Wardley <[email protected]>
16 #
17 # Refactored by Bill Moseley for v2.19 to add negative caching (i.e.
18 # tracking templates that are NOTFOUND so that we can decline quickly)
19 # and to provide better support for subclassing the provider.
20 #
21 # COPYRIGHT
22 # Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
23 #
24 # This module is free software; you can redistribute it and/or
25 # modify it under the same terms as Perl itself.
26 #
27 # WARNING:
28 # This code is ugly and contorted and is being totally re-written for TT3.
29 # In particular, we'll be throwing errors rather than messing around
30 # returning (value, status) pairs. With the benefit of hindsight, that
31 # was a really bad design decision on my part. I deserve to be knocked
32 # to the ground and kicked around a bit by hoards of angry TT developers
33 # for that one. Bill's refactoring has made the module easier to subclass,
34 # (so you can ease off the kicking now), but it really needs to be totally
35 # redesigned and rebuilt from the ground up along with the bits of TT that
36 # use it. -- abw 2007/04/27
37 #============================================================================
38
39 package Template::Provider;
40
41 use strict;
42 use warnings;
43 use base 'Template::Base';
44 use Template::Config;
45 use Template::Constants;
46 use Template::Document;
47 use File::Basename;
48 use File::Spec;
49
50 use constant PREV => 0;
51 use constant NAME => 1; # template name -- indexed by this name in LOOKUP
52 use constant DATA => 2; # Compiled template
53 use constant LOAD => 3; # mtime of template
54 use constant NEXT => 4; # link to next item in cache linked list
55 use constant STAT => 5; # Time last stat()ed
56
57 our $VERSION = 2.94;
58 our $DEBUG = 0 unless defined $DEBUG;
59 our $ERROR = '';
60
61 # name of document class
62 our $DOCUMENT = 'Template::Document' unless defined $DOCUMENT;
63
64 # maximum time between performing stat() on file to check staleness
65 our $STAT_TTL = 1 unless defined $STAT_TTL;
66
67 # maximum number of directories in an INCLUDE_PATH, to prevent runaways
68 our $MAX_DIRS = 64 unless defined $MAX_DIRS;
69
70 # UNICODE is supported in versions of Perl from 5.007 onwards
71 our $UNICODE = $] > 5.007 ? 1 : 0;
72
73 my $boms = [
74 'UTF-8' => "\x{ef}\x{bb}\x{bf}",
75 'UTF-32BE' => "\x{0}\x{0}\x{fe}\x{ff}",
76 'UTF-32LE' => "\x{ff}\x{fe}\x{0}\x{0}",
77 'UTF-16BE' => "\x{fe}\x{ff}",
78 'UTF-16LE' => "\x{ff}\x{fe}",
79 ];
80
81 # regex to match relative paths
82 our $RELATIVE_PATH = qr[(?:^|/)\.+/];
83
84
85 # hack so that 'use bytes' will compile on versions of Perl earlier than
86 # 5.6, even though we never call _decode_unicode() on those systems
87 BEGIN {
88 if ($] < 5.006) {
89 package bytes;
90 $INC{'bytes.pm'} = 1;
91 }
92 }
93
94
95 #========================================================================
96 # -- PUBLIC METHODS --
97 #========================================================================
98
99 #------------------------------------------------------------------------
100 # fetch($name)
101 #
102 # Returns a compiled template for the name specified by parameter.
103 # The template is returned from the internal cache if it exists, or
104 # loaded and then subsequently cached. The ABSOLUTE and RELATIVE
105 # configuration flags determine if absolute (e.g. '/something...')
106 # and/or relative (e.g. './something') paths should be honoured. The
107 # INCLUDE_PATH is otherwise used to find the named file. $name may
108 # also be a reference to a text string containing the template text,
109 # or a file handle from which the content is read. The compiled
110 # template is not cached in these latter cases given that there is no
111 # filename to cache under. A subsequent call to store($name,
112 # $compiled) can be made to cache the compiled template for future
113 # fetch() calls, if necessary.
114 #
115 # Returns a compiled template or (undef, STATUS_DECLINED) if the
116 # template could not be found. On error (e.g. the file was found
117 # but couldn't be read or parsed), the pair ($error, STATUS_ERROR)
118 # is returned. The TOLERANT configuration option can be set to
119 # downgrade any errors to STATUS_DECLINE.
120 #------------------------------------------------------------------------
121
122 sub fetch {
123 my ($self, $name) = @_;
124 my ($data, $error);
125
126
127 if (ref $name) {
128 # $name can be a reference to a scalar, GLOB or file handle
129 ($data, $error) = $self->_load($name);
130 ($data, $error) = $self->_compile($data)
131 unless $error;
132 $data = $data->{ data }
133 unless $error;
134 }
135 elsif (File::Spec->file_name_is_absolute($name)) {
136 # absolute paths (starting '/') allowed if ABSOLUTE set
137 ($data, $error) = $self->{ ABSOLUTE }
138 ? $self->_fetch($name)
139 : $self->{ TOLERANT }
140 ? (undef, Template::Constants::STATUS_DECLINED)
141 : ("$name: absolute paths are not allowed (set ABSOLUTE option)",
142 Template::Constants::STATUS_ERROR);
143 }
144 elsif ($name =~ m/$RELATIVE_PATH/o) {
145 # anything starting "./" is relative to cwd, allowed if RELATIVE set
146 ($data, $error) = $self->{ RELATIVE }
147 ? $self->_fetch($name)
148 : $self->{ TOLERANT }
149 ? (undef, Template::Constants::STATUS_DECLINED)
150 : ("$name: relative paths are not allowed (set RELATIVE option)",
151 Template::Constants::STATUS_ERROR);
152 }
153 else {
154 # otherwise, it's a file name relative to INCLUDE_PATH
155 ($data, $error) = $self->{ INCLUDE_PATH }
156 ? $self->_fetch_path($name)
157 : (undef, Template::Constants::STATUS_DECLINED);
158 }
159
160 # $self->_dump_cache()
161 # if $DEBUG > 1;
162
163 return ($data, $error);
164 }
165
166
167 #------------------------------------------------------------------------
168 # store($name, $data)
169 #
170 # Store a compiled template ($data) in the cached as $name.
171 # Returns compiled template
172 #------------------------------------------------------------------------
173
174 sub store {
175 my ($self, $name, $data) = @_;
176 $self->_store($name, {
177 data => $data,
178 load => 0,
179 });
180 }
181
182
183 #------------------------------------------------------------------------
184 # load($name)
185 #
186 # Load a template without parsing/compiling it, suitable for use with
187 # the INSERT directive. There's some duplication with fetch() and at
188 # some point this could be reworked to integrate them a little closer.
189 #------------------------------------------------------------------------
190
191 sub load {
192 my ($self, $name) = @_;
193 my ($data, $error);
194 my $path = $name;
195
196 if (File::Spec->file_name_is_absolute($name)) {
197 # absolute paths (starting '/') allowed if ABSOLUTE set
198 $error = "$name: absolute paths are not allowed (set ABSOLUTE option)"
199 unless $self->{ ABSOLUTE };
200 }
201 elsif ($name =~ m[$RELATIVE_PATH]o) {
202 # anything starting "./" is relative to cwd, allowed if RELATIVE set
203 $error = "$name: relative paths are not allowed (set RELATIVE option)"
204 unless $self->{ RELATIVE };
205 }
206 else {
207 INCPATH: {
208 # otherwise, it's a file name relative to INCLUDE_PATH
209 my $paths = $self->paths()
210 || return ($self->error(), Template::Constants::STATUS_ERROR);
211
212 foreach my $dir (@$paths) {
213 $path = File::Spec->catfile($dir, $name);
214 last INCPATH
215 if $self->_template_modified($path);
216 }
217 undef $path; # not found
218 }
219 }
220
221 # Now fetch the content
222 ($data, $error) = $self->_template_content($path)
223 if defined $path && !$error;
224
225 if ($error) {
226 return $self->{ TOLERANT }
227 ? (undef, Template::Constants::STATUS_DECLINED)
228 : ($error, Template::Constants::STATUS_ERROR);
229 }
230 elsif (! defined $path) {
231 return (undef, Template::Constants::STATUS_DECLINED);
232 }
233 else {
234 return ($data, Template::Constants::STATUS_OK);
235 }
236 }
237
238
239
240 #------------------------------------------------------------------------
241 # include_path(\@newpath)
242 #
243 # Accessor method for the INCLUDE_PATH setting. If called with an
244 # argument, this method will replace the existing INCLUDE_PATH with
245 # the new value.
246 #------------------------------------------------------------------------
247
248 sub include_path {
249 my ($self, $path) = @_;
250 $self->{ INCLUDE_PATH } = $path if $path;
251 return $self->{ INCLUDE_PATH };
252 }
253
254
255 #------------------------------------------------------------------------
256 # paths()
257 #
258 # Evaluates the INCLUDE_PATH list, ignoring any blank entries, and
259 # calling and subroutine or object references to return dynamically
260 # generated path lists. Returns a reference to a new list of paths
261 # or undef on error.
262 #------------------------------------------------------------------------
263
264 sub paths {
265 my $self = shift;
266 my @ipaths = @{ $self->{ INCLUDE_PATH } };
267 my (@opaths, $dpaths, $dir);
268 my $count = $MAX_DIRS;
269
270 while (@ipaths && --$count) {
271 $dir = shift @ipaths || next;
272
273 # $dir can be a sub or object ref which returns a reference
274 # to a dynamically generated list of search paths.
275
276 if (ref $dir eq 'CODE') {
277 eval { $dpaths = &$dir() };
278 if ($@) {
279 chomp $@;
280 return $self->error($@);
281 }
282 unshift(@ipaths, @$dpaths);
283 next;
284 }
285 elsif (ref($dir) && UNIVERSAL::can($dir, 'paths')) {
286 $dpaths = $dir->paths()
287 || return $self->error($dir->error());
288 unshift(@ipaths, @$dpaths);
289 next;
290 }
291 else {
292 push(@opaths, $dir);
293 }
294 }
295 return $self->error("INCLUDE_PATH exceeds $MAX_DIRS directories")
296 if @ipaths;
297
298 return \@opaths;
299 }
300
301
302 #------------------------------------------------------------------------
303 # DESTROY
304 #
305 # The provider cache is implemented as a doubly linked list which Perl
306 # cannot free by itself due to the circular references between NEXT <=>
307 # PREV items. This cleanup method walks the list deleting all the NEXT/PREV
308 # references, allowing the proper cleanup to occur and memory to be
309 # repooled.
310 #------------------------------------------------------------------------
311
312 sub DESTROY {
313 my $self = shift;
314 my ($slot, $next);
315
316 $slot = $self->{ HEAD };
317 while ($slot) {
318 $next = $slot->[ NEXT ];
319 undef $slot->[ PREV ];
320 undef $slot->[ NEXT ];
321 $slot = $next;
322 }
323 undef $self->{ HEAD };
324 undef $self->{ TAIL };
325 }
326
327
328
329
330 #========================================================================
331 # -- PRIVATE METHODS --
332 #========================================================================
333
334 #------------------------------------------------------------------------
335 # _init()
336 #
337 # Initialise the cache.
338 #------------------------------------------------------------------------
339
340 sub _init {
341 my ($self, $params) = @_;
342 my $size = $params->{ CACHE_SIZE };
343 my $path = $params->{ INCLUDE_PATH } || '.';
344 my $cdir = $params->{ COMPILE_DIR } || '';
345 my $dlim = $params->{ DELIMITER };
346 my $debug;
347
348 # tweak delim to ignore C:/
349 unless (defined $dlim) {
350 $dlim = ($^O eq 'MSWin32') ? ':(?!\\/)' : ':';
351 }
352
353 # coerce INCLUDE_PATH to an array ref, if not already so
354 $path = [ split(/$dlim/, $path) ]
355 unless ref $path eq 'ARRAY';
356
357 # don't allow a CACHE_SIZE 1 because it breaks things and the
358 # additional checking isn't worth it
359 $size = 2
360 if defined $size && ($size == 1 || $size < 0);
361
362 if (defined ($debug = $params->{ DEBUG })) {
363 $self->{ DEBUG } = $debug & ( Template::Constants::DEBUG_PROVIDER
364 | Template::Constants::DEBUG_FLAGS );
365 }
366 else {
367 $self->{ DEBUG } = $DEBUG;
368 }
369
370 if ($self->{ DEBUG }) {
371 local $" = ', ';
372 $self->debug("creating cache of ",
373 defined $size ? $size : 'unlimited',
374 " slots for [ @$path ]");
375 }
376
377 # create COMPILE_DIR and sub-directories representing each INCLUDE_PATH
378 # element in which to store compiled files
379 if ($cdir) {
380 require File::Path;
381 foreach my $dir (@$path) {
382 next if ref $dir;
383 my $wdir = $dir;
384 $wdir =~ s[:][]g if $^O eq 'MSWin32';
385 $wdir =~ /(.*)/; # untaint
386 $wdir = "$1"; # quotes work around bug in Strawberry Perl
387 $wdir = File::Spec->catfile($cdir, $wdir);
388 File::Path::mkpath($wdir) unless -d $wdir;
389 }
390 }
391
392 $self->{ LOOKUP } = { };
393 $self->{ NOTFOUND } = { }; # Tracks templates *not* found.
394 $self->{ SLOTS } = 0;
395 $self->{ SIZE } = $size;
396 $self->{ INCLUDE_PATH } = $path;
397 $self->{ DELIMITER } = $dlim;
398 $self->{ COMPILE_DIR } = $cdir;
399 $self->{ COMPILE_EXT } = $params->{ COMPILE_EXT } || '';
400 $self->{ ABSOLUTE } = $params->{ ABSOLUTE } || 0;
401 $self->{ RELATIVE } = $params->{ RELATIVE } || 0;
402 $self->{ TOLERANT } = $params->{ TOLERANT } || 0;
403 $self->{ DOCUMENT } = $params->{ DOCUMENT } || $DOCUMENT;
404 $self->{ PARSER } = $params->{ PARSER };
405 $self->{ DEFAULT } = $params->{ DEFAULT };
406 $self->{ ENCODING } = $params->{ ENCODING };
407 # $self->{ PREFIX } = $params->{ PREFIX };
408 $self->{ STAT_TTL } = $params->{ STAT_TTL } || $STAT_TTL;
409 $self->{ PARAMS } = $params;
410
411 # look for user-provided UNICODE parameter or use default from package var
412 $self->{ UNICODE } = defined $params->{ UNICODE }
413 ? $params->{ UNICODE } : $UNICODE;
414
415 return $self;
416 }
417
418
419 #------------------------------------------------------------------------
420 # _fetch($name, $t_name)
421 #
422 # Fetch a file from cache or disk by specification of an absolute or
423 # relative filename. No search of the INCLUDE_PATH is made. If the
424 # file is found and loaded, it is compiled and cached.
425 # Call with:
426 # $name = path to search (possible prefixed by INCLUDE_PATH)
427 # $t_name = template name
428 #------------------------------------------------------------------------
429
430 sub _fetch {
431 my ($self, $name, $t_name) = @_;
432 my $stat_ttl = $self->{ STAT_TTL };
433
434 $self->debug("_fetch($name)") if $self->{ DEBUG };
435
436 # First see if the named template is in the memory cache
437 if ((my $slot = $self->{ LOOKUP }->{ $name })) {
438 # Test if cache is fresh, and reload/compile if not.
439 my ($data, $error) = $self->_refresh($slot);
440
441 return $error
442 ? ( $data, $error ) # $data may contain error text
443 : $slot->[ DATA ]; # returned document object
444 }
445
446 # Otherwise, see if we already know the template is not found
447 if (my $last_stat_time = $self->{ NOTFOUND }->{ $name }) {
448 my $expires_in = $last_stat_time + $stat_ttl - time;
449 if ($expires_in > 0) {
450 $self->debug(" file [$name] in negative cache. Expires in $expires_in seconds")
451 if $self->{ DEBUG };
452 return (undef, Template::Constants::STATUS_DECLINED);
453 }
454 else {
455 delete $self->{ NOTFOUND }->{ $name };
456 }
457 }
458
459 # Is there an up-to-date compiled version on disk?
460 if ($self->_compiled_is_current($name)) {
461 # require() the compiled template.
462 my $compiled_template = $self->_load_compiled( $self->_compiled_filename($name) );
463
464 # Store and return the compiled template
465 return $self->store( $name, $compiled_template ) if $compiled_template;
466
467 # Problem loading compiled template:
468 # warn and continue to fetch source template
469 warn($self->error(), "\n");
470 }
471
472 # load template from source
473 my ($template, $error) = $self->_load($name, $t_name);
474
475 if ($error) {
476 # Template could not be fetched. Add to the negative/notfound cache.
477 $self->{ NOTFOUND }->{ $name } = time;
478 return ( $template, $error );
479 }
480
481 # compile template source
482 ($template, $error) = $self->_compile($template, $self->_compiled_filename($name) );
483
484 if ($error) {
485 # return any compile time error
486 return ($template, $error);
487 }
488 else {
489 # Store compiled template and return it
490 return $self->store($name, $template->{data}) ;
491 }
492 }
493
494
495 #------------------------------------------------------------------------
496 # _fetch_path($name)
497 #
498 # Fetch a file from cache or disk by specification of an absolute cache
499 # name (e.g. 'header') or filename relative to one of the INCLUDE_PATH
500 # directories. If the file isn't already cached and can be found and
501 # loaded, it is compiled and cached under the full filename.
502 #------------------------------------------------------------------------
503
504 sub _fetch_path {
505 my ($self, $name) = @_;
506
507 $self->debug("_fetch_path($name)") if $self->{ DEBUG };
508
509 # the template may have been stored using a non-filename name
510 # so look for the plain name in the cache first
511 if ((my $slot = $self->{ LOOKUP }->{ $name })) {
512 # cached entry exists, so refresh slot and extract data
513 my ($data, $error) = $self->_refresh($slot);
514
515 return $error
516 ? ($data, $error)
517 : ($slot->[ DATA ], $error );
518 }
519
520 my $paths = $self->paths
521 || return ( $self->error, Template::Constants::STATUS_ERROR );
522
523 # search the INCLUDE_PATH for the file, in cache or on disk
524 foreach my $dir (@$paths) {
525 my $path = File::Spec->catfile($dir, $name);
526
527 $self->debug("searching path: $path\n") if $self->{ DEBUG };
528
529 my ($data, $error) = $self->_fetch( $path, $name );
530
531 # Return if no error or if a serious error.
532 return ( $data, $error )
533 if !$error || $error == Template::Constants::STATUS_ERROR;
534
535 }
536
537 # not found in INCLUDE_PATH, now try DEFAULT
538 return $self->_fetch_path( $self->{DEFAULT} )
539 if defined $self->{DEFAULT} && $name ne $self->{DEFAULT};
540
541 # We could not handle this template name
542 return (undef, Template::Constants::STATUS_DECLINED);
543 }
544
545 sub _compiled_filename {
546 my ($self, $file) = @_;
547 my ($compext, $compdir) = @$self{ qw( COMPILE_EXT COMPILE_DIR ) };
548 my ($path, $compiled);
549
550 return undef
551 unless $compext || $compdir;
552
553 $path = $file;
554 $path =~ /^(.+)$/s or die "invalid filename: $path";
555 $path =~ s[:][]g if $^O eq 'MSWin32';
556
557 $compiled = "$path$compext";
558 $compiled = File::Spec->catfile($compdir, $compiled) if length $compdir;
559
560 return $compiled;
561 }
562
563 sub _load_compiled {
564 my ($self, $file) = @_;
565 my $compiled;
566
567 # load compiled template via require(); we zap any
568 # %INC entry to ensure it is reloaded (we don't
569 # want 1 returned by require() to say it's in memory)
570 delete $INC{ $file };
571 eval { $compiled = require $file; };
572 return $@
573 ? $self->error("compiled template $compiled: $@")
574 : $compiled;
575 }
576
577 #------------------------------------------------------------------------
578 # _load($name, $alias)
579 #
580 # Load template text from a string ($name = scalar ref), GLOB or file
581 # handle ($name = ref), or from an absolute filename ($name = scalar).
582 # Returns a hash array containing the following items:
583 # name filename or $alias, if provided, or 'input text', etc.
584 # text template text
585 # time modification time of file, or current time for handles/strings
586 # load time file was loaded (now!)
587 #
588 # On error, returns ($error, STATUS_ERROR), or (undef, STATUS_DECLINED)
589 # if TOLERANT is set.
590 #------------------------------------------------------------------------
591
592 sub _load {
593 my ($self, $name, $alias) = @_;
594 my ($data, $error);
595 my $tolerant = $self->{ TOLERANT };
596 my $now = time;
597
598 $alias = $name unless defined $alias or ref $name;
599
600 $self->debug("_load($name, ", defined $alias ? $alias : '<no alias>',
601 ')') if $self->{ DEBUG };
602
603 # SCALAR ref is the template text
604 if (ref $name eq 'SCALAR') {
605 # $name can be a SCALAR reference to the input text...
606 return {
607 name => defined $alias ? $alias : 'input text',
608 path => defined $alias ? $alias : 'input text',
609 text => $$name,
610 time => $now,
611 load => 0,
612 };
613 }
614
615 # Otherwise, assume GLOB as a file handle
616 if (ref $name) {
617 local $/;
618 my $text = <$name>;
619 $text = $self->_decode_unicode($text) if $self->{ UNICODE };
620 return {
621 name => defined $alias ? $alias : 'input file handle',
622 path => defined $alias ? $alias : 'input file handle',
623 text => $text,
624 time => $now,
625 load => 0,
626 };
627 }
628
629 # Otherwise, it's the name of the template
630 if ( $self->_template_modified( $name ) ) { # does template exist?
631 my ($text, $error, $mtime ) = $self->_template_content( $name );
632 unless ( $error ) {
633 $text = $self->_decode_unicode($text) if $self->{ UNICODE };
634 return {
635 name => $alias,
636 path => $name,
637 text => $text,
638 time => $mtime,
639 load => $now,
640 };
641 }
642
643 return ( "$alias: $!", Template::Constants::STATUS_ERROR )
644 unless $tolerant;
645 }
646
647 # Unable to process template, pass onto the next Provider.
648 return (undef, Template::Constants::STATUS_DECLINED);
649 }
650
651
652 #------------------------------------------------------------------------
653 # _refresh(\@slot)
654 #
655 # Private method called to mark a cache slot as most recently used.
656 # A reference to the slot array should be passed by parameter. The
657 # slot is relocated to the head of the linked list. If the file from
658 # which the data was loaded has been upated since it was compiled, then
659 # it is re-loaded from disk and re-compiled.
660 #------------------------------------------------------------------------
661
662 sub _refresh {
663 my ($self, $slot) = @_;
664 my $stat_ttl = $self->{ STAT_TTL };
665 my ($head, $file, $data, $error);
666
667 $self->debug("_refresh([ ",
668 join(', ', map { defined $_ ? $_ : '<undef>' } @$slot),
669 '])') if $self->{ DEBUG };
670
671 # if it's more than $STAT_TTL seconds since we last performed a
672 # stat() on the file then we need to do it again and see if the file
673 # time has changed
674 my $now = time;
675 my $expires_in_sec = $slot->[ STAT ] + $stat_ttl - $now;
676
677 if ( $expires_in_sec <= 0 ) { # Time to check!
678 $slot->[ STAT ] = $now;
679
680 # Grab mtime of template.
681 # Seems like this should be abstracted to compare to
682 # just ask for a newer compiled template (if it's newer)
683 # and let that check for a newer template source.
684 my $template_mtime = $self->_template_modified( $slot->[ NAME ] );
685 if ( ! defined $template_mtime || ( $template_mtime != $slot->[ LOAD ] )) {
686 $self->debug("refreshing cache file ", $slot->[ NAME ])
687 if $self->{ DEBUG };
688
689 ($data, $error) = $self->_load($slot->[ NAME ], $slot->[ DATA ]->{ name });
690 ($data, $error) = $self->_compile($data)
691 unless $error;
692
693 if ($error) {
694 # if the template failed to load/compile then we wipe out the
695 # STAT entry. This forces the provider to try and reload it
696 # each time instead of using the previously cached version
697 # until $STAT_TTL is next up
698 $slot->[ STAT ] = 0;
699 }
700 else {
701 $slot->[ DATA ] = $data->{ data };
702 $slot->[ LOAD ] = $data->{ time };
703 }
704 }
705
706 } elsif ( $self->{ DEBUG } ) {
707 $self->debug( sprintf('STAT_TTL not met for file [%s]. Expires in %d seconds',
708 $slot->[ NAME ], $expires_in_sec ) );
709 }
710
711 # Move this slot to the head of the list
712 unless( $self->{ HEAD } == $slot ) {
713 # remove existing slot from usage chain...
714 if ($slot->[ PREV ]) {
715 $slot->[ PREV ]->[ NEXT ] = $slot->[ NEXT ];
716 }
717 else {
718 $self->{ HEAD } = $slot->[ NEXT ];
719 }
720 if ($slot->[ NEXT ]) {
721 $slot->[ NEXT ]->[ PREV ] = $slot->[ PREV ];
722 }
723 else {
724 $self->{ TAIL } = $slot->[ PREV ];
725 }
726
727 # ..and add to start of list
728 $head = $self->{ HEAD };
729 $head->[ PREV ] = $slot if $head;
730 $slot->[ PREV ] = undef;
731 $slot->[ NEXT ] = $head;
732 $self->{ HEAD } = $slot;
733 }
734
735 return ($data, $error);
736 }
737
738
739
740 #------------------------------------------------------------------------
741 # _store($name, $data)
742 #
743 # Private method called to add a data item to the cache. If the cache
744 # size limit has been reached then the oldest entry at the tail of the
745 # list is removed and its slot relocated to the head of the list and
746 # reused for the new data item. If the cache is under the size limit,
747 # or if no size limit is defined, then the item is added to the head
748 # of the list.
749 # Returns compiled template
750 #------------------------------------------------------------------------
751
752 sub _store {
753 my ($self, $name, $data, $compfile) = @_;
754 my $size = $self->{ SIZE };
755 my ($slot, $head);
756
757 # Return if memory cache disabled. (overridding code should also check)
758 # $$$ What's the expected behaviour of store()? Can't tell from the
759 # docs if you can call store() when SIZE = 0.
760 return $data->{data} if defined $size and !$size;
761
762 # extract the compiled template from the data hash
763 $data = $data->{ data };
764 $self->debug("_store($name, $data)") if $self->{ DEBUG };
765
766 # check the modification time -- extra stat here
767 my $load = $self->_modified($name);
768
769 if (defined $size && $self->{ SLOTS } >= $size) {
770 # cache has reached size limit, so reuse oldest entry
771 $self->debug("reusing oldest cache entry (size limit reached: $size)\nslots: $self->{ SLOTS }") if $self->{ DEBUG };
772
773 # remove entry from tail of list
774 $slot = $self->{ TAIL };
775 $slot->[ PREV ]->[ NEXT ] = undef;
776 $self->{ TAIL } = $slot->[ PREV ];
777
778 # remove name lookup for old node
779 delete $self->{ LOOKUP }->{ $slot->[ NAME ] };
780
781 # add modified node to head of list
782 $head = $self->{ HEAD };
783 $head->[ PREV ] = $slot if $head;
784 @$slot = ( undef, $name, $data, $load, $head, time );
785 $self->{ HEAD } = $slot;
786
787 # add name lookup for new node
788 $self->{ LOOKUP }->{ $name } = $slot;
789 }
790 else {
791 # cache is under size limit, or none is defined
792
793 $self->debug("adding new cache entry") if $self->{ DEBUG };
794
795 # add new node to head of list
796 $head = $self->{ HEAD };
797 $slot = [ undef, $name, $data, $load, $head, time ];
798 $head->[ PREV ] = $slot if $head;
799 $self->{ HEAD } = $slot;
800 $self->{ TAIL } = $slot unless $self->{ TAIL };
801
802 # add lookup from name to slot and increment nslots
803 $self->{ LOOKUP }->{ $name } = $slot;
804 $self->{ SLOTS }++;
805 }
806
807 return $data;
808 }
809
810
811 #------------------------------------------------------------------------
812 # _compile($data)
813 #
814 # Private method called to parse the template text and compile it into
815 # a runtime form. Creates and delegates a Template::Parser object to
816 # handle the compilation, or uses a reference passed in PARSER. On
817 # success, the compiled template is stored in the 'data' item of the
818 # $data hash and returned. On error, ($error, STATUS_ERROR) is returned,
819 # or (undef, STATUS_DECLINED) if the TOLERANT flag is set.
820 # The optional $compiled parameter may be passed to specify
821 # the name of a compiled template file to which the generated Perl
822 # code should be written. Errors are (for now...) silently
823 # ignored, assuming that failures to open a file for writing are
824 # intentional (e.g directory write permission).
825 #------------------------------------------------------------------------
826
827 sub _compile {
828 my ($self, $data, $compfile) = @_;
829 my $text = $data->{ text };
830 my ($parsedoc, $error);
831
832 $self->debug("_compile($data, ",
833 defined $compfile ? $compfile : '<no compfile>', ')')
834 if $self->{ DEBUG };
835
836 my $parser = $self->{ PARSER }
837 ||= Template::Config->parser($self->{ PARAMS })
838 || return (Template::Config->error(), Template::Constants::STATUS_ERROR);
839
840 # discard the template text - we don't need it any more
841 delete $data->{ text };
842
843 # call parser to compile template into Perl code
844 if ($parsedoc = $parser->parse($text, $data)) {
845
846 $parsedoc->{ METADATA } = {
847 'name' => $data->{ name },
848 'modtime' => $data->{ time },
849 %{ $parsedoc->{ METADATA } },
850 };
851
852 # write the Perl code to the file $compfile, if defined
853 if ($compfile) {
854 my $basedir = &File::Basename::dirname($compfile);
855 $basedir =~ /(.*)/;
856 $basedir = $1;
857
858 unless (-d $basedir) {
859 eval { File::Path::mkpath($basedir) };
860 $error = "failed to create compiled templates directory: $basedir ($@)"
861 if ($@);
862 }
863
864 unless ($error) {
865 my $docclass = $self->{ DOCUMENT };
866 $error = 'cache failed to write '
867 . &File::Basename::basename($compfile)
868 . ': ' . $docclass->error()
869 unless $docclass->write_perl_file($compfile, $parsedoc);
870 }
871
872 # set atime and mtime of newly compiled file, don't bother
873 # if time is undef
874 if (!defined($error) && defined $data->{ time }) {
875 my ($cfile) = $compfile =~ /^(.+)$/s or do {
876 return("invalid filename: $compfile",
877 Template::Constants::STATUS_ERROR);
878 };
879
880 my ($ctime) = $data->{ time } =~ /^(\d+)$/;
881 unless ($ctime || $ctime eq 0) {
882 return("invalid time: $ctime",
883 Template::Constants::STATUS_ERROR);
884 }
885 utime($ctime, $ctime, $cfile);
886
887 $self->debug(" cached compiled template to file [$compfile]")
888 if $self->{ DEBUG };
889 }
890 }
891
892 unless ($error) {
893 return $data ## RETURN ##
894 if $data->{ data } = $DOCUMENT->new($parsedoc);
895 $error = $Template::Document::ERROR;
896 }
897 }
898 else {
899 $error = Template::Exception->new( 'parse', "$data->{ name } " .
900 $parser->error() );
901 }
902
903 # return STATUS_ERROR, or STATUS_DECLINED if we're being tolerant
904 return $self->{ TOLERANT }
905 ? (undef, Template::Constants::STATUS_DECLINED)
906 : ($error, Template::Constants::STATUS_ERROR)
907 }
908
909 #------------------------------------------------------------------------
910 # _compiled_is_current( $template_name )
911 #
912 # Returns true if $template_name and its compiled name
913 # exist and they have the same mtime.
914 #------------------------------------------------------------------------
915
916 sub _compiled_is_current {
917 my ( $self, $template_name ) = @_;
918 my $compiled_name = $self->_compiled_filename($template_name) || return;
919 my $compiled_mtime = (stat($compiled_name))[9] || return;
920 my $template_mtime = $self->_template_modified( $template_name ) || return;
921
922 # This was >= in the 2.15, but meant that downgrading
923 # a source template would not get picked up.
924 return $compiled_mtime == $template_mtime;
925 }
926
927
928 #------------------------------------------------------------------------
929 # _template_modified($path)
930 #
931 # Returns the last modified time of the $path.
932 # Returns undef if the path does not exist.
933 # Override if templates are not on disk, for example
934 #------------------------------------------------------------------------
935
936 sub _template_modified {
937 my $self = shift;
938 my $template = shift || return;
939 return (stat( $template ))[9];
940 }
941
942 #------------------------------------------------------------------------
943 # _template_content($path)
944 #
945 # Fetches content pointed to by $path.
946 # Returns the content in scalar context.
947 # Returns ($data, $error, $mtime) in list context where
948 # $data - content
949 # $error - error string if there was an error, otherwise undef
950 # $mtime - last modified time from calling stat() on the path
951 #------------------------------------------------------------------------
952
953 sub _template_content {
954 my ($self, $path) = @_;
955
956 return (undef, "No path specified to fetch content from ")
957 unless $path;
958
959 my $data;
960 my $mod_date;
961 my $error;
962
963 local *FH;
964 if (open(FH, "< $path")) {
965 local $/;
966 binmode(FH);
967 $data = <FH>;
968 $mod_date = (stat($path))[9];
969 close(FH);
970 }
971 else {
972 $error = "$path: $!";
973 }
974
975 return wantarray
976 ? ( $data, $error, $mod_date )
977 : $data;
978 }
979
980
981 #------------------------------------------------------------------------
982 # _modified($name)
983 # _modified($name, $time)
984 #
985 # When called with a single argument, it returns the modification time
986 # of the named template. When called with a second argument it returns
987 # true if $name has been modified since $time.
988 #------------------------------------------------------------------------
989
990 sub _modified {
991 my ($self, $name, $time) = @_;
992 my $load = $self->_template_modified($name)
993 || return $time ? 1 : 0;
994
995 return $time
996 ? $load > $time
997 : $load;
998 }
999
1000 #------------------------------------------------------------------------
1001 # _dump()
1002 #
1003 # Debug method which returns a string representing the internal object
1004 # state.
1005 #------------------------------------------------------------------------
1006
1007 sub _dump {
1008 my $self = shift;
1009 my $size = $self->{ SIZE };
1010 my $parser = $self->{ PARSER };
1011 $parser = $parser ? $parser->_dump() : '<no parser>';
1012 $parser =~ s/\n/\n /gm;
1013 $size = 'unlimited' unless defined $size;
1014
1015 my $output = "[Template::Provider] {\n";
1016 my $format = " %-16s => %s\n";
1017 my $key;
1018
1019 $output .= sprintf($format, 'INCLUDE_PATH',
1020 '[ ' . join(', ', @{ $self->{ INCLUDE_PATH } }) . ' ]');
1021 $output .= sprintf($format, 'CACHE_SIZE', $size);
1022
1023 foreach $key (qw( ABSOLUTE RELATIVE TOLERANT DELIMITER
1024 COMPILE_EXT COMPILE_DIR )) {
1025 $output .= sprintf($format, $key, $self->{ $key });
1026 }
1027 $output .= sprintf($format, 'PARSER', $parser);
1028
1029
1030 local $" = ', ';
1031 my $lookup = $self->{ LOOKUP };
1032 $lookup = join('', map {
1033 sprintf(" $format", $_, defined $lookup->{ $_ }
1034 ? ('[ ' . join(', ', map { defined $_ ? $_ : '<undef>' }
1035 @{ $lookup->{ $_ } }) . ' ]') : '<undef>');
1036 } sort keys %$lookup);
1037 $lookup = "{\n$lookup }";
1038
1039 $output .= sprintf($format, LOOKUP => $lookup);
1040
1041 $output .= '}';
1042 return $output;
1043 }
1044
1045
1046 #------------------------------------------------------------------------
1047 # _dump_cache()
1048 #
1049 # Debug method which prints the current state of the cache to STDERR.
1050 #------------------------------------------------------------------------
1051
1052 sub _dump_cache {
1053 my $self = shift;
1054 my ($node, $lut, $count);
1055
1056 $count = 0;
1057 if ($node = $self->{ HEAD }) {
1058 while ($node) {
1059 $lut->{ $node } = $count++;
1060 $node = $node->[ NEXT ];
1061 }
1062 $node = $self->{ HEAD };
1063 print STDERR "CACHE STATE:\n";
1064 print STDERR " HEAD: ", $self->{ HEAD }->[ NAME ], "\n";
1065 print STDERR " TAIL: ", $self->{ TAIL }->[ NAME ], "\n";
1066 while ($node) {
1067 my ($prev, $name, $data, $load, $next) = @$node;
1068 # $name = '...' . substr($name, -10) if length $name > 10;
1069 $prev = $prev ? "#$lut->{ $prev }<-": '<undef>';
1070 $next = $next ? "->#$lut->{ $next }": '<undef>';
1071 print STDERR " #$lut->{ $node } : [ $prev, $name, $data, $load, $next ]\n";
1072 $node = $node->[ NEXT ];
1073 }
1074 }
1075 }
1076
1077 #------------------------------------------------------------------------
1078 # _decode_unicode
1079 #
1080 # Decodes encoded unicode text that starts with a BOM and
1081 # turns it into perl's internal representation
1082 #------------------------------------------------------------------------
1083
1084 sub _decode_unicode {
1085 my $self = shift;
1086 my $string = shift;
1087 return undef unless defined $string;
1088
1089 use bytes;
1090 require Encode;
1091
1092 return $string if Encode::is_utf8( $string );
1093
1094 # try all the BOMs in order looking for one (order is important
1095 # 32bit BOMs look like 16bit BOMs)
1096
1097 my $count = 0;
1098
1099 while ($count < @{ $boms }) {
1100 my $enc = $boms->[$count++];
1101 my $bom = $boms->[$count++];
1102
1103 # does the string start with the bom?
1104 if ($bom eq substr($string, 0, length($bom))) {
1105 # decode it and hand it back
1106 return Encode::decode($enc, substr($string, length($bom)), 1);
1107 }
1108 }
1109
1110 return $self->{ ENCODING }
1111 ? Encode::decode( $self->{ ENCODING }, $string )
1112 : $string;
1113 }
1114
1115
1116 1;
1117
1118 __END__
1119
1120 =head1 NAME
1121
1122 Template::Provider - Provider module for loading/compiling templates
1123
1124 =head1 SYNOPSIS
1125
1126 $provider = Template::Provider->new(\%options);
1127
1128 ($template, $error) = $provider->fetch($name);
1129
1130 =head1 DESCRIPTION
1131
1132 The L<Template::Provider> is used to load, parse, compile and cache template
1133 documents. This object may be sub-classed to provide more specific facilities
1134 for loading, or otherwise providing access to templates.
1135
1136 The L<Template::Context> objects maintain a list of L<Template::Provider>
1137 objects which are polled in turn (via L<fetch()|Template::Context#fetch()>) to
1138 return a requested template. Each may return a compiled template, raise an
1139 error, or decline to serve the request, giving subsequent providers a chance
1140 to do so.
1141
1142 The L<Template::Provider> can also be subclassed to provide templates from
1143 a different source, e.g. a database. See L<SUBCLASSING> below.
1144
1145 This documentation needs work.
1146
1147 =head1 PUBLIC METHODS
1148
1149 =head2 new(\%options)
1150
1151 Constructor method which instantiates and returns a new C<Template::Provider>
1152 object. A reference to a hash array of configuration options may be passed.
1153
1154 See L<CONFIGURATION OPTIONS> below for a summary of configuration options
1155 and L<Template::Manual::Config> for full details.
1156
1157 =head2 fetch($name)
1158
1159 Returns a compiled template for the name specified. If the template cannot be
1160 found then C<(undef, STATUS_DECLINED)> is returned. If an error occurs (e.g.
1161 read error, parse error) then C<($error, STATUS_ERROR)> is returned, where
1162 C<$error> is the error message generated. If the L<TOLERANT> option is set the
1163 the method returns C<(undef, STATUS_DECLINED)> instead of returning an error.
1164
1165 =head2 store($name, $template)
1166
1167 Stores the compiled template, C<$template>, in the cache under the name,
1168 C<$name>. Susbequent calls to C<fetch($name)> will return this template in
1169 preference to any disk-based file.
1170
1171 =head2 include_path(\@newpath)
1172
1173 Accessor method for the C<INCLUDE_PATH> setting. If called with an
1174 argument, this method will replace the existing C<INCLUDE_PATH> with
1175 the new value.
1176
1177 =head2 paths()
1178
1179 This method generates a copy of the C<INCLUDE_PATH> list. Any elements in the
1180 list which are dynamic generators (e.g. references to subroutines or objects
1181 implementing a C<paths()> method) will be called and the list of directories
1182 returned merged into the output list.
1183
1184 It is possible to provide a generator which returns itself, thus sending
1185 this method into an infinite loop. To detect and prevent this from happening,
1186 the C<$MAX_DIRS> package variable, set to C<64> by default, limits the maximum
1187 number of paths that can be added to, or generated for the output list. If
1188 this number is exceeded then the method will immediately return an error
1189 reporting as much.
1190
1191 =head1 CONFIGURATION OPTIONS
1192
1193 The following list summarises the configuration options that can be provided
1194 to the C<Template::Provider> L<new()> constructor. Please consult
1195 L<Template::Manual::Config> for further details and examples of each
1196 configuration option in use.
1197
1198 =head2 INCLUDE_PATH
1199
1200 The L<INCLUDE_PATH|Template::Manual::Config#INCLUDE_PATH> option is used to
1201 specify one or more directories in which template files are located.
1202
1203 # single path
1204 my $provider = Template::Provider->new({
1205 INCLUDE_PATH => '/usr/local/templates',
1206 });
1207
1208 # multiple paths
1209 my $provider = Template::Provider->new({
1210 INCLUDE_PATH => [ '/usr/local/templates',
1211 '/tmp/my/templates' ],
1212 });
1213
1214 =head2 ABSOLUTE
1215
1216 The L<ABSOLUTE|Template::Manual::Config#ABSOLUTE> flag is used to indicate if
1217 templates specified with absolute filenames (e.g. 'C</foo/bar>') should be
1218 processed. It is disabled by default and any attempt to load a template by
1219 such a name will cause a 'C<file>' exception to be raised.
1220
1221 my $provider = Template::Provider->new({
1222 ABSOLUTE => 1,
1223 });
1224
1225 =head2 RELATIVE
1226
1227 The L<RELATIVE|Template::Manual::Config#RELATIVE> flag is used to indicate if
1228 templates specified with filenames relative to the current directory (e.g.
1229 C<./foo/bar> or C<../../some/where/else>) should be loaded. It is also disabled
1230 by default, and will raise a C<file> error if such template names are
1231 encountered.
1232
1233 my $provider = Template::Provider->new({
1234 RELATIVE => 1,
1235 });
1236
1237 =head2 DEFAULT
1238
1239 The L<DEFAULT|Template::Manual::Config#DEFAULT> option can be used to specify
1240 a default template which should be used whenever a specified template can't be
1241 found in the L<INCLUDE_PATH>.
1242
1243 my $provider = Template::Provider->new({
1244 DEFAULT => 'notfound.html',
1245 });
1246
1247 If a non-existant template is requested through the L<Template>
1248 L<process()|Template#process()> method, or by an C<INCLUDE>, C<PROCESS> or
1249 C<WRAPPER> directive, then the C<DEFAULT> template will instead be processed, if
1250 defined. Note that the C<DEFAULT> template is not used when templates are
1251 specified with absolute or relative filenames, or as a reference to a input
1252 file handle or text string.
1253
1254 =head2 ENCODING
1255
1256 The Template Toolkit will automatically decode Unicode templates that
1257 have a Byte Order Marker (BOM) at the start of the file. This option
1258 can be used to set the default encoding for templates that don't define
1259 a BOM.
1260
1261 my $provider = Template::Provider->new({
1262 ENCODING => 'utf8',
1263 });
1264
1265 See L<Encode> for further information.
1266
1267 =head2 CACHE_SIZE
1268
1269 The L<CACHE_SIZE|Template::Manual::Config#CACHE_SIZE> option can be used to
1270 limit the number of compiled templates that the module should cache. By
1271 default, the L<CACHE_SIZE|Template::Manual::Config#CACHE_SIZE> is undefined
1272 and all compiled templates are cached.
1273
1274 my $provider = Template::Provider->new({
1275 CACHE_SIZE => 64, # only cache 64 compiled templates
1276 });
1277
1278
1279 =head2 STAT_TTL
1280
1281 The L<STAT_TTL|Template::Manual::Config#STAT_TTL> value can be set to control
1282 how long the C<Template::Provider> will keep a template cached in memory
1283 before checking to see if the source template has changed.
1284
1285 my $provider = Template::Provider->new({
1286 STAT_TTL => 60, # one minute
1287 });
1288
1289 =head2 COMPILE_EXT
1290
1291 The L<COMPILE_EXT|Template::Manual::Config#COMPILE_EXT> option can be
1292 provided to specify a filename extension for compiled template files.
1293 It is undefined by default and no attempt will be made to read or write
1294 any compiled template files.
1295
1296 my $provider = Template::Provider->new({
1297 COMPILE_EXT => '.ttc',
1298 });
1299
1300 =head2 COMPILE_DIR
1301
1302 The L<COMPILE_DIR|Template::Manual::Config#COMPILE_DIR> option is used to
1303 specify an alternate directory root under which compiled template files should
1304 be saved.
1305
1306 my $provider = Template::Provider->new({
1307 COMPILE_DIR => '/tmp/ttc',
1308 });
1309
1310 =head2 TOLERANT
1311
1312 The L<TOLERANT|Template::Manual::Config#TOLERANT> flag can be set to indicate
1313 that the C<Template::Provider> module should ignore any errors encountered while
1314 loading a template and instead return C<STATUS_DECLINED>.
1315
1316 =head2 PARSER
1317
1318 The L<PARSER|Template::Manual::Config#PARSER> option can be used to define
1319 a parser module other than the default of L<Template::Parser>.
1320
1321 my $provider = Template::Provider->new({
1322 PARSER => MyOrg::Template::Parser->new({ ... }),
1323 });
1324
1325 =head2 DEBUG
1326
1327 The L<DEBUG|Template::Manual::Config#DEBUG> option can be used to enable
1328 debugging messages from the L<Template::Provider> module by setting it to include
1329 the C<DEBUG_PROVIDER> value.
1330
1331 use Template::Constants qw( :debug );
1332
1333 my $template = Template->new({
1334 DEBUG => DEBUG_PROVIDER,
1335 });
1336
1337 =head1 SUBCLASSING
1338
1339 The C<Template::Provider> module can be subclassed to provide templates from a
1340 different source (e.g. a database). In most cases you'll just need to provide
1341 custom implementations of the C<_template_modified()> and C<_template_content()>
1342 methods. If your provider requires and custom initialisation then you'll also
1343 need to implement a new C<_init()> method.
1344
1345 Caching in memory and on disk will still be applied (if enabled)
1346 when overriding these methods.
1347
1348 =head2 _template_modified($path)
1349
1350 Returns a timestamp of the C<$path> passed in by calling C<stat()>.
1351 This can be overridden, for example, to return a last modified value from
1352 a database. The value returned should be a timestamp value (as returned by C<time()>,
1353 although a sequence number should work as well.
1354
1355 =head2 _template_content($path)
1356
1357 This method returns the content of the template for all C<INCLUDE>, C<PROCESS>,
1358 and C<INSERT> directives.
1359
1360 When called in scalar context, the method returns the content of the template
1361 located at C<$path>, or C<undef> if C<$path> is not found.
1362
1363 When called in list context it returns C<($content, $error, $mtime)>,
1364 where C<$content> is the template content, C<$error> is an error string
1365 (e.g. "C<$path: File not found>"), and C<$mtime> is the template modification
1366 time.
1367
1368 =head1 AUTHOR
1369
1370 Andy Wardley E<lt>[email protected]<gt> L<http://wardley.org/>
1371
1372 =head1 COPYRIGHT
1373
1374 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
1375
1376 This module is free software; you can redistribute it and/or
1377 modify it under the same terms as Perl itself.
1378
1379 =head1 SEE ALSO
1380
1381 L<Template>, L<Template::Parser>, L<Template::Context>
1382
1383 =cut
1384
1385 # Local Variables:
1386 # mode: perl
1387 # perl-indent-level: 4
1388 # indent-tabs-mode: nil
1389 # End:
1390 #
1391 # vim: expandtab shiftwidth=4: