| 1 |
package Convert::UUlib; |
| 2 |
|
| 3 |
use Carp; |
| 4 |
|
| 5 |
require Exporter; |
| 6 |
require DynaLoader; |
| 7 |
use AutoLoader; |
| 8 |
|
| 9 |
$VERSION = 0.213; |
| 10 |
|
| 11 |
@ISA = qw(Exporter DynaLoader); |
| 12 |
|
| 13 |
@_consts = qw( |
| 14 |
ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING |
| 15 |
|
| 16 |
FILE_DECODED FILE_ERROR FILE_MISPART FILE_NOBEGIN FILE_NODATA |
| 17 |
FILE_NOEND FILE_OK FILE_READ FILE_TMPFILE |
| 18 |
|
| 19 |
MSG_ERROR MSG_FATAL MSG_MESSAGE MSG_NOTE MSG_PANIC MSG_WARNING |
| 20 |
|
| 21 |
OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS OPT_ENCEXT |
| 22 |
OPT_ERRNO OPT_FAST OPT_IGNMODE OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB |
| 23 |
OPT_PROGRESS OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE |
| 24 |
OPT_VERSION OPT_REMOVE OPT_MOREMIME OPT_DOTDOT |
| 25 |
|
| 26 |
RET_CANCEL RET_CONT RET_EXISTS RET_ILLVAL RET_IOERR RET_NODATA |
| 27 |
RET_NOEND RET_NOMEM RET_OK RET_UNSUP |
| 28 |
|
| 29 |
B64ENCODED BH_ENCODED PT_ENCODED QP_ENCODED |
| 30 |
XX_ENCODED UU_ENCODED YENC_ENCODED |
| 31 |
); |
| 32 |
|
| 33 |
@_funcs = qw( |
| 34 |
Initialize CleanUp GetOption SetOption strerror SetMsgCallback |
| 35 |
SetBusyCallback SetFileCallback SetFNameFilter SetFileNameCallback |
| 36 |
FNameFilter LoadFile GetFileListItem RenameFile DecodeToTemp |
| 37 |
RemoveTemp DecodeFile InfoFile Smerge QuickDecode EncodeMulti |
| 38 |
EncodePartial EncodeToStream EncodeToFile E_PrepSingle |
| 39 |
E_PrepPartial |
| 40 |
|
| 41 |
straction strencoding strmsglevel |
| 42 |
); |
| 43 |
|
| 44 |
@EXPORT = @_consts; |
| 45 |
@EXPORT_OK = @_funcs; |
| 46 |
%EXPORT_TAGS = (all => [@_consts,@_funcs], constants => \@_consts); |
| 47 |
|
| 48 |
bootstrap Convert::UUlib $VERSION; |
| 49 |
|
| 50 |
Initialize(); |
| 51 |
|
| 52 |
# not when < 5.005_6x |
| 53 |
# END { CleanUp() } |
| 54 |
|
| 55 |
for (@_consts) { |
| 56 |
my $constant = constant($_); |
| 57 |
*$_ = sub () { $constant }; |
| 58 |
} |
| 59 |
|
| 60 |
# action code -> string mapping |
| 61 |
sub straction($) { |
| 62 |
return 'copying' if $_[0] == &ACT_COPYING; |
| 63 |
return 'decoding' if $_[0] == &ACT_DECODING; |
| 64 |
return 'encoding' if $_[0] == &ACT_ENCODING; |
| 65 |
return 'idle' if $_[0] == &ACT_IDLE; |
| 66 |
return 'scanning' if $_[0] == &ACT_SCANNING; |
| 67 |
'unknown'; |
| 68 |
} |
| 69 |
|
| 70 |
# encoding type -> string mapping |
| 71 |
sub strencoding($) { |
| 72 |
return 'uuencode' if $_[0] == &UU_ENCODED; |
| 73 |
return 'base64' if $_[0] == &B64ENCODED; |
| 74 |
return 'yenc' if $_[0] == &YENC_ENCODED; |
| 75 |
return 'binhex' if $_[0] == &BH_ENCODED; |
| 76 |
return 'plaintext' if $_[0] == &PT_ENCODED; |
| 77 |
return 'quoted-printable' if $_[0] == &QP_ENCODED; |
| 78 |
return 'xxencode' if $_[0] == &XX_ENCODED; |
| 79 |
'unknown'; |
| 80 |
} |
| 81 |
|
| 82 |
sub strmsglevel($) { |
| 83 |
return 'message' if $_[0] == &MSG_MESSAGE; |
| 84 |
return 'note' if $_[0] == &MSG_NOTE; |
| 85 |
return 'warning' if $_[0] == &MSG_WARNING; |
| 86 |
return 'error' if $_[0] == &MSG_ERROR; |
| 87 |
return 'panic' if $_[0] == &MSG_PANIC; |
| 88 |
return 'fatal' if $_[0] == &MSG_FATAL; |
| 89 |
'unknown'; |
| 90 |
} |
| 91 |
|
| 92 |
1; |
| 93 |
__END__ |
| 94 |
|
| 95 |
=head1 NAME |
| 96 |
|
| 97 |
Convert::UUlib - Perl interface to the uulib library (a.k.a. uudeview/uuenview). |
| 98 |
|
| 99 |
=head1 SYNOPSIS |
| 100 |
|
| 101 |
use Convert::UUlib; |
| 102 |
|
| 103 |
=head1 DESCRIPTION |
| 104 |
|
| 105 |
Read the file uulibdoc.dvi.gz and the example-decoder source. Sorry - more |
| 106 |
to come once people use me ;) |
| 107 |
|
| 108 |
=head1 SMALL EXAMPLE DECODER |
| 109 |
|
| 110 |
The following code excerpt is a minimal decoder program. It reads all |
| 111 |
files given on the commandline and decodes any files in it. |
| 112 |
|
| 113 |
use Convert::UUlib ':all'; |
| 114 |
|
| 115 |
LoadFile($_) for @ARGV; |
| 116 |
|
| 117 |
for($i=0; $uu=GetFileListItem($i); $i++) { |
| 118 |
$uu->decode if $uu->state & FILE_OK; |
| 119 |
} |
| 120 |
|
| 121 |
=head1 LARGE EXAMPLE DECODER |
| 122 |
|
| 123 |
This is the file C<example-decoder> from the distribution, put here |
| 124 |
instead of more thorough documentation. |
| 125 |
|
| 126 |
# decode all the files in the directory uusrc/ and copy |
| 127 |
# the resulting files to uudst/ |
| 128 |
|
| 129 |
use Convert::UUlib ':all'; |
| 130 |
|
| 131 |
sub namefilter { |
| 132 |
my($path)=@_; |
| 133 |
$path=~s/^.*[\/\\]//; |
| 134 |
$path; |
| 135 |
} |
| 136 |
|
| 137 |
sub busycb { |
| 138 |
my($action,$curfile,$partno,$numparts,$percent,$fsize)=@_; |
| 139 |
$_[0]=straction($action); |
| 140 |
print "busy_callback(",join(",",@_),")\n"; |
| 141 |
0; |
| 142 |
} |
| 143 |
|
| 144 |
SetOption (OPT_IGNMODE, 1); |
| 145 |
SetOption (OPT_VERBOSE, 1); |
| 146 |
|
| 147 |
# show the three ways you can set callback functions |
| 148 |
SetFNameFilter (\&namefilter); |
| 149 |
|
| 150 |
SetBusyCallback ("busycb",333); |
| 151 |
|
| 152 |
SetMsgCallback (sub { |
| 153 |
my($msg,$level)=@_; |
| 154 |
print uc(strmsglevel($_[1])),": $msg\n"; |
| 155 |
}); |
| 156 |
|
| 157 |
for(<uusrc/*>) { |
| 158 |
my($retval,$count)=LoadFile ($_,$_,1); |
| 159 |
print "file($_), status(",strerror($retval),") parts($count)\n"; |
| 160 |
} |
| 161 |
|
| 162 |
SetOption (OPT_SAVEPATH, "uudst/"); |
| 163 |
|
| 164 |
$i=0; |
| 165 |
while($uu=GetFileListItem($i)) { |
| 166 |
$i++; |
| 167 |
print "file nr. $i"; |
| 168 |
print " state ",$uu->state; |
| 169 |
print " mode ",$uu->mode; |
| 170 |
print " uudet ",strencoding($uu->uudet); |
| 171 |
print " size ",$uu->size; |
| 172 |
print " filename ",$uu->filename; |
| 173 |
print " subfname ",$uu->subfname; |
| 174 |
print " mimeid ",$uu->mimeid; |
| 175 |
print " mimetype ",$uu->mimetype; |
| 176 |
print "\n"; |
| 177 |
|
| 178 |
# print additional info about all parts |
| 179 |
for($uu->parts) { |
| 180 |
while(my($k,$v)=each(%$_)) { |
| 181 |
print "$k > $v, "; |
| 182 |
} |
| 183 |
print "\n"; |
| 184 |
} |
| 185 |
|
| 186 |
$uu->decode_temp; |
| 187 |
print " temporarily decoded to ",$uu->binfile,"\n"; |
| 188 |
$uu->remove_temp; |
| 189 |
|
| 190 |
print strerror($uu->decode); |
| 191 |
print " saved as uudst/",$uu->filename,"\n"; |
| 192 |
} |
| 193 |
|
| 194 |
print "cleanup...\n"; |
| 195 |
|
| 196 |
CleanUp(); |
| 197 |
|
| 198 |
=head1 Exported constants |
| 199 |
|
| 200 |
Action code constants: |
| 201 |
|
| 202 |
ACT_COPYING ACT_DECODING ACT_ENCODING |
| 203 |
ACT_IDLE ACT_SCANNING |
| 204 |
|
| 205 |
File status flags: |
| 206 |
|
| 207 |
FILE_DECODED FILE_ERROR FILE_MISPART |
| 208 |
FILE_NOBEGIN FILE_NODATA FILE_NOEND |
| 209 |
FILE_OK FILE_READ FILE_TMPFILE |
| 210 |
|
| 211 |
Message severity levels: |
| 212 |
|
| 213 |
MSG_ERROR MSG_FATAL MSG_MESSAGE |
| 214 |
MSG_NOTE MSG_PANIC MSG_WARNING |
| 215 |
|
| 216 |
Options: |
| 217 |
|
| 218 |
OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS |
| 219 |
OPT_ENCEXT OPT_ERRNO OPT_FAST OPT_IGNMODE |
| 220 |
OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB OPT_PROGRESS |
| 221 |
OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE |
| 222 |
OPT_VERSION OPT_REMOVE OPT_MOREMIME |
| 223 |
|
| 224 |
Error/Result codes: |
| 225 |
|
| 226 |
RET_CANCEL RET_CONT RET_EXISTS RET_ILLVAL RET_IOERR |
| 227 |
RET_NODATA RET_NOEND RET_NOMEM RET_OK RET_UNSUP |
| 228 |
|
| 229 |
Encoding types: |
| 230 |
|
| 231 |
B64ENCODED BH_ENCODED PT_ENCODED QP_ENCODED XX_ENCODED |
| 232 |
UU_ENCODED YENC_ENCODED |
| 233 |
|
| 234 |
=head1 Exported functions |
| 235 |
|
| 236 |
Initializing and cleanup (Initialize is automatically called when the |
| 237 |
module is loaded and allocates quite a bit of memory. CleanUp releases |
| 238 |
that again). |
| 239 |
|
| 240 |
Initialize; # not normally necessary |
| 241 |
CleanUp; # could be called at the end to release memory |
| 242 |
|
| 243 |
Setting and querying options: |
| 244 |
|
| 245 |
$option = GetOption OPT_xxx; |
| 246 |
SetOption OPT_xxx, opt-value; |
| 247 |
|
| 248 |
Error and action values => stringified: |
| 249 |
|
| 250 |
$msg = straction ACT_xxx; |
| 251 |
$msg = strerror RET_xxx; |
| 252 |
|
| 253 |
Setting various callbacks: |
| 254 |
|
| 255 |
SetMsgCallback [callback-function]; |
| 256 |
SetBusyCallback [callback-function]; |
| 257 |
SetFileCallback [callback-function]; |
| 258 |
SetFNameFilter [callback-function]; |
| 259 |
|
| 260 |
Call the currently selected FNameFilter: |
| 261 |
|
| 262 |
$file = FNameFilter $file; |
| 263 |
|
| 264 |
Loading sourcefiles, optionally fuzzy merge and start decoding: |
| 265 |
|
| 266 |
($retval, $count) = LoadFile $fname, [$id, [$delflag]]; |
| 267 |
$retval = Smerge $pass; |
| 268 |
$item = GetFileListItem $item_number; |
| 269 |
|
| 270 |
The procedural interface is undocumented, use the following methods instead: |
| 271 |
|
| 272 |
$retval = $item->rename($newname); |
| 273 |
$retval = $item->decode_temp; |
| 274 |
$retval = $item->remove_temp; |
| 275 |
$retval = $item->decode([$target_path]); |
| 276 |
$retval = $item->info(callback-function); |
| 277 |
|
| 278 |
Querying (and setting) item attributes: |
| 279 |
|
| 280 |
$state = $item->state; |
| 281 |
$mode = $item->mode([newmode]); |
| 282 |
$uudet = $item->uudet; |
| 283 |
$size = $item->size; |
| 284 |
$filename = $item->filename([newfilename}); |
| 285 |
$subfname = $item->subfname; |
| 286 |
$mimeid = $item->mimeid; |
| 287 |
$mimetype = $item->mimetype; |
| 288 |
$binfile = $item->binfile; |
| 289 |
|
| 290 |
Totally undocumented and unsupported(!): |
| 291 |
|
| 292 |
$parts = $item->parts; |
| 293 |
|
| 294 |
Functions below not documented and not very well tested: |
| 295 |
|
| 296 |
int QuickDecode () ; |
| 297 |
int EncodeMulti () ; |
| 298 |
int EncodePartial () ; |
| 299 |
int EncodeToStream () ; |
| 300 |
int EncodeToFile () ; |
| 301 |
int E_PrepSingle () ; |
| 302 |
int E_PrepPartial () ; |
| 303 |
|
| 304 |
=head2 EXTENSION FUNCTIONS |
| 305 |
|
| 306 |
Functions found in this module but not documented in the uulib documentation: |
| 307 |
|
| 308 |
=over 4 |
| 309 |
|
| 310 |
=item SetFileNameCallback $cb |
| 311 |
|
| 312 |
Sets (or queries) the FileNameCallback, which is called whenever the |
| 313 |
decoding library can't find a filename and wants to extract a filename |
| 314 |
from the subject line of a posting. The callback will be called with |
| 315 |
two arguments, the subject line and the current candidate for the |
| 316 |
filename. The latter argument can be C<undef>, which means that no |
| 317 |
filename could be found (and likely no one exists, so it is safe to also |
| 318 |
return C<undef> in this case). If it doesn't return anything (not even |
| 319 |
C<undef>!), then nothing happens, so this is a no-op callback: |
| 320 |
|
| 321 |
sub cb { |
| 322 |
return (); |
| 323 |
} |
| 324 |
|
| 325 |
If it returns C<undef>, then this indicates that no filename could be |
| 326 |
found. In all other cases, the return value is taken to be the filename. |
| 327 |
|
| 328 |
This is a slightly more useful callback: |
| 329 |
|
| 330 |
sub cb { |
| 331 |
return unless $_[1]; # skip "Re:"-plies et al. |
| 332 |
my ($subject, $filename) = @_; |
| 333 |
# if we find some *.rar, take it |
| 334 |
return $1 if $subject =~ /(\w+\.rar)/; |
| 335 |
# otherwise just pass what we have |
| 336 |
return (); |
| 337 |
} |
| 338 |
|
| 339 |
=back |
| 340 |
|
| 341 |
=head1 AUTHOR |
| 342 |
|
| 343 |
Marc Lehmann <pcg@goof.com>, the original uulib library was written by |
| 344 |
Frank Pilhofer <fp@informatik.uni-frankfurt.de>. |
| 345 |
|
| 346 |
=head1 SEE ALSO |
| 347 |
|
| 348 |
perl(1), uudeview homepage at http://www.uni-frankfurt.de/~fp/uudeview/. |
| 349 |
|
| 350 |
=cut |
