[Templates-cvs] cvs commit: Template2/docs/src/Manual Config.html Credits.html Directives.html Filters.html Internals.html Intro.html Plugins.html Refs.html Syntax.html VMethods.html Variables.html Views.html
cvs@template-toolkit.org
cvs@template-toolkit.org
cvs 06/05/26 13:44:34
Modified: docs/src/Manual Config.html Credits.html Directives.html
Filters.html Internals.html Intro.html Plugins.html
Refs.html Syntax.html VMethods.html Variables.html
Views.html
Log:
Version 2.15
Revision Changes Path
1.49 +72 -34 Template2/docs/src/Manual/Config.html
Index: Config.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Manual/Config.html,v
retrieving revision 1.48
retrieving revision 1.49
diff -u -r1.48 -r1.49
--- Config.html 2006/01/30 20:03:21 1.48
+++ Config.html 2006/05/26 13:44:33 1.49
@@ -125,9 +125,9 @@
The PRE_CHOMP and POST_CHOMP options can help to clean up some of this
extraneous whitespace. Both are disabled by default.
</p>
-<pre> my $template = Template->new({
- PRE_CHOMP => 1,
- POST_CHOMP => 1,
+<pre> my $template = Template-E<gt>new({
+ PRE_CHOMP =E<gt> 1,
+ POST_CHOMP =E<gt> 1,
});</pre>
<p>
With PRE_CHOMP set to 1, the newline and whitespace preceding a directive
@@ -135,64 +135,102 @@
concatenating a line that starts with a directive onto the end of the
previous line.
</p>
-<pre> Foo <----------.
- |
+<pre> Foo E<lt>----------.
+ |
,---(PRE_CHOMP)----'
|
`-- [% tt_start_tag %] a = 10 [% tt_end_tag %] --.
- |
+ |
,---(POST_CHOMP)---'
|
- `-> Bar</pre>
+ `-E<gt> Bar</pre>
<p>
With POST_CHOMP set to 1, any whitespace after a directive up to and
including the newline will be deleted. This has the effect of joining
a line that ends with a directive onto the start of the next line.
</p>
<p>
-If PRE_CHOMP or POST_CHOMP is set to 2, then instead of removing all
-the whitespace, the whitespace will be collapsed to a single space.
+If PRE_CHOMP or POST_CHOMP is set to 2, all whitespace including any
+number of newline will be removed and replaced with a single space.
This is useful for HTML, where (usually) a contiguous block of
whitespace is rendered the same as a single space.
</p>
+<p>
+With PRE_CHOMP or POST_CHOMP set to 3, all adjacent whitespace
+(including newlines) will be removed entirely.
+</p>
<p>
-You may use the CHOMP_NONE, CHOMP_ALL, and CHOMP_COLLAPSE constants
-from the Template::Constants module to deactivate chomping, remove
-all whitespace, or collapse whitespace to a single space.
+These values are defined as CHOMP_NONE, CHOMP_ONE, CHOMP_COLLAPSE and
+CHOMP_GREEDY constants in the Template::Constants module. CHOMP_ALL
+is also defined as an alias for CHOMP_ONE to provide backwards
+compatability with earlier version of the Template Toolkit.
+</p>
+<p>
+Additionally the chomp tag modifiers listed below may also be used for
+the PRE_CHOMP and POST_CHOMP configuration.
+
+ my $template = Template->new({
+ PRE_CHOMP =< '~',
+ POST_CHOMP => '-',
+ });
</p>
<p>
PRE_CHOMP and POST_CHOMP can be activated for individual directives by
placing a '-' immediately at the start and/or end of the directive.
</p>
-<pre> [% tt_start_tag %] FOREACH user = userlist [% tt_end_tag %]
+<pre> [% tt_start_tag %] FOREACH user IN userlist [% tt_end_tag %]
[% tt_start_tag %]- user -[% tt_end_tag %]
[% tt_start_tag %] END [% tt_end_tag %]</pre>
+<p>
+This has the same effect as CHOMP_ONE in removing all whitespace
+before or after the directive up to and including the newline. The
+template will be processed as if written:
+</p>
+<pre> [% tt_start_tag %] FOREACH user IN userlist [% tt_end_tag %][% tt_start_tag %] user [% tt_end_tag %][% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
-The '-' characters activate both PRE_CHOMP and POST_CHOMP for the one
-directive '[% tt_start_tag %]- name -[% tt_end_tag %]'. Thus, the template will be processed as if
-written:
-</p>
-<pre> [% tt_start_tag %] FOREACH user = userlist [% tt_end_tag %][% tt_start_tag %] user [% tt_end_tag %][% tt_start_tag %] END [% tt_end_tag %]</pre>
-<p>
-Note that this is the same as if PRE_CHOMP and POST_CHOMP were set
-to CHOMP_ALL; the only way to get the CHOMP_COLLAPSE behavior is
-to set PRE_CHOMP or POST_CHOMP accordingly. If PRE_CHOMP or POST_CHOMP
-is already set to CHOMP_COLLAPSE, using '-' will give you CHOMP_COLLAPSE
-behavior, not CHOMP_ALL behavior.
-</p>
-<p>
-Similarly, '+' characters can be used to disable PRE_CHOMP or
-POST_CHOMP (i.e. leave the whitespace/newline intact) options on a
-per-directive basis.
+To remove all whitespace including any number of newlines, use the '~'
+character instead.
</p>
+<pre> [% tt_start_tag %] FOREACH user IN userlist [% tt_end_tag %]
+
+ [% tt_start_tag %]~ user ~[% tt_end_tag %]
+
+ [% tt_start_tag %] END [% tt_end_tag %]</pre>
+<p>
+To collapse all whitespace to a single space, use the '=' character.
+</p>
+<pre> [% tt_start_tag %] FOREACH user IN userlist [% tt_end_tag %]
+
+ [% tt_start_tag %]= user =[% tt_end_tag %]
+
+ [% tt_start_tag %] END [% tt_end_tag %]</pre>
+<p>
+Here the template is processed as if written:
+</p>
+<pre> [% tt_start_tag %] FOREACH user IN userlist [% tt_end_tag %] [% tt_start_tag %] user [% tt_end_tag %] [% tt_start_tag %] END [% tt_end_tag %]</pre>
+<p>
+If you have PRE_CHOMP or POST_CHOMP set as configuration options then
+you can use '+' to disable any chomping options (i.e. leave the
+whitespace intact) on a per-directive basis.
+</p>
<pre> [% tt_start_tag %] FOREACH user = userlist [% tt_end_tag %]
User: [% tt_start_tag %] user +[% tt_end_tag %]
[% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
-With POST_CHOMP enabled, the above example would be parsed as if written:
+With POST_CHOMP set to CHOMP_ONE, the above example would be parsed as
+if written:
</p>
<pre> [% tt_start_tag %] FOREACH user = userlist [% tt_end_tag %]User: [% tt_start_tag %] user [% tt_end_tag %]
[% tt_start_tag %] END [% tt_end_tag %]</pre>
+<p>
+For reference, the PRE_CHOMP and POST_CHOMP configuration options may be set to any of the following:
+</p>
+<pre> Constant Value Tag Modifier
+ ----------------------------------
+ CHOMP_NONE 0 +
+ CHOMP_ONE 1 -
+ CHOMP_COLLAPSE 2 =
+ CHOMP_GREEDY 3 ~</pre>
<li><b>TRIM</b><br>
<p>
@@ -1961,21 +1999,21 @@
[% WRAPPER section
title="AUTHOR"
-%]<p>
-Andy Wardley <abw@andywardley.com>
+Andy Wardley <abw@wardley.org>
</p>
<p>
-[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
+[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.15, released on 30 January 2006.
+Template Toolkit version 2.15, released on 26 May 2006.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
1.49 +17 -16 Template2/docs/src/Manual/Credits.html
Index: Credits.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Manual/Credits.html,v
retrieving revision 1.48
retrieving revision 1.49
diff -u -r1.48 -r1.49
--- Credits.html 2006/01/30 20:03:21 1.48
+++ Credits.html 2006/05/26 13:44:33 1.49
@@ -97,18 +97,19 @@
Chuck Adams, Stephen Adkins, Ivan Adzhubey, Mark Anderson, Bradley
Baetz, Thierry-Michel Barral, Craig Barratt, Stas Bekman, Tony Bowden,
Neil Bowers, Leon Brocard, Lyle Brooks, Dave Cash, Piers Cawley,
-Darren Chamberlain, Eric Cholet, Tosh Cooey, Dave Cross, Chris Dean,
-Francois Desarmenien, Horst Dumcke, Mark Fowler, Michael Fowler, Kenny
-Gatdula, Axel Gerstmair, Dylan William Hardison, Perrin Harkins, Bryce
-Harrington, Dave Hodgkinson, Lubomir Host, Dave Howorth, Harald Joerg,
-Colin Johnson, Vivek Khera, Rafael Kitover, Ivan Kurmanov, Hans von
-Lengerke, Jonas Liljegren, Simon Luff, Andy Maas, Paul Makepeace,
-Gervase Markham, Simon Matthews, Robert McArthur, Craig McLane, Myk
-Melez, Eugene Miretskiy, Tatsuhiko Miyagawa, Bill Moseley, Keith
-G. Murphy, Chris Nandor, Leslie Michael Orchard, Paul Orrock, Steve
-Peters, Briac Pilpré, Yuri Pimenov, Martin Portman, Slaven Rezic, Josh
-Rosenbaum, Christian Schaffner, Mike Schilli, Randal L. Schwartz, Paul
-Sharpe, Ville Skyttä, Barrie Slaymaker, Doug Steinwand, Michael
+Darren Chamberlain, Eric Cholet, Nik Clayton, Tosh Cooey, Dave Cross,
+Chris Dean, Francois Desarmenien, Horst Dumcke, Mark Fowler, Michael
+Fowler, Kenny Gatdula, Axel Gerstmair, Dylan William Hardison, Perrin
+Harkins, Bryce Harrington, Dave Hodgkinson, Lubomir Host, Dave
+Howorth, Harald Joerg, Colin Johnson, Vivek Khera, Rafael Kitover,
+Ivan Kurmanov, Hans von Lengerke, Jonas Liljegren, Simon Luff, Andy
+Maas, Paul Makepeace, Gervase Markham, Sergey Martynoff, Simon
+Matthews, Robert McArthur, Craig McLane, Myk Melez, Eugene Miretskiy,
+Tatsuhiko Miyagawa, Bill Moseley, Keith G. Murphy, Chris Nandor,
+Leslie Michael Orchard, Paul Orrock, Steve Peters, Briac Pilpré, Yuri
+Pimenov, Martin Portman, Slaven Rezic, Jess Robinson, Josh Rosenbaum,
+Christian Schaffner, Mike Schilli, Randal L. Schwartz, Paul Seamons,
+Paul Sharpe, Ville Skyttä, Barrie Slaymaker, Doug Steinwand, Michael
Stevens, Autrijus Tang, Drew Taylor, Swen Thuemmler, Richard Tietjen,
Stathy G. Touloumis, Jim Vaughan, Simon Wilcox, Chris Winters
</p>
@@ -116,21 +117,21 @@
[% WRAPPER section
title="AUTHOR"
-%]<p>
-Andy Wardley <abw@andywardley.com>
+Andy Wardley <abw@wardley.org>
</p>
<p>
-[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
+[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.15, released on 30 January 2006.
+Template Toolkit version 2.15, released on 26 May 2006.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
1.49 +4 -4 Template2/docs/src/Manual/Directives.html
Index: Directives.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Manual/Directives.html,v
retrieving revision 1.48
retrieving revision 1.49
diff -u -r1.48 -r1.49
--- Directives.html 2006/01/30 20:03:21 1.48
+++ Directives.html 2006/05/26 13:44:33 1.49
@@ -2036,21 +2036,21 @@
[% WRAPPER section
title="AUTHOR"
-%]<p>
-Andy Wardley <abw@andywardley.com>
+Andy Wardley <abw@wardley.org>
</p>
<p>
-[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
+[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.15, released on 30 January 2006.
+Template Toolkit version 2.15, released on 26 May 2006.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
1.48 +4 -4 Template2/docs/src/Manual/Filters.html
Index: Filters.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Manual/Filters.html,v
retrieving revision 1.47
retrieving revision 1.48
diff -u -r1.47 -r1.48
--- Filters.html 2006/01/30 20:03:21 1.47
+++ Filters.html 2006/05/26 13:44:33 1.48
@@ -501,21 +501,21 @@
[% WRAPPER section
title="AUTHOR"
-%]<p>
-Andy Wardley <abw@andywardley.com>
+Andy Wardley <abw@wardley.org>
</p>
<p>
-[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
+[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.15, released on 30 January 2006.
+Template Toolkit version 2.15, released on 26 May 2006.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
1.48 +4 -4 Template2/docs/src/Manual/Internals.html
Index: Internals.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Manual/Internals.html,v
retrieving revision 1.47
retrieving revision 1.48
diff -u -r1.47 -r1.48
--- Internals.html 2006/01/30 20:03:21 1.47
+++ Internals.html 2006/05/26 13:44:33 1.48
@@ -535,21 +535,21 @@
[% WRAPPER section
title="AUTHOR"
-%]<p>
-Andy Wardley <abw@andywardley.com>
+Andy Wardley <abw@wardley.org>
</p>
<p>
-[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
+[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.15, released on 30 January 2006.
+Template Toolkit version 2.15, released on 26 May 2006.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
1.48 +4 -4 Template2/docs/src/Manual/Intro.html
Index: Intro.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Manual/Intro.html,v
retrieving revision 1.47
retrieving revision 1.48
diff -u -r1.47 -r1.48
--- Intro.html 2006/01/30 20:03:21 1.47
+++ Intro.html 2006/05/26 13:44:33 1.48
@@ -258,21 +258,21 @@
[% WRAPPER section
title="AUTHOR"
-%]<p>
-Andy Wardley <abw@andywardley.com>
+Andy Wardley <abw@wardley.org>
</p>
<p>
-[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
+[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.15, released on 30 January 2006.
+Template Toolkit version 2.15, released on 26 May 2006.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
1.48 +4 -4 Template2/docs/src/Manual/Plugins.html
Index: Plugins.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Manual/Plugins.html,v
retrieving revision 1.47
retrieving revision 1.48
diff -u -r1.47 -r1.48
--- Plugins.html 2006/01/30 20:03:22 1.47
+++ Plugins.html 2006/05/26 13:44:33 1.48
@@ -365,21 +365,21 @@
[% WRAPPER section
title="AUTHOR"
-%]<p>
-Andy Wardley <abw@andywardley.com>
+Andy Wardley <abw@wardley.org>
</p>
<p>
-[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
+[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.15, released on 30 January 2006.
+Template Toolkit version 2.15, released on 26 May 2006.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
1.48 +4 -4 Template2/docs/src/Manual/Refs.html
Index: Refs.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Manual/Refs.html,v
retrieving revision 1.47
retrieving revision 1.48
diff -u -r1.47 -r1.48
--- Refs.html 2006/01/30 20:03:22 1.47
+++ Refs.html 2006/05/26 13:44:33 1.48
@@ -134,21 +134,21 @@
[% WRAPPER section
title="AUTHOR"
-%]<p>
-Andy Wardley <abw@andywardley.com>
+Andy Wardley <abw@wardley.org>
</p>
<p>
-[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
+[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.15, released on 30 January 2006.
+Template Toolkit version 2.15, released on 26 May 2006.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
1.48 +4 -4 Template2/docs/src/Manual/Syntax.html
Index: Syntax.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Manual/Syntax.html,v
retrieving revision 1.47
retrieving revision 1.48
diff -u -r1.47 -r1.48
--- Syntax.html 2006/01/30 20:03:22 1.47
+++ Syntax.html 2006/05/26 13:44:33 1.48
@@ -276,21 +276,21 @@
[% WRAPPER section
title="AUTHOR"
-%]<p>
-Andy Wardley <abw@andywardley.com>
+Andy Wardley <abw@wardley.org>
</p>
<p>
-[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
+[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.15, released on 30 January 2006.
+Template Toolkit version 2.15, released on 26 May 2006.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
1.15 +156 -39 Template2/docs/src/Manual/VMethods.html
Index: VMethods.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Manual/VMethods.html,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- VMethods.html 2006/01/30 20:03:22 1.14
+++ VMethods.html 2006/05/26 13:44:33 1.15
@@ -81,7 +81,7 @@
<pre> [% tt_start_tag %] name = 'foo, bar & baz' [% tt_end_tag %]
[% tt_start_tag %] name.remove('\W+') [% tt_end_tag %] # foobarbaz</pre>
-<li><b>match(pattern)</b><br>
+<li><b>match(pattern, global)</b><br>
<p>
Performs a regular expression match on the string using the pattern
passed as an argument. If the pattern matches the string then the
@@ -115,6 +115,14 @@
';
matches = name.match(re);
[% tt_end_tag %]</pre>
+<p>
+To perform a global search to match the pattern as many times as it
+appears in the source string, provide a true value for the 'global'
+argument following the pattern.
+</p>
+<pre> [% tt_start_tag %] text = 'bandanna';
+ text.match('an+', 1).join(', ) # an, ann
+ [% tt_end_tag %]</pre>
<li><b>search(pattern)</b><br>
<p>
@@ -161,6 +169,25 @@
</p>
<pre> 1,234,567</pre>
+<li><b>substr(offset, length, replacement)</b><br>
+<p>
+Returns a substring starting at 'offset', for 'length' characters.
+</p>
+<pre> [% tt_start_tag %] str 'foo bar baz wiz waz woz') [% tt_end_tag %]
+ [% tt_start_tag %] str.substr(4, 3) [% tt_end_tag %] # bar</pre>
+<p>
+If 'length' is not specified then it returns everything from the
+'offset' to the end of the string.
+</p>
+<pre> [% tt_start_tag %] str.substr(12) [% tt_end_tag %] # wiz waz woz</pre>
+<p>
+If both 'length' and 'replacement' are specified, then the method
+replaces everything from 'offset' for 'length' characters with
+$replacement. The substring removed from the string is then returned.
+</p>
+<pre> [% tt_start_tag %] str.substr(0, 11, 'FOO') [% tt_end_tag %] # foo bar baz
+ [% tt_start_tag %] str [% tt_end_tag %] # FOO wiz waz woz</pre>
+
<li><b>list</b><br>
<p>
Return the value as a single element list. This can be useful if you
@@ -190,16 +217,103 @@
[% WRAPPER subsection
title = "Hash Virtual Methods"
-%]<ul>
-<li><b>keys, values, each</b><br>
+<li><b>keys</b><br>
+<p>
+Returns a list of keys in the hash. They are not returned in any
+particular order, but the order is the same as for the corresponding
+values method.
+</p>
+<pre> [% tt_start_tag %] FOREACH key IN hash.keys [% tt_end_tag %]
+ * [% tt_start_tag %] key [% tt_end_tag %]
+ [% tt_start_tag %] END [% tt_end_tag %]</pre>
+<p>
+If you want the keys in sorted order, use the list 'sort' method.
+</p>
+<pre> [% tt_start_tag %] FOREACH key IN hash.keys.sort [% tt_end_tag %]
+ * [% tt_start_tag %] key [% tt_end_tag %]
+ [% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
-The regular hash operators returning lists of keys, values or both.
-Note how we use a '$' prefix on the 'key' variable in this example to
-have it interpolated (i.e. replaced with its value) before use.
+Having got the keys in sorted order, you can then use variable
+interpolation to fetch the value. This is shown in the following
+example by the use of '$key' to fetch the item from 'hash' whose
+key is stored in the 'key' variable.
</p>
-<pre> [% tt_start_tag %] FOREACH key = product.keys [% tt_end_tag %]
- [% tt_start_tag %] key [% tt_end_tag %] => [% tt_start_tag %] product.$key [% tt_end_tag %]
+<pre> [% tt_start_tag %] FOREACH key IN hash.keys.sort [% tt_end_tag %]
+ * [% tt_start_tag %] key [% tt_end_tag %] = [% tt_start_tag %] hash.$key [% tt_end_tag %]
[% tt_start_tag %] END [% tt_end_tag %]</pre>
+<p>
+Alternately, you can use the 'pairs' method to get a list of
+key/value pairs in sorted order.
+</p>
+
+<li><b>values</b><br>
+<p>
+Returns a list of the values in the hash. As with the 'keys' method,
+they are not returned in any particular order, although it is the same
+order that the keys are returned in.
+</p>
+<pre> [% tt_start_tag %] hash.values.join(', ') [% tt_end_tag %]</pre>
+
+<li><b>items</b><br>
+<p>
+Returns a list of both the keys and the values expanded into a single list.
+</p>
+<pre> [% tt_start_tag %] hash = {
+ a = 10
+ b = 20
+ };</pre>
+<pre> hash.items.join(', ') # a, 10, b, 20
+ [% tt_end_tag %]</pre>
+
+<li><b>each</b><br>
+<p>
+This method currently returns the same thing as the 'items' method.
+</p>
+<p>
+However, please note that this method will change in the next major
+version of the Template Toolkit (v3) to return the same thing as the
+'pairs' method. This will be done in an effort to make these virtual
+method more consistent with each other and how Perl works.
+</p>
+<p>
+In anticipation of this, we recommend that you stop using 'hash.each'
+and instead use 'hash.items'.
+</p>
+<li><b>pairs </b><br>
+<p>
+This method returns a list of key/value pairs. They are returned in
+sorted order according to the keys.
+</p>
+<pre> [% tt_start_tag %] FOREACH pair IN product.pairs [% tt_end_tag %]
+ * [% tt_start_tag %] pair.key [% tt_end_tag %] is [% tt_start_tag %] pair.value [% tt_end_tag %]
+ [% tt_start_tag %] END [% tt_end_tag %]</pre>
+
+<li><b>list</b><br>
+<p>
+Returns the contents of the hash in list form. An argument can be
+passed to indicate the desired items required in the list: 'keys' to
+return a list of the keys (same as hash.keys), 'values' to return a
+list of the values (same as hash.values), 'each' to return as list
+of key and values (same as hash.each), or 'pairs' to return a list
+of key/value pairs (same as hash.pairs).
+</p>
+<pre> [% tt_start_tag %] keys = hash.list('keys') [% tt_end_tag %]
+ [% tt_start_tag %] values = hash.list('values') [% tt_end_tag %]
+ [% tt_start_tag %] items = hash.list('each') [% tt_end_tag %]
+ [% tt_start_tag %] pairs = hash.list('pairs') [% tt_end_tag %]</pre>
+<p>
+When called without an argument it currently returns the same thing as
+the 'pairs' method. However, please note that this method will change
+in the next major version of the Template Toolkit (v3) to return a
+reference to a list containing the single hash reference (as per the
+scalar list method).
+</p>
+<p>
+In anticipation of this, we recommend that you stop using 'hash.list'
+and instead use 'hash.pairs'.
+</p>
+
<li><b>sort, nsort</b><br>
<p>
Return a list of the keys, sorted alphabetically (sort) or numerically
@@ -253,7 +367,7 @@
<li><b>size</b><br>
<p>
-Returns the number of key => value pairs in the hash.
+Returns the number of key/value pairs in the hash.
</p>
<li><b>item</b><br>
@@ -262,28 +376,6 @@
</p>
<pre> [% tt_start_tag %] hash.item('foo') [% tt_end_tag %] # same as hash.foo</pre>
-<li><b>list</b><br>
-<p>
-Returns the contents of the hash in list form. An argument can be
-passed to indicate the desired items required in the list: 'keys' to
-return a list of the keys (same as hash.keys), 'values' to return a
-list of the values (same as hash.values), or 'each' to return as list
-of (key, value) pairs (same as hash.each).
-</p>
-<p>
-When called without an argument it returns a reference to a list containing
-the contents of the hash.
-</p>
-<pre> [% tt_start_tag %] hash = { pi => 3.14 } [% tt_end_tag %]
- [% tt_start_tag %] hash.list.join [% tt_end_tag %] # pi 3.14</pre>
-<p>
-Please note that this is a new behaviour for version 2.15. Prior to
-this the method returned an insanely complex data structure comprised of
-a reference to a list containing references to hash arrays containing
-'key' and 'value' items representing each corresponding key/value pair
-in the hash. You can see why we changed it.
-</p>
-
</ul>
[%- END %]
[% WRAPPER subsection
@@ -363,10 +455,14 @@
<li><b>unshift(item), push(item)</b><br>
<p>
-Adds an item to the start/end of a list.
+The push() method adds an item or items to the end of list.
</p>
-<pre> [% tt_start_tag %] mylist.unshift('prev item') [% tt_end_tag %]
- [% tt_start_tag %] mylist.push('next item') [% tt_end_tag %]</pre>
+<pre> [% tt_start_tag %] mylist.push(foo) [% tt_end_tag %]
+ [% tt_start_tag %] mylist.push(foo, bar) [% tt_end_tag %]
+
+The unshift() method adds an item or items to the start of a list.</pre>
+<pre> [% tt_start_tag %] mylist.unshift(foo) [% tt_end_tag %]
+ [% tt_start_tag %] mylist.push(foo, bar) [% tt_end_tag %]</pre>
<li><b>shift, pop</b><br>
<p>
@@ -389,6 +485,18 @@
</p>
<pre> [% tt_start_tag %] numbers = mylist.unique.sort [% tt_end_tag %]</pre>
+<li><b>import</b><br>
+<p>
+Appends the contents of one or more other lists to the end of the
+current list.
+</p>
+<pre> [% tt_start_tag %] one = [ 1 2 3 ];
+ two = [ 4 5 6 ];
+ three = [ 7 8 9 ];</pre>
+<pre> one.import(two, three);</pre>
+<pre> one.join(', ); # 1, 2, 3, 4, 5, 6, 7, 8, 9
+ [% tt_end_tag %]</pre>
+
<li><b>merge</b><br>
<p>
Returns a list composed of zero or more other lists:
@@ -453,13 +561,22 @@
<li><b>hash </b><br>
<p>
-Returns a reference to a hash array comprised of the elements
-in the list.
+Returns a reference to a hash array comprised of the elements in the
+list. The even-numbered elements (0, 2, 4, etc) become the keys and
+the odd-numbered elements (1, 3, 5, etc) the values.
</p>
<pre> [% tt_start_tag %] list = ['pi', 3.14, 'e', 2.718] [% tt_end_tag %]
[% tt_start_tag %] hash = list.hash [% tt_end_tag %]
[% tt_start_tag %] hash.pi [% tt_end_tag %] # 3.14
[% tt_start_tag %] hash.e [% tt_end_tag %] # 2.718</pre>
+<p>
+If a numerical argument is provided then the hash returned will have
+keys generated for each item starting at the number specified.
+</p>
+<pre> [% tt_start_tag %] list = ['beer', 'peanuts'] [% tt_end_tag %]
+ [% tt_start_tag %] hash = list.hash(1) [% tt_end_tag %]
+ [% tt_start_tag %] hash.1 [% tt_end_tag %] # beer
+ [% tt_start_tag %] hash.2 [% tt_end_tag %] # peanuts</pre>
</ul>
[%- END %]
@@ -544,21 +661,21 @@
[% WRAPPER section
title="AUTHOR"
-%]<p>
-Andy Wardley <abw@andywardley.com>
+Andy Wardley <abw@wardley.org>
</p>
<p>
-[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
+[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.15, released on 30 January 2006.
+Template Toolkit version 2.15, released on 26 May 2006.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
1.48 +9 -4 Template2/docs/src/Manual/Variables.html
Index: Variables.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Manual/Variables.html,v
retrieving revision 1.47
retrieving revision 1.48
diff -u -r1.47 -r1.48
--- Variables.html 2006/01/30 20:03:22 1.47
+++ Variables.html 2006/05/26 13:44:33 1.48
@@ -194,6 +194,11 @@
[% tt_start_tag %] thing._private [% tt_end_tag %] # no output
[% tt_start_tag %] thing..hidden [% tt_end_tag %] # ERROR: unexpected token (..)</pre>
<p>
+You can disable this feature by setting the $Template::Stash::PRIVATE
+package variable to a false value.
+</p>
+<pre> $Template::Stash::PRIVATE = undef; # now you can thing._private</pre>
+<p>
To access a hash entry using a key stored in another variable, prefix
the key variable with '$' to have it interpolated before use (see
[% ttlink('Variable Interpolation') -%]).
@@ -873,21 +878,21 @@
[% WRAPPER section
title="AUTHOR"
-%]<p>
-Andy Wardley <abw@andywardley.com>
+Andy Wardley <abw@wardley.org>
</p>
<p>
-[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
+[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.15, released on 30 January 2006.
+Template Toolkit version 2.15, released on 26 May 2006.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
1.48 +4 -4 Template2/docs/src/Manual/Views.html
Index: Views.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Manual/Views.html,v
retrieving revision 1.47
retrieving revision 1.48
diff -u -r1.47 -r1.48
--- Views.html 2006/01/30 20:03:22 1.47
+++ Views.html 2006/05/26 13:44:33 1.48
@@ -608,21 +608,21 @@
[% WRAPPER section
title="AUTHOR"
-%]<p>
-Andy Wardley <abw@andywardley.com>
+Andy Wardley <abw@wardley.org>
</p>
<p>
-[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
+[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.15, released on 30 January 2006.
+Template Toolkit version 2.15, released on 26 May 2006.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or