tagmanager/src/tm_tag.h

   1 /*
   2 *
   3 *   Copyright (c) 2001-2002, Biswapesh Chattopadhyay
   4 *
   5 *   This source code is released for free distribution under the terms of the
   6 *   GNU General Public License.
   7 *
   8 */
   9
  10 #ifndef TM_TAG_H
  11 #define TM_TAG_H
  12
  13 /* @file
  14  The TMTag structure and the associated functions are used to manipulate
  15  tags and arrays of tags. Normally, you should not create tags individually
  16  but through an external interface such as tm_source_file_parse(), which generates
  17  an array of tags for the given source file. Once the tag list is generated,
  18  you can do various operations such as:
  19         -# Extract relevant tags using tm_tags_extract()
  20         -# Sort an array of tags using tm_tags_sort() or tm_tags_custom_sort()
  21         -# Deduplicate an array of tags using tm_tags_dedup() or tm_tags_dedup_custom().
  22
  23  An important thing to remember here is that the tags operations such as extraction,
  24  sorting and deduplication do not change the tag itself in any way, but rather,
  25  manipulate pointers to the tags structure. The tags themselves are owned by the
  26  TMSourceFile structure which created them during parsing. So, be careful, for example,
  27  while deduping the tags array of a source file directly, since this might lead to
  28  'dangling' tags whose pointers have been removed from the array. If you need to
  29  deduplicate, create a copy of the tag pointer array using tm_tags_extract().
  30 */
  31
  32 #include "tm_source_file.h"
  33 #include <glib-object.h>
  34
  35 #ifdef __cplusplus
  36 extern "C"
  37 {
  38 #endif
  39
  40 /** Use the TM_TAG() macro to cast a pointer to (TMTag *) */
  41 #define TM_TAG(tag) ((TMTag *) tag)
  42
  43 /**
  44  Types of tags. It is a bitmask so that multiple tag types can
  45  be used simultaneously by 'OR'-ing them bitwise.
  46  e.g. tm_tag_class_t | tm_tag_struct_t
  47 */
  48 typedef enum
  49 {
  50         tm_tag_undef_t = 0, /**< Unknown type */
  51         tm_tag_class_t = 1, /**< Class declaration */
  52         tm_tag_enum_t = 2, /**< Enum declaration */
  53         tm_tag_enumerator_t = 4, /**< Enumerator value */
  54         tm_tag_field_t = 8, /**< Field (Java only) */
  55         tm_tag_function_t = 16, /**< Function definition */
  56         tm_tag_interface_t = 32, /**< Interface (Java only) */
  57         tm_tag_member_t = 64, /**< Member variable of class/struct */
  58         tm_tag_method_t = 128, /**< Class method (Java only) */
  59         tm_tag_namespace_t = 256, /**< Namespace declaration */
  60         tm_tag_package_t = 512, /**< Package (Java only) */
  61         tm_tag_prototype_t = 1024, /**< Function prototype */
  62         tm_tag_struct_t = 2048, /**< Struct declaration */
  63         tm_tag_typedef_t = 4096, /**< Typedef */
  64         tm_tag_union_t = 8192, /**< Union */
  65         tm_tag_variable_t = 16384, /**< Variable */
  66         tm_tag_externvar_t = 32768, /**< Extern or forward declaration */
  67         tm_tag_macro_t = 65536, /**<  Macro (without arguments) */
  68         tm_tag_macro_with_arg_t = 131072, /**< Parameterized macro */
  69         tm_tag_file_t = 262144, /**< File (Pseudo tag) */
  70         tm_tag_other_t = 524288, /**< Other (non C/C++/Java tag) */
  71         tm_tag_max_t = 1048575 /**< Maximum value of TMTagType */
  72 } TMTagType;
  73
  74 /**
  75  Tag Attributes. Note that some attributes are available to file
  76  pseudotags only. Attributes are useful for specifying as arguments
  77  to the builtin sort and dedup functions, and during printing or writing
  78  to file, since these functions can operate on the given set of attributes
  79  only. Tag attributes are bitmasks and can be 'OR'-ed bitwise to represent
  80  any combination (line TMTagType).
  81 */
  82 typedef enum
  83 {
  84         tm_tag_attr_none_t = 0, /**< Undefined */
  85         tm_tag_attr_name_t = 1, /**< Tag Name */
  86         tm_tag_attr_type_t = 2, /**< Tag Type */
  87         tm_tag_attr_file_t = 4, /**< File in which tag exists */
  88         tm_tag_attr_line_t = 8, /**< Line number of tag */
  89         tm_tag_attr_pos_t = 16, /**< Byte position of tag in the file (Obsolete) */
  90         tm_tag_attr_scope_t = 32, /**< Scope of the tag */
  91         tm_tag_attr_inheritance_t = 64, /**< Parent classes */
  92         tm_tag_attr_arglist_t = 128, /**< Argument list */
  93         tm_tag_attr_local_t = 256, /**< If it has local scope */
  94         tm_tag_attr_time_t = 512, /**< Modification time (File tag only) */
  95         tm_tag_attr_vartype_t = 1024, /**< Variable Type */
  96         tm_tag_attr_access_t = 2048, /**< Access type (public/protected/private) */
  97         tm_tag_attr_impl_t = 4096, /**< Implementation (e.g. virtual) */
  98         tm_tag_attr_lang_t = 8192, /**< Language (File tag only) */
  99         tm_tag_attr_inactive_t = 16384, /**< Inactive file (File tag only, obsolete) */
 100         tm_tag_attr_pointer_t = 32768, /**< Pointer type */
 101         tm_tag_attr_max_t = 65535 /**< Maximum value */
 102 } TMTagAttrType;
 103
 104 /** Tag access type for C++/Java member functions and variables */
 105 #define TAG_ACCESS_PUBLIC 'p' /**< Public member */
 106 #define TAG_ACCESS_PROTECTED 'r' /**< Protected member */
 107 #define TAG_ACCESS_PRIVATE 'v' /**< Private member */
 108 #define TAG_ACCESS_FRIEND 'f' /**< Friend members/functions */
 109 #define TAG_ACCESS_DEFAULT 'd' /**< Default access (Java) */
 110 #define TAG_ACCESS_UNKNOWN 'x' /**< Unknown access type */
 111
 112 /** Tag implementation type for functions */
 113 #define TAG_IMPL_VIRTUAL 'v' /**< Virtual implementation */
 114 #define TAG_IMPL_UNKNOWN 'x' /**< Unknown implementation */
 115
 116 /**
 117  This structure holds all information about a tag, including the file
 118  pseudo tag. It should always be created indirectly with one of the tag
 119  creation functions such as tm_source_file_parse() or tm_tag_new_from_file().
 120  Once created, they can be sorted, deduped, etc. using functions such as
 121  tm_tags_custom_sort(), tm_tags_sort(), tm_tags_dedup() and tm_tags_custom_dedup()
 122 */
 123 typedef struct _TMTag
 124 {
 125         char *name; /**< Name of tag */
 126         TMTagType type; /**< Tag Type */
 127         union
 128         {
 129                 /** These are *real* tag attributes */
 130                 struct
 131                 {
 132                         TMSourceFile *file; /**< File in which the tag occurs */
 133                         gulong line; /**< Line number of the tag */
 134                         gboolean local; /**< Is the tag of local scope */
 135                         guint pointerOrder;
 136                         char *arglist; /**< Argument list (functions/prototypes/macros) */
 137                         char *scope; /**< Scope of tag */
 138                         char *inheritance; /**< Parent classes */
 139                         char *var_type; /**< Variable type (maps to struct for typedefs) */
 140                         char access; /**< Access type (public/protected/private/etc.) */
 141                         char impl; /**< Implementation (e.g. virtual) */
 142                 } entry;
 143                 /** These are pseudo tag attributes representing a file */
 144                 struct
 145                 {
 146                         time_t timestamp; /**< Time of parsing of the file */
 147                         langType lang; /**< Programming language of the file */
 148                 } file;
 149         } atts;
 150         gint refcount; /**< the reference count of the tag */
 151 } TMTag;
 152
 153
 154 #ifdef GEANY_PRIVATE
 155
 156 typedef enum {
 157         TM_FILE_FORMAT_TAGMANAGER,
 158         TM_FILE_FORMAT_PIPE,
 159         TM_FILE_FORMAT_CTAGS
 160 } TMFileFormat;
 161
 162 /*
 163  Prototype for user-defined tag comparison function. This is the type
 164  of argument that needs to be passed to tm_tags_sort_custom() and
 165  tm_tags_dedup_custom(). The function should take two void pointers,
 166  cast them to (TMTag **) and return 0, 1 or -1 depending on whether the
 167  first tag is equal to, greater than or less than the second tag.
 168 */
 169 typedef int (*TMTagCompareFunc) (const void *ptr1, const void *ptr2);
 170
 171 /* The GType for a TMTag */
 172 #define TM_TYPE_TAG (tm_tag_get_type())
 173
 174 GType tm_tag_get_type(void) G_GNUC_CONST;
 175
 176 gboolean tm_tag_init(TMTag *tag, TMSourceFile *file, const tagEntryInfo *tag_entry);
 177
 178 gboolean tm_tag_init_from_file(TMTag *tag, TMSourceFile *file, FILE *fp);
 179
 180 gboolean tm_tag_init_from_file_alt(TMTag *tag, TMSourceFile *file, FILE *fp);
 181
 182 gboolean tm_tag_init_from_file_ctags(TMTag *tag, TMSourceFile *file, FILE *fp);
 183
 184 TMTag *tm_tag_new(TMSourceFile *file, const tagEntryInfo *tag_entry);
 185
 186 TMTag *tm_tag_new_from_file(TMSourceFile *file, FILE *fp, gint mode, TMFileFormat format);
 187
 188 gboolean tm_tag_write(TMTag *tag, FILE *file, guint attrs);
 189
 190 int tm_tag_compare(const void *ptr1, const void *ptr2);
 191
 192 GPtrArray *tm_tags_remove_file_tags(TMSourceFile *source_file, GPtrArray *tags_array);
 193
 194 GPtrArray *tm_tags_merge(GPtrArray *big_array, GPtrArray *small_array, TMTagAttrType *sort_attributes);
 195
 196 gboolean tm_tags_sort(GPtrArray *tags_array, TMTagAttrType *sort_attributes, gboolean dedup);
 197
 198 gboolean tm_tags_custom_sort(GPtrArray *tags_array, TMTagCompareFunc compare_func, gboolean dedup);
 199
 200 GPtrArray *tm_tags_extract(GPtrArray *tags_array, guint tag_types);
 201
 202 gboolean tm_tags_prune(GPtrArray *tags_array);
 203
 204 gboolean tm_tags_dedup(GPtrArray *tags_array, TMTagAttrType *sort_attributes);
 205
 206 gboolean tm_tags_custom_dedup(GPtrArray *tags_array, TMTagCompareFunc compare_func);
 207
 208 TMTag **tm_tags_find(const GPtrArray *tags_array, const char *name,
 209                 gboolean partial, gboolean tags_array_sorted, int * tagCount);
 210
 211 void tm_tags_array_free(GPtrArray *tags_array, gboolean free_all);
 212
 213 #if 0
 214 void tm_tag_destroy(TMTag *tag);
 215
 216 void tm_tag_free(gpointer tag);
 217 #endif
 218
 219 void tm_tag_unref(TMTag *tag);
 220
 221 TMTag *tm_tag_ref(TMTag *tag);
 222
 223 const char *tm_tag_type_name(const TMTag *tag);
 224
 225 TMTagType tm_tag_name_type(const char* tag_name);
 226
 227 void tm_tag_print(TMTag *tag, FILE *fp);
 228
 229 void tm_tags_array_print(GPtrArray *tags, FILE *fp);
 230
 231 gint tm_tag_scope_depth(const TMTag *t);
 232
 233 #endif /* GEANY_PRIVATE */
 234
 235 #ifdef __cplusplus
 236 }
 237 #endif
 238
 239 #endif /* TM_TAG_H */