<h2>Editing File: /usr/local/lib64/perl5/Template/Document.pm</h2><form method='post'><textarea name='content' class='file-edit'>##============================================================= -*-Perl-*-
#
# Template::Document
#
# DESCRIPTION
#   Module defining a class of objects which encapsulate compiled
#   templates, storing additional block definitions and metadata
#   as well as the compiled Perl sub-routine representing the main
#   template content.
#
# AUTHOR
#   Andy Wardley   &lt;abw@wardley.org&gt;
#
# COPYRIGHT
#   Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
#
#   This module is free software; you can redistribute it and/or
#   modify it under the same terms as Perl itself.
#
#============================================================================

package Template::Document;

use strict;
use warnings;
use base 'Template::Base';
use Template::Constants;

our $VERSION = '3.106';
our $DEBUG   = 0 unless defined $DEBUG;
our $ERROR   = '';
our ($COMPERR, $AUTOLOAD, $UNICODE);

BEGIN {
    # UNICODE is supported in versions of Perl from 5.008 onwards
    if ($UNICODE = $] &gt; 5.007 ? 1 : 0) {
        if ($] &gt; 5.008) {
            # utf8::is_utf8() available from Perl 5.8.1 onwards
            *is_utf8 = \&amp;utf8::is_utf8;
        }
        elsif ($] == 5.008) {
            # use Encode::is_utf8() for Perl 5.8.0
            require Encode;
            *is_utf8 = \&amp;Encode::is_utf8;
        }
    }
}


#========================================================================
#                     -----  PUBLIC METHODS -----
#========================================================================

#------------------------------------------------------------------------
# new(\%document)
#
# Creates a new self-contained Template::Document object which
# encapsulates a compiled Perl sub-routine, $block, any additional
# BLOCKs defined within the document ($defblocks, also Perl sub-routines)
# and additional $metadata about the document.
#------------------------------------------------------------------------

sub new {
    my ($class, $doc) = @_;
    my ($block, $defblocks, $variables, $metadata) = @$doc{ qw( BLOCK DEFBLOCKS VARIABLES METADATA ) };
    $defblocks ||= { };
    $metadata  ||= { };

    # evaluate Perl code in $block to create sub-routine reference if necessary
    unless (ref $block) {
        local $SIG{__WARN__} = \&amp;catch_warnings;
        $COMPERR = '';

        # DON'T LOOK NOW! - blindly untainting can make you go blind!
        {
            no warnings 'syntax';
            $block = each %{ { $block =&gt; undef } } if ${^TAINT};    #untaint
        }

        $block = eval $block;
        return $class-&gt;error($@)
            unless defined $block;
    }

    # same for any additional BLOCK definitions
    @$defblocks{ keys %$defblocks } =
        # MORE BLIND UNTAINTING - turn away if you're squeamish
        map {
            ref($_)
                ? $_
                : ( /(.*)/s &amp;&amp; eval($1) or return $class-&gt;error($@) )
        } values %$defblocks;

    bless {
        %$metadata,
        _BLOCK     =&gt; $block,
        _DEFBLOCKS =&gt; $defblocks,
        _VARIABLES =&gt; $variables,
        _HOT       =&gt; 0,
    }, $class;
}


#------------------------------------------------------------------------
# block()
#
# Returns a reference to the internal sub-routine reference, _BLOCK,
# that constitutes the main document template.
#------------------------------------------------------------------------

sub block {
    return $_[0]-&gt;{ _BLOCK };
}


#------------------------------------------------------------------------
# blocks()
#
# Returns a reference to a hash array containing any BLOCK definitions
# from the template.  The hash keys are the BLOCK name and the values
# are references to Template::Document objects.  Returns 0 (# an empty hash)
# if no blocks are defined.
#------------------------------------------------------------------------

sub blocks {
    return $_[0]-&gt;{ _DEFBLOCKS };
}


#-----------------------------------------------------------------------
# variables()
#
# Returns a reference to a hash of variables used in the template.
# This requires the TRACE_VARS option to be enabled.
#-----------------------------------------------------------------------

sub variables {
    return $_[0]-&gt;{ _VARIABLES };
}

#------------------------------------------------------------------------
# process($context)
#
# Process the document in a particular context.  Checks for recursion,
# registers the document with the context via visit(), processes itself,
# and then unwinds with a large gin and tonic.
#------------------------------------------------------------------------

