Convert-UUlib/UUlib.pm

package Convert::UUlib;

use Carp;

require Exporter;
require DynaLoader;
use AutoLoader;

$VERSION = 0.2;

@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

        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
);

@_funcs = qw(
        Initialize CleanUp GetOption SetOption strerror
        SetMsgCallback SetBusyCallback SetFileCallback
        SetFNameFilter 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;
   ();
}

# encoding type -> string mapping
sub strencoding($) {
   return 'base64'              if $_[0] == &B64ENCODED;
   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;
   return 'uuencode'            if $_[0] == &UU_ENCODED;
   ();
}

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;
   ();
}

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

=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 () ;

=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.3
Committed:	Tue Jun 12 03:20:44 2001 UTC (22 years, 11 months ago) by root
Branch:	MAIN
Changes since 1.2:	+1 -1 lines
Log Message:	* empty log message *
#	Content
1	package Convert::UUlib;
2
3	use Carp;
4
5	require Exporter;
6	require DynaLoader;
7	use AutoLoader;
8
9	$VERSION = 0.2;
10
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	OPT_VERSION OPT_REMOVE OPT_MOREMIME
25
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	XX_ENCODED UU_ENCODED
31	);
32
33	@_funcs = qw(
34	Initialize CleanUp GetOption SetOption strerror
35	SetMsgCallback SetBusyCallback SetFileCallback
36	SetFNameFilter FNameFilter LoadFile GetFileListItem
37	RenameFile DecodeToTemp RemoveTemp DecodeFile
38	InfoFile Smerge QuickDecode EncodeMulti EncodePartial
39	EncodeToStream EncodeToFile E_PrepSingle E_PrepPartial
40
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	();
68	}
69
70	# encoding type -> string mapping
71	sub strencoding($) {
72	return 'base64' if $_[0] == &B64ENCODED;
73	return 'binhex' if $_[0] == &BH_ENCODED;
74	return 'plaintext' if $_[0] == &PT_ENCODED;
75	return 'quoted-printable' if $_[0] == &QP_ENCODED;
76	return 'xxencode' if $_[0] == &XX_ENCODED;
77	return 'uuencode' if $_[0] == &UU_ENCODED;
78	();
79	}
80
81	sub strmsglevel($) {
82	return 'message' if $_[0] == &MSG_MESSAGE;
83	return 'note' if $_[0] == &MSG_NOTE;
84	return 'warning' if $_[0] == &MSG_WARNING;
85	return 'error' if $_[0] == &MSG_ERROR;
86	return 'panic' if $_[0] == &MSG_PANIC;
87	return 'fatal' if $_[0] == &MSG_FATAL;
88	();
89	}
90
91	1;
92	__END__
93
94	=head1 NAME
95
96	Convert::UUlib - Perl interface to the uulib library (a.k.a. uudeview/uuenview).
97
98	=head1 SYNOPSIS
99
100	use Convert::UUlib;
101
102	=head1 DESCRIPTION
103
104	Read the file uulibdoc.dvi.gz and the example-decoder source. Sorry - more
105	to come once people use me ;)
106
107	=head1 SMALL EXAMPLE DECODER
108
109	The following code excerpt is a minimal decoder program. It reads all
110	files given on the commandline and decodes any files in it.
111
112	use Convert::UUlib ':all';
113
114	LoadFile($_) for @ARGV;
115
116	for($i=0; $uu=GetFileListItem($i); $i++) {
117	$uu->decode if $uu->state & FILE_OK;
118	}
119
120	=head1 LARGE EXAMPLE DECODER
121
122	This is the file C<example-decoder> from the distribution, put here
123	instead of more thorough documentation.
124
125	# decode all the files in the directory uusrc/ and copy
126	# the resulting files to uudst/
127
128	use Convert::UUlib ':all';
129
130	sub namefilter {
131	my($path)=@_;
132	$path=~s/^.*[\/\\]//;
133	$path;
134	}
135
136	sub busycb {
137	my($action,$curfile,$partno,$numparts,$percent,$fsize)=@_;
138	$_[0]=straction($action);
139	print "busy_callback(",join(",",@_),")\n";
140	0;
141	}
142
143	SetOption (OPT_IGNMODE, 1);
144	SetOption (OPT_VERBOSE, 1);
145
146	# show the three ways you can set callback functions
147	SetFNameFilter (\&namefilter);
148
149	SetBusyCallback ("busycb",333);
150
151	SetMsgCallback (sub {
152	my($msg,$level)=@_;
153	print uc(strmsglevel($_[1])),": $msg\n";
154	});
155
156	for(<uusrc/*>) {
157	my($retval,$count)=LoadFile ($_,$_,1);
158	print "file($_), status(",strerror($retval),") parts($count)\n";
159	}
160
161	SetOption (OPT_SAVEPATH, "uudst/");
162
163	$i=0;
164	while($uu=GetFileListItem($i)) {
165	$i++;
166	print "file nr. $i";
167	print " state ",$uu->state;
168	print " mode ",$uu->mode;
169	print " uudet ",strencoding($uu->uudet);
170	print " size ",$uu->size;
171	print " filename ",$uu->filename;
172	print " subfname ",$uu->subfname;
173	print " mimeid ",$uu->mimeid;
174	print " mimetype ",$uu->mimetype;
175	print "\n";
176
177	# print additional info about all parts
178	for($uu->parts) {
179	while(my($k,$v)=each(%$_)) {
180	print "$k > $v, ";
181	}
182	print "\n";
183	}
184
185	$uu->decode_temp;
186	print " temporarily decoded to ",$uu->binfile,"\n";
187	$uu->remove_temp;
188
189	print strerror($uu->decode);
190	print " saved as uudst/",$uu->filename,"\n";
191	}
192
193	print "cleanup...\n";
194
195	CleanUp();
196
197	=head1 Exported constants
198
199	Action code constants:
200
201	ACT_COPYING ACT_DECODING ACT_ENCODING
202	ACT_IDLE ACT_SCANNING
203
204	File status flags:
205
206	FILE_DECODED FILE_ERROR FILE_MISPART
207	FILE_NOBEGIN FILE_NODATA FILE_NOEND
208	FILE_OK FILE_READ FILE_TMPFILE
209
210	Message severity levels:
211
212	MSG_ERROR MSG_FATAL MSG_MESSAGE
213	MSG_NOTE MSG_PANIC MSG_WARNING
214
215	Options:
216
217	OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS
218	OPT_ENCEXT OPT_ERRNO OPT_FAST OPT_IGNMODE
219	OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB OPT_PROGRESS
220	OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE
221	OPT_VERSION OPT_REMOVE OPT_MOREMIME
222
223	Error/Result codes:
224
225	RET_CANCEL RET_CONT RET_EXISTS RET_ILLVAL RET_IOERR
226	RET_NODATA RET_NOEND RET_NOMEM RET_OK RET_UNSUP
227
228	Encoding types:
229
230	B64ENCODED BH_ENCODED PT_ENCODED
231	QP_ENCODED XX_ENCODED UU_ENCODED
232
233	=head1 Exported functions
234
235	Initializing and cleanup (Initialize is automatically called when the
236	module is loaded and allocates quite a bit of memory. CleanUp releases
237	that again).
238
239	Initialize; # not normally necessary
240	CleanUp; # could be called at the end to release memory
241
242	Setting and querying options:
243
244	$option = GetOption OPT_xxx;
245	SetOption OPT_xxx, opt-value;
246
247	Error and action values => stringified:
248
249	$msg = straction ACT_xxx;
250	$msg = strerror RET_xxx;
251
252	Setting various callbacks:
253
254	SetMsgCallback [callback-function];
255	SetBusyCallback [callback-function];
256	SetFileCallback [callback-function];
257	SetFNameFilter [callback-function];
258
259	Call the currently selected FNameFilter:
260
261	$file = FNameFilter $file;
262
263	Loading sourcefiles, optionally fuzzy merge and start decoding:
264
265	($retval, $count) = LoadFile $fname, [$id, [$delflag]];
266	$retval = Smerge $pass;
267	$item = GetFileListItem $item_number;
268
269	The procedural interface is undocumented, use the following methods instead:
270
271	$retval = $item->rename($newname);
272	$retval = $item->decode_temp;
273	$retval = $item->remove_temp;
274	$retval = $item->decode([$target_path]);
275	$retval = $item->info(callback-function);
276
277	Querying (and setting) item attributes:
278
279	$state = $item->state;
280	$mode = $item->mode([newmode]);
281	$uudet = $item->uudet;
282	$size = $item->size;
283	$filename = $item->filename([newfilename});
284	$subfname = $item->subfname;
285	$mimeid = $item->mimeid;
286	$mimetype = $item->mimetype;
287	$binfile = $item->binfile;
288
289	Totally undocumented and unsupported(!):
290
291	$parts = $item->parts;
292
293	Functions below not documented and not very well tested:
294
295	int QuickDecode () ;
296	int EncodeMulti () ;
297	int EncodePartial () ;
298	int EncodeToStream () ;
299	int EncodeToFile () ;
300	int E_PrepSingle () ;
301	int E_PrepPartial () ;
302
303	=head1 AUTHOR
304
305	Marc Lehmann <pcg@goof.com>, the original uulib library was written by
306	Frank Pilhofer <fp@informatik.uni-frankfurt.de>.
307
308	=head1 SEE ALSO
309
310	perl(1), uudeview homepage at http://www.uni-frankfurt.de/~fp/uudeview/.
311
312	=cut