main: add --oneshot=<filename> option

Signed-off-by: Masatake YAMATO <yamato@redhat.com>

Author: masatake

Tmain/oneshot.d/run.sh

@@ -0,0 +1,19 @@
+# Copyright: 2026 Masatake YAMATO
+# License: GPL-2
+
+CTAGS=$1
+
+gen()
+{
+	cat <<EOF
+int v;
+int f(void)
+{
+	return 0;
+}
+EOF
+}
+
+gen | ${CTAGS} --quiet --options=NONE --oneshot=sort-no.c --sort=no
+gen | ${CTAGS} --quiet --options=NONE --oneshot=sort-yes.c --sort=yes
+gen | ${CTAGS} --quiet --options=NONE --oneshot=x.c -x

Tmain/oneshot.d/stderr-expected.txt

@@ -0,0 +1,6 @@
+v	sort-no.c	/^int v;$/;"	v	typeref:typename:int
+f	sort-no.c	/^int f(void)$/;"	f	typeref:typename:int
+f	sort-yes.c	/^int f(void)$/;"	f	typeref:typename:int
+v	sort-yes.c	/^int v;$/;"	v	typeref:typename:int
+f                function      2 x.c              int f(void)
+v                variable      1 x.c              int v;

Tmain/oneshot.d/stdout-expected.txt

@@ -221,6 +221,48 @@ Input/Output File Options
 
 	This option is quite esoteric and is empty by default.
 
+``--oneshot=<filename>``
+	Makes ctags behave as a filter, reading source
+	file contents from standard input and printing their tags to
+	standard output. When this option is enabled, the options ``-L``,
+	``-f``, ``-o``, and ``--totals`` are ignored.
+
+	ctags assumes *<filename>* is the input file
+	name of the contents. It affects language selection.
+	*<filename>* appears as the input file name in the tags output.
+
+	This option is useful for extracting interesting names in command
+	output.
+
+	For example you cat extract C preprocessor macro names in the source
+	code specified by a URL:
+
+	.. code-block:: console
+
+	   $ curl -s -o - \
+				'https://raw.githubusercontent.com/torvalds/linux/refs/heads/master/fs/buffer.c' \
+			| ./ctags --oneshot=buf.c --kinds-C='{macro}'
+	   BH_ENTRY	buf.c	/^#define BH_ENTRY(/;"	d	file:
+	   ...
+
+	Make the output in JSON format:
+
+	.. code-block:: console
+
+	   $ curl -s -o - \
+				'https://raw.githubusercontent.com/torvalds/linux/refs/heads/master/fs/buffer.c' \
+			| ./ctags --oneshot=buf.c --kinds-C='{macro}' --output-format=json \
+			| jq .
+	   {
+	     "_type": "tag",
+	     "name": "BH_ENTRY",
+	     "path": "buf.c",
+	     "pattern": "/^#define BH_ENTRY(/",
+	     "file": true,
+	     "kind": "macro"
+	   }
+	   ...
+
 ``--links[=(yes|no)]``
 	Indicates whether symbolic links (if supported) should be followed.
 	When disabled, symbolic links are ignored. This option is on by default.

docs/man/ctags.1.rst

@@ -27,6 +27,12 @@ Extend ``--map-<LANG>=`` and ``--langmap=`` options to choose a parser using reg
 
 	``--list-maps`` has also been extended to include regular-expression-based mappings.
 
+New option: ``--oneshot=<filename>``
+
+	Makes @CTAGS_NAME_EXECUTABLE@ behave as a filter, reading source
+	file contents from standard input and printing their tags to
+	standard output.
+
 Incompatible changes
 ---------------------------------------------------------------------
 Messages for broken symlinks are now emitted at NOTICE level instead of

docs/news/HEAD.rst

