Go to the previous, next section.

Overview

Annotations are represented by annote objects which are implemented in the files `annote.h' and `annote.cc'. Each annotation contains two fields: a name and a data pointer. The name is a character string that must be entered in the lexicon. See section Lexicon. The name serves to identify the purpose of the annotation, and with the help of the annotation manager, it specifies the format of the associated data. The set_name method can be used to change the name of an annotation, but in most cases it's easier to just create a new annotation.

As a convention, each annotation name should have a global variable that is a pointer to its entry in the lexicon. The names of these variables should be k_ followed by the annotation name. For example, k_repeat_init is a global variable defined in the library to point to the "repeat_init" annotation name. Because the annotation names are always in the lexicon, you can just compare the names with the global variables instead of performing string comparisons. For example:

annote *an;
if (an->name() == k_repeat_init) {
    an->print();
}

The data field in an annotation is a void* pointer so that, with the appropriate type cast, it can refer to any data structure. The data and set_data methods may be used to directly access an annotation's data field. The immeds and set_immeds methods also provide access to the data in an annotation, but only if it can be represented by a list of immed values; this is described in more detail below for each kind of annotation.

The print method prints an annotation to the specified file. The format depends on the kind of annotation. Flat annotations are printed as lists of immed values. For unregistered annotation, the contents of the data field are printed directly as a pointer value (a hexidecimal representation on most systems). Structured annotations may have user-defined printing functions registered in the annotation manager; if such a function is defined, the library uses it. If no printing function is defined but a function to convert to a flat immed list is defined, that is used to temporarily convert to flat lists and print as such. If neither a printing nor a conversion function is provided, the printing is done as with unregistered annotations.

Go to the previous, next section.