--- Convert-UUlib/UUlib.pm 2002/10/13 13:51:00 1.12 +++ Convert-UUlib/UUlib.pm 2006/12/10 16:44:00 1.26 @@ -4,9 +4,8 @@ require Exporter; require DynaLoader; -use AutoLoader; -$VERSION = 0.3; +$VERSION = "1.07"; @ISA = qw(Exporter DynaLoader); @@ -18,6 +17,7 @@ MSG_ERROR MSG_FATAL MSG_MESSAGE MSG_NOTE MSG_PANIC MSG_WARNING + OPT_RBUF OPT_WBUF OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS OPT_ENCEXT OPT_ERRNO OPT_FAST OPT_IGNMODE OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB OPT_PROGRESS OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE @@ -101,9 +101,13 @@ use Convert::UUlib ':all'; # read all the files named on the commandline and decode them - LoadFile($_) for @ARGV; - for($i=0; $uu=GetFileListItem($i); $i++) { - $uu->decode if $uu->state & FILE_OK; + # into the CURRENT directory. See below for a longer example. + LoadFile $_ for @ARGV; + for (my $i = 0; my $uu = GetFileListItem $i; $i++) { + if ($uu->state & FILE_OK) { + $uu->decode; + print $uu->filename, "\n"; + } } =head1 DESCRIPTION @@ -150,9 +154,11 @@ OPT_PREAMB handle Mime preambles/epilogues OPT_TINYB64 detect short B64 outside of Mime OPT_ENCEXT extension for single-part encoded files - OPT_REMOVE remove input files after decoding + OPT_REMOVE remove input files after decoding (dangerous) OPT_MOREMIME strict MIME adherence - OPT_DOTDOT .. unescaping has not yet been done on input files + OPT_DOTDOT ".."-unescaping has not yet been done on input files + OPT_RBUF set default read I/O buffer size in bytes *EXPERIMENTAL* + OPT_WBUF set default write I/O buffer size in bytes *EXPERIMENTAL* =head2 Result/Error codes @@ -173,7 +179,7 @@ UUFILE_READ Read in, but not further processed - The following state codes are ored together: + The following state codes are or'ed together: FILE_MISPART Missing Part(s) detected FILE_NOBEGIN No 'begin' found @@ -199,56 +205,167 @@ =head2 Initializing and cleanup Initialize is automatically called when the module is loaded and allocates -quite a bit of memory. CleanUp releases that again. +quite a small amount of memory for todays machines ;) CleanUp releases that +again. + +On my machine, a fairly complete decode with DBI backend needs about 10MB +RSS to decode 20000 files. + +=over 4 + +=item Initialize - Initialize; # not normally necessary - CleanUp; # could be called at the end to release memory +Not normally necessary, (re-)initializes the library. + +=item CleanUp + +Not normally necessary, could be called at the end to release memory +before starting a new decoding round. + +=back =head2 Setting and querying options - $option = GetOption OPT_xxx; - SetOption OPT_xxx, opt-value; +=over 4 + +=item $option = GetOption OPT_xxx + +=item SetOption OPT_xxx, opt-value + +=back + +See the C constants above to see which options exist. =head2 Setting various callbacks - SetMsgCallback [callback-function]; - SetBusyCallback [callback-function]; - SetFileCallback [callback-function]; - SetFNameFilter [callback-function]; +=over 4 + +=item SetMsgCallback [callback-function] + +=item SetBusyCallback [callback-function] + +=item SetFileCallback [callback-function] + +=item SetFNameFilter [callback-function] + +=back =head2 Call the currently selected FNameFilter - $file = FNameFilter $file; +=over 4 + +=item $file = FNameFilter $file + +=back =head2 Loading sourcefiles, optionally fuzzy merge and start decoding - ($retval, $count) = LoadFile $fname, [$id, [$delflag]]; - $retval = Smerge $pass; - $item = GetFileListItem $item_number; - -=head2 The procedural interface is undocumented, use the following methods instead - - $retval = $item->rename($newname); - $retval = $item->decode_temp; - $retval = $item->remove_temp; - $retval = $item->decode([$target_path]); - $retval = $item->info(callback-function); +=over 4 + +=item ($retval, $count) = LoadFile $fname, [$id, [$delflag, [$partno]]] + +Load the given file and scan it for encoded contents. Optionally tag it +with the given id, and if C<$delflag> is true, delete the file after it +is no longer necessary. If you are certain of the part number, you can +specify it as the last argument. + +A better (usually faster) way of doing this is using the C +functionality. + +=item $retval = Smerge $pass + +If you are desperate, try to call C with increasing C<$pass> +values, beginning at C<0>, to try to merge parts that usually would not +have been merged. + +Most probably this will result in garbled files, so never do this by +default. + +=item $item = GetFileListItem $item_number + +Return the C<$item> structure for the C<$item_number>'th found file, or +C of no file with that number exists. + +The first file has number C<0>, and the series has no holes, so you can +iterate over all files by starting with zero and incrementing until you +hit C. + +=back + +=head2 Decoding files + +=over 4 + +=item $retval = $item->rename($newname) + +Change the ondisk filename where the decoded file will be saved. + +=item $retval = $item->decode_temp + +Decode the file into a temporary location, use C<< $item->infile >> to +retrieve the temporary filename. + +=item $retval = $item->remove_temp + +Remove the temporarily decoded file again. + +=item $retval = $item->decode([$target_path]) + +Decode the file to it's destination, or the given target path. + +=item $retval = $item->info(callback-function) + +=back =head2 Querying (and setting) item attributes - $state = $item->state; - $mode = $item->mode([newmode]); - $uudet = $item->uudet; - $size = $item->size; - $filename = $item->filename([newfilename}); - $subfname = $item->subfname; - $mimeid = $item->mimeid; - $mimetype = $item->mimetype; - $binfile = $item->binfile; +=over 4 + +=item $state = $item->state -=head2 Totally undocumented but well tested ;) +=item $mode = $item->mode([newmode]) - $parts = $item->parts; +=item $uudet = $item->uudet + +=item $size = $item->size + +=item $filename = $item->filename([newfilename}) + +=item $subfname = $item->subfname + +=item $mimeid = $item->mimeid + +=item $mimetype = $item->mimetype + +=item $binfile = $item->binfile + +=back + +=head2 Information about source parts + +=over 4 + +=item $parts = $item->parts + +Return information about all parts (source files) used to decode the file +as a list of hashrefs with the following structure: + + { + partno => , + # the following member sonly exist when they contain useful information + sfname => , + filename => , + subfname => , + subject => , + origin => , + mimetype => , + mimeid => , + } + +Usually you are interested mostly the C and possibly the C +and C members. + +=back =head2 Functions below not documented and not very well tested @@ -422,7 +539,7 @@ =head1 AUTHOR -Marc Lehmann , the original uulib library was written +Marc Lehmann , the original uulib library was written by Frank Pilhofer , and later heavily bugfixed by Marc Lehmann.