NAME

       Parse::Binary::FixedFormat::Variants - Convert between variant records and hashes

DESCRIPTION

       Parse::Binary::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 Parse::Binary::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 Parse::Binary::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.

       Parse::Binary::FixedFormat::Variants can be  used  is  if  it  were  a  Parse::Binary::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 Parse::Binary::FixedFormat::Variants instance contains the following attributes.

       Layouts
           Contains an array of Parse::Binary::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.

AUTHORS

       Audrey Tang <cpan@audreyt.org>

       Based     on     Data::FixedFormat::Variants,     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.

perl v5.28.1                                       2018-12-20             Parse::Binary::...ormat::Variants(3pm)