Source-highlight Library
/home/bettini/work/source-highlight/src-highlite/lib/srchilite/readtags.h
00001 /*
00002 *   $Id: readtags_8h_source.html,v 1.5 2012/06/30 13:06:12 bettini 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: */