NAME

Dir::List - Perl extension for retrieving directory/fileinformation

SYNOPSIS

  use Dir::List;

  my $dir = Dir::List->new();

  my $dirinfo = $dir->dirinfo('/var/ftp');

  A few things can be defined @ new, that will change the behaviour of Dir::List:

        - exclude (array, default: empty)
        - use_cache (1/0, default: 0 (disabled))
        - cache_root (path where to store the cache, if enabled, default: "/tmp/Dir_List")
        - cache_expires (Cache::File expires, default: '5 monutes')
        - check_diskusage (1/0, default: 1 (enabled))
        - show_directory_owner (1/0, default: 1 (enabled))
        - show_directory_group (1/0, default: 1 (enabled))
        - show_file_group (1/0, default: 1 (enabled))
        - show_file_owner (1/0, default: 1 (enabled))
        - datetimeformat (Date::Format template, default: "%Y-%m-%d %H:%M:%S")
        - new_is_max_sec (seconds as int, default 86400 * 5 (five days)

  These arguments can be specified the way (don't forget the '{'!)

  my $dir = new Dir::List({
          exclude => [ qw/^iso ^pub/ ],
          use_cache => 1,
          cache_root => '/tmp/MyApplication_Cache/',
          cache_expires => '20 minutes',
          check_diskusage => 1,
          show_directory_owner => 1,
          show_directory_group => 1,
          show_file_owner => 1,
          show_file_group => 1,
          datetimeformat => "%Y-%m-%d %H:%M:%S",
          new_is_max_sec => 86400 * 5,
  });

DESCRIPTION

  Dir::List is a wrapper around a few other modules. It provides you with various
  informations about the contents of a directory. Eg. diskusage of directory,
  user/group, uid/gid of files/directories, last modified date/time, if it's
  accessible by the current user and so on.

  Dir::List has caching functionality. This is usefull if you list many files/directories
  and don't want to Dir::List to consume to much CPU and I/O all the time.
  Also gatherin' the uid/gid an internal caching mechanism is used to speed up Dir::List.

  The module provides you with a few functions:

  dirinfo()

  This function is easy to use. Instanciate a new Dir::List and do:

  my $dirinfo = $dir->dirinfo('/var/ftp').

  $dirinfo will now hold a lots of information about the files/directories within /var/ftp.

  That's it. :-)

  There are two functions that help you with the cache:

  clearcache()

  Takes no arguments, simply clears the cache completely.

  remove_from_cache()

  Takes a path (always with the trailing slash!) as argument and removes the entry from the cache.

  Please note, that all functions from Cache::File and Cache are available through the $dir->{__cache},
  but normally it's not a good idea to modify internal variables directly...

  This module is a split of, of my FileLister project. As FileLister will become
  a mod_perl application sooner or later (I'm working on a rewrite), I think it's
  better to put more logic into modules and provide this function to other developers
  as well.

  Note, that I rewrote the functions from FileLister and did a lot of optimizations/changes to speed up
  things.

EXPORT

None by default.

SEE ALSO

Cache::File Filesys::DiskUsage Clone File::Type Date::Format

AUTHOR

Oliver Falk, <oliver@linux-kernel.at>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Oliver Falk

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.