[ViewVC] Diff of: cvs/Convert-UUlib/UUlib.pm

Comparing Convert-UUlib/UUlib.pm (file contents):
Revision 1.32 by root, Mon Oct 13 12:12:56 2008 UTC vs.
Revision 1.54 by root, Sat Dec 12 10:48:39 2020 UTC

…		…
1	package Convert::UUlib;	1	package Convert::UUlib;
2		2
3	no warnings;	3	use common::sense;
4	use strict;
5		4
6	use Carp;	5	use Carp;
7		6
8	require Exporter;	7	require Exporter;
9	require DynaLoader;	8	require DynaLoader;
10		9
11	our $VERSION = '1.12';	10	our $VERSION = 1.71;
12		11
13	our @ISA = qw(Exporter DynaLoader);	12	our @ISA = qw(Exporter DynaLoader);
14		13
15	our @_consts = qw(	14	our @_consts = qw(
16	ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING	15	ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING
22		21
23	OPT_RBUF OPT_WBUF	22	OPT_RBUF OPT_WBUF
24	OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS OPT_ENCEXT	23	OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS OPT_ENCEXT
25	OPT_ERRNO OPT_FAST OPT_IGNMODE OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB	24	OPT_ERRNO OPT_FAST OPT_IGNMODE OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB
26	OPT_PROGRESS OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE	25	OPT_PROGRESS OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE
27	OPT_VERSION OPT_REMOVE OPT_MOREMIME OPT_DOTDOT	26	OPT_VERSION OPT_REMOVE OPT_MOREMIME OPT_DOTDOT OPT_AUTOCHECK
28		27
29	RET_CANCEL RET_CONT RET_EXISTS RET_ILLVAL RET_IOERR RET_NODATA	28	RET_CANCEL RET_CONT RET_EXISTS RET_ILLVAL RET_IOERR RET_NODATA
30	RET_NOEND RET_NOMEM RET_OK RET_UNSUP	29	RET_NOEND RET_NOMEM RET_OK RET_UNSUP
31		30
32	B64_ENCODED BH_ENCODED PT_ENCODED QP_ENCODED	31	B64_ENCODED BH_ENCODED PT_ENCODED QP_ENCODED
…		…
34	);	33	);
35		34
36	our @_funcs = qw(	35	our @_funcs = qw(
37	Initialize CleanUp GetOption SetOption strerror SetMsgCallback	36	Initialize CleanUp GetOption SetOption strerror SetMsgCallback
38	SetBusyCallback SetFileCallback SetFNameFilter SetFileNameCallback	37	SetBusyCallback SetFileCallback SetFNameFilter SetFileNameCallback
39	FNameFilter LoadFile GetFileListItem RenameFile DecodeToTemp	38	FNameFilter LoadFile GetFileListItem GetFileList RenameFile DecodeToTemp
40	RemoveTemp DecodeFile InfoFile Smerge QuickDecode EncodeMulti	39	RemoveTemp DecodeFile InfoFile Smerge QuickDecode EncodeMulti
41	EncodePartial EncodeToStream EncodeToFile E_PrepSingle	40	EncodePartial EncodeToStream EncodeToFile E_PrepSingle
42	E_PrepPartial	41	E_PrepPartial
43		42
44	straction strencoding strmsglevel	43	straction strencoding strmsglevel
…		…
48	our @EXPORT_OK = @_funcs;	47	our @EXPORT_OK = @_funcs;
49	our %EXPORT_TAGS = (all => [@_consts,@_funcs], constants => \@_consts);	48	our %EXPORT_TAGS = (all => [@_consts,@_funcs], constants => \@_consts);
50		49
51	bootstrap Convert::UUlib $VERSION;	50	bootstrap Convert::UUlib $VERSION;
52		51
53	Initialize();	52	# dummy function for compatiiblity with pre-1.7 versions
54		53	sub Initialize { }
55	# not when < 5.005_6x
56	# END { CleanUp() }
57
58	for (@_consts) {
59	my $constant = constant($_);
60	no strict 'refs';
61	*$_ = sub () { $constant };
62	}
63		54
64	# action code -> string mapping	55	# action code -> string mapping
65	sub straction($) {	56	sub straction($) {
66	return 'copying' if $_[0] == &ACT_COPYING;	57	return 'copying' if $_[0] == &ACT_COPYING;
67	return 'decoding' if $_[0] == &ACT_DECODING;	58	return 'decoding' if $_[0] == &ACT_DECODING;
…		…
105	use Convert::UUlib ':all';	96	use Convert::UUlib ':all';
106		97
107	# read all the files named on the commandline and decode them	98	# read all the files named on the commandline and decode them
108	# into the CURRENT directory. See below for a longer example.	99	# into the CURRENT directory. See below for a longer example.
109	LoadFile $_ for @ARGV;	100	LoadFile $_ for @ARGV;
110	for (my $i = 0; my $uu = GetFileListItem $i; $i++) {	101
		102	for my $uu (GetFileList) {
111	if ($uu->state & FILE_OK) {	103	if ($uu->state & FILE_OK) {
112	$uu->decode;	104	$uu->decode;
113	print $uu->filename, "\n";	105	print $uu->filename, "\n";
114	}	106	}
115	}	107	}
…		…
159	OPT_TINYB64 detect short B64 outside of Mime	151	OPT_TINYB64 detect short B64 outside of Mime
160	OPT_ENCEXT extension for single-part encoded files	152	OPT_ENCEXT extension for single-part encoded files
161	OPT_REMOVE remove input files after decoding (dangerous)	153	OPT_REMOVE remove input files after decoding (dangerous)
162	OPT_MOREMIME strict MIME adherence	154	OPT_MOREMIME strict MIME adherence
163	OPT_DOTDOT ".."-unescaping has not yet been done on input files	155	OPT_DOTDOT ".."-unescaping has not yet been done on input files
164	OPT_RBUF set default read I/O buffer size in bytes EXPERIMENTAL	156	OPT_RBUF set default read I/O buffer size in bytes
165	OPT_WBUF set default write I/O buffer size in bytes EXPERIMENTAL	157	OPT_WBUF set default write I/O buffer size in bytes
		158	OPT_AUTOCHECK automatically check file list after every loadfile
166		159
167	=head2 Result/Error codes	160	=head2 Result/Error codes
168		161
169	RET_OK everything went fine	162	RET_OK everything went fine
170	RET_IOERR I/O Error - examine errno	163	RET_IOERR I/O Error - examine errno
…		…
213	again.	206	again.
214		207
215	On my machine, a fairly complete decode with DBI backend needs about 10MB	208	On my machine, a fairly complete decode with DBI backend needs about 10MB
216	RSS to decode 20000 files.	209	RSS to decode 20000 files.
217		210
218	=over 4	211	=over
219
220	=item Initialize
221
222	Not normally necessary, (re-)initializes the library.
223		212
224	=item CleanUp	213	=item CleanUp
225		214
226	Not normally necessary, could be called at the end to release memory	215	Release memory, file items and clean up files. Should be called after a
227	before starting a new decoding round.	216	decoidng run, if you want to start a new one.
228		217
229	=back	218	=back
230		219
231	=head2 Setting and querying options	220	=head2 Setting and querying options
232		221
233	=over 4	222	=over
234		223
235	=item $option = GetOption OPT_xxx	224	=item $option = GetOption OPT_xxx
236		225
237	=item SetOption OPT_xxx, opt-value	226	=item SetOption OPT_xxx, opt-value
238		227
…		…
240		229
241	See the C<OPT_xxx> constants above to see which options exist.	230	See the C<OPT_xxx> constants above to see which options exist.
242		231
243	=head2 Setting various callbacks	232	=head2 Setting various callbacks
244		233
245	=over 4	234	=over
246		235
247	=item SetMsgCallback [callback-function]	236	=item SetMsgCallback [callback-function]
248		237
249	=item SetBusyCallback [callback-function]	238	=item SetBusyCallback [callback-function]
250		239
…		…
254		243
255	=back	244	=back
256		245
257	=head2 Call the currently selected FNameFilter	246	=head2 Call the currently selected FNameFilter
258		247
259	=over 4	248	=over
260		249
261	=item $file = FNameFilter $file	250	=item $file = FNameFilter $file
262		251
263	=back	252	=back
264		253
265	=head2 Loading sourcefiles, optionally fuzzy merge and start decoding	254	=head2 Loading sourcefiles, optionally fuzzy merge and start decoding
266		255
267	=over 4	256	=over
268		257
269	=item ($retval, $count) = LoadFile $fname, [$id, [$delflag, [$partno]]]	258	=item ($retval, $count) = LoadFile $fname, [$id, [$delflag, [$partno]]]
270		259
271	Load the given file and scan it for encoded contents. Optionally tag it	260	Load the given file and scan it for encoded contents. Optionally tag it
272	with the given id, and if C<$delflag> is true, delete the file after it	261	with the given id, and if C<$delflag> is true, delete the file after it
…		…
281	If you are desperate, try to call C<Smerge> with increasing C<$pass>	270	If you are desperate, try to call C<Smerge> with increasing C<$pass>
282	values, beginning at C<0>, to try to merge parts that usually would not	271	values, beginning at C<0>, to try to merge parts that usually would not
283	have been merged.	272	have been merged.
284		273
285	Most probably this will result in garbled files, so never do this by	274	Most probably this will result in garbled files, so never do this by
286	default.	275	default, except:
		276
		277	If the C<OPT_AUTOCHECK> option has been disabled (by default it is
		278	enabled) to speed up file loading, then you I<have> to call C<Smerge -1>
		279	after loading all files as an additional pre-pass (which is normally done
		280	by C<LoadFile>).
287		281
288	=item $item = GetFileListItem $item_number	282	=item $item = GetFileListItem $item_number
289		283
290	Return the C<$item> structure for the C<$item_number>'th found file, or	284	Return the C<$item> structure for the C<$item_number>'th found file, or
291	C<undef> of no file with that number exists.	285	C<undef> of no file with that number exists.
292		286
293	The first file has number C<0>, and the series has no holes, so you can	287	The first file has number C<0>, and the series has no holes, so you can
294	iterate over all files by starting with zero and incrementing until you	288	iterate over all files by starting with zero and incrementing until you
295	hit C<undef>.	289	hit C<undef>.
296		290
		291	This function has to walk the linear list of fils on each access, so
		292	if you want to iterate over all items, it is usually faster to use
		293	C<GetFileList>.
		294
		295	=item @items = GetFileList
		296
		297	Similar to C<GetFileListItem>, but returns all files in one go, which is
		298	very much faster for large number of items, and has no drawbacks when used
		299	for a small number of items.
		300
297	=back	301	=back
298		302
299	=head2 Decoding files	303	=head2 Decoding files
300		304
301	=over 4	305	=over
302		306
303	=item $retval = $item->rename($newname)	307	=item $retval = $item->rename ($newname)
304		308
305	Change the ondisk filename where the decoded file will be saved.	309	Change the ondisk filename where the decoded file will be saved.
306		310
307	=item $retval = $item->decode_temp	311	=item $retval = $item->decode_temp
308		312
…		…
311		315
312	=item $retval = $item->remove_temp	316	=item $retval = $item->remove_temp
313		317
314	Remove the temporarily decoded file again.	318	Remove the temporarily decoded file again.
315		319
316	=item $retval = $item->decode([$target_path])	320	=item $retval = $item->decode ([$target_path])
317		321
318	Decode the file to it's destination, or the given target path.	322	Decode the file to its destination, or the given target path.
319		323
320	=item $retval = $item->info(callback-function)	324	=item $retval = $item->info (callback-function)
321		325
322	=back	326	=back
323		327
324	=head2 Querying (and setting) item attributes	328	=head2 Querying (and setting) item attributes
325		329
326	=over 4	330	=over
327		331
328	=item $state = $item->state	332	=item $state = $item->state
329		333
330	=item $mode = $item->mode([newmode])	334	=item $mode = $item->mode ([newmode])
331		335
332	=item $uudet = $item->uudet	336	=item $uudet = $item->uudet
333		337
334	=item $size = $item->size	338	=item $size = $item->size
335		339
336	=item $filename = $item->filename([newfilename})	340	=item $filename = $item->filename ([newfilename})
337		341
338	=item $subfname = $item->subfname	342	=item $subfname = $item->subfname
339		343
340	=item $mimeid = $item->mimeid	344	=item $mimeid = $item->mimeid
341		345
…		…
345		349
346	=back	350	=back
347		351
348	=head2 Information about source parts	352	=head2 Information about source parts
349		353
350	=over 4	354	=over
351		355
352	=item $parts = $item->parts	356	=item $parts = $item->parts
353		357
354	Return information about all parts (source files) used to decode the file	358	Return information about all parts (source files) used to decode the file
355	as a list of hashrefs with the following structure:	359	as a list of hashrefs with the following structure:
…		…
369	Usually you are interested mostly the C<sfname> and possibly the C<partno>	373	Usually you are interested mostly the C<sfname> and possibly the C<partno>
370	and C<filename> members.	374	and C<filename> members.
371		375
372	=back	376	=back
373		377
374	=head2 Functions below not documented and not very well tested	378	=head2 Functions below are not documented and not very well tested - feedback welcome
375		379
376	QuickDecode	380	QuickDecode
377	EncodeMulti	381	EncodeMulti
378	EncodePartial	382	EncodePartial
379	EncodeToStream	383	EncodeToStream
…		…
383		387
384	=head2 EXTENSION FUNCTIONS	388	=head2 EXTENSION FUNCTIONS
385		389
386	Functions found in this module but not documented in the uulib documentation:	390	Functions found in this module but not documented in the uulib documentation:
387		391
388	=over 4	392	=over
389		393
390	=item $msg = straction ACT_xxx	394	=item $msg = straction ACT_xxx
391		395
392	Return a human readable string representing the given action code.	396	Return a human readable string representing the given action code.
393		397
…		…
434		438
435	=back	439	=back
436		440
437	=head1 LARGE EXAMPLE DECODER	441	=head1 LARGE EXAMPLE DECODER
438		442
		443	The general workflow for decoding is like this:
		444
		445	=over
		446
		447	=item 1. Configure options with C<SetOption> or C<SetXXXCallback>.
		448
		449	=item 2. Load all source files with C<LoadFile>.
		450
		451	=item 3. Optionally C<Smerge>.
		452
		453	=item 4. Iterate over all C<GetFileList> items (i.e. result files).
		454
		455	=item 5. C<CleanUp> to delete files and free items.
		456
		457	=back
		458
439	This is the file C<example-decoder> from the distribution, put here	459	What follows is the file C<example-decoder> from the distribution that
440	instead of more thorough documentation.	460	illustrates the above worklfow in a non-trivial example.
441		461
442	#!/usr/bin/perl	462	#!/usr/bin/perl
443		463
444	# decode all the files in the directory uusrc/ and copy	464	# decode all the files in the directory uusrc/ and copy
445	# the resulting files to uudst/	465	# the resulting files to uudst/
…		…
464	SetOption OPT_RBUF, 128*1024;	484	SetOption OPT_RBUF, 128*1024;
465	SetOption OPT_WBUF, 1024*1024;	485	SetOption OPT_WBUF, 1024*1024;
466	SetOption OPT_IGNMODE, 1;	486	SetOption OPT_IGNMODE, 1;
467	SetOption OPT_IGNMODE, 1;	487	SetOption OPT_IGNMODE, 1;
468	SetOption OPT_VERBOSE, 1;	488	SetOption OPT_VERBOSE, 1;
		489	SetOption OPT_AUTOCHK, 0;
469		490
470	# show the three ways you can set callback functions. I normally	491	# show the three ways you can set callback functions. I normally
471	# prefer the one with the sub inplace.	492	# prefer the one with the sub inplace.
472	SetFNameFilter \&namefilter;	493	SetFNameFilter \&namefilter;
473		494
…		…
482	# of some subject lines not detected properly by uulib:	503	# of some subject lines not detected properly by uulib:
483	SetFileNameCallback sub {	504	SetFileNameCallback sub {
484	return unless $_[1]; # skip "Re:"-plies et al.	505	return unless $_[1]; # skip "Re:"-plies et al.
485	local $_ = $_[0];	506	local $_ = $_[0];
486		507
487	return $1 if /(\S+\s+IMG_\d+.jpg)/i;
488
489	# the following rules are rather effective on some newsgroups,	508	# the following rules are rather effective on some newsgroups,
490	# like alt.binaries.games.anime, where non-mime, uuencoded data	509	# like alt.binaries.games.anime, where non-mime, uuencoded data
491	# is very common	510	# is very common
492		511
493	# if we find some *.rar, take it as the filename	512	# if we find some *.rar, take it as the filename
…		…
509	# otherwise just pass what we have	528	# otherwise just pass what we have
510	()	529	()
511	};	530	};
512		531
513	# now read all files in the directory uusrc/*	532	# now read all files in the directory uusrc/*
514	for(<uusrc/*>) {	533	for (<uusrc/*>) {
515	my ($retval, $count) = LoadFile ($_, $_, 1);	534	my ($retval, $count) = LoadFile ($_, $_, 1);
516	print "file($_), status(", strerror $retval, ") parts($count)\n";	535	print "file($_), status(", strerror $retval, ") parts($count)\n";
517	}	536	}
518		537
		538	Smerge -1;
		539
519	SetOption OPT_SAVEPATH, "uudst/";	540	SetOption OPT_SAVEPATH, "uudst/";
520		541
521	# now wade through all files and their source parts	542	# now wade through all files and their source parts
522	$i = 0;	543	for my $uu (GetFileList) {
523	while ($uu = GetFileListItem $i) {	544	print "file ", $uu->filename, "\n";
524	$i++;
525	print "file nr. $i";
526	print " state ", $uu->state;	545	print " state ", $uu->state, "\n";
527	print " mode ", $uu->mode;	546	print " mode ", $uu->mode, "\n";
528	print " uudet ", strencoding $uu->uudet;	547	print " uudet ", strencoding $uu->uudet, "\n";
529	print " size ", $uu->size;	548	print " size ", $uu->size, "\n";
530	print " filename ", $uu->filename;
531	print " subfname ", $uu->subfname;	549	print " subfname ", $uu->subfname, "\n";
532	print " mimeid ", $uu->mimeid;	550	print " mimeid ", $uu->mimeid, "\n";
533	print " mimetype ", $uu->mimetype;	551	print " mimetype ", $uu->mimetype, "\n";
534	print "\n";
535		552
536	# print additional info about all parts	553	# print additional info about all parts
		554	print " parts";
537	for ($uu->parts) {	555	for ($uu->parts) {
538	while (my ($k, $v) = each %$_) {	556	for my $k (sort keys %$_) {
539	print "$k > $v, ";	557	print " $k=$_->{$k}";
540	}	558	}
541	print "\n";	559	print "\n";
542	}	560	}
543		561
544	print $uu->filename;
545
546	$uu->remove_temp;	562	$uu->remove_temp;
547		563
548	if (my $err = $uu->decode ()) {	564	if (my $err = $uu->decode) {
549	print ", ", strerror $err, "\n";	565	print " ERROR ", strerror $err, "\n";
550	} else {	566	} else {
551	print ", saved as uudst/", $uu->filename, "\n";	567	print " successfully saved as uudst/", $uu->filename, "\n";
552	}	568	}
553	}	569	}
554		570
555	print "cleanup...\n";	571	print "cleanup...\n";
556		572
557	CleanUp;	573	CleanUp;
		574
		575	=head1 PERLMULTICORE SUPPORT
		576
		577	This module supports the perlmulticore standard (see
		578	L<http://perlmulticore.schmorp.de/> for more info) for the following
		579	functions - generally these are functions accessing the disk and/or using
		580	considerable CPU time:
		581
		582	LoadFile
		583	$item->decode
		584	$item->decode_temp
		585	$item->remove_temp
		586	$item->info
		587
		588	The perl interpreter will be reacquired/released on every callback
		589	invocation, so for performance reasons, callbacks should be avoided if
		590	that is costly.
		591
		592	Future versions might enable multicore support for more functions.
		593
		594	=head1 BUGS AND LIMITATIONS
		595
		596	The original uulib library this module uses was written at a time where
		597	main memory of measured in megabytes and buffer overflows as a security
		598	thign didn't exist. While a lot of security fixes have been applied over
		599	the years (includign some defense in depth mechanism that can shield
		600	against a lot of as-of-yet undetected bugs), using this library for
		601	security purposes requires care.
		602
		603	Likewise, file sizes when the uulib library was written were tiny compared
		604	to today, so do not expect this library to handle files larger than 2GB.
		605
		606	Lastly, this module uses a very "C-like" interface, which means it doesn't
		607	protect you from invalid points as you might expect from "more perlish"
		608	modules - for example, accessing a file item object after callinbg
		609	C<CleanUp> will likely result in crashes, memory corruption, or worse.
558		610
559	=head1 AUTHOR	611	=head1 AUTHOR
560		612
561	Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written	613	Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written
562	by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily	614	by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily
563	bugfixed by Marc Lehmann.	615	bugfixed by Marc Lehmann.
564		616
565	=head1 SEE ALSO	617	=head1 SEE ALSO
566		618
567	perl(1), uudeview homepage at http://www.uni-frankfurt.de/~fp/uudeview/.	619	perl(1), uudeview homepage at L<http://www.fpx.de/fp/Software/UUDeview/>.
568		620
569	=cut	621	=cut
		622

Diff Legend

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

Comparing Convert-UUlib/UUlib.pm (file contents): Revision 1.32 by root, Mon Oct 13 12:12:56 2008 UTC vs. Revision 1.54 by root, Sat Dec 12 10:48:39 2020 UTC

Diff Legend

Comparing Convert-UUlib/UUlib.pm (file contents):
Revision 1.32 by root, Mon Oct 13 12:12:56 2008 UTC vs.
Revision 1.54 by root, Sat Dec 12 10:48:39 2020 UTC