=pod

=head1 TredMacro

TredMacro (F<tred.def>) - implements the public API for TrEd/bTred macros

=head2 Global variables

=over 4

=item C<$this>

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

=item C<$root>

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

=item C<$FileChanged> (alias C<$FileNotSaved> - still valid but obsolete)

See also C<ChangingFile()>.

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 B<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 C<$FileChanged> it is
adviced to use the default macro C<ChangingFile()> which tries to set
the file status only if really intended (see below).

=item C<$Redraw>

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

=item C<$forceFileSaved>

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

=item C<$libDir>

This variable contains a path to TrEd library directory.

=back

=head2 Navigation

Methods of L<Treex::PML::Node|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm> 
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.

=over 4

=item C<GotoTree(n)>

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

=item C<TieGotoTree(n)>

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

=item C<TieNextTree()>

Display the next tree in all tied windows.

=item C<TiePrevTree()>

Display the previous tree in all tied windows.

=item C<NextTree()>

Display the next tree in the current file.

=item C<PrevTree()>

Display the previous tree in the current file.

=item C<GetTrees()>

Return a list of trees in current L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm>. Equivallent to
C<<< CurrentFile()->trees >>>.

=item C<GetSecondaryFiles($fsfile?)>

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

=item C<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.

=item C<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.

=item C<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
C<$node-E<gt>following($top)> method, except that nodes of hidden subtrees
are skipped.

=item C<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
C<$node-E<gt>previous($top)> method, except that nodes of hidden subtrees
are skipped.

=item C<IsHidden(node)>

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

=item C<Hide(node)>

Hide a given node.

=item C<GetNodes(top?)>

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

=item C<GetVisibleNodes(top?)>

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

=item C<GetDisplayedNodes($win?)>

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

=item C<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.

=item C<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.

=item C<CurrentTreeNumber( $win? )>

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

=item C<GetNodeIndex()>

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

=item C<LocateNode(node?,fsfile?)>

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

If C<node> is not given, C<$this> is assumed. Should the node be from a
different file than the current one, the second argument must specify
the corresponding L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> object.

=item C<ThisAddress(node?,fsfile?)>

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

If C<node> is not given, C<$this> is assumed. Should the node be from a
different file than the current one, the second argument must specify
the corresponding L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> object.

=item C<ThisAddressNTRED(node?,fsfile?)>

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

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

If C<node> is not given, C<$this> is assumed. Should the node be from a
different file than the current one, the second argument must specify
the corresponding L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> object.

=item C<FPosition(node?,fsfile?)>

Prints the result of C<ThisAddress> on stdout.

=item C<NPosition(node?,fsfile?)>

Prints the result of C<ThisAddressNTRED> on stdout.

=item C<ParseNodeAddress(address)>

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

=back

=head2 Tree editing API

=over 4

=item C<CutPaste(node,new-parent)>

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

Note: this macro does not verify node types. Use
C<$parent-E<gt>test_child_type($node)> to be sure that type declarations permit
the node as a child node of the new parent.

=item C<CutPasteBefore(node,ref_node)>

Cut given node (including its subtree) nd paste it on ref_node's
parent node just before ref_node. This macro is safer than
PasteNodeBefore since it checks that new-parent is not a descendant of
node or node itself. This macro dies on error before any change is
made.

Note: this macro does not verify node types. Use
C<$parent-E<gt>test_child_type($node)> to be sure that type declarations permit
the node as a child node of the new parent.

=item C<CutPasteAfter(node,ref_node)>

Cut given node (including its subtree) and paste it on ref_node's parent node just after
ref_node. This macro is safer than PasteNodeBefore since it checks
that new-parent is not a descendant of node or node itself. This macro
dies on error before any change is made.

Note: this macro does not verify node types. Use
C<$parent-E<gt>test_child_type($node)> to be sure that type declarations permit
the node as a child node of the new parent.

=item C<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.

Note: this macro does not verify node types. Use
C<$parent-E<gt>test_child_type($node)> to be sure that type declarations permit
the node as a child node of the new parent.

=item C<PasteNodeBefore(node,ref_node)>

Cut given node (including its subtree) and paste it on ref_node's
parent node just before ref_node.

Note: this macro does not verify node types. Use
C<$parent-E<gt>test_child_type($node)> to be sure that type declarations permit
the node as a child node of the new parent.

=item C<PasteNodeAfter(node,ref_node)>

Cut given node (including its subtree) and paste it on ref_node's
parent node just after ref_node.

Note: this macro does not verify node types. Use
C<$parent-E<gt>test_child_type($node)> to be sure that type declarations permit
the node as a child node of the new parent.

=item C<CloneSubtree(node)>

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

=item C<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.

=item C<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.

