The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Data-FixedFormat-0.04
River stage zero No dependents
++
/ Data::FixedFormat

NAME

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

SYNOPSIS

   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 tied hash from the buffer
   my $hdr = $tarhdr->unformat_tied($buf); # $hdr gets a ref to a tied hash

   # 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

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.

METHODS

Data::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 Data::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);

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];

unformat_tied

unformat_tied works just like unformat except the returned object is a reference to a tied hash. This could provide large performance improvements when referencing only a few fields in complex record definitions. The tied interface does not support arrays.

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();

VARIANT RECORDS

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.

Chooser

When converting a buffer to a hash, this subroutine is invoked after applying the first format to the buffer. The generated 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 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 a list of formats. Each format contains a list of field specifications.

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.

ATTRIBUTES

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

Fields

Fields is a hash mapping field names to an index into the list returned by unpack.

Data::FixedFormat::Variants is a class that handles variant records. It contains the following attributes.

Layouts

Contains an array of Data::FixedFormat objects. Each of these objects is responsible for converting a single record format variant.

Chooser

This attribute contains the function that chooses which variant to apply to the record.

HISTORY

Version 0.03

Added some comprehensive tests. The tests exposed some bugs and those were fixed.

Added the tied interface.

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.

AUTHOR

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

COPYRIGHT

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