Merge pull request #2775 from masatake/add-role-ptag

main: add TAG_ROLE_DESCRIPTION to enuerate enabled roles as ptags

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

@@ -15,3 +15,4 @@ TAG_PROGRAM_AUTHOR        on      the author of this ctags implementation
 TAG_PROGRAM_NAME          on      the name of this ctags implementation
 TAG_PROGRAM_URL           on      the official site URL of this ctags implementation
 TAG_PROGRAM_VERSION       on      the version of this ctags implementation
+TAG_ROLE_DESCRIPTION      off     the names and descriptions of enabled roles

Tmain/ptag-dont-emit-to-stdout-by-default.d/input.c

@@ -0,0 +1 @@
+int x;

Tmain/ptag-dont-emit-to-stdout-by-default.d/run.sh

@@ -0,0 +1,6 @@
+# Copyright: 2020 Masatake YAMATO
+# License: GPL-2
+
+CTAGS=$1
+
+${CTAGS} --quiet --options=NONE --pseudo-tags='*' -o - input.c

Tmain/ptag-dont-emit-to-stdout-by-default.d/stdout-expected.txt

@@ -0,0 +1 @@
+x	input.c	/^int x;$/;"	v	typeref:typename:int

Tmain/ptag-in-optlib-parser.d/run.sh

@@ -1,4 +1,4 @@
-# Copyright: 2016 Masatake YAMATO
+# Copyright: 2020 Masatake YAMATO
 # License: GPL-2
 
 CTAGS=$1

Tmain/ptag-in-optlib-parser.d/stdout-expected.txt

@@ -17,6 +17,8 @@
 !_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
 !_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
 !_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+!_TAG_ROLE_DESCRIPTION!Sh!heredoc	endmarker	/end marker/
+!_TAG_ROLE_DESCRIPTION!Sh!script	loaded	/loaded/
 # REGEX
 !_TAG_EXTRA_DESCRIPTION	pseudo	/Include pseudo tags/
 !_TAG_EXTRA_DESCRIPTION!foo	extra	/extra example/

Tmain/ptag-role-desc.d/input.c

@@ -0,0 +1 @@
+/* EMPTY */

Tmain/ptag-role-desc.d/run.sh

@@ -0,0 +1,11 @@
+# Copyright: 2020 Masatake YAMATO
+# License: GPL-2
+
+CTAGS=$1
+O="--quiet --options=NONE "
+
+${CTAGS} $O \
+		 --extras=+p --pseudo-tags=TAG_ROLE_DESCRIPTION \
+		 --kinds-C=h \
+		 -o - \
+		 input.c

Tmain/ptag-role-desc.d/stdout-expected.txt

@@ -0,0 +1,2 @@
+!_TAG_ROLE_DESCRIPTION!C!header	local	/local header/
+!_TAG_ROLE_DESCRIPTION!C!header	system	/system header/

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

@@ -241,6 +241,15 @@ for using notable ones.
 ``TAG_PROGRAM_NAME``
 	TBW
 
+``TAG_ROLE_DESCRIPTION`` (new in Universal-ctags)
+	Indicates the names and descriptions of enabled roles::
+
+	  !_TAG_ROLE_DESCRIPTION!{language-name}!{kind-name}	{role-name}	/description/
+
+	If your tool relies on some roles, refer to the pseudo-tags of
+	this type. Note that a role owned by a disabled kind is not listed
+	even if the role itself is enabled.
+
 REDUNDANT-KINDS
 ---------------
 TBW

main/parse.c