=item C<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 L<Treex::PML::Node|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm>
object is returned.

=item C<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 L<Treex::PML::Node|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm>
object is returned.

=item C<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 C<$this> and B<resets>
C<$this> to the newly created node. If some node is given the value
of C<$this> is preserved.

=item C<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 C<$this> and B<resets>
C<$this> to the newly created node. If some node is given the value
of C<$this> is preserved.

=item C<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 right to the given parent.

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

=item C<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 C<$this> and
B<resets> C<$this> to the newly created node. If a parent node is
given the value of C<$this> is preserved.

=item C<DeleteThisNode()>

Delete the current (C<$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.

=item C<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.

=item C<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.

=item C<RemoveTree(n?,fsfile?)>

Removes n-th tree from a given L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> (trees are numbered starting from 0).
If no L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> is specified, uses the current file (see CurrentFile()).

Calling RemoveTree() without arguments, it is equivalent to

  RemoveTree(CurrentTreeNumber(),CurrentFile())

Returns the deleted tree. If you do not reattatch the tree to the L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm>,
use $tree->destroy method on the returned tree to prevent a memory leak.

=item C<DestroyTree(n?,fsfile?)>

Like RemoveTree but immediatelly destroys the removed tree. Returns 1
on success.

=item C<DetermineNodeType($node)>

For trees with L<Treex::PML::Schema|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Schema.pm>-based node typing, try to determine the type
of the node from the type of its parent, and associate the node with
the type (using $node->set_type). If there are more possibilities, the
user is asked to choose the correct type.

=item C<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.

=item C<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.

=item C<PlainNewSon(parent)>

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

=item C<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).

=item C<PlainDeleteSubtree(node)>

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

=item C<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 and repaste each node
so that the structural order corresponds with this new numbering.

If no numbering FS numbering attribute is available, all this macro
does is to ensure that the structural order of sibling nodes
corresponds to their order in the given list.

=item C<SortByOrd(listref)>

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

=item C<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.

=item C<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.

=item C<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.

=item C<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
accordingly.

=item C<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.

=item C<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.)

=item C<MoveNode(source-node,target-node)>

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

=item C<MoveSubtree(source-node,target-node)>

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

=back

=head2 Helper macros for attributes with list or alternatives of values

=over 4

=item C<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: do not apply this macro to an entire L<Treex::PML::Node|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm> since otherwise
you might result with a copy of the complete tree, schema, etc.

=item C<IsList(value)>

Check that a given value is a list, i.e. L<Treex::PML::List|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm> object.

=item C<IsAlt(value)>

Check that a given value is an alternative, i.e. L<Treex::PML::Alt|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Alt.pm> object.

=item C<IsSeq(value)>

Check that a given value is a sequence, i.e. L<Treex::PML::Seq|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Seq.pm> object.

=item C<List(value,value,...)>

Return a new list (L<Treex::PML::List|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm> object) populated with given values.

=item C<Alt(value,value,...)>

Return a new alternative (L<Treex::PML::Alt|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Alt.pm> object) populated with given values.

=item C<AltV(value)>

If the value is an alternative (i.e. a L<Treex::PML::Alt|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Alt.pm> object), return
all its values. Otherwise return value.

=item C<ListV(value)>

If the value is a list (i.e. a L<Treex::PML::List|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm> object), return
all its values. Otherwise return empty (Perl) list.

=item C<SeqV(value)>

If the value is a sequence (i.e. a L<Treex::PML::Seq|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Seq.pm> object), return all its
elements (L<Treex::PML::Seq::Element|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Seq/Element.pm> objects). Otherwise return empty (Perl)
list.

=item C<AddToAlt(node,attr,value,value...)>

Add given values as alternatives to the current value of
C<$node-E<gt>{$attr}>.  If only one value is given and C<$node-E<gt>{$attr}> is
empty or same as value, the given value is simply assigned to it. If
C<$node-E<gt>{$attr}> is a L<Treex::PML::Alt|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Alt.pm> object, the new values are simply added
to it. Otherwise, if C<$node-E<gt>{$attr}> is a simple value, C<$node-E<gt>{$attr}>
is set to a new L<Treex::PML::Alt|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Alt.pm> object containing the original value as
well as the given values.

=item C<AddToList(node,attr,value,value,...)>

Add values to a given attribute. If C<$node-E<gt>attr($attr)> is not defined or
empty, a new L<Treex::PML::List|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm> containing given values is created. If
C<$node-E<gt>attr($attr)> is a L<Treex::PML::List|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm> object, given values are simply added
to it. Error is issued if C<$node-E<gt>attr($attr)> is defined, non-empty, yet not
a L<Treex::PML::List|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm> object.

