Next: , Previous: , Up: Texinfo modules documentation   [Contents][Index]

25 Texinfo::TreeElement

Next: , Up: Texinfo::TreeElement   [Contents][Index]

25.1 Texinfo::TreeElement NAME

Texinfo::TreeElement - Texinfo tree element interface

Next: , Previous: , Up: Texinfo::TreeElement   [Contents][Index]

25.2 Texinfo::TreeElement SYNOPSIS

  my $element = Texinfo::TreeElement::new({});

Next: , Previous: , Up: Texinfo::TreeElement   [Contents][Index]

25.3 Texinfo::TreeElement NOTES

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Note that this module is not used in texi2any (except for the new method, which is trivial and could be moved to another module).

Note that this module could be removed at any time.

Next: , Previous: , Up: Texinfo::TreeElement   [Contents][Index]

25.4 Texinfo::TreeElement DESCRIPTION

Texinfo::TreeElement::new should be called on every Perl tree elements created.

Texinfo::TreeElement defines accessors and methods for Texinfo tree elements obtained from parsing Texinfo code. There is no specific advantage of using the accessors, but they may be needed when some Texinfo modules XS interfaces are used.

These accessors are not used in texi2any.

Next: , Previous: , Up: Texinfo::TreeElement   [Contents][Index]

25.5 Texinfo::TreeElement METHODS

$element = new($element_hash)

Turns the $element_hash element hash into a Texinfo::TreeElement object.

This function is called on all the tree elements created in Texinfo modules codes. Since no accessors are used in texi2any Texinfo modules, the call to new is mainly cosmetic. It also allows to distinguish a Texinfo tree element from a hash.

$type = $element->type()

Return the $element type, or undef.

$cmdname = $element->cmdname()

Return the $element command name, if defined, or undef.

$text = $element->text()

Return the $element text if the element is a text element, or undef.

$number = $element->children_number()

Return the number of children elements contained in $element.

$child = $element->get_child($index)

Return the $element child element at index $index.

$children_list = $element->get_children()

Return an array reference holding the elements contained in $element.

$parent = $element->parent()

Return the parent element of $element.

$source_info = $element->source_info()

Return the $element source info, or undef if there is none.

$value = $element->get_attribute($attribute_name)

Return the $element $attribute_name attribute value. If the $attribute_name does not exist or is not set at all, return undef.

$element->add_to_element_contents($added_element)

Insert $added_element at the end of the $element contents (ie the element children array).

Up: Texinfo::TreeElement METHODS   [Contents][Index]

25.5.1 Texinfo::TreeElement and XS extensions

The Texinfo Perl modules can be setup to use Perl XS module extensions in native code (written in C) that replace Perl package or methods by native code for faster execution. It may be important to use the Texinfo::TreeElement accessors that return elements instead of using hash keys described in TEXINFO TREE when some Texinfo modules XS interfaces are used.

The Texinfo modules XS interface is designed such that the Texinfo tree actually processed is not the Perl elements tree, but a tree stored in native code in XS extensions, corresponding to compiled C data structures. For some Texinfo modules XS extensions, Perl tree elements need to have a link from Perl to native code C data registered in the Perl element to find the C tree data corresponding to a Perl element.

Using the Texinfo::TreeElement methods may help setting up this link. Indeed, if an element has already a link to C data, the elements returned by Texinfo::TreeElement methods will also have this link setup.

For example, if $element has already a link to C data, $element_child will also have a link to C data setup: 

  my $element_child = $element->get_child(0)

Note that, even if XS extensions are used, calling new does not set up a link to C, Texinfo::Example::TreeElementConverter new_tree_element should be used for that.

For other ways to setup this link, see Texinfo::Example::TreeElementConverter and Texinfo::Reader and XS extensions.

Next: , Previous: , Up: Texinfo::TreeElement   [Contents][Index]

25.6 Texinfo::TreeElement SEE ALSO

TEXINFO TREE.

Next: , Previous: , Up: Texinfo::TreeElement   [Contents][Index]

25.7 Texinfo::TreeElement AUTHOR

Patrice Dumas.

Next: , Previous: , Up: Texinfo modules documentation   [Contents][Index]