From: Uri Guttman 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?a=commitdiff_plain;h=f02156f2bee079cf562de2f88179b46f435d079a;p=urisagit%2FPerl-Docs.git 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 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