NAME

       Parse::Binary::FixedFormat - Convert between fixed-length fields and hashes

SYNOPSIS

          use Parse::Binary::FixedFormat;

          my $tarhdr =
             new Parse::Binary::FixedFormat [ qw(name:a100 mode:a8 uid:a8 gid:a8 size:a12
                                        mtime:a12 chksum:a8 typeflag:a1 linkname:a100
                                        magic:a6 version:a2 uname:a32 gname:a32
                                        devmajor:a8 devminor:a8 prefix:a155) ];
          my $buf;
          read TARFILE, $buf, 512;

          # create a hash from the buffer read from the file
          my $hdr = $tarhdr->unformat($buf);   # $hdr gets a hash ref

          # create a flat record from a hash reference
          my $buf = $tarhdr->format($hdr);     # $hdr is a hash ref

          # create a hash for a new record
          my $newrec = $tarhdr->blank();

DESCRIPTION

       Parse::Binary::FixedFormat can be used to convert between a buffer with fixed-length field
       definitions and a hash with named entries for each field.  The perl "pack" and "unpack"
       functions are used to perform the conversions.  Parse::Binary::FixedFormat builds the
       format string by concatenating the field descriptions and converts between the lists used
       by "pack" and "unpack" and a hash that can be reference by field name.

METHODS

       Parse::Binary::FixedFormat provides the following methods.

   new
       To create a converter, invoke the new method with a reference to a list of field
       specifications.

           my $cvt =
               new Parse::Binary::FixedFormat [ 'field-name:descriptor:count', ... ];

       Field specifications contain the following information.

       field-name
           This is the name of the field and will be used as the hash index.

       descriptor
           This describes the content and size of the field.  All of the descriptors get strung
           together and passed to pack and unpack as part of the template argument.  See perldoc
           -f pack for information on what can be specified here.

           Don't use repeat counts in the descriptor except for string types ("a", "A", "h, "H",
           and "Z").  If you want to get an array out of the buffer, use the "count" argument.

       count
           This specifies a repeat count for the field.  If specified as a non-zero value, this
           field's entry in the resultant hash will be an array reference instead of a scalar.

   unformat
       To convert a buffer of data into a hash, pass the buffer to the unformat method.

           $hashref = $cvt->unformat($buf);

       Parse::Binary::FixedFormat applies the constructed format to the buffer with "unpack" and
       maps the returned list of elements to hash entries.  Fields can now be accessed by name
       though the hash:

           print $hashref->{field-name};
           print $hashref->{array-field}[3];

   format
       To convert the hash back into a fixed-format buffer, pass the hash reference to the format
       method.

           $buf = $cvt->format($hashref);

   blank
       To get a hash that can be used to create a new record, call the blank method.

           $newrec = $cvt->blank();

ATTRIBUTES

       Each Parse::Binary::FixedFormat instance contains the following attributes.

       Names
           Names contains a list of the field names for this variant.

       Count
           Count contains a list of occurrence counts.  This is used to indicate which fields
           contain arrays.

       Format
           Format contains the template string for the Perl pack and unpack functions.

AUTHORS

       Audrey Tang <cpan@audreyt.org>

       Based on Data::FixedFormat, written by Thomas Pfau <pfau@nbpfaus.net>
       http://nbpfaus.net/~pfau/.

COPYRIGHT

       Copyright 2004-2009 by Audrey Tang <cpan@audreyt.org>.

       Copyright (C) 2000,2002 Thomas Pfau.  All rights reserved.

       This module is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation; either
       version 2 of the License, or (at your option) any later version.

       This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU Library General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program;
       if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
       MA 02111-1307, USA.