tagmanager/include/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
  34 #ifdef __cplusplus
  35 extern "C"
  36 {
  37 #endif
  38
  39 /*! Use the TM_TAG() macro to cast a pointer to (TMTag *) */
  40 #define TM_TAG(tag) ((TMTag *) tag)
  41
  42 /*!
  43  Types of tags. It is a bitmask so that multiple tag types can
  44  be used simultaneously by 'OR'-ing them bitwise.
  45  e.g. tm_tag_class_t | tm_tag_struct_t
  46 */
  47 typedef enum
  48 {
  49         tm_tag_undef_t = 0, /*!< Unknown type */
  50         tm_tag_class_t = 1, /*!< Class declaration */
  51         tm_tag_enum_t = 2, /*!< Enum declaration */
  52         tm_tag_enumerator_t = 4, /*!< Enumerator value */
  53         tm_tag_field_t = 8, /*!< Field (Java only) */
  54         tm_tag_function_t = 16, /*!< Function definition */
  55         tm_tag_interface_t = 32, /*!< Interface (Java only) */
  56         tm_tag_member_t = 64, /*!< Member variable of class/struct */
  57         tm_tag_method_t = 128, /*!< Class method (Java only) */
  58         tm_tag_namespace_t = 256, /*!< Namespace declaration */
  59         tm_tag_package_t = 512, /*!< Package (Java only) */
  60         tm_tag_prototype_t = 1024, /*!< Function prototype */
  61         tm_tag_struct_t = 2048, /*!< Struct declaration */
  62         tm_tag_typedef_t = 4096, /*!< Typedef */
  63         tm_tag_union_t = 8192, /*!< Union */
  64         tm_tag_variable_t = 16384, /*!< Variable */
  65         tm_tag_externvar_t = 32768, /*!< Extern or forward declaration */
  66         tm_tag_macro_t = 65536, /*!<  Macro (without arguments) */
  67         tm_tag_macro_with_arg_t = 131072, /*!< Parameterized macro */
  68         tm_tag_file_t = 262144, /*!< File (Pseudo tag) */
  69         tm_tag_other_t = 524288, /*!< Other (non C/C++/Java tag) */
  70         tm_tag_max_t = 1048575 /*!< Maximum value of TMTagType */
  71 } TMTagType;
  72
  73 /*!
  74  Tag Attributes. Note that some attributes are available to file
  75  pseudotags only. Attributes are useful for specifying as arguments
  76  to the builtin sort and dedup functions, and during printing or writing
  77  to file, since these functions can operate on the given set of attributes
  78  only. Tag attributes are bitmasks and can be 'OR'-ed bitwise to represent
  79  any combination (line TMTagType).
  80 */
  81 typedef enum
  82 {
  83         tm_tag_attr_none_t = 0, /*!< Undefined */
  84         tm_tag_attr_name_t = 1, /*!< Tag Name */
  85         tm_tag_attr_type_t = 2, /*!< Tag Type */
  86         tm_tag_attr_file_t = 4, /*!< File in which tag exists */
  87         tm_tag_attr_line_t = 8, /*!< Line number of tag */
  88         tm_tag_attr_pos_t = 16, /*!< Byte position of tag in the file (Obsolete) */
  89         tm_tag_attr_scope_t = 32, /*!< Scope of the tag */
  90         tm_tag_attr_inheritance_t = 64, /*!< Parent classes */
  91         tm_tag_attr_arglist_t = 128, /*!< Argument list */
  92         tm_tag_attr_local_t = 256, /*!< If it has local scope */
  93         tm_tag_attr_time_t = 512, /*!< Modification time (File tag only) */
  94
  95 /* UPDATE: because of the change of the tagEntryInfo in ctags 5.6 about
  96  * the migration from "const char* varType" to "const char* typeRef [2]"
  97  * here the "tm_tag_attr_vartype_t" will be referred to "typeRef[1]".
  98  * Probably a day we will need an ugrade here.
  99  */
 100
 101         tm_tag_attr_vartype_t = 1024, /*!< Variable Type */
 102         tm_tag_attr_access_t = 2048, /*!< Access type (public/protected/private) */
 103         tm_tag_attr_impl_t = 4096, /*!< Implementation (e.g. virtual) */
 104         tm_tag_attr_lang_t = 8192, /*!< Language (File tag only) */
 105         tm_tag_attr_inactive_t = 16384, /*!< Inactive file (File tag only) */
 106         tm_tag_attr_pointer_t = 32768, /*!< Inactive file (File tag only) */
 107         tm_tag_attr_max_t = 65535 /*!< Maximum value */
 108 } TMTagAttrType;
 109
 110 /*! Tag access type for C++/Java member functions and variables */
 111 #define TAG_ACCESS_PUBLIC 'p' /*!< Public member */
 112 #define TAG_ACCESS_PROTECTED 'r' /*!< Protected member */
 113 #define TAG_ACCESS_PRIVATE 'v' /*!< Private member */
 114 #define TAG_ACCESS_FRIEND 'f' /*!< Friend members/functions */
 115 #define TAG_ACCESS_DEFAULT 'd' /*!< Default access (Java) */
 116 #define TAG_ACCESS_UNKNOWN 'x' /*!< Unknown access type */
 117
 118 /*! Tag implementation type for functions */
 119 #define TAG_IMPL_VIRTUAL 'v' /*!< Virtual implementation */
 120 #define TAG_IMPL_UNKNOWN 'x' /*!< Unknown implementation */
 121
 122 /*!
 123  This structure holds all information about a tag, including the file
 124  pseudo tag. It should always be created indirectly with one of the tag
 125  creation functions such as tm_source_file_parse() or tm_tag_new_from_file().
 126  Once created, they can be sorted, deduped, etc. using functions such as
 127  tm_tags_custom_sort(), tm_tags_sort(), tm_tags_dedup() and tm_tags_custom_dedup()
 128 */
 129 typedef struct _TMTag
 130 {
 131         char *name; /*!< Name of tag */
 132         TMTagType type; /*!< Tag Type */
 133         union
 134         {
 135                 /*! These are *real* tag attributes */
 136                 struct
 137                 {
 138                         TMSourceFile *file; /*!< File in which the tag occurs */
 139                         gulong line; /*!< Line number of the tag */
 140                         gboolean local; /*!< Is the tag of local scope */
 141                         guint pointerOrder;
 142                         char *arglist; /*!< Argument list (functions/prototypes/macros) */
 143                         char *scope; /*!< Scope of tag */
 144                         char *inheritance; /*!< Parent classes */
 145                         char *type_ref[2]; /*!< Variable type (maps to struct for typedefs) */
 146                         char access; /*!< Access type (public/protected/private/etc.) */
 147                         char impl; /*!< Implementation (e.g. virtual) */
 148                 } entry;
 149                 /*! These are pseudo tag attributes representing a file */
 150                 struct
 151                 {
 152                         time_t timestamp; /*!< Time of parsing of the file */
 153                         langType lang; /*!< Programming language of the file */
 154                         gboolean inactive; /*!< Whether this file is to be parsed */
 155                 } file;
 156         } atts;
 157 } TMTag;
 158
 159 /*!
 160  Prototype for user-defined tag comparison function. This is the type
 161  of argument that needs to be passed to tm_tags_sort_custom() and
 162  tm_tags_dedup_custom(). The function should take two void pointers,
 163  cast them to (TMTag **) and return 0, 1 or -1 depending on whether the
 164  first tag is equal to, greater than or less than the second tag.
 165 */
 166 typedef int (*TMTagCompareFunc) (const void *ptr1, const void *ptr2);
 167
 168 /*!
 169  Initializes a TMTag structure with information from a tagEntryInfo struct
 170  used by the ctags parsers. Note that the TMTag structure must be malloc()ed
 171  before calling this function. This function is called by tm_tag_new() - you
 172  should not need to call this directly.
 173  \param tag The TMTag structure to initialize
 174  \param file Pointer to a TMSourceFile struct (it is assigned to the file member)
 175  \param tag_entry Tag information gathered by the ctags parser
 176  \return TRUE on success, FALSE on failure
 177 */
 178 gboolean tm_tag_init(TMTag *tag, TMSourceFile *file, const tagEntryInfo *tag_entry);
 179
 180 /*!
 181  Initializes an already malloc()ed TMTag structure by reading a tag entry
 182  line from a file. The structure should be allocated beforehand.
 183  \param tag The TMTag structure to populate
 184  \param file The TMSourceFile struct (assigned to the file member)
 185  \param fp FILE pointer from where the tag line is read
 186  \return TRUE on success, FALSE on FAILURE
 187 */
 188 gboolean tm_tag_init_from_file(TMTag *tag, TMSourceFile *file, FILE *fp);
 189
 190 /*!
 191  Creates a new tag structure from a tagEntryInfo pointer and a TMSOurceFile pointer
 192  and returns a pointer to it.
 193  \param file - Pointer to the TMSourceFile structure containing the tag
 194  \param tag_entry Contains tag information generated by ctags
 195  \return the new TMTag structure. This should be free()-ed using tm_tag_free()
 196 */
 197 TMTag *tm_tag_new(TMSourceFile *file, const tagEntryInfo *tag_entry);
 198
 199 /*!
 200  Same as tm_tag_new() except that the tag attributes are read from file
 201 */
 202 TMTag *tm_tag_new_from_file(TMSourceFile *file, FILE *fp);
 203
 204 /*!
 205  Writes tag information to the given FILE *.
 206  \param tag The tag information to write.
 207  \param file FILE pointer to which the tag information is written.
 208  \param attrs Attributes to be written (bitmask).
 209  \return TRUE on success, FALSE on failure.
 210 */
 211 gboolean tm_tag_write(TMTag *tag, FILE *file, guint attrs);
 212
 213 /*!
 214  Inbuilt tag comparison function. Do not call directly since it needs some
 215  static variables to be set. Always use tm_tags_sort() and tm_tags_dedup()
 216  instead.
 217 */
 218 int tm_tag_compare(const void *ptr1, const void *ptr2);
 219
 220 /*!
 221  Sort an array of tags on the specified attribuites using the inbuilt comparison
 222  function.
 223  \param tags_array The array of tags to be sorted
 224  \param sort_attributes Attributes to be sorted on (int array terminated by 0)
 225  \param dedup Whether to deduplicate the sorted array
 226  \return TRUE on success, FALSE on failure
 227 */
 228 gboolean tm_tags_sort(GPtrArray *tags_array, TMTagAttrType *sort_attributes, gboolean dedup);
 229
 230 /*!
 231  This function should be used whenever more involved sorting is required. For this,
 232  you need to write a function as per the prototype of TMTagCompareFunc() and pass
 233  the function as a parameter to this function.
 234  \param tags_array Array of tags to be sorted
 235  \param compare_func A function which takes two pointers to (TMTag *)s and returns
 236  0, 1 or -1 depending on whether the first value is equal to, greater than or less that
 237  the second
 238  \param dedup Whether to deduplicate the sorted array. Note that the same comparison
 239  function will be used
 240  \return TRUE on success, FALSE on failure
 241 */
 242 gboolean tm_tags_custom_sort(GPtrArray *tags_array, TMTagCompareFunc compare_func, gboolean dedup);
 243
 244 /*!
 245  This function will extract the tags of the specified types from an array of tags.
 246  The returned value is a GPtrArray which should be free-d with a call to
 247  g_ptr_array_free(array, TRUE). However, do not free the tags themselves since they
 248  are not duplicated.
 249  \param tags_array The original array of tags
 250  \param tag_types - The tag types to extract. Can be a bitmask. For example, passing
 251  (tm_tag_typedef_t | tm_tag_struct_t) will extract all typedefs and structures from
 252  the original array.
 253  \return an array of tags (NULL on failure)
 254 */
 255 GPtrArray *tm_tags_extract(const GPtrArray *tags_array, guint tag_types);
 256
 257 /*!
 258  Removes NULL tag entries from an array of tags. Called after tm_tags_dedup() and
 259  tm_tags_custom_dedup() since these functions substitute duplicate entries with NULL
 260  \param tags_array Array of tags to dedup
 261  \return TRUE on success, FALSE on failure
 262 */
 263 gboolean tm_tags_prune(GPtrArray *tags_array);
 264
 265 /*!
 266  Deduplicates an array on tags using the inbuilt comparison function based on
 267  the attributes specified. Called by tm_tags_sort() when dedup is TRUE.
 268  \param tags_array Array of tags to dedup.
 269  \param sort_attributes Attributes the array is sorted on. They will be deduped
 270  on the same criteria.
 271  \return TRUE on success, FALSE on failure
 272 */
 273 gboolean tm_tags_dedup(GPtrArray *tags_array, TMTagAttrType *sort_attributes);
 274
 275 /*!
 276  This is a more powerful form of tm_tags_dedup() since it can accomodate user
 277  defined comparison functions. Called by tm_tags_custom_sort() is dedup is TRUE.
 278  \param tags_array Array of tags to dedup.
 279  \compare_function Comparison function
 280  \return TRUE on success, FALSE on FAILURE
 281  \sa TMTagCompareFunc
 282 */
 283 gboolean tm_tags_custom_dedup(GPtrArray *tags_array, TMTagCompareFunc compare_func);
 284
 285 /*!
 286  Returns a pointer to the position of the first matching tag in a sorted tags array.
 287  \param sorted_tags_array Tag array sorted on name
 288  \param name Name of the tag to locate.
 289  \param partial If TRUE, matches the first part of the name instead of doing exact match.
 290 */
 291 TMTag **tm_tags_find (const GPtrArray *sorted_tags_array, const char *name,
 292                                           gboolean partial, int * tagCount);
 293
 294 /*!
 295  Completely frees an array of tags.
 296  \param tags_array Array of tags to be freed.
 297  \param free_array Whether the GptrArray is to be freed as well.
 298 */
 299 void tm_tags_array_free(GPtrArray *tags_array, gboolean free_all);
 300
 301 #if 0
 302 /*!
 303  Destroys a TMTag structure, i.e. frees all elements except the tag itself.
 304  \param tag The TMTag structure to destroy
 305  \sa tm_tag_free()
 306 */
 307 void tm_tag_destroy(TMTag *tag);
 308 #endif
 309
 310 /*!
 311  Destroys all data in the tag and frees the tag structure as well.
 312  \param tag Pointer to a TMTag structure
 313 */
 314 void tm_tag_free(gpointer tag);
 315
 316 /*!
 317  Returns the type of tag as a string
 318  \param tag The tag whose type is required
 319 */
 320 const char *tm_tag_type_name(const TMTag *tag);
 321
 322 /*!
 323  Returns the TMTagType given the name of the type. Reverse of tm_tag_type_name.
 324  \param tag_name Name of the tag type
 325 */
 326 TMTagType tm_tag_name_type(const char* tag_name);
 327
 328 /*!
 329   Prints information about a tag to the given file pointer.
 330   \param tag The tag whose info is required.
 331   \fp The file pointer of teh file to print the info to.
 332 */
 333 void tm_tag_print(TMTag *tag, FILE *fp);
 334
 335 /*!
 336   Prints info about all tags in the array to the given file pointer.
 337 */
 338 void tm_tags_array_print(GPtrArray *tags, FILE *fp);
 339
 340 /*!
 341   Returns the depth of tag scope (useful for finding tag hierarchy
 342 */
 343 gint tm_tag_scope_depth(const TMTag *t);
 344
 345 void tm_tag_chunk_clean (void);
 346
 347 #ifdef __cplusplus
 348 }
 349 #endif
 350
 351 #endif /* TM_TAG_H */