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 / Directory.pm < prev    next >
Encoding:
Perl POD Document  |  2004-01-30  |  11.5 KB  |  411 lines
  1. #============================================================= -*-Perl-*-
  2. #
  3. # Template::Plugin::Directory
  4. #
  5. # DESCRIPTION
  6. #   Plugin for encapsulating information about a file system directory.
  7. #
  8. # AUTHORS
  9. #   Michael Stevens <michael@etla.org>, with some mutilations from 
  10. #   Andy Wardley <abw@kfs.org>.
  11. #
  12. # COPYRIGHT
  13. #   This module is free software; you can redistribute it and/or
  14. #   modify it under the same terms as Perl itself.
  15. #
  16. # REVISION
  17. #   $Id: Directory.pm,v 2.64 2004/01/13 16:20:38 abw Exp $
  18. #
  19. #============================================================================
  20.  
  21. package Template::Plugin::Directory;
  22.  
  23. require 5.004;
  24.  
  25. use strict;
  26. use Cwd;
  27. use File::Spec;
  28. use Template::Plugin::File;
  29. use vars qw( $VERSION );
  30. use base qw( Template::Plugin::File );
  31.  
  32. $VERSION = sprintf("%d.%02d", q$Revision: 2.64 $ =~ /(\d+)\.(\d+)/);
  33.  
  34.  
  35. #------------------------------------------------------------------------
  36. # new(\%config)
  37. #
  38. # Constructor method.
  39. #------------------------------------------------------------------------
  40.  
  41. sub new {
  42.     my $config = ref($_[-1]) eq 'HASH' ? pop(@_) : { };
  43.     my ($class, $context, $path) = @_;
  44.  
  45.     return $class->throw('no directory specified')
  46.     unless defined $path and length $path;
  47.  
  48.     my $self = $class->SUPER::new($context, $path, $config);
  49.     my ($dir, @files, $name, $item, $abs, $rel, $check);
  50.     $self->{ files } = [ ];
  51.     $self->{ dirs  } = [ ];
  52.     $self->{ list  } = [ ];
  53.     $self->{ _dir  } = { };
  54.  
  55.     # don't read directory if 'nostat' or 'noscan' set
  56.     return $self if $config->{ nostat } || $config->{ noscan };
  57.  
  58.     $self->throw("$path: not a directory")
  59.     unless $self->{ isdir };
  60.  
  61.     $self->scan($config);
  62.  
  63.     return $self;
  64. }
  65.  
  66.  
  67. #------------------------------------------------------------------------
  68. # scan(\%config)
  69. #
  70. # Scan directory for files and sub-directories.
  71. #------------------------------------------------------------------------
  72.  
  73. sub scan {
  74.     my ($self, $config) = @_;
  75.     $config ||= { };
  76.     local *DH;
  77.     my ($dir, @files, $name, $abs, $rel, $item);
  78.     
  79.     # set 'noscan' in config if recurse isn't set, to ensure Directories
  80.     # created don't try to scan deeper
  81.     $config->{ noscan } = 1 unless $config->{ recurse };
  82.  
  83.     $dir = $self->{ abs };
  84.     opendir(DH, $dir) or return $self->throw("$dir: $!");
  85.  
  86.     @files = readdir DH;
  87.     closedir(DH) 
  88.     or return $self->throw("$dir close: $!");
  89.  
  90.     my ($path, $files, $dirs, $list) = @$self{ qw( path files dirs list ) };
  91.     @$files = @$dirs = @$list = ();
  92.  
  93.     foreach $name (sort @files) {
  94.     next if $name =~ /^\./;
  95.     $abs = File::Spec->catfile($dir, $name);
  96.     $rel = File::Spec->catfile($path, $name);
  97.  
  98.     if (-d $abs) {
  99.         $item = Template::Plugin::Directory->new(undef, $rel, $config);
  100.         push(@$dirs, $item);
  101.     }
  102.     else {
  103.         $item = Template::Plugin::File->new(undef, $rel, $config);
  104.         push(@$files, $item);
  105.     }
  106.     push(@$list, $item);
  107.     $self->{ _dir }->{ $name } = $item;
  108.     }
  109.  
  110.     return '';
  111. }
  112.  
  113.  
  114. #------------------------------------------------------------------------
  115. # file($filename)
  116. #
  117. # Fetch a named file from this directory.
  118. #------------------------------------------------------------------------
  119.  
  120. sub file {
  121.     my ($self, $name) = @_;
  122.     return $self->{ _dir }->{ $name };
  123. }
  124.  
  125.  
  126. #------------------------------------------------------------------------
  127. # present($view)
  128. #
  129. # Present self to a Template::View
  130. #------------------------------------------------------------------------
  131.  
  132. sub present {
  133.     my ($self, $view) = @_;
  134.     $view->view_directory($self);
  135. }
  136.  
  137.  
  138. #------------------------------------------------------------------------
  139. # content($view)
  140. # 
  141. # Present directory content to a Template::View.
  142. #------------------------------------------------------------------------
  143.  
  144. sub content {
  145.     my ($self, $view) = @_;
  146.     return $self->{ list } unless $view;
  147.     my $output = '';
  148.     foreach my $file (@{ $self->{ list } }) {
  149.     $output .= $file->present($view);
  150.     }
  151.     return $output;
  152. }
  153.  
  154.  
  155. #------------------------------------------------------------------------
  156. # throw($msg)
  157. #
  158. # Throw a 'Directory' exception.
  159. #------------------------------------------------------------------------
  160.  
  161. sub throw {
  162.     my ($self, $error) = @_;
  163.     die (Template::Exception->new('Directory', $error));
  164. }
  165.  
  166. __END__
  167.  
  168.  
  169. #------------------------------------------------------------------------
  170. # IMPORTANT NOTE
  171. #   This documentation is generated automatically from source
  172. #   templates.  Any changes you make here may be lost.
  173. # 
  174. #   The 'docsrc' documentation source bundle is available for download
  175. #   from http://www.template-toolkit.org/docs.html and contains all
  176. #   the source templates, XML files, scripts, etc., from which the
  177. #   documentation for the Template Toolkit is built.
  178. #------------------------------------------------------------------------
  179.  
  180. =head1 NAME
  181.  
  182. Template::Plugin::Directory - Plugin for generating directory listings
  183.  
  184. =head1 SYNOPSIS
  185.  
  186.     [% USE dir = Directory(dirpath) %]
  187.  
  188.     # files returns list of regular files
  189.     [% FOREACH file = dir.files %]
  190.        [% file.name %] [% file.path %] ...
  191.     [% END %]
  192.  
  193.     # dirs returns list of sub-directories
  194.     [% FOREACH subdir = dir.dirs %]
  195.        [% subdir.name %] [% subdir.path %] ...
  196.     [% END %]
  197.  
  198.     # list returns both interleaved in order
  199.     [% FOREACH item = dir.list %]
  200.        [% IF item.isdir %]
  201.       Directory: [% item.name %]
  202.        [% ELSE 
  203.           File: [% item.name %]
  204.        [% END %]
  205.     [% END %]
  206.  
  207.     # define a VIEW to display dirs/files
  208.     [% VIEW myview %]
  209.        [% BLOCK file %]
  210.        File: [% item.name %]
  211.        [% END %]
  212.  
  213.        [% BLOCK directory %]
  214.        Directory: [% item.name %] 
  215.        [% item.content(myview) | indent -%]
  216.        [% END %]
  217.     [% END %]
  218.  
  219.     # display directory content using view
  220.     [% myview.print(dir) %]
  221.  
  222. =head1 DESCRIPTION
  223.  
  224. This Template Toolkit plugin provides a simple interface to directory
  225. listings.  It is derived from the Template::Plugin::File module and
  226. uses Template::Plugin::File object instances to represent files within
  227. a directory.  Sub-directories within a directory are represented by
  228. further Template::Plugin::Directory instances.
  229.  
  230. The constructor expects a directory name as an argument.
  231.  
  232.     [% USE dir = Directory('/tmp') %]
  233.  
  234. It then provides access to the files and sub-directories contained within 
  235. the directory.
  236.  
  237.     # regular files (not directories)
  238.     [% FOREACH file = dir.files %]
  239.        [% file.name %]
  240.     [% END %]
  241.  
  242.     # directories only
  243.     [% FOREACH file = dir.dirs %]
  244.        [% file.name %]
  245.     [% END %]
  246.  
  247.     # files and/or directories
  248.     [% FOREACH file = dir.list %]
  249.        [% file.name %] ([% file.isdir ? 'directory' : 'file' %])
  250.     [% END %]
  251.  
  252.     [% USE Directory('foo/baz') %]
  253.  
  254. The plugin constructor will throw a 'Directory' error if the specified
  255. path does not exist, is not a directory or fails to stat() (see
  256. L<Template::Plugin::File>).  Otherwise, it will scan the directory and
  257. create lists named 'files' containing files, 'dirs' containing
  258. directories and 'list' containing both files and directories combined.
  259. The 'nostat' option can be set to disable all file/directory checks
  260. and directory scanning.
  261.  
  262. Each file in the directory will be represented by a
  263. Template::Plugin::File object instance, and each directory by another
  264. Template::Plugin::Directory.  If the 'recurse' flag is set, then those
  265. directories will contain further nested entries, and so on.  With the
  266. 'recurse' flag unset, as it is by default, then each is just a place
  267. marker for the directory and does not contain any further content
  268. unless its scan() method is explicitly called.  The 'isdir' flag can
  269. be tested against files and/or directories, returning true if the item
  270. is a directory or false if it is a regular file.
  271.  
  272.     [% FOREACH file = dir.list %]
  273.        [% IF file.isdir %]
  274.           * Directory: [% file.name %]
  275.        [% ELSE %]
  276.           * File: [% file.name %]
  277.        [% END %]
  278.     [% END %]
  279.  
  280. This example shows how you might walk down a directory tree, displaying 
  281. content as you go.  With the recurse flag disabled, as is the default, 
  282. we need to explicitly call the scan() method on each directory, to force
  283. it to lookup files and further sub-directories contained within. 
  284.  
  285.     [% USE dir = Directory(dirpath) %]
  286.     * [% dir.path %]
  287.     [% INCLUDE showdir %]
  288.  
  289.     [% BLOCK showdir -%]
  290.       [% FOREACH file = dir.list -%]
  291.         [% IF file.isdir -%]
  292.         * [% file.name %]
  293.           [% file.scan -%]
  294.       [% INCLUDE showdir dir=file FILTER indent(4) -%]
  295.         [% ELSE -%]
  296.         - [% f.name %]
  297.         [% END -%]
  298.       [% END -%]
  299.      [% END %]
  300.  
  301. This example is adapted (with some re-formatting for clarity) from
  302. a test in F<t/directry.t> which produces the following output:
  303.  
  304.     * test/dir
  305.         - file1
  306.         - file2
  307.         * sub_one
  308.             - bar
  309.             - foo
  310.         * sub_two
  311.             - waz.html
  312.             - wiz.html
  313.         - xyzfile
  314.  
  315. The 'recurse' flag can be set (disabled by default) to cause the
  316. constructor to automatically recurse down into all sub-directories,
  317. creating a new Template::Plugin::Directory object for each one and 
  318. filling it with any further content.  In this case there is no need
  319. to explicitly call the scan() method.
  320.  
  321.     [% USE dir = Directory(dirpath, recurse=1) %]
  322.        ...
  323.  
  324.         [% IF file.isdir -%]
  325.         * [% file.name %]
  326.       [% INCLUDE showdir dir=file FILTER indent(4) -%]
  327.         [% ELSE -%]
  328.            ...
  329.  
  330. From version 2.01, the Template Toolkit provides support for views.
  331. A view can be defined as a VIEW ... END block and should contain 
  332. BLOCK definitions for files ('file') and directories ('directory').
  333.  
  334.     [% VIEW myview %]
  335.     [% BLOCK file %]
  336.        - [% item.name %]
  337.     [% END %]
  338.     
  339.     [% BLOCK directory %]
  340.        * [% item.name %]
  341.          [% item.content(myview) FILTER indent %]
  342.     [% END %]
  343.     [% END %]
  344.  
  345. Then the view print() method can be called, passing the
  346. Directory object as an argument.
  347.  
  348.     [% USE dir = Directory(dirpath, recurse=1) %]
  349.     [% myview.print(dir) %]
  350.  
  351. When a directory is presented to a view, either as [% myview.print(dir) %]
  352. or [% dir.present(view) %], then the 'directory' BLOCK within the 'myview' 
  353. VIEW is processed, with the 'item' variable set to alias the Directory object.
  354.  
  355.     [% BLOCK directory %]
  356.        * [% item.name %]
  357.          [% item.content(myview) FILTER indent %]
  358.     [% END %]
  359.  
  360. The directory name is first printed and the content(view) method is
  361. then called to present each item within the directory to the view.
  362. Further directories will be mapped to the 'directory' block, and files
  363. will be mapped to the 'file' block.
  364.  
  365. With the recurse option disabled, as it is by default, the 'directory'
  366. block should explicitly call a scan() on each directory.
  367.  
  368.     [% VIEW myview %]
  369.     [% BLOCK file %]
  370.        - [% item.name %]
  371.     [% END %]
  372.     
  373.     [% BLOCK directory %]
  374.        * [% item.name %]
  375.      [% item.scan %]
  376.          [% item.content(myview) FILTER indent %]
  377.     [% END %]
  378.     [% END %]
  379.  
  380.     [% USE dir = Directory(dirpath) %]
  381.     [% myview.print(dir) %]
  382.  
  383. =head1 TODO
  384.  
  385. Might be nice to be able to specify accept/ignore options to catch
  386. a subset of files.
  387.  
  388. =head1 AUTHORS
  389.  
  390. Michael Stevens E<lt>michael@etla.orgE<gt> wrote the original Directory plugin
  391. on which this is based.  Andy Wardley E<lt>abw@wardley.orgE<gt> split it into 
  392. separate File and Directory plugins, added some extra code and documentation
  393. for VIEW support, and made a few other minor tweaks.
  394.  
  395. =head1 VERSION
  396.  
  397. 2.64, distributed as part of the
  398. Template Toolkit version 2.13, released on 30 January 2004.
  399.  
  400.  
  401.  
  402. =head1 COPYRIGHT
  403.  
  404. This module is free software; you can redistribute it and/or
  405. modify it under the same terms as Perl itself.
  406.  
  407. =head1 SEE ALSO
  408.  
  409. L<Template::Plugin|Template::Plugin>, L<Template::Plugin::File|Template::Plugin::File>, L<Template::View|Template::View>
  410.  
  411.