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

Comparing Convert-UUlib/UUlib.pm (file contents):
Revision 1.40 by root, Wed Dec 15 00:10:59 2010 UTC vs.
Revision 1.49 by root, Fri Feb 28 17:33:09 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.34';	10	our $VERSION = 1.62;
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
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	}
…		…
214	again.	206	again.
215		207
216	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
217	RSS to decode 20000 files.	209	RSS to decode 20000 files.
218		210
219	=over 4	211	=over
220
221	=item Initialize
222
223	Not normally necessary, (re-)initializes the library.
224		212
225	=item CleanUp	213	=item CleanUp
226		214
227	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
228	before starting a new decoding round.	216	decoidng run, if you want to start a new one.
229		217
230	=back	218	=back
231		219
232	=head2 Setting and querying options	220	=head2 Setting and querying options
233		221
234	=over 4	222	=over
235		223
236	=item $option = GetOption OPT_xxx	224	=item $option = GetOption OPT_xxx
237		225
238	=item SetOption OPT_xxx, opt-value	226	=item SetOption OPT_xxx, opt-value
239		227
…		…
241		229
242	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.
243		231
244	=head2 Setting various callbacks	232	=head2 Setting various callbacks
245		233
246	=over 4	234	=over
247		235
248	=item SetMsgCallback [callback-function]	236	=item SetMsgCallback [callback-function]
249		237
250	=item SetBusyCallback [callback-function]	238	=item SetBusyCallback [callback-function]
251		239
…		…
255		243
256	=back	244	=back
257		245
258	=head2 Call the currently selected FNameFilter	246	=head2 Call the currently selected FNameFilter
259		247
260	=over 4	248	=over
261		249
262	=item $file = FNameFilter $file	250	=item $file = FNameFilter $file
263		251
264	=back	252	=back
265		253
266	=head2 Loading sourcefiles, optionally fuzzy merge and start decoding	254	=head2 Loading sourcefiles, optionally fuzzy merge and start decoding
267		255
268	=over 4	256	=over
269		257
270	=item ($retval, $count) = LoadFile $fname, [$id, [$delflag, [$partno]]]	258	=item ($retval, $count) = LoadFile $fname, [$id, [$delflag, [$partno]]]
271		259
272	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
273	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
…		…
298		286
299	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
300	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
301	hit C<undef>.	289	hit C<undef>.
302		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.
		298
