File::Read(3) User Contributed Perl Documentation File::Read(3)NAMEFile::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".
FUNCTIONSread_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
<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 <http://annocpan.org/dist/File-
Read>
· CPAN Ratings - http://cpanratings.perl.org/d/File-Read
<http://cpanratings.perl.org/d/File-Read>
· RT: CPAN's request tracker -
http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-Read
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-Read>
· Search CPAN - http://search.cpan.org/dist/File-Read
<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.
perl v5.14.1 2011-07-20 File::Read(3)