=item C<AddToListUniq(node,attr,value,value,...)>

Add values to a given attribute, unless already present among the
current values. If C<$node-E<gt>attr($attr)> is not defined or empty,
a new L<Treex::PML::List|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm> containing given values is created. If
C<$node-E<gt>attr($attr)> is a L<Treex::PML::List|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm> object, given values are
simply added to it. Error is issued if C<$node-E<gt>attr($attr)> is
defined, non-empty, yet not a L<Treex::PML::List|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm> object.

=item C<AddToSeq(node, attr, name => value, name => value,...)> or C<AddToSeq(node, attr, element, ...)>

Add elements to a given sequence attribute. If C<$node-E<gt>attr($attr)> is not defined or
empty, a new L<Treex::PML::Seq|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Seq.pm> object containing given name-value pairs (L<Treex::PML::Seq::Element|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Seq/Element.pm> objects) is created. If
C<$node-E<gt>attr($attr)> is a L<Treex::PML::Seq|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Seq.pm> object, given elements are simply added
to it. Error is issued if C<$node-E<gt>attr($attr)> is defined, non-empty, yet not
a L<Treex::PML::Seq|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Seq.pm> object.

=back

=head2 General-purpose list functions

=over 4

=item C<Index(array-ref,item)>

A helper function which returns the index of the first occurence of a
given item in an array. Returns nothing (empty list) if the item is
not found. Note: 'eq' is used for comparison.

=item C<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.

=item C<ListSubtract(array-ref, array-ref)>

Return elements occuring in the first list but not in the second list.
In scalar context returns a L<Treex::PML::List|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm> object (array-ref), in list
context returns a list. All duplicities are removed.

=item C<ListUnion(array-ref, array-ref, ...)>

Return union of given lists. In scalar context returns an array-ref,
in list context returns a L<Treex::PML::List|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm> object (array-ref). All
duplicities are removed.

=item C<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).

=back


=head2 GUI-related macros

=over 4

=item C<GUI()>

Return a reference if running from TrEd, i.e., GUI is available;
otherwise return C<undef>. If running from TrEd the returned value is
a TrEd::Window object representing the currently focused window.

=item C<CloseGUI()>

This macro is only available in TrEd. It closes TrEd's main window and
exits.

=item C<TrEdWindows()>

Return a list of TrEd::Window objects representing current TrEd
windows.

=item C<CurrentWindow()>

Return a TrEd::Window object representing the currently focused
window.

=item C<SetCurrentWindow(win)>

Focus a given window.

=item C<SplitWindowHorizontally(\%opts?)>

Split current window horizontally. Returns an object represening the
newly created window.

An optional HASHref with the following options can be passed as an argument:

=over 8

=item no_focus => 0|1

do not focus the new view (default value is 1)

=item no_init => 0|1

do not initialize the new view with the file, context, etc. from the
current vie (default value is 0)

=item no_redraw => 0|1

do not redraw the new view

=item ratio => float

A float value between 0 and 1 indicating the ratio of the height of
the new view to the current height of the active view.

=back

=item C<SplitWindowVertically()>

Split current window horizontally. Returns an object represening the
newly created window.

An optional HASHref with the following options can be passed as an argument:

=over 8

=item no_focus => 0|1

do not focus the new view (default value is 1)

=item no_init => 0|1

do not initialize the new view with the file, context, etc. from the
current vie (default value is 0)

=item no_redraw => 0|1

do not redraw the new view

=item ratio => float

A float value between 0 and 1 indicating the ratio of the height of
the new view to the current height of the active view.

=back

=item C<CloseWindow(win?)>

Close a given window, unless it is the last window that exists.  If no
window is given as an argument, try closing the current window.  If
the closed window was focused, then a next sibling window gets focus.

=item C<CurrentFile(win?)>

Return a L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> object representing the file currently open in a given
TrEd window or in the currently focused window if called without
arguments.

=item C<CurrentNodeInOtherWindow(win)>

Return the node currently active in a given window.

=item C<SetCurrentNodeInOtherWindow(win,node)>

Set active node for a given window.

=item C<InVerticalMode()>

Return true if the tree is currently displayed in the vertical mode.

=item C<ToplevelFrame()>

Returns the Tk::Toplevel object containing the current window.

=item C<PrintDialog(...)>

See the description in the L<Printing trees> section.

=item C<Redraw($win?.$ignoreThis)>

Force TrEd to immediately redraw the current (or given) 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). If the flag $ignoreThis is used, then current
value of $this variable will not be used to determine the current node
of the window (i.e. $win->{currentNode}).

=item C<Redraw_FSFile()>

Force TrEd to immediately redraw all windows displaying current
file.

=item C<Redraw_FSFile_Tree()>

