Treex::PML::Node - Treex::PML class representing a node.
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).
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.
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.
This function destroys a Treex::PML::Node (and all its descendants). The node should not be attached to a tree.
Return node's parent node (undef
if none).
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
.
Find and return the root of the node's tree.
Calculate node's level (root-level is 0).
Return node's left brother node (undef
if none).
Return node's right brother node (undef
if none).
Return node's first dependent node (undef
if none).
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).
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.
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.
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.
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.
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.
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.
Return the next node of the subtree in the order given by
structure (undef
if none), but not descending.
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.
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.
Return the rightmost lowest descendant of the node (or the node itself if the node is a leaf).
Return the leftmost lowest descendant of the node (or the node itself if the node is a leaf).
Return value of the given attribute.
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.
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.
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.
Set value of the given attribute.
Return a list of dependent nodes.
Return a list of visible dependent nodes.
Return a list recursively dependent nodes.
Return a list recursively dependent visible nodes.
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.
Disconnect the node from its parent and siblings. Returns the node itself.
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.
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.
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.
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
.
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).
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).
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).
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).
Treex::PML, Treex::PML::Factory, Treex::PML::Document, Treex::PML::Struct, Treex::PML::Container, Treex::PML::Schema
Copyright (C) 2006-2010 by Petr Pajas
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.