package FileCache;
-our $VERSION = 1.03;
+our $VERSION = '1.08';
=head1 NAME
=head1 SYNOPSIS
+ no strict 'refs';
+
use FileCache;
# or
use FileCache maxopen => 16;
namely; C<< '>' >>, C<< '+>' >>, C<< '<' >>, C<< '<+' >>, C<<< '>>' >>>,
C< '|-' > and C< '-|' >
+To pass supplemental arguments to a program opened with C< '|-' > or C< '-|' >
+append them to the command string as you would system EXPR.
+
Returns EXPR on success for convenience. You may neglect the
return value and manipulate EXPR as the filehandle directly if you prefer.
+=back
+
=head1 CAVEATS
While it is permissible to C<close> a FileCache managed file,
than which it was imported, or with another module which overrides C<close>.
If you must, use C<FileCache::cacheout_close>.
+Although FileCache can be used with piped opens ('-|' or '|-') doing so is
+strongly discouraged. If FileCache finds it necessary to close and then reopen
+a pipe, the command at the far end of the pipe will be reexecuted - the results
+of performing IO on FileCache'd pipes is unlikely to be what you expect. The
+ability to use FileCache on pipes may be removed in a future release.
+
+FileCache does not store the current file offset if it finds it necessary to
+close a file. When the file is reopened, the offset will be as specified by the
+original C<open> file mode. This could be construed to be a bug.
+
+The module functionality relies on symbolic references, so things will break
+under 'use strict' unless 'no strict "refs"' is also specified.
+
=head1 BUGS
F<sys/param.h> lies with its C<NOFILE> define on some systems,
so you may have to set I<maxopen> yourself.
-=head1 NOTES
-
-FileCache installs signal handlers for CHLD (a.k.a. CLD) and PIPE in the
-calling package to handle deceased children from 2-arg C<cacheout> with C<'|-'>
-or C<'-|'> I<expediently>. The children would otherwise be reaped eventually,
-unless you terminated before repeatedly calling cacheout.
-
=cut
require 5.006;
use Carp;
use strict;
no strict 'refs';
+
# These are not C<my> for legacy reasons.
# Previous versions requested the user set $cacheout_maxopen by hand.
# Some authors fiddled with %saw to overcome the clobber on initial open.
use vars qw(%saw $cacheout_maxopen);
+$cacheout_maxopen = 16;
+
+use base 'Exporter';
+our @EXPORT = qw[cacheout cacheout_close];
+
+
my %isopen;
my $cacheout_seq = 0;
sub import {
my ($pkg,%args) = @_;
- $pkg = caller(1);
- *{$pkg.'::cacheout'} = \&cacheout;
- *{$pkg.'::close'} = \&cacheout_close;
- # Reap our children
- @{"$pkg\::SIG"}{'CLD', 'CHLD', 'PIPE'} = ('IGNORE')x3;
+ # Use Exporter. %args are for us, not Exporter.
+ # Make sure to up export_to_level, or we will import into ourselves,
+ # rather than our calling package;
+
+ __PACKAGE__->export_to_level(1);
+ Exporter::import( $pkg );
# Truth is okay here because setting maxopen to 0 would be bad
return $cacheout_maxopen = $args{maxopen} if $args{maxopen};
+
+ # XXX This code is crazy. Why is it a one element foreach loop?
+ # Why is it using $param both as a filename and filehandle?
foreach my $param ( '/usr/include/sys/param.h' ){
if (open($param, '<', $param)) {
local ($_, $.);
sub cacheout_close {
# Short-circuit in case the filehandle disappeared
my $pkg = caller($_[1]||0);
- fileno(*{$pkg . '::' . $_[0]}) &&
+ defined fileno(*{$pkg . '::' . $_[0]}) &&
CORE::close(*{$pkg . '::' . $_[0]});
delete $isopen{$_[0]};
}
($file, $mode) = ($mode, $file) if $narg == 1;
croak "Invalid mode for cacheout" if $mode &&
( $mode !~ /^\s*(?:>>|\+?>|\+?<|\|\-|)|\-\|\s*$/ );
-
+
# Mode changed?
- if( $isopen{$file} && ($mode||'>') ne $isopen{$file}->[2] ){
+ if( $isopen{$file} && ($mode||'>') ne $isopen{$file}->[1] ){
&cacheout_close($file, 1);
}
-
+
if( $isopen{$file}) {
$ret = $file;
$isopen{$file}->[0]++;
}
#XXX should we just return the value from cacheout_open, no croak?
$ret = cacheout_open($mode, $file) or croak("Can't create $file: $!");
-
+
$isopen{$file} = [++$cacheout_seq, $mode];
}
return $ret;