fcopy()

dircopy()

returns true or false, for true in scalar context it returns the number of files and directories copied, In list context it returns the number of files and directories, number of directories only, depth level traversed.

  my $num_of_files_and_dirs = dircopy($orig,$new);
  my($num_of_files_and_dirs,$num_of_dirs,$depth_traversed) = dircopy($orig,$new);

Normally it stops and return's if a copy fails, to continue on regardless set $Vimana::Recursive::SkipFlop to true.

    local $Vimana::Recursive::SkipFlop = 1;

That way it will copy everythgingit can ina directory and won't stop because of permissions, etc...

rcopy()

rcopy_glob()

It returns and array whose items are array refs that contain the return value of each rcopy() call.

It forces behavior as if $Vimana::Recursive::CPRFComp is true.

fmove()

dirmove()

rmove()

rmove_glob()

$RemvBase

Default is false. When set to true the *move() functions will not only attempt to remove the original file or directory but will remove the given path it is in.

So if you:

   rmove('foo/bar/baz', '/etc/');
   # "baz" is removed from foo/bar after it is successfully copied to /etc/
   
   local $Vimana::Recursive::Remvbase = 1;
   rmove('foo/bar/baz','/etc/');
   # if baz is successfully copied to /etc/ :
   # first "baz" is removed from foo/bar
   # then "foo/bar is removed via pathrm()

$ForcePth

Default is false. When set to true it calls pathempty() before any directories are removed to empty the directory so it can be rmdir()'ed when $RemvBase is in effect.

Creating and Removing Paths

Default is false. If set to true rmdir(), mkdir(), and pathempty() calls in pathrm() and pathmk() do not return() on failure.

If its set to true they just silently go about their business regardless. This isn't a good idea but its there if you want it.

$DirPerms

Mode to pass to any mkdir() calls. Defaults to 0777 as per umask()'s POD. Explicitly having this allows older perls to be able to use FCR and might add a bit of flexibility for you.

Any value you set it to should be suitable for oct()

Path functions

These functions exist soley because they were necessary for the move and copy functions to have the features they do and not because they are of themselves the purpose of this module. That being said, here is how they work so you can understand how the copy and move funtions work and use them by themselves if you wish.

pathrm()

Removes a given path recursively. It removes the *entire* path so be carefull!!!

Returns 2 if the given path is not a directory.

  Vimana::Recursive::pathrm('foo/bar/baz') or die $!;
  # foo no longer exists

Same as:

  rmdir 'foo/bar/baz' or die $!;
  rmdir 'foo/bar' or die $!;
  rmdir 'foo' or die $!;

An optional second argument makes it call pathempty() before any rmdir()'s when set to true.

  Vimana::Recursive::pathrm('foo/bar/baz', 1) or die $!;
  # foo no longer exists

Same as:PFSCheck

  Vimana::Recursive::pathempty('foo/bar/baz') or die $!;
  rmdir 'foo/bar/baz' or die $!;
  Vimana::Recursive::pathempty('foo/bar/') or die $!;
  rmdir 'foo/bar' or die $!;
  Vimana::Recursive::pathempty('foo/') or die $!;
  rmdir 'foo' or die $!;

An optional third argument acts like $Vimana::Recursive::NoFtlPth, again probably not a good idea.

pathempty()

Recursively removes the given directory's contents so it is empty. returns 2 if argument is not a directory, 1 on successfully emptying the directory.

   Vimana::Recursive::pathempty($pth) or die $!;
   # $pth is now an empty directory

pathmk()

Creates a given path recursively. Creates foo/bar/baz even if foo does not exist.

   Vimana::Recursive::pathmk('foo/bar/baz') or die $!;

An optional second argument if true acts just like $Vimana::Recursive::NoFtlPth, which means you'd never get your die() if something went wrong. Again, probably a *bad* idea.

pathrmdir()

Same as rmdir() but it calls pathempty() first to recursively empty it first since rmdir can not remove a directory with contents. Just removes the top directory the path given instead of the entire path like pathrm(). Return 2 if given argument does not exist (IE its already gone). Return false if it exists but is not a directory.

Preserving Mode

Managing Depth

SymLinks

    if($Vimana::Recursive::CopyLink) {
        print "Symlinks will be preserved\n";
    } else {
        print "Symlinks will not be preserved because your system does not support it\n";
    }

If symlinks are being copied you can set $Vimana::Recursive::BdTrgWrn to true to make it carp when it copies a link whose target does not exist. Its false by default.

    local $Vimana::Recursive::BdTrgWrn  = 1;

Removing existing target file or directory before copying.

0 = off (This is the default)

1 = carp() $! if removal fails

2 = return if removal fails

    local $Vimana::Recursive::RMTrgFil = 1;
    fcopy($orig, $target) or die $!;
    # if it fails it does warn() and keeps going

    local $Vimana::Recursive::RMTrgDir = 2;
    dircopy($orig, $target) or die $!;
    # if it fails it does your "or die"

This should be unnecessary most of the time but its there if you need it :)

Turning off stat() check

Emulating cp -rf dir1/ dir2/

You can make dircopy() emulate cp -rf by setting $Vimana::Recursive::CPRFComp to true.

NOTE: This only emulates -f in the sense that it does not prompt. It does not remove the target file or directory if it exists. If you need to do that then use the variables $RMTrgFil and $RMTrgDir described in "Removing existing target file or directory before copying" above.

That means that if $dir2 exists it puts the contents into $dir2/$dir1 instead of $dir2 just like cp -rf. If $dir2 does not exist then the contents go into $dir2 like normal (also like cp -rf)

So assuming 'foo/file':

    dircopy('foo', 'bar') or die $!;
    # if bar does not exist the result is bar/file
    # if bar does exist the result is bar/file

    $Vimana::Recursive::CPRFComp = 1;
    dircopy('foo', 'bar') or die $!;
    # if bar does not exist the result is bar/file
    # if bar does exist the result is bar/foo/file

You can also specify a star for cp -rf glob type behavior:

    dircopy('foo/*', 'bar') or die $!;
    # if bar does not exist the result is bar/file
    # if bar does exist the result is bar/file

    $Vimana::Recursive::CPRFComp = 1;
    dircopy('foo/*', 'bar') or die $!;
    # if bar does not exist the result is bar/file
    # if bar does exist the result is bar/file

NOTE: The '*' is only like cp -rf foo/* and *DOES NOT EXPAND PARTIAL DIRECTORY NAMES LIKE YOUR SHELL DOES* (IE not like cp -rf fo* to copy foo/*)

Allowing Copy Loops

  cp -rf . foo/

type behavior set $Vimana::Recursive::CopyLoop to true.

This is false by default so that a check is done to see if the source directory will contain the target directory and croaks to avoid this problem.

If you ever find a situation where $CopyLoop = 1 is desirable let me know (IE its a bad bad idea but is there if you want it)

(Note: On Windows this was necessary since it uses stat() to detemine samedness and stat() is essencially useless for this on Windows. The test is now simply skipped on Windows but I'd rather have an actual reliable check if anyone in Microsoft land would care to share)