Fundamental tree modification routines

From an internal point of view, all modifications to the TeXmacs edit tree are decomposed into atomic modifications of eight different types. In this section, we describe the Scheme interface to these fundamental modification routines. Even though it is usually more convenient to use higher level modification routines, as described in the next section, the fundamental tree modification routines may occasionally be useful as well.

It should be emphasized that the fundamental tree modification routines are not checked for their correctness. It is the responsability of the user to verify that the operations are valid and that they lead to a correct new edit tree. Although it is sometimes possible to leave the edit tree in a temporarily incorrect or “unsimplified” state (for instance, by allowing subtrees of the form (concat "")), this practice is not generally recommended, and may lead to severe bugs.

(tree-assign! var new-value)
(tree assignment)

On input, we have a Scheme variable var of type tree and new-value of type content. The macro replaces the tree by new-value and updates var accordingly. The new tree value of var is returned.

(tree-insert! var pos ins)
(insertion of new nodes or characters)

The first parameter var is a Scheme variable of type tree. If var is a compound tree, then ins should be a list u0,…,ul - 1 of new children of type content. In that case, the routine inserts u0,…,ul - 1 into the children of var, at position pos (see figure ?). If var is a string tree, then ins should be of string content type, and the string ins is inserted into var at position pos. The variable var is updated with the result of the insertion and the result is returned.

(tree-remove! var pos nr)
(removal of nodes or characters)

The first parameter var is a Scheme variable of type tree. If var is a compound tree, then nr of its children are removed, starting at position pos (see figure ?). If var is a string tree, then nr characters are removed, starting at position pos. The variable var is updated with the result of the removal and the result is returned.

⟶insert(t,i,u)
⟶remove(t,i,l)

Figure 1. Illustration of the operations (tree-insert! t i u) and (tree-remove! t i l). If u has length l, then we notice that (tree-remove! t i l) undos the insertion (tree-insert! t i u).

(tree-split! var pos at)
(split the children into two parts)

The first parameter var is a Scheme variable of type tree. The macro is used to split the child u of var at position pos into two parts. If u is a compound tree, then the first part consists of the first at children and the second part of the remaining ones. Both parts carry the same label as u and u is replaced by the two parts inside var (see figure ?). If u is string tree, then it is rather split into two strings at position at. The variable var is updated with the result of the split command and the result is returned.

(tree-join! var pos)
(join two adjacent nodes)

The first parameter var is a Scheme variable of type tree. This macro is used to join the child u of var at position pos with the child v at position pos+1. If u and v are trees, then they are removed from var and replaced by a single tree which has the same label as u and whose children are those of u, followed by the children of v (see figure ?). If u and v are strings, then they are replaced by their concatenation. The variable var is updated with the result of the join command and the result is returned.

⟶split(t,i,j)
⟶join(t,i)

Figure 2. Illustration of the operations (tree-split! t i j) and (tree-join! t i). Notice that (tree-join! t i) undos (tree-split! t i j).

(tree-assign-node! var lab)
(assign the label of a tree)

This macro replaces the label of a compound tree stored in a Scheme variable var by a new value lab. The result of the substitution is returned.

(tree-insert-node! var pos ins)
(insert the tree as a child of another one)

Given a Scheme variable var, containing a tree, and a content tree ins, this macro replaces var by ins, with var inserted as a new child of ins at position pos (see figure ?). The result of the insertion is returned.

(tree-remove-node! var pos)
(replace a tree by a child)

Given a Scheme variable var, containing a compound tree, this macro replaces var by its child at position pos (see figure ?). The value of this child is returned.

t ⟶insert - node(t,i,u)
⟶remove - node(t,i) ti

Figure 3. Illustration of the operations (tree-insert-node! t i u) and (tree-remove-node! t i). Notice that the second operation undos the first one.

Remark 1. Each of the macros tree-assign!, tree-insert!, etc. has a functional counterpart tree-assign, tree-insert, etc. The first parameter of these counterparts can be an arbitrary “l-value” and does not have to be a scheme variable. However, in the case when a Scheme variable is passed as the first parameter, these variants do not necessarily update its contents with the return value.

© 2005 Joris van der Hoeven
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".