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

A line for a multi-part file has 4 fields

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
Returns a list of all the files in the database.
@complete = $rc->complete
Returns a list of all the files in the database that are complete.
$complete = $rc->complete($fileName)
Returns true iff all parts of ($fileName) have been received.
$entry = $rc->entry($fileName)

Returns the database entry for $fileName. $entry is a Convert::yEnc::Entry object.

If $fileName is not in the database, return undef.

$ok = $rc->drop($fileName)

Deletes the entry for $fileName from the database.

If $fileName is not in the database, return false.

$rc->save

Writes the contents of $newsrc back to the file from which it was loaded.

save dies if there is an error writing the file.

$newsrc->save($file)

Writes the contents of $newsrc to $file. Subsequent calls to save() will write to $file.

save dies if there is an error writing the file.

BUGS

item *

The database doesn't persist the yEnc 1.2 "total" field to disk.

SEE ALSO

AUTHOR

Steven W McDougall, <swmcd@world.std.com>

COPYRIGHT AND LICENSE

Copyright (c) 2002-2004 by Steven McDougall. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.