The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Convert-yEnc-0.04_01
River stage zero No dependents
++
/ Convert::yEnc

NAME

Convert::yEnc - Encode and decode using the yEnc method

SYNOPSIS

  use Convert::yEnc qw(yencode ydecode);

  # yEncode data
  yencode();

  # yDecode data -- NOTE: not yet implemented!
  ydecode();

DO NOT USE THIS DISTRIBUTION!

This code is not ready yet. It does not have any tests yet. It undoubtedly has bugs. It's not intended to be the standard yEnc-in-Perl implementation.

It's provided only so you can have a look at it, really. If it's useful to you, so much the better. If you can make it work, then more power to you (and "patches welcome"). If you want to create your own Convert::yEnc, you're more than welcome to do so -- you can even include code from this, if you want.

I don't know when I'll get around to making it work properly.

DESCRIPTION

yEnc is an encoding method devised by Jürgen Helbing and intended to be suitable for sending data via NNTP, where the datapath is nearly eight-bit-clean but some characters are special. It avoids the overhead involved with "readable" encodings such as MIME Base64 or uuencoding by only escaping a small number of bytes, thus resulting in an overhead of about 1-2% for large files.

EXPORT

None by default.

The subroutines yencode and ydecode are exported if you ask for them explicitly.

yencode

This subroutine enables you to yEncode data so that it is suitable for sending via NNTP.

ydecode

This is not yet implemented. When it is, it will enable you to decode yEncoded data.

AUTHOR

Philip Newton, <pne@cpan.org>

BUGS

  • Decoding is not implemented yet.

  • Multipart files are not yet supported

CAUTION

Beware: this module is still alpha, and especially the interface. The interface can, and most probably will, change, so check the documentation when you upgrade.

For example, I'm not sure how best to do data passing into and out of the function -- mandate passing filehandles? pass in a string and return a string? use callbacks for reading and/or writing? accept multiple possibilities?

Also, I'm not sure what the best way to handle multipart files is. Right now, the caller has to do a fair amount of bookkeeping; I wonder whether it might be a good idea to provide a subroutine which would keep track of things like that itself, and perhaps be passed a number of parts to split into, or a maximum length per part, and deduce the other parameter automatically and call yencode with the appropriate parameters.

Or maybe encapsulate the whole thing inside a stateful object which remembers which parts were already written and at what byte offsets?

Decoding multipart messages where some are missing is also likely to be "interesting".

At the moment, the interface is filehandle-oriented, like the sample C code it is derived from. Suggestions for improvements are welcome.

TODO

  • Implement multi-part files

  • Implement ydecoding

  • Support different ways of presenting data in and out -- filehandle, string data, arrayrefs, ...

  • What if the string =yend appears in the middle of data on decoding? Probably need to do checking on $filelen and/or begin= and end= values. Checking whether the length of the current line is less than the declared line length gets us part of the way, but if the last line happens to be the right length, it doesn't give us any warning. Counting bytes may be safer.

  • Write tests!

FEEDBACK

If you use this module, I'd appreciate it if you dropped me a note so I can see whether anyone uses it at all. Also, if you have any suggestions for improvements (especially if you wish to submit a code patch), feel free to send me email.

SEE ALSO

perl(1), Convert::UU.