.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Text::MicroMason::TemplatePath 3pm"
.TH Text::MicroMason::TemplatePath 3pm "2023-08-10" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Text::MicroMason::TemplatePath \- Template Path Searching
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Instead of using this class directly, pass its name to be mixed in:
.PP
.Vb 2
\&    use Text::MicroMason;
\&    my $mason = Text::MicroMason\->new( \-TemplatePath, template_path => [ \*(Aq/foo\*(Aq, \*(Aq/bar\*(Aq ] );
.Ve
.PP
Use the standard compile and execute methods to parse and evaluate templates:
.PP
.Vb 2
\&  print $mason\->compile( file=>$filepath )\->( \*(Aqname\*(Aq=>\*(AqDave\*(Aq );
\&  print $mason\->execute( file=>$filepath, \*(Aqname\*(Aq=>\*(AqDave\*(Aq );
.Ve
.PP
Templates stored in files are searched for in the specified template_path:
.PP
.Vb 1
\&    print $mason\->execute( file=>"includes/greeting.msn", \*(Aqname\*(Aq=>\*(AqCharles\*(Aq);
.Ve
.PP
When including other files into a template you can use relative paths:
.PP
.Vb 1
\&    <& ../includes/greeting.msn, name => \*(AqAlice\*(Aq &>
.Ve
.PP
When a file is included in the template, the including template's
current directory is added to the beginning of the template search path.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module works similarly to the related TemplateDir mix-in. However,
instead of specifying a single root which must contain all templates,
TemplatePath allows you to specify an arrayref of directories which will
be searched in order whenever a template filename must be resolved.
.PP
Using a TemplatePath object, absolute filenames are used as-is. If a
relative template filenames or file paths is used, every directory in
the specified template_path is checked for the existence of the
template, and the first existing template file is used.
.PP
If a template includes another template using <& ... &>, then the
including template's location is added to the beginning of the template
search path list, for the resolution of the included template's
filename. This allows the included template to be specified relative to
the including template, but also lets the template search fall back to
the configured template search path if necessary.
.SS "Supported Attributes"
.IX Subsection "Supported Attributes"
.IP "template_path" 4
.IX Item "template_path"
An array ref containing a list of directories in which to search for
relative template filenames.
.IP "strict_root" 4
.IX Item "strict_root"
Optional directory beyond which not to read files. Unlike TemplateDir,
this must be a specific file path. Causes read_file to croak if any
filename outside of the root is provided. You should make sure that all
paths specified in template_path are inside the specified strict_root.
(Note that this is not a chroot jail and only affects attempts to load a
file as a template; for greater security see the \fBchroot()\fR builtin and
Text::MicroMason::Safe.)
.SS "Private Methods"
.IX Subsection "Private Methods"
.IP "read_file" 4
.IX Item "read_file"
Intercepts file access to check for strict_root.
.SS "\s-1EXCEPTIONS\s0"
.IX Subsection "EXCEPTIONS"
The following additional exceptions are generated by
Text::MicroMason::TemplatePath when appropriate:
.IP "\(bu" 4
Text::MicroMason::TemplatePath: template '%s' not found in path.
.Sp
This indicates that the specified template name does not exist in any of
the directories in the configured path.
.IP "\(bu" 4
Text::MicroMason::TemplatePath: Template not in required base path '%s'
.Sp
The template found in the configured template path was not within the
configured strict_root directory. This may be caused by requesting an
absolute template filename not within strict_root, or by specifying a
strict_root which does not match the configured template path.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For an overview of this templating framework, see Text::MicroMason.
.PP
This is a mixin class intended for use with Text::MicroMason::Base.
.PP
For distribution, installation, support, copyright and license
information, see Text::MicroMason::Docs::ReadMe.