Force TrEd to immediately redraw all windows displaying current
tree.

=item C<Redraw_All()>

Force TrEd to immediately redraw all windows.

=item C<RedrawStatusLine()>

Force TrEd to immediately redraw status line.

=item C<EditAttribute(node,attribute)>

Open edit attribute GUI.

=item C<Undo()>

Act as if the user pressed the undo button. Note that this macro also
changes $this and $root (since undo replaces the current tree with an
in-memory copy).

WARNING: Be aware that calling Undo() from a hook may conflict with
some macros, more specifically, with macros triggering such a hook
(indirectly, i.e. via some API call). In a case, changes to $this and
$root caused by Undo() do not propagate to the macro, which in turn
ends up working with incorrect (already replaced) nodes. Thus, if
calling Undo() within a hook, make sure to reset $this from
$grp->{currentNode} and $root from $this->root after all calls from
your macros which may possibly invoke the hook.

=item C<Redo()>

Act as if the user pressed the undo button. Note that this macro also
changes $this and $root.

=item C<SaveUndo(comment)>

Save a snapshot of the current tree so that following operations on it
can be reverted with Undo. The C<comment> argument should provide
user-visible one-line diescription of the action following SaveUndo.

=item C<ForgetRedo()>

Disable redo. This is useful if you programmatically Undo user's
action and do not want the user to be able to redo the action with
Redo.

=item C<Find()>

Open the Find Node by Attributes GUI dialog.

=item C<FindNext()>

Searches for the first node matching the criteria of the previous use
of the Find... menu command or FindNode macro usage.

=item C<FindPrev()>

Searches for the previous node matching the criteria of the previous
use of the Find... menu command or FindNode macro usage.

=item C<ErrorMessage(message)>

In TrEd, show a dialog box containing the given error-message in a
text window.  In BTrEd print the error message on standard error output.

=item C<InfoMessage(message)>

In TrEd, show a dialog box containing the given info-message in a
text window.  In BTrEd print the message on standard output.

=item C<StandardTredFont()>

Return a string or Tk::Font object representation of the font used in
TrEd to label tree-nodes.

=item C<StandardTredValueLineFont()>

Return a string or Tk::Font object representation of the font used in
TrEd to display the "sentence" above the tree.

=item C<CenterOtherWinTo(win,node)>

Center given window to a given node.

=item C<HiddenVisible(win?)>

Return true if TrEd displays hidden nodes in a given window (or the
currently focused window if called without an argument).

=item C<ToggleHiding($win?)>

If TrEd displays hidden nodes (or the currently focused window if
called without an argument), hide them and vice versa.

=back

=head2 Create/modify keyboard shortcuts

=over 4

=item C<<< Bind( macro => bind-options,...) >>>

This macro can be used to dynamically create keyboard bindings and
menu items for user-defined macros in TrEd. The arguments consist of
one or more (macro => bind-options ) pairs
where macro is a subroutine name or a CODE reference and
bind-options is either a keyboard shortcut (e.g. 'Ctrl+a') or a HASH references
with the following keys and values (all optional):

=over 8

=item context

the binding context, e.g. the package in which context the macro is
evaluated. Only relevant if the macro is specified by name. If not
given, the caller package is used.

=item key

a keyboard binding for the macro (e.g. 'Ctrl+a'); if not given, no
keyboard binding is created.

=item menu

a label to be used for a menu-item created for the macro. If not
given, no menu-item is created for the macro.

=item changing_file

if the key C<changing_file> exists in the bind-options hash and its
value is I<value>, a call to the macro C<<< ChangignFile(I<value>) >>>
is made immediatelly after each invocation of the macro via this
binding.

=back

=item C<UnbindBuiltin(key-binding)>

(TrEd only). Remove default TrEd's keybinding for a given key so that
custom macro can be bound to that key.
E.g. UnbindBuiltin('Ctrl+Home'); Note: use with care. Built-in
key-bining once removed cannot be restored (except by restarting TrEd).

=item C<OverrideBuiltinBinding(context,key-binding, binding_spec )>

(TrEd only). Get or modify default TrEd's keybinding.

The C<binding_spec> argument, if given, must be an array reference with two elements:

  [ sub { ... }, 'description' ]

WARNING: You have to be very careful when overriding a builtin
binding, since your code is not called as a macro or a hook! The routine is
called with the following three arguments:

  $tk_window, $grp->{framegroup}, $key

You may obtain $grp from the second argument using
$_[1]->{currentWindow}.  You should probably call Tk->break at the end
of your code, so that the event does not propagate. There is no
C<$root> or C<$this> available within the callback.

A safer way (with slower execution, though) is to use a macro wrapped
into a MacroCallback() instead of a sub:

 [ MacroCallback(...), 'description' ]

