 |
High level modification routines |  |
The routine tree-set and the corresponding macro tree-set! can be used as a higher level interface to the fundamental routines for modifying trees as described in the previous section. However, the it is still up to the user to verify that the resulting edit tree is still correct.
(tree-set which accessors* new-value)
This routine replaces the tree (tree-ref which accessors*) by a new content value new-value. Besides the fact that the routine tree-set supports additional accessors for which (see the description of tree-ref below), tree-set differs from tree-assign in this respect that tree-set tries to cleverly decompose the assignment into fundamental modification routines. The objective of this decomposition is to make a less intrusive modifications in the document, so as to preserve as many tree positions and cursor positions.
For instance, the operation (tree-set t t) is a no-operation for all trees t. A more complex operations like
(tree-set! t ‘(foo "Hop"
,(tree-ref t 2)))
is decomposed into the following fundamental modifications:
(tree-remove-node! t 2)
(tree-insert-node! t 1 '(foo "Hop"))
Like in the case tree-assign and tree-assign!, you should use
the macro tree-set! in order to update the value of which if
which is a
In its simplest form, this routine allows for the quick access of a subtree of which via a list of integers accessors. For instance, if which contains the tree (frac "a" (sqrt "b"))), then (tree-ref which 1 0) returns the tree "b".
In its general form, tree-ref relies on the routine select in order to compute the desired subtree. With which as in the above example, this makes it possible to retrieve the subtree (sqrt "b") using (tree-ref t 'frac). In the case when there are several matches, the first match is returned. For instance, if which contains the tree (frac (sqrt "a") (sqrt "b"))), then (tree-ref t 'frac) returns (sqrt "a").
In fact, the result of tree-ref is not necessarily a subtree of which: the select utility also accepts the accessors :up, :down, :next, :previous, etc. for navigating inside the edit tree starting with which. For instance, (tree-ref (cursor-tree) :up) returns the parent of the cursor tree. For more details, we refer to the documentation of select.
Besides the above routine for the direct modification of a subtree of the document, TeXmacs also provides several routines for inserting content at the current cursor position.
Insert the content what at the current cursor position. TeXmacs does some additional checking whether it is allowed to perform the insertion. For instance, it is disallowed to insert multi-paragraph content inside a mathematical formula. Whenever the user attempts to make an invalid insertion, then insert is equivalent to a no-operation.
This routine may be used to insert a valid tag with label lab. As many empty arguments as necessary are inserted in order to make the tag valid. Similarly, if lab is a multi-paragraph tag, then the necessary operations are performed to put the tag in a separate paragraph.
make-with, make-return, etc.