IO::Moose::Handle - Reimplementation of IO::Handle with improvements |
IO::Moose::Handle - Reimplementation of IO::Handle with improvements
use IO::Moose::Handle;
my $fh = IO::Moose::Handle->new; $fh->fdopen( fileno(STDIN) ); print $fh->getline; my $content = $fh->slurp; $fh->close;
my $fh = IO::Moose::Handle->fdopen( \*STDERR, '>' ); $fh->autoflush(1); $fh->say('Some text'); undef $fh; # calls close at DESTROY
This class extends the IO::Handle manpage with following differences:
It is based on the Moose manpage object framework.
The stat
method returns the File::Stat::Moose manpage object.
It uses the Exception::Base manpage for signaling errors. Most of methods are throwing exception on failure.
The modifiers like input_record_separator
are supported on per file handle
basis.
extends the MooseX::GlobRef::Object manpage
extends the Moose::Object manpage
extends the IO::Handle manpage
Thrown whether method is called with wrong argument.
Thrown whether fatal error is occurred by core function.
File (file descriptor number, file handle or IO object) as a parameter for new
object or argument for fdopen
method.
File mode as a parameter for new object or argument for fdopen
method. Can
be Perl-style (<
, >
, >>
, etc.) or C-style (r
,
w
, a
, etc.)
File handle used for internal IO operations.
If is true value the input will be auto chomped.
If is false value and tainted mode is enabled the untaint
method will be
called after fdopen
.
If is false value the non-blocking IO will be turned on.
If is true value the file handle will be copy of file argument. If file argument is not a file handle, the the Exception::Argument manpage is thrown.
By default the object's file handle is tied variable, so it can be used with
standard, non-OO interface (open
, print
, getc
functions and
<>
operator). This interface is slow and can be disabled if the OO
interface only is used.
By default the accessors might be avoided for performance reason. This optimization can be disabled if the attribute is set to true value.
These are attributes assigned with Perl's built-in variables. See perlvar
for complete descriptions. The fields have accessors available as per file
handle basis if called as $io->accessor
or as global setting if called
as IO::Moose::Handle->accessor
.
Creates handle as a copy of standard handle and imports it into caller's namespace. This handles won't be created until explicit import.
use IO::Moose::Handle ':std'; print $STDOUT->autoflush(1); print $STDIN->slurp;
Creates the IO::Moose::Handle
object and calls fdopen
method if the
mode parameter is defined.
$io = IO::Moose::Handle->new( file => \*STDIN, mode => "r" );
The object can be created with unopened file handle which can be opened later.
$in = IO::Moose::Handle->new( file => \*STDIN ); $in->fdopen("r");
If copyfh is true value and file contains a file handle, this file handle is copied rather than new file handle created.
$tmp = File::Temp->new; $io = IO::Moose::Handle->new( file => $tmp, copyfh => 1, mode => "w" );
Creates the IO::Moose::Handle
object and immediately opens the file handle
based on arguments.
$out = IO::Moose::Handle->new_from_fd( \*STDOUT, "w" );
Opens the previously created file handle. If the file was already opened, it
is closed automatically and reopened without resetting its line counter. The
method also sets the file
and mode
attributes.
$out = IO::Moose::Handle->new; $out->fdopen( \*STDOUT, "w" );
$dup = IO::Moose::Handle->new; $dup->fdopen( $dup, "a" );
$stdin = IO::Moose::Handle->new; $stdin->fdopen( 0, "r");
Closes the opened file handle. The file
and mode
attributes are cleared
after closing.
These are front ends for corresponding built-in functions. Most of them throws exception on failure which can be caught with try/catch:
use Exception::Base; eval { open $f, "/etc/hostname"; $io = IO::Moose::Handle->new( file => $f, mode => "r" ); $c = $io->getc; }; if ($@) { my $e = Exception::Base->catch) { warn "problem with /etc/hostname file: $e"; };
The fdopen
, close
, print
, printf
and truncate
methods returns
this object.
The opposite of read. The wrapper for the perl perlfunc/write function is called
format_write
.
The wrapper for perl perlfunc/format function.
The readline
method which is called always in scalar context.
$io = IO::Moose::Handle->new( file=>\*STDIN, mode=>"r" ); push @a, $io->getline; # reads only one line
The readline
method which is called always in array context.
$io = IO::Moose::Handle->new( file => \*STDIN, mode => "r" ); print scalar $io->getlines; # error: can't call in scalar context.
Pushes a character with the given ordinal value back onto the given handle's input stream.
$io = IO::Moose::Handle->new( file => \*STDIN, mode => "r" ); $io->ungetc(ord('A')); print $io->getc; # prints A
The print
method with EOL character at the end.
$io = IO::Moose::Handle->new( file => \*STDOUT, mode => "w" ); $io->say("Hello!");
Creates the IO::Moose::Handle
object and returns its content as a scalar in
scalar context or as an array in array context.
open $f, "/etc/passwd"; $passwd_file = IO::Moose::Handle->slurp($f);
Additional args are passed to IO::Moose::Handle
constructor.
Reads whole file and returns its content as a scalar in scalar context or as
an array in array context (like getlines
method).
open $f, "/etc/passwd";
$io1 = IO::Moose::Handle->new( file => $f, mode => "r" ); $passwd_file = $io1->slurp;
$io2 = IO::Moose::Handle->new( file => $f, mode => "r" ); $io2->autochomp(1); @passwd_lines = $io2->slurp;
Returns File::Stat::Moose
object which represents status of file pointed by
current file handle.
open $f, "/etc/passwd"; $io = IO::Moose::Handle->new( file => $f, mode => "r" ); $st = $io->stat; print $st->size; # size of /etc/passwd file
Returns true value if the file handle has experienced any errors since it was
opened or since the last call to clearerr
, or if the handle is invalid.
It is recommended to use exceptions mechanism to handle errors.
Clear the given handle's error indicator. Returns true value if the file handle is valid or false value otherwise.
Synchronizes a file's in-memory state with that on the physical medium. It operates on file descriptor and it is low-level operation. Returns this object on success or throws an exception.
Flushes any buffered data at the perlio API level. Returns self object on success or throws an exception.
Turns on autoflush, print args and then restores the autoflush status. Returns self object on success or throws an exception.
If called with an argument blocking will turn on non-blocking IO if bool is
false, and turn it off if bool is true. blocking
will return the value
of the previous setting, or the current setting if bool is not given.
Marks the object as taint-clean, and as such data read from it will also be
considered taint-clean. It has meaning only if Perl is running in tainted
mode (-T
).
These are accessors assigned with Perl's built-in variables. See perlvar for complete descriptions.
The debugging mode can be enabled if PERL_DEBUG_IO_MOOSE_HANDLE
environment
variable is set to true value. The debugging mode requires the Smart::Comments manpage
module.
The run-time assertions can be enabled with the Test::Assert manpage module.
This module uses the MooseX::GlobRef::Object manpage and stores the object's attributes
in glob reference. They can be accessed with *$self->{attr}
expression or with standard accessors $self->attr
.
There are two handles used for IO operations: the original handle used for real IO operations and tied handle which hooks IO functions interface.
The OO-style uses original handle stored in fh field.
# Usage: $io->print("OO style");
# Implementation: package IO::Moose::Handle; sub print { my $self = shift; CORE::print { $self->fh } @_ }
The IO functions-style uses object reference which is dereferenced as a handle tied to proxy object which operates on original handle.
# Usage: print $io "IO functions style";
# Implementation: package IO::Moose::Handle; sub PRINT { shift()->print(@_) }; sub print { my $self = shift; CORE::print { $self->fh } @_ }
the IO::Handle manpage, the MooseX::GlobRef::Object manpage, the Moose manpage.
The API is not stable yet and can be changed in future.
Piotr Roszatycki <dexter@cpan.org>
Copyright 2007, 2008, 2009 by Piotr Roszatycki <dexter@cpan.org>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See http://www.perl.com/perl/misc/Artistic.html
IO::Moose::Handle - Reimplementation of IO::Handle with improvements |