1Template::Tools::ttree(U3s)er Contributed Perl DocumentatTieomnplate::Tools::ttree(3)
2
6 Template::Tools::ttree - Process entire directory trees of templates
7
9 ttree [options] [files]
10
12 The ttree script is used to process entire directory trees containing
13 template files. The resulting output from processing each file is then
14 written to a corresponding file in a destination directory. The script
15 compares the modification times of source and destination files (where
16 they already exist) and processes only those files that have been modi‐
17 fied. In other words, it is the equivalent of 'make' for the Template
18 Toolkit.
19 It supports a number of options which can be used to configure behav‐
21 iour, define locations and set Template Toolkit options. The script
22 first reads the .ttreerc configuration file in the HOME directory, or
23 an alternative file specified in the TTREERC environment variable.
24 Then, it processes any command line arguments, including any additional
25 configuration files specified via the "-f" (file) option.
26 The .ttreerc Configuration File
28 When you run ttree for the first time it will ask you if you want it to
30 create a .ttreerc file for you. This will be created in your home
31 directory.
32 $ ttree
34 Do you want me to create a sample '.ttreerc' file for you?
35 (file: /home/abw/.ttreerc) [y/n]: y
36 /home/abw/.ttreerc created. Please edit accordingly and re-run ttree
37 The purpose of this file is to set any global configuration options
39 that you want applied every time ttree is run. For example, you can
40 use the "ignore" and "copy" option to provide regular expressions that
41 specify which files should be ignored and which should be copied rather
42 than being processed as templates. You may also want to set flags like
43 "verbose" and "recurse" according to your preference.
44 A minimal .ttreerc:
46 # ignore these files
48 ignore = \b(CVS⎪RCS)\b
49 ignore = ^#
50 ignore = ~$
51 # copy these files
53 copy = \.(gif⎪png⎪jpg⎪pdf)$
54 # recurse into directories
56 recurse
57 # provide info about what's going on
59 verbose
60 In most cases, you'll want to create a different ttree configuration
62 file for each project you're working on. The "cfg" option allows you
63 to specify a directory where ttree can find further configuration
64 files.
65 cfg = /home/abw/.ttree
67 The "-f" command line option can be used to specify which configuration
69 file should be used. You can specify a filename using an absolute or
70 relative path:
71 $ ttree -f /home/abw/web/example/etc/ttree.cfg
73 $ ttree -f ./etc/ttree.cfg
74 $ ttree -f ../etc/ttree.cfg
75 If the configuration file does not begin with "/" or "." or something
77 that looks like a MS-DOS absolute path (e.g. "C:\\etc\\ttree.cfg") then
78 ttree will look for it in the directory specified by the "cfg" option.
79 $ ttree -f test1 # /home/abw/.ttree/test1
81 The "cfg" option can only be used in the .ttreerc file. All the other
83 options can be used in the .ttreerc or any other ttree configuration
84 file. They can all also be specified as command line options.
85 Remember that .ttreerc is always processed before any configuration
87 file specified with the "-f" option. Certain options like "lib" can be
88 used any number of times and accumulate their values.
89 For example, consider the following configuration files:
91 /home/abw/.ttreerc:
93 cfg = /home/abw/.ttree
95 lib = /usr/local/tt2/templates
96 /home/abw/.ttree/myconfig:
98 lib = /home/abw/web/example/templates/lib
100 When ttree is invoked as follows:
102 $ ttree -f myconfig
104 the "lib" option will be set to the following directories:
106 /usr/local/tt2/templates
108 /home/abw/web/example/templates/lib
109 Any templates located under /usr/local/tt2/templates will be used in
111 preference to those located under /home/abw/web/example/templates/lib.
112 This may be what you want, but then again, it might not. For this rea‐
113 son, it is good practice to keep the .ttreerc as simple as possible and
114 use different configuration files for each ttree project.
115 Directory Options
117 The "src" option is used to define the directory containing the source
119 templates to be processed. It can be provided as a command line option
120 or in a configuration file as shown here:
121 src = /home/abw/web/example/templates/src
123 Each template in this directory typically corresponds to a single web
125 page or other document.
126 The "dest" option is used to specify the destination directory for the
128 generated output.
129 dest = /home/abw/web/example/html
131 The "lib" option is used to define one or more directories containing
133 additional library templates. These templates are not documents in
134 their own right and typically comprise of smaller, modular components
135 like headers, footers and menus that are incorporated into pages tem‐
136 plates.
137 lib = /home/abw/web/example/templates/lib
139 lib = /usr/local/tt2/templates
140 The "lib" option can be used repeatedly to add further directories to
142 the search path.
143 A list of templates can be passed to ttree as command line arguments.
145 $ ttree foo.html bar.html
147 It looks for these templates in the "src" directory and processes them
149 through the Template Toolkit, using any additional template components
150 from the "lib" directories. The generated output is then written to
151 the corresponding file in the "dest" directory.
152 If ttree is invoked without explicitly specifying any templates to be
154 processed then it will process every file in the "src" directory. If
155 the "-r" (recurse) option is set then it will additionally iterate down
156 through sub-directories and process and other template files it finds
157 therein.
158 $ ttree -r
160 If a template has been processed previously, 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 ttree will not process it.
165 The -a (all) option can be used to force ttree to process all files
166 regardless of modification time.
167 $ tree -a
169 Any templates explicitly named as command line argument are always pro‐
171 cessed and the modification time checking is bypassed.
172 File Options
174 The "ignore", "copy" and "accept" options are used to specify Perl
176 regexen to filter file names. Files that match any of the "ignore"
177 options will not be processed. Remaining files that match any of the
178 "copy" regexen will be copied to the destination directory. Remaining
179 files that then match any of the "accept" criteria are then processed
180 via the Template Toolkit. If no "accept" parameter is specified then
181 all files will be accepted for processing if not already copied or
182 ignored.
183 # ignore these files
185 ignore = \b(CVS⎪RCS)\b
186 ignore = ^#
187 ignore = ~$
188 # copy these files
190 copy = \.(gif⎪png⎪jpg⎪pdf)$
191 # accept only .tt2 templates
193 accept = \.tt2$
194 The "suffix" option is used to define mappings between the file exten‐
196 sions for source templates and the generated output files. The follow‐
197 ing example specifies that source templates with a ".tt2" suffix should
198 be output as ".html" files:
199 suffix tt2=html
201 Or on the command line,
203 --suffix tt2=html
205 You can provide any number of different suffix mappings by repeating
207 this option.
208 Template Dependencies
210 The "depend" and "depend_file" options allow you to specify how any
212 given template file depends on another file or group of files. The
213 "depend" option is used to express a single dependency.
214 $ ttree --depend foo=bar,baz
216 This command line example shows the "--depend" option being used to
218 specify that the foo file is dependant on the bar and baz templates.
219 This option can be used many time on the command line:
220 $ ttree --depend foo=bar,baz --depend crash=bang,wallop
222 or in a configuration file:
224 depend foo=bar,baz
226 depend crash=bang,wallop
227 The file appearing on the left of the "=" is specified relative to the
229 "src" or "lib" directories. The file(s) appearing on the right can be
230 specified relative to any of these directories or as absolute file
231 paths.
232 For example:
234 $ ttree --depend foo=bar,/tmp/baz
236 To define a dependency that applies to all files, use "*" on the left
238 of the "=".
239 $ ttree --depend *=header,footer
241 or in a configuration file:
243 depend *=header,footer
245 Any templates that are defined in the "pre_process", "post_process",
247 "process" or "wrapper" options will automatically be added to the list
248 of global dependencies that apply to all templates.
249 The "depend_file" option can be used to specify a file that contains
251 dependency information.
252 $ ttree --depend_file=/home/abw/web/example/etc/ttree.dep
254 Here is an example of a dependency file:
256 # This is a comment. It is ignored.
258 index.html: header footer menubar
260 header: titlebar hotlinks
262 menubar: menuitem
264 # spanning multiple lines with the backslash
266 another.html: header footer menubar \
267 sidebar searchform
268 Lines beginning with the "#" character are comments and are ignored.
270 Blank lines are also ignored. All other lines should provide a file‐
271 name followed by a colon and then a list of dependant files separated
272 by whitespace, commas or both. Whitespace around the colon is also
273 optional. Lines ending in the "\" character are continued onto the
274 following line.
275 Files that contain spaces can be quoted. That is only necessary for
277 files after the colon (':'). The file before the colon may be quoted if
278 it contains a colon.
279 As with the command line options, the "*" character can be used as a
281 wildcard to specify a dependency for all templates.
282 * : config,header
284 Template Toolkit Options
286 ttree also provides access to the usual range of Template Toolkit
288 options. For example, the "--pre_chomp" and "--post_chomp" ttree
289 options correspond to the "PRE_CHOMP" and "POST_CHOMP" options.
290 Run "ttree -h" for a summary of the options available.
292
294 Andy Wardley <abw@andywardley.com>
295 <http://www.andywardley.com/⎪http://www.andywardley.com/>
297 With contributions from Dylan William Hardison (support for dependen‐
299 cies), Bryce Harrington ("absolute" and "relative" options), Mark
300 Anderson ("suffix" and "debug" options), Harald Joerg and Leon Brocard
301 who gets everywhere, it seems.
302
304 2.68, distributed as part of the Template Toolkit version 2.18,
305 released on 09 February 2007.
306
308 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
309 This module is free software; you can redistribute it and/or modify it
311 under the same terms as Perl itself.
312
314 tpage
315perl v5.8.8 2007-02-09 Template::Tools::ttree(3)