@@ -3842,7 +3842,8 @@ static bool createTagsWithFallback1 (const langType language,
 	if (useCork)
 		corkTagFile(corkFlags);
 
-	addParserPseudoTags (language);
+	if (isXtagEnabled (XTAG_PSEUDO_TAGS))
+		addParserPseudoTags (language);
 	initializeParserStats (parser);
 	tagFilePosition (&tagfpos);
 
@@ -4550,6 +4551,30 @@ static bool makeKindDescriptionPseudoTag (kindDefinition *kind,
 	return false;
 }
 
+static bool makeRoleDescriptionPseudoTag (kindDefinition *kind,
+										  roleDefinition *role,
+										  void *user_data)
+{
+	struct makeKindDescriptionPseudoTagData *data = user_data;
+
+	vString *parser_and_kind_name = vStringNewInit (data->langName);
+	vStringCatS (parser_and_kind_name, PSEUDO_TAG_SEPARATOR);
+	vStringCatS (parser_and_kind_name, kind->name);
+
+	vString *description = vStringNew ();
+	const char *d = role->description? role->description: role->name;
+	vStringCatSWithEscapingAsPattern (description, d);
+
+	data->written |=  writePseudoTag (data->pdesc, role->name,
+									  vStringValue (description),
+									  vStringValue (parser_and_kind_name));
+
+	vStringDelete (description);
+	vStringDelete (parser_and_kind_name);
+
+	return false;
+}
+
 extern bool makeKindDescriptionsPseudoTags (const langType language,
 					    const ptagDesc *pdesc)
 {
@@ -4659,6 +4684,47 @@ extern bool makeExtraDescriptionsPseudoTags (const langType language,
 	return written;
 }
 
+extern bool makeRoleDescriptionsPseudoTags (const langType language,
+											const ptagDesc *pdesc)
+{
+	parserObject *parser;
+	struct kindControlBlock *kcb;
+	parserDefinition* lang;
+	kindDefinition *kind;
+	struct makeKindDescriptionPseudoTagData data;
+
+	Assert (0 <= language  &&  language < (int) LanguageCount);
+	parser = LanguageTable + language;
+	kcb = parser->kindControlBlock;
+	lang = parser->def;
+
+	unsigned int kindCount = countKinds(kcb);
+
+	data.langName = lang->name;
+	data.pdesc = pdesc;
+	data.written = false;
+
+	for (unsigned int i = 0; i < kindCount; ++i)
+	{
+		if (!isLanguageKindEnabled (language, i))
+			continue;
+
+		kind = getKind (kcb, i);
+
+		unsigned int roleCount = countRoles (kcb, i);
+		for (unsigned int j = 0; j < roleCount; ++j)
+		{
+			if (isRoleEnabled (kcb, i, j))
+			{
+				roleDefinition *role = getRole (kcb, i, j);
+				makeRoleDescriptionPseudoTag (kind, role, &data);
+			}
+		}
+	}
+
+	return data.written;
+}
+
 /*
 *   Copyright (c) 2016, Szymon Tomasz Stefanek
 *

main/parse.h

@@ -84,7 +84,7 @@ struct sParserDefinition {
 	rescanParser parser2;          /* rescanning parser (unusual case) */
 	selectLanguage* selectLanguage; /* may be used to resolve conflicts */
 	unsigned int method;           /* See METHOD_ definitions above */
-	unsigned int useCork;		   /* bit or of corkUsage */
+	unsigned int useCork;		   /* bit fields of corkUsage */
 	bool useMemoryStreamInput;
 	bool allowNullTag;
 	bool requestAutomaticFQTag;

main/parse_p.h

@@ -170,6 +170,8 @@ extern bool makeFieldDescriptionsPseudoTags (const langType language,
 					       const ptagDesc *pdesc);
 extern bool makeExtraDescriptionsPseudoTags (const langType language,
 					       const ptagDesc *pdesc);
+extern bool makeRoleDescriptionsPseudoTags (const langType language,
+					       const ptagDesc *pdesc);
 
 extern void printLanguageMultitableStatistics (langType language);
 extern void printParserStatisticsIfUsed (langType lang);

main/ptag.c

@@ -116,6 +116,12 @@ static bool ptagMakeExtraDescriptions (ptagDesc *desc, langType language,
 	return makeExtraDescriptionsPseudoTags (language, desc);
 }
 
+static bool ptagMakeRoleDescriptions (ptagDesc *desc, langType language,
+									  const void *data CTAGS_ATTR_UNUSED)
+{
+	return makeRoleDescriptionsPseudoTags (language, desc);
+}
+
 static bool ptagMakeProcCwd (ptagDesc *desc, langType language,
 									   const void *data CTAGS_ATTR_UNUSED)
 {
@@ -176,6 +182,10 @@ static ptagDesc ptagDescs [] = {
 	  "the names and descriptions of enabled extras",
 	  ptagMakeExtraDescriptions,
 	  PTAGF_COMMON|PTAGF_PARSER },
+	{ false, "TAG_ROLE_DESCRIPTION",
+	  "the names and descriptions of enabled roles",
+	  ptagMakeRoleDescriptions,
+	  PTAGF_PARSER },
 	{ true, "TAG_OUTPUT_MODE",
 	  "the output mode: u-ctags or e-ctags",
 	  ptagMakeCtagsOutputMode,

main/ptag_p.h

@@ -37,6 +37,7 @@ typedef enum ePtagType { /* pseudo tag content control */
 	PTAG_KIND_DESCRIPTION,
 	PTAG_FIELD_DESCRIPTION,
 	PTAG_EXTRA_DESCRIPTION,
+	PTAG_ROLE_DESCRIPTION,
 	PTAG_OUTPUT_MODE,
 	PTAG_OUTPUT_FILESEP,
 	PTAG_PATTERN_TRUNCATION,

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

@@ -241,6 +241,15 @@ for using notable ones.
 ``TAG_PROGRAM_NAME``
 	TBW
 
+``TAG_ROLE_DESCRIPTION`` (new in Universal-ctags)
+	Indicates the names and descriptions of enabled roles::
+
+	  !_TAG_ROLE_DESCRIPTION!{language-name}!{kind-name}	{role-name}	/description/
+
+	If your tool relies on some roles, refer to the pseudo-tags of
+	this type. Note that a role owned by a disabled kind is not listed
+	even if the role itself is enabled.
+
 REDUNDANT-KINDS
 ---------------
 TBW