Added Cyg-Win
This commit is contained in:
parent
82cbc206eb
commit
413c315806
10586 changed files with 3806249 additions and 0 deletions
1484
Agent-Windows/OGP64/usr/share/doc/perl/AUTHORS
Normal file
1484
Agent-Windows/OGP64/usr/share/doc/perl/AUTHORS
Normal file
File diff suppressed because it is too large
Load diff
69
Agent-Windows/OGP64/usr/share/doc/perl/Changes
Normal file
69
Agent-Windows/OGP64/usr/share/doc/perl/Changes
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
For an overview of what's changed in this release, see pod/perldelta.pod.
|
||||
|
||||
For the details of changes in previous releases, see the individual
|
||||
perlNNNdelta.pod files. For example, pod/perl588delta.pod describes the
|
||||
changes between versions 5.8.7 and 5.8.8.
|
||||
|
||||
For a list of contributors to perl, see AUTHORS.
|
||||
|
||||
If you need a detailed commit history (i.e. descriptions of each
|
||||
individual commit), you can view the git version control history online
|
||||
at https://github.com/Perl/perl5. Or, you can download a copy of the git
|
||||
repository and then run a command like
|
||||
|
||||
git log --name-status v5.12.0..v5.14.0
|
||||
|
||||
to view all the changes between 5.12.0 and 5.14.0.
|
||||
|
||||
See pod/perlgit.pod for more details on using git and accessing the
|
||||
commit history.
|
||||
|
||||
In perl releases prior to 2009, the source tarball included a collection
|
||||
of Changes files that listed the individual commits that had gone into
|
||||
each release. Since these files had become very large, and since the
|
||||
same information is now freely available online, it was decided to remove
|
||||
them from subsequent releases.
|
||||
|
||||
If you need access to these removed files, then they can be be found most
|
||||
recently in the 5.8.9 and 5.10.0 tarballs, at
|
||||
|
||||
http://www.cpan.org/src/perl-5.8.9.tar.gz
|
||||
http://www.cpan.org/src/5.0/perl-5.10.0.tar.gz
|
||||
|
||||
The contents of the files in question can mostly be regenerated using git
|
||||
commands. The following table shows the equivalents. Note that the files
|
||||
prior to Changes5.005 were not simple lists of commits, so can't be
|
||||
recreated just by running the git command. As it happens, even the latter
|
||||
ones are not exact equivalents. This is due to a combination of errors in
|
||||
the original Changes files, and "impedance mismatches" when the previous
|
||||
version control data was imported into git in December 2008.
|
||||
|
||||
For example, the Changes5.005 file includes 206 spurious entries from the
|
||||
maint5.004 Perforce branch.
|
||||
|
||||
Running the following command with the range argument shown in the table
|
||||
will produce *approximately* the same list of changes in the specified
|
||||
file shown from the listed tarball.
|
||||
|
||||
git log --name-status <range>
|
||||
|
||||
file tarball <range> argument to 'git log'
|
||||
------------ ------ --------------------------------
|
||||
Changes5.000 Either N/A
|
||||
Changes5.001 Either perl-5.000..perl-5.001
|
||||
Changes5.002 Either perl-5.001..perl-5.002
|
||||
Changes5.003 Either perl-5.002..perl-5.003
|
||||
Changes5.004 Either perl-5.003..perl-5.004
|
||||
Changes5.005 Either perl-5.004..perl-5.005_03
|
||||
Changes5.6 Either perl-5.005_03..perl-5.6.0
|
||||
Changes5.8 Either perl-5.6.0..perl-5.8.0
|
||||
Changes5.8.1 5.8.9 perl-5.8.0..perl-5.8.1 ^1ede746b
|
||||
Changes5.8.2 5.8.9 perl-5.8.1..perl-5.8.2
|
||||
Changes5.8.3 5.8.9 perl-5.8.2..perl-5.8.3
|
||||
Changes5.8.4 5.8.9 perl-5.8.3..perl-5.8.4
|
||||
Changes5.8.5 5.8.9 perl-5.8.4..perl-5.8.5 ^3a81978b
|
||||
Changes5.8.6 5.8.9 perl-5.8.5..perl-5.8.6 ^498d59dd
|
||||
Changes5.8.7 5.8.9 perl-5.8.6..perl-5.8.7
|
||||
Changes5.8.8 5.8.9 perl-5.8.7..perl-5.8.8
|
||||
Changes 5.8.9 perl-5.8.8..perl-5.8.9
|
||||
Changes 5.10.0 perl-5.8.0..perl-5.10.0
|
||||
122
Agent-Windows/OGP64/usr/share/doc/perl/README
Normal file
122
Agent-Windows/OGP64/usr/share/doc/perl/README
Normal file
|
|
@ -0,0 +1,122 @@
|
|||
Perl is Copyright (C) 1993 - 2025 by Larry Wall and others.
|
||||
|
||||
All rights reserved.
|
||||
|
||||
# ABOUT PERL
|
||||
|
||||
Perl is a general-purpose programming language originally developed for
|
||||
text manipulation and now used for a wide range of tasks including
|
||||
system administration, web development, network programming, GUI
|
||||
development, and more.
|
||||
|
||||
The language is intended to be practical (easy to use, efficient,
|
||||
complete) rather than beautiful (tiny, elegant, minimal). Its major
|
||||
features are that it's easy to use, supports both procedural and
|
||||
object-oriented (OO) programming, has powerful built-in support for text
|
||||
processing, and has one of the world's most impressive collections of
|
||||
third-party modules.
|
||||
|
||||
For an introduction to the language's features, see pod/perlintro.pod.
|
||||
|
||||
For a discussion of the important changes in this release, see
|
||||
pod/perldelta.pod.
|
||||
|
||||
There are also many Perl books available, covering a wide variety of topics,
|
||||
from various publishers. See pod/perlbook.pod for more information.
|
||||
|
||||
|
||||
# INSTALLATION
|
||||
|
||||
If you're using a relatively modern operating system and want to
|
||||
install this version of Perl locally, run the following commands:
|
||||
|
||||
./Configure -des -Dprefix=$HOME/localperl
|
||||
make test
|
||||
make install
|
||||
|
||||
This will configure and compile perl for your platform, run the regression
|
||||
tests, and install perl in a subdirectory "localperl" of your home directory.
|
||||
|
||||
If you run into any trouble whatsoever or you need to install a customized
|
||||
version of Perl, you should read the detailed instructions in the "INSTALL"
|
||||
file that came with this distribution. Additionally, there are a number of
|
||||
"README" files with hints and tips about building and using Perl on a wide
|
||||
variety of platforms, some more common than others.
|
||||
|
||||
Once you have Perl installed, a wealth of documentation is available to you
|
||||
through the 'perldoc' tool. To get started, run this command:
|
||||
|
||||
perldoc perl
|
||||
|
||||
|
||||
# IF YOU RUN INTO TROUBLE
|
||||
|
||||
Perl is a large and complex system that's used for everything from
|
||||
knitting to rocket science. If you run into trouble, it's quite
|
||||
likely that someone else has already solved the problem you're
|
||||
facing. Once you've exhausted the documentation, please report bugs to us
|
||||
at the GitHub issue tracker at https://github.com/Perl/perl5/issues
|
||||
|
||||
While it was current when we made it available, Perl is constantly evolving
|
||||
and there may be a more recent version that fixes bugs you've run into or
|
||||
adds new features that you might find useful.
|
||||
|
||||
You can always find the latest version of perl on a CPAN (Comprehensive Perl
|
||||
Archive Network) site near you at https://www.cpan.org/src/
|
||||
|
||||
If you want to submit a simple patch to the perl source, see the "SUPER
|
||||
QUICK PATCH GUIDE" in pod/perlhack.pod.
|
||||
|
||||
Just a personal note: I want you to know that I create nice things like this
|
||||
because it pleases the Author of my story. If this bothers you, then your
|
||||
notion of Authorship needs some revision. But you can use perl anyway. :-)
|
||||
|
||||
The author.
|
||||
|
||||
|
||||
# LICENSING
|
||||
|
||||
This program is free software; you can redistribute it and/or modify
|
||||
it under the terms of either:
|
||||
|
||||
a. the GNU General Public License as published by the Free
|
||||
Software Foundation; either version 1, or (at your option) any
|
||||
later version, or
|
||||
|
||||
b. the "Artistic License" which comes with this Kit.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either
|
||||
the GNU General Public License or the Artistic License for more details.
|
||||
|
||||
You should have received a copy of the Artistic License with this
|
||||
Kit, in the file named "Artistic". If not, I'll be glad to provide one.
|
||||
|
||||
You should also have received a copy of the GNU General Public License
|
||||
along with this program in the file named "Copying". If not, write to the
|
||||
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
|
||||
Boston, MA 02110-1301, USA or visit their web page on the internet at
|
||||
https://www.gnu.org/copyleft/gpl.html.
|
||||
|
||||
For those of you that choose to use the GNU General Public License,
|
||||
my interpretation of the GNU General Public License is that no Perl
|
||||
script falls under the terms of the GPL unless you explicitly put
|
||||
said script under the terms of the GPL yourself. Furthermore, any
|
||||
object code linked with perl does not automatically fall under the
|
||||
terms of the GPL, provided such object code only adds definitions
|
||||
of subroutines and variables, and does not otherwise impair the
|
||||
resulting interpreter from executing any standard Perl script. I
|
||||
consider linking in C subroutines in this manner to be the moral
|
||||
equivalent of defining subroutines in the Perl language itself. You
|
||||
may sell such an object file as proprietary provided that you provide
|
||||
or offer to provide the Perl source, as specified by the GNU General
|
||||
Public License. (This is merely an alternate way of specifying input
|
||||
to the program.) You may also sell a binary produced by the dumping of
|
||||
a running Perl script that belongs to you, provided that you provide or
|
||||
offer to provide the Perl source as specified by the GPL. (The
|
||||
fact that a Perl interpreter and your code are in the same binary file
|
||||
is, in this case, a form of mere aggregation.) This is my interpretation
|
||||
of the GPL. If you still have concerns or difficulties understanding
|
||||
my intent, feel free to contact me. Of course, the Artistic License
|
||||
spells all this out for your protection, so you may prefer to use that.
|
||||
|
|
@ -0,0 +1,526 @@
|
|||
<?xml version="1.0" ?>
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<!-- saved from url=(0017)http://localhost/ -->
|
||||
<title>Error - Error/exception handling in an OO-ish way</title>
|
||||
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||||
<link rev="made" href="mailto:ASSI@walter.nonet" />
|
||||
</head>
|
||||
|
||||
<body id="_podtop_">
|
||||
<table border="0" width="100%" cellspacing="0" cellpadding="3">
|
||||
<tr><td class="_podblock_" style="background-color: #cccccc; color: #000" valign="middle">
|
||||
<big><strong><span class="_podblock_"> Error - Error/exception handling in an OO-ish way</span></strong></big>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
<ul id="index">
|
||||
<li><a href="#NAME">NAME</a></li>
|
||||
<li><a href="#VERSION">VERSION</a></li>
|
||||
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
|
||||
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
|
||||
<li><a href="#WARNING">WARNING</a></li>
|
||||
<li><a href="#PROCEDURAL-INTERFACE">PROCEDURAL INTERFACE</a></li>
|
||||
<li><a href="#COMPATIBILITY">COMPATIBILITY</a></li>
|
||||
<li><a href="#CLASS-INTERFACE">CLASS INTERFACE</a>
|
||||
<ul>
|
||||
<li><a href="#CONSTRUCTORS">CONSTRUCTORS</a></li>
|
||||
<li><a href="#STATIC-METHODS">STATIC METHODS</a></li>
|
||||
<li><a href="#OBJECT-METHODS">OBJECT METHODS</a></li>
|
||||
<li><a href="#OVERLOAD-METHODS">OVERLOAD METHODS</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#PRE-DEFINED-ERROR-CLASSES">PRE-DEFINED ERROR CLASSES</a>
|
||||
<ul>
|
||||
<li><a href="#Error%3A%3ASimple">Error::Simple</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#Error%3A%3AObjectifyCallback">$Error::ObjectifyCallback</a></li>
|
||||
<li><a href="#MESSAGE-HANDLERS">MESSAGE HANDLERS</a>
|
||||
<ul>
|
||||
<li><a href="#EXAMPLE">EXAMPLE</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#SEE-ALSO">SEE ALSO</a></li>
|
||||
<li><a href="#KNOWN-BUGS">KNOWN BUGS</a></li>
|
||||
<li><a href="#AUTHORS">AUTHORS</a></li>
|
||||
<li><a href="#MAINTAINER">MAINTAINER</a></li>
|
||||
<li><a href="#PAST-MAINTAINERS">PAST MAINTAINERS</a></li>
|
||||
<li><a href="#COPYRIGHT">COPYRIGHT</a></li>
|
||||
<li><a href="#SUPPORT">SUPPORT</a>
|
||||
<ul>
|
||||
<li><a href="#Websites">Websites</a></li>
|
||||
<li><a href="#Bugs-Feature-Requests">Bugs / Feature Requests</a></li>
|
||||
<li><a href="#Source-Code">Source Code</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#AUTHOR">AUTHOR</a></li>
|
||||
<li><a href="#BUGS">BUGS</a></li>
|
||||
<li><a href="#COPYRIGHT-AND-LICENSE">COPYRIGHT AND LICENSE</a></li>
|
||||
</ul>
|
||||
|
||||
<a href="#_podtop_"><h1 id="NAME">NAME</h1></a>
|
||||
|
||||
<p>Error - Error/exception handling in an OO-ish way</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="VERSION">VERSION</h1></a>
|
||||
|
||||
<p>version 0.17030</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="SYNOPSIS">SYNOPSIS</h1></a>
|
||||
|
||||
<pre><code>use Error qw(:try);
|
||||
|
||||
throw Error::Simple( "A simple error");
|
||||
|
||||
sub xyz {
|
||||
...
|
||||
record Error::Simple("A simple error")
|
||||
and return;
|
||||
}
|
||||
|
||||
unlink($file) or throw Error::Simple("$file: $!",$!);
|
||||
|
||||
try {
|
||||
do_some_stuff();
|
||||
die "error!" if $condition;
|
||||
throw Error::Simple "Oops!" if $other_condition;
|
||||
}
|
||||
catch Error::IO with {
|
||||
my $E = shift;
|
||||
print STDERR "File ", $E->{'-file'}, " had a problem\n";
|
||||
}
|
||||
except {
|
||||
my $E = shift;
|
||||
my $general_handler=sub {send_message $E->{-description}};
|
||||
return {
|
||||
UserException1 => $general_handler,
|
||||
UserException2 => $general_handler
|
||||
};
|
||||
}
|
||||
otherwise {
|
||||
print STDERR "Well I don't know what to say\n";
|
||||
}
|
||||
finally {
|
||||
close_the_garage_door_already(); # Should be reliable
|
||||
}; # Don't forget the trailing ; or you might be surprised</code></pre>
|
||||
|
||||
<a href="#_podtop_"><h1 id="DESCRIPTION">DESCRIPTION</h1></a>
|
||||
|
||||
<p>The <code>Error</code> package provides two interfaces. Firstly <code>Error</code> provides a procedural interface to exception handling. Secondly <code>Error</code> is a base class for errors/exceptions that can either be thrown, for subsequent catch, or can simply be recorded.</p>
|
||||
|
||||
<p>Errors in the class <code>Error</code> should not be thrown directly, but the user should throw errors from a sub-class of <code>Error</code>.</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="WARNING">WARNING</h1></a>
|
||||
|
||||
<p>Using the "Error" module is <b>no longer recommended</b> due to the black-magical nature of its syntactic sugar, which often tends to break. Its maintainers have stopped actively writing code that uses it, and discourage people from doing so. See the "SEE ALSO" section below for better recommendations.</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="PROCEDURAL-INTERFACE">PROCEDURAL INTERFACE</h1></a>
|
||||
|
||||
<p><code>Error</code> exports subroutines to perform exception handling. These will be exported if the <code>:try</code> tag is used in the <code>use</code> line.</p>
|
||||
|
||||
<dl>
|
||||
|
||||
<dt id="try-BLOCK-CLAUSES">try BLOCK CLAUSES</dt>
|
||||
<dd>
|
||||
|
||||
<p><code>try</code> is the main subroutine called by the user. All other subroutines exported are clauses to the try subroutine.</p>
|
||||
|
||||
<p>The BLOCK will be evaluated and, if no error is throw, try will return the result of the block.</p>
|
||||
|
||||
<p><code>CLAUSES</code> are the subroutines below, which describe what to do in the event of an error being thrown within BLOCK.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="catch-CLASS-with-BLOCK">catch CLASS with BLOCK</dt>
|
||||
<dd>
|
||||
|
||||
<p>This clauses will cause all errors that satisfy <code>$err->isa(CLASS)</code> to be caught and handled by evaluating <code>BLOCK</code>.</p>
|
||||
|
||||
<p><code>BLOCK</code> will be passed two arguments. The first will be the error being thrown. The second is a reference to a scalar variable. If this variable is set by the catch block then, on return from the catch block, try will continue processing as if the catch block was never found. The error will also be available in <code>$@</code>.</p>
|
||||
|
||||
<p>To propagate the error the catch block may call <code>$err->throw</code></p>
|
||||
|
||||
<p>If the scalar reference by the second argument is not set, and the error is not thrown. Then the current try block will return with the result from the catch block.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="except-BLOCK">except BLOCK</dt>
|
||||
<dd>
|
||||
|
||||
<p>When <code>try</code> is looking for a handler, if an except clause is found <code>BLOCK</code> is evaluated. The return value from this block should be a HASHREF or a list of key-value pairs, where the keys are class names and the values are CODE references for the handler of errors of that type.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="otherwise-BLOCK">otherwise BLOCK</dt>
|
||||
<dd>
|
||||
|
||||
<p>Catch any error by executing the code in <code>BLOCK</code></p>
|
||||
|
||||
<p>When evaluated <code>BLOCK</code> will be passed one argument, which will be the error being processed. The error will also be available in <code>$@</code>.</p>
|
||||
|
||||
<p>Only one otherwise block may be specified per try block</p>
|
||||
|
||||
</dd>
|
||||
<dt id="finally-BLOCK">finally BLOCK</dt>
|
||||
<dd>
|
||||
|
||||
<p>Execute the code in <code>BLOCK</code> either after the code in the try block has successfully completed, or if the try block throws an error then <code>BLOCK</code> will be executed after the handler has completed.</p>
|
||||
|
||||
<p>If the handler throws an error then the error will be caught, the finally block will be executed and the error will be re-thrown.</p>
|
||||
|
||||
<p>Only one finally block may be specified per try block</p>
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<a href="#_podtop_"><h1 id="COMPATIBILITY">COMPATIBILITY</h1></a>
|
||||
|
||||
<p><a>Moose</a> exports a keyword called <code>with</code> which clashes with Error's. This example returns a prototype mismatch error:</p>
|
||||
|
||||
<pre><code>package MyTest;
|
||||
|
||||
use warnings;
|
||||
use Moose;
|
||||
use Error qw(:try);</code></pre>
|
||||
|
||||
<p>(Thanks to <code>maik.hentsche@amd.com</code> for the report.).</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="CLASS-INTERFACE">CLASS INTERFACE</h1></a>
|
||||
|
||||
<h2 id="CONSTRUCTORS">CONSTRUCTORS</h2>
|
||||
|
||||
<p>The <code>Error</code> object is implemented as a HASH. This HASH is initialized with the arguments that are passed to it's constructor. The elements that are used by, or are retrievable by the <code>Error</code> class are listed below, other classes may add to these.</p>
|
||||
|
||||
<pre><code>-file
|
||||
-line
|
||||
-text
|
||||
-value
|
||||
-object</code></pre>
|
||||
|
||||
<p>If <code>-file</code> or <code>-line</code> are not specified in the constructor arguments then these will be initialized with the file name and line number where the constructor was called from.</p>
|
||||
|
||||
<p>If the error is associated with an object then the object should be passed as the <code>-object</code> argument. This will allow the <code>Error</code> package to associate the error with the object.</p>
|
||||
|
||||
<p>The <code>Error</code> package remembers the last error created, and also the last error associated with a package. This could either be the last error created by a sub in that package, or the last error which passed an object blessed into that package as the <code>-object</code> argument.</p>
|
||||
|
||||
<dl>
|
||||
|
||||
<dt id="Error-new">Error->new()</dt>
|
||||
<dd>
|
||||
|
||||
<p>See the Error::Simple documentation.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="throw-ARGS">throw ( [ ARGS ] )</dt>
|
||||
<dd>
|
||||
|
||||
<p>Create a new <code>Error</code> object and throw an error, which will be caught by a surrounding <code>try</code> block, if there is one. Otherwise it will cause the program to exit.</p>
|
||||
|
||||
<p><code>throw</code> may also be called on an existing error to re-throw it.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="with-ARGS">with ( [ ARGS ] )</dt>
|
||||
<dd>
|
||||
|
||||
<p>Create a new <code>Error</code> object and returns it. This is defined for syntactic sugar, eg</p>
|
||||
|
||||
<pre><code>die with Some::Error ( ... );</code></pre>
|
||||
|
||||
</dd>
|
||||
<dt id="record-ARGS">record ( [ ARGS ] )</dt>
|
||||
<dd>
|
||||
|
||||
<p>Create a new <code>Error</code> object and returns it. This is defined for syntactic sugar, eg</p>
|
||||
|
||||
<pre><code>record Some::Error ( ... )
|
||||
and return;</code></pre>
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<h2 id="STATIC-METHODS">STATIC METHODS</h2>
|
||||
|
||||
<dl>
|
||||
|
||||
<dt id="prior-PACKAGE">prior ( [ PACKAGE ] )</dt>
|
||||
<dd>
|
||||
|
||||
<p>Return the last error created, or the last error associated with <code>PACKAGE</code></p>
|
||||
|
||||
</dd>
|
||||
<dt id="flush-PACKAGE">flush ( [ PACKAGE ] )</dt>
|
||||
<dd>
|
||||
|
||||
<p>Flush the last error created, or the last error associated with <code>PACKAGE</code>.It is necessary to clear the error stack before exiting the package or uncaught errors generated using <code>record</code> will be reported.</p>
|
||||
|
||||
<pre><code>$Error->flush;</code></pre>
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<h2 id="OBJECT-METHODS">OBJECT METHODS</h2>
|
||||
|
||||
<dl>
|
||||
|
||||
<dt id="stacktrace">stacktrace</dt>
|
||||
<dd>
|
||||
|
||||
<p>If the variable <code>$Error::Debug</code> was non-zero when the error was created, then <code>stacktrace</code> returns a string created by calling <code>Carp::longmess</code>. If the variable was zero the <code>stacktrace</code> returns the text of the error appended with the filename and line number of where the error was created, providing the text does not end with a newline.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="object">object</dt>
|
||||
<dd>
|
||||
|
||||
<p>The object this error was associated with</p>
|
||||
|
||||
</dd>
|
||||
<dt id="file">file</dt>
|
||||
<dd>
|
||||
|
||||
<p>The file where the constructor of this error was called from</p>
|
||||
|
||||
</dd>
|
||||
<dt id="line">line</dt>
|
||||
<dd>
|
||||
|
||||
<p>The line where the constructor of this error was called from</p>
|
||||
|
||||
</dd>
|
||||
<dt id="text">text</dt>
|
||||
<dd>
|
||||
|
||||
<p>The text of the error</p>
|
||||
|
||||
</dd>
|
||||
<dt id="err-associate-obj">$err->associate($obj)</dt>
|
||||
<dd>
|
||||
|
||||
<p>Associates an error with an object to allow error propagation. I.e:</p>
|
||||
|
||||
<pre><code>$ber->encode(...) or
|
||||
return Error->prior($ber)->associate($ldap);</code></pre>
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<h2 id="OVERLOAD-METHODS">OVERLOAD METHODS</h2>
|
||||
|
||||
<dl>
|
||||
|
||||
<dt id="stringify">stringify</dt>
|
||||
<dd>
|
||||
|
||||
<p>A method that converts the object into a string. This method may simply return the same as the <code>text</code> method, or it may append more information. For example the file name and line number.</p>
|
||||
|
||||
<p>By default this method returns the <code>-text</code> argument that was passed to the constructor, or the string <code>"Died"</code> if none was given.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="value">value</dt>
|
||||
<dd>
|
||||
|
||||
<p>A method that will return a value that can be associated with the error. For example if an error was created due to the failure of a system call, then this may return the numeric value of <code>$!</code> at the time.</p>
|
||||
|
||||
<p>By default this method returns the <code>-value</code> argument that was passed to the constructor.</p>
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<a href="#_podtop_"><h1 id="PRE-DEFINED-ERROR-CLASSES">PRE-DEFINED ERROR CLASSES</h1></a>
|
||||
|
||||
<h2 id="Error::Simple">Error::Simple</h2>
|
||||
|
||||
<p>This class can be used to hold simple error strings and values. It's constructor takes two arguments. The first is a text value, the second is a numeric value. These values are what will be returned by the overload methods.</p>
|
||||
|
||||
<p>If the text value ends with <code>at file line 1</code> as $@ strings do, then this information will be used to set the <code>-file</code> and <code>-line</code> arguments of the error object.</p>
|
||||
|
||||
<p>This class is used internally if an eval'd block die's with an error that is a plain string. (Unless <code>$Error::ObjectifyCallback</code> is modified)</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="Error::ObjectifyCallback">$Error::ObjectifyCallback</h1></a>
|
||||
|
||||
<p>This variable holds a reference to a subroutine that converts errors that are plain strings to objects. It is used by Error.pm to convert textual errors to objects, and can be overridden by the user.</p>
|
||||
|
||||
<p>It accepts a single argument which is a hash reference to named parameters. Currently the only named parameter passed is <code>'text'</code> which is the text of the error, but others may be available in the future.</p>
|
||||
|
||||
<p>For example the following code will cause Error.pm to throw objects of the class MyError::Bar by default:</p>
|
||||
|
||||
<pre><code>sub throw_MyError_Bar
|
||||
{
|
||||
my $args = shift;
|
||||
my $err = MyError::Bar->new();
|
||||
$err->{'MyBarText'} = $args->{'text'};
|
||||
return $err;
|
||||
}
|
||||
|
||||
{
|
||||
local $Error::ObjectifyCallback = \&throw_MyError_Bar;
|
||||
|
||||
# Error handling here.
|
||||
}</code></pre>
|
||||
|
||||
<a href="#_podtop_"><h1 id="MESSAGE-HANDLERS">MESSAGE HANDLERS</h1></a>
|
||||
|
||||
<p><code>Error</code> also provides handlers to extend the output of the <code>warn()</code> perl function, and to handle the printing of a thrown <code>Error</code> that is not caught or otherwise handled. These are not installed by default, but are requested using the <code>:warndie</code> tag in the <code>use</code> line.</p>
|
||||
|
||||
<pre><code>use Error qw( :warndie );</code></pre>
|
||||
|
||||
<p>These new error handlers are installed in <code>$SIG{__WARN__}</code> and <code>$SIG{__DIE__}</code>. If these handlers are already defined when the tag is imported, the old values are stored, and used during the new code. Thus, to arrange for custom handling of warnings and errors, you will need to perform something like the following:</p>
|
||||
|
||||
<pre><code>BEGIN {
|
||||
$SIG{__WARN__} = sub {
|
||||
print STDERR "My special warning handler: $_[0]"
|
||||
};
|
||||
}
|
||||
|
||||
use Error qw( :warndie );</code></pre>
|
||||
|
||||
<p>Note that setting <code>$SIG{__WARN__}</code> after the <code>:warndie</code> tag has been imported will overwrite the handler that <code>Error</code> provides. If this cannot be avoided, then the tag can be explicitly <code>import</code>ed later</p>
|
||||
|
||||
<pre><code>use Error;
|
||||
|
||||
$SIG{__WARN__} = ...;
|
||||
|
||||
import Error qw( :warndie );</code></pre>
|
||||
|
||||
<h2 id="EXAMPLE">EXAMPLE</h2>
|
||||
|
||||
<p>The <code>__DIE__</code> handler turns messages such as</p>
|
||||
|
||||
<pre><code>Can't call method "foo" on an undefined value at examples/warndie.pl line 16.</code></pre>
|
||||
|
||||
<p>into</p>
|
||||
|
||||
<pre><code>Unhandled perl error caught at toplevel:
|
||||
|
||||
Can't call method "foo" on an undefined value
|
||||
|
||||
Thrown from: examples/warndie.pl:16
|
||||
|
||||
Full stack trace:
|
||||
|
||||
main::inner('undef') called at examples/warndie.pl line 20
|
||||
main::outer('undef') called at examples/warndie.pl line 23</code></pre>
|
||||
|
||||
<a href="#_podtop_"><h1 id="SEE-ALSO">SEE ALSO</h1></a>
|
||||
|
||||
<p>See <a>Exception::Class</a> for a different module providing Object-Oriented exception handling, along with a convenient syntax for declaring hierarchies for them. It doesn't provide Error's syntactic sugar of <code>try { ... }</code>, <code>catch { ... }</code>, etc. which may be a good thing or a bad thing based on what you want. (Because Error's syntactic sugar tends to break.)</p>
|
||||
|
||||
<p><a>Error::Exception</a> aims to combine <a href="/share/perl5/5.40/Test2/EventFacet/Error.html">Error</a> and <a>Exception::Class</a> "with correct stringification".</p>
|
||||
|
||||
<p><a>TryCatch</a> and <a>Try::Tiny</a> are similar in concept to Error.pm only providing a syntax that hopefully breaks less.</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="KNOWN-BUGS">KNOWN BUGS</h1></a>
|
||||
|
||||
<p>None, but that does not mean there are not any.</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="AUTHORS">AUTHORS</h1></a>
|
||||
|
||||
<p>Graham Barr <gbarr@pobox.com></p>
|
||||
|
||||
<p>The code that inspired me to write this was originally written by Peter Seibel <peter@weblogic.com> and adapted by Jesse Glick <jglick@sig.bsh.com>.</p>
|
||||
|
||||
<p><code>:warndie</code> handlers added by Paul Evans <leonerd@leonerd.org.uk></p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="MAINTAINER">MAINTAINER</h1></a>
|
||||
|
||||
<p>Shlomi Fish, <a href="http://www.shlomifish.org/">http://www.shlomifish.org/</a> .</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="PAST-MAINTAINERS">PAST MAINTAINERS</h1></a>
|
||||
|
||||
<p>Arun Kumar U <u_arunkumar@yahoo.com></p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="COPYRIGHT">COPYRIGHT</h1></a>
|
||||
|
||||
<p>Copyright (c) 1997-8 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="SUPPORT">SUPPORT</h1></a>
|
||||
|
||||
<h2 id="Websites">Websites</h2>
|
||||
|
||||
<p>The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.</p>
|
||||
|
||||
<ul>
|
||||
|
||||
<li><p>MetaCPAN</p>
|
||||
|
||||
<p>A modern, open-source CPAN search engine, useful to view POD in HTML format.</p>
|
||||
|
||||
<p><a href="https://metacpan.org/release/Error">https://metacpan.org/release/Error</a></p>
|
||||
|
||||
</li>
|
||||
<li><p>RT: CPAN's Bug Tracker</p>
|
||||
|
||||
<p>The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.</p>
|
||||
|
||||
<p><a href="https://rt.cpan.org/Public/Dist/Display.html?Name=Error">https://rt.cpan.org/Public/Dist/Display.html?Name=Error</a></p>
|
||||
|
||||
</li>
|
||||
<li><p>CPANTS</p>
|
||||
|
||||
<p>The CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution.</p>
|
||||
|
||||
<p><a href="http://cpants.cpanauthors.org/dist/Error">http://cpants.cpanauthors.org/dist/Error</a></p>
|
||||
|
||||
</li>
|
||||
<li><p>CPAN Testers</p>
|
||||
|
||||
<p>The CPAN Testers is a network of smoke testers who run automated tests on uploaded CPAN distributions.</p>
|
||||
|
||||
<p><a href="http://www.cpantesters.org/distro/E/Error">http://www.cpantesters.org/distro/E/Error</a></p>
|
||||
|
||||
</li>
|
||||
<li><p>CPAN Testers Matrix</p>
|
||||
|
||||
<p>The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms.</p>
|
||||
|
||||
<p><a href="http://matrix.cpantesters.org/?dist=Error">http://matrix.cpantesters.org/?dist=Error</a></p>
|
||||
|
||||
</li>
|
||||
<li><p>CPAN Testers Dependencies</p>
|
||||
|
||||
<p>The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution.</p>
|
||||
|
||||
<p><a href="http://deps.cpantesters.org/?module=Error">http://deps.cpantesters.org/?module=Error</a></p>
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h2 id="Bugs-Feature-Requests">Bugs / Feature Requests</h2>
|
||||
|
||||
<p>Please report any bugs or feature requests by email to <code>bug-error at rt.cpan.org</code>, or through the web interface at <a href="https://rt.cpan.org/Public/Bug/Report.html?Queue=Error">https://rt.cpan.org/Public/Bug/Report.html?Queue=Error</a>. You will be automatically notified of any progress on the request by the system.</p>
|
||||
|
||||
<h2 id="Source-Code">Source Code</h2>
|
||||
|
||||
<p>The code is open to the world, and available for you to hack on. Please feel free to browse it and play with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from your repository :)</p>
|
||||
|
||||
<p><a href="https://github.com/shlomif/perl-error.pm">https://github.com/shlomif/perl-error.pm</a></p>
|
||||
|
||||
<pre><code>git clone git://github.com/shlomif/perl-error.pm.git</code></pre>
|
||||
|
||||
<a href="#_podtop_"><h1 id="AUTHOR">AUTHOR</h1></a>
|
||||
|
||||
<p>Shlomi Fish ( http://www.shlomifish.org/ )</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="BUGS">BUGS</h1></a>
|
||||
|
||||
<p>Please report any bugs or feature requests on the bugtracker website <a href="https://github.com/shlomif/perl-error.pm/issues">https://github.com/shlomif/perl-error.pm/issues</a></p>
|
||||
|
||||
<p>When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="COPYRIGHT-AND-LICENSE">COPYRIGHT AND LICENSE</h1></a>
|
||||
|
||||
<p>This software is copyright (c) 2025 by Shlomi Fish ( http://www.shlomifish.org/ ).</p>
|
||||
|
||||
<p>This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.</p>
|
||||
|
||||
<table border="0" width="100%" cellspacing="0" cellpadding="3">
|
||||
<tr><td class="_podblock_" style="background-color: #cccccc; color: #000" valign="middle">
|
||||
<big><strong><span class="_podblock_"> Error - Error/exception handling in an OO-ish way</span></strong></big>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,178 @@
|
|||
<?xml version="1.0" ?>
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<!-- saved from url=(0017)http://localhost/ -->
|
||||
<title>Error::Simple - the simple error sub-class of Error</title>
|
||||
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||||
<link rev="made" href="mailto:ASSI@walter.nonet" />
|
||||
</head>
|
||||
|
||||
<body id="_podtop_">
|
||||
<table border="0" width="100%" cellspacing="0" cellpadding="3">
|
||||
<tr><td class="_podblock_" style="background-color: #cccccc; color: #000" valign="middle">
|
||||
<big><strong><span class="_podblock_"> Error::Simple - the simple error sub-class of Error</span></strong></big>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
<ul id="index">
|
||||
<li><a href="#NAME">NAME</a></li>
|
||||
<li><a href="#VERSION">VERSION</a></li>
|
||||
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
|
||||
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
|
||||
<li><a href="#METHODS">METHODS</a>
|
||||
<ul>
|
||||
<li><a href="#Error%3A%3ASimple-new-text-value">Error::Simple->new($text [, $value])</a></li>
|
||||
<li><a href="#err-stringify">$err->stringify()</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#KNOWN-BUGS">KNOWN BUGS</a></li>
|
||||
<li><a href="#AUTHORS">AUTHORS</a></li>
|
||||
<li><a href="#SEE-ALSO">SEE ALSO</a></li>
|
||||
<li><a href="#SUPPORT">SUPPORT</a>
|
||||
<ul>
|
||||
<li><a href="#Websites">Websites</a></li>
|
||||
<li><a href="#Bugs-Feature-Requests">Bugs / Feature Requests</a></li>
|
||||
<li><a href="#Source-Code">Source Code</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#AUTHOR">AUTHOR</a></li>
|
||||
<li><a href="#BUGS">BUGS</a></li>
|
||||
<li><a href="#COPYRIGHT-AND-LICENSE">COPYRIGHT AND LICENSE</a></li>
|
||||
</ul>
|
||||
|
||||
<a href="#_podtop_"><h1 id="NAME">NAME</h1></a>
|
||||
|
||||
<p>Error::Simple - the simple error sub-class of Error</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="VERSION">VERSION</h1></a>
|
||||
|
||||
<p>version 0.17030</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="SYNOPSIS">SYNOPSIS</h1></a>
|
||||
|
||||
<pre><code>use base 'Error::Simple';</code></pre>
|
||||
|
||||
<a href="#_podtop_"><h1 id="DESCRIPTION">DESCRIPTION</h1></a>
|
||||
|
||||
<p>The only purpose of this module is to allow one to say:</p>
|
||||
|
||||
<pre><code>use base 'Error::Simple';</code></pre>
|
||||
|
||||
<p>and the only thing it does is "use" Error.pm. Refer to the documentation of <a href="../../mnt/share/cygpkgs/perl-Error/perl-Error.noarch/build/blib/lib/Error.html">Error</a> for more information about Error::Simple.</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="METHODS">METHODS</h1></a>
|
||||
|
||||
<h2 id="Error::Simple-new-text-value">Error::Simple->new($text [, $value])</h2>
|
||||
|
||||
<p>Constructs an Error::Simple with the text <code>$text</code> and the optional value <code>$value</code>.</p>
|
||||
|
||||
<h2 id="err-stringify">$err->stringify()</h2>
|
||||
|
||||
<p>Error::Simple overloads this method.</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="KNOWN-BUGS">KNOWN BUGS</h1></a>
|
||||
|
||||
<p>None.</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="AUTHORS">AUTHORS</h1></a>
|
||||
|
||||
<p>Shlomi Fish ( <a href="http://www.shlomifish.org/">http://www.shlomifish.org/</a> )</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="SEE-ALSO">SEE ALSO</h1></a>
|
||||
|
||||
<p><a href="../../mnt/share/cygpkgs/perl-Error/perl-Error.noarch/build/blib/lib/Error.html">Error</a></p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="SUPPORT">SUPPORT</h1></a>
|
||||
|
||||
<h2 id="Websites">Websites</h2>
|
||||
|
||||
<p>The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.</p>
|
||||
|
||||
<ul>
|
||||
|
||||
<li><p>MetaCPAN</p>
|
||||
|
||||
<p>A modern, open-source CPAN search engine, useful to view POD in HTML format.</p>
|
||||
|
||||
<p><a href="https://metacpan.org/release/Error">https://metacpan.org/release/Error</a></p>
|
||||
|
||||
</li>
|
||||
<li><p>RT: CPAN's Bug Tracker</p>
|
||||
|
||||
<p>The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.</p>
|
||||
|
||||
<p><a href="https://rt.cpan.org/Public/Dist/Display.html?Name=Error">https://rt.cpan.org/Public/Dist/Display.html?Name=Error</a></p>
|
||||
|
||||
</li>
|
||||
<li><p>CPANTS</p>
|
||||
|
||||
<p>The CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution.</p>
|
||||
|
||||
<p><a href="http://cpants.cpanauthors.org/dist/Error">http://cpants.cpanauthors.org/dist/Error</a></p>
|
||||
|
||||
</li>
|
||||
<li><p>CPAN Testers</p>
|
||||
|
||||
<p>The CPAN Testers is a network of smoke testers who run automated tests on uploaded CPAN distributions.</p>
|
||||
|
||||
<p><a href="http://www.cpantesters.org/distro/E/Error">http://www.cpantesters.org/distro/E/Error</a></p>
|
||||
|
||||
</li>
|
||||
<li><p>CPAN Testers Matrix</p>
|
||||
|
||||
<p>The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms.</p>
|
||||
|
||||
<p><a href="http://matrix.cpantesters.org/?dist=Error">http://matrix.cpantesters.org/?dist=Error</a></p>
|
||||
|
||||
</li>
|
||||
<li><p>CPAN Testers Dependencies</p>
|
||||
|
||||
<p>The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution.</p>
|
||||
|
||||
<p><a href="http://deps.cpantesters.org/?module=Error">http://deps.cpantesters.org/?module=Error</a></p>
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h2 id="Bugs-Feature-Requests">Bugs / Feature Requests</h2>
|
||||
|
||||
<p>Please report any bugs or feature requests by email to <code>bug-error at rt.cpan.org</code>, or through the web interface at <a href="https://rt.cpan.org/Public/Bug/Report.html?Queue=Error">https://rt.cpan.org/Public/Bug/Report.html?Queue=Error</a>. You will be automatically notified of any progress on the request by the system.</p>
|
||||
|
||||
<h2 id="Source-Code">Source Code</h2>
|
||||
|
||||
<p>The code is open to the world, and available for you to hack on. Please feel free to browse it and play with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from your repository :)</p>
|
||||
|
||||
<p><a href="https://github.com/shlomif/perl-error.pm">https://github.com/shlomif/perl-error.pm</a></p>
|
||||
|
||||
<pre><code>git clone git://github.com/shlomif/perl-error.pm.git</code></pre>
|
||||
|
||||
<a href="#_podtop_"><h1 id="AUTHOR">AUTHOR</h1></a>
|
||||
|
||||
<p>Shlomi Fish ( http://www.shlomifish.org/ )</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="BUGS">BUGS</h1></a>
|
||||
|
||||
<p>Please report any bugs or feature requests on the bugtracker website <a href="https://github.com/shlomif/perl-error.pm/issues">https://github.com/shlomif/perl-error.pm/issues</a></p>
|
||||
|
||||
<p>When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="COPYRIGHT-AND-LICENSE">COPYRIGHT AND LICENSE</h1></a>
|
||||
|
||||
<p>This software is copyright (c) 2025 by Shlomi Fish ( http://www.shlomifish.org/ ).</p>
|
||||
|
||||
<p>This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.</p>
|
||||
|
||||
<table border="0" width="100%" cellspacing="0" cellpadding="3">
|
||||
<tr><td class="_podblock_" style="background-color: #cccccc; color: #000" valign="middle">
|
||||
<big><strong><span class="_podblock_"> Error::Simple - the simple error sub-class of Error</span></strong></big>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,187 @@
|
|||
<?xml version="1.0" ?>
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<!-- saved from url=(0017)http://localhost/ -->
|
||||
<title>Path::Class - Cross-platform path specification manipulation</title>
|
||||
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||||
<link rev="made" href="mailto:ASSI@walter.nonet" />
|
||||
</head>
|
||||
|
||||
<body id="_podtop_">
|
||||
<table border="0" width="100%" cellspacing="0" cellpadding="3">
|
||||
<tr><td class="_podblock_" style="background-color: #cccccc; color: #000" valign="middle">
|
||||
<big><strong><span class="_podblock_"> Path::Class - Cross-platform path specification manipulation</span></strong></big>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
<ul id="index">
|
||||
<li><a href="#NAME">NAME</a></li>
|
||||
<li><a href="#VERSION">VERSION</a></li>
|
||||
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
|
||||
<li><a href="#DESCRIPTION">DESCRIPTION</a>
|
||||
<ul>
|
||||
<li><a href="#EXPORT">EXPORT</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#Notes-on-Cross-Platform-Compatibility">Notes on Cross-Platform Compatibility</a></li>
|
||||
<li><a href="#AUTHOR">AUTHOR</a></li>
|
||||
<li><a href="#COPYRIGHT">COPYRIGHT</a></li>
|
||||
<li><a href="#SEE-ALSO">SEE ALSO</a></li>
|
||||
</ul>
|
||||
|
||||
<a href="#_podtop_"><h1 id="NAME">NAME</h1></a>
|
||||
|
||||
<p>Path::Class - Cross-platform path specification manipulation</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="VERSION">VERSION</h1></a>
|
||||
|
||||
<p>version 0.37</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="SYNOPSIS">SYNOPSIS</h1></a>
|
||||
|
||||
<pre><code> use Path::Class;
|
||||
|
||||
my $dir = dir('foo', 'bar'); # Path::Class::Dir object
|
||||
my $file = file('bob', 'file.txt'); # Path::Class::File object
|
||||
|
||||
# Stringifies to 'foo/bar' on Unix, 'foo\bar' on Windows, etc.
|
||||
print "dir: $dir\n";
|
||||
|
||||
# Stringifies to 'bob/file.txt' on Unix, 'bob\file.txt' on Windows
|
||||
print "file: $file\n";
|
||||
|
||||
my $subdir = $dir->subdir('baz'); # foo/bar/baz
|
||||
my $parent = $subdir->parent; # foo/bar
|
||||
my $parent2 = $parent->parent; # foo
|
||||
|
||||
my $dir2 = $file->dir; # bob
|
||||
|
||||
# Work with foreign paths
|
||||
use Path::Class qw(foreign_file foreign_dir);
|
||||
my $file = foreign_file('Mac', ':foo:file.txt');
|
||||
print $file->dir; # :foo:
|
||||
print $file->as_foreign('Win32'); # foo\file.txt
|
||||
|
||||
# Interact with the underlying filesystem:
|
||||
|
||||
# $dir_handle is an IO::Dir object
|
||||
my $dir_handle = $dir->open or die "Can't read $dir: $!";
|
||||
|
||||
# $file_handle is an IO::File object
|
||||
my $file_handle = $file->open($mode) or die "Can't read $file: $!";</code></pre>
|
||||
|
||||
<a href="#_podtop_"><h1 id="DESCRIPTION">DESCRIPTION</h1></a>
|
||||
|
||||
<p><code>Path::Class</code> is a module for manipulation of file and directory specifications (strings describing their locations, like <code>'/home/ken/foo.txt'</code> or <code>'C:\Windows\Foo.txt'</code>) in a cross-platform manner. It supports pretty much every platform Perl runs on, including Unix, Windows, Mac, VMS, Epoc, Cygwin, OS/2, and NetWare.</p>
|
||||
|
||||
<p>The well-known module <a>File::Spec</a> also provides this service, but it's sort of awkward to use well, so people sometimes avoid it, or use it in a way that won't actually work properly on platforms significantly different than the ones they've tested their code on.</p>
|
||||
|
||||
<p>In fact, <code>Path::Class</code> uses <code>File::Spec</code> internally, wrapping all the unsightly details so you can concentrate on your application code. Whereas <code>File::Spec</code> provides functions for some common path manipulations, <code>Path::Class</code> provides an object-oriented model of the world of path specifications and their underlying semantics. <code>File::Spec</code> doesn't create any objects, and its classes represent the different ways in which paths must be manipulated on various platforms (not a very intuitive concept). <code>Path::Class</code> creates objects representing files and directories, and provides methods that relate them to each other. For instance, the following <code>File::Spec</code> code:</p>
|
||||
|
||||
<pre><code>my $absolute = File::Spec->file_name_is_absolute(
|
||||
File::Spec->catfile( @dirs, $file )
|
||||
);</code></pre>
|
||||
|
||||
<p>can be written using <code>Path::Class</code> as</p>
|
||||
|
||||
<pre><code>my $absolute = Path::Class::File->new( @dirs, $file )->is_absolute;</code></pre>
|
||||
|
||||
<p>or even as</p>
|
||||
|
||||
<pre><code>my $absolute = file( @dirs, $file )->is_absolute;</code></pre>
|
||||
|
||||
<p>Similar readability improvements should happen all over the place when using <code>Path::Class</code>.</p>
|
||||
|
||||
<p>Using <code>Path::Class</code> can help solve real problems in your code too - for instance, how many people actually take the "volume" (like <code>C:</code> on Windows) into account when writing <code>File::Spec</code>-using code? I thought not. But if you use <code>Path::Class</code>, your file and directory objects will know what volumes they refer to and do the right thing.</p>
|
||||
|
||||
<p>The guts of the <code>Path::Class</code> code live in the <a href="../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/File.html">Path::Class::File</a> and <a href="../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/Dir.html">Path::Class::Dir</a> modules, so please see those modules' documentation for more details about how to use them.</p>
|
||||
|
||||
<h2 id="EXPORT">EXPORT</h2>
|
||||
|
||||
<p>The following functions are exported by default.</p>
|
||||
|
||||
<dl>
|
||||
|
||||
<dt id="file">file</dt>
|
||||
<dd>
|
||||
|
||||
<p>A synonym for <code>Path::Class::File->new</code>.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir">dir</dt>
|
||||
<dd>
|
||||
|
||||
<p>A synonym for <code>Path::Class::Dir->new</code>.</p>
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<p>If you would like to prevent their export, you may explicitly pass an empty list to perl's <code>use</code>, i.e. <code>use Path::Class ()</code>.</p>
|
||||
|
||||
<p>The following are exported only on demand.</p>
|
||||
|
||||
<dl>
|
||||
|
||||
<dt id="foreign_file">foreign_file</dt>
|
||||
<dd>
|
||||
|
||||
<p>A synonym for <code>Path::Class::File->new_foreign</code>.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="foreign_dir">foreign_dir</dt>
|
||||
<dd>
|
||||
|
||||
<p>A synonym for <code>Path::Class::Dir->new_foreign</code>.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="tempdir">tempdir</dt>
|
||||
<dd>
|
||||
|
||||
<p>Create a new Path::Class::Dir instance pointed to temporary directory.</p>
|
||||
|
||||
<pre><code>my $temp = Path::Class::tempdir(CLEANUP => 1);</code></pre>
|
||||
|
||||
<p>A synonym for <code>Path::Class::Dir->new(File::Temp::tempdir(@_))</code>.</p>
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<a href="#_podtop_"><h1 id="Notes-on-Cross-Platform-Compatibility">Notes on Cross-Platform Compatibility</h1></a>
|
||||
|
||||
<p>Although it is much easier to write cross-platform-friendly code with this module than with <code>File::Spec</code>, there are still some issues to be aware of.</p>
|
||||
|
||||
<ul>
|
||||
|
||||
<li><p>On some platforms, notably VMS and some older versions of DOS (I think), all filenames must have an extension. Thus if you create a file called <i>foo/bar</i> and then ask for a list of files in the directory <i>foo</i>, you may find a file called <i>bar.</i> instead of the <i>bar</i> you were expecting. Thus it might be a good idea to use an extension in the first place.</p>
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<a href="#_podtop_"><h1 id="AUTHOR">AUTHOR</h1></a>
|
||||
|
||||
<p>Ken Williams, KWILLIAMS@cpan.org</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="COPYRIGHT">COPYRIGHT</h1></a>
|
||||
|
||||
<p>Copyright (c) Ken Williams. All rights reserved.</p>
|
||||
|
||||
<p>This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="SEE-ALSO">SEE ALSO</h1></a>
|
||||
|
||||
<p><a href="../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/Dir.html">Path::Class::Dir</a>, <a href="../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/File.html">Path::Class::File</a>, <a>File::Spec</a></p>
|
||||
|
||||
<table border="0" width="100%" cellspacing="0" cellpadding="3">
|
||||
<tr><td class="_podblock_" style="background-color: #cccccc; color: #000" valign="middle">
|
||||
<big><strong><span class="_podblock_"> Path::Class - Cross-platform path specification manipulation</span></strong></big>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,485 @@
|
|||
<?xml version="1.0" ?>
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<!-- saved from url=(0017)http://localhost/ -->
|
||||
<title>Path::Class::Dir - Objects representing directories</title>
|
||||
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||||
<link rev="made" href="mailto:ASSI@walter.nonet" />
|
||||
</head>
|
||||
|
||||
<body id="_podtop_">
|
||||
<table border="0" width="100%" cellspacing="0" cellpadding="3">
|
||||
<tr><td class="_podblock_" style="background-color: #cccccc; color: #000" valign="middle">
|
||||
<big><strong><span class="_podblock_"> Path::Class::Dir - Objects representing directories</span></strong></big>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
<ul id="index">
|
||||
<li><a href="#NAME">NAME</a></li>
|
||||
<li><a href="#VERSION">VERSION</a></li>
|
||||
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
|
||||
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
|
||||
<li><a href="#METHODS">METHODS</a></li>
|
||||
<li><a href="#AUTHOR">AUTHOR</a></li>
|
||||
<li><a href="#SEE-ALSO">SEE ALSO</a></li>
|
||||
</ul>
|
||||
|
||||
<a href="#_podtop_"><h1 id="NAME">NAME</h1></a>
|
||||
|
||||
<p>Path::Class::Dir - Objects representing directories</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="VERSION">VERSION</h1></a>
|
||||
|
||||
<p>version 0.37</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="SYNOPSIS">SYNOPSIS</h1></a>
|
||||
|
||||
<pre><code> use Path::Class; # Exports dir() by default
|
||||
|
||||
my $dir = dir('foo', 'bar'); # Path::Class::Dir object
|
||||
my $dir = Path::Class::Dir->new('foo', 'bar'); # Same thing
|
||||
|
||||
# Stringifies to 'foo/bar' on Unix, 'foo\bar' on Windows, etc.
|
||||
print "dir: $dir\n";
|
||||
|
||||
if ($dir->is_absolute) { ... }
|
||||
if ($dir->is_relative) { ... }
|
||||
|
||||
my $v = $dir->volume; # Could be 'C:' on Windows, empty string
|
||||
# on Unix, 'Macintosh HD:' on Mac OS
|
||||
|
||||
$dir->cleanup; # Perform logical cleanup of pathname
|
||||
$dir->resolve; # Perform physical cleanup of pathname
|
||||
|
||||
my $file = $dir->file('file.txt'); # A file in this directory
|
||||
my $subdir = $dir->subdir('george'); # A subdirectory
|
||||
my $parent = $dir->parent; # The parent directory, 'foo'
|
||||
|
||||
my $abs = $dir->absolute; # Transform to absolute path
|
||||
my $rel = $abs->relative; # Transform to relative path
|
||||
my $rel = $abs->relative('/foo'); # Relative to /foo
|
||||
|
||||
print $dir->as_foreign('Mac'); # :foo:bar:
|
||||
print $dir->as_foreign('Win32'); # foo\bar
|
||||
|
||||
# Iterate with IO::Dir methods:
|
||||
my $handle = $dir->open;
|
||||
while (my $file = $handle->read) {
|
||||
$file = $dir->file($file); # Turn into Path::Class::File object
|
||||
...
|
||||
}
|
||||
|
||||
# Iterate with Path::Class methods:
|
||||
while (my $file = $dir->next) {
|
||||
# $file is a Path::Class::File or Path::Class::Dir object
|
||||
...
|
||||
}</code></pre>
|
||||
|
||||
<a href="#_podtop_"><h1 id="DESCRIPTION">DESCRIPTION</h1></a>
|
||||
|
||||
<p>The <code>Path::Class::Dir</code> class contains functionality for manipulating directory names in a cross-platform way.</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="METHODS">METHODS</h1></a>
|
||||
|
||||
<dl>
|
||||
|
||||
<dt id="dir-Path::Class::Dir-new-dir1-dir2">$dir = Path::Class::Dir->new( <dir1>, <dir2>, ... )</dt>
|
||||
<dd>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-dir-dir1-dir2">$dir = dir( <dir1>, <dir2>, ... )</dt>
|
||||
<dd>
|
||||
|
||||
<p>Creates a new <code>Path::Class::Dir</code> object and returns it. The arguments specify names of directories which will be joined to create a single directory object. A volume may also be specified as the first argument, or as part of the first argument. You can use platform-neutral syntax:</p>
|
||||
|
||||
<pre><code>my $dir = dir( 'foo', 'bar', 'baz' );</code></pre>
|
||||
|
||||
<p>or platform-native syntax:</p>
|
||||
|
||||
<pre><code>my $dir = dir( 'foo/bar/baz' );</code></pre>
|
||||
|
||||
<p>or a mixture of the two:</p>
|
||||
|
||||
<pre><code>my $dir = dir( 'foo/bar', 'baz' );</code></pre>
|
||||
|
||||
<p>All three of the above examples create relative paths. To create an absolute path, either use the platform native syntax for doing so:</p>
|
||||
|
||||
<pre><code>my $dir = dir( '/var/tmp' );</code></pre>
|
||||
|
||||
<p>or use an empty string as the first argument:</p>
|
||||
|
||||
<pre><code>my $dir = dir( '', 'var', 'tmp' );</code></pre>
|
||||
|
||||
<p>If the second form seems awkward, that's somewhat intentional - paths like <code>/var/tmp</code> or <code>\Windows</code> aren't cross-platform concepts in the first place (many non-Unix platforms don't have a notion of a "root directory"), so they probably shouldn't appear in your code if you're trying to be cross-platform. The first form is perfectly natural, because paths like this may come from config files, user input, or whatever.</p>
|
||||
|
||||
<p>As a special case, since it doesn't otherwise mean anything useful and it's convenient to define this way, <code>Path::Class::Dir->new()</code> (or <code>dir()</code>) refers to the current directory (<code>File::Spec->curdir</code>). To get the current directory as an absolute path, do <code>dir()->absolute</code>.</p>
|
||||
|
||||
<p>Finally, as another special case <code>dir(undef)</code> will return undef, since that's usually an accident on the part of the caller, and returning the root directory would be a nasty surprise just asking for trouble a few lines later.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-stringify">$dir->stringify</dt>
|
||||
<dd>
|
||||
|
||||
<p>This method is called internally when a <code>Path::Class::Dir</code> object is used in a string context, so the following are equivalent:</p>
|
||||
|
||||
<pre><code>$string = $dir->stringify;
|
||||
$string = "$dir";</code></pre>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-volume">$dir->volume</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns the volume (e.g. <code>C:</code> on Windows, <code>Macintosh HD:</code> on Mac OS, etc.) of the directory object, if any. Otherwise, returns the empty string.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-basename">$dir->basename</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns the last directory name of the path as a string.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-is_dir">$dir->is_dir</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a boolean value indicating whether this object represents a directory. Not surprisingly, <a href="../../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/File.html">Path::Class::File</a> objects always return false, and <code>Path::Class::Dir</code> objects always return true.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-is_absolute">$dir->is_absolute</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns true or false depending on whether the directory refers to an absolute path specifier (like <code>/usr/local</code> or <code>\Windows</code>).</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-is_relative">$dir->is_relative</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns true or false depending on whether the directory refers to a relative path specifier (like <code>lib/foo</code> or <code>./dir</code>).</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-cleanup">$dir->cleanup</dt>
|
||||
<dd>
|
||||
|
||||
<p>Performs a logical cleanup of the file path. For instance:</p>
|
||||
|
||||
<pre><code>my $dir = dir('/foo//baz/./foo')->cleanup;
|
||||
# $dir now represents '/foo/baz/foo';</code></pre>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-resolve">$dir->resolve</dt>
|
||||
<dd>
|
||||
|
||||
<p>Performs a physical cleanup of the file path. For instance:</p>
|
||||
|
||||
<pre><code>my $dir = dir('/foo//baz/../foo')->resolve;
|
||||
# $dir now represents '/foo/foo', assuming no symlinks</code></pre>
|
||||
|
||||
<p>This actually consults the filesystem to verify the validity of the path.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="file-dir-file-dir1-dir2-...-file">$file = $dir->file( <dir1>, <dir2>, ..., <file> )</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a <a href="../../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/File.html">Path::Class::File</a> object representing an entry in <code>$dir</code> or one of its subdirectories. Internally, this just calls <code>Path::Class::File->new( @_ )</code>.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="subdir-dir-subdir-dir1-dir2">$subdir = $dir->subdir( <dir1>, <dir2>, ... )</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a new <code>Path::Class::Dir</code> object representing a subdirectory of <code>$dir</code>.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="parent-dir-parent">$parent = $dir->parent</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns the parent directory of <code>$dir</code>. Note that this is the <i>logical</i> parent, not necessarily the physical parent. It really means we just chop off entries from the end of the directory list until we cain't chop no more. If the directory is relative, we start using the relative forms of parent directories.</p>
|
||||
|
||||
<p>The following code demonstrates the behavior on absolute and relative directories:</p>
|
||||
|
||||
<pre><code> $dir = dir('/foo/bar');
|
||||
for (1..6) {
|
||||
print "Absolute: $dir\n";
|
||||
$dir = $dir->parent;
|
||||
}
|
||||
|
||||
$dir = dir('foo/bar');
|
||||
for (1..6) {
|
||||
print "Relative: $dir\n";
|
||||
$dir = $dir->parent;
|
||||
}
|
||||
|
||||
########### Output on Unix ################
|
||||
Absolute: /foo/bar
|
||||
Absolute: /foo
|
||||
Absolute: /
|
||||
Absolute: /
|
||||
Absolute: /
|
||||
Absolute: /
|
||||
Relative: foo/bar
|
||||
Relative: foo
|
||||
Relative: .
|
||||
Relative: ..
|
||||
Relative: ../..
|
||||
Relative: ../../..</code></pre>
|
||||
|
||||
</dd>
|
||||
<dt id="list-dir-children">@list = $dir->children</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a list of <a href="../../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/File.html">Path::Class::File</a> and/or <code>Path::Class::Dir</code> objects listed in this directory, or in scalar context the number of such objects. Obviously, it is necessary for <code>$dir</code> to exist and be readable in order to find its children.</p>
|
||||
|
||||
<p>Note that the children are returned as subdirectories of <code>$dir</code>, i.e. the children of <i>foo</i> will be <i>foo/bar</i> and <i>foo/baz</i>, not <i>bar</i> and <i>baz</i>.</p>
|
||||
|
||||
<p>Ordinarily <code>children()</code> will not include the <i>self</i> and <i>parent</i> entries <code>.</code> and <code>..</code> (or their equivalents on non-Unix systems), because that's like I'm-my-own-grandpa business. If you do want all directory entries including these special ones, pass a true value for the <code>all</code> parameter:</p>
|
||||
|
||||
<pre><code>@c = $dir->children(); # Just the children
|
||||
@c = $dir->children(all => 1); # All entries</code></pre>
|
||||
|
||||
<p>In addition, there's a <code>no_hidden</code> parameter that will exclude all normally "hidden" entries - on Unix this means excluding all entries that begin with a dot (<code>.</code>):</p>
|
||||
|
||||
<pre><code>@c = $dir->children(no_hidden => 1); # Just normally-visible entries</code></pre>
|
||||
|
||||
</dd>
|
||||
<dt id="abs-dir-absolute">$abs = $dir->absolute</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a <code>Path::Class::Dir</code> object representing <code>$dir</code> as an absolute path. An optional argument, given as either a string or a <code>Path::Class::Dir</code> object, specifies the directory to use as the base of relativity - otherwise the current working directory will be used.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="rel-dir-relative">$rel = $dir->relative</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a <code>Path::Class::Dir</code> object representing <code>$dir</code> as a relative path. An optional argument, given as either a string or a <code>Path::Class::Dir</code> object, specifies the directory to use as the base of relativity - otherwise the current working directory will be used.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="boolean-dir-subsumes-other">$boolean = $dir->subsumes($other)</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns true if this directory spec subsumes the other spec, and false otherwise. Think of "subsumes" as "contains", but we only look at the <i>specs</i>, not whether <code>$dir</code> actually contains <code>$other</code> on the filesystem.</p>
|
||||
|
||||
<p>The <code>$other</code> argument may be a <code>Path::Class::Dir</code> object, a <a href="../../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/File.html">Path::Class::File</a> object, or a string. In the latter case, we assume it's a directory.</p>
|
||||
|
||||
<pre><code># Examples:
|
||||
dir('foo/bar' )->subsumes(dir('foo/bar/baz')) # True
|
||||
dir('/foo/bar')->subsumes(dir('/foo/bar/baz')) # True
|
||||
dir('foo/..')->subsumes(dir('foo/../bar)) # True
|
||||
dir('foo/bar' )->subsumes(dir('bar/baz')) # False
|
||||
dir('/foo/bar')->subsumes(dir('foo/bar')) # False
|
||||
dir('foo/..')->subsumes(dir('bar')) # False! Use C<contains> to resolve ".."</code></pre>
|
||||
|
||||
</dd>
|
||||
<dt id="boolean-dir-contains-other">$boolean = $dir->contains($other)</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns true if this directory actually contains <code>$other</code> on the filesystem. <code>$other</code> doesn't have to be a direct child of <code>$dir</code>, it just has to be subsumed after both paths have been resolved.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="foreign-dir-as_foreign-type">$foreign = $dir->as_foreign($type)</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a <code>Path::Class::Dir</code> object representing <code>$dir</code> as it would be specified on a system of type <code>$type</code>. Known types include <code>Unix</code>, <code>Win32</code>, <code>Mac</code>, <code>VMS</code>, and <code>OS2</code>, i.e. anything for which there is a subclass of <code>File::Spec</code>.</p>
|
||||
|
||||
<p>Any generated objects (subdirectories, files, parents, etc.) will also retain this type.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="foreign-Path::Class::Dir-new_foreign-type-args">$foreign = Path::Class::Dir->new_foreign($type, @args)</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a <code>Path::Class::Dir</code> object representing <code>$dir</code> as it would be specified on a system of type <code>$type</code>. Known types include <code>Unix</code>, <code>Win32</code>, <code>Mac</code>, <code>VMS</code>, and <code>OS2</code>, i.e. anything for which there is a subclass of <code>File::Spec</code>.</p>
|
||||
|
||||
<p>The arguments in <code>@args</code> are the same as they would be specified in <code>new()</code>.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="list-dir-dir_list-OFFSET-LENGTH">@list = $dir->dir_list([OFFSET, [LENGTH]])</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns the list of strings internally representing this directory structure. Each successive member of the list is understood to be an entry in its predecessor's directory list. By contract, <code>Path::Class->new( $dir->dir_list )</code> should be equivalent to <code>$dir</code>.</p>
|
||||
|
||||
<p>The semantics of this method are similar to Perl's <code>splice</code> or <code>substr</code> functions; they return <code>LENGTH</code> elements starting at <code>OFFSET</code>. If <code>LENGTH</code> is omitted, returns all the elements starting at <code>OFFSET</code> up to the end of the list. If <code>LENGTH</code> is negative, returns the elements from <code>OFFSET</code> onward except for <code>-LENGTH</code> elements at the end. If <code>OFFSET</code> is negative, it counts backward <code>OFFSET</code> elements from the end of the list. If <code>OFFSET</code> and <code>LENGTH</code> are both omitted, the entire list is returned.</p>
|
||||
|
||||
<p>In a scalar context, <code>dir_list()</code> with no arguments returns the number of entries in the directory list; <code>dir_list(OFFSET)</code> returns the single element at that offset; <code>dir_list(OFFSET, LENGTH)</code> returns the final element that would have been returned in a list context.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-components">$dir->components</dt>
|
||||
<dd>
|
||||
|
||||
<p>Identical to <code>dir_list()</code>. It exists because there's an analogous method <code>dir_list()</code> in the <code>Path::Class::File</code> class that also returns the basename string, so this method lets someone call <code>components()</code> without caring whether the object is a file or a directory.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="fh-dir-open">$fh = $dir->open()</dt>
|
||||
<dd>
|
||||
|
||||
<p>Passes <code>$dir</code> to <code>IO::Dir->open</code> and returns the result as an <a>IO::Dir</a> object. If the opening fails, <code>undef</code> is returned and <code>$!</code> is set.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-mkpath-verbose-mode">$dir->mkpath($verbose, $mode)</dt>
|
||||
<dd>
|
||||
|
||||
<p>Passes all arguments, including <code>$dir</code>, to <code>File::Path::mkpath()</code> and returns the result (a list of all directories created).</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-rmtree-verbose-cautious">$dir->rmtree($verbose, $cautious)</dt>
|
||||
<dd>
|
||||
|
||||
<p>Passes all arguments, including <code>$dir</code>, to <code>File::Path::rmtree()</code> and returns the result (the number of files successfully deleted).</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-remove">$dir->remove()</dt>
|
||||
<dd>
|
||||
|
||||
<p>Removes the directory, which must be empty. Returns a boolean value indicating whether or not the directory was successfully removed. This method is mainly provided for consistency with <code>Path::Class::File</code>'s <code>remove()</code> method.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-tempfile">$dir->tempfile(...)</dt>
|
||||
<dd>
|
||||
|
||||
<p>An interface to <a href="../../share/perl5/5.40/File/Temp.html">File::Temp</a>'s <code>tempfile()</code> function. Just like that function, if you call this in a scalar context, the return value is the filehandle and the file is <code>unlink</code>ed as soon as possible (which is immediately on Unix-like platforms). If called in a list context, the return values are the filehandle and the filename.</p>
|
||||
|
||||
<p>The given directory is passed as the <code>DIR</code> parameter.</p>
|
||||
|
||||
<p>Here's an example of pretty good usage which doesn't allow race conditions, won't leave yucky tempfiles around on your filesystem, etc.:</p>
|
||||
|
||||
<pre><code>my $fh = $dir->tempfile;
|
||||
print $fh "Here's some data...\n";
|
||||
seek($fh, 0, 0);
|
||||
while (<$fh>) { do something... }</code></pre>
|
||||
|
||||
<p>Or in combination with a <code>fork</code>:</p>
|
||||
|
||||
<pre><code>my $fh = $dir->tempfile;
|
||||
print $fh "Here's some more data...\n";
|
||||
seek($fh, 0, 0);
|
||||
if ($pid=fork()) {
|
||||
wait;
|
||||
} else {
|
||||
something($_) while <$fh>;
|
||||
}</code></pre>
|
||||
|
||||
</dd>
|
||||
<dt id="dir_or_file-dir-next">$dir_or_file = $dir->next()</dt>
|
||||
<dd>
|
||||
|
||||
<p>A convenient way to iterate through directory contents. The first time <code>next()</code> is called, it will <code>open()</code> the directory and read the first item from it, returning the result as a <code>Path::Class::Dir</code> or <a href="../../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/File.html">Path::Class::File</a> object (depending, of course, on its actual type). Each subsequent call to <code>next()</code> will simply iterate over the directory's contents, until there are no more items in the directory, and then the undefined value is returned. For example, to iterate over all the regular files in a directory:</p>
|
||||
|
||||
<pre><code>while (my $file = $dir->next) {
|
||||
next unless -f $file;
|
||||
my $fh = $file->open('r') or die "Can't read $file: $!";
|
||||
...
|
||||
}</code></pre>
|
||||
|
||||
<p>If an error occurs when opening the directory (for instance, it doesn't exist or isn't readable), <code>next()</code> will throw an exception with the value of <code>$!</code>.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-traverse-sub-...-args">$dir->traverse( sub { ... }, @args )</dt>
|
||||
<dd>
|
||||
|
||||
<p>Calls the given callback for the root, passing it a continuation function which, when called, will call this recursively on each of its children. The callback function should be of the form:</p>
|
||||
|
||||
<pre><code>sub {
|
||||
my ($child, $cont, @args) = @_;
|
||||
# ...
|
||||
}</code></pre>
|
||||
|
||||
<p>For instance, to calculate the number of files in a directory, you can do this:</p>
|
||||
|
||||
<pre><code>my $nfiles = $dir->traverse(sub {
|
||||
my ($child, $cont) = @_;
|
||||
return sum($cont->(), ($child->is_dir ? 0 : 1));
|
||||
});</code></pre>
|
||||
|
||||
<p>or to calculate the maximum depth of a directory:</p>
|
||||
|
||||
<pre><code>my $depth = $dir->traverse(sub {
|
||||
my ($child, $cont, $depth) = @_;
|
||||
return max($cont->($depth + 1), $depth);
|
||||
}, 0);</code></pre>
|
||||
|
||||
<p>You can also choose not to call the callback in certain situations:</p>
|
||||
|
||||
<pre><code>$dir->traverse(sub {
|
||||
my ($child, $cont) = @_;
|
||||
return if -l $child; # don't follow symlinks
|
||||
# do something with $child
|
||||
return $cont->();
|
||||
});</code></pre>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-traverse_if-sub-...-sub-...-args">$dir->traverse_if( sub { ... }, sub { ... }, @args )</dt>
|
||||
<dd>
|
||||
|
||||
<p>traverse with additional "should I visit this child" callback. Particularly useful in case examined tree contains inaccessible directories.</p>
|
||||
|
||||
<p>Canonical example:</p>
|
||||
|
||||
<pre><code>$dir->traverse_if(
|
||||
sub {
|
||||
my ($child, $cont) = @_;
|
||||
# do something with $child
|
||||
return $cont->();
|
||||
},
|
||||
sub {
|
||||
my ($child) = @_;
|
||||
# Process only readable items
|
||||
return -r $child;
|
||||
});</code></pre>
|
||||
|
||||
<p>Second callback gets single parameter: child. Only children for which it returns true will be processed by the first callback.</p>
|
||||
|
||||
<p>Remaining parameters are interpreted as in traverse, in particular <code>traverse_if(callback, sub { 1 }, @args</code> is equivalent to <code>traverse(callback, @args)</code>.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-recurse-callback-sub">$dir->recurse( callback => sub {...} )</dt>
|
||||
<dd>
|
||||
|
||||
<p>Iterates through this directory and all of its children, and all of its children's children, etc., calling the <code>callback</code> subroutine for each entry. This is a lot like what the <a href="../../share/perl5/5.40/File/Find.html">File::Find</a> module does, and of course <code>File::Find</code> will work fine on <a href="../../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class.html">Path::Class</a> objects, but the advantage of the <code>recurse()</code> method is that it will also feed your callback routine <code>Path::Class</code> objects rather than just pathname strings.</p>
|
||||
|
||||
<p>The <code>recurse()</code> method requires a <code>callback</code> parameter specifying the subroutine to invoke for each entry. It will be passed the <code>Path::Class</code> object as its first argument.</p>
|
||||
|
||||
<p><code>recurse()</code> also accepts two boolean parameters, <code>depthfirst</code> and <code>preorder</code> that control the order of recursion. The default is a preorder, breadth-first search, i.e. <code>depthfirst => 0, preorder => 1</code>. At the time of this writing, all combinations of these two parameters are supported <i>except</i> <code>depthfirst => 0, preorder => 0</code>.</p>
|
||||
|
||||
<p><code>callback</code> is normally not required to return any value. If it returns special constant <code>Path::Class::Entity::PRUNE()</code> (more easily available as <code>$item->PRUNE</code>), no children of analyzed item will be analyzed (mostly as if you set <code>$File::Find::prune=1</code>). Of course pruning is available only in <code>preorder</code>, in postorder return value has no effect.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="st-file-stat">$st = $file->stat()</dt>
|
||||
<dd>
|
||||
|
||||
<p>Invokes <code>File::stat::stat()</code> on this directory and returns a <code>File::stat</code> object representing the result.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="st-file-lstat">$st = $file->lstat()</dt>
|
||||
<dd>
|
||||
|
||||
<p>Same as <code>stat()</code>, but if <code>$file</code> is a symbolic link, <code>lstat()</code> stats the link instead of the directory the link points to.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="class-file-file_class">$class = $file->file_class()</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns the class which should be used to create file objects.</p>
|
||||
|
||||
<p>Generally overridden whenever this class is subclassed.</p>
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<a href="#_podtop_"><h1 id="AUTHOR">AUTHOR</h1></a>
|
||||
|
||||
<p>Ken Williams, kwilliams@cpan.org</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="SEE-ALSO">SEE ALSO</h1></a>
|
||||
|
||||
<p><a href="../../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class.html">Path::Class</a>, <a href="../../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/File.html">Path::Class::File</a>, <a>File::Spec</a></p>
|
||||
|
||||
<table border="0" width="100%" cellspacing="0" cellpadding="3">
|
||||
<tr><td class="_podblock_" style="background-color: #cccccc; color: #000" valign="middle">
|
||||
<big><strong><span class="_podblock_"> Path::Class::Dir - Objects representing directories</span></strong></big>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
<?xml version="1.0" ?>
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<!-- saved from url=(0017)http://localhost/ -->
|
||||
<title>Path::Class::Entity - Base class for files and directories</title>
|
||||
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||||
<link rev="made" href="mailto:ASSI@walter.nonet" />
|
||||
</head>
|
||||
|
||||
<body id="_podtop_">
|
||||
<table border="0" width="100%" cellspacing="0" cellpadding="3">
|
||||
<tr><td class="_podblock_" style="background-color: #cccccc; color: #000" valign="middle">
|
||||
<big><strong><span class="_podblock_"> Path::Class::Entity - Base class for files and directories</span></strong></big>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
<ul id="index">
|
||||
<li><a href="#NAME">NAME</a></li>
|
||||
<li><a href="#VERSION">VERSION</a></li>
|
||||
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
|
||||
<li><a href="#AUTHOR">AUTHOR</a></li>
|
||||
<li><a href="#SEE-ALSO">SEE ALSO</a></li>
|
||||
</ul>
|
||||
|
||||
<a href="#_podtop_"><h1 id="NAME">NAME</h1></a>
|
||||
|
||||
<p>Path::Class::Entity - Base class for files and directories</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="VERSION">VERSION</h1></a>
|
||||
|
||||
<p>version 0.37</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="DESCRIPTION">DESCRIPTION</h1></a>
|
||||
|
||||
<p>This class is the base class for <code>Path::Class::File</code> and <code>Path::Class::Dir</code>, it is not used directly by callers.</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="AUTHOR">AUTHOR</h1></a>
|
||||
|
||||
<p>Ken Williams, kwilliams@cpan.org</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="SEE-ALSO">SEE ALSO</h1></a>
|
||||
|
||||
<p>Path::Class</p>
|
||||
|
||||
<table border="0" width="100%" cellspacing="0" cellpadding="3">
|
||||
<tr><td class="_podblock_" style="background-color: #cccccc; color: #000" valign="middle">
|
||||
<big><strong><span class="_podblock_"> Path::Class::Entity - Base class for files and directories</span></strong></big>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,356 @@
|
|||
<?xml version="1.0" ?>
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<!-- saved from url=(0017)http://localhost/ -->
|
||||
<title>Path::Class::File - Objects representing files</title>
|
||||
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||||
<link rev="made" href="mailto:ASSI@walter.nonet" />
|
||||
</head>
|
||||
|
||||
<body id="_podtop_">
|
||||
<table border="0" width="100%" cellspacing="0" cellpadding="3">
|
||||
<tr><td class="_podblock_" style="background-color: #cccccc; color: #000" valign="middle">
|
||||
<big><strong><span class="_podblock_"> Path::Class::File - Objects representing files</span></strong></big>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
<ul id="index">
|
||||
<li><a href="#NAME">NAME</a></li>
|
||||
<li><a href="#VERSION">VERSION</a></li>
|
||||
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
|
||||
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
|
||||
<li><a href="#METHODS">METHODS</a></li>
|
||||
<li><a href="#AUTHOR">AUTHOR</a></li>
|
||||
<li><a href="#SEE-ALSO">SEE ALSO</a></li>
|
||||
</ul>
|
||||
|
||||
<a href="#_podtop_"><h1 id="NAME">NAME</h1></a>
|
||||
|
||||
<p>Path::Class::File - Objects representing files</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="VERSION">VERSION</h1></a>
|
||||
|
||||
<p>version 0.37</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="SYNOPSIS">SYNOPSIS</h1></a>
|
||||
|
||||
<pre><code>use Path::Class; # Exports file() by default
|
||||
|
||||
my $file = file('foo', 'bar.txt'); # Path::Class::File object
|
||||
my $file = Path::Class::File->new('foo', 'bar.txt'); # Same thing
|
||||
|
||||
# Stringifies to 'foo/bar.txt' on Unix, 'foo\bar.txt' on Windows, etc.
|
||||
print "file: $file\n";
|
||||
|
||||
if ($file->is_absolute) { ... }
|
||||
if ($file->is_relative) { ... }
|
||||
|
||||
my $v = $file->volume; # Could be 'C:' on Windows, empty string
|
||||
# on Unix, 'Macintosh HD:' on Mac OS
|
||||
|
||||
$file->cleanup; # Perform logical cleanup of pathname
|
||||
$file->resolve; # Perform physical cleanup of pathname
|
||||
|
||||
my $dir = $file->dir; # A Path::Class::Dir object
|
||||
|
||||
my $abs = $file->absolute; # Transform to absolute path
|
||||
my $rel = $file->relative; # Transform to relative path</code></pre>
|
||||
|
||||
<a href="#_podtop_"><h1 id="DESCRIPTION">DESCRIPTION</h1></a>
|
||||
|
||||
<p>The <code>Path::Class::File</code> class contains functionality for manipulating file names in a cross-platform way.</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="METHODS">METHODS</h1></a>
|
||||
|
||||
<dl>
|
||||
|
||||
<dt id="file-Path::Class::File-new-dir1-dir2-...-file">$file = Path::Class::File->new( <dir1>, <dir2>, ..., <file> )</dt>
|
||||
<dd>
|
||||
|
||||
</dd>
|
||||
<dt id="file-file-dir1-dir2-...-file">$file = file( <dir1>, <dir2>, ..., <file> )</dt>
|
||||
<dd>
|
||||
|
||||
<p>Creates a new <code>Path::Class::File</code> object and returns it. The arguments specify the path to the file. Any volume may also be specified as the first argument, or as part of the first argument. You can use platform-neutral syntax:</p>
|
||||
|
||||
<pre><code>my $file = file( 'foo', 'bar', 'baz.txt' );</code></pre>
|
||||
|
||||
<p>or platform-native syntax:</p>
|
||||
|
||||
<pre><code>my $file = file( 'foo/bar/baz.txt' );</code></pre>
|
||||
|
||||
<p>or a mixture of the two:</p>
|
||||
|
||||
<pre><code>my $file = file( 'foo/bar', 'baz.txt' );</code></pre>
|
||||
|
||||
<p>All three of the above examples create relative paths. To create an absolute path, either use the platform native syntax for doing so:</p>
|
||||
|
||||
<pre><code>my $file = file( '/var/tmp/foo.txt' );</code></pre>
|
||||
|
||||
<p>or use an empty string as the first argument:</p>
|
||||
|
||||
<pre><code>my $file = file( '', 'var', 'tmp', 'foo.txt' );</code></pre>
|
||||
|
||||
<p>If the second form seems awkward, that's somewhat intentional - paths like <code>/var/tmp</code> or <code>\Windows</code> aren't cross-platform concepts in the first place, so they probably shouldn't appear in your code if you're trying to be cross-platform. The first form is perfectly fine, because paths like this may come from config files, user input, or whatever.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="file-stringify">$file->stringify</dt>
|
||||
<dd>
|
||||
|
||||
<p>This method is called internally when a <code>Path::Class::File</code> object is used in a string context, so the following are equivalent:</p>
|
||||
|
||||
<pre><code>$string = $file->stringify;
|
||||
$string = "$file";</code></pre>
|
||||
|
||||
</dd>
|
||||
<dt id="file-volume">$file->volume</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns the volume (e.g. <code>C:</code> on Windows, <code>Macintosh HD:</code> on Mac OS, etc.) of the object, if any. Otherwise, returns the empty string.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="file-basename">$file->basename</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns the name of the file as a string, without the directory portion (if any).</p>
|
||||
|
||||
</dd>
|
||||
<dt id="file-components">$file->components</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a list of the directory components of this file, followed by the basename.</p>
|
||||
|
||||
<p>Note: unlike <code>$dir->components</code>, this method currently does not accept any arguments to select which elements of the list will be returned. It may do so in the future. Currently it throws an exception if such arguments are present.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="file-is_dir">$file->is_dir</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a boolean value indicating whether this object represents a directory. Not surprisingly, <code>Path::Class::File</code> objects always return false, and <a href="../../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/Dir.html">Path::Class::Dir</a> objects always return true.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="file-is_absolute">$file->is_absolute</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns true or false depending on whether the file refers to an absolute path specifier (like <code>/usr/local/foo.txt</code> or <code>\Windows\Foo.txt</code>).</p>
|
||||
|
||||
</dd>
|
||||
<dt id="file-is_relative">$file->is_relative</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns true or false depending on whether the file refers to a relative path specifier (like <code>lib/foo.txt</code> or <code>.\Foo.txt</code>).</p>
|
||||
|
||||
</dd>
|
||||
<dt id="file-cleanup">$file->cleanup</dt>
|
||||
<dd>
|
||||
|
||||
<p>Performs a logical cleanup of the file path. For instance:</p>
|
||||
|
||||
<pre><code>my $file = file('/foo//baz/./foo.txt')->cleanup;
|
||||
# $file now represents '/foo/baz/foo.txt';</code></pre>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-resolve">$dir->resolve</dt>
|
||||
<dd>
|
||||
|
||||
<p>Performs a physical cleanup of the file path. For instance:</p>
|
||||
|
||||
<pre><code>my $file = file('/foo/baz/../foo.txt')->resolve;
|
||||
# $file now represents '/foo/foo.txt', assuming no symlinks</code></pre>
|
||||
|
||||
<p>This actually consults the filesystem to verify the validity of the path.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-file-dir">$dir = $file->dir</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a <code>Path::Class::Dir</code> object representing the directory containing this file.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="dir-file-parent">$dir = $file->parent</dt>
|
||||
<dd>
|
||||
|
||||
<p>A synonym for the <code>dir()</code> method.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="abs-file-absolute">$abs = $file->absolute</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a <code>Path::Class::File</code> object representing <code>$file</code> as an absolute path. An optional argument, given as either a string or a <a href="../../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/Dir.html">Path::Class::Dir</a> object, specifies the directory to use as the base of relativity - otherwise the current working directory will be used.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="rel-file-relative">$rel = $file->relative</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a <code>Path::Class::File</code> object representing <code>$file</code> as a relative path. An optional argument, given as either a string or a <code>Path::Class::Dir</code> object, specifies the directory to use as the base of relativity - otherwise the current working directory will be used.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="foreign-file-as_foreign-type">$foreign = $file->as_foreign($type)</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a <code>Path::Class::File</code> object representing <code>$file</code> as it would be specified on a system of type <code>$type</code>. Known types include <code>Unix</code>, <code>Win32</code>, <code>Mac</code>, <code>VMS</code>, and <code>OS2</code>, i.e. anything for which there is a subclass of <code>File::Spec</code>.</p>
|
||||
|
||||
<p>Any generated objects (subdirectories, files, parents, etc.) will also retain this type.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="foreign-Path::Class::File-new_foreign-type-args">$foreign = Path::Class::File->new_foreign($type, @args)</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns a <code>Path::Class::File</code> object representing a file as it would be specified on a system of type <code>$type</code>. Known types include <code>Unix</code>, <code>Win32</code>, <code>Mac</code>, <code>VMS</code>, and <code>OS2</code>, i.e. anything for which there is a subclass of <code>File::Spec</code>.</p>
|
||||
|
||||
<p>The arguments in <code>@args</code> are the same as they would be specified in <code>new()</code>.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="fh-file-open-mode-permissions">$fh = $file->open($mode, $permissions)</dt>
|
||||
<dd>
|
||||
|
||||
<p>Passes the given arguments, including <code>$file</code>, to <code>IO::File->new</code> (which in turn calls <code>IO::File->open</code> and returns the result as an <a>IO::File</a> object. If the opening fails, <code>undef</code> is returned and <code>$!</code> is set.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="fh-file-openr">$fh = $file->openr()</dt>
|
||||
<dd>
|
||||
|
||||
<p>A shortcut for</p>
|
||||
|
||||
<pre><code>$fh = $file->open('r') or croak "Can't read $file: $!";</code></pre>
|
||||
|
||||
</dd>
|
||||
<dt id="fh-file-openw">$fh = $file->openw()</dt>
|
||||
<dd>
|
||||
|
||||
<p>A shortcut for</p>
|
||||
|
||||
<pre><code>$fh = $file->open('w') or croak "Can't write to $file: $!";</code></pre>
|
||||
|
||||
</dd>
|
||||
<dt id="fh-file-opena">$fh = $file->opena()</dt>
|
||||
<dd>
|
||||
|
||||
<p>A shortcut for</p>
|
||||
|
||||
<pre><code>$fh = $file->open('a') or croak "Can't append to $file: $!";</code></pre>
|
||||
|
||||
</dd>
|
||||
<dt id="file-touch">$file->touch</dt>
|
||||
<dd>
|
||||
|
||||
<p>Sets the modification and access time of the given file to right now, if the file exists. If it doesn't exist, <code>touch()</code> will <i>make</i> it exist, and - YES! - set its modification and access time to now.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="file-slurp">$file->slurp()</dt>
|
||||
<dd>
|
||||
|
||||
<p>In a scalar context, returns the contents of <code>$file</code> in a string. In a list context, returns the lines of <code>$file</code> (according to how <code>$/</code> is set) as a list. If the file can't be read, this method will throw an exception.</p>
|
||||
|
||||
<p>If you want <code>chomp()</code> run on each line of the file, pass a true value for the <code>chomp</code> or <code>chomped</code> parameters:</p>
|
||||
|
||||
<pre><code>my @lines = $file->slurp(chomp => 1);</code></pre>
|
||||
|
||||
<p>You may also use the <code>iomode</code> parameter to pass in an IO mode to use when opening the file, usually IO layers (though anything accepted by the MODE argument of <code>open()</code> is accepted here). Just make sure it's a <i>reading</i> mode.</p>
|
||||
|
||||
<pre><code>my @lines = $file->slurp(iomode => ':crlf');
|
||||
my $lines = $file->slurp(iomode => '<:encoding(UTF-8)');</code></pre>
|
||||
|
||||
<p>The default <code>iomode</code> is <code>r</code>.</p>
|
||||
|
||||
<p>Lines can also be automatically split, mimicking the perl command-line option <code>-a</code> by using the <code>split</code> parameter. If this parameter is used, each line will be returned as an array ref.</p>
|
||||
|
||||
<pre><code>my @lines = $file->slurp( chomp => 1, split => qr/\s*,\s*/ );</code></pre>
|
||||
|
||||
<p>The <code>split</code> parameter can only be used in a list context.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="file-spew-content">$file->spew( $content );</dt>
|
||||
<dd>
|
||||
|
||||
<p>The opposite of <a href="#slurp">"slurp"</a>, this takes a list of strings and prints them to the file in write mode. If the file can't be written to, this method will throw an exception.</p>
|
||||
|
||||
<p>The content to be written can be either an array ref or a plain scalar. If the content is an array ref then each entry in the array will be written to the file.</p>
|
||||
|
||||
<p>You may use the <code>iomode</code> parameter to pass in an IO mode to use when opening the file, just like <a href="#slurp">"slurp"</a> supports.</p>
|
||||
|
||||
<pre><code>$file->spew(iomode => '>:raw', $content);</code></pre>
|
||||
|
||||
<p>The default <code>iomode</code> is <code>w</code>.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="file-spew_lines-content">$file->spew_lines( $content );</dt>
|
||||
<dd>
|
||||
|
||||
<p>Just like <code>spew</code>, but, if $content is a plain scalar, appends $/ to it, or, if $content is an array ref, appends $/ to each element of the array.</p>
|
||||
|
||||
<p>Can also take an <code>iomode</code> parameter like <code>spew</code>. Again, the default <code>iomode</code> is <code>w</code>.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="file-traverse-sub-...-args">$file->traverse(sub { ... }, @args)</dt>
|
||||
<dd>
|
||||
|
||||
<p>Calls the given callback on $file. This doesn't do much on its own, but see the associated documentation in <a href="../../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/Dir.html">Path::Class::Dir</a>.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="file-remove">$file->remove()</dt>
|
||||
<dd>
|
||||
|
||||
<p>This method will remove the file in a way that works well on all platforms, and returns a boolean value indicating whether or not the file was successfully removed.</p>
|
||||
|
||||
<p><code>remove()</code> is better than simply calling Perl's <code>unlink()</code> function, because on some platforms (notably VMS) you actually may need to call <code>unlink()</code> several times before all versions of the file are gone - the <code>remove()</code> method handles this process for you.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="st-file-stat">$st = $file->stat()</dt>
|
||||
<dd>
|
||||
|
||||
<p>Invokes <code>File::stat::stat()</code> on this file and returns a <a href="../../share/perl5/5.40/File/stat.html">File::stat</a> object representing the result.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="st-file-lstat">$st = $file->lstat()</dt>
|
||||
<dd>
|
||||
|
||||
<p>Same as <code>stat()</code>, but if <code>$file</code> is a symbolic link, <code>lstat()</code> stats the link instead of the file the link points to.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="class-file-dir_class">$class = $file->dir_class()</dt>
|
||||
<dd>
|
||||
|
||||
<p>Returns the class which should be used to create directory objects.</p>
|
||||
|
||||
<p>Generally overridden whenever this class is subclassed.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="copy-file-copy_to-dest">$copy = $file->copy_to( $dest );</dt>
|
||||
<dd>
|
||||
|
||||
<p>Copies the <code>$file</code> to <code>$dest</code>. It returns a <a href="../../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/File.html">Path::Class::File</a> object when successful, <code>undef</code> otherwise.</p>
|
||||
|
||||
</dd>
|
||||
<dt id="moved-file-move_to-dest">$moved = $file->move_to( $dest );</dt>
|
||||
<dd>
|
||||
|
||||
<p>Moves the <code>$file</code> to <code>$dest</code>, and updates <code>$file</code> accordingly.</p>
|
||||
|
||||
<p>It returns <code>$file</code> is successful, <code>undef</code> otherwise.</p>
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<a href="#_podtop_"><h1 id="AUTHOR">AUTHOR</h1></a>
|
||||
|
||||
<p>Ken Williams, kwilliams@cpan.org</p>
|
||||
|
||||
<a href="#_podtop_"><h1 id="SEE-ALSO">SEE ALSO</h1></a>
|
||||
|
||||
<p><a href="../../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class.html">Path::Class</a>, <a href="../../../mnt/share/cygpkgs/perl-Path-Class/perl-Path-Class.noarch/build/blib/lib/Path/Class/Dir.html">Path::Class::Dir</a>, <a>File::Spec</a></p>
|
||||
|
||||
<table border="0" width="100%" cellspacing="0" cellpadding="3">
|
||||
<tr><td class="_podblock_" style="background-color: #cccccc; color: #000" valign="middle">
|
||||
<big><strong><span class="_podblock_"> Path::Class::File - Objects representing files</span></strong></big>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue