Creating a Project Directory - Perl

ttree Configuration File

Now we need to define a configuration file for ttree. Example 2-10 shows an example of a typical etc/ttree.cfg file.

Example 2-10. etc/ttree.cfg

# directories
src = /home/dent/web/src
lib = /home/dent/web/lib
dest = /home/dent/web/html

# copy images and other binary files
copy = \.(png|gif|jpg)$

# ignore CVS, RCS, and Emacs temporary files
ignore = \b(CVS|RCS)\b
ignore = ^#

# misc options
verbose
recurse

Options can appear in any order in the configuration file. In certain cases (such as lib, copy, and ignore), an option can be repeated any number of times.

The first section defines the three important template directories:

# directories
src = /home/dent/web/src
lib = /home/dent/web/lib
dest = /home/dent/web/html

The src option tells ttree where to look for HTML page templates. The lib option (of which there can be many) tells it where the library of additional template compo nents can be found. Finally, the dest option specifies the destination directory for the generated HTML pages.

The next two sections provide regular expressions that ttree uses to identify files that should be copied rather than processed through the Template Toolkit ( copy ), and to identify files that should be ignored altogether ( ignore ):

# copy images and other binary files
copy = \.(png|gif|jpg)$

# ignore CVS, RCS, and Emacs temporary files
ignore = \b(CVS|RCS)\b
ignore = ^#

In this example, we’re setting the options so that any images with png, gif, or jpg file extensions are copied, and any CVS or temporary files left lying around by our favorite text editor are ignored.

The next section sets two ttree flags:

# misc options
verbose
recurse

The verbose flag causes ttree to print additional information to STDERR about what it’s doing, while it’s doing it. The recurse flag tells it to recurse down into any subdirectories under the src directory.

Running ttree for the First Time

When you run ttree for the first time, it will display the following prompt, which asks if you’d like it to create a default .ttreerc file:

Do you want me to create a sample '.ttreerc' file for you? (file: /home/dent/.ttreerc) [y/n]:

Answer y to have it create the file in your home directory.

This file is used to provide a default configuration for ttree. If you’ve got only one web site to maintain, you can copy the contents of the etc/ttree.cfg file into it and run ttree without any command-line options:

$ ttree

If you’ve got more than one site to maintain, you’ll probably want to keep separate configuration files for each. In that case, you can use the -f command-line option to provide the name of the configuration file when you invoke ttree:

$ ttree -f /home/dent/web/etc/ttree.cfg

Using a Build Script

Rather than providing a command-line configuration option for ttree each time you use it, you may prefer to write a simple build script that does it for you (as in Example 2-11).

Example 2-11. bin/build

ttree -f /home/dent/web/etc/ttree.cfg $@

The $@ at the end of the line passes any command-line arguments on to the ttree program, in addition to the -f option that is provided explicitly.

ttree Confguration Directory

Another alternative is to set the cfg option in the .ttreerc file to denote a default directory for ttree configuration files. You could set this to point to the project directory:

cfg = /home/dent/web/etc

and then invoke ttree with the short name of the configuration file:

$ tpage -f ttree.cfg

If you have many different web sites to maintain, another option is to create one general directory for ttree configuration files and use symbolic links from this directory to the project-specific files. The .ttree directory in your home directory is a common choice. In the .ttreerc file, we specify it like so:

cfg = /home/dent/.ttree

Then we prepare the directory, creating a symbolic link to our project-specific configuration file. We give it a memorable name (e.g., dentweb ) to distinguish it from the various other ttree.cfg files that we may create links to from this directory:

$ cd /home/dent
$ mkdir .ttree
$ cd .ttree
$ ln -s /home/dent/web/etc/ttree.cfg dentweb

With these changes in place, ttree can then be invoked using the -f option to specify the dentweb configuration file:

$ tpage -f dentweb

The settings in the .ttreerc file and the magic of symbolic links result in ttree ending up with the right configuration file without us having to specify the full path to it every time. The other benefit of this approach is that ttree can be invoked from any directory and the correct configuration file will still be located.

Calling ttree Through the Build Script

From now on we’ll assume that the bin/build script invokes ttree with the appropri ate option to locate the configuration file. For the sake of clarity, we’ll use it in the examples that follow whenever we want to build the site content, rather than calling ttree directly. Any other commands that you want performed when the site is built (e.g., copying files, restarting the web server or database) can also be added here.

As we saw in Example 2-11, any command-line options that we provide to the script are forwarded to ttree. One particularly useful option is
-h , which provides a helpful summary of all the different ttree options:

$ bin/build - h
ttree 2.63 (Template Toolkit version 2.10)

usage: ttree [options] [files]

Options:
-a      (--all)       Process all files, regardless of modification
-r      (--recurse)   Recurse into sub-directories
-p      (--preserve)  Preserve file ownership and permission
-n      (--nothing)   Do nothing, just print summary (enables -v)
-v      (--verbose)   Verbose mode
-h      (--help)      This help
-dbg    (--debug)     Debug mode
-s DIR  (--src=DIR)   Source directory
-d DIR  (--dest=DIR)  Destination directory
-c DIR  (--cfg=DIR)   Location of configuration files
-l DIR  (--lib=DIR)   Library directory (INCLUDE_PATH) (multiple)
-f FILE (--file=FILE) Read named configuration file (multiple)

File search specifications (all may appear multiple times):
--ignore=REGEX   Ignore files matching REGEX
--copy=REGEX     Copy files matching REGEX
--accept=REGEX   Process only files matching REGEX

Additional options to set Template Toolkit configuration items:
--define var=value      Define template variable
--interpolate           Interpolate '$var' references in text
--anycase               Accept directive keywords in any case.
--pre_chomp             Chomp leading whitespace
--post_chomp            Chomp trailing whitespace
--trim                  Trim blank lines around template blocks
--eval_perl             Evaluate [% PERL %] ... [% END %] code blocks
--load_perl             Load regular Perl modules via USE directive
--pre_process=TEMPLATE  Process TEMPLATE before each main template
--post_process=TEMPLATE Process TEMPLATE after each main template
--process=TEMPLATE      Process TEMPLATE instead of main template
--wrapper=TEMPLATE      Process TEMPLATE wrapper around main template
--default=TEMPLATE      Use TEMPLATE as default
--error=TEMPLATE        Use TEMPLATE to handle errors
--start_tag=STRING      STRING defines start of directive tag
--end_tag=STRING        STRING defined end of directive tag
--tag_style=STYLE       Use pre-defined tag STYLE
--plugin_base=PACKAGE   Base PACKAGE for plugins
--compile_ext=STRING    File extension for compiled template files
--compile_dir=DIR       Directory for compiled template files
--perl5lib=DIR          Specify additional Perl library directories