14. User Macros

14. User Macros
Prev		Next

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.

14.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” should be added, so that the macro appears in the User-defined menu and thus may be called interactively, 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.

14.2. Macro files

On startup, TrEd looks for two files with macros.

The default set of macros (described in more detail in Section 14.8, “Public API: pre-defined macros”) tred.def
The user set of 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.

Macro programmers are supposed to keep the tred.def file unchanged, but are encouraged to modify or append the tred.mac macro file according to their needs.

Other macro files may be included into any tred.mac 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 each item:

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

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

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

14.5. Associating macros with menu entries and keyboard shortcuts

The last set of directives is used for convenient adding of macros to TrEd's User-defined menu and for associating macros with keyboard shortcuts.

To connect a macro named my_first_macro with a new menu item labeled My First Macro under the User-defined menu, 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 binding context(s). The second one removes an existing menu item from the submenu of User-defined pertaining to the current binding context. These directives is especially useful for disabling certain functionality and bindings of an incuded macro file.

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

14.7. Accessing tree nodes

14.7.1. Accessing node attributes
14.7.2. Accessing neighboring nodes
14.7.3. Accessing other trees

All tree nodes in TrEd are represented by FSNode 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). FSNode objects provide several basic methods, most of which are related to accessing their neighbouring nodes in the tree.

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, it's 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.

14.7.1. Accessing node attributes

Let $node be a FSNode 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 Perl hashes), lists (represented as Perl ARRAY references of the Fslib::List class) and alternatives (represented as Perl ARRAY references of the Fslib::List class). So let's suppose for a while, that the value of $node->{attrib} is an AVS structure with attribute level2-attrib and it's 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 14.8, “Public API: pre-defined macros”).

14.7.2. Accessing neighboring nodes

There is a few methods provided by every FSNode reference that can be used to access other nodes in the tree. Each of the methods returns either a FSNode 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 all available FSNode methods:

Table 3. FSNode 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, `FSNode` 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 `FSNode` 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 `FSNode` 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.

14.7.3. Accessing other trees

