NAME

File::Format::RIFF::Container - RIFF Container (Lists and RIFFs)

SYNOPSIS

You should not instantiate a File::Format::RIFF::Container directly; instead, you should instantiate one of its subclasses: either a File::Format::RIFF object, or a File::Format::RIFF::List object.

DESCRIPTION

File::Format::RIFF::Container is a base class for both RIFF objects and RIFF lists. It is, essentially, an array of other RIFF lists and/or RIFF chunks, and you can add, change, delete, and read them.

METHODS

$type = $container->type;

Returns the type of $container.

$container->type( $type );

Sets the type of $container. $type must be a four character code, which represents what data will be found in $container.

$id = $container->id;

Returns the id of $container. $container must be either a RIFF object or a List object, so $id will be 'RIFF' or 'LIST', respectively.

@data = $container->data;

Returns the RIFF chunks and/or RIFF lists contained by $container.

$container->data( $data );

Clears out any existing RIFF chunks contained by $container and replaces them with $data. $data must be an array reference containing some number of RIFF lists and/or RIFF chunks.

$numChunks = $container->numChunks;

Returns the number of RIFF lists and/or RIFF chunks contained by $container.

$size = $container->size;

Returns the size (in bytes) of $container's data, when written to a file.

$total_size = $container->total_size;

Returns the total size (in bytes) that $container will take up when written out to a file. Total size is the size of the data, plus 12 bytes for the header.

@replaced = $self->splice( $offset, $length, @list );

$container->push( @chunks );

$chunk = $container->pop;

$container->unshift( @chunks );

$chunk = $container->shift;

splice, push, pop, unshift, and shift operate analogously to the same-named functions in core perl, acting on $container's array of RIFF lists and/or RIFF chunks. All items added must be RIFF lists or RIFF chunks.

$chunk = $container->at( $i );

Returns the RIFF list or RIFF chunk at the $ith position in $container's array.

$container->at( $i, $chunk );

Sets the $ith position in $container's array to $chunk, replacing the previous item. $chunk must be a RIFF list or a RIFF chunk.

$newChunk = $container->addChunk( $id, $data );

Creates a new RIFF chunk object with the given $id and $data, appending it to $container's array. Returns the just-created RIFF chunk.

$newList = $container->addList( $type, $data );

Creates a new List object with the given $type and $data, appending it to $container's array. Returns the just-created RIFF list.

$container->dump( $max );

Prints a string representation of $container to STDOUT, recursively printing contained items. If a RIFF chunk's data is larger than $max bytes, prints '[...]' instead of the actual data. If $max is not specified or undef, it defaults to 64.

A RIFF chunk is rendered as:

id: <id> size: <size> (<total size>): <data>

A RIFF container is rendered as:

id: <id> (<type>) size: <size> (<total size>)

Items contained in the RIFF list are recursively printed on subsequent lines, and are indented in one additional tab level.

SEE ALSO

File::Format::RIFF

File::Format::RIFF::List

AUTHOR

Paul Sturm <sturm@branewave.com>