KDevelop API Documentation

readtags.h

Go to the documentation of this file.
00001 /*
00002 *   $Id: readtags.h,v 1.2 2004/04/14 20:26:12 mueller Exp $
00003 *
00004 *   Copyright (c) 1996-2003, Darren Hiebert
00005 *
00006 *   This source code is released for the public domain.
00007 *
00008 *   This file defines the public interface for looking up tag entries in tag
00009 *   files.
00010 *
00011 *   The functions defined in this interface are intended to provide tag file
00012 *   support to a software tool. The tag lookups provided are sufficiently fast
00013 *   enough to permit opening a sorted tag file, searching for a matching tag,
00014 *   then closing the tag file each time a tag is looked up (search times are
00015 *   on the order of hundreths of a second, even for huge tag files). This is
00016 *   the recommended use of this library for most tool applications. Adhering
00017 *   to this approach permits a user to regenerate a tag file at will without
00018 *   the tool needing to detect and resynchronize with changes to the tag file.
00019 *   Even for an unsorted 24MB tag file, tag searches take about one second.
00020 */
00021 #ifndef READTAGS_H
00022 #define READTAGS_H
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 /*
00029 *  MACROS
00030 */
00031 
00032 /* Options for tagsSetSortType() */
00033 typedef enum {
00034     TAG_UNSORTED, TAG_SORTED, TAG_FOLDSORTED
00035 } sortType ;
00036 
00037 /* Options for tagsFind() */
00038 #define TAG_FULLMATCH     0x0
00039 #define TAG_PARTIALMATCH  0x1
00040 
00041 #define TAG_OBSERVECASE   0x0
00042 #define TAG_IGNORECASE    0x2
00043 
00044 /*
00045 *  DATA DECLARATIONS
00046 */
00047 
00048 typedef enum { TagFailure = 0, TagSuccess = 1 } tagResult;
00049 
00050 struct sTagFile;
00051 
00052 typedef struct sTagFile tagFile;
00053 
00054 /* This structure contains information about the tag file. */
00055 typedef struct {
00056 
00057     struct {
00058             /* was the tag file successfully opened? */
00059         int opened;
00060 
00061             /* errno value when 'opened' is false */
00062         int error_number;
00063     } status;
00064 
00065         /* information about the structure of the tag file */
00066     struct {
00067             /* format of tag file (1 = original, 2 = extended) */
00068         short format;
00069 
00070             /* how is the tag file sorted? */
00071         sortType sort;
00072     } file;
00073 
00074 
00075         /* information about the program which created this tag file */
00076     struct {
00077             /* name of author of generating program (may be null) */
00078         const char *author;
00079 
00080             /* name of program (may be null) */
00081         const char *name;
00082 
00083             /* URL of distribution (may be null) */
00084         const char *url;
00085 
00086             /* program version (may be null) */
00087         const char *version;
00088     } program;
00089 
00090 } tagFileInfo;
00091 
00092 /* This structure contains information about an extension field for a tag.
00093  * These exist at the end of the tag in the form "key:value").
00094  */
00095 typedef struct {
00096 
00097         /* the key of the extension field */
00098     const char *key;
00099 
00100         /* the value of the extension field (may be an empty string) */
00101     const char *value;
00102 
00103 } tagExtensionField;
00104 
00105 /* This structure contains information about a specific tag. */
00106 typedef struct {
00107 
00108         /* name of tag */
00109     const char *name;
00110 
00111         /* path of source file containing definition of tag */
00112     const char *file;
00113 
00114         /* address for locating tag in source file */
00115     struct {
00116             /* pattern for locating source line
00117              * (may be NULL if not present) */
00118         const char *pattern;
00119 
00120             /* line number in source file of tag definition
00121              * (may be zero if not known) */
00122         unsigned long lineNumber;
00123     } address;
00124 
00125         /* kind of tag (may by name, character, or NULL if not known) */
00126     const char *kind;
00127 
00128         /* is tag of file-limited scope? */
00129     short fileScope;
00130 
00131         /* miscellaneous extension fields */
00132     struct {
00133             /* number of entries in `list' */
00134         unsigned short count;
00135 
00136             /* list of key value pairs */
00137         tagExtensionField *list;
00138     } fields;
00139 
00140 } tagEntry;
00141 
00142 
00143 /*
00144 *  FUNCTION PROTOTYPES
00145 */
00146 
00147 /*
00148 *  This function must be called before calling other functions in this
00149 *  library. It is passed the path to the tag file to read and a (possibly
00150 *  null) pointer to a structure which, if not null, will be populated with
00151 *  information about the tag file. If successful, the function will return a
00152 *  handle which must be supplied to other calls to read information from the
00153 *  tag file, and info.status.opened will be set to true. If unsuccessful,
00154 *  info.status.opened will be set to false and info.status.error_number will
00155 *  be set to the errno value representing the system error preventing the tag
00156 *  file from being successfully opened.
00157 */
00158 extern tagFile *tagsOpen (const char *const filePath, tagFileInfo *const info);
00159 
00160 /*
00161 *  This function allows the client to override the normal automatic detection
00162 *  of how a tag file is sorted. Permissible values for `type' are
00163 *  TAG_UNSORTED, TAG_SORTED, TAG_FOLDSORTED. Tag files in the new extended
00164 *  format contain a key indicating whether or not they are sorted. However,
00165 *  tag files in the original format do not contain such a key even when
00166 *  sorted, preventing this library from taking advantage of fast binary
00167 *  lookups. If the client knows that such an unmarked tag file is indeed
00168 *  sorted (or not), it can override the automatic detection. Note that
00169 *  incorrect lookup results will result if a tag file is marked as sorted when
00170 *  it actually is not. The function will return TagSuccess if called on an
00171 *  open tag file or TagFailure if not.
00172 */
00173 extern tagResult tagsSetSortType (tagFile *const file, const sortType type);
00174 
00175 /*
00176 *  Reads the first tag in the file, if any. It is passed the handle to an
00177 *  opened tag file and a (possibly null) pointer to a structure which, if not
00178 *  null, will be populated with information about the first tag file entry.
00179 *  The function will return TagSuccess another tag entry is found, or
00180 *  TagFailure if not (i.e. it reached end of file).
00181 */
00182 extern tagResult tagsFirst (tagFile *const file, tagEntry *const entry);
00183 
00184 /*
00185 *  Step to the next tag in the file, if any. It is passed the handle to an
00186 *  opened tag file and a (possibly null) pointer to a structure which, if not
00187 *  null, will be populated with information about the next tag file entry. The
00188 *  function will return TagSuccess another tag entry is found, or TagFailure
00189 *  if not (i.e. it reached end of file). It will always read the first tag in
00190 *  the file immediately after calling tagsOpen().
00191 */
00192 extern tagResult tagsNext (tagFile *const file, tagEntry *const entry);
00193 
00194 /*
00195 *  Retrieve the value associated with the extension field for a specified key.
00196 *  It is passed a pointer to a structure already populated with values by a
00197 *  previous call to tagsNext(), tagsFind(), or tagsFindNext(), and a string
00198 *  containing the key of the desired extension field. If no such field of the
00199 *  specified key exists, the function will return null.
00200 */
00201 extern const char *tagsField (const tagEntry *const entry, const char *const key);
00202 
00203 /*
00204 *  Find the first tag matching `name'. The structure pointed to by `entry'
00205 *  will be populated with information about the tag file entry. If a tag file
00206 *  is sorted using the C locale, a binary search algorithm is used to search
00207 *  the tag file, resulting in very fast tag lookups, even in huge tag files.
00208 *  Various options controlling the matches can be combined by bit-wise or-ing
00209 *  certain values together. The available values are:
00210 *
00211 *    TAG_PARTIALMATCH
00212 *        Tags whose leading characters match `name' will qualify.
00213 *
00214 *    TAG_FULLMATCH
00215 *        Only tags whose full lengths match `name' will qualify.
00216 *
00217 *    TAG_IGNORECASE
00218 *        Matching will be performed in a case-insenstive manner. Note that
00219 *        this disables binary searches of the tag file.
00220 *
00221 *    TAG_OBSERVECASE
00222 *        Matching will be performed in a case-senstive manner. Note that
00223 *        this enables binary searches of the tag file.
00224 *
00225 *  The function will return TagSuccess if a tag matching the name is found, or
00226 *  TagFailure if not.
00227 */
00228 extern tagResult tagsFind (tagFile *const file, tagEntry *const entry, const char *const name, const int options);
00229 
00230 /*
00231 *  Find the next tag matching the name and options supplied to the most recent
00232 *  call to tagsFind() for the same tag file. The structure pointed to by
00233 *  `entry' will be populated with information about the tag file entry. The
00234 *  function will return TagSuccess if another tag matching the name is found,
00235 *  or TagFailure if not.
00236 */
00237 extern tagResult tagsFindNext (tagFile *const file, tagEntry *const entry);
00238 
00239 /*
00240 *  Call tagsTerminate() at completion of reading the tag file, which will
00241 *  close the file and free any internal memory allocated. The function will
00242 *  return TagFailure is no file is currently open, TagSuccess otherwise.
00243 */
00244 extern tagResult tagsClose (tagFile *const file);
00245 
00246 #ifdef __cplusplus
00247 }
00248 #endif
00249 
00250 #endif
00251 
00252 /* vi:set tabstop=8 shiftwidth=4: */
KDE Logo
This file is part of the documentation for KDevelop Version 3.1.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Tue Feb 22 09:22:38 2005 by doxygen 1.3.9.1 written by Dimitri van Heesch, © 1997-2003