Merge pull request #3149 from masatake/tcl-force-enabling-class-handler

masatake · web-flow · commit 6a03e55e7435 · 2021-09-07T05:52:28.000+09:00
ITcl,TclOO: introduce forceuse parameters
diff --git a/Tmain/list-params.d/stdout-expected.txt b/Tmain/list-params.d/stdout-expected.txt
@@ -1,10 +1,12 @@
 # ALL
-#LANGUAGE      NAME    DESCRIPTION
-CPreProcessor  _expand expand macros if their definitions are in the current C/C++/CUDA input file (true or [false])
-CPreProcessor  define  define replacement for an identifier (name(params,...)=definition)
-CPreProcessor  if0     examine code within "#if 0" branch (true or [false])
-CPreProcessor  ignore  a token to be specially handled
-Fypp           guest   parser run after Fypp parser parses the original input ("NONE" or a parser name [Fortran])
+#LANGUAGE      NAME     DESCRIPTION
+CPreProcessor  _expand  expand macros if their definitions are in the current C/C++/CUDA input file (true or [false])
+CPreProcessor  define   define replacement for an identifier (name(params,...)=definition)
+CPreProcessor  if0      examine code within "#if 0" branch (true or [false])
+CPreProcessor  ignore   a token to be specially handled
+Fypp           guest    parser run after Fypp parser parses the original input ("NONE" or a parser name [Fortran])
+ITcl           forceUse enable the parser even when `itcl' namespace is not specified in the input (true or [false])
+TclOO          forceUse enable the parser even when `oo' namespace is not specified in the input (true or [false])
 
 # ALL MACHINABLE
 #LANGUAGE	NAME	DESCRIPTION
