main: revise ptags for client tools

.gitignore

@@ -77,6 +77,9 @@ _build
 man/ctags.1
 man/ctags.1.html
 man/ctags.1.rst
+man/ctags-client-tools.7
+man/ctags-client-tools.7.rst
+man/ctags-client-tools.7.html
 man/ctags-incompatibilities.7
 man/ctags-incompatibilities.7.html
 man/ctags-incompatibilities.7.rst

Makefile.am

@@ -210,6 +210,7 @@ man_MANS = \
 	\
 	man/tags.5 \
 	\
+	man/ctags-client-tools.7 \
 	man/ctags-incompatibilities.7 \
 	man/ctags-optlib.7 \
 	\

Tmain/extras-field-for-pseudo-tags.d/input.c

@@ -0,0 +1 @@
+int main (void) { return 0; }

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

@@ -0,0 +1,17 @@
+# Copyright: 2016 Masatake YAMATO
+# License: GPL-2
+
+CTAGS=$1
+
+run_ctags()
+{
+	echo '# option: ' "$@"
+	${CTAGS} --quiet --options=NONE \
+			 --fields=E --extras=p \
+			 --pseudo-tags=-TAG_PROGRAM_VERSION \
+			 $@ \
+			 -o - input.c
+}
+
+run_ctags --format=1
+run_ctags --format=2

Tmain/extras-field-for-pseudo-tags.d/stdout-expected.txt

@@ -0,0 +1,20 @@
+# option:  --format=1
+!_TAG_FILE_FORMAT	1	/original ctags format/
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
+!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/
+!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/
+!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/
+!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
+!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+main	input.c	/^int main (void) { return 0; }$/
+# option:  --format=2
+!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/;"	extras:pseudo
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/;"	extras:pseudo
+!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/;"	extras:pseudo
+!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/;"	extras:pseudo
+!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/;"	extras:pseudo
+!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//;"	extras:pseudo
+!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/;"	extras:pseudo
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/;"	extras:pseudo
+main	input.c	/^int main (void) { return 0; }$/

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

@@ -1,12 +1,15 @@
 #NAME                     ENABLED DESCRIPTION
 JSON_OUTPUT_VERSION       off     the version of json output stream format
+TAG_EXTRA_DESCRIPTION     off     the names and descriptions of enabled extras
+TAG_FIELD_DESCRIPTION     off     the names and descriptions of enabled fields
 TAG_FILE_FORMAT           on      the version of tags file format
 TAG_FILE_SORTED           on      how tags are sorted
-TAG_KIND_DESCRIPTION      off     the letters, names and descriptions of kinds in a parser
+TAG_KIND_DESCRIPTION      off     the letters, names and descriptions of enabled kinds in the language
 TAG_KIND_SEPARATOR        off     the separators used in kinds
 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_PATTERN_LENGTH_LIMIT  on      the limit of pattern length
+TAG_PROC_CWD              off     the current working directory of the tags generator
 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

Tmain/option-pseudo-tags.d/input.c

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

Tmain/option-pseudo-tags.d/run.sh

@@ -0,0 +1,63 @@
+# Copyright: 2020 Masatake YAMATO
+# License: GPL-2
+
+CTAGS=$1
+O="--quiet --options=NONE "
+
+echo '# single with no curly bracket'
+${CTAGS} $O \
+		 --extras=+p --pseudo-tags=TAG_PROGRAM_URL \
+		 -o - \
+		 input.c
+
+echo '# single with curly bracket'
+${CTAGS} $O \
+		 --extras=+p --pseudo-tags='{TAG_PROGRAM_URL}' \
+		 -o - \
+		 input.c
+
+echo '# single with + no curly bracket'
+${CTAGS} $O \
+		 --extras=+p --pseudo-tags= \
+		 --pseudo-tags=+TAG_PROGRAM_URL \
+		 -o - \
+		 input.c
+
+echo '# single with + curly bracket'
+${CTAGS} $O \
+		 --extras=+p --pseudo-tags= \
+		 --pseudo-tags=+'{TAG_PROGRAM_URL}' \
+		 -o - \
+		 input.c
+
+echo '# single with +- no curly bracket'
+${CTAGS} $O \
+		 --extras=+p --pseudo-tags= \
+		 --pseudo-tags=+TAG_PROGRAM_VERSION \
+		 --pseudo-tags=+TAG_PROGRAM_URL \
+		 --pseudo-tags=-TAG_PROGRAM_VERSION \
+		 -o - \
+		 input.c
+
+echo '# single with +- curly bracket'
+${CTAGS} $O \
+		 --extras=+p --pseudo-tags= \
+		 --pseudo-tags=+'{TAG_PROGRAM_VERSION}' \
+		 --pseudo-tags=+'{TAG_PROGRAM_URL}' \
+		 --pseudo-tags=-'{TAG_PROGRAM_VERSION}' \
+		 -o - \
+		 input.c
+
+echo '# multiple specifications with +- curly bracket'
+${CTAGS} $O \
+		 --extras=+p --pseudo-tags= \
+		 --pseudo-tags='+{TAG_PROGRAM_VERSION}{TAG_FILE_SORTED}{TAG_PROGRAM_URL}-{TAG_PROGRAM_VERSION}' \
+		 -o - \
+		 input.c
+
+echo '# multiple specifications with -+- curly bracket'
+${CTAGS} $O \
+		 --extras=+p --pseudo-tags= \
+		 --pseudo-tags='-{TAG_PROGRAM_VERSION}+{TAG_PROGRAM_VERSION}{TAG_FILE_FORMAT}{TAG_PROGRAM_URL}-{TAG_PROGRAM_VERSION}' \
+		 -o - \
+		 input.c

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

