Logo Search packages:      
Sourcecode: qdevelop version File versions  Download package

readtags.h

/********************************************************************************************************
 * PROGRAM    : 
 * DATE - TIME  : lundi 10 avril 2006 - 22:28
 * AUTHOR      : Darren Hiebert and Anacr0x ( fred.julian at gmail.com )
 * FILENAME  : 
 * LICENSE    : GPL
 * COMMENTARY   : Modified file (with qt) of the ctags project
 ********************************************************************************************************/

/*
*   This file defines the public interface for looking up tag entries in tag
*   files.
*
*   The functions defined in this interface are intended to provide tag file
*   support to a software tool. The tag lookups provided are sufficiently fast
*   enough to permit opening a sorted tag file, searching for a matching tag,
*   then closing the tag file each time a tag is looked up (search times are
*   on the order of hundreths of a second, even for huge tag files). This is
*   the recommended use of this library for most tool applications. Adhering
*   to this approach permits a user to regenerate a tag file at will without
*   the tool needing to detect and resynchronize with changes to the tag file.
*   Even for an unsorted 24MB tag file, tag searches take about one second.
*/
#ifndef READTAGS_H
#define READTAGS_H

#ifdef __cplusplus
extern "C"
{
#endif

      /*
      *  MACROS
      */

      /* Options for tagsSetSortType() */
      typedef enum
      {
          TAG_UNSORTED, TAG_SORTED, TAG_FOLDSORTED
      } sortType;

      /* Options for tagsFind() */
#define TAG_FULLMATCH     0x0
#define TAG_PARTIALMATCH  0x1

#define TAG_OBSERVECASE   0x0
#define TAG_IGNORECASE    0x2

      /*
      *  DATA DECLARATIONS
      */

      typedef enum
      { TagFailure = 0, TagSuccess = 1 } tagResult;

      struct sTagFile;

      typedef struct sTagFile tagFile;

      /* This structure contains information about the tag file. */
      typedef struct
      {

            struct
            {
                  /* was the tag file successfully opened? */
                  int opened;

                  /* errno value when 'opened' is false */
                  int error_number;
            }
            status;

            /* information about the structure of the tag file */
            struct
            {
                  /* format of tag file (1 = original, 2 = extended) */
                  short format;

                  /* how is the tag file sorted? */
                  sortType sort;
            }
            file;


            /* information about the program which created this tag file */
            struct
            {
                  /* name of author of generating program (may be null) */
                  const char *author;

                  /* name of program (may be null) */
                  const char *name;

                  /* URL of distribution (may be null) */
                  const char *url;

                  /* program version (may be null) */
                  const char *version;
            }
            program;

      }
      tagFileInfo;

      /* This structure contains information about an extension field for a tag.
       * These exist at the end of the tag in the form "key:value").
       */
      typedef struct
      {

            /* the key of the extension field */
            const char *key;

            /* the value of the extension field (may be an empty string) */
            const char *value;

      }
      tagExtensionField;

      /* This structure contains information about a specific tag. */
      typedef struct
      {

            /* name of tag */
            const char *name;

            /* path of source file containing definition of tag */
            const char *file;

            /* address for locating tag in source file */
            struct
            {
                  /* pattern for locating source line
                   * (may be NULL if not present) */
                  const char *pattern;

                  /* line number in source file of tag definition
                   * (may be zero if not known) */
                  unsigned long lineNumber;
            }
            address;

            /* kind of tag (may by name, character, or NULL if not known) */
            const char *kind;

            /* is tag of file-limited scope? */
            short fileScope;

            /* miscellaneous extension fields */
            struct
            {
                  /* number of entries in `list' */
                  unsigned short count;

                  /* list of key value pairs */
                  tagExtensionField *list;
            }
            fields;

      }
      tagEntry;


      /*
      *  FUNCTION PROTOTYPES
      */

      /*
      *  This function must be called before calling other functions in this
      *  library. It is passed the path to the tag file to read and a (possibly
      *  null) pointer to a structure which, if not null, will be populated with
      *  information about the tag file. If successful, the function will return a
      *  handle which must be supplied to other calls to read information from the
      *  tag file, and info.status.opened will be set to true. If unsuccessful,
      *  info.status.opened will be set to false and info.status.error_number will
      *  be set to the errno value representing the system error preventing the tag
      *  file from being successfully opened.
      */
      extern tagFile *tagsOpen(const char *const filePath, tagFileInfo * const info);

      /*
      *  This function allows the client to override the normal automatic detection
      *  of how a tag file is sorted. Permissible values for `type' are
      *  TAG_UNSORTED, TAG_SORTED, TAG_FOLDSORTED. Tag files in the new extended
      *  format contain a key indicating whether or not they are sorted. However,
      *  tag files in the original format do not contain such a key even when
      *  sorted, preventing this library from taking advantage of fast binary
      *  lookups. If the client knows that such an unmarked tag file is indeed
      *  sorted (or not), it can override the automatic detection. Note that
      *  incorrect lookup results will result if a tag file is marked as sorted when
      *  it actually is not. The function will return TagSuccess if called on an
      *  open tag file or TagFailure if not.
      */
      extern tagResult tagsSetSortType(tagFile * const file, const sortType type);

      /*
      *  Reads the first tag in the file, if any. It is passed the handle to an
      *  opened tag file and a (possibly null) pointer to a structure which, if not
      *  null, will be populated with information about the first tag file entry.
      *  The function will return TagSuccess another tag entry is found, or
      *  TagFailure if not (i.e. it reached end of file).
      */
      extern tagResult tagsFirst(tagFile * const file, tagEntry * const entry);

      /*
      *  Step to the next tag in the file, if any. It is passed the handle to an
      *  opened tag file and a (possibly null) pointer to a structure which, if not
      *  null, will be populated with information about the next tag file entry. The
      *  function will return TagSuccess another tag entry is found, or TagFailure
      *  if not (i.e. it reached end of file). It will always read the first tag in
      *  the file immediately after calling tagsOpen().
      */
      extern tagResult tagsNext(tagFile * const file, tagEntry * const entry);

      /*
      *  Retrieve the value associated with the extension field for a specified key.
      *  It is passed a pointer to a structure already populated with values by a
      *  previous call to tagsNext(), tagsFind(), or tagsFindNext(), and a string
      *  containing the key of the desired extension field. If no such field of the
      *  specified key exists, the function will return null.
      */
      extern const char *tagsField(const tagEntry * const entry,
                                         const char *const key);

      /*
      *  Find the first tag matching `name'. The structure pointed to by `entry'
      *  will be populated with information about the tag file entry. If a tag file
      *  is sorted using the C locale, a binary search algorithm is used to search
      *  the tag file, resulting in very fast tag lookups, even in huge tag files.
      *  Various options controlling the matches can be combined by bit-wise or-ing
      *  certain values together. The available values are:
      *
      *    TAG_PARTIALMATCH
      *        Tags whose leading characters match `name' will qualify.
      *
      *    TAG_FULLMATCH
      *        Only tags whose full lengths match `name' will qualify.
      *
      *    TAG_IGNORECASE
      *        Matching will be performed in a case-insenstive manner. Note that
      *        this disables binary searches of the tag file.
      *
      *    TAG_OBSERVECASE
      *        Matching will be performed in a case-senstive manner. Note that
      *        this enables binary searches of the tag file.
      *
      *  The function will return TagSuccess if a tag matching the name is found, or
      *  TagFailure if not.
      */
      extern tagResult tagsFind(tagFile * const file, tagEntry * const entry,
                                      const char *const name, const int options);

      /*
      *  Find the next tag matching the name and options supplied to the most recent
      *  call to tagsFind() for the same tag file. The structure pointed to by
      *  `entry' will be populated with information about the tag file entry. The
      *  function will return TagSuccess if another tag matching the name is found,
      *  or TagFailure if not.
      */
      extern tagResult tagsFindNext(tagFile * const file, tagEntry * const entry);

      /*
      *  Call tagsTerminate() at completion of reading the tag file, which will
      *  close the file and free any internal memory allocated. The function will
      *  return TagFailure is no file is currently open, TagSuccess otherwise.
      */
      extern tagResult tagsClose(tagFile * const file);

#ifdef __cplusplus
};
#endif

#endif

/* vi:set tabstop=8 shiftwidth=4: */

Generated by  Doxygen 1.6.0   Back to index