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

- NAME
- SYNOPSIS
- DESCRIPTION
- INHERITANCE
- EXCEPTIONS
- ATTRIBUTES
- CONSTRUCTORS
- METHODS
- SEE ALSO
- BUGS
- AUTHOR
- LICENSE

# 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:

- It is based on the Moose manpage object framework.

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

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

Back to Top

# INHERITANCE

- extends the IO::Moose::Seekable manpage

  - extends the IO::Moose::Handle manpage

    - extends the MooseX::GlobRef::Object manpage

      - extends the Moose::Object manpage

- extends the IO::File manpage

  - extends the IO::Seekable manpage

    - extends the IO::Handle manpage

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