- NAME
- SYNOPSIS
- DESCRIPTION
- FUNCTIONS

- find
- move
- del
- deldir
- copy
- mkpath
- parsefile
- dirname
- basename
- expand

- SEE ALSO
- MAINTAINER
- COPYRIGHT
- VERSION

# 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.64 2007/02/10 17:45:41 sbeck Exp $