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 } tagErrno; 63 64 struct sTagFile; 65 66 typedef struct sTagFile tagFile; 67 68 /* This structure contains information about the tag file. */ 69 typedef struct { 70 71 struct { 72 /* was the tag file successfully opened? */ 73 int opened; 74 75 /* errno value or tagErrno typed value 76 when 'opened' is false */ 77 int error_number; 78 } status; 79 80 /* information about the structure of the tag file */ 81 struct { 82 /* format of tag file (1 = original, 2 = extended) */ 83 short format; 84 85 /* how is the tag file sorted? */ 86 tagSortType sort; 87 } file; 88 89 90 /* information about the program which created this tag file */ 91 struct { 92 /* name of author of generating program (may be null) */ 93 const char *author; 94 95 /* name of program (may be null) */ 96 const char *name; 97 98 /* URL of distribution (may be null) */ 99 const char *url; 100 101 /* program version (may be null) */ 102 const char *version; 103 } program; 104 105 } tagFileInfo; 106 107 /* This structure contains information about an extension field for a tag. 108 * These exist at the end of the tag in the form "key:value"). 109 */ 110 typedef struct { 111 112 /* the key of the extension field */ 113 const char *key; 114 115 /* the value of the extension field (may be an empty string) */ 116 const char *value; 117 118 } tagExtensionField; 119 120 /* This structure contains information about a specific tag. */ 121 typedef struct { 122 123 /* name of tag */ 124 const char *name; 125 126 /* path of source file containing definition of tag. 127 For a broken tags file, this can be NULL. */ 128 const char *file; 129 130 /* address for locating tag in source file */ 131 struct { 132 /* pattern for locating source line 133 * (may be NULL if not present) */ 134 const char *pattern; 135 136 /* line number in source file of tag definition 137 * (may be zero if not known) */ 138 unsigned long lineNumber; 139 } address; 140 141 /* kind of tag (may by name, character, or NULL if not known) */ 142 const char *kind; 143 144 /* is tag of file-limited scope? */ 145 short fileScope; 146 147 /* miscellaneous extension fields */ 148 struct { 149 /* number of entries in `list' */ 150 unsigned short count; 151 152 /* list of key value pairs */ 153 tagExtensionField *list; 154 } fields; 155 156 } tagEntry; 157 158 159 /* 160 * FUNCTION PROTOTYPES 161 */ 162 163 /* 164 * This function must be called before calling other functions in this 165 * library. It is passed the path to the tag file to read and a (possibly 166 * null) pointer to a structure which, if not null, will be populated with 167 * information about the tag file. If successful, the function will return a 168 * handle which must be supplied to other calls to read information from the 169 * tag file, and info.status.opened will be set to true. 170 * If unsuccessful, the function will return NULL, and 171 * info.status.opened will be set to false and 172 * info.status.error_number will be set to either the errno value 173 * representing the system error preventing the tag file from being 174 * successfully opened, or the tagErrno typed value representing the 175 * library level error. The error_number will be ENOMEM if the memory 176 * allocation for the handle is failed. 177 */ 178 extern tagFile *tagsOpen (const char *const filePath, tagFileInfo *const info); 179 180 /* 181 * This function allows the client to override the normal automatic detection 182 * of how a tag file is sorted. Permissible values for `type' are 183 * TAG_UNSORTED, TAG_SORTED, TAG_FOLDSORTED. Tag files in the new extended 184 * format contain a key indicating whether or not they are sorted. However, 185 * tag files in the original format do not contain such a key even when 186 * sorted, preventing this library from taking advantage of fast binary 187 * lookups. If the client knows that such an unmarked tag file is indeed 188 * sorted (or not), it can override the automatic detection. Note that 189 * incorrect lookup results will result if a tag file is marked as sorted when 190 * it actually is not. The function will return TagSuccess if called on an 191 * open tag file or TagFailure if not. 192 */ 193 extern tagResult tagsSetSortType (tagFile *const file, const tagSortType type); 194 195 /* 196 * Reads the first tag in the file, if any. It is passed the handle to an 197 * opened tag file and a (possibly null) pointer to a structure which, if not 198 * null, will be populated with information about the first tag file entry. 199 * The function will return TagSuccess another tag entry is found, or 200 * TagFailure if not (i.e. it reached end of file). 201 */ 202 extern tagResult tagsFirst (tagFile *const file, tagEntry *const entry); 203 204 /* 205 * Step to the next tag in the file, if any. It is passed the handle to an 206 * opened tag file and a (possibly null) pointer to a structure which, if not 207 * null, will be populated with information about the next tag file entry. The 208 * function will return TagSuccess another tag entry is found, or TagFailure 209 * if not (i.e. it reached end of file). It will always read the first tag in 210 * the file immediately after calling tagsOpen(). 211 */ 212 extern tagResult tagsNext (tagFile *const file, tagEntry *const entry); 213 214 /* 215 * Retrieve the value associated with the extension field for a specified key. 216 * It is passed a pointer to a structure already populated with values by a 217 * previous call to tagsNext(), tagsFind(), or tagsFindNext(), and a string 218 * containing the key of the desired extension field. If no such field of the 219 * specified key exists, the function will return null. 220 */ 221 extern const char *tagsField (const tagEntry *const entry, const char *const key); 222 223 /* 224 * Find the first tag matching `name'. The structure pointed to by `entry' 225 * will be populated with information about the tag file entry. If a tag file 226 * is sorted using the C locale, a binary search algorithm is used to search 227 * the tag file, resulting in very fast tag lookups, even in huge tag files. 228 * Various options controlling the matches can be combined by bit-wise or-ing 229 * certain values together. The available values are: 230 * 231 * TAG_PARTIALMATCH 232 * Tags whose leading characters match `name' will qualify. 233 * 234 * TAG_FULLMATCH 235 * Only tags whose full lengths match `name' will qualify. 236 * 237 * TAG_IGNORECASE 238 * Matching will be performed in a case-insensitive manner. Note that 239 * this disables binary searches of the tag file. 240 * 241 * TAG_OBSERVECASE 242 * Matching will be performed in a case-sensitive manner. Note that 243 * this enables binary searches of the tag file. 244 * 245 * The function will return TagSuccess if a tag matching the name is found, or 246 * TagFailure if not. 247 */ 248 extern tagResult tagsFind (tagFile *const file, tagEntry *const entry, const char *const name, const int options); 249 250 /* 251 * Find the next tag matching the name and options supplied to the most recent 252 * call to tagsFind() for the same tag file. The structure pointed to by 253 * `entry' will be populated with information about the tag file entry. The 254 * function will return TagSuccess if another tag matching the name is found, 255 * or TagFailure if not. 256 */ 257 extern tagResult tagsFindNext (tagFile *const file, tagEntry *const entry); 258 259 /* 260 * Does the same as tagsFirst(), but is specialized to pseudo tags. 261 * If tagFileInfo doesn't contain pseudo tags you are interested, read 262 * them sequentially with this function and tagsNextPseudoTag(). 263 */ 264 extern tagResult tagsFirstPseudoTag (tagFile *const file, tagEntry *const entry); 265 266 /* 267 * Does the same as tagsNext(), but is specialized to pseudo tags. Use with 268 * tagsFirstPseudoTag(). 269 */ 270 extern tagResult tagsNextPseudoTag (tagFile *const file, tagEntry *const entry); 271 272 /* 273 * Call tagsClose() at completion of reading the tag file, which will 274 * close the file and free any internal memory allocated. The function will 275 * return TagFailure if no file is currently open, TagSuccess otherwise. 276 */ 277 extern tagResult tagsClose (tagFile *const file); 278 279 /* 280 * Get the error status set in the last API call. 281 * Much of the API functions return TagFailure because (1) no tag is 282 * found, or (2) an error occurs. tagsGetErrno() is for distinguishing 283 * (1) or (2). This function will return 0 for (1). The errno value 284 * representing the system error or tagErrno value for (2). 285 * 286 * This function does not deal with the results of tagsOpen(), 287 * tagsClose(), and tagsField(). 288 */ 289 extern int tagsGetErrno (tagFile *const file); 290 291 #ifdef __cplusplus 292 }; 293 #endif 294 295 #endif 296