OBS-URL: https://build.opensuse.org/package/show/devel:languages:perl/perl-File-Slurp?expand=0&rev=14
This commit is contained in:
Stephan Kulow
Git OBS Bridge
parent
b56772bb74
commit
8b6eff6962
@ -54,267 +54,6 @@ slurp_bench.pl program in the extras/ directory. It compares many different
|
|||||||
forms of slurping. You can select the I/O direction, context and file
|
forms of slurping. You can select the I/O direction, context and file
|
||||||
sizes. Use the --help option to see how to run it.
|
sizes. Use the --help option to see how to run it.
|
||||||
|
|
||||||
*read_file*
|
|
||||||
This sub reads in an entire file and returns its contents to the
|
|
||||||
caller. In list context it will return a list of lines (using the
|
|
||||||
current value of $/ as the separator including support for paragraph
|
|
||||||
mode when it is set to ''). In scalar context it returns the entire
|
|
||||||
file as a single scalar.
|
|
||||||
|
|
||||||
my $text = read_file( 'filename' ) ;
|
|
||||||
my @lines = read_file( 'filename' ) ;
|
|
||||||
|
|
||||||
By default 'read_file' returns an undef in scalar contex or a single
|
|
||||||
undef in list context if it encounters an error. Those are both
|
|
||||||
impossible to get with a clean read_file call which means you can check
|
|
||||||
the return value and always know if you had an error. You can change
|
|
||||||
how errors are handled with the 'err_mode' option.
|
|
||||||
|
|
||||||
The first argument to 'read_file' is the filename and the rest of the
|
|
||||||
arguments are key/value pairs which are optional and which modify the
|
|
||||||
behavior of the call. Other than binmode the options all control how
|
|
||||||
the slurped file is returned to the caller or how errors are handled.
|
|
||||||
|
|
||||||
If the first argument is a handle (if it is a ref and is an IO or GLOB
|
|
||||||
object), then that handle is slurped in. This mode is supported so you
|
|
||||||
slurp handles such as 'DATA', 'STDIN'. See the test handle.t for an
|
|
||||||
example that does 'open( '-|' )' and child process spews data to the
|
|
||||||
parant which slurps it in. All of the options that control how the data
|
|
||||||
is returned to the caller still work in this case.
|
|
||||||
|
|
||||||
If the first argument is an overloaded object then its stringified
|
|
||||||
value is used for the filename and that file is opened. This is a new
|
|
||||||
feature in 9999.14. See the stringify.t test for an example.
|
|
||||||
|
|
||||||
NOTE: as of version 9999.06, read_file works correctly on the 'DATA'
|
|
||||||
handle. It used to need a sysseek workaround but that is now handled
|
|
||||||
when needed by the module itself.
|
|
||||||
|
|
||||||
You can optionally request that 'slurp()' is exported to your code.
|
|
||||||
This is an alias for read_file and is meant to be forward compatible
|
|
||||||
with Perl 6 (which will have slurp() built-in).
|
|
||||||
|
|
||||||
The options are:
|
|
||||||
|
|
||||||
binmode
|
|
||||||
If you set the binmode option, then its value is passed to a call
|
|
||||||
to binmode on the opened handle. You can use this to set the file
|
|
||||||
to be read in binary mode, utf8, etc. See perldoc -f binmode for
|
|
||||||
more.
|
|
||||||
|
|
||||||
my $bin_data = read_file( $bin_file, binmode => ':raw' ) ;
|
|
||||||
my $utf_text = read_file( $bin_file, binmode => ':utf8' ) ;
|
|
||||||
|
|
||||||
array_ref
|
|
||||||
If this boolean option is set, the return value (only in scalar
|
|
||||||
context) will be an array reference which contains the lines of the
|
|
||||||
slurped file. The following two calls are equivalent:
|
|
||||||
|
|
||||||
my $lines_ref = read_file( $bin_file, array_ref => 1 ) ;
|
|
||||||
my $lines_ref = [ read_file( $bin_file ) ] ;
|
|
||||||
|
|
||||||
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. 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 ) ;
|
|
||||||
|
|
||||||
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. 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 ) ;
|
|
||||||
my @lines = read_file( $bin_file, buf_ref => \$buffer ) ;
|
|
||||||
|
|
||||||
blk_size
|
|
||||||
You can use this option to set the block size used when slurping
|
|
||||||
from an already open handle (like \*STDIN). It defaults to 1MB.
|
|
||||||
|
|
||||||
my $text_ref = read_file( $bin_file, blk_size => 10_000_000,
|
|
||||||
array_ref => 1 ) ;
|
|
||||||
|
|
||||||
err_mode
|
|
||||||
You can use this option to control how read_file behaves when an
|
|
||||||
error occurs. This option defaults to 'croak'. You can set it to
|
|
||||||
'carp' or to 'quiet to have no special error handling. This code
|
|
||||||
wants to carp and then read another file if it fails.
|
|
||||||
|
|
||||||
my $text_ref = read_file( $file, err_mode => 'carp' ) ;
|
|
||||||
unless ( $text_ref ) {
|
|
||||||
|
|
||||||
# read a different file but croak if not found
|
|
||||||
$text_ref = read_file( $another_file ) ;
|
|
||||||
}
|
|
||||||
|
|
||||||
# process ${$text_ref}
|
|
||||||
|
|
||||||
*write_file*
|
|
||||||
This sub writes out an entire file in one call.
|
|
||||||
|
|
||||||
write_file( 'filename', @data ) ;
|
|
||||||
|
|
||||||
The first argument to 'write_file' is the filename. The next argument
|
|
||||||
is an optional hash reference and it contains key/values that can
|
|
||||||
modify the behavior of 'write_file'. The rest of the argument list is
|
|
||||||
the data to be written to the file.
|
|
||||||
|
|
||||||
write_file( 'filename', {append => 1 }, @data ) ;
|
|
||||||
write_file( 'filename', {binmode => ':raw'}, $buffer ) ;
|
|
||||||
|
|
||||||
As a shortcut if the first data argument is a scalar or array
|
|
||||||
reference, it is used as the only data to be written to the file. Any
|
|
||||||
following arguments in @_ are ignored. This is a faster way to pass in
|
|
||||||
the output to be written to the file and is equivalent to the 'buf_ref'
|
|
||||||
option of 'read_file'. These following pairs are equivalent but the
|
|
||||||
pass by reference call will be faster in most cases (especially with
|
|
||||||
larger files).
|
|
||||||
|
|
||||||
write_file( 'filename', \$buffer ) ;
|
|
||||||
write_file( 'filename', $buffer ) ;
|
|
||||||
|
|
||||||
write_file( 'filename', \@lines ) ;
|
|
||||||
write_file( 'filename', @lines ) ;
|
|
||||||
|
|
||||||
If the first argument is a handle (if it is a ref and is an IO or GLOB
|
|
||||||
object), then that handle is written to. This mode is supported so you
|
|
||||||
spew to handles such as \*STDOUT. See the test handle.t for an example
|
|
||||||
that does 'open( '-|' )' and child process spews data to the parent
|
|
||||||
which slurps it in. All of the options that control how the data are
|
|
||||||
passed into 'write_file' still work in this case.
|
|
||||||
|
|
||||||
If the first argument is an overloaded object then its stringified
|
|
||||||
value is used for the filename and that file is opened. This is new
|
|
||||||
feature in 9999.14. See the stringify.t test for an example.
|
|
||||||
|
|
||||||
By default 'write_file' returns 1 upon successfully writing the file or
|
|
||||||
undef if it encountered an error. You can change how errors are handled
|
|
||||||
with the 'err_mode' option.
|
|
||||||
|
|
||||||
The options are:
|
|
||||||
|
|
||||||
binmode
|
|
||||||
If you set the binmode option, then its value is passed to a call
|
|
||||||
to binmode on the opened handle. You can use this to set the file
|
|
||||||
to be read in binary mode, utf8, etc. See perldoc -f binmode for
|
|
||||||
more.
|
|
||||||
|
|
||||||
write_file( $bin_file, {binmode => ':raw'}, @data ) ;
|
|
||||||
write_file( $bin_file, {binmode => ':utf8'}, $utf_text ) ;
|
|
||||||
|
|
||||||
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;
|
|
||||||
|
|
||||||
buf_ref
|
|
||||||
You can use this option to pass in a scalar reference which has the
|
|
||||||
data to be written. If this is set then any data arguments
|
|
||||||
(including the scalar reference shortcut) in @_ will be ignored.
|
|
||||||
These are equivalent:
|
|
||||||
|
|
||||||
write_file( $bin_file, { buf_ref => \$buffer } ) ;
|
|
||||||
write_file( $bin_file, \$buffer ) ;
|
|
||||||
write_file( $bin_file, $buffer ) ;
|
|
||||||
|
|
||||||
atomic
|
|
||||||
If you set this boolean option, the file will be written to in an
|
|
||||||
atomic fashion. A temporary file name is created by appending the
|
|
||||||
pid ($$) to the file name argument and that file is spewed to.
|
|
||||||
After the file is closed it is renamed to the original file name
|
|
||||||
(and rename is an atomic operation on most OS's). If the program
|
|
||||||
using this were to crash in the middle of this, then the file with
|
|
||||||
the pid suffix could be left behind.
|
|
||||||
|
|
||||||
append
|
|
||||||
If you set this boolean option, the data will be written at the end
|
|
||||||
of the current file. Internally this sets the sysopen mode flag
|
|
||||||
O_APPEND.
|
|
||||||
|
|
||||||
write_file( $file, {append => 1}, @data ) ;
|
|
||||||
|
|
||||||
You
|
|
||||||
can import append_file and it does the same thing.
|
|
||||||
|
|
||||||
no_clobber
|
|
||||||
If you set this boolean option, an existing file will not be
|
|
||||||
overwritten.
|
|
||||||
|
|
||||||
write_file( $file, {no_clobber => 1}, @data ) ;
|
|
||||||
|
|
||||||
err_mode
|
|
||||||
You can use this option to control how 'write_file' behaves when an
|
|
||||||
error occurs. This option defaults to 'croak'. You can set it to
|
|
||||||
'carp' or to 'quiet' to have no error handling other than the
|
|
||||||
return value. If the first call to 'write_file' fails it will carp
|
|
||||||
and then write to another file. If the second call to 'write_file'
|
|
||||||
fails, it will croak.
|
|
||||||
|
|
||||||
unless ( write_file( $file, { err_mode => 'carp', \$data ) ;
|
|
||||||
|
|
||||||
# write a different file but croak if not found
|
|
||||||
write_file( $other_file, \$data ) ;
|
|
||||||
}
|
|
||||||
|
|
||||||
overwrite_file
|
|
||||||
This sub is just a typeglob alias to write_file since write_file always
|
|
||||||
overwrites an existing file. This sub is supported for backwards
|
|
||||||
compatibility with the original version of this module. See write_file
|
|
||||||
for its API and behavior.
|
|
||||||
|
|
||||||
append_file
|
|
||||||
This sub will write its data to the end of the file. It is a wrapper
|
|
||||||
around write_file and it has the same API so see that for the full
|
|
||||||
documentation. These calls are equivalent:
|
|
||||||
|
|
||||||
append_file( $file, @data ) ;
|
|
||||||
write_file( $file, {append => 1}, @data ) ;
|
|
||||||
|
|
||||||
read_dir
|
|
||||||
This sub reads all the file names from directory and returns them to
|
|
||||||
the caller but '.' and '..' are removed by default.
|
|
||||||
|
|
||||||
my @files = read_dir( '/path/to/dir' ) ;
|
|
||||||
|
|
||||||
The first argument is the path to the directory to read. The rest of
|
|
||||||
the arguments are a list key/value options.
|
|
||||||
|
|
||||||
In list context 'read_dir' returns a list of the entries in the
|
|
||||||
directory. In a scalar context it returns an array reference which has
|
|
||||||
the entries.
|
|
||||||
|
|
||||||
err_mode
|
|
||||||
If the 'err_mode' option is set, it selects how errors are handled
|
|
||||||
(see 'err_mode' in 'read_file' or 'write_file').
|
|
||||||
|
|
||||||
keep_dot_dot
|
|
||||||
If this boolean option is set, '.' and '..' are not removed from
|
|
||||||
the list of files.
|
|
||||||
|
|
||||||
my @all_files = read_dir( '/path/to/dir', keep_dot_dot => 1 ) ;
|
|
||||||
|
|
||||||
EXPORT
|
|
||||||
read_file write_file overwrite_file append_file read_dir
|
|
||||||
|
|
||||||
LICENSE
|
|
||||||
Same as Perl.
|
|
||||||
|
|
||||||
SEE ALSO
|
|
||||||
An article on file slurping in extras/slurp_article.pod. There is also
|
|
||||||
a benchmarking script in extras/slurp_bench.pl.
|
|
||||||
|
|
||||||
BUGS
|
|
||||||
If run under Perl 5.004, slurping from the DATA handle will fail as
|
|
||||||
that requires B.pm which didn't get into core until 5.005.
|
|
||||||
|
|
||||||
%prep
|
%prep
|
||||||
%setup -q -n %{cpan_name}-%{version}
|
%setup -q -n %{cpan_name}-%{version}
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user