GT::File::Tools - Export tools for dealing with files
use GT::File::Tools qw/:all/; # Find all files in a users home directory. find "/home/user", sub { print shift }; # Rename a file1 to file2. move "file1", "file2";
# Remove a list of files. del @files;
# Remove a users home directory deldir "/home/foo";
# Copy a file copy "file1", "file2";
# Recursively copy a directory. copy "/home/user", "/home/user.bak";
# Recursively make a directory. mkpath "/home/user/www/cgi-bin", 0755;
# Parse a filename into directory, file and is_relative components my ($dir, $file, $is_rel) = parsefile("/home/foo/file.txt");
# Get the file portion of a filename my $file = basename("/home/foo/file.txt");
# Get the directory portion of a filename. my $dir = dirname("/home/foo/file.txt");
# Use shell like expansion to get a list of absolute files. my @src = expand("*.c", "*.h");
GT::File::Tools is designed to export requested functions into your namespace. These function perform various file operations.
GT::File::Tools exports functions to your namespace. Here is a list of the functions you can request to be exported.
find
takes three parameters: directory to search in, callback to run for
each file and/or directory found, and a hash ref of options. Note: this is
the opposite order of File::Find's find()
function! The following options
can be passed set:
Expand filenames in the same way as the unix shell:
find("/home/a*", sub { print shift; }, { globbing => 1 });
would fine all home directories starting with the letter a. This option is off by default.
A code ref that is run whenever find encounters an error. If the callback returns 0, find will stop immediately, otherwise find will continue searching (default).
By default, find will chdir into the directories it is searching as this results in a dramatic performance improvement. Upon completion, find will chdir back to the original directory. This behavior is on by default.
This option controls the order find traverses. It defaults on, and means find will go down directories first before looking at files. This is essential for recursively deleting a directory.
This option tells find to run the callback only for each file found and not for each directory. Off by default.
This option tells find to run the callback only for each directory found and not for each file. Off by default.
Defaults to 1000, this option controls how deep a directory structure find will traverse. Meant mainly as a safety, and should not need to be adjusted.
move
has the same syntax as the system mv command:
move 'file', 'file2'; move 'file1', 'file2', 'dir'; move 'file1', 'file2', 'dir3', 'dir'; move '*.c', 'dir', { globbing => 1 };
The only difference is the last argument can be a hash ref of options. The following options are allowed:
del
has the same syntax as the rm system command, but it can not remove
directories. Use deldir
below to recursively remove files.
del 'file1'; del '*.c', { globbing => 1 }; del 'a', 'b', 'c';
It takes a list of files or directories to delete, and an optional hash ref of options. The following options are allowed:
deldir
is similiar to del
, but allows recursive deletes of directories:
deldir 'file1'; deldir 'dir11', 'dir2', 'dir3'; deldir '/home/a*', { globbing => 1 };
It takes a list of files and/or directories to remove, and an optional hash ref of options. The following options are allowed:
copy
is similiar to the system cp command:
copy 'file1', 'file2'; copy 'file1', 'file2', 'file3', 'dir1'; copy '*.c', '/usr/local/src', { globbing => 1 }; copy
It copies a source file to a destination file or directory. You can also specify multiple source files, and copy them into a single directory. The last argument should be a hash ref of options:
This option will preserve permissions. i.e.: if the original file is set 755, the copy will also be set 755. It defaults on.
This option will preserver file ownership. Note: you must be root to be able to change ownerhsip of a file. This defaults off.
This option will preserve file modification time.
This option sets set_perms, set_owner and set_time on.
mkpath
recursively makes a directory. It takes the same arguments as
perl's mkdir():
mkpath("/home/alex/create/these/dirs", 0755) or die "Can't mkpath: $!";
For compatibility with older module versions, rmkdir()
is an alias for
mkpath().
This function takes any type of filename (relative, fullpath, etc) and returns the inputs directory, file, and whether it is a relative path or not. For example:
my ($directory, $file, $is_relative) = parsefile("../foo/bar.txt");
Returns the directory portion of a filename.
Returns the last portion of a filename (typically, the filename itself without
any leading directory). A deprecated filename()
alias for basename()
also
exists.
Uses shell like expansion to expand a list of filenames to full paths. For example:
my @source = expand("*.c", "*.h"); my @homedirs = expand("/home/*");
If you pass in relative paths, expand always returns absolute paths of expanded files. Note: this does not actually go to the shell.
This module depends on perl's Cwd module for getting the current working directory. It also uses GT::AutoLoader to load on demand functions.
Scott Beck
Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/
Revision: $Id: Tools.pm,v 1.64 2007/02/10 17:45:41 sbeck Exp $