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.15 by root, Tue Oct 15 23:35:31 2002 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 = 0.31;
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]]
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 is
266no longer necessary.
267
226 $retval = Smerge $pass; 268=item $retval = Smerge $pass
269
270If you are desperate, try to call C<Smerge> with increasing C<$pass>
271values, beginning at C<0>, to try to merge parts that usually would not
272have been merged.
273
274Most probably this will result in garbled files, so never do this by
275default.
276
227 $item = GetFileListItem $item_number; 277=item $item = GetFileListItem $item_number
228 278
229=head2 The procedural interface is undocumented, use the following methods instead 279Return the C<$item> structure for the C<$item_number>'th found file, or
280C<undef> of no file with that number exists.
230 281
282The first file has number C<0>, and the series has no holes, so you can
283iterate over all files by starting with zero and incrementing until you
284hit C<undef>.
285
286=back
287
288=head2 Decoding files
289
290=over 4
291
231 $retval = $item->rename($newname); 292=item $retval = $item->rename($newname)
293
294Change the ondisk filename where the decoded file will be saved.
295
232 $retval = $item->decode_temp; 296=item $retval = $item->decode_temp
297
298Decode the file into a temporary location, use C<< $item->infile >> to
299retrieve the temporary filename.
300
233 $retval = $item->remove_temp; 301=item $retval = $item->remove_temp
302
303Remove the temporarily decoded file again.
304
234 $retval = $item->decode([$target_path]); 305=item $retval = $item->decode([$target_path])
306
307Decode the file to it's destination, or the given target path.
308
235 $retval = $item->info(callback-function); 309=item $retval = $item->info(callback-function)
310
311=back
236 312
237=head2 Querying (and setting) item attributes 313=head2 Querying (and setting) item attributes
238 314
315=over 4
316
239 $state = $item->state; 317=item $state = $item->state
318
240 $mode = $item->mode([newmode]); 319=item $mode = $item->mode([newmode])
320
241 $uudet = $item->uudet; 321=item $uudet = $item->uudet
322
242 $size = $item->size; 323=item $size = $item->size
324
243 $filename = $item->filename([newfilename}); 325=item $filename = $item->filename([newfilename})
326
244 $subfname = $item->subfname; 327=item $subfname = $item->subfname
328
245 $mimeid = $item->mimeid; 329=item $mimeid = $item->mimeid
330
246 $mimetype = $item->mimetype; 331=item $mimetype = $item->mimetype
332
247 $binfile = $item->binfile; 333=item $binfile = $item->binfile
248 334
249=head2 Totally undocumented but well tested ;) 335=back
250 336
337=head2 Information about source parts
338
339=over 4
340
251 $parts = $item->parts; 341=item $parts = $item->parts
342
343Return information about all parts (source files) used to decode the file
344as a list of hashrefs with the following structure:
345
346 {
347 partno => <integer describing the part number, starting with 1>,
348 # the following member sonly exist when they contain useful information
349 sfname => <local pathname of the file where this part is from>,
350 filename => <the ondisk filename of the decoded file>,
351 subfname => <used to cluster postings, possibly the posting filename>,
352 subject => <the subject of the posting/mail>,
353 origin => <the possible source (From) address>,
354 mimetype => <the possible mimetype of the decoded file>,
355 mimeid => <the id part of the Content-Type>,
356 }
357
358Usually you are interested mostly the C<sfname> and possibly the C<partno>
359and C<filename> members.
360
361=back
252 362
253=head2 Functions below not documented and not very well tested 363=head2 Functions below not documented and not very well tested
254 364
255 QuickDecode 365 QuickDecode
256 EncodeMulti 366 EncodeMulti

Diff Legend

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