@@ -227,6 +227,9 @@ static optionDescription LongOptionDescription [] = {
  {1,0,"  --filter-terminator=<string>"},
  {1,0,"       Specify <string> to print to stdout following the tags for each file"},
  {1,0,"       parsed when --filter is enabled."},
+ {1,0,"  --oneshot=<filename>"},
+ {1,0,"       Behave as a filter, reading file contents from standard input and"},
+ {1,0,"       writing tags to standard output. <filename> is used as the input field of tags."},
  {1,0,"  --links[=(yes|no)]"},
  {1,0,"       Indicate whether symbolic links should be followed [yes]."},
  {1,0,"  --maxdepth=<N>"},
@@ -496,6 +499,8 @@ static optionDescription LongOptionDescription [] = {
  {1,0,"       Print this option summary including experimental features."},
  {1,0,"  --license"},
  {1,0,"       Print details of software license."},
+ {1,0,"  --oneshot-limit=<bytes>"},
+ {1,0,"       Limit the input size in the oneshot mode, in bytes (default is 32MB)."},
  {0,0,"  --print-language"},
  {0,0,"       Don't make tags file but just print the guessed language name for"},
  {0,0,"       input file."},
@@ -1675,6 +1680,27 @@ static void processHelpFullOption (
 	exit (0);
 }
 
+static void processOneshot (
+		const char *const option,
+		const char *const parameter)
+{
+	if (!parameter || parameter[0] == '\0')
+		error (FATAL, "No input file name given to --%s=%s", option, parameter);
+
+	static struct interactiveModeArgs args = { .sandbox = false, };
+	Option.interactive |= INTERACTIVE_MODE|INTERACTIVE_ONESHOT;
+
+#ifdef HAVE_SECCOMP
+	Option.interactive |= INTERACTIVE_WITH_SANDBOX;
+	args.sandbox = true;
+#endif
+
+	args.fname = parameter;
+	args.limit = oneshotLimit;
+
+	setMainLoop (interactiveOneshot, &args);
+}
+
 #ifdef HAVE_JANSSON
 static void processInteractiveOption (
 		const char *const option,
@@ -2723,6 +2749,28 @@ static bool inOneshotMode (void)
 	return (Option.interactive & INTERACTIVE_ONESHOT);
 }
 
+static void oneshotSetLimit (size_t limit)
+{
+	verbose ("adjust input limit of oneshot mode: %lu", (unsigned long)limit);
+	oneshotLimit = limit;
+}
+
+static void processOneshotLimit (
+		const char *const option, const char *const parameter)
+{
+	if (parameter == NULL || parameter[0] == '\0')
+		error (FATAL, "A positive number or 0 is needed after --%s option", option);
+
+	unsigned long limit = 0;
+	if (!strToULong(parameter, 0, &limit))
+		error (FATAL, "Invalid oneshot limit: %s", parameter);
+	if (limit > SIZE_MAX)
+		error (FATAL, "Too large limit: %s (> %lu)",
+			   parameter, (unsigned long)SIZE_MAX);
+
+	oneshotSetLimit ((size_t)limit);
+}
+
 static void processSortOption (
 		const char *const option, const char *const parameter)
 {
@@ -3125,6 +3173,8 @@ static parametricOption ParametricOptions [] = {
 	{ "list-roles",             processListRolesOption,         true,   STAGE_ANY },
 	{ "list-subparsers",        processListSubparsersOption,    true,   STAGE_ANY },
 	{ "maxdepth",               processMaxRecursionDepthOption, true,   STAGE_ANY },
+	{ "oneshot",                processOneshot,                 true,   STAGE_ANY },
+	{ "oneshot-limit",          processOneshotLimit,            true,   STAGE_ANY },
 	{ "optlib-dir",             processOptlibDir,               false,  STAGE_ANY },
 	{ "options",                processOptionFile,              false,  STAGE_ANY },
 	{ "options-maybe",          processOptionFileMaybe,         false,  STAGE_ANY },

main/options.c

@@ -221,6 +221,48 @@ Input/Output File Options
 
 	This option is quite esoteric and is empty by default.
 
+``--oneshot=<filename>``
+	Makes @CTAGS_NAME_EXECUTABLE@ behave as a filter, reading source
+	file contents from standard input and printing their tags to
+	standard output. When this option is enabled, the options ``-L``,
+	``-f``, ``-o``, and ``--totals`` are ignored.
+
+	@CTAGS_NAME_EXECUTABLE@ assumes *<filename>* is the input file
+	name of the contents. It affects language selection.
+	*<filename>* appears as the input file name in the tags output.
+
+	This option is useful for extracting interesting names in command
+	output.
+
+	For example you cat extract C preprocessor macro names in the source
+	code specified by a URL:
+
+	.. code-block:: console
+
+	   $ curl -s -o - \
+				'https://raw.githubusercontent.com/torvalds/linux/refs/heads/master/fs/buffer.c' \
+			| ./ctags --oneshot=buf.c --kinds-C='{macro}'
+	   BH_ENTRY	buf.c	/^#define BH_ENTRY(/;"	d	file:
+	   ...
+
+	Make the output in JSON format:
+
+	.. code-block:: console
+
+	   $ curl -s -o - \
+				'https://raw.githubusercontent.com/torvalds/linux/refs/heads/master/fs/buffer.c' \
+			| ./ctags --oneshot=buf.c --kinds-C='{macro}' --output-format=json \
+			| jq .
+	   {
+	     "_type": "tag",
+	     "name": "BH_ENTRY",
+	     "path": "buf.c",
+	     "pattern": "/^#define BH_ENTRY(/",
+	     "file": true,
+	     "kind": "macro"
+	   }
+	   ...
+
 ``--links[=(yes|no)]``
 	Indicates whether symbolic links (if supported) should be followed.
 	When disabled, symbolic links are ignored. This option is on by default.