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.