NAME
    Mac::Macbinary - Decodes Macbinary files

SYNOPSIS
      use Mac::Macbinary;

      $mb = Mac::Macbinary->new(\*FH);      # filehandle
      $mb = Mac::Macbinary->new($fh);       # IO::* instance
      $mb = Mac::Macbinary->new("/path/to/file");

      # do validation
      eval {
          $mb = Mac::Macbinary->new("/path/to/file", { validate => 1 });
      };

      $header = $mb->header;                # Mac::Macbinary::Header instance
      $name = $header->name;
  
DESCRIPTION
    This module provides an object-oriented way to extract various kinds of
    information from Macintosh Macbinary files.

METHODS
    Following methods are available.

  Class method
    new( THINGY, [ \%attr ] )
        Constructor of Mac::Macbinary. Accepts filhandle GLOB reference,
        FileHandle instance, IO::* instance, or whatever objects that can do
        "read" methods.

        If the argument belongs none of those above, "new()" treats it as a
        path to file. Any of following examples are valid constructors.

          open FH, "path/to/file";
          $mb = Mac::Macbinary->new(\*FH);

          $fh = FileHandle->new("path/to/file");
          $mb = Mac::Macbinary->new($fh);

          $io = IO::File->new("path/to/file");
          $mb = Mac::Macbinary->new($io);

          $mb = Mac::Macbinary->new("path/to/file");

        "new()" throws an exception "Can't read blahblah" if the given
        argument to the constructor is neither a valid filehandle nor an
        existing file.

        The optional \%attr parameter can be used for validation of file
        format. You can check and see if a file is really a Macbinary or not
        by setting "validate" attribute to 1.

          $fh = FileHandle->new("path/to/file");
          eval {
              $mb = Mac::Macbinary->new(FileHandle->new($fh), { 
                   validate => 1,
              });
          };
          if ($@) {
              warn "file is not a Macbinary.";
          }

  Instance Method
    data
        returns the data range of original file.

    header
        returns the header object (instance of Mac::Macbinary::Header).

    Following accessors are available via Mac::Macbinary::Header instance.

    name, type, creator, flags, location, dflen, rflen, cdate, mdate
        returns the original entry in the header of Macbinary file. Below is
        a structure of the info file, taken from MacBin.C

          char zero1;
          char nlen;
          char name[63];
          char type[4];           65      0101
          char creator[4];        69
          char flags;             73
          char zero2;             74      0112
          char location[6];       80
          char protected;         81      0121
          char zero3;             82      0122
          char dflen[4];
          char rflen[4];
          char cdate[4];
          char mdate[4];

EXAMPLE
    Some versions of MSIE for Macintosh sends their local files as Macbinary
    format via forms. You can decode them in a following way:

      use CGI;
      use Mac::Macbinary;

      $q = new CGI;
      $filename = $q->param('uploaded_file');
      $type = $q->uploadInfo($filename)->{'Content-Type'};
 
      if ($type eq 'application/x-macbinary') {
          $mb = Mac::Macbinary->new($q->upload('uploaded_file'));
          # now, you can get data via $mb->data;
      } 

COPYRIGHT
    Copyright 2000 Tatsuhiko Miyagawa <miyagawa@bulknews.net>

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

ACKNOWLEDGEMENT
    Macbinary.pm is originally written by Dan Kogai <dankogai@dan.co.jp>.

    There are also "Mac::Conversions" and "Convert::BinHex", working kind
    similar to this module. (However, "Mac::Conversions" works only on
    MacPerl, and "Convert::BinHex" is now deprecated.) Many thanks to Paul
    J. Schinder and Eryq, authors of those ones.

    Macbinary validation is almost a replication of is_macbinary in
    Mac::Conversions.

SEE ALSO
    perl(1), Mac::Conversions, Convert::BinHex.