/ 
IO-Moose-0.0601
River stage zero No dependents
/ IO::Moose::File

NAME

IO::Moose::File - Reimplementation of IO::File with improvements

SYNOPSIS

use IO::Moose::File;
my $file = IO::Moose::File->new( file => "/etc/passwd" );
my @passwd = $file->getlines;

DESCRIPTION

This class provides an interface mostly compatible with IO::File. The differences:

  • It is based on Moose object framework.

  • It uses Exception::Base for signaling errors. Most of methods are throwing exception on failure.

  • It doesn't export any constants. Use Fcntl instead.

  • It is pure-Perl implementation.

BASE CLASSES

ROLE CLASSES

ATTRIBUTES

file : Str|FileHandle|OpenHandle {rw, new}

File (file name, file handle or IO object) as a parameter for new object.

mode : Num|OpenModeWithLayerStr|CanonOpenModeStr = "<" {rw, new}

File mode as a parameter for new object. Can be Perl-style (<, >, >>, etc.) with optional PerlIO layer after colon (i.e. "<:encoding(UTF-8)") or C-style (r, w, a, etc.) or decimal number (O_RDONLY, O_RDWR, O_CREAT, other constants from standard module Fcntl).

perms : Num = 0666 {rw, new}

Permissions to use in case a new file is created and mode was decimal number. The permissions are always modified by umask.

layer : PerlIOLayerStr = "" {rw, new}

PerlIO layer string.

CONSTRUCTORS

new( args : Hash ) : Self

Creates an object. If file is defined, the c<open> method is called; if the open fails, the object is destroyed. Otherwise, it is returned to the caller.

$io = IO::Moose::File->new;
$io->open("/etc/passwd");

$io = IO::Moose::File->new( file => "/var/log/perl.log", mode => "a" );

If file is a File::Temp object, this object is used as fh attribute and mode attribute is changed to +> value.

$tmp = IO::Moose::File->new( file => File::Temp->new );
$tmp->say("This file will be deleted after destroy");
new_tmpfile( args : Hash ) : Self

Creates the object with opened temporary and anonymous file for read/write. If the temporary file cannot be created or opened, the object is destroyed. Otherwise, it is returned to the caller.

All args will be passed to the File::Temp constructor.

$io = IO::Moose::File->new_tmpfile( UNLINK => 1, SUFFIX => '.jpg' );
$pos = $io->getpos;  # save position
$io->say("foo");
$io->setpos($pos);   # rewind
$io->slurp;          # prints "foo"

METHODS

open( file : Str|FileHandle|OpenHandle , mode : OpenModeWithLayerStr|CanonOpenModeStr = "<" ) : Self
open( file : Str|FileHandle|OpenHandle , mode : Num, perms : Num = 0600 ) : Self

Opens the file and returns self object. If mode is Perl-style mode string or C-style mode string, it uses "open" in perlfunc function. If mode is decimal (it can be O_XXX constant from standard module Fcntl) it uses "sysopen" in perlfunc function with default permissions set to 0666.

$io = IO::Moose::File->new;
$io->open("/etc/passwd");

$io = IO::Moose::File->new;
$io->open("/var/tmp/output", "w");

use Fcntl;
$io = IO::Moose::File->new;
$io->open("/etc/hosts", O_RDONLY);
binmode() : Self
binmode( layer : PerlIOLayerStr ) : Self

Sets binmode on the underlying IO object. On some systems (in general, DOS and Windows-based systems) binmode is necessary when you're not working with a text file.

It can also sets PerlIO layer (:bytes, :crlf, :utf8, :encoding(XXX), etc.). More details can be found in PerlIO::encoding.

In general, binmode should be called after open but before any I/O is done on the file handler.

Returns self object.

$io = IO::Moose::File->new( file => "/tmp/picture.png", mode => "w" );
$io->binmode;

$io = IO::Moose::File->new( file => "/var/tmp/fromdos.txt" );
$io->binmode(":crlf");

SEE ALSO

IO::File, IO::Moose, IO::Moose::Handle, IO::Moose::Seekable, File::Temp.

BUGS

The API is not stable yet and can be changed in future.

AUTHOR

Piotr Roszatycki <dexter@debian.org>

LICENSE

Copyright 2008, 2009 by Piotr Roszatycki <dexter@debian.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