#----------------------------------------------------------------------------
#this is subroutines of file and folder process.
#usage:
#      in your perl file when you want use the following functions, insert
#      ther following string:
#                           require filedir_misc;
#note:
#     the string "require filedir_misc;" only be included once in a file.
#----------------------------------------------------------------------------
require string_misc;

my $OS_Win = ($^O =~ /mswin/i);
my $isCygwin = ($^O =~ /cygwin/i);
my $dirSprtor = $OS_Win? '\\': '/';

# get the current directory which "$0" lies in.
# the return value contains no "/" character at the end of the string.
sub getCurrentDirectory()
{
    my ($lcwd, $cwd) = '';

    eval "\$lcwd = Win32::GetCwd";

    if (!($lcwd eq '' || $lcwd eq 'Win32::GetCwd')) {
        $cwd = $lcwd;
    }
    else {
        chomp($cwd = `pwd`);
    }

    &convetSlash(\$cwd) if ($isCygwin);

    return $cwd;
}

# extentAbsPath()
#    - get aboslute path according relative path.
#
# param0
#    - [in|out]: the relative path when passed in,
#                and absolute path when passed out.
#
sub extentAbsPath(\$)
{
    my ($refPath) = shift;
    my ($temp);

    return 0 if (ref($refPath) ne "SCALAR");

    return $$refPath = &getCurrentDirectory() if ('.' eq $$refPath);
    return $$refPath if ($$refPath =~ m/:/g or $$refPath =~ m/^[\\\/]/);

    $temp = $$refPath;
    $temp =~ s:\/[\w\.]+$::;

    $temp = &getCurrentDirectory() . $dirSprtor . $temp;
    $$refPath = $temp;
}

# getListInDir()
#    - list the dirs and files in the folder.
#
# param0
#   - [out]: reference of a array to store the item list (files and dirs).
# param1
#   - [in]: the dir to be listed.
#
# return
#   - the total count of files and subdirs in this folder.
sub getListInDir(\@$)
{
    my ($refArray, $curDir) = @_;

    die "parameter[0] should be a array!" if (!$refArray);
    die "parameter[1] should be a dir! value==$curDir" if (!$curDir);

    $curDir = $curDir . "/" if ($curDir =~ m /^[A-Za-z]{1}:$/);
    opendir(CURDIR, $curDir) || die "$curDir - $!";

    #remove the "." and  ".." which is short for current fold
    #and parent folder respectively.
    @$refArray = grep(!/^\.\.?$/, readdir(CURDIR));
    closedir(CURDIR);

    return scalar(@$refArray);
}

# param0
#   - [in]: file name or a open file handle.
# param1
#   - [in]: optional param. Mostly this is passed from DirHandler() in order
#           to some alternation determine. For example, we want delete the
#           files in "CVS". So if 1 indicating this file is in the directory
#           'CVS' so delete this file arbitrarily, any other value do nothing
#           on this file.
# param2
#   - [in]: a callback function to be called in this subroutine.
#           By executing this callback the subroutine "handleSingleFile()"
#           makes effect on the file/fileHandle passed from [param1].
sub handleSingleFile($$*)
{
    my ($file, $optionIndicator, $callback) = @_;

    &$callback($file, $optionIndicator) if defined(&$callback);
}

# recursive file system (directory) handler. The detail process can be
# breakdown as following:
#   1: handle the current dir first (if the handler result is 0 then stop
#      recursive handler, otherwise the recursive call will go on.)
#   2: parse the current dir (call the parse callback function).(this is only
#      to pass the parse result to FILE_HANDLER, not recursive intension.)
#   3: handle the files in the current directory according current dir
#      parse result.
#   4: recursive call this handler routine if necessary (according the result
#      returned by step 1).
#
# param0
#   - [in]: directory name which to be handled.
# param1
#   - [in]: directory parse function. $dirHandler(param3) will handle the dir
#           according this callback function's return value. So the return
#           value means:
#               -- positive: this value will be pass to next recursive call
#                   in other words, all subfolder parse value will be ignored
#                   instead using this value.
#               -- negative: (recursive call) subfolder will call $dirParseCB
#                   (param1) to get the value to pass to $dirHandler(param3).
#               -- 0: do nothing on the current directory and no recursive
#                   call is needed.
# param2
#   - [in]: whether the iterate action is width first.
#               0 : depth iterate first.
#               1 : width iterate first.
# param3:
#   - [in]: dir handler. The function prototype likes this:
#           dirHandler($curDir, $dirParseValue).
# param4:
#   - [in]: file handler. The function prototype likes this:
#           fileHandler($curDir, $parentDirParseValue).
# param5:
#   - [in]: This param is optional. If this param is passed by NEGATIVE value
#           that indicates $dirParseCB(param1) is no used.
sub handleSingleDir($*$**;$)
{
    my ($curDir, $dirParseCB, $widthIterate, $dirHandler, $fileHandler,
        $parseInheritable) = @_;
    my ($dirParseValue, @itemList, @dirList, @fileList, $item, $fullFileName);

    die "handleSingleDir() parameter error: dir_handler!\n"
        if (!defined $dirHandler or !$dirHandler);

    &extentAbsPath(\$curDir) unless ($curDir =~ m/^[\\\/]/
                                     or $curDir =~ m/:/g);

    return 0 if (! -d $curDir);

    return 0 if (defined $parseInheritable and 0 == $parseInheritable);

    if (defined $parseInheritable and 0 < $parseInheritable) {
        $dirParseValue = $parseInheritable;
    }
    else {
        if ($dirParseCB) {
            $dirParseValue = &$dirParseCB($curDir);
            return 0 if (0 == $dirParseValue);
        }
        else {
            $dirParseValue = -1;
        }
    }

    if (0 == &getListInDir(\@itemList, $curDir)) {
=here      $dirHandler------------1
=cut
        return &$dirHandler($curDir, $dirParseValue);
    }

    #make the array element ascending.
    @itemList = sort(@itemList);
=here      $dirHandler------------2
=cut
    if ($widthIterate) {
        &$dirHandler($curDir, $dirParseValue);
    }

    foreach $item (@itemList) {
        $fullFileName = "${curDir}${dirSprtor}${item}";

        #width iterate
        if ($widthIterate) {
            #handling file first
            if (-f $fullFileName) {
                &handleSingleFile($fullFileName,
                                  $dirParseValue,
                                  $fileHandler) if ($fileHandler);
            }
            #handling directory
            elsif (-d $fullFileName) {
                #store the subfolder into the @dirList.
                #So a recursive call will be done.
                push(@dirList, $fullFileName);
            }
        }
        #depth iterate
        else {
            #handling file first
            if (-f $fullFileName) {
                #store the files into the @fileList. So if all subdir handle
                #done current file list has chance to handled.
                push(@fileList, $fullFileName);
            }
            #handling directory
            elsif (-d $fullFileName) {
                #store the subfolder into the @dirList.
                #So a recursive call will be done.
                push(@dirList, $fullFileName);
            }
        }
    }

    foreach $item (@dirList) {
        #recursive call
        &handleSingleDir($item,
                         $dirParseCB,
                         $widthIterate,
                         $dirHandler,
                         $fileHandler,
                         $dirParseValue);
    }

    #if there is no fold in the current directory it's time to handle the
    #files stored in the @fileList.
    foreach $item (@fileList) {
        &handleSingleFile($item,
                          $dirParseValue,
                          $fileHandler) if ($fileHandler);
    }

    &$dirHandler($curDir, $dirParseValue) if (!$widthIterate);

    return 1;
}

1;