/ 
Data-FixedFormat-0.01
River stage zero No dependents
/ Data::FixedFormat

NAME

Data::FixedFormat - converter between fixed-fields and hashes

SYNOPSIS

   use Data::FixedFormat;

   my $tarhdr = new Data::FixedFormat [ '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

DESCRIPTION

Data::FixedFormat can be used to convert between a buffer with fixed field definitions and a hash with named entries for each field.

First, load the Data::FixedFormat module:

use Data::FixedFormat;

To create a converter, invoke the new method with a reference to an array of field specifications:

my $cvt = new Data::FixedFormat [ 'field-name:descriptor:count', ... ];
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.

count

This specifies a repeat count for the field. If not specified, it defaults to 1. If greater than 1, this field's entry in the resultant hash will be an array reference instead of a scalar.

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

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

Data::FixedFormat applies the format to the buffer and creates a hash containing an element for each field. Fields can now be accessed by name though the hash:

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

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

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

Variant record formats are supported. Instead of passing an array reference to the new method, pass a hash reference containing the following elements:

Chooser

When converting a buffer to a hash, this subroutine is invoked after applying the first format to the buffer. The hash reference is passed to this routine. Any field names specified in the first format are available to be used in making a decision on which format to use to decipher the buffer. This routine should return the index of the proper format specification.

When converting a hash to a buffer, this subroutine is invoked to first to choose a packing format. Since the same function is used for both conversions, this function should restrict itself to field names that exist in format 0 and those fields should exist in the same place in all formats.

Formats

This is a reference to an array of references to formats.

For example:

    my $cvt = new Data::FixedFormat {
        Chooser => sub { $_[0]->{RecordType} eq '0' ? 1 : 2 },
	Format => [ [ '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----->");

Each Data::FixedFormat instance also contains the following attributes:

Names

Names contains a list of lists of field names indexed as [record variant, field number]. For example, to find the third field name in a non-variant record, use $cvt-{Names}[0][2]>.

Count

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

Format

Format contains a list of template strings for the Perl pack and unpack functions.

AUTHOR

Data::FixedFormat was written by Thomas Pfau <pfau@eclipse.net> http://www.eclipse.net/~pfau/.

COPYRIGHT

Copyright (C) 2000 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.