readtags.h

   1 /*
   2 *   $Id: readtags.h 443 2006-05-30 04:37:13Z darren $
   3 *
   4 *   Copyright (c) 1996-2003, Darren Hiebert
   5 *
   6 *   This source code is released for the public domain.
   7 *
   8 *   This file defines the public interface for looking up tag entries in tag
   9 *   files.
  10 *
  11 *   The functions defined in this interface are intended to provide tag file
  12 *   support to a software tool. The tag lookups provided are sufficiently fast
  13 *   enough to permit opening a sorted tag file, searching for a matching tag,
  14 *   then closing the tag file each time a tag is looked up (search times are
  15 *   on the order of hundreths of a second, even for huge tag files). This is
  16 *   the recommended use of this library for most tool applications. Adhering
  17 *   to this approach permits a user to regenerate a tag file at will without
  18 *   the tool needing to detect and resynchronize with changes to the tag file.
  19 *   Even for an unsorted 24MB tag file, tag searches take about one second.
  20 */
  21 #ifndef READTAGS_H
  22 #define READTAGS_H
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /*
  29 *  MACROS
  30 */
  31
  32 /* Options for tagsSetSortType() */
  33 typedef enum {
  34         TAG_UNSORTED, TAG_SORTED, TAG_FOLDSORTED
  35 } sortType ;
  36
  37 /* Options for tagsFind() */
  38 #define TAG_FULLMATCH     0x0
  39 #define TAG_PARTIALMATCH  0x1
  40
  41 #define TAG_OBSERVECASE   0x0
  42 #define TAG_IGNORECASE    0x2
  43
  44 /*
  45 *  DATA DECLARATIONS
  46 */
  47
  48 typedef enum { TagFailure = 0, TagSuccess = 1 } tagResult;
  49
  50 struct sTagFile;
  51
  52 typedef struct sTagFile tagFile;
  53
  54 /* This structure contains information about the tag file. */
  55 typedef struct {
  56
  57         struct {
  58                         /* was the tag file successfully opened? */
  59                 int opened;
  60
  61                         /* errno value when 'opened' is false */
  62                 int error_number;
  63         } status;
  64
  65                 /* information about the structure of the tag file */
  66         struct {
  67                                 /* format of tag file (1 = original, 2 = extended) */
  68                         short format;
  69
  70                                 /* how is the tag file sorted? */
  71                         sortType sort;
  72         } file;
  73
  74
  75                 /* information about the program which created this tag file */
  76         struct {
  77                         /* name of author of generating program (may be null) */
  78                 const char *author;
  79
  80                         /* name of program (may be null) */
  81                 const char *name;
  82
  83                         /* URL of distribution (may be null) */
  84                 const char *url;
  85
  86                         /* program version (may be null) */
  87                 const char *version;
  88         } program;
  89
  90 } tagFileInfo;
  91
  92 /* This structure contains information about an extension field for a tag.
  93  * These exist at the end of the tag in the form "key:value").
  94  */
  95 typedef struct {
  96
  97                 /* the key of the extension field */
  98         const char *key;
  99
 100                 /* the value of the extension field (may be an empty string) */
 101         const char *value;
 102
 103 } tagExtensionField;
 104
 105 /* This structure contains information about a specific tag. */
 106 typedef struct {
 107
 108                 /* name of tag */
 109         const char *name;
 110
 111                 /* path of source file containing definition of tag */
 112         const char *file;
 113
 114                 /* address for locating tag in source file */
 115         struct {
 116                         /* pattern for locating source line
 117                          * (may be NULL if not present) */
 118                 const char *pattern;
 119
 120                         /* line number in source file of tag definition
 121                          * (may be zero if not known) */
 122                 unsigned long lineNumber;
 123         } address;
 124
 125                 /* kind of tag (may by name, character, or NULL if not known) */
 126         const char *kind;
 127
 128                 /* is tag of file-limited scope? */
 129         short fileScope;
 130
 131                 /* miscellaneous extension fields */
 132         struct {
 133                         /* number of entries in `list' */
 134                 unsigned short count;
 135
 136                         /* list of key value pairs */
 137                 tagExtensionField *list;
 138         } fields;
 139
 140 } tagEntry;
 141
 142
 143 /*
 144 *  FUNCTION PROTOTYPES
 145 */
 146
 147 /*
 148 *  This function must be called before calling other functions in this
 149 *  library. It is passed the path to the tag file to read and a (possibly
 150 *  null) pointer to a structure which, if not null, will be populated with
 151 *  information about the tag file. If successful, the function will return a
 152 *  handle which must be supplied to other calls to read information from the
 153 *  tag file, and info.status.opened will be set to true. If unsuccessful,
 154 *  info.status.opened will be set to false and info.status.error_number will
 155 *  be set to the errno value representing the system error preventing the tag
 156 *  file from being successfully opened.
 157 */
 158 extern tagFile *tagsOpen (const char *const filePath, tagFileInfo *const info);
 159
 160 /*
 161 *  This function allows the client to override the normal automatic detection
 162 *  of how a tag file is sorted. Permissible values for `type' are
 163 *  TAG_UNSORTED, TAG_SORTED, TAG_FOLDSORTED. Tag files in the new extended
 164 *  format contain a key indicating whether or not they are sorted. However,
 165 *  tag files in the original format do not contain such a key even when
 166 *  sorted, preventing this library from taking advantage of fast binary
 167 *  lookups. If the client knows that such an unmarked tag file is indeed
 168 *  sorted (or not), it can override the automatic detection. Note that
 169 *  incorrect lookup results will result if a tag file is marked as sorted when
 170 *  it actually is not. The function will return TagSuccess if called on an
 171 *  open tag file or TagFailure if not.
 172 */
 173 extern tagResult tagsSetSortType (tagFile *const file, const sortType type);
 174
 175 /*
 176 *  Reads the first tag in the file, if any. It is passed the handle to an
 177 *  opened tag file and a (possibly null) pointer to a structure which, if not
 178 *  null, will be populated with information about the first tag file entry.
 179 *  The function will return TagSuccess another tag entry is found, or
 180 *  TagFailure if not (i.e. it reached end of file).
 181 */
 182 extern tagResult tagsFirst (tagFile *const file, tagEntry *const entry);
 183
 184 /*
 185 *  Step to the next tag in the file, if any. It is passed the handle to an
 186 *  opened tag file and a (possibly null) pointer to a structure which, if not
 187 *  null, will be populated with information about the next tag file entry. The
 188 *  function will return TagSuccess another tag entry is found, or TagFailure
 189 *  if not (i.e. it reached end of file). It will always read the first tag in
 190 *  the file immediately after calling tagsOpen().
 191 */
 192 extern tagResult tagsNext (tagFile *const file, tagEntry *const entry);
 193
 194 /*
 195 *  Retrieve the value associated with the extension field for a specified key.
 196 *  It is passed a pointer to a structure already populated with values by a
 197 *  previous call to tagsNext(), tagsFind(), or tagsFindNext(), and a string
 198 *  containing the key of the desired extension field. If no such field of the
 199 *  specified key exists, the function will return null.
 200 */
 201 extern const char *tagsField (const tagEntry *const entry, const char *const key);
 202
 203 /*
 204 *  Find the first tag matching `name'. The structure pointed to by `entry'
 205 *  will be populated with information about the tag file entry. If a tag file
 206 *  is sorted using the C locale, a binary search algorithm is used to search
 207 *  the tag file, resulting in very fast tag lookups, even in huge tag files.
 208 *  Various options controlling the matches can be combined by bit-wise or-ing
 209 *  certain values together. The available values are:
 210 *
 211 *    TAG_PARTIALMATCH
 212 *        Tags whose leading characters match `name' will qualify.
 213 *
 214 *    TAG_FULLMATCH
 215 *        Only tags whose full lengths match `name' will qualify.
 216 *
 217 *    TAG_IGNORECASE
 218 *        Matching will be performed in a case-insenstive manner. Note that
 219 *        this disables binary searches of the tag file.
 220 *
 221 *    TAG_OBSERVECASE
 222 *        Matching will be performed in a case-senstive manner. Note that
 223 *        this enables binary searches of the tag file.
 224 *
 225 *  The function will return TagSuccess if a tag matching the name is found, or
 226 *  TagFailure if not.
 227 */
 228 extern tagResult tagsFind (tagFile *const file, tagEntry *const entry, const char *const name, const int options);
 229
 230 /*
 231 *  Find the next tag matching the name and options supplied to the most recent
 232 *  call to tagsFind() for the same tag file. The structure pointed to by
 233 *  `entry' will be populated with information about the tag file entry. The
 234 *  function will return TagSuccess if another tag matching the name is found,
 235 *  or TagFailure if not.
 236 */
 237 extern tagResult tagsFindNext (tagFile *const file, tagEntry *const entry);
 238
 239 /*
 240 *  Call tagsTerminate() at completion of reading the tag file, which will
 241 *  close the file and free any internal memory allocated. The function will
 242 *  return TagFailure is no file is currently open, TagSuccess otherwise.
 243 */
 244 extern tagResult tagsClose (tagFile *const file);
 245
 246 #ifdef __cplusplus
 247 };
 248 #endif
 249
 250 #endif
 251
 252 /* vi:set tabstop=4 shiftwidth=4: */