[Templates-svn] r1069 - in trunk: . docs/src/FAQ docs/src/Library docs/src/Manual docs/src/Modules docs/src/Modules/Template docs/src/Modules/Template/Namespace docs/src/Modules/Template/Plugin docs/src/Modules/Template/Stash docs/src/Release docs/src/Tools docs/src/Tutorial lib/Template lib/Template/Manual
svn@template-toolkit.org
svn@template-toolkit.org
Author: abw
Date: 2007-04-27 19:32:51 +0100 (Fri, 27 Apr 2007)
New Revision: 1069
Modified:
trunk/Changes
trunk/HACKING
trunk/INSTALL
trunk/README
trunk/TODO
trunk/docs/src/FAQ/FAQ.html
trunk/docs/src/Library/HTML.html
trunk/docs/src/Library/PostScript.html
trunk/docs/src/Library/Splash.html
trunk/docs/src/Manual/Config.html
trunk/docs/src/Manual/Credits.html
trunk/docs/src/Manual/Directives.html
trunk/docs/src/Manual/Filters.html
trunk/docs/src/Manual/Internals.html
trunk/docs/src/Manual/Intro.html
trunk/docs/src/Manual/Plugins.html
trunk/docs/src/Manual/Refs.html
trunk/docs/src/Manual/Syntax.html
trunk/docs/src/Manual/VMethods.html
trunk/docs/src/Manual/Variables.html
trunk/docs/src/Manual/Views.html
trunk/docs/src/Modules/Template.html
trunk/docs/src/Modules/Template/Base.html
trunk/docs/src/Modules/Template/Config.html
trunk/docs/src/Modules/Template/Constants.html
trunk/docs/src/Modules/Template/Context.html
trunk/docs/src/Modules/Template/Document.html
trunk/docs/src/Modules/Template/Exception.html
trunk/docs/src/Modules/Template/Filters.html
trunk/docs/src/Modules/Template/Iterator.html
trunk/docs/src/Modules/Template/Namespace/Constants.html
trunk/docs/src/Modules/Template/Parser.html
trunk/docs/src/Modules/Template/Plugin.html
trunk/docs/src/Modules/Template/Plugin/Autoformat.html
trunk/docs/src/Modules/Template/Plugin/CGI.html
trunk/docs/src/Modules/Template/Plugin/Datafile.html
trunk/docs/src/Modules/Template/Plugin/Date.html
trunk/docs/src/Modules/Template/Plugin/Directory.html
trunk/docs/src/Modules/Template/Plugin/Dumper.html
trunk/docs/src/Modules/Template/Plugin/File.html
trunk/docs/src/Modules/Template/Plugin/Filter.html
trunk/docs/src/Modules/Template/Plugin/Format.html
trunk/docs/src/Modules/Template/Plugin/HTML.html
trunk/docs/src/Modules/Template/Plugin/Image.html
trunk/docs/src/Modules/Template/Plugin/Iterator.html
trunk/docs/src/Modules/Template/Plugin/Math.html
trunk/docs/src/Modules/Template/Plugin/Pod.html
trunk/docs/src/Modules/Template/Plugin/Procedural.html
trunk/docs/src/Modules/Template/Plugin/String.html
trunk/docs/src/Modules/Template/Plugin/Table.html
trunk/docs/src/Modules/Template/Plugin/URL.html
trunk/docs/src/Modules/Template/Plugin/View.html
trunk/docs/src/Modules/Template/Plugin/Wrap.html
trunk/docs/src/Modules/Template/Plugins.html
trunk/docs/src/Modules/Template/Provider.html
trunk/docs/src/Modules/Template/Service.html
trunk/docs/src/Modules/Template/Stash.html
trunk/docs/src/Modules/Template/Stash/Context.html
trunk/docs/src/Modules/Template/Stash/XS.html
trunk/docs/src/Modules/Template/Test.html
trunk/docs/src/Release/Changes.html
trunk/docs/src/Release/HACKING.html
trunk/docs/src/Release/INSTALL.html
trunk/docs/src/Release/README.html
trunk/docs/src/Release/TODO.html
trunk/docs/src/Tools/tpage.html
trunk/docs/src/Tools/ttree.html
trunk/docs/src/Tutorial/Datafile.html
trunk/docs/src/Tutorial/Web.html
trunk/lib/Template/Filters.pm
trunk/lib/Template/Grammar.pm
trunk/lib/Template/Manual/Filters.pod
Log:
rebuilt everything for release 2.19
Modified: trunk/Changes
===================================================================
--- trunk/Changes 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/Changes 2007-04-27 18:32:51 UTC (rev 1069)
@@ -3,7 +3,7 @@
# Changes
#
# DESCRIPTION
-# Revision history for the Template Toolkit version 2.18, detailing
+# Revision history for the Template Toolkit version 2.19, detailing
# significant changes between versions, most recent first. Some
# way down the file you'll find a section detailing major changes from
# version 1.* to 2.* and a list of "Gotchas!" that you might have to
@@ -23,6 +23,55 @@
#========================================================================
#------------------------------------------------------------------------
+# Version 2.19 - 27th April 2007
+#------------------------------------------------------------------------
+
+* Applied a patch to t/fileline.t from Steffen Müller which fixes the
+ problems running on Win32 with backslashes in paths.
+
+ https://rt.cpan.org/Ticket/Display.html?id=20488
+
+* Applied a patch to the XS Stash from Randy Kobes which fixes some other
+ Win32 problems.
+
+ http://tt2.org/pipermail/templates/2007-February/009247.html
+
+* Applied another patch to the XS Stash from Steve Peters which fixes
+ a problem with tied hashes under more recent version of Perl.
+
+ http://tt2.org/pipermail/templates/2007-January/009181.html
+
+* Fixed a problem in the Perl Stash when using objects that have
+ overloaded comparison operators. Thanks to Randal Schwartz, Tatsuhiko
+ Miyagawa and Daisuke Maki for their contributions.
+
+ http://tt2.org/pipermail/templates/2007-March/009265.html
+
+* Applied a patch from Bill Moseley to Template::Provider which adds
+ negative caching and moves some functionality into separate methods
+ to make subclassing easier. Also added the STAT_TTL configuration
+ parameter.
+
+ http://tt2.org/pipermail/templates/2007-January/009183.html
+
+* Added the url filter as a less aggressive form of the uri filter.
+ Whereas the uri filter now (from v2.16 onwards) encodes all the
+ reserved characters (@, :, /, etc.) as per RFC2396, the url filter
+ leaves them intact and thus behaves just like the uri filter used
+ to.
+
+ http://tt2.org/pipermail/templates/2007-March/009277.html
+
+#------------------------------------------------------------------------
+# Version 2.18a - 9th February 2007
+#------------------------------------------------------------------------
+
+* Applied a patch from Steve Peters to the Stash.xs to allow it to
+ compile with bleadperl 5.9.x
+
+ https://rt.cpan.org/Public/Bug/Display.html?id=22506
+
+#------------------------------------------------------------------------
# Version 2.18 - 9th February 2007
#------------------------------------------------------------------------
Modified: trunk/HACKING
===================================================================
--- trunk/HACKING 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/HACKING 2007-04-27 18:32:51 UTC (rev 1069)
@@ -1,9 +1,9 @@
Template Toolkit
- Version 2.18
+ Version 2.19
- 09 February 2007
+ 27 April 2007
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved
Modified: trunk/INSTALL
===================================================================
--- trunk/INSTALL 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/INSTALL 2007-04-27 18:32:51 UTC (rev 1069)
@@ -1,9 +1,9 @@
Template Toolkit
- Version 2.18
+ Version 2.19
- 09 February 2007
+ 27 April 2007
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved
@@ -24,8 +24,8 @@
To install the Template Toolkit:
- tar zxf Template-Toolkit-2.18.tar.gz
- cd Template-Toolkit-2.18
+ tar zxf Template-Toolkit-2.19.tar.gz
+ cd Template-Toolkit-2.19
perl Makefile.PL
make
make test
@@ -87,19 +87,19 @@
Template-Toolkit-<version>.tar.gz
-where <version> represents the current version number, e.g. 2.18.
+where <version> represents the current version number, e.g. 2.19.
To install the Template Toolkit, unpack the distribution archive to
create an installation directory. Something like this:
- tar zxf Template-Toolkit-2.18.tar.gz
+ tar zxf Template-Toolkit-2.19.tar.gz
or
- gunzip Template-Toolkit-2.18.tar.gz
- tar xf Template-Toolkit-2.18.tar
+ gunzip Template-Toolkit-2.19.tar.gz
+ tar xf Template-Toolkit-2.19.tar
You can then 'cd' into the directory created,
- cd Template-Toolkit-2.18
+ cd Template-Toolkit-2.19
and perform the usual Perl installation procedure:
Modified: trunk/README
===================================================================
--- trunk/README 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/README 2007-04-27 18:32:51 UTC (rev 1069)
@@ -1,9 +1,9 @@
Template Toolkit
- Version 2.18
+ Version 2.19
- 09 February 2007
+ 27 April 2007
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved
@@ -25,8 +25,8 @@
To install the Template Toolkit:
- tar zxf Template-Toolkit-2.18.tar.gz
- cd Template-Toolkit-2.18
+ tar zxf Template-Toolkit-2.19.tar.gz
+ cd Template-Toolkit-2.19
perl Makefile.PL
make
make test
@@ -68,6 +68,11 @@
WHAT'S NEW?
-----------
+Version 2.19 fixes some minor bugs in both Perl and XS versions of the Template
+Stash, and fixes a problem with a test in the test suite failing under Win32.
+It also adds the url filter as a version of what the uri filter used to do
+before we fixed it to do the right thing.
+
Version 2.18 fixes a number of minor bugs. It also includes a modification to
the parser grammar so that you can write expressions as arguments to
subroutine, method or vmethod calls.
Modified: trunk/TODO
===================================================================
--- trunk/TODO 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/TODO 2007-04-27 18:32:51 UTC (rev 1069)
@@ -3,7 +3,7 @@
# TODO
#
# DESCRIPTION
-# TODO list for the Template Toolkit version 2.18, containing
+# TODO list for the Template Toolkit version 2.19, containing
# known bugs, limitations, planned enhancements, long term visions
# and a few whacky ideas.
#
Modified: trunk/docs/src/FAQ/FAQ.html
===================================================================
--- trunk/docs/src/FAQ/FAQ.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/FAQ/FAQ.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -398,7 +398,7 @@
title="VERSION"
-%]<p>
2.68, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Library/HTML.html
===================================================================
--- trunk/docs/src/Library/HTML.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Library/HTML.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -293,7 +293,7 @@
title="VERSION"
-%]<p>
2.68, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Library/PostScript.html
===================================================================
--- trunk/docs/src/Library/PostScript.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Library/PostScript.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -48,7 +48,7 @@
title="VERSION"
-%]<p>
2.68, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Library/Splash.html
===================================================================
--- trunk/docs/src/Library/Splash.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Library/Splash.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -893,7 +893,7 @@
title="VERSION"
-%]<p>
2.68, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Manual/Config.html
===================================================================
--- trunk/docs/src/Manual/Config.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Manual/Config.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -1349,11 +1349,20 @@
The CACHE_SIZE can be set to 0 to disable caching altogether.
</p>
<pre> my $template = Template->new({
- CACHE_SIZE => 64, # only cache 64 compiled templates
+ CACHE_SIZE => 64, # only cache 64 compiled templates
});</pre>
<pre> my $template = Template->new({
- CACHE_SIZE => 0, # don't cache any compiled templates
+ CACHE_SIZE => 0, # don't cache any compiled templates
});</pre>
+<p>
+As well as caching templates as they are found, the Template::Provider
+also implements negative caching to keep track of templates that are
+<i>not</i> found. This allows the provider to quickly decline a request
+for a template that it has previously failed to locate, saving the effort
+of going to look for it again. This is useful when an INCLUDE_PATH includes
+multiple providers, ensuring that the request is passed down through the
+providers as quickly as possible.
+</p>
<li><b>COMPILE_EXT</b><br>
<p>
@@ -2003,7 +2012,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Manual/Credits.html
===================================================================
--- trunk/docs/src/Manual/Credits.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Manual/Credits.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -120,7 +120,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Manual/Directives.html
===================================================================
--- trunk/docs/src/Manual/Directives.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Manual/Directives.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -588,10 +588,6 @@
</p>
<pre> == != < <= > >= && || ! and or not</pre>
<p>
-Note that <code>'and'</code>, <code>'or'</code> and <code>'not'</code> are also provided as aliases for
-<code>'&&'</code>, <code>'||'</code> and <code>'!'</code>, respectively.
-</p>
-<p>
Conditions may be arbitrarily complex and are evaluated with the same
precedence as in Perl. Parenthesis may be used to explicitly
determine evaluation order.
@@ -602,6 +598,14 @@
[% tt_start_tag %] ELSIF more > less [% tt_end_tag %]
That's more or less correct.
[% tt_start_tag %] END [% tt_end_tag %]</pre>
+<p>
+The <code>'and'</code>, <code>'or'</code> and <code>'not'</code> operator are provided as aliases for
+<code>'&&'</code>, <code>'||'</code> and <code>'!'</code>, respectively. Unlike Perl, which treats
+<code>'and'</code>, <code>'or'</code> and <code>'not'</code> as separate, lower-precedence versions of the
+other operators, the Template Toolkit performs a straightforward substitution
+of <code>'and'</code> for <code>'&&'</code>, and so on. That means that <code>'and'</code>, <code>'or'</code> and <code>'not'</code>
+have the same operator precedence as <code>'&&'</code>, <code>'||'</code> and <code>'!'</code>.
+</p>
<li><b>SWITCH / CASE</b><br>
<p>
@@ -2041,7 +2045,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Manual/Filters.html
===================================================================
--- trunk/docs/src/Manual/Filters.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Manual/Filters.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -31,6 +31,7 @@
"html_break / html_para_break",
"html_line_break",
"uri",
+ "url",
"indent(pad)",
"truncate(length,dots)",
"repeat(iterations)",
@@ -251,14 +252,66 @@
</p>
<pre> my%20file.html</pre>
<p>
-Note that as of TT version 2.16, the uri filter now correctly encodes
-all reserved characters. This includes <code>'&'</code>, <code>'@'</code>, <code>'/'</code>, <code>';'</code>, <code>':'</code>,
-<code>'='</code>, <code>'+'</code>, <code>'?'</code> and <code>'$'</code> which were not escaped (incorrectly) by the
-uri filter in versions 2.15 and earlier. See RFC 2396 for further
-details.
+The uri filter correctly encodes all reserved characters, including
+<code>'&'</code>, <code>'@'</code>, <code>'/'</code>, <code>';'</code>, <code>':'</code>, <code>'='</code>, <code>'+'</code>, <code>'?'</code> and <code>'$'</code>. This filter
+is typically used to encode parameters in a URL that could otherwise
+be interpreted as part of the URL. Here's an example:
</p>
+<pre> [% tt_start_tag %] path = 'http://tt2.org/example'
+ back = '/other?foo=bar&baz=bam'
+ title = 'Earth: "Mostly Harmless"'
+ [% tt_end_tag %]
+ <a href="[% tt_start_tag %] path [% tt_end_tag %]?back=[% tt_start_tag %] back | uri [% tt_end_tag %]&title=[% tt_start_tag %] title | uri [% tt_end_tag %]"></pre>
+<p>
+The output generated is rather long so we'll show it split across two
+lines:
+</p>
+<pre> <a href="http://tt2.org/example?back=%2Fother%3Ffoo%3Dbar%26
+ baz%3Dbam&title=Earth%3A%20%22Mostly%20Harmless%22"></pre>
+<p>
+Without the uri filter the output would look like this (also split across
+two lines).
+</p>
+<pre> <a href="http://tt2.org/example?back=/other?foo=bar
+ &baz=bam&title=Earth: "Mostly Harmless""></pre>
+<p>
+In this rather contrived example we've manage to generate both a broken URL
+(the repeated <code>'?'</code> is not allowed) and a broken HTML element (the href
+attribute is terminated by the first <code>'"'</code> after <code>'Earth: '</code> leaving <code>'Mostly
+Harmless"'</code> dangling on the end of the tag in precisely the way that harmless
+things shouldn't dangle). So don't do that. Always use the uri filter to
+encode your URL parameters.
+</p>
+<p>
+However, you should <b>not</b> use the uri filter to encode an entire URL.
+</p>
+<pre> <a href="[% tt_start_tag %] page_url | uri [% tt_end_tag %]"> # WRONG!</pre>
+<p>
+This will incorrectly encode any reserved characters like <code>':'</code> and <code>'/'</code>
+and that's almost certainly not what you want in this case. Instead
+you should use the <b>url</b> (note spelling) filter for this purpose.
+</p>
+<pre> <a href="[% tt_start_tag %] page_url | url [% tt_end_tag %]"> # CORRECT</pre>
+<p>
+Please note that this behaviour was changed in version 2.16 of the
+Template Toolkit. Prior to that, the uri filter did not encode the
+reserved characters, making it technically incorrect according to the
+RFC 2396 specification. So we fixed it in 2.16 and provided the url
+filter to implement the old behaviour of not encoding reserved
+characters.
+</p>
[%- END %]
[% WRAPPER subsection
+ title = "url"
+-%]<p>
+The url filter is a less aggressive version of the uri filter. It encodes
+any characters outside of the permitted URI character set (as defined by RFC 2396)
+into <code>'%nn'</code> hex escapes. However, unlike the uri filter, the url filter does
+<b>not</b> encode the reserved characters <code>'&'</code>, <code>'@'</code>, <code>'/'</code>, <code>';'</code>, <code>':'</code>, <code>'='</code>, <code>'+'</code>,
+<code>'?'</code> and <code>'$'</code>.
+</p>
+[%- END %]
+[% WRAPPER subsection
title = "indent(pad)"
-%]<p>
Indents the text block by a fixed pad string or width. The 'pad' argument
@@ -506,7 +559,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Manual/Internals.html
===================================================================
--- trunk/docs/src/Manual/Internals.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Manual/Internals.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -536,7 +536,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Manual/Intro.html
===================================================================
--- trunk/docs/src/Manual/Intro.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Manual/Intro.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -260,7 +260,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Manual/Plugins.html
===================================================================
--- trunk/docs/src/Manual/Plugins.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Manual/Plugins.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -368,7 +368,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Manual/Refs.html
===================================================================
--- trunk/docs/src/Manual/Refs.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Manual/Refs.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -139,7 +139,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Manual/Syntax.html
===================================================================
--- trunk/docs/src/Manual/Syntax.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Manual/Syntax.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -281,7 +281,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Manual/VMethods.html
===================================================================
--- trunk/docs/src/Manual/VMethods.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Manual/VMethods.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -664,7 +664,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Manual/Variables.html
===================================================================
--- trunk/docs/src/Manual/Variables.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Manual/Variables.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -882,7 +882,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Manual/Views.html
===================================================================
--- trunk/docs/src/Manual/Views.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Manual/Views.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -613,7 +613,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Base.html
===================================================================
--- trunk/docs/src/Modules/Template/Base.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Base.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -151,7 +151,7 @@
title="VERSION"
-%]<p>
2.77, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Config.html
===================================================================
--- trunk/docs/src/Modules/Template/Config.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Config.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -171,7 +171,7 @@
title="VERSION"
-%]<p>
2.74, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Constants.html
===================================================================
--- trunk/docs/src/Modules/Template/Constants.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Constants.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -124,7 +124,7 @@
title="VERSION"
-%]<p>
2.74, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Context.html
===================================================================
--- trunk/docs/src/Modules/Template/Context.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Context.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -676,7 +676,7 @@
title="VERSION"
-%]<p>
2.98, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Document.html
===================================================================
--- trunk/docs/src/Modules/Template/Document.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Document.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -213,7 +213,7 @@
title="VERSION"
-%]<p>
2.79, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Exception.html
===================================================================
--- trunk/docs/src/Modules/Template/Exception.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Exception.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -92,7 +92,7 @@
title="VERSION"
-%]<p>
2.69, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Filters.html
===================================================================
--- trunk/docs/src/Modules/Template/Filters.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Filters.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -43,6 +43,7 @@
"html_break / html_para_break",
"html_line_break",
"uri",
+ "url",
"indent(pad)",
"truncate(length,dots)",
"repeat(iterations)",
@@ -456,14 +457,66 @@
</p>
<pre> my%20file.html</pre>
<p>
-Note that as of TT version 2.16, the uri filter now correctly encodes
-all reserved characters. This includes <code>'&'</code>, <code>'@'</code>, <code>'/'</code>, <code>';'</code>, <code>':'</code>,
-<code>'='</code>, <code>'+'</code>, <code>'?'</code> and <code>'$'</code> which were not escaped (incorrectly) by the
-uri filter in versions 2.15 and earlier. See RFC 2396 for further
-details.
+The uri filter correctly encodes all reserved characters, including
+<code>'&'</code>, <code>'@'</code>, <code>'/'</code>, <code>';'</code>, <code>':'</code>, <code>'='</code>, <code>'+'</code>, <code>'?'</code> and <code>'$'</code>. This filter
+is typically used to encode parameters in a URL that could otherwise
+be interpreted as part of the URL. Here's an example:
</p>
+<pre> [% tt_start_tag %] path = 'http://tt2.org/example'
+ back = '/other?foo=bar&baz=bam'
+ title = 'Earth: "Mostly Harmless"'
+ [% tt_end_tag %]
+ <a href="[% tt_start_tag %] path [% tt_end_tag %]?back=[% tt_start_tag %] back | uri [% tt_end_tag %]&title=[% tt_start_tag %] title | uri [% tt_end_tag %]"></pre>
+<p>
+The output generated is rather long so we'll show it split across two
+lines:
+</p>
+<pre> <a href="http://tt2.org/example?back=%2Fother%3Ffoo%3Dbar%26
+ baz%3Dbam&title=Earth%3A%20%22Mostly%20Harmless%22"></pre>
+<p>
+Without the uri filter the output would look like this (also split across
+two lines).
+</p>
+<pre> <a href="http://tt2.org/example?back=/other?foo=bar
+ &baz=bam&title=Earth: "Mostly Harmless""></pre>
+<p>
+In this rather contrived example we've manage to generate both a broken URL
+(the repeated <code>'?'</code> is not allowed) and a broken HTML element (the href
+attribute is terminated by the first <code>'"'</code> after <code>'Earth: '</code> leaving <code>'Mostly
+Harmless"'</code> dangling on the end of the tag in precisely the way that harmless
+things shouldn't dangle). So don't do that. Always use the uri filter to
+encode your URL parameters.
+</p>
+<p>
+However, you should <b>not</b> use the uri filter to encode an entire URL.
+</p>
+<pre> <a href="[% tt_start_tag %] page_url | uri [% tt_end_tag %]"> # WRONG!</pre>
+<p>
+This will incorrectly encode any reserved characters like <code>':'</code> and <code>'/'</code>
+and that's almost certainly not what you want in this case. Instead
+you should use the <b>url</b> (note spelling) filter for this purpose.
+</p>
+<pre> <a href="[% tt_start_tag %] page_url | url [% tt_end_tag %]"> # CORRECT</pre>
+<p>
+Please note that this behaviour was changed in version 2.16 of the
+Template Toolkit. Prior to that, the uri filter did not encode the
+reserved characters, making it technically incorrect according to the
+RFC 2396 specification. So we fixed it in 2.16 and provided the url
+filter to implement the old behaviour of not encoding reserved
+characters.
+</p>
[%- END %]
[% WRAPPER subsection
+ title = "url"
+-%]<p>
+The url filter is a less aggressive version of the uri filter. It encodes
+any characters outside of the permitted URI character set (as defined by RFC 2396)
+into <code>'%nn'</code> hex escapes. However, unlike the uri filter, the url filter does
+<b>not</b> encode the reserved characters <code>'&'</code>, <code>'@'</code>, <code>'/'</code>, <code>';'</code>, <code>':'</code>, <code>'='</code>, <code>'+'</code>,
+<code>'?'</code> and <code>'$'</code>.
+</p>
+[%- END %]
+[% WRAPPER subsection
title = "indent(pad)"
-%]<p>
Indents the text block by a fixed pad string or width. The 'pad' argument
@@ -711,8 +764,8 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-2.85, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+2.86, distributed as part of the
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Iterator.html
===================================================================
--- trunk/docs/src/Modules/Template/Iterator.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Iterator.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -242,7 +242,7 @@
title="VERSION"
-%]<p>
2.68, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Namespace/Constants.html
===================================================================
--- trunk/docs/src/Modules/Template/Namespace/Constants.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Namespace/Constants.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -104,7 +104,7 @@
title="VERSION"
-%]<p>
1.27, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Parser.html
===================================================================
--- trunk/docs/src/Modules/Template/Parser.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Parser.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -543,7 +543,7 @@
title="VERSION"
-%]<p>
2.89, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
<pre> </pre>
[%- END %]
Modified: trunk/docs/src/Modules/Template/Plugin/Autoformat.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/Autoformat.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/Autoformat.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -154,7 +154,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/CGI.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/CGI.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/CGI.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -105,7 +105,7 @@
title="VERSION"
-%]<p>
2.7, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/Datafile.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/Datafile.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/Datafile.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -105,7 +105,7 @@
title="VERSION"
-%]<p>
2.72, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/Date.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/Date.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/Date.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -166,7 +166,7 @@
title="VERSION"
-%]<p>
2.77, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/Directory.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/Directory.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/Directory.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -247,7 +247,7 @@
title="VERSION"
-%]<p>
2.7, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/Dumper.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/Dumper.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/Dumper.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -104,7 +104,7 @@
title="VERSION"
-%]<p>
2.7, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/File.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/File.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/File.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -268,7 +268,7 @@
title="VERSION"
-%]<p>
2.71, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/Filter.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/Filter.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/Filter.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -286,7 +286,7 @@
title="VERSION"
-%]<p>
1.36, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/Format.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/Format.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/Format.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -62,7 +62,7 @@
title="VERSION"
-%]<p>
2.7, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/HTML.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/HTML.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/HTML.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -120,7 +120,7 @@
title="VERSION"
-%]<p>
2.62, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/Image.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/Image.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/Image.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -274,7 +274,7 @@
title="VERSION"
-%]<p>
1.21, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/Iterator.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/Iterator.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/Iterator.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -64,7 +64,7 @@
title="VERSION"
-%]<p>
2.68, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/Math.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/Math.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/Math.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -130,7 +130,7 @@
title="VERSION"
-%]<p>
1.16, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/Pod.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/Pod.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/Pod.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -62,7 +62,7 @@
title="VERSION"
-%]<p>
2.69, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/Procedural.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/Procedural.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/Procedural.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -77,7 +77,7 @@
title="VERSION"
-%]<p>
1.17, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/String.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/String.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/String.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -431,7 +431,7 @@
title="VERSION"
-%]<p>
2.4, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/Table.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/Table.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/Table.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -219,7 +219,7 @@
title="VERSION"
-%]<p>
2.71, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/URL.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/URL.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/URL.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -133,7 +133,7 @@
title="VERSION"
-%]<p>
2.74, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/View.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/View.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/View.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -68,7 +68,7 @@
title="VERSION"
-%]<p>
2.68, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin/Wrap.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin/Wrap.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin/Wrap.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -101,7 +101,7 @@
title="VERSION"
-%]<p>
2.68, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugin.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugin.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugin.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -243,7 +243,7 @@
title="VERSION"
-%]<p>
2.7, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Plugins.html
===================================================================
--- trunk/docs/src/Modules/Template/Plugins.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Plugins.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -628,7 +628,7 @@
title="VERSION"
-%]<p>
2.77, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Provider.html
===================================================================
--- trunk/docs/src/Modules/Template/Provider.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Provider.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -28,6 +28,9 @@
"paths()"
];
PROCESS tocitem
+ title ="SUBCLASSING"
+ subs = [];
+ PROCESS tocitem
title ="AUTHOR"
subs = [];
PROCESS tocitem
@@ -58,14 +61,18 @@
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
+decline to serve the request, giving subsequent providers a chance to
do so.
</p>
<p>
-This is the "Chain of Responsiblity" pattern. See 'Design Patterns' for
+This is the "Chain of Responsibility" pattern. See 'Design Patterns' for
further information.
</p>
<p>
+The Template::Provider can also be subclassed to provide templates from
+a different source, e.g. a database. See [% ttlink('SUBCLASSING') -%] below.
+</p>
+<p>
This documentation needs work.
</p>
[%- END %]
@@ -251,12 +258,40 @@
The CACHE_SIZE can be set to 0 to disable caching altogether.
</p>
<pre> my $provider = Template::Provider->new({
- CACHE_SIZE => 64, # only cache 64 compiled templates
+ CACHE_SIZE => 64, # only cache 64 compiled templates
});</pre>
<pre> my $provider = Template::Provider->new({
- CACHE_SIZE => 0, # don't cache any compiled templates
+ CACHE_SIZE => 0, # don't cache any compiled templates
});</pre>
+<p>
+As well as caching templates as they are found, the Template::Provider
+also implements negative caching to keep track of templates that are
+<i>not</i> found. This allows the provider to quickly decline a request
+for a template that it has previously failed to locate, saving the effort
+of going to look for it again. This is useful when an INCLUDE_PATH includes
+multiple providers, ensuring that the request is passed down through the
+providers as quickly as possible.
+</p>
+<li><b>STAT_TTL</b><br>
+<p>
+This value can be set to control how long the Template::Provider will keep a
+template cached in memory before checking to see if the source template has
+changed.
+</p>
+<pre> my $provider = Template::Provider->new({
+ STAT_TTL => 60, # one minute
+ });</pre>
+<p>
+The default value is 1 (second). You'll probably want to set this to a higher
+value if you're running the Template Toolkit inside a persistent web server
+application (e.g. mod_perl). For example, set it to 60 and the provider will
+only look for changes to templates once a minute at most. However, during
+development (or any time you're making frequent changes to templates) you'll
+probably want to keep it set to a low value so that you don't have to wait
+for the provider to notice that your templates have changed.
+</p>
+
<li><b>COMPILE_EXT</b><br>
<p>
From version 2 onwards, the Template Toolkit has the ability to
@@ -441,6 +476,46 @@
[%- END %]
[%- END %]
[% WRAPPER section
+ title="SUBCLASSING"
+-%]<p>
+The Template::Provider module can be subclassed to provide templates from a
+different source (e.g. a database). In most cases you'll just need to provide
+custom implementations of the <code>'_template_modified()'</code> and <code>'_template_content()'</code>
+methods. If your provider requires and custom initialisation then you'll also
+need to implement a new <code>'_init()'</code> method.
+</p>
+<p>
+Caching in memory and on disk will still be applied (if enabled)
+when overriding these methods.
+</p>
+<ul>
+<li><b>_template_modified($path)</b><br>
+<p>
+Returns a timestamp of the <code>'$path'</code> passed in by calling stat().
+This can be overridden, for example, to return a last modified value from
+a database. The value returned should be a timestamp value (as returned by <code>'time()'</code>,
+although a sequence number should work as well.
+</p>
+
+<li><b>_template_content($path)</b><br>
+<p>
+This method returns the content of the template for all INCLUDE, PROCESS,
+and INSERT directives.
+</p>
+<p>
+When called in scalar context, the method returns the content of the template
+located at $path, or undef if <code>'$path'</code> is not found.
+</p>
+<p>
+When called in list context it returns <code>'($content, $error, $mtime)'</code>,
+where <code>'$content'</code> is the template content, <code>'$error'</code> is an error string
+(e.g. "$path: File not found"), and <code>'$mtime'</code> is the template modification
+time.
+</p>
+
+</ul>
+[%- END %]
+[% WRAPPER section
title="AUTHOR"
-%]<p>
Andy Wardley <abw@wardley.org>
@@ -452,8 +527,8 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-2.91, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+2.93, distributed as part of the
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Service.html
===================================================================
--- trunk/docs/src/Modules/Template/Service.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Service.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -454,8 +454,8 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-2.91, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+2.93, distributed as part of the
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Stash/Context.html
===================================================================
--- trunk/docs/src/Modules/Template/Stash/Context.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Stash/Context.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -117,7 +117,7 @@
title="VERSION"
-%]<p>
1.63, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Stash/XS.html
===================================================================
--- trunk/docs/src/Modules/Template/Stash/XS.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Stash/XS.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -110,7 +110,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Stash.html
===================================================================
--- trunk/docs/src/Modules/Template/Stash.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Stash.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -183,7 +183,7 @@
title="VERSION"
-%]<p>
2.9, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template/Test.html
===================================================================
--- trunk/docs/src/Modules/Template/Test.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template/Test.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -297,7 +297,7 @@
title="VERSION"
-%]<p>
2.75, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Modules/Template.html
===================================================================
--- trunk/docs/src/Modules/Template.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Modules/Template.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -787,7 +787,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Release/Changes.html
===================================================================
--- trunk/docs/src/Release/Changes.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Release/Changes.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -7,7 +7,7 @@
# Changes
#
# DESCRIPTION
-# Revision history for the Template Toolkit version 2.18, detailing
+# Revision history for the Template Toolkit version 2.19, detailing
# significant changes between versions, most recent first. Some
# way down the file you'll find a section detailing major changes from
# version 1.* to 2.* and a list of "Gotchas!" that you might have to
@@ -27,6 +27,55 @@
#========================================================================
#------------------------------------------------------------------------
+# Version 2.19 - 27th April 2007
+#------------------------------------------------------------------------
+
+* Applied a patch to t/fileline.t from Steffen Müller which fixes the
+ problems running on Win32 with backslashes in paths.
+
+ https://rt.cpan.org/Ticket/Display.html?id=20488
+
+* Applied a patch to the XS Stash from Randy Kobes which fixes some other
+ Win32 problems.
+
+ http://tt2.org/pipermail/templates/2007-February/009247.html
+
+* Applied another patch to the XS Stash from Steve Peters which fixes
+ a problem with tied hashes under more recent version of Perl.
+
+ http://tt2.org/pipermail/templates/2007-January/009181.html
+
+* Fixed a problem in the Perl Stash when using objects that have
+ overloaded comparison operators. Thanks to Randal Schwartz, Tatsuhiko
+ Miyagawa and Daisuke Maki for their contributions.
+
+ http://tt2.org/pipermail/templates/2007-March/009265.html
+
+* Applied a patch from Bill Moseley to Template::Provider which adds
+ negative caching and moves some functionality into separate methods
+ to make subclassing easier. Also added the STAT_TTL configuration
+ parameter.
+
+ http://tt2.org/pipermail/templates/2007-January/009183.html
+
+* Added the url filter as a less aggressive form of the uri filter.
+ Whereas the uri filter now (from v2.16 onwards) encodes all the
+ reserved characters (@, :, /, etc.) as per RFC2396, the url filter
+ leaves them intact and thus behaves just like the uri filter used
+ to.
+
+ http://tt2.org/pipermail/templates/2007-March/009277.html
+
+#------------------------------------------------------------------------
+# Version 2.18a - 9th February 2007
+#------------------------------------------------------------------------
+
+* Applied a patch from Steve Peters to the Stash.xs to allow it to
+ compile with bleadperl 5.9.x
+
+ https://rt.cpan.org/Public/Bug/Display.html?id=22506
+
+#------------------------------------------------------------------------
# Version 2.18 - 9th February 2007
#------------------------------------------------------------------------
Modified: trunk/docs/src/Release/HACKING.html
===================================================================
--- trunk/docs/src/Release/HACKING.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Release/HACKING.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -5,9 +5,9 @@
Template Toolkit
- Version 2.18
+ Version 2.19
- 09 February 2007
+ 27 April 2007
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved
Modified: trunk/docs/src/Release/INSTALL.html
===================================================================
--- trunk/docs/src/Release/INSTALL.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Release/INSTALL.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -5,9 +5,9 @@
Template Toolkit
- Version 2.18
+ Version 2.19
- 09 February 2007
+ 27 April 2007
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved
@@ -28,8 +28,8 @@
To install the Template Toolkit:
- tar zxf Template-Toolkit-2.18.tar.gz
- cd Template-Toolkit-2.18
+ tar zxf Template-Toolkit-2.19.tar.gz
+ cd Template-Toolkit-2.19
perl Makefile.PL
make
make test
@@ -91,19 +91,19 @@
Template-Toolkit-<version>.tar.gz
-where <version> represents the current version number, e.g. 2.18.
+where <version> represents the current version number, e.g. 2.19.
To install the Template Toolkit, unpack the distribution archive to
create an installation directory. Something like this:
- tar zxf Template-Toolkit-2.18.tar.gz
+ tar zxf Template-Toolkit-2.19.tar.gz
or
- gunzip Template-Toolkit-2.18.tar.gz
- tar xf Template-Toolkit-2.18.tar
+ gunzip Template-Toolkit-2.19.tar.gz
+ tar xf Template-Toolkit-2.19.tar
You can then 'cd' into the directory created,
- cd Template-Toolkit-2.18
+ cd Template-Toolkit-2.19
and perform the usual Perl installation procedure:
Modified: trunk/docs/src/Release/README.html
===================================================================
--- trunk/docs/src/Release/README.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Release/README.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -5,9 +5,9 @@
Template Toolkit
- Version 2.18
+ Version 2.19
- 09 February 2007
+ 27 April 2007
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved
@@ -29,8 +29,8 @@
To install the Template Toolkit:
- tar zxf Template-Toolkit-2.18.tar.gz
- cd Template-Toolkit-2.18
+ tar zxf Template-Toolkit-2.19.tar.gz
+ cd Template-Toolkit-2.19
perl Makefile.PL
make
make test
@@ -72,6 +72,11 @@
WHAT'S NEW?
-----------
+Version 2.19 fixes some minor bugs in both Perl and XS versions of the Template
+Stash, and fixes a problem with a test in the test suite failing under Win32.
+It also adds the url filter as a version of what the uri filter used to do
+before we fixed it to do the right thing.
+
Version 2.18 fixes a number of minor bugs. It also includes a modification to
the parser grammar so that you can write expressions as arguments to
subroutine, method or vmethod calls.
Modified: trunk/docs/src/Release/TODO.html
===================================================================
--- trunk/docs/src/Release/TODO.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Release/TODO.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -7,7 +7,7 @@
# TODO
#
# DESCRIPTION
-# TODO list for the Template Toolkit version 2.18, containing
+# TODO list for the Template Toolkit version 2.19, containing
# known bugs, limitations, planned enhancements, long term visions
# and a few whacky ideas.
#
Modified: trunk/docs/src/Tools/tpage.html
===================================================================
--- trunk/docs/src/Tools/tpage.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Tools/tpage.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -74,7 +74,7 @@
title="VERSION"
-%]<p>
2.68, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Tools/ttree.html
===================================================================
--- trunk/docs/src/Tools/ttree.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Tools/ttree.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -365,7 +365,7 @@
title="VERSION"
-%]<p>
2.68, distributed as part of the
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Tutorial/Datafile.html
===================================================================
--- trunk/docs/src/Tutorial/Datafile.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Tutorial/Datafile.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -433,7 +433,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/docs/src/Tutorial/Web.html
===================================================================
--- trunk/docs/src/Tutorial/Web.html 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/docs/src/Tutorial/Web.html 2007-04-27 18:32:51 UTC (rev 1069)
@@ -783,7 +783,7 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.18, released on 09 February 2007.
+Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
Modified: trunk/lib/Template/Filters.pm
===================================================================
--- trunk/lib/Template/Filters.pm 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/lib/Template/Filters.pm 2007-04-27 18:32:51 UTC (rev 1069)
@@ -1016,12 +1016,61 @@
my%20file.html
-Note that as of TT version 2.16, the uri filter now correctly encodes
-all reserved characters. This includes C<&>, C<@>, C</>, C<;>, C<:>,
-C<=>, C<+>, C<?> and C<$> which were not escaped (incorrectly) by the
-uri filter in versions 2.15 and earlier. See RFC 2396 for further
-details.
+The uri filter correctly encodes all reserved characters, including
+C<&>, C<@>, C</>, C<;>, C<:>, C<=>, C<+>, C<?> and C<$>. This filter
+is typically used to encode parameters in a URL that could otherwise
+be interpreted as part of the URL. Here's an example:
+ [% path = 'http://tt2.org/example'
+ back = '/other?foo=bar&baz=bam'
+ title = 'Earth: "Mostly Harmless"'
+ %]
+ <a href="[% path %]?back=[% back | uri %]&title=[% title | uri %]">
+
+The output generated is rather long so we'll show it split across two
+lines:
+
+ <a href="http://tt2.org/example?back=%2Fother%3Ffoo%3Dbar%26
+ baz%3Dbam&title=Earth%3A%20%22Mostly%20Harmless%22">
+
+Without the uri filter the output would look like this (also split across
+two lines).
+
+ <a href="http://tt2.org/example?back=/other?foo=bar
+ &baz=bam&title=Earth: "Mostly Harmless"">
+
+In this rather contrived example we've manage to generate both a broken URL
+(the repeated C<?> is not allowed) and a broken HTML element (the href
+attribute is terminated by the first C<"> after C<Earth: > leaving C<Mostly
+Harmless"> dangling on the end of the tag in precisely the way that harmless
+things shouldn't dangle). So don't do that. Always use the uri filter to
+encode your URL parameters.
+
+However, you should B<not> use the uri filter to encode an entire URL.
+
+ <a href="[% page_url | uri %]"> # WRONG!
+
+This will incorrectly encode any reserved characters like C<:> and C</>
+and that's almost certainly not what you want in this case. Instead
+you should use the B<url> (note spelling) filter for this purpose.
+
+ <a href="[% page_url | url %]"> # CORRECT
+
+Please note that this behaviour was changed in version 2.16 of the
+Template Toolkit. Prior to that, the uri filter did not encode the
+reserved characters, making it technically incorrect according to the
+RFC 2396 specification. So we fixed it in 2.16 and provided the url
+filter to implement the old behaviour of not encoding reserved
+characters.
+
+=head2 url
+
+The url filter is a less aggressive version of the uri filter. It encodes
+any characters outside of the permitted URI character set (as defined by RFC 2396)
+into C<%nn> hex escapes. However, unlike the uri filter, the url filter does
+B<not> encode the reserved characters C<&>, C<@>, C</>, C<;>, C<:>, C<=>, C<+>,
+C<?> and C<$>.
+
=head2 indent(pad)
Indents the text block by a fixed pad string or width. The 'pad' argument
Modified: trunk/lib/Template/Grammar.pm
===================================================================
--- trunk/lib/Template/Grammar.pm 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/lib/Template/Grammar.pm 2007-04-27 18:32:51 UTC (rev 1069)
@@ -5229,7 +5229,7 @@
sub
#line 71 "Parser.yp"
{ push(@{$_[1]}, $_[2])
- if defined $_[2]; $_[1] }
+ if defined $_[2]; $_[1] }
],
[#Rule 5
'chunks', 1,
@@ -5248,8 +5248,8 @@
sub
#line 77 "Parser.yp"
{ return '' unless $_[1];
- $_[0]->location() . $_[1];
- }
+ $_[0]->location() . $_[1];
+ }
],
[#Rule 8
'statement', 1, undef
@@ -5402,8 +5402,8 @@
sub
#line 127 "Parser.yp"
{ $_[0]->{ INFOR }
- ? $factory->next()
- : ($_[0]->{ INWHILE }
+ ? $factory->next()
+ : ($_[0]->{ INWHILE }
? 'next LOOP;'
: 'next;') }
],
@@ -5412,13 +5412,13 @@
sub
#line 132 "Parser.yp"
{ if ($_[2]->[0]->[0] =~ /^'(on|off)'$/) {
- $_[0]->{ DEBUG_DIRS } = ($1 eq 'on');
- $factory->debug($_[2]);
- }
- else {
- $_[0]->{ DEBUG_DIRS } ? $factory->debug($_[2]) : '';
- }
- }
+ $_[0]->{ DEBUG_DIRS } = ($1 eq 'on');
+ $factory->debug($_[2]);
+ }
+ else {
+ $_[0]->{ DEBUG_DIRS } ? $factory->debug($_[2]) : '';
+ }
+ }
],
[#Rule 42
'atomdir', 1, undef
@@ -5455,7 +5455,7 @@
sub
#line 153 "Parser.yp"
{ unshift(@{$_[5]}, [ @_[2, 4] ]);
- $_[5]; }
+ $_[5]; }
],
[#Rule 49
'else', 3,
@@ -5480,7 +5480,7 @@
sub
#line 164 "Parser.yp"
{ unshift(@{$_[5]}, [ @_[2, 4] ]);
- $_[5]; }
+ $_[5]; }
],
[#Rule 53
'case', 4,
@@ -5511,181 +5511,181 @@
sub
#line 172 "Parser.yp"
{ $_[0]->{ INFOR }--;
- $factory->foreach(@{$_[2]}, $_[5]) }
+ $factory->foreach(@{$_[2]}, $_[5]) }
],
[#Rule 58
'loop', 3,
sub
-#line 176 "Parser.yp"
+#line 174 "Parser.yp"
{ $factory->foreach(@{$_[3]}, $_[1]) }
],
[#Rule 59
'@2-3', 0,
sub
-#line 177 "Parser.yp"
+#line 175 "Parser.yp"
{ $_[0]->{ INWHILE }++ }
],
[#Rule 60
'loop', 6,
sub
-#line 178 "Parser.yp"
+#line 176 "Parser.yp"
{ $_[0]->{ INWHILE }--;
$factory->while(@_[2, 5]) }
],
[#Rule 61
'loop', 3,
sub
-#line 180 "Parser.yp"
+#line 178 "Parser.yp"
{ $factory->while(@_[3, 1]) }
],
[#Rule 62
'loopvar', 4,
sub
-#line 183 "Parser.yp"
+#line 181 "Parser.yp"
{ [ @_[1, 3, 4] ] }
],
[#Rule 63
'loopvar', 4,
sub
-#line 184 "Parser.yp"
+#line 182 "Parser.yp"
{ [ @_[1, 3, 4] ] }
],
[#Rule 64
'loopvar', 2,
sub
-#line 185 "Parser.yp"
+#line 183 "Parser.yp"
{ [ 0, @_[1, 2] ] }
],
[#Rule 65
'wrapper', 5,
sub
-#line 189 "Parser.yp"
+#line 187 "Parser.yp"
{ $factory->wrapper(@_[2, 4]) }
],
[#Rule 66
'wrapper', 3,
sub
-#line 191 "Parser.yp"
+#line 189 "Parser.yp"
{ $factory->wrapper(@_[3, 1]) }
],
[#Rule 67
'try', 5,
sub
-#line 195 "Parser.yp"
+#line 193 "Parser.yp"
{ $factory->try(@_[3, 4]) }
],
[#Rule 68
'final', 5,
sub
-#line 199 "Parser.yp"
+#line 197 "Parser.yp"
{ unshift(@{$_[5]}, [ @_[2,4] ]);
- $_[5]; }
+ $_[5]; }
],
[#Rule 69
'final', 5,
sub
-#line 202 "Parser.yp"
+#line 200 "Parser.yp"
{ unshift(@{$_[5]}, [ undef, $_[4] ]);
- $_[5]; }
+ $_[5]; }
],
[#Rule 70
'final', 4,
sub
-#line 205 "Parser.yp"
+#line 203 "Parser.yp"
{ unshift(@{$_[4]}, [ undef, $_[3] ]);
- $_[4]; }
+ $_[4]; }
],
[#Rule 71
'final', 3,
sub
-#line 207 "Parser.yp"
+#line 205 "Parser.yp"
{ [ $_[3] ] }
],
[#Rule 72
'final', 0,
sub
-#line 208 "Parser.yp"
+#line 206 "Parser.yp"
{ [ 0 ] }
],
[#Rule 73
'use', 2,
sub
-#line 211 "Parser.yp"
+#line 209 "Parser.yp"
{ $factory->use($_[2]) }
],
[#Rule 74
'@3-3', 0,
sub
-#line 214 "Parser.yp"
-{ $_[0]->push_defblock(); }
+#line 212 "Parser.yp"
+{ $_[0]->push_defblock(); }
],
[#Rule 75
'view', 6,
sub
-#line 215 "Parser.yp"
+#line 213 "Parser.yp"
{ $factory->view(@_[2,5],
- $_[0]->pop_defblock) }
+ $_[0]->pop_defblock) }
],
[#Rule 76
'@4-2', 0,
sub
-#line 219 "Parser.yp"
+#line 217 "Parser.yp"
{ ${$_[0]->{ INPERL }}++; }
],
[#Rule 77
'perl', 5,
sub
-#line 220 "Parser.yp"
+#line 218 "Parser.yp"
{ ${$_[0]->{ INPERL }}--;
- $_[0]->{ EVAL_PERL }
- ? $factory->perl($_[4])
- : $factory->no_perl(); }
+ $_[0]->{ EVAL_PERL }
+ ? $factory->perl($_[4])
+ : $factory->no_perl(); }
],
[#Rule 78
'@5-1', 0,
sub
-#line 226 "Parser.yp"
+#line 224 "Parser.yp"
{ ${$_[0]->{ INPERL }}++;
- $rawstart = ${$_[0]->{'LINE'}}; }
+ $rawstart = ${$_[0]->{'LINE'}}; }
],
[#Rule 79
'rawperl', 5,
sub
-#line 228 "Parser.yp"
+#line 226 "Parser.yp"
{ ${$_[0]->{ INPERL }}--;
- $_[0]->{ EVAL_PERL }
- ? $factory->rawperl($_[4], $rawstart)
- : $factory->no_perl(); }
+ $_[0]->{ EVAL_PERL }
+ ? $factory->rawperl($_[4], $rawstart)
+ : $factory->no_perl(); }
],
[#Rule 80
'filter', 5,
sub
-#line 235 "Parser.yp"
+#line 233 "Parser.yp"
{ $factory->filter(@_[2,4]) }
],
[#Rule 81
'filter', 3,
sub
-#line 237 "Parser.yp"
+#line 235 "Parser.yp"
{ $factory->filter(@_[3,1]) }
],
[#Rule 82
'defblock', 5,
sub
-#line 242 "Parser.yp"
+#line 240 "Parser.yp"
{ my $name = join('/', @{ $_[0]->{ DEFBLOCKS } });
- pop(@{ $_[0]->{ DEFBLOCKS } });
- $_[0]->define_block($name, $_[4]);
- undef
- }
+ pop(@{ $_[0]->{ DEFBLOCKS } });
+ $_[0]->define_block($name, $_[4]);
+ undef
+ }
],
[#Rule 83
'defblockname', 2,
sub
-#line 249 "Parser.yp"
+#line 247 "Parser.yp"
{ push(@{ $_[0]->{ DEFBLOCKS } }, $_[2]);
- $_[2];
- }
+ $_[2];
+ }
],
[#Rule 84
'blockname', 1, undef
@@ -5693,7 +5693,7 @@
[#Rule 85
'blockname', 1,
sub
-#line 255 "Parser.yp"
+#line 253 "Parser.yp"
{ $_[1] =~ s/^'(.*)'$/$1/; $_[1] }
],
[#Rule 86
@@ -5705,28 +5705,28 @@
[#Rule 88
'anonblock', 5,
sub
-#line 263 "Parser.yp"
+#line 261 "Parser.yp"
{ local $" = ', ';
- print STDERR "experimental block args: [@{ $_[2] }]\n"
- if $_[2];
- $factory->anon_block($_[4]) }
+ print STDERR "experimental block args: [@{ $_[2] }]\n"
+ if $_[2];
+ $factory->anon_block($_[4]) }
],
[#Rule 89
'capture', 3,
sub
-#line 269 "Parser.yp"
+#line 267 "Parser.yp"
{ $factory->capture(@_[1, 3]) }
],
[#Rule 90
'macro', 6,
sub
-#line 273 "Parser.yp"
+#line 271 "Parser.yp"
{ $factory->macro(@_[2, 6, 4]) }
],
[#Rule 91
'macro', 3,
sub
-#line 274 "Parser.yp"
+#line 272 "Parser.yp"
{ $factory->macro(@_[2, 3]) }
],
[#Rule 92
@@ -5735,31 +5735,31 @@
[#Rule 93
'mdir', 4,
sub
-#line 278 "Parser.yp"
+#line 276 "Parser.yp"
{ $_[3] }
],
[#Rule 94
'margs', 2,
sub
-#line 281 "Parser.yp"
+#line 279 "Parser.yp"
{ push(@{$_[1]}, $_[2]); $_[1] }
],
[#Rule 95
'margs', 2,
sub
-#line 282 "Parser.yp"
+#line 280 "Parser.yp"
{ $_[1] }
],
[#Rule 96
'margs', 1,
sub
-#line 283 "Parser.yp"
+#line 281 "Parser.yp"
{ [ $_[1] ] }
],
[#Rule 97
'metadata', 2,
sub
-#line 286 "Parser.yp"
+#line 284 "Parser.yp"
{ push(@{$_[1]}, @{$_[2]}); $_[1] }
],
[#Rule 98
@@ -5771,21 +5771,21 @@
[#Rule 100
'meta', 3,
sub
-#line 291 "Parser.yp"
+#line 289 "Parser.yp"
{ for ($_[3]) { s/^'//; s/'$//;
- s/\\'/'/g };
- [ @_[1,3] ] }
+ s/\\'/'/g };
+ [ @_[1,3] ] }
],
[#Rule 101
'meta', 5,
sub
-#line 294 "Parser.yp"
+#line 292 "Parser.yp"
{ [ @_[1,4] ] }
],
[#Rule 102
'meta', 3,
sub
-#line 295 "Parser.yp"
+#line 293 "Parser.yp"
{ [ @_[1,3] ] }
],
[#Rule 103
@@ -5797,43 +5797,43 @@
[#Rule 105
'lterm', 3,
sub
-#line 307 "Parser.yp"
+#line 305 "Parser.yp"
{ "[ $_[2] ]" }
],
[#Rule 106
'lterm', 3,
sub
-#line 308 "Parser.yp"
+#line 306 "Parser.yp"
{ "[ $_[2] ]" }
],
[#Rule 107
'lterm', 2,
sub
-#line 309 "Parser.yp"
+#line 307 "Parser.yp"
{ "[ ]" }
],
[#Rule 108
'lterm', 3,
sub
-#line 310 "Parser.yp"
+#line 308 "Parser.yp"
{ "{ $_[2] }" }
],
[#Rule 109
'sterm', 1,
sub
-#line 313 "Parser.yp"
+#line 311 "Parser.yp"
{ $factory->ident($_[1]) }
],
[#Rule 110
'sterm', 2,
sub
-#line 314 "Parser.yp"
+#line 312 "Parser.yp"
{ $factory->identref($_[2]) }
],
[#Rule 111
'sterm', 3,
sub
-#line 315 "Parser.yp"
+#line 313 "Parser.yp"
{ $factory->quoted($_[2]) }
],
[#Rule 112
@@ -5845,7 +5845,7 @@
[#Rule 114
'list', 2,
sub
-#line 320 "Parser.yp"
+#line 318 "Parser.yp"
{ "$_[1], $_[2]" }
],
[#Rule 115
@@ -5857,7 +5857,7 @@
[#Rule 117
'range', 3,
sub
-#line 325 "Parser.yp"
+#line 323 "Parser.yp"
{ $_[1] . '..' . $_[3] }
],
[#Rule 118
@@ -5866,13 +5866,13 @@
[#Rule 119
'hash', 0,
sub
-#line 330 "Parser.yp"
+#line 328 "Parser.yp"
{ "" }
],
[#Rule 120
'params', 2,
sub
-#line 333 "Parser.yp"
+#line 331 "Parser.yp"
{ "$_[1], $_[2]" }
],
[#Rule 121
@@ -5884,28 +5884,28 @@
[#Rule 123
'param', 3,
sub
-#line 338 "Parser.yp"
+#line 336 "Parser.yp"
{ "$_[1] => $_[3]" }
],
[#Rule 124
'param', 3,
sub
-#line 339 "Parser.yp"
+#line 337 "Parser.yp"
{ "$_[1] => $_[3]" }
],
[#Rule 125
'ident', 3,
sub
-#line 342 "Parser.yp"
+#line 340 "Parser.yp"
{ push(@{$_[1]}, @{$_[3]}); $_[1] }
],
[#Rule 126
'ident', 3,
sub
-#line 343 "Parser.yp"
+#line 341 "Parser.yp"
{ push(@{$_[1]},
- map {($_, 0)} split(/\./, $_[3]));
- $_[1]; }
+ map {($_, 0)} split(/\./, $_[3]));
+ $_[1]; }
],
[#Rule 127
'ident', 1, undef
@@ -5913,111 +5913,111 @@
[#Rule 128
'node', 1,
sub
-#line 349 "Parser.yp"
+#line 347 "Parser.yp"
{ [ $_[1], 0 ] }
],
[#Rule 129
'node', 4,
sub
-#line 350 "Parser.yp"
+#line 348 "Parser.yp"
{ [ $_[1], $factory->args($_[3]) ] }
],
[#Rule 130
'item', 1,
sub
-#line 353 "Parser.yp"
+#line 351 "Parser.yp"
{ "'$_[1]'" }
],
[#Rule 131
'item', 3,
sub
-#line 354 "Parser.yp"
+#line 352 "Parser.yp"
{ $_[2] }
],
[#Rule 132
'item', 2,
sub
-#line 355 "Parser.yp"
+#line 353 "Parser.yp"
{ $_[0]->{ V1DOLLAR }
- ? "'$_[2]'"
- : $factory->ident(["'$_[2]'", 0]) }
+ ? "'$_[2]'"
+ : $factory->ident(["'$_[2]'", 0]) }
],
[#Rule 133
'expr', 3,
sub
-#line 360 "Parser.yp"
+#line 358 "Parser.yp"
{ "$_[1] $_[2] $_[3]" }
],
[#Rule 134
'expr', 3,
sub
-#line 361 "Parser.yp"
+#line 359 "Parser.yp"
{ "$_[1] $_[2] $_[3]" }
],
[#Rule 135
'expr', 3,
sub
-#line 362 "Parser.yp"
+#line 360 "Parser.yp"
{ "$_[1] $_[2] $_[3]" }
],
[#Rule 136
'expr', 3,
sub
-#line 363 "Parser.yp"
+#line 361 "Parser.yp"
{ "int($_[1] / $_[3])" }
],
[#Rule 137
'expr', 3,
sub
-#line 364 "Parser.yp"
+#line 362 "Parser.yp"
{ "$_[1] % $_[3]" }
],
[#Rule 138
'expr', 3,
sub
-#line 365 "Parser.yp"
+#line 363 "Parser.yp"
{ "$_[1] $CMPOP{ $_[2] } $_[3]" }
],
[#Rule 139
'expr', 3,
sub
-#line 366 "Parser.yp"
+#line 364 "Parser.yp"
{ "$_[1] . $_[3]" }
],
[#Rule 140
'expr', 3,
sub
-#line 367 "Parser.yp"
+#line 365 "Parser.yp"
{ "$_[1] && $_[3]" }
],
[#Rule 141
'expr', 3,
sub
-#line 368 "Parser.yp"
+#line 366 "Parser.yp"
{ "$_[1] || $_[3]" }
],
[#Rule 142
'expr', 2,
sub
-#line 369 "Parser.yp"
+#line 367 "Parser.yp"
{ "! $_[2]" }
],
[#Rule 143
'expr', 5,
sub
-#line 370 "Parser.yp"
+#line 368 "Parser.yp"
{ "$_[1] ? $_[3] : $_[5]" }
],
[#Rule 144
'expr', 3,
sub
-#line 371 "Parser.yp"
+#line 369 "Parser.yp"
{ $factory->assign(@{$_[2]}) }
],
[#Rule 145
'expr', 3,
sub
-#line 372 "Parser.yp"
+#line 370 "Parser.yp"
{ "($_[2])" }
],
[#Rule 146
@@ -6026,7 +6026,7 @@
[#Rule 147
'setlist', 2,
sub
-#line 376 "Parser.yp"
+#line 374 "Parser.yp"
{ push(@{$_[1]}, @{$_[2]}); $_[1] }
],
[#Rule 148
@@ -6038,50 +6038,50 @@
[#Rule 150
'assign', 3,
sub
-#line 382 "Parser.yp"
+#line 380 "Parser.yp"
{ [ $_[1], $_[3] ] }
],
[#Rule 151
'assign', 3,
sub
-#line 383 "Parser.yp"
+#line 381 "Parser.yp"
{ [ @_[1,3] ] }
],
[#Rule 152
'args', 2,
sub
-#line 390 "Parser.yp"
+#line 388 "Parser.yp"
{ push(@{$_[1]}, $_[2]); $_[1] }
],
[#Rule 153
'args', 2,
sub
-#line 391 "Parser.yp"
+#line 389 "Parser.yp"
{ push(@{$_[1]->[0]}, $_[2]); $_[1] }
],
[#Rule 154
'args', 4,
sub
-#line 392 "Parser.yp"
+#line 390 "Parser.yp"
{ push(@{$_[1]->[0]}, "'', " .
- $factory->assign(@_[2,4])); $_[1] }
+ $factory->assign(@_[2,4])); $_[1] }
],
[#Rule 155
'args', 2,
sub
-#line 394 "Parser.yp"
+#line 392 "Parser.yp"
{ $_[1] }
],
[#Rule 156
'args', 0,
sub
-#line 395 "Parser.yp"
+#line 393 "Parser.yp"
{ [ [ ] ] }
],
[#Rule 157
'lnameargs', 3,
sub
-#line 405 "Parser.yp"
+#line 403 "Parser.yp"
{ push(@{$_[3]}, $_[1]); $_[3] }
],
[#Rule 158
@@ -6093,7 +6093,7 @@
[#Rule 160
'lvalue', 3,
sub
-#line 410 "Parser.yp"
+#line 408 "Parser.yp"
{ $factory->quoted($_[2]) }
],
[#Rule 161
@@ -6102,43 +6102,43 @@
[#Rule 162
'nameargs', 3,
sub
-#line 414 "Parser.yp"
+#line 412 "Parser.yp"
{ [ [$factory->ident($_[2])], $_[3] ] }
],
[#Rule 163
'nameargs', 2,
sub
-#line 415 "Parser.yp"
+#line 413 "Parser.yp"
{ [ @_[1,2] ] }
],
[#Rule 164
'nameargs', 4,
sub
-#line 416 "Parser.yp"
+#line 414 "Parser.yp"
{ [ @_[1,3] ] }
],
[#Rule 165
'names', 3,
sub
-#line 419 "Parser.yp"
+#line 417 "Parser.yp"
{ push(@{$_[1]}, $_[3]); $_[1] }
],
[#Rule 166
'names', 1,
sub
-#line 420 "Parser.yp"
+#line 418 "Parser.yp"
{ [ $_[1] ] }
],
[#Rule 167
'name', 3,
sub
-#line 423 "Parser.yp"
+#line 421 "Parser.yp"
{ $factory->quoted($_[2]) }
],
[#Rule 168
'name', 1,
sub
-#line 424 "Parser.yp"
+#line 422 "Parser.yp"
{ "'$_[1]'" }
],
[#Rule 169
@@ -6147,7 +6147,7 @@
[#Rule 170
'filename', 3,
sub
-#line 436 "Parser.yp"
+#line 426 "Parser.yp"
{ "$_[1].$_[3]" }
],
[#Rule 171
@@ -6165,32 +6165,32 @@
[#Rule 175
'quoted', 2,
sub
-#line 450 "Parser.yp"
+#line 440 "Parser.yp"
{ push(@{$_[1]}, $_[2])
- if defined $_[2]; $_[1] }
+ if defined $_[2]; $_[1] }
],
[#Rule 176
'quoted', 0,
sub
-#line 452 "Parser.yp"
+#line 442 "Parser.yp"
{ [ ] }
],
[#Rule 177
'quotable', 1,
sub
-#line 455 "Parser.yp"
+#line 445 "Parser.yp"
{ $factory->ident($_[1]) }
],
[#Rule 178
'quotable', 1,
sub
-#line 456 "Parser.yp"
+#line 446 "Parser.yp"
{ $factory->text($_[1]) }
],
[#Rule 179
'quotable', 1,
sub
-#line 457 "Parser.yp"
+#line 447 "Parser.yp"
{ undef }
]
];
Modified: trunk/lib/Template/Manual/Filters.pod
===================================================================
--- trunk/lib/Template/Manual/Filters.pod 2007-04-27 13:33:25 UTC (rev 1068)
+++ trunk/lib/Template/Manual/Filters.pod 2007-04-27 18:32:51 UTC (rev 1069)
@@ -225,12 +225,61 @@
my%20file.html
-Note that as of TT version 2.16, the uri filter now correctly encodes
-all reserved characters. This includes C<&>, C<@>, C</>, C<;>, C<:>,
-C<=>, C<+>, C<?> and C<$> which were not escaped (incorrectly) by the
-uri filter in versions 2.15 and earlier. See RFC 2396 for further
-details.
+The uri filter correctly encodes all reserved characters, including
+C<&>, C<@>, C</>, C<;>, C<:>, C<=>, C<+>, C<?> and C<$>. This filter
+is typically used to encode parameters in a URL that could otherwise
+be interpreted as part of the URL. Here's an example:
+ [% path = 'http://tt2.org/example'
+ back = '/other?foo=bar&baz=bam'
+ title = 'Earth: "Mostly Harmless"'
+ %]
+ <a href="[% path %]?back=[% back | uri %]&title=[% title | uri %]">
+
+The output generated is rather long so we'll show it split across two
+lines:
+
+ <a href="http://tt2.org/example?back=%2Fother%3Ffoo%3Dbar%26
+ baz%3Dbam&title=Earth%3A%20%22Mostly%20Harmless%22">
+
+Without the uri filter the output would look like this (also split across
+two lines).
+
+ <a href="http://tt2.org/example?back=/other?foo=bar
+ &baz=bam&title=Earth: "Mostly Harmless"">
+
+In this rather contrived example we've manage to generate both a broken URL
+(the repeated C<?> is not allowed) and a broken HTML element (the href
+attribute is terminated by the first C<"> after C<Earth: > leaving C<Mostly
+Harmless"> dangling on the end of the tag in precisely the way that harmless
+things shouldn't dangle). So don't do that. Always use the uri filter to
+encode your URL parameters.
+
+However, you should B<not> use the uri filter to encode an entire URL.
+
+ <a href="[% page_url | uri %]"> # WRONG!
+
+This will incorrectly encode any reserved characters like C<:> and C</>
+and that's almost certainly not what you want in this case. Instead
+you should use the B<url> (note spelling) filter for this purpose.
+
+ <a href="[% page_url | url %]"> # CORRECT
+
+Please note that this behaviour was changed in version 2.16 of the
+Template Toolkit. Prior to that, the uri filter did not encode the
+reserved characters, making it technically incorrect according to the
+RFC 2396 specification. So we fixed it in 2.16 and provided the url
+filter to implement the old behaviour of not encoding reserved
+characters.
+
+=head2 url
+
+The url filter is a less aggressive version of the uri filter. It encodes
+any characters outside of the permitted URI character set (as defined by RFC 2396)
+into C<%nn> hex escapes. However, unlike the uri filter, the url filter does
+B<not> encode the reserved characters C<&>, C<@>, C</>, C<;>, C<:>, C<=>, C<+>,
+C<?> and C<$>.
+
=head2 indent(pad)
Indents the text block by a fixed pad string or width. The 'pad' argument