view release on metacpan or  search on metacpan

lib/File/Takeput.pm  view on Meta::CPAN

sub reset() {
# Change default settings to the original defaults.

    my $nsp = caller;
    $default->{$nsp} = {$default->{'File::Takeput'}->%*};
    1;};


sub set( %set ) {
# Change default settings.

    my $nsp = caller;
    my $s = full_setting(\%set,$default->{$nsp})
      or return errah('set: ',$default->{$nsp});

    $default->{$nsp} = $s;
    1;};

# ------------------------------------------------------------------------- #

=pod

=encoding utf8

=head1 NAME

File::Takeput - Slurp style file IO with locking.

=head1 VERSION

0.30

=head1 SYNOPSIS

    use File::Takeput;

    # Lock some file and read its content.
    my @content1 = take('some_file_name.csv');

    # Read content of some other file.
    # Retry for up to 2.5 seconds if it is already locked.
    my @content2 = grab('some_other_file_name.log' , patience => 2.5);

    # Append some data to that other file.
    append('some_other_file_name.log')->(@some_data);

    # Read content of some third file as a single string.
    my ($content3) = grab('some_third_file_name.html' , separator => undef);

    # Write content back to the first file after editing it.
    # The locks will be released right afterwards.
    $content1[$_] =~ s/,/;/g for (0..$#content1);
    put('some_file_name.csv')->(@content1);

=head1 DESCRIPTION

Slurp style file IO with locking. The purpose of Takeput is to make it pleasant for you to script file IO. Slurp style is both user friendly and very effective if you can have your files in memory.

The other major point of Takeput is locking. Takeput is careful to help your script be a good citizen in a busy filesystem. All its file operations respect and set flock locking.

If your script misses a lock and does not release it, the lock will be released when your script terminates.

Encoding is often part of file IO operations, but Takeput keeps out of that. It reads and writes file content just as strings of bytes, in a sort of line-based binmode. Use some other module if you need decoding and encoding. For example:

    use File::Takeput;
    use Encode;

    my @article = map {decode('iso-8859-1',$_)} grab 'article.latin-1';

=head1 SUBROUTINES AND VARIABLES

Imported by default:
L<append|/append( $filename )-E<gt>( @data )>,
L<grab|/grab( $filename )>,
L<pass|/pass( $filename )>,
L<plunk|/plunk( $filename )-E<gt>( @data )>,
L<put|/put( $filename )-E<gt>( @data )>,
L<take|/take( $filename )>

Imported on demand:
L<fgrab|/fgrab( $filename )>,
L<fpass|/fpass( $filename )>,
L<ftake|/ftake( $filename )>,
L<reset|/reset>,
L<set|/set( %settings )>

=over

=item append( $filename )->( @data )

Appends @data to the $filename file.

=item grab( $filename )

Reads and returns the content of the $filename file. Will never change the content of $filename, or create the file.

Reading an empty file will return a list with one element, the empty string. If a false value is returned instead, it is because "grab" could not read the file.

=item pass( $filename )

Releases the lock on the $filename file.

The content of the file will normally be the same as when the lock was taken with the "take" subroutine. This is useful when a lock was taken, but it later turned out that there was nothing to write to the file.

There are two caveats. If the "create" configuration parameter is true, the file might have been created when it was taken, so it has been changed in that sense. And of course flock locks are only advisory, so other processes can ignore the locks and...

=item plunk( $filename )->( @data )

Overwrites the $filename file with @data.

=item put( $filename )->( @data )

Overwrites the taken $filename file, with @data, and releases the lock on it.

Setting the L<"create" configuration parameter|/create> on this call will not work. Set it on the "take" call instead.

=item take( $filename )

Sets a lock on the $filename file, reads and returns its content.