15. User Macros

15. User Macros
Prev		Next

15.1. A Macro
15.2. Macro files
15.3. Using various character encodings
15.4. Conditional macro code
15.5. Associating macros with menu entries and keyboard shortcuts
15.6. When macro ends
15.7. Accessing tree nodes
15.8. Public API: pre-defined macros
15.9. Hooks: automatically executed macros
15.10. Using different sets of macros in different situations

This section describes in detail TrEd's support for user macros and is dedicated mainly to programmers.

As was already mentioned, TrEd is itself written in Perl and therefore it is natural that also user macros are written in the Perl language. The details of the Perl language syntax are not described here. You may find them in various literature on programming in Perl as well as in manual pages of Perl language. A large volume of documentation on Perl and many specific Perl modules is collected for example by ActiveState. In this text, we concentrate on the TrEd's macro specifics only.

15.1. A Macro

A macro for TrEd is simply a Perl routine defined using the sub name { ... } construct, e.g.:

sub my_first_macro {
 print "Hallo World\n";
}

Macros may be called from other macros in the same way as any other sub-routines in Perl, for example:

sub my_first_macro {
	my_second_macro();  # call to another macro
}

In this case, macros may use the usual Perl mechanisms to pass any number of argumens to the called macro.

To make the macro accessible from TrEd, two more things should be done. First, a special “binding directive” can be added, so that the macro is associated with a keyboard shortcut and/or added to the list of named macros and filed under the Macros menu under a short descriptive name, where users can easily find and invoke it. Second, the macro must be stored in some file and TrEd must be told where to look for the file. This (and more) is discussed in the following sections.

15.2. Macro files

On startup, TrEd looks for two files with macros.

The default set of macros (described in more detail in Section 15.8, “Public API: pre-defined macros”) tred.def
The set of extension macros tred.mac or any other file given after the -m parameter on the command line or a file specified in the TrEd's configuration option MacroFile.

Developers of macros should never modify the tred.def file directly. In theory, the file tred.mac can be modified when preparing a customized installation of TrEd, but it is seldom needed. In fact, in the current development model, the file tred.mac plays the role of a testing ground for macros that are supposed to eventually make it into tred.def but whose API is not yet guaranteed to remain unchanged. It also creates initial keyboard and menu bindings for the TredMacro annotation mode (see Section 15.10, “Using different sets of macros in different situations”).

Instead, the developers of macros are encouraged either to place their macros into an extension package, or to create a subfolder with a contrib.mac file in tredlib/contrib/, e.g. tredlib/contrib/subdir_name/contrib.mac, which will be automatically included into tred.mac (the standard version of tred.mac includes the file tredlib/contrib/contrib.mac which in turn does a wildcard include of */contrib.mac, as described below).

One Macro file may be included into other macro file using one of the following #include directives where filename is supposed to provide a relative or absolute path to the macro file, under the terms described below:

#include "filename"

The filename must be relative to the directory of the file to which it is included.

#include <filename>

The filename must be relative to the TrEd's library directory.

#include "<wildcard>"

Expands wildcard relatively to the directory of the file containing the directive and includes all matching file.

#include filename

The filename may be both absolute or relative. In the latter case the directories are searched in the following order:

Current directory is searched.
The directory of the file where the #include directive occured is searched.
TrEd's library directory is searched.

If #include fails to find given file, it is a fatal error and TrEd/bTrEd immediatelly stops. You may use #ifinclude directive, if you wish TrEd to continue (without error or warning) even if the requested file was not found.

15.3. Using various character encodings

Note

This section applies only to TrEd/bTrEd running under Perl 5.8 and higher.

If non-ASCII characters should occur in macro code, it is necessary to indicate the character encoding used. Otherwise TrEd wouldn't be able to translate the non-ASCII characters into an internal Unicode representation. Failing to indicate encoding used in macro code can therefore lead to unexpected behaviour of the code and/or fatal run-time errors.

