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.53 by root, Sat Dec 12 02:03:14 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;
10 9
11our $VERSION = 1.62; 10our $VERSION = 1.71;
12 11
13our @ISA = qw(Exporter DynaLoader); 12our @ISA = qw(Exporter DynaLoader);
14 13
15our @_consts = qw( 14our @_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
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/
… …
470 SetOption OPT_RBUF, 128*1024; 482 SetOption OPT_RBUF, 128*1024;
471 SetOption OPT_WBUF, 1024*1024; 483 SetOption OPT_WBUF, 1024*1024;
472 SetOption OPT_IGNMODE, 1; 484 SetOption OPT_IGNMODE, 1;
473 SetOption OPT_IGNMODE, 1; 485 SetOption OPT_IGNMODE, 1;
474 SetOption OPT_VERBOSE, 1; 486 SetOption OPT_VERBOSE, 1;
487 SetOption OPT_AUTOCHK, 0;
475 488
476 # show the three ways you can set callback functions. I normally 489 # show the three ways you can set callback functions. I normally
477 # prefer the one with the sub inplace. 490 # prefer the one with the sub inplace.
478 SetFNameFilter \&namefilter; 491 SetFNameFilter \&namefilter;
479 492
… …
513 # otherwise just pass what we have 526 # otherwise just pass what we have
514 () 527 ()
515 }; 528 };
516 529
517 # now read all files in the directory uusrc/* 530 # now read all files in the directory uusrc/*
518 for(<uusrc/*>) { 531 for (<uusrc/*>) {
519 my ($retval, $count) = LoadFile ($_, $_, 1); 532 my ($retval, $count) = LoadFile ($_, $_, 1);
520 print "file($_), status(", strerror $retval, ") parts($count)\n"; 533 print "file($_), status(", strerror $retval, ") parts($count)\n";
521 } 534 }
522 535
536 Smerge -1;
537
523 SetOption OPT_SAVEPATH, "uudst/"; 538 SetOption OPT_SAVEPATH, "uudst/";
524 539
525 # now wade through all files and their source parts 540 # now wade through all files and their source parts
526 $i = 0; 541 for my $uu (GetFileList) {
527 while ($uu = GetFileListItem $i) { 542 print "file ", $uu->filename, "\n";
528 $i++;
529 print "file nr. $i";
530 print " state ", $uu->state; 543 print " state ", $uu->state, "\n";
531 print " mode ", $uu->mode; 544 print " mode ", $uu->mode, "\n";
532 print " uudet ", strencoding $uu->uudet; 545 print " uudet ", strencoding $uu->uudet, "\n";
533 print " size ", $uu->size; 546 print " size ", $uu->size, "\n";
534 print " filename ", $uu->filename;
535 print " subfname ", $uu->subfname; 547 print " subfname ", $uu->subfname, "\n";
536 print " mimeid ", $uu->mimeid; 548 print " mimeid ", $uu->mimeid, "\n";
537 print " mimetype ", $uu->mimetype; 549 print " mimetype ", $uu->mimetype, "\n";
538 print "\n";
539 550
540 # print additional info about all parts 551 # print additional info about all parts
552 print " parts";
541 for ($uu->parts) { 553 for ($uu->parts) {
542 while (my ($k, $v) = each %$_) { 554 for my $k (sort keys %$_) {
543 print "$k > $v, "; 555 print " $k=$_->{$k}";
544 } 556 }
545 print "\n"; 557 print "\n";
546 } 558 }
547 559
548 print $uu->filename;
549
550 $uu->remove_temp; 560 $uu->remove_temp;
551 561
552 if (my $err = $uu->decode ()) { 562 if (my $err = $uu->decode) {
553 print ", ", strerror $err, "\n"; 563 print " ERROR ", strerror $err, "\n";
554 } else { 564 } else {
555 print ", saved as uudst/", $uu->filename, "\n"; 565 print " successfully saved as uudst/", $uu->filename, "\n";
556 } 566 }
557 } 567 }
558 568
559 print "cleanup...\n"; 569 print "cleanup...\n";
560 570
… …
589security purposes requires care. 599security purposes requires care.
590 600
591Likewise, file sizes when the uulib library was written were tiny compared 601Likewise, 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. 602to today, so do not expect this library to handle files larger than 2GB.
593 603
604Lastly, this module uses a very "C-like" interface, which means it doesn't
605protect you from invalid points as you might expect from "more perlish"
606modules - for example, accessing a file item object after callinbg
607C<CleanUp> will likely result in crashes, memory corruption, or worse.
608
594=head1 AUTHOR 609=head1 AUTHOR
595 610
596Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written 611Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written
597by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily 612by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily
598bugfixed by Marc Lehmann. 613bugfixed by Marc Lehmann.

Diff Legend

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