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

Comparing Convert-UUlib/UUlib.pm (file contents):
Revision 1.43 by root, Thu Oct 24 15:18:26 2019 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.6;	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
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, 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
303	=back	301	=back
304		302
305	=head2 Decoding files	303	=head2 Decoding files
306		304
307	=over 4	305	=over
308		306
309	=item $retval = $item->rename($newname)	307	=item $retval = $item->rename ($newname)
310		308
311	Change the ondisk filename where the decoded file will be saved.	309	Change the ondisk filename where the decoded file will be saved.
312		310
313	=item $retval = $item->decode_temp	311	=item $retval = $item->decode_temp
314		312
…		…
317		315
318	=item $retval = $item->remove_temp	316	=item $retval = $item->remove_temp
319		317
320	Remove the temporarily decoded file again.	318	Remove the temporarily decoded file again.
321		319
322	=item $retval = $item->decode([$target_path])	320	=item $retval = $item->decode ([$target_path])
323		321
324	Decode the file to it's destination, or the given target path.	322	Decode the file to its destination, or the given target path.
325		323
326	=item $retval = $item->info(callback-function)	324	=item $retval = $item->info (callback-function)
327		325
328	=back	326	=back
329		327
330	=head2 Querying (and setting) item attributes	328	=head2 Querying (and setting) item attributes
331		329
332	=over 4	330	=over
333		331
334	=item $state = $item->state	332	=item $state = $item->state
335		333
336	=item $mode = $item->mode([newmode])	334	=item $mode = $item->mode ([newmode])
337		335
338	=item $uudet = $item->uudet	336	=item $uudet = $item->uudet
339		337
340	=item $size = $item->size	338	=item $size = $item->size
341		339
342	=item $filename = $item->filename([newfilename})	340	=item $filename = $item->filename ([newfilename})
343		341
344	=item $subfname = $item->subfname	342	=item $subfname = $item->subfname
345		343
346	=item $mimeid = $item->mimeid	344	=item $mimeid = $item->mimeid
347		345
…		…
351		349
352	=back	350	=back
353		351
354	=head2 Information about source parts	352	=head2 Information about source parts
355		353
356	=over 4	354	=over
357		355
358	=item $parts = $item->parts	356	=item $parts = $item->parts
359		357
360	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
361	as a list of hashrefs with the following structure:	359	as a list of hashrefs with the following structure:
…		…
375	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>
376	and C<filename> members.	374	and C<filename> members.
377		375
378	=back	376	=back
379		377
380	=head2 Functions below not documented and not very well tested	378	=head2 Functions below are not documented and not very well tested - feedback welcome
381		379
382	QuickDecode	380	QuickDecode
383	EncodeMulti	381	EncodeMulti
384	EncodePartial	382	EncodePartial
385	EncodeToStream	383	EncodeToStream
…		…
389		387
390	=head2 EXTENSION FUNCTIONS	388	=head2 EXTENSION FUNCTIONS
391		389
392	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:
393		391
394	=over 4	392	=over
395		393
396	=item $msg = straction ACT_xxx	394	=item $msg = straction ACT_xxx
397		395
398	Return a human readable string representing the given action code.	396	Return a human readable string representing the given action code.
399		397
…		…
440		438
441	=back	439	=back
442		440
443	=head1 LARGE EXAMPLE DECODER	441	=head1 LARGE EXAMPLE DECODER
444		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
445	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
446	instead of more thorough documentation.	460	illustrates the above worklfow in a non-trivial example.
447		461
448	#!/usr/bin/perl	462	#!/usr/bin/perl
449		463
450	# decode all the files in the directory uusrc/ and copy	464	# decode all the files in the directory uusrc/ and copy
451	# the resulting files to uudst/	465	# the resulting files to uudst/
…		…
470	SetOption OPT_RBUF, 128*1024;	484	SetOption OPT_RBUF, 128*1024;
471	SetOption OPT_WBUF, 1024*1024;	485	SetOption OPT_WBUF, 1024*1024;
472	SetOption OPT_IGNMODE, 1;	486	SetOption OPT_IGNMODE, 1;
473	SetOption OPT_IGNMODE, 1;	487	SetOption OPT_IGNMODE, 1;
474	SetOption OPT_VERBOSE, 1;	488	SetOption OPT_VERBOSE, 1;
		489	SetOption OPT_AUTOCHK, 0;
