home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / tsw / TSW_3.4.0.exe / Apache2 / perl / ttree < prev    next >
Encoding:
Text File  |  2004-03-20  |  35.0 KB  |  1,070 lines
  1. #!/usr/bin/perl -w
  2. #========================================================================
  3. #
  4. # ttree
  5. #
  6. # DESCRIPTION
  7. #   Script for processing all directory trees containing templates.
  8. #   Template files are processed and the output directed to the 
  9. #   relvant file in an output tree.  The timestamps of the source and
  10. #   destination files can then be examined for future invocations 
  11. #   to process only those files that have changed.  In other words,
  12. #   it's a lot like 'make' for templates.
  13. #
  14. # AUTHOR
  15. #   Andy Wardley   <abw@wardley.org>
  16. #
  17. # COPYRIGHT
  18. #   Copyright (C) 1996-2003 Andy Wardley.  All Rights Reserved.
  19. #   Copyright (C) 1998-2003 Canon Research Centre Europe Ltd.
  20. #
  21. #   This module is free software; you can redistribute it and/or
  22. #   modify it under the same terms as Perl itself.
  23. #
  24. #------------------------------------------------------------------------
  25. #
  26. # $Id: ttree,v 1.2 2004/03/20 23:00:29 joker Exp $
  27. #
  28. #========================================================================
  29.  
  30. use strict;
  31. use Template;
  32. use AppConfig qw( :expand );
  33. use File::Copy;
  34. use File::Path;
  35. use File::Spec;
  36. use File::Basename;
  37. use Text::ParseWords qw(quotewords);
  38.  
  39. my $NAME     = "ttree";
  40. my $VERSION  = sprintf("%d.%02d", q$Revision: 1.2 $ =~ /(\d+)\.(\d+)/);
  41. my $HOME     = $ENV{ HOME } || '';
  42. my $RCFILE   = $ENV{"\U${NAME}rc"} || "$HOME/.${NAME}rc";
  43. my $TTMODULE = 'Template';
  44.  
  45. #------------------------------------------------------------------------
  46. # configuration options
  47. #------------------------------------------------------------------------
  48.  
  49. # offer create a sample config file if it doesn't exist, unless a '-f'
  50. # has been specified on the command line
  51. unless (-f $RCFILE or grep(/^-f$/, @ARGV) ) {
  52.     print("Do you want me to create a sample '.ttreerc' file for you?\n",
  53.       "(file: $RCFILE)   [y/n]: ");
  54.     my $y = <STDIN>;
  55.     if ($y =~ /^y(es)?/i) {
  56.         write_config($RCFILE);
  57.         exit(0);
  58.     }
  59. }
  60.  
  61. # read configuration file and command line arguments - I need to remember 
  62. # to fix varlist() and varhash() in AppConfig to make this nicer...
  63. my $config   = read_config($RCFILE);
  64. my $dryrun   = $config->nothing;
  65. my $verbose  = $config->verbose || $dryrun;
  66. my $recurse  = $config->recurse;
  67. my $preserve = $config->preserve;
  68. my $all      = $config->all;
  69. my $libdir   = $config->lib;
  70. my $ignore   = $config->ignore;
  71. my $copy     = $config->copy;
  72. my $accept   = $config->accept;
  73. my $absolute = $config->absolute;
  74. my $relative = $config->relative;
  75. my $suffix   = $config->suffix;
  76. my $depends  = $config->depend;
  77. my $depsfile = $config->depend_file;
  78. my $srcdir   = $config->src
  79.     || die "Source directory not set (-s)\n";
  80. my $destdir  = $config->dest
  81.     || die "Destination directory not set (-d)\n";
  82. die "Source and destination directories may not be the same:\n  $srcdir\n"
  83.     if $srcdir eq $destdir;
  84.  
  85. # unshift any perl5lib directories onto front of INC
  86. unshift(@INC, @{ $config->perl5lib });
  87.  
  88. # get all template_* options from the config and fold keys to UPPER CASE
  89. my %ttopts   = $config->varlist('^template_', 1);
  90. my $ttmodule = delete($ttopts{ module });
  91. my $ucttopts = {
  92.     map { my $v = $ttopts{ $_ }; defined $v ? (uc $_, $v) : () }
  93.     keys %ttopts,
  94. };
  95.  
  96. # get all template variable definitions
  97. my $replace = $config->get('define');
  98.  
  99. # now create complete parameter hash for creating template processor
  100. my $ttopts   = {
  101.     %$ucttopts,
  102.     RELATIVE     => $relative,
  103.     ABSOLUTE     => $absolute,
  104.     INCLUDE_PATH => [ $srcdir, @$libdir ],
  105.     OUTPUT_PATH  => $destdir,
  106. };
  107.  
  108. # load custom template module 
  109. if ($ttmodule) {
  110.     my $ttpkg = $ttmodule;
  111.     $ttpkg =~ s[::][/]g;
  112.     $ttpkg .= '.pm';
  113.     require $ttpkg;
  114. }
  115. else {
  116.     $ttmodule = $TTMODULE;
  117. }
  118.  
  119.  
  120. #------------------------------------------------------------------------
  121. # inter-file dependencies
  122. #------------------------------------------------------------------------
  123.  
  124. if ($depsfile or $depends) {
  125.     $depends = dependencies($depsfile, $depends);
  126. } 
  127. else {
  128.     $depends = { };
  129. }
  130.  
  131. my $global_deps = $depends->{'*'} || [ ];
  132.  
  133. # add any PRE_PROCESS, etc., templates as global dependencies
  134. foreach my $ttopt (qw( PRE_PROCESS POST_PROCESS PROCESS WRAPPER )) {
  135.     my $deps = $ucttopts->{ $ttopt } || next;
  136.     my @deps = ref $deps eq 'ARRAY' ? (@$deps) : ($deps);
  137.     next unless @deps;
  138.     push(@$global_deps, @deps);
  139. }
  140.  
  141. # remove any duplicates
  142. $global_deps = { map { ($_ => 1) } @$global_deps };
  143. $global_deps = [ keys %$global_deps ];
  144.  
  145. # update $depends hash or delete it if there are no dependencies
  146. if (@$global_deps) {
  147.     $depends->{'*'} = $global_deps;
  148. }
  149. else {
  150.     delete $depends->{'*'};
  151.     $global_deps = undef;
  152. }
  153. $depends = undef
  154.     unless keys %$depends;
  155.  
  156. my $DEP_DEBUG = $config->depend_debug();
  157.  
  158.  
  159. #------------------------------------------------------------------------
  160. # pre-amble
  161. #------------------------------------------------------------------------
  162.  
  163. if ($verbose) {
  164.     local $" = ', ';
  165.  
  166.  
  167.     print "$NAME $VERSION (Template Toolkit version $Template::VERSION)\n\n";
  168.  
  169.     my $sfx = join(', ', map { "$_ => $suffix->{$_}" } keys %$suffix);
  170.  
  171.     print("      Source: $srcdir\n",
  172.           " Destination: $destdir\n",
  173.           "Include Path: [ @$libdir ]\n",
  174.           "      Ignore: [ @$ignore ]\n",
  175.           "        Copy: [ @$copy ]\n",
  176.           "      Accept: [ @$accept ]\n",
  177.           "      Suffix: [ $sfx ]\n");
  178.     print("      Module: $ttmodule ", $ttmodule->module_version(), "\n")
  179.         unless $ttmodule eq $TTMODULE;
  180.  
  181.     if ($depends && $DEP_DEBUG) {
  182.         print "Dependencies:\n";
  183.         foreach my $key ('*', grep { !/\*/ } keys %$depends) {
  184.             printf("    %-16s %s\n", $key, 
  185.                    join(', ', @{ $depends->{ $key } }));
  186.         }
  187.     }
  188.     print "\n";
  189.     print "NOTE: dry run, doing nothing...\n"
  190.         if $dryrun;
  191. }
  192.  
  193. #------------------------------------------------------------------------
  194. # main processing loop
  195. #------------------------------------------------------------------------
  196.  
  197. my $template = $ttmodule->new($ttopts)
  198.     || die $ttmodule->error();
  199.  
  200. if (@ARGV) {
  201.     # explicitly process files specified on command lines 
  202.     foreach my $file (@ARGV) {
  203.         process_file($file, $srcdir ? "$srcdir/$file" : $file, force => 1);
  204.     }
  205. }
  206. else {
  207.     # implicitly process all file in source directory
  208.     process_tree();
  209. }
  210.  
  211. exit(0);
  212.  
  213.  
  214. #========================================================================
  215. # END 
  216. #========================================================================
  217.  
  218.  
  219. #------------------------------------------------------------------------
  220. # process_tree($dir)
  221. #
  222. # Walks the directory tree starting at $dir or the current directory
  223. # if unspecified, processing files as found.
  224. #------------------------------------------------------------------------
  225.  
  226. sub process_tree {
  227.     my $dir = shift;
  228.     my ($file, $path, $abspath, $check);
  229.     my $target;
  230.     local *DIR;
  231.  
  232.     my $absdir = join('/', $srcdir ? $srcdir : (), $dir ? $dir : ());
  233.     $absdir ||= '.';
  234.  
  235.     opendir(DIR, $absdir) || do { warn "$absdir: $!\n"; return undef; };
  236.  
  237.     FILE: while (defined ($file = readdir(DIR))) {
  238.         next if $file eq '.' || $file eq '..';
  239.         $path = $dir ? "$dir/$file" : $file;
  240.         $abspath = "$absdir/$file";
  241.         
  242.         next unless -e $abspath;
  243.  
  244.         # check against ignore list
  245.         foreach $check (@$ignore) {
  246.             if ($path =~ /$check/) {
  247.                 printf "  - %-32s (ignored, matches /$check/)\n", $path
  248.                     if $verbose;
  249.                 next FILE;
  250.             }
  251.         }
  252.  
  253.         if (-d $abspath) {
  254.             if ($recurse) {
  255.                 my ($uid, $gid, $mode);
  256.                 
  257.                 (undef, undef, $mode, undef, $uid, $gid, undef, undef,
  258.                  undef, undef, undef, undef, undef)  = stat($abspath);
  259.                 
  260.                 # create target directory if required
  261.                 $target = "$destdir/$path";
  262.                 unless (-d $target || $dryrun) {
  263.                     mkdir $target, $mode || do { 
  264.                         warn "mkdir  ($target): $!\n";
  265.                         next;
  266.                     };
  267. # commented out by abw on 2000/12/04 - seems to raise a warning?   
  268. #           chown($uid, $gid, $target) || warn "chown($target): $!\n";
  269.                     printf "  + %-32s (created target directory)\n", $path
  270.                         if $verbose;
  271.                 }
  272.                 # recurse into directory
  273.                 process_tree($path);
  274.             }
  275.             else {
  276.                 printf "  - %-32s (directory, not recursing)\n", $path
  277.                     if $verbose;
  278.             }
  279.         }
  280.         else {
  281.             process_file($path, $abspath);
  282.         }
  283.     }
  284.     closedir(DIR);
  285. }
  286.     
  287.  
  288. #------------------------------------------------------------------------
  289. # process_file()
  290. #
  291. # File filtering and processing sub-routine called by process_tree()
  292. #------------------------------------------------------------------------
  293.  
  294. sub process_file {
  295.     my ($file, $absfile, %options) = @_;
  296.     my ($dest, $destfile, $filename, $check, 
  297.         $srctime, $desttime, $mode, $uid, $gid);
  298.     my ($old_suffix, $new_suffix);
  299.     my $is_dep = 0;
  300.     my $copy_file = 0;
  301.  
  302.     $absfile ||= $file;
  303.     $filename = basename($file);
  304.     $destfile = $file;
  305.     
  306.     # look for any relevant suffix mapping
  307.     if (%$suffix) {
  308.         if ($filename =~ m/\.(.+)$/) {
  309.             $old_suffix = $1;
  310.             if ($new_suffix = $suffix->{ $old_suffix }) {
  311.                 $destfile =~ s/$old_suffix$/$new_suffix/;
  312.             }
  313.         }
  314.     }
  315.     $dest = $destdir ? "$destdir/$destfile" : $destfile;
  316.                    
  317. #    print "proc $file => $dest\n";
  318.  
  319.  
  320.     
  321.     # check against copy list
  322.     foreach $check (@$copy) {
  323.         if ($filename =~ /$check/) {
  324.             $copy_file = 1;
  325.         }
  326.     }
  327.  
  328.     # stat the source file unconditionally, so we can preserve
  329.     # mode and ownership
  330.     (undef, undef, $mode, undef, $uid, $gid, undef, undef, undef, $srctime,
  331.      undef, undef, undef)  = stat($absfile);
  332.     
  333.     # test modification time of existing destination file
  334.     if (! $all && ! $options{ force } && -f $dest) {
  335.         $desttime = ( stat($dest) )[9];
  336.  
  337.         if (defined $depends and not $copy_file) {
  338.             my $deptime  = depend_time($file, $depends);
  339.             if (defined $deptime && ($srctime < $deptime)) {
  340.                 $srctime = $deptime;
  341.                 $is_dep = 1;
  342.             }
  343.         }
  344.     
  345.         if ($desttime >= $srctime) {
  346.             printf "  - %-32s (not modified)\n", $file
  347.                 if $verbose;
  348.             return;
  349.         }
  350.     }
  351.     
  352.     # check against copy list
  353.     if ($copy_file) {
  354.         printf "  > %-32s (copied, matches /$check/)\n", $file
  355.             if $verbose;
  356.  
  357.         unless ($dryrun) {
  358.             copy($absfile, $dest);
  359.  
  360.             if ($preserve) {
  361.                 chown($uid, $gid, $dest) || warn "chown($dest): $!\n";
  362.                 chmod($mode, $dest) || warn "chmod($dest): $!\n";
  363.             }
  364.         }
  365.         return;
  366.     }
  367.  
  368.     # check against acceptance list
  369.     if (@$accept) {
  370.         unless (grep { $filename =~ /$_/ } @$accept) {
  371.             printf "  - %-32s (not accepted)\n", $file
  372.                 if $verbose;
  373.             return;
  374.         }
  375.     }
  376.  
  377.     if ($verbose) {
  378.         printf("  + %-32s", $file);
  379.         print " (changed suffix to $new_suffix)" if $new_suffix;
  380.         print "\n";
  381.     }
  382.  
  383.     # process file
  384.     unless ($dryrun) {
  385.         $template->process($file, $replace, $destfile)
  386.             || print("  ! ", $template->error(), "\n");
  387.  
  388.         if ($preserve) {
  389.             chown($uid, $gid, $dest) || warn "chown($dest): $!\n";
  390.             chmod($mode, $dest) || warn "chmod($dest): $!\n";
  391.         }
  392.     }
  393. }
  394.  
  395.  
  396. #------------------------------------------------------------------------
  397. # dependencies($file, $depends)
  398. # 
  399. # Read the dependencies from $file, if defined, and merge in with 
  400. # those passed in as the hash array $depends, if defined.
  401. #------------------------------------------------------------------------
  402.  
  403. sub dependencies {
  404.     my ($file, $depend) = @_;
  405.     my %depends = ();
  406.  
  407.     if (defined $file) {
  408.         my ($fh, $text, $line);
  409.         open $fh, $file or die "Can't open $file, $!";
  410.         local $/ = undef;
  411.         $text = <$fh>;
  412.         close($fh);
  413.         $text =~ s[\\\n][]mg;
  414.         
  415.         foreach $line (split("\n", $text)) {
  416.             next if $line =~ /^\s*(#|$)/;
  417.             chomp $line;
  418.             my ($file, @files) = quotewords('\s*:\s*', 0, $line);
  419.             $file =~ s/^\s+//;
  420.             @files = grep(defined, quotewords('(,|\s)\s*', 0, @files));
  421.             $depends{$file} = \@files;
  422.         }
  423.     }
  424.  
  425.     if (defined $depend) {
  426.         foreach my $key (keys %$depend) {
  427.             $depends{$key} = [ quotewords(',', 0, $depend->{$key}) ];
  428.         }
  429.     }
  430.  
  431.     return \%depends;
  432. }
  433.  
  434.  
  435.  
  436. #------------------------------------------------------------------------
  437. # depend_time($file, \%depends)
  438. #
  439. # Returns the mtime of the most recent in @files.
  440. #------------------------------------------------------------------------
  441.  
  442. sub depend_time {
  443.     my ($file, $depends) = @_;
  444.     my ($deps, $absfile, $modtime);
  445.     my $maxtime = 0;
  446.     my @pending = ($file);
  447.     my @files;
  448.     my %seen;
  449.  
  450.     # push any global dependencies onto the pending list
  451.     if ($deps = $depends->{'*'}) {
  452.         push(@pending, @$deps);
  453.     }
  454.  
  455.     print "    # checking dependencies for $file...\n"
  456.         if $DEP_DEBUG;
  457.  
  458.     # iterate through the list of pending files
  459.     while (@pending) {
  460.         $file = shift @pending;
  461.         next if $seen{ $file }++;
  462.  
  463.         if (File::Spec->file_name_is_absolute($file) && -f $file) {
  464.             $modtime = (stat($file))[9];
  465.             print "    #   $file [$modtime]\n"
  466.                 if $DEP_DEBUG;
  467.         }
  468.         else {
  469.             $modtime = 0;
  470.             foreach my $dir ($srcdir, @$libdir) {
  471.                 $absfile = File::Spec->catfile($dir, $file);
  472.                 if (-f $absfile) {
  473.                     $modtime = (stat($absfile))[9];
  474.                     print "    #   $absfile [$modtime]\n"
  475.                         if $DEP_DEBUG;
  476.                     last;
  477.                 }
  478.             }
  479.         }
  480.         $maxtime = $modtime
  481.             if $modtime > $maxtime;
  482.  
  483.         if ($deps = $depends->{ $file }) {
  484.             push(@pending, @$deps);
  485.             print "    #     depends on ", join(', ', @$deps), "\n"
  486.                 if $DEP_DEBUG;
  487.         }
  488.     }
  489.  
  490.     return $maxtime;
  491. }
  492.  
  493.  
  494. #------------------------------------------------------------------------
  495. # read_config($file)
  496. #
  497. # Handles reading of config file and/or command line arguments.
  498. #------------------------------------------------------------------------
  499.  
  500. sub read_config {
  501.     my $file = shift;
  502.  
  503.     my $config = AppConfig->new(
  504.         { 
  505.             ERROR  => sub { die(@_, "\ntry `$NAME --help'\n") }
  506.         }, 
  507.         'help|h'      => { ACTION => \&help },
  508.         'src|s=s'     => { EXPAND => EXPAND_ALL },
  509.         'dest|d=s'    => { EXPAND => EXPAND_ALL },
  510.         'lib|l=s@'    => { EXPAND => EXPAND_ALL },
  511.         'cfg|c=s'     => { EXPAND => EXPAND_ALL, DEFAULT => '.' },
  512.         'verbose|v'   => { DEFAULT => 0 },
  513.         'recurse|r'   => { DEFAULT => 0 },
  514.         'nothing|n'   => { DEFAULT => 0 },
  515.         'preserve|p'  => { DEFAULT => 0 },
  516.         'absolute'    => { DEFAULT => 0 },
  517.         'relative'    => { DEFAULT => 0 },
  518.         'all|a'       => { DEFAULT => 0 },
  519.         'define=s%',
  520.         'suffix=s%',
  521.         'ignore=s@',
  522.         'copy=s@',
  523.         'accept=s@',
  524.         'depend=s%',
  525.         'depend_file|depfile=s',
  526.         'depend_debug|depdbg',
  527.         'template_module|module=s',
  528.         'template_anycase|anycase',
  529.         'template_eval_perl|eval_perl',
  530.         'template_load_perl|load_perl',
  531.         'template_interpolate|interpolate',
  532.         'template_pre_chomp|pre_chomp|prechomp',
  533.         'template_post_chomp|post_chomp|postchomp',
  534.         'template_trim|trim',
  535.         'template_pre_process|pre_process|preprocess=s@',
  536.         'template_post_process|post_process|postprocess=s@',
  537.         'template_process|process=s',
  538.         'template_wrapper|wrapper=s',
  539.         'template_recursion|recursion',
  540.         'template_expose_blocks|expose_blocks',
  541.         'template_default|default=s',
  542.         'template_error|error=s',
  543.         'template_debug|debug=s',
  544.         'template_start_tag|start_tag|starttag=s',
  545.         'template_end_tag|end_tag|endtag=s',
  546.         'template_tag_style|tag_style|tagstyle=s',
  547.         'template_compile_ext|compile_ext=s',
  548.         'template_compile_dir|compile_dir=s',
  549.         'template_plugin_base|plugin_base|pluginbase=s@',
  550.         'perl5lib|perllib=s@'
  551.     );
  552.  
  553.     # add the 'file' option now that we have a $config object that we 
  554.     # can reference in a closure
  555.     $config->define(
  556.         'file|f=s@' => { 
  557.             EXPAND => EXPAND_ALL, 
  558.             ACTION => sub { 
  559.                 my ($state, $item, $file) = @_;
  560.                 $file = $state->cfg . "/$file" 
  561.                     unless $file =~ /^[\.\/]|(?:\w:)/;
  562.                 $config->file($file) }  
  563.         }
  564.     );
  565.  
  566.     # process main config file, then command line args
  567.     $config->file($file) if -f $file;
  568.     $config->args();
  569.  
  570.     $config;
  571. }
  572.  
  573.  
  574. #------------------------------------------------------------------------
  575. # write_config($file)
  576. #
  577. # Writes a sample configuration file to the filename specified.
  578. #------------------------------------------------------------------------
  579.  
  580. sub write_config {
  581.     my $file = shift;
  582.  
  583.     open(CONFIG, ">$file") || die "failed to create $file: $!\n";
  584.     print(CONFIG <<END_OF_CONFIG);
  585. #------------------------------------------------------------------------
  586. # sample .ttreerc file created automatically by $NAME version $VERSION
  587. #
  588. # This file originally written to $file
  589. #
  590. # For more information on the contents of this configuration file, see
  591. # 
  592. #     perldoc ttree
  593. #     ttree -h
  594. #
  595. #------------------------------------------------------------------------
  596.  
  597. # The most flexible way to use ttree is to create a separate directory 
  598. # for configuration files and simply use the .ttreerc to tell ttree where
  599. # it is.  
  600. #
  601. #     cfg = /path/to/ttree/config/directory
  602.  
  603. # print summary of what's going on 
  604. verbose 
  605.  
  606. # recurse into any sub-directories and process files
  607. recurse
  608.  
  609. # regexen of things that aren't templates and should be ignored
  610. ignore = \\b(CVS|RCS)\\b
  611. ignore = ^#
  612.  
  613. # ditto for things that should be copied rather than processed.
  614. copy = \\.png\$ 
  615. copy = \\.gif\$ 
  616.  
  617. # by default, everything not ignored or copied is accepted; add 'accept'
  618. # lines if you want to filter further. e.g.
  619. #
  620. #    accept = \\.html\$
  621. #    accept = \\.tt2\$
  622.  
  623. # options to rewrite files suffixes (htm => html, tt2 => html)
  624. #
  625. #    suffix htm=html
  626. #    suffix tt2=html
  627.  
  628. # options to define dependencies between templates
  629. #
  630. #    depend *=header,footer,menu
  631. #    depend index.html=mainpage,sidebar
  632. #    depend menu=menuitem,menubar
  633. # 
  634.  
  635. #------------------------------------------------------------------------
  636. # The following options usually relate to a particular project so 
  637. # you'll probably want to put them in a separate configuration file 
  638. # in the directory specified by the 'cfg' option and then invoke tree 
  639. # using '-f' to tell it which configuration you want to use.
  640. # However, there's nothing to stop you from adding default 'src',
  641. # 'dest' or 'lib' options in the .ttreerc.  The 'src' and 'dest' options
  642. # can be re-defined in another configuration file, but be aware that 'lib' 
  643. # options accumulate so any 'lib' options defined in the .ttreerc will
  644. # be applied every time you run ttree.
  645. #------------------------------------------------------------------------
  646. # # directory containing source page templates
  647. # src = /path/to/your/source/page/templates
  648. #
  649. # # directory where output files should be written
  650. # dest = /path/to/your/html/output/directory
  651. # 
  652. # # additional directories of library templates
  653. # lib = /first/path/to/your/library/templates
  654. # lib = /second/path/to/your/library/templates
  655.  
  656. END_OF_CONFIG
  657.  
  658.     close(CONFIG);
  659.     print "$file created.  Please edit accordingly and re-run $NAME\n"; 
  660. }
  661.  
  662.  
  663. #------------------------------------------------------------------------
  664. # help()
  665. #
  666. # Prints help message and exits.
  667. #------------------------------------------------------------------------
  668.  
  669. sub help {
  670.     print<<END_OF_HELP;
  671. $NAME $VERSION (Template Toolkit version $Template::VERSION)
  672.  
  673. usage: $NAME [options] [files]
  674.  
  675. Options:
  676.    -a      (--all)          Process all files, regardless of modification
  677.    -r      (--recurse)      Recurse into sub-directories
  678.    -p      (--preserve)     Preserve file ownership and permission
  679.    -n      (--nothing)      Do nothing, just print summary (enables -v)
  680.    -v      (--verbose)      Verbose mode
  681.    -h      (--help)         This help
  682.    -s DIR  (--src=DIR)      Source directory
  683.    -d DIR  (--dest=DIR)     Destination directory
  684.    -c DIR  (--cfg=DIR)      Location of configuration files
  685.    -l DIR  (--lib=DIR)      Library directory (INCLUDE_PATH)  (multiple)
  686.    -f FILE (--file=FILE)    Read named configuration file     (multiple)
  687.  
  688. File search specifications (all may appear multiple times):
  689.    --ignore=REGEX           Ignore files matching REGEX
  690.    --copy=REGEX             Copy files matching REGEX
  691.    --accept=REGEX           Process only files matching REGEX 
  692.  
  693. File Dependencies Options:
  694.    --depend foo=bar,baz     Specify that 'foo' depends on 'bar' and 'baz'.
  695.    --depend_file FILE       Read file dependancies from FILE.
  696.    --depend_debug           Enable debugging for dependencies
  697.  
  698.  
  699. File suffix rewriting (may appear multiple times)
  700.    --suffix old=new         Change any '.old' suffix to '.new'
  701.  
  702. Additional options to set Template Toolkit configuration items:
  703.    --define var=value       Define template variable
  704.    --interpolate            Interpolate '\$var' references in text
  705.    --anycase                Accept directive keywords in any case.
  706.    --pre_chomp              Chomp leading whitespace 
  707.    --post_chomp             Chomp trailing whitespace
  708.    --trim                   Trim blank lines around template blocks
  709.    --eval_perl              Evaluate [% PERL %] ... [% END %] code blocks
  710.    --load_perl              Load regular Perl modules via USE directive
  711.    --absolute               Enable the ABSOLUTE option
  712.    --relative               Enable the RELATIVE option
  713.    --pre_process=TEMPLATE   Process TEMPLATE before each main template
  714.    --post_process=TEMPLATE  Process TEMPLATE after each main template
  715.    --process=TEMPLATE       Process TEMPLATE instead of main template
  716.    --wrapper=TEMPLATE       Process TEMPLATE wrapper around main template
  717.    --default=TEMPLATE       Use TEMPLATE as default
  718.    --error=TEMPLATE         Use TEMPLATE to handle errors
  719.    --debug=STRING           Set TT DEBUG option to STRING
  720.    --start_tag=STRING       STRING defines start of directive tag
  721.    --end_tag=STRING         STRING defined end of directive tag
  722.    --tag_style=STYLE        Use pre-defined tag STYLE    
  723.    --plugin_base=PACKAGE    Base PACKAGE for plugins            
  724.    --compile_ext=STRING     File extension for compiled template files
  725.    --compile_dir=DIR        Directory for compiled template files
  726.    --perl5lib=DIR           Specify additional Perl library directories
  727.    --template_module=MODULE Specify alternate Template module
  728.  
  729. See 'perldoc ttree' for further information.  
  730.  
  731. END_OF_HELP
  732.  
  733.     exit(0);
  734. }
  735.  
  736. __END__
  737.  
  738.  
  739. #------------------------------------------------------------------------
  740. # IMPORTANT NOTE
  741. #   This documentation is generated automatically from source
  742. #   templates.  Any changes you make here may be lost.
  743. # 
  744. #   The 'docsrc' documentation source bundle is available for download
  745. #   from http://www.template-toolkit.org/docs.html and contains all
  746. #   the source templates, XML files, scripts, etc., from which the
  747. #   documentation for the Template Toolkit is built.
  748. #------------------------------------------------------------------------
  749.  
  750. =head1 NAME
  751.  
  752. Template::Tools::ttree - Process entire directory trees of templates
  753.  
  754. =head1 SYNOPSIS
  755.  
  756.     ttree [options] [files]
  757.  
  758. =head1 DESCRIPTION
  759.  
  760. The F<ttree> script is used to process entire directory trees containing
  761. template files.  The resulting output from processing each file is then 
  762. written to a corresponding file in a destination directory.  The script
  763. compares the modification times of source and destination files (where
  764. they already exist) and processes only those files that have been modified.
  765. In other words, it is the equivalent of 'make' for the Template Toolkit.
  766.  
  767. It supports a number of options which can be used to configure
  768. behaviour, define locations and set Template Toolkit options.  The
  769. script first reads the F<.ttreerc> configuration file in the HOME
  770. directory, or an alternative file specified in the TTREERC environment
  771. variable.  Then, it processes any command line arguments, including
  772. any additional configuration files specified via the C<-f> (file)
  773. option.
  774.  
  775. =head2 The F<.ttreerc> Configuration File
  776.  
  777. When you run F<ttree> for the first time it will ask you if you want
  778. it to create a F<.ttreerc> file for you.  This will be created in your
  779. home directory.
  780.  
  781.     $ ttree
  782.     Do you want me to create a sample '.ttreerc' file for you?
  783.     (file: /home/abw/.ttreerc)   [y/n]: y
  784.     /home/abw/.ttreerc created.  Please edit accordingly and re-run ttree
  785.  
  786. The purpose of this file is to set any I<global> configuration options
  787. that you want applied I<every> time F<ttree> is run.  For example, you
  788. can use the C<ignore> and C<copy> option to provide regular expressions
  789. that specify which files should be ignored and which should be copied 
  790. rather than being processed as templates.  You may also want to set 
  791. flags like C<verbose> and C<recurse> according to your preference.
  792.  
  793. A minimal F<.ttreerc>:
  794.  
  795.     # ignore these files
  796.     ignore = \b(CVS|RCS)\b
  797.     ignore = ^#
  798.     ignore = ~$
  799.  
  800.     # copy these files
  801.     copy   = \.(gif|png|jpg|pdf)$ 
  802.  
  803.     # recurse into directories
  804.     recurse
  805.  
  806.     # provide info about what's going on
  807.     verbose
  808.  
  809. In most cases, you'll want to create a different F<ttree> configuration 
  810. file for each project you're working on.  The C<cfg> option allows you
  811. to specify a directory where F<ttree> can find further configuration 
  812. files.
  813.  
  814.     cfg = /home/abw/.ttree
  815.  
  816. The C<-f> command line option can be used to specify which configuration
  817. file should be used.  You can specify a filename using an absolute or 
  818. relative path:
  819.  
  820.     $ ttree -f /home/abw/web/example/etc/ttree.cfg
  821.     $ ttree -f ./etc/ttree.cfg
  822.     $ ttree -f ../etc/ttree.cfg
  823.  
  824. If the configuration file does not begin with C</> or C<.> or something
  825. that looks like a MS-DOS absolute path (e.g. C<C:\\etc\\ttree.cfg>) then
  826. F<ttree> will look for it in the directory specified by the C<cfg> option.
  827.  
  828.     $ ttree -f test1          # /home/abw/.ttree/test1
  829.  
  830. The C<cfg> option can only be used in the F<.ttreerc> file.  All the
  831. other options can be used in the F<.ttreerc> or any other F<ttree>
  832. configuration file.  They can all also be specified as command line
  833. options.
  834.  
  835. Remember that F<.ttreerc> is always processed I<before> any
  836. configuration file specified with the C<-f> option.  Certain options
  837. like C<lib> can be used any number of times and accumulate their values.
  838.  
  839. For example, consider the following configuration files:
  840.  
  841. F</home/abw/.ttreerc>:
  842.  
  843.     cfg = /home/abw/.ttree
  844.     lib = /usr/local/tt2/templates
  845.  
  846. F</home/abw/.ttree/myconfig>:
  847.  
  848.     lib = /home/abw/web/example/templates/lib
  849.  
  850. When F<ttree> is invoked as follows:
  851.  
  852.     $ ttree -f myconfig
  853.  
  854. the C<lib> option will be set to the following directories:
  855.  
  856.     /usr/local/tt2/templates
  857.     /home/abw/web/example/templates/lib
  858.  
  859. Any templates located under F</usr/local/tt2/templates> will be used
  860. in preference to those located under
  861. F</home/abw/web/example/templates/lib>.  This may be what you want,
  862. but then again, it might not.  For this reason, it is good practice to
  863. keep the F<.ttreerc> as simple as possible and use different
  864. configuration files for each F<ttree> project.
  865.  
  866. =head2 Directory Options
  867.  
  868. The C<src> option is used to define the directory containing the
  869. source templates to be processed.  It can be provided as a command
  870. line option or in a configuration file as shown here:
  871.  
  872.     src = /home/abw/web/example/templates/src
  873.  
  874. Each template in this directory typically corresponds to a single
  875. web page or other document. 
  876.  
  877. The C<dest> option is used to specify the destination directory for the
  878. generated output.
  879.  
  880.     dest = /home/abw/web/example/html
  881.  
  882. The C<lib> option is used to define one or more directories containing
  883. additional library templates.  These templates are not documents in
  884. their own right and typically comprise of smaller, modular components
  885. like headers, footers and menus that are incorporated into pages templates.
  886.  
  887.     lib = /home/abw/web/example/templates/lib
  888.     lib = /usr/local/tt2/templates
  889.  
  890. The C<lib> option can be used repeatedly to add further directories to
  891. the search path.
  892.  
  893. A list of templates can be passed to F<ttree> as command line arguments.
  894.  
  895.     $ ttree foo.html bar.html
  896.  
  897. It looks for these templates in the C<src> directory and processes them
  898. through the Template Toolkit, using any additional template components
  899. from the C<lib> directories.  The generated output is then written to 
  900. the corresponding file in the C<dest> directory.
  901.  
  902. If F<ttree> is invoked without explicitly specifying any templates
  903. to be processed then it will process every file in the C<src> directory.
  904. If the C<-r> (recurse) option is set then it will additionally iterate
  905. down through sub-directories and process and other template files it finds
  906. therein.
  907.  
  908.     $ ttree -r
  909.  
  910. If a template has been processed previously, F<ttree> will compare the
  911. modification times of the source and destination files.  If the source
  912. template (or one it is dependant on) has not been modified more
  913. recently than the generated output file then F<ttree> will not process
  914. it.  The F<-a> (all) option can be used to force F<ttree> to process
  915. all files regardless of modification time.
  916.  
  917.     $ tree -a
  918.  
  919. Any templates explicitly named as command line argument are always
  920. processed and the modification time checking is bypassed.
  921.  
  922. =head2 File Options
  923.  
  924. The C<ignore>, C<copy> and C<accept> options are used to specify Perl
  925. regexen to filter file names.  Files that match any of the C<ignore>
  926. options will not be processed.  Remaining files that match any of the
  927. C<copy> regexen will be copied to the destination directory.  Remaining
  928. files that then match any of the C<accept> criteria are then processed
  929. via the Template Toolkit.  If no C<accept> parameter is specified then 
  930. all files will be accepted for processing if not already copied or
  931. ignored.
  932.  
  933.     # ignore these files
  934.     ignore = \b(CVS|RCS)\b
  935.     ignore = ^#
  936.     ignore = ~$
  937.  
  938.     # copy these files
  939.     copy   = \.(gif|png|jpg|pdf)$ 
  940.  
  941.     # accept only .tt2 templates
  942.     accept = \.tt2$
  943.  
  944. The C<suffix> option is used to define mappings between the file
  945. extensions for source templates and the generated output files.  The
  946. following example specifies that source templates with a C<.tt2>
  947. suffix should be output as C<.html> files:
  948.  
  949.     suffix tt2=html
  950.  
  951. Or on the command line, 
  952.  
  953.     --suffix tt2=html
  954.  
  955. You can provide any number of different suffix mappings by repeating 
  956. this option.
  957.  
  958. =head2 Template Dependencies
  959.  
  960. The C<depend> and C<depend_file> options allow you to specify
  961. how any given template file depends on another file or group of files. 
  962. The C<depend> option is used to express a single dependency.
  963.  
  964.   $ ttree --depend foo=bar,baz
  965.  
  966. This command line example shows the C<--depend> option being used to
  967. specify that the F<foo> file is dependant on the F<bar> and F<baz>
  968. templates.  This option can be used many time on the command line:
  969.  
  970.   $ ttree --depend foo=bar,baz --depend crash=bang,wallop
  971.  
  972. or in a configuration file:
  973.  
  974.   depend foo=bar,baz
  975.   depend crash=bang,wallop
  976.  
  977. The file appearing on the left of the C<=> is specified relative to
  978. the C<src> or C<lib> directories.  The file(s) appearing on the right
  979. can be specified relative to any of these directories or as absolute
  980. file paths.
  981.  
  982. For example:
  983.  
  984.   $ ttree --depend foo=bar,/tmp/baz
  985.  
  986. To define a dependency that applies to all files, use C<*> on the 
  987. left of the C<=>.
  988.  
  989.   $ ttree --depend *=header,footer
  990.  
  991. or in a configuration file:
  992.  
  993.   depend *=header,footer
  994.  
  995. Any templates that are defined in the C<pre_process>, C<post_process>,
  996. C<process> or C<wrapper> options will automatically be added to the
  997. list of global dependencies that apply to all templates.
  998.  
  999. The C<depend_file> option can be used to specify a file that contains
  1000. dependency information.  
  1001.  
  1002.     $ ttree --depend_file=/home/abw/web/example/etc/ttree.dep
  1003.  
  1004. Here is an example of a dependency file:
  1005.  
  1006.    # This is a comment. It is ignored.
  1007.   
  1008.    index.html: header footer menubar 
  1009.   
  1010.    header: titlebar hotlinks
  1011.   
  1012.    menubar: menuitem
  1013.   
  1014.    # spanning multiple lines with the backslash
  1015.    another.html: header footer menubar \
  1016.    sidebar searchform
  1017.  
  1018. Lines beginning with the C<#> character are comments and are ignored.
  1019. Blank lines are also ignored.  All other lines should provide a
  1020. filename followed by a colon and then a list of dependant files
  1021. separated by whitespace, commas or both.  Whitespace around the colon
  1022. is also optional.  Lines ending in the C<\> character are continued
  1023. onto the following line.
  1024.  
  1025. Files that contain spaces can be quoted. That is only necessary
  1026. for files after the colon (':'). The file before the colon may be
  1027. quoted if it contains a colon. 
  1028.  
  1029. As with the command line options, the C<*> character can be used
  1030. as a wildcard to specify a dependency for all templates.
  1031.  
  1032.     * : config,header
  1033.  
  1034. =head2 Template Toolkit Options
  1035.  
  1036. F<ttree> also provides access to the usual range of Template Toolkit
  1037. options.  For example, the C<--pre_chomp> and C<--post_chomp> F<ttree>
  1038. options correspond to the C<PRE_CHOMP> and C<POST_CHOMP> options.
  1039.  
  1040. Run C<ttree -h> for a summary of the options available.
  1041.  
  1042. =head1 AUTHORS
  1043.  
  1044. Andy Wardley E<lt>abw@andywardley.comE<gt>
  1045.  
  1046. L<http://www.andywardley.com/|http://www.andywardley.com/>
  1047.  
  1048. With contributions from Dylan William Hardison (support for
  1049. dependencies), Bryce Harrington (C<absolute> and C<relative> options),
  1050. Mark Anderson (C<suffix> and C<debug> options), Harald Joerg and Leon
  1051. Brocard who gets everywhere, it seems.
  1052.  
  1053. =head1 VERSION
  1054.  
  1055. 2.69, distributed as part of the
  1056. Template Toolkit version 2.13, released on 30 January 2004.
  1057.  
  1058. =head1 COPYRIGHT
  1059.  
  1060.   Copyright (C) 1996-2004 Andy Wardley.  All Rights Reserved.
  1061.   Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
  1062.  
  1063. This module is free software; you can redistribute it and/or
  1064. modify it under the same terms as Perl itself.
  1065.  
  1066. =head1 SEE ALSO
  1067.  
  1068. L<tpage|Template::Tools::tpage>
  1069.  
  1070.