[Templates-cvs] cvs commit: Template2/docsrc/src/Manual VMethods.tt2
cvs@template-toolkit.org
cvs@template-toolkit.org
cvs 06/02/01 18:06:02
Modified: docsrc/src/Manual VMethods.tt2
Log:
* documented changes (and future changes) to hash.list, list.hash
and related methods
Revision Changes Path
1.11 +114 -29 Template2/docsrc/src/Manual/VMethods.tt2
Index: VMethods.tt2
===================================================================
RCS file: /template-toolkit/Template2/docsrc/src/Manual/VMethods.tt2,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- VMethods.tt2 2006/02/01 16:21:08 1.10
+++ VMethods.tt2 2006/02/01 18:06:01 1.11
@@ -181,16 +181,98 @@
=over 4
-=item keys, values, each
+=item keys
-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.
+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.
- [% FOREACH key = product.keys %]
- [% key %] => [% product.$key %]
+ [% FOREACH key IN hash.keys %]
+ * [% key %]
[% END %]
+If you want the keys in sorted order, use the list 'sort' method.
+
+ [% FOREACH key IN hash.keys.sort %]
+ * [% key %]
+ [% END %]
+
+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.
+
+ [% FOREACH key IN hash.keys.sort %]
+ * [% key %] = [% hash.$key %]
+ [% END %]
+
+Alternately, you can use the 'pairs' method to get a list of
+key/value pairs in sorted order.
+
+=item values
+
+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.
+
+ [% hash.values.join(', ') %]
+
+=item items
+
+Returns a list of both the keys and the values expanded into a single list.
+
+ [% hash = {
+ a = 10
+ b = 20
+ };
+
+ hash.items.join(', ') # a, 10, b, 20
+ %]
+
+=item each
+
+This method currently returns the same thing as the 'items' method.
+
+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.
+
+In anticipation of this, we recommend that you stop using 'hash.each'
+and instead use 'hash.items'.
+
+=item pairs
+
+This method returns a list of key/value pairs. They are returned in
+sorted order according to the keys.
+
+ [% FOREACH pair IN product.pairs %]
+ * [% pair.key %] is [% pair.value %]
+ [% END %]
+
+=item list
+
+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).
+
+ [% keys = hash.list('keys') %]
+ [% values = hash.list('values') %]
+ [% items = hash.list('each') %]
+ [% pairs = hash.list('pairs') %]
+
+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).
+
+In anticipation of this, we recommend that you stop using 'hash.list'
+and instead use 'hash.pairs'.
+
=item sort, nsort
Return a list of the keys, sorted alphabetically (sort) or numerically
@@ -244,7 +326,7 @@
=item size
-Returns the number of key =E<gt> value pairs in the hash.
+Returns the number of key/value pairs in the hash.
=item item
@@ -252,26 +334,6 @@
[% hash.item('foo') %] # same as hash.foo
-=item list
-
-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).
-
-When called without an argument it returns a reference to a list containing
-the contents of the hash.
-
- [% hash = { pi => 3.14 } %]
- [% hash.list.join %] # pi 3.14
-
-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.
-
=back
=head2 List Virtual Methods
@@ -381,6 +443,20 @@
[% numbers = mylist.unique.sort %]
+=item import
+
+Appends the contents of one or more other lists to the end of the
+current list.
+
+ [% one = [ 1 2 3 ];
+ two = [ 4 5 6 ];
+ three = [ 7 8 9 ];
+
+ one.import(two, three);
+
+ one.join(', ); # 1, 2, 3, 4, 5, 6, 7, 8, 9
+ %]
+
=item merge
Returns a list composed of zero or more other lists:
@@ -448,13 +524,22 @@
=item hash
-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.
[% list = ['pi', 3.14, 'e', 2.718] %]
[% hash = list.hash %]
[% hash.pi %] # 3.14
[% hash.e %] # 2.718
+
+If a numerical argument is provided then the hash returned will have
+keys generated for each item starting at the number specified.
+
+ [% list = ['beer', 'peanuts'] %]
+ [% hash = list.hash(1) %]
+ [% hash.1 %] # beer
+ [% hash.2 %] # peanuts
=back