Data::FixedFormat 0.04 -- convert between fixed-length fields and hashes

	Copyright (C) 2000,2002,2007,2008 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 progam; if not, write to the Free
	Software Foundation, Inc., 59 Temple Place - Suite 330,
	Boston, MA 02111-1307, USA.

Data::FixedFormat is written and maintained by Thomas Pfau
<pfau@nbpfaus.net>.  Bug reports and patches are welcome.

Data::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.  Data::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.

Example:

   use Data::FixedFormat;

   my $tarhdr =
      new Data::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();

Data::FixedFormat supports variant record formats.  To describe a
variant structure, pass a hash reference containing the following
elements to new.  The object returned to handle variant records will
be a Data::FixedFormat::Variants which can be used is if it were a
Data::FixedFormat.  The format and unformat methods will determine
which variant to use automatically.  The blank method requires an
argument that specifies the variant number.

Example:

    my $cvt = new Data::FixedFormat {
        Chooser => sub { my $rec=shift;
		         $rec->{RecordType} eq '0' ? 1 : 2
		       },
	Formats => [ [ 'RecordType:A1' ],
		     [ 'RecordType:A1', 'FieldA:A6', 'FieldB:A4:4' ],
		     [ 'RecordType:A1', 'FieldC:A4', 'FieldD:A18' ] ]
        };
    my $rec0 = $cvt->unformat("0FieldAB[0]B[1]B[2]B[3]");
    my $rec1 = $cvt->unformat("1FldC<-----FieldD----->");

More details are provided in the module documentation.  Type 'perldoc
Data::FixedFormat' after installation.

Installation

Data::FixedFormat is installed in the standard way.  Unpack the
distribution, set default into the distribution directory and issue
the following commands.

	perl Makefile.PL
	make
	make test
	make install

History

Version 0.04 removes the requirement for perl 5.8.8 from Makefile.PL.
That was inserted by h2ph and I hadn't noticed it.

Version 0.03 provides comprehensive tests, a tied interface, and some
bug fixes.

Version 0.02 is a major restructuring of the code but the external
interface has not changed.  Provided you access its functionality
through its methods and don't poke around on the inside, your code
should continue to work with this version.  See the document Changes
for more detailed change information.