00001 /* 00002 * $Id: readtags.h,v 1.3 2009-05-10 12:58:46 bettini Exp $ 00003 * 00004 * Copyright (c) 1996-2003, Darren Hiebert 00005 * 00006 * This source code is released for the public domain. 00007 * 00008 * This file defines the public interface for looking up tag entries in tag 00009 * files. 00010 * 00011 * The functions defined in this interface are intended to provide tag file 00012 * support to a software tool. The tag lookups provided are sufficiently fast 00013 * enough to permit opening a sorted tag file, searching for a matching tag, 00014 * then closing the tag file each time a tag is looked up (search times are 00015 * on the order of hundreths of a second, even for huge tag files). This is 00016 * the recommended use of this library for most tool applications. Adhering 00017 * to this approach permits a user to regenerate a tag file at will without 00018 * the tool needing to detect and resynchronize with changes to the tag file. 00019 * Even for an unsorted 24MB tag file, tag searches take about one second. 00020 */ 00021 #ifndef READTAGS_H 00022 #define READTAGS_H 00023 00024 #ifdef __cplusplus 00025 extern "C" { 00026 #endif 00027 00028 /* 00029 * MACROS 00030 */ 00031 00032 /* Options for tagsSetSortType() */ 00033 typedef enum { 00034 TAG_UNSORTED, TAG_SORTED, TAG_FOLDSORTED 00035 } sortType ; 00036 00037 /* Options for tagsFind() */ 00038 #define TAG_FULLMATCH 0x0 00039 #define TAG_PARTIALMATCH 0x1 00040 00041 #define TAG_OBSERVECASE 0x0 00042 #define TAG_IGNORECASE 0x2 00043 00044 /* 00045 * DATA DECLARATIONS 00046 */ 00047 00048 typedef enum { TagFailure = 0, TagSuccess = 1 } tagResult; 00049 00050 struct sTagFile; 00051 00052 typedef struct sTagFile tagFile; 00053 00054 /* This structure contains information about the tag file. */ 00055 typedef struct { 00056 00057 struct { 00058 /* was the tag file successfully opened? */ 00059 int opened; 00060 00061 /* errno value when 'opened' is false */ 00062 int error_number; 00063 } status; 00064 00065 /* information about the structure of the tag file */ 00066 struct { 00067 /* format of tag file (1 = original, 2 = extended) */ 00068 short format; 00069 00070 /* how is the tag file sorted? */ 00071 sortType sort; 00072 } file; 00073 00074 00075 /* information about the program which created this tag file */ 00076 struct { 00077 /* name of author of generating program (may be null) */ 00078 const char *author; 00079 00080 /* name of program (may be null) */ 00081 const char *name; 00082 00083 /* URL of distribution (may be null) */ 00084 const char *url; 00085 00086 /* program version (may be null) */ 00087 const char *version; 00088 } program; 00089 00090 } tagFileInfo; 00091 00092 /* This structure contains information about an extension field for a tag. 00093 * These exist at the end of the tag in the form "key:value"). 00094 */ 00095 typedef struct { 00096 00097 /* the key of the extension field */ 00098 const char *key; 00099 00100 /* the value of the extension field (may be an empty string) */ 00101 const char *value; 00102 00103 } tagExtensionField; 00104 00105 /* This structure contains information about a specific tag. */ 00106 typedef struct { 00107 00108 /* name of tag */ 00109 const char *name; 00110 00111 /* path of source file containing definition of tag */ 00112 const char *file; 00113 00114 /* address for locating tag in source file */ 00115 struct { 00116 /* pattern for locating source line 00117 * (may be NULL if not present) */ 00118 const char *pattern; 00119 00120 /* line number in source file of tag definition 00121 * (may be zero if not known) */ 00122 unsigned long lineNumber; 00123 } address; 00124 00125 /* kind of tag (may by name, character, or NULL if not known) */ 00126 const char *kind; 00127 00128 /* is tag of file-limited scope? */ 00129 short fileScope; 00130 00131 /* miscellaneous extension fields */ 00132 struct { 00133 /* number of entries in `list' */ 00134 unsigned short count; 00135 00136 /* list of key value pairs */ 00137 tagExtensionField *list; 00138 } fields; 00139 00140 } tagEntry; 00141 00142 00143 /* 00144 * FUNCTION PROTOTYPES 00145 */ 00146 00147 /* 00148 * This function must be called before calling other functions in this 00149 * library. It is passed the path to the tag file to read and a (possibly 00150 * null) pointer to a structure which, if not null, will be populated with 00151 * information about the tag file. If successful, the function will return a 00152 * handle which must be supplied to other calls to read information from the 00153 * tag file, and info.status.opened will be set to true. If unsuccessful, 00154 * info.status.opened will be set to false and info.status.error_number will 00155 * be set to the errno value representing the system error preventing the tag 00156 * file from being successfully opened. 00157 */ 00158 extern tagFile *tagsOpen (const char *const filePath, tagFileInfo *const info); 00159 00160 /* 00161 * This function allows the client to override the normal automatic detection 00162 * of how a tag file is sorted. Permissible values for `type' are 00163 * TAG_UNSORTED, TAG_SORTED, TAG_FOLDSORTED. Tag files in the new extended 00164 * format contain a key indicating whether or not they are sorted. However, 00165 * tag files in the original format do not contain such a key even when 00166 * sorted, preventing this library from taking advantage of fast binary 00167 * lookups. If the client knows that such an unmarked tag file is indeed 00168 * sorted (or not), it can override the automatic detection. Note that 00169 * incorrect lookup results will result if a tag file is marked as sorted when 00170 * it actually is not. The function will return TagSuccess if called on an 00171 * open tag file or TagFailure if not. 00172 */ 00173 extern tagResult tagsSetSortType (tagFile *const file, const sortType type); 00174 00175 /* 00176 * Reads the first tag in the file, if any. It is passed the handle to an 00177 * opened tag file and a (possibly null) pointer to a structure which, if not 00178 * null, will be populated with information about the first tag file entry. 00179 * The function will return TagSuccess another tag entry is found, or 00180 * TagFailure if not (i.e. it reached end of file). 00181 */ 00182 extern tagResult tagsFirst (tagFile *const file, tagEntry *const entry); 00183 00184 /* 00185 * Step to the next tag in the file, if any. It is passed the handle to an 00186 * opened tag file and a (possibly null) pointer to a structure which, if not 00187 * null, will be populated with information about the next tag file entry. The 00188 * function will return TagSuccess another tag entry is found, or TagFailure 00189 * if not (i.e. it reached end of file). It will always read the first tag in 00190 * the file immediately after calling tagsOpen(). 00191 */ 00192 extern tagResult tagsNext (tagFile *const file, tagEntry *const entry); 00193 00194 /* 00195 * Retrieve the value associated with the extension field for a specified key. 00196 * It is passed a pointer to a structure already populated with values by a 00197 * previous call to tagsNext(), tagsFind(), or tagsFindNext(), and a string 00198 * containing the key of the desired extension field. If no such field of the 00199 * specified key exists, the function will return null. 00200 */ 00201 extern const char *tagsField (const tagEntry *const entry, const char *const key); 00202 00203 /* 00204 * Find the first tag matching `name'. The structure pointed to by `entry' 00205 * will be populated with information about the tag file entry. If a tag file 00206 * is sorted using the C locale, a binary search algorithm is used to search 00207 * the tag file, resulting in very fast tag lookups, even in huge tag files. 00208 * Various options controlling the matches can be combined by bit-wise or-ing 00209 * certain values together. The available values are: 00210 * 00211 * TAG_PARTIALMATCH 00212 * Tags whose leading characters match `name' will qualify. 00213 * 00214 * TAG_FULLMATCH 00215 * Only tags whose full lengths match `name' will qualify. 00216 * 00217 * TAG_IGNORECASE 00218 * Matching will be performed in a case-insenstive manner. Note that 00219 * this disables binary searches of the tag file. 00220 * 00221 * TAG_OBSERVECASE 00222 * Matching will be performed in a case-senstive manner. Note that 00223 * this enables binary searches of the tag file. 00224 * 00225 * The function will return TagSuccess if a tag matching the name is found, or 00226 * TagFailure if not. 00227 */ 00228 extern tagResult tagsFind (tagFile *const file, tagEntry *const entry, const char *const name, const int options); 00229 00230 /* 00231 * Find the next tag matching the name and options supplied to the most recent 00232 * call to tagsFind() for the same tag file. The structure pointed to by 00233 * `entry' will be populated with information about the tag file entry. The 00234 * function will return TagSuccess if another tag matching the name is found, 00235 * or TagFailure if not. 00236 */ 00237 extern tagResult tagsFindNext (tagFile *const file, tagEntry *const entry); 00238 00239 /* 00240 * Call tagsTerminate() at completion of reading the tag file, which will 00241 * close the file and free any internal memory allocated. The function will 00242 * return TagFailure is no file is currently open, TagSuccess otherwise. 00243 */ 00244 extern tagResult tagsClose (tagFile *const file); 00245 00246 #ifdef __cplusplus 00247 }; 00248 #endif 00249 00250 #endif 00251 00252 /* vi:set tabstop=8 shiftwidth=4: */