NAME

TectoMT::Node

DESCRIPTION

This class represents a TectoMT node. TectoMT trees (contained in bundles) are formed by nodes and edges. Attributes can be attached only to nodes. Edge's attributes must be stored as the lower node's attributes. Tree's attributes must be stored as attributes of the root node.

METHODS

Constructor

my $new_node = TectoMT::Node->new();: Creates a new node as well as its underlying FSNode representation.
my $new_node = TectoMT::Node->new( { 'fsnode' => $fsnode } );: Creates a new node and associates it with an already existing FSNode object.
my $new_node = TectoMT::Node->new( { 'attributes' => {'lemma'=>'house','tag'=>'NN' } );: Creates a new node and fills some of its attributes.

Access to the underlying Fslib representation

$node->tie_with_fsnode($fsnode);: Associates the given node with a FSNode object which will be used as its underlying represenatation.
my $fsnode = $node->get_tied_fsnode();: Returns the associated FSNode object used as the node's underlying represenatation.

Access to the containers

my $bundle = $node->get_bundle();: Returns the TectoMT::Bundle object in which the node's tree is contained.
my $document = $node->get_document();: Returns the TectoMT::Document object in which the node's tree is contained.

Access to attributes

my $value = $node->get_attr($name);: Returns the value of the node attribute of the given name.
my $node->set_attr($name,$value);: Sets the given attribute of the node with the given value. If the attribute name is 'id', then the document's indexing table is updated. If value of the type List is to be filled, then $value must be a reference to the array of values.
my $node2 = $node1->get_deref_attr($name);: If value of the given attribute is reference (or list of references), it returns the appropriate node (or a reference to the list of nodes).
my $node1->set_deref_attr($name, $node2);: Sets the given attribute with ID (list of IDs) of the given node (list of nodes).
my $node->add_to_listattr($name, $value);: If the given attribute is list, the given value is appended to it.
my $node->get_attrs(qw(name_of_attr1 name_of_attr2 ...));: Get more attributes at once. If the last argument is {undefs=>$value}, all undefs are substituted by a $value (typically the value is an empty string).

Access to tree topology

my $parent_node = $node->get_parent();: Returns the parent node, or undef if there is none (if $node itself is the root)
$node->set_parent($parent_node);: Makes $node a child of $parent_node.
$node->disconnect();: Disconnecting a node (or a subtree rooted by the given node) from its parent. Underlying fs-node representation is disconnected too. Node identifier is removed from the document indexing table. The disconnected node cannot be futher used.
my $root_node = $node->get_root();: Returns the root of the node's tree.
my $root_node = $node->is_root();: Returns true if the node has no parent.

Next three methods (for access to children / descendants / siblings) have an optional argument $arg_ref for specifying switches. By adding some switches, you can modify the behavior of these methods. See Switches for examples.

my @child_nodes = $node->get_children($arg_ref);: Returns an array of child nodes.
my @descendant_nodes = $node->get_descendants($arg_ref);: Returns an array of descendant nodes ('transitive children').
my @sibling_nodes = $node->get_siblings($arg_ref);: Returns an array of nodes sharing the parent with the current node.

Switches

Actually there are 6 switches:

ordered
preceding_only, following_only
first_only, last_only
add_self

Examples of usage

Names of variables in the examples suppose a language with left-to-right script.

 my @ordered_descendants       = $node->get_descendants({ordered=>1});
 my @self_and_left_children    = $node->get_children({preceding_only=>1, add_self=>1});
 my @ordered_self_and_children = $node->get_children({ordered=>1, add_self=>1});
 my $leftmost_child            = $node->get_children({first_only=>1});
 my @ordered_siblings          = $node->get_siblings({ordered=>1});
 my $left_neighbor             = $node->get_siblings({preceding_only=>1, last_only=>1});
 my $right_neighbor            = $node->get_siblings({following_only=>1, first_only=>1});
 my $leftmost_sibling_or_self  = $node->get_siblings({add_self=>1, first_only=>1});

Restrictions

first_only and last_only switches makes the method return just one item - a scalar, even if combined with the add_self switch.
Specifying (first|last|preceding|following)_only implies ordered, so explicit addition of ordered gives a warning.
Specifying both preceding_only and following_only gives an error (same for combining first_only and last_only).

Shortcuts

There are shortcuts for comfort of those who use left-to-right scripts:

my $left_neighbor_node = $node->get_left_neighbor();: Returns the rightmost node from the set of left siblings (the nearest left sibling). Actually, this is shortcut for $node->get_siblings({preceding_only=>1, last_only=>1}).
my $right_neighbor_node = $node->get_right_neighbor();: Returns the leftmost node from the set of right siblings (the nearest right sibling). Actually, this is shortcut for $node->get_siblings({following_only=>1, first_only=>1}).

Access to nodes ordering

my $attrname = $node->get_ordering_attribute();: Returns the name of the ordering attribute ('ord' by default). This method is supposed to be redefined in derived classes (to return e.g. 'deepord' for tectogrammatical layer nodes). All methods following in this section make use of this method.
my $ord = $node->get_ordering_value();: Returns the ordering value of the given node. (In this class, i.e. the value of 'ord' attribute.)
$rootnode->normalize_node_ordering();: The values of the ordering attribute of all nodes in the tree (possibly containing negative or fractional numbers) are normalized. The node ordering is preserved, but only integer values are used now (starting from 0 for the root, with increment 1). This method can be called only on tree roots (nodes without parent), otherwise fatal error is invoked. BEWARE: This method is only needed when there are some fractional values of the ordering atttribute in a tree. If possible, use methods from the next section (Reordering nodes) instead of do-it-yourself reordering that involves fractional ords.
my $boolean = $node->precedes($another_node);: Does this node precedes $another_node?
my $following_node = $node->get_next_node();: Return the closest following node (according to the ordering attribute) or undef if $node is the last one in the tree.
my $preceding_node = $node->get_prev_node();: Return the closest preceding node (according to the ordering attribute) or undef if $node is the first one in the tree.

Reordering nodes

Next four methods for changing the order of nodes (typically the word order defined by the attribute ord) have an optional argument $arg_ref for specifying switches. Actually there is only one switch - without_children which is by default set to 0. It means that the default behavior is to shift the node with all its descendants. Only if you want to leave the position of the descendants unchanged and shift just the node, use e.g.

 $node->shift_after_node($reference_node, {without_children=>1});

Shifting involves only changing the ordering attribute of nodes. There is no rehanging (changing parents). The node which is going to be shifted must be already added to the tree and the reference node must be in the same tree.

For languages with left-to-right script: after means ``to the right of'' and before means ``to the left of''.

$node->shift_after_node($reference_node);: Shifts (changes the ord of) the node just behind the reference node.
$node->shift_after_subtree($reference_node);: Shifts (changes the ord of) the node behind the subtree of the reference node.
$node->shift_before_node($reference_node);: Shifts (changes the ord of) the node just in front of the reference node.
$node->shift_before_subtree($reference_node);: Shifts (changes the ord of) the node in front of the subtree of the reference node.

Other methods

$node->generate_new_id();: Generate new (=so far unindexed) identifier (to be used when creating new nodes). The new identifier is derived from the identifier of the root ($node->root), by adding suffix x1 (or x2, if ...x1 has already been indexed, etc.) to the root's id.
my $position = $node->get_fposition();: Return the node address, i.e. file name and node's position within the file, similarly to TrEd's FPosition() (but the value is only returned, not printed).
my $levels = $node->get_depth();: Return the depth of the node. The root has depth = 0, its children have depth = 1 etc.

DEPRECATED METHODS

Instead of $node->geta_xy(), use $node->get_attr('xy') (the shortcut notation did not come into the use of TectoMT programmers).

Instead of methods with ordered, left, right in names, use appropriate switches (for access to children / descendants / siblings) or shifting methods (for shifting / reordering).

my $value = $node->geta_ATTRNAME();: Generic set of faster-to-write attribute-getter methods, such as $node->geta_functor() equivalent to $node->get_attr('functor'), or $node->geta_gram__number() equivalent to $node->get_attr('gram/number'). In the case of structured attributes, '/' in the attribute name is to be substituted with '__' (double underscore).
$node->seta_ATTRNAME($name,$value);: Generic set of faster-to-write attribute-setter methods, such as $node->seta_functor('ACT') equivalent to $node->set_attr('functor','ACT'), or $node->seta_gram__number('pl') equivalent to $node->get_attr('gram/number','pl'). In the case of structured attributes, '/' in the attribute name is to be substituted with '__' (double underscore).
my @child_nodes = $node->get_ordered_children();: Returns array of descendants sorted using the get_ordering_value method.
my @left_child_nodes = $node->get_left_children();: Returns array of sorted descendants with the ordering value smaller than that of the given node.
my @right_child_nodes = $node->get_right_children();: Returns array of sorted descendants with the ordering value bigger than that of the given node.
my $leftmost_child_node = $node->get_leftmost_child();: Returns the child node with the smallest ordering value.
my $rightmost_child_node = $node->get_rightmost_child();: Returns the child node with the biggest ordering value.
my @sibling_nodes = $node->get_ordered_siblings();: Returns an array of sibling nodes (nodes sharing their parent with the current node), ordered according to get_ordering_value.
my @left_sibling_nodes = $node->get_left_siblings();: Returns an array (ordered according to get_ordering_value) of sibling nodes with ordering values smaller than that of the current node.
my @right_sibling_nodes = $node->get_right_siblings();: Returns an array (ordered according to get_ordering_value) of sibling nodes with ordering values bigger than that of the current node.
$node->shift_left();: Node and its subtree is moved among its siblings. Projective tree is assumed.
$node->shift_right();: Node and its subtree is moved among its siblings. Projective tree is assumed.