1File::Slurp(3) User Contributed Perl Documentation File::Slurp(3)
2
6 File::Slurp - Efficient Reading/Writing of Complete Files
7
9 use File::Slurp;
10 my $text = read_file( 'filename' ) ;
12 my @lines = read_file( 'filename' ) ;
13 write_file( 'filename', @lines ) ;
15 use File::Slurp qw( slurp ) ;
17 my $text = slurp( 'filename' ) ;
19
21 This module provides subs that allow you to read or write entire files
22 with one simple call. They are designed to be simple to use, have flex‐
23 ible ways to pass in or get the file contents and to be very efficient.
24 There is also a sub to read in all the files in a directory other than
25 "." and ".."
26 These slurp/spew subs work for files, pipes and sockets, and stdio,
28 pseudo-files, and DATA.
29 read_file
31 This sub reads in an entire file and returns its contents to the call‐
33 er. In list context it will return a list of lines (using the current
34 value of $/ as the separator including support for paragraph mode when
35 it is set to ''). In scalar context it returns the entire file as a
36 single scalar.
37 my $text = read_file( 'filename' ) ;
39 my @lines = read_file( 'filename' ) ;
40 The first argument to "read_file" is the filename and the rest of the
42 arguments are key/value pairs which are optional and which modify the
43 behavior of the call. Other than binmode the options all control how
44 the slurped file is returned to the caller.
45 If the first argument is a file handle reference or I/O object (if ref
47 is true), then that handle is slurped in. This mode is supported so you
48 slurp handles such as "DATA", "STDIN". See the test handle.t for an
49 example that does "open( '-⎪' )" and child process spews data to the
50 parant which slurps it in. All of the options that control how the
51 data is returned to the caller still work in this case.
52 NOTE: as of version 9999.06, read_file works correctly on the "DATA"
54 handle. It used to need a sysseek workaround but that is now handled
55 when needed by the module itself.
56 You can optionally request that "slurp()" is exported to your code.
58 This is an alias for read_file and is meant to be forward compatible
59 with Perl 6 (which will have slurp() built-in).
60 The options are:
62 binmode
64 If you set the binmode option, then the file will be slurped in binary
66 mode.
67 my $bin_data = read_file( $bin_file, binmode => ':raw' ) ;
69 NOTE: this actually sets the O_BINARY mode flag for sysopen. It proba‐
71 bly should call binmode and pass its argument to support other file
72 modes.
73 array_ref
75 If this boolean option is set, the return value (only in scalar con‐
77 text) will be an array reference which contains the lines of the
78 slurped file. The following two calls are equivalent:
79 my $lines_ref = read_file( $bin_file, array_ref => 1 ) ;
81 my $lines_ref = [ read_file( $bin_file ) ] ;
82 scalar_ref
84 If this boolean option is set, the return value (only in scalar con‐
86 text) will be an scalar reference to a string which is the contents of
87 the slurped file. This will usually be faster than returning the plain
88 scalar.
89 my $text_ref = read_file( $bin_file, scalar_ref => 1 ) ;
91 buf_ref
93 You can use this option to pass in a scalar reference and the slurped
95 file contents will be stored in the scalar. This can be used in con‐
96 junction with any of the other options.
97 my $text_ref = read_file( $bin_file, buf_ref => \$buffer,
99 array_ref => 1 ) ;
100 my @lines = read_file( $bin_file, buf_ref => \$buffer ) ;
101 blk_size
103 You can use this option to set the block size used when slurping from
105 an already open handle (like \*STDIN). It defaults to 1MB.
106 my $text_ref = read_file( $bin_file, blk_size => 10_000_000,
108 array_ref => 1 ) ;
109 err_mode
111 You can use this option to control how read_file behaves when an error
113 occurs. This option defaults to 'croak'. You can set it to 'carp' or to
114 'quiet to have no error handling. This code wants to carp and then read
115 abother file if it fails.
116 my $text_ref = read_file( $file, err_mode => 'carp' ) ;
118 unless ( $text_ref ) {
119 # read a different file but croak if not found
121 $text_ref = read_file( $another_file ) ;
122 }
123 # process ${$text_ref}
125 write_file
127 This sub writes out an entire file in one call.
129 write_file( 'filename', @data ) ;
131 The first argument to "write_file" is the filename. The next argument
133 is an optional hash reference and it contains key/values that can mod‐
134 ify the behavior of "write_file". The rest of the argument list is the
135 data to be written to the file.
136 write_file( 'filename', {append => 1 }, @data ) ;
138 write_file( 'filename', {binmode => ':raw' }, $buffer ) ;
139 As a shortcut if the first data argument is a scalar or array refer‐
141 ence, it is used as the only data to be written to the file. Any fol‐
142 lowing arguments in @_ are ignored. This is a faster way to pass in the
143 output to be written to the file and is equivilent to the "buf_ref"
144 option. These following pairs are equivilent but the pass by reference
145 call will be faster in most cases (especially with larger files).
146 write_file( 'filename', \$buffer ) ;
148 write_file( 'filename', $buffer ) ;
149 write_file( 'filename', \@lines ) ;
151 write_file( 'filename', @lines ) ;
152 If the first argument is a file handle reference or I/O object (if ref
154 is true), then that handle is slurped in. This mode is supported so you
155 spew to handles such as \*STDOUT. See the test handle.t for an example
156 that does "open( '-⎪' )" and child process spews data to the parant
157 which slurps it in. All of the options that control how the data is
158 passes into "write_file" still work in this case.
159 "write_file" returns 1 upon successfully writing the file or undef if
161 it encountered an error.
162 The options are:
164 binmode
166 If you set the binmode option, then the file will be written in binary
168 mode.
169 write_file( $bin_file, {binmode => ':raw'}, @data ) ;
171 NOTE: this actually sets the O_BINARY mode flag for sysopen. It proba‐
173 bly should call binmode and pass its argument to support other file
174 modes.
175 buf_ref
177 You can use this option to pass in a scalar reference which has the
179 data to be written. If this is set then any data arguments (including
180 the scalar reference shortcut) in @_ will be ignored. These are equivi‐
181 lent:
182 write_file( $bin_file, { buf_ref => \$buffer } ) ;
184 write_file( $bin_file, \$buffer ) ;
185 write_file( $bin_file, $buffer ) ;
186 atomic
188 If you set this boolean option, the file will be written to in an
190 atomic fashion. A temporary file name is created by appending the pid
191 ($$) to the file name argument and that file is spewed to. After the
192 file is closed it is renamed to the original file name (and rename is
193 an atomic operation on most OS's). If the program using this were to
194 crash in the middle of this, then the file with the pid suffix could be
195 left behind.
196 append
198 If you set this boolean option, the data will be written at the end of
200 the current file.
201 write_file( $file, {append => 1}, @data ) ;
203 "write_file" croaks if it cannot open the file. It returns true if it
205 succeeded in writing out the file and undef if there was an error.
206 (Yes, I know if it croaks it can't return anything but that is for when
207 I add the options to select the error handling mode).
208 no_clobber
210 If you set this boolean option, an existing file will not be overwrit‐
212 ten.
213 write_file( $file, {no_clobber => 1}, @data ) ;
215 err_mode
217 You can use this option to control how "write_file" behaves when an
219 error occurs. This option defaults to 'croak'. You can set it to 'carp'
220 or to 'quiet' to have no error handling other than the return value. If
221 the first call to "write_file" fails it will carp and then write to
222 another file. If the second call to "write_file" fails, it will croak.
223 unless ( write_file( $file, { err_mode => 'carp', \$data ) ;
225 # write a different file but croak if not found
227 write_file( $other_file, \$data ) ;
228 }
229 overwrite_file
231 This sub is just a typeglob alias to write_file since write_file always
233 overwrites an existing file. This sub is supported for backwards com‐
234 patibility with the original version of this module. See write_file for
235 its API and behavior.
236 append_file
238 This sub will write its data to the end of the file. It is a wrapper
240 around write_file and it has the same API so see that for the full doc‐
241 umentation. These calls are equivilent:
242 append_file( $file, @data ) ;
244 write_file( $file, {append => 1}, @data ) ;
245 read_dir
247 This sub reads all the file names from directory and returns them to
249 the caller but "." and ".." are removed by default.
250 my @files = read_dir( '/path/to/dir' ) ;
252 It croaks if it cannot open the directory.
254 In a list context "read_dir" returns a list of the entries in the
256 directory. In a scalar context it returns an array reference which has
257 the entries.
258 keep_dot_dot
260 If this boolean option is set, "." and ".." are not removed from the
262 list of files.
263 my @all_files = read_dir( '/path/to/dir', keep_dot_dot => 1 ) ;
265 EXPORT
267 read_file write_file overwrite_file append_file read_dir
269 SEE ALSO
271 An article on file slurping in extras/slurp_article.pod. There is also
273 a benchmarking script in extras/slurp_bench.pl.
274 BUGS
276 If run under Perl 5.004, slurping from the DATA handle will fail as
278 that requires B.pm which didn't get into core until 5.005.
279
281 Uri Guttman, <uri@stemsystems.com>
282perl v5.8.8 2006-02-17 File::Slurp(3)