3 Template::Tools::ttree - Process entire directory trees of templates
7 ttree [options] [files]
11 The F<ttree> script is used to process entire directory trees containing
12 template files. The resulting output from processing each file is then
13 written to a corresponding file in a destination directory. The script
14 compares the modification times of source and destination files (where
15 they already exist) and processes only those files that have been modified.
16 In other words, it is the equivalent of 'make' for the Template Toolkit.
18 It supports a number of options which can be used to configure
19 behaviour, define locations and set Template Toolkit options. The
20 script first reads the F<.ttreerc> configuration file in the HOME
21 directory, or an alternative file specified in the TTREERC environment
22 variable. Then, it processes any command line arguments, including
23 any additional configuration files specified via the C<-f> (file)
26 =head2 The F<.ttreerc> Configuration File
28 When you run F<ttree> for the first time it will ask you if you want
29 it to create a F<.ttreerc> file for you. This will be created in your
33 Do you want me to create a sample '.ttreerc' file for you?
34 (file: /home/abw/.ttreerc) [y/n]: y
35 /home/abw/.ttreerc created. Please edit accordingly and re-run ttree
37 The purpose of this file is to set any I<global> configuration options
38 that you want applied I<every> time F<ttree> is run. For example, you
39 can use the C<ignore> and C<copy> option to provide regular expressions
40 that specify which files should be ignored and which should be copied
41 rather than being processed as templates. You may also want to set
42 flags like C<verbose> and C<recurse> according to your preference.
44 A minimal F<.ttreerc>:
47 ignore = \b(CVS|RCS)\b
52 copy = \.(gif|png|jpg|pdf)$
54 # recurse into directories
57 # provide info about what's going on
60 In most cases, you'll want to create a different F<ttree> configuration
61 file for each project you're working on. The C<cfg> option allows you
62 to specify a directory where F<ttree> can find further configuration
65 cfg = /home/abw/.ttree
67 The C<-f> command line option can be used to specify which configuration
68 file should be used. You can specify a filename using an absolute or
71 $ ttree -f /home/abw/web/example/etc/ttree.cfg
72 $ ttree -f ./etc/ttree.cfg
73 $ ttree -f ../etc/ttree.cfg
75 If the configuration file does not begin with C</> or C<.> or something
76 that looks like a MS-DOS absolute path (e.g. C<C:\\etc\\ttree.cfg>) then
77 F<ttree> will look for it in the directory specified by the C<cfg> option.
79 $ ttree -f test1 # /home/abw/.ttree/test1
81 The C<cfg> option can only be used in the F<.ttreerc> file. All the
82 other options can be used in the F<.ttreerc> or any other F<ttree>
83 configuration file. They can all also be specified as command line
86 Remember that F<.ttreerc> is always processed I<before> any
87 configuration file specified with the C<-f> option. Certain options
88 like C<lib> can be used any number of times and accumulate their values.
90 For example, consider the following configuration files:
92 F</home/abw/.ttreerc>:
94 cfg = /home/abw/.ttree
95 lib = /usr/local/tt2/templates
97 F</home/abw/.ttree/myconfig>:
99 lib = /home/abw/web/example/templates/lib
101 When F<ttree> is invoked as follows:
105 the C<lib> option will be set to the following directories:
107 /usr/local/tt2/templates
108 /home/abw/web/example/templates/lib
110 Any templates located under F</usr/local/tt2/templates> will be used
111 in preference to those located under
112 F</home/abw/web/example/templates/lib>. This may be what you want,
113 but then again, it might not. For this reason, it is good practice to
114 keep the F<.ttreerc> as simple as possible and use different
115 configuration files for each F<ttree> project.
117 =head2 Directory Options
119 The C<src> option is used to define the directory containing the
120 source templates to be processed. It can be provided as a command
121 line option or in a configuration file as shown here:
123 src = /home/abw/web/example/templates/src
125 Each template in this directory typically corresponds to a single
126 web page or other document.
128 The C<dest> option is used to specify the destination directory for the
131 dest = /home/abw/web/example/html
133 The C<lib> option is used to define one or more directories containing
134 additional library templates. These templates are not documents in
135 their own right and typically comprise of smaller, modular components
136 like headers, footers and menus that are incorporated into pages templates.
138 lib = /home/abw/web/example/templates/lib
139 lib = /usr/local/tt2/templates
141 The C<lib> option can be used repeatedly to add further directories to
144 A list of templates can be passed to F<ttree> as command line arguments.
146 $ ttree foo.html bar.html
148 It looks for these templates in the C<src> directory and processes them
149 through the Template Toolkit, using any additional template components
150 from the C<lib> directories. The generated output is then written to
151 the corresponding file in the C<dest> directory.
153 If F<ttree> is invoked without explicitly specifying any templates
154 to be processed then it will process every file in the C<src> directory.
155 If the C<-r> (recurse) option is set then it will additionally iterate
156 down through sub-directories and process and other template files it finds
161 If a template has been processed previously, F<ttree> will compare the
162 modification times of the source and destination files. If the source
163 template (or one it is dependant on) has not been modified more
164 recently than the generated output file then F<ttree> will not process
165 it. The F<-a> (all) option can be used to force F<ttree> to process
166 all files regardless of modification time.
170 Any templates explicitly named as command line argument are always
171 processed and the modification time checking is bypassed.
175 The C<ignore>, C<copy> and C<accept> options are used to specify Perl
176 regexen to filter file names. Files that match any of the C<ignore>
177 options will not be processed. Remaining files that match any of the
178 C<copy> regexen will be copied to the destination directory. Remaining
179 files that then match any of the C<accept> criteria are then processed
180 via the Template Toolkit. If no C<accept> parameter is specified then
181 all files will be accepted for processing if not already copied or
185 ignore = \b(CVS|RCS)\b
190 copy = \.(gif|png|jpg|pdf)$
192 # accept only .tt2 templates
195 The C<suffix> option is used to define mappings between the file
196 extensions for source templates and the generated output files. The
197 following example specifies that source templates with a C<.tt2>
198 suffix should be output as C<.html> files:
202 Or on the command line,
206 You can provide any number of different suffix mappings by repeating
209 =head2 Template Dependencies
211 The C<depend> and C<depend_file> options allow you to specify
212 how any given template file depends on another file or group of files.
213 The C<depend> option is used to express a single dependency.
215 $ ttree --depend foo=bar,baz
217 This command line example shows the C<--depend> option being used to
218 specify that the F<foo> file is dependant on the F<bar> and F<baz>
219 templates. This option can be used many time on the command line:
221 $ ttree --depend foo=bar,baz --depend crash=bang,wallop
223 or in a configuration file:
226 depend crash=bang,wallop
228 The file appearing on the left of the C<=> is specified relative to
229 the C<src> or C<lib> directories. The file(s) appearing on the right
230 can be specified relative to any of these directories or as absolute
235 $ ttree --depend foo=bar,/tmp/baz
237 To define a dependency that applies to all files, use C<*> on the
240 $ ttree --depend *=header,footer
242 or in a configuration file:
244 depend *=header,footer
246 Any templates that are defined in the C<pre_process>, C<post_process>,
247 C<process> or C<wrapper> options will automatically be added to the
248 list of global dependencies that apply to all templates.
250 The C<depend_file> option can be used to specify a file that contains
251 dependency information.
253 $ ttree --depend_file=/home/abw/web/example/etc/ttree.dep
255 Here is an example of a dependency file:
257 # This is a comment. It is ignored.
259 index.html: header footer menubar
261 header: titlebar hotlinks
265 # spanning multiple lines with the backslash
266 another.html: header footer menubar \
269 Lines beginning with the C<#> character are comments and are ignored.
270 Blank lines are also ignored. All other lines should provide a
271 filename followed by a colon and then a list of dependant files
272 separated by whitespace, commas or both. Whitespace around the colon
273 is also optional. Lines ending in the C<\> character are continued
274 onto the following line.
276 Files that contain spaces can be quoted. That is only necessary
277 for files after the colon (':'). The file before the colon may be
278 quoted if it contains a colon.
280 As with the command line options, the C<*> character can be used
281 as a wildcard to specify a dependency for all templates.
285 =head2 Template Toolkit Options
287 F<ttree> also provides access to the usual range of Template Toolkit
288 options. For example, the C<--pre_chomp> and C<--post_chomp> F<ttree>
289 options correspond to the C<PRE_CHOMP> and C<POST_CHOMP> options.
291 Run C<ttree -h> for a summary of the options available.
295 Andy Wardley E<lt>abw@wardley.orgE<gt>
297 L<http://www.wardley.org>
299 With contributions from Dylan William Hardison (support for
300 dependencies), Bryce Harrington (C<absolute> and C<relative> options),
301 Mark Anderson (C<suffix> and C<debug> options), Harald Joerg and Leon
302 Brocard who gets everywhere, it seems.
306 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
308 This module is free software; you can redistribute it and/or
309 modify it under the same terms as Perl itself.
313 L<Template::Tools::tpage|tpage>