@@ -0,0 +1,18 @@
+# single with no curly bracket
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+# single with curly bracket
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+# single with + no curly bracket
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+# single with + curly bracket
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+# single with +- no curly bracket
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+# single with +- curly bracket
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+# multiple specifications with +- curly bracket
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+# multiple specifications with -+- curly bracket
+!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/

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

@@ -0,0 +1,18 @@
+# Copyright: 2020 Masatake YAMATO
+# License: GPL-2
+
+CTAGS=$1
+O="--quiet --options=NONE "
+
+${CTAGS} $O \
+		 --extras=p --pseudo-tags=TAG_EXTRA_DESCRIPTION \
+		 --extras=+g \
+		 --extras-Robot='{whitespaceSwapped}' \
+		 -o - \
+		 input.robot
+
+${CTAGS} $O \
+		 --extras=p --pseudo-tags=TAG_EXTRA_DESCRIPTION \
+		 --extras-Robot=-'{whitespaceSwapped}' \
+		 -o - \
+		 input.robot

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

@@ -0,0 +1,4 @@
+!_TAG_EXTRA_DESCRIPTION	guest	/Include tags generated by guest parsers/
+!_TAG_EXTRA_DESCRIPTION	pseudo	/Include pseudo tags/
+!_TAG_EXTRA_DESCRIPTION!Robot	whitespaceSwapped	/Include tags swapping whitespace and underscore chars/
+!_TAG_EXTRA_DESCRIPTION	pseudo	/Include pseudo tags/

Tmain/ptag-field-sec.d/input.c

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

Tmain/ptag-field-sec.d/run.sh

@@ -0,0 +1,12 @@
+# Copyright: 2020 Masatake YAMATO
+# License: GPL-2
+
+CTAGS=$1
+O="--quiet --options=NONE "
+
+${CTAGS} $O \
+		 --extras=+p --pseudo-tags=TAG_FIELD_DESCRIPTION \
+		 --fields=le \
+		 --fields-C='{macrodef}' \
+		 -o - \
+		 input.c

Tmain/ptag-field-sec.d/stdout-expected.txt

@@ -0,0 +1,6 @@
+!_TAG_FIELD_DESCRIPTION	end	/end lines of various items/
+!_TAG_FIELD_DESCRIPTION	input	/input file/
+!_TAG_FIELD_DESCRIPTION	language	/Language of input file containing tag/
+!_TAG_FIELD_DESCRIPTION	name	/tag name/
+!_TAG_FIELD_DESCRIPTION	pattern	/pattern/
+!_TAG_FIELD_DESCRIPTION!C	macrodef	/macro definition/

Tmain/ptag-in-optlib-parser.d/input.foo

@@ -0,0 +1 @@
+# EMPTY

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

@@ -0,0 +1,25 @@
+# Copyright: 2016 Masatake YAMATO
+# License: GPL-2
+
+CTAGS=$1
+
+. ../utils.sh
+
+{
+    echo '# BUILTIN'
+    ${CTAGS} --quiet --options=NONE -o - --extras=p --pseudo-tags='*' \
+		 --pseudo-tags=-TAG_PROC_CWD \
+		 --fields='-{typeref}{file}' \
+	     input.sh
+
+    echo '# REGEX'
+    ${CTAGS} --quiet --options=NONE -o - --extras=p --pseudo-tags='*' \
+		 --pseudo-tags=-TAG_PROC_CWD \
+	     --langdef=foo --langmap=foo:+.foo \
+		 --_fielddef-foo='field,field example' \
+		 --fields='-{typeref}{file}' \
+		 --fields-foo='{field}' \
+		 --_extradef-foo='extra,extra example' \
+		 --extras-foo='{extra}' \
+	     --regex-foo='/abc/\1/k,kind,kinds/' input.foo
+} | grep -v VERSION

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

