Source-highlight Library
readtags.h
1/*
2* $Id: readtags.h,v 1.3 2009-05-10 12:58:46 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
25extern "C" {
26#endif
27
28/*
29* MACROS
30*/
31
32/* Options for tagsSetSortType() */
33typedef 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
48typedef enum { TagFailure = 0, TagSuccess = 1 } tagResult;
49
50struct sTagFile;
51
52typedef struct sTagFile tagFile;
53
54/* This structure contains information about the tag file. */
55typedef 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
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 */
95typedef 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. */
106typedef 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*/
158extern 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*/
173extern 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*/
182extern 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*/
192extern 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*/
201extern 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*/
228extern 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*/
237extern 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*/
244extern 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.c:42
Definition: readtags.h:106
Definition: readtags.h:95
Definition: readtags.h:55