readtags.h

/*
*   $Id: readtags_8h-source.html,v 1.11 2004/05/02 16:58:48 heicom Exp $
*
*   Copyright (c) 1996-2003, Darren Hiebert
*
*   This source code is released for the public domain.
*
*   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
*/

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;

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;

typedef struct {

    const char *key;

    const char *value;

} tagExtensionField;

typedef struct {

    const char *name;

    const char *file;

    struct {
        const char *pattern;

        unsigned long lineNumber;
    } address;

    const char *kind;

    short fileScope;

    struct {
        unsigned short count;

        tagExtensionField *list;
    } fields;

} tagEntry;


/*
*  FUNCTION PROTOTYPES
*/

extern tagFile *tagsOpen (const char *const filePath, tagFileInfo *const info);

extern tagResult tagsSetSortType (tagFile *const file, const sortType type);

extern tagResult tagsFirst (tagFile *const file, tagEntry *const entry);

extern tagResult tagsNext (tagFile *const file, tagEntry *const entry);

extern const char *tagsField (const tagEntry *const entry, const char *const key);

extern tagResult tagsFind (tagFile *const file, tagEntry *const entry, const char *const name, const int options);

extern tagResult tagsFindNext (tagFile *const file, tagEntry *const entry);

extern tagResult tagsClose (tagFile *const file);

#ifdef __cplusplus
};
#endif

#endif

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

---