Mdc::ReadDir

Mdc::ReadDir

Package Name

        ReadDir  version 2.03 -- 2004-07-20
        A simple interface for reading directories and file lists.
        Usage:
                use Mdc::ReadDir;
                my $DIR = new Mdc::ReadDir($path);
                print $DIR->

Description

        Read directory contents given the path and file pattern to search for.
        File or directory names will be returned in the order dictated by the
        operating system and cannot be changed.  However, names returned with 
        the List methods will always be in alphanumeric order.
        If the given path does not exist or if a directory cannot be opened for
        reading, return undef.
        Uses the built-in perl functions 'opendir', and 'readdir'.
        Will not affect the pwd of the perl environment.

Methods

new

        object = new ReadDir(ipath,(optional file extension list))
        Open a directory for reading and create a new directory object.  Returns
        the object reference.  ARG1 is the initial path.
        ARG2 is optional list of file extensions or file types to be included in
        subsequent file lists.  List is not case sensitive.  List may also be set
        using the Ext method.
        An empty ARG2 list will cause all file types to be included in subsequent
        file lists.
        Current path (cPath) is set to initial path when first opended.

Close

        Close directory handles and any open filehandles.

Ipath

        Return the inital path that was set during object creation.
                $mypath = $D->Ipath;

cPath

        Set or return current path.  This differs from the initial path in that
        the current path must be directly under the initial path.  This allows
        all subdirectories under the initial path to be examined with subsequent
        cPath and Pop statements.  Does not affect the current directory of the
        Perl environment.
        When changing the current path, the current directory information is saved.
        Uppon returning to this directory, the file and subdirectory pointers
        will be returned to their original positions.
                $currpath = $D->cPath;
        In the context of returning the current path, the entire path string
        starting from the initial path will be returned.
                $currpath = $D->cPath('bender');
        In the context of setting the current path, the entire path starting
        with the initial path will be returned if successful.  Return empty
        scalar if not.

Pop

        Change the current directory back to it's parent directory.  File and
        subdirectory pointers will be returned to their previous states.
                $path = $D->Pop;
        Return directory name.

FileExt

        Set or return list of file extensions or file types to be included in
        subsequent file lists.  List is not case sensitive. List may also be set
        during object creation.  An empty FileExt list will cause all file types to be included
        in subsequent file lists.
                @extlist = $D->FileExt;         # return list of file types
                $D->FileExt( 'htm', 'html' );   # Set list of file types

FilePattern

        Define a pattern for file searching or return the current pattern string.  
        Uses a regular expresion.  The filename pattern will be applied to the list 
        of file types that were defined in the FileExt or object creation methods.
        Using a blank argument will reset the pattern.
                $D->FilePattern('\..*htm.*$');          # find all html files
                $D->FilePattern('');                    # reset pattern
                $pat = $D->FilePattern;                 # return current pattern
        Note:  In pattern matching, case is always ignored.

SubPattern

        Define a pattern for file searching or return the current pattern string.  
        Uses a regular expresion.  The subdirectory pattern will be applied to the 
        list of subdirectories in the current path.
        Using a blank argument will reset the pattern.
                $D->SubPattern('^foo');                 # find all subdirectories that
                                                        # begin with "foo"
                $D->SubPattern('');                     # reset pattern
                $pat = $D->SubPattern;                  # return current pattern
        Note:  In pattern matching, case is always ignored.

FileCount

        Return count of files in current directory that match the the defined file type
        and the file pattern.

SubCount

        Return count of subdirectories in current directory that match the defined
        sub pattern.

ListFiles

        Return list of files in cPath matching FileExt list and pattern.

ListSubs

        Return list of all subdirectories in cPath

NextFile

        Return next file in the list under cPath matching FileExt list and pattern.
        Return empty scalar if end of file list.
                $file = $D->NextFile;

NextSub

        Return next subdiretory in the list under cPath.
        Return empty scalar if end of subdiretory list.
                $dir = $D->NextSub;

EOF

        Return 1 if end of file list.

EOD

        Return 1 if end of subdirectory list.

RewindFiles

        Set current file pointer to the beginning of the directory.

RewindSubs

        Set current subdirectory pointer to the beginning of the directory.

Error

        Return value of last error encountered.
        Error Codes:
                0       No error
                613     Unable to read directory contents
                614     Directory does not exist

Examples

        # Print a list of all html files in Bender's directory:
                my $D = new ReadDir( '/export/home/bender', 'html' );
                while( $f = $D->Next ){
                        print $f . "\n";
                }
                $D->Close;
        # Reopen bender's directory and print list of all .txt files:
                my $D = new ReadDir( '/export/home/bender', 'txt' );
                while( $f = $D->Next ){
                        print $f . "\n";
                }
                $D->Close;
        # Another way to print a list of files:
                my $D = new ReadDir( '/export/home/bender', 'txt' );
                print join( "\n", $D->ListFiles );
                $D->Close;
        # Print a list of files in all subdirectories
                my $D = new ReadDir( '/export/home/bender', 'txt' );
                print "Dir: " , $D->cPath , "\n";
                while(1) {
                        print join( "\n", $D->ListFiles );
                        if( $D->NextSub ) {
                                print "Dir: " , $D->cPath , "\n";
                        }else{
                                $path = $D->Pop;
                        }
                }
                $D->Close;

Author

        Mark K Mueller <mark@224.com>
        Copyright (c) 2003 MUELLER Design & Consulting