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.

INHERITANCE

• extends IO::Moose::Seekable

  • extends IO::Moose::Handle

    • extends MooseX::GlobRef::Object

      • extends Moose::Object

• extends IO::File

  • extends IO::Seekable

    • extends IO::Handle

EXCEPTIONS

Exception::Argument

Thrown whether method is called with wrong argument.

Exception::Fatal

Thrown whether fatal error is occurred by core function.

ATTRIBUTES

file : Str|FileHandle|OpenHandle {ro}

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

mode : OpenModeWithLayerStr|CanonOpenModeStr = "<" {ro}

File mode as a parameter for new object or open method. Can be Perl-style string (<, >, >>, etc.) with optional PerlIO layer after colon (i.e. <:encoding(UTF-8)) or C-style string (r, w, a, etc.)

sysmode : Num {ro}

File mode as a parameter for new object or sysopen method. Can be decimal number (O_RDONLY, O_RDWR, O_CREAT, other constants from standard module Fcntl).

perms : Num = 0666 {ro}

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

layer : PerlIOLayerStr = "" {ro}

PerlIO layer string.

CONSTRUCTORS

new( args : Hash ) : Self

Creates an object. If file is defined and is a string or array reference, the 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 handler, the fdopen method is called.

  $tmp = IO::Moose::File->new( file => \*STDERR, mode => 'w' );
  $tmp->say("Some important message");

If layer is defined, the binmode method is called.

  $io = IO::Moose::File->new( file => "test.txt", layer => ":utf8" );

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 and IO::Moose::Handle constructors.

  $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"

  $tmp = IO::Moose::File->new_tmpfile( output_record_separator => "\n" );
  $tmp->print("say");  # with eol

METHODS

open( file : Str, mode : OpenModeWithLayerStr|CanonOpenModeStr = "<" ) : Self

Opens the file with "open" in perlfunc function and returns self object.

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

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

sysopen( file : Str, sysmode : Num, perms : Num = 0600 ) : Self

Opens the file with "sysopen" in perlfunc function and returns self object. The sysmode is decimal value (it can be O_XXX constant from standard module Fcntl). The default perms are set to 0666. The mode attribute is set based on sysmode value.

  use Fcntl;
  $io = IO::Moose::File->new;
  $io->open("/etc/hosts", O_RDONLY);
  print $io->mode;   # prints "<"

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@cpan.org>

LICENSE

Copyright 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