/ 
Convert-yEnc-1.03
River stage zero No dependents
/ Convert::yEnc

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 $HOME{ENV}/.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.

$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 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 = $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 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.

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.