NAME
Convert::yEnc - yEnc decoder
SYNOPSIS
use Convert::yEnc;
$yEnc = new Convert::yEnc RC => $rcFile,
out => $outDir,
tmp => $tmpDir;
$yEnc->out_dir($dir);
$yEnc->tmp_dir($dir);
$ok = $yEnc->decode(\*FILE);
$ok = $yEnc->decode( $file);
$decoder = $yEnc->decoder;
$rc = $yEnc->RC;
undef $yEnc; # saves the Convert::yEnc::RC database to disk
package My::Decoder;
use base qw(Convert::yEnc);
sub mkpath
{
my($yEnc, $dir, $name) = @_;
"$dir/$name"
}
ABSTRACT
yEnc decoder, with database of file parts
DESCRIPTION
Convert::yEnc
decodes yEncoded files and writes them to disk. File parts are saved to $tmpDir; when all parts of a file have been received, the completed file is moved to $outDir.
Convert::yEnc
maintains a database of partially received files, called the RC database. The RC database is loaded from disk when a Convert::yEnc
object is created, and saved to disk when the object is DESTROY
'd.
Exports
Nothing.
Methods
- $yEnc =
new
Convert::yEnc
RC
=> $rcFile,out
=> $outDir,tmp
=> $tmpDir -
Creates and returns a new
Convert::yEnc
object. $rcFile contains the RC database. $outDir is the output directory, and $tmpDir is the temporary directory,If the
RC
parameter is omitted, it defaults to $ENV{HOME}/.yencrc. If theout
parameter is omitted, it defaults to the current working directory. If thetmp
parameter is omitted, it defaults to theout
parameter. - $yEnc->
out_dir
($dir) -
Sets the output directory to $dir
- $yEnc->
tmp_dir
($dir) -
Sets the temporary directory to $dir
- $ok = $yEnc->
decode
($file) - $ok = $yEnc->
decode
(\*FILE) -
Decodes a yEncoded file and writes it to the
tmp
directory. If the file is complete, moves it to theout
directory and drops the entry for the file from the RC database.The first form reads the file named $file. The second form reads the file handle FILE.
In scalar context, returns true on success. In list context, returns
($ok, $err)
where $ok is true on success, and $err is an error message.
- $rc = $yEnc->
RC
-
Returns the
Convert::yEnc::RC
object that holds the RC database for $yEnc. Applications can use the returned value to query or manipulate the RC database directly. DESTROY
-
Convert::yEnc::RC
has a destructor. The destructor writes the RC database back to the file from which it was loaded.
Overrides
mkpath
-
Convert::yEnc
callsmkpath
to construct the path to which a completed file is moved. The default implementation ofmkpath
is shown in the "SYNOPSIS".Applications can subclass from
Convert::yEnc
and override this method if they want the completed file to appear somewhere else.If
mkpath
returnsundef
, the completed file is discarded.
NOTES
Destructors don't work reliably at global destruct time
Convert::yEnc
provides a DESTROY
method as a convenience: you can create a yEnc
object, use it, forget about it
my $yEnc = new Convert::yEnc;
$yEnc->decode(...);
and the RC file will automatically be written when the object ref count goes to zero.
Unless the ref count never goes to zero, because, for example, a named closure is holding a reference on the object
sub A { $yEnc }
In this case, the object won't be destructed until global destruct time. Unfortunately, the order in which objects are destructed during global destruction isn't controlled, and if the embedded $yEnc->RC
object is destructed before $yEnc
itself, then $yEnc->DESTROY
won't be able to write the RC file.
To avoid creating closures, pass yEnc
objects as parameters
my $yEnc = new Convert::yEnc;
A($yEnc);
sub A { my $yEnc = shift }
rather than referencing them as globals. To pass a yEnc
object to a File::Find
wanted routine, use an anonymous closure
File::Find::find(sub { A($yEnc) }, $dir)
It isn't always obvious when a closure is created; if you're feeling paranoid, write
$yEnc->RC->save
to save the RC file.
This problem is reported as bug 7853 at http://www.perl.org.
SEE ALSO
AUTHOR
Steven W McDougall, <swmcd@world.std.com>
COPYRIGHT AND LICENSE
Copyright (c) 2002-2008 by Steven McDougall. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.