.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Convert::BinHex 3pm"
.TH Convert::BinHex 3pm "2015-11-15" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Convert::BinHex \- extract data from Macintosh BinHex files
.PP
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!
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBSimple functions:\fR
.PP
.Vb 1
\&    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);
.Ve
.PP
\&\fBHex to bin, low-level interface.\fR
Conversion is actually done via an object (\*(L"Convert::BinHex::Hex2Bin\*(R")
which keeps internal conversion state:
.PP
.Vb 6
\&    # 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
.Ve
.PP
\&\fBHex to bin, \s-1OO\s0 interface.\fR
The following operations \fImust\fR be done in the order shown!
.PP
.Vb 5
\&    # Read data in piecemeal:
\&    $HQX = Convert::BinHex\->open(FH=>\e*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
.Ve
.PP
\&\fBBin to hex, low-level interface.\fR
Conversion is actually done via an object (\*(L"Convert::BinHex::Bin2Hex\*(R")
which keeps internal conversion state:
.PP
.Vb 6
\&    # 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
.Ve
.PP
\&\fBBin to hex, file interface.\fR  Yes, you can convert \fIto\fR BinHex
as well as from it!
.PP
.Vb 2
\&    # 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(\e*STDOUT);
.Ve
.PP
\&\fB\s-1PLANNED\s0!!!! Bin to hex, \*(L"\s-1CAP\*(R"\s0 interface.\fR
\&\fIThanks to Ken Lunde for suggesting this\fR.
.PP
.Vb 3
\&    # Create new, empty object from CAP tree:
\&    my $HQX = Convert::BinHex\->from_cap("/path/to/root/file");
\&    $HQX\->encode(\e*STDOUT);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBinHex\fR is a format used by Macintosh for transporting Mac files
safely through electronic mail, as short-lined, 7\-bit, semi-compressed
data streams.  Ths module provides a means of converting those
data streams back into into binary data.
.SH "FORMAT"
.IX Header "FORMAT"
\&\fI(Some text taken from \s-1RFC\-1741.\s0)\fR
Files on the Macintosh consist of two parts, called \fIforks\fR:
.IP "Data fork" 4
.IX Item "Data fork"
The actual data included in the file.  The Data fork is typically the
only meaningful part of a Macintosh file on a non-Macintosh computer system.
For example, if a Macintosh user wants to send a file of data to a
user on an IBM-PC, she would only send the Data fork.
.IP "Resource fork" 4
.IX Item "Resource fork"
Contains a collection of arbitrary attribute/value pairs, including
program segments, icon bitmaps, and parametric values.
.PP
Additional information regarding Macintosh files is stored by the
Finder in a hidden file, called the \*(L"Desktop Database\*(R".
.PP
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 \s-1ASCII\s0 as follows:
.IP "1." 4
The file is output as a \fBbyte stream\fR consisting of some basic header
information (filename, type, creator), then the data fork, then the
resource fork.
.IP "2." 4
The byte stream is \fBcompressed\fR by looking for series of duplicated
bytes and representing them using a special binary escape sequence
(of course, any occurences of the escape character must also be escaped).
.IP "3." 4
The compressed stream is \fBencoded\fR via the \*(L"6/8 hemiola\*(R" common
to \fIbase64\fR and \fIuuencode\fR: each group of three 8\-bit bytes (24 bits)
is chopped into four 6\-bit numbers, which are used as indexes into
an \s-1ASCII \s0\*(L"alphabet\*(R".
(I assume that leftover bytes are zero-padded; documentation is thin).
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "\s-1CRC\s0 computation"
.IX Subsection "CRC computation"
.IP "macbinary_crc \s-1DATA, SEED\s0" 4
.IX Item "macbinary_crc DATA, SEED"
Compute the MacBinary-II-style \s-1CRC\s0 for the given \s-1DATA,\s0 with the \s-1CRC\s0
seeded to \s-1SEED. \s0 Normally, you start with a \s-1SEED\s0 of 0, and you pump in
the previous \s-1CRC\s0 as the \s-1SEED\s0 if you're handling a lot of data one chunk
at a time.  That is:
.Sp
.Vb 4
\&    $crc = 0;
\&    while (<STDIN>) {
\&        $crc = macbinary_crc($_, $crc);
\&    }
.Ve
.Sp
\&\fINote:\fR Extracted from the \fImcvert\fR utility (Doug Moore, April '87),
using a \*(L"magic array\*(R" algorithm by Jim Van Verth for efficiency.
Converted to Perl5 by Eryq.  \fBUntested.\fR
.IP "binhex_crc \s-1DATA, SEED\s0" 4
.IX Item "binhex_crc DATA, SEED"
Compute the HQX-style \s-1CRC\s0 for the given \s-1DATA,\s0 with the \s-1CRC\s0 seeded to \s-1SEED.\s0
Normally, you start with a \s-1SEED\s0 of 0, and you pump in the previous \s-1CRC\s0 as
the \s-1SEED\s0 if you're handling a lot of data one chunk at a time.  That is:
.Sp
.Vb 4
\&    $crc = 0;
\&    while (<STDIN>) {
\&        $crc = binhex_crc($_, $crc);
\&    }
.Ve
.Sp
\&\fINote:\fR Extracted from the \fImcvert\fR utility (Doug Moore, April '87),
using a \*(L"magic array\*(R" algorithm by Jim Van Verth for efficiency.
Converted to Perl5 by Eryq.
.SH "OO INTERFACE"
.IX Header "OO INTERFACE"
.SS "Conversion"
.IX Subsection "Conversion"
.IP "bin2hex" 4
.IX Item "bin2hex"
\&\fIClass method, constructor.\fR
Return a converter object.  Just creates a new instance of
\&\*(L"Convert::BinHex::Bin2Hex\*(R"; see that class for details.
.IP "hex2bin" 4
.IX Item "hex2bin"
\&\fIClass method, constructor.\fR
Return a converter object.  Just creates a new instance of
\&\*(L"Convert::BinHex::Hex2Bin\*(R"; see that class for details.
.SS "Construction"
.IX Subsection "Construction"
.IP "new \s-1PARAMHASH\s0" 4
.IX Item "new PARAMHASH"
\&\fIClass method, constructor.\fR
Return a handle on a BinHex'able entity.  In general, the data and resource
forks for such an entity are stored in native format (binary) format.
.Sp
Parameters in the \s-1PARAMHASH\s0 are the same as header-oriented method names,
and may be used to set attributes:
.Sp
.Vb 3
\&    $HQX = new Convert::BinHex filename => "icon.gif",
\&                               type    => "GIFB",
\&                               creator => "CNVS";
.Ve
.IP "open \s-1PARAMHASH\s0" 4
.IX Item "open PARAMHASH"
\&\fIClass method, constructor.\fR
Return a handle on a new BinHex'ed stream, for parsing.
Params are:
.RS 4
.IP "Data" 4
.IX Item "Data"
Input a \s-1HEX\s0 stream from the given data.  This can be a scalar, or a
reference to an array of scalars.
.IP "Expr" 4
.IX Item "Expr"
Input a \s-1HEX\s0 stream from any \fIopen()\fRable expression.  It will be opened and
binmode'd, and the filehandle will be closed either on a \f(CW\*(C`close()\*(C'\fR
or when the object is destructed.
.IP "\s-1FH\s0" 4
.IX Item "FH"
Input a \s-1HEX\s0 stream from the given filehandle.
.IP "NoComment" 4
.IX Item "NoComment"
If true, the parser should not attempt to skip a leading \*(L"(This file...)\*(R"
comment.  That means that the first nonwhite characters encountered
must be the binhex'ed data.
.RE
.RS 4
.RE
.SS "Get/set header information"
.IX Subsection "Get/set header information"
.IP "creator [\s-1VALUE\s0]" 4
.IX Item "creator [VALUE]"
\&\fIInstance method.\fR
Get/set the creator of the file.  This is a four-character
string (though I don't know if it's guaranteed to be printable \s-1ASCII\s0!)
that serves as part of the Macintosh's version of a \s-1MIME \s0\*(L"content-type\*(R".
.Sp
For example, a document created by \*(L"Canvas\*(R" might have
creator \f(CW"CNVS"\fR.
.IP "data [\s-1PARAMHASH\s0]" 4
.IX Item "data [PARAMHASH]"
\&\fIInstance method.\fR
Get/set the data fork.  Any arguments are passed into the
\&\fInew()\fR method of \*(L"Convert::BinHex::Fork\*(R".
.IP "filename [\s-1VALUE\s0]" 4
.IX Item "filename [VALUE]"
\&\fIInstance method.\fR
Get/set the name of the file.
.IP "flags [\s-1VALUE\s0]" 4
.IX Item "flags [VALUE]"
\&\fIInstance method.\fR
Return the flags, as an integer.  Use bitmasking to get as the values
you need.
.IP "header_as_string" 4
.IX Item "header_as_string"
Return a stringified version of the header that you might
use for logging/debugging purposes.  It looks like this:
.Sp
.Vb 7
\&    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
.Ve
.Sp
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.
.IP "requires [\s-1VALUE\s0]" 4
.IX Item "requires [VALUE]"
\&\fIInstance method.\fR
Get/set the software version required to convert this file, as
extracted from the comment that preceded the actual binhex'ed
data; e.g.:
.Sp
.Vb 1
\&    (This file must be converted with BinHex 4.0)
.Ve
.Sp
In this case, after parsing in the comment, the code:
.Sp
.Vb 1
\&    $HQX\->requires;
.Ve
.Sp
would get back \*(L"4.0\*(R".
.IP "resource [\s-1PARAMHASH\s0]" 4
.IX Item "resource [PARAMHASH]"
\&\fIInstance method.\fR
Get/set the resource fork.  Any arguments are passed into the
\&\fInew()\fR method of \*(L"Convert::BinHex::Fork\*(R".
.IP "type [\s-1VALUE\s0]" 4
.IX Item "type [VALUE]"
\&\fIInstance method.\fR
Get/set the type of the file.  This is a four-character
string (though I don't know if it's guaranteed to be printable \s-1ASCII\s0!)
that serves as part of the Macintosh's version of a \s-1MIME \s0\*(L"content-type\*(R".
.Sp
For example, a GIF89a file might have type \f(CW"GF89"\fR.
.IP "version [\s-1VALUE\s0]" 4
.IX Item "version [VALUE]"
\&\fIInstance method.\fR
Get/set the version, as an integer.
.SS "Decode, high-level"
.IX Subsection "Decode, high-level"
.IP "read_comment" 4
.IX Item "read_comment"
\&\fIInstance method.\fR
Skip past the opening comment in the file, which is of the form:
.Sp
.Vb 1
\&   (This file must be converted with BinHex 4.0)
.Ve
.Sp
As per \s-1RFC\-1741, \s0\fIthis comment must immediately precede the BinHex data,\fR
and any text before it will be ignored.
.Sp
\&\fIYou don't need to invoke this method yourself;\fR \f(CW\*(C`read_header()\*(C'\fR will
do it for you.  After the call, the version number in the comment is
accessible via the \f(CW\*(C`requires()\*(C'\fR method.
.IP "read_header" 4
.IX Item "read_header"
\&\fIInstance method.\fR
Read in the BinHex file header.  You must do this first!
.IP "read_data [\s-1NBYTES\s0]" 4
.IX Item "read_data [NBYTES]"
\&\fIInstance method.\fR
Read information from the data fork.  Use it in an array context to
slurp all the data into an array of scalars:
.Sp
.Vb 1
\&    @data = $HQX\->read_data;
.Ve
.Sp
Or use it in a scalar context to get the data piecemeal:
.Sp
.Vb 3
\&    while (defined($data = $HQX\->read_data)) {
\&       # do stuff with $data
\&    }
.Ve
.Sp
The \s-1NBYTES\s0 to read defaults to 2048.
.IP "read_resource [\s-1NBYTES\s0]" 4
.IX Item "read_resource [NBYTES]"
\&\fIInstance method.\fR
Read in all/some of the resource fork.
See \f(CW\*(C`read_data()\*(C'\fR for usage.
.SS "Encode, high-level"
.IX Subsection "Encode, high-level"
.IP "encode \s-1OUT\s0" 4
.IX Item "encode OUT"
Encode the object as a BinHex stream to the given output handle \s-1OUT.
OUT\s0 can be a filehandle, or any blessed object that responds to a
\&\f(CW\*(C`print()\*(C'\fR message.
.Sp
The leading comment is output, using the \f(CW\*(C`requires()\*(C'\fR attribute.
.SH "SUBMODULES"
.IX Header "SUBMODULES"
.SS "Convert::BinHex::Bin2Hex"
.IX Subsection "Convert::BinHex::Bin2Hex"
A BINary-to-HEX converter.  This kind of conversion requires
a certain amount of state information; it cannot be done by
just calling a simple function repeatedly.  Use it like this:
.PP
.Vb 6
\&    # 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>) { ...
.Ve
.PP
On each iteration, \f(CW\*(C`next()\*(C'\fR (and \f(CW\*(C`done()\*(C'\fR) 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.
.PP
Note that \f(CW\*(C`done()\*(C'\fR \fIalways\fR converts and hands you whatever is left.
.PP
This may have been a good approach.  It may not.  Someday, the converter
may also allow you give it an object that responds to \fIread()\fR, or
a FileHandle, and it will do all the nasty buffer-filling on its own,
serving you stuff line by line:
.PP
.Vb 5
\&    # Someday, maybe...
\&    my $B2H = Convert::BinHex\->bin2hex(\e*STDIN);
\&    while (defined($_ = $B2H\->getline)) {
\&        print STDOUT $_;
\&    }
.Ve
.PP
Someday, maybe.  Feel free to voice your opinions.
.SS "Convert::BinHex::Hex2Bin"
.IX Subsection "Convert::BinHex::Hex2Bin"
A HEX-to-BINary converter. This kind of conversion requires
a certain amount of state information; it cannot be done by
just calling a simple function repeatedly.  Use it like this:
.PP
.Vb 6
\&    # 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>) { ...
.Ve
.PP
On each iteration, \f(CW\*(C`next()\*(C'\fR (and \f(CW\*(C`done()\*(C'\fR) 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.
.PP
Note that \f(CW\*(C`done()\*(C'\fR \fIalways\fR converts and hands you whatever is left.
.PP
Note that this converter does \fInot\fR find the initial
\&\*(L"BinHex version\*(R" comment.  You have to skip that yourself.  It
only handles data between the opening and closing \f(CW":"\fR.
.SS "Convert::BinHex::Fork"
.IX Subsection "Convert::BinHex::Fork"
A fork in a Macintosh file.
.PP
.Vb 3
\&    # 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 => \e@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(\e@array_of_scalars);
\&
\&    # Get/set the CRC:
\&    $crc = $FORK\->crc;
\&    $FORK\->crc($crc);
.Ve
.SH "UNDER THE HOOD"
.IX Header "UNDER THE HOOD"
.SS "Design issues"
.IX Subsection "Design issues"
.IP "BinHex needs a stateful parser" 4
.IX Item "BinHex needs a stateful parser"
Unlike its cousins \fIbase64\fR and \fIuuencode\fR, BinHex format is not
amenable to being parsed line-by-line.  There appears to be no
guarantee that lines contain 4n encoded characters... and even if there
is one, the BinHex compression algorithm interferes: even when you
can \fIdecode\fR one line at a time, you can't necessarily
\&\fIdecompress\fR a line at a time.
.Sp
For example: a decoded line ending with the byte \f(CW\*(C`\ex90\*(C'\fR (the escape
or \*(L"mark\*(R" character) is ambiguous: depending on the next decoded byte,
it could mean a literal \f(CW\*(C`\ex90\*(C'\fR (if the next byte is a \f(CW\*(C`\ex00\*(C'\fR), or
it could mean n\-1 more repetitions of the previous character (if
the next byte is some nonzero \f(CW\*(C`n\*(C'\fR).
.Sp
For this reason, a BinHex parser has to be somewhat stateful: you
cannot have code like this:
.Sp
.Vb 4
\&    #### NO! #### NO! #### NO! #### NO! #### NO! ####
\&    while (<STDIN>) {            # read HEX
\&        print hexbin($_);          # convert and write BIN
\&    }
.Ve
.Sp
unless something is happening \*(L"behind the scenes\*(R" to keep track of
what was last done.  \fIThe dangerous thing, however, is that this
approach will \f(BIseem\fI to work, if you only test it on BinHex files
which do not use compression and which have 4n \s-1HEX\s0 characters
on each line.\fR
.Sp
Since we have to be stateful anyway, we use the parser object to
keep our state.
.IP "We need to be handle large input files" 4
.IX Item "We need to be handle large input files"
Solutions that demand reading everything into core don't cut
it in my book.  The first \s-1MPEG\s0 file that comes along can louse
up your whole day.  So, there are no size limitations in this
module: the data is read on-demand, and filehandles are always
an option.
.IP "Boy, is this slow!" 4
.IX Item "Boy, is this slow!"
A lot of the byte-level manipulation that has to go on, particularly
the \s-1CRC\s0 computing (which involves intensive bit-shifting and masking)
slows this module down significantly.  What is needed perhaps is an
\&\fIoptional\fR extension library where the slow pieces can be done more
quickly... a Convert::BinHex::CRC, if you will.  Volunteers, anyone?
.Sp
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...
.SS "How it works"
.IX Subsection "How it works"
Since BinHex is a layered format, consisting of...
.PP
.Vb 4
\&      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"]
.Ve
.PP
\&...there is a layered parsing algorithm to reverse the process.
Basically, it works in a similar fashion to stdio's \fIfread()\fR:
.PP
.Vb 11
\&       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.
.Ve
.PP
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.
.SH "WARNINGS"
.IX Header "WARNINGS"
Only handles \f(CW\*(C`Hqx7\*(C'\fR files, as per \s-1RFC\-1741.\s0
.PP
Remember that Macintosh text files use \f(CW"\er"\fR 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:
.PP
.Vb 2
\&    # Get the data, and output it according to normal conventions:
\&    foreach ($HQX\->read_data) { s/\er/\en/g; print }
.Ve
.SH "AUTHOR AND CREDITS"
.IX Header "AUTHOR AND CREDITS"
Maintained by Stephen Nelson <stephenenelson@mac.com>
.PP
Written by Eryq, \fIhttp://www.enteract.com/~eryq\fR / \fIeryq@enteract.com\fR
.PP
Support for native-Mac conversion, \fIplus\fR invaluable contributions in 
Alpha Testing, \fIplus\fR a few patches, \fIplus\fR the baseline binhex/debinhex
programs, were provided by Paul J. Schinder (\s-1NASA/GSFC\s0).
.PP
Ken Lunde (Adobe) suggested incorporating the \s-1CAP\s0 file representation.
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (c) 1997 by Eryq.  All rights reserved.  This program is free
software; you can redistribute it and/or modify it under the same terms as
Perl itself.
.PP
This software comes with \fB\s-1NO WARRANTY\s0\fR of any kind.
See the \s-1COPYING\s0 file in the distribution for details.