The TeXmacs editing model

Routines for editing documents are usually based on one or several of the following ingredients:

1. Identification of the document fragments which have to be edited.
2. Modification of one or several document fragments.
3. Moving the cursor to a new place.

Before going into the precise API which allows you to carry out these tasks, let us first describe the fundamental underlying data types, and go through an example.

Document fragments

All TeXmacs documents or document fragments can be thought of as trees, as explained in more detail in the chapter about the TeXmacs document format. For instance, the mathematical formula

corresponds to the tree

Trees which are part of a document which is effectively being edited are said to be active, and they are implemented using the Scheme type tree.

Besides this representation format, which is preferred when editing document fragments, TeXmacs also allows you to represent passive document fragments by Scheme trees. This alternative representation, which corresponds to the Scheme type stree, is more convenient when writing routines for processing documents (such as conversions to another format). Finally, TeXmacs provides a hybrid representation, which corresponds to the Scheme type content. The content type (corresponding to the prefix tm-, for simplicity) is typically used for writing abstract utility routines for trees, which can then be applied indistinctly to objects of type tree or stree.

One major advantage of active trees (of type tree) is that they are aware of their own location in the document. As a consequence, TeXmacs provides editing routines which allow you to modify the document simply by assigning a tree to a different value. For instance, assume that the Scheme variable t contains the subscript 1 in formula (?). Then the instruction

will simultaneously change the subscript into a 2 and update the Scheme variable t. Another nicety is that the value of t is persistent during changes of other parts of the document. For instance, if we change the a's into b's in the formula (?), then t keeps its value and its location. Of course, the location of t may be lost when t or one of its parents is modified. Nevertheless, the modification routines are designed in such a way that we try hard to remember locations. For instance, when insert “a₀ + ” in front of the formula (?) using the routine tree-insert!, then t keeps its value and its location, even though one of its ancestors was altered.

Some further precisions and terminology will be useful. First of all, we have seen a distinction between active and passive trees, according to whether a tree is part of a document or not. Secondly, TeXmacs both supports native trees (of type tree), which are implemented in C++, and scheme trees (of type stree), which have a more familiar Scheme syntax. Finally, hybrid trees unify native and scheme trees. Formally speaking, a hybrid tree is either a string, a native tree or a list whose first element is a symbol and whose other elements are again hybrid trees. We notice that active trees are necessarily native, but native trees may both be active or passive. Furthermore, certain descendants of an inactive tree may be active, but we never have the contrary.

Positions inside document fragments

The main way to address positions inside a tree is via a list of positive integers, called a path, and corresponding to the Scheme type path. For instance, assume that x corresponds to the expression (?). Then the subscript 1 is identified uniquely by the path (1 0). Similarly the cursor position just behind the subscript 1 corresponds to the path (1 0 1). More generally, if p is a path to a string leaf, then the path (rcons p i) corresponds to the cursor position just behind the i-th character in the string (we notice that rcons is used to append a new element at the end of a list). If p is a path to a non-string subtree, then (rcons p 0) and (rcons p 1) correspond to the cursor positions before and behind this subtree.

It should be noticed that paths do not necessarily correspond to valid subtrees or cursor positions. Clearly, some of the elements in the path may be “out of range”. However, certain a priori possible cursor positions may correspond to invisible parts of the document (like a cursor position inside a folded argument or an attribute of with). Moreover, two possible cursor positions may actually coincide, like the paths (0) and (0 0) inside the expression (?). In this example, only the second cursor path is valid. Usually, the validity of a cursor path may be quickly detected using DRD (Data Relation Definition) information, which is determined from the style file. In execeptional cases, the validity may only be available after typesetting the document.

It should also be noticed that all active trees are a subtree of the global TeXmacs edit tree or root tree, which can be retrieved using (root-tree). The routines tree->path and path->tree can be used in order to get the location of an active tree and the active tree at a given location.

A simple way to address subtrees of a tree in a more persistent way is using object of type tree, i.e. by considering the subtrees themselves. The persistent analogue of a cursor path is a persistent position, which corresponds to an object of Scheme type position. One particularity of persitent positions is that, even when a tree into which they point is removed, they keep indicating a valid close position in the remaining document. For instance, assume that pos stands for the cursor position (1 0 1) in the expression (?). If we remove a₁ + ⋯ + , then the tree corresponding to the remaining expression a_n is given by

and the position associated to pos becomes (0 0). TeXmacs provides the routines position-new, position-delete, position-set and position-get to create, delete, set and get persistent cursor positions.

Semantic navigation and further utilities

Because accessing subtrees using paths may become quite cumbersome, TeXmacs provides some additional functionality to simplify this task. As a general rule, the routines select and match? may be used to select all subtrees of a given tree which match a certain pattern. For instance, if x corresponds to the expression (?), then

returns a list with the two subscripts 1 and n. In fact, select may also be used in order to navigate through a tree. For instance, if t corresponds to the subscript 1 in (?), then

returns the list with one element “ + ⋯ + a”. The routine select is implicitly called by many routines which operate on trees. For instance, with t as above,

directly returns the tree “ + ⋯ + a”.

Besides simpler access to subtrees of a tree or other “close trees”, TeXmacs also provides several other useful mechanisms for writing editing routines. For instance, the routine tree-innermost and the macro with-innermost may be used to retrieve the innermost supertree of a certain type at the current cursor position. Since many editing routines operate at the current cursor position, two other useful macros are with-cursor and cursor-after, which allow you to perform some operations at a temporarily distinct cursor position resp. to compute the cursor position after some operations, without actually changing the current cursor position.

A worked example

In order to illustrate the TeXmacs API for editing documents on a simple example, assume that we wish to write a function swap-numerator-denominator which allows us to swap the numerator and the denominator of the innermost fraction at the current cursor position.

The innermost fraction may simply be retrieved using the macro with-innermost. Together with the routine tree-set! for modifying a tree, this yields a first simple implementation:

It should be noticed that the macro with-innermost ignores its body whenever no innermost fraction is found.

The above implementation has the disadvantage that we loose the current cursor position inside the numerator or denominator (whereever we were). The following refined implementation allows us to remain at the “same position” modulo the exchange numerator/denominator:

Here we used the routines tree-cursor-path and tree-go-to, which allow us to manipulate the cursor position relative to a given tree. As the icing on the cake, we may make our routine available through the mechanism of structured variants: