tred_def documentation

Table of contents


TredMacro

ToC

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

Global variables

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

Tree editing API

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

Helper macros for attributes with list or alternatives of values

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.

General-purpose list functions

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

Create/modify keyboard shortcuts

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

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.

key

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

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.

changing_file

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 API

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.

Context API

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.

Treex::PML::FSFormat API

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

Treex::PML::Document I/O API

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:

filename

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

fsfile

operate on a given fsfile rather than the current one

backend

save using a given I/O backend

update_refs

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

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.

General I/O macros

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.

Printing trees

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.

Other macros

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.

Implementation of TredMacro::import

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.

XPath extension (slow)

SetupXPath(function-mapping...)

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

This macro requires XML::XPath module to be installed. It 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:

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

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