6 use Fcntl qw( :DEFAULT :seek ) ;
10 use vars qw( %EXPORT_TAGS @EXPORT_OK $VERSION @EXPORT) ;
12 %EXPORT_TAGS = ( 'all' => [
13 qw( read_file write_file overwrite_file append_file read_dir ) ] ) ;
15 #@EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
16 @EXPORT = ( @{ $EXPORT_TAGS{'all'} } );
23 my( $file_name, %args ) = @_ ;
26 my $buf_ref = $args{'buf_ref'} || \$buf ;
30 my( $read_fh, $size_left, $blk_size ) ;
32 if ( defined( fileno( $file_name ) ) ) {
34 $read_fh = $file_name ;
35 $blk_size = $args{'blk_size'} || 1024 * 1024 ;
36 $size_left = $blk_size ;
41 $mode |= O_BINARY if $args{'binmode'} ;
45 unless ( sysopen( $read_fh, $file_name, $mode ) ) {
46 @_ = ( \%args, "read_file '$file_name' - sysopen: $!");
50 $size_left = -s $read_fh ;
55 my $read_cnt = sysread( $read_fh, ${$buf_ref},
56 $size_left, length ${$buf_ref} ) ;
58 if ( defined $read_cnt ) {
60 last if $read_cnt == 0 ;
63 $size_left -= $read_cnt ;
64 last if $size_left <= 0 ;
68 # handle the read error
70 @_ = ( \%args, "read_file '$file_name' - sysread: $!");
76 return [ split( m|(?<=$/)|, ${$buf_ref} ) ] if $args{'array_ref'} ;
80 return split( m|(?<=$/)|, ${$buf_ref} ) if wantarray ;
84 return $buf_ref if $args{'scalar_ref'} ;
86 # handle scalar context
88 return ${$buf_ref} if defined wantarray ;
90 # handle void context (return scalar by buffer reference)
97 my $file_name = shift ;
99 my $args = ( ref $_[0] eq 'HASH' ) ? shift : {} ;
101 my( $buf_ref, $write_fh, $no_truncate ) ;
103 # get the buffer ref - either passed by name or first data arg or autovivified
104 # ${$buf_ref} will have the data after this
106 if ( ref $args->{'buf_ref'} eq 'SCALAR' ) {
108 $buf_ref = $args->{'buf_ref'} ;
110 elsif ( ref $_[0] eq 'SCALAR' ) {
114 elsif ( ref $_[0] eq 'ARRAY' ) {
116 ${$buf_ref} = join '', @{$_[0]} ;
120 ${$buf_ref} = join '', @_ ;
123 if ( defined( fileno( $file_name ) ) ) {
125 $write_fh = $file_name ;
130 my $mode = O_WRONLY | O_CREAT ;
131 $mode |= O_BINARY if $args->{'binmode'} ;
132 $mode |= O_APPEND if $args->{'append'} ;
135 unless ( sysopen( $write_fh, $file_name, $mode ) ) {
136 @_ = ( $args, "write_file '$file_name' - sysopen: $!");
142 my $size_left = length( ${$buf_ref} ) ;
146 my $write_cnt = syswrite( $write_fh, ${$buf_ref},
147 $size_left, $offset ) ;
149 unless ( defined $write_cnt ) {
151 @_ = ( $args, "write_file '$file_name' - syswrite: $!");
155 $size_left -= $write_cnt ;
156 $offset += $write_cnt ;
158 } while( $size_left > 0 ) ;
161 sysseek( $write_fh, 0, SEEK_CUR ) ) unless $no_truncate ;
168 # this is for backwards compatibility with the previous File::Slurp module.
169 # write_file always overwrites an existing file
171 *overwrite_file = \&write_file ;
173 # the current write_file has an append mode so we use that. this
174 # supports the same API with an optional second argument which is a
175 # hash ref of options.
180 if ( ref $args eq 'HASH' ) {
181 $args->{append} = 1 ;
185 splice( @_, 1, 0, { append => 1 } ) ;
192 my ($dir, %args ) = @_;
196 if ( opendir( DIRH, $dir ) ) {
197 return grep( $_ ne "." && $_ ne "..", readdir(DIRH));
200 @_ = ( \%args, "read_dir '$dir' - opendir: $!" ) ; goto &error ;
212 my( $args, $err_msg ) = @_ ;
216 my $func = $err_func{ $args->{'err_mode'} || 'croak' } ;
218 return unless $func ;
230 File::Slurp - Efficient Reading/Writing of Complete Files
236 my $text = read_file( 'filename' ) ;
237 my @lines = read_file( 'filename' ) ;
239 write_file( 'filename', @lines ) ;
243 This module provides subs that allow you to read or write entire files
244 with one simple call. They are designed to be simple to use, have
245 flexible ways to pass in or get the file contents and to be very
246 efficient. There is also a sub to read in all the files in a
247 directory other than C<.> and C<..>
249 Note that these slurp/spew subs work only for files and not for pipes
250 or stdio. If you want to slurp the latter, use the standard techniques
251 such as setting $/ to undef, reading <> in a list context, or printing
252 all you want to STDOUT.
256 This sub reads in an entire file and returns its contents to the
257 caller. In list context it will return a list of lines (using the
258 current value of $/ as the separator. In scalar context it returns the
259 entire file as a single scalar.
261 my $text = read_file( 'filename' ) ;
262 my @lines = read_file( 'filename' ) ;
264 The first argument to C<read_file> is the filename and the rest of the
265 arguments are key/value pairs which are optional and which modify the
266 behavior of the call. Other than binmode the options all control how
267 the slurped file is returned to the caller.
269 If the first argument is a file handle reference or I/O object (if
270 fileno returns a defined value), then that handle is slurped in. This
271 mode is supported so you slurp handles such as <DATA>, \*STDIN. See
272 the test handle.t for an example that does C<open( '-|' )> and child
273 process spews data to the parant which slurps it in. All of the
274 options that control how the data is returned to the caller still work
281 If you set the binmode option, then the file will be slurped in binary
284 my $bin_data = read_file( $bin_file, binmode => ':raw' ) ;
286 NOTE: this actually sets the O_BINARY mode flag for sysopen. It
287 probably should call binmode and pass its argument to support other
292 If this boolean option is set, the return value (only in scalar
293 context) will be an array reference which contains the lines of the
294 slurped file. The following two calls are equivilent:
296 my $lines_ref = read_file( $bin_file, array_ref => 1 ) ;
297 my $lines_ref = [ read_file( $bin_file ) ] ;
301 If this boolean option is set, the return value (only in scalar
302 context) will be an scalar reference to a string which is the contents
303 of the slurped file. This will usually be faster than returning the
306 my $text_ref = read_file( $bin_file, scalar_ref => 1 ) ;
310 You can use this option to pass in a scalar reference and the slurped
311 file contents will be stored in the scalar. This can be used in
312 conjunction with any of the other options.
314 my $text_ref = read_file( $bin_file, buf_ref => \$buffer,
316 my @lines = read_file( $bin_file, buf_ref => \$buffer ) ;
320 You can use this option to set the block size used when slurping from an already open handle (like \*STDIN). It defaults to 1MB.
322 my $text_ref = read_file( $bin_file, blk_size => 10_000_000,
327 You can use this option to control how read_file behaves when an error
328 occurs. This option defaults to 'croak'. You can set it to 'carp' or
329 to 'quiet to have no error handling. This code wants to carp and then
330 read abother file if it fails.
332 my $text_ref = read_file( $file, err_mode => 'carp' ) ;
333 unless ( $text_ref ) {
335 # read a different file but croak if not found
336 $text_ref = read_file( $another_file ) ;
339 # process ${$text_ref}
343 This sub writes out an entire file in one call.
345 write_file( 'filename', @data ) ;
347 The first argument to C<write_file> is the filename. The next argument
348 is an optional hash reference and it contains key/values that can
349 modify the behavior of C<write_file>. The rest of the argument list is
350 the data to be written to the file.
352 write_file( 'filename', {append => 1 }, @data ) ;
353 write_file( 'filename', {binmode => ':raw' }, $buffer ) ;
355 As a shortcut if the first data argument is a scalar or array
356 reference, it is used as the only data to be written to the file. Any
357 following arguments in @_ are ignored. This is a faster way to pass in
358 the output to be written to the file and is equivilent to the
359 C<buf_ref> option. These following pairs are equivilent but the pass
360 by reference call will be faster in most cases (especially with larger
363 write_file( 'filename', \$buffer ) ;
364 write_file( 'filename', $buffer ) ;
366 write_file( 'filename', \@lines ) ;
367 write_file( 'filename', @lines ) ;
369 If the first argument is a file handle reference or I/O object (if
370 fileno returns a defined value), then that handle is slurped in. This
371 mode is supported so you spew to handles such as \*STDOUT. See the
372 test handle.t for an example that does C<open( '-|' )> and child
373 process spews data to the parant which slurps it in. All of the
374 options that control how the data is passes into C<write_file> still
381 If you set the binmode option, then the file will be written in binary
384 write_file( $bin_file, {binmode => ':raw'}, @data ) ;
386 NOTE: this actually sets the O_BINARY mode flag for sysopen. It
387 probably should call binmode and pass its argument to support other
392 You can use this option to pass in a scalar reference which has the
393 data to be written. If this is set then any data arguments (including
394 the scalar reference shortcut) in @_ will be ignored. These are
397 write_file( $bin_file, { buf_ref => \$buffer } ) ;
398 write_file( $bin_file, \$buffer ) ;
399 write_file( $bin_file, $buffer ) ;
403 If you set this boolean option, the data will be written at the end of
406 write_file( $file, {append => 1}, @data ) ;
408 C<write_file> croaks if it cannot open the file. It returns true if it
409 succeeded in writing out the file and undef if there was an
410 error. (Yes, I know if it croaks it can't return anything but that is
411 for when I add the options to select the error handling mode).
415 You can use this option to control how C<write_file> behaves when an
416 error occurs. This option defaults to 'croak'. You can set it to
417 'carp' or to 'quiet to have no error handling. If the first call to
418 C<write_file> fails it will carp and then write to another file. If the
419 second call to C<write_file> fails, it will croak.
421 unless ( write_file( $file, { err_mode => 'carp', \$data ) ;
423 # write a different file but croak if not found
424 write_file( $other_file, \$data ) ;
427 =head2 overwrite_file
429 This sub is just a typeglob alias to write_file since write_file
430 always overwrites an existing file. This sub is supported for
431 backwards compatibility with the original version of this module. See
432 write_file for its API and behavior.
436 This sub will write its data to the end of the file. It is a wrapper
437 around write_file and it has the same API so see that for the full
438 documentation. These calls are equivilent:
440 append_file( $file, @data ) ;
441 write_file( $file, {append => 1}, @data ) ;
445 This sub reads all the file names from directory and returns them to
446 the caller but C<.> and C<..> are removed.
448 my @files = read_dir( '/path/to/dir' ) ;
450 It croaks if it cannot open the directory.
454 read_file write_file overwrite_file append_file read_dir
458 Uri Guttman, E<lt>uri@stemsystems.comE<gt>