Add a format specification in global tags files and implement an additional…

Add a format specification in global tags files and implement an additional fallback if the specification is missing.
Adjust code and scripts which generate global tags files to add the new format specification.
Update global tags files.
Add documentation for the two supported global tags files formats.

git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@3465 ea778897-0a13-0410-b9d1-a72fbfd435f5

ChangeLog

+2009-01-14  Enrico Tröger  <enrico(dot)troeger(at)uvena(dot)de>
+
+ * data/global.tags, data/latex.tags, data/pascal.tags, data/php.tags,
+   data/python.tags, doc/geany.html, doc/geany.txt,
+   scripts/create_php_tags.php, scripts/create_py_tags.py,
+   tagmanager/include/tm_tag.h, tagmanager/tm_project.c,
+   tagmanager/tm_tag.c, tagmanager/tm_workspace.c:
+   Add a format specification in global tags files and implement
+   an additional fallback if the specification is missing.
+   Adjust code and scripts which generate global tags files to
+   add the new format specification.
+   Update global tags files.
+   Add documentation for the two supported global tags files formats.
+
+
 2009-01-12  Nick Treleaven  <nick(dot)treleaven(at)btinternet(dot)com>
 
  * data/filetypes.vala:
-   Add default build commands (other sections are commented out and 
+   Add default build commands (other sections are commented out and
    untested).
 
 

data/global.tags

+# format=tagmanager
 ABS655360
 ABS131072(a)0
 AIO_PRIO_DELTA_MAX655360

data/latex.tags

+# format=pipe
 \above|||
 \abovecaptionskip|||
 \abovedisplayshortskip|||

data/pascal.tags

+# format=pipe
 arc||(X: SmallInt, Y: SmallInt, StAngle: Word, EndAngle: Word, Radius: Word)|
 assigncrt||(File: Text)|
 bar||(x1: SmallInt; y1: SmallInt; x2: SmallInt; y2: SmallInt)|

data/php.tags

-# Automatically generated file - do not edit (created on Tue, 10 Jun 2008 18:27:43 +0200)
+# format=tagmanager - Automatically generated file - do not edit (created on Wed, 14 Jan 2009 16:59:30 +0100)
 abs128(int number)int
 acosh128(float number)float
 acos128(float number)float

data/python.tags

-# Automatically generated file - do not edit (created on Tue Jun 10 18:27:52 2008)
+# format=tagmanager - Automatically generated file - do not edit (created on Wed Jan 14 16:59:26 2009)
 AbstractHTTPHandler1(BaseHandler)
 AbstractWriter1(NullWriter)
 AddPackagePath128(packagename, path)
@@ -377,6 +377,7 @@ artcmd
 article128(self, id)
 asBase64128(self, maxlinelength=76)
 as_tuple128(self)
+ascii_upper128(s)
 assert_line_data128(self, flag=1)
 assure_pickle_consistency128(verbose=False)
 async_chat1(asyncore.dispatcher)

doc/geany.txt

@@ -1205,22 +1205,58 @@ corresponding filetype is first used. Currently these are for:
 * Python
 
 
-Generating a global tags file
-`````````````````````````````
+Global tags file format
+```````````````````````
+
+Global tags files can have two different formats:
+
+* Tagmanager format
+* Pipe-separated format
+
+The first line of global tags files should be a comment, introduced
+by ``#`` followed by a space and a string like ``format=pipe``
+respectively ``format=tagmanager`` (case-sensitive).
+This helps Geany to read the file properly. If this line
+is missing, Geany tries to auto-detect the used format but this
+might fail.
+
+
+The Tagmanager format is a bit more complex and is used for files
+created by the ``geany -g`` command. There is one tag per line.
+Different tag attributes like the return value or the argument list
+are separated with different characters indicating the type of the
+following argument.
 
+The Pipe-separated format is easier to read and write.
+There is one tag per line and different tag attributes are separated
+by the pipe character (``|``). A line looks like::
 
-*Filetypes support:*
+    basename|string|(string path [, string suffix])|
 
-Currently this is not yet supported for Pascal, PHP and LaTeX
-filetypes.
+| The first field is the tag name (usually a function name).
+| The second field is the type of the return value.
+| The third field is the argument list for this tag.
+| The fourth field is the description for this tag but
+  currently unused and should be left empty.
+
+Except for the first field (tag name), all other field can be left
+empty but the pipe separator must appear for them.
+
+You can easily write your own global tag files using this format.
+Just save them in your tags directory, as described earlier in the
+section `Global tags`_.
+
+
+Generating a global tags file
+`````````````````````````````
 
 You can generate your own global tags files by parsing a list of
 source files. The command is::
 
     geany -g [-P] <Tag File> <File list>
 
-* Tag File should be in the format described earlier -- see the
-  section called `Global tags`_.
+* Tag File filename should be in the format described earlier --
+  see the section called `Global tags`_.
 * File list is a list of filenames, each with a full path (unless
   you are generating C/C++ tags and have set the CFLAGS environment
   variable appropriately).

scripts/create_php_tags.php

@@ -59,8 +59,9 @@ for($line = 0, $lineCount = count($file); $line < $lineCount; ++$line) {
         TA_ARGLIST, $funcDefMatch['params'], TA_VARTYPE, $funcDefMatch['retType']);
 }
 
-$tagsOutput[] = sprintf('# Automatically generated file - do not edit (created on %s)',
-                    date('r'));
+$tagsOutput[] = sprintf(
+    '# format=tagmanager - Automatically generated file - do not edit (created on %s)',
+    date('r'));
 // Sort the output
 sort($tagsOutput);
 

scripts/create_py_tags.py

@@ -265,7 +265,8 @@ def main():
 	tags.sort()
 	# write them
 	fp = open(tag_filename, 'wb')
-	fp.write('# Automatically generated file - do not edit (created on %s)\n' % \
+	fp.write(
+		'# format=tagmanager - Automatically generated file - do not edit (created on %s)\n' % \
 		datetime.datetime.now().ctime())
 	for s in tags:
 		if not s == '\n': # skip empty lines

tagmanager/include/tm_tag.h

@@ -199,7 +199,7 @@ 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);
+TMTag *tm_tag_new_from_file(TMSourceFile *file, FILE *fp, gint mode, gboolean format_pipe);
 
 /*!
  Writes tag information to the given FILE *.

tagmanager/tm_project.c

@@ -385,7 +385,7 @@ gboolean tm_project_open(TMProject *project, gboolean force)
 	tm_project_set_ignorelist(project);
 	if (NULL == (fp = g_fopen(project->work_object.file_name, "r")))
 		return FALSE;
-	while (NULL != (tag = tm_tag_new_from_file(source_file, fp, 0)))
+	while (NULL != (tag = tm_tag_new_from_file(source_file, fp, 0, FALSE)))
 	{
 		if (tm_tag_file_t == tag->type)
 		{

tagmanager/tm_tag.c

@@ -300,7 +300,7 @@ gboolean tm_tag_init_from_file(TMTag *tag, TMSourceFile *file, FILE *fp)
 					tag->atts.entry.impl = *(start + 1);
 					break;
 				default:
-#ifdef TM_DEBUG
+#ifdef GEANY_DEBUG
 					g_warning("Unknown attribute %s", start + 1);
 #endif
 					break;
@@ -359,23 +359,17 @@ gboolean tm_tag_init_from_file_alt(TMTag *tag, TMSourceFile *file, FILE *fp)
 	return TRUE;
 }
 
-TMTag *tm_tag_new_from_file(TMSourceFile *file, FILE *fp, gint mode)
+TMTag *tm_tag_new_from_file(TMSourceFile *file, FILE *fp, gint mode, gboolean format_pipe)
 {
 	TMTag *tag;
 	gboolean result;
 
 	TAG_NEW(tag);
 
-	switch (mode)
-	{
-		case 4:	/* pascal */
-		case 8:	/* latex */
-			result = tm_tag_init_from_file_alt(tag, file, fp);
-			break;
-
-		default:
-			result = tm_tag_init_from_file(tag, file, fp);
-	}
+	if (format_pipe)
+		result = tm_tag_init_from_file_alt(tag, file, fp);
+	else
+		result = tm_tag_init_from_file(tag, file, fp);
 
 	if (! result)
 	{

tagmanager/tm_workspace.c

@@ -142,8 +142,10 @@ static TMTagAttrType global_tags_sort_attrs[] =
 
 gboolean tm_workspace_load_global_tags(const char *tags_file, gint mode)
 {
+	guchar buf[BUFSIZ];
 	FILE *fp;
 	TMTag *tag;
+	gboolean format_pipe = FALSE;
 
 	if (NULL == (fp = g_fopen(tags_file, "r")))
 		return FALSE;
@@ -151,7 +153,29 @@ gboolean tm_workspace_load_global_tags(const char *tags_file, gint mode)
 		return FALSE;
 	if (NULL == theWorkspace->global_tags)
 		theWorkspace->global_tags = g_ptr_array_new();
-	while (NULL != (tag = tm_tag_new_from_file(NULL, fp, mode)))
+	if ((NULL == fgets((gchar*) buf, BUFSIZ, fp)) || ('\0' == *buf))
+		return FALSE; /* early out on error */
+	else
+	{	/* We read the first line for the format specification. */
+		if (buf[0] == '#' && strstr((gchar*) buf, "format=pipe") != NULL)
+			format_pipe = TRUE;
+		else if (buf[0] == '#' && strstr((gchar*) buf, "format=tagmanager") != NULL)
+			format_pipe = FALSE;
+		else
+		{	/* We didn't find a valid format specification, so we try to auto-detect the format
+			 * by counting the pipe characters on the first line and asumme pipe format when
+			 * we find more than one pipe on the line. */
+			guint i, pipe_cnt = 0;
+			for (i = 0; i < BUFSIZ && buf[i] != '\0' && pipe_cnt < 2; i++)
+			{
+				if (buf[i] == '|')
+					pipe_cnt++;
+			}
+			format_pipe = (pipe_cnt > 1);
+		}
+		rewind(fp); /* reset the file pointer, to start reading again from the beginning */
+	}
+	while (NULL != (tag = tm_tag_new_from_file(NULL, fp, mode, format_pipe)))
 		g_ptr_array_add(theWorkspace->global_tags, tag);
 	fclose(fp);
 
@@ -409,6 +433,7 @@ gboolean tm_workspace_create_global_tags(const char *config_dir, const char *pre
 		tm_source_file_free(source_file);
 		return FALSE;
 	}
+	fprintf(fp, "# format=tagmanager\n");
 	for (i = 0; i < tags_array->len; ++i)
 	{
 		tm_tag_write(TM_TAG(tags_array->pdata[i]), fp, tm_tag_attr_type_t