/ 
Treex-Core-2.20151210
River stage one • 4 direct dependents • 4 total dependents
/ Treex::Core::Node

NAME

Treex::Core::Node - smallest unit that holds information in Treex

VERSION

version 2.20151210

DESCRIPTION

This class represents a Treex node. Treex 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

Construction

my $new_node = $existing_node->create_child({lemma=>'house', tag=>'NN' });

Creates a new node as a child of an existing node. Some of its attribute can be filled. Direct calls of node constructors (->new) should be avoided.

Access to the containers

my $bundle = $node->get_bundle();

Returns the Treex::Core::Bundle object in which the node's tree is contained.

my $document = $node->get_document();

Returns the Treex::Core::Document object in which the node's tree is contained.

get_layer

Return the layer of this node (a, t, n or p).

get_zone

Return the zone (Treex::Core::BundleZone) to which this node (and the whole tree) belongs.

$lang_code = $node->language

shortcut for $lang_code = $node->get_zone()->language

$selector = $node->selector

shortcut for $selector = $node->get_zone()->selector

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->remove({children=>remove});

Deletes a node. Node identifier is removed from the document indexing table. The removed node cannot be further used.

Optional argument children in $arg_ref can specify what to do with children (and all descendants, i.e. the subtree rooted by the given node) if present: remove, remove_warn, rehang, rehang_warn. The default is remove -- remove recursively. rehang means reattach the children of $node to the parent of $node. The _warn variants will in addition produce a warning.

my $root_node = $node->get_root();

Returns the root of the node's tree.

$node->is_root();

Returns true if the node has no parent.

$node->is_leaf();

Returns true if the node has no children.

$node1->is_descendant_of($node2);

Tests whether $node1 is among transitive descendants of $node2;

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

Currently 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}).

my $type = $node->get_pml_type_name;
$node->fix_pml_type();

If a node has no PML type, then its type is detected (according to the node's location) and filled by the PML interface.

Access to alignment

$node->add_aligned_node($target, $type)

Aligns $target node to $node. The prior existence of the link is not checked.

my ($nodes_rf, $types_rf) = $node->get_aligned_nodes()

Returns an array containing two array references. The first array contains the nodes aligned to this node, the second array contains types of the links.

my @nodes = $node->get_aligned_nodes_of_type($regex_constraint_on_type)

Returns a list of nodes aligned to the $node by the specified alignment type.

$node->delete_aligned_node($target, $type)

All alignments of the $target to $node are deleted, if their types equal $type.

my $is_aligned = $node->is_aligned_to($target, $regex_constraint_on_type)

Returns 1 if the nodes are aligned, 0 otherwise.

$node->update_aligned_nodes()

Removes all alignment links leading to nodes which have been deleted.

References (alignment and other references depending on node subtype)

my @refnodes = $node->get_referencing_nodes($ref_type);

Returns an array of nodes referencing this node with the given reference type (e.g. 'alignment', 'a/lex.rf' etc.).

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 $levels = $node->get_depth();

Return the depth of the node. The root has depth = 0, its children have depth = 1 etc.

my $address = $node->get_address();

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).

$node->equals($another_node)

This is the internal implementation of overloaded == operator, which checks whether $node == $another_node (the object instance must be identical).

my $string = $node->to_string()

This is the internal implementation of overloaded stringification, so you can use e.g. print "There is a node $node.". It returns the id ($node-id>), but the behavior may be overridden in subclasses. See overload pragma for details about overloading operators in Perl.

AUTHORS

Zdeněk Žabokrtský <zabokrtsky@ufal.mff.cuni.cz>

Martin Popel <popel@ufal.mff.cuni.cz>

David Mareček <marecek@ufal.mff.cuni.cz>

Daniel Zeman <zeman@ufal.mff.cuni.cz>

Ondřej Dušek <odusek@ufal.mff.cuni.cz>

COPYRIGHT AND LICENSE

Copyright © 2011-2012 by Institute of Formal and Applied Linguistics, Charles University in Prague

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.