NAME

Parse::Matroska::Element - a mid-level representation of an EBML element

VERSION

version 0.001001

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.

ATTRIBUTES

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.

Equivalent to elem_by_hexid($elem->{value})->{valtype}.

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 decoded by "decode" in Encode.

Is undef if the "type" is binary and the contents were delay-loaded and not yet read. "get_value" 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's.

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, which excludes 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.

If $keep_bin is true, the delay-loaded data is kept as the "value", otherwise, further calls to get_value will reread the data from the "reader".

next_child($read_bin)

Builtin iterator; reads and returns the next child element. Always 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; so calling "next_child($read_bin)" after the iterator returned undef will return the first child.

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 each element in-order as would be given by "all_children($recurse,$read_bin)".

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 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.

NOTE

The API of this module is not yet considered stable.

AUTHOR

Kovensky <diogomfranco@gmail.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2012 by Diogo Franco.

This is free software, licensed under:

  The (two-clause) FreeBSD License