Template Toolkit: Утилиты: ttree

Утилита ttree используется для обработки целых деревьев каталогов с файлами шаблонов. Результаты обработки каждого файла затем сохраняются в соответствующем файле в каталоге назначения. Скрипт сравнивает время модификации исходного и результирующего файлов (если последний существует) и обрабатывает только те файлы, которые были изменены. Другими словами, это эквивалент 'make' для Template Toolkit.

Утилита поддерживает ряд опций, которые используются для установки режимов работы, определения расположения файлов и катологов и установки опций Template Toolkit. Вначале утилита конфигурационный файл .ttreerc в домашнем каталоге (HOME), или альтернативный файл, заданный в переменной окружения TTREERC. Затем он обрабатывает аргументы командной строки, включая дополнительные файлы конфигурации, указанные через опцию '-f' (file).

Файл конфигурации .ttreerc

При первом запуске ttree, утилита предложит создать для вас файл .ttreerc. Он будет создан в вашем домашнем каталоге.

    $ ttree
    Do you want me to create a sample '.ttreerc' file for you?
    (file: /home/abw/.ttreerc)   [y/n]: y
    /home/abw/.ttreerc created.  Please edit accordingly and re-run ttree

Назначение этого файла - установка любых глобальных опций конфигурации, которые будут использоваться каждый раз при запуске ttree. Например, вы можете использовать опции 'ignore' и 'copy', чтобы задать регулярные выражения, определяющие какие файлы будут проигнорированы или вместо обработки парсером шаблонов скопированы. Также можно установить в соответствии с вашими предпочтениями флаги 'verbose' и 'recurse'.

Минимальный файл .ttreerc:

    # эти файлы игнорировать
    ignore = \b(CVS|RCS)\b
    ignore = ^#
    ignore = ~$

    # эти файлы копировать вместо обработки
    copy   = \.(gif|png|jpg|pdf)$

    # обрабатывать файлы во вложенных каталогах
    recurse

    # выводить информацию о ходе работы утилиты
    verbose

В большинстве случаев, может потребоваться создать отдельный файл конфигурации ttree для каждого рабочего проекта. Опция 'cfg' позволяет задать каталог, в котором ttree будет искать дополнительные файлы конфигурации.

    cfg = /home/abw/.ttree

Опция командной строки '-f' используется для указания какой конфигурационный файл будет использоваться. Можно указать как относительный так и абсолютный путь к файлу:

    $ ttree -f /home/abw/web/example/etc/ttree.cfg
    $ ttree -f ./etc/ttree.cfg
    $ ttree -f ../etc/ttree.cfg

Если путь не начинается с '/' или '.' или чего-нибудь напоминающего абсолютный путь MS-DOS (например, 'C:\\etc\\ttree.cfg'), то ttree будет искать файл в каталоге, определенном опцией 'cfg'.

    $ ttree -f test1          # /home/abw/.ttree/test1

Опцию 'cfg' можно использовать только в файле .ttreerc. Все остальные опции можно использовать как в файле .ttreerc, так и в любом другом файле конфигурации. Также их можно указывать в качестве аргументов командной строки.

Имейте в виду, что .ttreerc всегда обрабатывается до любого конфигурационного файла, указанного с помощью опции '-f'. Некоторые опции, такие как 'lib', можно указывать много раз, и все значения будут собраны вместе.

Рассмотрим, например, следующие конфигурационные файлы:

/home/abw/.ttreerc:

    cfg = /home/abw/.ttree
    lib = /usr/local/tt2/templates

/home/abw/.ttree/myconfig:

    lib = /home/abw/web/example/templates/lib

Когда ttree вызывается следующим образом:

    $ ttree -f myconfig

опции 'lib' будет содержать следующие каталоги:

    /usr/local/tt2/templates
    /home/abw/web/example/templates/lib

Любые шаблоны, расположенные внутри каталога /usr/local/tt2/templates будут приоритетней, чем соответствующие в каталоге /home/abw/web/example/templates/lib. Это может как соответствовать вашим потребностям, так и нет. По этой причине, хорошей практикой будет оставить файл .ttreerc насколько возможно простым и использовать различные конфигурационные файлы для каждого проекта ttree.

Опции каталогов

Опция 'src' определяет каталог с шаблонами для обработки. Ее можно указать в качестве аргумента командной строки или внутри конфигурационного файла, как в приведенном ниже примере:

    src = /home/abw/web/example/templates/src

Каждый шаблон в этом каталоге обычно соответсвует одной веб-странице или другому документу.

Опция 'dest' определяет каталог назначения для сгенерированного вывода.

    dest = /home/abw/web/example/html

Опция 'lib' используется для определения одного или более каталогов, содержащих дополнительные библиотечные шаблоны. Эти шаблоны не являются полноценными документами и обычно содержат более мелкие модульные компоненты, такие как шапки, подвалы и меню, которые включаются в шаблоны страниц.

    lib = /home/abw/web/example/templates/lib
    lib = /usr/local/tt2/templates

Опцию 'lib' можно указывать повторно, чтобы добавить дополнительные каталоги к пути поиска.

Список шаблонов можно передать утилите ttree как аргументы командной строки.

    $ ttree foo.html bar.html

