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


NAME

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

Back to Top


SYNOPSIS

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

Back to Top


DESCRIPTION

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

Back to Top


INHERITANCE

Back to Top


EXCEPTIONS

the Exception::Argument manpage

Thrown whether method is called with wrong argument.

the Exception::Fatal manpage

Thrown whether fatal error is occurred by core function.

Back to Top


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.

Back to Top


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 the File::Temp manpage and the IO::Moose::Handle manpage 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

Back to Top


METHODS

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

Opens the file with perlfunc/open 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 perlfunc/sysopen 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 the PerlIO::encoding manpage.

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");

Back to Top


SEE ALSO

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

Back to Top


BUGS

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

Back to Top


AUTHOR

Piotr Roszatycki <dexter@cpan.org>

Back to Top


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

Back to Top

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