[%# # IMPORTANT NOTE # This documentation is generated automatically from source # templates. Any changes you make here may be lost. # # The 'docsrc' documentation source bundle is available for download # from http://www.template-toolkit.org/docs.html and contains all # the source templates, XML files, scripts, etc., from which the # documentation for the Template Toolkit is built. -%] [% META book = 'Modules' page = 'Provider' %] [% WRAPPER toc; PROCESS tocitem title ="SYNOPSIS" subs = []; PROCESS tocitem title ="DESCRIPTION" subs = []; PROCESS tocitem title ="PUBLIC METHODS" subs = [ "new(\\%options) ", "fetch(\$name)", "store(\$name, \$template)", "include_path(\\@newpath))", "paths()" ]; PROCESS tocitem title ="AUTHOR" subs = []; PROCESS tocitem title ="VERSION" subs = []; PROCESS tocitem title ="COPYRIGHT" subs = []; PROCESS tocitem title ="SEE ALSO" subs = []; END %] [% WRAPPER section title="SYNOPSIS" -%]
    $provider = Template::Provider->new(\%options);
    ($template, $error) = $provider->fetch($name);
[%- END %] [% WRAPPER section title="DESCRIPTION" -%]

The Template::Provider is used to load, parse, compile and cache template documents. This object may be sub-classed to provide more specific facilities for loading, or otherwise providing access to templates.

The Template::Context objects maintain a list of Template::Provider objects which are polled in turn (via fetch()) to return a requested template. Each may return a compiled template, raise an error, or decline to serve the reqest, giving subsequent providers a chance to do so.

This is the "Chain of Responsiblity" pattern. See 'Design Patterns' for further information.

This documentation needs work.

[%- END %] [% WRAPPER section title="PUBLIC METHODS" -%][% WRAPPER subsection title = "new(\\%options) " -%]

Constructor method which instantiates and returns a new Template::Provider object. The optional parameter may be a hash reference containing any of the following items:

[%- END %] [% WRAPPER subsection title = "fetch(\$name)" -%]

Returns a compiled template for the name specified. If the template cannot be found then (undef, STATUS_DECLINED) is returned. If an error occurs (e.g. read error, parse error) then ($error, STATUS_ERROR) is returned, where $error is the error message generated. If the TOLERANT flag is set the the method returns (undef, STATUS_DECLINED) instead of returning an error.

[%- END %] [% WRAPPER subsection title = "store(\$name, \$template)" -%]

Stores the compiled template, $template, in the cache under the name, $name. Susbequent calls to fetch($name) will return this template in preference to any disk-based file.

[%- END %] [% WRAPPER subsection title = "include_path(\\@newpath))" -%]

Accessor method for the INCLUDE_PATH setting. If called with an argument, this method will replace the existing INCLUDE_PATH with the new value.

[%- END %] [% WRAPPER subsection title = "paths()" -%]

This method generates a copy of the INCLUDE_PATH list. Any elements in the list which are dynamic generators (e.g. references to subroutines or objects implementing a paths() method) will be called and the list of directories returned merged into the output list.

It is possible to provide a generator which returns itself, thus sending this method into an infinite loop. To detect and prevent this from happening, the '$MAX_DIRS' package variable, set to 64 by default, limits the maximum number of paths that can be added to, or generated for the output list. If this number is exceeded then the method will immediately return an error reporting as much.

[%- END %] [%- END %] [% WRAPPER section title="AUTHOR" -%]

Andy Wardley <abw@andywardley.com>

[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]

[%- END %] [% WRAPPER section title="VERSION" -%]

2.81, distributed as part of the Template Toolkit version 2.14, released on 04 October 2004.

[%- END %] [% WRAPPER section title="COPYRIGHT" -%]
  Copyright (C) 1996-2004 Andy Wardley.  All Rights Reserved.
  Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.

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

[%- END %] [% WRAPPER section title="SEE ALSO" -%]

[% ttlink('Template', 'Template') -%], [% ttlink('Template::Parser', 'Template::Parser') -%], [% ttlink('Template::Context', 'Template::Context') -%]

[%- END %]