By default, TrEd expects UTF-8 encoded macro code (unless specified otherwise using the defaultMacroEncoding configuration option). Any other character encoding must be indicated using #encoding directive, followed by name of the encoding, such as utf-8, iso-8859-1, windows-1256, etc. The encoding indicated by an #encoding directive applies on the macro file strating from the line following the directive to the end of the file or to another #encoding directive occurence, whichever happens first. Encoding directive does not apply to included macro files.

Example 2. Indicating macro character encoding

  (UTF-8 encoded macro code)

#encoding iso-8859-2
  
  (latin-2 encoded macro code)

#encoding utf-8

  (UTF-8 encoded macro code continues)

15.4. Conditional macro code

If macro code is spanned across several files or is shared between TrEd and bTrEd, it may be useful to make some parts of the macro code (such as an #include directive) conditional.

For this purpose TrEd, provides similar mechanisms as standard C pre-processors using #define, #undefine, #ifdef, #ifndef, and #endif directives. These directives must appear on the very beginning of line. Any code enclosed within

#ifdef symbol-name

and

#endif

directives is included if and only if the symbol symbol-name was previously defined using a #define symbol-name directive. Any code enclosed within

#ifndef symbol-name

and

#endif

directives is included if and only if the symbol symbol-name is not defined. A defined symbol can later be undefined with #undefine symbol-name. Unlike C macros, symbols in TrEd have no other purpose than this.

Except for symbols defined by a #define directive, symbol TRED is always initially defined in TrEd, symbol BTRED is always initially defined in bTrEd. This may help to simplify sharing macro code with specific parts for TrEd and bTrEd between these two applications.

15.5. Associating macros with menu entries and keyboard shortcuts

The last set of directives is used to associate a macro with a keyboard shortcut and to add it to the list of macros and and the Macros menu under a short descriptive name, so that the user can easily find and invoke it.

To connect a macro named my_first_macro with a new entries labeled My First Macro in the Macros → List of Macros... dialog and also in the menu Macros → All Modes → mode, the following directive should appear in some macro file read by TrEd:

#insert my_first_macro as menu My First Macro

Actually the words as and menu may be omitted, so it is possible to write the above directive also as:

#insert my_first_macro as My First Macro

or even

#insert my_first_macro My First Macro

Association between a macro and a keyboard shortcut is defined using the directive #bind. For example, to “bind” a macro named my_first_macro to say Ctrl+Alt+Del keyboard shortcut, the following line should appear somewhere in the macro file:

#bind my_first_macro to key Ctrl+Alt+Del

Again, the to and key keywords may be omitted.

Warning

Using the particular shortcut chosen here as a funny example is a silly idea indeed, since this very shortcut is typicaly used to restart the system. Remember that only shortcuts that are not interpreted by the operating system or the desktop environment can possibly work as expected.

Both a menu item and a keyboard shortcut can be associated with a macro in one step with a directive of the following :

#bind my_first_macro to key Ctrl+Alt+Del menu My First Macro

If more than one keyboard shortcut or menu item are associated with the same macro, any of them may be used to invoke the macro. If more than one macro was associated with the same keyboard shortcut, then the latest binding is used. Also, if two or more macros with the same name appear in the loaded macro files (within the same package), the last one is used, but that holds in general for any Perl subroutine.

#unbind-key Ctrl+Alt+Del

#remove-menu My First Macro

The first of the directives above removes an existing key-bindning from current annotation mode(s). The second one removes an existing menu entry from the macro menu of the current annotation mode (Macros → All Modes → annotation mode). These directives is especially useful for disabling certain functionality and bindings of an incuded macro file.

15.6. When macro ends

When an interactively invoked macro returns, TrEd performs the following steps:

the node referenced in $this is activated in the current view (provided it belongs to the current tree)
all views are redrawn (unless specified otherwise in the variable$Redraw), see below.
unless the value of the variable $FileChanged (see Section 15.8, “Public API: pre-defined macros”) is set to 0, the save-status of the current file is turned to modified (as indicated by the state of the button).

The variable $Redraw may have the following values:

file (the default): redraw all windows displaying current file
tree: redraw all windows displaying current tree
win: redraw current window
all: redraw all windows
tie: redraw all windows if TrEd windows are tied otherwise redraw only the current one
none: disables redrawing

Because TrEd has no way to identify whether the current file (or in fact any other file) was actually modified by the macro, it always assumes it was. To prevent this and indicate that no actual changes which would require the user to save the file were done to the current file, the macro must explicitly set a special variable named $FileChanged to zero. Even better (to prevent accidental collisions between several assignments to this variable), instead of directly assigning to this variable, call the default macro ChangingFile(0).

To make things more complicated, it should be noted, that btred, the off-line variant of TrEd, never saves any processed file unless the variable $FileChanged has been explicitely set to 1 or -S command-line switch is used. So, conversely, in btred, a macro should indicate making a change worth saving by calling ChangingFile(1).

Note

If the state of the file was already modified and not saved when a macro was interactively invoked, then any changes to the $FileChanged variable made by the macro are ignored. Macro may however force the file status to return to saved by setting the variable $forceFileSaved to 1 (typically after an explicit call to Save()).

Note

For historical reasons, there exists an alias for $FileChanged named $FileNotSaved. These variables are identical.

15.7. Accessing tree nodes

15.7.1. Node types
15.7.2. Accessing node attributes
15.7.3. Accessing neighboring nodes
15.7.4. Accessing other trees

A tree in TrEd is represented by its root node. The root node can be distinguished from other nodes by having no parent node. Similarly leaf nodes have no children (see firstson() method described bellow).

All tree nodes in TrEd are represented by Treex::PML::Node Perl objects. These objects are basically only hash references where the attribute-name/attribute-value information is stored as a key/value pair (except that some hash keys are reserved for representing the tree structure). Treex::PML::Node objects provide several basic methods, most of which are related to accessing their neighbouring nodes (i.e. traversing the tree) and modifying the tree structure by means of cut and paste operations.

Macros usually start from the nodes accessible via global variables (these variables are declared in the TredMacro package, but exported by default to any other derived package):

$this: is the active node in the current tree. Macros may use this variable to access the active node, its attributes, methods etc. They also may assign to this variable to activate a different node.
$root: is the root of the current tree. Macros may use this variable to access the root of the tree and (by following the tree edges) to access the whole tree. Assigning to this variable has no visible effect.

15.7.1. Node types

Each node may be associated with a PML type (see also Section 16.6.3, “Internal representation of PML data”) dictating e.g. which the attributes the node may or must carry and for each attribute its data type.

Note

Some older I/O backends do not provide PML-based typing and produce nodes that are untyped. In such a case, the names, types, and roles of the attributes can be obtained from the Treex::PML::FSFormat object associated with the document (see below).

The object representation of the data type of a node is returned by the method $node->type() (see Treex::PML::Node). It may be either from the class Treex::PML::Schema::Struct (or derived) if the node is represented in PML by a structure or Treex::PML::Schema::Container (or derived) if the node is represented in PML by a container. To get the object representation of the complete PML schema where the node type is declared (Treex::PML::Schema), one may call $node->type()->schema(), provided $node->type() is known to be defined.

15.7.2. Accessing node attributes

Let $node be a Treex::PML::Node object, i.e. a node of the tree. Typically, nodes are attribute-value structures, so the attribute named attrib is accessible as $node->{attrib}. Assigning a different value, say $val, to the attribute attrib is as simple as this:

$node->{attrib}=$val;

Attribute values may not always be atomic, i.e. numbers or strings (although for most backends this is the case). They may also be AVS structures (represented as Treex::PML::Struct objects, which are basically just Perl hashes), lists (represented as Perl ARRAY references of the Treex::PML::List class) and alternatives (represented as Perl ARRAY references of the Treex::PML::List class). So let's suppose for a while, that the value of $node->{attrib} is an AVS structure with attribute level2-attrib and its value is a list of structures with an attribute level3-attrib whose value (of whatever type it is) we want to get and possibly change. To access the attribute level3-attrib, we may either use Perl-only syntax and proceed e.g. as follows:

$node->{attrib}{level2-attrib}[0]{level3-attrib}

Notice, that from the list of structures in level2-attrib we have only selected the first one (in Perl, array indexes start with 0). This approach has a non-obvious drawback: if on some level the value is not defined, Perl “auto-creates” an empty structure on that level (this “auto-creation” continues also for all further levels of the expression). Hence, by querying a value, we have actually made a change. This typically is an undesirable effect. There are two ways to avoid it: first would be to follow the nesting of the Perl structures one level at a time and on every step first check that the value on that level is non-empty. This is however makes the code less readable and unnecessarily complex. Second method provides the same functionality with a nice syntax using so called attribute-paths. Attribute path is an expression similar to a directory path or XPath and expresses a path in the nesting of the Perl structures. Using attribute-paths, the expression

$node->{attrib}{level2-attrib}[0]{level3-attrib}

could be rewritten as

$node->attr('attrib/level2-attrib/[1]/level3-attrib')

The method attr resolves attribute-paths safely, avoiding auto-creation of Perl structures on the way. Note, that in the attribute-path, list and alternative members are indexed starting from 1. In fact, if we want to access the 1st element, we may completely skip the index specification and write:

$node->attr('attrib/level2-attrib/level3-attrib')

Sometimes it is necessary to iterate over all list members of some attributes. The macro ListV (and its cousin macro AltV used for alternatives) can be used to produce a list of all values of a given attribute, e.g.

foreach my $member
	  (ListV($node->attr('attrib/level2-attrib')))
	  { # process list member $member print
	  $member->{level3-attrib},"\n";
	  }

Values of attributes can be changed by pure Perl assignments, e.g.

$node->{attrib} = new_value;

$node->{attrib}{level2-attrib}[0]{level3-attrib} = new_value

The previous assign ment may also be achieved using

$node->set_attr('attrib/level2-attrib/[1]/level3-attrib',new_value);

The macro List can be used to construct a new list value. Several other default macros for dealing with list and alternative values exists (see Section 15.8, “Public API: pre-defined macros”).

15.7.3. Accessing neighboring nodes

There is a few methods provided by every Treex::PML::Node reference that can be used to access other nodes in the tree. Each of the methods returns either a Treex::PML::Node reference pointing to the requested node, or zero if the requested node does not exist. For example, the following code may be used to make the active node's parent node active:

$this = $this->parent if ($this->parent);

The above code states: activate the parent node of the currently active node in case the currently active node has a parent.

The following table describes some Treex::PML::Node methods. For a complete list, refer to the documentation of Treex::PML.pm.

Table 4. Treex::PML::Node methods

Method name	Description
`parent`	Return node's parent node.
`firstson`	Return the first child node of the given node (the first node depending on the given node).
`rbrother`	Return the right brother of the given node. However, hence the nodes may be displayed in the order given by the special FS-format numbering attribute `@N`, the returned node need not necessarily be displayed to the right of the given node. This is because the ordering according to the special numbering attribute does not have to correspond to the deep-first structure ordering of the tree.
`lbrother`	Return the left brother of the given node. However, as for the right brother, hence the nodes may be displayed in the order given by the special FS-format numbering attribute `@N`, the returned node need not necessarily be displayed to the left of the given node. This is because the ordering according to the special numbering attribute does not have to correspond to the deep-first structure ordering of the tree.
`following(top?)`	Return the next node of the given node in the natural ordering of the tree provided by the tree structure. E.g. if the given node has a child, this child is returned. If the node has no childs but does have a right brother, `Treex::PML::Node` reference to the right brother is returned. If no child and no right brother exists for the given node, the method looks for a right brother of its nearest ancestor, etc. Starting from the root of the tree and calling this method repeatedly on the returned nodes ensures that all the nodes in the trees are accessed during the procedure. If the optional argument `top` contains a `Treex::PML::Node` reference, the searching is limited to the subtree governed by the node of `top`.
`previous(top?)`	Return the previous node of the given node in the deep-first ordering of the tree provided by the tree structure (see the above description of the `following` method for more detail on the ordering). If the optional argument `top` contains a `Treex::PML::Node` reference, the searching is limited to the subtree governed by the node of `top`.
`children`	Return a list of all child-nodes of the given node. The nodes in the list are ordered in their structural order starting from the first son of their parent, each node followed by its right brother.

15.7.4. Accessing other trees

For this purpose many default macros exist and we recommend read their documentation first (see Section 15.8, “Public API: pre-defined macros”). In this section we describe more low-level approach that utilizes one of the most fundamental internal structures used by TrEd, namely the “grouping” structure. This structure may be accessed using the $grp variable. There is really a lot of things that can be achieved by using this variable in a proper way, but because it is an open gate to TrEd internals, it may also be dangerous. Here, we only pay our attention to a few of the safe features of $grp. In most cases, using wrappers over this structure provided by default macros, is still a much safer option.

The current file is accessed via the CurrentFile() reference. This reference is a pointer to an object of the Treex::PML::Document class. The following methods are provided for the class:

Table 5. Treex::PML::Document class methods

Method name	Description
`filename`	Returns current file's name.
`changeFilename(name)`	Change current file's name.
`FS`	Return a reference to an associated `Treex::PML::FSFormat` object.
`trees`	Return a list of all trees (i.e. a list of `Treex::PML::Node` object references pointing to the roots of the trees).
`hint`	Return the TrEd's hint pattern associated with the file.
`changeHint(pattern)`	Change the TrEd's hint pattern associated with the file.
`pattern(n)`	Return the `n`'th attribute pattern associated with the file.
`patterns`	Return a list of all attribute patterns associated with the file.
`pattern_count`	Return the number of display attribute patterns associated with the file.
`changePatterns(patterns)`	Change the list of attribute patterns associated with the file.

Actually, some other Treex::PML::Document methods exist, but as they are not intended to be used from the macros directly, there is no reason to describe them here.

The most important of the methods above is the FS method which may be used to access the Treex::PML::FSFormat class object associated with the given file. Similarly as in the case of Treex::PML::Document class, only the most importand methods of the Treex::PML::FSFormat class are described here.

Table 6. Treex::PML::FSFormat class methods

Method name	Description
`order`	Return the name of the special numerical FS attribute responsible for providing the tree order. This attribute is declared in the FS file as `@N`.
`sentord`	Return the name of the special numerical FS attribute responsible for providing the order of the values to form a “sentence”. This attribute is declared in the FS file as `@W`.
`value`	Return the name of the special FS attribute providing a descriptive value of the node used when forming a “sentence”. This attribute is declared in the FS file as `@V`.
`hide`	Return the name of the special FS attribute which can be used for hiding subtrees. This attribute is declared in the FS file as `@H`; a subtree is hidden if its governing node's value for this attribute is `'hide'` or `1`.
`isHidden(node)`	Return true if the given `Treex::PML::Node` `node` belongs to a hidden subtree.
`isList(attr)`	Return true if the given attribute is of list type with a strictly defined set of possible values. This type of attributes is declared by the `@L` header in the FS format.
`listValues(attr)`	Return a list of all possible values for the given attribute `attr`. Empty list is retured in case the attribute is not of the list type.
`color(attr)`	Return one of the `Shadow`, `Hilite`, `XHilite` and `normal` values, depending on the color specified in the FS file header. See also UseFSColors configuration option.
`attributes`	Return a list containing names of all the attributes declared in the FS file header.
`atno(n)`	Return name of the `n`'th attribute.
`indexOf(attr)`	Return index of the attribute named `attr`, according to the order in which attributes are defined in the FS file.
`count`	Return the number of attributes defined in the FS file.
`exists(attr)`	Return true if attribute named `attr` exists for the FS file. If it is not the case, false (i.e. zero) is returned.
`make_sentence(root_node)`	Return a string forming a “sentence” for the given node's subtree. The sentence is formed in the following way: All the nodes of the `root_node` node's subtree and ordered according to their values for the special numerical FS sentence ordering attribute (see method `sentord` above). The special FS numbering attribute (see method `order` above) is used if no sentence ordering attribute is declared in the FS file. For every such node, its descriptive value (see method `value` above) is taken. The values obtained in this way and order are joined into a single string with fields separated by the value of `separator`.

The methods sentord, order, value, and hide described above are useful especially in macros of general purposes, where names of the corresponding attributes are not known in advance

Note

In PML there is no equivalent of sentord, value and hide. Nodes associated with a PML type implement the methods $node->get_ordering_member_name() and $node->get_order() to get the name and value of their ordering attribute (i.e. associated with PML role #ORDER).

Note

Calling the FSFormat methods sentord, order, value, and hide (as well as Node methods get_order and get_ordering_member_name too many times (e.g. in a sort or map operations on a set of nodes) may result in bad performence, so it is recommended to store their return values in local variables. Here is an example:

  my $ord    = FS()->sentord or FS()->order;
  my $value  = FS()->value;
  return join( ' ',
	       map { $_->{$value} }
	       sort { $a->{$ord} <=> $b->{$ord} } GetDisplayedNodes() );

If the values of value, sentord or possibly order were evaluated each time the Perl sort or map function needs to compare or map nodes, the performance of the code would considerably decrease.

15.8. Public API: pre-defined macros

15.8.1. Global variables
15.8.2. Navigation
15.8.3. Tree editing API
15.8.4. Helper macros for attributes with list or alternatives of values
15.8.5. General-purpose list functions
15.8.6. GUI-related macros
15.8.7. Create/modify keyboard shortcuts
15.8.8. Stylesheet API
15.8.9. Context API
15.8.10. Treex::PML::FSFormat API
15.8.11. Treex::PML::Document I/O API
15.8.12. General I/O macros
15.8.13. Printing trees
15.8.14. Other macros
15.8.15. Implementation of TredMacro::import
15.8.16. XPath extension (slow)

The role of a public API available to macros is played by a set of macros defined in the TredMacro package in the file named tred.def. Most of these pre-defined macros are just safe wrappers for TrEd internal function calls. Pre-defined macros and object methods (namely those of Treex::PML::Node, Treex::PML::Document and Treex::PML::FSFormat should be the only access points used by a macro to interact with TrEd. All other ways of creeping into TrEd's internals are dangerous and should be avoided.

15.8.1. Global variables

$this

Current node (i.e. the active node in TrEd and the node in turn if -N or -H flag was used in bTrEd). Assigning a different node from the current tree to this variable results in changing the active node in TrEd and continuing processing at that node in bTrEd.

$root

Root of the current tree. If possible, avoid changing this variable in a macro, so that called macros may rely on its value too.

$FileChanged (alias $FileNotSaved - still valid but obsolete)

15.8.2. Navigation

Methods of Treex::PML::Node objects should be used for basic navigation within trees. Here are described means to navigate from one tree to another and a few extra macros for specific navigation in trees.

GotoTree(n)

Display the n'th tree in the current file. The number of the first tree for this function is 1.

TieGotoTree(n)

Go to n'th tree in all tied windows. The number of the first tree for this function is 1.

TieNextTree()

Display the next tree in all tied windows.

TiePrevTree()

Display the previous tree in all tied windows.

NextTree()

Display the next tree in the current file.

PrevTree()

Display the previous tree in the current file.

GetTrees()

Return a list of trees in current Treex::PML::Document. Equivallent to CurrentFile()->trees.

GetSecondaryFiles($fsfile?)

Return a list of secondary Treex::PML::Document objects for the given (or current) file. A secondary file is a file required by a file to be loaded along with it; this is typical for files containing some form of a stand-off annotation where one tree is built upon another. Note however, that this does not include so called knitting - an operation where the stand-off annotation is handled by a IO backend and the resulting knitted file appears to btred as a single unit. Only those secondary files that are already open are returned.

NextNode(node,top?)

Return the first displayed node following the given node in the subtree of top. This function behaves in the same manner as the node->following(top) method, except it works only on the nodes which are actually visible according to the state of the View->Show Hidden Nodes menu item.

PrevNode(node,top?)

Return the first displayed node preceding the given node in the subtree of top. This function behaves in the same manner as the node->previous(top) method, except it works only on the nodes which are actually visible according to the state of the View->Show Hidden Nodes menu item.

NextVisibleNode(node,top?)

Return the first visible node following the given node in the subtree of top. This function behaves in the same manner as the $node->following($top) method, except that nodes of hidden subtrees are skipped.

PrevVisibleNode(node,top?)

Return the first visible node preceding the given node in the subtree of top. This function behaves in the same manner as the $node->previous($top) method, except that nodes of hidden subtrees are skipped.

IsHidden(node)

Return true if the given node is member of a hidden subtree. This macro is only an abbreviation for FS()->isHidden(node)

Hide(node)

Hide a given node.

GetNodes(top?)

Get a list of all nodes in the current tree or (if top is given) in the subtree of top (the root of the tree is icluded as well). The list returned is ordered in the depth-first ordering. (This function automatically returns array reference in scalar context.)

GetVisibleNodes(top?)

Return the list of all visible nodes in the subtree of the given top node (or the whole current tree if no top is given). The list returned is ordered in the depth-first ordering and all members of hidden subtrees are skipped.

GetDisplayedNodes($win?)

Return the list of all nodes actually currently displayed in the current window in TrEd (which nodes are actually displayed can be e.g. specified with get_nodelist_hook).

PrevNodeLinear(node,attribute,top?)

Returns nearest node in the tree preceding the given node in linear ordering provided by the given attribute. If top node is present, only a subtree of top is examined.

NextNodeLinear(node,attribute,top?)

Returns nearest node in the tree following the given node in linear ordering provided by the given attribute. If top node is present, only a subtree of top is examined.

CurrentTreeNumber( $win? )

Return current tree number. Note that the number of the first tree if file reported by this function is 0, so you have to add 1 before passing the number to functions like GotoTree. If used in TrEd, optional argument win can be used to specify TrEd window (defaults to the current window).

GetNodeIndex()

Return given node's position in the deep-first tree ordering.

LocateNode(node?,fsfile?)

Return current filename, index of a tree (starting from 1) in the file to which the node belongs (0 if not found) and node's position in the tree in the deep-first tree ordering.

If node is not given, $this is assumed. Should the node be from a different file than the current one, the second argument must specify the corresponding Treex::PML::Document object.

ThisAddress(node?,fsfile?)

Return a given node's address string in a form of filename#tree_no.index (tree_no starts from 1 to reflect TrEd's UI convention). If the correct tree number could not be determined (the node does not belong to any top-level tree in the file) and the node has an ID, the address is returned in the form filename#ID.

If node is not given, $this is assumed. Should the node be from a different file than the current one, the second argument must specify the corresponding Treex::PML::Document object.

ThisAddressNTRED(node?,fsfile?)

Return a given node's address string in a form of ntred://filename@tree_no#1.index (tree_no starts from 1 to reflect TrEd's UI convention). If the correct tree number could not be determined (the node does not belong to any top-level tree in the file) and the node has an ID, the address is returned in the form ntred://filename#ID.

The returned address may be opened in TrEd to examine the tree in memory of a remote btred server.

If node is not given, $this is assumed. Should the node be from a different file than the current one, the second argument must specify the corresponding Treex::PML::Document object.

FPosition(node?,fsfile?)

Prints the result of ThisAddress on stdout.

NPosition(node?,fsfile?)

Prints the result of ThisAddressNTRED on stdout.

ParseNodeAddress(address)

Split given address into a filename/URL and a suffix and return these as a two element list.

15.8.3. Tree editing API

CutPaste(node,new-parent)

Cut given node (including its subtree) and paste it to a new parent. This macro is safer than PasteNode since it checks that new-parent is not a descendant of node or node itself. If the check fails, the macro dies with an error before any change is made.