Ticket #587: FileScan.d

/*******************************************************************************

        copyright:      Copyright (c) 2004 Kris Bell. All rights reserved

        license:        BSD style: $(LICENSE)

        version:        Jun 2004: Initial release
        version:        Dec 2006: Pacific release

        author:         Kris

*******************************************************************************/

module tango.io.FileScan;

public import tango.io.FilePath;

/*******************************************************************************

        Scan files and directories (recursively by default), adding filtered 
        files to an output structure as we go. This can be used to produce a 
        list of subdirectories and the files contained therein. The following
        example lists all files with suffix ".d" located via the current
        directory, along with the folders containing them:

    Examples:
        ---
        auto scan = new FileScan;

        scan (".", ".d");

        Stdout.formatln ("{0} Folders", scan.folders.length);
        foreach (folder; scan.folders)
                 Stdout.formatln ("{0}", folder);

        Stdout.formatln ("\n{0} Files", scan.files.length);
        foreach (file; scan.files)
                 Stdout.formatln ("{0}", file);
        ---

        This is unlikely the most efficient method to scan a vast number of
        files, but operates in a convenient manner
        
        The above code will result in the scan terminating early if an error
        is encountered along the way (such as permission denied, or a malformed
        soft-link, etc).  In order to continue in the event of errors use the
        stopOnError parameter of sweep:
        ---
        auto scan = new FileScan;

        scan (".", ".d", true);
        
        foreach (idx, file; scan.errors)
            Stdout.format("Error [{0}]: {1} -- {2}", idx, file.path.toUtf8, file.msg);
        ---
*******************************************************************************/

class FileScan
{       
        alias sweep opCall;

        uint            total_;
        FilePath[]      files_,
                        folders_;
        FileScanError[] errors_;
        
        /***********************************************************************

            Alias for Filter delegate. Accepts a FilePath & a bool as 
            arguments and returns a bool.

            The FilePath argument represents a file found by the scan, 
            and the bool whether the FilePath represents a folder.

            The filter should return true, if matched by the filter. Note
            that returning false where the path is a folder will result 
            in all files contained being ignored. To always recurse folders, 
            do something like this:
            ---
            return (isDir || match (fp.name));
            ---

        ***********************************************************************/

        alias bool delegate (FilePath, bool) Filter;

        /***********************************************************************

                Return the number of files found in the last scan

        ***********************************************************************/

        public uint inspected ()
        {
                return total_;
        }

        /***********************************************************************

                Return all the files found in the last scan

        ***********************************************************************/

        public FilePath[] files ()
        {
                return files_;
        }

        /***********************************************************************
        
                Return all directories found in the last scan

        ***********************************************************************/

        public FilePath[] folders ()
        {
                return folders_;
        }

        /***********************************************************************
        
                Return all errors found in the last scan

        ***********************************************************************/

        public FileScanError[] errors ()
        {
                return errors_;
        }
        
        /***********************************************************************

                Sweep a set of files and directories from the given parent
                path, where the files are filtered by the given suffix
                
                Params:  path =         The path to sweep
                         match =        The pattern to match while sweeping
                         stopOnError =  If true sweep will throw an exception 
                                        on encountering an error
                         recurse =  Do a recursive scan if true
        
        ***********************************************************************/
        
        FileScan sweep (char[] path, char[] match, bool stopOnError = true, bool recurse = true)
        {
                return sweep (path, (FilePath fp, bool isDir)
                             {return isDir || match == "" || fp.suffix == match;}, stopOnError, recurse);
        }

        /***********************************************************************

                Sweep a set of files and directories from the given parent
                path, where the files are filtered by the provided delegate

                Params:  path =         The path to sweep
                         match =        The pattern to match while sweeping
                         stopOnError =  If true sweep will throw an exception 
                                        on encountering an error
                         recurse =  Do a recursive scan if true
        
        ***********************************************************************/
        
        FileScan sweep (char[] path, Filter filter, bool stopOnError = true, bool recurse = true)
        {
                total_ = 0;
                files_ = folders_ = null;
                errors_ = null;
                return scan (new FilePath(path), filter, stopOnError, recurse);
        }

        /***********************************************************************

                Internal routine to locate files and sub-directories. We
                skip folders composed only of '.' chars. 

        ***********************************************************************/

        private FileScan scan (FilePath folder, Filter filter, bool stopOnError, bool recurse) 
        {
                FilePath[] paths;

                void add (char[] prefix, char[] name, bool isDir)
                { 
                        char[512] tmp;

                        int len = prefix.length + name.length;
                        assert (len < tmp.length);
                        ++total_;

                        // construct full pathname
                        tmp[0..prefix.length] = prefix;
                        tmp[prefix.length..len] = name;

                        auto p = new FilePath (tmp[0 .. len], isDir);

                        // test this entry for inclusion
                        if (filter (p, isDir))
                           {
                           // skip dirs composed only of '.'
                           if (name.length > 3 || name != "..."[0 .. name.length])
                               paths ~= p;                                                   
                           }
                        else
                           delete p;
                }

        try {
                    folder.toList (&add);
                } catch (Exception e) {
                    if (stopOnError)
                        throw e;
                    else {
                        errors_ ~= new FileScanError(folder, e.msg);
                        return this;
                    }
                }
                auto count = files_.length;
                
                foreach (path; paths)
                         if (path.isDir)
                             if (recurse)
                                  scan (path, filter, stopOnError, recurse);
                             else
                                  folders_ ~= path;
                         else
                            files_ ~= path;
                
                // add packages only if there's something in them
                if (files_.length > count)
                    folders_ ~= folder;

                return this;
        }
}

/*******************************************************************************

    Hold information about errors encountered during the scan
    
    Params: path =      path the triggered the errors
        msg =       reason behind the error

*******************************************************************************/

class FileScanError {
    FilePath    path;
    char []     msg;
    
    this(FilePath Path, char [] Msg) {
        path = Path;
        msg = Msg;
    }
}