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.