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

Comparing Convert-UUlib/UUlib.pm (file contents):
Revision 1.35 by root, Mon Aug 24 06:15:00 2009 UTC vs.
Revision 1.48 by root, Fri Feb 28 17:19:02 2020 UTC

…		…
6	use Carp;	6	use Carp;
7		7
8	require Exporter;	8	require Exporter;
9	require DynaLoader;	9	require DynaLoader;
10		10
11	our $VERSION = '1.12';	11	our $VERSION = 1.62;
12		12
13	our @ISA = qw(Exporter DynaLoader);	13	our @ISA = qw(Exporter DynaLoader);
14		14
15	our @_consts = qw(	15	our @_consts = qw(
16	ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING	16	ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING
…		…
34	);	34	);
35		35
36	our @_funcs = qw(	36	our @_funcs = qw(
37	Initialize CleanUp GetOption SetOption strerror SetMsgCallback	37	Initialize CleanUp GetOption SetOption strerror SetMsgCallback
38	SetBusyCallback SetFileCallback SetFNameFilter SetFileNameCallback	38	SetBusyCallback SetFileCallback SetFNameFilter SetFileNameCallback
39	FNameFilter LoadFile GetFileListItem RenameFile DecodeToTemp	39	FNameFilter LoadFile GetFileListItem GetFileList RenameFile DecodeToTemp
40	RemoveTemp DecodeFile InfoFile Smerge QuickDecode EncodeMulti	40	RemoveTemp DecodeFile InfoFile Smerge QuickDecode EncodeMulti
41	EncodePartial EncodeToStream EncodeToFile E_PrepSingle	41	EncodePartial EncodeToStream EncodeToFile E_PrepSingle
42	E_PrepPartial	42	E_PrepPartial
43		43
44	straction strencoding strmsglevel	44	straction strencoding strmsglevel
…		…
48	our @EXPORT_OK = @_funcs;	48	our @EXPORT_OK = @_funcs;
49	our %EXPORT_TAGS = (all => [@_consts,@_funcs], constants => \@_consts);	49	our %EXPORT_TAGS = (all => [@_consts,@_funcs], constants => \@_consts);
50		50
51	bootstrap Convert::UUlib $VERSION;	51	bootstrap Convert::UUlib $VERSION;
52		52
53	Initialize();	53	# dummy function for compatiiblity with pre-1.7 versions
54		54	sub Initialize { }
55	# not when < 5.005_6x
56	# END { CleanUp() }
57		55
58	for (@_consts) {	56	for (@_consts) {
59	my $constant = constant($_);	57	my $constant = constant ($_);
60	no strict 'refs';	58	no strict 'refs';
61	*$_ = sub () { $constant };	59	*$_ = sub () { $constant };
62	}	60	}
63		61
64	# action code -> string mapping	62	# action code -> string mapping
…		…
105	use Convert::UUlib ':all';	103	use Convert::UUlib ':all';
106		104
107	# read all the files named on the commandline and decode them	105	# read all the files named on the commandline and decode them
108	# into the CURRENT directory. See below for a longer example.	106	# into the CURRENT directory. See below for a longer example.
109	LoadFile $_ for @ARGV;	107	LoadFile $_ for @ARGV;
110	for (my $i = 0; my $uu = GetFileListItem $i; $i++) {	108
		109	for my $uu (GetFileList) {
111	if ($uu->state & FILE_OK) {	110	if ($uu->state & FILE_OK) {
112	$uu->decode;	111	$uu->decode;
113	print $uu->filename, "\n";	112	print $uu->filename, "\n";
114	}	113	}
115	}	114	}
…		…
214	again.	213	again.
215		214
216	On my machine, a fairly complete decode with DBI backend needs about 10MB	215	On my machine, a fairly complete decode with DBI backend needs about 10MB
217	RSS to decode 20000 files.	216	RSS to decode 20000 files.
218		217
219	=over 4	218	=over
220
221	=item Initialize
222
223	Not normally necessary, (re-)initializes the library.
224		219
225	=item CleanUp	220	=item CleanUp
226		221
227	Not normally necessary, could be called at the end to release memory	222	Release memory, file items and clean up files. Should be called after a
228	before starting a new decoding round.	223	decoidng run, if you want to start a new one.
229		224
230	=back	225	=back
231		226
232	=head2 Setting and querying options	227	=head2 Setting and querying options
233		228
234	=over 4	229	=over
235		230
236	=item $option = GetOption OPT_xxx	231	=item $option = GetOption OPT_xxx
237		232
238	=item SetOption OPT_xxx, opt-value	233	=item SetOption OPT_xxx, opt-value
239		234
…		…
241		236
242	See the C<OPT_xxx> constants above to see which options exist.	237	See the C<OPT_xxx> constants above to see which options exist.
243		238
244	=head2 Setting various callbacks	239	=head2 Setting various callbacks
245		240
246	=over 4	241	=over
247		242
248	=item SetMsgCallback [callback-function]	243	=item SetMsgCallback [callback-function]
249		244
250	=item SetBusyCallback [callback-function]	245	=item SetBusyCallback [callback-function]
251		246
…		…
255		250
256	=back	251	=back
257		252
258	=head2 Call the currently selected FNameFilter	253	=head2 Call the currently selected FNameFilter
259		254
260	=over 4	255	=over
261		256
262	=item $file = FNameFilter $file	257	=item $file = FNameFilter $file
263		258
264	=back	259	=back
265		260
266	=head2 Loading sourcefiles, optionally fuzzy merge and start decoding	261	=head2 Loading sourcefiles, optionally fuzzy merge and start decoding
267		262
268	=over 4	263	=over
269		264
270	=item ($retval, $count) = LoadFile $fname, [$id, [$delflag, [$partno]]]	265	=item ($retval, $count) = LoadFile $fname, [$id, [$delflag, [$partno]]]
271		266
272	Load the given file and scan it for encoded contents. Optionally tag it	267	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	268	with the given id, and if C<$delflag> is true, delete the file after it
…		…
298		293
299	The first file has number C<0>, and the series has no holes, so you can	294	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	295	iterate over all files by starting with zero and incrementing until you
301	hit C<undef>.	296	hit C<undef>.
302		297
		298	This function has to walk the linear list of fils on each access, so
		299	if you want to iterate over all items, it is usually faster to use
		300	C<GetFileList>.
		301
		302	=item @items = GetFileList
		303
		304	Similar to C<GetFileListItem>, but returns all files in one go.
		305
303	=back	306	=back
304		307
305	=head2 Decoding files	308	=head2 Decoding files
306		309
307	=over 4	310	=over
308		311
309	=item $retval = $item->rename($newname)	312	=item $retval = $item->rename ($newname)
310		313
311	Change the ondisk filename where the decoded file will be saved.	314	Change the ondisk filename where the decoded file will be saved.
312		315
313	=item $retval = $item->decode_temp	316	=item $retval = $item->decode_temp
314		317
…		…
317		320
318	=item $retval = $item->remove_temp	321	=item $retval = $item->remove_temp
319		322
320	Remove the temporarily decoded file again.	323	Remove the temporarily decoded file again.
321		324
322	=item $retval = $item->decode([$target_path])	325	=item $retval = $item->decode ([$target_path])
323		326
324	Decode the file to it's destination, or the given target path.	327	Decode the file to its destination, or the given target path.
325		328
326	=item $retval = $item->info(callback-function)	329	=item $retval = $item->info (callback-function)
327		330
328	=back	331	=back
329		332
330	=head2 Querying (and setting) item attributes	333	=head2 Querying (and setting) item attributes
331		334
332	=over 4	335	=over
333		336
334	=item $state = $item->state	337	=item $state = $item->state
335		338
336	=item $mode = $item->mode([newmode])	339	=item $mode = $item->mode ([newmode])
337		340
338	=item $uudet = $item->uudet	341	=item $uudet = $item->uudet
339		342
340	=item $size = $item->size	343	=item $size = $item->size
341		344
342	=item $filename = $item->filename([newfilename})	345	=item $filename = $item->filename ([newfilename})
343		346
344	=item $subfname = $item->subfname	347	=item $subfname = $item->subfname
345		348
346	=item $mimeid = $item->mimeid	349	=item $mimeid = $item->mimeid
347		350
…		…
351		354
352	=back	355	=back
353		356
354	=head2 Information about source parts	357	=head2 Information about source parts
355		358
356	=over 4	359	=over
357		360
358	=item $parts = $item->parts	361	=item $parts = $item->parts
359		362
360	Return information about all parts (source files) used to decode the file	363	Return information about all parts (source files) used to decode the file
361	as a list of hashrefs with the following structure:	364	as a list of hashrefs with the following structure:
…		…
375	Usually you are interested mostly the C<sfname> and possibly the C<partno>	378	Usually you are interested mostly the C<sfname> and possibly the C<partno>
376	and C<filename> members.	379	and C<filename> members.
377		380
378	=back	381	=back
379		382
380	=head2 Functions below not documented and not very well tested	383	=head2 Functions below are not documented and not very well tested - feedback welcome
381		384
382	QuickDecode	385	QuickDecode
383	EncodeMulti	386	EncodeMulti
384	EncodePartial	387	EncodePartial
385	EncodeToStream	388	EncodeToStream
…		…
389		392
390	=head2 EXTENSION FUNCTIONS	393	=head2 EXTENSION FUNCTIONS
391		394
392	Functions found in this module but not documented in the uulib documentation:	395	Functions found in this module but not documented in the uulib documentation:
393		396
394	=over 4	397	=over
395		398
396	=item $msg = straction ACT_xxx	399	=item $msg = straction ACT_xxx
397		400
398	Return a human readable string representing the given action code.	401	Return a human readable string representing the given action code.
399		402
…		…
440		443
441	=back	444	=back
442		445
443	=head1 LARGE EXAMPLE DECODER	446	=head1 LARGE EXAMPLE DECODER
444		447
		448	The general workflow for decoding is like this:
		449
		450	=over
		451
		452	=item 1. Configure options with C<SetOption> or C<SetXXXCallback>.
		453
		454	=item 2. Load all source files with C<LoadFile>.
		455
		456	=item 3. Optionally C<Smerge>.
		457
		458	=item 4. Iterate over all C<GetFileList> items (i.e. result files).
		459
		460	=item 5. C<CleanUp> to delete files and free items.
		461
		462	=back
		463
445	This is the file C<example-decoder> from the distribution, put here	464	What follows is the file C<example-decoder> from the distribution that
446	instead of more thorough documentation.	465	illustrates the above worklfow in a non-trivial example.
447		466
448	#!/usr/bin/perl	467	#!/usr/bin/perl
449		468
450	# decode all the files in the directory uusrc/ and copy	469	# decode all the files in the directory uusrc/ and copy
451	# the resulting files to uudst/	470	# the resulting files to uudst/
…		…
513	# otherwise just pass what we have	532	# otherwise just pass what we have
514	()	533	()
515	};	534	};
516		535
517	# now read all files in the directory uusrc/*	536	# now read all files in the directory uusrc/*
518	for(<uusrc/*>) {	537	for (<uusrc/*>) {
519	my ($retval, $count) = LoadFile ($_, $_, 1);	538	my ($retval, $count) = LoadFile ($_, $_, 1);
520	print "file($_), status(", strerror $retval, ") parts($count)\n";	539	print "file($_), status(", strerror $retval, ") parts($count)\n";
521	}	540	}
522		541
523	SetOption OPT_SAVEPATH, "uudst/";	542	SetOption OPT_SAVEPATH, "uudst/";
524		543
525	# now wade through all files and their source parts	544	# now wade through all files and their source parts
526	$i = 0;	545	for my $uu (GetFileList) {
527	while ($uu = GetFileListItem $i) {	546	print "file ", $uu->filename, "\n";
528	$i++;
529	print "file nr. $i";
530	print " state ", $uu->state;	547	print " state ", $uu->state, "\n";
531	print " mode ", $uu->mode;	548	print " mode ", $uu->mode, "\n";
532	print " uudet ", strencoding $uu->uudet;	549	print " uudet ", strencoding $uu->uudet, "\n";
533	print " size ", $uu->size;	550	print " size ", $uu->size, "\n";
534	print " filename ", $uu->filename;
535	print " subfname ", $uu->subfname;	551	print " subfname ", $uu->subfname, "\n";
536	print " mimeid ", $uu->mimeid;	552	print " mimeid ", $uu->mimeid, "\n";
537	print " mimetype ", $uu->mimetype;	553	print " mimetype ", $uu->mimetype, "\n";
538	print "\n";
539		554
540	# print additional info about all parts	555	# print additional info about all parts
		556	print " parts";
541	for ($uu->parts) {	557	for ($uu->parts) {
542	while (my ($k, $v) = each %$_) {	558	for my $k (sort keys %$_) {
543	print "$k > $v, ";	559	print " $k=$_->{$k}";
544	}	560	}
545	print "\n";	561	print "\n";
546	}	562	}
547		563
548	print $uu->filename;
549
550	$uu->remove_temp;	564	$uu->remove_temp;
551		565
552	if (my $err = $uu->decode ()) {	566	if (my $err = $uu->decode) {
553	print ", ", strerror $err, "\n";	567	print " ERROR ", strerror $err, "\n";
554	} else {	568	} else {
555	print ", saved as uudst/", $uu->filename, "\n";	569	print " successfully saved as uudst/", $uu->filename, "\n";
556	}	570	}
557	}	571	}
558		572
559	print "cleanup...\n";	573	print "cleanup...\n";
560		574
561	CleanUp;	575	CleanUp;
		576
		577	=head1 PERLMULTICORE SUPPORT
		578
		579	This module supports the perlmulticore standard (see
		580	L<http://perlmulticore.schmorp.de/> for more info) for the following
		581	functions - generally these are functions accessing the disk and/or using
		582	considerable CPU time:
		583
		584	LoadFile
		585	$item->decode
		586	$item->decode_temp
		587	$item->remove_temp
		588	$item->info
		589
		590	The perl interpreter will be reacquired/released on every callback
		591	invocation, so for performance reasons, callbacks should be avoided if
		592	that is costly.
		593
		594	Future versions might enable multicore support for more functions.
		595
		596	=head1 BUGS AND LIMITATIONS
		597
		598	The original uulib library this module uses was written at a time where
		599	main memory of measured in megabytes and buffer overflows as a security
		600	thign didn't exist. While a lot of security fixes have been applied over
		601	the years (includign some defense in depth mechanism that can shield
		602	against a lot of as-of-yet undetected bugs), using this library for
		603	security purposes requires care.
		604
		605	Likewise, file sizes when the uulib library was written were tiny compared
		606	to today, so do not expect this library to handle files larger than 2GB.
562		607
563	=head1 AUTHOR	608	=head1 AUTHOR
564		609
565	Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written	610	Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written
566	by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily	611	by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily
567	bugfixed by Marc Lehmann.	612	bugfixed by Marc Lehmann.
568		613
569	=head1 SEE ALSO	614	=head1 SEE ALSO
570		615
571	perl(1), uudeview homepage at http://www.uni-frankfurt.de/~fp/uudeview/.	616	perl(1), uudeview homepage at L<http://www.fpx.de/fp/Software/UUDeview/>.
572		617
573	=cut	618	=cut
		619

Diff Legend

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

Comparing Convert-UUlib/UUlib.pm (file contents): Revision 1.35 by root, Mon Aug 24 06:15:00 2009 UTC vs. Revision 1.48 by root, Fri Feb 28 17:19:02 2020 UTC

Diff Legend

Comparing Convert-UUlib/UUlib.pm (file contents):
Revision 1.35 by root, Mon Aug 24 06:15:00 2009 UTC vs.
Revision 1.48 by root, Fri Feb 28 17:19:02 2020 UTC