Convert-UUlib/UUlib.pm

package Convert::UUlib;

use Carp;

require Exporter;
require DynaLoader;
use AutoLoader;

$VERSION = 0.212;

@ISA = qw(Exporter DynaLoader);

@_consts = qw(
        ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING

        FILE_DECODED FILE_ERROR FILE_MISPART FILE_NOBEGIN FILE_NODATA
        FILE_NOEND FILE_OK FILE_READ FILE_TMPFILE

        MSG_ERROR MSG_FATAL MSG_MESSAGE MSG_NOTE MSG_PANIC MSG_WARNING

        OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS OPT_ENCEXT
        OPT_ERRNO OPT_FAST OPT_IGNMODE OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB
        OPT_PROGRESS OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE
        OPT_VERSION OPT_REMOVE OPT_MOREMIME OPT_DOTDOT

        RET_CANCEL RET_CONT RET_EXISTS RET_ILLVAL RET_IOERR RET_NODATA
        RET_NOEND RET_NOMEM RET_OK RET_UNSUP

        B64ENCODED BH_ENCODED PT_ENCODED QP_ENCODED
        XX_ENCODED UU_ENCODED YENC_ENCODED
);

@_funcs = qw(
        Initialize CleanUp GetOption SetOption strerror SetMsgCallback
        SetBusyCallback SetFileCallback SetFNameFilter SetFileNameCallback
        FNameFilter LoadFile GetFileListItem RenameFile DecodeToTemp
        RemoveTemp DecodeFile InfoFile Smerge QuickDecode EncodeMulti
        EncodePartial EncodeToStream EncodeToFile E_PrepSingle
        E_PrepPartial

        straction strencoding strmsglevel
);

@EXPORT = @_consts;
@EXPORT_OK = @_funcs;
%EXPORT_TAGS = (all => [@_consts,@_funcs], constants => \@_consts);

bootstrap Convert::UUlib $VERSION;

Initialize();

# not when < 5.005_6x
# END { CleanUp() }

for (@_consts) {
   my $constant = constant($_);
   *$_ = sub () { $constant };
}

# action code -> string mapping
sub straction($) {
   return 'copying'     if $_[0] == &ACT_COPYING;
   return 'decoding'    if $_[0] == &ACT_DECODING;
   return 'encoding'    if $_[0] == &ACT_ENCODING;
   return 'idle'        if $_[0] == &ACT_IDLE;
   return 'scanning'    if $_[0] == &ACT_SCANNING;
   'unknown';
}

# encoding type -> string mapping
sub strencoding($) {
   return 'uuencode'            if $_[0] == &UU_ENCODED;
   return 'base64'              if $_[0] == &B64ENCODED;
   return 'yenc'                if $_[0] == &YENC_ENCODED;
   return 'binhex'              if $_[0] == &BH_ENCODED;
   return 'plaintext'           if $_[0] == &PT_ENCODED;
   return 'quoted-printable'    if $_[0] == &QP_ENCODED;
   return 'xxencode'            if $_[0] == &XX_ENCODED;
   'unknown';
}

sub strmsglevel($) {
   return 'message'     if $_[0] == &MSG_MESSAGE;
   return 'note'        if $_[0] == &MSG_NOTE;
   return 'warning'     if $_[0] == &MSG_WARNING;
   return 'error'       if $_[0] == &MSG_ERROR;
   return 'panic'       if $_[0] == &MSG_PANIC;
   return 'fatal'       if $_[0] == &MSG_FATAL;
   'unknown';
}

1;
__END__

=head1 NAME

Convert::UUlib - Perl interface to the uulib library (a.k.a. uudeview/uuenview).

=head1 SYNOPSIS

  use Convert::UUlib;

=head1 DESCRIPTION

Read the file uulibdoc.dvi.gz and the example-decoder source. Sorry - more
to come once people use me ;)

=head1 SMALL EXAMPLE DECODER

