IO::Moose::File(3)

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>