[geany/geany] 0470f4: TM: move function descriptions from headers to sources

Branch: refs/heads/master Author: Jiří Techet techet@gmail.com Committer: Jiří Techet techet@gmail.com Date: Sat, 18 Oct 2014 19:40:10 UTC Commit: 0470f45e0cac539efed63e3f01d519ac01623f74 https://github.com/geany/geany/commit/0470f45e0cac539efed63e3f01d519ac01623f...

Log Message: ----------- TM: move function descriptions from headers to sources

To make it consistent with the rest of Geany.

Modified Paths: -------------- tagmanager/src/tm_source_file.c tagmanager/src/tm_source_file.h tagmanager/src/tm_tag.c tagmanager/src/tm_tag.h tagmanager/src/tm_workspace.c tagmanager/src/tm_workspace.h

Modified: tagmanager/src/tm_source_file.c 78 lines changed, 78 insertions(+), 0 deletions(-) =================================================================== @@ -79,6 +79,12 @@ static char *realpath (const char *pathname, char *resolved_path) } #endif

+/** + Given a file name, returns a newly allocated string containing the realpath() + of the file. + @param file_name The original file_name + @return A newly allocated string containing the real path to the file. NULL if none is available. +*/ gchar *tm_get_real_path(const gchar *file_name) { if (file_name) @@ -94,6 +100,7 @@ gchar *tm_get_real_path(const gchar *file_name) return NULL; }