@@ -13,13 +15,17 @@ CPreProcessor	define	define replacement for an identifier (name(params,...)=defi
 CPreProcessor	if0	examine code within "#if 0" branch (true or [false])
 CPreProcessor	ignore	a token to be specially handled
 Fypp	guest	parser run after Fypp parser parses the original input ("NONE" or a parser name [Fortran])
+ITcl	forceUse	enable the parser even when `itcl' namespace is not specified in the input (true or [false])
+TclOO	forceUse	enable the parser even when `oo' namespace is not specified in the input (true or [false])
 
 # ALL MACHINABLE NOHEADER
 CPreProcessor	_expand	expand macros if their definitions are in the current C/C++/CUDA input file (true or [false])
 CPreProcessor	define	define replacement for an identifier (name(params,...)=definition)
 CPreProcessor	if0	examine code within "#if 0" branch (true or [false])
 CPreProcessor	ignore	a token to be specially handled
 Fypp	guest	parser run after Fypp parser parses the original input ("NONE" or a parser name [Fortran])
+ITcl	forceUse	enable the parser even when `itcl' namespace is not specified in the input (true or [false])
+TclOO	forceUse	enable the parser even when `oo' namespace is not specified in the input (true or [false])
 
 # CPP
 #NAME    DESCRIPTION
diff --git a/Units/parser-cpreprocessor.r/if0-false-with-param.c.d/args.ctags b/Units/parser-cpreprocessor.r/if0-false-with-param.c.d/args.ctags
@@ -1,2 +1 @@
---param-CPreProcessor:if0=false
-
+--param-CPreProcessor.if0=false
diff --git a/Units/parser-cpreprocessor.r/if0-true-with-param.c.d/args.ctags b/Units/parser-cpreprocessor.r/if0-true-with-param.c.d/args.ctags
@@ -1,2 +1 @@
---param-CPreProcessor:if0=true
-
+--param-CPreProcessor.if0=true
diff --git a/Units/parser-cpreprocessor.r/macroexpand.d/args.ctags b/Units/parser-cpreprocessor.r/macroexpand.d/args.ctags
@@ -1,4 +1,4 @@
---param-CPreProcessor:_expand=1
+--param-CPreProcessor._expand=1
 --fields-C=+{macrodef}
 --fields=+Ss
 --sort=no
diff --git a/Units/parser-cpreprocessor.r/macros-specified-with-param.c.d/args.ctags b/Units/parser-cpreprocessor.r/macros-specified-with-param.c.d/args.ctags
@@ -1,5 +1,5 @@
 --kinds-c=+p
 --fields=+S
---param-CPreProcessor:ignore=MACRO2
+--param-CPreProcessor.ignore=MACRO2
 --fields=+r
 --extras=+r
diff --git a/Units/parser-fypp.r/run-alt-guest.d/args.ctags b/Units/parser-fypp.r/run-alt-guest.d/args.ctags
@@ -1,6 +1,6 @@
 --fields=+e
 # The next redundant options are for improve the test coverage.
---param-Fypp:guest=Lisp
---param-Fypp:guest=NONE
---param-Fypp:guest=Java
+--param-Fypp.guest=Lisp
+--param-Fypp.guest=NONE
+--param-Fypp.guest=Java
 --extras=+g
diff --git a/Units/parser-itcl.r/force-use.d/args.ctags b/Units/parser-itcl.r/force-use.d/args.ctags
@@ -0,0 +1,3 @@
+--sort=no
+--param-ITcl.forceUse=1
+--fields=+{language}
diff --git a/Units/parser-itcl.r/force-use.d/expected.tags b/Units/parser-itcl.r/force-use.d/expected.tags
@@ -0,0 +1,2 @@
+MyClass	input.tcl	/^class MyClass {$/;"	c	language:ITcl
+foo	input.tcl	/^    public method foo {} {$/;"	m	language:ITcl	class:MyClass
diff --git a/Units/parser-itcl.r/force-use.d/input.tcl b/Units/parser-itcl.r/force-use.d/input.tcl
@@ -0,0 +1,14 @@
+# Assume this source file is loaded from
+# another source file:
+# 
+#   package require Itcl
+#   namespace import itcl::*
+#   source input.tcl
+#
+class MyClass {
+    public method foo {} {
+    }
+}
+
+body MyClass::foo {} {
+}
diff --git a/Units/parser-ldscript.r/ld-symtab.d/args.ctags b/Units/parser-ldscript.r/ld-symtab.d/args.ctags
@@ -1,3 +1,3 @@
---param-CPreProcessor:_expand=1
+--param-CPreProcessor._expand=1
 --fields-CPreProcessor=+{macrodef}
 --fields=+{signature}
diff --git a/Units/parser-tcloo.r/force-use.d/args.ctags b/Units/parser-tcloo.r/force-use.d/args.ctags
@@ -0,0 +1,3 @@
+--sort=no
+--param-TclOO.forceUse=1
+--fields=+{language}
diff --git a/Units/parser-tcloo.r/force-use.d/expected.tags b/Units/parser-tcloo.r/force-use.d/expected.tags
@@ -0,0 +1,3 @@
+X	input.tcl	/^class create X {$/;"	c	language:TclOO
+add	input.tcl	/^    method add v {$/;"	m	language:TclOO	class:X
+doSomething	input.tcl	/^    }; method doSomething {v} {$/;"	m	language:TclOO	class:X
diff --git a/Units/parser-tcloo.r/force-use.d/input.tcl b/Units/parser-tcloo.r/force-use.d/input.tcl
@@ -0,0 +1,11 @@
+# Assume this source file is loaded from
+# another source file:
+# 
+#   namespace import oo::*
+#   source input.tcl
+#
+class create X {
+    method add v {
+    }; method doSomething {v} {
+    }
+}
diff --git a/docs/man-pages.rst b/docs/man-pages.rst
@@ -9,15 +9,19 @@ Man pages
 
 	ctags(1) <man/ctags.1.rst>
 	tags(5) <man/tags.5.rst>
+
 	ctags-optlib(7) <man/ctags-optlib.7.rst>
 	ctags-client-tools(7) <man/ctags-client-tools.7.rst>
+	ctags-incompatibilities(7) <man/ctags-incompatibilities.7.rst>
 	ctags-faq(7) <man/ctags-faq.7.rst>
+
+	ctags-lang-inko(7) <man/ctags-lang-inko.7.rst>
 	ctags-lang-iPythonCell(7) <man/ctags-lang-iPythonCell.7.rst>
 	ctags-lang-julia(7) <man/ctags-lang-julia.7.rst>
 	ctags-lang-python(7) <man/ctags-lang-python.7.rst>
-	ctags-lang-verilog(7) <man/ctags-lang-verilog.7.rst>
-	ctags-lang-inko(7) <man/ctags-lang-inko.7.rst>
 	ctags-lang-r(7) <man/ctags-lang-r.7.rst>
 	ctags-lang-sql(7) <man/ctags-lang-sql.7.rst>
-	ctags-incompatibilities(7) <man/ctags-incompatibilities.7.rst>
+	ctags-lang-tcl(7) <man/ctags-lang-tcl.7.rst>
+	ctags-lang-verilog(7) <man/ctags-lang-verilog.7.rst>
+
 	readtags(1) <man/readtags.1.rst>
diff --git a/docs/man/ctags-lang-tcl.7.rst b/docs/man/ctags-lang-tcl.7.rst
@@ -0,0 +1,73 @@
+.. _ctags-lang-tcl(7):
+
+==============================================================
+ctags-lang-tcl
+==============================================================
+
+Random notes about tagging tcl source code with Universal Ctags
+
+:Version: 5.9.0
+:Manual group: Universal Ctags
+:Manual section: 7
+
+SYNOPSIS
+--------
+|	**ctags** ... --languages=+Tcl ...
+|	**ctags** ... --language-force=Tcl ...
+|	**ctags** ... --map-Tcl=+.tcl ...
+
+DESCRIPTION
+-----------
+This man page gathers random notes about tagging tcl source code.
+
+TAGGING language objects of OO Extensions
+-----------------------------------------
+
+TclOO parser and ITcl parser are subparsers running on the Tcl parser.
+As the names of parsers show, they are for tagging language objects of
+object oriented programming extensions for the Tcl language.
+
+A pattern, "namespace import oo" in an input file activates the TclOO
+parser. A pattern, "namespace import itcl" in an input file activates
+the ITcl parser.
+
+There are cases that one of the OO extensions is used though neither
+pattern are appeared in an input file.
+
+Consider the following input files:
+
+"main.tcl"
+
+.. code-block:: Tcl
+
+	package require Itcl
+	namespace import itcl::*
+	source input.tcl
+
+"input.tcl"
+
+.. code-block:: Tcl
+
+	class MyClass {
+		public method foo {} {
+		}
+	}
+
+The pattern for activating the ITcl parser is not appeared
+in "input.tcl" though "class" command is used. As a result,
+ctags cannot extract "MyClass".
+
+The parameters `TclOO.forceUse=true|[false]` and
+`ITcl.forceuse=true|[false]` for handling this situation. With the
+parameter, you can force ctags to activate one of the subparsers.
+
+You can use the parameters like ``--param-ITcl.forceuse=true``
+in a command-line.
+
+Note that you can enable only one of ITcl parser or TclOO parser.
+Enabling both parsers with specifying the parameters can cause
+unexpected results.
+
+SEE ALSO
+--------
+:ref:`ctags(1) <ctags(1)>`
diff --git a/docs/man/ctags.1.rst b/docs/man/ctags.1.rst
@@ -684,7 +684,7 @@ See "`TAG ENTRIES`_" about fields, kinds, roles, and extras.
 	description of ``MASTER`` column of ``--list-kinds-full``.
 
 ..	COMMENT:
-	``--param-<LANG>:name=argument`` is moved to "Language Specific Options"
+	``--param-<LANG>.name=argument`` is moved to "Language Specific Options"
 
 ``--pattern-length-limit=<N>``
 	Truncate patterns of tag entries after *<N>* characters. Disable by setting to 0
@@ -993,7 +993,7 @@ Language Specific Options
 	would cause the source file to be incorrectly parsed. Correct behavior
 	can be restored by specifying "``-I CLASS=class``".
 
-``--param-<LANG>:<name>=<argument>``
+``--param-<LANG>.<name>=<argument>``
 	Set a *<LANG>* specific parameter, a parameter specific to the *<LANG>*.
 
 	Available parameters can be listed with ``--list-params``.
diff --git a/docs/output-tags.rst b/docs/output-tags.rst
@@ -526,12 +526,12 @@ A parser defines a set of parameters. Each parameter has name and
 takes an argument. A user can set a parameter with following notation
 ::
 
-   --param-<LANG>:name=arg
+   --param-<LANG>.name=arg
 
 An example of specifying a parameter
 ::
 
-   --param-CPreProcessor:if0=true
+   --param-CPreProcessor.if0=true
 
 Here `if0` is a name of parameter of CPreProcessor parser and
 `true` is the value of it.
diff --git a/docs/parser-cxx.rst b/docs/parser-cxx.rst
@@ -178,7 +178,7 @@ SAME file can be expanded with following options:
 
 .. code-block:: text
 
-   --param-CPreProcessor:_expand=1
+   --param-CPreProcessor._expand=1
    --fields-C=+{macrodef}
    --fields-C++=+{macrodef}
    --fields-CUDA=+{macrodef}
@@ -209,7 +209,7 @@ The output without options:
 The output with options:
 .. code-block::
 
-   $ ctags --param-CPreProcessor:_expand=1 --fields-C=+'{macrodef}' --fields=+'{signature}' -o - input.c
+   $ ctags --param-CPreProcessor._expand=1 --fields-C=+'{macrodef}' --fields=+'{signature}' -o - input.c
    BEGIN	input.c	/^#define BEGIN /;"	d	language:C	file:	macrodef:{
    DEFUN	input.c	/^#define DEFUN(/;"	d	language:C	file:	signature:(NAME)	macrodef:int NAME (int x, int y)
    END	input.c	/^#define END /;"	d	language:C	file:	macrodef:}
diff --git a/main/options.c b/main/options.c
@@ -407,7 +407,7 @@ static optionDescription LongOptionDescription [] = {
  {1,0,"  -I [+|-]<list>|@<file>"},
  {1,0,"       A <list> of tokens to be specially handled is read from either the"},
  {1,0,"       command line or the specified <file>."},
- {1,0,"  --param-<LANG>:<name>=<argument>"},
+ {1,0,"  --param-<LANG>.<name>=<argument>"},
  {1,0,"       Set <LANG> specific parameter. Available parameters can be listed with --list-params."},
  {1,0,""},
  {1,0,"Listing Options"},
@@ -796,11 +796,17 @@ extern langType getLanguageComponentInOptionFull (const char *const option,
 	}
 
 	/* Extract <LANG> from
-	 * --param-<LANG>:<PARAM>=..., and
+	 * --param-<LANG>.<PARAM>=..., and
 	 * --_roledef-<LANG>.<KIND>=... */
+
+	/*  `:' is only for keeping self compatibility. */
 	sep = strpbrk (lang, ":.");
 	if (sep)
+	{
+		if (*sep == ':')
+			error (WARNING, "using `:' as a separator is obsolete; use `.' instead: --%s", option);
 		lang_len = sep - lang;
+	}
 	language = getNamedLanguageFull (lang, lang_len, noPretending, false);
 	if (language == LANG_IGNORE)
 	{
@@ -2018,8 +2024,9 @@ extern bool processParamOption (
 		return false;
 
 	sep = option + strlen ("param-") + strlen (getLanguageName (language));
-	if (*sep != ':')
-		error (FATAL, "no separator(:) is given for %s=%s", option, value);
+	/* `:' is only for keeping self compatibility */
+	if (! (*sep == '.' || *sep == ':' ))
+		error (FATAL, "no separator(.) is given for %s=%s", option, value);
 	name = sep + 1;
 
 	if (value == NULL || value [0] == '\0')
diff --git a/main/parse.c b/main/parse.c
@@ -2856,10 +2856,10 @@ extern bool processKindsOption (
  * How --param should be change to align --roles-<LANG> notation
  * ---------------------------------------------------------------------
  *
- * --_param-<LANG>.name=argument
+ * --param-<LANG>.name=argument
  *
- *  * The notation was
- * --_param-<LANG>:name=argument
+ * The notation was
+ * --param-<LANG>:name=argument
  *
  *
  * How --paramdef should be to align --roles-<LANG> notation
diff --git a/man/Makefile.am b/man/Makefile.am
@@ -30,6 +30,7 @@ GEN_IN_MAN_FILES = \
 	ctags-lang-iPythonCell.7 \
 	ctags-lang-julia.7 \
 	ctags-lang-python.7 \
+	ctags-lang-tcl.7 \
 	ctags-lang-verilog.7 \
 	ctags-lang-inko.7 \
 	ctags-lang-r.7 \
diff --git a/man/ctags-lang-tcl.7.rst.in b/man/ctags-lang-tcl.7.rst.in
@@ -0,0 +1,73 @@
+.. _ctags-lang-tcl(7):
+
+==============================================================
+ctags-lang-tcl
+==============================================================
+-------------------------------------------------------------------
+Random notes about tagging tcl source code with Universal Ctags
+-------------------------------------------------------------------
+:Version: @VERSION@
+:Manual group: Universal Ctags
+:Manual section: 7
+
+SYNOPSIS
+--------
+|	**@CTAGS_NAME_EXECUTABLE@** ... --languages=+Tcl ...
+|	**@CTAGS_NAME_EXECUTABLE@** ... --language-force=Tcl ...
+|	**@CTAGS_NAME_EXECUTABLE@** ... --map-Tcl=+.tcl ...
+
+DESCRIPTION
+-----------
+This man page gathers random notes about tagging tcl source code.
+
+TAGGING language objects of OO Extensions
+-----------------------------------------
+
+TclOO parser and ITcl parser are subparsers running on the Tcl parser.
+As the names of parsers show, they are for tagging language objects of
+object oriented programming extensions for the Tcl language.
+
+A pattern, "namespace import oo" in an input file activates the TclOO
+parser. A pattern, "namespace import itcl" in an input file activates
+the ITcl parser.
+
+There are cases that one of the OO extensions is used though neither
+pattern are appeared in an input file.
+
+Consider the following input files:
+
+"main.tcl"
+
+.. code-block:: Tcl
+
+	package require Itcl
+	namespace import itcl::*
+	source input.tcl
+
+"input.tcl"
+
+.. code-block:: Tcl
+
+	class MyClass {
+		public method foo {} {
+		}
+	}
+
+The pattern for activating the ITcl parser is not appeared
+in "input.tcl" though "class" command is used. As a result,
+ctags cannot extract "MyClass".
+
+The parameters `TclOO.forceUse=true|[false]` and
+`ITcl.forceuse=true|[false]` for handling this situation. With the
+parameter, you can force ctags to activate one of the subparsers.
+
+You can use the parameters like ``--param-ITcl.forceuse=true``
+in a command-line.
+
+Note that you can enable only one of ITcl parser or TclOO parser.
+Enabling both parsers with specifying the parameters can cause
+unexpected results.
+
+SEE ALSO
+--------
+ctags(1)
diff --git a/man/ctags.1.rst.in b/man/ctags.1.rst.in
diff --git a/parsers/itcl.c b/parsers/itcl.c
diff --git a/parsers/tcloo.c b/parsers/tcloo.c

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1 @@`
`1`		`---param-CPreProcessor:if0=false`
`2`		`-`
	`1`	`+--param-CPreProcessor.if0=false`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1 @@`
`1`		`---param-CPreProcessor:if0=true`
`2`		`-`
	`1`	`+--param-CPreProcessor.if0=true`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`---param-CPreProcessor:_expand=1`
	`1`	`+--param-CPreProcessor._expand=1`
`2`	`2`	`--fields-C=+{macrodef}`
`3`	`3`	`--fields=+Ss`
`4`	`4`	`--sort=no`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+--sort=no`
	`2`	`+--param-ITcl.forceUse=1`
	`3`	`+--fields=+{language}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+MyClass input.tcl /^class MyClass {$/;" c language:ITcl`
	`2`	`+foo input.tcl /^ public method foo {} {$/;" m language:ITcl class:MyClass`