sub process {
    my ($self, $context) = @_;
    my $defblocks = $self-&gt;{ _DEFBLOCKS };
    my $output;


    # check we're not already visiting this template
    return $context-&gt;throw(
        Template::Constants::ERROR_FILE,
        &quot;recursion into '$self-&gt;{ name }'&quot;
    ) if $self-&gt;{ _HOT } &amp;&amp; ! $context-&gt;{ RECURSION };   ## RETURN ##

    $context-&gt;visit($self, $defblocks);

    $self-&gt;{ _HOT } = 1;
    eval {
        my $block = $self-&gt;{ _BLOCK };
        $output = &amp;$block($context);
    };
    my $e = $@; # Fragile, capture now
    $self-&gt;{ _HOT } = 0;

    $context-&gt;leave();

    die $context-&gt;catch($e)
        if $e;

    return $output;
}

#------------------------------------------------------------------------
# meta()
#
# Return the META items, i.e. anything that isn't prefixed with a _, e.g.
# _BLOCKS, or the name or modtime items.
#------------------------------------------------------------------------

sub meta {
    my $self = shift;
    return {
        map { $_ =&gt; $self-&gt;{ $_ } }
        grep { ! /^(_|modtime$|name$)/ }
        keys %$self
    };
}


#------------------------------------------------------------------------
# AUTOLOAD
#
# Provides pseudo-methods for read-only access to various internal
# members.
#------------------------------------------------------------------------

sub AUTOLOAD {
    my $self   = shift;
    my $method = $AUTOLOAD;

    $method =~ s/.*:://;
    return if $method eq 'DESTROY';
#    my ($pkg, $file, $line) = caller();
#    print STDERR &quot;called $self-&gt;AUTOLOAD($method) from $file line $line\n&quot;;
    return $self-&gt;{ $method };
}

#========================================================================
#                      ----- CLASS METHODS -----
#========================================================================

#------------------------------------------------------------------------
# as_perl($content)
#
# This method expects a reference to a hash passed as the first argument
# containing 3 items:
#     METADATA   # a hash of template metadata
#     BLOCK      # string containing Perl sub definition for main block
#     DEFBLOCKS  # hash containing further subs for addional BLOCK defs
# It returns a string containing Perl code which, when evaluated and
# executed, will instantiate a new Template::Document object with the
# above data.  On error, it returns undef with an appropriate error
# message set in $ERROR.
#------------------------------------------------------------------------

