{
    "content": [
        {
            "type": "text",
            "text": "# Convert::BinHex (perldoc)\n\n## NAME\n\nConvert::BinHex - extract data from Macintosh BinHex files  *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!*\n\n## SYNOPSIS\n\nSimple functions:\nuse Convert::BinHex qw(binhexcrc macbinarycrc);\n# Compute HQX7-style CRC for data, pumping in old CRC if desired:\n$crc = binhexcrc($data, $crc);\n# Compute the MacBinary-II-style CRC for the data:\n$crc = macbinarycrc($data, $crc);\nHex to bin, low-level interface. Conversion is actually done via an object\n(\"Convert::BinHex::Hex2Bin\") which keeps internal conversion state:\n# Create and use a \"translator\" object:\nmy $H2B = Convert::BinHex->hex2bin;    # get a converter object\nwhile (<STDIN>) {\nprint $STDOUT $H2B->next($);        # convert some more input\n}\nprint $STDOUT $H2B->done;              # no more input: finish up\nHex to bin, OO interface. The following operations *must* be done in the order shown!\n# Read data in piecemeal:\n$HQX = Convert::BinHex->open(FH=>\\*STDIN) || die \"open: $!\";\n$HQX->readheader;                  # read header info\n@data = $HQX->readdata;            # read in all the data\n@rsrc = $HQX->readresource;        # read in all the resource\nBin to hex, low-level interface. Conversion is actually done via an object\n(\"Convert::BinHex::Bin2Hex\") which keeps internal conversion state:\n# Create and use a \"translator\" object:\nmy $B2H = Convert::BinHex->bin2hex;    # get a converter object\nwhile (<STDIN>) {\nprint $STDOUT $B2H->next($);        # convert some more input\n}\nprint $STDOUT $B2H->done;              # no more input: finish up\nBin to hex, file interface. Yes, you can convert *to* BinHex as well as from it!\n# Create new, empty object:\nmy $HQX = Convert::BinHex->new;\n# Set header attributes:\n$HQX->filename(\"logo.gif\");\n$HQX->type(\"GIFA\");\n$HQX->creator(\"CNVS\");\n# Give it the data and resource forks (either can be absent):\n$HQX->data(Path => \"/path/to/data\");       # here, data is on disk\n$HQX->resource(Data => $resourcefork);     # here, resource is in core\n# Output as a BinHex stream, complete with leading comment:\n$HQX->encode(\\*STDOUT);\nPLANNED!!!! Bin to hex, \"CAP\" interface. *Thanks to Ken Lunde for suggesting this*.\n# Create new, empty object from CAP tree:\nmy $HQX = Convert::BinHex->fromcap(\"/path/to/root/file\");\n$HQX->encode(\\*STDOUT);\n\n## DESCRIPTION\n\nBinHex is a format used by Macintosh for transporting Mac files safely through electronic mail,\nas short-lined, 7-bit, semi-compressed data streams. Ths module provides a means of converting\nthose data streams back into into binary data.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **FORMAT**\n- **FUNCTIONS**\n- **OO INTERFACE** (4 subsections)\n- **SUBMODULES** (3 subsections)\n- **UNDER THE HOOD** (2 subsections)\n- **WARNINGS**\n- **AUTHOR AND CREDITS**\n- **LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Convert::BinHex",
        "section": "",
        "mode": "perldoc",
        "summary": "Convert::BinHex - extract data from Macintosh BinHex files  *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!*",
        "synopsis": "Simple functions:\nuse Convert::BinHex qw(binhexcrc macbinarycrc);\n# Compute HQX7-style CRC for data, pumping in old CRC if desired:\n$crc = binhexcrc($data, $crc);\n# Compute the MacBinary-II-style CRC for the data:\n$crc = macbinarycrc($data, $crc);\nHex to bin, low-level interface. Conversion is actually done via an object\n(\"Convert::BinHex::Hex2Bin\") which keeps internal conversion state:\n# Create and use a \"translator\" object:\nmy $H2B = Convert::BinHex->hex2bin;    # get a converter object\nwhile (<STDIN>) {\nprint $STDOUT $H2B->next($);        # convert some more input\n}\nprint $STDOUT $H2B->done;              # no more input: finish up\nHex to bin, OO interface. The following operations *must* be done in the order shown!\n# Read data in piecemeal:\n$HQX = Convert::BinHex->open(FH=>\\*STDIN) || die \"open: $!\";\n$HQX->readheader;                  # read header info\n@data = $HQX->readdata;            # read in all the data\n@rsrc = $HQX->readresource;        # read in all the resource\nBin to hex, low-level interface. Conversion is actually done via an object\n(\"Convert::BinHex::Bin2Hex\") which keeps internal conversion state:\n# Create and use a \"translator\" object:\nmy $B2H = Convert::BinHex->bin2hex;    # get a converter object\nwhile (<STDIN>) {\nprint $STDOUT $B2H->next($);        # convert some more input\n}\nprint $STDOUT $B2H->done;              # no more input: finish up\nBin to hex, file interface. Yes, you can convert *to* BinHex as well as from it!\n# Create new, empty object:\nmy $HQX = Convert::BinHex->new;\n# Set header attributes:\n$HQX->filename(\"logo.gif\");\n$HQX->type(\"GIFA\");\n$HQX->creator(\"CNVS\");\n# Give it the data and resource forks (either can be absent):\n$HQX->data(Path => \"/path/to/data\");       # here, data is on disk\n$HQX->resource(Data => $resourcefork);     # here, resource is in core\n# Output as a BinHex stream, complete with leading comment:\n$HQX->encode(\\*STDOUT);\nPLANNED!!!! Bin to hex, \"CAP\" interface. *Thanks to Ken Lunde for suggesting this*.\n# Create new, empty object from CAP tree:\nmy $HQX = Convert::BinHex->fromcap(\"/path/to/root/file\");\n$HQX->encode(\\*STDOUT);",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 61,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "FORMAT",
                "lines": 31,
                "subsections": []
            },
            {
                "name": "FUNCTIONS",
                "lines": 27,
                "subsections": []
            },
            {
                "name": "OO INTERFACE",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Conversion",
                        "lines": 8
                    },
                    {
                        "name": "Construction",
                        "lines": 89
                    },
                    {
                        "name": "Decode, high-level",
                        "lines": 31
                    },
                    {
                        "name": "Encode, high-level",
                        "lines": 6
                    }
                ]
            },
            {
                "name": "SUBMODULES",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Convert::BinHex::Bin2Hex",
                        "lines": 33
                    },
                    {
                        "name": "Convert::BinHex::Hex2Bin",
                        "lines": 24
                    },
                    {
                        "name": "Convert::BinHex::Fork",
                        "lines": 28
                    }
                ]
            },
            {
                "name": "UNDER THE HOOD",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Design issues",
                        "lines": 39
                    },
                    {
                        "name": "How it works",
                        "lines": 27
                    }
                ]
            },
            {
                "name": "WARNINGS",
                "lines": 8,
                "subsections": []
            },
            {
                "name": "AUTHOR AND CREDITS",
                "lines": 10,
                "subsections": []
            },
            {
                "name": "LICENSE",
                "lines": 6,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Convert::BinHex - extract data from Macintosh BinHex files\n\n*ALPHA WARNING: this code is currently in its Alpha release. Things may change drastically until\nthe interface is hammered out: if you have suggestions or objections, please speak up now!*\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "Simple functions:\n\nuse Convert::BinHex qw(binhexcrc macbinarycrc);\n\n# Compute HQX7-style CRC for data, pumping in old CRC if desired:\n$crc = binhexcrc($data, $crc);\n\n# Compute the MacBinary-II-style CRC for the data:\n$crc = macbinarycrc($data, $crc);\n\nHex to bin, low-level interface. Conversion is actually done via an object\n(\"Convert::BinHex::Hex2Bin\") which keeps internal conversion state:\n\n# Create and use a \"translator\" object:\nmy $H2B = Convert::BinHex->hex2bin;    # get a converter object\nwhile (<STDIN>) {\nprint $STDOUT $H2B->next($);        # convert some more input\n}\nprint $STDOUT $H2B->done;              # no more input: finish up\n\nHex to bin, OO interface. The following operations *must* be done in the order shown!\n\n# Read data in piecemeal:\n$HQX = Convert::BinHex->open(FH=>\\*STDIN) || die \"open: $!\";\n$HQX->readheader;                  # read header info\n@data = $HQX->readdata;            # read in all the data\n@rsrc = $HQX->readresource;        # read in all the resource\n\nBin to hex, low-level interface. Conversion is actually done via an object\n(\"Convert::BinHex::Bin2Hex\") which keeps internal conversion state:\n\n# Create and use a \"translator\" object:\nmy $B2H = Convert::BinHex->bin2hex;    # get a converter object\nwhile (<STDIN>) {\nprint $STDOUT $B2H->next($);        # convert some more input\n}\nprint $STDOUT $B2H->done;              # no more input: finish up\n\nBin to hex, file interface. Yes, you can convert *to* BinHex as well as from it!\n\n# Create new, empty object:\nmy $HQX = Convert::BinHex->new;\n\n# Set header attributes:\n$HQX->filename(\"logo.gif\");\n$HQX->type(\"GIFA\");\n$HQX->creator(\"CNVS\");\n\n# Give it the data and resource forks (either can be absent):\n$HQX->data(Path => \"/path/to/data\");       # here, data is on disk\n$HQX->resource(Data => $resourcefork);     # here, resource is in core\n\n# Output as a BinHex stream, complete with leading comment:\n$HQX->encode(\\*STDOUT);\n\nPLANNED!!!! Bin to hex, \"CAP\" interface. *Thanks to Ken Lunde for suggesting this*.\n\n# Create new, empty object from CAP tree:\nmy $HQX = Convert::BinHex->fromcap(\"/path/to/root/file\");\n$HQX->encode(\\*STDOUT);\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "BinHex is a format used by Macintosh for transporting Mac files safely through electronic mail,\nas short-lined, 7-bit, semi-compressed data streams. Ths module provides a means of converting\nthose data streams back into into binary data.\n",
                "subsections": []
            },
            "FORMAT": {
                "content": "*(Some text taken from RFC-1741.)* Files on the Macintosh consist of two parts, called *forks*:\n\nData fork\nThe actual data included in the file. The Data fork is typically the only meaningful part of\na Macintosh file on a non-Macintosh computer system. For example, if a Macintosh user wants\nto send a file of data to a user on an IBM-PC, she would only send the Data fork.\n\nResource fork\nContains a collection of arbitrary attribute/value pairs, including program segments, icon\nbitmaps, and parametric values.\n\nAdditional information regarding Macintosh files is stored by the Finder in a hidden file,\ncalled the \"Desktop Database\".\n\nBecause of the complications in storing different parts of a Macintosh file in a non-Macintosh\nfilesystem that only handles consecutive data in one part, it is common to convert the Macintosh\nfile into some other format before transferring it over the network. The BinHex format squashes\nthat data into transmittable ASCII as follows:\n\n1.  The file is output as a byte stream consisting of some basic header information (filename,\ntype, creator), then the data fork, then the resource fork.\n\n2.  The byte stream is compressed by looking for series of duplicated bytes and representing\nthem using a special binary escape sequence (of course, any occurences of the escape\ncharacter must also be escaped).\n\n3.  The compressed stream is encoded via the \"6/8 hemiola\" common to *base64* and *uuencode*:\neach group of three 8-bit bytes (24 bits) is chopped into four 6-bit numbers, which are used\nas indexes into an ASCII \"alphabet\". (I assume that leftover bytes are zero-padded;\ndocumentation is thin).\n",
                "subsections": []
            },
            "FUNCTIONS": {
                "content": "CRC computation\nmacbinarycrc DATA, SEED\nCompute the MacBinary-II-style CRC for the given DATA, with the CRC seeded to SEED.\nNormally, you start with a SEED of 0, and you pump in the previous CRC as the SEED if you're\nhandling a lot of data one chunk at a time. That is:\n\n$crc = 0;\nwhile (<STDIN>) {\n$crc = macbinarycrc($, $crc);\n}\n\n*Note:* Extracted from the *mcvert* utility (Doug Moore, April '87), using a \"magic array\"\nalgorithm by Jim Van Verth for efficiency. Converted to Perl5 by Eryq. Untested.\n\nbinhexcrc DATA, SEED\nCompute the HQX-style CRC for the given DATA, with the CRC seeded to SEED. Normally, you\nstart with a SEED of 0, and you pump in the previous CRC as the SEED if you're handling a\nlot of data one chunk at a time. That is:\n\n$crc = 0;\nwhile (<STDIN>) {\n$crc = binhexcrc($, $crc);\n}\n\n*Note:* Extracted from the *mcvert* utility (Doug Moore, April '87), using a \"magic array\"\nalgorithm by Jim Van Verth for efficiency. Converted to Perl5 by Eryq.\n",
                "subsections": []
            },
            "OO INTERFACE": {
                "content": "",
                "subsections": [
                    {
                        "name": "Conversion",
                        "content": "bin2hex\n*Class method, constructor.* Return a converter object. Just creates a new instance of\n\"Convert::BinHex::Bin2Hex\"; see that class for details.\n\nhex2bin\n*Class method, constructor.* Return a converter object. Just creates a new instance of\n\"Convert::BinHex::Hex2Bin\"; see that class for details.\n"
                    },
                    {
                        "name": "Construction",
                        "content": "new PARAMHASH\n*Class method, constructor.* Return a handle on a BinHex'able entity. In general, the data\nand resource forks for such an entity are stored in native format (binary) format.\n\nParameters in the PARAMHASH are the same as header-oriented method names, and may be used to\nset attributes:\n\n$HQX = new Convert::BinHex filename => \"icon.gif\",\ntype    => \"GIFB\",\ncreator => \"CNVS\";\n\nopen PARAMHASH\n*Class method, constructor.* Return a handle on a new BinHex'ed stream, for parsing. Params\nare:\n\nData\nInput a HEX stream from the given data. This can be a scalar, or a reference to an array\nof scalars.\n\nExpr\nInput a HEX stream from any open()able expression. It will be opened and binmode'd, and\nthe filehandle will be closed either on a \"close()\" or when the object is destructed.\n\nFH  Input a HEX stream from the given filehandle.\n\nNoComment\nIf true, the parser should not attempt to skip a leading \"(This file...)\" comment. That\nmeans that the first nonwhite characters encountered must be the binhex'ed data.\n\nGet/set header information\ncreator [VALUE]\n*Instance method.* Get/set the creator of the file. This is a four-character string (though\nI don't know if it's guaranteed to be printable ASCII!) that serves as part of the\nMacintosh's version of a MIME \"content-type\".\n\nFor example, a document created by \"Canvas\" might have creator \"CNVS\".\n\ndata [PARAMHASH]\n*Instance method.* Get/set the data fork. Any arguments are passed into the new() method of\n\"Convert::BinHex::Fork\".\n\nfilename [VALUE]\n*Instance method.* Get/set the name of the file.\n\nflags [VALUE]\n*Instance method.* Return the flags, as an integer. Use bitmasking to get as the values you\nneed.\n\nheaderasstring\nReturn a stringified version of the header that you might use for logging/debugging\npurposes. It looks like this:\n\nX-HQX-Software: BinHex 4.0 (Convert::BinHex 1.102)\nX-HQX-Filename: Somethingnew.eps\nX-HQX-Version: 0\nX-HQX-Type: EPSF\nX-HQX-Creator: ART5\nX-HQX-Data-Length: 49731\nX-HQX-Rsrc-Length: 23096\n\nAs some of you might have guessed, this is RFC-822-style, and may be easily plunked down\ninto the middle of a mail header, or split into lines, etc.\n\nrequires [VALUE]\n*Instance method.* Get/set the software version required to convert this file, as extracted\nfrom the comment that preceded the actual binhex'ed data; e.g.:\n\n(This file must be converted with BinHex 4.0)\n\nIn this case, after parsing in the comment, the code:\n\n$HQX->requires;\n\nwould get back \"4.0\".\n\nresource [PARAMHASH]\n*Instance method.* Get/set the resource fork. Any arguments are passed into the new() method\nof \"Convert::BinHex::Fork\".\n\ntype [VALUE]\n*Instance method.* Get/set the type of the file. This is a four-character string (though I\ndon't know if it's guaranteed to be printable ASCII!) that serves as part of the Macintosh's\nversion of a MIME \"content-type\".\n\nFor example, a GIF89a file might have type \"GF89\".\n\nversion [VALUE]\n*Instance method.* Get/set the version, as an integer.\n"
                    },
                    {
                        "name": "Decode, high-level",
                        "content": "readcomment\n*Instance method.* Skip past the opening comment in the file, which is of the form:\n\n(This file must be converted with BinHex 4.0)\n\nAs per RFC-1741, *this comment must immediately precede the BinHex data,* and any text\nbefore it will be ignored.\n\n*You don't need to invoke this method yourself;* \"readheader()\" will do it for you. After\nthe call, the version number in the comment is accessible via the \"requires()\" method.\n\nreadheader\n*Instance method.* Read in the BinHex file header. You must do this first!\n\nreaddata [NBYTES]\n*Instance method.* Read information from the data fork. Use it in an array context to slurp\nall the data into an array of scalars:\n\n@data = $HQX->readdata;\n\nOr use it in a scalar context to get the data piecemeal:\n\nwhile (defined($data = $HQX->readdata)) {\n# do stuff with $data\n}\n\nThe NBYTES to read defaults to 2048.\n\nreadresource [NBYTES]\n*Instance method.* Read in all/some of the resource fork. See \"readdata()\" for usage.\n"
                    },
                    {
                        "name": "Encode, high-level",
                        "content": "encode OUT\nEncode the object as a BinHex stream to the given output handle OUT. OUT can be a\nfilehandle, or any blessed object that responds to a \"print()\" message.\n\nThe leading comment is output, using the \"requires()\" attribute.\n"
                    }
                ]
            },
            "SUBMODULES": {
                "content": "",
                "subsections": [
                    {
                        "name": "Convert::BinHex::Bin2Hex",
                        "content": "A BINary-to-HEX converter. This kind of conversion requires a certain amount of state\ninformation; it cannot be done by just calling a simple function repeatedly. Use it like this:\n\n# Create and use a \"translator\" object:\nmy $B2H = Convert::BinHex->bin2hex;    # get a converter object\nwhile (<STDIN>) {\nprint STDOUT $B2H->next($);          # convert some more input\n}\nprint STDOUT $B2H->done;               # no more input: finish up\n\n# Re-use the object:\n$B2H->rewind;                 # ready for more action!\nwhile (<MOREIN>) { ...\n\nOn each iteration, \"next()\" (and \"done()\") may return either a decent-sized non-empty string\n(indicating that more converted data is ready for you) or an empty string (indicating that the\nconverter is waiting to amass more input in its private buffers before handing you more stuff to\noutput.\n\nNote that \"done()\" *always* converts and hands you whatever is left.\n\nThis may have been a good approach. It may not. Someday, the converter may also allow you give\nit an object that responds to read(), or a FileHandle, and it will do all the nasty\nbuffer-filling on its own, serving you stuff line by line:\n\n# Someday, maybe...\nmy $B2H = Convert::BinHex->bin2hex(\\*STDIN);\nwhile (defined($ = $B2H->getline)) {\nprint STDOUT $;\n}\n\nSomeday, maybe. Feel free to voice your opinions.\n"
                    },
                    {
                        "name": "Convert::BinHex::Hex2Bin",
                        "content": "A HEX-to-BINary converter. This kind of conversion requires a certain amount of state\ninformation; it cannot be done by just calling a simple function repeatedly. Use it like this:\n\n# Create and use a \"translator\" object:\nmy $H2B = Convert::BinHex->hex2bin;    # get a converter object\nwhile (<STDIN>) {\nprint STDOUT $H2B->next($);          # convert some more input\n}\nprint STDOUT $H2B->done;               # no more input: finish up\n\n# Re-use the object:\n$H2B->rewind;                 # ready for more action!\nwhile (<MOREIN>) { ...\n\nOn each iteration, \"next()\" (and \"done()\") may return either a decent-sized non-empty string\n(indicating that more converted data is ready for you) or an empty string (indicating that the\nconverter is waiting to amass more input in its private buffers before handing you more stuff to\noutput.\n\nNote that \"done()\" *always* converts and hands you whatever is left.\n\nNote that this converter does *not* find the initial \"BinHex version\" comment. You have to skip\nthat yourself. It only handles data between the opening and closing \":\".\n"
                    },
                    {
                        "name": "Convert::BinHex::Fork",
                        "content": "A fork in a Macintosh file.\n\n# How to get them...\n$datafork = $HQX->data;      # get the data fork\n$rsrcfork = $HQX->resource;  # get the resource fork\n\n# Make a new fork:\n$FORK = Convert::BinHex::Fork->new(Path => \"/tmp/file.data\");\n$FORK = Convert::BinHex::Fork->new(Data => $scalar);\n$FORK = Convert::BinHex::Fork->new(Data => \\@arrayofscalars);\n\n# Get/set the length of the data fork:\n$len = $FORK->length;\n$FORK->length(170);        # this overrides the REAL value: be careful!\n\n# Get/set the path to the underlying data (if in a disk file):\n$path = $FORK->path;\n$FORK->path(\"/tmp/file.data\");\n\n# Get/set the in-core data itself, which may be a scalar or an arrayref:\n$data = $FORK->data;\n$FORK->data($scalar);\n$FORK->data(\\@arrayofscalars);\n\n# Get/set the CRC:\n$crc = $FORK->crc;\n$FORK->crc($crc);\n"
                    }
                ]
            },
            "UNDER THE HOOD": {
                "content": "",
                "subsections": [
                    {
                        "name": "Design issues",
                        "content": "BinHex needs a stateful parser\nUnlike its cousins *base64* and *uuencode*, BinHex format is not amenable to being parsed\nline-by-line. There appears to be no guarantee that lines contain 4n encoded characters...\nand even if there is one, the BinHex compression algorithm interferes: even when you can\n*decode* one line at a time, you can't necessarily *decompress* a line at a time.\n\nFor example: a decoded line ending with the byte \"\\x90\" (the escape or \"mark\" character) is\nambiguous: depending on the next decoded byte, it could mean a literal \"\\x90\" (if the next\nbyte is a \"\\x00\"), or it could mean n-1 more repetitions of the previous character (if the\nnext byte is some nonzero \"n\").\n\nFor this reason, a BinHex parser has to be somewhat stateful: you cannot have code like\nthis:\n\n#### NO! #### NO! #### NO! #### NO! #### NO! ####\nwhile (<STDIN>) {            # read HEX\nprint hexbin($);          # convert and write BIN\n}\n\nunless something is happening \"behind the scenes\" to keep track of what was last done. *The\ndangerous thing, however, is that this approach will seem to work, if you only test it on\nBinHex files which do not use compression and which have 4n HEX characters on each line.*\n\nSince we have to be stateful anyway, we use the parser object to keep our state.\n\nWe need to be handle large input files\nSolutions that demand reading everything into core don't cut it in my book. The first MPEG\nfile that comes along can louse up your whole day. So, there are no size limitations in this\nmodule: the data is read on-demand, and filehandles are always an option.\n\nBoy, is this slow!\nA lot of the byte-level manipulation that has to go on, particularly the CRC computing\n(which involves intensive bit-shifting and masking) slows this module down significantly.\nWhat is needed perhaps is an *optional* extension library where the slow pieces can be done\nmore quickly... a Convert::BinHex::CRC, if you will. Volunteers, anyone?\n\nEven considering that, however, it's slower than I'd like. I'm sure many improvements can be\nmade in the HEX-to-BIN end of things. No doubt I'll attempt some as time goes on...\n"
                    },
                    {
                        "name": "How it works",
                        "content": "Since BinHex is a layered format, consisting of...\n\nA Macintosh file [the \"BIN\"]...\nEncoded as a structured 8-bit bytestream, then...\nCompressed to reduce duplicate bytes, then...\nEncoded as 7-bit ASCII [the \"HEX\"]\n\n...there is a layered parsing algorithm to reverse the process. Basically, it works in a similar\nfashion to stdio's fread():\n\n0. There is an internal buffer of decompressed (BIN) data,\ninitially empty.\n1. Application asks to read() n bytes of data from object\n2. If the buffer is not full enough to accommodate the request:\n2a. The read() method grabs the next available chunk of input\ndata (the HEX).\n2b. HEX data is converted and decompressed into as many BIN\nbytes as possible.\n2c. BIN bytes are added to the read() buffer.\n2d. Go back to step 2a. until the buffer is full enough\nor we hit end-of-input.\n\nThe conversion-and-decompression algorithms need their own internal buffers and state (since the\nnext input chunk may not contain all the data needed for a complete conversion/decompression\noperation). These are maintained in the object, so parsing two different input streams\nsimultaneously is possible.\n"
                    }
                ]
            },
            "WARNINGS": {
                "content": "Only handles \"Hqx7\" files, as per RFC-1741.\n\nRemember that Macintosh text files use \"\\r\" as end-of-line: this means that if you want a\ntextual file to look normal on a non-Mac system, you probably want to do this to the data:\n\n# Get the data, and output it according to normal conventions:\nforeach ($HQX->readdata) { s/\\r/\\n/g; print }\n",
                "subsections": []
            },
            "AUTHOR AND CREDITS": {
                "content": "Maintained by Stephen Nelson <stephenenelson@mac.com>\n\nWritten by Eryq, http://www.enteract.com/~eryq / eryq@enteract.com\n\nSupport for native-Mac conversion, *plus* invaluable contributions in Alpha Testing, *plus* a\nfew patches, *plus* the baseline binhex/debinhex programs, were provided by Paul J. Schinder\n(NASA/GSFC).\n\nKen Lunde (Adobe) suggested incorporating the CAP file representation.\n",
                "subsections": []
            },
            "LICENSE": {
                "content": "Copyright (c) 1997 by Eryq. All rights reserved. This program is free software; you can\nredistribute it and/or modify it under the same terms as Perl itself.\n\nThis software comes with NO WARRANTY of any kind. See the COPYING file in the distribution for\ndetails.\n",
                "subsections": []
            }
        }
    }
}