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.10 by root, Mon Aug 19 23:25:34 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.213; 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
… …
24 OPT_VERSION OPT_REMOVE OPT_MOREMIME OPT_DOTDOT 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 SetMsgCallback 34 Initialize CleanUp GetOption SetOption strerror SetMsgCallback
… …
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 QP_ENCODED XX_ENCODED 189 UU_ENCODED UUencoded data
232 UU_ENCODED YENC_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
303 262
304=head2 EXTENSION FUNCTIONS 263=head2 EXTENSION FUNCTIONS
305 264
306Functions found in this module but not documented in the uulib documentation: 265Functions found in this module but not documented in the uulib documentation:
307 266
308=over 4 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.
309 284
310=item SetFileNameCallback $cb 285=item SetFileNameCallback $cb
311 286
312Sets (or queries) the FileNameCallback, which is called whenever the 287Sets (or queries) the FileNameCallback, which is called whenever the
313decoding library can't find a filename and wants to extract a filename 288decoding library can't find a filename and wants to extract a filename
… …
336 return (); 311 return ();
337 } 312 }
338 313
339=back 314=back
340 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();
422
341=head1 AUTHOR 423=head1 AUTHOR
342 424
343Marc Lehmann <pcg@goof.com>, the original uulib library was written by 425Marc Lehmann <pcg@goof.com>, the original uulib library was written
344Frank Pilhofer <fp@informatik.uni-frankfurt.de>. 426by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily
427bugfixed by Marc Lehmann.
345 428
346=head1 SEE ALSO 429=head1 SEE ALSO
347 430
348perl(1), uudeview homepage at http://www.uni-frankfurt.de/~fp/uudeview/. 431perl(1), uudeview homepage at http://www.uni-frankfurt.de/~fp/uudeview/.
349 432

Diff Legend

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