saint/discourse-legacysite-perl
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Second pass at adding key files

Browse Source
This commit is contained in:
dsainty
2024-06-17 22:24:05 +10:00
parent aa25e9347f
commit b6fc94ff0f
923 changed files with 243184 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

550
site/glist/templates/help/GT/Template.html Normal file
View File

@ -0,0 +1,550 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>GT::Template - Gossamer Threads template parser</title>
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
<style type="text/css">
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
/* $MVD$:fontset("Arial","Arial") */
/* $MVD$:fontset("Arial Black","Arial Black") */
/* $MVD$:fontset("Algerian","Algerian") */
body {
background-color: white;
font-family: Verdana, Arial, sans-serif;
font-size: small;
color: black;
}
p {
background-color : white;
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
h1 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : medium;
background-color : white;
color : maroon;
}
h2 {
font-family : Verdana, Arial, sans-serif;
font-size : medium;
font-weight : bold;
color : blue;
background-color : white;
}
h3 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : medium;
color : black;
background-color : white;
}
h4 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : small;
color : maroon;
background-color : white;
}
h5 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : small;
color : blue;
background-color : white;
}
h6 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : small;
color : black;
background-color : white;
}
ul {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
ol {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
dl {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
li {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
th {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
td {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
dl {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
dd {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
dt {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
code {
font-family : Courier;
font-size : small;
color : black;
}
pre {
font-family : Courier;
font-size : small;
color : black;
}
.mvd-H1 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : 14.0pt;
background-color : transparent;
background-image : none;
color : maroon;
}
.mvd-H2 {
font-family : Verdana, Arial, sans-serif;
font-size : 12.0pt;
color : blue;
}
p.indent {
font-family : "Verdana, Arial, sans-serif";
list-style-type : circle;
list-style-position : inside;
color : black;
margin-left : 16.0pt;
}
.mvd-P-indent {
font-family : Verdana, Arial, sans-serif;
list-style-type : circle;
list-style-position : inside;
color : black;
margin-left : 16.0pt;
}
pre.programlisting {
font-size : 9.0pt;
list-style-type : disc;
margin-left : 16.0pt;
margin-top : -14.0pt;
}
.mvd-PRE-programlisting {
font-size : 9.0pt;
list-style-type : disc;
margin-left : 16.0pt;
margin-top : -14.0pt;
}
.mvd-PRE {
font-size : 9.0pt;
}
p.note {
margin-left : 28.0pt;
}
.mvd-P-note {
margin-left : 28.0pt;
}
.mvd-H4 {
font-family : Verdana, Arial, sans-serif;
font-weight : normal;
font-size : 9.0pt;
color : black;
margin-left : 6.0pt;
margin-top : -14.0pt;
}
.mvd-P {
font-family : Verdana, Arial, sans-serif;
font-size : 10.0pt;
color : black;
}
.mvd-BODY {
font-family : Verdana, Arial, sans-serif;
background-color : white;
}
p.indentnobullet {
font-family : Verdana, Arial, sans-serif;
list-style-type : none;
}
.mvd-P-indentnobullet {
font-family : Verdana, Arial, sans-serif;
list-style-type : none;
}
</style>
</head>
<body style="background-color: white">
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<ul>
<li><a href="#template_syntax">Template Syntax</a></li>
<li><a href="#parse">parse</a></li>
<li><a href="#parse_print">parse_print</a></li>
<li><a href="#parse_stream">parse_stream</a></li>
<li><a href="#parse_options">Parse Options</a></li>
<ul>
<li><a href="#filename">Filename</a></li>
<li><a href="#variables">Variables</a></li>
<li><a href="#options">Options</a></li>
<li><a href="#aliases">Aliases</a></li>
</ul>
<li><a href="#vars">vars</a></li>
</ul>
<li><a href="#examples">EXAMPLES</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#copyright">COPYRIGHT</a></li>
<li><a href="#version">VERSION</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>GT::Template - Gossamer Threads template parser</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
use GT::Template;
my $var = GT::Template-&gt;parse('file.txt', { key =&gt; 'value' });
...
print $var;</pre>
<p>or</p>
<pre>
use GT::Template;
GT::Template-&gt;parse_print('file.txt', { key =&gt; 'value' });</pre>
<p>or</p>
<pre>
use GT::Template;
GT::Template-&gt;parse_stream('file.txt', { key =&gt; 'value' });</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>GT::Template provides a simple way (one line) to parse a template (which
can be either a file or a string) and make sophisticated replacements.</p>
<p>It supports simple replacements, conditionals, function calls, including other
templates, and more.</p>
<p>Additionally, through using pre-compiled files, subsequent parses of a template
will be very fast.</p>
<p>
</p>
<h2><a name="template_syntax">Template Syntax</a></h2>
<p>The template syntax documentation has moved - it is now documented in
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Tutorial.html">the GT::Template::Tutorial manpage</a>.</p>
<p>
</p>
<h2><a name="parse">parse</a></h2>
<p>This option parses a template, and returns the value of the parsed template.
See <a href="#parse_options">Parse Options</a> for a description of the possible parse parameters.</p>
<p>
</p>
<h2><a name="parse_print">parse_print</a></h2>
<p>This option parses a template, and prints it. See <a href="#parse_options">Parse Options</a> for a
description of the possible parse_print parameters.</p>
<p>
</p>
<h2><a name="parse_stream">parse_stream</a></h2>
<p>This option parses a template, and prints each part of it as the parse occurs.
It should only be used in situations where streaming content is required as it
is measurably slower than the parse_print alternative. See <a href="#parse_options">Parse Options</a>
for a description of the possible parse_stream parameters.</p>
<p>
</p>
<h2><a name="parse_options">Parse Options</a></h2>
<p>
</p>
<h3><a name="filename">Filename</a></h3>
<p>The first argument to <code>parse()/parse_print()/parse_stream()</code> (hereafter referred
to simply as <code>parse())</code> is the full or relative (to the current working
directory) path to the file to parse.</p>
<p>
</p>
<h3><a name="variables">Variables</a></h3>
<p>The second argument is a hash reference of template variables that will be
available in the parsed template (see <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Tutorial.html">the GT::Template::Tutorial manpage</a>). Arbitrary
hash/array data structure access is supported (see
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Tutorial.html#advanced_variables_using_references">Advanced variables using references in the GT::Template::Tutorial manpage</a>).</p>
<p>Loops are supported by providing an array reference or code reference as a
value; array reference loops are generally preferred as they enable the loop to
be used multiple times and support the &lt;%loopvar.length%&gt; syntax.</p>
<p>
</p>
<h3><a name="options">Options</a></h3>
<p>The third argument (which is not required) takes additional options that change
the way a parse is performed. The available options (there are more, however
their use is discouraged) are as follows.</p>
<ul>
<li><strong><a name="item_string__3d_3e__24template">string =&gt; $template</a></strong><br />
</li>
Passing in <a href="#item_string__3d_3e__24template"><code>string =&gt; $template</code></a> will use $template as for the template
content instead of reading the file specified as the first <code>parse()</code> argument.
If provided, the first argument to <code>parse()</code> (the filename) is ignored.
<p></p>
<li><strong><a name="item_compress__3d_3e_1">compress =&gt; 1</a></strong><br />
</li>
Setting compress =&gt; 1 will compress all white space generated by the program.
This is usually acceptable for HTML, reducing page sizes by typically 10-20%,
but should not be used for non-HTML templates. The default is 0 (no
compression). This option has no effect when using parse_stream().
<p></p>
<li><strong><a name="item_strict__3d_3e_0">strict =&gt; 0</a></strong><br />
</li>
If set to 1, attempting to use a tag that does not exist will display an
``Unknown tag 'tagname''' error. If strict is set to 0, using an unset tag will
not display anything.
<p></p>
<li><strong><a name="item_escape__3d_3e_1">escape =&gt; 1</a></strong><br />
</li>
If enabled, this option will cause all variables to be HTML escaped before
being included on a page. Enabling this option is strongly recommended.
all variables before they are printed. Tag values that should not be escaped
should be passed as scalar references (\$foo or \'&lt;html&gt;').
<p>This option currently defaults to 0, but may eventually change to 1 - so
passing an explicit 1 or 0 value is strongly recommended.</p>
<p></p>
<li><strong><a name="item_disable__3d_3e__7b__2e_2e_2e__7d">disable =&gt; { ... }</a></strong><br />
</li>
This can be used to disable certain GT::Template functionality. To disable a
particular feature, the hash reference passed to disable should contain a
<code>feature_name</code> with a <code>1</code> value, unless otherwise indicated. Feature names
are as follows:
<ul>
<li><strong><a name="item_functions">functions</a></strong><br />
</li>
This can be used to disable Package::function calls, such as
<code>&lt;%Some::Package::function%&gt;</code>. Note, however, that this does _not_
disable aliased function calls (see below).
<p></p>
<li><strong><a name="item_function_args">function_args</a></strong><br />
</li>
This disables any function calls that specify arguments - for instance,
<code>&lt;%Some::Package::function(1)&gt;</code>. Note that this does _not_ disable
passing arguments to aliased function calls (see below).
<p></p>
<li><strong><a name="item_function_restrict">function_restrict</a></strong><br />
</li>
This can be used to restrict function calls by limiting the available
functions. It takes a regular expression as an argument, which will be tested
against the fully qualified function name - any function that does not match
the regular expression will not be called. For example, to only allow
functions in 'Package::One' and 'Second::Package' to be called, you could use:
<pre>
function_restrict =&gt; '^(?:Package::One|Second::Package)::\w+$'</pre>
<p>Like the above options, this does not restrict aliased function calls.</p>
<p></p>
<li><strong><a name="item_coderefs_args">coderefs_args</a></strong><br />
</li>
This can be specified to disable the calling of code reference variables with
arguments. Tags such as <code>&lt;%coderefname%&gt;</code> and
<code>&lt;%coderefname()%&gt;</code> will be allowed, but <code>&lt;%coderefname(1)%&gt;</code>
will not.
<p></p>
<li><strong><a name="item_alias_args">alias_args</a></strong><br />
</li>
This option can be used to disable the passing of arguments to aliased function
calls (see below).
<p></p></ul>
<li><strong><a name="item_pkg_chop">pkg_chop</a></strong><br />
</li>
When calling a function such as &lt;%Package::A::B::function%&gt;, GT::Template will
first attempt to load Package/A/B.pm, then, if it fails, Package/A.pm, and so
on down to Package.pm, looking for Package::A::B::function in each file. This
behaviour is slow and often undesirable - it is recommended to properly split
up packages (that is, putting Package::A::B inside Package/A/B.pm instead of
Package/A.pm or Package.pm). The ``package chopping'' occurs if pkg_chop is set
to 1 (currently the default, but may change), and does not occur if pkg_chop is
set to 0 (recommended, but not the default for historic reasons).
<p></p>
<li><strong><a name="item_heap">heap</a></strong><br />
</li>
If this is set, it will be added to the end of any other arguments passed to
functions called.
<p></p>
<li><strong><a name="item_func_code">func_code</a></strong><br />
</li>
When calling a function such as &lt;%Package::function%&gt;, you can override the
default behaviour of simply calling the function by providing a code reference
to <a href="#item_func_code"><code>func_code</code></a>. Instead of calling Package::function(), your code reference
will be called with the string of the package to call (e.g.
'Package::function') and the arguments that would have been passed to the
function. The return value of your code will be used as if it was the return
value from the real function.
<p></p>
<li><strong><a name="item_begin">begin</a></strong><br />
</li>
<li><strong><a name="item_end">end</a></strong><br />
</li>
<a href="#item_begin"><code>begin</code></a> and <a href="#item_end"><code>end</code></a> can be used to change the characters that start and end a
template tag. These default to <code>&lt;%</code> for <a href="#item_begin"><code>begin</code></a>, and <code>%&gt;</code> for
<a href="#item_end"><code>end</code></a>. For example, if you changed <a href="#item_begin"><code>begin</code></a> to <code>[*</code> and <a href="#item_end"><code>end</code></a> to <code>*]</code>, you
would use <code>[*tagname*]</code> for a normal tag, <code>[*-- comment --*]</code> for a comment,
etc.
<p></p></ul>
<p>
</p>
<h3><a name="aliases">Aliases</a></h3>
<p>The forth option to parse is an optional hash of aliases to set up for
functions. The key should be the alias name and the value should be the
function to call when the alias is invoked. For example:</p>
<pre>
print GT::Template-&gt;parse(
'file.htm',
{ key =&gt; 'value' },
{ compress =&gt; 1 },
{ myfunc =&gt; 'Long::Package::Name::To::myfunc' }
);</pre>
<p>Now in your template you can do:</p>
<pre>
&lt;%myfunc('argument')%&gt;</pre>
<p>Which will call <code>Long::Package::Name::To::myfunc</code>.</p>
<p>
</p>
<h2><a name="vars">vars</a></h2>
<p>Accessing variables from outside a template can be done by calling the
<code>GT::Template-&gt;vars</code> method. For further details, please see
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Vars.html">the GT::Template::Vars manpage</a>.</p>
<p>
</p>
<hr />
<h1><a name="examples">EXAMPLES</a></h1>
<p>Parse the string contained in $template, making the 'key' tag available.</p>
<pre>
my $parsed = GT::Template-&gt;parse(undef, { key =&gt; 'value' }, { string =&gt; $template });</pre>
<p>Parse file.txt, compress the result, and print it. This is equivelant to
<code>print GT::Template-&gt;parse(...)</code>, but slightly faster.</p>
<pre>
GT::Template-&gt;parse_print('file.txt', { key =&gt; 'value' }, { compress =&gt; 1 });</pre>
<p>Print the output of the template it as it is parsed, not after entirely parsed.
This will output the same as the above command would without the ``compress''
option, but is slower (unless, of course, streaming is needed).</p>
<pre>
GT::Template-&gt;parse_stream('file.txt', { key =&gt; 'value' });</pre>
<p>Don't display warnings on invalid keys:</p>
<pre>
GT::Template-&gt;parse_print('file.txt', { key =&gt; 'value' }, { strict =&gt; 0 });</pre>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Tutorial.html">the GT::Template::Tutorial manpage</a> - Documentation/tutorial for GT::Template template
tags.</p>
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Vars.html">the GT::Template::Vars manpage</a> - Interface for accessing/manipulating template tags from
Perl code.</p>
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Inheritance.html">the GT::Template::Inheritance manpage</a> - Documentation for GT::Template template
inheritance.</p>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright (c) 2005 Gossamer Threads Inc. All Rights Reserved.
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
<p>
</p>
<hr />
<h1><a name="version">VERSION</a></h1>
<p>Revision: $Id: Template.pm,v 2.142 2005/07/05 00:39:40 jagerman Exp $</p>
</body>
</html>