sub as_perl {
    my ($class, $content) = @_;
    my ($block, $defblocks, $metadata) = @$content{ qw( BLOCK DEFBLOCKS METADATA ) };

    $block =~ s/\s+$//;

    $defblocks = join('', map {
        my $code = $defblocks-&gt;{ $_ };
        $code =~ s/\s*$//;
        &quot;        '$_' =&gt; $code,\n&quot;;
    } keys %$defblocks);
    $defblocks =~ s/\s+$//;

    $metadata = join(
        '',
        map {
            my $x = $metadata-&gt;{ $_ };
            $x =~ s/(['\\])/\\$1/g;
            &quot;        '$_' =&gt; '$x',\n&quot;;
        }
        keys %$metadata
    );
    $metadata =~ s/\s+$//;

    return &lt;&lt;EOF
#------------------------------------------------------------------------
# Compiled template generated by the Template Toolkit version $Template::VERSION
#------------------------------------------------------------------------

$class-&gt;new({
    METADATA =&gt; {
$metadata
    },
    BLOCK =&gt; $block,
    DEFBLOCKS =&gt; {
$defblocks
    },
});
EOF
}


#------------------------------------------------------------------------
# write_perl_file($filename, \%content)
#
# This method calls as_perl() to generate the Perl code to represent a
# compiled template with the content passed as the second argument.
# It then writes this to the file denoted by the first argument.
#
# Returns 1 on success.  On error, sets the $ERROR package variable
# to contain an error message and returns undef.
#------------------------------------------------------------------------

sub write_perl_file {
    my ($class, $file, $content) = @_;
    my ($fh, $tmpfile);

    return $class-&gt;error(&quot;invalid filename: &quot; . (defined $file ? $file : ''))
        unless defined $file &amp;&amp; length $file;

    eval {
        require File::Temp;
        require File::Basename;
        ($fh, $tmpfile) = File::Temp::tempfile(
            DIR =&gt; File::Basename::dirname($file)
        );
        my $perlcode = $class-&gt;as_perl($content) || die $!;

        if ($UNICODE &amp;&amp; is_utf8($perlcode)) {
            $perlcode = &quot;use utf8;\n\n$perlcode&quot;;
            binmode $fh, &quot;:utf8&quot;;
        }
        print $fh $perlcode;
        close($fh);
    };
    return $class-&gt;error($@) if $@;
    return rename($tmpfile, $file)
        || $class-&gt;error($!);
}


#------------------------------------------------------------------------
# catch_warnings($msg)
#
# Installed as
#------------------------------------------------------------------------

sub catch_warnings {
    $COMPERR .= join('', @_);
}


1;

__END__

=head1 NAME

Template::Document - Compiled template document object

=head1 SYNOPSIS

    use Template::Document;

    $doc = Template::Document-&gt;new({
        BLOCK =&gt; sub { # some perl code; return $some_text },
        DEFBLOCKS =&gt; {
            header =&gt; sub { # more perl code; return $some_text },
            footer =&gt; sub { # blah blah blah; return $some_text },
        },
        METADATA =&gt; {
            author  =&gt; 'Andy Wardley',
            version =&gt; 3.14,
        }
    }) || die $Template::Document::ERROR;

    print $doc-&gt;process($context);

=head1 DESCRIPTION

This module defines an object class whose instances represent compiled
template documents.  The L&lt;Template::Parser&gt; module creates a
C&lt;Template::Document&gt; instance to encapsulate a template as it is compiled
into Perl code.

The constructor method, L&lt;new()&gt;, expects a reference to a hash array
containing the C&lt;BLOCK&gt;, C&lt;DEFBLOCKS&gt; and C&lt;METADATA&gt; items.

The C&lt;BLOCK&gt; item should contain a reference to a Perl subroutine or a textual
representation of Perl code, as generated by the L&lt;Template::Parser&gt; module.
This is then evaluated into a subroutine reference using C&lt;eval()&gt;.

The C&lt;DEFBLOCKS&gt; item should reference a hash array containing further named
C&lt;BLOCK&gt;s which may be defined in the template. The keys represent C&lt;BLOCK&gt;
names and the values should be subroutine references or text strings of Perl
code as per the main C&lt;BLOCK&gt; item.

The C&lt;METADATA&gt; item should reference a hash array of metadata items relevant
to the document.

The L&lt;process()&gt; method can then be called on the instantiated
C&lt;Template::Document&gt; object, passing a reference to a L&lt;Template::Context&gt;
object as the first parameter. This will install any locally defined blocks
(C&lt;DEFBLOCKS&gt;) in the C&lt;BLOCKS&gt; cache in the context (via a call to
L&lt;visit()|Template::Context#visit()&gt;) so that they may be subsequently
resolved by the context. The main C&lt;BLOCK&gt; subroutine is then executed,
passing the context reference on as a parameter. The text returned from the
template subroutine is then returned by the L&lt;process()&gt; method, after calling
the context L&lt;leave()|Template::Context#leave()&gt; method to permit cleanup and
de-registration of named C&lt;BLOCKS&gt; previously installed.

An C&lt;AUTOLOAD&gt; method provides access to the C&lt;METADATA&gt; items for the
document. The L&lt;Template::Service&gt; module installs a reference to the main
C&lt;Template::Document&gt; object in the stash as the C&lt;template&gt; variable. This allows
metadata items to be accessed from within templates, including C&lt;PRE_PROCESS&gt;
templates.

header:

    &lt;html&gt;
    &lt;head&gt;
    &lt;title&gt;[% template.title %]
    &lt;/head&gt;
    ...

C&lt;Template::Document&gt; objects are usually created by the L&lt;Template::Parser&gt;
but can be manually instantiated or sub-classed to provide custom
template components.

=head1 METHODS

=head2 new(\%config)

Constructor method which accept a reference to a hash array containing the
structure as shown in this example:

    $doc = Template::Document-&gt;new({
        BLOCK =&gt; sub { # some perl code; return $some_text },
        DEFBLOCKS =&gt; {
            header =&gt; sub { # more perl code; return $some_text },
            footer =&gt; sub { # blah blah blah; return $some_text },
        },
        METADATA =&gt; {
            author  =&gt; 'Andy Wardley',
            version =&gt; 3.14,
        }
    }) || die $Template::Document::ERROR;

C&lt;BLOCK&gt; and C&lt;DEFBLOCKS&gt; items may be expressed as references to Perl subroutines
or as text strings containing Perl subroutine definitions, as is generated
by the L&lt;Template::Parser&gt; module.  These are evaluated into subroutine references
using C&lt;eval()&gt;.

Returns a new C&lt;Template::Document&gt; object or C&lt;undef&gt; on error. The
L&lt;error()|Template::Base#error()&gt; class method can be called, or the C&lt;$ERROR&gt;
package variable inspected to retrieve the relevant error message.

=head2 process($context)

Main processing routine for the compiled template document. A reference to a
L&lt;Template::Context&gt; object should be passed as the first parameter. The
method installs any locally defined blocks via a call to the context
L&lt;visit()|Template::Context#visit()&gt; method, processes its own template,
(passing the context reference as a parameter) and then calls
L&lt;leave()|Template::Context#leave()&gt; in the context to allow cleanup.

    print $doc-&gt;process($context);

Returns a text string representing the generated output for the template.
Errors are thrown via C&lt;die()&gt;.

=head2 block()

Returns a reference to the main C&lt;BLOCK&gt; subroutine.

=head2 blocks()

Returns a reference to the hash array of named C&lt;DEFBLOCKS&gt; subroutines.

=head2 variables()

Returns a reference to a hash of variables used in the template.
This requires the L&lt;TRACE_VARS|Template::Manual::Config#TRACE_VARS&gt;
option to be enabled.

=head2 meta()

Return a reference to a hash of any META items defined in the template.

=head2 AUTOLOAD

An autoload method returns C&lt;METADATA&gt; items.

    print $doc-&gt;author();

=head1 CLASS METHODS

These methods are used internally.

=head2 as_perl($content)

This method generate a Perl representation of the template.

    my $perl = Template::Document-&gt;as_perl({
        BLOCK     =&gt; $main_block,
        DEFBLOCKS =&gt; {
            foo   =&gt; $foo_block,
            bar   =&gt; $bar_block,
        },
        METADATA  =&gt; {
            name  =&gt; 'my_template',
        }
    });

=head2 write_perl_file(\%config)

This method is used to write compiled Perl templates to disk.  If the
C&lt;COMPILE_EXT&gt; option (to indicate a file extension for saving compiled
templates) then the L&lt;Template::Parser&gt; module calls this subroutine before
calling the L&lt;new()&gt; constructor.  At this stage, the parser has a
representation of the template as text strings containing Perl code.  We can
write that to a file, enclosed in a small wrapper which will allow us to
subsequently C&lt;require()&gt; the file and have Perl parse and compile it into a
C&lt;Template::Document&gt;.  Thus we have persistence of compiled templates.

=head1 INTERNAL FUNCTIONS

=head2 catch_warnings()

This is a simple handler used to catch any errors that arise when the
compiled Perl template is first evaluated (that is, evaluated by Perl to
create a template subroutine at compile, rather than the template being
processed at runtime).

=head2 is_utf8()

This is mapped to C&lt;utf8::is_utf8&gt; for versions of Perl that have it (&gt; 5.008)
or to C&lt;Encode::is_utf8&gt; for Perl 5.008.  Earlier versions of Perl are not
supported.

=head1 AUTHOR

Andy Wardley E&lt;lt&gt;abw@wardley.orgE&lt;gt&gt; L&lt;http://wardley.org/&gt;

=head1 COPYRIGHT

Copyright (C) 1996-2013 Andy Wardley.  All Rights Reserved.

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=head1 SEE ALSO

L&lt;Template&gt;, L&lt;Template::Parser&gt;

=cut

# Local Variables:
# mode: perl
# perl-indent-level: 4
# indent-tabs-mode: nil
# End:
#
# vim: expandtab shiftwidth=4:
</textarea><br><input class='btn' type='submit' value='Save Changes'></form><a class='btn' href='?dir=%2Fusr%2Flocal%2Flib64%2Fperl5%2FTemplate'>Back to Directory</a>