Convert::yEnc - yEnc decoder
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" }
yEnc decoder, with database of file parts
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.
Nothing.
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 the out
parameter is omitted,
it defaults to the current working directory.
If the tmp
parameter is omitted,
it defaults to the out
parameter.
out_dir
($dir)
tmp_dir
($dir)
decode
($file)
decode
(\*FILE)
Decodes a yEncoded file and writes it to the tmp
directory.
If the file is complete,
moves it to the out
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
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.
mkpath
Convert::yEnc
calls mkpath
to construct the path to which a
completed file is moved.
The default implementation of mkpath
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
returns undef
, the completed file is discarded.
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.
Steven W McDougall, <swmcd@theworld.com>
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.