NAME

File::Open - wrap open/sysopen and give them a nice and simple interface

SYNOPSIS

 use File::Open qw(fopen fopen_nothrow fsysopen fsysopen_nothrow);

 my $fh = fopen $file;
 my $fh = fopen $file, $mode;
 my $fh = fopen $file, $mode, $layers;

 my $fh = fopen_nothrow $file or die "$0: $file: $!\n";
 my $fh = fopen_nothrow $file, $mode or die "$0: $file: $!\n";
 my $fh = fopen_nothrow $file, $mode, $layers or die "$0: $file: $!\n";

 my $fh = fsysopen $file, $mode;
 my $fh = fsysopen $file, $mode, \%flags;

 my $fh = fsysopen_nothrow $file, $mode or die "$0: $file: $!\n";
 my $fh = fsysopen_nothrow $file, $mode, \%flags or die "$0: $file: $!\n";

DESCRIPTION

This module provides convenience wrappers around open and sysopen for opening simple files. Nothing is exported by default; you have to specify every function you want to import explicitly.

Functions

fopen FILE

fopen FILE, MODE

fopen FILE, MODE, LAYERS

Opens FILE and returns a filehandle. If the open fails, it throws an exception of the form "$program: $filename: $!\n".

MODE is a string specifying how the file should be opened. The following values are supported:

'r', '<'

Open the file for reading.

'w', '>'

Open the file for writing. If the file exists, wipe out its contents and make it empty; if it doesn't exist, create it.

'a', '>>'

Open the file for appending. If the file doesn't exist, create it. All writes will go to the end of the file.

'r+', '+<'

Open the file for reading (like 'r') but also allow writes.

'w+', '+>'

Open the file for writing (like 'w') but also allow reads.

'a+', '+>>'

Open the file for appending (like 'a') but also allow reads.

In addition you can append a 'b' to each of the mode strings listed above. This will cause binmode to be called on the filehandle.

If you don't specify a MODE, it defaults to 'r'.

If you pass LAYERS, fopen will combine it with the open mode in the underlying open call. This gives you greater control than the simple 'b' in MODE (which is equivalent to passing :raw as LAYERS). For example, to read from a UTF-8 file:

  my $fh = fopen $file, 'r', ':encoding(UTF-8)';
  # does
  #   open my $fh, '<:encoding(UTF-8)', $file
  # under the covers
 
  while (my $line = readline $fh) {
      ...
  }

See PerlIO and Encode::Supported for a list of available layers and encoding names, respectively.

If you don't pass LAYERS, fopen will use the default layers set via use open ..., if any (see open). Default layers aren't supported on old perls (i.e. anything before 5.10.0); on those you'll have to pass an explicit LAYERS argument.

fopen_nothrow FILE

fopen_nothrow FILE, MODE

fopen_nothrow FILE, MODE, LAYERS

Works exactly like fopen but if the open fails it simply returns undef.

fsysopen FILE, MODE

fsysopen FILE, MODE, FLAGS

Uses the more low-level interface of sysopen to open FILE. If it succeeds, it returns a filehandle; if it fails, it throws an exception of the form "$program: $filename: $!\n".

MODE must be 'r', 'w', or 'rw' to open the file for reading, writing, or both reading and writing, respectively (this corresponds to the open flags O_RDONLY, O_WRONLY, and O_RDWR).

You can pass additional flags in FLAGS, which must be a hash reference. The hash keys are strings (specifying the flag) and the values are booleans (indicating whether the flag should be off (default) or on) - with one exception. The exception is the 'creat' flag; if set, its value must be a number that specifies the permissions of the newly created file. See "umask" in perlfunc for details.

The following flags are recognized:

'append' - sets O_APPEND

'async' - sets O_ASYNC

'creat' - sets O_CREAT and specifies file permissions

'direct' - sets O_DIRECT

'directory' - sets O_DIRECTORY

'excl' - sets O_EXCL

'noatime' - sets O_NOATIME

'noctty' - sets O_NOCTTY

'nofollow' - sets O_NOFOLLOW

'nonblock' - sets O_NONBLOCK

'sync' - sets O_SYNC

'trunc' - sets O_TRUNC

See Fcntl and open(2) for the meaning of these flags. Some of them may not exist on your system; in that case you'll get a runtime exception when you try to specify a non-existent flag.

fsysopen_nothrow FILE, MODE

fsysopen_nothrow FILE, MODE, FLAGS

Works exactly like fsysopen but if the sysopen fails it simply returns undef.

Methods

The returned filehandles behave like IO::Handle objects (actually IO::File objects, which is a subclass of IO::Handle). However, on perl versions before 5.14.0 you have to use IO::Handle; manually before you can call any methods on them. (Current perl versions will do this for you automatically but it doesn't hurt to load IO::Handle anyway.)

Here is a toy example that copies all lines from one file to another, using method calls instead of functions:

  use File::Open qw(fopen);
  use IO::Handle;  # not needed on 5.14+
 
  my $fh_in  = fopen $file_in,  'r';
  my $fh_out = fopen $file_out, 'w';
 
  while (defined(my $line = $fh_in->getline)) {
      $fh_out->print($line) or die "$0: $file_out: $!\n";
  }
 
  $fh_out->close or die "$0: $file_out: $!\n";
  $fh_in->close;

SEE ALSO

"open" in perlfunc, "binmode" in perlfunc, "sysopen" in perlfunc, perlopentut, IO::Handle, Fcntl, open(2)

AUTHOR

Lukas Mai, <l.mai at web.de>

COPYRIGHT & LICENSE

Copyright 2011, 2013 Lukas Mai.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.