The following code excerpt is a minimal decoder program. It reads all
files given on the commandline and decodes any files in it.

 use Convert::UUlib ':all';
 
 LoadFile($_) for @ARGV;
 
 for($i=0; $uu=GetFileListItem($i); $i++) {
    $uu->decode if $uu->state & FILE_OK;
 }

=head1 LARGE EXAMPLE DECODER

This is the file C<example-decoder> from the distribution, put here
instead of more thorough documentation.

 # decode all the files in the directory uusrc/ and copy
 # the resulting files to uudst/

 use Convert::UUlib ':all';

 sub namefilter {
    my($path)=@_;
    $path=~s/^.*[\/\\]//;
    $path;
 }

 sub busycb {
    my($action,$curfile,$partno,$numparts,$percent,$fsize)=@_;
    $_[0]=straction($action);
    print "busy_callback(",join(",",@_),")\n";
    0;
 }

 SetOption (OPT_IGNMODE, 1);
 SetOption (OPT_VERBOSE, 1);

 # show the three ways you can set callback functions
 SetFNameFilter (\&namefilter);

 SetBusyCallback ("busycb",333);

 SetMsgCallback (sub {
    my($msg,$level)=@_;
    print uc(strmsglevel($_[1])),": $msg\n";
 });

 for(<uusrc/*>) {
    my($retval,$count)=LoadFile ($_,$_,1);
    print "file($_), status(",strerror($retval),") parts($count)\n";
 }

 SetOption (OPT_SAVEPATH, "uudst/");

 $i=0;
 while($uu=GetFileListItem($i)) {
    $i++;
    print "file nr. $i";
    print " state ",$uu->state;
    print " mode ",$uu->mode;
    print " uudet ",strencoding($uu->uudet);
    print " size ",$uu->size;
    print " filename ",$uu->filename;
    print " subfname ",$uu->subfname;
    print " mimeid ",$uu->mimeid;
    print " mimetype ",$uu->mimetype;
    print "\n";

    # print additional info about all parts
    for($uu->parts) {
       while(my($k,$v)=each(%$_)) {
          print "$k > $v, ";
       }
       print "\n";
    }

    $uu->decode_temp;
    print " temporarily decoded to ",$uu->binfile,"\n";
    $uu->remove_temp;

    print strerror($uu->decode);
    print " saved as uudst/",$uu->filename,"\n";
 }

 print "cleanup...\n";

 CleanUp();

=head1 Exported constants

Action code constants:

  ACT_COPYING ACT_DECODING ACT_ENCODING
  ACT_IDLE    ACT_SCANNING

File status flags:

  FILE_DECODED FILE_ERROR  FILE_MISPART
  FILE_NOBEGIN FILE_NODATA FILE_NOEND
  FILE_OK      FILE_READ   FILE_TMPFILE

Message severity levels:

  MSG_ERROR MSG_FATAL MSG_MESSAGE
  MSG_NOTE  MSG_PANIC MSG_WARNING

Options:

  OPT_BRACKPOL OPT_DEBUG     OPT_DESPERATE OPT_DUMBNESS
  OPT_ENCEXT   OPT_ERRNO     OPT_FAST      OPT_IGNMODE
  OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB    OPT_PROGRESS
  OPT_SAVEPATH OPT_TINYB64   OPT_USETEXT   OPT_VERBOSE
  OPT_VERSION  OPT_REMOVE    OPT_MOREMIME

Error/Result codes:

  RET_CANCEL RET_CONT  RET_EXISTS RET_ILLVAL RET_IOERR
  RET_NODATA RET_NOEND RET_NOMEM  RET_OK     RET_UNSUP

Encoding types:

  B64ENCODED BH_ENCODED PT_ENCODED QP_ENCODED XX_ENCODED
  UU_ENCODED YENC_ENCODED

=head1 Exported functions

Initializing and cleanup (Initialize is automatically called when the
module is loaded and allocates quite a bit of memory. CleanUp releases
that again).

  Initialize; # not normally necessary
  CleanUp;    # could be called at the end to release memory

Setting and querying options:

  $option = GetOption OPT_xxx;
  SetOption OPT_xxx, opt-value;

Error and action values => stringified:

  $msg = straction ACT_xxx;
  $msg = strerror RET_xxx;

Setting various callbacks:

  SetMsgCallback [callback-function];
  SetBusyCallback [callback-function];
  SetFileCallback [callback-function];
  SetFNameFilter [callback-function];

Call the currently selected FNameFilter:

  $file = FNameFilter $file;

Loading sourcefiles, optionally fuzzy merge and start decoding:

  ($retval, $count) = LoadFile $fname, [$id, [$delflag]];
  $retval = Smerge $pass;
  $item = GetFileListItem $item_number;

The procedural interface is undocumented, use the following methods instead:

  $retval = $item->rename($newname);
  $retval = $item->decode_temp;
  $retval = $item->remove_temp;
  $retval = $item->decode([$target_path]);
  $retval = $item->info(callback-function);

Querying (and setting) item attributes:

  $state    = $item->state;
  $mode     = $item->mode([newmode]);
  $uudet    = $item->uudet;
  $size     = $item->size;
  $filename = $item->filename([newfilename});
  $subfname = $item->subfname;
  $mimeid   = $item->mimeid;
  $mimetype = $item->mimetype;
  $binfile  = $item->binfile;

Totally undocumented and unsupported(!):

  $parts = $item->parts;

Functions below not documented and not very well tested:

  int     QuickDecode           () ;
  int     EncodeMulti           () ;
  int     EncodePartial () ;
  int     EncodeToStream        () ;
  int     EncodeToFile          () ;
  int     E_PrepSingle          () ;
  int     E_PrepPartial () ;

=head2 EXTENSION FUNCTIONS

Functions found in this module but not documented in the uulib documentation:

=over 4

=item SetFileNameCallback $cb

Sets (or queries) the FileNameCallback, which is called whenever the
decoding library can't find a filename and wants to extract a filename
from the subject line of a posting. The callback will be called with
two arguments, the subject line and the current candidate for the
filename. The latter argument can be C<undef>, which means that no
filename could be found (and likely no one exists, so it is safe to also
return C<undef> in this case). If it doesn't return anything (not even
C<undef>!), then nothing happens, so this is a no-op callback:

   sub cb {
      return ();
   }

If it returns C<undef>, then this indicates that no filename could be
found. In all other cases, the return value is taken to be the filename.

This is a slightly more useful callback:

  sub cb {
     return unless $_[1]; # skip "Re:"-plies et al.
     my ($subject, $filename) = @_;
     # if we find some *.rar, take it
     return $1 if $subject =~ /(\w+\.rar)/;
     # otherwise just pass what we have
     return ();
  }

=back

=head1 AUTHOR

Marc Lehmann <pcg@goof.com>, the original uulib library was written by
Frank Pilhofer <fp@informatik.uni-frankfurt.de>.

=head1 SEE ALSO

perl(1), uudeview homepage at http://www.uni-frankfurt.de/~fp/uudeview/.

=cut
Revision:	1.9
Committed:	Sat Apr 6 02:28:35 2002 UTC (22 years, 1 month ago) by root
Branch:	MAIN
Changes since 1.8:	+1 -1 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	package Convert::UUlib;
2
3			use Carp;
4
5			require Exporter;
6			require DynaLoader;
7			use AutoLoader;
8
9	root	1.9	$VERSION = 0.212;
10	root	1.1
11			@ISA = qw(Exporter DynaLoader);
12
13			@_consts = qw(
14			ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING
15
16			FILE_DECODED FILE_ERROR FILE_MISPART FILE_NOBEGIN FILE_NODATA
17			FILE_NOEND FILE_OK FILE_READ FILE_TMPFILE
18
19			MSG_ERROR MSG_FATAL MSG_MESSAGE MSG_NOTE MSG_PANIC MSG_WARNING
20
21			OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS OPT_ENCEXT
22			OPT_ERRNO OPT_FAST OPT_IGNMODE OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB
23			OPT_PROGRESS OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE
24	root	1.8	OPT_VERSION OPT_REMOVE OPT_MOREMIME OPT_DOTDOT
25	root	1.1
26			RET_CANCEL RET_CONT RET_EXISTS RET_ILLVAL RET_IOERR RET_NODATA
27			RET_NOEND RET_NOMEM RET_OK RET_UNSUP
28
29			B64ENCODED BH_ENCODED PT_ENCODED QP_ENCODED
30	root	1.5	XX_ENCODED UU_ENCODED YENC_ENCODED
31	root	1.1	);
32
33			@_funcs = qw(
34	root	1.6	Initialize CleanUp GetOption SetOption strerror SetMsgCallback
35			SetBusyCallback SetFileCallback SetFNameFilter SetFileNameCallback
36			FNameFilter LoadFile GetFileListItem RenameFile DecodeToTemp
37			RemoveTemp DecodeFile InfoFile Smerge QuickDecode EncodeMulti
38			EncodePartial EncodeToStream EncodeToFile E_PrepSingle
39			E_PrepPartial
40	root	1.1
41			straction strencoding strmsglevel
42			);
43
44			@EXPORT = @_consts;
45			@EXPORT_OK = @_funcs;
46			%EXPORT_TAGS = (all => [@_consts,@_funcs], constants => \@_consts);
47
48			bootstrap Convert::UUlib $VERSION;
49
50			Initialize();
51
52			# not when < 5.005_6x
53			# END { CleanUp() }
54
55			for (@_consts) {
56			my $constant = constant($_);
57			*$_ = sub () { $constant };
58			}
59
60			# action code -> string mapping
61			sub straction($) {
62			return 'copying' if $_[0] == &ACT_COPYING;
63			return 'decoding' if $_[0] == &ACT_DECODING;
64			return 'encoding' if $_[0] == &ACT_ENCODING;
65			return 'idle' if $_[0] == &ACT_IDLE;
66			return 'scanning' if $_[0] == &ACT_SCANNING;
67	root	1.5	'unknown';
68	root	1.1	}
69
70			# encoding type -> string mapping
71			sub strencoding($) {
72	root	1.5	return 'uuencode' if $_[0] == &UU_ENCODED;
73	root	1.1	return 'base64' if $_[0] == &B64ENCODED;
74	root	1.5	return 'yenc' if $_[0] == &YENC_ENCODED;
75	root	1.1	return 'binhex' if $_[0] == &BH_ENCODED;
76			return 'plaintext' if $_[0] == &PT_ENCODED;
77			return 'quoted-printable' if $_[0] == &QP_ENCODED;
78			return 'xxencode' if $_[0] == &XX_ENCODED;
79	root	1.5	'unknown';
80	root	1.1	}
81
82			sub strmsglevel($) {
83			return 'message' if $_[0] == &MSG_MESSAGE;
84			return 'note' if $_[0] == &MSG_NOTE;
85			return 'warning' if $_[0] == &MSG_WARNING;
86			return 'error' if $_[0] == &MSG_ERROR;
87			return 'panic' if $_[0] == &MSG_PANIC;
88			return 'fatal' if $_[0] == &MSG_FATAL;
89	root	1.5	'unknown';
90	root	1.1	}
91
92			1;
93			__END__
94
95			=head1 NAME
96
97			Convert::UUlib - Perl interface to the uulib library (a.k.a. uudeview/uuenview).
98
99			=head1 SYNOPSIS
100
101			use Convert::UUlib;
102
103			=head1 DESCRIPTION
104
105			Read the file uulibdoc.dvi.gz and the example-decoder source. Sorry - more
106			to come once people use me ;)
107
108			=head1 SMALL EXAMPLE DECODER
109
110			The following code excerpt is a minimal decoder program. It reads all
111			files given on the commandline and decodes any files in it.
112
113			use Convert::UUlib ':all';
114
115			LoadFile($_) for @ARGV;
116
117			for($i=0; $uu=GetFileListItem($i); $i++) {
118			$uu->decode if $uu->state & FILE_OK;
119			}
120
121			=head1 LARGE EXAMPLE DECODER
122
123			This is the file C<example-decoder> from the distribution, put here
124			instead of more thorough documentation.
125
126			# decode all the files in the directory uusrc/ and copy
127			# the resulting files to uudst/
128
129			use Convert::UUlib ':all';
130
131			sub namefilter {
132			my($path)=@_;
133			$path=~s/^.*[\/\\]//;
134			$path;
135			}
136
137			sub busycb {
138			my($action,$curfile,$partno,$numparts,$percent,$fsize)=@_;
139			$_[0]=straction($action);
140			print "busy_callback(",join(",",@_),")\n";
141			0;
142			}
143
144			SetOption (OPT_IGNMODE, 1);
145			SetOption (OPT_VERBOSE, 1);
146
147			# show the three ways you can set callback functions
148			SetFNameFilter (\&namefilter);
149
150			SetBusyCallback ("busycb",333);
151
152			SetMsgCallback (sub {
153			my($msg,$level)=@_;
154			print uc(strmsglevel($_[1])),": $msg\n";
155			});
156
157			for(<uusrc/*>) {
158			my($retval,$count)=LoadFile ($_,$_,1);
159			print "file($_), status(",strerror($retval),") parts($count)\n";
160			}
161
162			SetOption (OPT_SAVEPATH, "uudst/");
163
164			$i=0;
165			while($uu=GetFileListItem($i)) {
166			$i++;
167			print "file nr. $i";
168			print " state ",$uu->state;
169			print " mode ",$uu->mode;
170			print " uudet ",strencoding($uu->uudet);
171			print " size ",$uu->size;
172			print " filename ",$uu->filename;
173			print " subfname ",$uu->subfname;
174			print " mimeid ",$uu->mimeid;
175			print " mimetype ",$uu->mimetype;
176			print "\n";
177
178			# print additional info about all parts
179			for($uu->parts) {
180			while(my($k,$v)=each(%$_)) {
181			print "$k > $v, ";
182			}
183			print "\n";
184			}
185
186			$uu->decode_temp;
187			print " temporarily decoded to ",$uu->binfile,"\n";
188			$uu->remove_temp;
189
190			print strerror($uu->decode);
191			print " saved as uudst/",$uu->filename,"\n";
192			}
193
194			print "cleanup...\n";
195
196			CleanUp();
197
198			=head1 Exported constants
199
200			Action code constants:
201
202			ACT_COPYING ACT_DECODING ACT_ENCODING
203			ACT_IDLE ACT_SCANNING
204
205			File status flags:
206
207			FILE_DECODED FILE_ERROR FILE_MISPART
208			FILE_NOBEGIN FILE_NODATA FILE_NOEND
209			FILE_OK FILE_READ FILE_TMPFILE
210
211			Message severity levels:
212
213			MSG_ERROR MSG_FATAL MSG_MESSAGE
214			MSG_NOTE MSG_PANIC MSG_WARNING
215
216			Options:
217
218			OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS
219			OPT_ENCEXT OPT_ERRNO OPT_FAST OPT_IGNMODE
220			OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB OPT_PROGRESS
221			OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE
222	root	1.2	OPT_VERSION OPT_REMOVE OPT_MOREMIME
223	root	1.1
224			Error/Result codes:
225
226			RET_CANCEL RET_CONT RET_EXISTS RET_ILLVAL RET_IOERR
227			RET_NODATA RET_NOEND RET_NOMEM RET_OK RET_UNSUP
228
229			Encoding types:
230
231	root	1.6	B64ENCODED BH_ENCODED PT_ENCODED QP_ENCODED XX_ENCODED
232			UU_ENCODED YENC_ENCODED
233	root	1.1
234			=head1 Exported functions
235
236			Initializing and cleanup (Initialize is automatically called when the
237			module is loaded and allocates quite a bit of memory. CleanUp releases
238			that again).
239
240			Initialize; # not normally necessary
241			CleanUp; # could be called at the end to release memory
242
243			Setting and querying options:
244
245			$option = GetOption OPT_xxx;
246			SetOption OPT_xxx, opt-value;
247
248			Error and action values => stringified:
249
250			$msg = straction ACT_xxx;
251			$msg = strerror RET_xxx;
252
253			Setting various callbacks:
254
255			SetMsgCallback [callback-function];
256			SetBusyCallback [callback-function];
257			SetFileCallback [callback-function];
258			SetFNameFilter [callback-function];
259
260			Call the currently selected FNameFilter:
261
262			$file = FNameFilter $file;
263
264			Loading sourcefiles, optionally fuzzy merge and start decoding:
265
266			($retval, $count) = LoadFile $fname, [$id, [$delflag]];
267			$retval = Smerge $pass;
268			$item = GetFileListItem $item_number;
269
270			The procedural interface is undocumented, use the following methods instead:
271
272			$retval = $item->rename($newname);
273			$retval = $item->decode_temp;
274			$retval = $item->remove_temp;
275			$retval = $item->decode([$target_path]);
276			$retval = $item->info(callback-function);
277
278			Querying (and setting) item attributes:
279
280			$state = $item->state;
281			$mode = $item->mode([newmode]);
282			$uudet = $item->uudet;
283			$size = $item->size;
284			$filename = $item->filename([newfilename});
285			$subfname = $item->subfname;
286			$mimeid = $item->mimeid;
287			$mimetype = $item->mimetype;
288			$binfile = $item->binfile;
289
290			Totally undocumented and unsupported(!):
291
292			$parts = $item->parts;
293
294			Functions below not documented and not very well tested:
295
296			int QuickDecode () ;
297			int EncodeMulti () ;
298			int EncodePartial () ;
299			int EncodeToStream () ;
300			int EncodeToFile () ;
301			int E_PrepSingle () ;
302			int E_PrepPartial () ;
303	root	1.6
304			=head2 EXTENSION FUNCTIONS
305
306			Functions found in this module but not documented in the uulib documentation:
307
308			=over 4
309
310			=item SetFileNameCallback $cb
311
312			Sets (or queries) the FileNameCallback, which is called whenever the
313			decoding library can't find a filename and wants to extract a filename
314			from the subject line of a posting. The callback will be called with
315			two arguments, the subject line and the current candidate for the
316			filename. The latter argument can be C<undef>, which means that no
317			filename could be found (and likely no one exists, so it is safe to also
318			return C<undef> in this case). If it doesn't return anything (not even
319			C<undef>!), then nothing happens, so this is a no-op callback:
320
321			sub cb {
322			return ();
323			}
324
325			If it returns C<undef>, then this indicates that no filename could be
326			found. In all other cases, the return value is taken to be the filename.
327
328			This is a slightly more useful callback:
329
330			sub cb {
331			return unless $_[1]; # skip "Re:"-plies et al.
332			my ($subject, $filename) = @_;
333			# if we find some *.rar, take it
334			return $1 if $subject =~ /(\w+\.rar)/;
335			# otherwise just pass what we have
336			return ();
337			}
338
339			=back
340	root	1.1
341			=head1 AUTHOR
342
343			Marc Lehmann <pcg@goof.com>, the original uulib library was written by
344			Frank Pilhofer <fp@informatik.uni-frankfurt.de>.
345
346			=head1 SEE ALSO
347
348			perl(1), uudeview homepage at http://www.uni-frankfurt.de/~fp/uudeview/.
349
350			=cut