| 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() and tagsFindPseudoTag() */ |
| 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 |
* Does the same as tagsFind(), but is specialized to pseudo tags. |
| 275 |
* The available values for `match' are: |
| 276 |
* |
| 277 |
* TAG_PARTIALMATCH |
| 278 |
* Tags whose leading characters match `name' will qualify. |
| 279 |
* |
| 280 |
* TAG_FULLMATCH |
| 281 |
* Only tags whose full lengths match `name' will qualify. |
| 282 |
* |
| 283 |
* NOTE: unlike tagsFind(), this function uses liner-searching even if |
| 284 |
* the tags file is sorted. |
| 285 |
*/ |
| 286 |
extern tagResult tagsFindPseudoTag (tagFile *const file, tagEntry *const entry, const char *const name, const int match); |
| 287 |
|
| 288 |
/* |
| 289 |
* Call tagsClose() at completion of reading the tag file, which will |
| 290 |
* close the file and free any internal memory allocated. The function will |
| 291 |
* return TagFailure if no file is currently open, TagSuccess otherwise. |
| 292 |
*/ |
| 293 |
extern tagResult tagsClose (tagFile *const file); |
| 294 |
|
| 295 |
/* |
| 296 |
* Get the error status set in the last API call. |
| 297 |
* Much of the API functions return TagFailure because (1) no tag is |
| 298 |
* found, or (2) an error occurs. tagsGetErrno() is for distinguishing |
| 299 |
* (1) or (2). This function will return 0 for (1). The errno value |
| 300 |
* representing the system error or tagErrno value for (2). |
| 301 |
* |
| 302 |
* This function does not deal with the results of tagsOpen(), |
| 303 |
* tagsClose(), and tagsField(). |
| 304 |
*/ |
| 305 |
extern int tagsGetErrno (tagFile *const file); |
| 306 |
|
| 307 |
#ifdef __cplusplus |
| 308 |
}; |
| 309 |
#endif |
| 310 |
|
| 311 |
#endif |