Template Toolkit: Руководство: Виртуальные методы

Template Toolkit

(русская редакция)

[ Пособия ] [ Руководство ] [ Модули ] [ Библиотеки ] [ Утилиты ] [ Вопросы ] [ Релиз ] [ Perl-ресурсы ] Форум ]
 
Поиск
Template Toolkit | Руководство | Виртуальные методы

Виртуальные методы

[ ◄ Переменные ] [ Конфигурация ► ]
Виртуальные методы.

Оглавление

ОПИСАНИЕ

Индекс ] [ Руководство ] [ Наверх ]

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

АВТОР

Индекс ] [ Руководство ] [ Наверх ]

Энди Уардли (Andy Wardley <abw@andywardley.com>)

http://www.andywardley.com/

ВЕРСИЯ

Индекс ] [ Руководство ] [ Наверх ]

Template Toolkit версия 2.14, дата релиза - 4 октября 2004.

АВТОРСКИЕ ПРАВА

Индекс ] [ Руководство ] [ Наверх ]

  Copyright (C) 1996-2004 Andy Wardley.  All Rights Reserved.
  Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.

Этот модуль является свободно-распространяемым программным обеспечением; вы можете распространять и/или модифицировать его на тех же условиях, что и Perl.