Debian Codegraph @

geanyctags/src/readtags.h

raw
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