main: introduce 'output version'

Close #3583.

Signed-off-by: Masatake YAMATO <[email protected]>

Tmain/extras-field-for-pseudo-tags.d/run.sh

@@ -11,6 +11,7 @@ run_ctags()
 			 --pseudo-tags=-TAG_PROGRAM_VERSION \
 			 --pseudo-tags=-TAG_PROC_CWD \
 			 --pseudo-tags=-TAG_PARSER_VERSION \
+			 --pseudo-tags=-TAG_OUTPUT_VERSION \
 			 $@ \
 			 -o - input.c
 }

Tmain/input-encoding-option.d/run.sh

@@ -20,6 +20,7 @@ if ${CTAGS} --quiet --options=NONE --list-features | grep -q iconv; then
 	      --pseudo-tags=-TAG_FIELD_DESCRIPTION \
 	      --pseudo-tags=-TAG_ROLE_DESCRIPTION \
 	      --pseudo-tags=-TAG_PARSER_VERSION \
+	      --pseudo-tags=-TAG_OUTPUT_VERSION \
 	      --input-encoding=utf-8 --input-encoding-java=shift_jis --input-encoding-javascript=euc-jp \
 	      -o ${BUILDDIR}/tags \
 	      input.js input.java ; then

Tmain/json-output-format.d/run.sh

@@ -12,6 +12,7 @@ if is_feature_available "${CTAGS}" json; then
 	run_with_format json --languages=+man --fields="*"-T --extras='*'
     } | cat \
 		| grep -v TAG_PROGRAM_VERSION \
+		| grep -v TAG_OUTPUT_VERSION  \
 		| grep -v TAG_OUTPUT_FILESEP  \
 		| grep -v TAG_PROC_CWD
 fi

Tmain/list-pseudo-tags.d/stdout-expected.txt

@@ -9,6 +9,7 @@ TAG_KIND_SEPARATOR        off     the separators used in kinds
 TAG_OUTPUT_EXCMD          on      the excmd: number, pattern, mixed, or combine
 TAG_OUTPUT_FILESEP        on      the separator used in file name (slash or backslash)
 TAG_OUTPUT_MODE           on      the output mode: u-ctags or e-ctags
+TAG_OUTPUT_VERSION        on      the version of the output interface (current.age)
 TAG_PARSER_VERSION        on      the version of the parser (current.age)
 TAG_PATTERN_LENGTH_LIMIT  on      the limit of pattern length
 TAG_PROC_CWD              on      the current working directory of the tags generator

Tmain/output-encoding-option.d/run.sh

@@ -19,6 +19,7 @@ if ${CTAGS} --quiet --options=NONE --list-features | grep -q iconv; then
 	       --pseudo-tags=-TAG_EXTRA_DESCRIPTION \
 	       --pseudo-tags=-TAG_ROLE_DESCRIPTION \
 	       --pseudo-tags=-TAG_PARSER_VERSION \
+	       --pseudo-tags=-TAG_OUTPUT_VERSION \
 	       --output-encoding=shift_jis --input-encoding=utf-8 --input-encoding-javascript=euc-jp \
 	       -o ${BUILDDIR}/tags \
 	       input.js input.java ; then

Tmain/ptag-kind-sep.d/run.sh

@@ -18,4 +18,5 @@ ${CTAGS} --quiet --options=NONE -o - \
 	 --pseudo-tags=-TAG_EXTRA_DESCRIPTION \
 	 --pseudo-tags=-TAG_ROLE_DESCRIPTION \
 	 --pseudo-tags=-TAG_PARSER_VERSION \
+	 --pseudo-tags=-TAG_OUTPUT_VERSION \
 	 input.php

docs/man/ctags-client-tools.7.rst

@@ -220,6 +220,18 @@ for using notable ones.
 ``TAG_OUTPUT_MODE`` (new in Universal Ctags)
 	TBW
 
+``TAG_OUTPUT_VERSION`` (new in Universal Ctags 6.0)
+    Indicates the language-common interface version of the output::
+
+	  !_TAG_OUTPUT_VERSION	{current}.{age}	/.../
+
+	The public interface includes common fields, common extras,
+	pseudo tags.
+
+	The maintainer of Universal Ctags may update the numbers,
+	"{current}" and "{age}" in the same manner as explained
+	in ``TAG_PARSER_VERSION``.
+
 ``TAG_PARSER_VERSION`` (new in Universal Ctags 6.0)
 	Indicates the interface version of the parser::
 

docs/man/ctags.1.rst

@@ -1330,8 +1330,8 @@ Miscellaneous Options
 ``--version[=<language>]``
 	Prints a version identifier for ctags to standard
 	output, and then exits. This is guaranteed to always contain the string
