Конструктор, который инициализирует и возвращает новый объект Template::Provider. В качестве опционального параметра можно передать ссылку на хеш, содержащий любой из следующих элементов:
- INCLUDE_PATH
INCLUDE_PATH используется для указания одного или нескольких каталогов, в которых расположены файлы шаблонов. Когда запрашивается шаблон, который не определен локально с помощью директивы BLOCK, каждый из каталогов, определенных в INCLUDE_PATH, просматривается в поисках файла-шаблона. Несколько каталогов можно указать с помощью ссылки на массив или в виде одной строки, в которой каталоги разделены символом ':'.
my $provider = Template::Provider->new({
INCLUDE_PATH => '/usr/local/templates',
});
my $provider = Template::Provider->new({
INCLUDE_PATH => '/usr/local/templates:/tmp/my/templates',
});
my $provider = Template::Provider->new({
INCLUDE_PATH => [ '/usr/local/templates',
'/tmp/my/templates' ],
});
В системах Win32, используется небольшой дополнительный трюк - игнорируются разделители ':', за которыми сразу следуют символы '/' или '\'. Это позволяет избежать путаницы при использовании каталогов с такими именами 'C:\Blah Blah'.
При использовании массива для определения каталогов, INCLUDE_PATH может содержать элементы, которые динамически генерируют список каталогов для INCLUDE_PATH. Эти элементы-генераторы можно определить как ссылки на функции или объекты с методом paths().
my $provider = Template::Provider->new({
INCLUDE_PATH => [ '/usr/local/templates',
\&incpath_generator,
My::IncPath::Generator->new( ... ) ],
});
При каждом запросе шаблона и проверке INCLUDE_PATH, будет вызываться функция или метод объекта, которые должны вернуть ссылку на массив с путями к каталогам. При возникновении ошибки функции-генераторы должны вызывать die() с сообщением о причине ошибки. Методы-генераторы в этом случае должны вернуть undef, а причина ошибки должна возвращаться через вызов метода error() объекта.
Например:
sub incpath_generator {
# ...код...
if ($all_is_well) {
return \@list_of_directories;
}
else {
die "cannot generate INCLUDE_PATH...\n";
}
}
или:
package My::IncPath::Generator;
# Template::Base (или Class::Base) предоставляет метод error()
use Template::Base;
use base qw( Template::Base );
sub paths {
my $self = shift;
# ...код...
if ($all_is_well) {
return \@list_of_directories;
}
else {
return $self->error("cannot generate INCLUDE_PATH...\n");
}
}
1;
- DELIMITER
Используется для установки альтернативной последовательности символов, используемой для разделения путей, заданных в INCLUDE_PATH. Значение по умолчанию для DELIMITER - ':'.
# позволим использовать соглашения файловой системы глупого Билли (Silly Billy)
my $provider = Template::Provider->new({
DELIMITER => '; ',
INCLUDE_PATH => 'C:/HERE/NOW; D:/THERE/THEN',
});
# решение получше: установите Linux! :-)
На системах Win32, разделитель по умолчанию используется немного более разумно, разбивая пути только по символам ':', за которыми нет сразу символа '/'. Это означает, что следующий пример будет работать как и запланировано, разделяя INCLUDE_PATH на 2 каталога C:/foo и C:/bar.
# только для Win32
my $provider = Template::Provider->new({
INCLUDE_PATH => 'C:/Foo:C:/Bar'
});
Тем не менее, при использовании Win32 рекомендуется явно переопределить символ DELIMITER на что-нибудь иное (например, ';'), а не полагаться на этот тонкий трюк.
- ABSOLUTE
Флаг ABSOLUTE указывает, можно ли загружать шаблоны с абсолютными путями (например, '/foo/bar'). Опция запрещена по умолчанию и любая попытка загрузить шаблон с таким именем приведет к возбуждению исключения 'file'.
my $provider = Template::Provider->new({
ABSOLUTE => 1,
});
# именно поэтому опция запрещена по умолчанию
[% INSERT /etc/passwd %]
Для Win32 систем регулярное выражение для проверки абсолютных путей немного подправлено, чтобы также определять имена, которые начинаются с буквы устройства и двоеточия, например:
C:/Foo/Bar
- RELATIVE
Флаг RELATIVE указывает, можно ли загружать шаблоны с относительными относительно текущего каталога путями (например, './foo/bar' или '../../some/where/else'). Эта опция также запрещена по умолчанию, и в случае обнаружения таких имен файлов шаблонов, будет возбуждено исключение 'file'.
my $provider = Template::Provider->new({
RELATIVE => 1,
});
[% INCLUDE ../logs/error.log %]
- DEFAULT
С помощью опции DEFAULT можно указать шаблон по умолчанию, который будет использован, если указанный шаблон не будет найден в INCLUDE_PATH.
my $provider = Template::Provider->new({
DEFAULT => 'notfound.html',
});
Если запрашивается несуществующий шаблон через метод Template process() или через директивы INCLUDE, PROCESS или WRAPPER, то вместо него будет обработан шаблон DEFAULT в случае, если он определен. Имейте в виду, что шаблон DEFAULT не используется, когда шаблоны указаны с абсолютными или относительными путями, или если он определен как указатель на входной файл или текстовая строка.
- CACHE_SIZE
Модуль Template::Provider кеширует шаблоны, чтобы избежать повторной компиляции файлов шаблонов или блоков, при их повторном использовании. Опция CACHE_SIZE используется для ограничения числа скомпилированных шаблонов, которые модуль будет кешировать.
По умолчанию, CACHE_SIZE имеет неопределенное значение и все скомпилированные шаблоны кешируются. Если значение опции положительное число, кеш будет ограничен на хранение не более указанного числа скомпилированных шаблонов. Когда загружается и компилируется новый шаблон, а кеш заполнен (т.е. число элементов == CACHE_SIZE), самый давно не использовавшийся шаблон удаляется, чтобы освободить место для нового.
Установка CACHE_SIZE в 0 запрещает кеширование.
my $provider = Template::Provider->new({
CACHE_SIZE => 64, # кешировать только 64 скомпилированных шаблона
});
my $provider = Template::Provider->new({
CACHE_SIZE => 0, # не кешировать скомпилированные шаблоны
});
- COMPILE_EXT
Начиная с версии 2 Template Toolkit предоставляет возможность компилировать шаблоны в код Perl и сохранять их на диск для последующего использования (т.е. постоянный кеш). Опция COMPILE_EXT используется для определения расширения для файлов скомпилированных шаблонов. По умолчанию, опция имеет неопределенное значение и попытки прочитать или записать скомпилированные шаблоны не предпринимаются.
my $provider = Template::Provider->new({
COMPILE_EXT => '.ttc',
});
Если COMPILE_EXT определена (а COMPILE_DIR нет, смотри ниже), то скомпилированные шаблоны с расширением COMPILE_EXT будут записываться в каталог, из которого исходный файл шаблона был загружен.
Компиляция и последующее повторное использование шаблонов происходит автоматически всякий раз, когда установлены опции COMPILE_EXT или COMPILE_DIR. Template Toolkit автоматически загрузит и использует скомпилированные файлы, если найдет их на диске. Если соответствующий исходный файл был изменен после того как он был скомпилирован и сохранен, Template Toolkit загрузит и перекомпилирует исходник и сохранит новую версию на диск.
Эта форма постоянного кеша дает значительную экономию времени и ресурсов, необходимых для перезагрузки шаблона. Скомпилированные шаблоны могут быть перезагружены посредством простого вызова require(), освобождая Perl от разбора и компиляции. Это Правильная Вещь.
- COMPILE_DIR
Опция COMPILE_DIR используется для определения альтернативного корня каталогов, в которых будут сохраняться скомпилированные шаблоны.
my $provider = Template::Provider->new({
COMPILE_DIR => '/tmp/ttc',
});
Опция COMPILE_EXT также может быть использована для явного определения расширения, которое будет добавляться к этим файлам.
my $provider1 = Template::Provider->new({
COMPILE_DIR => '/tmp/ttc',
COMPILE_EXT => '.ttc1',
});
my $provider2 = Template::Provider->new({
COMPILE_DIR => '/tmp/ttc',
COMPILE_EXT => '.ttc2',
});
Когда COMPILE_EXT не определена, файлы скомпилированных шаблонов сохраняются с исходными именами файлов, но в другом дереве каталогов.
Путь каждого каталога из INCLUDE_PATH полностью воспроизводится внутри каталога COMPILE_DIR. Этот пример:
my $provider = Template::Provider->new({
COMPILE_DIR => '/tmp/ttc',
INCLUDE_PATH => '/home/abw/templates:/usr/share/templates',
});
приведет к созданию следующей структуры каталогов:
/tmp/ttc/home/abw/templates/
/tmp/ttc/usr/share/templates/
Скомпилированные шаблоны файлов, загруженные из различных каталогов INCLUDE_PATH, будут сохранены в соответствующих каталогах в COMPILE_DIR.
На платформах Win32 имя файла может начинаться с имени устройства и двоеточия. Например,
C:/My Templates/header
Двоеточие будет молча вырезано из имени файла при добавлении к значению COMPILE_DIR, чтобы предотвратить использование неправильных имен файлов. Двоеточия в элементах COMPILE_DIR останутся без изменений. Например:
# только в Win32
my $provider = Template::Provider->new({
DELIMITER => ';',
COMPILE_DIR => 'C:/TT2/Cache',
INCLUDE_PATH => 'C:/TT2/Templates;D:/My Templates',
});
Это приведет к созданию следующих каталогов кеша:
C:/TT2/Cache/C/TT2/Templates
C:/TT2/Cache/D/My Templates
- TOLERANT
Флаг TOLERANT используется различными модулями-поставщиками Template Toolkit (Template::Provider, Template::Plugins, Template::Filters) для управления их поведением при возникновении ошибок. По умолчанию, о любых ошибках как таковых генерируется отчет, с одновременным запретом доступа к их источнику (шаблон, плагин, фильтр) и возбуждением исключения. Когда флаг TOLERANT установлен в любое истинное значение, ошибки будут без уведомления игнорироваться, а поставщик вместо этого вернет отказ от обслуживания (STATUS_DECLINED). Это позволяет вместо неудачного завершения после запроса поставщику, передать ответственность за предоставление источника следующему поставщику. Если все поставщики отклонят запрос на обслуживание либо по причине возникновения ошибки, либо из-за невозможности его выполнить, возбуждается исключение ' not found'.
- PARSER
Модуль Template::Parser реализует объект парсера для компиляции шаблонов в perl-код, который затем может быть выполнен. Объект этого класса по умолчанию создается автоматически и затем используется объектом Template::Provider, как только шаблон загружен и требует компиляции. Опция PARSER используется для указания ссылки на объект альтернативного парсера.
my $provider = Template::Provider->new({
PARSER => MyOrg::Template::Parser->new({ ... }),
});
- DEBUG
Опцию DEBUG можно использовать, чтобы включить отладочные сообщения модуля Template::Provider, установкой (дополнением) этого флага значением DEBUG_PROVIDER.
use Template::Constants qw( :debug );
my $template = Template->new({
DEBUG => DEBUG_PROVIDER,
});
Возвращает скомпилированный шаблон для указанного имени. Если шаблон не найден возвращается (undef, STATUS_DECLINED). Если при чтении или разборе шаблона происходит ошибка возвращается ($error, STATUS_ERROR), где $error содержит сгенерированное сообщение об ошибке. Если установлен флаг TOLERANT метод вместо ошибки возвращает (undef, STATUS_DECLINED).
Сохраняет скомпилированный шаблон $template в кеше под именем $name. При последующих вызовах fetch($name) будет возвратит этот шаблон вместо файла с диска.
Метод доступа к опции INCLUDE_PATH. Если метод вызывается с параметром, то существующее значение INCLUDE_PATH будет заменено на новое.
Этот метод генерирует копию списка INCLUDE_PATH. Любые элементы списка, являющиеся динамическими генераторомами (например, ссылками на функции или объекты с методом paths()) будут вызваны, и возвращенный ими список каталогов будет включен в результирующий список.
Существует возможность передать генератор, который возвращает самого себя, что приводит к зацикливанию внутри метода. Чтобы обнаружить и предотвратить это, введена переменная пакета '$MAX_DIRS', установленная по умолчанию в 64, которая ограничивает максимально возможное количество путей, которые можно добавить или сгенерировать в результирующий список. Если это число будет превышено, метод немедленно возвращает ошибку с соответствующим сообщением.