9 use Fcntl qw( :DEFAULT ) ;
10 use POSIX qw( :fcntl_h ) ;
14 use vars qw( @ISA %EXPORT_TAGS @EXPORT_OK $VERSION @EXPORT ) ;
15 @ISA = qw( Exporter ) ;
17 %EXPORT_TAGS = ( 'all' => [
18 qw( read_file write_file overwrite_file append_file read_dir ) ] ) ;
20 @EXPORT = ( @{ $EXPORT_TAGS{'all'} } );
21 @EXPORT_OK = qw( slurp prepend_file ) ;
25 my $max_fast_slurp_size = 1024 * 100 ;
27 my $is_win32 = $^O =~ /win32/i ;
29 # Install subs for various constants that aren't set in older perls
30 # (< 5.005). Fcntl on old perls uses Exporter to define subs without a
31 # () prototype These can't be overridden with the constant pragma or
32 # we get a prototype mismatch. Hence this less than aesthetically
33 # appealing BEGIN block:
36 unless( defined &SEEK_SET ) {
37 *SEEK_SET = sub { 0 };
38 *SEEK_CUR = sub { 1 };
39 *SEEK_END = sub { 2 };
42 unless( defined &O_BINARY ) {
43 *O_BINARY = sub { 0 };
44 *O_RDONLY = sub { 0 };
45 *O_WRONLY = sub { 1 };
48 unless ( defined &O_APPEND ) {
50 if ( $^O =~ /olaris/ ) {
51 *O_APPEND = sub { 8 };
52 *O_CREAT = sub { 256 };
53 *O_EXCL = sub { 1024 };
55 elsif ( $^O =~ /inux/ ) {
56 *O_APPEND = sub { 1024 };
57 *O_CREAT = sub { 64 };
58 *O_EXCL = sub { 128 };
60 elsif ( $^O =~ /BSD/i ) {
61 *O_APPEND = sub { 8 };
62 *O_CREAT = sub { 512 };
63 *O_EXCL = sub { 2048 };
68 # print "OS [$^O]\n" ;
70 # print "O_BINARY = ", O_BINARY(), "\n" ;
71 # print "O_RDONLY = ", O_RDONLY(), "\n" ;
72 # print "O_WRONLY = ", O_WRONLY(), "\n" ;
73 # print "O_APPEND = ", O_APPEND(), "\n" ;
74 # print "O_CREAT ", O_CREAT(), "\n" ;
75 # print "O_EXCL ", O_EXCL(), "\n" ;
78 *slurp = \&read_file ;
82 my $file_name = shift ;
83 my $opts = ( ref $_[0] eq 'HASH' ) ? shift : { @_ } ;
85 if ( !ref $file_name && 0 &&
86 -e $file_name && -s _ < $max_fast_slurp_size && ! %{$opts} && !wantarray ) {
90 unless( open( FH, $file_name ) ) {
92 @_ = ( $opts, "read_file '$file_name' - sysopen: $!");
96 my $read_cnt = sysread( FH, my $buf, -s _ ) ;
98 unless ( defined $read_cnt ) {
100 # handle the read error
103 "read_file '$file_name' - small sysread: $!");
110 # set the buffer to either the passed in one or ours and init it to the null
114 my $buf_ref = $opts->{'buf_ref'} || \$buf ;
117 my( $read_fh, $size_left, $blk_size ) ;
119 # deal with ref for a file name
120 # it could be an open handle or an overloaded object
122 if ( ref $file_name ) {
124 my $ref_result = _check_ref( $file_name ) ;
126 if ( ref $ref_result ) {
128 # we got an error, deal with it
130 @_ = ( $opts, $ref_result ) ;
136 # we got an overloaded object and the result is the stringified value
137 # use it as the file name
139 $file_name = $ref_result ;
143 # here we have just an open handle. set $read_fh so we don't do a sysopen
145 $read_fh = $file_name ;
146 $blk_size = $opts->{'blk_size'} || 1024 * 1024 ;
147 $size_left = $blk_size ;
151 # see if we have a path we need to open
153 unless ( $read_fh ) {
155 # a regular file. set the sysopen mode
157 my $mode = O_RDONLY ;
159 #printf "RD: BINARY %x MODE %x\n", O_BINARY, $mode ;
161 # open the file and handle any error
164 unless ( sysopen( $read_fh, $file_name, $mode ) ) {
165 @_ = ( $opts, "read_file '$file_name' - sysopen: $!");
169 if ( my $binmode = $opts->{'binmode'} ) {
170 binmode( $read_fh, $binmode ) ;
173 # get the size of the file for use in the read loop
175 $size_left = -s $read_fh ;
177 #print "SIZE $size_left\n" ;
180 # we need a blk_size if the size is 0 so we can handle pseudofiles like in
181 # /proc. these show as 0 size but have data to be slurped.
183 unless( $size_left ) {
185 $blk_size = $opts->{'blk_size'} || 1024 * 1024 ;
186 $size_left = $blk_size ;
191 # if ( $size_left < 10000 && keys %{$opts} == 0 && !wantarray ) {
193 # #print "OPT\n" and $printed++ unless $printed ;
195 # my $read_cnt = sysread( $read_fh, my $buf, $size_left ) ;
197 # unless ( defined $read_cnt ) {
199 # # handle the read error
201 # @_ = ( $opts, "read_file '$file_name' - small2 sysread: $!");
208 # infinite read loop. we exit when we are done slurping
212 # do the read and see how much we got
214 my $read_cnt = sysread( $read_fh, ${$buf_ref},
215 $size_left, length ${$buf_ref} ) ;
217 unless ( defined $read_cnt ) {
219 # handle the read error
221 @_ = ( $opts, "read_file '$file_name' - loop sysread: $!");
225 # good read. see if we hit EOF (nothing left to read)
227 last if $read_cnt == 0 ;
229 # loop if we are slurping a handle. we don't track $size_left then.
233 # count down how much we read and loop if we have more to read.
235 $size_left -= $read_cnt ;
236 last if $size_left <= 0 ;
239 # fix up cr/lf to be a newline if this is a windows text file
241 ${$buf_ref} =~ s/\015\012/\n/g if $is_win32 && !$opts->{'binmode'} ;
243 # this is the 5 returns in a row. each handles one possible
244 # combination of caller context and requested return type
247 $sep = '\n\n+' if defined $sep && $sep eq '' ;
249 # see if caller wants lines
251 if( wantarray || $opts->{'array_ref'} ) {
253 my @parts = split m/($sep)/, ${$buf_ref}, -1;
257 while( @parts > 2 ) {
259 my( $line, $sep ) = splice( @parts, 0, 2 ) ;
260 push @lines, "$line$sep" ;
263 push @lines, shift @parts if @parts && length $parts[0] ;
265 return \@lines if $opts->{'array_ref'} ;
269 # caller wants a scalar ref to the slurped text
271 return $buf_ref if $opts->{'scalar_ref'} ;
273 # caller wants a scalar with the slurped text (normal scalar context)
275 return ${$buf_ref} if defined wantarray ;
277 # caller passed in an i/o buffer by reference (normal void context)
282 # # caller wants to get an array ref of lines
284 # # this split doesn't work since it tries to use variable length lookbehind
285 # # the m// line works.
286 # # return [ split( m|(?<=$sep)|, ${$buf_ref} ) ] if $opts->{'array_ref'} ;
287 # return [ length(${$buf_ref}) ? ${$buf_ref} =~ /(.*?$sep|.+)/sg : () ]
288 # if $opts->{'array_ref'} ;
290 # # caller wants a list of lines (normal list context)
292 # # same problem with this split as before.
293 # # return split( m|(?<=$sep)|, ${$buf_ref} ) if wantarray ;
294 # return length(${$buf_ref}) ? ${$buf_ref} =~ /(.*?$sep|.+)/sg : ()
297 # # caller wants a scalar ref to the slurped text
299 # return $buf_ref if $opts->{'scalar_ref'} ;
301 # # caller wants a scalar with the slurped text (normal scalar context)
303 # return ${$buf_ref} if defined wantarray ;
305 # # caller passed in an i/o buffer by reference (normal void context)
311 # errors in this sub are returned as scalar refs
312 # a normal IO/GLOB handle is an empty return
313 # an overloaded object returns its stringified as a scalarfilename
319 # check if we are reading from a handle (GLOB or IO object)
321 if ( eval { $handle->isa( 'GLOB' ) || $handle->isa( 'IO' ) } ) {
323 # we have a handle. deal with seeking to it if it is DATA
325 my $err = _seek_data_handle( $handle ) ;
327 # return the error string if any
329 return \$err if $err ;
331 # we have good handle
335 eval { require overload } ;
337 # return an error if we can't load the overload pragma
338 # or if the object isn't overloaded
340 return \"Bad handle '$handle' is not a GLOB or IO object or overloaded"
341 if $@ || !overload::Overloaded( $handle ) ;
343 # must be overloaded so return its stringified value
348 sub _seek_data_handle {
352 # DEEP DARK MAGIC. this checks the UNTAINT IO flag of a
353 # glob/handle. only the DATA handle is untainted (since it is from
354 # trusted data in the source file). this allows us to test if this is
355 # the DATA handle and then to do a sysseek to make sure it gets
356 # slurped correctly. on some systems, the buffered i/o pointer is not
357 # left at the same place as the fd pointer. this sysseek makes them
358 # the same so slurping with sysread will work.
365 Can't find B.pm with this Perl: $!.
366 That module is needed to properly slurp the DATA handle.
370 if ( B::svref_2object( $handle )->IO->IoFLAGS & 16 ) {
372 # set the seek position to the current tell.
374 unless( sysseek( $handle, tell( $handle ), SEEK_SET ) ) {
375 return "read_file '$handle' - sysseek: $!" ;
379 # seek was successful, return no error string
387 my $file_name = shift ;
389 # get the optional argument hash ref from @_ or an empty hash ref.
391 my $opts = ( ref $_[0] eq 'HASH' ) ? shift : {} ;
393 my( $buf_ref, $write_fh, $no_truncate, $orig_file_name, $data_is_ref ) ;
395 # get the buffer ref - it depends on how the data is passed into write_file
396 # after this if/else $buf_ref will have a scalar ref to the data.
398 if ( ref $opts->{'buf_ref'} eq 'SCALAR' ) {
400 # a scalar ref passed in %opts has the data
401 # note that the data was passed by ref
403 $buf_ref = $opts->{'buf_ref'} ;
406 elsif ( ref $_[0] eq 'SCALAR' ) {
408 # the first value in @_ is the scalar ref to the data
409 # note that the data was passed by ref
414 elsif ( ref $_[0] eq 'ARRAY' ) {
416 # the first value in @_ is the array ref to the data so join it.
418 ${$buf_ref} = join '', @{$_[0]} ;
422 # good old @_ has all the data so join it.
424 ${$buf_ref} = join '', @_ ;
427 # deal with ref for a file name
429 if ( ref $file_name ) {
431 my $ref_result = _check_ref( $file_name ) ;
433 if ( ref $ref_result ) {
435 # we got an error, deal with it
437 @_ = ( $opts, $ref_result ) ;
443 # we got an overloaded object and the result is the stringified value
444 # use it as the file name
446 $file_name = $ref_result ;
450 # we now have a proper handle ref.
451 # make sure we don't call truncate on it.
453 $write_fh = $file_name ;
458 # see if we have a path we need to open
460 unless( $write_fh ) {
462 # spew to regular file.
464 if ( $opts->{'atomic'} ) {
466 # in atomic mode, we spew to a temp file so make one and save the original
468 $orig_file_name = $file_name ;
469 $file_name .= ".$$" ;
472 # set the mode for the sysopen
474 my $mode = O_WRONLY | O_CREAT ;
475 $mode |= O_APPEND if $opts->{'append'} ;
476 $mode |= O_EXCL if $opts->{'no_clobber'} ;
478 my $perms = $opts->{perms} ;
479 $perms = 0666 unless defined $perms ;
481 #printf "WR: BINARY %x MODE %x\n", O_BINARY, $mode ;
483 # open the file and handle any error.
486 unless ( sysopen( $write_fh, $file_name, $mode, $perms ) ) {
488 @_ = ( $opts, "write_file '$file_name' - sysopen: $!");
493 if ( my $binmode = $opts->{'binmode'} ) {
494 binmode( $write_fh, $binmode ) ;
497 sysseek( $write_fh, 0, SEEK_END ) if $opts->{'append'} ;
500 #print 'WR before data ', unpack( 'H*', ${$buf_ref}), "\n" ;
502 # fix up newline to write cr/lf if this is a windows text file
504 if ( $is_win32 && !$opts->{'binmode'} ) {
506 # copy the write data if it was passed by ref so we don't clobber the
508 $buf_ref = \do{ my $copy = ${$buf_ref}; } if $data_is_ref ;
509 ${$buf_ref} =~ s/\n/\015\012/g ;
512 #print 'after data ', unpack( 'H*', ${$buf_ref}), "\n" ;
514 # get the size of how much we are writing and init the offset into that buffer
516 my $size_left = length( ${$buf_ref} ) ;
519 # loop until we have no more data left to write
523 # do the write and track how much we just wrote
525 my $write_cnt = syswrite( $write_fh, ${$buf_ref},
526 $size_left, $offset ) ;
528 unless ( defined $write_cnt ) {
531 @_ = ( $opts, "write_file '$file_name' - syswrite: $!");
535 # track much left to write and where to write from in the buffer
537 $size_left -= $write_cnt ;
538 $offset += $write_cnt ;
540 } while( $size_left > 0 ) ;
542 # we truncate regular files in case we overwrite a long file with a shorter file
543 # so seek to the current position to get it (same as tell()).
546 sysseek( $write_fh, 0, SEEK_CUR ) ) unless $no_truncate ;
550 # handle the atomic mode - move the temp file to the original filename.
552 if ( $opts->{'atomic'} && !rename( $file_name, $orig_file_name ) ) {
554 @_ = ( $opts, "write_file '$file_name' - rename: $!" ) ;
561 # this is for backwards compatibility with the previous File::Slurp module.
562 # write_file always overwrites an existing file
564 *overwrite_file = \&write_file ;
566 # the current write_file has an append mode so we use that. this
567 # supports the same API with an optional second argument which is a
568 # hash ref of options.
572 # get the optional opts hash ref
574 if ( ref $opts eq 'HASH' ) {
576 # we were passed an opts ref so just mark the append mode
578 $opts->{append} = 1 ;
582 # no opts hash so insert one with the append mode
584 splice( @_, 1, 0, { append => 1 } ) ;
587 # magic goto the main write_file sub. this overlays the sub without touching
593 # basic wrapper around opendir/readdir
595 # prepend data to the beginning of a file
599 my $file_name = shift ;
601 #print "FILE $file_name\n" ;
603 my $opts = ( ref $_[0] eq 'HASH' ) ? shift : {} ;
605 # delete unsupported options
608 grep $_ ne 'err_mode' && $_ ne 'binmode', keys %{$opts} ;
610 delete @{$opts}{@bad_opts} ;
612 my $prepend_data = shift ;
613 $prepend_data = '' unless defined $prepend_data ;
614 $prepend_data = ${$prepend_data} if ref $prepend_data eq 'SCALAR' ;
616 #print "PRE [$prepend_data]\n" ;
619 ###### set croak as error_mode
622 my $err_mode = delete $opts->{err_mode} ;
623 $opts->{ err_mode } = 'croak' ;
624 $opts->{ scalar_ref } = 1 ;
627 eval { $existing_data = read_file( $file_name, $opts ) } ;
631 @_ = ( { err_mode => $err_mode },
632 "prepend_file '$file_name' - read_file: $!" ) ;
636 #print "EXIST [$$existing_data]\n" ;
638 $opts->{ atomic } = 1 ;
640 my $write_result = eval {
641 write_file( $file_name, $opts,
642 $prepend_data, $$existing_data ) ;
647 @_ = ( { err_mode => $err_mode },
648 "prepend_file '$file_name' - write_file: $!" ) ;
652 return $write_result ;
658 my $opts = ( ref $_[0] eq 'HASH' ) ? shift : { @_ } ;
660 # this handle will be destroyed upon return
664 # open the dir and handle any errors
666 unless ( opendir( DIRH, $dir ) ) {
668 @_ = ( $opts, "read_dir '$dir' - opendir: $!" ) ;
672 my @dir_entries = readdir(DIRH) ;
674 @dir_entries = grep( $_ ne "." && $_ ne "..", @dir_entries )
675 unless $opts->{'keep_dot_dot'} ;
677 return @dir_entries if wantarray ;
678 return \@dir_entries ;
681 # error handling section
683 # all the error handling uses magic goto so the caller will get the
684 # error message as if from their code and not this module. if we just
685 # did a call on the error code, the carp/croak would report it from
686 # this module since the error sub is one level down on the call stack
687 # from read_file/write_file/read_dir.
697 my( $opts, $err_msg ) = @_ ;
699 # get the error function to use
701 my $func = $err_func{ $opts->{'err_mode'} || 'croak' } ;
703 # if we didn't find it in our error function hash, they must have set
704 # it to quiet and we don't do anything.
706 return unless $func ;
708 # call the carp/croak function
710 $func->($err_msg) if $func ;
712 # return a hard undef (in list context this will be a single value of
713 # undef which is not a legal in-band value)
723 File::Slurp - Simple and Efficient Reading/Writing of Complete Files
729 # read in a whole file into a scalar
731 my $text = read_file( 'filename' ) ;
733 # read in a whole file into an array of lines
735 my @lines = read_file( 'filename' ) ;
737 # write out a whole file from a scalar
739 write_file( 'filename', $text ) ;
741 # write out a whole file from an array of lines
743 write_file( 'filename', @lines ) ;
745 # Here is a simple and fast way to load and save a simple config file
746 # made of key=value lines.
748 my %conf = read_file( $file_name ) =~ /^(\w+)=(\.*)$/mg ;
749 write_file( $file_name, {atomic => 1}, map "$_=$conf{$_}\n", keys %conf ;
751 # read in a whole directory of file names (skipping . and ..)
753 my @files = read_dir( '/path/to/dir' ) ;
757 This module provides subs that allow you to read or write entire files
758 with one simple call. They are designed to be simple to use, have
759 flexible ways to pass in or get the file contents and to be very
760 efficient. There is also a sub to read in all the files in a
761 directory other than C<.> and C<..>
763 These slurp/spew subs work for files, pipes and sockets, stdio,
764 pseudo-files, and the DATA handle. Read more about why slurping files is
765 a good thing in the file 'slurp_article.pod' in the extras/ directory.
767 If you are interested in how fast these calls work, check out the
768 slurp_bench.pl program in the extras/ directory. It compares many
769 different forms of slurping. You can select the I/O direction, context
770 and file sizes. Use the --help option to see how to run it.
774 This sub reads in an entire file and returns its contents to the
775 caller. In scalar context it returns the entire file as a single
776 scalar. In list context it will return a list of lines (using the
777 current value of $/ as the separator including support for paragraph
778 mode when it is set to '').
780 my $text = read_file( 'filename' ) ;
781 my $bin = read_file( 'filename' { binmode => ':raw' } ) ;
782 my @lines = read_file( 'filename' ) ;
783 my $lines = read_file( 'filename', array_ref => 1 ) ;
785 The first argument is the file to slurp in. If the next argument is a
786 hash reference, then it is used as the options. Otherwise the rest of
787 the argument list are is used as key/value options.
789 If the file argument is a handle (if it is a ref and is an IO or GLOB
790 object), then that handle is slurped in. This mode is supported so you
791 slurp handles such as C<DATA> and C<STDIN>. See the test handle.t for
792 an example that does C<open( '-|' )> and the child process spews data
793 to the parant which slurps it in. All of the options that control how
794 the data is returned to the caller still work in this case.
796 If the first argument is an overloaded object then its stringified value
797 is used for the filename and that file is opened. This is a new feature
798 in 9999.14. See the stringify.t test for an example.
800 By default C<read_file> returns an undef in scalar contex or a single
801 undef in list context if it encounters an error. Those are both
802 impossible to get with a clean read_file call which means you can check
803 the return value and always know if you had an error. You can change how
804 errors are handled with the C<err_mode> option.
806 NOTE: as of version 9999.06, read_file works correctly on the C<DATA>
807 handle. It used to need a sysseek workaround but that is now handled
808 when needed by the module itself.
810 You can optionally request that C<slurp()> is exported to your code. This
811 is an alias for read_file and is meant to be forward compatible with
812 Perl 6 (which will have slurp() built-in).
814 The options for C<read_file> are:
818 If you set the binmode option, then its value is passed to a call to
819 binmode on the opened handle. You can use this to set the file to be
820 read in binary mode, utf8, etc. See perldoc -f binmode for more.
822 my $bin_data = read_file( $bin_file, binmode => ':raw' ) ;
823 my $utf_text = read_file( $bin_file, binmode => ':utf8' ) ;
827 If this boolean option is set, the return value (only in scalar
828 context) will be an array reference which contains the lines of the
829 slurped file. The following two calls are equivalent:
831 my $lines_ref = read_file( $bin_file, array_ref => 1 ) ;
832 my $lines_ref = [ read_file( $bin_file ) ] ;
836 If this boolean option is set, the return value (only in scalar context)
837 will be an scalar reference to a string which is the contents of the
838 slurped file. This will usually be faster than returning the plain
839 scalar. It will also save memory as it will not make a copy of the file
842 my $text_ref = read_file( $bin_file, scalar_ref => 1 ) ;
846 You can use this option to pass in a scalar reference and the slurped
847 file contents will be stored in the scalar. This can be used in
848 conjunction with any of the other options. This saves an extra copy of
849 the slurped file and can lower ram usage vs returning the file.
851 read_file( $bin_file, buf_ref => \$buffer ) ;
855 You can use this option to set the block size used when slurping from
856 an already open handle (like \*STDIN). It defaults to 1MB.
858 my $text_ref = read_file( $bin_file, blk_size => 10_000_000,
863 You can use this option to control how read_file behaves when an error
864 occurs. This option defaults to 'croak'. You can set it to 'carp' or to
865 'quiet to have no special error handling. This code wants to carp and
866 then read another file if it fails.
868 my $text_ref = read_file( $file, err_mode => 'carp' ) ;
869 unless ( $text_ref ) {
871 # read a different file but croak if not found
872 $text_ref = read_file( $another_file ) ;
875 # process ${$text_ref}
879 This sub writes out an entire file in one call.
881 write_file( 'filename', @data ) ;
883 The first argument to C<write_file> is the filename. The next argument
884 is an optional hash reference and it contains key/values that can
885 modify the behavior of C<write_file>. The rest of the argument list is
886 the data to be written to the file.
888 write_file( 'filename', {append => 1 }, @data ) ;
889 write_file( 'filename', {binmode => ':raw'}, $buffer ) ;
891 As a shortcut if the first data argument is a scalar or array reference,
892 it is used as the only data to be written to the file. Any following
893 arguments in @_ are ignored. This is a faster way to pass in the output
894 to be written to the file and is equivalent to the C<buf_ref> option of
895 C<read_file>. These following pairs are equivalent but the pass by
896 reference call will be faster in most cases (especially with larger
899 write_file( 'filename', \$buffer ) ;
900 write_file( 'filename', $buffer ) ;
902 write_file( 'filename', \@lines ) ;
903 write_file( 'filename', @lines ) ;
905 If the first argument is a handle (if it is a ref and is an IO or GLOB
906 object), then that handle is written to. This mode is supported so you
907 spew to handles such as \*STDOUT. See the test handle.t for an example
908 that does C<open( '-|' )> and child process spews data to the parent
909 which slurps it in. All of the options that control how the data are
910 passed into C<write_file> still work in this case.
912 If the first argument is an overloaded object then its stringified value
913 is used for the filename and that file is opened. This is new feature
914 in 9999.14. See the stringify.t test for an example.
916 By default C<write_file> returns 1 upon successfully writing the file or
917 undef if it encountered an error. You can change how errors are handled
918 with the C<err_mode> option.
924 If you set the binmode option, then its value is passed to a call to
925 binmode on the opened handle. You can use this to set the file to be
926 read in binary mode, utf8, etc. See perldoc -f binmode for more.
928 write_file( $bin_file, {binmode => ':raw'}, @data ) ;
929 write_file( $bin_file, {binmode => ':utf8'}, $utf_text ) ;
933 The perms option sets the permissions of newly-created files. This value
934 is modified by your process's umask and defaults to 0666 (same as
937 NOTE: this option is new as of File::Slurp version 9999.14;
941 You can use this option to pass in a scalar reference which has the
942 data to be written. If this is set then any data arguments (including
943 the scalar reference shortcut) in @_ will be ignored. These are
946 write_file( $bin_file, { buf_ref => \$buffer } ) ;
947 write_file( $bin_file, \$buffer ) ;
948 write_file( $bin_file, $buffer ) ;
952 If you set this boolean option, the file will be written to in an
953 atomic fashion. A temporary file name is created by appending the pid
954 ($$) to the file name argument and that file is spewed to. After the
955 file is closed it is renamed to the original file name (and rename is
956 an atomic operation on most OS's). If the program using this were to
957 crash in the middle of this, then the file with the pid suffix could
962 If you set this boolean option, the data will be written at the end of
963 the current file. Internally this sets the sysopen mode flag O_APPEND.
965 write_file( $file, {append => 1}, @data ) ;
968 can import append_file and it does the same thing.
972 If you set this boolean option, an existing file will not be overwritten.
974 write_file( $file, {no_clobber => 1}, @data ) ;
978 You can use this option to control how C<write_file> behaves when an
979 error occurs. This option defaults to 'croak'. You can set it to
980 'carp' or to 'quiet' to have no error handling other than the return
981 value. If the first call to C<write_file> fails it will carp and then
982 write to another file. If the second call to C<write_file> fails, it
985 unless ( write_file( $file, { err_mode => 'carp', \$data ) ;
987 # write a different file but croak if not found
988 write_file( $other_file, \$data ) ;
991 =head2 overwrite_file
993 This sub is just a typeglob alias to write_file since write_file
994 always overwrites an existing file. This sub is supported for
995 backwards compatibility with the original version of this module. See
996 write_file for its API and behavior.
1000 This sub will write its data to the end of the file. It is a wrapper
1001 around write_file and it has the same API so see that for the full
1002 documentation. These calls are equivalent:
1004 append_file( $file, @data ) ;
1005 write_file( $file, {append => 1}, @data ) ;
1010 This sub writes data to the beginning of a file. The previously existing
1011 data is written after that so the effect is prepending data in front of
1012 a file. It is a counterpart to the append_file sub in this module. It
1013 works by first using C<read_file> to slurp in the file and then calling
1014 C<write_file> with the new data and the existing file data.
1016 The first argument to C<prepend_file> is the filename. The next argument
1017 is an optional hash reference and it contains key/values that can modify
1018 the behavior of C<prepend_file>. The rest of the argument list is the
1019 data to be written to the file and that is passed to C<write_file> as is
1020 (see that for allowed data).
1022 Only the C<binmode> and C<err_mode> options are supported. The
1023 C<write_file> call has the C<atomic> option set so you will always have
1024 a consistant file. See above for more about those options.
1026 C<prepend_file> is not exported by default, you need to import it
1029 use File::Slurp qw( prepend_file ) ;
1030 prepend_file( $file, $header ) ;
1031 prepend_file( $file, \@lines ) ;
1032 prepend_file( $file, { binmode => 'raw:'}, $bin_data ) ;
1036 This sub reads all the file names from directory and returns them to
1037 the caller but C<.> and C<..> are removed by default.
1039 my @files = read_dir( '/path/to/dir' ) ;
1041 The first argument is the path to the directory to read. If the next
1042 argument is a hash reference, then it is used as the options.
1043 Otherwise the rest of the argument list are is used as key/value
1046 In list context C<read_dir> returns a list of the entries in the
1047 directory. In a scalar context it returns an array reference which has
1052 If the C<err_mode> option is set, it selects how errors are handled (see
1053 C<err_mode> in C<read_file> or C<write_file>).
1057 If this boolean option is set, C<.> and C<..> are not removed from the
1060 my @all_files = read_dir( '/path/to/dir', keep_dot_dot => 1 ) ;
1064 read_file write_file overwrite_file append_file read_dir
1072 An article on file slurping in extras/slurp_article.pod. There is
1073 also a benchmarking script in extras/slurp_bench.pl.
1077 If run under Perl 5.004, slurping from the DATA handle will fail as
1078 that requires B.pm which didn't get into core until 5.005.
1082 Uri Guttman, E<lt>uri AT stemsystems DOT comE<gt>