Template Toolkit предоставляет виртуальные методы для работы со
значениями переменных. Большинство из них аналогичны одноименным
функциям Perl. Этот раздел описывает различные виртуальные методы,
которые можно применять к скалярам, значениям массивов и хэшей.
Виртуальные методы для работы со скалярами
- defined
Возвращает истинное значение если значение определенно.
[% user = get_user(uid) IF uid.defined %]
- length
Возвращает длину строкового представления элемента:
[% IF password.length < 8 %]
Password too short, dumbass!
[% END %]
- repeat(n)
Повторяет строку указанное количество раз.
[% name = 'foo' %]
[% name.repeat(3) %] # foofoofoo
- replace(search, replace)
Выводит строку с заменой всех вхождений первого аргумента
(заданного как регулярное выражение Perl) значением второго
аргумента.
[% name = 'foo, bar & baz' %]
[% name.replace('\W+', '_') %] # foo_bar_baz
- match(pattern)
Метод пытается сопоставить со строкой шаблон, передаваемый
в качестве аргумента. Если шаблон встречается в
строке, метод возвращает ссылку на массив всех строк,
захваченных в скобках внутри шаблона.
[% name = 'Larry Wall' %]
[% matches = name.match('(\w+) (\w+)') %]
[% matches.1 %], [% matches.0 %] # Wall, Larry
Если шаблон не соответствует строке метод возвращает ложное
значение, что предпочтительнее, чем возвращение ссылки на
пустой список, который как Perl так и Template Toolkit воспринимают
как истинное значение. Это позволяет использовать подобные выражения:
[% "We're not worthy!" IF name.match('Larry Wall') %]
[% IF (matches = name.match('(\w+) (\w+)')) %]
pattern matches: [% matches.join(', ') %]
[% ELSE %]
pattern does not match
[% END %]
Любые модификаторы регулярных выражений, такие как
'/s', следует добавлять в регурные выражения
с использованием синтаксиса '(?s)'. Например,
для того чтобы игнорировать "пробельные символы" в регулярном
выражении (модификатор '/x'), используйте:
[% re = '(?x)
(\w+)
[ ]
(\w+)
';
matches = name.match(re);
%]
- search(pattern)
Аналогично функции 'match', но возвращает просто истинное значение, если строка соответствует регулярному выражению, передаваевому в качестве аргумента.
[% name = 'foo bar baz' %]
[% name.search('bar') ? 'bar' : 'no bar' %] # bar
Этот виртуальный метод не рекомендуется (deprecated)
использовать вместо 'match'.
- split(pattern)
Вызывает Perl-функцию split() для разбиения строки на массив
строк.
[% FOREACH dir = mypath.split(':') %]
[% dir %]
[% END %]
- chunk(size)
Разбивает значение переменной на список элементов определенного
размера.
[% ccard_no = "1234567824683579";
ccard_no.chunk(4).join
%]
Вывод:
1234 5678 2468 3579
Если размер указан как отрицательное число
текст будет разбиваться справа налево. Это
позволяет выполнять правильную группировку
при разбиении больших чисел, например:
[% number = 1234567;
number.chunk(-3).join(',')
%]
Вывод:
1,234,567
- list
Преобразует скаляр в ссылку на одноэлементный массив.
Это может быть полезным, если у вас есть переменная, которая
может содержать как одиночное значение, так и массив значений,
а вы хотите работать с ними одинаковым образом. Если метод 'list'
применяется к ссылке на массив ничего не происходит, возвращается
исходная ссылка.
[% thing.list.size %] # thing can be a scalar or a list
- hash
Преобразует скаляр в ссылку на хэш, содержащий одну запись
с ключом 'value', указывающим на исходный скаляр. Как и метод
'list' используется в основном для приведения данных в разных
форматах к единому виду.
- size
Для скаляров всегда возвращает 1. Этот метод предоставляется
для связности с данными, представленными в виде массивов или
хэшей, для которых также определены методы size.
Виртуальные методы для работы с хэшами
- keys, values, each
Обычные операторы для работы с хэшами, возвращающие
список ключей, список значений или список пар ключ-значение.
Обратите внимание на использование префикса '$' перед
переменной 'key' в следующем примере. Это необходимо
для интерполяции переменной (т.е. замены значением)
перед использованием.
[% FOREACH key = product.keys %]
[% key %] => [% product.$key %]
[% END %]
- sort, nsort
x is c,
y is b,
z is a,
Возвращает список ключей, отсортированных по соответствующим
значениям хэша по алфавиту (sort) или по числовым
значениям (nsort).
[% FOREACH n = phones.sort %]
[% phones.$n %] is [% n %],
[% END %]
- import
Метод import можно применить к хэшу, чтобы импортировать в него
содержимое другого хэша.
[% hash1 = {
foo => 'Foo',
bar => 'Bar',
}
hash2 = {
wiz => 'Wiz',
woz => 'Woz',
}
%]
[% hash1.import(hash2) %]
[% hash1.wiz %] # Wiz
Вызов метода import() самого по себе позволяет импортировать
содержимое хэша в текущее пространство имен.
[% user = { id => 'lwall', name => 'Larry Wall' } %]
[% import(user) %]
[% id %]: [% name %] # lwall: Larry Wall
- defined, exists
Возвращает истинное или ложное значение в зависимости от того определен
или существует соответственно элемент хэша, обозначенный ключом, переданным
в качестве аргумента методу.
[% hash.defined('somekey') ? 'yes' : 'no' %]
[% hash.exists('somekey') ? 'yes' : 'no' %]
- size
Возвращает количество пар ключ-значение в хэше.
- item
Возвращает значение хэша по ключу, переданному в качестве аргумента.
[% hash.item('foo') %] # тоже самое, что и hash.foo
- list
Возвращает содержимое хэша в форме массива. Методу можно передать
аргумент указывающий, что необходимо включить в массив: 'keys' -
список ключей (аналог hash.keys), 'values' - список значений
(аналог hash.values), или 'each' - список пар ключ-значение
(аналог hash.each). Если аргумент не указан метод возвращает
список ссылок на хэши, каждый из которых содержит одну пару
ключ => значение из исходного хэша.
Виртуальные методы для работы с массивами
- first, last
Возвращают первый/последний элементы массива. Элемент из массива
не удаляется.
[% results.first %] to [% results.last %]
Если в качестве аругмента передается целое число, методы возвращают
первые 'n' или последние 'n' элементов
соответственно:
The first 5 results are [% results.first(5).join(", ") %].
- size, max
Возвращают размер массива (количество элементов) и наибольшее
значение индекса (size - 1), соответственно.
[% results.size %] search results matched your query
- reverse
Возвращает элементы массива в обратном порядке.
[% FOREACH s = scores.reverse %]
...
[% END %]
- join
Соединяет элементы массива в одну строку и использованием
Perl-функции join.
[% items.join(', ') %]
- grep
Возвращает список элементов массива соответствующих шаблону
регулярного выражения.
[% FOREACH directory.files.grep('\.txt$') %]
...
[% END %]
- sort, nsort
Возвращает элементы отсортированными по алфавиту (sort)
или по числовому значению (nsort).
[% library = books.sort %]
Методу можно передать в качестве аргумента ключ поиска. Если
элементы массива ссылки на хэши, ключ поиска будет использован
для извлечения значения из хэша, которое затем будет использовано
при сравнении. Если элементы - объекты, у которых реализован
метод с таким именем, то этот метод будет вызываться для получения
значения используемого при сравнении.
[% library = books.sort('author') %]
В примере, массив 'books' может содержать ссылки на хэши, у которых
есть ключ 'author', или объекты с методом 'author'.
- unshift(item), push(item)
Добавляет элемент в начало/конец массива.
[% mylist.unshift('prev item') %]
[% mylist.push('next item') %]
- shift, pop
Удаляет первый/последний элементы массива и возвращает его.
[% first = mylist.shift %]
[% last = mylist.pop %]
- unique
Возвращает список уникальных элементов массива в том
же порядке, что и в оригинальном массиве.
[% mylist = [ 1, 2, 3, 2, 3, 4, 1, 4, 3, 4, 5 ] %]
[% numbers = mylist.unique %]
Поскольку существует возможность явно отсортировать массив,
нет необходимости сортировать его до того как уникальные
элементы будут извлечены (в отличие от соответствующей
Unix-утилиты).
[% numbers = mylist.unique.sort %]
- merge
Возвращает массив, составленный из нескольких других массивов:
[% list_one = [ 1 2 3 ];
list_two = [ 4 5 6 ];
list_three = [ 7 8 9 ];
list_four = list_one.merge(list_two, list_three);
%]
Оригинальные массивы остаются без изменений.
- slice(from, to)
Возвращает срез элементов массива между границами,
установленными аргументами. Если второй аргумент 'to'
опущен, то срез делается до последнего элемента массива.
Оригинальный массив остается без изменений.
[% first_three = list.slice(0,2) %]
[% last_three = list.slice(-3, -1) %]
- splice(offset, length, list)
Ведет себя аналогично Perl-функции splice() позволяя выборочно
удалять и/или заменять элементы в массиве. Он удалет 'length'
элементов из массива, начиная с 'offset' и заменяет их элементами
массива 'list'.
[% play_game = [ 'play', 'scrabble' ];
ping_pong = [ 'ping', 'pong' ];
redundant = play_game.splice(1, 1, ping_pong);
redundant.join; # scrabble
play_game.join; # play ping pong
%]
Метод возвращает список вырезанных элементов. Можно
использовать директиву CALL, чтобы подавить вывод, если
вы не собираетесь использовать результат далее (не
сохраняете его в переменной).
[% CALL play_game.splice(1, 1, ping_pong) %]
Кроме передачи ссылки на массив с элементами для замены, можно
передавать элементы этого массива один за другим.
[% CALL list.splice(-1, 0, 'foo', 'bar') %]
Будьте осторожны при передаче одного элемента в качестве
значения для замены. Если это ссылка на массив, то она будет
разрешена и будет использоваться содержимое всего массива.
Если нет - она будет интерпретирована как одиночное значение.
Используйте вокруг одиночного элемента квадратные скобки,
явно определяя массив для замены:
[% # вставить одиночный элемент an_item
CALL list.splice(-1, 0, an_item);
# вставить элементы из another_list
CALL list.splice(-1, 0, another_list);
# вставить ссылку на another_list
CALL list.splice(-1, 0, [ another_list ]);
%]
Автомагическое преобразование скаляра в список при вызове виртуальных методов
В дополнение к скалярным виртуальным методам, перечисленным
ранее, можно применять к скалярам любой виртуальный метод массивов.
Скаляр будет "автомагически" преобразован в одноэлементный массив
и соответствующий виртуальный метод будет вызван.
Одна очевидная польза этого проявляется при вызове функций или
методов, которые возвращают массив элементов вместо предпочтительной
ссылки на массив. В этом случае Template Toolkit автоматически
складывает возвращаемые значения в массив.
В результате вы можете продолжать использовать существующие
модули Perl или код, которые возвращают массивы без необходимости
подстраивать их под Template Toolkit (возвращая ссылки на массивы).
Модуль Class::DBI - это лишь один пример такого чрезвычайно полезного
модуля, который возвращает значения таким способом.
Если функция возвращает один элемент, то Template Toolkit
предполагает, что возвращается одиночный элемент (а не список,
содержащий один элемент) и оставляет его как есть. Например, если
вы выполняете запрос к базе данных, вы можете получить в результате
1 элемент или несколько элементов, которые будут сложены в массив.
Директива FOREACH одинаково успешно примет как массив, так и одиночный
элемент, который она преобразует в массив. Таким образом, можно без
опасений писать директивы подобным образом, где предполагается, что
'something' связано с функцией, которая может возвращать как один так
и множество элементов:
[% FOREACH item = something %]
...
[% END %]
"Автомагическое преобразование" скаляров в одноэлементные массивы
означает, что можно без опасений использовать виртуальные методы
массивов, даже если возвращается только один элемент. Например:
[% something.first %]
[% something.join %]
[% something.reverse.join(', ') %]
Имейте в виду, что это самое низкоприоритетное поведение.
Если, например, возвращаемый одиночный элемент - объект с
методом 'first', то как и ожидается будет вызван этот метод,
а не одноименный виртуальный метод массива.
Определение собственных виртуальных методов
Вы можете определить собственные виртуальные методы для скаляров,
массивов и хэшей. Переменные пакета Template::Stash $SCALAR_OPS,
$LIST_OPS и $HASH_OPS - ссылки на хэши, в которых определенны эти
виртуальные методы. Методы HASH_OPS и LIST_OPS - функции, которые
принимают в качестве первого аргумента ссылку на массив/хэш.
SCALAR_OPS - функции, принимающие в качестве первого аргумента
скаляр. Все остальные аргументы передаются из вызова метода в
шаблоне.
# загружаем Template::Stash чтобы получить доступ к таблицам методов
use Template::Stash;
# определяем метод массивов возвращающий массив из нечетных элементов исходного массива
$Template::Stash::LIST_OPS->{ odd } = sub {
my $list = shift;
return [ grep { $_ % 2 } @$list ];
};
Шаблон:
[% primes = [ 2, 3, 5, 7, 9 ] %]
[% primes.odd.join(', ') %] # 3, 5, 7, 9
|