1789 lines
49 KiB
Plaintext
1789 lines
49 KiB
Plaintext
=pod
|
|
|
|
=for comment
|
|
DO NOT EDIT. This Pod was generated by Swim v0.1.46.
|
|
See http://github.com/ingydotnet/swim-pm#readme
|
|
|
|
=encoding utf8
|
|
|
|
=head1 NAME
|
|
|
|
IO::All - IO::All to Larry Wall!
|
|
|
|
=for html
|
|
<a href="https://travis-ci.org/ingydotnet/io-all-pm"><img src="https://travis-ci.org/ingydotnet/io-all-pm.png" alt="io-all-pm"></a>
|
|
|
|
=head1 VERSION
|
|
|
|
This document describes L<IO::All> version B<0.87>.
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
First, some safe examples:
|
|
|
|
use IO::All;
|
|
|
|
# Some of the many ways to read a whole file into a scalar
|
|
$contents = io->file('file.txt')->slurp; # Read an entire file
|
|
@files = io->dir('lib')->all; # Get a list of files
|
|
$tail = io->pipe('-| tail app.log'); # Open a pipe to a command
|
|
$line = $tail->getline; # Read from the pipe
|
|
|
|
That said, there are a lot more things that are very convenient and will help
|
|
you write code very quickly, though they should be used judiciously:
|
|
|
|
use IO::All; # Let the madness begin...
|
|
|
|
# Some of the many ways to read a whole file into a scalar
|
|
io('file.txt') > $contents; # Overloaded "arrow"
|
|
$contents < io 'file.txt'; # Flipped but same operation
|
|
$io = io 'file.txt'; # Create a new IO::All object
|
|
$contents = $$io; # Overloaded scalar dereference
|
|
$contents = $io->all; # A method to read everything
|
|
$contents = $io->slurp; # Another method for that
|
|
$contents = join '', $io->getlines; # Join the separate lines
|
|
$contents = join '', map "$_\n", @$io; # Same. Overloaded array deref
|
|
$io->tie; # Tie the object as a handle
|
|
$contents = join '', <$io>; # And use it in builtins
|
|
# and the list goes on ...
|
|
|
|
# Other file operations:
|
|
@lines = io('file.txt')->slurp; # List context slurp
|
|
$content > io('file.txt'); # Print to a file
|
|
io('file.txt')->print($content, $more); # (ditto)
|
|
$content >> io('file.txt'); # Append to a file
|
|
io('file.txt')->append($content); # (ditto)
|
|
$content << $io; # Append to a string
|
|
io('copy.txt') < io('file.txt'); $ Copy a file
|
|
io('file.txt') > io('copy.txt'); # Invokes File::Copy
|
|
io('more.txt') >> io('all.txt'); # Add on to a file
|
|
io('dir/') < io('file.txt'); $ Copy a file to a directory
|
|
io('file.txt') > io('dir/'); # Invokes File::Copy
|
|
io('more.txt') >> io('dir/'); # Add on to a file in the dir
|
|
|
|
# UTF-8 Support
|
|
$contents = io('file.txt')->utf8->all; # Turn on utf8
|
|
use IO::All -utf8; # Turn on utf8 for all io
|
|
$contents = io('file.txt')->all; # by default in this package.
|
|
|
|
# General Encoding Support
|
|
$contents = io('file.txt')->encoding('big5')->all;
|
|
use IO::All -encoding => 'big5'; # Turn on big5 for all io
|
|
$contents = io('file.txt')->all; # by default in this package.
|
|
|
|
# Print the path name of a file:
|
|
print $io->name; # The direct method
|
|
print "$io"; # Object stringifies to name
|
|
print $io; # Quotes not needed here
|
|
print $io->filename; # The file portion only
|
|
$io->os('win32'); # change the object to be a
|
|
# win32 path
|
|
print $io->ext; # The file extension only
|
|
print $io->mimetype; # The mimetype, requires a
|
|
# working File::MimeType
|
|
|
|
|
|
# Read all the files/directories in a directory:
|
|
$io = io('my/directory/'); # Create new directory object
|
|
@contents = $io->all; # Get all contents of dir
|
|
@contents = @$io; # Directory as an array
|
|
@contents = values %$io; # Directory as a hash
|
|
push @contents, $subdir # One at a time
|
|
while $subdir = $io->next;
|
|
|
|
# Print the name and file type for all the contents above:
|
|
print "$_ is a " . $_->type . "\n" # Each element of @contents
|
|
for @contents; # is an IO::All object!!
|
|
|
|
# Print first line of each file:
|
|
print $_->getline # getline gets one line
|
|
for io('dir')->all_files; # Files only
|
|
|
|
# Print names of all files/dirs three directories deep:
|
|
print "$_\n" for $io->all(3); # Pass in the depth. Default=1
|
|
|
|
# Print names of all files/dirs recursively:
|
|
print "$_\n" for $io->all(0); # Zero means all the way down
|
|
print "$_\n" for $io->All; # Capitalized shortcut
|
|
print "$_\n" for $io->deep->all; # Another way
|
|
|
|
# There are some special file names:
|
|
print io('-'); # Print STDIN to STDOUT
|
|
io('-') > io('-'); # Do it again
|
|
io('-') < io('-'); # Same. Context sensitive.
|
|
"Bad puppy" > io('='); # Message to STDERR
|
|
$string_file = io('$'); # Create string based filehandle
|
|
$temp_file = io('?'); # Create a temporary file
|
|
|
|
# Socket operations:
|
|
$server = io('localhost:5555')->fork; # Create a daemon socket
|
|
$connection = $server->accept; # Get a connection socket
|
|
$input < $connection; # Get some data from it
|
|
"Thank you!" > $connection; # Thank the caller
|
|
$connection->close; # Hang up
|
|
io(':6666')->accept->slurp > io->devnull; # Take a complaint and file it
|
|
|
|
# DBM database operations:
|
|
$dbm = io 'my/database'; # Create a database object
|
|
print $dbm->{grocery_list}; # Hash context makes it a DBM
|
|
$dbm->{todo} = $new_list; # Write to database
|
|
$dbm->dbm('GDBM_file'); # Demand specific DBM
|
|
io('mydb')->mldbm->{env} = \%ENV; # MLDBM support
|
|
|
|
# Tie::File support:
|
|
$io = io 'file.txt';
|
|
$io->[42] = 'Line Forty Three'; # Change a line
|
|
print $io->[@$io / 2]; # Print middle line
|
|
@$io = reverse @$io; # Reverse lines in a file
|
|
|
|
# Stat functions:
|
|
printf "%s %s %s\n", # Print name, uid and size of
|
|
$_->name, $_->uid, $_->size # contents of current directory
|
|
for io('.')->all;
|
|
print "$_\n" for sort # Use mtime method to sort all
|
|
{$b->mtime <=> $a->mtime} # files under current directory
|
|
io('.')->All_Files; # by recent modification time.
|
|
|
|
# File::Spec support:
|
|
$contents < io->catfile(qw(dir file.txt)); # Portable IO operation
|
|
|
|
# Miscellaneous:
|
|
@lines = io('file.txt')->chomp->slurp; # Chomp as you slurp
|
|
@chunks =
|
|
io('file.txt')->separator('xxx')->slurp; # Use alternnate record sep
|
|
$binary = io('file.bin')->binary->all; # Read a binary file
|
|
io('a-symlink')->readlink->slurp; # Readlink returns an object
|
|
print io('foo')->absolute->pathname; # Print absolute path of foo
|
|
|
|
# IO::All External Plugin Methods
|
|
io("myfile") > io->("ftp://store.org"); # Upload a file using ftp
|
|
$html < io->http("www.google.com"); # Grab a web page
|
|
io('mailto:worst@enemy.net')->print($spam); # Email a "friend"
|
|
|
|
# This is just the beginning, read on...
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
IO::All combines all of the best Perl IO modules into a single nifty object
|
|
oriented interface to greatly simplify your everyday Perl IO idioms. It
|
|
exports a single function called C<io>, which returns a new IO::All object.
|
|
And that object can do it all!
|
|
|
|
The IO::All object is a proxy for IO::File, IO::Dir, IO::Socket, Tie::File,
|
|
File::Spec, File::Path, File::MimeInfo and File::ReadBackwards; as well as all
|
|
the DBM and MLDBM modules. You can use most of the methods found in these
|
|
classes and in IO::Handle (which they inherit from). IO::All adds dozens of
|
|
other helpful idiomatic methods including file stat and manipulation
|
|
functions.
|
|
|
|
IO::All is pluggable, and modules like L<IO::All::LWP> and L<IO::All::Mailto>
|
|
add even more functionality. Optionally, every IO::All object can be tied to
|
|
itself. This means that you can use most perl IO builtins on it: readline, C<<
|
|
<> >>, getc, print, printf, syswrite, sysread, close.
|
|
|
|
The distinguishing magic of IO::All is that it will automatically open (and
|
|
close) files, directories, sockets and other IO things for you. You never need
|
|
to specify the mode (C<< < >>, C<< >> >>, etc), since it is determined by the
|
|
usage context. That means you can replace this:
|
|
|
|
open STUFF, '<', './mystuff'
|
|
or die "Can't open './mystuff' for input:\n$!";
|
|
local $/;
|
|
my $stuff = <STUFF>;
|
|
close STUFF;
|
|
|
|
with this:
|
|
|
|
my $stuff < io './mystuff';
|
|
|
|
And that is a B<good thing>!
|
|
|
|
=head1 USAGE
|
|
|
|
Normally just say:
|
|
|
|
use IO::All;
|
|
|
|
and IO::All will export a single function called C<io>, which constructs all
|
|
IO objects.
|
|
|
|
=head2 Note on C<io>
|
|
|
|
The C<io> function is a I<magic constructor>. It is easy to use and will
|
|
usually do the right thing, but can also blow up easily.
|
|
|
|
It takes a single optional argument and determines what type of IO::All
|
|
subclass object to return. With no arguments it returns an C<IO::All> object,
|
|
which has no I/O methods, but has methods to construct subclass objects like
|
|
C<IO::All::File>.
|
|
|
|
In other words, these 2 statements are usually the same:
|
|
|
|
$content = io('file.txt')->all;
|
|
$content = io->file('file.txt')->all;
|
|
|
|
Use the first form when you are demonstrating your Perl virtues of laziness
|
|
and impatience, and use the second form when your job is on the line.
|
|
|
|
=head1 METHOD ROLE CALL
|
|
|
|
Here is an alphabetical list of all the public methods that you can call on an
|
|
IO::All object.
|
|
|
|
L</abs2rel>, L</absolute>, L</accept>, L</All>, L</all>, L</All_Dirs>,
|
|
L</all_dirs>, L</All_Files>, L</all_files>, L</All_Links>, L</all_links>,
|
|
L</append>, L</appendf>, L</appendln>, L</assert>, L</atime>, L</autoclose>,
|
|
L</autoflush>, L</backwards>, L</bcc>, L</binary>, L</binmode>, L</blksize>,
|
|
L</blocks>, L</block_size>, L</buffer>, L</canonpath>, L</case_tolerant>,
|
|
L</catdir>, L</catfile>, L</catpath>, L</cc>, L</chdir>, L</chomp>, L</clear>,
|
|
L</close>, L</confess>, L</content>, L</copy>, L</ctime>, L</curdir>, L</dbm>,
|
|
L</deep>, L</device>, L</device_id>, L</devnull>, L</dir>, L</domain>,
|
|
L</empty>, L</ext>, L</encoding>, L</eof>, L</errors>, L</file>, L</filename>,
|
|
L</fileno>, L</filepath>, L</filter>, L</fork>, L</from>, L</ftp>, L</get>,
|
|
L</getc>, L</getline>, L</getlines>, L</gid>, L</glob>, L</handle>, L</head>,
|
|
L</http>, L</https>, L</inode>, L</io_handle>, L</is_absolute>, L</is_dir>,
|
|
L</is_dbm>, L</is_executable>, L</is_file>, L</is_link>, L</is_mldbm>,
|
|
L</is_open>, L</is_pipe>, L</is_readable>, L</is_socket>, L</is_stdio>,
|
|
L</is_string>, L</is_temp>, L</is_writable>, L</join>, L</length>, L</link>,
|
|
L</lock>, L</mailer>, L</mailto>, L</mimetype>, L</mkdir>, L</mkpath>,
|
|
L</mldbm>, L</mode>, L</modes>, L</mtime>, L</name>, L</new>, L</next>,
|
|
L</nlink>, L</open>, L</os> L</password>, L</path>, L</pathname>, L</perms>,
|
|
L</pipe>, L</port>, L</print>, L</printf>, L</println>, L</put>, L</rdonly>,
|
|
L</rdwr>, L</read>, L</readdir>, L</readlink>, L</recv>, L</rel2abs>,
|
|
L</relative>, L</rename>, L</request>, L</response>, L</rmdir>, L</rmtree>,
|
|
L</rootdir>, L</scalar>, L</seek>, L</send>, L</separator>, L</shutdown>,
|
|
L</size>, L</slurp>, L</socket>, L</sort>, L</splitdir>, L</splitpath>,
|
|
L</stat>, L</stdio>, L</stderr>, L</stdin>, L</stdout>, L</string>,
|
|
L</string_ref>, L</subject>, L</sysread>, L</syswrite>, L</tail>, L</tell>,
|
|
L</temp>, L</tie>, L</tmpdir>, L</to>, L</touch>, L</truncate>, L</type>,
|
|
L</user>, L</uid>, L</unlink>, L</unlock>, L</updir>, L</uri>, L</utf8>,
|
|
L</utime> and L</write>.
|
|
|
|
Each method is documented further below.
|
|
|
|
=head1 OPERATOR OVERLOADING
|
|
|
|
IO::All objects overload a small set of Perl operators to great effect. The
|
|
overloads are limited to C<< < >>, C<< << >>, C<< > >>, C<< >> >>,
|
|
dereferencing operations, and stringification.
|
|
|
|
Even though relatively few operations are overloaded, there is actually a huge
|
|
matrix of possibilities for magic. That's because the overloading is sensitive
|
|
to the types, position and context of the arguments, and an IO::All object can
|
|
be one of many types.
|
|
|
|
The most important overload to become familiar with is stringification.
|
|
IO::All objects stringify to their file or directory name. Here we print the
|
|
contents of the current directory:
|
|
|
|
perl -MIO::All -le 'print for io(".")->all'
|
|
|
|
is the same as:
|
|
|
|
perl -MIO::All -le 'print $_->name for io(".")->all'
|
|
|
|
Stringification is important because it allows IO::All operations to return
|
|
objects when they might otherwise return file names. Then the recipient can
|
|
use the result either as an object or a string.
|
|
|
|
C<< > >> and C<< < >> move data between objects in the direction pointed to by
|
|
the operator.
|
|
|
|
$content1 < io('file1');
|
|
$content1 > io('file2');
|
|
io('file2') > $content3;
|
|
io('file3') < $content3;
|
|
io('file3') > io('file4');
|
|
io('file5') < io('file4');
|
|
|
|
C<< >> >> and C<< << >> do the same thing except the recipient string or file
|
|
is appended to.
|
|
|
|
An IO::All file used as an array reference becomes tied using Tie::File:
|
|
|
|
$file = io "file";
|
|
# Print last line of file
|
|
print $file->[-1];
|
|
# Insert new line in middle of file
|
|
$file->[$#$file / 2] = 'New line';
|
|
|
|
An IO::All file used as a hash reference becomes tied to a DBM class:
|
|
|
|
io('mydbm')->{ingy} = 'YAML';
|
|
|
|
An IO::All directory used as an array reference, will expose each file or
|
|
subdirectory as an element of the array.
|
|
|
|
print "$_\n" for @{io 'dir'};
|
|
|
|
IO::All directories used as hash references have file names as keys, and
|
|
IO::All objects as values:
|
|
|
|
print io('dir')->{'foo.txt'}->slurp;
|
|
|
|
Files used as scalar references get slurped:
|
|
|
|
print ${io('dir')->{'foo.txt'}};
|
|
|
|
Not all combinations of operations and object types are supported. Some just
|
|
haven't been added yet, and some just don't make sense. If you use an invalid
|
|
combination, an error will be thrown.
|
|
|
|
=head1 COOKBOOK
|
|
|
|
This section describes some various things that you can easily cook up
|
|
with IO::All.
|
|
|
|
=head2 File Locking
|
|
|
|
IO::All makes it very easy to lock files. Just use the C<lock> method. Here's
|
|
a standalone program that demonstrates locking for both write and read:
|
|
|
|
use IO::All;
|
|
my $io1 = io('myfile')->lock;
|
|
$io1->println('line 1');
|
|
|
|
fork or do {
|
|
my $io2 = io('myfile')->lock;
|
|
print $io2->slurp;
|
|
exit;
|
|
};
|
|
|
|
sleep 1;
|
|
$io1->println('line 2');
|
|
$io1->println('line 3');
|
|
$io1->unlock;
|
|
|
|
There are a lot of subtle things going on here. An exclusive lock is issued
|
|
for C<$io1> on the first C<println>. That's because the file isn't actually
|
|
opened until the first IO operation.
|
|
|
|
When the child process tries to read the file using C<$io2>, there is a shared
|
|
lock put on it. Since C<$io1> has the exclusive lock, the slurp blocks.
|
|
|
|
The parent process sleeps just to make sure the child process gets a chance.
|
|
The parent needs to call C<unlock> or C<close> to release the lock. If all
|
|
goes well the child will print 3 lines.
|
|
|
|
=head2 In-place Editing
|
|
|
|
Because an IO::All object can be used as an array reference, operations on
|
|
arrays are supported transparently (using Tie::File) so a file can be modified
|
|
in the same way you would modify an array.
|
|
|
|
> cat > x.txt
|
|
The sexy saxophone,
|
|
|
|
got the axe.
|
|
^d
|
|
|
|
> perl -MIO::All -e 'map { s/x/X/g; $_ } @{ io(shift) }' x.txt
|
|
> cat x.txt
|
|
The seXy saXophone,
|
|
|
|
got the aXe.
|
|
|
|
This one liner uses shift() to grab the file from STDIN and create an io
|
|
object that is dereferenced using @{ } and fed to map() like any perl array
|
|
reference.
|
|
|
|
=head2 Round Robin
|
|
|
|
This simple example will read lines from a file forever. When the last line is
|
|
read, it will reopen the file and read the first one again.
|
|
|
|
my $io = io 'file1.txt';
|
|
$io->autoclose(1);
|
|
while (my $line = $io->getline || $io->getline) {
|
|
print $line;
|
|
}
|
|
|
|
=head2 Reading Backwards
|
|
|
|
If you call the C<backwards> method on an IO::All object, the C<getline> and
|
|
C<getlines> will work in reverse. They will read the lines in the file from
|
|
the end to the beginning.
|
|
|
|
my @reversed;
|
|
my $io = io('file1.txt');
|
|
$io->backwards;
|
|
while (my $line = $io->getline) {
|
|
push @reversed, $line;
|
|
}
|
|
|
|
or more simply:
|
|
|
|
my @reversed = io('file1.txt')->backwards->getlines;
|
|
|
|
The C<backwards> method returns the IO::All object so that you can chain
|
|
the calls.
|
|
|
|
NOTE: This operation requires that you have the L<File::ReadBackwards> module
|
|
installed.
|
|
|
|
=head2 Client/Server Sockets
|
|
|
|
IO::All makes it really easy to write a forking socket server and a client to
|
|
talk to it.
|
|
|
|
In this example, a server will return 3 lines of text, to every client that
|
|
calls it. Here is the server code:
|
|
|
|
use IO::All;
|
|
|
|
my $socket = io(':12345')->fork->accept;
|
|
$socket->print($_) while <DATA>;
|
|
$socket->close;
|
|
|
|
__DATA__
|
|
On your mark,
|
|
Get set,
|
|
Go!
|
|
|
|
Here is the client code:
|
|
|
|
use IO::All;
|
|
|
|
my $io = io('localhost:12345');
|
|
print while $_ = $io->getline;
|
|
|
|
You can run the server once, and then run the client repeatedly (in another
|
|
terminal window). It should print the 3 data lines each time.
|
|
|
|
Note that it is important to close the socket if the server is forking, or
|
|
else the socket won't go out of scope and close.
|
|
|
|
=head2 A Tiny Web Server
|
|
|
|
Here is how you could write a simplistic web server that works with static and
|
|
dynamic pages:
|
|
|
|
perl -MIO::All -e 'io(":8080")->fork->accept->(sub { $_[0] < io(-x $1 ? "./$1 |" : $1) if /^GET \/(.*) / })'
|
|
|
|
There is are a lot of subtle things going on here. First we accept a socket
|
|
and fork the server. Then we overload the new socket as a code ref. This code
|
|
ref takes one argument, another code ref, which is used as a callback.
|
|
|
|
The callback is called once for every line read on the socket. The line is put
|
|
into C<$_> and the socket itself is passed in to the callback.
|
|
|
|
Our callback is scanning the line in C<$_> for an HTTP GET request. If one is
|
|
found it parses the file name into C<$1>. Then we use C<$1> to create an new
|
|
IO::All file object... with a twist. If the file is executable (C<-x>), then
|
|
we create a piped command as our IO::All object. This somewhat approximates
|
|
CGI support.
|
|
|
|
Whatever the resulting object is, we direct the contents back at our socket
|
|
which is in C<$_[0]>. Pretty simple, eh?
|
|
|
|
=head2 DBM Files
|
|
|
|
IO::All file objects used as a hash reference, treat the file as a DBM tied to
|
|
a hash. Here I write my DB record to STDERR:
|
|
|
|
io("names.db")->{ingy} > io('=');
|
|
|
|
Since their are several DBM formats available in Perl, IO::All picks the first
|
|
one of these that is installed on your system:
|
|
|
|
DB_File GDBM_File NDBM_File ODBM_File SDBM_File
|
|
|
|
You can override which DBM you want for each IO::All object:
|
|
|
|
my @keys = keys %{io('mydbm')->dbm('SDBM_File')};
|
|
|
|
=head2 File Subclassing
|
|
|
|
Subclassing is easy with IO::All. Just create a new module and use IO::All as
|
|
the base class, like this:
|
|
|
|
package NewModule;
|
|
use IO::All -base;
|
|
|
|
You need to do it this way so that IO::All will export the C<io> function.
|
|
Here is a simple recipe for subclassing:
|
|
|
|
IO::Dumper inherits everything from IO::All and adds an extra method called
|
|
C<dump>, which will dump a data structure to the file we specify in the
|
|
C<io> function. Since it needs Data::Dumper to do the dumping, we override
|
|
the C<open> method to C<require Data::Dumper> and then pass control to the
|
|
real C<open>.
|
|
|
|
First the code using the module:
|
|
|
|
use IO::Dumper;
|
|
|
|
io('./mydump')->dump($hash);
|
|
|
|
And next the IO::Dumper module itself:
|
|
|
|
package IO::Dumper;
|
|
use IO::All -base;
|
|
use Data::Dumper;
|
|
|
|
sub dump {
|
|
my $self = shift;
|
|
Dumper(@_) > $self;
|
|
}
|
|
|
|
1;
|
|
|
|
=head2 Inline Subclassing
|
|
|
|
This recipe does the same thing as the previous one, but without needing to
|
|
write a separate module. The only real difference is the first line. Since you
|
|
don't "use" IO::Dumper, you need to still call its C<import> method manually.
|
|
|
|
IO::Dumper->import;
|
|
io('./mydump')->dump($hash);
|
|
|
|
package IO::Dumper;
|
|
use IO::All -base;
|
|
use Data::Dumper;
|
|
|
|
sub dump {
|
|
my $self = shift;
|
|
Dumper(@_) > $self;
|
|
}
|
|
|
|
=head1 THE IO::ALL METHODS
|
|
|
|
This section gives a full description of all of the methods that you can call
|
|
on IO::All objects. The methods have been grouped into subsections based on
|
|
object construction, option settings, configuration, action methods and
|
|
support for specific modules.
|
|
|
|
=head2 Object Construction and Initialization Methods
|
|
|
|
=over
|
|
|
|
=item new
|
|
|
|
There are three ways to create a new IO::All object. The first is with the
|
|
special function C<io> which really just calls C<< IO::All->new >>. The second
|
|
is by calling C<new> as a class method. The third is calling C<new> as an
|
|
object instance method. In this final case, the new objects attributes are
|
|
copied from the instance object.
|
|
|
|
io(file-descriptor);
|
|
IO::All->new(file-descriptor);
|
|
$io->new(file-descriptor);
|
|
|
|
All three forms take a single argument, a file descriptor. A file descriptor
|
|
can be any of the following:
|
|
|
|
- A file name
|
|
- A file handle
|
|
- A directory name
|
|
- A directory handle
|
|
- A typeglob reference
|
|
- A piped shell command. eg '| ls -al'
|
|
- A socket domain/port. eg 'perl.com:5678'
|
|
- '-' means STDIN or STDOUT (depending on usage)
|
|
- '=' means STDERR
|
|
- '$' means an in memory filehandle object
|
|
- '?' means a temporary file
|
|
- A URI including: http, https, ftp and mailto
|
|
- An IO::All object
|
|
|
|
If you provide an IO::All object, you will simply get that I<same object>
|
|
returned from the constructor.
|
|
|
|
If no file descriptor is provided, an object will still be created, but it
|
|
must be defined by one of the following methods before it can be used for I/O:
|
|
|
|
=item file
|
|
|
|
io->file("path/to/my/file.txt");
|
|
|
|
Using the C<file> method sets the type of the object to I<file> and sets the
|
|
pathname of the file if provided.
|
|
|
|
It might be important to use this method if you had a file whose name was C<'-
|
|
'>, or if the name might otherwise be confused with a directory or a socket.
|
|
In this case, either of these statements would work the same:
|
|
|
|
my $file = io('-')->file;
|
|
my $file = io->file('-');
|
|
|
|
=item dir
|
|
|
|
io->dir($dir_name);
|
|
|
|
Make the object be of type I<directory>.
|
|
|
|
=item socket
|
|
|
|
io->socket("${domain}:${port}");
|
|
|
|
Make the object be of type I<socket>.
|
|
|
|
=item link
|
|
|
|
io->link($link_name);
|
|
|
|
Make the object be of type I<link>.
|
|
|
|
=item pipe
|
|
|
|
io->pipe($pipe_command);
|
|
|
|
Make the object be of type I<pipe>. The following three statements are
|
|
equivalent:
|
|
|
|
my $io = io('ls -l |');
|
|
my $io = io('ls -l')->pipe;
|
|
my $io = io->pipe('ls -l');
|
|
|
|
=item dbm
|
|
|
|
This method takes the names of zero or more DBM modules. The first one that is
|
|
available is used to process the dbm file.
|
|
|
|
io('mydbm')->dbm('NDBM_File', 'SDBM_File')->{author} = 'ingy';
|
|
|
|
If no module names are provided, the first available of the following is used:
|
|
|
|
DB_File GDBM_File NDBM_File ODBM_File SDBM_File
|
|
|
|
=item mldbm
|
|
|
|
Similar to the C<dbm> method, except create a Multi Level DBM object using the
|
|
MLDBM module.
|
|
|
|
This method takes the names of zero or more DBM modules and an optional
|
|
serialization module. The first DBM module that is available is used to
|
|
process the MLDBM file. The serialization module can be Data::Dumper, Storable
|
|
or FreezeThaw.
|
|
|
|
io('mymldbm')->mldbm('GDBM_File', 'Storable')->{author} =
|
|
{nickname => 'ingy'};
|
|
|
|
=item string
|
|
|
|
Make the object be an in memory filehandle. These are equivalent:
|
|
|
|
my $io = io('$');
|
|
my $io = io->string;
|
|
|
|
=item temp
|
|
|
|
Make the object represent a temporary file. It will automatically be open for
|
|
both read and write.
|
|
|
|
=item stdio
|
|
|
|
Make the object represent either STDIN or STDOUT depending on how it is used
|
|
subsequently. These are equivalent:
|
|
|
|
my $io = io('-');
|
|
my $io = io->stdin;
|
|
|
|
=item stdin
|
|
|
|
Make the object represent STDIN.
|
|
|
|
=item stdout
|
|
|
|
Make the object represent STDOUT.
|
|
|
|
=item stderr
|
|
|
|
Make the object represent STDERR.
|
|
|
|
=item handle
|
|
|
|
io->handle($io_handle);
|
|
|
|
Forces the object to be created from an pre-existing IO handle. You can chain
|
|
calls together to indicate the type of handle:
|
|
|
|
my $file_object = io->file->handle($file_handle);
|
|
my $dir_object = io->dir->handle($dir_handle);
|
|
|
|
=item http
|
|
|
|
Make the object represent an HTTP URI. Requires IO-All-LWP.
|
|
|
|
=item https
|
|
|
|
Make the object represent an HTTPS URI. Requires IO-All-LWP.
|
|
|
|
=item ftp
|
|
|
|
Make the object represent an FTP URI. Requires IO-All-LWP.
|
|
|
|
=item mailto
|
|
|
|
Make the object represent a C<mailto:> URI. Requires IO-All-Mailto.
|
|
|
|
=back
|
|
|
|
If you need to use the same options to create a lot of objects, and don't want
|
|
to duplicate the code, just create a dummy object with the options you want,
|
|
and use that object to spawn other objects.
|
|
|
|
my $lt = io->lock->tie;
|
|
...
|
|
my $io1 = $lt->new('file1');
|
|
my $io2 = $lt->new('file2');
|
|
|
|
Since the new method copies attributes from the calling object, both C<$io1>
|
|
and C<$io2> will be locked and tied.
|
|
|
|
=head2 Option Setting Methods
|
|
|
|
The following methods don't do any actual II<O, but they specify options about
|
|
how the I>O should be done.
|
|
|
|
Each option can take a single argument of 0 or 1. If no argument is given, the
|
|
value 1 is assumed. Passing 0 turns the option off.
|
|
|
|
All of these options return the object reference that was used to invoke them.
|
|
This is so that the option methods can be chained together. For example:
|
|
|
|
my $io = io('path/file')->tie->assert->chomp->lock;
|
|
|
|
=over
|
|
|
|
=item absolute
|
|
|
|
Indicates that the C<pathname> for the object should be made absolute.
|
|
|
|
# Print the full path of the current working directory
|
|
# (like pwd).
|
|
|
|
use IO::All;
|
|
|
|
print io->curdir->absolute;
|
|
|
|
=item assert
|
|
|
|
This method ensures that the path for a file or directory actually exists
|
|
before the file is open. If the path does not exist, it is created.
|
|
|
|
For example, here is a program called "create-cat-to" that outputs to a file
|
|
that it creates.
|
|
|
|
#!/usr/bin/perl
|
|
|
|
# create-cat-to.pl
|
|
# cat to a file that can be created.
|
|
|
|
use strict;
|
|
use warnings;
|
|
|
|
use IO::All;
|
|
|
|
my $filename = shift(@ARGV);
|
|
|
|
# Create a file called $filename, including all leading components.
|
|
io('-') > io->file($filename)->assert;
|
|
|
|
Here's an example use of it:
|
|
|
|
$ ls -l
|
|
total 0
|
|
$ echo "Hello World" | create-cat-to one/two/three/four.txt
|
|
$ ls -l
|
|
total 4
|
|
drwxr-xr-x 3 shlomif shlomif 4096 2010-10-14 18:03 one/
|
|
$ cat one/two/three/four.txt
|
|
Hello World
|
|
$
|
|
|
|
=item autoclose
|
|
|
|
By default, IO::All will close an object opened for input when EOF is reached.
|
|
By closing the handle early, one can immediately do other operations on the
|
|
object without first having to close it.
|
|
|
|
This option is on by default, so if you don't want this behaviour, say so
|
|
like this:
|
|
|
|
$io->autoclose(0);
|
|
|
|
The object will then be closed when C<$io> goes out of scope, or you manually
|
|
call C<< $io->close >>.
|
|
|
|
=item autoflush
|
|
|
|
Proxy for IO::Handle::autoflush
|
|
|
|
=item backwards
|
|
|
|
Sets the object to 'backwards' mode. All subsequent C<getline> operations will
|
|
read backwards from the end of the file.
|
|
|
|
Requires the File::ReadBackwards CPAN module.
|
|
|
|
=item binary
|
|
|
|
Adds C<:raw> to the list of PerlIO layers applied after C<open>, and applies
|
|
it immediately on an open handle.
|
|
|
|
=item chdir
|
|
|
|
chdir() to the pathname of a directory object. When object goes out of scope,
|
|
chdir back to starting directory.
|
|
|
|
=item chomp
|
|
|
|
Indicates that all operations that read lines should chomp the lines. If the
|
|
C<separator> method has been called, chomp will remove that value from the end
|
|
of each record.
|
|
|
|
Note that C<chomp> may cause the following idiom to halt prematurely (e.g., if
|
|
C<separator> is C<\n> (the default) and C<chomp> is in effect, then this
|
|
command will stop reading at the first blank line):
|
|
|
|
while ( my $line = $io->getline ) {...}
|
|
|
|
Try the following instead:
|
|
|
|
while ( defined(my $line = $io->getline) ) {...}
|
|
|
|
=item confess
|
|
|
|
Errors should be reported with the very detailed Carp::confess function.
|
|
|
|
=item deep
|
|
|
|
Indicates that calls to the C<all> family of methods should search directories
|
|
as deep as possible.
|
|
|
|
=item fork
|
|
|
|
Indicates that the process should automatically be forked inside the C<accept>
|
|
socket method.
|
|
|
|
=item lock
|
|
|
|
Indicate that operations on an object should be locked using flock.
|
|
|
|
=item rdonly
|
|
|
|
This option indicates that certain operations like DBM and Tie::File access
|
|
should be done in read-only mode.
|
|
|
|
=item rdwr
|
|
|
|
This option indicates that DBM and MLDBM files should be opened in
|
|
read/write mode.
|
|
|
|
=item relative
|
|
|
|
Indicates that the C<pathname> for the object should be made relative. If
|
|
passed an argument, path will be made relative to passed argument.
|
|
|
|
=item sort
|
|
|
|
Indicates whether objects returned from one of the C<all> methods will be in
|
|
sorted order by name. True by default.
|
|
|
|
=item tie
|
|
|
|
Indicate that the object should be tied to itself, thus allowing it to be used
|
|
as a filehandle in any of Perl's builtin IO operations.
|
|
|
|
my $io = io('foo')->tie;
|
|
@lines = <$io>;
|
|
|
|
=item utf8
|
|
|
|
Adds C<:encoding(UTF-8)> to the list of PerlIO layers applied after C<open>,
|
|
and applies it immediately on an open handle.
|
|
|
|
=back
|
|
|
|
=head2 Configuration Methods
|
|
|
|
The following methods don't do any actual I/O, but they set specific values to
|
|
configure the IO::All object.
|
|
|
|
If these methods are passed no argument, they will return their current value.
|
|
If arguments are passed they will be used to set the current value, and the
|
|
object reference will be returned for potential method chaining.
|
|
|
|
=over
|
|
|
|
=item bcc
|
|
|
|
Set the Bcc field for a mailto object.
|
|
|
|
=item binmode
|
|
|
|
Adds the specified layer to the list of PerlIO layers applied after C<open>,
|
|
and applies it immediately on an open handle. Does a bare C<binmode> when
|
|
called without argument.
|
|
|
|
=item block_size
|
|
|
|
The default length to be used for C<read> and C<sysread> calls.
|
|
Defaults to 1024.
|
|
|
|
=item buffer
|
|
|
|
Returns a reference to the internal buffer, which is a scalar. You can use
|
|
this method to set the buffer to a scalar of your choice. (You can just pass
|
|
in the scalar, rather than a reference to it.)
|
|
|
|
This is the buffer that C<read> and C<write> will use by default.
|
|
|
|
You can easily have IO::All objects use the same buffer:
|
|
|
|
my $input = io('abc');
|
|
my $output = io('xyz');
|
|
my $buffer;
|
|
$output->buffer($input->buffer($buffer));
|
|
$output->write while $input->read;
|
|
|
|
=item cc
|
|
|
|
Set the Cc field for a mailto object.
|
|
|
|
=item content
|
|
|
|
Get or set the content for an LWP operation manually.
|
|
|
|
=item domain
|
|
|
|
Set the domain name or ip address that a socket should use.
|
|
|
|
=item encoding
|
|
|
|
Adds the specified encoding to the list of PerlIO layers applied after
|
|
C<open>, and applies it immediately on an open handle. Requires an argument.
|
|
|
|
=item errors
|
|
|
|
Use this to set a subroutine reference that gets called when an internal error
|
|
is thrown.
|
|
|
|
=item filter
|
|
|
|
Use this to set a subroutine reference that will be used to grep which objects
|
|
get returned on a call to one of the C<all> methods. For example:
|
|
|
|
my @odd = io->curdir->filter(sub {$_->size % 2})->All_Files;
|
|
|
|
C<@odd> will contain all the files under the current directory whose size is
|
|
an odd number of bytes.
|
|
|
|
=item from
|
|
|
|
Indicate the sender for a mailto object.
|
|
|
|
=item mailer
|
|
|
|
Set the mailer program for a mailto transaction. Defaults to 'sendmail'.
|
|
|
|
=item mode
|
|
|
|
Set the mode for which the file should be opened. Examples:
|
|
|
|
$io->mode('>>')->open;
|
|
$io->mode(O_RDONLY);
|
|
|
|
my $log_appender = io->file('/var/log/my-application.log')
|
|
->mode('>>')->open();
|
|
|
|
$log_appender->print("Stardate 5987.6: Mission accomplished.");
|
|
|
|
=item name
|
|
|
|
Set or get the name of the file or directory represented by the IO::All
|
|
object.
|
|
|
|
=item password
|
|
|
|
Set the password for an LWP transaction.
|
|
|
|
=item perms
|
|
|
|
Sets the permissions to be used if the file/directory needs to be created.
|
|
|
|
=item port
|
|
|
|
Set the port number that a socket should use.
|
|
|
|
=item request
|
|
|
|
Manually specify the request object for an LWP transaction.
|
|
|
|
=item response
|
|
|
|
Returns the resulting response object from an LWP transaction.
|
|
|
|
=item separator
|
|
|
|
Sets the record (line) separator to whatever value you pass it. Default is
|
|
C<\n>. Affects the chomp setting too.
|
|
|
|
=item string_ref
|
|
|
|
Returns a reference to the internal string that is acting like a file.
|
|
|
|
=item subject
|
|
|
|
Set the subject for a mailto transaction.
|
|
|
|
=item to
|
|
|
|
Set the recipient address for a mailto request.
|
|
|
|
=item uri
|
|
|
|
Direct access to the URI used in LWP transactions.
|
|
|
|
=item user
|
|
|
|
Set the user name for an LWP transaction.
|
|
|
|
=back
|
|
|
|
=head2 IO Action Methods
|
|
|
|
These are the methods that actually perform I/O operations on an IO::All
|
|
object. The stat methods and the File::Spec methods are documented in separate
|
|
sections below.
|
|
|
|
=over
|
|
|
|
=item accept
|
|
|
|
For sockets. Opens a server socket (LISTEN => 1, REUSE => 1). Returns an
|
|
IO::All socket object that you are listening on.
|
|
|
|
If the C<fork> method was called on the object, the process will automatically
|
|
be forked for every connection.
|
|
|
|
=item all
|
|
|
|
Read all contents into a single string.
|
|
|
|
compare(io('file1')->all, io('file2')->all);
|
|
|
|
=item all (For directories)
|
|
|
|
Returns a list of IO::All objects for all files and subdirectories in a
|
|
directory.
|
|
|
|
'.' and '..' are excluded.
|
|
|
|
Takes an optional argument telling how many directories deep to search. The
|
|
default is 1. Zero (0) means search as deep as possible.
|
|
|
|
The filter method can be used to limit the results.
|
|
|
|
The items returned are sorted by name unless C<< ->sort(0) >> is used.
|
|
|
|
=item All
|
|
|
|
Same as C<all(0)>.
|
|
|
|
=item all_dirs
|
|
|
|
Same as C<all>, but only return directories.
|
|
|
|
=item All_Dirs
|
|
|
|
Same as C<all_dirs(0)>.
|
|
|
|
=item all_files
|
|
|
|
Same as C<all>, but only return files.
|
|
|
|
=item All_Files
|
|
|
|
Same as C<all_files(0)>.
|
|
|
|
=item all_links
|
|
|
|
Same as C<all>, but only return links.
|
|
|
|
=item All_Links
|
|
|
|
Same as C<all_links(0)>.
|
|
|
|
=item append
|
|
|
|
Same as print, but sets the file mode to '>>'.
|
|
|
|
=item appendf
|
|
|
|
Same as printf, but sets the file mode to '>>'.
|
|
|
|
=item appendln
|
|
|
|
Same as println, but sets the file mode to '>>'.
|
|
|
|
=item clear
|
|
|
|
Clear the internal buffer. This method is called by C<write> after it writes
|
|
the buffer. Returns the object reference for chaining.
|
|
|
|
=item close
|
|
|
|
Close will basically unopen the object, which has different meanings for
|
|
different objects. For files and directories it will close and release the
|
|
handle. For sockets it calls shutdown. For tied things it unties them, and it
|
|
unlocks locked things.
|
|
|
|
=item copy
|
|
|
|
Copies the object to the path passed. Works on both files and directories, but
|
|
directories require C<File::Copy::Recursive> to be installed.
|
|
|
|
=item empty
|
|
|
|
Returns true if a file exists but has no size, or if a directory exists but
|
|
has no contents.
|
|
|
|
=item eof
|
|
|
|
Proxy for IO::Handle::eof
|
|
|
|
=item ext
|
|
|
|
Returns the extension of the file. Can also be spelled as C<extension>
|
|
|
|
=item exists
|
|
|
|
Returns whether or not the file or directory exists.
|
|
|
|
=item filename
|
|
|
|
Return the name portion of the file path in the object. For example:
|
|
|
|
io('my/path/file.txt')->filename;
|
|
|
|
would return C<file.txt>.
|
|
|
|
=item fileno
|
|
|
|
Proxy for IO::Handle::fileno
|
|
|
|
=item filepath
|
|
|
|
Return the path portion of the file path in the object. For example:
|
|
|
|
io('my/path/file.txt')->filepath;
|
|
|
|
would return C<my/path>.
|
|
|
|
=item get
|
|
|
|
Perform an LWP GET request manually.
|
|
|
|
=item getc
|
|
|
|
Proxy for IO::Handle::getc
|
|
|
|
=item getline
|
|
|
|
Calls IO::File::getline. You can pass in an optional record separator.
|
|
|
|
=item getlines
|
|
|
|
Calls IO::File::getlines. You can pass in an optional record separator.
|
|
|
|
=item glob
|
|
|
|
Creates IO::All objects for the files matching the glob in the IO::All::Dir.
|
|
For example:
|
|
|
|
io->dir($ENV{HOME})->glob('*.txt')
|
|
|
|
=item head
|
|
|
|
Return the first 10 lines of a file. Takes an optional argument which is the
|
|
number of lines to return. Works as expected in list and scalar context. Is
|
|
subject to the current line separator.
|
|
|
|
=item io_handle
|
|
|
|
Direct access to the actual IO::Handle object being used on an opened
|
|
IO::All object.
|
|
|
|
=item is_dir
|
|
|
|
Returns boolean telling whether or not the IO::All object represents a
|
|
directory.
|
|
|
|
=item is_executable
|
|
|
|
Returns true if file or directory is executable.
|
|
|
|
=item is_dbm
|
|
|
|
Returns boolean telling whether or not the IO::All object represents a dbm
|
|
file.
|
|
|
|
=item is_file
|
|
|
|
Returns boolean telling whether or not the IO::All object represents a file.
|
|
|
|
=item is_link
|
|
|
|
Returns boolean telling whether or not the IO::All object represents a
|
|
symlink.
|
|
|
|
=item is_mldbm
|
|
|
|
Returns boolean telling whether or not the IO::All object represents a
|
|
mldbm file.
|
|
|
|
=item is_open
|
|
|
|
Indicates whether the IO::All is currently open for input/output.
|
|
|
|
=item is_pipe
|
|
|
|
Returns boolean telling whether or not the IO::All object represents a pipe
|
|
operation.
|
|
|
|
=item is_readable
|
|
|
|
Returns true if file or directory is readable.
|
|
|
|
=item is_socket
|
|
|
|
Returns boolean telling whether or not the IO::All object represents a socket.
|
|
|
|
=item is_stdio
|
|
|
|
Returns boolean telling whether or not the IO::All object represents a STDIO
|
|
file handle.
|
|
|
|
=item is_string
|
|
|
|
Returns boolean telling whether or not the IO::All object represents an in
|
|
memory filehandle.
|
|
|
|
=item is_temp
|
|
|
|
Returns boolean telling whether or not the IO::All object represents a
|
|
temporary file.
|
|
|
|
=item is_writable
|
|
|
|
Returns true if file or directory is writable. Can also be spelled as
|
|
C<is_writeable>.
|
|
|
|
=item length
|
|
|
|
Return the length of the internal buffer.
|
|
|
|
=item mimetype
|
|
|
|
Return the mimetype of the file.
|
|
|
|
Requires a working installation of the L<File::MimeInfo> CPAN module.
|
|
|
|
=item mkdir
|
|
|
|
Create the directory represented by the object.
|
|
|
|
=item mkpath
|
|
|
|
Create the directory represented by the object, when the path contains more
|
|
than one directory that doesn't exist. Proxy for File::Path::mkpath.
|
|
|
|
=item next
|
|
|
|
For a directory, this will return a new IO::All object for each file or
|
|
subdirectory in the directory. Return undef on EOD.
|
|
|
|
=item open
|
|
|
|
Open the IO::All object. Takes two optional arguments C<mode> and C<perms>,
|
|
which can also be set ahead of time using the C<mode> and C<perms> methods.
|
|
|
|
NOTE: Normally you won't need to call open (or mode/perms), since this happens
|
|
automatically for most operations.
|
|
|
|
=item os
|
|
|
|
Change the object's os representation. Valid options are: C<win32>, C<unix>,
|
|
C<vms>, C<mac>, C<os2>.
|
|
|
|
=item pathname
|
|
|
|
Return the absolute or relative pathname for a file or directory, depending on
|
|
whether object is in C<absolute> or C<relative> mode.
|
|
|
|
=item print
|
|
|
|
Proxy for IO::Handle::print
|
|
|
|
=item printf
|
|
|
|
Proxy for IO::Handle::printf
|
|
|
|
=item println
|
|
|
|
Same as print, but adds newline to each argument unless it already ends with
|
|
one.
|
|
|
|
=item put
|
|
|
|
Perform an LWP PUT request manually.
|
|
|
|
=item read
|
|
|
|
This method varies depending on its context. Read carefully (no pun intended).
|
|
|
|
For a file, this will proxy IO::File::read. This means you must pass it a
|
|
buffer, a length to read, and optionally a buffer offset for where to put the
|
|
data that is read. The function returns the length actually read (which is
|
|
zero at EOF).
|
|
|
|
If you don't pass any arguments for a file, IO::All will use its own internal
|
|
buffer, a default length, and the offset will always point at the end of the
|
|
buffer. The buffer can be accessed with the C<buffer> method. The length can
|
|
be set with the C<block_size> method. The default length is 1024 bytes. The
|
|
C<clear> method can be called to clear the buffer.
|
|
|
|
For a directory, this will proxy IO::Dir::read.
|
|
|
|
=item readdir
|
|
|
|
Similar to the Perl C<readdir> builtin. In scalar context, return the next
|
|
directory entry (ie file or directory name), or undef on end of directory. In
|
|
list context, return all directory entries.
|
|
|
|
Note that C<readdir> does not return the special C<.> and C<..> entries.
|
|
|
|
=item readline
|
|
|
|
Same as C<getline>.
|
|
|
|
=item readlink
|
|
|
|
Calls Perl's readlink function on the link represented by the object.
|
|
Instead of returning the file path, it returns a new IO::All object using
|
|
the file path.
|
|
|
|
=item recv
|
|
|
|
Proxy for IO::Socket::recv
|
|
|
|
=item rename
|
|
|
|
my $new = $io->rename('new-name');
|
|
|
|
Calls Perl's rename function and returns an IO::All object for the renamed
|
|
file. Returns false if the rename failed.
|
|
|
|
=item rewind
|
|
|
|
Proxy for IO::Dir::rewind
|
|
|
|
=item rmdir
|
|
|
|
Delete the directory represented by the IO::All object.
|
|
|
|
=item rmtree
|
|
|
|
Delete the directory represented by the IO::All object and all the files and
|
|
directories beneath it. Proxy for File::Path::rmtree.
|
|
|
|
=item scalar
|
|
|
|
Deprecated. Same as C<all()>.
|
|
|
|
=item seek
|
|
|
|
Proxy for IO::Handle::seek. If you use seek on an unopened file, it will be
|
|
opened for both read and write.
|
|
|
|
=item send
|
|
|
|
Proxy for IO::Socket::send
|
|
|
|
=item shutdown
|
|
|
|
Proxy for IO::Socket::shutdown
|
|
|
|
=item slurp
|
|
|
|
Read all file content in one operation. Returns the file content as a string.
|
|
In list context returns every line in the file.
|
|
|
|
=item stat
|
|
|
|
Proxy for IO::Handle::stat
|
|
|
|
=item sysread
|
|
|
|
Proxy for IO::Handle::sysread
|
|
|
|
=item syswrite
|
|
|
|
Proxy for IO::Handle::syswrite
|
|
|
|
=item tail
|
|
|
|
Return the last 10 lines of a file. Takes an optional argument which is the
|
|
number of lines to return. Works as expected in list and scalar context. Is
|
|
subject to the current line separator.
|
|
|
|
=item tell
|
|
|
|
Proxy for IO::Handle::tell
|
|
|
|
=item throw
|
|
|
|
This is an internal method that gets called whenever there is an error. It
|
|
could be useful to override it in a subclass, to provide more control in
|
|
error handling.
|
|
|
|
=item touch
|
|
|
|
Update the atime and mtime values for a file or directory. Creates an empty
|
|
file if the file does not exist.
|
|
|
|
=item truncate
|
|
|
|
Proxy for IO::Handle::truncate
|
|
|
|
=item type
|
|
|
|
Returns a string indicated the type of io object. Possible values are:
|
|
|
|
file
|
|
dir
|
|
link
|
|
socket
|
|
string
|
|
pipe
|
|
|
|
Returns undef if type is not determinable.
|
|
|
|
=item unlink
|
|
|
|
Unlink (delete) the file represented by the IO::All object.
|
|
|
|
NOTE: You can unlink a file after it is open, and continue using it until it
|
|
is closed.
|
|
|
|
=item unlock
|
|
|
|
Release a lock from an object that used the C<lock> method.
|
|
|
|
=item utime
|
|
|
|
Proxy for the utime Perl function.
|
|
|
|
=item write
|
|
|
|
Opposite of C<read> for file operations only.
|
|
|
|
NOTE: When used with the automatic internal buffer, C<write> will clear the
|
|
buffer after writing it.
|
|
|
|
=back
|
|
|
|
=head2 Stat Methods
|
|
|
|
This methods get individual values from a stat call on the file, directory or
|
|
handle represented by the IO::All object.
|
|
|
|
=over
|
|
|
|
=item atime
|
|
|
|
Last access time in seconds since the epoch
|
|
|
|
=item blksize
|
|
|
|
Preferred block size for file system I/O
|
|
|
|
=item blocks
|
|
|
|
Actual number of blocks allocated
|
|
|
|
=item ctime
|
|
|
|
Inode change time in seconds since the epoch
|
|
|
|
=item device
|
|
|
|
Device number of filesystem
|
|
|
|
=item device_id
|
|
|
|
Device identifier for special files only
|
|
|
|
=item gid
|
|
|
|
Numeric group id of file's owner
|
|
|
|
=item inode
|
|
|
|
Inode number
|
|
|
|
=item modes
|
|
|
|
File mode - type and permissions
|
|
|
|
=item mtime
|
|
|
|
Last modify time in seconds since the epoch
|
|
|
|
=item nlink
|
|
|
|
Number of hard links to the file
|
|
|
|
=item size
|
|
|
|
Total size of file in bytes
|
|
|
|
=item uid
|
|
|
|
Numeric user id of file's owner
|
|
|
|
=back
|
|
|
|
=head2 File::Spec Methods
|
|
|
|
These methods are all adaptations from File::Spec. Each method actually does
|
|
call the matching File::Spec method, but the arguments and return values
|
|
differ slightly. Instead of being file and directory B<names>, they are
|
|
IO::All B<objects>. Since IO::All objects stringify to their names, you can
|
|
generally use the methods just like File::Spec.
|
|
|
|
=over
|
|
|
|
=item abs2rel
|
|
|
|
Returns the relative path for the absolute path in the IO::All object. Can
|
|
take an optional argument indicating the base path.
|
|
|
|
=item canonpath
|
|
|
|
Returns the canonical path for the IO::All object. The canonical path is the
|
|
fully resolved path if the file exists, so any symlinks will be resolved.
|
|
|
|
=item case_tolerant
|
|
|
|
Returns 0 or 1 indicating whether the file system is case tolerant. Since an
|
|
active IO::All object is not needed for this function, you can code it like:
|
|
|
|
IO::All->case_tolerant;
|
|
|
|
or more simply:
|
|
|
|
io->case_tolerant;
|
|
|
|
=item catdir
|
|
|
|
Concatenate the directory components together, and return a new IO::All object
|
|
representing the resulting directory.
|
|
|
|
=item catfile
|
|
|
|
Concatenate the directory and file components together, and return a new
|
|
IO::All object representing the resulting file.
|
|
|
|
my $contents = io->catfile(qw(dir subdir file))->slurp;
|
|
|
|
This is a very portable way to read C<dir/subdir/file>.
|
|
|
|
=item catpath
|
|
|
|
Concatenate the volume, directory and file components together, and return a
|
|
new IO::All object representing the resulting file.
|
|
|
|
=item curdir
|
|
|
|
Returns an IO::All object representing the current directory.
|
|
|
|
=item devnull
|
|
|
|
Returns an IO::All object representing the C</dev/null> file.
|
|
|
|
=item is_absolute
|
|
|
|
Returns 0 or 1 indicating whether the C<name> field of the IO::All object is
|
|
an absolute path.
|
|
|
|
=item join
|
|
|
|
Same as C<catfile>.
|
|
|
|
=item path
|
|
|
|
Returns a list of IO::All directory objects for each directory in your path.
|
|
|
|
=item rel2abs
|
|
|
|
Returns the absolute path for the relative path in the IO::All object. Can
|
|
take an optional argument indicating the base path.
|
|
|
|
=item rootdir
|
|
|
|
Returns an IO::All object representing the root directory on your file system.
|
|
|
|
=item splitdir
|
|
|
|
Returns a list of the directory components of a path in an IO::All object.
|
|
|
|
=item splitpath
|
|
|
|
Returns a volume directory and file component of a path in an IO::All object.
|
|
|
|
=item tmpdir
|
|
|
|
Returns an IO::All object representing a temporary directory on your
|
|
file system.
|
|
|
|
=item updir
|
|
|
|
Returns an IO::All object representing the current parent directory.
|
|
|
|
=back
|
|
|
|
=head1 OPERATIONAL NOTES
|
|
|
|
=over
|
|
|
|
=item Reblessing
|
|
|
|
Each IO::All object gets reblessed into an IO::All::* object as soon as
|
|
IO::All can determine what type of object it should be. Sometimes it gets
|
|
reblessed more than once:
|
|
|
|
my $io = io('mydbm.db');
|
|
$io->dbm('DB_File');
|
|
$io->{foo} = 'bar';
|
|
|
|
In the first statement, $io has a reference value of 'IO::All::File', if
|
|
C<mydbm.db> exists. In the second statement, the object is reblessed into
|
|
class 'IO::All::DBM'.
|
|
|
|
=item Auto-Open
|
|
|
|
An IO::All object will automatically be opened as soon as there is enough
|
|
contextual information to know what type of object it is, and what mode it
|
|
should be opened for. This is usually when the first read or write operation
|
|
is invoked but might be sooner.
|
|
|
|
=item Auto-Mode
|
|
|
|
The mode for an object to be opened with is determined heuristically unless
|
|
specified explicitly.
|
|
|
|
=item Auto-Close
|
|
|
|
For input, IO::All objects will automatically be closed after EOF (or EOD).
|
|
For output, the object closes when it goes out of scope.
|
|
|
|
To keep input objects from closing at EOF, do this:
|
|
|
|
$io->autoclose(0);
|
|
|
|
=item Explicit open and close
|
|
|
|
You can always call C<open> and C<close> explicitly, if you need that level of
|
|
control. To test if an object is currently open, use the C<is_open> method.
|
|
|
|
=item Overload
|
|
|
|
Overloaded operations return the target object, if one exists.
|
|
|
|
This would set C<$xxx> to the IO::All object:
|
|
|
|
my $xxx = $contents > io('file.txt');
|
|
|
|
While this would set C<$xxx> to the content string:
|
|
|
|
my $xxx = $contents < io('file.txt');
|
|
|
|
=back
|
|
|
|
=head1 STABILITY
|
|
|
|
The goal of the IO::All project is to continually refine the module to be as
|
|
simple and consistent to use as possible. Therefore, in the early stages of
|
|
the project, I will not hesitate to break backwards compatibility with other
|
|
versions of IO::All if I can find an easier and clearer way to do a
|
|
particular thing.
|
|
|
|
IO is tricky stuff. There is definitely more work to be done. On the other
|
|
hand, this module relies heavily on very stable existing IO modules; so it may
|
|
work fairly well.
|
|
|
|
I am sure you will find many unexpected "features". Please send all problems,
|
|
ideas and suggestions to ingy@cpan.org.
|
|
|
|
=head2 Known Bugs and Deficiencies
|
|
|
|
Not all possible combinations of objects and methods have been tested. There
|
|
are many many combinations. All of the examples have been tested. If you find
|
|
a bug with a particular combination of calls, let me know.
|
|
|
|
If you call a method that does not make sense for a particular object, the
|
|
result probably won't make sense. Little attempt is made to check for
|
|
improper usage.
|
|
|
|
=head1 CREDITS
|
|
|
|
A lot of people have sent in suggestions, that have become a part of IO::All.
|
|
Thank you.
|
|
|
|
Special thanks to Ian Langworth for continued testing and patching.
|
|
|
|
Thank you Simon Cozens for tipping me off to the overloading possibilities.
|
|
|
|
Finally, thanks to Autrijus Tang, for always having one more good idea.
|
|
|
|
(It seems IO::All of it to a lot of people!)
|
|
|
|
=head1 REPOSITORY AND COMMUNITY
|
|
|
|
The IO::All module can be found on CPAN and on GitHub:
|
|
L<http://github.com/ingydotnet/io-all-pm>.
|
|
|
|
Please join the IO::All discussion on #io-all on irc.perl.org.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
=over
|
|
|
|
=item * L<File::Spec>
|
|
|
|
=item * L<File::Path>
|
|
|
|
=item * L<File::ReadBackwards>
|
|
|
|
=item * L<File::MimeInfo>
|
|
|
|
=item * L<IO::Handle>
|
|
|
|
=item * L<IO::File>
|
|
|
|
=item * L<IO::Dir>
|
|
|
|
=item * L<IO::Socket>
|
|
|
|
=item * L<Tie::File>
|
|
|
|
=back
|
|
|
|
=head1 AUTHOR
|
|
|
|
Ingy döt Net <ingy@cpan.org>
|
|
|
|
=head1 COPYRIGHT AND LICENSE
|
|
|
|
Copyright 2004-2017. Ingy döt Net.
|
|
|
|
This program is free software; you can redistribute it and/or modify it under
|
|
the same terms as Perl itself.
|
|
|
|
See L<http://www.perl.com/perl/misc/Artistic.html>
|
|
|
|
=cut
|