For this purpose many default macros exist and we recommend read their documentation first (see Section 14.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 $grp->{FSFile} reference. This reference is a pointer to an object of the FSFile class. The following methods are provided for the class:

Table 4. FSFile 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 `FSFormat` object.
`trees`	Return a list of all trees (i.e. a list of `FSNode` 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 FSFile 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 FSFormat class object associated with the given file. Similarly as in the case of FSFile class, only the most importand methods of the FSFormat class are described here.

Table 5. 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 `FSNode` `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.
`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. However, one should keep in mind that calling these functions too often may result in considerably worse performence. The following example which actually re-implements the make_sentence method shows usage of the FSFormat object member methods.

sub MakeSentence {
  my ($top,$separator)=@_;   # two parameters

  $separator = ' ' unless defined($separator);
  my @nodes  = ();           # array to store the nodes in
  my $ord    = $grp->{FSFile}->FS->sentord ||
	       $grp->{FSFile}->FS->order;
  my $value  = $grp->{FSFile}->FS->value;

  my $node = $top;
  while ($node) {
    push @nodes, $node;      # collect all nodes in the nodes array
    $node = $node->following($top);
  }

  # Translation of the following mighty Perl construct to English:
  # 1. sort the collected nodes comparing their values for attribute $ord
  # 2. get their values using a "map" which maps element $_ to $_->{$value}
  # 3. join the values separating the fields with $separator
  # 4. and finally return the string.

  return join( $separator,
	       map { $_->{$value} }
	       sort { $a->{$ord} <=> $b->{$ord} } @nodes );
}

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.

14.8. Public API: pre-defined macros

14.8.1. Global variables
14.8.2. Navigation
14.8.3. Tree editing API
14.8.4. Helper macros for attributes with list or alternatives of values
14.8.5. General-purpose list functions
14.8.6. GUI-related macros
14.8.7. Stylesheet API
14.8.8. Context API
14.8.9. FSFormat API
14.8.10. FSFile I/O API
14.8.11. General I/O macros
14.8.12. Printing trees
14.8.13. Compatibility macros used by the Graph2Tred macro convertor
14.8.14. Implementation of TredMacro::import
14.8.15. 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 FSNode, FSFile and 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.

14.8.1. Global variables

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

If this variable is set to 1, TrEd/bTrEd considers the current file to be modified and in case of bTrEd makes the program to save it before it is closed (in case of TrEd, user is prompted before the file is closed). If the macro does not change this variable, bTrEd does not change the file status, while TrEd still assumes that the file was modified. In other words, set this variable to 1 in bTrEd if you want the file to be saved at last, and set this variable to 0 in TrEd if you are sure you did not make any change to the file that would be worth saving it. As there is a danger that calling one macro from another may result in a mess in the value of $FileChanged it is adviced to use the default macro ChangingFile() which tries to set the file status only if really intended (see below).

$Redraw

This variable makes sense only in TrEd. You may set it to one of file, tree, win, all, tie to alter the mechanism of redrawing the screen. The default value is file (redraw all windows displaying current file), while tree means redraw all windows displaying current tree, win means redraw only current window and tie means redraw all if windows are tied or (if not) redraw only current window. To disable redrawing set this variable to none.

$forceFileSaved

In TrEd, you may wish to set this variable to 0 if you wish to change the status of the file to saved (e.g. after saving the file from your macro).

$root

Root of the current tree. If possible, avoid changing this variable in your code, so that other macros you call may use it too.

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

$libDir

This variable contains a path to TrEd library directory.

$grp

This variable is a hash reference which stores the fundamental piece of information about the current file, context etc. DO NOT CHANGE IT. You may, however, use this variable to access that information:

$grp->{FSFile}: This field stores the FSFile object of the current file. See Fslib or manual to TrEd (section Accessing other trees) for more info.
$grp->{treeNo}: This field contains index of the current tree.
$grp->{macroContext}: This field contains the name of current macro context. To change current context use the pre-defined macro SwitchContext

14.8.2. Navigation

Methods of FSNode 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.
TieGotoTree(n): Go to n'th tree in all tied windows.
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 FSFile. Equivallent to $grp->{FSFile}->trees.
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 $grp->{FSFile}->FS->isHidden(node)
Hide(node): Hide a given node.
GetNodes(top?): Get a list of all nodes in the current tree of (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 natural structure 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 natural structure ordering and all members of hidden subtrees are skipped.
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(): Return current tree number.
GetNodeIndex(): Return given node's position in the deep-first tree ordering.
LocateNode(node): 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.
ThisAddress(node?): Return current node's address string in a form of filename#tree_no.index (tree_no starts from 1 to reflect TrEd's UI convention).
ThisAddressNTRED(node?): Return current 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). This address may be opened in TrEd to examine the tree in memory of a remote btred server.
FPosition(node?): Prints the result of ThisAddress on stdout.
NPosition(node?): Prints the result of ThisAddressNTRED on stdout.

14.8.3. Tree editing API

CutPaste(node,new-parent)

Cut given node and paste it to a new parent. This macro is safer than PasteNode since it checks that new-parent isn't a descendant of node or node itself. This macro dies on error before any change is made.

PasteNode(node,new-parent)

Paste the subtree of the node under the new-parent. The root of the subtree is placed among other children of new-parent with respect to the numbering attribute.

CloneSubtree(node)

Return an identical copy (except that only declared attributes are preserved) of the given subtree.

CopyNode(node)

Return an identical copy (except that only declared attributes are preserved) of the given node. The input node must belong to the current file.

CutNode(node)

Cut the node's subtree off the tree and return it. By cuttin a subtree we mean disconnecting it from the rest of the tree. Use PasteNode to attach it to some node again.

NewTree()

Create a new tree before the current tree. The new tree consists of exactly one node. This node is activated and a reference to its FSNode object is returned.

NewTreeAfter()

Create a new tree after the current tree. The new tree consists of exactly one node. This node is activated and a reference to its FSNode object is returned.

NewRBrother(node)

Create a new brother of the given node and recalculate the special FS numbering attribute values in the whole tree so that the new node is the first right sibling of the given node.

If no node is given, this function operates on $this and resets $this to the newly created node. If some node is given the value of $this is preserved.

NewLBrother(node)

Create a new brother of the given node and recalculate the special FS numbering attribute values in the whole tree so that the new node is the first left sibling of the given node.

If no node is given, this function operates on $this and resets $this to the newly created node. If some node is given the value of $this is preserved.

NewSon(parent)

Create a new child of the given parent node and recalculate the special FS numbering attribute values in the whole tree so that the new node is the first node left to the given parent.

If no parent node is given, this function operates on $this and resets $this to the newly created node. If a parent node is given the value of $this is preserved.

NewParent(node)

Create a node between given node and its parent and recalculate the special FS numbering attribute values in the whole tree so that the new node is the first node left to the given node.

If no node is given, this function operates on $this and resets $this to the newly created node. If a parent node is given the value of $this is preserved.

DeleteThisNode()

Delete the current ($this) node and recalculate the special FS numbering attribute values in the whole tree so that there is no gap in the numbering. If the current node is not a leaf or if it is the root of the current tree, this macro does nothing.

DeleteLeafNode(node)

Delete a leaf node and recalculate the special FS numbering attribute values in the whole tree so that there is no gap in the numbering. If a given node is not a leaf, this macro does nothing.

DeleteSubtree(node)

Deletes a whole node's subtree and recalculate the special FS numbering attribute values in the whole tree so that there is no gap in the numbering.

CopyValues()

Copy the values of all the attributes except the special FS numbering attribute of the current node to a global hash variable named %ValuesClipboard.

PasteValues()

Replace existing values of the current node's attributes by all values stored in the global hash variable named %ValuesClipboard. The function does not perform any node-type validity checks.

PlainNewSon(parent)

Add a new child node to the given parent and make it the current node (by setting $this to point to it).

PlainDeleteNode()

Delete the given node. The node must be a leaf of the tree (may not have any children) and must have a parent (may not be the root of the tree).

PlainDeleteSubtree(node)

Cut a the given node's subtree and destroy all its nodes. This macro doesn't recalculate ordering attributes.

NormalizeOrds(listref)

Adjusts the special FS numbering attribute of every node of the list referenced by the listref argument so that the value for the attribute corresponds to the order of the node in the list.

SortByOrd(listref)

Sort the list of nodes referenced by the listref argumnt according to the values of the special FS numbering attribute.

RepasteNode(node)

Cut the given node and paste it immediately on the same parent so that its structural position between its parent children is brought to correspondence with the values of the special FS numbering attribute.

ShiftNodeRightSkipHidden(node)

Shift the current node in the tree to the right leaping over all hidden subtress by modifying the tree structure and value of the special FS numbering attribute appropriately.

ShiftNodeLeftSkipHidden(node,min?)

Shift the current node in the tree to the left leaping over all hidden subtress by modifying the tree structure and value of the special FS numbering attribute appropriately. The optional argument min may be used to specify the minimum left boundary for the value of the ordering attribute of node.

ShiftNodeRight(node)

Shift the current node in the tree to the right by modifying the tree structure and value of the special FS numbering attribute appropriately.

ShiftNodeLeft(node)

Shift the current node in the tree to the right by modifying the tree structure and value of the special FS numbering attribute appropriately.

GetNodesExceptSubtree(node)

Returns the reference to an array containing the whole tree except the nodes strictly in the subtrees of nodes given in an array referenced by the parameter. (The returned array does contain the nodes passed in the parameter.)

MoveNode

Move the node specified by the first parameter after the node specified by the second parameter in the ordering on nodes.

MoveSubtree

Move the subtree of the node specified by the first parameter after the node specified by the second parameter in the ordering on nodes. The subtree of the first argument is made contiguous in the ordering on nodes, if it happens not to be so. (We use the fact that the technical root node is always first in the ordering.)

14.8.4. Helper macros for attributes with list or alternatives of values

CloneValue(value)

Return an identical deep copy of a given scalar. Useful for copying attribute values (and any value below them), including structured attributes, lists or alternatives.

Warning: don't apply this macro to an entire FSNode since otherwise you might result with a copy of the complete tree, schema, etc.

IsList(value)

Check that a given value is a list, i.e. Fslib::List object.

IsAlt(value)

Check that a given value is an alternative, i.e. Fslib::Alt object.

List(value,value,...)

Return a new list (Fslib::List object) populated with given values.

Alt(value,value,...)

Return a new alternative (Fslib::Alt object) populated with given values.

AltV(value)

If the value is an alternative (i.e. a Fslib::Alt object), return all its values. Otherwise return value.

ListV(value)

If the value is a list (i.e. a Fslib::List object), return all its values. Otherwise return empty (Perl) list.

AddToAlt(node,attr,value,value...)

Add given values as alternatives to the current value of $node->{$attr}. If only one value is given and $node->{$attr} is empty or same as value, the given value is simply assigned to it. If $node->{$attr} is a Fslib::Alt object, the new values are simply added to it. Otherwise, if $node->{$attr} is a simple value, $node->{$attr} is set to a new Fslib::Alt object containing the original value as well as the given values.

AddToList(node,attr,value,value,...)

Add values to a given attribute. If $node->{$attr} is not defined or empty, a new Fslib::List containing given values is created. If $node->{$attr} is a Fslib::List object, given values are simply added to it. Error is issued if $node->{$attr} is defined, non-empty, yet not a Fslib::List object.

14.8.5. General-purpose list functions

Index(array-ref,item): A helper function which returns the first occurence of the item in the array.
ListIntersect(array-ref,array-ref,...): Compute intersection of given lists. In scalar context returns an array-ref, in list context returns a list. All duplicities are removed.
ListSubtract(array-ref, array-ref): Return elements occuring in the first list but not in the second list. In scalar context returns a Fslib::List object (array-ref), in list context returns a list. All duplicities are removed.
ListUnion(array-ref, array-ref, ...): Return union of given lists. In scalar context returns an array-ref, in list context returns a Fslib::List object (array-ref). All duplicities are removed.
ListRegroupElements(array-ref, array-ref, ...): This is rotate-matrix like operation. The input is a list of rows (array-refs each representing a row in a matrix); the output is a list of columns in the matrix (a list of array-refs, each representing a column in the matrix).

14.8.6. GUI-related macros

GUI(): Return 1 if running from TrEd, i.e., GUI is available.
Redraw(): Force TrEd to immediately redraw the current window. Hence TrEd redraws the tree right after an interactively invoked macro finishes, explicit calls to Redraw macro are needed rather rearly (for example from a hook).
Redraw_FSFile(): Force TrEd to immediately redraw all windows displaying current file.
Redraw_FSFile_Tree(): Force TrEd to immediately redraw all windows displaying current tree.
Redraw_All(): Force TrEd to immediately redraw all windows.
RedrawStatusLine(): Force TrEd to immediately redraw status line.
EditAttribute(node,attribute): Open edit attribute GUI.
Find(): Open the Find Node by Attributes GUI dialog.
FindNext(): Searches for the first node matching the criteria of the previous use of the Find... menu command or FindNode macro usage.
FindPrev(): Searches for the previous node matching the criteria of the previous use of the Find... menu command or FindNode macro usage.
ToplevelFrame(): Returns the Tk::Toplevel object containing the current window.
PrintDialog(...): See the description in the Printing trees section.
ErrorMessage(message): In TrEd, show a dialog box containing the given error-message. In BTrEd print the error message on standard output.
StandardTredFont(): Return a string or Tk::Font object representation of the font used in TrEd to label tree-nodes.
StandardTredValueLineFont(): Return a string or Tk::Font object representation of the font used in TrEd to display the "sentence" above the tree.
SetCurrentNodeInOtherWin(win,node): Set active node for a given window.
CenterOtherWinTo(win,node): Center given window to a given node.
HiddenVisible(): Return true if TrEd presently displays hidden nodes.

14.8.7. Stylesheet API

STYLESHEET_FROM_FILE()

This function returns a symbolic name for a virtual stylesheet that is constructed from the patterns and hint specified in the currently displayed file.

SetStylesheetPatterns(patterns,stylesheet,create)

Set TrEd's display patterns for a given stylesheet. If stylesheet is undefined, then the stylesheet currently selected for the active view is used. The patterns argument should either be a string or an array reference. If it is a string, then it should provide all the patterns, each pattern starting on a new line (but possibly spanning across several lines) which starts with a pattern prefix of the form "something:", where "something" is hint for the hint pattern, or "node" for the node pattern, etc.

Patterns can also be provided as an array reference containing three elements: the first one being a hint text, the second the context pattern (regular expression), and the second one an array reference whose each element is the text of an individual pattern.

The create flag can be set to 1 in order to create a new stylesheet in case that no stylesheet with the given exists.

This function returns 1 if success, 0 if failed (i.e. when create is not set and a given stylesheet is not found).

DeleteStylesheet(stylesheet)

Delete given stylesheet. All windows using that stylesheet are switched to the pattern and hint specified in the respective files they display.

SaveStylesheets()

Save all TrEd's stylesheets (to ~/.tred-stylesheets).

ReloadStyleseets(filename?)

Reload stylesheets from a given file. If no filename is specified, the default path "~/.tred-stylesheets" is used.

GetStylesheetPatterns(stylesheet)

For a given stylesheet, return it's patterns. In a scalar context, returns a string consisting of all patterns, including the hint. In the array context returns three scalars: the first one containing the text of the hint pattern, the second the context pattern (regexp) and the other a reference to a list containing the stylesheet patterns. Returns empty list in case of failure.

GetPatternsByPrefix(prefix,stylesheet?)

Return all patterns of a given stylesheet starting with a given prefix. If no stylesheet name is given, a current stylesheet is used.

StylesheetExists(stylesheet)

Returns true if stylesheet with a given name exists.

Stylesheets()

Returns a list of TrEd's stylesheet names.

SetCurrentStylesheet()

Set stylesheet for the active window.

GetCurrentStylesheet()

Returns name of the stylesheet currently selected for the active window.

GetSpecialPattern(prefix) - OBSOLETE!!

This macro is obsoleted by GetPatternsByPrefix.

SetDisplayAttrs(pattern,...) - OBSOLETE!!

Setup given patterns as a stylesheet of the currently displayed FSFile. This doesn't include a hint pattern.

SetBalloonPattern(string,...) - OBSOLETE!!

Use given strings as a hint: pattern for the currently displayed FSFile.

GetDisplayAttrs() - OBSOLETE!!

Get patterns of the currently displayed FSFile's stylesheet, except for a hint: pattern.

GetBalloonPattern() - OBSOLETE!!

Get a hint: pattern of the currently displayed FSFile's stylesheet.

CustomColor(name,new-value?)

Get or set user defined custom color.

UserConf(name,new-value?)

Get or set value of a user defined configuration option.

AddStyle(styles,object,key => value,...)

Auxiliary funcion: add styles for an object to a given style-hash (can be used e.g. from node_style_hook).

14.8.8. Context API

SwitchContext(): Switch to given macro context.
SwitchContextForWindow(): Switch given window to given macro context.
CurrentContext(): Return the name of the current macro context.

14.8.9. FSFormat API

Here are described for working with FSFormat objects. Beside these macros, FSFormat object methods can be used.

FS(): Return FSFormat object associated with the current FSFile.
GetOrd(node): Return value of the special numbering FS attribute. This macro actually returns the same value as $node->{$grp->{FSFile}->FS->order()}
Attributes(): Return a list of names of all attributes declared in the header of the current FS file.
SubstituteFSHeader(declarations): Substitute a new FS header for current document. A list of valid FS declarations must be passed to this function.
AppendFSHeader(declarations): Merge given FS header declarations with the present header of the current document.
UndeclareAttributes(attribute,...): Remove declarations of given attributes from the FS header

14.8.10. FSFile I/O API

See also FSFile object methods defined in Fslib.

ChangingFile(0|1): If no argument given the default is 1. If $FileChanged is already set to 1 already 1, does nothing. If $FileChanged has not yet been assigned or is zero, sets it to the given value. Returns the resulting value. ChangingFile(1) also resets $forceFileSaved to 0.
Open(filename): Open a given FSFile in TrEd.
Save(): Save the current FSFile.
GetFileSaveStatus(): Return 1 if some file modification was noticed by TrEd untill last save or reload, 0 otherwise.
SetFileSaveStatus(): Use SetFileSaveStatus(1) to declare that some modification was made to the file. Use SetFileSaveStatus(0) after the file was saved from a macro (and TrEd/bTrEd would not notice that).
DefaultInputEncoding(): Return's TrEd's/bTrEd's default IO encoding.
SetDefaultInputEncoding(encoding): Set TrEd's/bTrEd's default IO encoding.
DumpFS(treelist,fsfile,fh): Dump given trees from the given FSFile in FS format to the given filehandle. If $treelist is undefined, all trees from the FSFile are dumped. If $fsfile is undefined, current file is used. If $fh is undefined, STDOUT is used.
FileName(): Return current file's name.
FileMetaData(key,value?): Get or set meta data associated with the current FSFile. Key is the meta data key. If value is omitted, current value associated with the key is returned. Otherwise, the given value is associated with the key, overwritting any previous value.
FileUserData(key,value?): Get or set user data associated with the current FSFile. Key is the user data key. If value is omitted, current value associated with the key is returned. Otherwise, the given value is associated with the key, overwritting any previous value.
FileAppData(key,value?): Get or set application specific data associated with the current FSFile. Key is the appData key. If value is omitted, current value associated with the key is returned. Otherwise, the given value is associated with the key, overwritting any previous value.
GotoFileNo(n): Goto n'th file in the current filelist.
LastFileNo(): Return the index of the last file in the current filelist.
CurrentFileNo(): Return the index of the current file in the current filelist.
SaveAndNextFile(): Save the current file and open the next file in the current file-list.
NextFile(): Goto next file in the file-list.
SaveAndPrevFile(): Save the current file and open the previous file in the current file-list.
PrevFile(): Goto previous file in the file-list.

14.8.11. General I/O macros

ResourcePath(): Return a list of directories in a current resource path.
AddToResourcePath(dirs): Add given directories to the current resource path.
RemoveFromResourcePath(dirs): Remove given directories from the current resource path (directory names must exactly match those listed in the resource path).
SetResourcePath(dirs): Set given list of directories as a current resource path (discarding the existing values of ResourcePath).
FindDirInResources(dirname): If a given dirname is a relative path of a directory found in TrEd's resource directory, return an absolute path for the resource. Otherwise return dirname.
FindInResources(filename): If a given filename is a relative path of a file found in TrEd's resource directory, return an absolute path for the resource. Otherwise return filename.
ResolvePath(ref-filename,filename,use_resources?): If a given filename is a relative path, try to find the file in the same directory as ref-filename. In case of success, return a path based on the directory part of ref-filename and filename. If the file can't be located in this way and use_resources is true, return the value of FindInResources(filename).
writeln(string?,...): Print the arguments to standard output appending a new-line if missing.
stdout(string?,...): If called without arguments return current standard output filehandle. Otherwise call print the arguments to standard output.
stderr(string?,...): If called without arguments return current standard error output filehandle. Otherwise call print the arguments to standard output.
tmpFileName(): Returns a temporary filename..

14.8.12. Printing trees

PrintDialog(-option => value,...)

Display TrEd's standard print dialog. Possible options providing substitutes for the default values in the print dialog are:

-command: System command to send the output to (e.g. lpr to print on the default printer on UNIX platform).
-toFile: If set to 1, the output is saved to a file specified in -filename.
-filename: Output filename.
-fileExtension: Default output file extension.
-format: One of PS, PDF, EPS, ImageMagick. Default is PS.
-imageMagickResolution: This value is passed to the command convert of the ImageMagick toolkit as -density. It specifies the horizontal and vertical resolution in pixels of the image.
-noRotate: Disable automatic landscape rotation of trees which are wider than taller.
-sentenceInfo: If set to 1, this command prints also the text associated with the tree. Instead of 0 or 1, an CODE reference (subroutine) may be passed in this parameter. This CODE is then evaluated for every tree to produce the desired text. The CODE obtains two arguments: the current FSFile object and an integer position of the tree (starting from 0).
-colors: Set to 1 for colour output.

Print(-option => value,...)

Print trees given from current file according to given printing options:

-range: Lists trees to be printed (e.g. 5,-3,9-12,15- prints trees 5,1,2,3,9,10,11,12,15,16,...)
-command: System command to send the output to (e.g. lpr to print on the default printer on UNIX platform).
-toFile: If set to 1, the output is saved to a file specified in -filename.
-filename: Output filename (only when printing to file).
-format: One of PS, PDF, EPS, ImageMagick. Default is PS.
-noRotate: Disable automatic landscape rotation of trees which are wider than taller.
-sentenceInfo: If set to 1, this command prints also the text associated with the tree. Instead of 0 or 1, a CODE reference (subroutine) may be passed in this parameter. This CODE is then evaluated for every tree to produce the desired text. The CODE obtains two arguments: the current FSFile object and an integer position of the tree (starting from 0).
-imageMagickResolution: This value is passed to the command convert of the ImageMagick toolkit as -density. It specifies the horizontal and vertical resolution in pixels of the image.
-colors: Set to 1 for colour output.
-hidden: Set to 1 to print hidden nodes.
-psFontFile: Specifies the PostScript font file to be used instead of the default one.
--psFontAFMFile: Specifies the PostScript ASCII metric font file to be used instead of the default one.
-ttFont: Specifies the TrueType font file to be used when printing via PDF.
-fontSize: Font size.
-fmtWidth: Page width.
-fmtHeight: Page height.
-hMargin: The size of the left and right horizontal margins.
-vMargin: The size of the top and bottom margins.
-maximize: Expand small trees to fit the whole page size. (Shrinking is done automatically).
-psMedia: PostScript media information used in the resulting PostScript file header (only when printing to PostScript).

14.8.13. Compatibility macros used by the Graph2Tred macro convertor

PrintToFile(filename,string,...): Print given strings to the end of the given file.
ValNo(n,string): Return the n'th field of the given string where individual fields are separated by "|".
AtrNo(n): Retrun name of the n'th attribute defined in the FS file. This macro only abbreviates the following expression: $grp->{FSFile}->FS->atno(n)
Union(string_a,string_b): Return a string consisting of |-separated fields which form a pairwise disjoint set of the |-separated fields of the given strings string_a and string_b.
Interjection(string_a,string_b): Return a string consisting of |-separated fields which form the interjection of the sets of |-separated fields of the given strings string_a and string_b.
ListSplit(string): Split the given string of |-separated fields and return a list of the individual fields.
ListJoin(list): Form a string of |-separated fields from the given list of fields.
ListEq(string1, string2): Compare the sets of |-separated fields of the two given strings. Return true if the sets contain the same elements; return false otherwise.
ListAssign(string,n,value): Return the given string of |-separated fields, except that the n'th field in the string is replaced by the given value.
SubStr(string,position,length): Simple substr wrapper which returns an empty string if the position is beyond the end of the string.

14.8.14. Implementation of TredMacro::import

import(names?): If specified without parameter, exports every symbol to the caller package (except for symbols already (re)defined in the caller package). If parameters are given, exports only names specified by the parameters and the following few variables that every package derived from TredMacro (e.g. a context) must share: $libDir, $grp, $root, $this $_NoSuchTree $Redraw, $forceFileSaved, $FileChanged, $FileNotSaved, $NodeClipboard.

14.8.15. XPath extension (slow)

SetupXPath(function-mapping...)

SetupXPath( id => \&find_node_by_id, pos => \&node_position, attributes => \&node_attributes_hashref, name => \&node_name, value => \&node_value, children => \&node_children, parent => \&node_parent, lbrother => \&node_left_sibling, rbrother => \&node_right_sibling, )

This macro requires XML::XPath module to be installed. It adjusts FSNode API to match XPath model based on a given function mapping. By defalut, 'id' is defined to return nothing, 'pos' returns nodes sentence-ordering position (or tree-ordering position if sentord attribute isn't defined), 'attributes' returs a hashref of node's attributes (actually a FSNode itself), 'name' returns "node", 'value' returns node's value of the special FS value attribute, and 'children', 'parent', 'lbrother', and 'rbrother' all default to the respective FSNode methods.

Usage example:

SetupXPath(id => sub { $hashed_ids{ $_[0] } }, name => sub { $_[0]->{functor} } value => sub { $_[0]->{t_lemma} });

foreach ($node->findnodes(q{//ACT/PAT[starts-with(@tag,"N") or .="ano"]})) { # process matching nodes }

14.9. Hooks: automatically executed macros

There is a special set of macros that was not mentioned yet. These macros, called hooks, are automatically executed by TrEd on certain occasions. By defining such macros a little more of the TrEd's implicit behaviour may be influenced, for example the execution of a planned action may be aborted.

Warning

Writing hooks correctly is a little bit more difficult than writing simple macros. An incorrectly written hook may result in errorneous behavior of TrEd, which in some cases may even lead to a crash. When in doubt about where exactly is a particular hook called, with what parameters and what it is expected to do, it is best to peek directly into tred or btred sources. The possibility of doing so is one of the nice advantages of dealing with free software - in the Richard Stallman's sense - the joy of which I feel obliged not to deprive you of.

Hooks differ from other macros in the following aspects:

User cannot choose a name for a hook; on the contrary, hook is recognized as a macro having a special name identifying it as being a certain hook.
Sometimes parameters are passed to hooks.
No modifications of the tree or current node are reflected after the hook returns, i.e. the tree is not redrawn, changes to $this variable are not reflected. If necessary, a hook must provide this functionality itself.
Unlike macros, hooks are not expected to modify the tree unless they explicitly state that, typically by calling ChangingFile(1).

There is a special class of hooks that may be used to prevent TrEd from finishing a planned action, e.g. enabling the user to modify certain attribute value etc. The value returned by a hook of this class is checked and the action is aborted in case the value equals to “stop”.

In the following table the hooks which may be used to prevent TrEd from executing a certain action are marked by yes in the column “Stop”.

Table 6. Hooks

Name	Stop	Hook event description
`start_hook`	yes	Executed on start-up, before the main event loop is entered.
`init_hook`	yes	Executed on start-up, before the first file specified on the command-line is opened (i.e. also before the `start_hook`).
`exit_hook`	no	Executed when the main window of TrEd is destroyed, before the user is prompted to save the modified files.
`event_hook`	yes	Arguments: `Tk-XEvent,Tk-win,shortcuts...` This is a very low-level hook, executed when a non-predefined keyboard shortcut was issued. It can be used to block certain keyboard events (in which case it should return `stop`) or to provide “on-the-fly” bindings (by returning the name of a macro to be executed). The first argument is an Tk::XEvent object which can be used to obtain a detailed information of the event. The second argument is a Tk::Widget that caught the event and the rest of the arguments are keyboard-binding shortcuts computed from the event (these are the shortcuts that TrEd would try to look up in the current context bindings if this hook returns no macro name).
`do_edit_node_hook`	yes	Arguments: `node` Executed before the Edit Node dialog is displayed, i.e. when the user double-clicks a node, presses Enter in the main window or issues Node->Edit Node .... If the hook returns `stop`, the dialog is suppressed.
`enable_edit_node_hook`	yes	Arguments: `node` Executed before the Edit Node dialog is displayed, i.e. when the user double-clicks a node, presses Enter in the main window or issues Node->Edit Node ..., but after `do_edit_node_hook` was called (and only if it didn't return `stop`). If this hook returns `stop`, the dialog is displayed, but only with a Cancel button, i.e. making it impossible to confirm and save the edits.
`do_edit_attr_hook`	yes	Arguments: `attr,node` Executed before a dialog window for editing an attribute value is displayed (usually when the user double-clicks the displayed attribute value). If `stop` is returned, the dialog is suppressed.
`enable_attr_hook`	yes	Arguments: `attr,type` Executed before any text field for an attribute value modification or list of possible values is created. If the hook returns “`stop`”, the field or list is made read-only. The `type` argument may have one of the following values: `ambiguous` (in case of multiple values or an attribute with a given list of possible values) or `normal`. If this hook returns `stop`, the corresponding edit fields in a displayed dialog are disabled (read-only) and if the dialog only displays the particular attribute, then the confirmation OK button is removed from it.
`goto_file_hook`	yes	Executed before the next or previous file in the current file-list is opened.
`file_opened_hook`	no	Executed after a file is opened but before the first tree is displayed.
`preload_hook`	yes	Only used by btred. Executed before a file is preloaded.
`file_resumed_hook`	no	Executed after an already open (kept) file is resumed.
`file_save_hook`	yes	Arguments: `output_filename` Executed before TrEd attempts to save a file.
`file_close_hook`	no	Executed before TrEd attempts to close a file (this hook is called even if the file remains open but postponed if the close fails e.g. because the file being closed is required by another open file).
`file_autosave_hook`	yes	Arguments: `fsfile` Executed before TrEd attempts to create an auto-save file for the given`fsfile`. Note that this is not necessarily the file displayed in the active view and accessible via the `$grp` variable.
`get_backends_hook`	no	Arguments: `backends...` Executed before a new file is opened. It receives a list of available I/O backends known by TrEd as arguments. It should return a new array-ref consisting of backends that TrEd should actually try to use. This may be used both to add custom backends to the list or to prevent some standard backends from being used (by omitting them in the returned array-ref).
`allow_switch_context_hook`	yes	Arguments: `previous,next` Executed in the new context, but before the macro context is actually changed (see Section 14.10, “Using different sets of macros in different situations”) and before `pre_switch_context_hook` is called (in the old-context). The `previous` argument contains the name of the current context while `next` contains the name of the target context.
`pre_switch_context_hook`	yes	Arguments: `previous,next` Executed in the old context before the macro context is changed (see Section 14.10, “Using different sets of macros in different situations”). The `previous` argument contains the name of the current context while `next` contains the name of the target context.
`switch_context_hook`	no	Arguments: `previous,current` Executed just after a context is changed (see Section 14.10, “Using different sets of macros in different situations”). The `previous` argument contains the name of the previous context while `next` contains the name of the new current context.
`pre_switch_stylesheet_hook`	yes	Arguments: `previous,next` Executed when user attempts to switch the current stylesheet from `previous` to `next`.
`switch_stylesheet_hook`	no	Arguments: `previous,current` Executed after switching stylesheets. The fist argument is the previous stylesheet. The second argument is the newly selected current stylesheet.
`about_file_hook`	no	Arguments: `stringref` This hook is executed before the About window is displayed. The hook takes one argument: a reference to a scalar variable. The hook may populate the referenced variable with any information which is then displayed as a part of the About window message.
`customize_attrs_hook`	yes	Executed before the dialog for customizing attribute patterns is displayed.
`sort_attrs_hook`	no	Arguments: `attibsref` Executed when attribute names are pre-sorted (see `SortAttributes` configuration options). The `attribsref` parameter passed to the hook is a reference pointing to a list variable. The list is populated with all attribute names and the hook may modify the list by changing the order of its elements or by removing certain elements from the list. If then non-zero value is returned by the hook, the (possibly modified) list is used for displaying purposes without any further sorting.
`after_edit_node_hook`	no	Arguments: `node,result` Executed after a node's attribute values were edited in the Edit Node ... dialog window. The `result` argument contains `1` if the user pressed Ok button to close the dialog, and it contains `0` if the user closed the dialog with the Close button.
`after_edit_attr_hook`	no	Executed after a node's attribute was edited in the Edit Attribute dialog window. The `result` argument contains `1` if the user pressed Ok button to close the dialog, and it contains `0` if the user closed the dialog with the Close button.
`get_value_line_hook`	no	Arguments: `fsfile,treeNo` Supply custom value-line content based on given `fsfile` and `treeNo`. The value returned from the hook may be either a string to appear in the value line on the top of TrEd's main window or an array reference consisting of a list of array references representing individual nodes. In the later case, the array references representing individual nodes must be of the form `[text, node,options...]` where `text` is a text to appear on the value-line, `node` is the node represented by the array reference and `options` is arbitrary set of strings. If these strings are of the form `-option => value` where `option` is one of `foreground`, `background`, `underline`, they are used to alter visual appearance of the corresponding part of the text displayed on the value-line. All other strings are ignored.
`highlight_value_line_tag_hook`	no	Invoked every time a node is selected. The hook should return a tag associated with some text in the value line. The text is then highlighted in the value line.
`get_nodelist_hook`	no	Arguments: `fsfile,treeNo,show_hidden` This hook may be used to supply custom node ordering given a fsfile, treeNo and hidden node visibility state. If used, it should return a two-element array reference with the first element being a array reference to a list of nodes to be displayed (in a left-to-right order) and the second element being a node to be set up as the initial active node.
`node_release_hook`	yes	Arguments: `node,target-node,mod` Called when a node is released over another node after a mouse drag. `mod` is a keyboard modifier string, such as `Control`, `Shift`, `Alt`, or `Meta`. It can also be empty. If `mod` is empty, the hook should either result 'stop', to disable the default action of cutting `node` and pasting it on `target-node`, or take no action. In all other cases, the hook may reorganize the tree in arbitrary way, but it should call `Redraw_FSFile_Tree()` and set `$FileChanged=1` if needed.
`node_doubleclick_hook`	no	Arguments: `node,mod` Called when a node is double-clicked while a modifier key was pressed. `mod` is a keyboard modifier string, such as `Control`, `Shift`, `Alt`, or `Meta`. The hook is responsible for calling `Redraw_FSFile_Tree()` or similar default macro to redraw the tree as well as for setting `$FileChanged=1` if needed.
`text_doubleclick_hook`	no	Arguments: `node,attr,mod` Called when an attribute in a displayed node or edge label is double-clicked while a modifier key was pressed. `mod` is a keyboard modifier string, such as `Control`, `Shift`, `Alt`, or `Meta`. `node` is the FSNode object whose attribute was clicked. `attr` is name of the attribute which was clicked. The hook is responsible for calling `Redraw_FSFile_Tree()` or similar default macro to redraw the tree as well as for setting `$FileChanged=1` if needed.
`line_click_hook`	no	Arguments: `node,tag,button,double,mod,XEvent` Called when a line (segment of an edge) is clicked or double-clicked. Argument values are as follows: `node` is the node the line pertains to (i.e. the one whose stylesheet specification caused the line to be drawn); `tag` is the part of the stylesheet value `Line-tag` corresponding to the particular segment of the line; `button` is the number of mouse button (1,2,3); `double` is 1 if the event was a double-click and 0 otherwise; `mod` is a keyboard modifier (`Control`, `Shift`, `Alt`, or `Meta`); `XEvent` is a `Tk::XEvent` object which can be used to obtain detailed information of the event (such as position of the mouse pointer, etc.). The hook is responsible for calling `Redraw_FSFile_Tree()` or similar default macro to redraw the tree as well as for setting `$FileChanged=1` if needed.
`node_moved_hook`	no	Arguments: `node,old-parent` called after a node is moved using a mouse
`current_node_change_hook`	no	Arguments: `current_node,prev_current_node` executed when a new active node is selected.
`get_status_line_hook`	no	Supply status-line content. This hook is responsible for providing the content for a status-line. The value returned from `get_status_line_hook` should have the form `[field-definitions, style-definitions, ]`. `field-definitions` is an array reference of the form `[text1,tags1, text2,tags2,... ]` specifying one or more pieces of textual content of the status-line. Each piece of text is followed by another array reference, containing a list of `tags` associated with the text. Tags may be arbitrary strings. `style-definitions` is an array reference which can map some tags to visual appearance attributes. It has a form `[tag1, [option => value, option => value, ...], tag2, [option => value, option => value, ...], ... ]` where `option` may be one of `-foreground`, `-background` and `-underline`.
`value_line_doubleclick_hook`	no	Arguments: `tags...` Called when the user double-clicks the text in the value-line, i.e. text field displayed above the tree. Arguments are the tags associated with the clicked part of the text. Tag may be arbitrary strings associated with the text in the `value_line_hook` or a serialized form of a node reference if the text is associated with a particular node. (More specifically, the Perl expression `$tag eq $node` is true for one of the tags and the corresponding node, where `$tag` is a simple scalar, i.e. astring. Hence, if necessary, the macro has to iterated through the tree in order to find the corresponding node.)
`status_line_doubleclick_hook`	no	Arguments: `tags...` Called when the user double-clicks the status-line. Arguments are the tags associated with the clicked field (see above). Tag may be arbitrary strings and it is up to user's will to set up some useful convention for tagging text of the status-line.
`status_line_click_hook`	no	Arguments: `tags...` Called when the user clicks the status-line with the same arguments as `status_line_doubleclick_hook` above.
`reload_macros_hook`	no	Executed before macros are re-loaded (i.e. when the user issues Help->Reload macros). This macro may be used to do clean-up (e.g. cleanly deallocate non-perl resources, break circular dependences, etc.) before TrEd sweeps away the memory and code currently occupied and used by macros.
`macros_reloaded_hook`	no	Executed after macros has been re-loaded (i.e. after the user issued Help->Reload macros). At the moment of the call to this hook, the newly loaded macros are already in effect.
`node_click_hook`	no	Arguments: `node,modifier,XEvent` Executed when the user clicks on a node with a mouse button while holding a keyboard modifier (one of Shift, Control, Alt, Meta). The first argument is a node the user clicked on. The second argument is the keyboard modifier to which the suffix `-2` or `-3` has been appended if the user pressed mouse button 2 or 3 respectivelly. The last argument is a raw `Tk::XEvent` object which can be used to obtain details about the event (such as position of the mouse pointer, etc.).
`node_motion_hook`	no	Arguments: `node,modifier,XEvent` Executed repeatedly while the user drags a node while holding a keyboard modifier. Arguments passed to this hook are same as for the `node_click_hook`.
`text_click_hook`	no	Arguments: `node,attribute,modifier,XEvent` Executed when the user double-clicks on a node label linked to a particular node attribute. The `modifier` and `XEvent` arguments are as described in `node_click_hook` above.
`node_style_hook`	no	Arguments: `node,syles` This hook is called for every node of a tree every time the tree is being drawn. It may be used to provide additional styling information on top of the information provided by a current stylesheet. The first argument is the particular node. The second argument is a hash-reference containing current styling information provided by defaults and the current stylesheet. It consists of key - value pairs, where key is a styled object (`Node`,`NodeLabel`, `EdgeLabel`, `Oval`, `Line`, `Text`, `TextBg`, `TextBox`) and values are array-references consisting of feature - value pairs for these objects. The hook may alter this hash-reference and thus the styling of the particular node. It is recommended to take the advantage of the `AddStyle` default macro when altering the content of the `styles` hash-ref.
`root_style_hook`	no	Arguments: `root-node,syles` This hook is executed once every time the tree is being drawn before the content of a currently selected stylesheet is applied and before `node_style_hook` is called. The first argument is the root-node of the tree and `styles` are as in `node_style_hook` above.
`print_tree_filename_hook`	no	Executed when File->Print ... command is invoked in order to obtain a suggestion for the target file-name used when printing to file.

14.10. Using different sets of macros in different situations

Name-spaces, contexts and binding contexts

TrEd adopts mechanisms similar e.g. to Emacs major-modes which allow the user to safely create several sets of macros with possibly coliding key and menu bindings as well as macro names. These mechanisms are called contexts, or more specifically: name-spaces and binding contexts.

To prevent macros from colliding or modifying the internal TrEd variables or functions the Perl concept of packages or namespaces is used. Unless the Perl package command is used, each macro belongs to a default package (or name-space) called TredMacro. Beside the user-defined macros, the pre-defined macros are defined within this package.

New package named say MyPackage is created using the following command:

package MyPackage;

To be able to call macros defined in the TredMacro package (e.g. the pre-defined macros) without having to prefix their names with one of TredMacro-> or TredMacro:: prefixes the following command may be used to import the TredMacro name-space to the current package's name-space:

import TredMacro;

Now all the subsequent macro definitions (or global variable declarations) are created within the MyPackage name-space unless other package command occurs. Thus the following example defines a macro named my_macro in a new name-space of the MyPackage package:

package MyPackage;
import TredMacro;

sub my_macro {
  # macro code comes here 
}

To call the my_macro of the previous example from a different package than MyPackage, the full package name must be given together with the name of the macro:

MyPackage::my_macro();   # call to a macro defined in MyPackage

In the interactive work, name-spaces are combined with a concept of binding-contexts. Only one context can be active in TrEd at a time. The active context is displayed on and may be selected from a menu on the right end of the menu bar.

Binding contexts usually correspond to the package names. Analogously to the package command, a special directive exists for creating or switching a binding context, however in this case, more then one binding-contexts may be used at once:

#binding-context context_name_1 context_name_2 ...

The default binding-context is again named TredMacro. To switch to a new context, say MyContext, the following directive should be used:

#binding-context MyContext

Now, all the subsequent directives #bind, #insert, #unbind-key, and #remove-menu would apply to this context and all the bound macros, when invoked, will be first searched in the package named MyContext.

A binding context may import menu and keyboard bindings from other context(s) using

#key-binding-adopt other_context(s)

and

#menu-binding-adopt other_context(s)

directives.

There is a separate submenu created for each binding-context in the User-defined menu. For contexts with a large number of menu bindings it is usually more comfortable to select a macro using View->List of available macros.

If a keyboard shortcut is pressed, TrEd first searches for a macro bound to the shortcut within the active binding-context and if such macro exists, TrEd invokes it. In this case, the macro is supposed to be defined or imported in a package of the same name as is the name of the active context. If no macro is bound to the shortcut within the active binding-context, TrEd tries to find a binding in the default TredMacro context. The macro is then supposed to be defined within the TredMacro package. If the search fails, no action is taken. The same holds for hooks as well.

The following example shows how to create a set of macros which enable TrEd to automatically decide which context to use when a file is opened. It is quite similar to the Emacs concept of “auto-modes”, except that content of the file is considered here, not the file-name extension. In the example, existence of a certain attribute is used to decide which context to use. The example is extracted form the set of macros written for the annotation of the Prague Dependency Treebank. There are two contexts for annotation: for the “Analytic” and “Tectogrammatic” layers. The “tectogrammatic” trees may be easily distinguished from the “analytical” ones because (among others) a special attribute named TR is defined for them.

Example 3. Using contexts

package TredMacro; # Ensure we are in the default package
                   # (This may not be necessary.)

# we use a hook to set the context
sub file_opened_hook {
  if ($grp->{FSFile}->FS->exists('TR')) {
    SwitchContext('Tectogrammatic'); 
  } else {
    SwitchContext('Analytic');
  }
}

#binding-context Analytic
package Analytic;
import TredMacro;


#bind SubtreeAfunAssign to Ctrl+Shift+F1
sub SubtreeAfunAssign {
   # automatic assignment of some analytical attributes
}

sub ReorderTree {
   # ...
}


# the following binding of ReorderTree will apply to both binding contexts

#binding-context Analytic Tectogrammatic
#bind ReorderTree to Ctrl+R

#binding-context Tectogrammatic
package Tectogrammatic;
import Analytic;   # all macros of the Analytic package (eg. ReorderTree) 
	           # will now be available here directly

#bind SubtreeAfunAssign to Ctrl+Shift+F1
sub SubtreeFuncAssign {
   # automatic assignment of some tectogrammatical attributes
}

Prev		Next
13. Command-line options	Home \| ToC	15. I/O backends