NAME
File::Xcopy - copy files after comparing them.
SYNOPSIS
use File::Xcopy;
xcopy("file1","file2", "action");
xcopy("from_dir", "to_dir", "action", "file_name_pattern");
xcp("file1","file2", "action");
xcp("from_dir", "to_dir", "action", "file_name_pattern");
my $xcp = File::Xcopy->new(log_file=>"file_name");DESCRIPTION
The File::Xcopy module provides two basic functions, xcopy and xmove, which are useful for coping and/or moving a file or files in a directory from one place to another. It mimics some of behaviours of xcopy in DOS but with more functions and options.
The differences between xcopy and copy are
xcopysearches files based on file name pattern if the pattern is specified.xcopycompares the timestamp and size of a file before it copies.xcopytakes different actions if you tell it to.
The Constructor new(%arg)
Without any input, i.e., new(), the constructor generates an empty object with default values for its parameters.
If any argument is provided, the constructor expects them in the name and value pairs, i.e., in a hash array.
xcopy($from, $to, $act, $pat, $par)
Input variables:
$from - a source file or directory
$to - a target directory or file name
$act - action:
report|test - test run
copy|CP - copy files from source to target only if
1) the files do not exist or
2) newer than the existing ones
This is default.
overwrite|OW - copy files from source to target even if
the files exist and newer than the source files
move|MV - same as in copy except it removes from source the
following files:
1) files are exactly the same (size and time stamp)
2) files are copied successfully
update|UD - copy files only if
1) the file exists in the target and
2) different from the source in size and time stamp.
$pat - file name match pattern, default to {.+}
$par - parameter array
log_file - log file name with full path
source Specifies the file(s) to copy.
destination Specifies the location and/or name of new files.
/A Copies only files with the archive attribute set,
doesn't change the attribute.
/M Copies only files with the archive attribute set,
turns off the archive attribute.
/D:m-d-y Copies files changed on or after the specified date.
If no date is given, copies only those files whose
source time is newer than the destination time.
/EXCLUDE:file1[+file2][+file3]...
Specifies a list of files containing strings. When any of the
strings match any part of the absolute path of the file to be
copied, that file will be excluded from being copied. For
example, specifying a string like \obj\ or .obj will exclude
all files underneath the directory obj or all files with the
.obj extension respectively.
/P Prompts you before creating each destination file.
/S Copies directories and subdirectories except empty ones.
/E Copies directories and subdirectories, including empty ones.
Same as /S /E. May be used to modify /T.
/V Verifies each new file.
/W Prompts you to press a key before copying.
/C Continues copying even if errors occur.
/I If destination does not exist and copying more than one file,
assumes that destination must be a directory.
/Q Does not display file names while copying.
/F Displays full source and destination file names while copying.
/L Displays files that would be copied.
/H Copies hidden and system files also.
/R Overwrites read-only files.
/T Creates directory structure, but does not copy files. Does not
include empty directories or subdirectories. /T /E includes
empty directories and subdirectories.
/U Copies only files that already exist in destination.
/K Copies attributes. Normal Xcopy will reset read-only attributes.
/N Copies using the generated short names.
/O Copies file ownership and ACL information.
/X Copies file audit settings (implies /O).
/Y Suppresses prompting to confirm you want to overwrite an
existing destination file.
/-Y Causes prompting to confirm you want to overwrite an
existing destination file.
/Z Copies networked files in restartable mode.Variables used or routines called: None.
How to use:
use File::Xcopy;
my $obj = File::Xcopy->new;
# update all the files with .txt extension if they exists in /tgt/dir
$obj->xcopy('/src/files', '/tgt/dir', 'OW', '\.txt$');
use File:Xcopy qw(xcopy);
xcopy('/src/files', '/tgt/dir', 'OW', '\.txt$'); Return: ($n, $m).
$n - number of files copied or moved.
$m - total number of files matchedfind_files($dir,$re)
Input variables:
$dir - directory name in which files and sub-dirs will be searched
$re - file name pattern to be matched. Variables used or routines called: None.
How to use:
use File::Xcopy;
my $fc = File::Xcopu->new;
# find all the pdf files and stored in the array ref $ar
my $ar = $fc->find_files('/my/src/dir', '\.pdf$'); Return: $ar - array ref and can be accessed as ${$ar}[$i]{$itm}, where $i is sequence number, and $itm are
file - file name without dir
pdir - parent dir for the file
path - full path for the fileThis method resursively finds all the matched files in the directory and its sub-directories. It uses finddepth method from File::Find(1) module.
list_files($dir,$re)
Input variables:
$dir - directory name in which files will be searched
$re - file name pattern to be matched. Variables used or routines called: None.
How to use:
use File::Xcopy;
my $fc = File::Xcopu->new;
# find all the pdf files and stored in the array ref $ar
my $ar = $fc->list_files('/my/src/dir', '\.pdf$'); Return: $ar - array ref and can be accessed as ${$ar}[$i]{$itm}, where $i is sequence number, and $itm are
file - file name without dir
pdir - parent dir for the file
path - full path for the fileThis method only finds the matched files in the directory and will not search sub directories. It uses readdir to get file names.
file_stat($dir,$ar)
Input variables:
$dir - directory name in which files will be searched
$ar - array ref returned from C<find_files> or C<list_files>
method. Variables used or routines called: None.
How to use:
use File::Xcopy;
my $fc = File::Xcopu->new;
# find all the pdf files and stored in the array ref $ar
my $ar = $fc->find_files('/my/src/dir', '\.pdf$');
my $br = $fc->file_stat('/my/src/dir', $ar); Return: $br - hash array ref and can be accessed as ${$ar}{$k}{$itm}, where $k is rdir and the $itm are
size - file size in bytes
time - modification time in Perl time
file - file name
pdir - parent directoryThis method also adds the following elements additional to 'file', 'pdir', and 'path' in the $ar array:
prop - file stat array
rdir - relative file name to the $dir
The following lists the elements in the stat array:
file stat array - ${$far}[$i]{prop}:
0 dev device number of filesystem
1 ino inode number
2 mode file mode (type and permissions)
3 nlink number of (hard) links to the file
4 uid numeric user ID of file's owner
5 gid numeric group ID of file's owner
6 rdev the device identifier (special files only)
7 size total size of file, in bytes
8 atime last access time in seconds since the epoch
9 mtime last modify time in seconds since the epoch
10 ctime inode change time (NOT creation time!) in seconds
sinc e the epoch
11 blksize preferred block size for file system I/O
12 blocks actual number of blocks allocatedThis method converts the array into a hash array and add additional elements to the input array as well.
AUTHOR
File::Xcopy is written by Hanming Tu <hanming_tu@yahoo.com>.