1 /* 2 * $Id: readtags.h,v 1.1 2009/11/10 10:23:01 yetanothergeek Exp $ 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: */ 253 254