added POD to state that using scalar_ref or buf_ref will be and save

[urisagit/Perl-Docs.git] / lib / File / Slurp.pm

diff --git a/lib/File/Slurp.pm b/lib/File/Slurp.pm
index 73249c6..965a492 100755 (executable)
--- a/lib/File/Slurp.pm
+++ b/lib/File/Slurp.pm
@@ -20,6 +20,8 @@ use vars qw( %EXPORT_TAGS @EXPORT_OK $VERSION @EXPORT ) ;
 
 $VERSION = '9999.14';
 
+our $max_fast_slurp_size = 1024 * 100 ;
+
 my $is_win32 = $^O =~ /win32/i ;
 
 # Install subs for various constants that aren't set in older perls
@@ -41,7 +43,7 @@ BEGIN {
                *O_WRONLY = sub { 1 };
        }
 
-       unless ( defined O_APPEND ) {
+       unless ( defined &O_APPEND ) {
 
                if ( $^O =~ /olaris/ ) {
                        *O_APPEND = sub { 8 };
@@ -78,7 +80,7 @@ sub read_file {
        my( $file_name, %args ) = @_ ;
 
        if ( !ref $file_name && 0 &&
-            -e $file_name && -s _ < 10000 && ! %args && !wantarray ) {
+            -e $file_name && -s _ < $max_fast_slurp_size && ! %args && !wantarray ) {
 
                local( *FH ) ;
 
@@ -342,18 +344,21 @@ sub write_file {
                $mode |= O_APPEND if $args->{'append'} ;
                $mode |= O_EXCL if $args->{'no_clobber'} ;
 
+               my $perms = $args->{perms} ;
+               $perms = 0666 unless defined $perms ;
+
 #printf "WR: BINARY %x MODE %x\n", O_BINARY, $mode ;
 
 # open the file and handle any error.
 
                $write_fh = gensym ;
-               unless ( sysopen( $write_fh, $file_name, $mode ) ) {
+               unless ( sysopen( $write_fh, $file_name, $mode, $perms ) ) {
                        @_ = ( $args, "write_file '$file_name' - sysopen: $!");
                        goto &_error ;
                }
        }
 
-       if ( my $binmode = $args{'binmode'} ) {
+       if ( my $binmode = $args->{'binmode'} ) {
                binmode( $write_fh, $binmode ) ;
        }
 
@@ -510,7 +515,7 @@ sub _error {
 
 # call the carp/croak function
 
-       $func->($err_msg) ;
+       $func->($err_msg) if $func ;
 
 # return a hard undef (in list context this will be a single value of
 # undef which is not a legal in-band value)
@@ -585,14 +590,11 @@ The options are:
 
 =head3 binmode
 
-If you set the binmode option, then the file will be slurped in binary
-mode.
+If you set the binmode option, then the option will be passed to a
+binmode call on the opened filehandle.
 
        my $bin_data = read_file( $bin_file, binmode => ':raw' ) ;
-
-NOTE: this actually sets the O_BINARY mode flag for sysopen. It
-probably should call binmode and pass its argument to support other
-file modes.
+       my $utf_text = read_file( $bin_file, binmode => ':utf8' ) ;
 
 =head3 array_ref
 
@@ -605,18 +607,29 @@ slurped file. The following two calls are equivalent:
 
 =head3 scalar_ref
 
-If this boolean option is set, the return value (only in scalar
-context) will be an scalar reference to a string which is the contents
-of the slurped file. This will usually be faster than returning the
-plain scalar.
+If this boolean option is set, the return value (only in scalar context)
+will be an scalar reference to a string which is the contents of the
+slurped file. This will usually be faster than returning the plain
+scalar. It will also save memory as it will not make a copy of the file
+to return.
 
        my $text_ref = read_file( $bin_file, scalar_ref => 1 ) ;
 
+=head3 perms
+
+The perms option sets the permissions of newly-created files. This value
+is modified by your process's umask and defaults to 0666 (same as
+sysopen).
+
+NOTE: this option is new as of File::Slurp version 9999.14;
+
+
 =head3 buf_ref
 
 You can use this option to pass in a scalar reference and the slurped
 file contents will be stored in the scalar. This can be used in
-conjunction with any of the other options.
+conjunction with any of the other options. This saves an extra copy of
+the slurped file and can lower ram usage vs returning the file.
 
        my $text_ref = read_file( $bin_file, buf_ref => \$buffer,
                                             array_ref => 1 ) ;
@@ -720,14 +733,12 @@ be left behind.
 =head3 append
 
 If you set this boolean option, the data will be written at the end of
-the current file.
+the current file. Internally this sets the sysopen mode flag O_APPEND.
 
        write_file( $file, {append => 1}, @data ) ;
 
 C<write_file> croaks if it cannot open the file. It returns true if it
-succeeded in writing out the file and undef if there was an
-error. (Yes, I know if it croaks it can't return anything but that is
-for when I add the options to select the error handling mode).
+succeeded in writing out the file and undef if there was an error.
 
 =head3 no_clobber
 
@@ -790,6 +801,10 @@ list of files.
 
   read_file write_file overwrite_file append_file read_dir
 
+=head2 LICENSE
+
+  Same as Perl.
+
 =head2 SEE ALSO
 
 An article on file slurping in extras/slurp_article.pod. There is