-	"Universal Ctags". See also the description for ``TAG_PROGRAM_VERSION`` in
-	:ref:`ctags-client-tools(7) <ctags-client-tools(7)>`.
+	"Universal Ctags". See also the description for ``TAG_PROGRAM_VERSION``
+	and ``TAG_OUTPUT_VERSION`` in :ref:`ctags-client-tools(7) <ctags-client-tools(7)>`.
 
 	If *<language>* is given, print the version identifier for the parser
 	for *<language>*. See also the description for ``TAG_PARSER_VERSION`` in

main/ctags.h

@@ -48,6 +48,26 @@
 #define PROGRAM_COPYRIGHT "Copyright (C) 2015-2022"
 #define AUTHOR_NAME       "Universal Ctags Team"
 
+/* The concept of CURRENT and AGE is taken from libtool.
+ * However, we deleted REVISION in libtool when importing
+ * the concept of versioning from libtool.
+ *
+ * If common fields, common extras, pseudo tags have been added,
+ * removed or changed since last release, increment CURRENT.
+ * If they have been added since last release, increment AGE.
+ * If they have been removed since last release, set AGE to 0
+ *
+ * From the command line of ctags, you can see the version
+ * information with --version and --version=NONE.
+ *
+ * In the tags file, !_TAGS_OUTPUT_VERSION shows the the version.
+ *
+ * Chaning for the command line interface, and implementation changes
+ * like bug fixes don't affect the CURRENT an AGE.
+ */
+#define OUTPUT_VERSION_CURRENT 0
+#define OUTPUT_VERSION_AGE 0
+
 /*
  * Constant
  */

main/options.c

@@ -1614,6 +1614,8 @@ static void printProgramIdentification (void)
 
 	printf ("  Compiled: %s, %s\n", __DATE__, __TIME__);
 	printf ("  URL: %s\n", PROGRAM_URL);
+	printf ("  Output version: %d.%d\n",
+			OUTPUT_VERSION_CURRENT, OUTPUT_VERSION_AGE);
 
 	printFeatureList ();
 }

main/ptag.c

@@ -139,6 +139,15 @@ static bool ptagMakeParserVersion(ptagDesc *desc, langType language,
 	return writePseudoTag (desc, buf, "current.age", name);
 }
 
+static bool ptagMakeOutputVersion (ptagDesc *desc, langType language,
+								   const void *data CTAGS_ATTR_UNUSED)
+{
+	char buf[32];			/* 2^32 '.' 2^32 '\0' */
+	snprintf (buf, sizeof(buf), "%u.%u",
+			  OUTPUT_VERSION_CURRENT, OUTPUT_VERSION_AGE);
+	return writePseudoTag (desc, buf, "current.age", NULL);
+}
+
 static ptagDesc ptagDescs [] = {
 	{
 	  /* The prefix is not "TAG_".
@@ -222,6 +231,10 @@ static ptagDesc ptagDescs [] = {
 	  "the version of the parser (current.age)",
 	  ptagMakeParserVersion,
 	  PTAGF_PARSER },
+	{ true, "TAG_OUTPUT_VERSION",
+	  "the version of the output interface (current.age)",
+	  ptagMakeOutputVersion,
+	  PTAGF_COMMON },
 };
 
 extern bool makePtagIfEnabled (ptagType type, langType language, const void *data)

main/ptag_p.h

@@ -44,6 +44,7 @@ typedef enum ePtagType { /* pseudo tag content control */
 	PTAG_PROC_CWD,
 	PTAG_OUTPUT_EXCMD,
 	PTAG_PARSER_VERSION,
+	PTAG_OUTPUT_VERSION,
 	PTAG_COUNT
 } ptagType;
 

man/ctags-client-tools.7.rst.in

@@ -220,6 +220,18 @@ for using notable ones.
 ``TAG_OUTPUT_MODE`` (new in Universal Ctags)
 	TBW
 
+``TAG_OUTPUT_VERSION`` (new in Universal Ctags 6.0)
+    Indicates the language-common interface version of the output::
+
+	  !_TAG_OUTPUT_VERSION	{current}.{age}	/.../
+
+	The public interface includes common fields, common extras,
+	pseudo tags.
+
+	The maintainer of Universal Ctags may update the numbers,
+	"{current}" and "{age}" in the same manner as explained
+	in ``TAG_PARSER_VERSION``.
+
 ``TAG_PARSER_VERSION`` (new in Universal Ctags 6.0)
 	Indicates the interface version of the parser::
 

man/ctags.1.rst.in

@@ -1330,8 +1330,8 @@ Miscellaneous Options
 ``--version[=<language>]``
 	Prints a version identifier for @CTAGS_NAME_EXECUTABLE@ to standard
 	output, and then exits. This is guaranteed to always contain the string
-	"Universal Ctags". See also the description for ``TAG_PROGRAM_VERSION`` in
-	ctags-client-tools(7).
+	"Universal Ctags". See also the description for ``TAG_PROGRAM_VERSION``
+	and ``TAG_OUTPUT_VERSION`` in ctags-client-tools(7).
 
 	If *<language>* is given, print the version identifier for the parser
 	for *<language>*. See also the description for ``TAG_PARSER_VERSION`` in