1.. _ctags(1): 2 3============================================================== 4@CTAGS_NAME_EXECUTABLE@ 5============================================================== 6-------------------------------------------------------------- 7Generate tag files for source code 8-------------------------------------------------------------- 9:Version: @VERSION@ 10:Manual group: Universal Ctags 11:Manual section: 1 12 13SYNOPSIS 14-------- 15| **@CTAGS_NAME_EXECUTABLE@** [<options>] [<source_file(s)>] 16| **@ETAGS_NAME_EXECUTABLE@** [<options>] [<source_file(s)>] 17 18 19DESCRIPTION 20----------- 21 22The *@CTAGS_NAME_EXECUTABLE@* and *@ETAGS_NAME_EXECUTABLE@* (see ``-e`` option) programs 23(hereinafter collectively referred to as @CTAGS_NAME_EXECUTABLE@, 24except where distinguished) generate an index (or "tag") file for a 25variety of *language objects* found in *source file(s)*. This tag file allows 26these items to be quickly and easily located by a text editor or other 27utilities (*client tools*). A *tag* signifies a language object for which an index entry is 28available (or, alternatively, the index entry created for that object). 29 30Alternatively, @CTAGS_NAME_EXECUTABLE@ can generate a cross reference 31file which lists, in human readable form, information about the various 32language objects found in a set of source files. 33 34Tag index files are supported by numerous editors, which allow the user to 35locate the object associated with a name appearing in a source file and 36jump to the file and line which defines the name. See the manual of your 37favorite editor about utilizing @CTAGS_NAME_EXECUTABLE@ command and 38the tag index files in the editor. 39 40@CTAGS_NAME_EXECUTABLE@ is capable of generating different *kinds* of tags 41for each of many different *languages*. For a complete list of supported 42languages, the names by which they are recognized, and the kinds of tags 43which are generated for each, see the ``--list-languages`` and ``--list-kinds-full`` 44options. 45 46This man page describes *Universal Ctags*, an implementation of ctags 47derived from *Exuberant Ctags*. The major incompatible changes between 48Universal Ctags and Exuberant Ctags are enumerated in 49ctags-incompatibilities(7). 50 51One of the advantages of Exuberant Ctags is that it allows a user to 52define a new parser from the command line. Extending this capability is one 53of the major features of Universal Ctags. ctags-optlib(7) 54describes how the capability is extended. 55 56Newly introduced experimental features are not explained here. If you 57are interested in such features and @CTAGS_NAME_EXECUTABLE@ internals, 58visit https://docs.ctags.io/. 59 60 61COMMAND LINE INTERFACE 62---------------------- 63 64Despite the wealth of available options, defaults are set so that 65@CTAGS_NAME_EXECUTABLE@ is most commonly executed without any options (e.g. 66"``@CTAGS_NAME_EXECUTABLE@ *``", or "``@CTAGS_NAME_EXECUTABLE@ -R``"), which will 67create a tag file in the current directory for all recognized source 68files. The options described below are provided merely to allow custom 69tailoring to meet special needs. 70 71Note that spaces separating the single-letter options from their parameters 72are optional. 73 74Note also that the boolean parameters to the long form options (those 75beginning with ``--`` and that take a ``[=(yes|no)]`` parameter) may be omitted, 76in which case ``=yes`` is implied. (e.g. ``--sort`` is equivalent to ``--sort=yes``). 77Note further that ``=1``, ``=on``, and ``=true`` are considered synonyms for ``=yes``, 78and that ``=0``, ``=off``, and ``=false`` are considered synonyms for ``=no``. 79 80Some options are either ignored or useful only when used while running in 81etags mode (see ``-e`` option). Such options will be noted. 82 83*<options>* must precede the *<source_file(s)>* following the standard POSIX 84convention. 85 86Options taking language names will accept those names in either upper or 87lower case. See the ``--list-languages`` option for a complete list of the 88built-in language names. 89 90 91Letters and names 92~~~~~~~~~~~~~~~~~ 93 94Some options take one-letter flags as parameters (e.g. ``--kinds-<LANG>`` option). 95Specifying just letters help a user create a complicated command line 96quickly. However, a command line including sequences of one-letter flags 97becomes difficult to understand. 98 99Universal Ctags accepts long-name flags in 100addition to such one-letter flags. The long-name and one-letter flags can be mixed in an 101option parameter by surrounding each long-name by braces. Thus, for an 102example, the following three notations for ``--kinds-C`` option have 103the same meaning:: 104 105 --kinds-C=+pLl 106 --kinds-C=+{prototype}{label}{local} 107 --kinds-C=+{prototype}L{local} 108 109Note that braces may be meta characters in your shell. Put 110single quotes in such case. 111 112``--list-...`` options shows one-letter flags and associated long-name flags. 113 114 115List options 116~~~~~~~~~~~~ 117 118Universal Ctags introduces many ``--list-...`` options that provide 119the internal data of Universal Ctags (See "`Listing Options`_"). Both users and client tools may 120use the data. ``--with-list-header`` and ``--machinable`` options 121adjust the output of the most of ``--list-...`` options. 122 123The default setting (``--with-list-header=yes`` and ``--machinable=no``) 124is for using interactively from a terminal. The header that explains 125the meaning of columns is simply added to the output, and each column is 126aligned in all lines. The header line starts with a hash ('``#``') character. 127 128For scripting in a client tool, ``--with-list-header=no`` and 129``--machinable=yes`` may be useful. The header is not added to the 130output, and each column is separated by tab characters. 131 132Note the order of columns will change in the future release. 133However, labels in the header will not change. So by scanning 134the header, a client tool can find the index for the target 135column. 136 137.. options that should be explained and revised here 138 ``--list-features`` (done) 139 ``--machinable`` (done) 140 ``--with-list-header`` (done) 141 142 143OPTIONS 144------------ 145@CTAGS_NAME_EXECUTABLE@ has more options than listed here. 146Options starting with an underscore character, such as ``--_echo=<msg>``, 147are not listed here. They are experimental or for debugging purpose. 148 149Notation: ``<foo>`` is for a variable string ``foo``, ``[ ... ]`` for optional, 150``|`` for selection, and ``( ... )`` for grouping. For example 151``--foo[=(yes|no)]'' means ``--foo``, ``-foo=yes``, or ``-foo=no``. 152 153.. _option_input_output_file: 154 155Input/Output File Options 156~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 157``--exclude=<pattern>`` 158 Add *<pattern>* to a list of excluded files and directories. This option may 159 be specified as many times as desired. For each file name considered 160 by @CTAGS_NAME_EXECUTABLE@, each pattern specified using this option 161 will be compared against both the complete path (e.g. 162 ``some/path/base.ext``) and the base name (e.g. ``base.ext``) of the file, thus 163 allowing patterns which match a given file name irrespective of its 164 path, or match only a specific path. 165 166 If appropriate support is available 167 from the runtime library of your C compiler, then pattern may 168 contain the usual shell wildcards (not regular expressions) common on 169 Unix (be sure to quote the option parameter to protect the wildcards from 170 being expanded by the shell before being passed to @CTAGS_NAME_EXECUTABLE@; 171 also be aware that wildcards can match the slash character, '``/``'). 172 You can determine if shell wildcards are available on your platform by 173 examining the output of the ``--list-features`` option, which will include 174 ``wildcards`` in the compiled feature list; otherwise, pattern is matched 175 against file names using a simple textual comparison. 176 177 If *<pattern>* begins with the character '``@``', then the rest of the string 178 is interpreted as a file name from which to read exclusion patterns, 179 one per line. If pattern is empty, the list of excluded patterns is 180 cleared. 181 182 Note that at program startup, the default exclude list contains names of 183 common hidden and system files, patterns for binary files, and directories 184 for which it is generally not desirable to descend while processing the 185 ``--recurse`` option. To see the list of built-in exclude patterns, use 186 ``--list-excludes``. 187 188 See also the description for ``--exclude-exception=`` option. 189 190``--exclude-exception=<pattern>`` 191 Add *<pattern>* to a list of included files and directories. The pattern 192 affects the files and directories that are excluded by the pattern 193 specified with ``--exclude=`` option. 194 195 For an example, you want @CTAGS_NAME_EXECUTABLE@ to ignore all files 196 under ``foo`` directory except ``foo/main.c``, use the following command 197 line: ``--exclude=foo/* --exclude-exception=foo/main.c``. 198 199``--filter[=(yes|no)]`` 200 Makes @CTAGS_NAME_EXECUTABLE@ behave as a filter, reading source 201 file names from standard input and printing their tags to standard 202 output on a file-by-file basis. If ``--sort`` is enabled, tags are sorted 203 only within the source file in which they are defined. File names are 204 read from standard input in line-oriented input mode (see note for ``-L`` 205 option) and only after file names listed on the command line or from 206 any file supplied using the ``-L`` option. When this option is enabled, 207 the options ``-f``, ``-o``, and ``--totals`` are ignored. This option is quite 208 esoteric and is disabled by default. 209 210``--filter-terminator=<string>`` 211 Specifies a *<string>* to print to standard output following the tags for 212 each file name parsed when the ``--filter`` option is enabled. This may 213 permit an application reading the output of @CTAGS_NAME_EXECUTABLE@ 214 to determine when the output for each file is finished. 215 216 Note that if the 217 file name read is a directory and ``--recurse`` is enabled, this string will 218 be printed only once at the end of all tags found for by descending 219 the directory. This string will always be separated from the last tag 220 line for the file by its terminating newline. 221 222 This option is quite esoteric and is empty by default. 223 224``--links[=(yes|no)]`` 225 Indicates whether symbolic links (if supported) should be followed. 226 When disabled, symbolic links are ignored. This option is on by default. 227 228``--maxdepth=<N>`` 229 Limits the depth of directory recursion enabled with the ``--recurse`` 230 (``-R``) option. 231 232``--recurse[=(yes|no)]`` 233 Recurse into directories encountered in the list of supplied files. 234 235 If the list of supplied files is empty and no file list is specified with 236 the ``-L`` option, then the current directory (i.e. '``.``') is assumed. 237 Symbolic links are followed by default (See ``--links`` option). If you don't like these behaviors, either 238 explicitly specify the files or pipe the output of ``find(1)`` into 239 "``@CTAGS_NAME_EXECUTABLE@ -L -``" instead. See, also, the ``--exclude`` and 240 ``--maxdepth`` to limit recursion. 241 242 Note: This option is not supported on 243 all platforms at present. It is available if the output of the ``--help`` 244 option includes this option. 245 246.. TODO(code): --list-features option should support this. 247 248``-R`` 249 Equivalent to ``--recurse``. 250 251``-L <file>`` 252 Read from *<file>* a list of file names for which tags should be generated. 253 254 If file is specified as '``-``', then file names are read from standard 255 input. File names read using this option are processed following file 256 names appearing on the command line. Options are also accepted in this 257 input. If this option is specified more than once, only the last will 258 apply. 259 260 Note: file is read in line-oriented mode, where a new line is 261 the only delimiter and non-trailing white space is considered significant, 262 in order that file names containing spaces may be supplied 263 (however, trailing white space is stripped from lines); this can affect 264 how options are parsed if included in the input. 265 266``--append[=(yes|no)]`` 267 Indicates whether tags generated from the specified files should be 268 appended to those already present in the tag file or should replace them. 269 This option is ``no`` by default. 270 271``-a`` 272 Equivalent to ``--append``. 273 274``-f <tagfile>`` 275 Use the name specified by *<tagfile>* for the tag file (default is "``tags``", 276 or "``TAGS``" when running in etags mode). If *<tagfile>* is specified as '``-``', 277 then the tags are written to standard output instead. 278 279 @CTAGS_NAME_EXECUTABLE@ 280 will stubbornly refuse to take orders if tagfile exists and 281 its first line contains something other than a valid tags line. This 282 will save your neck if you mistakenly type "``@CTAGS_NAME_EXECUTABLE@ -f 283 *.c``", which would otherwise overwrite your first C file with the tags 284 generated by the rest! It will also refuse to accept a multi-character 285 file name which begins with a '``-``' (dash) character, since this most 286 likely means that you left out the tag file name and this option tried to 287 grab the next option as the file name. If you really want to name your 288 output tag file ``-ugly``, specify it as "``-f ./-ugly``". 289 290 This option must 291 appear before the first file name. If this option is specified more 292 than once, only the last will apply. 293 294``-o <tagfile>`` 295 Equivalent to "``-f tagfile``". 296 297.. _option_output_format: 298 299Output Format Options 300~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 301``--format=(1|2)`` 302 Change the format of the output tag file. Currently the only valid 303 values for level are 1 or 2. Level 1 specifies the original tag file 304 format and level 2 specifies a new extended format containing extension 305 fields (but in a manner which retains backward-compatibility with 306 original ``vi(1)`` implementations). The default level is 2. 307 [Ignored in etags mode] 308 309``--output-format=(u-ctags|e-ctags|etags|xref|json)`` 310 Specify the output format. The default is ``u-ctags``. 311 See tags(5) for ``u-ctags`` and ``e-ctags``. 312 See ``-e`` for ``etags``, and ``-x`` for ``xref``. 313 ``json`` format is available only if 314 the ctags executable is built with ``libjansson``. 315 See ctags-client-tools(7) for more about ``json`` format. 316 317``-e`` 318 Same as ``--output-format=etags``. 319 Enable etags mode, which will create a tag file for use with the Emacs 320 editor. Alternatively, if @CTAGS_NAME_EXECUTABLE@ is invoked by a 321 name containing the string "@ETAGS_NAME_EXECUTABLE@" (either by renaming, 322 or creating a link to, the executable), etags mode will be enabled. 323 324``-x`` 325 Same as ``--output-format=xref``. 326 Print a tabular, human-readable cross reference (xref) file to standard 327 output instead of generating a tag file. The information contained in 328 the output includes: the tag name; the kind of tag; the line number, 329 file name, and source line (with extra white space condensed) of the 330 file which defines the tag. No tag file is written and all options 331 affecting tag file output will be ignored. 332 333 Example applications for this 334 feature are generating a listing of all functions located in a source 335 file (e.g. "``@CTAGS_NAME_EXECUTABLE@ -x --kinds-c=f file``"), or generating 336 a list of all externally visible global variables located in a source 337 file (e.g. "``@CTAGS_NAME_EXECUTABLE@ -x --kinds-c=v --extras=-F file``"). 338 339``--sort=(yes|no|foldcase)`` 340 Indicates whether the tag file should be sorted on the tag name 341 (default is ``yes``). Note that the original ``vi(1)`` required sorted tags. 342 The ``foldcase`` value specifies case insensitive (or case-folded) sorting. 343 Fast binary searches of tag files sorted with case-folding will require 344 special support from tools using tag files, such as that found in the 345 @CTAGS_NAME_EXECUTABLE@ readtags library, or Vim version 6.2 or higher 346 (using "``set ignorecase``"). 347 [Ignored in etags mode] 348 349``-u`` 350 Equivalent to ``--sort=no`` (i.e. "unsorted"). 351 352``--etags-include=<file>`` 353 Include a reference to *<file>* in the tag file. This option may be specified 354 as many times as desired. This supports Emacs' capability to use a 355 tag file which *includes* other tag files. [Available only in etags mode] 356 357``--input-encoding=<encoding>`` 358 Specifies the *<encoding>* of the input files. 359 If this option is specified, Universal Ctags converts the input from this 360 encoding to the encoding specified by ``--output-encoding=encoding``. 361 362``--input-encoding-<LANG>=<encoding>`` 363 Specifies a specific input *<encoding>* for *<LANG>*. It overrides the global 364 default value given with ``--input-encoding``. 365 366``--output-encoding=<encoding>`` 367 Specifies the *<encoding>* of the tags file. 368 Universal Ctags converts the encoding of input files from the encoding 369 specified by ``--input-encoding=<encoding>`` to this encoding. 370 371 In addition *<encoding>* is specified at the top the tags file as the 372 value for the ``TAG_FILE_ENCODING`` pseudo-tag. The default value of 373 *<encoding>* is ``UTF-8``. 374 375.. _option_lang_mapping: 376 377Language Selection and Mapping Options 378~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 379``--language-force=(<language>|auto)`` 380 By default, @CTAGS_NAME_EXECUTABLE@ automatically selects the language 381 of a source file, ignoring those files whose language cannot be 382 determined (see "`Determining file language`_"). This option forces the specified 383 *language* (case-insensitive; either built-in or user-defined) to be used 384 for every supplied file instead of automatically selecting the language 385 based upon its extension. 386 387 In addition, the special value ``auto`` indicates 388 that the language should be automatically selected (which effectively 389 disables this option). 390 391``--languages=[+|-](<list>|all)`` 392 Specifies the languages for which tag generation is enabled, with *<list>* 393 containing a comma-separated list of language names (case-insensitive; 394 either built-in or user-defined). 395 396 If the first language of *<list>* is not 397 preceded by either a '``+``' or '``-``', the current list (the current settings 398 of enabled/disabled languages managed in @CTAGS_NAME_EXECUTABLE@ internally) 399 will be cleared before adding or removing the languages in *<list>*. Until a '``-``' is 400 encountered, each language in the *<list>* will be added to the current list. 401 402 As either the '``+``' or '``-``' is encountered in the *<list>*, the languages 403 following it are added or removed from the current list, respectively. 404 Thus, it becomes simple to replace the current list with a new one, or 405 to add or remove languages from the current list. 406 407 The actual list of 408 files for which tags will be generated depends upon the language 409 extension mapping in effect (see the ``--langmap`` option). Note that the most of 410 languages, including user-defined languages, are enabled unless explicitly 411 disabled using this option. Language names included in list may be any 412 built-in language or one previously defined with ``--langdef``. 413 414 The default 415 is ``all``, which is also accepted as a valid argument. See the 416 ``--list-languages`` option for a list of the all (built-in and user-defined) 417 language names. 418 419 Note ``--languages=`` option works cumulative way; the option can be 420 specified with different arguments multiple times in a command line. 421 422``--alias-<LANG>=[+|-](<pattern>|default)`` 423 Adds ('``+``') or removes ('``-``') an alias *<pattern>* to a language specified 424 with *<LANG>*. @CTAGS_NAME_EXECUTABLE@ refers to the alias pattern in 425 "`Determining file language`_" stage. 426 427 The parameter *<pattern>* is not a list. Use this option multiple 428 times in a command line to add or remove multiple alias 429 patterns. 430 431 To restore the default language aliases, specify ``default``. 432 433 Using ``all`` for *<LANG>* has meaning in following two cases: 434 435 ``--alias-all=`` 436 This clears aliases setting of all languages. 437 438 ``--alias-all=default`` 439 This restores the default languages aliases for all languages. 440 441``--guess-language-eagerly`` 442 Looks into the file contents for heuristically guessing the proper language parser. 443 See "`Determining file language`_". 444 445``-G`` 446 Equivalent to ``--guess-language-eagerly``. 447 448``--langmap=<map>[,<map>[...]]`` 449 Controls how file names are mapped to languages (see the ``--list-maps`` 450 option). Each comma-separated *<map>* consists of the language name (either 451 a built-in or user-defined language), a colon, and a list of *file 452 extensions* and/or *file name patterns*. A file extension is specified by 453 preceding the extension with a period (e.g. ``.c``). A file name pattern 454 is specified by enclosing the pattern in parentheses (e.g. 455 ``([Mm]akefile)``). 456 457 If appropriate support is available from the runtime 458 library of your C compiler, then the file name pattern may contain the usual 459 shell wildcards common on Unix (be sure to quote the option parameter to 460 protect the wildcards from being expanded by the shell before being 461 passed to @CTAGS_NAME_EXECUTABLE@). You can determine if shell wildcards 462 are available on your platform by examining the output of the 463 ``--list-features`` option, which will include ``wildcards`` in the compiled 464 feature list; otherwise, the file name patterns are matched against 465 file names using a simple textual comparison. 466 467 When mapping a file extension with ``--langmap`` option, 468 it will first be unmapped from any other languages. (``--map-<LANG>`` 469 option provides more fine-grained control.) 470 471 If the first character in a *<map>* is a plus sign ('``+``'), then the extensions and 472 file name patterns in that map will be appended to the current map 473 for that language; otherwise, the map will replace the current map. 474 For example, to specify that only files with extensions of ``.c`` and ``.x`` are 475 to be treated as C language files, use ``--langmap=c:.c.x``; to also add 476 files with extensions of ``.j`` as Java language files, specify 477 ``--langmap=c:.c.x,java:+.j``. To map makefiles (e.g. files named either 478 ``Makefile``, ``makefile``, or having the extension ``.mak``) to a language 479 called ``make``, specify ``--langmap=make:([Mm]akefile).mak``. To map files 480 having no extension, specify a period not followed by a non-period 481 character (e.g. '``.``', ``..x``, ``.x.``). 482 483 To clear the mapping for a 484 particular language (thus inhibiting automatic generation of tags for 485 that language), specify an empty extension list (e.g. ``--langmap=fortran:``). 486 To restore the default language mappings for a particular language, 487 supply the keyword ``default`` for the mapping. To specify restore the 488 default language mappings for all languages, specify ``--langmap=default``. 489 490 Note that file name patterns are tested before file extensions when inferring 491 the language of a file. This order of Universal Ctags is different from 492 Exuberant Ctags. See ctags-incompatibilities(7) for the background of 493 this incompatible change. 494 495``--map-<LANG>=[+|-]<extension>|<pattern>`` 496 This option provides the way to control mapping(s) of file names to 497 languages in a more fine-grained way than ``--langmap`` option. 498 499 In @CTAGS_NAME_EXECUTABLE@, more than one language can map to a 500 file name *<pattern>* or file *<extension>* (*N:1 map*). Alternatively, 501 ``--langmap`` option handle only *1:1 map*, only one language 502 mapping to one file name *<pattern>* or file *<extension>*. A typical N:1 503 map is seen in C++ and ObjectiveC language; both languages have 504 a map to ``.h`` as a file extension. 505 506 A file extension is specified by preceding the extension with a period (e.g. ``.c``). 507 A file name pattern is specified by enclosing the pattern in parentheses (e.g. 508 ``([Mm]akefile)``). A prefixed plus ('``+``') sign is for adding, and 509 minus ('``-``') is for removing. No prefix means replacing the map of *<LANG>*. 510 511 Unlike ``--langmap``, *<extension>* (or *<pattern>*) is not a list. 512 ``--map-<LANG>`` takes one extension (or pattern). However, 513 the option can be specified with different arguments multiple times 514 in a command line. 515 516.. _option_tags_file_contents: 517 518Tags File Contents Options 519~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 520See "`TAG ENTRIES`_" about fields, kinds, roles, and extras. 521 522``--excmd=(number|pattern|mix|combine)`` 523 Determines the type of ``EX`` command used to locate tags in the source 524 file. [Ignored in etags mode] 525 526 The valid values for type (either the entire word or the first letter 527 is accepted) are: 528 529 ``number`` 530 Use only line numbers in the tag file for locating tags. This has 531 four advantages: 532 533 1. Significantly reduces the size of the resulting tag file. 534 2. Eliminates failures to find tags because the line defining the 535 tag has changed, causing the pattern match to fail (note that 536 some editors, such as ``vim``, are able to recover in many such 537 instances). 538 3. Eliminates finding identical matching, but incorrect, source 539 lines (see "`BUGS`_"). 540 4. Retains separate entries in the tag file for lines which are 541 identical in content. In pattern mode, duplicate entries are 542 dropped because the search patterns they generate are identical, 543 making the duplicate entries useless. 544 545 However, this option has one significant drawback: changes to the 546 source files can cause the line numbers recorded in the tag file 547 to no longer correspond to the lines in the source file, causing 548 jumps to some tags to miss the target definition by one or more 549 lines. Basically, this option is best used when the source code 550 to which it is applied is not subject to change. Selecting this 551 option type causes the following options to be ignored: ``-B``, ``-F``. 552 553 ``number`` type is ignored in Xref and JSON output formats. Use 554 ``--_xformat="...%n"`` for Xref output format, or ``--fields=+n-P`` for 555 JSON output format. 556 557 .. NOTE: #2792 558 559 ``pattern`` 560 Use only search patterns for all tags, rather than the line numbers 561 usually used for macro definitions. This has the advantage of 562 not referencing obsolete line numbers when lines have been added or 563 removed since the tag file was generated. 564 565 ``mixed`` 566 In this mode, patterns are generally used with a few exceptions. 567 For C, line numbers are used for macro definition tags. For Fortran, line numbers 568 are used for common blocks because their corresponding source lines 569 are generally identical, making pattern searches useless 570 for finding all matches. 571 572 This was the default format generated by the original ctags and is, 573 therefore, retained as the default for this option. 574 575 ``combine`` 576 Concatenate the line number and pattern with a semicolon in between. 577 578``-n`` 579 Equivalent to ``--excmd=number``. 580 581``-N`` 582 Equivalent to ``--excmd=pattern``. 583 584``--extras=[+|-][<flags>|*]`` 585 Specifies whether to include extra tag entries for certain kinds of 586 information. See also "`Extras`_" subsection to know what are extras. 587 588 The parameter *<flags>* is a set of one-letter flags (and/or long-name flags), each 589 representing one kind of extra tag entry to include in the tag file. 590 If flags is preceded by either the '``+``' or '``-``' character, the effect of 591 each flag is added to, or removed from, those currently enabled; 592 otherwise the flags replace any current settings. All entries are 593 included if '``*``' is given. 594 595 This ``--extras=`` option is for controlling extras common in all 596 languages (or language-independent extras). Universal Ctags also 597 supports language-specific extras. (See "`Language-specific fields and 598 extras`_" about the concept). Use ``--extras-<LANG>=`` option for 599 controlling them. 600 601``--extras-(<LANG>|all)=[+|-][<flags>|*]`` 602 Specifies whether to include extra tag entries for certain kinds of 603 information for language *<LANG>*. Universal Ctags 604 introduces language-specific extras. See "`Language-specific fields and 605 extras`_" about the concept. This option is for controlling them. 606 607 Specifies ``all`` as *<LANG>* to apply the parameter *<flags>* to all 608 languages; all extras are enabled with specifying '``*``' as the 609 parameter flags. If specifying nothing as the parameter flags 610 (``--extras-all=``), all extras are disabled. These two combinations 611 are useful for testing. 612 613 Check the output of the ``--list-extras=<LANG>`` option for the 614 extras of specific language *<LANG>*. 615 616``--fields=[+|-][<flags>|*]`` 617 Specifies which language-independent fields are to be included in the tag 618 entries. Language-independent fields are extension fields which are common 619 in all languages. See "`TAG FILE FORMAT`_" section, and "`Extension fields`_" 620 subsection, for details of extension fields. 621 622 The parameter *<flags>* is a set of one-letter or long-name flags, 623 each representing one type of extension field to include. 624 Each flag or group of flags may be preceded by either '``+``' to add it 625 to the default set, or '``-``' to exclude it. In the absence of any 626 preceding '``+``' or '``-``' sign, only those fields explicitly listed in flags 627 will be included in the output (i.e. overriding the default set). All 628 fields are included if '``*``' is given. 629 630 This option is ignored if the 631 option ``--format=1`` (legacy tag file format) has been specified. 632 633 Use ``--fields-<LANG>=`` option for controlling language-specific fields. 634 635``--fields-(<LANG>|all)=[+|-][<flags>|*]`` 636 Specifies which language-specific fields are to be included in 637 the tag entries. Universal Ctags 638 supports language-specific fields. (See "`Language-specific fields and 639 extras`_" about the concept). 640 641 Specify ``all`` as *<LANG>* to apply the parameter *<flags>* to all 642 languages; all fields are enabled with specifying '``*``' as the 643 parameter flags. If specifying nothing as the parameter *<flags>* 644 (i.e. ``--fields-all=``), all fields are disabled. These two combinations 645 are useful for testing. 646 647 See the description of ``--fields=[+|-][<flags>|*]`` about *<flags>*. 648 649 Use ``--fields=`` option for controlling language-independent fields. 650 651 652``--kinds-(<LANG>|all)=[+|-](<kinds>|*)`` 653 Specifies a list of language-specific *<kinds>* of tags (or kinds) to 654 include in the output file for a particular language, where *<LANG>* is 655 case-insensitive and is one of the built-in language names (see the 656 ``--list-languages`` option for a complete list). 657 658 The parameter *<kinds>* is a group 659 of one-letter or long-name flags designating kinds of tags (particular to the language) 660 to either include or exclude from the output. The specific sets of 661 flags recognized for each language, their meanings and defaults may be 662 list using the ``--list-kinds-full`` option. 663 664 Each letter or group of letters 665 may be preceded by either '``+``' to add it to, or '``-``' to remove it from, 666 the default set. In the absence of any preceding '``+``' or '``-``' sign, only 667 those kinds explicitly listed in kinds will be included in the output 668 (i.e. overriding the default for the specified language). 669 670 Specify '``*``' as the parameter to include all kinds implemented 671 in *<LANG>* in the output. Furthermore if ``all`` is given as *<LANG>*, 672 specification of the parameter ``kinds`` affects all languages defined 673 in @CTAGS_NAME_EXECUTABLE@. Giving ``all`` makes sense only when '``*``' or 674 '``F``' is given as the parameter ``kinds``. 675 676 As an example for the C language, in order to add prototypes and 677 external variable declarations to the default set of tag kinds, 678 but exclude macros, use ``--kinds-c=+px-d``; to include only tags for 679 functions, use ``--kinds-c=f``. 680 681 Some kinds of C and C++ languages are synchronized; enabling 682 (or disabling) a kind in one language enables the kind having 683 the same one-letter and long-name in the other language. See also the 684 description of ``MASTER`` column of ``--list-kinds-full``. 685 686.. COMMENT: 687 ``--param-<LANG>.name=argument`` is moved to "Language Specific Options" 688 689``--pattern-length-limit=<N>`` 690 Truncate patterns of tag entries after *<N>* characters. Disable by setting to 0 691 (default is 96). 692 693 An input source file with long lines and multiple tag matches per 694 line can generate an excessively large tags file with an 695 unconstrained pattern length. For example, running ctags on a 696 minified JavaScript source file often exhibits this behavior. 697 698 The truncation avoids cutting in the middle of a UTF-8 code point 699 spanning multiple bytes to prevent writing invalid byte sequences from 700 valid input files. This handling allows for an extra 3 bytes above the 701 configured limit in the worse case of a 4 byte code point starting 702 right before the limit. Please also note that this handling is fairly 703 naive and fast, and although it is resistant against any input, it 704 requires a valid input to work properly; it is not guaranteed to work 705 as the user expects when dealing with partially invalid UTF-8 input. 706 This also partially affect non-UTF-8 input, if the byte sequence at 707 the truncation length looks like a multibyte UTF-8 sequence. This 708 should however be rare, and in the worse case will lead to including 709 up to an extra 3 bytes above the limit. 710 711``--pseudo-tags=[+|-](<pseudo-tag>|*)`` 712 Enable/disable emitting pseudo-tag named *<pseudo-tag>*. 713 If '``*``' is given, enable/disable emitting all pseudo-tags. 714 715``--put-field-prefix`` 716 Put ``UCTAGS`` as prefix for the name of fields newly introduced in 717 Universal Ctags. 718 719 Some fields are newly introduced in Universal Ctags and more will 720 be introduced in the future. Other tags generators may also 721 introduce their specific fields. 722 723 In such a situation, there is a concern about conflicting field 724 names; mixing tags files generated by multiple tags generators 725 including Universal Ctags is difficult. This option provides a 726 workaround for such station. 727 728 .. code-block:: console 729 730 $ @CTAGS_NAME_EXECUTABLE@ --fields='{line}{end}' -o - hello.c 731 main hello.c /^main(int argc, char **argv)$/;" f line:3 end:6 732 $ @CTAGS_NAME_EXECUTABLE@ --put-field-prefix --fields='{line}{end}' -o - hello.c 733 main hello.c /^main(int argc, char **argv)$/;" f line:3 UCTAGSend:6 734 735 In the above example, the prefix is put to ``end`` field which is 736 newly introduced in Universal Ctags. 737 738``--roles-(<LANG>|all).(<kind>|*)=[+|-][<roles>|*]`` 739 Specifies a list of kind-specific roles of tags to include in the 740 output file for a particular language. 741 *<kind>* specifies the kind where the *<roles>* are defined. 742 *<LANG>* specifies the language where the kind is defined. 743 Each role in *<roles>* must be surrounded by braces (e.g. ``{system}`` 744 for a role named "system"). 745 746 Like ``--kinds-<LANG>`` option, '``+``' is for adding the role to the 747 list, and '``-``' is for removing from the list. '``*``' is for including 748 all roles of the kind to the list. The option with no argument 749 makes the list empty. 750 751 Both a one-letter flag or a long name flag surrounded by braces are 752 acceptable for specifying a kind (e.g. ``--roles-C.h=+{system}{local}`` 753 or ``--roles-C.{header}=+{system}{local}``). '``*``' can be used for *<KIND>* 754 only for adding/removing all roles of all kinds in a language to/from 755 the list (e.g. ``--roles-C.*=*`` or ``--roles-C.*=``). 756 757 ``all`` can be used for *<LANG>* only for adding/removing all roles of 758 all kinds in all languages to/from the list 759 (e.g. ``--roles-all.*=*`` or ``--roles-all.*=``). 760 761``--tag-relative=(yes|no|always|never)`` 762 Specifies how the file paths recorded in the tag file. 763 The default is ``yes`` when running in etags mode (see 764 the ``-e`` option), ``no`` otherwise. 765 766 ``yes`` 767 indicates that the file paths recorded in the tag file should be 768 *relative to the directory containing the tag file* 769 unless the files supplied on the command line 770 are specified with absolute paths. 771 772 ``no`` 773 indicates that the file paths recorded in the tag file should be 774 *relative to the current directory* 775 unless the files supplied on the command line 776 are specified with absolute paths. 777 778 ``always`` 779 indicates the recorded file paths should be relative 780 even if source file names are passed in with absolute paths. 781 782 ``never`` 783 indicates the recorded file paths should be absolute 784 even if source file names are passed in with relative paths. 785 786``--use-slash-as-filename-separator[=(yes|no)]`` 787 Uses slash ('``/``') character as filename separators instead of backslash 788 ('``\``') character when printing ``input:`` field. 789 The default is ``yes`` for the default "u-ctags" output format, and 790 ``no`` for the other formats. 791 792 This option is available on MS Windows only. 793 794``-B`` 795 Use backward searching patterns (e.g. ``?pattern?``). [Ignored in etags mode] 796 797``-F`` 798 Use forward searching patterns (e.g. ``/pattern/``) (default). [Ignored 799 in etags mode] 800 801Option File Options 802~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 803.. TODO: merge some of description in option-file.rst into FILE or a dedicated 804 section 805 806``--options=<pathname>`` 807 Read additional options from file or directory. 808 809 @CTAGS_NAME_EXECUTABLE@ searches *<pathname>* in the optlib path list 810 first. If @CTAGS_NAME_EXECUTABLE@ cannot find a file or directory 811 in the list, @CTAGS_NAME_EXECUTABLE@ reads a file or directory 812 at the specified *<pathname>*. 813 814 If a file is specified, it should contain one option per line. If 815 a directory is specified, files suffixed with ``.ctags`` under it 816 are read in alphabetical order. 817 818 As a special case, if ``--options=NONE`` is specified as the first 819 option on the command line, preloading is disabled; the option 820 will disable the automatic reading of any configuration options 821 from a file (see "`FILES`_"). 822 823``--options-maybe=<pathname>`` 824 Same as ``--options`` but doesn't cause an error if file 825 (or directory) specified with *<pathname>* doesn't exist. 826 827``--optlib-dir=[+]<directory>`` 828 Add an optlib *<directory>* to or reset the optlib path list. 829 By default, the optlib path list is empty. 830 831optlib Options 832~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 833See ctags-optlib(7) for details of each option. 834 835``--kinddef-<LANG>=<letter>,<name>,<description>`` 836 Define a kind for *<LANG>*. 837 Don't be confused this with ``--kinds-<LANG>``. 838 839``--langdef=<name>`` 840 Defines a new user-defined language, *<name>*, to be parsed with regular 841 expressions. 842 843``--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]`` 844 Define multi-line regular expression for locating tags in specific language. 845 846``--regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]`` 847 Define single-line regular expression for locating tags in specific language. 848 849.. _option_lang_specific: 850 851Language Specific Options 852~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 853``--if0[=(yes|no)]`` 854 Indicates a preference as to whether code within an "``#if 0``" branch of a 855 preprocessor conditional should be examined for non-macro tags (macro 856 tags are always included). Because the intent of this construct is to 857 disable code, the default value of this option is ``no`` (disabled). 858 859 Note that this 860 indicates a preference only and does not guarantee skipping code within 861 an "``#if 0``" branch, since the fall-back algorithm used to generate 862 tags when preprocessor conditionals are too complex follows all branches 863 of a conditional. 864 865``--line-directives[=(yes|no)]`` 866 Specifies whether ``#line`` directives should be recognized. These are 867 present in the output of a preprocessor and contain the line number, and 868 possibly the file name, of the original source file(s) from which the 869 preprocessor output file was generated. This option is off by default. 870 871 When enabled, this option will 872 cause @CTAGS_NAME_EXECUTABLE@ to generate tag entries marked with the 873 file names and line numbers of their locations original source file(s), 874 instead of their actual locations in the preprocessor output. The actual 875 file names placed into the tag file will have the same leading path 876 components as the preprocessor output file, since it is assumed that 877 the original source files are located relative to the preprocessor 878 output file (unless, of course, the ``#line`` directive specifies an 879 absolute path). 880 881 Note: This option is generally 882 only useful when used together with the ``--excmd=number`` (``-n``) option. 883 Also, you may have to use either the ``--langmap`` or ``--language-force`` option 884 if the extension of the preprocessor output file is not known to 885 @CTAGS_NAME_EXECUTABLE@. 886 887``-D <macro>=<definition>`` 888 Defines a C preprocessor *<macro>*. This emulates the behavior of the 889 corresponding gcc option. All types of macros are supported, 890 including the ones with parameters and variable arguments. 891 Stringification, token pasting and recursive macro expansion are also 892 supported. 893 This extends the function provided by ``-I`` option. 894 895``-h (<list>|default)`` 896 Specifies a *<list>* of file extensions, separated by periods, which are 897 to be interpreted as include (or header) files. To indicate files having 898 no extension, use a period not followed by a non-period character 899 (e.g. '``.``', ``..x``, ``.x.``). 900 901 This option only affects how the scoping of 902 particular kinds of tags are interpreted (i.e. whether or not they are 903 considered as globally visible or visible only within the file in which 904 they are defined); it does not map the extension to any particular 905 language. Any tag which is located in a non-include file and cannot be 906 seen (e.g. linked to) from another file is considered to have file-limited 907 (e.g. static) scope. No kind of tag appearing in an include file 908 will be considered to have file-limited scope. 909 910 If the first character in the list is '``+``', then the extensions in the list will be 911 appended to the current list; otherwise, the list will replace the 912 current list. See, also, the ``fileScope``/``F`` flag of ``--extras`` option. 913 914 The default list is 915 ``.h.H.hh.hpp.hxx.h++.inc.def``. To restore the default list, specify "``-h 916 default``". 917 918 Note that if an extension supplied to this option is not 919 already mapped to a particular language (see "`Determining file language`_", above), 920 you will also need to use either the ``--map-<LANG>``, ``--langmap`` or 921 ``--language-force`` option. 922 923``-I <identifier-list>`` 924 Specifies a *<identifier-list>* of identifiers which are to be specially handled while 925 parsing C and C++ source files. This option is specifically provided 926 to handle special cases arising through the use of preprocessor macros. 927 When the identifiers listed are simple identifiers, these identifiers 928 will be ignored during parsing of the source files. 929 930 If an identifier is 931 suffixed with a '``+``' character (i.e. "``-I FOO+``"), @CTAGS_NAME_EXECUTABLE@ will also 932 ignore any parenthesis-enclosed argument list which may immediately 933 follow the identifier in the source files. See the example of "``-I 934 MODULE_VERSION+``" below. 935 936 If two identifiers are 937 separated with the '``=``' character (i.e. ``-I FOO=BAR``), the first identifiers is replaced by 938 the second identifiers for parsing purposes. The list of identifiers may 939 be supplied directly on the command line or read in from a separate file. 940 See the example of "``-I CLASS=class``" below. 941 942 If the first character of *<identifier-list>* is '``@``', '``.``' or a pathname 943 separator ('``/``' or '``\``'), or the first two characters specify a drive 944 letter (e.g. ``C:``), the parameter *<identifier-list>* will be interpreted as 945 a filename from which to read a list of identifiers, one per input line. 946 947 Otherwise, *<identifier-list>* is a list of identifiers (or identifier 948 pairs) to be specially handled, each delimited by either a comma or 949 by white space (in which case the list should be quoted to keep the 950 entire list as one command line argument). 951 952 Multiple ``-I`` options may be 953 supplied. To clear the list of ignore identifiers, supply a single 954 dash ('``-``') for *<identifier-list>*. 955 956 This feature is useful when preprocessor macros are used in such a way 957 that they cause syntactic confusion due to their presence. Indeed, 958 this is the best way of working around a number of problems caused by 959 the presence of syntax-busting macros in source files (see "`CAVEATS`_"). 960 Some examples will illustrate this point. 961 962 .. code-block:: C 963 964 int foo ARGDECL4(void *, ptr, long int, nbytes) 965 966 In the above example, the macro ``ARGDECL4`` would be mistakenly 967 interpreted to be the name of the function instead of the correct name 968 of ``foo``. Specifying "``-I ARGDECL4``" results in the correct behavior. 969 970 .. code-block:: C 971 972 /* creates an RCS version string in module */ 973 MODULE_VERSION("$Revision$") 974 975 In the above example the macro invocation looks too much like a function 976 definition because it is not followed by a semicolon (indeed, it 977 could even be followed by a global variable definition that would look 978 much like a K&R style function parameter declaration). In fact, this 979 seeming function definition could possibly even cause the rest of the 980 file to be skipped over while trying to complete the definition. 981 Specifying "``-I MODULE_VERSION+``" would avoid such a problem. 982 983 .. code-block:: C 984 985 CLASS Example { 986 // your content here 987 }; 988 989 The example above uses ``CLASS`` as a preprocessor macro which expands to 990 something different for each platform. For instance ``CLASS`` may be 991 defined as ``class __declspec(dllexport)`` on Win32 platforms and simply 992 ``class`` on UNIX. Normally, the absence of the C++ keyword ``class`` 993 would cause the source file to be incorrectly parsed. Correct behavior 994 can be restored by specifying "``-I CLASS=class``". 995 996``--param-<LANG>.<name>=<argument>`` 997 Set a *<LANG>* specific parameter, a parameter specific to the *<LANG>*. 998 999 Available parameters can be listed with ``--list-params``. 1000 1001.. _option_listing: 1002 1003Listing Options 1004~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1005``--list-aliases[=(<language>|all)]`` 1006 Lists the aliases for either the specified *<language>* or ``all`` 1007 languages, and then exits. 1008 ``all`` is used as default value if the option argument is omitted. 1009 The aliases are used when heuristically testing a language parser for a 1010 source file. 1011 1012``--list-excludes`` 1013 Lists the current exclusion patterns used to exclude files. 1014 1015``--list-extras[=(<language>|all)]`` 1016 Lists the extras recognized for either the specified *<language>* or 1017 ``all`` languages. See "`Extras`_" subsection to know what are extras. 1018 ``all`` is used as default value if the option argument is omitted. 1019 1020 An extra can be enabled or disabled with ``--extras=`` for common 1021 extras in all languages, or ``--extras-<LANG>=`` for the specified 1022 language. These option takes one-letter flag or long-name flag as a parameter 1023 for specifying an extra. 1024 1025 The meaning of columns in output are as follows: 1026 1027 LETTER 1028 One-letter flag. '``-``' means the extra does not have one-letter flag. 1029 1030 NAME 1031 Long-name flag. The long-name is used in ``extras`` field. 1032 1033 ENABLED 1034 Whether the extra is enabled or not. It takes ``yes`` or ``no``. 1035 1036 LANGUAGE 1037 The name of language if the extra is owned by a parser. 1038 ``NONE`` means the extra is common in parsers. 1039 1040 DESCRIPTION 1041 Human readable description for the extra. 1042 1043``--list-features`` 1044 Lists the compiled features. 1045 1046``--list-fields[=(<language>|all)]`` 1047 Lists the fields recognized for either the specified *<language>* or 1048 ``all`` languages. See "`Extension fields`_" subsection to know what are fields. 1049 ``all`` is used as default value if the option argument is omitted. 1050 1051 The meaning of columns are as follows: 1052 1053 LETTER 1054 One-letter flag. '``-``' means the field does not have one-letter flag. 1055 1056 NAME 1057 Long-name of field. 1058 1059 ENABLED 1060 Whether the field is enabled or not. It takes ``yes`` or ``no``. 1061 1062 LANGUAGE 1063 The name of language if the field is owned by a parser. 1064 ``NONE`` means that the field is a language-independent field which is 1065 common in all languages. 1066 1067 JSTYPE 1068 JSON type used in printing the value of field when ``--output-format=json`` 1069 is specified. See ctags-client-tools(7). 1070 1071 FIXED 1072 Whether this field can be disabled or not in tags output. 1073 1074 Some fields are printed always in tags output. 1075 They have ``yes`` as the value for this column. 1076 1077 Unlike the tag output mode, JSON output mode allows disabling 1078 any fields. 1079 1080 OP 1081 How this field can be accessed from optscript code. 1082 This field is for Universal Ctags developers. 1083 1084 1085 DESCRIPTION 1086 Human readable description for the field. 1087 1088``--list-kinds[=(<language>|all)]`` 1089 Subset of ``--list-kinds-full``. This option is kept for 1090 backward-compatibility with Exuberant Ctags. 1091 1092 This option prints only LETTER, DESCRIPTION, and ENABLED fields 1093 of ``--list-kinds-full`` output. However, the presentation of 1094 ENABLED column is different from that of ``--list-kinds-full`` 1095 option; ``[off]`` follows after description if the kind is disabled, 1096 and nothing follows if enabled. The most of all kinds are enabled 1097 by default. 1098 1099 The critical weakness of this option is that this option does not 1100 print the name of kind. Universal Ctags introduces 1101 ``--list-kinds-full`` because it considers that names are 1102 important. 1103 1104 This option does not work with ``--machinable`` nor 1105 ``--with-list-header``. 1106 1107``--list-kinds-full[=(<language>|all)]`` 1108 Lists the tag kinds recognized for either the specified *<language>* 1109 or ``all`` languages, and then exits. See "`Kinds`_" subsection to 1110 learn what kinds are. 1111 ``all`` is used as default value if the option argument is omitted. 1112 1113 Each kind of tag recorded in the tag file is represented by a 1114 one-letter flag, or a long-name flag. They are also used to filter the tags 1115 placed into the output through use of the ``--kinds-<LANG>`` 1116 option. 1117 1118 The meaning of columns are as follows: 1119 1120 LANGUAGE 1121 The name of language having the kind. 1122 1123 LETTER 1124 One-letter flag. This must be unique in a language. 1125 1126 NAME 1127 The long-name flag of the kind. This can be used as the alternative 1128 to the one-letter flag described above. If enabling ``K`` field with 1129 ``--fields=+K``, @CTAGS_NAME_EXECUTABLE@ uses long-names instead of 1130 one-letters in tags output. To enable/disable a kind with 1131 ``--kinds-<LANG>`` option, long-name surrounded by braces instead 1132 of one-letter. See "`Letters and names`_" for details. This must be 1133 unique in a language. 1134 1135 ENABLED 1136 Whether the kind is enabled or not. It takes ``yes`` or ``no``. 1137 1138 REFONLY 1139 Whether the kind is specialized for reference tagging or not. 1140 If the column is ``yes``, the kind is for reference tagging, and 1141 it is never used for definition tagging. See also "`TAG ENTRIES`_". 1142 1143 NROLES 1144 The number of roles this kind has. See also "`Roles`_". 1145 1146 MASTER 1147 The master parser controlling enablement of the kind. 1148 A kind belongs to a language (owner) in Universal Ctags; 1149 enabling and disabling a kind in a language has no effect on 1150 a kind in another language even if both kinds has the 1151 same one-letter flag and/or the same long-name flag. In other words, 1152 the namespace of kinds are separated by language. 1153 1154 However, Exuberant Ctags does not separate the kinds of C and 1155 C++. Enabling/disabling kindX in C language enables/disables a 1156 kind in C++ language having the same long-name flag with kindX. To 1157 emulate this behavior in Universal Ctags, a concept named 1158 *master parser* is introduced. Enabling/disabling some kinds 1159 are synchronized under the control of a master language. 1160 1161 .. code-block:: console 1162 1163 $ ctags --kinds-C=+'{local}' --list-kinds-full \ 1164 | grep -E '^(#|C\+\+ .* local)' 1165 #LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION 1166 C++ l local yes no 0 C local variables 1167 $ ctags --kinds-C=-'{local}' --list-kinds-full \ 1168 | grep -E '^(#|C\+\+ .* local)' 1169 #LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION 1170 C++ l local no no 0 C local variables 1171 1172 You see ``ENABLED`` field of ``local`` kind of C++ language is changed 1173 Though ``local`` kind of C language is enabled/disabled. If you swap the languages, you 1174 see the same result. 1175 1176 .. TODO: need a reference to "master parser" 1177 1178 DESCRIPTION 1179 Human readable description for the kind. 1180 1181``--list-languages`` 1182 Lists the names of the languages understood by @CTAGS_NAME_EXECUTABLE@, 1183 and then exits. These language names are case insensitive and may be 1184 used in many other options like ``--language-force``, 1185 ``--languages``, ``--kinds-<LANG>``, ``--regex-<LANG>``, and so on. 1186 1187 Each language listed is disabled if followed by ``[disabled]``. 1188 To use the parser for such a language, specify the language as an 1189 argument of ``--languages=+`` option. 1190 1191 ``--machinable`` and ``--with-list-header`` options are ignored if they are 1192 specified with this option. 1193 1194``--list-map-extensions[=(<language>|all)]`` 1195 Lists the file extensions which associate a file 1196 name with a language for either the specified *<language>* or ``all`` 1197 languages, and then exits. 1198 ``all`` is used as default value if the option argument is omitted. 1199 1200``--list-map-patterns[=(<language>|all)]`` 1201 Lists the file name patterns which associate a file 1202 name with a language for either the specified *<language>* or ``all`` 1203 languages, and then exits. 1204 ``all`` is used as default value if the option argument is omitted. 1205 1206``--list-maps[=(<language>|all)]`` 1207 Lists file name patterns and the file extensions which associate a file 1208 name with a language for either the specified *<language>* or ``all`` 1209 languages, and then exits. 1210 ``all`` is used as default value if the option argument is omitted. 1211 1212 To list the file extensions or file name patterns individually, use 1213 ``--list-map-extensions`` or ``--list-map-patterns`` option. 1214 See the ``--langmap`` option, and "`Determining file language`_", above. 1215 1216 This option does not work with ``--machinable`` nor 1217 ``--with-list-header``. 1218 1219``--list-mline-regex-flags`` 1220 Output list of flags which can be used in a multiline regex parser 1221 definition. 1222 See ctags-optlib(7). 1223 1224``--list-params[=(<language>|all)]`` 1225 Lists the parameters for either the specified *<language>* or ``all`` 1226 languages, and then exits. 1227 ``all`` is used as default value if the option argument is omitted. 1228 1229``--list-pseudo-tags`` 1230 Output list of pseudo-tags. 1231 1232``--list-regex-flags`` 1233 Lists the flags that can be used in ``--regex-<LANG>`` option. 1234 See ctags-optlib(7). 1235 1236``--list-roles[=(<language>|all)[.(<kind-specs>|*)]]`` 1237 List the roles for either the specified *<language>* or ``all`` languages. 1238 ``all`` is used as default value if the option argument is omitted. 1239 1240 If the parameter *<kindspecs>* is given after the parameter 1241 *<language>* or ``all`` with concatenating with '``.``', list only roles 1242 defined in the kinds. Both one-letter flags and long name flags surrounded 1243 by braces are acceptable as the parameter *<kindspecs>*. 1244 1245 The meaning of columns are as follows: 1246 1247 LANGUAGE 1248 The name of language having the role. 1249 1250 KIND(L/N) 1251 The one-letter flag and the long-name flag of kind having the role. 1252 1253 NAME 1254 The long-name flag of the role. 1255 1256 ENABLED 1257 Whether the kind is enabled or not. It takes ``yes`` or ``no``. 1258 1259 DESCRIPTION 1260 Human readable description for the role. 1261 1262``--list-subparsers[=(<baselang>|all)]`` 1263 Lists the subparsers for a base language for either the specified 1264 *<baselang>* or ``all`` languages, and then exits. 1265 ``all`` is used as default value if the option argument is omitted. 1266 1267``--machinable[=(yes|no)]`` 1268 Use tab character as separators for ``--list-`` option output. It 1269 may be suitable for scripting. See "`List options`_" for considered 1270 use cases. Disabled by default. 1271 1272``--with-list-header[=(yes|no)]`` 1273 Print headers describing columns in ``--list-`` option output. 1274 See also "`List options`_". 1275 1276.. _option_misc: 1277 1278Miscellaneous Options 1279~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1280 1281``--help`` 1282 Prints to standard output a detailed usage description, and then exits. 1283 1284``-?`` 1285 Equivalent to ``--help``. 1286 1287``--help-full`` 1288 Prints to standard output a detailed usage description including experimental 1289 features, and then exits. Visit https://docs.ctags.io/ for information 1290 about the latest exciting experimental features. 1291 1292``--license`` 1293 Prints a summary of the software license to standard output, and then exits. 1294 1295``--print-language`` 1296 Just prints the language parsers for specified source files, and then exits. 1297 1298``--quiet[=(yes|no)]`` 1299 Write fewer messages (default is ``no``). 1300 1301``--totals[=(yes|no|extra)]`` 1302 Prints statistics about the source files read and the tag file written 1303 during the current invocation of @CTAGS_NAME_EXECUTABLE@. This option 1304 is ``no`` by default. 1305 1306 The ``extra`` value prints parser specific statistics for parsers 1307 gathering such information. 1308 1309``--verbose[=(yes|no)]`` 1310 Enable verbose mode. This prints out information on option processing 1311 and a brief message describing what action is being taken for each file 1312 considered by @CTAGS_NAME_EXECUTABLE@. Normally, @CTAGS_NAME_EXECUTABLE@ 1313 does not read command line arguments until after options are read 1314 from the configuration files (see "`FILES`_", below). 1315 However, if this option is the first argument on 1316 the command line, it will take effect before any options are read from 1317 these sources. The default is ``no``. 1318 1319``-V`` 1320 Equivalent to ``--verbose``. 1321 1322``--version`` 1323 Prints a version identifier for @CTAGS_NAME_EXECUTABLE@ to standard 1324 output, and then exits. This is guaranteed to always contain the string 1325 "Universal Ctags". 1326 1327Obsoleted Options 1328~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1329These options are kept for backward-compatibility with Exuberant Ctags. 1330 1331``-w`` 1332 This option is silently ignored for backward-compatibility with the 1333 ctags of SVR4 Unix. 1334 1335``--file-scope[=(yes|no)]`` 1336 This options is removed. Use ``--extras=[+|-]F`` or 1337 ``--extras=[+|-]{fileScope}`` instead. 1338 1339``--extra=[+|-][<flags>|*]`` 1340 Equivalent to ``--extras=[+|-][<flags>|*]``, which was introduced to make 1341 the option naming convention align to the other options like 1342 ``--kinds-<LANG>=`` and ``--fields=``. 1343 1344``--<LANG>-kinds=[+|-](<kinds>|*)`` 1345 This option is obsolete. Use ``--kinds-<LANG>=...`` instead. 1346 1347OPERATIONAL DETAILS 1348------------------- 1349As @CTAGS_NAME_EXECUTABLE@ considers each source file name in turn, it tries to 1350determine the language of the file by applying tests described in 1351"`Determining file language`_". 1352 1353If a language was identified, the file is opened and then the appropriate 1354language parser is called to operate on the currently open file. The parser 1355parses through the file and adds an entry to the tag file for each 1356language object it is written to handle. See "`TAG FILE FORMAT`_", below, 1357for details on these entries. 1358 1359Notes for C/C++ Parser 1360~~~~~~~~~~~~~~~~~~~~~~~~~~ 1361 1362.. TODO: move the following description to parser-cxx.rst. 1363 1364This implementation of @CTAGS_NAME_EXECUTABLE@ imposes no formatting 1365requirements on C code as do legacy implementations. Older implementations 1366of ctags tended to rely upon certain formatting assumptions in order to 1367help it resolve coding dilemmas caused by preprocessor conditionals. 1368 1369In general, @CTAGS_NAME_EXECUTABLE@ tries to be smart about conditional 1370preprocessor directives. If a preprocessor conditional is encountered 1371within a statement which defines a tag, @CTAGS_NAME_EXECUTABLE@ follows 1372only the first branch of that conditional (except in the special case of 1373``#if 0``, in which case it follows only the last branch). The reason for 1374this is that failing to pursue only one branch can result in ambiguous 1375syntax, as in the following example: 1376 1377.. code-block:: C 1378 1379 #ifdef TWO_ALTERNATIVES 1380 struct { 1381 #else 1382 union { 1383 #endif 1384 short a; 1385 long b; 1386 } 1387 1388Both branches cannot be followed, or braces become unbalanced and 1389@CTAGS_NAME_EXECUTABLE@ would be unable to make sense of the syntax. 1390 1391If the application of this heuristic fails to properly parse a file, 1392generally due to complicated and inconsistent pairing within the 1393conditionals, @CTAGS_NAME_EXECUTABLE@ will retry the file using a 1394different heuristic which does not selectively follow conditional 1395preprocessor branches, but instead falls back to relying upon a closing 1396brace ('``}``') in column 1 as indicating the end of a block once any brace 1397imbalance results from following a ``#if`` conditional branch. 1398 1399@CTAGS_NAME_EXECUTABLE@ will also try to specially handle arguments lists 1400enclosed in double sets of parentheses in order to accept the following 1401conditional construct:: 1402 1403 extern void foo __ARGS((int one, char two)); 1404 1405Any name immediately preceding the '``((``' will be automatically ignored and 1406the previous name will be used. 1407 1408C++ operator definitions are specially handled. In order for consistency 1409with all types of operators (overloaded and conversion), the operator 1410name in the tag file will always be preceded by the string "operator " 1411(i.e. even if the actual operator definition was written as "operator<<"). 1412 1413After creating or appending to the tag file, it is sorted by the tag name, 1414removing identical tag lines. 1415 1416.. _guessing: 1417 1418Determining file language 1419~~~~~~~~~~~~~~~~~~~~~~~~~~ 1420 1421File name mapping 1422.......................... 1423 1424Unless the ``--language-force`` option is specified, the language of each source 1425file is automatically selected based upon a *mapping* of file names to 1426languages. The mappings in effect for each language may be displayed using 1427the ``--list-maps`` option and may be changed using the ``--langmap`` or 1428``--map-<LANG>`` options. 1429 1430If the name of a file is not mapped to a language, @CTAGS_NAME_EXECUTABLE@ tries 1431to heuristically guess the language for the file by inspecting its content. 1432 1433All files that have no file name mapping and no guessed parser are 1434ignored. This permits running @CTAGS_NAME_EXECUTABLE@ on all files in 1435either a single directory (e.g. "``@CTAGS_NAME_EXECUTABLE@ *``"), or on 1436all files in an entire source directory tree 1437(e.g. "``@CTAGS_NAME_EXECUTABLE@ -R``"), since only those files whose 1438names are mapped to languages will be scanned. 1439 1440An extension may be mapped to multiple parsers. For example, ``.h`` 1441are mapped to C++, C and ObjectiveC. These mappings can cause 1442issues. @CTAGS_NAME_EXECUTABLE@ tries to select the proper parser 1443for the source file by applying heuristics to its content, however 1444it is not perfect. In case of issues one can use ``--language-force=<language>``, 1445``--langmap=<map>[,<map>[...]]``, or the ``--map-<LANG>=[+|-]<extension>|<pattern>`` 1446options. (Some of the heuristics are applied whether ``--guess-language-eagerly`` 1447is given or not.) 1448 1449.. TODO: all heuristics??? To be confirmed. 1450 1451Heuristically guessing 1452.......................... 1453 1454If @CTAGS_NAME_EXECUTABLE@ cannot select a parser from the mapping of file names, 1455various heuristic tests are conducted to determine the language: 1456 1457template file name testing 1458 If the file name has an ``.in`` extension, @CTAGS_NAME_EXECUTABLE@ applies 1459 the mapping to the file name without the extension. For example, 1460 ``config.h`` is tested for a file named ``config.h.in``. 1461 1462"interpreter" testing 1463 The first line of the file is checked to see if the file is a ``#!`` 1464 script for a recognized language. @CTAGS_NAME_EXECUTABLE@ looks for 1465 a parser having the same name. 1466 1467 If @CTAGS_NAME_EXECUTABLE@ finds no such parser, 1468 @CTAGS_NAME_EXECUTABLE@ looks for the name in alias lists. For 1469 example, consider if the first line is ``#!/bin/sh``. Though 1470 @CTAGS_NAME_EXECUTABLE@ has a "shell" parser, it doesn't have a "sh" 1471 parser. However, ``sh`` is listed as an alias for ``shell``, therefore 1472 @CTAGS_NAME_EXECUTABLE@ selects the "shell" parser for the file. 1473 1474 An exception is ``env``. If ``env`` is specified (for example 1475 "``#!/usr/bin/env python``"), @CTAGS_NAME_EXECUTABLE@ 1476 reads more lines to find real interpreter specification. 1477 1478 To display the list of aliases, use ``--list-aliases`` option. 1479 To add an item to the list or to remove an item from the list, use the 1480 ``--alias-<LANG>=+<pattern>`` or ``--alias-<LANG>=-<pattern>`` option 1481 respectively. 1482 1483"zsh autoload tag" testing 1484 If the first line starts with ``#compdef`` or ``#autoload``, 1485 @CTAGS_NAME_EXECUTABLE@ regards the line as "zsh". 1486 1487"emacs mode at the first line" testing 1488 The Emacs editor has multiple editing modes specialized for programming 1489 languages. Emacs can recognize a marker called modeline in a file 1490 and utilize the marker for the mode selection. This heuristic test does 1491 the same as what Emacs does. 1492 1493 @CTAGS_NAME_EXECUTABLE@ treats ``MODE`` as a name of interpreter and applies the same 1494 rule of "interpreter" testing if the first line has one of 1495 the following patterns:: 1496 1497 -*- mode: MODE -*- 1498 1499 or 1500 1501 :: 1502 1503 -*- MODE -*- 1504 1505"emacs mode at the EOF" testing 1506 Emacs editor recognizes another marker at the end of file as a 1507 mode specifier. This heuristic test does the same as what Emacs does. 1508 1509 @CTAGS_NAME_EXECUTABLE@ treats ``MODE`` as a name of an interpreter and applies the same 1510 rule of "interpreter" heuristic testing, if the lines at the tail of the file 1511 have the following pattern:: 1512 1513 Local Variables: 1514 ... 1515 mode: MODE 1516 ... 1517 End: 1518 1519 3000 characters are sought from the end of file to find the pattern. 1520 1521"vim modeline" testing 1522 Like the modeline of the Emacs editor, Vim editor has the same concept. 1523 @CTAGS_NAME_EXECUTABLE@ treats ``TYPE`` as a name of interpreter and applies the same 1524 rule of "interpreter" heuristic testing if the last 5 lines of the file 1525 have one of the following patterns:: 1526 1527 filetype=TYPE 1528 1529 or 1530 1531 :: 1532 1533 ft=TYPE 1534 1535"PHP marker" testing 1536 If the first line is started with ``<?php``, 1537 @CTAGS_NAME_EXECUTABLE@ regards the line as "php". 1538 1539Looking into the file contents is a more expensive operation than file 1540name matching. So @CTAGS_NAME_EXECUTABLE@ runs the testings in limited 1541conditions. "interpreter" testing is enabled only when a file is an 1542executable or the ``--guess-language-eagerly`` (``-G`` in short) option is 1543given. The other heuristic tests are enabled only when ``-G`` option is 1544given. 1545 1546The ``--print-language`` option can be used just to print the results of 1547parser selections for given files instead of generating a tags file. 1548 1549Examples: 1550 1551.. code-block:: console 1552 1553 $ @CTAGS_NAME_EXECUTABLE@ --print-language config.h.in input.m input.unknown 1554 config.h.in: C++ 1555 input.m: MatLab 1556 input.unknown: NONE 1557 1558``NONE`` means that @CTAGS_NAME_EXECUTABLE@ does not select any parser for the file. 1559 1560TAG FILE FORMAT 1561--------------- 1562 1563This section describes the tag file format briefly. See tags(5) and 1564ctags-client-tools(7) for more details. 1565 1566When not running in etags mode, each entry in the tag file consists of a 1567separate line, each looking like this, called *regular tags*, in the most general case: 1568 1569:: 1570 1571 <tag_name><TAB><file_name><TAB><ex_cmd>;"<TAB><extension_fields> 1572 1573The fields and separators of these lines are specified as follows: 1574 1575 1. ``<tag_name>``: tag name 1576 2. ``<TAB>``: single tab character 1577 3. ``<file_name>``: name of the file in which the object associated with the tag is located 1578 4. ``<TAB>``: single tab character 1579 5. ``<ex_cmd>``: EX command used to locate the tag within the file; generally a 1580 search pattern (either ``/pattern/`` or ``?pattern?``) or line number (see 1581 ``--excmd=<type>`` option). 1582 6. ``;"<TAB><extension_fields>``: a set of extension fields. See 1583 "`Extension fields`_" for more details. 1584 1585 Tag file format 2 (see ``--format``) extends the EX command 1586 to include the extension fields embedded in an EX comment immediately appended 1587 to the EX command, which leaves it backward-compatible with original 1588 ``vi(1)`` implementations. 1589 1590A few special tags, called *pseudo tags*, are written into the tag file for internal purposes. 1591 1592:: 1593 1594 !_TAG_FILE_FORMAT 2 /extended format; --format=1 will not append ;" to lines/ 1595 !_TAG_FILE_SORTED 1 /0=unsorted, 1=sorted, 2=foldcase/ 1596 ... 1597 1598``--pseudo-tags=[+|-](<pseudo-tag>|*)`` option enables or disables emitting pseudo-tags. 1599 1600See the output of "``@CTAGS_NAME_EXECUTABLE@ --list-pseudo-tags``" for the list of 1601the kinds. 1602See also tags(5) and ctags-client-tools(7) for more details of the pseudo tags. 1603 1604These tags are composed in such a way that they always sort to the top of 1605the file. Therefore, the first two characters of these tags are used a magic 1606number to detect a tag file for purposes of determining whether a 1607valid tag file is being overwritten rather than a source file. 1608 1609Note that the name of each source file will be recorded in the tag file 1610exactly as it appears on the command line. Therefore, if the path you 1611specified on the command line was relative to the current directory, then 1612it will be recorded in that same manner in the tag file. See, however, 1613the ``--tag-relative=(yes|no|always|never)`` option for how this behavior can be 1614modified. 1615 1616.. _tag_entries: 1617 1618TAG ENTRIES 1619----------- 1620 1621A tag is an index for a language object. The concept of a tag and related 1622items in Exuberant Ctags are refined and extended in Universal Ctags. 1623 1624A tag is categorized into *definition tags* or *reference tags*. 1625In general, Exuberant Ctags only tags *definitions* of 1626language objects: places where newly named language objects *are introduced*. 1627Universal Ctags, on the other hand, can also tag *references* of language 1628objects: places where named language objects *are used*. However, support 1629for generating reference tags is new and limited to specific areas of 1630specific languages in the current version. 1631 1632Extension fields 1633~~~~~~~~~~~~~~~~ 1634 1635A tag can record various information, called *extension fields*. 1636 1637Extension fields are tab-separated key-value pairs appended to the end of 1638the EX command as a comment, as described above. These key value pairs 1639appear in the general form ``key:value``. 1640 1641In addition, information on the scope of the tag definition may be 1642available, with the key portion equal to some language-dependent construct 1643name and its value the name declared for that construct in the program. 1644This scope entry indicates the scope in which the tag was found. 1645For example, a tag generated for a C structure member would have a scope 1646looking like ``struct:myStruct``. 1647 1648``--fields=[+|-][<flags>|*]`` and ``--fields-(<LANG>|all)=[+|-][<flags>|*]`` options specifies 1649which available extension fields are to be included in the tag entries. 1650 1651See the output of "``@CTAGS_NAME_EXECUTABLE@ --list-fields``" for the list of 1652extension fields. 1653The essential fields are ``name``, ``input``, ``pattern``, and ``line``. 1654The meaning of major fields is as follows (long-name flag/one-letter flag): 1655 1656``access``/``a`` 1657 Indicates the visibility of this class member, where value is specific 1658 to the language. 1659 1660``end``/``e`` 1661 Indicates the line number of the end lines of the language object. 1662 1663``extras``/``E`` 1664 Extra tag type information. See "`Extras`_" for details. 1665 1666``file``/``f`` 1667 Indicates that the tag has file-limited visibility. This key has no 1668 corresponding value. Enabled by default. 1669 1670``implementation``/``m`` 1671 When present, this indicates a limited implementation (abstract vs. 1672 concrete) of a routine or class, where value is specific to the 1673 language (``virtual`` or ``pure virtual`` for C++; ``abstract`` for Java). 1674 1675``inherits``/``i`` 1676 When present, value is a comma-separated list of classes from which 1677 this class is derived (i.e. inherits from). 1678 1679``input``/``F`` 1680 The name of source file where ``name`` is defined or referenced. 1681 1682``k`` 1683 `Kind <Kinds>`_ of tag as one-letter. Enabled by default. 1684 This field has no long-name. 1685 See also ``kind``/``z`` flag. 1686 1687``K`` 1688 `Kind <Kinds>`_ of tag as long-name. 1689 This field has no long-name. 1690 See also ``kind``/``z`` flag. 1691 1692``kind``/``z`` 1693 Include the ``kind:`` key in `kind field <Kinds>`_. See also ``k`` and ``K`` flags. 1694 1695``language``/``l`` 1696 Language of source file containing tag 1697 1698``line``/``n`` 1699 The line number where ``name`` is defined or referenced in ``input``. 1700 1701``name``/``N`` 1702 The name of language objects. 1703 1704``nth``/``o`` 1705 The order in the parent scope. 1706 (i.e. 4th parameter in the function). 1707 1708``pattern``/``P`` 1709 Can be used to search the ``name`` in ``input`` 1710 1711``roles``/``r`` 1712 Roles assigned to the tag. See "`Roles`_" for more details. 1713 1714``s`` 1715 Scope of tag definition. Enabled by default. 1716 This field has no long-name. 1717 See also ``scope``/``Z`` flag. 1718 1719``scope``/``Z`` 1720 Prepend the ``scope:`` key to scope (``s``) field. 1721 See also ``s`` flag. 1722 1723``scopeKind``/``p`` 1724 Kind of scope as long-name 1725 1726``signature``/``S`` 1727 When present, value is a language-dependent representation of the 1728 signature of a routine (e.g. prototype or parameter list). A routine signature in its complete form 1729 specifies the return type of a routine and its formal argument list. 1730 This extension field is presently supported only for C-based 1731 languages and does not include the return type. 1732 1733``typeref``/``t`` 1734 Type and name of a variable, typedef, or return type of 1735 callable like function as ``typeref:`` field. 1736 Enabled by default. 1737 1738Kinds 1739...... 1740 1741``kind`` is a field which represents the *kind* of language object 1742specified by a tag. Kinds used and defined are very different between 1743parsers. For example, C language defines ``macro``, ``function``, 1744``variable``, ``typedef``, etc. 1745 1746``--kinds-(<LANG>|all)=[+|-](<kinds>|*)`` option specifies a list of language-specific 1747kinds of tags (or kinds) to include in the output file for a particular 1748language. 1749 1750See the output of "``@CTAGS_NAME_EXECUTABLE@ --list-kinds-full``" for the complete 1751list of the kinds. 1752 1753Its value is either one of the 1754corresponding one-letter flags or a long-name flag. It is permitted 1755(and is, in fact, the default) for the key portion of this field to be 1756omitted. The optional behaviors are controlled with the ``--fields`` option as follows. 1757 1758.. code-block:: console 1759 1760 $ ctags -o - kinds.c 1761 foo kinds.c /^int foo() {$/;" f typeref:typename:int 1762 $ ctags --fields=+k -o - kinds.c 1763 foo kinds.c /^int foo() {$/;" f typeref:typename:int 1764 $ ctags --fields=+K -o - kinds.c 1765 foo kinds.c /^int foo() {$/;" function typeref:typename:int 1766 $ ctags --fields=+z -o - kinds.c 1767 foo kinds.c /^int foo() {$/;" kind:f typeref:typename:int 1768 $ ctags --fields=+zK -o - kinds.c 1769 foo kinds.c /^int foo() {$/;" kind:function typeref:typename:int 1770 1771Roles 1772...... 1773 1774*Role* is a newly introduced concept in Universal Ctags. Role is a 1775concept associated with reference tags, and is not implemented widely yet. 1776 1777As described previously in "`Kinds`_", the ``kind`` field represents the type 1778of language object specified with a tag, such as a function vs. a variable. 1779Specific kinds are defined for reference tags, such as the C++ kind ``header`` for 1780header file, or Java kind ``package`` for package statements. For such reference 1781kinds, a ``roles`` field can be added to distinguish the role of the reference 1782kind. In other words, the ``kind`` field identifies the *what* of the language 1783object, whereas the ``roles`` field identifies the *how* of a referenced language 1784object. Roles are only used with specific kinds. 1785 1786For a definition tag, this field takes ``def`` as a value. 1787 1788For example, ``Baz`` is tagged as a reference tag with kind ``package`` and with 1789role ``imported`` with the following code. 1790 1791.. code-block:: java 1792 1793 package Bar; 1794 import Baz; 1795 1796 class Foo { 1797 // ... 1798 } 1799 1800.. code-block:: console 1801 1802 $ ctags --fields=+KEr -uo - roles.java 1803 Bar roles.java /^package Bar;$/;" package roles:def 1804 Foo roles.java /^class Foo {$/;" class roles:def 1805 $ ctags --fields=+EKr --extras=+r -uo - roles.java 1806 Bar roles.java /^package Bar;$/;" package roles:def 1807 Baz roles.java /^import Baz;$/;" package roles:imported extras:reference 1808 Foo roles.java /^class Foo {$/;" class roles:def 1809 1810``--roles-(<LANG>|all).(<kind>|all)=[+|-][<roles>|*]`` option specifies a list of kind-specific 1811roles of tags to include in the output file for a particular language. 1812 1813Inquire the output of "``@CTAGS_NAME_EXECUTABLE@ --list-roles``" for the list of 1814roles. 1815 1816Extras 1817~~~~~~ 1818 1819Generally, @CTAGS_NAME_EXECUTABLE@ tags only language objects appearing 1820in source files, as is. In other words, a value for a ``name:`` field 1821should be found on the source file associated with the ``name:``. An 1822``extra`` type tag (*extra*) is for tagging a language object with a processed 1823name, or for tagging something not associated with a language object. A typical 1824extra tag is ``qualified``, which tags a language object with a 1825class-qualified or scope-qualified name. 1826 1827``--extras-(<LANG>|all)=[+|-][<flags>|*]`` option specifies 1828whether to include extra tag entries for certain kinds of information. 1829 1830Inquire the output of ``@CTAGS_NAME_EXECUTABLE@ --list-extras`` for the list of extras. 1831The meaning of major extras is as follows (long-name flag/one-letter flag): 1832 1833``anonymous``/none 1834 Include an entry for the language object that has no name like lambda 1835 function. This extra has no one-letter flag and is enabled by 1836 default. 1837 1838 The extra tag is useful as a placeholder to fill scope fields 1839 for language objects defined in a language object with no name. 1840 1841 .. code-block:: C 1842 1843 struct { 1844 double x, y; 1845 } p = { .x = 0.0, .y = 0.0 }; 1846 1847 '``x``' and '``y``' are the members of a structure. When filling the scope 1848 fields for them, @CTAGS_NAME_EXECUTABLE@ has trouble because the struct 1849 where '``x``' and '``y``' belong to has no name. For overcoming the trouble, 1850 @CTAGS_NAME_EXECUTABLE@ generates an anonymous extra tag for the struct 1851 and fills the scope fields with the name of the extra tag. 1852 1853 .. code-block:: console 1854 1855 $ ctags --fields=-f -uo - input.c 1856 __anon9f26d2460108 input.c /^struct {$/;" s 1857 x input.c /^ double x, y;$/;" m struct:__anon9f26d2460108 1858 y input.c /^ double x, y;$/;" m struct:__anon9f26d2460108 1859 p input.c /^} p = { .x = 0.0, .y = 0.0 };$/;" v typeref:struct:__anon9f26d2460108 1860 1861 The above tag output has ``__anon9f26d2460108`` as an anonymous extra tag. 1862 The typeref field of '``p``' also receives the benefit of it. 1863 1864``fileScope``/``F`` 1865 Indicates whether tags scoped only for a single file (i.e. tags which 1866 cannot be seen outside of the file in which they are defined, such as 1867 language objects with ``static`` modifier of C language) should be included 1868 in the output. See also the ``-h`` option. 1869 1870 This extra tag is enabled by default. Add ``--extras=-F`` option not to 1871 output tags scoped only for a single-file. This is the replacement for 1872 ``--file-scope`` option of Exuberant Ctags. 1873 1874 .. code-block:: c 1875 1876 static int f() { 1877 return 0; 1878 } 1879 int g() { 1880 return 0; 1881 } 1882 1883 .. code-block:: console 1884 1885 $ ctags -uo - filescope.c 1886 f filescope.c /^static int f() {$/;" f typeref:typename:int file: 1887 g filescope.c /^int g() {$/;" f typeref:typename:int 1888 $ ctags --extras=-F -uo - filescope.c 1889 g filescope.c /^int g() {$/;" f typeref:typename:int 1890 1891``inputFile``/``f`` 1892 Include an entry for the base file name of every source file 1893 (e.g. ``example.c``), which addresses the first line of the file. 1894 This flag is the replacement for ``--file-tags`` hidden option of 1895 Exuberant Ctags. 1896 1897 If the ``end:`` field is enabled, the end line number of the file can be 1898 attached to the tag. (However, @CTAGS_NAME_EXECUTABLE@ omits the ``end:`` field 1899 if no newline is in the file like an empty file.) 1900 1901 By default, @CTAGS_NAME_EXECUTABLE@ doesn't create the ``inputFile``/``f`` extra 1902 tag for the source file when @CTAGS_NAME_EXECUTABLE@ doesn't find a parser 1903 for it. Enabling ``Unknown`` parser with ``--languages=+Unknown`` forces 1904 @CTAGS_NAME_EXECUTABLE@ to create the extra tags for any source files. 1905 1906 The etags mode enables the ``Unknown`` parser implicitly. 1907 1908``pseudo``/``p`` 1909 Include pseudo-tags. Enabled by default unless the tag file is 1910 written to standard output. See ctags-client-tools(7) about 1911 the detail of pseudo-tags. 1912 1913``qualified``/``q`` 1914 Include an extra class-qualified or namespace-qualified tag entry 1915 for each tag which is a member of a class or a namespace. 1916 1917 This may allow easier location of a specific tags when 1918 multiple occurrences of a tag name occur in the tag file. 1919 Note, however, that this could potentially more than double 1920 the size of the tag file. 1921 1922 The actual form of the qualified tag depends upon the language 1923 from which the tag was derived (using a form that is most 1924 natural for how qualified calls are specified in the 1925 language). For C++ and Perl, it is in the form 1926 ``class::member``; for Eiffel and Java, it is in the form 1927 ``class.member``. 1928 1929 Note: Using backslash characters as separators forming 1930 qualified name in PHP. However, in tags output of 1931 Universal Ctags, a backslash character in a name is escaped 1932 with a backslash character. See tags(5) about the escaping. 1933 1934 The following example demonstrates the ``qualified`` extra tag. 1935 1936 .. code-block:: Java 1937 1938 class point { 1939 double x; 1940 }; 1941 1942 For the above source file, @CTAGS_NAME_EXECUTABLE@ tags ``point`` and ``x`` by 1943 default. If the ``qualified`` extra is enabled from the command line 1944 (``--extras=+q``), then ``point.x`` is also tagged even though the string 1945 "``point.x``" is not in the source code. 1946 1947 .. code-block:: console 1948 1949 $ ctags --fields=+K -uo - qualified.java 1950 point qualified.java /^class point {$/;" class 1951 x qualified.java /^ double x;$/;" field class:point 1952 $ ctags --fields=+K --extras=+q -uo - qualified.java 1953 point qualified.java /^class point {$/;" class 1954 x qualified.java /^ double x;$/;" field class:point 1955 point.x qualified.java /^ double x;$/;" field class:point 1956 1957``reference``/``r`` 1958 Include reference tags. See "`TAG ENTRIES`_" about reference tags. 1959 1960 The following example demonstrates the ``reference`` extra tag. 1961 1962 .. code-block:: c 1963 1964 #include <stdio.h> 1965 #include "utils.h" 1966 #define X 1967 #undef X 1968 1969 The ``roles:system`` or ``roles:local`` fields will be 1970 added depending on whether the include file name begins with '``<``' or not. 1971 1972 "``#define X``" emits a definition tag. On the other hand "``#undef X``" emits a 1973 reference tag. 1974 1975 .. code-block:: console 1976 1977 $ ctags --fields=+EKr -uo - inc.c 1978 X inc.c /^#define X$/;" macro file: roles:def extras:fileScope 1979 $ ctags --fields=+EKr --extras=+r -uo - inc.c 1980 stdio.h inc.c /^#include <stdio.h>/;" header roles:system extras:reference 1981 utils.h inc.c /^#include "utils.h"/;" header roles:local extras:reference 1982 X inc.c /^#define X$/;" macro file: roles:def extras:fileScope 1983 X inc.c /^#undef X$/;" macro file: roles:undef extras:fileScope,reference 1984 1985Language-specific fields and extras 1986~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1987 1988Exuberant Ctags has the concept of *fields* and *extras*. They are common 1989between parsers of different languages. Universal Ctags extends this concept 1990by providing language-specific fields and extras. 1991 1992.. Note: kinds are language-specific since e-ctags. roles are new to u-ctags. 1993 1994.. TODO: move the following "Hot to ..." sections to FAQ man page when available 1995 1996HOW TO USE WITH VI 1997------------------ 1998 1999``vi(1)`` will, by default, expect a tag file by the name ``tags`` in the current 2000directory. Once the tag file is built, the following commands exercise 2001the tag indexing feature: 2002 2003``vi -t tag`` 2004 Start vi and position the cursor at the file and line where ``tag`` 2005 is defined. 2006 2007``:ta tag`` 2008 Find a tag. 2009 2010``Ctrl-]`` 2011 Find the tag under the cursor. 2012 2013``Ctrl-T`` 2014 Return to previous location before jump to tag (not widely implemented). 2015 2016 2017HOW TO USE WITH GNU EMACS 2018------------------------- 2019 2020``emacs(1)`` will, by default, expect a tag file by the name ``TAGS`` in the 2021current directory. Once the tag file is built, the following commands 2022exercise the tag indexing feature: 2023 2024``M-x visit-tags-table <RET> FILE <RET>`` 2025 Select the tag file, ``FILE``, to use. 2026 2027``M-. [TAG] <RET>`` 2028 Find the first definition of TAG. The default tag is the identifier 2029 under the cursor. 2030 2031``M-*`` 2032 Pop back to where you previously invoked ``M-.``. 2033 2034``C-u M-.`` 2035 Find the next definition for the last tag. 2036 2037For more commands, see the Tags topic in the Emacs info document. 2038 2039 2040HOW TO USE WITH NEDIT 2041--------------------- 2042 2043NEdit version 5.1 and later can handle the new extended tag file format 2044(see ``--format``). 2045 2046* To make NEdit use the tag file, select "File->Load Tags File". 2047* To jump to the definition for a tag, highlight the word, then press ``Ctrl-D``. 2048 2049NEdit 5.1 can read multiple tag files from different 2050directories. Setting the X resource ``nedit.tagFile`` to the name of a tag 2051file instructs NEdit to automatically load that tag file at startup time. 2052 2053 2054CAVEATS 2055------- 2056 2057Because @CTAGS_NAME_EXECUTABLE@ is neither a preprocessor nor a compiler, 2058use of preprocessor macros can fool @CTAGS_NAME_EXECUTABLE@ into either 2059missing tags or improperly generating inappropriate tags. Although 2060@CTAGS_NAME_EXECUTABLE@ has been designed to handle certain common cases, 2061this is the single biggest cause of reported problems. In particular, 2062the use of preprocessor constructs which alter the textual syntax of C 2063can fool @CTAGS_NAME_EXECUTABLE@. You can work around many such problems 2064by using the ``-I`` option. 2065 2066Note that since @CTAGS_NAME_EXECUTABLE@ generates patterns for locating 2067tags (see the ``--excmd`` option), it is entirely possible that the wrong line 2068may be found by your editor if there exists another source line which is 2069identical to the line containing the tag. The following example 2070demonstrates this condition: 2071 2072.. code-block:: C 2073 2074 int variable; 2075 2076 /* ... */ 2077 void foo(variable) 2078 int variable; 2079 { 2080 /* ... */ 2081 } 2082 2083Depending upon which editor you use and where in the code you happen to be, 2084it is possible that the search pattern may locate the local parameter 2085declaration before it finds the actual global variable definition, 2086since the lines (and therefore their search patterns) are 2087identical. 2088 2089This can be avoided by use of the ``--excmd=n`` option. 2090 2091 2092BUGS 2093---- 2094 2095@CTAGS_NAME_EXECUTABLE@ has more options than ``ls(1)``. 2096 2097@CTAGS_NAME_EXECUTABLE@ assumes the input file is written in the correct 2098grammar. Otherwise output of ctags is undefined. In other words it has garbage 2099in, garbage out (GIGO) feature. 2100 2101.. TODO: move the following paragraph to parser-cxx.rst. 2102 2103When parsing a C++ member function definition (e.g. ``className::function``), 2104@CTAGS_NAME_EXECUTABLE@ cannot determine whether the scope specifier 2105is a class name or a namespace specifier and always lists it as a class name 2106in the scope portion of the extension fields. Also, if a C++ function 2107is defined outside of the class declaration (the usual case), the access 2108specification (i.e. public, protected, or private) and implementation 2109information (e.g. virtual, pure virtual) contained in the function 2110declaration are not known when the tag is generated for the function 2111definition. It will, however be available for prototypes (e.g. ``--kinds-c++=+p``). 2112 2113No qualified tags are generated for language objects inherited into a class. 2114 2115ENVIRONMENT VARIABLES 2116--------------------- 2117``TMPDIR`` 2118 On Unix-like hosts where ``mkstemp(3)`` is available, the value of this 2119 variable specifies the directory in which to place temporary files. 2120 This can be useful if the size of a temporary file becomes too large 2121 to fit on the partition holding the default temporary directory 2122 defined at compilation time. 2123 2124 @CTAGS_NAME_EXECUTABLE@ creates temporary 2125 files only if either (1) an emacs-style tag file is being 2126 generated, (2) the tag file is being sent to standard output, or 2127 (3) the program was compiled to use an internal sort algorithm to sort 2128 the tag files instead of the ``sort(1)`` utility of the operating system. 2129 If the ``sort(1)`` utility of the operating system is being used, it will 2130 generally observe this variable also. 2131 2132 Note that if @CTAGS_NAME_EXECUTABLE@ 2133 is setuid, the value of ``TMPDIR`` will be ignored. 2134 2135 2136FILES 2137----- 2138 2139``tags`` 2140 The default tag file created by @CTAGS_NAME_EXECUTABLE@. 2141 2142``TAGS`` 2143 The default tag file created by @ETAGS_NAME_EXECUTABLE@. 2144 2145``$XDG_CONFIG_HOME/ctags/*.ctags``, or ``$HOME/.config/ctags/*.ctags`` if 2146``$XDG_CONFIG_HOME`` is not defined 2147(on other than MS Windows) 2148 2149``$HOME/.ctags.d/*.ctags`` 2150 2151``$HOMEDRIVE$HOMEPATH/ctags.d/*.ctags`` (on MS Windows only) 2152 2153``.ctags.d/*.ctags`` 2154 2155``ctags.d/*.ctags`` 2156 2157 If any of these configuration files exist, each will be expected to 2158 contain a set of default options which are read in the order listed 2159 when @CTAGS_NAME_EXECUTABLE@ starts, but before any command line options 2160 are read. This makes it possible to set up personal or project-level defaults. 2161 2162 It 2163 is possible to compile @CTAGS_NAME_EXECUTABLE@ to read an additional 2164 configuration file before any of those shown above, which will be 2165 indicated if the output produced by the ``--version`` option lists the 2166 ``custom-conf`` feature. 2167 2168 Options appearing on the command line will override options 2169 specified in these files. Only options will be read from these 2170 files. 2171 2172 Note that the option 2173 files are read in line-oriented mode in which spaces are significant 2174 (since shell quoting is not possible) but spaces at the beginning 2175 of a line are ignored. Each line of the file is read as 2176 one command line parameter (as if it were quoted with single quotes). 2177 Therefore, use new lines to indicate separate command-line arguments. 2178 2179 A line starting with '``#``' is treated as a comment. 2180 2181 ``*.ctags`` files in a directory are loaded in alphabetical order. 2182 2183 2184SEE ALSO 2185-------- 2186 2187See ctags-optlib(7) for defining (or extending) a parser 2188in a configuration file. 2189 2190See tags(5) for the format of tag files. 2191 2192See ctags-incompatibilities(7) about known incompatible changes 2193with Exuberant Ctags. 2194 2195See ctags-client-tools(7) if you are interested in writing 2196a tool for processing tags files. 2197 2198See ctags-lang-python(7) about python input specific notes. 2199 2200See readtags(1) about a client tool for binary searching a 2201name in a sorted tags file. 2202 2203The official Universal Ctags web site at: https://ctags.io/ 2204 2205Also ``ex(1)``, ``vi(1)``, ``elvis(1)``, or, better yet, ``vim(1)``, the official editor of ctags. 2206For more information on ``vim(1)``, see the Vim web site at: https://www.vim.org/ 2207 2208 2209AUTHOR 2210------ 2211 2212Universal Ctags project 2213https://ctags.io/ 2214 2215Darren Hiebert <dhiebert@users.sourceforge.net> 2216http://DarrenHiebert.com/ 2217 2218 2219MOTIVATION 2220---------- 2221 2222"Think ye at all times of rendering some service to every member of the 2223human race." 2224 2225"All effort and exertion put forth by man from the fullness of his heart is 2226worship, if it is prompted by the highest motives and the will to do 2227service to humanity." 2228 2229-- From the Baha'i Writings 2230 2231CREDITS 2232------- 2233This version of @CTAGS_NAME_EXECUTABLE@ (Universal Ctags) derived from 2234the repository, known as fishman-ctags, started by Reza Jelveh. 2235 2236The fishman-ctags was derived from Exuberant Ctags. 2237 2238Some parsers are taken from ``tagmanager`` of the Geany (https://www.geany.org/) 2239project. 2240 2241Exuberant Ctags was originally derived from and 2242inspired by the ctags program by Steve Kirkendall <kirkenda@cs.pdx.edu> 2243that comes with the Elvis vi clone (though virtually none of the original 2244code remains). 2245 2246Credit is also due Bram Moolenaar <Bram@vim.org>, the author of vim, 2247who has devoted so much of his time and energy both to developing the editor 2248as a service to others, and to helping the orphans of Uganda. 2249 2250The section entitled "`HOW TO USE WITH GNU EMACS`_" was shamelessly stolen 2251from the info page for GNU etags. 2252