NAME

File::Format::RIFF - Resource Interchange File Format/RIFF files

SYNOPSIS

   use File::Format::RIFF;
   open( IN, 'file' ) or die "Could not open file: $!";
   my ( $riff1 ) = File::Format::RIFF->read( \*IN );
   close( IN );
   $riff1->dump;
   my ( $riff2 ) = new File::Format::RIFF( 'TYPE' );
   foreach my $chunk ( $riff1->data )
   {
      next if ( $chunk->id eq 'LIST' );
      $riff2->addChunk( $chunk->id, $chunk->data );
   }
   open( OUT, ">otherfile" ) or die "Could not open file: $!";
   $riff2->write( \*OUT );
   close( OUT );

DESCRIPTION

"File::Format::RIFF" provides an implementation of the Resource Interchange File Format. You can read, manipulate, and write RIFF files.

CONSTRUCTORS

$riff = new File::Format::RIFF( $type, $data );

Creates a new File::Format::RIFF object. $type is a four character code that identifies the type of this particular RIFF file. Certain types are defined to have a format, specifying which chunks must appear (e.g., WAVE files). If $type is not specified, it defaults to ' ' (four spaces). $data must be an array reference containing some number of RIFF lists and/or RIFF chunks. If $data is "undef" or not specified, then the new RIFF object is initialized empty.

$riff = File::Format::RIFF->read( $fh, $filesize );

Reads and parses an existing RIFF file from the given filehandle $fh. An exception will be thrown if the file is not a valid RIFF file. $filesize controls one aspect of the file format checking -- if $filesize is not specified, then "stat" will be called on $fh to determine how much data to expect. You may explicitly specify how much data to expect by passing in that value as $filesize. In either case, the amount of data read will be checked to make sure it matches the amount expected. Otherwise, it will throw an exception. If you do not wish it to make this check, pass in "undef" for $filesize.

Please note, if you wish to read an "in memory" filehandle, such as by doing this: "open( $fh, '<', \$variable )", you may do so, but you must pass in length( $variable ) for $filesize, because filehandles opened this way to do not support the "stat" call.

You may also use sockets for $fh. But if you do, you must either specify the amount of data expected by passing in a value for $filesize, or if you do not know ahead of time how much data to expect, you must pass in "undef" for $filesize. (An example of using sockets to read and write RIFF files is available with your File::Format::RIFF distribution, at eq/socketpair.pl.)

METHODS

$riff->read( $fh, $filesize );

The "read" constructor may also be used as a method. If used in this manner, then all existing data contained in $riff will be discarded, and replaced by the contents read from $fh.

$riff->write( $fh );

Outputs a properly-formatted RIFF file to the given filehandle $fh.

SEE ALSO

File::Format::RIFF::Container

"File::Format::RIFF" inherits from "File::Format::RIFF::Container", so all methods available for Containers can be used on RIFF objects. A Container essentially contains an array of RIFF lists and/or RIFF chunks. See the File::Format::RIFF::Container page for more information.

File::Format::RIFF::List

File::Format::RIFF::Chunk

SUPPORT

The author monitors the CPAN forum at:

<http://www.cpanforum.com/dist/File-Format-RIFF>

AUTHOR

Paul Sturm <sturm@branewave.com>

WEBSITE

<http://branewave.com/perl>

COPYRIGHT

Copyright (c) 2005 Paul Sturm. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

I would love to hear about my software being used; send me an email!