From: Uri Guttman <uri@quad.(none)>
Date: Thu, 22 Apr 2010 05:55:38 +0000 (-0400)
Subject: added POD to state that using scalar_ref or buf_ref will be and save
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=urisagit%2FPerl-Docs.git;a=commitdiff_plain;h=f02156f2bee079cf562de2f88179b46f435d079a

added POD to state that using scalar_ref or buf_ref will be and save
memory due to not making a copy
---

diff --git a/lib/File/Slurp.pm b/lib/File/Slurp.pm
index 6becb10..965a492 100755
--- a/lib/File/Slurp.pm
+++ b/lib/File/Slurp.pm
@@ -43,7 +43,7 @@ BEGIN {
 		*O_WRONLY = sub { 1 };
 	}
 
-	unless ( defined O_APPEND ) {
+	unless ( defined &O_APPEND ) {
 
 		if ( $^O =~ /olaris/ ) {
 			*O_APPEND = sub { 8 };
@@ -344,12 +344,15 @@ 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 ;
 		}
@@ -512,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)
@@ -604,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 ) ;
@@ -719,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
 
@@ -789,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