Data::FixedFormat - convert between fixed-length fields and hashes
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 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.
Data::FixedFormat provides the following methods.
To create a converter, invoke the new method with a reference to a list of field specifications.
my $cvt = new Data::FixedFormat [ 'field-name:descriptor:count', ... ];
Field specifications contain the following information.
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.
To convert a buffer of data into a hash, pass the buffer to the unformat method.
$hashref = $cvt->unformat($buf);
Data::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];
To convert the hash back into a fixed-format buffer, pass the hash reference to the format method.
$buf = $cvt->format($hashref);
To get a hash that can be used to create a new record, call the blank method.
$newrec = $cvt->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.
When converting a hash to a buffer, this subroutine is invoked 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.
For 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----->");
In the above example, the Chooser
function looks at the contents of
the RecordType
field. If it contains a '0', format 1 is used.
Otherwise, format 2 is used.
Data::FixedFormat::Variants 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.
Each Data::FixedFormat instance contains the following attributes.
Data::FixedFormat::Variants is a class that handles variant records. It contains the following attributes.
Version 0.02
This was a restructuring of the class. The initial implementation used a single package for variant and non-variant records. All attempts to format or unformat buffers resulted in checking for variants. Non-variant records can now skip this step and should be faster.
In this version, Data::FixedFormat was rewritten to handle a single
variant. The new
method now returns a
Data::FixedFormat::Variants if a variant record layout is
requested. This class maintains a list of Data::FixedFormat
objects to perform conversions.
This version also added the blank
method.
The documentation was updated and some corrections were made to the examples.
Version 0.01
This was the initial release.
Data::FixedFormat was written by Thomas Pfau <pfau@nbpfaus.net> http://nbpfaus.net/~pfau/.
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 progam; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.