303	=back	299	=back
304		300
305	=head2 Decoding files	301	=head2 Decoding files
306		302
307	=over 4	303	=over
308		304
309	=item $retval = $item->rename($newname)	305	=item $retval = $item->rename ($newname)
310		306
311	Change the ondisk filename where the decoded file will be saved.	307	Change the ondisk filename where the decoded file will be saved.
312		308
313	=item $retval = $item->decode_temp	309	=item $retval = $item->decode_temp
314		310
…		…
317		313
318	=item $retval = $item->remove_temp	314	=item $retval = $item->remove_temp
319		315
320	Remove the temporarily decoded file again.	316	Remove the temporarily decoded file again.
321		317
322	=item $retval = $item->decode([$target_path])	318	=item $retval = $item->decode ([$target_path])
323		319
324	Decode the file to it's destination, or the given target path.	320	Decode the file to its destination, or the given target path.
325		321
326	=item $retval = $item->info(callback-function)	322	=item $retval = $item->info (callback-function)
327		323
328	=back	324	=back
329		325
330	=head2 Querying (and setting) item attributes	326	=head2 Querying (and setting) item attributes
331		327
332	=over 4	328	=over
333		329
334	=item $state = $item->state	330	=item $state = $item->state
335		331
336	=item $mode = $item->mode([newmode])	332	=item $mode = $item->mode ([newmode])
337		333
338	=item $uudet = $item->uudet	334	=item $uudet = $item->uudet
339		335
340	=item $size = $item->size	336	=item $size = $item->size
341		337
342	=item $filename = $item->filename([newfilename})	338	=item $filename = $item->filename ([newfilename})
343		339
344	=item $subfname = $item->subfname	340	=item $subfname = $item->subfname
345		341
346	=item $mimeid = $item->mimeid	342	=item $mimeid = $item->mimeid
347		343
…		…
351		347
352	=back	348	=back
353		349
354	=head2 Information about source parts	350	=head2 Information about source parts
355		351
356	=over 4	352	=over
357		353
358	=item $parts = $item->parts	354	=item $parts = $item->parts
359		355
360	Return information about all parts (source files) used to decode the file	356	Return information about all parts (source files) used to decode the file
361	as a list of hashrefs with the following structure:	357	as a list of hashrefs with the following structure:
…		…
375	Usually you are interested mostly the C<sfname> and possibly the C<partno>	371	Usually you are interested mostly the C<sfname> and possibly the C<partno>
376	and C<filename> members.	372	and C<filename> members.
377		373
378	=back	374	=back
379		375
380	=head2 Functions below not documented and not very well tested	376	=head2 Functions below are not documented and not very well tested - feedback welcome
381		377
382	QuickDecode	378	QuickDecode
383	EncodeMulti	379	EncodeMulti
384	EncodePartial	380	EncodePartial
385	EncodeToStream	381	EncodeToStream
…		…
389		385
390	=head2 EXTENSION FUNCTIONS	386	=head2 EXTENSION FUNCTIONS
391		387
392	Functions found in this module but not documented in the uulib documentation:	388	Functions found in this module but not documented in the uulib documentation:
393		389
394	=over 4	390	=over
395		391
396	=item $msg = straction ACT_xxx	392	=item $msg = straction ACT_xxx
397		393
398	Return a human readable string representing the given action code.	394	Return a human readable string representing the given action code.
399		395
…		…
440		436
441	=back	437	=back
442		438
443	=head1 LARGE EXAMPLE DECODER	439	=head1 LARGE EXAMPLE DECODER
444		440
		441	The general workflow for decoding is like this:
		442
		443	=over
		444
		445	=item 1. Configure options with C<SetOption> or C<SetXXXCallback>.
		446
		447	=item 2. Load all source files with C<LoadFile>.
		448
		449	=item 3. Optionally C<Smerge>.
		450
		451	=item 4. Iterate over all C<GetFileList> items (i.e. result files).
		452
		453	=item 5. C<CleanUp> to delete files and free items.
		454
		455	=back
		456
