NAME

Treex::PML::Node - Treex::PML class representing a node.

DESCRIPTION

This class implements a node in a tree. The node has zero or one parent node (parent()) (if it has no parent, it is a root of a tree), zero or more child nodes (the left-most of them returned by firstson()) and zero or more siblings (lbrother() is the immediate sibling the left and rbrother() is the immediate sibling the right).

A node can also be associated with a PML type (contianer or structure) and may carry named attributes (with atomic or complex values).

Representation of trees

Treex::PML provides representation for oriented rooted trees (such as dependency trees or constituency trees).

In Treex::PML, each tree is represented by its root-node. A node is a Treex::PML::Node object, which is underlined by a usual Perl hash reference whose hash keys represent node attributes (name-value pairs).

The set of available attributes at each node is specified in the data format (which, depending on I/O backend, is represented either by a Treex::PML::FSFormat or Treex::PML::Schema object; whereas Treex::PML::FSFormat uses a fixed set of attributes for all nodes with text values (or alternating text values), in Treex::PML::Schema the set of attributes may depend on the type of the node and a wide range of data-structures is supported for attribute values. In particular, attribute values may be plain scalars or Treex::PML data objects (Treex::PML::List, Treex::PML::Alt, Treex::PML::Struct, Treex::PML::Container, Treex::PML::Seq.

FS format also allows to declare some attributes as representants of extra features, such as total ordering on a tree, text value of a node, indicator for "hidden" nodes, etc. Similarly, in PML schema, some attributes may be associated with roles, e.g. the role '#ID' for an attribute carrying a unique identifier of the node, or '#ORDER' for an integer attribute representing the order of the node in the horizontal ordering of the tree.

The tree structure can be modified and traversed by various Treex::PML::Node object methods, such as parent, firstson, rbrother, lbrother, following, previous, cut, paste_on, paste_after, and paste_before.

Four special hash keys are reserved for representing the tree structure in the Treex::PML::Node hash. These keys are defined in global variables: $Treex::PML::Node::parent, $Treex::PML::Node::firstson, $Treex::PML::Node::rbrother, and $Treex::PML::Node::lbrother. Another special key $Treex::PML::Node::type is reserved for storing data type information. It is highly recommended to use Treex::PML::Node object methods instead of accessing these hash keys directly. By default, the values of these special keys in order are _P_, _S_, _R_, _L_, _T_.

Although arbitrary non-attribute non-special keys may be added to the node hashes at run-time, such keys are not normally preserved via I/O backends and extreme care must be taken to aviod conflicts with attribute names or the special hash keys described above.

METHODS

Treex::PML::Node->new($hash?,$reuse?)

NOTE: Don't call this constructor directly, use Treex::PML::Factory->createTypedNode() or Treex::PML::Factory->createNode() instead!

Create a new Treex::PML::Node object. Treex::PML::Node is basically a hash reference. This means that node's attributes can be accessed simply as $node->{attribute}.

If a hash-reference is passed as the 1st argument, all its keys and values are are copied to the new Treex::PML::Node.

An optional 2nd argument $reuse can be set to a true value to indicate that the passed hash-reference can be used directly as the underlying hash-reference for the new Treex::PML::Node object (which avoids copying). It is, however, not guaranteed that the hash-reference will be reused; the caller thus must even in this case work with the object returned by the constructor rather that the hash-reference passed.

Returns the newly created Treex::PML::Node object.

$node->destroy

This function destroys a Treex::PML::Node (and all its descendants). If the node has a parent, it is cut from it first.

$node->destroy_leaf

This function destroys a leaf Treex::PML::Node and fails if the node is not a leaf (has children). If the node has a parent, it is cut from it first.

$node->parent

Return node's parent node (undef if none).

$node->type (attr-path?)

If called without an argument or if attr-path is empty, return node's data-type declaration (undef if none). If attr-path is non-empty, return the data-type declaration of the value reachable from $node under the attribute-path attr-path.

$node->root

Find and return the root of the node's tree.

$node->level

Calculate node's level (root-level is 0).

$node->lbrother

Return node's left brother node (undef if none).

$node->rbrother

Return node's right brother node (undef if none).

$node->firstson

Return node's first dependent node (undef if none).

$node->set_type (type)

Wherever possible, avoid using this method directly; instead create a typed nodes using Treex::PML::Factory->createTypedNode().

Associate Treex::PML::Node object with a type declaration-object (see Treex::PML::Schema class).

$node->set_type_by_name (schema,type-name)

Lookup a structure or container declaration in the given Treex::PML::Schema by its type name and associate the corresponding type-declaration object with the Treex::PML::Node.

$node->validate (attr-path?,log?)

This method requires $node to be associated with a type declaration.

Validates the content of the node according to the associated type and schema. If attr-path is non-empty, validate only attribute selected by the attribute path. An array reference may be passed as the 2nd argument log to obtain a detailed report of all validation errors.

Note: this method does not validate descendants of the node. Use e.g.

$node->validate_subtree(\@log);

to validate the complete subtree.

Returns: 1 if the content validates, 0 otherwise.

$node->validate_subtree (log?)

This method requires $node to be associated with a type declaration.

Validates the content of the node and all its descendants according to the associated type and schema. An array reference log may be passed as an argument to obtain a detailed report of all validation errors.

Returns: 1 if the subtree validates, 0 otherwise.

$node->attribute_paths

This method requires $node to be associated with a type declaration.

This method is similar to Treex::PML::Schema->attributes but for a single node. It returns attribute paths valid for the current node. That is, it returns paths to all atomic subtypes of the type of the current node.

$node->following (top?)

Return the next node of the subtree in the order given by structure (undef if none). If any descendant exists, the first one is returned. Otherwise, right brother is returned, if any. If the given node has neither a descendant nor a right brother, the right brother of the first (lowest) ancestor for which right brother exists, is returned.

$node->following_visible (FSFormat_object,top?)

Return the next visible node of the subtree in the order given by structure (undef if none). A node is considered visible if it has no hidden ancestor. Requires FSFormat object as the first parameter.

$node->following_right_or_up (top?)

Return the next node of the subtree in the order given by structure (undef if none), but not descending.

$node->previous (top?)

Return the previous node of the subtree in the order given by structure (undef if none). The way of searching described in following is used here in reversed order.

$node->previous_visible (FSFormat_object,top?)

Return the next visible node of the subtree in the order given by structure (undef if none). A node is considered visible if it has no hidden ancestor. Requires FSFormat object as the first parameter.

$node->rightmost_descendant (node)

Return the rightmost lowest descendant of the node (or the node itself if the node is a leaf).

$node->leftmost_descendant (node)

Return the leftmost lowest descendant of the node (or the node itself if the node is a leaf).

$node->getAttribute (attr_name)

Return value of the given attribute.

$node->attr (path)

Retrieve first value matching a given attribute path.

$node->attr($path)

is an alias for

Treex::PML::Instance::get_data($node,$path);

See Treex::PML::Instance::get_data for details.

$node->all (path)

Retrieve all values matching a given attribute path.

$node->all($path)

is an alias for

Treex::PML::Instance::get_all($node,$path);

See Treex::PML::Instance::get_all for details.

$node->set_attr (path,value,strict?)

Store a given value to a possibly nested attribute of $node specified by path. The path argument uses the XPath-like syntax described in Treex::PML::Instance::set_data.

$node->setAttribute (name,value)

Set value of the given attribute.

$node->children

Return a list of dependent nodes.

$node->visible_children (fsformat)

Return a list of visible dependent nodes.

$node->descendants

Return a list recursively dependent nodes.

$node->visible_descendants (fsformat)

Return a list recursively dependent visible nodes.

$node->ancestors

Return a list of ancestor nodes of $node, e.g. the list of nodes on the path from the node's parent to the root of the tree.

$node->cut ()

Disconnect the node from its parent and siblings. Returns the node itself.

$node->paste_on (new-parent,ord-attr)

Attach a new or previously disconnected node to a new parent, placing it to the position among the other child nodes corresponding to a numerical value obtained from the ordering attribute specified in ord-attr. If ord-attr is not given, the node becomes the left-most child of its parent.

This method does not check node types, but one can use $parent->test_child_type($node) before using this method to verify that the node is of a permitted child-type for the parent node.

Returns the node itself.

$node->paste_after (ref-node)

Attach a new or previously disconnected node to ref-node's parent node as a closest right sibling of ref-node in the structural order of sibling nodes.

This method does not check node types, but one can use $ref_node->parent-test_child_type($node)> before using this method to verify that the node is of a permitted child-type for the parent node.

Returns the node itself.

$node->paste_before (ref-node)

Attach a new or previously disconnected node to ref-node's parent node as a closest left sibling of ref-node in the structural order of sibling nodes.

This method does not check node types, but one can use $ref_node->parent-test_child_type($node)> before using this method to verify that the node is of a permitted child-type for the parent node.

Returns the node itself.

$node->test_child_type ( test_node )

This method can be used before a paste_on or a similar operation to test if the node provided as an argument is of a type that is valid for children of the current node. More specifically, return 1 if the current node is not associated with a type declaration or if it has a #CHILDNODES member which is of a list or sequence type and the list or sequence can contain members of the type of test_node. Otherwise return 0.

A type-declaration object can be passed directly instead of test_node.

$node->get_order

For a typed node return value of the ordering attribute on the node (i.e. the one with role #ORDER). Returns undef for untyped nodes (for untyped nodes the name of the ordering attribute can be obtained from the FSFormat object).

$node->get_ordering_member_name

For a typed node return name of the ordering attribute on the node (i.e. the one with role #ORDER). Returns undef for untyped nodes (for untyped nodes the name of the ordering attribute can be obtained from the FSFormat object).

$node->get_id

For a typed node return value of the ID attribute on the node (i.e. the one with role #ID). Returns undef for untyped nodes (for untyped nodes the name of the ID attribute can be obtained from the FSFormat object).

$node->get_id_member_name

For a typed node return name of the ID attribute on the node (i.e. the one with role #ID). Returns undef for untyped nodes (for untyped nodes the name of the ID attribute can be obtained from the FSFormat object).

SEE ALSO

Treex::PML, Treex::PML::Factory, Treex::PML::Document, Treex::PML::Struct, Treex::PML::Container, Treex::PML::Schema

COPYRIGHT AND LICENSE

Copyright (C) 2006-2010 by Petr Pajas, 2010-2024 Jan Stepanek

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.