NAME

Convert::yEnc::RC - yEnc file-part database

SYNOPSIS

  use Convert::yEnc::RC;


              $rc = new Convert::yEnc::RC;
              $rc = new Convert::yEnc::RC $file;


  $ok       = $rc->load;
  $ok       = $rc->load($file);


  $ok       = $rc->update  ($line);
  @files    = $rc->files;
  @complete = $rc->complete;
  $complete = $rc->complete($fileName);
  $entry    = $rc->entry   ($fileName);
  $ok       = $rc->drop    ($fileName);


              $rc->save;
              $rc->save($file);

ABSTRACT

yEnc file-part database

DESCRIPTION

A Convert::yEnc::RC object manages a database of yEnc file parts.

Applications pass the =ybegin, =ypart, and =yend lines from yEncoded files to the object, and it keeps track of the files, parts and bytes as they are received. The object reports errors if the sequence of =y lines is inconsistent.

Applications can query the object to find out what files, parts, and bytes have been received, and whether a given file is complete.

The database can be be saved to and restored from disk.

Database format

The database is stored on disk as a flat ASCII file. There is one line in the database for each yEncoded file.

A line for a single-part file has 3 fields

the file name
the file size
the number of bytes received

A line for a multi-part file has 4 fields

the file name
the file size
a Set::IntSpan run list showing which bytes of the file have been recieved
a Set::IntSpan run list showing which parts of the file have been recieved

Fields are tab-delimited, so that file names may contain whitespace.

Example

    a.jpg       20000   20000
    b.jpg       10000   1-5000  1

Exports

Nothing.

Methods

$rc = new Convert::yEnc::RC

$rc = new Convert::yEnc::RC $file

Creates and returns a new Convert::yEnc::RC object.

If $file is supplied, initializes the database from $file.

If $file is not supplied, or doesn't exist, initializes the database to empty.

$ok = $rc->load($file)

Loads the database in $file into $rc. Any existing data in $rc is discarded. Returns true on success.

If $file can't be opened, load does nothing and returns false.

If $file contains invalid lines, load dies. When this happens, the state of $rc is undefined.

$ok = $rc->update($line)

Updates $rc according to the contents of $line. $line should be a header (=begin), trailer (=end), or part (=part) line from a yEncoded file.

Returns true iff $line is well-formed and consistent with the current state of the database.

@files = $rc->files