TredMacro (tred.def) - implements the public API for TrEd/bTred macros
$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 and continuing processing at that node in bTrEd.
$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.
$FileChanged
(alias $FileNotSaved
- still valid but obsolete)See also 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 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).
$libDir
This variable contains a path to TrEd library directory.
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
$parent->test_child_type($node)
to be sure that type declarations permit
the node as a child node of the new parent.
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
$parent->test_child_type($node)
to be sure that type declarations permit
the node as a child node of the new parent.
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
$parent->test_child_type($node)
to be sure that type declarations permit
the node as a child node of the new parent.
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
$parent->test_child_type($node)
to be sure that type declarations permit
the node as a child node of the new parent.
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
$parent->test_child_type($node)
to be sure that type declarations permit
the node as a child node of the new parent.
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
$parent->test_child_type($node)
to be sure that type declarations permit
the node as a child node of the new parent.
CloneSubtree(node)
Return an identical copy (except that only declared attributes are preserved) of the given subtree.
CopyNode(node)
Return an identical copy (except that only declared attributes are preserved) of the given node. The input node must belong to the current file.
CutNode(node)
Cut the node's subtree off the tree and return it. By cuttin a subtree we mean disconnecting it from the rest of the tree. Use PasteNode to attach it to some node again.
NewTree()
Create a new tree before the current tree. The new tree consists of exactly one node. This node is activated and a reference to its Treex::PML::Node 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 Treex::PML::Node object is returned.
NewRBrother(node)
Create a new brother of the given node and recalculate the special FS numbering attribute values in the whole tree so that the new node is the first right sibling of the given node.
If no node is given, this function operates on $this
and resets
$this
to the newly created node. If some node is given the value
of $this
is preserved.
NewLBrother(node)
Create a new brother of the given node and recalculate the special FS numbering attribute values in the whole tree so that the new node is the first left sibling of the given node.
If no node is given, this function operates on $this
and resets
$this
to the newly created node. If some node is given the value
of $this
is preserved.
NewSon(parent)
Create a new child of the given parent node and recalculate the special FS numbering attribute values in the whole tree so that the new node is the first node right to the given parent.
If no parent node is given, this function operates on $this
and
resets $this
to the newly created node. If a parent node is
given the value of $this
is preserved.
NewParent(node)
Create a node between given node and its parent and recalculate the special FS numbering attribute values in the whole tree so that the new node is the first node left to the given node.
If no node is given, this function operates on $this
and
resets $this
to the newly created node. If a parent node is
given the value of $this
is preserved.
DeleteThisNode()
Delete the current ($this
) node and recalculate the special FS
numbering attribute values in the whole tree so that there is no gap
in the numbering. If the current node is not a leaf or if it is the
root of the current tree, this macro does nothing.
DeleteLeafNode(node)
Delete a leaf node and recalculate the special FS numbering attribute values in the whole tree so that there is no gap in the numbering. If a given node is not a leaf, this macro does nothing.
DeleteSubtree(node)
Deletes a whole node's subtree and recalculate the special FS numbering attribute values in the whole tree so that there is no gap in the numbering.
RemoveTree(n?,fsfile?)
Removes n-th tree from a given Treex::PML::Document (trees are numbered starting from 0). If no Treex::PML::Document 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 Treex::PML::Document, use $tree->destroy method on the returned tree to prevent a memory leak.
DestroyTree(n?,fsfile?)
Like RemoveTree but immediatelly destroys the removed tree. Returns 1 on success.
DetermineNodeType($node)
For trees with Treex::PML::Schema-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.
CopyValues()
Copy the values of all the attributes except the special FS numbering attribute of the current node to a global hash variable named %ValuesClipboard.
PasteValues()
Replace existing values of the current node's attributes by all values stored in the global hash variable named %ValuesClipboard. The function does not perform any node-type validity checks.
PlainNewSon(parent)
Add a new child node to the given parent and make it the current
node (by setting $this
to point to it).
PlainDeleteNode()
Delete the given node. The node must be a leaf of the tree (may not have any children) and must have a parent (may not be the root of the tree).
PlainDeleteSubtree(node)
Cut a the given node's subtree and destroy all its nodes. This macro does not recalculate ordering attributes.
NormalizeOrds(listref)
Adjusts the special FS numbering attribute of every node of the list referenced by the listref argument so that the value for the attribute corresponds to the order of the node in the list 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.
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 accordingly.
ShiftNodeLeft(node)
Shift the current node in the tree to the right by modifying the tree structure and value of the special FS numbering attribute appropriately.
GetNodesExceptSubtree(node)
Returns the reference to an array containing the whole tree except the nodes strictly in the subtrees of nodes given in an array referenced by the parameter. (The returned array does contain the nodes passed in the parameter.)
MoveNode(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.
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.)
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 Treex::PML::Node since otherwise you might result with a copy of the complete tree, schema, etc.
IsList(value)
Check that a given value is a list, i.e. Treex::PML::List object.
IsAlt(value)
Check that a given value is an alternative, i.e. Treex::PML::Alt object.
IsSeq(value)
Check that a given value is a sequence, i.e. Treex::PML::Seq object.
List(value,value,...)
Return a new list (Treex::PML::List object) populated with given values.
Alt(value,value,...)
Return a new alternative (Treex::PML::Alt object) populated with given values.
AltV(value)
If the value is an alternative (i.e. a Treex::PML::Alt object), return all its values. Otherwise return value.
ListV(value)
If the value is a list (i.e. a Treex::PML::List object), return all its values. Otherwise return empty (Perl) list.
SeqV(value)
If the value is a sequence (i.e. a Treex::PML::Seq object), return all its elements (Treex::PML::Seq::Element objects). Otherwise return empty (Perl) list.
AddToAlt(node,attr,value,value...)
Add given values as alternatives to the current value of
$node->{$attr}
. If only one value is given and $node->{$attr}
is
empty or same as value, the given value is simply assigned to it. If
$node->{$attr}
is a Treex::PML::Alt object, the new values are simply added
to it. Otherwise, if $node->{$attr}
is a simple value, $node->{$attr}
is set to a new Treex::PML::Alt object containing the original value as
well as the given values.
AddToList(node,attr,value,value,...)
Add values to a given attribute. If $node->attr($attr)
is not defined or
empty, a new Treex::PML::List containing given values is created. If
$node->attr($attr)
is a Treex::PML::List object, given values are simply added
to it. Error is issued if $node->attr($attr)
is defined, non-empty, yet not
a Treex::PML::List object.
AddToListUniq(node,attr,value,value,...)
Add values to a given attribute, unless already present among the
current values. If $node->attr($attr)
is not defined or empty,
a new Treex::PML::List containing given values is created. If
$node->attr($attr)
is a Treex::PML::List object, given values are
simply added to it. Error is issued if $node->attr($attr)
is
defined, non-empty, yet not a Treex::PML::List object.
AddToSeq(node, attr, name =
value, name => value,...)> or AddToSeq(node, attr, element, ...)
Add elements to a given sequence attribute. If $node->attr($attr)
is not defined or
empty, a new Treex::PML::Seq object containing given name-value pairs (Treex::PML::Seq::Element objects) is created. If
$node->attr($attr)
is a Treex::PML::Seq object, given elements are simply added
to it. Error is issued if $node->attr($attr)
is defined, non-empty, yet not
a Treex::PML::Seq object.
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.
ListIntersect(array-ref,array-ref,...)
Compute intersection of given lists. In scalar context returns an array-ref, in list context returns a list. All duplicities are removed.
ListSubtract(array-ref, array-ref)
Return elements occuring in the first list but not in the second list. In scalar context returns a Treex::PML::List object (array-ref), in list context returns a list. All duplicities are removed.
ListUnion(array-ref, array-ref, ...)
Return union of given lists. In scalar context returns an array-ref, in list context returns a Treex::PML::List object (array-ref). All duplicities are removed.
ListRegroupElements(array-ref, array-ref, ...)
This is rotate-matrix like operation. The input is a list of rows (array-refs each representing a row in a matrix); the output is a list of columns in the matrix (a list of array-refs, each representing a column in the matrix).
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):
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.
a keyboard binding for the macro (e.g. 'Ctrl+a'); if not given, no keyboard binding is created.
a label to be used for a menu-item created for the macro. If not given, no menu-item is created for the macro.
if the key changing_file
exists in the bind-options hash and its
value is value, a call to the macro ChangignFile(value)
is made immediatelly after each invocation of the macro via this
binding.
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).
OverrideBuiltinBinding(context,key-binding, binding_spec )
(TrEd only). Get or modify default TrEd's keybinding.
The 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
$root
or $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 MacroCallback
macro for details. The macro is called with the
same arguments (appended to a list of arguments provided in
MacroCallback
). The macro can use all standard macro functions and
variables.
If the context
argument is a name of a binding context, the binding
is only used in the specific context. If context
is '*'
, 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 left/right
with 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']);
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).
STYLESHEET_FROM_FILE()
This function returns a symbolic name for a virtual stylesheet that is constructed from the patterns and hint specified in the currently displayed file.
SetStylesheetPatterns(patterns,stylesheet,create)
Set TrEd's display patterns for a given stylesheet. If stylesheet is undefined, then the stylesheet currently selected for the active view is used. The patterns argument should either be a string or an array reference. If it is a string, then it should provide all the patterns, each pattern starting on a new line (but possibly spanning across several lines) which starts with a pattern prefix of the form "something:", where "something" is hint for the hint pattern, or "node" for the node pattern, etc.
Patterns can also be provided as an array reference containing three elements: the first one being a hint text, the second the context pattern (regular expression), and the second one an array reference whose each element is the text of an individual pattern.
The create flag can be set to 1 in order to create a new stylesheet in case that no stylesheet with the given exists.
This function returns 1 if success, 0 if failed (i.e. when create is not set and a given stylesheet is not found).
DeleteStylesheet(stylesheet)
Delete given stylesheet. All windows using that stylesheet are switched to the pattern and hint specified in the respective files they display.
SaveStylesheet(name)
Save given TrEd's stylesheet (to ~/.tred.d/stylesheets/name).
SaveStylesheets()
Save all TrEd's stylesheets (to ~/.tred.d/stylesheets/).
ReloadStylesheet(name,dir?)
Reload a given stylesheet. If no dir is specified, the default path "~/.tred.d/stylesheets/" is used.
ReloadStylesheets(dir?)
Reload stylesheets from a given file or directory. If no filename is specified, the default path "~/.tred.d/stylesheets/" is used.
GetStylesheetPatterns(stylesheet)
For a given stylesheet, return it's patterns. In a scalar context, returns a string consisting of all patterns, including the hint. In the array context returns three scalars: the first one containing the text of the hint pattern, the second the context pattern (regexp) and the other a reference to a list containing the stylesheet patterns. Returns empty list in case of failure.
GetPatternsByPrefix(prefix,stylesheet?)
Return all patterns of a given stylesheet starting with a given prefix. If no stylesheet name is given, a current stylesheet is used.
StylesheetExists(stylesheet)
Returns true if stylesheet with a given name exists.
Stylesheets()
Returns a list of TrEd's stylesheet names.
GetCurrentStylesheet()
Returns name of the stylesheet currently selected for the active window.
SetCurrentStylesheet(stylesheet_name)
Set stylesheet for the active window.
GetSpecialPattern(prefix)
- OBSOLETE!!This macro is obsoleted by GetPatternsByPrefix.
SetDisplayAttrs(pattern,...)
- OBSOLETE!!Setup given patterns as a stylesheet of the currently displayed Treex::PML::Document. This does not include a hint pattern.
SetBalloonPattern(string,...)
- OBSOLETE!!Use given strings as a hint:
pattern for
the currently displayed Treex::PML::Document.
GetDisplayAttrs()
- OBSOLETE!!Get patterns of the currently displayed Treex::PML::Document's stylesheet, except
for a hint:
pattern.
GetBalloonPattern()
- OBSOLETE!!Get a hint:
pattern of the currently displayed
Treex::PML::Document's stylesheet.
CustomColor(name,new-value?)
Get or set user defined custom color.
UserConf(name,new-value?)
Get or set value of a user defined configuration option.
AddStyle(styles,object,key => value,...)
Auxiliary funcion: add styles for an object to a given style-hash (can be used e.g. from node_style_hook).
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.
CurrentContext()
Return the name of the current macro context.
SwitchContext(context)
Switch to given macro context.
CurrentContextForWindow(win)
Get a macro context currently selected in a given window.
SwitchContextForWindow(win,context)
Switch given window to given macro context.
Here are described for working with Treex::PML::FSFormat objects. Beside these macros, Treex::PML::FSFormat object methods can be used.
FS()
Return Treex::PML::FSFormat object associated with the current Treex::PML::Document.
GetOrd(node)
Return value of the special numbering FS attribute. This macro
actually returns the same value as
$node->{FS()->order()}
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()
SubstituteFSHeader(declarations)
Substitute a new FS header for current document. A list of valid FS declarations must be passed to this function.
AppendFSHeader(declarations)
Merge given FS header declarations with the present header of the current document.
UndeclareAttributes(attribute,...)
Remove declarations of given attributes from the FS header
See also Treex::PML::Document object methods defined in the Treex::PML module.
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.
CurrentFile()
Return a Treex::PML::Document object representing the currently processed file.
Open(filename,flags)
Open a given Treex::PML::Document in TrEd. Flags is an optional HASH reference that may contain various flags internally used by TrEd.
OpenSecondaryFiles($fsfile)
Open secondary files for a given Treex::PML::Document in TrEd.
ReloadCurrentFile()
Close and reload current fsfile.
Resume($fsfile)
Resume a previously open fsfile a given window in TrEd.
CloseFile(file?)
Close a given Treex::PML::Document.
CloseFileInWindow(window?)
This macro is for TrEd only. It closes the Treex::PML::Document 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.
Save()
Save the current Treex::PML::Document.
SaveAs({ option=
value,... })>NOTE: This macro is currently only available in TrEd.
Save the current Treex::PML::Document under a new filename. Returns 1 if the file was saved successfully.
Options:
The new-filename. If undefined, the usual "Save As..." dialog prompts the user to select the output filename.
operate on a given fsfile rather than the current one
save using a given I/O backend
update references from other files to this file. Values can be: 'ask', 'all', an array of Treex::PML::Document objects; all other values mean no update. Default is 'ask'.
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'.
GetOpenFiles()
Return a list of Treex::PML::Document objects currently open in TrEd (including postponed files).
Backends()
Return a list of currently registered I/O backends.
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 Treex::PML::ImportBackends()); If $before_backend is defined, the new backend is added before a given backend. Otherwise the backend is added as a last backend.
RemoveBackend($classname)
Remove (unregister) a given backend.
AddNewFileList($filelist)
This macro is only available in TrEd.
Creates a new TrED filelist from a given Filelist
object.
RemoveFileList($filelist_object_or_name)
This macro is only available in TrEd. It disposes of a given filelist
(identified either by a Filelist
object or by name) by removing it
from TrEd's internal list of open filelists.
GetCurrentFileList($win?)
This macro is only available in TrEd. It returns the current file-list (a Filelist object) of this or a given window.
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 Filelist
object. Returns undef if not found.
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.
SetCurrentFileList($name)
This macro is only available in TrEd. Selects the filelist of a given name for the current window.
SetCurrentFileListInWindow($name, $win)
This macro is only available in TrEd. Selects the filelist of a given name for the given window.
TrEdFileLists()
This macro is only available in TrEd. It returns all registered filelists.
GetFileSaveStatus()
Return 1 if the document was modified since last save or reload, 0 otherwise.
SetFileSaveStatus()
Use SetFileSaveStatus(1) to declare that some modification was made to the file. Use SetFileSaveStatus(0) after the file was saved from a macro (and TrEd/bTrEd would not notice that).
DefaultInputEncoding()
Return's TrEd's/bTrEd's default IO encoding.
SetDefaultInputEncoding(encoding)
Set TrEd's/bTrEd's default IO encoding.
FileName()
Return current file's name.
FileMetaData(key,value?)
Get or set meta data associated with the current Treex::PML::Document. Key is the meta data key. If value is omitted, current value associated with the key is returned. Otherwise, the given value is associated with the key, overwritting any previous value.
FileUserData(key,value?)
Get or set user data associated with the current Treex::PML::Document. Key is the user data key. If value is omitted, current value associated with the key is returned. Otherwise, the given value is associated with the key, overwritting any previous value.
FileAppData(key,value?)
Get or set application specific data associated with the current Treex::PML::Document. Key is the appData key. If value is omitted, current value associated with the key is returned. Otherwise, the given value is associated with the key, overwritting any previous value.
GotoFileNo(n)
Goto n'th file in the current filelist. The number of the first file in filelist is 0.
LastFileNo($win?)
Return the index of the last file in the current filelist.
CurrentFileNo($win?)
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.
ResourcePaths()
Return the current list of directories used to search for resources.
SetResourcePaths(dirs)
Set given list of directories as a current resource path (discarding the existing values of ResourcePath).
AddResourcePath(dirs)
Add given directories to the end of the current resource path (to be searched last).
AddToResourcePathAsFirst(dirs)
Add given directories to the beginning of the current resource path (to be searched first).
RemoveResourcePath(dir-paths)
Remove given directories from the current resource path (directory paths must exactly match those listed in the resource path).
FindDirInResources(dirname)
If a given dirname is a relative path of a directory found in TrEd's resource directory, return an absolute path for the resource. Otherwise return dirname.
FindInResources(filename)
If a given filename is a relative path of a file found in TrEd's resource directory, return an absolute path for the resource. Otherwise return filename.
ResolvePath(ref-filename,filename,use_resources?)
If a given filename is a relative path, try to find the file in the
same directory as ref-filename. In case of success, return a path
based on the directory part of ref-filename and filename. If the file
cannot be located in this way and use_resources is true, return the
value of FindInResources(filename)
.
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.
writeln(string?,...)
Print the arguments to standard output appending a new-line if missing.
stdout(string?,...)
If called without arguments return current standard output filehandle. Otherwise call print the arguments to standard output.
stderr(string?,...)
If called without arguments return current standard error output filehandle. Otherwise call print the arguments to standard output.
tmpFileName()
Returns a temporary filename..
DirPart($path)
Returns directory part of a given path (including volume).
FilePart($path)
Returns file-name part of a given path.
CallerPath()
Return path of the perl module or macro-file that invoked this macro.
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.
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.
PrintDialog(-option => value,...)
Display TrEd's standard print dialog. Possible options providing substitutes for the default values in the print dialog are:
-command
System command to send the output to (e.g. lpr
to print on the
default printer on UNIX platform).
-toFile
If set to 1, the output is saved to a file specified in -filename
.
-filename
Output filename.
-fileExtension
Default output file extension.
-format
One of PS, PDF, EPS, ImageMagick. Default is PS.
-imageMagickResolution
This value is passed to the command convert
of the ImageMagick
toolkit as -density
. It specifies the horizontal and vertical
resolution in pixels of the image.
-noRotate
Disable automatic landscape rotation of trees which are wider than taller.
-sentenceInfo
If set to 1, this command prints also the text associated with the tree. Instead of 0 or 1, an CODE reference (subroutine) may be passed in this parameter. This CODE is then evaluated for every tree to produce the desired text. The CODE obtains two arguments: the current Treex::PML::Document object and an integer position of the tree (starting from 0).
-fileInfo
If true, print filename and tree number under each tree.
-colors
Set to 1 for colour output.
Print(-option => value,...)
Print trees given from current file according to given printing options:
-range
Lists trees to be printed (e.g. 5,-3,9-12,15-
prints trees
5,1,2,3,9,10,11,12,15,16,...)
-to
Possible values: file (print to file specified by -filename
),
(send output to ImageMagick convert, see -convert
),
pipe (send output to the standard input of command -command
),
string (return output as a string), object (return output as an object -
the exact type of the value depends on the output format).
-command
System command to send the output to (usually default to lpr
on UNIX platform).
-convert
Path to ImageMagick 'convert' command.
-filename
Output filename (only when printing to file).
-format
One of PS, PDF, EPS, ImageMagick. Default is PS.
-noRotate
Disable automatic landscape rotation of trees which are wider than taller.
-sentenceInfo
If set to 1, this command prints also the text associated with the tree. Instead of 0 or 1, a CODE reference (subroutine) may be passed in this parameter. This CODE is then evaluated for every tree to produce the desired text. The CODE obtains two arguments: the current Treex::PML::Document object and an integer position of the tree (starting from 0).
-fileInfo
If true, print filename and tree number under each tree.
-imageMagickResolution
This value is passed to the command convert
of the ImageMagick
toolkit as -density
. It specifies the horizontal and vertical
resolution in pixels of the image.
-colors
Set to 1 for colour output.
-hidden
Set to 1 to print hidden nodes.
-psFontFile
Specifies the PostScript font file to be used instead of the default one.
--psFontAFMFile
Specifies the PostScript ASCII metric font file to be used instead of the default one.
-ttFont
Specifies the TrueType font file to be used when printing via PDF.
-fontSize
Font size.
-fmtWidth
Page width.
-fmtHeight
Page height.
-hMargin
The size of the left and right horizontal margins.
-vMargin
The size of the top and bottom margins.
-maximize
Expand small trees to fit the whole page size. (Shrinking is done automatically).
-psMedia
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
-stylesheet
Name of the stylesheet to use (defaults to the current stylesheet).
-toplevel
Toplevel window (e.g. ToplevelFrame()) if you wish for graphical progress indicator.
quit()
This command acts just like a 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
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.
import(names?)
If specified without parameter, exports every symbol to the caller
package (except for symbols already (re)defined in the caller
package). If parameters are given, exports only names specified by
the parameters and the following few variables that every package
derived from TredMacro (e.g. a context) must share: $libDir
,
$grp
, $root
, $this
$_NoSuchTree
$Redraw
,
$forceFileSaved
, $FileChanged
, $FileNotSaved
,
$NodeClipboard
.
SetupXPath(function-mapping...)
This macro requires XML::XPath
module to be installed. It adjusts
Treex::PML::Node 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 Treex::PML::Node 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 Treex::PML::Node methods.
Usage example:
foreach ($node->findnodes(q{//ACT/PAT[starts-with(@tag,"N") or .="ano"]})) {
# process matching nodes
}