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