To be able to describe a method to access any tree in a file opened by TrEd from macros we must first take a more detailed look on the TrEd's internal structures and classes.
Macros have actually access to one of the most fundamental structure of TrEd: the so called “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 since actually not many members of the “Grouping” structure are guaranteed to be present or unchanged in the future versions of TrEd, here we pay our attention only to a few of the most important.
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 3. 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 4. 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 to hide several 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'. |
| isHidden(node) | Return true if the given FSNodenode 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:
|
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.