See C<MacroCallback> macro for details. The macro is called with the
same arguments (appended to a list of arguments provided in
C<MacroCallback>). The macro can use all standard macro functions and
variables.

If the C<context> argument is a name of a binding context, the binding
is only used in the specific context.  If C<context> is C<'*'>, the
binding applies to all contexts (except for contexts that specifically
overrid it).

If called without a binding_spec, the current binding_spec is returned, otherwise
the previous binding_spec is returned.

Example (swaps the behavior of normal C<left/right> with C<Shift+left/right>)

  my @keys = qw(Left Right);
  my %normal = map { $_ => OverrideBuiltinBinding('*',$_) } @keys;
  my %shift = map { $_ => OverrideBuiltinBinding('*',"Shift+$_") } @keys;
  for (@keys) {
    OverrideBuiltinBinding(__PACKAGE__, $_, $shift{$_});
    OverrideBuiltinBinding(__PACKAGE__, "Shift+$_", $normal{$_});
  }

Here is another example that changes the Up arrow to move to the
grand-parent instead of a parent:

  # Using TrEd internals (faster, but prone to changes in the internal API):

  OverrideBuiltinBinding(
    __PACKAGE__,
    'Up',
    [sub { main::currentUp($_[1]) for 1..2 },
    'Move to grand-parent']);

  # Using a macro (slower):

  OverrideBuiltinBinding(
    __PACKAGE__,
    "Up",
    [MacroCallback(sub { $this=$this->parent; $this=$this->parent if $this }),
    'Move to grand-parent']);

=item C<MacroCallback(macro_spec,@args)>

This macro can be used to safely wrap a given macro into a code that
can be used to override a TrEd builtin or passed as a callback to a Tk
widget.

The first argument can take one of the following forms:

  String:
    "macro_name" or "Package->macro_name"

  Anonymous subrutine:
    sub { ...code... }

  Hash reference:
    { -command => sub { ...code... },
      -changing_file => 0 | 1,
      -contex => 'PackageName'
    }

  Array reference:
    [ sub { ..code ...}, arg1, arg2, ...]

The macro is called with the arguments provided in the macro_spec,
followed by the arguments provided in the call to MacroCallback,
followed by arguments passed by the caller (e.g. TrEd or the Tk
widget).

=back

=head2 Stylesheet API

=over 4

=item C<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.

=item C<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).

=item C<DeleteStylesheet(stylesheet)>

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

=item C<SaveStylesheet(name)>

Save given TrEd's stylesheet (to ~/.tred.d/stylesheets/name).

=item C<SaveStylesheets()>

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

=item C<ReloadStylesheet(name,dir?)>

Reload a given stylesheet. If no dir is specified, the
default path "~/.tred.d/stylesheets/" is used.

=item C<ReloadStylesheets(dir?)>

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

=item C<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.

=item C<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.

=item C<StylesheetExists(stylesheet)>

Returns true if stylesheet with a given name exists.

=item C<Stylesheets()>

Returns a list of TrEd's stylesheet names.

=item C<GetCurrentStylesheet()>

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

=item C<SetCurrentStylesheet(stylesheet_name)>

Set stylesheet for the active window.

=item C<GetSpecialPattern(prefix)> - OBSOLETE!!

This macro is obsoleted by GetPatternsByPrefix.

=item C<SetDisplayAttrs(pattern,...)> - OBSOLETE!!

Setup given patterns as a stylesheet of
the currently displayed L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm>. This does not include
a hint pattern.

=item C<SetBalloonPattern(string,...)> - OBSOLETE!!

Use given strings as a C<hint:> pattern for
the currently displayed L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm>.

=item C<GetDisplayAttrs()> - OBSOLETE!!

Get patterns of the currently displayed L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm>'s stylesheet, except
for a C<hint:> pattern.

=item C<GetBalloonPattern()> - OBSOLETE!!

Get a C<hint:> pattern of the currently displayed
L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm>'s stylesheet.

=item C<CustomColor(name,new-value?)>

Get or set user defined custom color.

=item C<UserConf(name,new-value?)>

Get or set value of a user defined configuration option.

=item C<AddStyle(styles,object,key =E<gt> value,...)>

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

=item C<GetStyles(styles,object,$feature?)>

Auxiliary funcion: if feature is given, retrieves and returns a
feature of a particular object from the given style-hash.  If feature
is not given or undef, returns a (flat) list of feature => value pairs
consisting of the style features of a given type of object obtained
from the style-hash.

This function can be used e.g. from node_style_hook.

=back

=head2 Context API

=over 4

=item C<CurrentContext()>

Return the name of the current macro context.

=item C<SwitchContext(context)>

Switch to given macro context.

