ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Convert-UUlib/UUlib.pm
(Generate patch)

Comparing Convert-UUlib/UUlib.pm (file contents):
Revision 1.5 by root, Sun Mar 31 20:19:09 2002 UTC vs.
Revision 1.11 by root, Sun Oct 13 13:47:09 2002 UTC

… …
4 4
5require Exporter; 5require Exporter;
6require DynaLoader; 6require DynaLoader;
7use AutoLoader; 7use AutoLoader;
8 8
9$VERSION = 0.21; 9$VERSION = 0.214;
10 10
11@ISA = qw(Exporter DynaLoader); 11@ISA = qw(Exporter DynaLoader);
12 12
13@_consts = qw( 13@_consts = qw(
14 ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING 14 ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING
… …
19 MSG_ERROR MSG_FATAL MSG_MESSAGE MSG_NOTE MSG_PANIC MSG_WARNING 19 MSG_ERROR MSG_FATAL MSG_MESSAGE MSG_NOTE MSG_PANIC MSG_WARNING
20 20
21 OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS OPT_ENCEXT 21 OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS OPT_ENCEXT
22 OPT_ERRNO OPT_FAST OPT_IGNMODE OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB 22 OPT_ERRNO OPT_FAST OPT_IGNMODE OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB
23 OPT_PROGRESS OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE 23 OPT_PROGRESS OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE
24 OPT_VERSION OPT_REMOVE OPT_MOREMIME 24 OPT_VERSION OPT_REMOVE OPT_MOREMIME OPT_DOTDOT
25 25
26 RET_CANCEL RET_CONT RET_EXISTS RET_ILLVAL RET_IOERR RET_NODATA 26 RET_CANCEL RET_CONT RET_EXISTS RET_ILLVAL RET_IOERR RET_NODATA
27 RET_NOEND RET_NOMEM RET_OK RET_UNSUP 27 RET_NOEND RET_NOMEM RET_OK RET_UNSUP
28 28
29 B64ENCODED BH_ENCODED PT_ENCODED QP_ENCODED 29 B64_ENCODED BH_ENCODED PT_ENCODED QP_ENCODED
30 XX_ENCODED UU_ENCODED YENC_ENCODED 30 XX_ENCODED UU_ENCODED YENC_ENCODED
31); 31);
32 32
33@_funcs = qw( 33@_funcs = qw(
34 Initialize CleanUp GetOption SetOption strerror 34 Initialize CleanUp GetOption SetOption strerror SetMsgCallback
35 SetMsgCallback SetBusyCallback SetFileCallback 35 SetBusyCallback SetFileCallback SetFNameFilter SetFileNameCallback
36 SetFNameFilter FNameFilter LoadFile GetFileListItem 36 FNameFilter LoadFile GetFileListItem RenameFile DecodeToTemp
37 RenameFile DecodeToTemp RemoveTemp DecodeFile 37 RemoveTemp DecodeFile InfoFile Smerge QuickDecode EncodeMulti
38 InfoFile Smerge QuickDecode EncodeMulti EncodePartial 38 EncodePartial EncodeToStream EncodeToFile E_PrepSingle
39 EncodeToStream EncodeToFile E_PrepSingle E_PrepPartial 39 E_PrepPartial
40 40
41 straction strencoding strmsglevel 41 straction strencoding strmsglevel
42); 42);
43 43
44@EXPORT = @_consts; 44@EXPORT = @_consts;
… …
68} 68}
69 69
70# encoding type -> string mapping 70# encoding type -> string mapping
71sub strencoding($) { 71sub strencoding($) {
72 return 'uuencode' if $_[0] == &UU_ENCODED; 72 return 'uuencode' if $_[0] == &UU_ENCODED;
73 return 'base64' if $_[0] == &B64ENCODED; 73 return 'base64' if $_[0] == &B64_ENCODED;
74 return 'yenc' if $_[0] == &YENC_ENCODED; 74 return 'yenc' if $_[0] == &YENC_ENCODED;
75 return 'binhex' if $_[0] == &BH_ENCODED; 75 return 'binhex' if $_[0] == &BH_ENCODED;
76 return 'plaintext' if $_[0] == &PT_ENCODED; 76 return 'plaintext' if $_[0] == &PT_ENCODED;
77 return 'quoted-printable' if $_[0] == &QP_ENCODED; 77 return 'quoted-printable' if $_[0] == &QP_ENCODED;
78 return 'xxencode' if $_[0] == &XX_ENCODED; 78 return 'xxencode' if $_[0] == &XX_ENCODED;
… …
96 96
97Convert::UUlib - Perl interface to the uulib library (a.k.a. uudeview/uuenview). 97Convert::UUlib - Perl interface to the uulib library (a.k.a. uudeview/uuenview).
98 98
99=head1 SYNOPSIS 99=head1 SYNOPSIS
100 100
101 use Convert::UUlib;
102
103=head1 DESCRIPTION
104
105Read the file uulibdoc.dvi.gz and the example-decoder source. Sorry - more
106to come once people use me ;)
107
108=head1 SMALL EXAMPLE DECODER
109
110The following code excerpt is a minimal decoder program. It reads all
111files given on the commandline and decodes any files in it.
112
113 use Convert::UUlib ':all'; 101 use Convert::UUlib ':all';
114 102
103 # read all the files named on the commandline and decode them
115 LoadFile($_) for @ARGV; 104 LoadFile($_) for @ARGV;
116
117 for($i=0; $uu=GetFileListItem($i); $i++) { 105 for($i=0; $uu=GetFileListItem($i); $i++) {
118 $uu->decode if $uu->state & FILE_OK; 106 $uu->decode if $uu->state & FILE_OK;
119 } 107 }
120 108
121=head1 LARGE EXAMPLE DECODER 109=head1 DESCRIPTION
122 110
123This is the file C<example-decoder> from the distribution, put here 111Read the file doc/library.pdf from the distribution for in-depth
124instead of more thorough documentation. 112information about the C-library used in this interface, and the rest of
113this document and especially the non-trivial decoder program at the end.
125 114
126 # decode all the files in the directory uusrc/ and copy 115=head1 EXPORTED CONSTANTS
127 # the resulting files to uudst/
128 116
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
200Action code constants: 117=head2 Action code constants
201 118
202 ACT_COPYING ACT_DECODING ACT_ENCODING 119 ACT_IDLE we don't do anything
203 ACT_IDLE ACT_SCANNING 120 ACT_SCANNING scanning an input file
121 ACT_DECODING decoding into a temp file
122 ACT_COPYING copying temp to target
123 ACT_ENCODING encoding a file
204 124
205File 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
211Message severity levels: 125=head2 Message severity levels
212 126
213 MSG_ERROR MSG_FATAL MSG_MESSAGE 127 MSG_MESSAGE just a message, nothing important
214 MSG_NOTE MSG_PANIC MSG_WARNING 128 MSG_NOTE something that should be noticed
129 MSG_WARNING important msg, processing continues
130 MSG_ERROR processing has been terminated
131 MSG_FATAL decoder cannot process further requests
132 MSG_PANIC recovery impossible, app must terminate
215 133
216Options: 134=head2 Options
217 135
218 OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS 136 OPT_VERSION version number MAJOR.MINORplPATCH (ro)
219 OPT_ENCEXT OPT_ERRNO OPT_FAST OPT_IGNMODE 137 OPT_FAST assumes only one part per file
220 OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB OPT_PROGRESS 138 OPT_DUMBNESS switch off the program's intelligence
221 OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE 139 OPT_BRACKPOL give numbers in [] higher precendence
222 OPT_VERSION OPT_REMOVE OPT_MOREMIME 140 OPT_VERBOSE generate informative messages
141 OPT_DESPERATE try to decode incomplete files
142 OPT_IGNREPLY ignore RE:plies (off by default)
143 OPT_OVERWRITE whether it's OK to overwrite ex. files
144 OPT_SAVEPATH prefix to save-files on disk
145 OPT_IGNMODE ignore the original file mode
146 OPT_DEBUG print messages with FILE/LINE info
147 OPT_ERRNO get last error code for RET_IOERR (ro)
148 OPT_PROGRESS retrieve progress information
149 OPT_USETEXT handle text messages
150 OPT_PREAMB handle Mime preambles/epilogues
151 OPT_TINYB64 detect short B64 outside of Mime
152 OPT_ENCEXT extension for single-part encoded files
153 OPT_REMOVE remove input files after decoding
154 OPT_MOREMIME strict MIME adherence
155 OPT_DOTDOT .. unescaping has not yet been done on input files
223 156
224Error/Result codes: 157=head2 Result/Error codes
225 158
226 RET_CANCEL RET_CONT RET_EXISTS RET_ILLVAL RET_IOERR 159 RET_OK everything went fine
227 RET_NODATA RET_NOEND RET_NOMEM RET_OK RET_UNSUP 160 RET_IOERR I/O Error - examine errno
161 RET_NOMEM not enough memory
162 RET_ILLVAL illegal value for operation
163 RET_NODATA decoder didn't find any data
164 RET_NOEND encoded data wasn't ended properly
165 RET_UNSUP unsupported function (encoding)
166 RET_EXISTS file exists (decoding)
167 RET_CONT continue -- special from ScanPart
168 RET_CANCEL operation canceled
228 169
170=head2 File States
171
172 This code is zero, i.e. "false":
173
174 UUFILE_READ Read in, but not further processed
175
176 The following state codes are ored together:
177
178 FILE_MISPART Missing Part(s) detected
179 FILE_NOBEGIN No 'begin' found
180 FILE_NOEND No 'end' found
181 FILE_NODATA File does not contain valid uudata
182 FILE_OK All Parts found, ready to decode
183 FILE_ERROR Error while decoding
184 FILE_DECODED Successfully decoded
185 FILE_TMPFILE Temporary decoded file exists
186
229Encoding types: 187=head2 Encoding types
230 188
231 B64ENCODED BH_ENCODED PT_ENCODED 189 UU_ENCODED UUencoded data
232 QP_ENCODED XX_ENCODED UU_ENCODED 190 B64_ENCODED Mime-Base64 data
191 XX_ENCODED XXencoded data
192 BH_ENCODED Binhex encoded
193 PT_ENCODED Plain-Text encoded (MIME)
194 QP_ENCODED Quoted-Printable (MIME)
195 YENC_ENCODED yEnc encoded (non-MIME)
233 196
234=head1 Exported functions 197=head1 EXPORTED FUNCTIONS
235 198
236Initializing and cleanup (Initialize is automatically called when the 199=head2 Initializing and cleanup
237module is loaded and allocates quite a bit of memory. CleanUp releases 200
238that again). 201Initialize is automatically called when the module is loaded and allocates
202quite a bit of memory. CleanUp releases that again.
239 203
240 Initialize; # not normally necessary 204 Initialize; # not normally necessary
241 CleanUp; # could be called at the end to release memory 205 CleanUp; # could be called at the end to release memory
242 206
243Setting and querying options: 207=head2 Setting and querying options
244 208
245 $option = GetOption OPT_xxx; 209 $option = GetOption OPT_xxx;
246 SetOption OPT_xxx, opt-value; 210 SetOption OPT_xxx, opt-value;
247 211
248Error and action values => stringified:
249
250 $msg = straction ACT_xxx;
251 $msg = strerror RET_xxx;
252
253Setting various callbacks: 212=head2 Setting various callbacks
254 213
255 SetMsgCallback [callback-function]; 214 SetMsgCallback [callback-function];
256 SetBusyCallback [callback-function]; 215 SetBusyCallback [callback-function];
257 SetFileCallback [callback-function]; 216 SetFileCallback [callback-function];
258 SetFNameFilter [callback-function]; 217 SetFNameFilter [callback-function];
259 218
260Call the currently selected FNameFilter: 219=head2 Call the currently selected FNameFilter
261 220
262 $file = FNameFilter $file; 221 $file = FNameFilter $file;
263 222
264Loading sourcefiles, optionally fuzzy merge and start decoding: 223=head2 Loading sourcefiles, optionally fuzzy merge and start decoding
265 224
266 ($retval, $count) = LoadFile $fname, [$id, [$delflag]]; 225 ($retval, $count) = LoadFile $fname, [$id, [$delflag]];
267 $retval = Smerge $pass; 226 $retval = Smerge $pass;
268 $item = GetFileListItem $item_number; 227 $item = GetFileListItem $item_number;
269 228
270The procedural interface is undocumented, use the following methods instead: 229=head2 The procedural interface is undocumented, use the following methods instead
271 230
272 $retval = $item->rename($newname); 231 $retval = $item->rename($newname);
273 $retval = $item->decode_temp; 232 $retval = $item->decode_temp;
274 $retval = $item->remove_temp; 233 $retval = $item->remove_temp;
275 $retval = $item->decode([$target_path]); 234 $retval = $item->decode([$target_path]);
276 $retval = $item->info(callback-function); 235 $retval = $item->info(callback-function);
277 236
278Querying (and setting) item attributes: 237=head2 Querying (and setting) item attributes
279 238
280 $state = $item->state; 239 $state = $item->state;
281 $mode = $item->mode([newmode]); 240 $mode = $item->mode([newmode]);
282 $uudet = $item->uudet; 241 $uudet = $item->uudet;
283 $size = $item->size; 242 $size = $item->size;
… …
285 $subfname = $item->subfname; 244 $subfname = $item->subfname;
286 $mimeid = $item->mimeid; 245 $mimeid = $item->mimeid;
287 $mimetype = $item->mimetype; 246 $mimetype = $item->mimetype;
288 $binfile = $item->binfile; 247 $binfile = $item->binfile;
289 248
290Totally undocumented and unsupported(!): 249=head2 Totally undocumented but well tested ;)
291 250
292 $parts = $item->parts; 251 $parts = $item->parts;
293 252
294Functions below not documented and not very well tested: 253=head2 Functions below not documented and not very well tested
295 254
296 int QuickDecode () ; 255 QuickDecode
297 int EncodeMulti () ; 256 EncodeMulti
298 int EncodePartial () ; 257 EncodePartial
299 int EncodeToStream () ; 258 EncodeToStream
300 int EncodeToFile () ; 259 EncodeToFile
301 int E_PrepSingle () ; 260 E_PrepSingle
302 int E_PrepPartial () ; 261 E_PrepPartial
262
263=head2 EXTENSION FUNCTIONS
264
265Functions found in this module but not documented in the uulib documentation:
266
267=over 4
268
269=item $msg = straction ACT_xxx
270
271Return a human readable string representing the given action code.
272
273=item $msg = strerror RET_xxx
274
275Return a human readable string representing the given error code.
276
277=item $str = strencoding xxx_ENCODED
278
279Return the name of the encoding type as a string.
280
281=item $str = strmsglevel MSG_xxx
282
283Returns the message level as a string.
284
285=item SetFileNameCallback $cb
286
287Sets (or queries) the FileNameCallback, which is called whenever the
288decoding library can't find a filename and wants to extract a filename
289from the subject line of a posting. The callback will be called with
290two arguments, the subject line and the current candidate for the
291filename. The latter argument can be C<undef>, which means that no
292filename could be found (and likely no one exists, so it is safe to also
293return C<undef> in this case). If it doesn't return anything (not even
294C<undef>!), then nothing happens, so this is a no-op callback:
295
296 sub cb {
297 return ();
298 }
299
300If it returns C<undef>, then this indicates that no filename could be
301found. In all other cases, the return value is taken to be the filename.
302
303This is a slightly more useful callback:
304
305 sub cb {
306 return unless $_[1]; # skip "Re:"-plies et al.
307 my ($subject, $filename) = @_;
308 # if we find some *.rar, take it
309 return $1 if $subject =~ /(\w+\.rar)/;
310 # otherwise just pass what we have
311 return ();
312 }
313
314=back
315
316=head1 LARGE EXAMPLE DECODER
317
318This is the file C<example-decoder> from the distribution, put here
319instead of more thorough documentation.
320
321 # decode all the files in the directory uusrc/ and copy
322 # the resulting files to uudst/
323
324 use Convert::UUlib ':all';
325
326 sub namefilter {
327 my($path)=@_;
328 $path=~s/^.*[\/\\]//;
329 $path;
330 }
331
332 sub busycb {
333 my ($action, $curfile, $partno, $numparts, $percent, $fsize) = @_;
334 $_[0]=straction($action);
335 print "busy_callback(", (join ",",@_), ")\n";
336 0;
337 }
338
339 SetOption OPT_IGNMODE, 1;
340 SetOption OPT_VERBOSE, 1;
341
342 # show the three ways you can set callback functions. I normally
343 # prefer the one with the sub inplace.
344 SetFNameFilter \&namefilter;
345
346 SetBusyCallback "busycb", 333;
347
348 SetMsgCallback sub {
349 my ($msg, $level) = @_;
350 print uc strmsglevel $_[1], ": $msg\n";
351 };
352
353 # the following non-trivial FileNameCallback takes care
354 # of some subject lines not detected properly by uulib:
355 SetFileNameCallback sub {
356 return unless $_[1]; # skip "Re:"-plies et al.
357 local $_ = $_[0];
358
359 # the following rules are rather effective on some newsgroups,
360 # like alt.binaries.games.anime, where non-mime, uuencoded data
361 # is very common
362
363 # if we find some *.rar, take it as the filename
364 return $1 if /(\S{3,}\.(?:[rstuvwxyz]\d\d|rar))\s/i;
365
366 # one common subject format
367 return $1 if /- "(.{2,}?\..+?)" (?:yenc )?\(\d+\/\d+\)/i;
368
369 # - filename.par (04/55)
370 return $1 if /- "?(\S{3,}\.\S+?)"? (?:yenc )?\(\d+\/\d+\)/i;
371
372 # - (xxx) No. 1 sayuri81.jpg 756565 bytes
373 # - (20 files) No.17 Roseanne.jpg [2/2]
374 return $1 if /No\.[ 0-9]+ (\S+\....) (?:\d+ bytes )?\[/;
375
376 # otherwise just pass what we have
377 return ();
378 };
379
380 # now read all files in the directory uusrc/*
381 for(<uusrc/*>) {
382 my($retval,$count)=LoadFile ($_, $_, 1);
383 print "file($_), status(", strerror $retval, ") parts($count)\n";
384 }
385
386 SetOption OPT_SAVEPATH, "uudst/";
387
388 # now wade through all files and their source parts
389 $i = 0;
390 while ($uu = GetFileListItem($i)) {
391 $i++;
392 print "file nr. $i";
393 print " state ", $uu->state;
394 print " mode ", $uu->mode;
395 print " uudet ", strencoding $uu->uudet;
396 print " size ", $uu->size;
397 print " filename ", $uu->filename;
398 print " subfname ", $uu->subfname;
399 print " mimeid ", $uu->mimeid;
400 print " mimetype ", $uu->mimetype;
401 print "\n";
402
403 # print additional info about all parts
404 for ($uu->parts) {
405 while (my ($k, $v) = each %$_) {
406 print "$k > $v, ";
407 }
408 print "\n";
409 }
410
411 $uu->decode_temp;
412 print " temporarily decoded to ", $uu->binfile, "\n";
413 $uu->remove_temp;
414
415 print strerror $uu->decode;
416 print " saved as uudst/", $uu->filename, "\n";
417 }
418
419 print "cleanup...\n";
420
421 CleanUp();
303 422
304=head1 AUTHOR 423=head1 AUTHOR
305 424
306Marc Lehmann <pcg@goof.com>, the original uulib library was written by 425Marc Lehmann <pcg@goof.com>, the original uulib library was written
307Frank Pilhofer <fp@informatik.uni-frankfurt.de>. 426by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily
427bugfixed by Marc Lehmann.
308 428
309=head1 SEE ALSO 429=head1 SEE ALSO
310 430
311perl(1), uudeview homepage at http://www.uni-frankfurt.de/~fp/uudeview/. 431perl(1), uudeview homepage at http://www.uni-frankfurt.de/~fp/uudeview/.
312 432

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines