Source-highlight Library
Main Page
Namespaces
Classes
Files
File List
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
103
}
tagExtensionField
;
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: */
tagEntry
Definition:
readtags.h:106
tagExtensionField
Definition:
readtags.h:95
tagFileInfo
Definition:
readtags.h:55
sTagFile
Definition:
readtags.c:42
lib
srchilite
readtags.h
Generated on Mon Mar 30 2015 20:44:16 for Source-highlight Library by
1.8.8