ALPHA WARNING: this code is currently in its Alpha release. Things may change drastically until the interface is hammered out: if you have suggestions or objections, please speak up now!
use Convert::BinHex qw(binhex_crc macbinary_crc); # Compute HQX7-style CRC for data, pumping in old CRC if desired: $crc = binhex_crc($data, $crc); # Compute the MacBinary-II-style CRC for the data: $crc = macbinary_crc($data, $crc);
Hex to bin, low-level interface. Conversion is actually done via an object (``Convert::BinHex::Hex2Bin'') which keeps internal conversion state:
# Create and use a "translator" object: my $H2B = Convert::BinHex->hex2bin; # get a converter object while (<STDIN>) { print $STDOUT $H2B->next($_); # convert some more input } print $STDOUT $H2B->done; # no more input: finish up
Hex to bin, OO interface. The following operations must be done in the order shown!
# Read data in piecemeal: $HQX = Convert::BinHex->open(FH=>\*STDIN) || die "open: $!"; $HQX->read_header; # read header info @data = $HQX->read_data; # read in all the data @rsrc = $HQX->read_resource; # read in all the resource
Bin to hex, low-level interface. Conversion is actually done via an object (``Convert::BinHex::Bin2Hex'') which keeps internal conversion state:
# Create and use a "translator" object: my $B2H = Convert::BinHex->bin2hex; # get a converter object while (<STDIN>) { print $STDOUT $B2H->next($_); # convert some more input } print $STDOUT $B2H->done; # no more input: finish up
Bin to hex, file interface. Yes, you can convert to BinHex as well as from it!
# Create new, empty object: my $HQX = Convert::BinHex->new; # Set header attributes: $HQX->filename("logo.gif"); $HQX->type("GIFA"); $HQX->creator("CNVS"); # Give it the data and resource forks (either can be absent): $HQX->data(Path => "/path/to/data"); # here, data is on disk $HQX->resource(Data => $resourcefork); # here, resource is in core # Output as a BinHex stream, complete with leading comment: $HQX->encode(\*STDOUT);
PLANNED!!!! Bin to hex, ``CAP'' interface. Thanks to Ken Lunde for suggesting this.
# Create new, empty object from CAP tree: my $HQX = Convert::BinHex->from_cap("/path/to/root/file"); $HQX->encode(\*STDOUT);
Additional information regarding Macintosh files is stored by the Finder in a hidden file, called the ``Desktop Database''.
Because of the complications in storing different parts of a Macintosh file in a non-Macintosh filesystem that only handles consecutive data in one part, it is common to convert the Macintosh file into some other format before transferring it over the network. The BinHex format squashes that data into transmittable ASCII as follows:
$crc = 0; while (<STDIN>) { $crc = macbinary_crc($_, $crc); }
Note: Extracted from the mcvert utility (Doug Moore, April '87), using a ``magic array'' algorithm by Jim Van Verth for efficiency. Converted to Perl5 by Eryq. Untested.
$crc = 0; while (<STDIN>) { $crc = binhex_crc($_, $crc); }
Note: Extracted from the mcvert utility (Doug Moore, April '87), using a ``magic array'' algorithm by Jim Van Verth for efficiency. Converted to Perl5 by Eryq.
Parameters in the PARAMHASH are the same as header-oriented method names, and may be used to set attributes:
$HQX = new Convert::BinHex filename => "icon.gif", type => "GIFB", creator => "CNVS";
For example, a document created by ``Canvas'' might have creator "CNVS".
X-HQX-Software: BinHex 4.0 (Convert::BinHex 1.102) X-HQX-Filename: Something_new.eps X-HQX-Version: 0 X-HQX-Type: EPSF X-HQX-Creator: ART5 X-HQX-Data-Length: 49731 X-HQX-Rsrc-Length: 23096
As some of you might have guessed, this is RFC-822-style, and may be easily plunked down into the middle of a mail header, or split into lines, etc.
(This file must be converted with BinHex 4.0)
In this case, after parsing in the comment, the code:
$HQX->requires;
would get back ``4.0''.
For example, a GIF89a file might have type "GF89".
(This file must be converted with BinHex 4.0)
As per RFC-1741, this comment must immediately precede the BinHex data, and any text before it will be ignored.
You don't need to invoke this method yourself; "read_header()" will do it for you. After the call, the version number in the comment is accessible via the "requires()" method.
@data = $HQX->read_data;
Or use it in a scalar context to get the data piecemeal:
while (defined($data = $HQX->read_data)) { # do stuff with $data }
The NBYTES to read defaults to 2048.
The leading comment is output, using the "requires()" attribute.
# Create and use a "translator" object: my $B2H = Convert::BinHex->bin2hex; # get a converter object while (<STDIN>) { print STDOUT $B2H->next($_); # convert some more input } print STDOUT $B2H->done; # no more input: finish up # Re-use the object: $B2H->rewind; # ready for more action! while (<MOREIN>) { ...
On each iteration, "next()" (and "done()") may return either a decent-sized non-empty string (indicating that more converted data is ready for you) or an empty string (indicating that the converter is waiting to amass more input in its private buffers before handing you more stuff to output.
Note that "done()" always converts and hands you whatever is left.
This may have been a good approach. It may not. Someday, the converter may also allow you give it an object that responds to read(), or a FileHandle, and it will do all the nasty buffer-filling on its own, serving you stuff line by line:
# Someday, maybe... my $B2H = Convert::BinHex->bin2hex(\*STDIN); while (defined($_ = $B2H->getline)) { print STDOUT $_; }
Someday, maybe. Feel free to voice your opinions.
# Create and use a "translator" object: my $H2B = Convert::BinHex->hex2bin; # get a converter object while (<STDIN>) { print STDOUT $H2B->next($_); # convert some more input } print STDOUT $H2B->done; # no more input: finish up # Re-use the object: $H2B->rewind; # ready for more action! while (<MOREIN>) { ...
On each iteration, "next()" (and "done()") may return either a decent-sized non-empty string (indicating that more converted data is ready for you) or an empty string (indicating that the converter is waiting to amass more input in its private buffers before handing you more stuff to output.
Note that "done()" always converts and hands you whatever is left.
Note that this converter does not find the initial ``BinHex version'' comment. You have to skip that yourself. It only handles data between the opening and closing ":".
# How to get them... $data_fork = $HQX->data; # get the data fork $rsrc_fork = $HQX->resource; # get the resource fork # Make a new fork: $FORK = Convert::BinHex::Fork->new(Path => "/tmp/file.data"); $FORK = Convert::BinHex::Fork->new(Data => $scalar); $FORK = Convert::BinHex::Fork->new(Data => \@array_of_scalars); # Get/set the length of the data fork: $len = $FORK->length; $FORK->length(170); # this overrides the REAL value: be careful! # Get/set the path to the underlying data (if in a disk file): $path = $FORK->path; $FORK->path("/tmp/file.data"); # Get/set the in-core data itself, which may be a scalar or an arrayref: $data = $FORK->data; $FORK->data($scalar); $FORK->data(\@array_of_scalars); # Get/set the CRC: $crc = $FORK->crc; $FORK->crc($crc);
For example: a decoded line ending with the byte "\x90" (the escape or ``mark'' character) is ambiguous: depending on the next decoded byte, it could mean a literal "\x90" (if the next byte is a "\x00"), or it could mean n-1 more repetitions of the previous character (if the next byte is some nonzero "n").
For this reason, a BinHex parser has to be somewhat stateful: you cannot have code like this:
#### NO! #### NO! #### NO! #### NO! #### NO! #### while (<STDIN>) { # read HEX print hexbin($_); # convert and write BIN }
unless something is happening ``behind the scenes'' to keep track of what was last done. The dangerous thing, however, is that this approach will seem to work, if you only test it on BinHex files which do not use compression and which have 4n HEX characters on each line.
Since we have to be stateful anyway, we use the parser object to keep our state.
Even considering that, however, it's slower than I'd like. I'm sure many improvements can be made in the HEX-to-BIN end of things. No doubt I'll attempt some as time goes on...
A Macintosh file [the "BIN"]... Encoded as a structured 8-bit bytestream, then... Compressed to reduce duplicate bytes, then... Encoded as 7-bit ASCII [the "HEX"]
...there is a layered parsing algorithm to reverse the process. Basically, it works in a similar fashion to stdio's fread():
0. There is an internal buffer of decompressed (BIN) data, initially empty. 1. Application asks to read() n bytes of data from object 2. If the buffer is not full enough to accommodate the request: 2a. The read() method grabs the next available chunk of input data (the HEX). 2b. HEX data is converted and decompressed into as many BIN bytes as possible. 2c. BIN bytes are added to the read() buffer. 2d. Go back to step 2a. until the buffer is full enough or we hit end-of-input.
The conversion-and-decompression algorithms need their own internal buffers and state (since the next input chunk may not contain all the data needed for a complete conversion/decompression operation). These are maintained in the object, so parsing two different input streams simultaneously is possible.
Remember that Macintosh text files use "\r" as end-of-line: this means that if you want a textual file to look normal on a non-Mac system, you probably want to do this to the data:
# Get the data, and output it according to normal conventions: foreach ($HQX->read_data) { s/\r/\n/g; print }
Written by Eryq, http://www.enteract.com/~eryq / eryq@enteract.com
Support for native-Mac conversion, plus invaluable contributions in Alpha Testing, plus a few patches, plus the baseline binhex/debinhex programs, were provided by Paul J. Schinder (NASA/GSFC).
Ken Lunde (Adobe) suggested incorporating the CAP file representation.
This software comes with NO WARRANTY of any kind. See the COPYING file in the distribution for details.