NAME

       File::Read - Unique interface for reading one or more files

VERSION

       Version 0.0801

SYNOPSIS

           use File::Read;

           # read a file
           $file = read_file($path);

           # read several files
           @files = read_files(@paths);

           # aggregate several files
           $file = read_files(@paths);

           # read a file as root, skip comments and blank lines
           $file = read_file({ as_root => 1, skip_comments => 1, skip_blanks => 1 }, $path);

DESCRIPTION

       This module mainly proposes functions for reading one or more files, with different
       options. See below for more details and examples.

   Rationale
       This module was created to address a quite specific need: reading many files, some as a
       normal user and others as root, and eventually do a little more processing, all while
       being at the same time compatible with Perl 5.004. "File::Slurp" addresses the first
       point, but not the others, hence the creation of "File::Read". If you don't need reading
       files as root or the post-processing features, then it's faster to directly use
       "File::Slurp".

EXPORT

       By default, this module exports all the functions documented afterhand.  It also
       recognizes import options. For example

           use File::Read 'err_mode=quiet';

       set "read_file()"'s "err_mode" option default value to "quiet".

FUNCTIONS

       read_file()
           Read the files given in argument and return their content, as as list, one element per
           file, when called in list context, or as one big chunk of text when called in scalar
           context.  Options can be set using a hashref as first parameter.

           Options

           •   "aggregate" controls how the function returns the content of the files that were
               successfully read. By default, When set to true (default), the function returns
               the content as a scalar; when set to false, the content is returned as a list.

           •   "as_root" tells the function to read the given file(s) as root using the command
               indicated by the "cmd" option.

           •   "cmd" sets the shell command used for reading files as root. Default is "sudo
               cat". Therefore you need sudo(8) and cat(1) on your system, and sudoers(5) must be
               set so the user can execute cat(1).

           •   "err_mode" controls how the function behaves when an error occurs.  Available
               values are "croak", "carp" and "quiet".  Default value is "croak".

           •   "skip_comments" tells the functions to remove all comment lines from the read
               files.

           •   "skip_blanks" tells the functions to remove all blank lines from the read files.

           •   "to_ascii" tells the functions to convert the text to US-ASCII using
               "Text::Unidecode". If this module is not available, non-ASCII data are deleted.

           Examples

           Just read a file:

               my $file = read_file($path);

           Read a file, returning it as list:

               my @file = read_file({ aggregate => 0 }, $path);

           Read a file, skipping comments:

               my $file = read_file({ skip_comments => 1 }, $path);

           Read several files, skipping blank lines and comments:

               my @files = read_file({ skip_comments => 1, skip_blanks => 1 }, @paths);

       read_files()
           "read_files()" is just an alias for "read_file()" so that it look more sane when
           reading several files.

DIAGNOSTICS

       "Bad value '%s' for option '%s'"
           (E) You gave a bad value for the indicated option. Please check the documentation for
           the valid values.

       "This function needs at least one path"
           (E) You called a function without giving it argument.

SEE ALSO

       File::Slurp

       IO::All

AUTHOR

       Sebastien Aperghis-Tramoni, "<sebastien at aperghis.net>"

BUGS

       Please report any bugs or feature requests to "bug-file-read at rt.cpan.org", or through
       the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Read>.  I will
       be notified, and then you'll automatically be notified of progress on your bug as I make
       changes.

SUPPORT

       You can find documentation for this module with the perldoc command.

           perldoc File::Read

       You can also look for information at:

       •   AnnoCPAN: Annotated CPAN documentation - <http://annocpan.org/dist/File-Read>

       •   CPAN Ratings - <http://cpanratings.perl.org/d/File-Read>

       •   RT: CPAN's request tracker - <http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-Read>

       •   Search CPAN - <http://search.cpan.org/dist/File-Read>

COPYRIGHT & LICENSE

       Copyright (C) 2006, 2007 Sebastien Aperghis-Tramoni, all rights reserved.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.