view release on metacpan or  search on metacpan

lib/Finnigan/Decoder.pm  view on Meta::CPAN

  }
}

sub purge_unused_data {
  my $self = shift;
  delete $self->{current_element_number};
  delete $self->{addr};
  delete $self->{size};
  foreach my $key (keys %{$self->{data}}) {
    if ( substr($key, 0, 4) eq 'unkn' ) {
      delete $self->{data}->{$key};
    }
    else {
      delete $self->{data}->{$key}->{type};
      delete $self->{data}->{$key}->{addr};
      delete $self->{data}->{$key}->{seq};
      delete $self->{data}->{$key}->{size};
    }
  }
  return $self;
}

1;
__END__
=head1 NAME

Finnigan::Decoder - a generic binary structure decoder

=head1 SYNOPSIS

  use Finnigan;

  my $fields = [
    short_int => 'v',
    long_int => 'V',
    ascii_string => 'C60',
    wide_string => 'U0C18',
    audit_tag => 'object=Finnigan::AuditTag',
    time => 'windows_time',
  ];

  my $data = Finnigan::Decoder->read(\*STREAM, $fields);


=head1 DESCRIPTION

This class is not inteded to be used directly; it is a parent class
for all Finnigan decoders. The fields to decode are passed to
the decoder's read() method in a list reference, where every even item
specifies the key the item will be known as in the resulting hash, and
every odd item specifies the unpack template.

Perl unpack templates are used to decode most fields. For some fields, non-perl templates are used, such as:

=over 2

=item * object: instructs the current decoder to call another Finnigan decoder at that location.

=item * windows_time: instructs Finingan::Decoder to call its own Windows timestamp routine.

=item * varstr: decoded as a Windows Pascal string in a special case in the Finnigan::Decoder::read() method.

=back

=head2 METHODS

=over 4

=item read($class, $stream, $fields, $any_arg)

Returns a new decoder blessed into class C<$class> and initialized
with the values read from C<$stream> and decoded according to a list
of templates specified in C<$fields>.

The fourth argument, C<$any_arg> is not used by the Decoder class, but
may be used by derived classes to pass parse context to their
component decoders. For example, this can be useful to parse
structures whose layout is governed by the data they contain; in that
case if the layout indicator is read by the top-level decoder, it can
be passed to lower-level decoders whose work depends on it. Also, this
argument is used by the user program to pass the Finnigan file version
to version-sensitive decoders.

Here is an example of the template list for a simple decoder:

  my $fields = [
    "mz"        => ['f<', 'Float32'],
    "abundance" => ['f<', 'Float32'],
  ];

=item decode($stream, $fields, $any_arg)

This method must be called on a blessed, instantiated Decoder. The
C<read()> method calls it internally, but it can also be used by the
user code in those cases where not all data can be decoded with a
plain list of templates. In some cases, it may be necessary to decode
one part of an object, analyse it, make decisions about the rest
(calculate sizes, layouts, etc.), and then grow the object under
construction by decoding more data from the stream.


=item iterate_scalar($stream, $count, $name, $desc)

This method is similar to the C<decode> metod, in that it does not
instantiate a Decoder, but rather adds data to an existing one. Its
purpose is to decode simple arrays whose elements have neither
structure, nor behaviour, and can be described by a simple list. The
list will consist of C<$count> elements read into the current
Decoder's attribute given in C<$name>, according to the template
specified in C<$desc>.  For example, to read a list of 4-byte
integers, the template description must be of the form:

  $desc = ['V', 'UInt32']


=item iterate_object($stream, $count, $name, $class, $any_arg)

Similarly to C<iterate_scalar()>, this method can be used to read a
list of structures into the current decoder's attribute specified in
the C<$name> argument, but in this case, the list elements can be
complex structures to be decoded with their own decoder specified in
C<$class>. The optional argument C<$any_arg> can be used to parse
context information to that decoder.

=item purge_unused_data

Delete the location, size and type data for all structure
elements. Calling this method will free some memory when no
introspection is needeed (the necessary measure in production-grade
code)

=back

=head2 METHODS

=over 4

=item addr

Get the seek address of the decoded object

=item size

Get object size

=item data

Get the object's data hash (equivalent to $obj->{data}). Every data hash element contains the decoded value as well as location and type data.

=item item($key)

Get an item by name (equivalent to $obj->{data}->{$key})

=item values

Extract the simple value hash (no location data, only the element names and values)

=item dump($param)

Dump the object's contents in three different styles, using absolute
or relative addresses. The attribute $param->{style} can be set to
wiki or html, or it can be absent or have any other value, it which
case the dump will have a simple tabular format. The attribute
$param->{relative}is a Boolean, requesting relative addresses when it
is set to a truthy value.

=back

=head1 SEE ALSO

Use this command to list all available Finnigan decoders:

 perl -MFinnigan -e 'Finnigan::list_modules'


=head1 AUTHOR

Gene Selkov, E<lt>selkovjr@gmail.comE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2010 by Gene Selkov

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.10.0 or,
at your option, any later version of Perl 5 you may have available.

=cut