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.47 by root, Fri Feb 28 16: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
… …
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;
101
110 for my $uu (GetFileList) { 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 }
… …
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
… …
304if you want to iterate over all items, it is usually faster to use 292if you want to iterate over all items, it is usually faster to use
305C<GetFileList>. 293C<GetFileList>.
306 294
307=item @items = GetFileList 295=item @items = GetFileList
308 296
309Similar to C<GetFileListItem>, but returns all files in one go. 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.
310 300
311=back 301=back
312 302
313=head2 Decoding files 303=head2 Decoding files
314 304
… …
448 438
449=back 439=back
450 440
451=head1 LARGE EXAMPLE DECODER 441=head1 LARGE EXAMPLE DECODER
452 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
453This is the file C<example-decoder> from the distribution, put here 459What follows is the file C<example-decoder> from the distribution that
454instead of more thorough documentation. 460illustrates the above worklfow in a non-trivial example.
455 461
456 #!/usr/bin/perl 462 #!/usr/bin/perl
457 463
458 # decode all the files in the directory uusrc/ and copy 464 # decode all the files in the directory uusrc/ and copy
459 # the resulting files to uudst/ 465 # the resulting files to uudst/
… …
478 SetOption OPT_RBUF, 128*1024; 484 SetOption OPT_RBUF, 128*1024;
479 SetOption OPT_WBUF, 1024*1024; 485 SetOption OPT_WBUF, 1024*1024;
480 SetOption OPT_IGNMODE, 1; 486 SetOption OPT_IGNMODE, 1;
481 SetOption OPT_IGNMODE, 1; 487 SetOption OPT_IGNMODE, 1;
482 SetOption OPT_VERBOSE, 1; 488 SetOption OPT_VERBOSE, 1;
489 SetOption OPT_AUTOCHK, 0;
483 490
484 # show the three ways you can set callback functions. I normally 491 # show the three ways you can set callback functions. I normally
485 # prefer the one with the sub inplace. 492 # prefer the one with the sub inplace.
486 SetFNameFilter \&namefilter; 493 SetFNameFilter \&namefilter;
487 494
… …
525 # now read all files in the directory uusrc/* 532 # now read all files in the directory uusrc/*
526 for (<uusrc/*>) { 533 for (<uusrc/*>) {
527 my ($retval, $count) = LoadFile ($_, $_, 1); 534 my ($retval, $count) = LoadFile ($_, $_, 1);
528 print "file($_), status(", strerror $retval, ") parts($count)\n"; 535 print "file($_), status(", strerror $retval, ") parts($count)\n";
529 } 536 }
537
538 Smerge -1;
530 539
531 SetOption OPT_SAVEPATH, "uudst/"; 540 SetOption OPT_SAVEPATH, "uudst/";
532 541
533 # now wade through all files and their source parts 542 # now wade through all files and their source parts
534 for my $uu (GetFileList) { 543 for my $uu (GetFileList) {
… …
592security purposes requires care. 601security purposes requires care.
593 602
594Likewise, file sizes when the uulib library was written were tiny compared 603Likewise, file sizes when the uulib library was written were tiny compared
595to 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.
596 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
597=head1 AUTHOR 611=head1 AUTHOR
598 612
599Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written 613Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written
600by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily 614by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily
601bugfixed by Marc Lehmann. 615bugfixed by Marc Lehmann.

Diff Legend

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