NAME

IO::Simple - Adds error checking to file handles and provides per file handle options.

SYNOPSIS

You can export the file method as below

  use IO::Simple ':all';
  
  my $fh = file('test.txt', 'w');          #dies if file can't be opened
  $fh->say("This is a line");             #say appends new line
  $fh->print("This has no new line!!!");  #regular print behavior
  $fh->close();                           #dies on failure

  my $contents = file('test.txt')->slurp();

Or you can use the new class method

  use IO::Simple;
  my $fh = new IO::Simple('test.txt');

DESCRIPTION

IO::Simple provides a thin layer over IO::File. This layer causes files to default to opening in read mode and to croaking on failure opening, closeing or printing to files. It provides methods to set $\, $/, $:, $^L and $, on a per handle basis and a slurp function.

REASONING

You can get similar results using a combination of IO::All, Fatal and File::Slurp. I found that fatal didn't provide as descriptive as errors as I wanted, and IO::All was overly bloated so this module was born to fill in those gaps.

METHODS

new IO::Simple ( [FILENAME [,MODE, [OPTIONS]]])

Passes any arguments to $self->open for processing, otherwise simply returns a new object.

$fh->open ( FILENAME [,MODE, [OPTIONS]])

file accepts up to three parameters. If only FILENAME is supplied then the default mode is 'read' The mode can be one of 'r',' 'read', 'w', 'write', 'a', 'append' which translate to '<', '>', and '>>'. The third parameter is a hash of options. It also adds some magic so that the '-' file name will cause STDIN or STDOUT to be opened depending on the mode.

    Option                       Sets
        line_break_characters        $:
    format_formfeed              $^L
    output_field_separator       $,
    output_record_separator      $\
    input_record_separator       $/
        autochomp                    auto chomp on readline or slurp

reopen ( [MODE] )

Reopen a previously opened file with the same mode or a new mode.

        my $fh = file('test');  #open it for reading;
        $fh->close;
        $fh->reopen('a');  #reopen the file for writing.

file ( FILENAME [,MODE, [OPTIONS]])

file accepts up to three parameters. If only one is supplied then the default mode is 'read' The mode can be one of 'r',' 'read', 'w', 'write', 'a', 'append' which translate to '<', '>', and '>>'. The third parameter is a hash of options. By default autochomp is on, but you can use this to disable it if you prefer. which would cause the slurp method to chomp each line in array context. irs shoft for "Input Record Seperator" lets you set a default value for $\ that will be used for readline and slurp operations.

   my $read  = file('test');
   my $write = file('test', 'w');

   my $not_chomped = file('test', 'r', autochomp => 0)
   my @lines       = $not_chomped->slurp();
   
   my $pipedel = file('test', 'r', irs => '|')
   my @fields  = $pipedel->slurp();

$fh->close

Wrapper for IO::Handle close with added error handling.

PerlVar per Handle Methods

Stores your choice and later localizes the perlvar and sets it appropriately during output operations. Returns current value if no STR is provided.

        $fh->format_line_break_characters( [STR] ) $:
        $fh->format_formfeed( [STR])               $^L
        $fh->output_field_separator( [STR] )       $,
        $fh->output_record_separator( [STR] )      $\

Stores your choice and later localizes the perlvar and sets it appropriately during input operations. Returns current value if no STR is provided.

        $fh->input_record_separator( [STR] )       $/

$fh->print

Wrapper for IO::Handle print with added error handling and localizes $:, $^L, $,, $\ and sets them properly for each file handle.

IO::Simple::slurp(FILE [,SEP])

Takes a file name an slurps up the file. In list context it uses the SEP and outputs an array of lines in scalar context it ignores the SEP and returns the entire file in a scalar.

   use IO::Simple qw/slurp/;
   my $content = slurp('test');

$fh->slurp([SEP])

slurp returns the remaining contents of the file handle. If used in list context it returns the lines of the file in an array (setting $/ = SEP), otherwise it returns the entire file slurped into a scalar. Unless disablled with autochomp, lines returned in list context will be chomped.

   my $content = file('test')->slurp();

EXPORT

Optionaly exports two functions file and slurp or use :all to import both. No methods are exported by default.

CAVEAT

The error checking only works when you use the object methods. This allows you to use the builtins when wish to handle your own error checking.

   my $fh = file('test.txt');
   $fh->print("Hello Wolrd");    #results in error
   print $fh "Hello World";      #doesn't through error.
   
   my $fh = new IO::Simple;
   $fh->open('test');            #throws error if test doesn't exist
   open($fh, '<', 'test');       #allows you to handle errors on your own.

If you don't use the open method the errors will not know which file you opened or what mode you opened it in.

SEE ALSO

IO::All, IO::File, Perl6::Slurp, File::Slurp, Fatal

AUTHOR

Eric Hodges <eric256@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2007 by Eric Hodges

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.