[geany/geany] 0470f4: TM: move function descriptions from headers to sources
Jiří Techet
git-noreply at xxxxx
Sat Nov 8 18:57:53 UTC 2014
Branch: refs/heads/master
Author: Jiří Techet <techet at gmail.com>
Committer: Jiří Techet <techet at gmail.com>
Date: Sat, 18 Oct 2014 19:40:10 UTC
Commit: 0470f45e0cac539efed63e3f01d519ac01623f74
https://github.com/geany/geany/commit/0470f45e0cac539efed63e3f01d519ac01623f74
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).
More information about the Commits
mailing list