Утилита ищет эти шаблоны в каталоге 'src' и обрабатывает их с помощью Template Toolkit, используя дополнительные шаблонные компоненты из каталогов 'lib'. Затем полученный результат записывается в соответствующий файл в каталоге 'dest'.

Если ttree вызывается без явного указания каких-либо шаблонов, то утилита обработает каждый файл в каталоге 'src'. Если установлена опция '-r' (recurse), она дополнительно пойдет вглубь подкаталогов и обработает другие шаблоны, которые в них найдет.

    $ ttree -r

Если шаблон ранее обрабатывался, ttree сравнивает время модификации исходного и результирующего файлов. Если исходный шаблон и ни один из шаблонов, от которых он зависит, не изменялись после последней генерации результирующего файла, то ttree не будет обрабатывать его. Опция -a (all) используется для принудительной обработки всех файлов утилитой ttree независимо от времени модификации.

    $ tree -a

Все шаблоны, явно указанные в командной строке, обрабатываются всегда, проверка времени модификации не производится.

Опции файлов

Опции 'ignore', 'copy' и 'accept' используются для фильтрации имен файлов с помощью регулярных выражений perl. Файлы, которые соответсвуют одной из опций 'ignore' не будут обрабатываться. Оставшиеся файлы, которые соответствуют одному из регулярных выражений опций 'copy', будут скопированы в каталог назначения. Остальные файлы, которые соответствуют любому из условий 'accept', будут обработаны с помощью Template Toolkit. Если параметр 'accept' не указан все файлы будут обработаны, за исключением копируемых ('copy') или пропускаемых ('ignore').

    # эти файлы игнорируем
    ignore = \b(CVS|RCS)\b
    ignore = ^#
    ignore = ~$

    # эти файлы копируем
    copy   = \.(gif|png|jpg|pdf)$

    # обрабатываем только шаблоны .tt2
    accept = \.tt2$

Опция 'suffix' используется для определения соответствий между расширениями файлов шаблонов и результирующих файлов. Следующий пример определяет, что обработанные исходные шаблоны, оканчивающиеся на '.tt2' будут сохранены в файлы с расширением '.html':

    suffix tt2=html

Или через командную строку,

    --suffix tt2=html

Можно определить любое количество соответствий суффиксов (расширений), повторно используя эту опцию.

Зависимости шаблонов

Опции 'depend' и 'depend_file' позволяют указать зависимость определенного шаблона от другого файла или группы файлов. Опция 'depend' используется для простой установки единичной зависимости.

  $ ttree --depend foo=bar,baz

Этот пример командной строки показывает, как использовать опцию '--depend', чтобы установить зависимость файла foo от шаблонов bar и baz. Эту опцию можно использовать в командной строке много раз:

  $ ttree --depend foo=bar,baz --depend crash=bang,wallop

или в конфигурационном файле:

  depend foo=bar,baz
  depend crash=bang,wallop

Путь к файлу слева от '=', указывается относитльно каталогов 'src' или 'lib'. Пути к файлу (файлам) в правой части указываются либо относительно этих каталогов, либо как абсолютные пути.

Например:

  $ ttree --depend foo=bar,/tmp/baz

Для определения зависимости, которая применяется ко всем файлам, используйте '*' слева от '='.

  $ ttree --depend *=header,footer

или в конфигурационном файле:

  depend *=header,footer

Любые шаблоны, которые определены в опциях 'pre_process', 'post_process', 'process' или 'wrapper' будут автоматически добавлены к списку глобальных зависимостей, которые применяются ко всем шаблонам.

Опция 'depend_file' используется для указания файла зависимостей.

    $ ttree --depend_file=/home/abw/web/example/etc/ttree.dep

Ниже приведен пример файла зависимостей:

   # Это комментарий. Он игнорируется.

   index.html: header footer menubar

   header: titlebar hotlinks

   menubar: menuitem

   # объединение нескольких строк с помощью обратного слэша
   another.html: header footer menubar \
   sidebar searchform

Строки, начинающиеся с символа '#', являются комментариями и игнорируются. Также пропускаются пустые строки. Остальные строки должны содержать имя файла, двоеточие и затем список файлов, от которых он зависит, разделенных пробелами или запятыми. Пробелы вокруг двоеточия также допустимы. Строка, завершающаяся символом '\' продолжается на следующую.

Имена файлов, содержащие пробелы, можно заключать в кавычки. Для таких файлов, указанных в правой части (после двоеточия ':') это нужно делать обязательно. Файл до двоеточия можно заключить в кавычки, если имя содержит двоеточие.

Как и в случае командной строки, символ '*' можно использовать как групповой символ, для определения зависимости для всех шаблонов.

    * : config,header

Опции Template Toolkit

ttree также позволяет устанавливать обычно используемые опции Template Toolkit. Например, опции ttree '--pre_chomp' и '--post_chomp' соответствуют опциям 'PRE_CHOMP' and 'POST_CHOMP'.

Для получения сводки доступных опций запустите 'ttree -h'.

Template Toolkit

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

ttree

Оглавление

ОБЗОР

ОПИСАНИЕ

Файл конфигурации .ttreerc

Опции каталогов

Опции файлов

Зависимости шаблонов

Опции Template Toolkit

АВТОРЫ

ВЕРСИЯ

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

СМОТРИ ТАКЖЕ