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.11 by root, Sun Oct 13 13:47:09 2002 UTC vs.
Revision 1.26 by root, Sun Dec 10 16:44:00 2006 UTC

… …
2 2
3use Carp; 3use Carp;
4 4
5require Exporter; 5require Exporter;
6require DynaLoader; 6require DynaLoader;
7use AutoLoader;
8 7
9$VERSION = 0.214; 8$VERSION = "1.07";
10 9
11@ISA = qw(Exporter DynaLoader); 10@ISA = qw(Exporter DynaLoader);
12 11
13@_consts = qw( 12@_consts = qw(
14 ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING 13 ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING
… …
16 FILE_DECODED FILE_ERROR FILE_MISPART FILE_NOBEGIN FILE_NODATA 15 FILE_DECODED FILE_ERROR FILE_MISPART FILE_NOBEGIN FILE_NODATA
17 FILE_NOEND FILE_OK FILE_READ FILE_TMPFILE 16 FILE_NOEND FILE_OK FILE_READ FILE_TMPFILE
18 17
19 MSG_ERROR MSG_FATAL MSG_MESSAGE MSG_NOTE MSG_PANIC MSG_WARNING 18 MSG_ERROR MSG_FATAL MSG_MESSAGE MSG_NOTE MSG_PANIC MSG_WARNING
20 19
20 OPT_RBUF OPT_WBUF
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 OPT_DOTDOT 24 OPT_VERSION OPT_REMOVE OPT_MOREMIME OPT_DOTDOT
25 25
… …
99=head1 SYNOPSIS 99=head1 SYNOPSIS
100 100
101 use Convert::UUlib ':all'; 101 use Convert::UUlib ':all';
102 102
103 # read all the files named on the commandline and decode them 103 # read all the files named on the commandline and decode them
104 # into the CURRENT directory. See below for a longer example.
104 LoadFile($_) for @ARGV; 105 LoadFile $_ for @ARGV;
105 for($i=0; $uu=GetFileListItem($i); $i++) { 106 for (my $i = 0; my $uu = GetFileListItem $i; $i++) {
106 $uu->decode if $uu->state & FILE_OK; 107 if ($uu->state & FILE_OK) {
108 $uu->decode;
109 print $uu->filename, "\n";
110 }
107 } 111 }
108 112
109=head1 DESCRIPTION 113=head1 DESCRIPTION
110 114
111Read the file doc/library.pdf from the distribution for in-depth 115Read the file doc/library.pdf from the distribution for in-depth
… …
148 OPT_PROGRESS retrieve progress information 152 OPT_PROGRESS retrieve progress information
149 OPT_USETEXT handle text messages 153 OPT_USETEXT handle text messages
150 OPT_PREAMB handle Mime preambles/epilogues 154 OPT_PREAMB handle Mime preambles/epilogues
151 OPT_TINYB64 detect short B64 outside of Mime 155 OPT_TINYB64 detect short B64 outside of Mime
152 OPT_ENCEXT extension for single-part encoded files 156 OPT_ENCEXT extension for single-part encoded files
153 OPT_REMOVE remove input files after decoding 157 OPT_REMOVE remove input files after decoding (dangerous)
154 OPT_MOREMIME strict MIME adherence 158 OPT_MOREMIME strict MIME adherence
155 OPT_DOTDOT .. unescaping has not yet been done on input files 159 OPT_DOTDOT ".."-unescaping has not yet been done on input files
160 OPT_RBUF set default read I/O buffer size in bytes *EXPERIMENTAL*
161 OPT_WBUF set default write I/O buffer size in bytes *EXPERIMENTAL*
156 162
157=head2 Result/Error codes 163=head2 Result/Error codes
158 164
159 RET_OK everything went fine 165 RET_OK everything went fine
160 RET_IOERR I/O Error - examine errno 166 RET_IOERR I/O Error - examine errno
… …
171 177
172 This code is zero, i.e. "false": 178 This code is zero, i.e. "false":
173 179
174 UUFILE_READ Read in, but not further processed 180 UUFILE_READ Read in, but not further processed
175 181
176 The following state codes are ored together: 182 The following state codes are or'ed together:
177 183
178 FILE_MISPART Missing Part(s) detected 184 FILE_MISPART Missing Part(s) detected
179 FILE_NOBEGIN No 'begin' found 185 FILE_NOBEGIN No 'begin' found
180 FILE_NOEND No 'end' found 186 FILE_NOEND No 'end' found
181 FILE_NODATA File does not contain valid uudata 187 FILE_NODATA File does not contain valid uudata
… …
197=head1 EXPORTED FUNCTIONS 203=head1 EXPORTED FUNCTIONS
198 204
199=head2 Initializing and cleanup 205=head2 Initializing and cleanup
200 206
201Initialize is automatically called when the module is loaded and allocates 207Initialize is automatically called when the module is loaded and allocates
202quite a bit of memory. CleanUp releases that again. 208quite a small amount of memory for todays machines ;) CleanUp releases that
209again.
203 210
204 Initialize; # not normally necessary 211On my machine, a fairly complete decode with DBI backend needs about 10MB
212RSS to decode 20000 files.
213
214=over 4
215
216=item Initialize
217
218Not normally necessary, (re-)initializes the library.
219
220=item CleanUp
221
205 CleanUp; # could be called at the end to release memory 222Not normally necessary, could be called at the end to release memory
223before starting a new decoding round.
224
225=back
206 226
207=head2 Setting and querying options 227=head2 Setting and querying options
208 228
229=over 4
230
209 $option = GetOption OPT_xxx; 231=item $option = GetOption OPT_xxx
232
210 SetOption OPT_xxx, opt-value; 233=item SetOption OPT_xxx, opt-value
234
235=back
236
237See the C<OPT_xxx> constants above to see which options exist.
211 238
212=head2 Setting various callbacks 239=head2 Setting various callbacks
213 240
241=over 4
242
214 SetMsgCallback [callback-function]; 243=item SetMsgCallback [callback-function]
244
215 SetBusyCallback [callback-function]; 245=item SetBusyCallback [callback-function]
246
216 SetFileCallback [callback-function]; 247=item SetFileCallback [callback-function]
248
217 SetFNameFilter [callback-function]; 249=item SetFNameFilter [callback-function]
250
251=back
218 252
219=head2 Call the currently selected FNameFilter 253=head2 Call the currently selected FNameFilter
220 254
255=over 4
256
221 $file = FNameFilter $file; 257=item $file = FNameFilter $file
258
259=back
222 260
223=head2 Loading sourcefiles, optionally fuzzy merge and start decoding 261=head2 Loading sourcefiles, optionally fuzzy merge and start decoding
224 262
263=over 4
264
225 ($retval, $count) = LoadFile $fname, [$id, [$delflag]]; 265=item ($retval, $count) = LoadFile $fname, [$id, [$delflag, [$partno]]]
266
267Load the given file and scan it for encoded contents. Optionally tag it
268with the given id, and if C<$delflag> is true, delete the file after it
269is no longer necessary. If you are certain of the part number, you can
270specify it as the last argument.
271
272A better (usually faster) way of doing this is using the C<SetFNameFilter>
273functionality.
274
226 $retval = Smerge $pass; 275=item $retval = Smerge $pass
276
277If you are desperate, try to call C<Smerge> with increasing C<$pass>
278values, beginning at C<0>, to try to merge parts that usually would not
279have been merged.
280
281Most probably this will result in garbled files, so never do this by
282default.
283
227 $item = GetFileListItem $item_number; 284=item $item = GetFileListItem $item_number
228 285
229=head2 The procedural interface is undocumented, use the following methods instead 286Return the C<$item> structure for the C<$item_number>'th found file, or
287C<undef> of no file with that number exists.
230 288
289The first file has number C<0>, and the series has no holes, so you can
290iterate over all files by starting with zero and incrementing until you
291hit C<undef>.
292
293=back
294
295=head2 Decoding files
296
297=over 4
298
231 $retval = $item->rename($newname); 299=item $retval = $item->rename($newname)
300
301Change the ondisk filename where the decoded file will be saved.
302
232 $retval = $item->decode_temp; 303=item $retval = $item->decode_temp
304
305Decode the file into a temporary location, use C<< $item->infile >> to
306retrieve the temporary filename.
307
233 $retval = $item->remove_temp; 308=item $retval = $item->remove_temp
309
310Remove the temporarily decoded file again.
311
234 $retval = $item->decode([$target_path]); 312=item $retval = $item->decode([$target_path])
313
314Decode the file to it's destination, or the given target path.
315
235 $retval = $item->info(callback-function); 316=item $retval = $item->info(callback-function)
317
318=back
236 319
237=head2 Querying (and setting) item attributes 320=head2 Querying (and setting) item attributes
238 321
322=over 4
323
239 $state = $item->state; 324=item $state = $item->state
325
240 $mode = $item->mode([newmode]); 326=item $mode = $item->mode([newmode])
327
241 $uudet = $item->uudet; 328=item $uudet = $item->uudet
329
242 $size = $item->size; 330=item $size = $item->size
331
243 $filename = $item->filename([newfilename}); 332=item $filename = $item->filename([newfilename})
333
244 $subfname = $item->subfname; 334=item $subfname = $item->subfname
335
245 $mimeid = $item->mimeid; 336=item $mimeid = $item->mimeid
337
246 $mimetype = $item->mimetype; 338=item $mimetype = $item->mimetype
339
247 $binfile = $item->binfile; 340=item $binfile = $item->binfile
248 341
249=head2 Totally undocumented but well tested ;) 342=back
250 343
344=head2 Information about source parts
345
346=over 4
347
251 $parts = $item->parts; 348=item $parts = $item->parts
349
350Return information about all parts (source files) used to decode the file
351as a list of hashrefs with the following structure:
352
353 {
354 partno => <integer describing the part number, starting with 1>,
355 # the following member sonly exist when they contain useful information
356 sfname => <local pathname of the file where this part is from>,
357 filename => <the ondisk filename of the decoded file>,
358 subfname => <used to cluster postings, possibly the posting filename>,
359 subject => <the subject of the posting/mail>,
360 origin => <the possible source (From) address>,
361 mimetype => <the possible mimetype of the decoded file>,
362 mimeid => <the id part of the Content-Type>,
363 }
364
365Usually you are interested mostly the C<sfname> and possibly the C<partno>
366and C<filename> members.
367
368=back
252 369
253=head2 Functions below not documented and not very well tested 370=head2 Functions below not documented and not very well tested
254 371
255 QuickDecode 372 QuickDecode
256 EncodeMulti 373 EncodeMulti
… …
420 537
421 CleanUp(); 538 CleanUp();
422 539
423=head1 AUTHOR 540=head1 AUTHOR
424 541
425Marc Lehmann <pcg@goof.com>, the original uulib library was written 542Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written
426by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily 543by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily
427bugfixed by Marc Lehmann. 544bugfixed by Marc Lehmann.
428 545
429=head1 SEE ALSO 546=head1 SEE ALSO
430 547

Diff Legend

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