445	This is the file C<example-decoder> from the distribution, put here	457	What follows is the file C<example-decoder> from the distribution that
446	instead of more thorough documentation.	458	illustrates the above worklfow in a non-trivial example.
447		459
448	#!/usr/bin/perl	460	#!/usr/bin/perl
449		461
450	# decode all the files in the directory uusrc/ and copy	462	# decode all the files in the directory uusrc/ and copy
451	# the resulting files to uudst/	463	# the resulting files to uudst/
…		…
513	# otherwise just pass what we have	525	# otherwise just pass what we have
514	()	526	()
515	};	527	};
516		528
517	# now read all files in the directory uusrc/*	529	# now read all files in the directory uusrc/*
518	for(<uusrc/*>) {	530	for (<uusrc/*>) {
519	my ($retval, $count) = LoadFile ($_, $_, 1);	531	my ($retval, $count) = LoadFile ($_, $_, 1);
520	print "file($_), status(", strerror $retval, ") parts($count)\n";	532	print "file($_), status(", strerror $retval, ") parts($count)\n";
521	}	533	}
522		534
523	SetOption OPT_SAVEPATH, "uudst/";	535	SetOption OPT_SAVEPATH, "uudst/";
524		536
525	# now wade through all files and their source parts	537	# now wade through all files and their source parts
526	$i = 0;	538	for my $uu (GetFileList) {
527	while ($uu = GetFileListItem $i) {	539	print "file ", $uu->filename, "\n";
528	$i++;
529	print "file nr. $i";
530	print " state ", $uu->state;	540	print " state ", $uu->state, "\n";
531	print " mode ", $uu->mode;	541	print " mode ", $uu->mode, "\n";
532	print " uudet ", strencoding $uu->uudet;	542	print " uudet ", strencoding $uu->uudet, "\n";
533	print " size ", $uu->size;	543	print " size ", $uu->size, "\n";
534	print " filename ", $uu->filename;
535	print " subfname ", $uu->subfname;	544	print " subfname ", $uu->subfname, "\n";
536	print " mimeid ", $uu->mimeid;	545	print " mimeid ", $uu->mimeid, "\n";
537	print " mimetype ", $uu->mimetype;	546	print " mimetype ", $uu->mimetype, "\n";
538	print "\n";
539		547
540	# print additional info about all parts	548	# print additional info about all parts
		549	print " parts";
541	for ($uu->parts) {	550	for ($uu->parts) {
542	while (my ($k, $v) = each %$_) {	551	for my $k (sort keys %$_) {
543	print "$k > $v, ";	552	print " $k=$_->{$k}";
544	}	553	}
545	print "\n";	554	print "\n";
546	}	555	}
547		556
548	print $uu->filename;
549
550	$uu->remove_temp;	557	$uu->remove_temp;
551		558
552	if (my $err = $uu->decode ()) {	559	if (my $err = $uu->decode) {
553	print ", ", strerror $err, "\n";	560	print " ERROR ", strerror $err, "\n";
554	} else {	561	} else {
555	print ", saved as uudst/", $uu->filename, "\n";	562	print " successfully saved as uudst/", $uu->filename, "\n";
556	}	563	}
557	}	564	}
558		565
559	print "cleanup...\n";	566	print "cleanup...\n";
560		567
561	CleanUp;	568	CleanUp;
		569
		570	=head1 PERLMULTICORE SUPPORT
		571
		572	This module supports the perlmulticore standard (see
		573	L<http://perlmulticore.schmorp.de/> for more info) for the following
		574	functions - generally these are functions accessing the disk and/or using
		575	considerable CPU time:
		576
		577	LoadFile
		578	$item->decode
		579	$item->decode_temp
		580	$item->remove_temp
		581	$item->info
		582
		583	The perl interpreter will be reacquired/released on every callback
		584	invocation, so for performance reasons, callbacks should be avoided if
		585	that is costly.
		586
		587	Future versions might enable multicore support for more functions.
		588
		589	=head1 BUGS AND LIMITATIONS
		590
		591	The original uulib library this module uses was written at a time where
		592	main memory of measured in megabytes and buffer overflows as a security
		593	thign didn't exist. While a lot of security fixes have been applied over
		594	the years (includign some defense in depth mechanism that can shield
		595	against a lot of as-of-yet undetected bugs), using this library for
		596	security purposes requires care.
		597
		598	Likewise, file sizes when the uulib library was written were tiny compared
		599	to today, so do not expect this library to handle files larger than 2GB.
562		600
563	=head1 AUTHOR	601	=head1 AUTHOR
564		602
565	Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written	603	Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written
566	by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily	604	by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily
567	bugfixed by Marc Lehmann.	605	bugfixed by Marc Lehmann.
568		606
569	=head1 SEE ALSO	607	=head1 SEE ALSO
570		608
571	perl(1), uudeview homepage at http://www.uni-frankfurt.de/~fp/uudeview/.	609	perl(1), uudeview homepage at L<http://www.fpx.de/fp/Software/UUDeview/>.
572		610
573	=cut	611	=cut
		612

Diff Legend

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

Comparing Convert-UUlib/UUlib.pm (file contents): Revision 1.40 by root, Wed Dec 15 00:10:59 2010 UTC vs. Revision 1.49 by root, Fri Feb 28 17:33:09 2020 UTC

Diff Legend

Comparing Convert-UUlib/UUlib.pm (file contents):
Revision 1.40 by root, Wed Dec 15 00:10:59 2010 UTC vs.
Revision 1.49 by root, Fri Feb 28 17:33:09 2020 UTC