1Convert::BinHex(3) User Contributed Perl Documentation Convert::BinHex(3)
2
6 Convert::BinHex - extract data from Macintosh BinHex files
7 ALPHA WARNING: this code is currently in its Alpha release. Things may
9 change drastically until the interface is hammered out: if you have
10 suggestions or objections, please speak up now!
11
13 Simple functions:
14 use Convert::BinHex qw(binhex_crc macbinary_crc);
16 # Compute HQX7-style CRC for data, pumping in old CRC if desired:
18 $crc = binhex_crc($data, $crc);
19 # Compute the MacBinary-II-style CRC for the data:
21 $crc = macbinary_crc($data, $crc);
22 Hex to bin, low-level interface. Conversion is actually done via an
24 object ("Convert::BinHex::Hex2Bin") which keeps internal conversion
25 state:
26 # Create and use a "translator" object:
28 my $H2B = Convert::BinHex->hex2bin; # get a converter object
29 while (<STDIN>) {
30 print $STDOUT $H2B->next($_); # convert some more input
31 }
32 print $STDOUT $H2B->done; # no more input: finish up
33 Hex to bin, OO interface. The following operations must be done in the
35 order shown!
36 # Read data in piecemeal:
38 $HQX = Convert::BinHex->open(FH=>\*STDIN) || die "open: $!";
39 $HQX->read_header; # read header info
40 @data = $HQX->read_data; # read in all the data
41 @rsrc = $HQX->read_resource; # read in all the resource
42 Bin to hex, low-level interface. Conversion is actually done via an
44 object ("Convert::BinHex::Bin2Hex") which keeps internal conversion
45 state:
46 # Create and use a "translator" object:
48 my $B2H = Convert::BinHex->bin2hex; # get a converter object
49 while (<STDIN>) {
50 print $STDOUT $B2H->next($_); # convert some more input
51 }
52 print $STDOUT $B2H->done; # no more input: finish up
53 Bin to hex, file interface. Yes, you can convert to BinHex as well as
55 from it!
56 # Create new, empty object:
58 my $HQX = Convert::BinHex->new;
59 # Set header attributes:
61 $HQX->filename("logo.gif");
62 $HQX->type("GIFA");
63 $HQX->creator("CNVS");
64 # Give it the data and resource forks (either can be absent):
66 $HQX->data(Path => "/path/to/data"); # here, data is on disk
67 $HQX->resource(Data => $resourcefork); # here, resource is in core
68 # Output as a BinHex stream, complete with leading comment:
70 $HQX->encode(\*STDOUT);
71 PLANNED!!!! Bin to hex, "CAP" interface. Thanks to Ken Lunde for
73 suggesting this.
74 # Create new, empty object from CAP tree:
76 my $HQX = Convert::BinHex->from_cap("/path/to/root/file");
77 $HQX->encode(\*STDOUT);
78
80 BinHex is a format used by Macintosh for transporting Mac files safely
81 through electronic mail, as short-lined, 7-bit, semi-compressed data
82 streams. Ths module provides a means of converting those data streams
83 back into into binary data.
84
86 (Some text taken from RFC-1741.) Files on the Macintosh consist of two
87 parts, called forks:
88 Data fork
90 The actual data included in the file. The Data fork is typically
91 the only meaningful part of a Macintosh file on a non-Macintosh
92 computer system. For example, if a Macintosh user wants to send a
93 file of data to a user on an IBM-PC, she would only send the Data
94 fork.
95 Resource fork
97 Contains a collection of arbitrary attribute/value pairs, including
98 program segments, icon bitmaps, and parametric values.
99 Additional information regarding Macintosh files is stored by the
101 Finder in a hidden file, called the "Desktop Database".
102 Because of the complications in storing different parts of a Macintosh
104 file in a non-Macintosh filesystem that only handles consecutive data
105 in one part, it is common to convert the Macintosh file into some other
106 format before transferring it over the network. The BinHex format
107 squashes that data into transmittable ASCII as follows:
108 1. The file is output as a byte stream consisting of some basic header
110 information (filename, type, creator), then the data fork, then the
111 resource fork.
112 2. The byte stream is compressed by looking for series of duplicated
114 bytes and representing them using a special binary escape sequence
115 (of course, any occurences of the escape character must also be
116 escaped).
117 3. The compressed stream is encoded via the "6/8 hemiola" common to
119 base64 and uuencode: each group of three 8-bit bytes (24 bits) is
120 chopped into four 6-bit numbers, which are used as indexes into an
121 ASCII "alphabet". (I assume that leftover bytes are zero-padded;
122 documentation is thin).
123
125 CRC computation
126 macbinary_crc DATA, SEED
127 Compute the MacBinary-II-style CRC for the given DATA, with the CRC
128 seeded to SEED. Normally, you start with a SEED of 0, and you pump
129 in the previous CRC as the SEED if you're handling a lot of data
130 one chunk at a time. That is:
131 $crc = 0;
133 while (<STDIN>) {
134 $crc = macbinary_crc($_, $crc);
135 }
136 Note: Extracted from the mcvert utility (Doug Moore, April '87),
138 using a "magic array" algorithm by Jim Van Verth for efficiency.
139 Converted to Perl5 by Eryq. Untested.
140 binhex_crc DATA, SEED
142 Compute the HQX-style CRC for the given DATA, with the CRC seeded
143 to SEED. Normally, you start with a SEED of 0, and you pump in the
144 previous CRC as the SEED if you're handling a lot of data one chunk
145 at a time. That is:
146 $crc = 0;
148 while (<STDIN>) {
149 $crc = binhex_crc($_, $crc);
150 }
151 Note: Extracted from the mcvert utility (Doug Moore, April '87),
153 using a "magic array" algorithm by Jim Van Verth for efficiency.
154 Converted to Perl5 by Eryq.
155
157 Conversion
158 bin2hex
159 Class method, constructor. Return a converter object. Just
160 creates a new instance of "Convert::BinHex::Bin2Hex"; see that
161 class for details.
162 hex2bin
164 Class method, constructor. Return a converter object. Just
165 creates a new instance of "Convert::BinHex::Hex2Bin"; see that
166 class for details.
167 Construction
169 new PARAMHASH
170 Class method, constructor. Return a handle on a BinHex'able
171 entity. In general, the data and resource forks for such an entity
172 are stored in native format (binary) format.
173 Parameters in the PARAMHASH are the same as header-oriented method
175 names, and may be used to set attributes:
176 $HQX = new Convert::BinHex filename => "icon.gif",
178 type => "GIFB",
179 creator => "CNVS";
180 open PARAMHASH
182 Class method, constructor. Return a handle on a new BinHex'ed
183 stream, for parsing. Params are:
184 Data
186 Input a HEX stream from the given data. This can be a scalar,
187 or a reference to an array of scalars.
188 Expr
190 Input a HEX stream from any open()able expression. It will be
191 opened and binmode'd, and the filehandle will be closed either
192 on a close() or when the object is destructed.
193 FH Input a HEX stream from the given filehandle.
195 NoComment
197 If true, the parser should not attempt to skip a leading "(This
198 file...)" comment. That means that the first nonwhite
199 characters encountered must be the binhex'ed data.
200 Get/set header information
202 creator [VALUE]
203 Instance method. Get/set the creator of the file. This is a four-
204 character string (though I don't know if it's guaranteed to be
205 printable ASCII!) that serves as part of the Macintosh's version
206 of a MIME "content-type".
207 For example, a document created by "Canvas" might have creator
209 "CNVS".
210 data [PARAMHASH]
212 Instance method. Get/set the data fork. Any arguments are passed
213 into the new() method of "Convert::BinHex::Fork".
214 filename [VALUE]
216 Instance method. Get/set the name of the file.
217 flags [VALUE]
219 Instance method. Return the flags, as an integer. Use bitmasking
220 to get as the values you need.
221 header_as_string
223 Return a stringified version of the header that you might use for
224 logging/debugging purposes. It looks like this:
225 X-HQX-Software: BinHex 4.0 (Convert::BinHex 1.102)
227 X-HQX-Filename: Something_new.eps
228 X-HQX-Version: 0
229 X-HQX-Type: EPSF
230 X-HQX-Creator: ART5
231 X-HQX-Data-Length: 49731
232 X-HQX-Rsrc-Length: 23096
233 As some of you might have guessed, this is RFC-822-style, and may
235 be easily plunked down into the middle of a mail header, or split
236 into lines, etc.
237 requires [VALUE]
239 Instance method. Get/set the software version required to convert
240 this file, as extracted from the comment that preceded the actual
241 binhex'ed data; e.g.:
242 (This file must be converted with BinHex 4.0)
244 In this case, after parsing in the comment, the code:
246 $HQX->requires;
248 would get back "4.0".
250 resource [PARAMHASH]
252 Instance method. Get/set the resource fork. Any arguments are
253 passed into the new() method of "Convert::BinHex::Fork".
254 type [VALUE]
256 Instance method. Get/set the type of the file. This is a four-
257 character string (though I don't know if it's guaranteed to be
258 printable ASCII!) that serves as part of the Macintosh's version
259 of a MIME "content-type".
260 For example, a GIF89a file might have type "GF89".
262 version [VALUE]
264 Instance method. Get/set the version, as an integer.
265 Decode, high-level
267 read_comment
268 Instance method. Skip past the opening comment in the file, which
269 is of the form:
270 (This file must be converted with BinHex 4.0)
272 As per RFC-1741, this comment must immediately precede the BinHex
274 data, and any text before it will be ignored.
275 You don't need to invoke this method yourself; read_header() will
277 do it for you. After the call, the version number in the comment
278 is accessible via the requires() method.
279 read_header
281 Instance method. Read in the BinHex file header. You must do this
282 first!
283 read_data [NBYTES]
285 Instance method. Read information from the data fork. Use it in
286 an array context to slurp all the data into an array of scalars:
287 @data = $HQX->read_data;
289 Or use it in a scalar context to get the data piecemeal:
291 while (defined($data = $HQX->read_data)) {
293 # do stuff with $data
294 }
295 The NBYTES to read defaults to 2048.
297 read_resource [NBYTES]
299 Instance method. Read in all/some of the resource fork. See
300 read_data() for usage.
301 Encode, high-level
303 encode OUT
304 Encode the object as a BinHex stream to the given output handle
305 OUT. OUT can be a filehandle, or any blessed object that responds
306 to a print() message.
307 The leading comment is output, using the requires() attribute.
309
311 Convert::BinHex::Bin2Hex
312 A BINary-to-HEX converter. This kind of conversion requires a certain
313 amount of state information; it cannot be done by just calling a simple
314 function repeatedly. Use it like this:
315 # Create and use a "translator" object:
317 my $B2H = Convert::BinHex->bin2hex; # get a converter object
318 while (<STDIN>) {
319 print STDOUT $B2H->next($_); # convert some more input
320 }
321 print STDOUT $B2H->done; # no more input: finish up
322 # Re-use the object:
324 $B2H->rewind; # ready for more action!
325 while (<MOREIN>) { ...
326 On each iteration, next() (and done()) may return either a decent-sized
328 non-empty string (indicating that more converted data is ready for you)
329 or an empty string (indicating that the converter is waiting to amass
330 more input in its private buffers before handing you more stuff to
331 output.
332 Note that done() always converts and hands you whatever is left.
334 This may have been a good approach. It may not. Someday, the
336 converter may also allow you give it an object that responds to read(),
337 or a FileHandle, and it will do all the nasty buffer-filling on its
338 own, serving you stuff line by line:
339 # Someday, maybe...
341 my $B2H = Convert::BinHex->bin2hex(\*STDIN);
342 while (defined($_ = $B2H->getline)) {
343 print STDOUT $_;
344 }
345 Someday, maybe. Feel free to voice your opinions.
347 Convert::BinHex::Hex2Bin
349 A HEX-to-BINary converter. This kind of conversion requires a certain
350 amount of state information; it cannot be done by just calling a simple
351 function repeatedly. Use it like this:
352 # Create and use a "translator" object:
354 my $H2B = Convert::BinHex->hex2bin; # get a converter object
355 while (<STDIN>) {
356 print STDOUT $H2B->next($_); # convert some more input
357 }
358 print STDOUT $H2B->done; # no more input: finish up
359 # Re-use the object:
361 $H2B->rewind; # ready for more action!
362 while (<MOREIN>) { ...
363 On each iteration, next() (and done()) may return either a decent-sized
365 non-empty string (indicating that more converted data is ready for you)
366 or an empty string (indicating that the converter is waiting to amass
367 more input in its private buffers before handing you more stuff to
368 output.
369 Note that done() always converts and hands you whatever is left.
371 Note that this converter does not find the initial "BinHex version"
373 comment. You have to skip that yourself. It only handles data between
374 the opening and closing ":".
375 Convert::BinHex::Fork
377 A fork in a Macintosh file.
378 # How to get them...
380 $data_fork = $HQX->data; # get the data fork
381 $rsrc_fork = $HQX->resource; # get the resource fork
382 # Make a new fork:
384 $FORK = Convert::BinHex::Fork->new(Path => "/tmp/file.data");
385 $FORK = Convert::BinHex::Fork->new(Data => $scalar);
386 $FORK = Convert::BinHex::Fork->new(Data => \@array_of_scalars);
387 # Get/set the length of the data fork:
389 $len = $FORK->length;
390 $FORK->length(170); # this overrides the REAL value: be careful!
391 # Get/set the path to the underlying data (if in a disk file):
393 $path = $FORK->path;
394 $FORK->path("/tmp/file.data");
395 # Get/set the in-core data itself, which may be a scalar or an arrayref:
397 $data = $FORK->data;
398 $FORK->data($scalar);
399 $FORK->data(\@array_of_scalars);
400 # Get/set the CRC:
402 $crc = $FORK->crc;
403 $FORK->crc($crc);
404
406 Design issues
407 BinHex needs a stateful parser
408 Unlike its cousins base64 and uuencode, BinHex format is not
409 amenable to being parsed line-by-line. There appears to be no
410 guarantee that lines contain 4n encoded characters... and even if
411 there is one, the BinHex compression algorithm interferes: even
412 when you can decode one line at a time, you can't necessarily
413 decompress a line at a time.
414 For example: a decoded line ending with the byte "\x90" (the escape
416 or "mark" character) is ambiguous: depending on the next decoded
417 byte, it could mean a literal "\x90" (if the next byte is a
418 "\x00"), or it could mean n-1 more repetitions of the previous
419 character (if the next byte is some nonzero "n").
420 For this reason, a BinHex parser has to be somewhat stateful: you
422 cannot have code like this:
423 #### NO! #### NO! #### NO! #### NO! #### NO! ####
425 while (<STDIN>) { # read HEX
426 print hexbin($_); # convert and write BIN
427 }
428 unless something is happening "behind the scenes" to keep track of
430 what was last done. The dangerous thing, however, is that this
431 approach will seem to work, if you only test it on BinHex files
432 which do not use compression and which have 4n HEX characters on
433 each line.
434 Since we have to be stateful anyway, we use the parser object to
436 keep our state.
437 We need to be handle large input files
439 Solutions that demand reading everything into core don't cut it in
440 my book. The first MPEG file that comes along can louse up your
441 whole day. So, there are no size limitations in this module: the
442 data is read on-demand, and filehandles are always an option.
443 Boy, is this slow!
445 A lot of the byte-level manipulation that has to go on,
446 particularly the CRC computing (which involves intensive bit-
447 shifting and masking) slows this module down significantly. What
448 is needed perhaps is an optional extension library where the slow
449 pieces can be done more quickly... a Convert::BinHex::CRC, if you
450 will. Volunteers, anyone?
451 Even considering that, however, it's slower than I'd like. I'm
453 sure many improvements can be made in the HEX-to-BIN end of things.
454 No doubt I'll attempt some as time goes on...
455 How it works
457 Since BinHex is a layered format, consisting of...
458 A Macintosh file [the "BIN"]...
460 Encoded as a structured 8-bit bytestream, then...
461 Compressed to reduce duplicate bytes, then...
462 Encoded as 7-bit ASCII [the "HEX"]
463 ...there is a layered parsing algorithm to reverse the process.
465 Basically, it works in a similar fashion to stdio's fread():
466 0. There is an internal buffer of decompressed (BIN) data,
468 initially empty.
469 1. Application asks to read() n bytes of data from object
470 2. If the buffer is not full enough to accommodate the request:
471 2a. The read() method grabs the next available chunk of input
472 data (the HEX).
473 2b. HEX data is converted and decompressed into as many BIN
474 bytes as possible.
475 2c. BIN bytes are added to the read() buffer.
476 2d. Go back to step 2a. until the buffer is full enough
477 or we hit end-of-input.
478 The conversion-and-decompression algorithms need their own internal
480 buffers and state (since the next input chunk may not contain all the
481 data needed for a complete conversion/decompression operation). These
482 are maintained in the object, so parsing two different input streams
483 simultaneously is possible.
484
486 Only handles "Hqx7" files, as per RFC-1741.
487 Remember that Macintosh text files use "\r" as end-of-line: this means
489 that if you want a textual file to look normal on a non-Mac system, you
490 probably want to do this to the data:
491 # Get the data, and output it according to normal conventions:
493 foreach ($HQX->read_data) { s/\r/\n/g; print }
494
496 Maintained by Stephen Nelson <stephenenelson@mac.com>
497 Written by Eryq, http://www.enteract.com/~eryq / eryq@enteract.com
499 Support for native-Mac conversion, plus invaluable contributions in
501 Alpha Testing, plus a few patches, plus the baseline binhex/debinhex
502 programs, were provided by Paul J. Schinder (NASA/GSFC).
503 Ken Lunde (Adobe) suggested incorporating the CAP file representation.
505
507 Copyright (c) 1997 by Eryq. All rights reserved. This program is free
508 software; you can redistribute it and/or modify it under the same terms
509 as Perl itself.
510 This software comes with NO WARRANTY of any kind. See the COPYING file
512 in the distribution for details.
513perl v5.36.0 2023-01-20 Convert::BinHex(3)