=item C<CurrentContextForWindow(win)>

Get a macro context currently selected in a given window.

=item C<SwitchContextForWindow(win,context)>

Switch given window to given macro context.

=back

=head2 Treex::PML::FSFormat API

Here are described for working with L<Treex::PML::FSFormat|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/FSFormat.pm> objects. Beside these
macros, L<Treex::PML::FSFormat|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/FSFormat.pm> object methods can be used.

=over 4

=item C<FS()>

Return L<Treex::PML::FSFormat|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/FSFormat.pm> object associated with the current L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm>.

=item C<GetOrd(node)>

Return value of the special numbering FS attribute. This macro
actually returns the same value as
C<<< $node-E<gt>{FS()->order()} >>>

=item C<Attributes(node?,normal_fields?)>

If no node is given or the node is not associated with a type, return
a list of names of all attributes declared in the FS-file header or
Schema.

If node is associated with a type and the 2nd attribute is undef or
false, return list of paths to all its (possibly nested) atomic-value
attributes.  This is equivalent to

  $node->type->schema->attributes($node->type)

If node is associated with a type and the 2nd attribute is true,
return only first-level attribute names. This is equivalent to

  $node->type->get_normal_fields()

=item C<SubstituteFSHeader(declarations)>

Substitute a new FS header for current document. A list of valid FS
declarations must be passed to this function.

=item C<AppendFSHeader(declarations)>

Merge given FS header declarations with the present header
of the current document.

=item C<UndeclareAttributes(attribute,...)>

Remove declarations of given attributes from the FS header

=back

=head2 Treex::PML::Document I/O API

See also L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> object methods defined in the L<Treex::PML|http://search.cpan.org/dist/Treex-PML> module.

=over 4

=item C<ChangingFile(0|1)>

If no argument given the default is 1. If C<$FileChanged> is already
set to 1, does nothing. If C<$FileChanged> has not yet been
assigned or is zero, sets it to the given value. Returns the resulting
value. C<ChangingFile(1)> also resets C<$forceFileSaved> to 0.

=item C<CurrentFile()>

Return a L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> object representing the currently processed file.

=item C<Open(filename,flags)>

Open a given L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> in TrEd. Flags is an optional HASH reference
that may contain various flags internally used by TrEd.

=item C<OpenSecondaryFiles($fsfile)>

Open secondary files for a given L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> in TrEd.

=item C<ReloadCurrentFile()>

Close and reload current fsfile.

=item C<Resume($fsfile)>

Resume a previously open fsfile a given window in TrEd.

=item C<CloseFile(file?)>

Close a given L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm>.

=item C<CloseFileInWindow(window?)>

This macro is for TrEd only. It closes the L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> open in the given or
current window.  If the file is open in other windows, it is kept
among postponed files. If the file is modified, the user is asked to
save it.

=item C<Save()>

Save the current L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm>.

=item C<SaveAs({ option=>value,... })>

NOTE: This macro is currently only available in TrEd.

Save the current L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> under a new filename.
Returns 1 if the file was saved successfully.

Options:

=over 6

=item filename

The new-filename. If undefined, the usual "Save As..." dialog prompts
the user to select the output filename.

=item fsfile

operate on a given fsfile rather than the current one

=item backend

save using a given I/O backend

=item update_refs

update references from other files to this file.  Values can be:
'ask', 'all', an array of L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> objects; all
other values mean no update. Default is 'ask'.

=item update_filelist

update references from the current filelist to this file.  Values can
be: 'ask', 'current' (update only the current position);
any other value means no update. Default is 'ask'.

=back

=item C<GetOpenFiles()>

Return a list of L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> objects currently open in TrEd (including
postponed files).

=item C<Backends()>

Return a list of currently registered I/O backends.

=item C<AddBackend($classname,$before_backend)>

Register a new I/O backend. Note that the caller is responsible for
loading the required module (e.g. by calling L<Treex::PML::ImportBackends|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/ImportBackends.pm>());
If $before_backend is defined, the new backend is added before a given
backend. Otherwise the backend is added as a last backend.

=item C<RemoveBackend($classname)>

Remove (unregister) a given backend.

=item C<AddNewFileList($filelist)>

This macro is only available in TrEd.
Creates a new TrED filelist from a given C<Filelist> object.

=item C<RemoveFileList($filelist_object_or_name)>

This macro is only available in TrEd.  It disposes of a given filelist
(identified either by a C<Filelist> object or by name) by removing it
from TrEd's internal list of open filelists.

=item C<GetCurrentFileList($win?)>

This macro is only available in TrEd. It returns the current file-list
(a Filelist object) of this or a given window.

=item C<GetFileList($name)>

