TredMacro

TredMacro

tred.def - This package implements default macros for TrEd/bTred

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 path to TrEd's library directory.
$grp: This variable is a hash reference which stores the fundamental piece of information about current file, current context etc. DO NOT CHANGE IT. You may (and in some situations must), however, use this variable to access that information.

FUNCTION REFERENCE

Auxiliary functions

Index (array-ref, item): This is an auxiliary function imported from Fslib which returns the first occurence of the item in the array.
import (names?): If specified without parameter, exports every symbol to the caller package (except for symbols already (re)defined in the caller packages). If parameters are given, exports only names specified by the parameters and the following few variables that every TredMacro must share: $libDir $grp $root $this $_NoSuchTree $Redraw $forceFileSaved $FileChanged $FileNotSaved $NodeClipboard.

Basic TrEd-related macros

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.
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.
SetDisplayAttrs: Use the given list of TrEd's patterns for displaying attributes.
SetBalloonPattern: Use the given pattern as a new hint pattern
GetDisplayAttrs: Get the current list of patterns used by TrEd to display attributes.
GetBalloonPattern: Get TrEd's current hint pattern.
SwitchContext: Switch to given macro context.
SwitchContextForWindow: Switch given window to given macro context.
CurrentContext: Return the name of the current macro context.
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.
GetOrd (node): Return value of the special numbering FS attribute. This macro actually returns the same value as $node-{$grp->{FSFile}->FS->order()}>
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.
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.
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.
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.
Open ($filename): Open given file.
Save: Save the current file.
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.
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.
ErrorMessage (message): In TrEd, show a dialog box containing the given error-message. In BTrEd print the error message on standard output.
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.
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 the values of the current node's attributes by those stored in the global hash variable named %ValuesClipboard.
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 the given node.

Macros used by Graph2Tred macro convertor

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).
Attributes: Return a list of names of all attributes declared in the header of the current FS file.
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 empty string if the position is beyond the end of the string.

Node shifting macros

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

Miscelaneous macros

HiddenVisible: Return true if TrEd presently displays hidden nodes.
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.
GetTrees: Return a list of trees in current FSFile. Equivallent to $grp->{FSFile}->trees.
FS: Return FSFormat object associated with the current FSFile.
FileName: Return current file's name.
CurrentTreeNumber: Return current tree number.
GetNodeIndex: Return given node's position in the deep-first tree ordering.
ThisAddress: 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: 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.
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).
GetSpecialPattern (prefix): Return value of the first pattern prefixed with given prefix. Note, that only some prefixes (such as node, edge, style, or rootstyle) are used by TrEd. All other patterns are ignored, so feel free to use them for other purposes.
GUI: Return 1 if running from TrEd, i.e., GUI is available.
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(@attributes): Remove declarations of given attributes from the FS header
AddStyle($styles,$object,%styles): Auxiliary funcion: add styles for an object to given style-sheet (can be used e.g. from node_style_hook).
DefaultInputEncoding(): Return's TrEd's/bTrEd's default IO encoding.
SetDefaultInputEncoding($encoding): Set TrEd's/bTrEd's default IO encoding.
stdout: If called without arguments return current standard output filehandle. Otherwise call print the arguments to standard output.
stderr: If called without arguments return current standard error output filehandle. Otherwise call print the arguments to standard output.
tmpFileName: Returns a temporary filename..
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.
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.
PrintDialog (-option => value, ...): Display TrEd's standard print dialog. Possible options are:; -command -psFile -toFile -format -imageMagickResolution -fileExtension -useType1Font -sentenceInfo -noRotate -colors
Print (-option => value, ...): Print trees given from current file according to given printing options:; -command -toFile -filename -format -noRotate -sentenceInfo -imageMagickResolution -colors -hidden -psFontFile -psFontAFMFile -ttFont -fontSize -fmtWidth -hMargin -fmtHeight -vMargin -maximize -psMedia
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 returns a new object based on $node that allows for XPath searches relative to $node or any other node within the same tree. Caller may optionally specify functions to override some of the methods used for XPath queries. 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 @V FS-attribute value, and 'children', 'parent', 'lbrother', and 'rbrother' all default to the respective FSNode method.; Usage example:; $xp_node = SetupXPath(id => sub { $hashed_ids{ $_[0] } }, name => sub { $_[0]->{func} }, value => sub { $_[0]->{trlemma} });; foreach ($xp_node->findnodes(q{ //ACT/PAT[starts-with(@tag,``N'') or .=``cedule''] })) { # process matching nodes }