Source-highlight Library
readtags.h
1 /*
2 * $Id: readtags_8h_source.html,v 1.6 2015/03/30 19:31:00 bettini 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 
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=8 shiftwidth=4: */
Definition: readtags.h:106
Definition: readtags.h:95
Definition: readtags.h:55
Definition: readtags.c:42