From 8b6eff6962c7464ec64526ac438a9f49bfca14a708139a34056f91260754c5d9 Mon Sep 17 00:00:00 2001 From: Stephan Kulow Date: Thu, 31 Mar 2011 18:29:02 +0000 Subject: [PATCH] OBS-URL: https://build.opensuse.org/package/show/devel:languages:perl/perl-File-Slurp?expand=0&rev=14 --- perl-File-Slurp.spec | 261 ------------------------------------------- 1 file changed, 261 deletions(-) diff --git a/perl-File-Slurp.spec b/perl-File-Slurp.spec index 2a5ee4c..0a2e5f9 100644 --- a/perl-File-Slurp.spec +++ b/perl-File-Slurp.spec @@ -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}