NAME

Parse::Matroska::Element

VERSION

version 0.001

SYNOPSIS

    use Parse::Matroska::Reader;
    my $reader = Parse::Matroska::Reader->new($path);
    my $elem = $reader->read_element;

    print "ID: $elem->{elid}\n";
    print "Name: $elem->{name}\n";
    print "Length: $elem->{content_len}\n";
    print "Type: $elem->{type}\n";
    print "Child count: ", scalar(@{$elem->all_children}), "\n";
    if ($elem->{type} eq 'sub') {
        while (my $chld = $elem->next_child) {
            print "Child Name: $chld->{name}\n";
        }
    } else {
        print "Value: ", $elem->get_value, "\n";
    }

DESCRIPTION

Represents a single Matroska element as decoded by Parse::Matroska::Reader. This is essentially a hash augmented with functions for delay-loading of binary values and children elements.

NOTE

The API of this module is not yet considered stable.

FIELDS

elid

The EBML Element ID, suitable for passing to "elem_by_hexid" in Parse::Matroska::Definitions.

name

The EBML Element's name.

type

The EBML Element's type. Can be 'uint', 'sint', 'float', 'ebml_id', 'str' or 'binary'. See "value" for details.

value

The EBML Element's value. Should be obtained through "get_value".

Is an unicode string if the "type" is str, that is, the string has already been "decode" in Encoded.

Is undef if the "type" is binary and the contents were delay-loaded and not yet read. "get_type" will do the delayed load if needed.

Is an arrayref if the "type" is sub, containing the children nodes that were already loaded.

Is a hashref if the "type" is ebml_id, containing the referred element's information as defined in Parse::Matroska::Definitions. Calling elem_by_hexid($elem->{value}->{elid}) will return the same object as $elem->{value}.

full_len

The entire length of this EBML Element, including the header.

size_len

The length of the size marker. Used when calculating "full_len" from "content_len"

content_len

The length of the contents of this EBML Element, excluding the header.

reader

A weakened reference to the associated Parse::Matroska::Reader.

METHODS

new(%hash)

Creates a new Element initialized with the hash given as argument.

initialize(%hash)

Called by new on initialization.

skip

Called by the user to ignore the contents of this EBML node. Needed when ignoring the children of a node.

get_value(keep_bin)

Returns the value contained by this EBML element.

If the element has children, returns an arrayref to the children elements that were already encountered.

If the element's type is "binary" and the value was delay-loaded, does the reading now.

next_child(read_bin)

Builtin iterator; reads and returns the next child element. Returns undef if the type isn't 'sub'; returns undef at the end of the iterator and resets itself to point to the first element.

The optional read_bin parameter has the children elements not delay-load their value if their type is 'binary'.

If all children elements have already been read, return the elements in-order as would be given by "all_children".

all_children(recurse,read_bin)

Calls "populate_children(recurse,read_bin)" on self and returns an arrayref with the children nodes.

Both recurse and read_bin are optional and default to false.

children_by_name(name)

Searches in the already read children elements for all elements with the EBML name name. Returns the found element if only one was found, or an arrayref containing all found elements. If no elements are found, an empty arrayref is returned.

populate_children(recurse,read_bin)

Populates the internal array of children elements, that is, requests that the associated Matroska::Parser::Reader reads all children elements.

If recurse is provided and is true, the method will call itself in the children elements with the same parameters it received; this will build a full EBML children tree.

If read_bin is provided and is true, disables delay-loading of the contents of 'binary'-type nodes, reading the contents to memory.

If both recurse and read_bin are true, entire EBML trees can be loaded without requiring seeks, thus behaving correctly on unseekable streams. If read_bin is false, the entire EBML tree is still loaded, but calling "get_value" on 'binary'-type nodes will produce an error on unseekable streams.

AUTHOR

Diogo Franco <diogomfranco@gmail.com>, aka Kovensky.

SEE ALSO

Parse::Matroska::Reader, Parse::Matroska::Definitions.

LICENSE

The FreeBSD license, equivalent to the ISC license.