@@ -0,0 +1,33 @@
+# BUILTIN
+!_TAG_EXTRA_DESCRIPTION	pseudo	/Include pseudo tags/
+!_TAG_FIELD_DESCRIPTION	input	/input file/
+!_TAG_FIELD_DESCRIPTION	name	/tag name/
+!_TAG_FIELD_DESCRIPTION	pattern	/pattern/
+!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
+!_TAG_KIND_DESCRIPTION!Sh	a,alias	/aliases/
+!_TAG_KIND_DESCRIPTION!Sh	f,function	/functions/
+!_TAG_KIND_DESCRIPTION!Sh	h,heredoc	/label for here document/
+!_TAG_KIND_DESCRIPTION!Sh	s,script	/script files/
+!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/
+!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/
+!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/
+!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
+!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+# REGEX
+!_TAG_EXTRA_DESCRIPTION	pseudo	/Include pseudo tags/
+!_TAG_EXTRA_DESCRIPTION!foo	extra	/extra example/
+!_TAG_FIELD_DESCRIPTION	input	/input file/
+!_TAG_FIELD_DESCRIPTION	name	/tag name/
+!_TAG_FIELD_DESCRIPTION	pattern	/pattern/
+!_TAG_FIELD_DESCRIPTION!foo	field	/field example/
+!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
+!_TAG_KIND_DESCRIPTION!foo	k,kind	/kinds/
+!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/
+!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/
+!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/
+!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
+!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/

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

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

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

@@ -1,17 +1,11 @@
-# Copyright: 2016 Masatake YAMATO
+# Copyright: 2020 Masatake YAMATO
 # License: GPL-2
 
 CTAGS=$1
+O="--quiet --options=NONE "
 
-. ../utils.sh
-
-{
-    echo '# BUILTIN'
-    ${CTAGS} --quiet --options=NONE -o - --extras=p --pseudo-tags='*' \
-	     input.sh
-
-    echo '# REGEX'
-    ${CTAGS} --quiet --options=NONE -o - --extras=p --pseudo-tags='*' \
-	     --langdef=foo --langmap=foo:+.foo \
-	     --regex-foo='/abc/\1/k,kind,kinds/' input.foo
-} | grep -v VERSION
+${CTAGS} $O \
+		 --extras=+p --pseudo-tags=TAG_KIND_DESCRIPTION \
+		 --kinds-C=df \
+		 -o - \
+		 input.c

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

@@ -1,23 +1,2 @@
-# BUILTIN
-!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
-!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
-!_TAG_KIND_DESCRIPTION!Sh	a,alias	/aliases/
-!_TAG_KIND_DESCRIPTION!Sh	f,function	/functions/
-!_TAG_KIND_DESCRIPTION!Sh	h,heredoc	/label for here document/
-!_TAG_KIND_DESCRIPTION!Sh	s,script	/script files/
-!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/
-!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/
-!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/
-!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
-!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
-!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
-# REGEX
-!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
-!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
-!_TAG_KIND_DESCRIPTION!foo	k,kind	/kinds/
-!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/
-!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/
-!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/
-!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
-!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
-!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+!_TAG_KIND_DESCRIPTION!C	d,macro	/macro definitions/
+!_TAG_KIND_DESCRIPTION!C	f,function	/function definitions/

Tmain/ptag-proc-cwd.d/input.c

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

Tmain/ptag-proc-cwd.d/run.sh

@@ -0,0 +1,17 @@
+# Copyright: 2020 Masatake YAMATO
+# License: GPL-2
+
+CTAGS=$1
+
+. ../utils.sh
+exit_if_win32 $CTAGS
+
+O="--quiet --options=NONE "
+
+(
+	cd /
+	${CTAGS} $O \
+			 --extras=+p --pseudo-tags=TAG_PROC_CWD \
+			 -o - \
+			 input.c
+)

Tmain/ptag-proc-cwd.d/stdout-expected.txt

@@ -0,0 +1 @@
+!_TAG_PROC_CWD	/	//

configure.ac

@@ -739,6 +739,7 @@ AC_CHECK_FUNCS(mblen)
 
 AC_CONFIG_FILES([Makefile
 		 man/ctags.1.rst
+		 man/ctags-client-tools.7.rst
 		 man/ctags-incompatibilities.7.rst
 		 man/ctags-optlib.7.rst
 		 ])

docs/man-pages.rst

@@ -8,6 +8,7 @@ Man pages
 	:maxdepth: 3
 
 	ctags(1) <man/ctags.1.rst>
+	ctags-client-tools(7) <man/ctags-client-tools.7.rst>
 	ctags-incompatibilities(7) <man/ctags-incompatibilities.7.rst>
 	ctags-optlib(7) <man/ctags-optlib.7.rst>
 	tags(5) <man/tags.5.rst>