+/* Initializes a TMSourceFile structure from a file name. */ gboolean tm_source_file_init(TMSourceFile *source_file, const char *file_name , gboolean update, const char* name) { @@ -147,6 +154,12 @@ gboolean tm_source_file_init(TMSourceFile *source_file, const char *file_name return TRUE; }

+/** Initializes a TMSourceFile structure and returns a pointer to it. + * @param file_name The file name. + * @param update Update the tag array of the file. + * @param name Name of the used programming language, NULL for autodetection. + * @return The created TMSourceFile object. + * */ TMSourceFile *tm_source_file_new(const char *file_name, gboolean update, const char *name) { TMSourceFile *source_file = g_new(TMSourceFile, 1); @@ -158,6 +171,10 @@ TMSourceFile *tm_source_file_new(const char *file_name, gboolean update, const c return source_file; }

+/* Destroys the contents of the source file. Note that the tags are owned by the + source file and are also destroyed when the source file is destroyed. If pointers + to these tags are used elsewhere, then those tag arrays should be rebuilt. +*/ void tm_source_file_destroy(TMSourceFile *source_file) { #ifdef TM_DEBUG @@ -172,6 +189,7 @@ void tm_source_file_destroy(TMSourceFile *source_file) } }

+/** Frees a TMSourceFile structure, including all contents */ void tm_source_file_free(TMSourceFile *source_file) { if (NULL != source_file) @@ -181,6 +199,11 @@ void tm_source_file_free(TMSourceFile *source_file) } }

+/* Parses the source file and regenarates the tags. + @param source_file The source file to parse + @return TRUE on success, FALSE on failure + @see tm_source_file_update() +*/ gboolean tm_source_file_parse(TMSourceFile *source_file) { const char *file_name; @@ -237,6 +260,13 @@ gboolean tm_source_file_parse(TMSourceFile *source_file) return status; }

+/* Parses the text-buffer and regenarates the tags. + @param source_file The source file to parse + @param text_buf The text buffer to parse + @param buf_size The size of text_buf. + @return TRUE on success, FALSE on failure + @see tm_source_file_update() +*/ gboolean tm_source_file_buffer_parse(TMSourceFile *source_file, guchar* text_buf, gint buf_size) { const char *file_name; @@ -309,6 +339,7 @@ gboolean tm_source_file_buffer_parse(TMSourceFile *source_file, guchar* text_buf return status; }

+/* Set the argument list of tag identified by its name */ void tm_source_file_set_tag_arglist(const char *tag_name, const char *arglist) { int count; @@ -332,6 +363,12 @@ void tm_source_file_set_tag_arglist(const char *tag_name, const char *arglist) } }

+/* + This function is registered into the ctags parser when a file is parsed for + the first time. The function is then called by the ctags parser each time + it finds a new tag. You should not have to use this function. + @see tm_source_file_parse() +*/ int tm_source_file_tags(const tagEntryInfo *tag) { if (NULL == current_source_file) @@ -343,6 +380,15 @@ int tm_source_file_tags(const tagEntryInfo *tag) return TRUE; }

+/** Updates the source file by reparsing. The tags array and + the tags themselves are destroyed and re-created, hence any other tag arrays + pointing to these tags should be rebuilt as well. All sorting information is + also lost. The language parameter is automatically set the first time the file + is parsed. + @param source_file The source file to update. + @param update_workspace If set to TRUE, sends an update signal to the workspace if required. You should + always set this to TRUE if you are calling this function directly. +*/ void tm_source_file_update(TMSourceFile *source_file, gboolean update_workspace) { #ifdef TM_DEBUG @@ -373,6 +419,22 @@ void tm_source_file_update(TMSourceFile *source_file, gboolean update_workspace) }

+/* Updates the source file by reparsing the text-buffer passed as parameter. + Ctags will use a parsing based on buffer instead of on files. + You should call this function when you don't want a previous saving of the file + you're editing. It's useful for a "real-time" updating of the tags. + The tags array and the tags themselves are destroyed and re-created, hence any + other tag arrays pointing to these tags should be rebuilt as well. All sorting + information is also lost. The language parameter is automatically set the first + time the file is parsed. + @param source_file The source file to update with a buffer. + @param text_buf A text buffer. The user should take care of allocate and free it after + the use here. + @param buf_size The size of text_buf. + @param update_workspace If set to TRUE, sends an update signal to the workspace if required. You should + always set this to TRUE if you are calling this function directly. + @return TRUE if the file was parsed, FALSE otherwise. +*/ void tm_source_file_buffer_update(TMSourceFile *source_file, guchar* text_buf, gint buf_size, gboolean update_workspace) { @@ -404,6 +466,14 @@ void tm_source_file_buffer_update(TMSourceFile *source_file, guchar* text_buf, }

+/* + Writes all tags of a source file (including the file tag itself) to the passed + file pointer. + @param source_file The source file to write. + @param fp The file pointer to write to. + @param attrs The attributes to write. + @return TRUE on success, FALSE on failure. +*/ gboolean tm_source_file_write(TMSourceFile *source_file, FILE *fp, guint attrs) { TMTag *tag; @@ -429,6 +499,10 @@ gboolean tm_source_file_write(TMSourceFile *source_file, FILE *fp, guint attrs) return TRUE; }

+/* Gets the name associated with the language index. + @param lang The language index. + @return The language name, or NULL. +*/ const gchar *tm_source_file_get_lang_name(gint lang) { if (NULL == LanguageTable) @@ -443,6 +517,10 @@ const gchar *tm_source_file_get_lang_name(gint lang) return getLanguageName(lang); }

+/* Gets the language index for \a name. + @param name The language name. + @return The language index, or -2. +*/ gint tm_source_file_get_named_lang(const gchar *name) { if (NULL == LanguageTable)

Modified: tagmanager/src/tm_source_file.h 79 lines changed, 0 insertions(+), 79 deletions(-) =================================================================== @@ -44,116 +44,37 @@ typedef struct GPtrArray *tags_array; /**< Tags obtained by parsing the object */ } TMSourceFile;

-/** Initializes a TMSourceFile structure and returns a pointer to it. - * @param file_name The file name. - * @param update Update the tag array of the file. - * @param name Name of the used programming language, NULL for autodetection. - * @return The created TMSourceFile object. - * */ TMSourceFile *tm_source_file_new(const char *file_name, gboolean update, const char *name);

-/** Updates the source file by reparsing. The tags array and - the tags themselves are destroyed and re-created, hence any other tag arrays - pointing to these tags should be rebuilt as well. All sorting information is - also lost. The language parameter is automatically set the first time the file - is parsed. - @param source_file The source file to update. - @param update_workspace If set to TRUE, sends an update signal to the workspace if required. You should - always set this to TRUE if you are calling this function directly. -*/ void tm_source_file_update(TMSourceFile *source_file, gboolean update_workspace);

-/** Frees a TMSourceFile structure, including all contents */ void tm_source_file_free(TMSourceFile *source_file);

-/** - Given a file name, returns a newly allocated string containing the realpath() - of the file. - @param file_name The original file_name - @return A newly allocated string containing the real path to the file. NULL if none is available. -*/ gchar *tm_get_real_path(const gchar *file_name);

#ifdef GEANY_PRIVATE

-/* Initializes a TMSourceFile structure from a file name. */ gboolean tm_source_file_init(TMSourceFile *source_file, const char *file_name, gboolean update, const char *name);

-/* Destroys the contents of the source file. Note that the tags are owned by the - source file and are also destroyed when the source file is destroyed. If pointers - to these tags are used elsewhere, then those tag arrays should be rebuilt. -*/ void tm_source_file_destroy(TMSourceFile *source_file);

-/* Updates the source file by reparsing the text-buffer passed as parameter. - Ctags will use a parsing based on buffer instead of on files. - You should call this function when you don't want a previous saving of the file - you're editing. It's useful for a "real-time" updating of the tags. - The tags array and the tags themselves are destroyed and re-created, hence any - other tag arrays pointing to these tags should be rebuilt as well. All sorting - information is also lost. The language parameter is automatically set the first - time the file is parsed. - @param source_file The source file to update with a buffer. - @param text_buf A text buffer. The user should take care of allocate and free it after - the use here. - @param buf_size The size of text_buf. - @param update_workspace If set to TRUE, sends an update signal to the workspace if required. You should - always set this to TRUE if you are calling this function directly. - @return TRUE if the file was parsed, FALSE otherwise. -*/ void tm_source_file_buffer_update(TMSourceFile *source_file, guchar* text_buf, gint buf_size, gboolean update_workspace);

-/* Parses the source file and regenarates the tags. - @param source_file The source file to parse - @return TRUE on success, FALSE on failure - @see tm_source_file_update() -*/ gboolean tm_source_file_parse(TMSourceFile *source_file);

-/* Parses the text-buffer and regenarates the tags. - @param source_file The source file to parse - @param text_buf The text buffer to parse - @param buf_size The size of text_buf. - @return TRUE on success, FALSE on failure - @see tm_source_file_update() -*/ gboolean tm_source_file_buffer_parse(TMSourceFile *source_file, guchar* text_buf, gint buf_size);

-/* - This function is registered into the ctags parser when a file is parsed for - the first time. The function is then called by the ctags parser each time - it finds a new tag. You should not have to use this function. - @see tm_source_file_parse() -*/ int tm_source_file_tags(const tagEntryInfo *tag);

-/* - Writes all tags of a source file (including the file tag itself) to the passed - file pointer. - @param source_file The source file to write. - @param fp The file pointer to write to. - @param attrs The attributes to write. - @return TRUE on success, FALSE on failure. -*/ gboolean tm_source_file_write(TMSourceFile *source_file, FILE *fp, guint attrs);

- -/* Gets the name associated with the language index. - @param lang The language index. - @return The language name, or NULL. -*/ const gchar *tm_source_file_get_lang_name(gint lang);

-/* Gets the language index for \a name. - @param name The language name. - @return The language index, or -2. -*/ gint tm_source_file_get_named_lang(const gchar *name);

-/* Set the argument list of tag identified by its name */ void tm_source_file_set_tag_arglist(const char *tag_name, const char *arglist);

#endif /* GEANY_PRIVATE */

Modified: tagmanager/src/tm_tag.c 154 lines changed, 153 insertions(+), 1 deletions(-) =================================================================== @@ -144,6 +144,7 @@ static int s_tag_types[] = { tm_tag_other_t };

+/* Gets the GType for a TMTag */ GType tm_tag_get_type(void) { static GType gtype = 0; @@ -208,6 +209,16 @@ static char get_tag_access(const char *access) return TAG_ACCESS_UNKNOWN; }

+/* + Initializes a TMTag structure with information from a tagEntryInfo struct + used by the ctags parsers. Note that the TMTag structure must be malloc()ed + before calling this function. This function is called by tm_tag_new() - you + should not need to call this directly. + @param tag The TMTag structure to initialize + @param file Pointer to a TMSourceFile struct (it is assigned to the file member) + @param tag_entry Tag information gathered by the ctags parser + @return TRUE on success, FALSE on failure +*/ gboolean tm_tag_init(TMTag *tag, TMSourceFile *file, const tagEntryInfo *tag_entry) { tag->refcount = 1; @@ -256,6 +267,13 @@ gboolean tm_tag_init(TMTag *tag, TMSourceFile *file, const tagEntryInfo *tag_ent } }

+/* + Creates a new tag structure from a tagEntryInfo pointer and a TMSOurceFile pointer + and returns a pointer to it. + @param file - Pointer to the TMSourceFile structure containing the tag + @param tag_entry Contains tag information generated by ctags + @return the new TMTag structure. This should be free()-ed using tm_tag_free() +*/ TMTag *tm_tag_new(TMSourceFile *file, const tagEntryInfo *tag_entry) { TMTag *tag; @@ -269,6 +287,14 @@ TMTag *tm_tag_new(TMSourceFile *file, const tagEntryInfo *tag_entry) return tag; }

+/* + Initializes an already malloc()ed TMTag structure by reading a tag entry + line from a file. The structure should be allocated beforehand. + @param tag The TMTag structure to populate + @param file The TMSourceFile struct (assigned to the file member) + @param fp FILE pointer from where the tag line is read + @return TRUE on success, FALSE on FAILURE +*/ gboolean tm_tag_init_from_file(TMTag *tag, TMSourceFile *file, FILE *fp) { guchar buf[BUFSIZ]; @@ -409,7 +435,10 @@ gboolean tm_tag_init_from_file_alt(TMTag *tag, TMSourceFile *file, FILE *fp) return TRUE; }

-/* Reads ctags format (http://ctags.sourceforge.net/FORMAT) */ +/* + Same as tm_tag_init_from_file(), but parsing CTags tag file format + (http://ctags.sourceforge.net/FORMAT) +*/ gboolean tm_tag_init_from_file_ctags(TMTag *tag, TMSourceFile *file, FILE *fp) { gchar buf[BUFSIZ]; @@ -551,6 +580,10 @@ gboolean tm_tag_init_from_file_ctags(TMTag *tag, TMSourceFile *file, FILE *fp) return TRUE; }

+/* + Same as tm_tag_new() except that the tag attributes are read from file. + @param mode langType to use for the tag. +*/ TMTag *tm_tag_new_from_file(TMSourceFile *file, FILE *fp, gint mode, TMFileFormat format) { TMTag *tag; @@ -580,6 +613,13 @@ TMTag *tm_tag_new_from_file(TMSourceFile *file, FILE *fp, gint mode, TMFileForma return tag; }

+/* + Writes tag information to the given FILE *. + @param tag The tag information to write. + @param file FILE pointer to which the tag information is written. + @param attrs Attributes to be written (bitmask). + @return TRUE on success, FALSE on failure. +*/ gboolean tm_tag_write(TMTag *tag, FILE *fp, guint attrs) { fprintf(fp, "%s", tag->name); @@ -619,6 +659,11 @@ gboolean tm_tag_write(TMTag *tag, FILE *fp, guint attrs) return FALSE; }

+/* + Destroys a TMTag structure, i.e. frees all elements except the tag itself. + @param tag The TMTag structure to destroy + @see tm_tag_free() +*/ static void tm_tag_destroy(TMTag *tag) { g_free(tag->name); @@ -632,12 +677,21 @@ static void tm_tag_destroy(TMTag *tag) }

#if 0 +/* + Destroys all data in the tag and frees the tag structure as well. + @param tag Pointer to a TMTag structure +*/ void tm_tag_free(gpointer tag) { tm_tag_unref(tag); } #endif

+/* + Drops a reference from a TMTag. If the reference count reaches 0, this function + destroys all data in the tag and frees the tag structure as well. + @param tag Pointer to a TMTag structure +*/ void tm_tag_unref(TMTag *tag) { /* be NULL-proof because tm_tag_free() was NULL-proof and we indent to be a @@ -649,12 +703,22 @@ void tm_tag_unref(TMTag *tag) } }

+/* + Adds a reference to a TMTag. + @param tag Pointer to a TMTag structure + @return the passed-in TMTag +*/ TMTag *tm_tag_ref(TMTag *tag) { g_atomic_int_inc(&tag->refcount); return tag; }

+/* + Inbuilt tag comparison function. Do not call directly since it needs some + static variables to be set. Always use tm_tags_sort() and tm_tags_dedup() + instead. +*/ int tm_tag_compare(const void *ptr1, const void *ptr2) { unsigned int *sort_attr; @@ -720,6 +784,12 @@ int tm_tag_compare(const void *ptr1, const void *ptr2) return returnval; }

+/* + Removes NULL tag entries from an array of tags. Called after tm_tags_dedup() and + tm_tags_custom_dedup() since these functions substitute duplicate entries with NULL + @param tags_array Array of tags to dedup + @return TRUE on success, FALSE on failure +*/ gboolean tm_tags_prune(GPtrArray *tags_array) { guint i, count; @@ -732,6 +802,14 @@ gboolean tm_tags_prune(GPtrArray *tags_array) return TRUE; }

+/* + Deduplicates an array on tags using the inbuilt comparison function based on + the attributes specified. Called by tm_tags_sort() when dedup is TRUE. + @param tags_array Array of tags to dedup. + @param sort_attributes Attributes the array is sorted on. They will be deduped + on the same criteria. + @return TRUE on success, FALSE on failure +*/ gboolean tm_tags_dedup(GPtrArray *tags_array, TMTagAttrType *sort_attributes) { guint i; @@ -751,6 +829,14 @@ gboolean tm_tags_dedup(GPtrArray *tags_array, TMTagAttrType *sort_attributes) return TRUE; }

+/* + This is a more powerful form of tm_tags_dedup() since it can accomodate user + defined comparison functions. Called by tm_tags_custom_sort() is dedup is TRUE. + @param tags_array Array of tags to dedup. + @param compare_func Comparison function + @return TRUE on success, FALSE on FAILURE + @see TMTagCompareFunc +*/ gboolean tm_tags_custom_dedup(GPtrArray *tags_array, TMTagCompareFunc compare_func) { guint i; @@ -812,6 +898,14 @@ gboolean tm_tags_merge(GPtrArray *tags_array, gsize orig_len, return TRUE; }

+/* + Sort an array of tags on the specified attribuites using the inbuilt comparison + function. + @param tags_array The array of tags to be sorted + @param sort_attributes Attributes to be sorted on (int array terminated by 0) + @param dedup Whether to deduplicate the sorted array + @return TRUE on success, FALSE on failure +*/ gboolean tm_tags_sort(GPtrArray *tags_array, TMTagAttrType *sort_attributes, gboolean dedup) { if ((!tags_array) || (!tags_array->len)) @@ -938,6 +1032,18 @@ GPtrArray *tm_tags_merge_big_small(GPtrArray *big_array, GPtrArray *small_array, return res_array; }

+/* + This function should be used whenever more involved sorting is required. For this, + you need to write a function as per the prototype of TMTagCompareFunc() and pass + the function as a parameter to this function. + @param tags_array Array of tags to be sorted + @param compare_func A function which takes two pointers to (TMTag *)s and returns + 0, 1 or -1 depending on whether the first value is equal to, greater than or less that + the second + @param dedup Whether to deduplicate the sorted array. Note that the same comparison + function will be used + @return TRUE on success, FALSE on failure +*/ gboolean tm_tags_custom_sort(GPtrArray *tags_array, TMTagCompareFunc compare_func, gboolean dedup) { if ((!tags_array) || (!tags_array->len)) @@ -948,6 +1054,17 @@ gboolean tm_tags_custom_sort(GPtrArray *tags_array, TMTagCompareFunc compare_fun return TRUE; }

+/* + This function will extract the tags of the specified types from an array of tags. + The returned value is a GPtrArray which should be free-d with a call to + g_ptr_array_free(array, TRUE). However, do not free the tags themselves since they + are not duplicated. + @param tags_array The original array of tags + @param tag_types - The tag types to extract. Can be a bitmask. For example, passing + (tm_tag_typedef_t | tm_tag_struct_t) will extract all typedefs and structures from + the original array. + @return an array of tags (NULL on failure) +*/ GPtrArray *tm_tags_extract(GPtrArray *tags_array, guint tag_types) { GPtrArray *new_tags; @@ -966,6 +1083,11 @@ GPtrArray *tm_tags_extract(GPtrArray *tags_array, guint tag_types) return new_tags; }

+/* + Completely frees an array of tags. + @param tags_array Array of tags to be freed. + @param free_array Whether the GptrArray is to be freed as well. +*/ void tm_tags_array_free(GPtrArray *tags_array, gboolean free_all) { if (tags_array) @@ -1003,6 +1125,17 @@ static TMTag **tags_search(const GPtrArray *tags_array, TMTag *tag, gboolean par return NULL; }

+/* + Returns a pointer to the position of the first matching tag in a (sorted) tags array. + The passed array of tags should be already sorted by name for optimal performance. If + \c tags_array_sorted is set to FALSE, it may be unsorted but the lookup will be slower. + @param tags_array Tag array (may be sorted on name) + @param name Name of the tag to locate. + @param partial If TRUE, matches the first part of the name instead of doing exact match. + @param tags_array_sorted If TRUE, the passed \c tags_array is sorted by name so it can be + searched with binary search. Otherwise it is searched linear which is obviously slower. + @param tagCount Return location of the matched tags. +*/ TMTag **tm_tags_find(const GPtrArray *tags_array, const char *name, gboolean partial, gboolean tags_array_sorted, int * tagCount) { @@ -1049,6 +1182,10 @@ TMTag **tm_tags_find(const GPtrArray *tags_array, const char *name, return (TMTag **) result; }

+/* + Returns the type of tag as a string + @param tag The tag whose type is required +*/ const char *tm_tag_type_name(const TMTag *tag) { g_return_val_if_fail(tag, NULL); @@ -1078,6 +1215,10 @@ const char *tm_tag_type_name(const TMTag *tag) return NULL; }

+/* + Returns the TMTagType given the name of the type. Reverse of tm_tag_type_name. + @param tag_name Name of the tag type +*/ TMTagType tm_tag_name_type(const char* tag_name) { g_return_val_if_fail(tag_name, tm_tag_undef_t); @@ -1126,6 +1267,11 @@ static const char *tm_tag_access_name(TMTag *tag) return NULL; }

+/* + Prints information about a tag to the given file pointer. + @param tag The tag whose info is required. + @param fp The file pointer of teh file to print the info to. +*/ void tm_tag_print(TMTag *tag, FILE *fp) { const char *laccess, *impl, *type; @@ -1160,6 +1306,9 @@ void tm_tag_print(TMTag *tag, FILE *fp) fprintf(fp, "\n"); }

+/* + Prints info about all tags in the array to the given file pointer. +*/ void tm_tags_array_print(GPtrArray *tags, FILE *fp) { guint i; @@ -1173,6 +1322,9 @@ void tm_tags_array_print(GPtrArray *tags, FILE *fp) } }

+/* + Returns the depth of tag scope (useful for finding tag hierarchy +*/ gint tm_tag_scope_depth(const TMTag *t) { gint depth;

Modified: tagmanager/src/tm_tag.h 156 lines changed, 0 insertions(+), 156 deletions(-) =================================================================== @@ -171,71 +171,22 @@ typedef int (*TMTagCompareFunc) (const void *ptr1, const void *ptr2); /* The GType for a TMTag */ #define TM_TYPE_TAG (tm_tag_get_type())

-/* Gets the GType for a TMTag */ GType tm_tag_get_type(void) G_GNUC_CONST;

-/* - Initializes a TMTag structure with information from a tagEntryInfo struct - used by the ctags parsers. Note that the TMTag structure must be malloc()ed - before calling this function. This function is called by tm_tag_new() - you - should not need to call this directly. - @param tag The TMTag structure to initialize - @param file Pointer to a TMSourceFile struct (it is assigned to the file member) - @param tag_entry Tag information gathered by the ctags parser - @return TRUE on success, FALSE on failure -*/ gboolean tm_tag_init(TMTag *tag, TMSourceFile *file, const tagEntryInfo *tag_entry);

-/* - Initializes an already malloc()ed TMTag structure by reading a tag entry - line from a file. The structure should be allocated beforehand. - @param tag The TMTag structure to populate - @param file The TMSourceFile struct (assigned to the file member) - @param fp FILE pointer from where the tag line is read - @return TRUE on success, FALSE on FAILURE -*/ gboolean tm_tag_init_from_file(TMTag *tag, TMSourceFile *file, FILE *fp);

-/* - Same as tm_tag_init_from_file(), but using an alternative parser for PHP and - LaTeX global tags files. -*/ gboolean tm_tag_init_from_file_alt(TMTag *tag, TMSourceFile *file, FILE *fp);

-/* - Same as tm_tag_init_from_file(), but parsing CTags tag file format -*/ gboolean tm_tag_init_from_file_ctags(TMTag *tag, TMSourceFile *file, FILE *fp);

-/* - Creates a new tag structure from a tagEntryInfo pointer and a TMSOurceFile pointer - and returns a pointer to it. - @param file - Pointer to the TMSourceFile structure containing the tag - @param tag_entry Contains tag information generated by ctags - @return the new TMTag structure. This should be free()-ed using tm_tag_free() -*/ TMTag *tm_tag_new(TMSourceFile *file, const tagEntryInfo *tag_entry);

-/* - Same as tm_tag_new() except that the tag attributes are read from file. - @param mode langType to use for the tag. -*/ TMTag *tm_tag_new_from_file(TMSourceFile *file, FILE *fp, gint mode, TMFileFormat format);

-/* - Writes tag information to the given FILE *. - @param tag The tag information to write. - @param file FILE pointer to which the tag information is written. - @param attrs Attributes to be written (bitmask). - @return TRUE on success, FALSE on failure. -*/ gboolean tm_tag_write(TMTag *tag, FILE *file, guint attrs);

-/* - Inbuilt tag comparison function. Do not call directly since it needs some - static variables to be set. Always use tm_tags_sort() and tm_tags_dedup() - instead. -*/ int tm_tag_compare(const void *ptr1, const void *ptr2);

gboolean tm_tags_merge(GPtrArray *tags_array, gsize orig_len, @@ -245,148 +196,41 @@ GPtrArray *tm_tags_remove_file_tags(TMSourceFile *source_file, GPtrArray *tags_a

GPtrArray *tm_tags_merge_big_small(GPtrArray *big_array, GPtrArray *small_array, TMTagAttrType *sort_attributes);

-/* - Sort an array of tags on the specified attribuites using the inbuilt comparison - function. - @param tags_array The array of tags to be sorted - @param sort_attributes Attributes to be sorted on (int array terminated by 0) - @param dedup Whether to deduplicate the sorted array - @return TRUE on success, FALSE on failure -*/ gboolean tm_tags_sort(GPtrArray *tags_array, TMTagAttrType *sort_attributes, gboolean dedup);

-/* - This function should be used whenever more involved sorting is required. For this, - you need to write a function as per the prototype of TMTagCompareFunc() and pass - the function as a parameter to this function. - @param tags_array Array of tags to be sorted - @param compare_func A function which takes two pointers to (TMTag *)s and returns - 0, 1 or -1 depending on whether the first value is equal to, greater than or less that - the second - @param dedup Whether to deduplicate the sorted array. Note that the same comparison - function will be used - @return TRUE on success, FALSE on failure -*/ gboolean tm_tags_custom_sort(GPtrArray *tags_array, TMTagCompareFunc compare_func, gboolean dedup);

-/* - This function will extract the tags of the specified types from an array of tags. - The returned value is a GPtrArray which should be free-d with a call to - g_ptr_array_free(array, TRUE). However, do not free the tags themselves since they - are not duplicated. - @param tags_array The original array of tags - @param tag_types - The tag types to extract. Can be a bitmask. For example, passing - (tm_tag_typedef_t | tm_tag_struct_t) will extract all typedefs and structures from - the original array. - @return an array of tags (NULL on failure) -*/ GPtrArray *tm_tags_extract(GPtrArray *tags_array, guint tag_types);

-/* - Removes NULL tag entries from an array of tags. Called after tm_tags_dedup() and - tm_tags_custom_dedup() since these functions substitute duplicate entries with NULL - @param tags_array Array of tags to dedup - @return TRUE on success, FALSE on failure -*/ gboolean tm_tags_prune(GPtrArray *tags_array);

-/* - Deduplicates an array on tags using the inbuilt comparison function based on - the attributes specified. Called by tm_tags_sort() when dedup is TRUE. - @param tags_array Array of tags to dedup. - @param sort_attributes Attributes the array is sorted on. They will be deduped - on the same criteria. - @return TRUE on success, FALSE on failure -*/ gboolean tm_tags_dedup(GPtrArray *tags_array, TMTagAttrType *sort_attributes);

-/* - This is a more powerful form of tm_tags_dedup() since it can accomodate user - defined comparison functions. Called by tm_tags_custom_sort() is dedup is TRUE. - @param tags_array Array of tags to dedup. - @param compare_func Comparison function - @return TRUE on success, FALSE on FAILURE - @see TMTagCompareFunc -*/ gboolean tm_tags_custom_dedup(GPtrArray *tags_array, TMTagCompareFunc compare_func);

-/* - Returns a pointer to the position of the first matching tag in a (sorted) tags array. - The passed array of tags should be already sorted by name for optimal performance. If - \c tags_array_sorted is set to FALSE, it may be unsorted but the lookup will be slower. - @param tags_array Tag array (may be sorted on name) - @param name Name of the tag to locate. - @param partial If TRUE, matches the first part of the name instead of doing exact match. - @param tags_array_sorted If TRUE, the passed \c tags_array is sorted by name so it can be - searched with binary search. Otherwise it is searched linear which is obviously slower. - @param tagCount Return location of the matched tags. -*/ TMTag **tm_tags_find(const GPtrArray *tags_array, const char *name, gboolean partial, gboolean tags_array_sorted, int * tagCount);

-/* - Completely frees an array of tags. - @param tags_array Array of tags to be freed. - @param free_array Whether the GptrArray is to be freed as well. -*/ void tm_tags_array_free(GPtrArray *tags_array, gboolean free_all);

#if 0 -/* - Destroys a TMTag structure, i.e. frees all elements except the tag itself. - @param tag The TMTag structure to destroy - @see tm_tag_free() -*/ void tm_tag_destroy(TMTag *tag);

-/* - Destroys all data in the tag and frees the tag structure as well. - @param tag Pointer to a TMTag structure -*/ void tm_tag_free(gpointer tag); #endif

-/* - Drops a reference from a TMTag. If the reference count reaches 0, this function - destroys all data in the tag and frees the tag structure as well. - @param tag Pointer to a TMTag structure -*/ void tm_tag_unref(TMTag *tag);

-/* - Adds a reference to a TMTag. - @param tag Pointer to a TMTag structure - @return the passed-in TMTag -*/ TMTag *tm_tag_ref(TMTag *tag);

-/* - Returns the type of tag as a string - @param tag The tag whose type is required -*/ const char *tm_tag_type_name(const TMTag *tag);

-/* - Returns the TMTagType given the name of the type. Reverse of tm_tag_type_name. - @param tag_name Name of the tag type -*/ TMTagType tm_tag_name_type(const char* tag_name);

-/* - Prints information about a tag to the given file pointer. - @param tag The tag whose info is required. - @param fp The file pointer of teh file to print the info to. -*/ void tm_tag_print(TMTag *tag, FILE *fp);

-/* - Prints info about all tags in the array to the given file pointer. -*/ void tm_tags_array_print(GPtrArray *tags, FILE *fp);

-/* - Returns the depth of tag scope (useful for finding tag hierarchy -*/ gint tm_tag_scope_depth(const TMTag *t);

#endif /* GEANY_PRIVATE */

Modified: tagmanager/src/tm_workspace.c 80 lines changed, 79 insertions(+), 1 deletions(-) =================================================================== @@ -47,6 +47,9 @@ static gboolean tm_create_workspace(void) return TRUE; }

+/* Frees the workspace structure and all child source files. Use only when + exiting from the main program. +*/ void tm_workspace_free(void) { guint i; @@ -76,6 +79,12 @@ void tm_workspace_free(void) } }

+/* Since TMWorkspace is a singleton, you should not create multiple + workspaces, but get a pointer to the workspace whenever required. The first + time a pointer is requested, or a source file is added to the workspace, + a workspace is created. Subsequent calls to the function will return the + created workspace. +*/ const TMWorkspace *tm_get_workspace(void) { if (NULL == theWorkspace) @@ -83,6 +92,10 @@ const TMWorkspace *tm_get_workspace(void) return theWorkspace; }

+/** Adds a source file to the workspace. + @param source_file The source file to add to the workspace. + @return TRUE on success, FALSE on failure (e.g. object already exixts). +*/ gboolean tm_workspace_add_source_file(TMSourceFile *source_file) { /* theWorkspace should already have been created otherwise something went wrong */ @@ -94,6 +107,12 @@ gboolean tm_workspace_add_source_file(TMSourceFile *source_file) return TRUE; }

+/** Removes a member object from the workspace if it exists. + @param source_file Pointer to the source file to be removed. + @param do_free Whether the source file is to be freed as well. + @param update Whether to update workspace objects. + @return TRUE on success, FALSE on failure (e.g. the source file does not exist). +*/ gboolean tm_workspace_remove_source_file(TMSourceFile *source_file, gboolean do_free, gboolean update) { guint i; @@ -124,6 +143,12 @@ static TMTagAttrType global_tags_sort_attrs[] = tm_tag_attr_type_t, tm_tag_attr_arglist_t, 0 };

+/* Loads the global tag list from the specified file. The global tag list should + have been first created using tm_workspace_create_global_tags(). + @param tags_file The file containing global tags. + @return TRUE on success, FALSE on failure. + @see tm_workspace_create_global_tags() +*/ gboolean tm_workspace_load_global_tags(const char *tags_file, gint mode) { gsize orig_len; @@ -265,6 +290,17 @@ static gchar *create_temp_file(const gchar *tpl) return name; }

+/* Creates a list of global tags. Ideally, this should be created once during + installations so that all users can use the same file. Thsi is because a full + scale global tag list can occupy several megabytes of disk space. + @param pre_process The pre-processing command. This is executed via system(), + so you can pass stuff like 'gcc -E -dD -P `gnome-config --cflags gnome`'. + @param includes Include files to process. Wildcards such as '/usr/include/a*.h' + are allowed. + @param tags_file The file where the tags will be stored. + @param lang The language to use for the tags file. + @return TRUE on success, FALSE on failure. +*/ gboolean tm_workspace_create_global_tags(const char *pre_process, const char **includes, int includes_count, const char *tags_file, int lang) { @@ -447,6 +483,10 @@ gboolean tm_workspace_create_global_tags(const char *pre_process, const char **i return TRUE; }

+/* Recreates the tag array of the workspace by collecting the tags of + all member source files. You shouldn't have to call this directly since + this is called automatically by tm_workspace_update(). +*/ void tm_workspace_recreate_tags_array(void) { guint i, j; @@ -513,6 +553,9 @@ void tm_workspace_merge_file_tags(TMSourceFile *source_file) } }

+/** Calls tm_source_file_update() for all workspace member source files and creates + workspace tag array. Use if you want to globally refresh the workspace. +*/ void tm_workspace_update(void) { #ifdef TM_DEBUG @@ -524,6 +567,7 @@ void tm_workspace_update(void) tm_workspace_recreate_tags_array(); }

+/* Dumps the workspace tree - useful for debugging */ void tm_workspace_dump(void) { if (theWorkspace) @@ -543,6 +587,15 @@ void tm_workspace_dump(void) } }

+/* Returns all matching tags found in the workspace. + @param name The name of the tag to find. + @param type The tag types to return (TMTagType). Can be a bitmask. + @param attrs The attributes to sort and dedup on (0 terminated integer array). + @param partial Whether partial match is allowed. + @param lang Specifies the language(see the table in parsers.h) of the tags to be found, + -1 for all + @return Array of matching tags. Do not free() it since it is a static member. +*/ const GPtrArray *tm_workspace_find(const char *name, int type, TMTagAttrType *attrs , gboolean partial, langType lang) { @@ -680,7 +733,16 @@ fill_find_tags_array (GPtrArray *dst, const GPtrArray *src, }

-/* adapted from tm_workspace_find, Anjuta 2.02 */ +/* Returns all matching tags found in the workspace. Adapted from tm_workspace_find, Anjuta 2.02 + @param name The name of the tag to find. + @param scope The scope name of the tag to find, or NULL. + @param type The tag types to return (TMTagType). Can be a bitmask. + @param attrs The attributes to sort and dedup on (0 terminated integer array). + @param partial Whether partial match is allowed. + @param lang Specifies the language(see the table in parsers.h) of the tags to be found, + -1 for all + @return Array of matching tags. Do not free() it since it is a static member. +*/ const GPtrArray * tm_workspace_find_scoped (const char *name, const char *scope, gint type, TMTagAttrType *attrs, gboolean partial, langType lang, gboolean global_search) @@ -709,6 +771,11 @@ tm_workspace_find_scoped (const char *name, const char *scope, gint type, }

+/* Returns TMTag which "own" given line + @param line Current line in edited file. + @param file_tags A GPtrArray of edited file TMTag pointers. + @param tag_types the tag types to include in the match + @return TMTag pointers to owner tag. */ const TMTag * tm_get_current_tag (GPtrArray * file_tags, const gulong line, const guint tag_types) { @@ -733,6 +800,10 @@ tm_get_current_tag (GPtrArray * file_tags, const gulong line, const guint tag_ty }

+/* Returns TMTag to function or method which "own" given line + @param line Current line in edited file. + @param file_tags A GPtrArray of edited file TMTag pointers. + @return TMTag pointers to owner function. */ const TMTag * tm_get_current_function (GPtrArray * file_tags, const gulong line) { @@ -1059,6 +1130,10 @@ tm_workspace_find_namespace_members (const GPtrArray * file_tags, const char *na } #endif

+/* Returns all matching members tags found in given struct/union/class name. + @param name Name of the struct/union/class. + @param file_tags A GPtrArray of edited file TMTag pointers (for search speedup, can be NULL). + @return A GPtrArray of TMTag pointers to struct/union/class members */ const GPtrArray * tm_workspace_find_scope_members (const GPtrArray * file_tags, const char *name, gboolean search_global, gboolean no_definitions) @@ -1195,6 +1270,9 @@ tm_workspace_find_scope_members (const GPtrArray * file_tags, const char *name, return tags; }

+/* Returns a list of parent classes for the given class name + @param name Name of the class + @return A GPtrArray of TMTag pointers (includes the TMTag for the class) */ const GPtrArray *tm_workspace_get_parents(const gchar *name) { static TMTagAttrType type[] = { tm_tag_attr_name_t, tm_tag_attr_none_t };

Modified: tagmanager/src/tm_workspace.h 83 lines changed, 1 insertions(+), 82 deletions(-) =================================================================== @@ -34,99 +34,33 @@ typedef struct (just pointers to source file tags, the tag objects are owned by the source files) */ } TMWorkspace;

-/** Adds a source file to the workspace. - @param source_file The source file to add to the workspace. - @return TRUE on success, FALSE on failure (e.g. object already exixts). -*/ gboolean tm_workspace_add_source_file(TMSourceFile *source_file);

-/** Removes a member object from the workspace if it exists. - @param source_file Pointer to the source file to be removed. - @param do_free Whether the source file is to be freed as well. - @param update Whether to update workspace objects. - @return TRUE on success, FALSE on failure (e.g. the source file does not exist). -*/ gboolean tm_workspace_remove_source_file(TMSourceFile *source_file, gboolean do_free, gboolean update);

-/** Calls tm_source_file_update() for all workspace member source files and creates - workspace tag array. Use if you want to globally refresh the workspace. -*/ void tm_workspace_update(void);

#ifdef GEANY_PRIVATE

-/* Since TMWorkspace is a singleton, you should not create multiple - workspaces, but get a pointer to the workspace whenever required. The first - time a pointer is requested, or a source file is added to the workspace, - a workspace is created. Subsequent calls to the function will return the - created workspace. -*/ const TMWorkspace *tm_get_workspace(void);

- -/* Loads the global tag list from the specified file. The global tag list should - have been first created using tm_workspace_create_global_tags(). - @param tags_file The file containing global tags. - @return TRUE on success, FALSE on failure. - @see tm_workspace_create_global_tags() -*/ gboolean tm_workspace_load_global_tags(const char *tags_file, gint mode); -/*gboolean tm_workspace_load_global_tags(const char *tags_file);*/ - -/* Creates a list of global tags. Ideally, this should be created once during - installations so that all users can use the same file. Thsi is because a full - scale global tag list can occupy several megabytes of disk space. - @param pre_process The pre-processing command. This is executed via system(), - so you can pass stuff like 'gcc -E -dD -P `gnome-config --cflags gnome`'. - @param includes Include files to process. Wildcards such as '/usr/include/a*.h' - are allowed. - @param tags_file The file where the tags will be stored. - @param lang The language to use for the tags file. - @return TRUE on success, FALSE on failure. -*/ + gboolean tm_workspace_create_global_tags(const char *pre_process, const char **includes, int includes_count, const char *tags_file, int lang);

-/* Recreates the tag array of the workspace by collecting the tags of - all member source files. You shouldn't have to call this directly since - this is called automatically by tm_workspace_update(). -*/ void tm_workspace_recreate_tags_array(void);

-/* Dumps the workspace tree - useful for debugging */ void tm_workspace_dump(void);

-/* Returns all matching tags found in the workspace. - @param name The name of the tag to find. - @param type The tag types to return (TMTagType). Can be a bitmask. - @param attrs The attributes to sort and dedup on (0 terminated integer array). - @param partial Whether partial match is allowed. - @param lang Specifies the language(see the table in parsers.h) of the tags to be found, - -1 for all - @return Array of matching tags. Do not free() it since it is a static member. -*/ const GPtrArray *tm_workspace_find(const char *name, int type, TMTagAttrType *attrs , gboolean partial, langType lang);

-/* Returns all matching tags found in the workspace. - @param name The name of the tag to find. - @param scope The scope name of the tag to find, or NULL. - @param type The tag types to return (TMTagType). Can be a bitmask. - @param attrs The attributes to sort and dedup on (0 terminated integer array). - @param partial Whether partial match is allowed. - @param lang Specifies the language(see the table in parsers.h) of the tags to be found, - -1 for all - @return Array of matching tags. Do not free() it since it is a static member. -*/ const GPtrArray * tm_workspace_find_scoped (const char *name, const char *scope, gint type, TMTagAttrType *attrs, gboolean partial, langType lang, gboolean global_search);

-/* Returns all matching members tags found in given struct/union/class name. - @param name Name of the struct/union/class. - @param file_tags A GPtrArray of edited file TMTag pointers (for search speedup, can be NULL). - @return A GPtrArray of TMTag pointers to struct/union/class members */ const GPtrArray *tm_workspace_find_scope_members(const GPtrArray *file_tags, const char *scope_name, gboolean find_global, @@ -136,27 +70,12 @@ const GPtrArray * tm_workspace_find_namespace_members (const GPtrArray * file_tags, const char *name, gboolean search_global);

-/* Returns TMTag which "own" given line - @param line Current line in edited file. - @param file_tags A GPtrArray of edited file TMTag pointers. - @param tag_types the tag types to include in the match - @return TMTag pointers to owner tag. */ const TMTag *tm_get_current_tag(GPtrArray *file_tags, const gulong line, const guint tag_types);

-/* Returns TMTag to function or method which "own" given line - @param line Current line in edited file. - @param file_tags A GPtrArray of edited file TMTag pointers. - @return TMTag pointers to owner function. */ const TMTag *tm_get_current_function(GPtrArray *file_tags, const gulong line);

-/* Returns a list of parent classes for the given class name - @param name Name of the class - @return A GPtrArray of TMTag pointers (includes the TMTag for the class) */ const GPtrArray *tm_workspace_get_parents(const gchar *name);

-/* Frees the workspace structure and all child source files. Use only when - exiting from the main program. -*/ void tm_workspace_free(void);

void tm_workspace_merge_file_tags(TMSourceFile *source_file);

-------------- This E-Mail was brought to you by github_commit_mail.py (Source: https://github.com/geany/infrastructure).