NAME

GT::File::Tools - Export tools for dealing with files

SYNOPSIS

    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.
    rmkdir "/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 = filename("/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");

DESCRIPTION

GT::File::Tools is designed to export requested functions into your namespace. These function perform various file operations.

FUNCTIONS

GT::File::Tools exports functions to your namespace. Here is a list of the functions you can request to be exported.

find

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:

globbing
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.

error_handler
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).

no_chdir
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.

dirs_first
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.

files_only
This option tells find to run the callback only for each file found and not for each directory. Off by default.

dirs_only
This option tells find to run the callback only for each directory found and not for each file. Off by default.

max_depth
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

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:

globbing
error_handler
max_depth

del

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:

error_handler
globbing

deldir

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:

error_handler
globbing
max_depth

copy

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:

set_perms
This option will preserve permissions. i.e.: if the original file is set 755, the copy will also be set 755. It defaults on.

set_owner
This option will preserver file ownership. Note: you must be root to be able to change ownerhsip of a file. This defaults off.

set_time
This option will preserve file modification time.

preserve_all
This option sets set_perms, set_owner and set_time on.

error_handler
globbing
max_depth

rmkdir

rmkdir recursively makes a directory. It takes the same arguments as perl's mkdir():

    rmkdir("/home/alex/create/these/dirs", 0755) or die "Can't rmkdir: $!";

parsefile

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");

dirname

Returns the directory portion of a filename.

filename

Returns the file portion of a filename.

expand

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.

SEE ALSO

This module depends on perl's Cwd module for getting the current working directory. It also uses GT::AutoLoader to load on demand functions.

MAINTAINER

Scott Beck

COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

VERSION

Revision: $Id: Tools.pm,v 1.53 2004/02/17 01:33:07 jagerman Exp $