NAME

File::DirScan - Scan directories and manipulate filename/pathnames.

VERSION

version 1.19

SYNOPSIS

$dscan = File::DirScan->new( 'directory' => $path );

# We are interested in directories
$dscan->directories( 1 );

# We are not interested in file
$dscan->files( 0 );

# We are interested in items beginning with '.'
$dscan->dots( 1 );

print "Directories are ", join(',',$dscan->list), "\n";

# Alternate version of the above using initializer defaults

$dscan = File::DirScan->new( {
    'directory'     => $path,
    'directories'   => 1,
    'files'         => 0,
    'dots'          => 1,
    } );
print "Directories are ", join(',',$dscan->list), "\n";


# Default initialisation is equivalent to

$dscan = File::DirScan->new( {
        {
        'directory' => undef,
        'pattern' => '.*',
        'directories' => 0,
        'files' => 1,
        'fullnames' => 0,
        'dots' => 0,
        } );

DESCRIPTION

File::DirScan is a module to provide a object/method mechanism to obtain the contents of a given directory. It also provides some methods to allow building and sanitisation of filenames and directory names.

The module reads and caches the directory contents on the first call to the list() method, and then produces a result based on the current filter methods. It will refresh the cache if the mtime of the directory changes or the invalidate() method is called.

The directory can only be provided during the call to new() and cannot be changed thereafter. The new() call will default the value to / if not provided. The directory does not need to exist at the time of calling new() but obviously does need to by the time any of the query methods are called.

METHODS

• directory

    my $curdir = $dirscan->directory;
  

• relative_path

  Get and optionally set the relative_path member.

• files

  A boolean field specifying whether files should be included in the output. Defaults to 1 (true).

• directories

  A boolean field specifying whether directories should be included in the output. Defaults to 0 (false).

• others

  A boolean field specifying whether items other than files or directories should be included in the output. Defaults to 0 (false).

• dots

  A boolean field specifying whether names starting with '.' should be included in the output. Defaults to 0 (false).

• fullnames

  A boolean field specifying whether items returned should be be fully specified. Defaults to 0 (false).

• pattern

  A regexp defining which items should be returned in the output. Defaults to '.*' aka all items (modulo meeting the requirements of directories, files & dots.

• list

  A read-only method which returns the directory items according to the supplied constraints. Will return a list or list reference according to context.

• relative_list

  Return the current list with the relative_path as the the prefix. Temporarily overrides the fullnames option.

• fullname_list

  Return the current list with just the fullnames. Temporarily overrides the fullnames option.

• basename_list

  Return the current list with just the basenames. Temporarily overrides the fullnames option.

• subdirectory_list =item subdirectory_list( dots )

  Return a list (or reference to a list) of File::DirScan objects of all subdirectories of this object (ignoring the pattern).

  Takes optional parameter which can be used to temporarily override the current dots option to control whether directories with dots should be included in the result.

  The returned File::DirScan objects inherit the options of the parent.

• invalidate

  Force the cache of names to be invalidated and trigger a re-read of the directory the next time the list method is called. The cache will automatically be invalidated if the mtime of the directory changes, or the directory path is changed.

• build_path( elements, ... )

  Build a full pathname from an array of directory elements with a degree of pathname sanitisation.

  So the following snippets are equivalent

    $dscan->fullnames(1);
    @fulllist = $dscan->list;
  
    $dscan->fullnames(0);
    @fulllist = map { $dscan->build_path( $dscan->directory, $_ ); } $dscan->list;
  

  This method can also be called for any list of path elements without affecting any of the object constraints, values or results.

    chdir $origin;
    $oscan = File::DirScan->new( {
            'directory' => '.',
            'directories' => 1,
            'files' => 0,
            } );
    foreach $subdir( $oscan->list )
    {
        print "Checking for files in element $subdir\n";
        $dscan = File::DirScan->new( { 'directory' => $subdir } );
        foreach( $dscan->list )
        {
            print "Found file ", $dscan->build_path( $origin, $subdir, $_ ), "\n";
        }
    }
  

• ensure_dir_exists( directory, [directory_mode] )

  Ensure the specified directory exists, recursing for parent if it does not exist. Set the specified mode on creation (defaults to 0700).

NOTES

The others flag enables the inclusion of items which are not recognised as either files or directories. This includes devices, pipes, etc. It also includes symlinks where the target of the symlink is not a file or a directory or the symlink no longer exists. It is also worth highlighting for completeness that symlinks that do point to files or directories will be returned as in the files and directories categories.

COMPATIBILITY

• File::DirScan requires Class::Accessorize, IO::Handle & File::Basename.

AUTHOR

Bernard Quatermass toolsmith@quatermass.co.uk

COPYRIGHT AND LICENSE

This software is copyright (c) 2017,2018 by Bernard Quatermass.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.