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.12 by root, Sun Oct 13 13:51:00 2002 UTC vs.
Revision 1.19 by root, Sun Apr 18 14:48:53 2004 UTC

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

Diff Legend

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