### 14.5 Accessing an utterance ¶

There are a number of standard functions that allow one to access parts of an utterance and traverse through it.

Functions exist in Lisp (and of course C++) for accessing an utterance. The Lisp access functions are

‘`(utt.relationnames UTT)`’

  returns a list of the names of the relations currently created in `UTT`.

‘`(utt.relation.items UTT RELATIONNAME)`’

  returns a list of all items in `RELATIONNAME` in `UTT`. This is nil if no relation of that name exists. Note for tree relation will give the items in pre-order.

‘`(utt.relation_tree UTT RELATIONNAME)`’

  A Lisp tree presentation of the items `RELATIONNAME` in `UTT`. The Lisp bracketing reflects the tree structure in the relation.

‘`(utt.relation.leafs UTT RELATIONNAME)`’

  A list of all the leafs of the items in `RELATIONNAME` in `UTT`. Leafs are defined as those items with no daughters within that relation. For simple list relations `utt.relation.leafs` and `utt.relation.items` will return the same thing.

‘`(utt.relation.first UTT RELATIONNAME)`’

  returns the first item in `RELATIONNAME`. Returns `nil` if this relation contains no items

‘`(utt.relation.last UTT RELATIONNAME)`’

  returns the last (the most next) item in `RELATIONNAME`. Returns `nil` if this relation contains no items

‘`(item.feat ITEM FEATNAME)`’

  returns the value of feature `FEATNAME` in `ITEM`. `FEATNAME` may be a feature name, feature function name, or pathname (see below). allowing reference to other parts of the utterance this item is in.

‘`(item.features ITEM)`’

  Returns an assoc list of feature-value pairs of all local features on this item.

‘`(item.name ITEM)`’

  Returns the name of this `ITEM`. This could also be accessed as `(item.feat ITEM 'name)`.

‘`(item.set_name ITEM NEWNAME)`’

  Sets name on `ITEM` to be `NEWNAME`. This is equivalent to `(item.set_feat ITEM 'name NEWNAME)`

‘`(item.set_feat ITEM FEATNAME FEATVALUE)`’

  set the value of `FEATNAME` to `FEATVALUE` in `ITEM`. `FEATNAME` should be a simple name and not refer to next, previous or other relations via links.

‘`(item.relation ITEM RELATIONNAME)`’

  Return the item as viewed from `RELATIONNAME`, or `nil` if `ITEM` is not in that relation.

‘`(item.relationnames ITEM)`’

  Return a list of relation names that this item is in.

‘`(item.relationname ITEM)`’

  Return the relation name that this item is currently being viewed as.

‘`(item.next ITEM)`’

  Return the next item in `ITEM`’s current relation, or `nil` if there is no next.

‘`(item.prev ITEM)`’

  Return the previous item in `ITEM`’s current relation, or `nil` if there is no previous.

‘`(item.parent ITEM)`’

  Return the parent of `ITEM` in `ITEM`’s current relation, or `nil` if there is no parent.

‘`(item.daughter1 ITEM)`’

  Return the first daughter of `ITEM` in `ITEM`’s current relation, or `nil` if there are no daughters.

‘`(item.daughter2 ITEM)`’

  Return the second daughter of `ITEM` in `ITEM`’s current relation, or `nil` if there is no second daughter.

‘`(item.daughtern ITEM)`’

  Return the last daughter of `ITEM` in `ITEM`’s current relation, or `nil` if there are no daughters.

‘`(item.leafs ITEM)`’

  Return a list of all lefs items (those with no daughters) dominated by this item.

‘`(item.next_leaf ITEM)`’

  Find the next item in this relation that has no daughters. Note this may traverse up the tree from this point to search for such an item.

As from 1.2 the utterance structure may be fully manipulated from Scheme. Relations and items may be created and deleted, as easily as they can in C++;

‘`(utt.relation.present UTT RELATIONNAME)`’

  returns `t` if relation named `RELATIONNAME` is present, `nil` otherwise.

