A macro for TrEd is simply any Perl routine defined using the sub { ... } construct:

sub my_first_macro {
	# any Perl code may come here
}

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 another macro
}

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

To make the macro accessible from TrEd, two more things should be done. First, a special “pragmas” 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.

On startup, TrEd looks for two files with macros.

Other macro files may be included into any tred.mac file by using the following directive:

If the filename provides only a relative path, then directories are searched in the following way and order:

For convenience, two more directives are available for adding a macro to TrEd's User-defined menu and for assigning a keyboard shortcut to macro.

To connect the 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:

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

or even

To make the macro accessible via a keyboard shortcut, the #bind directive may be used. Thus, to “bind” the my_first_macro macro to say Ctrl+Alt+Del keyboard shortcut, the following line should appear somewhere in the macro file:

Again, the to and key words may be omitted.

	Warning
	Using the shortcut selected here as an example is probbably not a good idea, as it is a shortcut that restarts the system on many computers. Remember, that only shortcuts which are not interpreted by the operating system or desktop environment may be assigned to TrEd's macros and work correctly.

If both the menu item and keyboard shortcut are needed for a macro, the following abbreviated form can be used:

If more than one keyboard shortcuts or menu items are connected with the same macro, any of them may be used to invoke the macro. If more than one macro was assigned the same keyboard shortcut, the latest binding appearing in the macro files is used. Also, if two or more macros with the same name appear in the loaded macro files, the last one is used.

When an interactively invoked macro returns, TrEd automatically redraws the tree and activates the node referenced by variable $this. Moreover, the file is also considered modified which may toggle the state of the button. This may be an unwanted behaviour for macros which do not change the structure of the trees nor attribute values. To prevent TrEd from considering the file modified by the macro, the macro must explicitly set the special variable named $FileNotSaved to zero.

	Note
	If the state of the file was considered modified and not saved when a macro was interactively invoked, any changes to the $FileNotSaved variable made by the macro are ignored.

In TrEd macros as well as in TrEd itself tree nodes are represented by FSNode objects. They are basically only references to hash tables where the attribute-name/attribute-value information is stored as a key/value pair. Moreover, the FSNode object provide a few methods to access the node's neighbors in the tree.

The macro invoked by user action (e.g. pressing the keyboard shortcut assigned to the macro) may use the following global variables (declared within the TredMacro namespace, but exported by default to other derived contexts) to refer to the active node and to the root of the active tree (how to access any tree in the file will be told later):

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

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 );
}
	  

The above mentioned tred.def file provides a set of pre-defined TrEd macros. Pre-defined macros may be freely used in all other user-defined macros and are guaranteed to be updated and shipped with every version of TrEd preserving their own API. Most of the pre-defined macros wrap the key TrEd's internal function calls. The following table briefly describes each of them.

$node->{ $grp->{FSFile}->FS->order }

node->following(top)

node->previous(top)

node->following(top)

node->previous(top)

$grp->{FSFile}->FS->isHidden(node)

$grp->{FSFile}->FS->atno(n)

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.

Hooks differ from other macros in the following aspects:

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

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;
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-space are combined with a concept of binding-contexts. 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:

There is a separate submenu created for each binding-context in the User-defined menu. In TrEd there may be only one context active at one time. The active context may be choosen from the menu on the right end of the menu bar. 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.

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
}