581 lines
14 KiB
HTML
581 lines
14 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>GT::File::Tools - Export tools for dealing with files</title>
|
|
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
|
|
|
|
<style type="text/css">
|
|
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
|
|
/* $MVD$:fontset("Arial","Arial") */
|
|
/* $MVD$:fontset("Arial Black","Arial Black") */
|
|
/* $MVD$:fontset("Algerian","Algerian") */
|
|
|
|
|
|
body {
|
|
background-color: white;
|
|
font-family: Verdana, Arial, sans-serif;
|
|
font-size: small;
|
|
color: black;
|
|
}
|
|
|
|
|
|
p {
|
|
background-color : white;
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
h1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
background-color : white;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
h2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : medium;
|
|
font-weight : bold;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h3 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : maroon;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h5 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h6 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
ul {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
ol {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
li {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
th {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
td {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dd {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dt {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
code {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
pre {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-H1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : 14.0pt;
|
|
background-color : transparent;
|
|
background-image : none;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
.mvd-H2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 12.0pt;
|
|
color : blue;
|
|
}
|
|
|
|
|
|
p.indent {
|
|
font-family : "Verdana, Arial, sans-serif";
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-indent {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
pre.programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE-programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE {
|
|
font-size : 9.0pt;
|
|
}
|
|
|
|
|
|
p.note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-H4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : normal;
|
|
font-size : 9.0pt;
|
|
color : black;
|
|
margin-left : 6.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 10.0pt;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-BODY {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
p.indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
|
|
|
|
.mvd-P-indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
<p><a name="__index__"></a></p>
|
|
<!-- INDEX BEGIN -->
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#functions">FUNCTIONS</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#find">find</a></li>
|
|
<li><a href="#move">move</a></li>
|
|
<li><a href="#del">del</a></li>
|
|
<li><a href="#deldir">deldir</a></li>
|
|
<li><a href="#copy">copy</a></li>
|
|
<li><a href="#mkpath">mkpath</a></li>
|
|
<li><a href="#parsefile">parsefile</a></li>
|
|
<li><a href="#dirname">dirname</a></li>
|
|
<li><a href="#basename">basename</a></li>
|
|
<li><a href="#expand">expand</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#maintainer">MAINTAINER</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
<li><a href="#version">VERSION</a></li>
|
|
</ul>
|
|
<!-- INDEX END -->
|
|
|
|
<hr />
|
|
<p>
|
|
</p>
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>GT::File::Tools - Export tools for dealing with files</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
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";</pre>
|
|
<pre>
|
|
# Remove a list of files.
|
|
del @files;</pre>
|
|
<pre>
|
|
# Remove a users home directory
|
|
deldir "/home/foo";</pre>
|
|
<pre>
|
|
# Copy a file
|
|
copy "file1", "file2";</pre>
|
|
<pre>
|
|
# Recursively copy a directory.
|
|
copy "/home/user", "/home/user.bak";</pre>
|
|
<pre>
|
|
# Recursively make a directory.
|
|
mkpath "/home/user/www/cgi-bin", 0755;</pre>
|
|
<pre>
|
|
# Parse a filename into directory, file and is_relative components
|
|
my ($dir, $file, $is_rel) = parsefile("/home/foo/file.txt");</pre>
|
|
<pre>
|
|
# Get the file portion of a filename
|
|
my $file = basename("/home/foo/file.txt");</pre>
|
|
<pre>
|
|
# Get the directory portion of a filename.
|
|
my $dir = dirname("/home/foo/file.txt");</pre>
|
|
<pre>
|
|
# Use shell like expansion to get a list of absolute files.
|
|
my @src = expand("*.c", "*.h");</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>GT::File::Tools is designed to export requested functions into your namespace.
|
|
These function perform various file operations.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="functions">FUNCTIONS</a></h1>
|
|
<p>GT::File::Tools exports functions to your namespace. Here is a list of the
|
|
functions you can request to be exported.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="find">find</a></h2>
|
|
<p><code>find</code> takes three parameters: directory to search in, callback to run for
|
|
each file and/or directory found, and a hash ref of options. <strong>Note</strong>: this is
|
|
the opposite order of File::Find's <code>find()</code> function! The following options
|
|
can be passed set:</p>
|
|
<dl>
|
|
<dt><strong><a name="item_globbing">globbing</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Expand filenames in the same way as the unix shell:
|
|
</dd>
|
|
<dd>
|
|
<pre>
|
|
find("/home/a*", sub { print shift; }, { globbing => 1 });</pre>
|
|
</dd>
|
|
<dd>
|
|
<p>would fine all home directories starting with the letter a. This option is
|
|
off by default.</p>
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_error_handler">error_handler</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
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).
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_no_chdir">no_chdir</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
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.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_dirs_first">dirs_first</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
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.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_files_only">files_only</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
This option tells find to run the callback only for each file found
|
|
and not for each directory. Off by default.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_dirs_only">dirs_only</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
This option tells find to run the callback only for each directory found
|
|
and not for each file. Off by default.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_max_depth">max_depth</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
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.
|
|
</dd>
|
|
<p></p></dl>
|
|
<p>
|
|
</p>
|
|
<h2><a name="move">move</a></h2>
|
|
<p><code>move</code> has the same syntax as the system mv command:</p>
|
|
<pre>
|
|
move 'file', 'file2';
|
|
move 'file1', 'file2', 'dir';
|
|
move 'file1', 'file2', 'dir3', 'dir';
|
|
move '*.c', 'dir', { globbing => 1 };</pre>
|
|
<p>The only difference is the last argument can be a hash ref of options. The
|
|
following options are allowed:</p>
|
|
<dl>
|
|
<dt><strong>globbing</strong><br />
|
|
</dt>
|
|
<dt><strong>error_handler</strong><br />
|
|
</dt>
|
|
<dt><strong>max_depth</strong><br />
|
|
</dt>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<h2><a name="del">del</a></h2>
|
|
<p><code>del</code> has the same syntax as the rm system command, but it can not remove
|
|
directories. Use <code>deldir</code> below to recursively remove files.</p>
|
|
<pre>
|
|
del 'file1';
|
|
del '*.c', { globbing => 1 };
|
|
del 'a', 'b', 'c';</pre>
|
|
<p>It takes a list of files or directories to delete, and an optional hash ref
|
|
of options. The following options are allowed:</p>
|
|
<dl>
|
|
<dt><strong>error_handler</strong><br />
|
|
</dt>
|
|
<dt><strong>globbing</strong><br />
|
|
</dt>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<h2><a name="deldir">deldir</a></h2>
|
|
<p><code>deldir</code> is similiar to <code>del</code>, but allows recursive deletes of directories:</p>
|
|
<pre>
|
|
deldir 'file1';
|
|
deldir 'dir11', 'dir2', 'dir3';
|
|
deldir '/home/a*', { globbing => 1 };</pre>
|
|
<p>It takes a list of files and/or directories to remove, and an optional hash ref
|
|
of options. The following options are allowed:</p>
|
|
<dl>
|
|
<dt><strong>error_handler</strong><br />
|
|
</dt>
|
|
<dt><strong>globbing</strong><br />
|
|
</dt>
|
|
<dt><strong>max_depth</strong><br />
|
|
</dt>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<h2><a name="copy">copy</a></h2>
|
|
<p><code>copy</code> is similiar to the system cp command:</p>
|
|
<pre>
|
|
copy 'file1', 'file2';
|
|
copy 'file1', 'file2', 'file3', 'dir1';
|
|
copy '*.c', '/usr/local/src', { globbing => 1 };
|
|
copy</pre>
|
|
<p>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:</p>
|
|
<dl>
|
|
<dt><strong><a name="item_set_perms">set_perms</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
This option will preserve permissions. i.e.: if the original file is set 755,
|
|
the copy will also be set 755. It defaults on.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_set_owner">set_owner</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
This option will preserver file ownership. Note: you must be root to be able
|
|
to change ownerhsip of a file. This defaults off.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_set_time">set_time</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
This option will preserve file modification time.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_preserve_all">preserve_all</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
This option sets set_perms, set_owner and set_time on.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong>error_handler</strong><br />
|
|
</dt>
|
|
<dt><strong>globbing</strong><br />
|
|
</dt>
|
|
<dt><strong>max_depth</strong><br />
|
|
</dt>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<h2><a name="mkpath">mkpath</a></h2>
|
|
<p><code>mkpath</code> recursively makes a directory. It takes the same arguments as
|
|
perl's mkdir():</p>
|
|
<pre>
|
|
mkpath("/home/alex/create/these/dirs", 0755) or die "Can't mkpath: $!";</pre>
|
|
<p>For compatibility with older module versions, <code>rmkdir()</code> is an alias for
|
|
mkpath().</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="parsefile">parsefile</a></h2>
|
|
<p>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:</p>
|
|
<pre>
|
|
my ($directory, $file, $is_relative) = parsefile("../foo/bar.txt");</pre>
|
|
<p>
|
|
</p>
|
|
<h2><a name="dirname">dirname</a></h2>
|
|
<p>Returns the directory portion of a filename.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="basename">basename</a></h2>
|
|
<p>Returns the last portion of a filename (typically, the filename itself without
|
|
any leading directory). A deprecated <code>filename()</code> alias for <code>basename()</code> also
|
|
exists.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="expand">expand</a></h2>
|
|
<p>Uses shell like expansion to expand a list of filenames to full paths. For
|
|
example:</p>
|
|
<pre>
|
|
my @source = expand("*.c", "*.h");
|
|
my @homedirs = expand("/home/*");</pre>
|
|
<p>If you pass in relative paths, expand always returns absolute paths of
|
|
expanded files. <strong>Note</strong>: this does not actually go to the shell.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p>This module depends on perl's Cwd module for getting the current working
|
|
directory. It also uses GT::AutoLoader to load on demand functions.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="maintainer">MAINTAINER</a></h1>
|
|
<p>Scott Beck</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved.
|
|
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="version">VERSION</a></h1>
|
|
<p>Revision: $Id: Tools.pm,v 1.61 2005/05/13 01:48:23 jagerman Exp $</p>
|
|
|
|
</body>
|
|
|
|
</html>
|