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
|
||||
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
|
||||
%setup -q -n %{cpan_name}-%{version}
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user