src/tagmanager/tm_tag.h

   1 /*
   2 *
   3 *   Copyright (c) 2001-2002, Biswapesh Chattopadhyay
   4 *   Copyright 2005 The Geany contributors
   5 *
   6 *   This source code is released for free distribution under the terms of the
   7 *   GNU General Public License.
   8 *
   9 */
  10
  11 #ifndef TM_TAG_H
  12 #define TM_TAG_H
  13
  14 /* @file
  15  The TMTag structure and the associated functions are used to manipulate
  16  tags and arrays of tags. Normally, you should not create tags individually
  17  but through an external interface such as tm_source_file_parse(), which generates
  18  an array of tags for the given source file. Once the tag list is generated,
  19  you can do various operations such as:
  20         -# Extract relevant tags using tm_tags_extract()
  21         -# Sort an array of tags using tm_tags_sort()
  22         -# Deduplicate an array of tags using tm_tags_dedup().
  23
  24  An important thing to remember here is that the tags operations such as extraction,
  25  sorting and deduplication do not change the tag itself in any way, but rather,
  26  manipulate pointers to the tags structure. The tags themselves are owned by the
  27  TMSourceFile structure which created them during parsing. So, be careful, for example,
  28  while deduping the tags array of a source file directly, since this might lead to
  29  'dangling' tags whose pointers have been removed from the array. If you need to
  30  deduplicate, create a copy of the tag pointer array using tm_tags_extract().
  31 */
  32
  33 #include "tm_source_file.h"
  34 #include "tm_parser.h"
  35 #include <glib-object.h>
  36
  37 G_BEGIN_DECLS
  38
  39 /** Use the TM_TAG() macro to cast a pointer to (TMTag *) */
  40 #define TM_TAG(tag) ((TMTag *) tag)
  41
  42 /**
  43  Tag Attributes. Note that some attributes are available to file
  44  pseudotags only. Attributes are useful for specifying as arguments
  45  to the builtin sort and dedup functions, and during printing or writing
  46  to file, since these functions can operate on the given set of attributes
  47  only. Tag attributes are bitmasks and can be 'OR'-ed bitwise to represent
  48  any combination (line TMTagType).
  49 */
  50 typedef enum
  51 {
  52         tm_tag_attr_none_t = 0, /**< Undefined */
  53         tm_tag_attr_name_t = 1, /**< Tag Name */
  54         tm_tag_attr_type_t = 2, /**< Tag Type */
  55         tm_tag_attr_file_t = 4, /**< File in which tag exists */
  56         tm_tag_attr_line_t = 8, /**< Line number of tag */
  57         tm_tag_attr_pos_t = 16, /**< Byte position of tag in the file (Obsolete) */
  58         tm_tag_attr_scope_t = 32, /**< Scope of the tag */
  59         tm_tag_attr_inheritance_t = 64, /**< Parent classes */
  60         tm_tag_attr_arglist_t = 128, /**< Argument list */
  61         tm_tag_attr_local_t = 256, /**< If it has local scope */
  62         tm_tag_attr_time_t = 512, /**< Modification time (File tag only) */
  63         tm_tag_attr_vartype_t = 1024, /**< Variable Type */
  64         tm_tag_attr_access_t = 2048, /**< Access type (public/protected/private) */
  65         tm_tag_attr_impl_t = 4096, /**< Implementation (e.g. virtual) */
  66         tm_tag_attr_lang_t = 8192, /**< Language (File tag only) */
  67         tm_tag_attr_inactive_t = 16384, /**< Inactive file (File tag only, obsolete) */
  68         tm_tag_attr_flags_t = 32768, /**< Additional flags */
  69         tm_tag_attr_max_t = 65535 /**< Maximum value */
  70 } TMTagAttrType;
  71
  72 /** Tag access type for C++/Java member functions and variables */
  73 #define TAG_ACCESS_PUBLIC 'p' /**< Public member */
  74 #define TAG_ACCESS_PROTECTED 'r' /**< Protected member */
  75 #define TAG_ACCESS_PRIVATE 'v' /**< Private member */
  76 #define TAG_ACCESS_FRIEND 'f' /**< Friend members/functions */
  77 #define TAG_ACCESS_DEFAULT 'd' /**< Default access (Java) */
  78 #define TAG_ACCESS_UNKNOWN 'x' /**< Unknown access type */
  79
  80 /** Tag implementation type for functions */
  81 #define TAG_IMPL_VIRTUAL 'v' /**< Virtual implementation */
  82 #define TAG_IMPL_UNKNOWN 'x' /**< Unknown implementation */
  83
  84 enum
  85 {
  86         tm_tag_flag_none_t = 0, /**< No flags */
  87         tm_tag_flag_anon_t = 1, /**< Anonymous tag */
  88         tm_tag_flag_max_t = 1, /**< Maximum value */
  89 };
  90
  91 /**
  92  * The TMTag structure represents a single tag in the tag manager.
  93  **/
  94 typedef struct TMTag
  95 {
  96         char *name; /**< Name of tag */
  97         TMTagType type; /**< Tag Type */
  98         gint refcount; /* the reference count of the tag */
  99
 100         /** These are tag attributes */
 101         TMSourceFile *file; /**< File in which the tag occurs; NULL for global tags */
 102         gulong line; /**< Line number of the tag */
 103         gboolean local; /**< Is the tag of local scope */
 104         guint flags; /**< Additional flags */
 105         char *arglist; /**< Argument list (functions/prototypes/macros) */
 106         char *scope; /**< Scope of tag */
 107         char *inheritance; /**< Parent classes */
 108         char *var_type; /**< Variable type (maps to struct for typedefs) */
 109         char access; /**< Access type (public/protected/private/etc.) */
 110         char impl; /**< Implementation (e.g. virtual) */
 111         TMParserType lang; /* Programming language of the file */
 112         gchar kind_letter; /* Kind letter from ctags */
 113 } TMTag;
 114
 115 /* The GType for a TMTag */
 116 #define TM_TYPE_TAG (tm_tag_get_type())
 117
 118 GType tm_tag_get_type(void) G_GNUC_CONST;
 119
 120 #ifdef GEANY_PRIVATE
 121
 122 TMTag *tm_tag_new(void);
 123
 124 void tm_tags_remove_file_tags(TMSourceFile *source_file, GPtrArray *tags_array);
 125
 126 GPtrArray *tm_tags_merge(GPtrArray *big_array, GPtrArray *small_array,
 127         TMTagAttrType *sort_attributes, gboolean unref_duplicates);
 128
 129 void tm_tags_sort(GPtrArray *tags_array, TMTagAttrType *sort_attributes,
 130         gboolean dedup, gboolean unref_duplicates);
 131
 132 GPtrArray *tm_tags_extract(GPtrArray *tags_array, guint tag_types);
 133
 134 void tm_tags_prune(GPtrArray *tags_array);
 135
 136 void tm_tags_dedup(GPtrArray *tags_array, TMTagAttrType *sort_attributes, gboolean unref_duplicates);
 137
 138 TMTag **tm_tags_find(const GPtrArray *tags_array, const char *name,
 139                 gboolean partial, guint * tagCount);
 140
 141 void tm_tags_array_free(GPtrArray *tags_array, gboolean free_all);
 142
 143 const TMTag *tm_get_current_tag(GPtrArray *file_tags, const gulong line, const TMTagType tag_types);
 144
 145 void tm_tag_unref(TMTag *tag);
 146
 147 TMTag *tm_tag_ref(TMTag *tag);
 148
 149 gboolean tm_tags_equal(const TMTag *a, const TMTag *b);
 150
 151 gboolean tm_tag_is_anon(const TMTag *tag);
 152
 153 #ifdef TM_DEBUG /* various debugging functions */
 154
 155 const char *tm_tag_type_name(const TMTag *tag);
 156
 157 TMTagType tm_tag_name_type(const char* tag_name);
 158
 159 void tm_tag_print(TMTag *tag, FILE *fp);
 160
 161 void tm_tags_array_print(GPtrArray *tags, FILE *fp);
 162
 163 gint tm_tag_scope_depth(const TMTag *t);
 164
 165 #endif /* TM_DEBUG */
 166
 167 #endif /* GEANY_PRIVATE */
 168
 169 G_END_DECLS
 170
 171 #endif /* TM_TAG_H */