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