discourse-legacysite-perl/site/glist/templates/help/GT/File/Tools.html

581 lines
14 KiB
HTML
Raw Normal View History

2024-06-17 12:24:05 +00:00
<!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 &quot;/home/user&quot;, sub { print shift };
# Rename a file1 to file2.
move &quot;file1&quot;, &quot;file2&quot;;</pre>
<pre>
# Remove a list of files.
del @files;</pre>
<pre>
# Remove a users home directory
deldir &quot;/home/foo&quot;;</pre>
<pre>
# Copy a file
copy &quot;file1&quot;, &quot;file2&quot;;</pre>
<pre>
# Recursively copy a directory.
copy &quot;/home/user&quot;, &quot;/home/user.bak&quot;;</pre>
<pre>
# Recursively make a directory.
mkpath &quot;/home/user/www/cgi-bin&quot;, 0755;</pre>
<pre>
# Parse a filename into directory, file and is_relative components
my ($dir, $file, $is_rel) = parsefile(&quot;/home/foo/file.txt&quot;);</pre>
<pre>
# Get the file portion of a filename
my $file = basename(&quot;/home/foo/file.txt&quot;);</pre>
<pre>
# Get the directory portion of a filename.
my $dir = dirname(&quot;/home/foo/file.txt&quot;);</pre>
<pre>
# Use shell like expansion to get a list of absolute files.
my @src = expand(&quot;*.c&quot;, &quot;*.h&quot;);</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(&quot;/home/a*&quot;, sub { print shift; }, { globbing =&gt; 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 =&gt; 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 =&gt; 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 =&gt; 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 =&gt; 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(&quot;/home/alex/create/these/dirs&quot;, 0755) or die &quot;Can't mkpath: $!&quot;;</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(&quot;../foo/bar.txt&quot;);</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(&quot;*.c&quot;, &quot;*.h&quot;);
my @homedirs = expand(&quot;/home/*&quot;);</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>