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.46 by root, Fri Feb 28 06:57:25 2020 UTC vs.
Revision 1.50 by root, Fri Feb 28 18:02:01 2020 UTC

1package Convert::UUlib; 1package Convert::UUlib;
2 2
3no warnings; 3use common::sense;
4use strict;
5 4
6use Carp; 5use Carp;
7 6
8require Exporter; 7require Exporter;
9require DynaLoader; 8require DynaLoader;
… …
34); 33);
35 34
36our @_funcs = qw( 35our @_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
… …
48our @EXPORT_OK = @_funcs; 47our @EXPORT_OK = @_funcs;
49our %EXPORT_TAGS = (all => [@_consts,@_funcs], constants => \@_consts); 48our %EXPORT_TAGS = (all => [@_consts,@_funcs], constants => \@_consts);
50 49
51bootstrap Convert::UUlib $VERSION; 50bootstrap Convert::UUlib $VERSION;
52 51
53Initialize(); 52# dummy function for compatiiblity with pre-1.7 versions
54 53sub Initialize { }
55# not when < 5.005_6x
56# END { CleanUp() }
57
58for (@_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
65sub straction($) { 56sub 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 }
… …
216On my machine, a fairly complete decode with DBI backend needs about 10MB 208On my machine, a fairly complete decode with DBI backend needs about 10MB
217RSS to decode 20000 files. 209RSS to decode 20000 files.
218 210
219=over 211=over
220 212
221=item Initialize
222
223Not normally necessary, (re-)initializes the library.
224
225=item CleanUp 213=item CleanUp
226 214
227Not normally necessary, could be called at the end to release memory 215Release memory, file items and clean up files. Should be called after a
228before starting a new decoding round. 216decoidng 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
… …
297C<undef> of no file with that number exists. 285C<undef> of no file with that number exists.
298 286
299The first file has number C<0>, and the series has no holes, so you can 287The first file has number C<0>, and the series has no holes, so you can
300iterate over all files by starting with zero and incrementing until you 288iterate over all files by starting with zero and incrementing until you
301hit C<undef>. 289hit C<undef>.
290
291This function has to walk the linear list of fils on each access, so
292if you want to iterate over all items, it is usually faster to use
293C<GetFileList>.
294
295=item @items = GetFileList
296
297Similar to C<GetFileListItem>, but returns all files in one go.
302 298
303=back 299=back
304 300
305=head2 Decoding files 301=head2 Decoding files
306 302
… …
440 436
441=back 437=back
442 438
443=head1 LARGE EXAMPLE DECODER 439=head1 LARGE EXAMPLE DECODER
444 440
441The 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
445This is the file C<example-decoder> from the distribution, put here 457What follows is the file C<example-decoder> from the distribution that
446instead of more thorough documentation. 458illustrates 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
… …
589security purposes requires care. 596security purposes requires care.
590 597
591Likewise, file sizes when the uulib library was written were tiny compared 598Likewise, file sizes when the uulib library was written were tiny compared
592to today, so do not expect this library to handle files larger than 2GB. 599to today, so do not expect this library to handle files larger than 2GB.
593 600
601Lastly, this module uses a very "C-like" interface, which means it doesn't
602protect you from invalid points as you might expect from "more perlish"
603modules - for example, accessing a file item object after callinbg
604C<CleanUp> will likely result in crashes, memory corruption, or worse.
605
594=head1 AUTHOR 606=head1 AUTHOR
595 607
596Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written 608Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written
597by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily 609by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily
598bugfixed by Marc Lehmann. 610bugfixed by Marc Lehmann.

Diff Legend

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