475		490
476	# show the three ways you can set callback functions. I normally	491	# show the three ways you can set callback functions. I normally
477	# prefer the one with the sub inplace.	492	# prefer the one with the sub inplace.
478	SetFNameFilter \&namefilter;	493	SetFNameFilter \&namefilter;
479		494
…		…
513	# otherwise just pass what we have	528	# otherwise just pass what we have
514	()	529	()
515	};	530	};
516		531
517	# now read all files in the directory uusrc/*	532	# now read all files in the directory uusrc/*
518	for(<uusrc/*>) {	533	for (<uusrc/*>) {
519	my ($retval, $count) = LoadFile ($_, $_, 1);	534	my ($retval, $count) = LoadFile ($_, $_, 1);
520	print "file($_), status(", strerror $retval, ") parts($count)\n";	535	print "file($_), status(", strerror $retval, ") parts($count)\n";
521	}	536	}
522		537
		538	Smerge -1;
		539
523	SetOption OPT_SAVEPATH, "uudst/";	540	SetOption OPT_SAVEPATH, "uudst/";
524		541
525	# now wade through all files and their source parts	542	# now wade through all files and their source parts
526	$i = 0;	543	for my $uu (GetFileList) {
527	while ($uu = GetFileListItem $i) {	544	print "file ", $uu->filename, "\n";
528	$i++;
529	print "file nr. $i";
530	print " state ", $uu->state;	545	print " state ", $uu->state, "\n";
531	print " mode ", $uu->mode;	546	print " mode ", $uu->mode, "\n";
532	print " uudet ", strencoding $uu->uudet;	547	print " uudet ", strencoding $uu->uudet, "\n";
533	print " size ", $uu->size;	548	print " size ", $uu->size, "\n";
534	print " filename ", $uu->filename;
535	print " subfname ", $uu->subfname;	549	print " subfname ", $uu->subfname, "\n";
536	print " mimeid ", $uu->mimeid;	550	print " mimeid ", $uu->mimeid, "\n";
537	print " mimetype ", $uu->mimetype;	551	print " mimetype ", $uu->mimetype, "\n";
538	print "\n";
539		552
540	# print additional info about all parts	553	# print additional info about all parts
		554	print " parts";
541	for ($uu->parts) {	555	for ($uu->parts) {
542	while (my ($k, $v) = each %$_) {	556	for my $k (sort keys %$_) {
543	print "$k > $v, ";	557	print " $k=$_->{$k}";
544	}	558	}
545	print "\n";	559	print "\n";
546	}	560	}
547		561
548	print $uu->filename;
549
550	$uu->remove_temp;	562	$uu->remove_temp;
551		563
552	if (my $err = $uu->decode ()) {	564	if (my $err = $uu->decode) {
553	print ", ", strerror $err, "\n";	565	print " ERROR ", strerror $err, "\n";
554	} else {	566	} else {
555	print ", saved as uudst/", $uu->filename, "\n";	567	print " successfully saved as uudst/", $uu->filename, "\n";
556	}	568	}
557	}	569	}
558		570
559	print "cleanup...\n";	571	print "cleanup...\n";
560		572
561	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.
562		610
563	=head1 AUTHOR	611	=head1 AUTHOR
564		612
565	Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written	613	Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written
566	by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily	614	by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily
567	bugfixed by Marc Lehmann.	615	bugfixed by Marc Lehmann.
568		616
569	=head1 SEE ALSO	617	=head1 SEE ALSO
570		618
571	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/>.
572		620
573	=cut	621	=cut
		622

Diff Legend

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

Comparing Convert-UUlib/UUlib.pm (file contents): Revision 1.43 by root, Thu Oct 24 15:18:26 2019 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.43 by root, Thu Oct 24 15:18:26 2019 UTC vs.
Revision 1.54 by root, Sat Dec 12 10:48:39 2020 UTC