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.54 by root, Sat Dec 12 10:48:39 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, which is
298very much faster for large number of items, and has no drawbacks when used
299for a small number of items.
302 300
303=back 301=back
304 302
305=head2 Decoding files 303=head2 Decoding files
306 304
… …
440 438
441=back 439=back
442 440
443=head1 LARGE EXAMPLE DECODER 441=head1 LARGE EXAMPLE DECODER
444 442
443The 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
445This is the file C<example-decoder> from the distribution, put here 459What follows is the file C<example-decoder> from the distribution that
446instead of more thorough documentation. 460illustrates 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
… …
589security purposes requires care. 601security purposes requires care.
590 602
591Likewise, file sizes when the uulib library was written were tiny compared 603Likewise, 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. 604to today, so do not expect this library to handle files larger than 2GB.
593 605
606Lastly, this module uses a very "C-like" interface, which means it doesn't
607protect you from invalid points as you might expect from "more perlish"
608modules - for example, accessing a file item object after callinbg
609C<CleanUp> will likely result in crashes, memory corruption, or worse.
610
594=head1 AUTHOR 611=head1 AUTHOR
595 612
596Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written 613Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written
597by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily 614by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily
598bugfixed by Marc Lehmann. 615bugfixed by Marc Lehmann.

Diff Legend

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