NAME
Parse::Matroska::Element - a mid-level representation of an EBML element
VERSION
version 0.003
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 an array containing all found elements. On scalar context, returns only the first element found.
Croaks if the element's type isn't sub.
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. Returns itself.
Returns false if the element's type isn't sub.
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