This macro is only available in TrEd.
Finds a filelist of a given name in TrEd's internal list open filelists
and returns the corresponding C<Filelist> object. Returns undef if not found.

=item C<AbsolutizeFileName($relative_path,$base_path)>

Converts a relative path to an absolute path.  The returned value is
an absolute path or URI, computed relative to a given base_path (file
name or URI). The function is able to strip TrEd position suffixes
(##N, ##N.M, and #ID) from the relative path and reattach them to the
returned absolute path.

=item C<SetCurrentFileList($name)>

This macro is only available in TrEd. Selects the filelist of a given
name for the current window.

=item C<SetCurrentFileListInWindow($name, $win)>

This macro is only available in TrEd. Selects the filelist of a given
name for the given window.

=item C<TrEdFileLists()>

This macro is only available in TrEd. It returns all registered
filelists.

=item C<GetFileSaveStatus()>

Return 1 if the document was modified since last save or reload, 0
otherwise.

=item C<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).

=item C<DefaultInputEncoding()>

Return's TrEd's/bTrEd's default IO encoding.

=item C<SetDefaultInputEncoding(encoding)>

Set TrEd's/bTrEd's default IO encoding.

=item C<FileName()>

Return current file's name.

=item C<FileMetaData(key,value?)>

Get or set meta data associated with the current L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm>.  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.

=item C<FileUserData(key,value?)>

Get or set user data associated with the current L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm>.  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.

=item C<FileAppData(key,value?)>

Get or set application specific data associated with the current
L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm>.  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.

=item C<GotoFileNo(n)>

Goto n'th file in the current filelist.
The number of the first file in filelist is 0.

=item C<LastFileNo($win?)>

Return the index of the last file in the current filelist.

=item C<CurrentFileNo($win?)>

Return the index of the current file in the current filelist.

=item C<SaveAndNextFile()>

Save the current file and open the next file in the current file-list.

=item C<NextFile()>

Goto next file in the file-list.

=item C<SaveAndPrevFile()>

Save the current file and open the previous file in the current
file-list.

=item C<PrevFile()>

Goto previous file in the file-list.

=back

=head2 General I/O macros

=over 4

=item C<ResourcePaths()>

    Return the current list of directories used to search for
    resources.

=item C<SetResourcePaths(dirs)>

Set given list of directories as a current resource path (discarding
the existing values of ResourcePath).

=item C<AddResourcePath(dirs)>

Add given directories to the end of the current resource path (to be
searched last).

=item C<AddToResourcePathAsFirst(dirs)>

Add given directories to the beginning of the current resource path
(to be searched first).

=item C<RemoveResourcePath(dir-paths)>

Remove given directories from the current resource path (directory
paths must exactly match those listed in the resource path).

=item C<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.

=item C<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.

=item C<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
cannot be located in this way and use_resources is true, return the
value of C<FindInResources(filename)>.

=item C<SlurpURI($filename_or_uri,$chomp?)>

Given a file name or URI of a resource, the macro returns the content
of the resource. In array context the return value is a list of lines,
in scalar context the value is a scalar. If the chomp flag is true,
chomp() is applied to the returned array or scalar.

=item C<writeln(string?,...)>

Print the arguments to standard output appending a new-line if missing.

=item C<stdout(string?,...)>

If called without arguments return current standard output filehandle.
Otherwise call print the arguments to standard output.

=item C<stderr(string?,...)>

If called without arguments return current standard error output
filehandle.  Otherwise call print the arguments to standard output.

=item C<tmpFileName()>

Returns a temporary filename..

=item C<DirPart($path)>

Returns directory part of a given path (including volume).

=item C<FilePart($path)>

Returns file-name part of a given path.

=item C<CallerPath()>

Return path of the perl module or macro-file that invoked this macro.

=item C<CallerDir($rel_path?)>

If called without an argument, returns the directory of the perl
module or macro-file that invoked this macro.

If a relative path is given as an argument, a respective absolute path
is computed based on the caller's directory and returned.

=item C<FindMacroDir($rel_dir)>

Searches for a given relative path in directories with user-defined
macros and returns an absolute path to the first directory that matches.

=back

=head2 Printing trees

=over 4

=item C<PrintDialog(-option =E<gt> value,...)>

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

=over 3

=item C<-command>

System command to send the output to (e.g. C<lpr> to print on the
default printer on UNIX platform).

=item C<-toFile>

If set to 1, the output is saved to a file specified in C<-filename>.

=item C<-filename>

Output filename.

=item C<-fileExtension>

Default output file extension.

=item C<-format>

One of PS, PDF, EPS, ImageMagick. Default is PS.

=item C<-imageMagickResolution>

