| 1 | package Parse::Binary::FixedFormat::Variants; | ||
| 2 | |||
| 3 | use strict; | ||
| 4 | our $VERSION = "0.03"; | ||
| 5 | |||
| 6 | sub new { | ||
| 7 | my ($class,$recfmt) = @_; | ||
| 8 | my $self; | ||
| 9 | $self = { Layouts=>[], Chooser=>$recfmt->{Chooser}, Formats => $recfmt->{Formats} }; | ||
| 10 | bless $self, $class; | ||
| 11 | foreach my $fmt (@{$recfmt->{Formats}}) { | ||
| 12 | push @{$self->{Layouts}},new Parse::Binary::FixedFormat $fmt; | ||
| 13 | } | ||
| 14 | return $self; | ||
| 15 | } | ||
| 16 | |||
| 17 | sub unformat { | ||
| 18 | my ($self,$frec) = @_; | ||
| 19 | my $rec = $self->{Layouts}[0]->unformat($frec); | ||
| 20 | if ($self->{Chooser}) { | ||
| 21 | my $w = &{$self->{Chooser}}($rec, $self, 'unformat'); | ||
| 22 | $rec = $self->{Layouts}[$w]->unformat($frec) if $w; | ||
| 23 | } | ||
| 24 | return $rec; | ||
| 25 | } | ||
| 26 | |||
| 27 | sub format { | ||
| 28 | my ($self,$rec) = @_; | ||
| 29 | my $w = 0; | ||
| 30 | if ($self->{Chooser}) { | ||
| 31 | $w = &{$self->{Chooser}}($rec, $self, 'format'); | ||
| 32 | } | ||
| 33 | my $frec = $self->{Layouts}[$w]->format($rec); | ||
| 34 | return $frec; | ||
| 35 | } | ||
| 36 | |||
| 37 | sub blank { | ||
| 38 | my ($self,$w) = @_; | ||
| 39 | $w = 0 unless $w; | ||
| 40 | my $rec = $self->{Layouts}[$w]->blank(); | ||
| 41 | return $rec; | ||
| 42 | } | ||
| 43 | |||
| 44 | 1; | ||
| 45 | |||
| 46 | =head1 NAME | ||
| 47 | |||
| 48 | Parse::Binary::FixedFormat::Variants - Convert between variant records and hashes | ||
| 49 | |||
| 50 | =head1 DESCRIPTION | ||
| 51 | |||
| 52 | B<Parse::Binary::FixedFormat> supports variant record formats. To describe a | ||
| 53 | variant structure, pass a hash reference containing the following | ||
| 54 | elements to B<new>. The object returned to handle variant records | ||
| 55 | will be a B<Parse::Binary::FixedFormat::Variants>. | ||
| 56 | |||
| 57 | =over 4 | ||
| 58 | |||
| 59 | =item Chooser | ||
| 60 | |||
| 61 | When converting a buffer to a hash, this subroutine is invoked after | ||
| 62 | applying the first format to the buffer. The generated hash reference | ||
| 63 | is passed to this routine. Any field names specified in the first | ||
| 64 | format are available to be used in making a decision on which format | ||
| 65 | to use to decipher the buffer. This routine should return the index | ||
| 66 | of the proper format specification. | ||
| 67 | |||
| 68 | When converting a hash to a buffer, this subroutine is invoked first | ||
| 69 | to choose a packing format. Since the same function is used for both | ||
| 70 | conversions, this function should restrict itself to field names that | ||
| 71 | exist in format 0 and those fields should exist in the same place in | ||
| 72 | all formats. | ||
| 73 | |||
| 74 | =item Formats | ||
| 75 | |||
| 76 | This is a reference to a list of formats. Each format contains a list | ||
| 77 | of field specifications. | ||
| 78 | |||
| 79 | =back | ||
| 80 | |||
| 81 | For example: | ||
| 82 | |||
| 83 | my $cvt = new Parse::Binary::FixedFormat { | ||
| 84 | Chooser => sub { my $rec=shift; | ||
| 85 | $rec->{RecordType} eq '0' ? 1 : 2 | ||
| 86 | }, | ||
| 87 | Formats => [ [ 'RecordType:A1' ], | ||
| 88 | [ 'RecordType:A1', 'FieldA:A6', 'FieldB:A4:4' ], | ||
| 89 | [ 'RecordType:A1', 'FieldC:A4', 'FieldD:A18' ] ] | ||
| 90 | }; | ||
| 91 | my $rec0 = $cvt->unformat("0FieldAB[0]B[1]B[2]B[3]"); | ||
| 92 | my $rec1 = $cvt->unformat("1FldC<-----FieldD----->"); | ||
| 93 | |||
| 94 | In the above example, the C<Chooser> function looks at the contents of | ||
| 95 | the C<RecordType> field. If it contains a '0', format 1 is used. | ||
| 96 | Otherwise, format 2 is used. | ||
| 97 | |||
| 98 | B<Parse::Binary::FixedFormat::Variants> can be used is if it were a | ||
| 99 | B<Parse::Binary::FixedFormat>. The C<format> and C<unformat> methods will | ||
| 100 | determine which variant to use automatically. The C<blank> method | ||
| 101 | requires an argument that specifies the variant number. | ||
| 102 | |||
| 103 | =head1 ATTRIBUTES | ||
| 104 | |||
| 105 | Each Parse::Binary::FixedFormat::Variants instance contains the following | ||
| 106 | attributes. | ||
| 107 | |||
| 108 | =over 4 | ||
| 109 | |||
| 110 | =item Layouts | ||
| 111 | |||
| 112 | Contains an array of Parse::Binary::FixedFormat objects. Each of these objects | ||
| 113 | is responsible for converting a single record format variant. | ||
| 114 | |||
| 115 | =item Chooser | ||
| 116 | |||
| 117 | This attribute contains the function that chooses which variant to | ||
| 118 | apply to the record. | ||
| 119 | |||
| 120 | =back | ||
| 121 | |||
| 122 | =head1 AUTHORS | ||
| 123 | |||
| 124 | Audrey Tang E<lt>cpan@audreyt.orgE<gt> | ||
| 125 | |||
| 126 | Based on Data::FixedFormat::Variants, written by Thomas Pfau <pfau@nbpfaus.net> | ||
| 127 | http://nbpfaus.net/~pfau/. | ||
| 128 | |||
| 129 | =head1 COPYRIGHT | ||
| 130 | |||
| 131 | Copyright 2004-2009 by Audrey Tang E<lt>cpan@audreyt.orgE<gt>. | ||
| 132 | |||
| 133 | Copyright (C) 2000,2002 Thomas Pfau. All rights reserved. | ||
| 134 | |||
| 135 | This module is free software; you can redistribute it and/or modify it | ||
| 136 | under the terms of the GNU General Public License as published by the | ||
| 137 | Free Software Foundation; either version 2 of the License, or (at your | ||
| 138 | option) any later version. | ||
| 139 | |||
| 140 | This library is distributed in the hope that it will be useful, but | ||
| 141 | WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 142 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
| 143 | Library General Public License for more details. | ||
| 144 | |||
| 145 | You should have received a copy of the GNU General Public License | ||
| 146 | along with this program; if not, write to the Free Software Foundation, | ||
| 147 | Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. | ||
| 148 | |||
| 149 | =cut |