‘`(utt.relation.create UTT RELATIONNAME)`’

  Creates a new relation called `RELATIONNAME`. If this relation already exists it is deleted first and items in the relation are derefenced from it (deleting the items if they are no longer referenced by any relation). Thus create relation guarantees an empty relation.

‘`(utt.relation.delete UTT RELATIONNAME)`’

  Deletes the relation called `RELATIONNAME` in utt. All items in that relation are derefenced from the relation and if they are no longer in any relation the items themselves are deleted.

‘`(utt.relation.append UTT RELATIONNAME ITEM)`’

  Append `ITEM` to end of relation named `RELATIONNAME` in `UTT`. Returns `nil` if there is not relation named `RELATIONNAME` in `UTT` otherwise returns the item appended. This new item becomes the last in the top list. `ITEM` item may be an item itself (in this or another relation) or a LISP description of an item, which consist of a list containing a name and a set of feature vale pairs. It `ITEM` is `nil` or inspecified an new empty item is added. If `ITEM` is already in this relation it is dereferenced from its current position (and an empty item re-inserted).

‘`(item.insert ITEM1 ITEM2 DIRECTION)`’

  Insert `ITEM2` into `ITEM1`’s relation in the direction specified by `DIRECTION`. `DIRECTION` may take the value, `before`, `after`, `above` and `below`. If unspecified, `after` is assumed. Note it is not recommended to insert above and below and the functions `item.insert_parent` and `item.append_daughter` should normally be used for tree building. Inserting using `before` and `after` within daughters is perfectly safe.

‘`(item.append_daughter PARENT DAUGHTER)`’

  Append `DAUGHTER`, an item or a description of an item to the item `PARENT` in the `PARENT`’s relation.

‘`(item.insert_parent DAUGHTER NEWPARENT)`’

  Insert a new parent above `DAUGHTER`. `NEWPARENT` may be a item or the description of an item.

‘`(item.delete ITEM)`’

  Delete this item from all relations it is in. All daughters of this item in each relations are also removed from the relation (which may in turn cause them to be deleted if they cease to be referenced by any other relation.

‘`(item.relation.remove ITEM)`’

  Remove this item from this relation, and any of its daughters. Other relations this item are in remain untouched.

‘`(item.move_tree FROM TO)`’

  Move the item `FROM` to the position of `TO` in `TO`’s relation. `FROM` will often be in the same relation as `TO` but that isn’t necessary. The contents of `TO` are dereferenced. its daughters are saved then descendants of `FROM` are recreated under the new `TO`, then `TO`’s previous daughters are derefenced. The order of this is important as `FROM` may be part of `TO`’s descendants. Note that if `TO` is part of `FROM`’s descendants no moving occurs and `nil` is returned. For example to remove all punction terminal nodes in the Syntax relation the call would be something like

      (define (syntax_relation_punc p)
        (if (string-equal "punc" (item.feat (item.daughter2 p) "pos"))
            (item.move_tree (item.daughter1 p) p)
        (mapcar syntax_remove_punc (item.daughters p))))

‘`(item.exchange_trees ITEM1 ITEM2)`’

  Exchange `ITEM1` and `ITEM2` and their descendants in `ITEM2`’s relation. If `ITEM1` is within `ITEM2`’s descendants or vice versa `nil` is returns and no exchange takes place. If `ITEM1` is not in `ITEM2`’s relation, no exchange takes place.

Daughters of a node are actually represented as a list whose first daughter is double linked to the parent. Although being aware of this structure may be useful it is recommended that all access go through the tree specific functions `*.parent` and `*.daughter*` which properly deal with the structure, thus is the internal structure ever changes in the future only these tree access function need be updated.

With the above functions quite elaborate utterance manipulations can be performed. For example in post-lexical rules where modifications to the segments are required based on the words and their context. See Post-lexical rules, for an example of using various utterance access functions.