1File::Read(3)         User Contributed Perl Documentation        File::Read(3)
2
3
4

NAME

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

VERSION

9       Version 0.0801
10

SYNOPSIS

12           use File::Read;
13
14           # read a file
15           $file = read_file($path);
16
17           # read several files
18           @files = read_files(@paths);
19
20           # aggregate several files
21           $file = read_files(@paths);
22
23           # read a file as root, skip comments and blank lines
24           $file = read_file({ as_root => 1, skip_comments => 1, skip_blanks => 1 }, $path);
25

DESCRIPTION

27       This module mainly proposes functions for reading one or more files,
28       with different options. See below for more details and examples.
29
30   Rationale
31       This module was created to address a quite specific need: reading many
32       files, some as a normal user and others as root, and eventually do a
33       little more processing, all while being at the same time compatible
34       with Perl 5.004. "File::Slurp" addresses the first point, but not the
35       others, hence the creation of "File::Read". If you don't need reading
36       files as root or the post-processing features, then it's faster to
37       directly use "File::Slurp".
38

EXPORT

40       By default, this module exports all the functions documented afterhand.
41       It also recognizes import options. For example
42
43           use File::Read 'err_mode=quiet';
44
45       set "read_file()"'s "err_mode" option default value to "quiet".
46

FUNCTIONS

48       read_file()
49           Read the files given in argument and return their content, as as
50           list, one element per file, when called in list context, or as one
51           big chunk of text when called in scalar context.  Options can be
52           set using a hashref as first parameter.
53
54           Options
55
56           ·   "aggregate" controls how the function returns the content of
57               the files that were successfully read. By default, When set to
58               true (default), the function returns the content as a scalar;
59               when set to false, the content is returned as a list.
60
61           ·   "as_root" tells the function to read the given file(s) as root
62               using the command indicated by the "cmd" option.
63
64           ·   "cmd" sets the shell command used for reading files as root.
65               Default is "sudo cat". Therefore you need sudo(8) and cat(1) on
66               your system, and sudoers(5) must be set so the user can execute
67               cat(1).
68
69           ·   "err_mode" controls how the function behaves when an error
70               occurs.  Available values are "croak", "carp" and "quiet".
71               Default value is "croak".
72
73           ·   "skip_comments" tells the functions to remove all comment lines
74               from the read files.
75
76           ·   "skip_blanks" tells the functions to remove all blank lines
77               from the read files.
78
79           ·   "to_ascii" tells the functions to convert the text to US-ASCII
80               using "Text::Unidecode". If this module is not available, non-
81               ASCII data are deleted.
82
83           Examples
84
85           Just read a file:
86
87               my $file = read_file($path);
88
89           Read a file, returning it as list:
90
91               my @file = read_file({ aggregate => 0 }, $path);
92
93           Read a file, skipping comments:
94
95               my $file = read_file({ skip_comments => 1 }, $path);
96
97           Read several files, skipping blank lines and comments:
98
99               my @files = read_file({ skip_comments => 1, skip_blanks => 1 }, @paths);
100
101       read_files()
102           "read_files()" is just an alias for "read_file()" so that it look
103           more sane when reading several files.
104

DIAGNOSTICS

106       "Bad value '%s' for option '%s'"
107           (E) You gave a bad value for the indicated option. Please check the
108           documentation for the valid values.
109
110       "This function needs at least one path"
111           (E) You called a function without giving it argument.
112

SEE ALSO

114       File::Slurp
115
116       IO::All
117

AUTHOR

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

BUGS

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

SUPPORT

130       You can find documentation for this module with the perldoc command.
131
132           perldoc File::Read
133
134       You can also look for information at:
135
136       ·   AnnoCPAN: Annotated CPAN documentation -
137           http://annocpan.org/dist/File-Read <http://annocpan.org/dist/File-
138           Read>
139
140       ·   CPAN Ratings - http://cpanratings.perl.org/d/File-Read
141           <http://cpanratings.perl.org/d/File-Read>
142
143       ·   RT: CPAN's request tracker -
144           http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-Read
145           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-Read>
146
147       ·   Search CPAN - http://search.cpan.org/dist/File-Read
148           <http://search.cpan.org/dist/File-Read>
149

151       Copyright (C) 2006, 2007 Sebastien Aperghis-Tramoni, all rights
152       reserved.
153
154       This program is free software; you can redistribute it and/or modify it
155       under the same terms as Perl itself.
156
157
158
159perl v5.12.0                      2010-05-01                     File::Read(3)
Impressum