Skip to content
Newer
Older
100644 253 lines (205 sloc) 8.11 KB
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
1 /*
2 * $Id$
3 *
7f0fb28 Updated copyright dates.
Darren Hiebert authored Apr 1, 2003
4 * Copyright (c) 1996-2003, Darren Hiebert
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
5 *
6 * This source code is released for the public domain.
7 *
2f6b127 Changed interface and added partial and case-insensitive searched.
Darren Hiebert authored Dec 17, 2001
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
2f55859 Improvement in documentation and demo program.
Darren Hiebert authored Feb 16, 2002
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.
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
20 */
9603255 Renamed a few small items and added minor function in readtags library.
Darren Hiebert authored Aug 26, 2002
21 #ifndef READTAGS_H
22 #define READTAGS_H
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
23
bc04f57 Added extern C around contents for C++ compatibility.
Darren Hiebert authored Jan 16, 2003
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
28 /*
2f6b127 Changed interface and added partial and case-insensitive searched.
Darren Hiebert authored Dec 17, 2001
29 * MACROS
30 */
31
9603255 Renamed a few small items and added minor function in readtags library.
Darren Hiebert authored Aug 26, 2002
32 /* Options for tagsSetSortType() */
33 typedef enum {
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
34 TAG_UNSORTED, TAG_SORTED, TAG_FOLDSORTED
9603255 Renamed a few small items and added minor function in readtags library.
Darren Hiebert authored Aug 26, 2002
35 } sortType ;
2f55859 Improvement in documentation and demo program.
Darren Hiebert authored Feb 16, 2002
36
37 /* Options for tagsFind() */
2f6b127 Changed interface and added partial and case-insensitive searched.
Darren Hiebert authored Dec 17, 2001
38 #define TAG_FULLMATCH 0x0
39 #define TAG_PARTIALMATCH 0x1
9603255 Renamed a few small items and added minor function in readtags library.
Darren Hiebert authored Aug 26, 2002
40
2f6b127 Changed interface and added partial and case-insensitive searched.
Darren Hiebert authored Dec 17, 2001
41 #define TAG_OBSERVECASE 0x0
42 #define TAG_IGNORECASE 0x2
43
44 /*
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
45 * DATA DECLARATIONS
46 */
47
48 typedef enum { TagFailure = 0, TagSuccess = 1 } tagResult;
49
8bd9ecf Fixed memory overwrite. Changed external interface to eliminate use o…
Darren Hiebert authored Dec 16, 2001
50 struct sTagFile;
51
52 typedef struct sTagFile tagFile;
53
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
54 /* This structure contains information about the tag file. */
55 typedef struct {
56
49cb582 Improved ability to report failure of tagsOpen() to open tag file.
Darren Hiebert authored Sep 16, 2002
57 struct {
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
58 /* was the tag file successfully opened? */
49cb582 Improved ability to report failure of tagsOpen() to open tag file.
Darren Hiebert authored Sep 16, 2002
59 int opened;
60
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
61 /* errno value when 'opened' is false */
49cb582 Improved ability to report failure of tagsOpen() to open tag file.
Darren Hiebert authored Sep 16, 2002
62 int error_number;
63 } status;
64
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
65 /* information about the structure of the tag file */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
66 struct {
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
67 /* format of tag file (1 = original, 2 = extended) */
68 short format;
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
69
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
70 /* how is the tag file sorted? */
71 sortType sort;
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
72 } file;
73
8bd9ecf Fixed memory overwrite. Changed external interface to eliminate use o…
Darren Hiebert authored Dec 16, 2001
74
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
75 /* information about the program which created this tag file */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
76 struct {
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
77 /* name of author of generating program (may be null) */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
78 const char *author;
79
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
80 /* name of program (may be null) */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
81 const char *name;
82
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
83 /* URL of distribution (may be null) */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
84 const char *url;
85
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
86 /* program version (may be null) */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
87 const char *version;
88 } program;
89
90 } tagFileInfo;
91
2f6b127 Changed interface and added partial and case-insensitive searched.
Darren Hiebert authored Dec 17, 2001
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 */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
95 typedef struct {
96
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
97 /* the key of the extension field */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
98 const char *key;
99
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
100 /* the value of the extension field (may be an empty string) */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
101 const char *value;
102
103 } tagExtensionField;
104
105 /* This structure contains information about a specific tag. */
106 typedef struct {
107
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
108 /* name of tag */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
109 const char *name;
110
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
111 /* path of source file containing definition of tag */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
112 const char *file;
113
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
114 /* address for locating tag in source file */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
115 struct {
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
116 /* pattern for locating source line
117 * (may be NULL if not present) */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
118 const char *pattern;
119
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
120 /* line number in source file of tag definition
121 * (may be zero if not known) */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
122 unsigned long lineNumber;
123 } address;
124
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
125 /* kind of tag (may by name, character, or NULL if not known) */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
126 const char *kind;
127
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
128 /* is tag of file-limited scope? */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
129 short fileScope;
130
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
131 /* miscellaneous extension fields */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
132 struct {
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
133 /* number of entries in `list' */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
134 unsigned short count;
135
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
136 /* list of key value pairs */
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
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
9603255 Renamed a few small items and added minor function in readtags library.
Darren Hiebert authored Aug 26, 2002
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
49cb582 Improved ability to report failure of tagsOpen() to open tag file.
Darren Hiebert authored Sep 16, 2002
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.
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
157 */
0746335 Fixed prototype.
Darren Hiebert authored Jan 16, 2003
158 extern tagFile *tagsOpen (const char *const filePath, tagFileInfo *const info);
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
159
160 /*
2f6b127 Changed interface and added partial and case-insensitive searched.
Darren Hiebert authored Dec 17, 2001
161 * This function allows the client to override the normal automatic detection
9603255 Renamed a few small items and added minor function in readtags library.
Darren Hiebert authored Aug 26, 2002
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.
2f6b127 Changed interface and added partial and case-insensitive searched.
Darren Hiebert authored Dec 17, 2001
172 */
35b1d07 Fixed prototypes to match exactly, since it appears some compilers co…
Darren Hiebert authored Jan 16, 2003
173 extern tagResult tagsSetSortType (tagFile *const file, const sortType type);
2f6b127 Changed interface and added partial and case-insensitive searched.
Darren Hiebert authored Dec 17, 2001
174
175 /*
9603255 Renamed a few small items and added minor function in readtags library.
Darren Hiebert authored Aug 26, 2002
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
8bd9ecf Fixed memory overwrite. Changed external interface to eliminate use o…
Darren Hiebert authored Dec 16, 2001
180 * TagFailure if not (i.e. it reached end of file).
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
181 */
35b1d07 Fixed prototypes to match exactly, since it appears some compilers co…
Darren Hiebert authored Jan 16, 2003
182 extern tagResult tagsFirst (tagFile *const file, tagEntry *const entry);
9603255 Renamed a few small items and added minor function in readtags library.
Darren Hiebert authored Aug 26, 2002
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 */
35b1d07 Fixed prototypes to match exactly, since it appears some compilers co…
Darren Hiebert authored Jan 16, 2003
192 extern tagResult tagsNext (tagFile *const file, tagEntry *const entry);
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
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 */
35b1d07 Fixed prototypes to match exactly, since it appears some compilers co…
Darren Hiebert authored Jan 16, 2003
201 extern const char *tagsField (const tagEntry *const entry, const char *const key);
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
202
203 /*
2f6b127 Changed interface and added partial and case-insensitive searched.
Darren Hiebert authored Dec 17, 2001
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 *
2f55859 Improvement in documentation and demo program.
Darren Hiebert authored Feb 16, 2002
214 * TAG_FULLMATCH
215 * Only tags whose full lengths match `name' will qualify.
216 *
2f6b127 Changed interface and added partial and case-insensitive searched.
Darren Hiebert authored Dec 17, 2001
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 *
2f55859 Improvement in documentation and demo program.
Darren Hiebert authored Feb 16, 2002
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 *
2f6b127 Changed interface and added partial and case-insensitive searched.
Darren Hiebert authored Dec 17, 2001
225 * The function will return TagSuccess if a tag matching the name is found, or
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
226 * TagFailure if not.
227 */
35b1d07 Fixed prototypes to match exactly, since it appears some compilers co…
Darren Hiebert authored Jan 16, 2003
228 extern tagResult tagsFind (tagFile *const file, tagEntry *const entry, const char *const name, const int options);
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
229
230 /*
2f6b127 Changed interface and added partial and case-insensitive searched.
Darren Hiebert authored Dec 17, 2001
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.
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
236 */
35b1d07 Fixed prototypes to match exactly, since it appears some compilers co…
Darren Hiebert authored Jan 16, 2003
237 extern tagResult tagsFindNext (tagFile *const file, tagEntry *const entry);
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
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 */
35b1d07 Fixed prototypes to match exactly, since it appears some compilers co…
Darren Hiebert authored Jan 16, 2003
244 extern tagResult tagsClose (tagFile *const file);
759ae2c Initial restoration.
Darren Hiebert authored Nov 2, 2001
245
bc04f57 Added extern C around contents for C++ compatibility.
Darren Hiebert authored Jan 16, 2003
246 #ifdef __cplusplus
247 };
248 #endif
249
9603255 Renamed a few small items and added minor function in readtags library.
Darren Hiebert authored Aug 26, 2002
250 #endif
251
edf593f Reformatted code for independence of tab stop setting.
Darren Hiebert authored May 30, 2006
252 /* vi:set tabstop=4 shiftwidth=4: */
Something went wrong with that request. Please try again.