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

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

mkpath

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

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.

basename

Returns the last portion of a filename (typically, the filename itself without any leading directory). A deprecated filename() alias for basename() also exists.

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.61 2005/05/13 01:48:23 jagerman Exp $