html/suif1_70.html

   1 <HTML>
   2 <HEAD>
   3 <!-- This HTML file has been created by texi2html 1.54
   4      from suif1.texi on 28 April 1999 -->
   5
   6 <TITLE>The SUIF Version 1 Library - Annotation Overview</TITLE>
   7 <link href="suif1_71.html" rel=Next>
   8 <link href="suif1_69.html" rel=Previous>
   9 <link href="suif1_toc.html" rel=ToC>
  10
  11 </HEAD>
  12 <BODY>
  13 <p>Go to the <A HREF="suif1_1.html">first</A>, <A HREF="suif1_69.html">previous</A>, <A HREF="suif1_71.html">next</A>, <A HREF="suif1_113.html">last</A> section, <A HREF="suif1_toc.html">table of contents</A>.
  14 <P><HR><P>
  15
  16
  17 <H2><A NAME="SEC70" HREF="suif1_toc.html#TOC70">Overview</A></H2>
  18
  19 <P>
  20 <A NAME="IDX544"></A>
  21 <A NAME="IDX545"></A>
  22 <A NAME="IDX546"></A>
  23 Annotations are represented by <CODE>annote</CODE> objects which are
  24 implemented in the files <TT>`annote.h'</TT> and <TT>`annote.cc'</TT>.  Each
  25 annotation contains two fields: a name and a data pointer.  The name is
  26 a character string that must be entered in the <CODE>lexicon</CODE>.
  27 See section <A HREF="suif1_102.html#SEC102">Lexicon</A>.  The name serves to identify the purpose of the
  28 annotation, and with the help of the annotation manager, it specifies
  29 the format of the associated data.  The <CODE>set_name</CODE> method can be
  30 used to change the name of an annotation, but in most cases it's easier
  31 to just create a new annotation.
  32
  33 </P>
  34 <P>
  35 As a convention, each annotation name should have a global variable that
  36 is a pointer to its entry in the <CODE>lexicon</CODE>.  The names of these
  37 variables should be <CODE>k_</CODE> followed by the annotation name.  For
  38 example, <CODE>k_repeat_init</CODE> is a global variable defined in the
  39 library to point to the <CODE>"repeat_init"</CODE> annotation name.  Because
  40 the annotation names are always in the <CODE>lexicon</CODE>, you can just
  41 compare the names with the global variables instead of performing string
  42 comparisons.  For example:
  43
  44 </P>
  45
  46 <PRE>
  47 annote *an;
  48 if (an-&#62;name() == k_repeat_init) {
  49     an-&#62;print();
  50 }
  51 </PRE>
  52
  53 <P>
  54 <A NAME="IDX547"></A>
  55 <A NAME="IDX548"></A>
  56 <A NAME="IDX549"></A>
  57 <A NAME="IDX550"></A>
  58 The data field in an annotation is a <CODE>void*</CODE> pointer so that, with
  59 the appropriate type cast, it can refer to any data structure.  The
  60 <CODE>data</CODE> and <CODE>set_data</CODE> methods may be used to directly access
  61 an annotation's data field.  The <CODE>immeds</CODE> and <CODE>set_immeds</CODE>
  62 methods also provide access to the data in an annotation, but only if it
  63 can be represented by a list of <CODE>immed</CODE> values; this is described
  64 in more detail below for each kind of annotation.
  65
  66 </P>
  67 <P>
  68 <A NAME="IDX551"></A>
  69 The <CODE>print</CODE> method prints an annotation to the specified file.  The
  70 format depends on the kind of annotation.  Flat annotations are printed
  71 as lists of <CODE>immed</CODE> values.  For unregistered annotation, the
  72 contents of the data field are printed directly as a pointer value (a
  73 hexidecimal representation on most systems).  Structured annotations
  74 may have user-defined printing functions registered in the annotation
  75 manager; if such a function is defined, the library uses it.  If no
  76 printing function is defined but a function to convert to a flat
  77 <CODE>immed</CODE> list is defined, that is used to temporarily convert to
  78 flat lists and print as such.  If neither a printing nor a conversion
  79 function is provided, the printing is done as with unregistered
  80 annotations.
  81
  82 </P>
  83 <P><HR><P>
  84 <p>Go to the <A HREF="suif1_1.html">first</A>, <A HREF="suif1_69.html">previous</A>, <A HREF="suif1_71.html">next</A>, <A HREF="suif1_113.html">last</A> section, <A HREF="suif1_toc.html">table of contents</A>.
  85 </BODY>
  86 </HTML>