SYNOPSIS
Top[% USE dir = Directory(dirpath) %]
# files returns list of regular files
[% FOREACH file = dir.files %]
   [% file.name %] [% file.path %] ...
[% END %]
# dirs returns list of sub-directories
[% FOREACH subdir = dir.dirs %]
   [% subdir.name %] [% subdir.path %] ...
[% END %]
# list returns both interleaved in order
[% FOREACH item = dir.list %]
   [% IF item.isdir %]
      Directory: [% item.name %]
   [% ELSE 
      File: [% item.name %]
   [% END %]
[% END %]
# define a VIEW to display dirs/files
[% VIEW myview %]
   [% BLOCK file %]
   File: [% item.name %]
   [% END %]
   [% BLOCK directory %]
   Directory: [% item.name %] 
   [% item.content(myview) | indent -%]
   [% END %]
[% END %]
# display directory content using view
[% myview.print(dir) %]
              DESCRIPTION
Top
                      This Template Toolkit plugin provides a simple interface to directory
                      listings. It is derived from the Template::Plugin::File
                      module and uses Template::Plugin::File object instances to represent files
                      within a directory. Sub-directories within a directory are represented by
                      further Template::Plugin::Directory instances.
                    
The constructor expects a directory name as an argument.
[% USE dir = Directory('/tmp') %]
                    It then provides access to the files and sub-directories contained within the directory.
# regular files (not directories) [% FOREACH file IN dir.files %] [% file.name %] [% END %]
# directories only [% FOREACH file IN dir.dirs %] [% file.name %] [% END %]
# files and/or directories [% FOREACH file IN dir.list %] [% file.name %] ([% file.isdir ? 'directory' : 'file' %]) [% END %]
                      The plugin constructor will throw a Directory error if the
                      specified path does not exist, is not a directory or fails to
                      stat() (see Template::Plugin::File). Otherwise, it will scan the directory
                      and create lists named 'files' containing files,
                      'dirs' containing directories and 'list'
                      containing both files and directories combined. The nostat
                      option can be set to disable all file/directory checks and directory
                      scanning.
                    
                      Each file in the directory will be represented by a Template::Plugin::File
                      object instance, and each directory by another
                      Template::Plugin::Directory. If the recurse
                      flag is set, then those directories will contain further nested entries,
                      and so on. With the recurse flag unset, as it is by default,
                      then each is just a place marker for the directory and does not contain
                      any further content unless its scan() method is explicitly
                      called. The isdir flag can be tested against files and/or
                      directories, returning true if the item is a directory or false if it is
                      a regular file.
                    
[% FOREACH file = dir.list %]
   [% IF file.isdir %]
      * Directory: [% file.name %]
   [% ELSE %]
      * File: [% file.name %]
   [% END %]
[% END %]
                    
                      This example shows how you might walk down a directory tree, displaying
                      content as you go. With the recurse flag disabled, as is the default, we
                      need to explicitly call the scan() method on each directory,
                      to force it to lookup files and further sub-directories contained within.
                    
[% USE dir = Directory(dirpath) %]
* [% dir.path %]
[% INCLUDE showdir %]
[% BLOCK showdir -%]
  [% FOREACH file = dir.list -%]
    [% IF file.isdir -%]
    * [% file.name %]
      [% file.scan -%]
      [% INCLUDE showdir dir=file FILTER indent(4) -%]
    [% ELSE -%]
    - [% f.name %]
    [% END -%]
  [% END -%]
 [% END %]
                    This example is adapted (with some re-formatting for clarity) from a test in t/directry.t which produces the following output:
* test/dir
    - file1
    - file2
    * sub_one
        - bar
        - foo
    * sub_two
        - waz.html
        - wiz.html
    - xyzfile
                    
                      The recurse flag can be set (disabled by default) to cause
                      the constructor to automatically recurse down into all sub-directories,
                      creating a new Template::Plugin::Directory object for each
                      one and filling it with any further content. In this case there is no
                      need to explicitly call the scan() method.
                    
[% USE dir = Directory(dirpath, recurse=1) %]
   ...
    [% IF file.isdir -%]
    * [% file.name %]
      [% INCLUDE showdir dir=file FILTER indent(4) -%]
    [% ELSE -%]
       ...
                    
                      The directory plugin also provides support for views. A view can be
                      defined as a VIEW ... END block and should contain
                      BLOCK definitions for files ('file') and
                      directories ('directory').
                    
[% VIEW myview %]
[% BLOCK file %]
   - [% item.name %]
[% END %]
[% BLOCK directory %]
   * [% item.name %]
     [% item.content(myview) FILTER indent %]
[% END %]
[% END %]
                    
                      The view print() method can then be called, passing the
                      Directory object as an argument.
                    
[% USE dir = Directory(dirpath, recurse=1) %] [% myview.print(dir) %]
                      When a directory is presented to a view, either as [%
                      myview.print(dir) %] or [% dir.present(view) %], then
                      the directory BLOCK within the
                      myview VIEW is processed. The item
                      variable will be set to alias the Directory object.
                    
[% BLOCK directory %]
   * [% item.name %]
     [% item.content(myview) FILTER indent %]
[% END %]
                    
                      In this example, the directory name is first printed and the
                      content(view) method is then called to present each item within the
                      directory to the view. Further directories will be mapped to the
                      directory block, and files will be mapped to the
                      file block.
                    
                      With the recurse option disabled, as it is by default, the
                      directory block should explicitly call a scan()
                      on each directory.
                    
[% VIEW myview %]
[% BLOCK file %]
   - [% item.name %]
[% END %]
[% BLOCK directory %]
   * [% item.name %]
     [% item.scan %]
     [% item.content(myview) FILTER indent %]
[% END %]
[% END %]
[% USE dir = Directory(dirpath) %]
[% myview.print(dir) %]
              AUTHORS
TopCOPYRIGHT
TopCopyright (C) 2000-2007 Michael Stevens, Andy Wardley.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.