This value is passed to the command C<convert> of the ImageMagick
toolkit as C<-density>. It specifies the horizontal and vertical
resolution in pixels of the image.

=item C<-noRotate>

Disable automatic landscape rotation of trees which are wider than
taller.

=item C<-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
L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> object and an integer position of the tree (starting from 0).

=item C<-fileInfo>

If true, print filename and tree number under each tree.

=item C<-colors>

Set to 1 for colour output.

=back

=item C<Print(-option =E<gt> value,...)>

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

=over 3

=item C<-range>

Lists trees to be printed (e.g. C<5,-3,9-12,15-> prints trees
5,1,2,3,9,10,11,12,15,16,...)

=item C<-to>

Possible values: file (print to file specified by C<-filename>),
(send output to ImageMagick convert, see C<-convert>),
pipe (send output to the standard input of command C<-command>),
string (return output as a string), object (return output as an object -
the exact type of the value depends on the output format).

=item C<-command>

System command to send the output to (usually default to C<lpr> on UNIX platform).

=item C<-convert>

Path to ImageMagick 'convert' command.

=item C<-filename>

Output filename (only when printing to file).

=item C<-format>

One of PS, PDF, EPS, ImageMagick. Default is PS.

=item C<-noRotate>

Disable automatic landscape rotation of trees which are wider than
taller.

=item C<-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
L<Treex::PML::Document|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm> object and an integer position of the tree (starting from 0).

=item C<-fileInfo>

If true, print filename and tree number under each tree.

=item C<-imageMagickResolution>

This value is passed to the command C<convert> of the ImageMagick
toolkit as C<-density>. It specifies the horizontal and vertical
resolution in pixels of the image.

=item C<-colors>

Set to 1 for colour output.

=item C<-hidden>

Set to 1 to print hidden nodes.

=item C<-psFontFile>

Specifies the PostScript font file to be used instead of the default
one.

=item C<--psFontAFMFile>

Specifies the PostScript ASCII metric font file to be used instead of
the default one.

=item C<-ttFont>

Specifies the TrueType font file to be used when printing via PDF.

=item C<-fontSize>

Font size.

=item C<-fmtWidth>

Page width.

=item  C<-fmtHeight>

Page height.

=item C<-hMargin>

The size of the left and right horizontal margins.

=item C<-vMargin>

The size of the top and bottom margins.

=item C<-maximize>

Expand small trees to fit the whole page size. (Shrinking is done
automatically).

=item C<-psMedia>

Specifies target given media size (used for PostScript and PDF).
Possible values:

User (dimensions specified in -fmtHeight and -fmtWidth), BBox
(bounding box of the tree with only -hMargin and -vMargin added),
Letter, LetterSmall, Legal, Statement, Tabloid, Ledger, Folio, Quarto,
Executive, A0, A1, A2, A3, A4, A4Small, A5, A6, A7, A8, A9, A10, B0,
B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, ISOB0, ISOB1, ISOB2, ISOB3,
ISOB4, ISOB5, ISOB6, ISOB7, ISOB8, ISOB9, ISOB10, C0, C1, C2, C3, C4,
C5, C6, C7, 7x9, 9x11, 9x12, 10x13, 10x14

=item C<-stylesheet>

Name of the stylesheet to use (defaults to the current stylesheet).

=item C<-toplevel>

Toplevel window (e.g. ToplevelFrame()) if you wish for graphical progress
indicator.

=back

=back

=head2 Other macros

=over 4

=item C<quit()>

This command acts just like a C<die> but without producing any error
message at all. It can be used to immediatelly stop execution of the
macro code and returning control to TrEd or btred (in which case btred
starts processing the next file) but does not propagate through
C<eval{}>, so it can also be trapped.

Note that hooks that my follow execution of the macro code (such as
file_close_hook or exit_hook in btred) are executed as if the macro
ended normally.

=back

=head2 Implementation of TredMacro::import

=over 4

=item C<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)  B<must> share: C<$libDir>,
C<$grp>, C<$root>, C<$this> C<$_NoSuchTree> C<$Redraw>,
C<$forceFileSaved>, C<$FileChanged>, C<$FileNotSaved>,
C<$NodeClipboard>.

=back

=head2 XPath extension (slow)

=over 4

=item C<SetupXPath(function-mapping...)>

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

This macro requires C<XML::XPath> module to be installed.  It adjusts
L<Treex::PML::Node|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm> API to match XPath model based on a given function mapping.  By
default, 'id' is defined to return nothing, 'pos' returns nodes
sentence-ordering position (or depth-first-ordering position if sentord
attribute is not defined), 'attributes' returs a hashref of node's
attributes (actually a L<Treex::PML::Node|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm> 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 L<Treex::PML::Node|http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm> methods.

Usage example:

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

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

=back

