UUlib(3) User Contributed Perl Documentation UUlib(3)
NAME
Convert::UUlib - Perl interface to the uulib library (a.k.a.
uudeview/uuenview).
SYNOPSIS
use Convert::UUlib ':all';
# read all the files named on the commandline and decode them
# 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 & FILEOK) {
$uu->decode;
print $uu->filename, "\n";
}
}
DESCRIPTION
Read the file doc/library.pdf from the distribution for in-depth
information about the C-library used in this interface, and the rest of
this document and especially the non-trivial decoder program at the
end.
EEXXPPOORRTTEEDD CCOONNSSTTAANNTTSS
AAccttiioonn ccooddee ccoonnssttaannttss
ACTIDLE we don't do anything
ACTSCANNING scanning an input file
ACTDECODING decoding into a temp file
ACTCOPYING copying temp to target
ACTENCODING encoding a file
MMeessssaaggee sseevveerriittyy lleevveellss
MSGMESSAGE just a message, nothing important
MSGNOTE something that should be noticed
MSGWARNING important msg, processing continues
MSGERROR processing has been terminated
MSGFATAL decoder cannot process further requests
MSGPANIC recovery impossible, app must terminate
Options
OPTVERSION version number MAJOR.MINORplPATCH (ro)
OPTFAST assumes only one part per file
OPTDUMBNESS switch off the program's intelligence
OPTBRACKPOL give numbers in [] higher precendence
OPTVERBOSE generate informative messages
OPTDESPERATE try to decode incomplete files
OPTIGNREPLY ignore RE:plies (off by default)
OPTOVERWRITE whether it's OK to overwrite ex. files
OPTSAVEPATH prefix to save-files on disk
OPTIGNMODE ignore the original file mode
OPTDEBUG print messages with FILE/LINE info
OPTERRNO get last error code for RETIOERR (ro)
OPTPROGRESS retrieve progress information
OPTUSETEXT handle text messages
OPTPREAMB handle Mime preambles/epilogues
OPTTINYB64 detect short B64 outside of Mime
OPTENCEXT extension for single-part encoded files
OPTREMOVE remove input files after decoding (dangerous)
OPTMOREMIME strict MIME adherence
OPTDOTDOT ".."-unescaping has not yet been done on input files
OPTRBUF set default read I/O buffer size in bytes *EXPERIMENTAL*
OPTWBUF set default write I/O buffer size in bytes *EXPERIMENTAL*
RReessuulltt//EErrrroorr ccooddeess
RETOK everything went fine
RETIOERR I/O Error - examine errno
RETNOMEM not enough memory
RETILLVAL illegal value for operation
RETNODATA decoder didn't find any data
RETNOEND encoded data wasn't ended properly
RETUNSUP unsupported function (encoding)
RETEXISTS file exists (decoding)
RETCONT continue - special from ScanPart
RETCANCEL operation canceled
FFiillee SSttaatteess
This code is zero, i.e. "false":
UUFILEREAD Read in, but not further processed
The following state codes are or'ed together:
FILEMISPART Missing Part(s) detected
FILENOBEGIN No 'begin' found
FILENOEND No 'end' found
FILENODATA File does not contain valid uudata
FILEOK All Parts found, ready to decode
FILEERROR Error while decoding
FILEDECODED Successfully decoded
FILETMPFILE Temporary decoded file exists
EEnnccooddiinngg ttyyppeess
UUENCODED UUencoded data
B64ENCODED Mime-Base64 data
XXENCODED XXencoded data
BHENCODED Binhex encoded
PTENCODED Plain-Text encoded (MIME)
QPENCODED Quoted-Printable (MIME)
YENCENCODED yEnc encoded (non-MIME)
EEXXPPOORRTTEEDD FFUUNNCCTTIIOONNSS
IInniittiiaalliizziinngg aanndd cclleeaannuupp
Initialize is automatically called when the module is loaded and
allocates 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.
Initialize
Not normally necessary, (re-)initializes the library.
CleanUp
Not normally necessary, could be called at the end to release
memory before starting a new decoding round.
SSeettttiinngg aanndd qquueerryyiinngg ooppttiioonnss
$option = GetOption OPTxxx
SetOption OPTxxx, opt-value
See the "OPTxxx" constants above to see which options exist.
SSeettttiinngg vvaarriioouuss ccaallllbbaacckkss
SetMsgCallback [callback-function]
SetBusyCallback [callback-function]
SetFileCallback [callback-function]
SetFNameFilter [callback-function]
CCaallll tthhee ccuurrrreennttllyy sseelleecctteedd FFNNaammeeFFiilltteerr
$file = FNameFilter $file
LLooaaddiinngg ssoouurrcceeffiilleess,, ooppttiioonnaallllyy ffuuzzzzyy mmeerrggee aanndd ssttaarrtt ddeeccooddiinngg
($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 $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
"SetFNameFilter" functionality.
$retval = Smerge $pass
If you are desperate, try to call "Smerge" with increasing $pass
values, beginning at 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 = GetFileListItem $itemnumber
Return the $item structure for the $itemnumber'th found file, or
"undef" of no file with that number exists.
The first file has number 0, and the series has no holes, so you
can iterate over all files by starting with zero and incrementing
until you hit "undef".
DDeeccooddiinngg ffiilleess
$retval = $item->rename($newname)
Change the ondisk filename where the decoded file will be saved.
$retval = $item->decodetemp
Decode the file into a temporary location, use "$item->infile" to
retrieve the temporary filename.
$retval = $item->removetemp
Remove the temporarily decoded file again.
$retval = $item->decode([$targetpath])
Decode the file to it's destination, or the given target path.
$retval = $item->info(callback-function)
QQuueerryyiinngg ((aanndd sseettttiinngg)) iitteemm aattttrriibbuutteess
$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
IInnffoorrmmaattiioonn aabboouutt ssoouurrccee ppaarrttss
$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 "sfname" and possibly the
"partno" and "filename" members.
FFuunnccttiioonnss bbeellooww nnoott ddooccuummeenntteedd aanndd nnoott vveerryy wweellll tteesstteedd
QuickDecode
EncodeMulti
EncodePartial
EncodeToStream
EncodeToFile
EPrepSingle
EPrepPartial
EEXXTTEENNSSIIOONN FFUUNNCCTTIIOONNSS
Functions found in this module but not documented in the uulib
documentation:
$msg = straction ACTxxx
Return a human readable string representing the given action code.
$msg = strerror RETxxx
Return a human readable string representing the given error code.
$str = strencoding xxxENCODED
Return the name of the encoding type as a string.
$str = strmsglevel MSGxxx
Returns the message level as a string.
SetFileNameCallback $cb
Sets (or queries) the FileNameCallback, which is called whenever
the decoding library can't find a filename and wants to extract a
filename from the subject line of a posting. The callback will be
called with two arguments, the subject line and the current
candidate for the filename. The latter argument can be "undef",
which means that no filename could be found (and likely no one
exists, so it is safe to also return "undef" in this case). If it
doesn't return anything (not even "undef"!), then nothing happens,
so this is a no-op callback:
sub cb {
return ();
}
If it returns "undef", then this indicates that no filename could
be found. In all other cases, the return value is taken to be the
filename.
This is a slightly more useful callback:
sub cb {
return unless $[1]; # skip "Re:"-plies et al.
my ($subject, $filename) = @;
# if we find some *.rar, take it
return $1 if $subject =~ /(\w+\.rar)/;
# otherwise just pass what we have
return ();
}
LLAARRGGEE EEXXAAMMPPLLEE DDEECCOODDEERR
This is the file "example-decoder" from the distribution, put here
instead of more thorough documentation.
# decode all the files in the directory uusrc/ and copy
# the resulting files to uudst/
use Convert::UUlib ':all';
sub namefilter {
my($path)=@;
$path=~s/^.*[\/\\]//;
$path;
}
sub busycb {
my ($action, $curfile, $partno, $numparts, $percent, $fsize) = @;
$[0]=straction($action);
print "busycallback(", (join ",",@), ")\n";
0;
}
SetOption OPTIGNMODE, 1;
SetOption OPTVERBOSE, 1;
# show the three ways you can set callback functions. I normally
# prefer the one with the sub inplace.
SetFNameFilter \&namefilter;
SetBusyCallback "busycb", 333;
SetMsgCallback sub {
my ($msg, $level) = @;
print uc strmsglevel $[1], ": $msg\n";
};
# the following non-trivial FileNameCallback takes care
# of some subject lines not detected properly by uulib:
SetFileNameCallback sub {
return unless $[1]; # skip "Re:"-plies et al.
local $ = $[0];
# the following rules are rather effective on some newsgroups,
# like alt.binaries.games.anime, where non-mime, uuencoded data
# is very common
# if we find some *.rar, take it as the filename
return $1 if /(\S{3,}\.(?:[rstuvwxyz]\d\d|rar))\s/i;
# one common subject format
return $1 if /- "(.{2,}?\..+?)" (?:yenc )?\(\d+\/\d+\)/i;
# - filename.par (04/55)
return $1 if /- "?(\S{3,}\.\S+?)"? (?:yenc )?\(\d+\/\d+\)/i;
# - (xxx) No. 1 sayuri81.jpg 756565 bytes
# - (20 files) No.17 Roseanne.jpg [2/2]
return $1 if /No\.[ 0-9]+ (\S+\....) (?:\d+ bytes )?\[/;
# otherwise just pass what we have
return ();
};
# now read all files in the directory uusrc/*
for() {
my($retval,$count)=LoadFile ($, $, 1);
print "file($), status(", strerror $retval, ") parts($count)\n";
}
SetOption OPTSAVEPATH, "uudst/";
# now wade through all files and their source parts
$i = 0;
while ($uu = GetFileListItem($i)) {
$i++;
print "file nr. $i";
print " state ", $uu->state;
print " mode ", $uu->mode;
print " uudet ", strencoding $uu->uudet;
print " size ", $uu->size;
print " filename ", $uu->filename;
print " subfname ", $uu->subfname;
print " mimeid ", $uu->mimeid;
print " mimetype ", $uu->mimetype;
print "\n";
# print additional info about all parts
for ($uu->parts) {
while (my ($k, $v) = each %$) {
print "$k > $v, ";
}
print "\n";
}
$uu->decodetemp;
print " temporarily decoded to ", $uu->binfile, "\n";
$uu->removetemp;
print strerror $uu->decode;
print " saved as uudst/", $uu->filename, "\n";
}
print "cleanup...\n";
CleanUp();
AUTHOR Marc Lehmann , the original uulib library was
written by Frank Pilhofer , and later
heavily bugfixed by Marc Lehmann.
SEE ALSO
perl(1), uudeview homepage at
http://www.uni-frankfurt.de/~fp/uudeview/.
perl v5.8.8 2005-05-02 UUlib(3)