| Version: | +5.9.0 |
|---|---|
| Manual group: | Universal Ctags | +
| Manual section: | 7 | +
Client tool means a tool running the ctags command +and/or reading a tags file generated by ctags command. +This man page gathers hints for people who develop client tools.
+Pseudo-tags, stored in a tag file, indicate how +ctags generated the tags file: whether the +tags file is sorted or not, which version of tags file format is used, +the name of tags generator, and so on. The opposite term for +pseudo-tags is regular-tags. A regular-tag is for a language +object in an input file. A pseudo-tag is for the tags file +itself. Client tools may use pseudo-tags as reference for processing +regular-tags.
+A pseudo-tag is stored in a tags file in the same format as +regular-tags as described in tags(5), except that pseudo-tag names +are prefixed with "!_". For the general information about +pseudo-tags, see "TAG FILE INFORMATION" in tags(5).
+An example of a pseudo tag:
++!_TAG_PROGRAM_NAME Universal Ctags /Derived from Exuberant Ctags/ ++
The value, "2", associated with the pseudo tag "TAG_PROGRAM_NAME", is +used in the field for input file. The description, "Derived from +Exuberant Ctags", is used in the field for pattern.
+Universal Ctags extends the naming scheme of the classical pseudo-tags +available in Exuberant Ctags for emitting language specific +information as pseudo tags:
+
+!_{pseudo-tag-name}!{language-name} {associated-value} /{description}/
+
+The language-name is appended to the pseudo-tag name with a separator, "!".
+An example of pseudo tag with a language suffix:
++!_TAG_KIND_DESCRIPTION!C f,function /function definitions/ ++
This pseudo-tag says "the function kind of C language is enabled +when generating this tags file." --pseudo-tags is the option for +enabling/disabling individual pseudo-tags. When enabling/disabling a +pseudo tag with the option, specify the tag name only +"TAG_KIND_DESCRIPTION", without the prefix ("!_") or the suffix ("!C").
+Forces writing pseudo-tags.
+ctags emits pseudo-tags by default when writing tags +to a regular file (e.g. "tags'.) However, when specifying -o - +or -f - for writing tags to standard output, +ctags doesn't emit pseudo-tags. --extras=+p or +--extras=+{pseudo} will force pseudo-tags to be written.
+Lists available types of pseudo-tags and shows whether they are enabled or disabled.
+Running ctags with --list-pseudo-tags option +lists available pseudo-tags. Some of pseudo-tags newly introduced +in Universal Ctags project are disabled by default. Use +--pseudo-tags=... to enable them.
+Specifies a list of pseudo-tag types to include in the output.
+The parameters are a set of pseudo tag names. Valid pseudo tag names +can be listed with --list-pseudo-tags. Surround each name in the set +with braces, like "{TAG_PROGRAM_AUTHOR}". You don't have to include the "!_" +pseudo tag prefix when specifying a name in the option argument for --pseudo-tags= +option.
+pseudo-tags don't have a notation using one-letter flags.
+If a name is preceded by either the '+' or '-' characters, that +tags's effect has been added or removed. Otherwise the names replace +any current settings. All entries are included if '*' is given.
+Attach "extras:pseudo" field to pseudo-tags.
+An example of pseudo tags with the field:
++!_TAG_PROGRAM_NAME Universal Ctags /Derived from Exuberant Ctags/ extras:pseudo ++
If the name of a normal tag in a tag file starts with "!_", a +client tool cannot distinguish whether the tag is a regular-tag or +pseudo-tag. The fields attached with this option help the tool +distinguish them.
+Running ctags with --list-pseudo-tags option lists available types +of pseudo-tags with short descriptions. This subsection shows hints +for using notable ones.
+Indicates the names and descriptions of enabled extras:
+
+!_TAG_EXTRA_DESCRIPTION {extra-name} /description/
+!_TAG_EXTRA_DESCRIPTION!{language-name} {extra-name} /description/
+
+If your tool relies on some extra tags (extras), refer to +the pseudo-tags of this type. A tool can reject the tags file that +doesn't include expected extras, and raise an error in an early +stage of processing.
+An example of the pseudo-tags:
+
+$ ctags --extras=+p --pseudo-tags='{TAG_EXTRA_DESCRIPTION}' -o - input.c
+!_TAG_EXTRA_DESCRIPTION anonymous /Include tags for non-named objects like lambda/
+!_TAG_EXTRA_DESCRIPTION fileScope /Include tags of file scope/
+!_TAG_EXTRA_DESCRIPTION pseudo /Include pseudo tags/
+!_TAG_EXTRA_DESCRIPTION subparser /Include tags generated by subparsers/
+...
+
+A client tool can know "{anonymous}", "{fileScope}", "{pseudo}", +and "{subparser}" extras are enabled from the output.
+Indicates the names and descriptions of enabled fields:
+
+!_TAG_FIELD_DESCRIPTION {field-name} /description/
+!_TAG_FIELD_DESCRIPTION!{language-name} {field-name} /description/
+
+If your tool relies on some fields, refer to the pseudo-tags of +this type. A tool can reject a tags file that doesn't include +expected fields, and raise an error in an early stage of +processing.
+An example of the pseudo-tags:
+
+$ ctags --fields-C=+'{macrodef}' --extras=+p --pseudo-tags='{TAG_FIELD_DESCRIPTION}' -o - input.c
+!_TAG_FIELD_DESCRIPTION file /File-restricted scoping/
+!_TAG_FIELD_DESCRIPTION input /input file/
+!_TAG_FIELD_DESCRIPTION name /tag name/
+!_TAG_FIELD_DESCRIPTION pattern /pattern/
+!_TAG_FIELD_DESCRIPTION typeref /Type and name of a variable or typedef/
+!_TAG_FIELD_DESCRIPTION!C macrodef /macro definition/
+...
+
+A client tool can know "{file}", "{input}", "{name}", "{pattern}", +and "{typeref}" fields are enabled from the output. +The fields are common in languages. In addition to the common fields, +the tool can known "{macrodef}" field of C language is also enabled.
+Indicates the names and descriptions of enabled kinds:
+
+!_TAG_KIND_DESCRIPTION!{language-name} {kind-letter},{kind-name} /description/
+
+If your tool relies on some kinds, refer to the pseudo-tags of +this type. A tool can reject the tags file that doesn't include +expected kinds, and raise an error in an early stage of +processing.
+Kinds are language specific, so a language name is always +appended to the tag name as suffix.
+An example of the pseudo-tags:
+
+$ ctags --extras=+p --kinds-C=vfm --pseudo-tags='{TAG_KIND_DESCRIPTION}' -o - input.c
+!_TAG_KIND_DESCRIPTION!C f,function /function definitions/
+!_TAG_KIND_DESCRIPTION!C m,member /struct, and union members/
+!_TAG_KIND_DESCRIPTION!C v,variable /variable definitions/
+...
+
+A client tool can know "{function}", "{member}", and "{variable}" +kinds of C language are enabled from the output.
+Indicates the working directory of ctags during processing.
+This pseudo-tag helps a client tool solve the absolute paths for +the input files for tag entries even when they are tagged with +relative paths.
+An example of the pseudo-tags:
+
+$ cat tags
+!_TAG_PROC_CWD /tmp/ //
+main input.c /^int main (void) { return 0; }$/;" f typeref:typename:int
+...
+
+From the regular tag for "main", the client tool can know the +"main" is at "input.c". However, it is a relative path. So if the +directory where ctags run and the directory +where the client tool runs are different, the client tool cannot +find "input.c" from the file system. In that case, +TAG_PROC_CWD gives the tool a hint; "input.c" may be at "/tmp".
+Indicates the names and descriptions of enabled roles:
+
+!_TAG_ROLE_DESCRIPTION!{language-name}!{kind-name} {role-name} /description/
+
+If your tool relies on some roles, refer to the pseudo-tags of +this type. Note that a role owned by a disabled kind is not listed +even if the role itself is enabled.
+TBW
+Universal ctags can run multiple parsers. +That means a parser, which supports multiple parsers, may output tags for +different languages. language/l field can be used to show the language +for each tag.
++$ cat /tmp/foo.html +<html> +<script>var x = 1</script> +<h1>title</h1> +</html> +$ ./ctags -o - --extras=+g /tmp/foo.html +title /tmp/foo.html /^ <h1>title<\/h1>$/;" h +x /tmp/foo.html /var x = 1/;" v +$ ./ctags -o - --extras=+g --fields=+l /tmp/foo.html +title /tmp/foo.html /^ <h1>title<\/h1>$/;" h language:HTML +x /tmp/foo.html /var x = 1/;" v language:JavaScript ++
See readtags(1) to know how to use readtags. This section is for discussing +some notable topics for client tools.
+Certain escape sequences in expressions are recognized by readtags. For +example, when searching for a tag that matches a\?b, if using a filter +expression like '(eq? $name "a\?b")', since \? is translated into a +single ? by readtags, it actually searches for a?b.
+Another problem is if a single quote appear in filter expressions (which is +also wrapped by single quotes), it terminates the expression, producing broken +expressions, and may even cause unintended shell injection. Single quotes can +be escaped using '"'"'.
+So, client tools need to:
+inside the expressions. If the expression also contains strings, " in the +strings needs to be replaced by \".
+Client tools written in Lisp could build the expression using lists. prin1 +(in Common Lisp style Lisps) and write (in Scheme style Lisps) can +translate the list into a string that can be directly used. For example, in +EmacsLisp:
+ +The "?" is escaped, and readtags can handle it. Scheme style Lisps should do +proper escaping so the expression readtags gets is just the expression passed +into write. Common Lisp style Lisps may produce unrecognized escape +sequences by readtags, like \#. Readtags provides some aliases for these +Lisps:
+Notice that even when the client tool uses this method, ' still needs to be +replaced by '"'"' to prevent broken expressions and shell injection.
+Another thing to notice is that missing fields are represented by #f, and +applying string operators to them will produce an error. You should always +check if a field is missing before applying string operators. See the +"Filtering" section in readtags(1) to know how to do this. Run "readtags -H +filter" to see which operators take string arguments.
+In the output of readtags, tabs can appear in all field values (e.g., the tag +name itself could contain tabs), which makes it hard to split the line into +fields. Client tools should use the -E option, which keeps the escape +sequences in the tags file, so the only field that could contain tabs is the +pattern field.
+The pattern field could:
+These are true for tags files using extended format, which is the default one. +The legacy format (i.e. --format=1) doesn't include the semicolons. It's +old and barely used, so we won't discuss it here.
+Client tools could split the line using the following steps:
+Then, the escape sequences in fields other than the pattern field should be +translated. See "Proposal" in tags(5) to know about all the escape sequences.
+The pattern field specifies how to find a tag in its source file. The code +generating this field seems to have a long history, so there are some pitfalls +and it's a bit hard to handle. A client tool could simply require the line: +field and jump to the line it specifies, to avoid using the pattern field. But +anyway, we'll discuss how to make the best use of it here.
+You should take the words here merely as suggestions, and not standards. A +client tool could definitely develop better (or simpler) ways to use the +pattern field.
+From the last section, we know the pattern field could contain a line number +and a search pattern. When it only contains the line number, handling it is +easy: you simply go to that line.
+The search pattern resembles an EX command, but as we'll see later, it's +actually not a valid one, so some manual work are required to process it.
+The search pattern could look like /pat/, called "forward search pattern", +or ?pat?, called "backward search pattern". Using a search pattern means +even if the source file is updated, as long as the part containing the tag +doesn't change, we could still locate the tag correctly by searching.
+When the pattern field only contains the search pattern, you just search for +it. The search direction (forward/backward) doesn't matter, as it's decided +solely by whether the -B option is enabled, and not the actual context. You +could always start the search from say the beginning of the file.
+When both the search pattern and the line number are presented, you could make +good use of the line number, by going to the line first, then searching for the +nearest occurence of the pattern. A way to do this is to search both forward +and backward for the pattern, and when there is a occurence on both sides, go +to the nearer one.
+What's good about this is when there are multiple identical lines in the source +file (e.g. the COMMON block in Fortran), this could help us find the correct +one, even after the source file is updated and the tag position is shifted by a +few lines.
+Now let's discuss how to search for the pattern. After you trim the / or +? around it, the pattern resembles a regex pattern. It should be a regex +pattern, as required by being a valid EX command, but it's actually not, as +you'll see below.
+It could begin with a ^, which means the pattern starts from the beginning +of a line. It could also end with an unescaped $ which means the pattern +ends at the end of a line. Let's keep this information, and trim them too.
+Now the remaining part is the actual string containing the tag. Some characters +are escaped:
+You need to unescape these to get the literal string. Now you could convert +this literal string to a regexp that matches it (by escaping, like +re.escape in Python or regexp-quote in Elisp), and assemble it with +^ or $ if the pattern originally has it, and finally search for the tag +using this regexp.
+In some earlier versions of Universal Ctags, the line number in the pattern +field is the actual line number minus one, for forward search patterns; or plus +one, for backward search patterns. The idea is to resemble an EX command: you +go to the line, then search forward/backward for the pattern, and you can +always find the correct one. But this denies the purpose of using a search +pattern: to tolerate file updates. For example, the tag is at line 50, +according to this scheme, the pattern field should be:
++49;/pat/;" ++
Then let's assume that some code above are removed, and the tag is now at +line 45. Now you can't find it if you search forward from line 49.
+Due to this reason, Universal Ctags turns to use the actual line number. A +client tool could distinguish them by the TAG_OUTPUT_EXCMD pseudo tag, it's +"combine" for the old scheme, and "combineV2" for the present scheme. But +probably there's no need to treat them differently, since "search for the +nearest occurence from the line" gives good result on both schemes.
+Universal Ctags supports JSON (strictly +speaking JSON Lines) output format if the +ctags executable is built with libjansson. JSON output goes to +standard output by default.
+Each JSON line represents a tag.
++$ ctags --extras=+p --output-format=json --fields=-s input.py +{"_type": "ptag", "name": "JSON_OUTPUT_VERSION", "path": "0.0", "pattern": "in development"} +{"_type": "ptag", "name": "TAG_FILE_SORTED", "path": "1", "pattern": "0=unsorted, 1=sorted, 2=foldcase"} +... +{"_type": "tag", "name": "Klass", "path": "/tmp/input.py", "pattern": "/^class Klass:$/", "language": "Python", "kind": "class"} +{"_type": "tag", "name": "method", "path": "/tmp/input.py", "pattern": "/^ def method(self):$/", "language": "Python", "kind": "member", "scope": "Klass", "scopeKind": "class"} +... ++
A key not starting with _ is mapped to a field of ctags. +"--output-format=json --list-fields" options list the fields.
+A key starting with _ represents meta information of the JSON +line. Currently only _type key is used. If the value for the key +is tag, the JSON line represents a normal tag. If the value is +ptag, the line represents a pseudo-tag.
+The output format can be changed in the +future. JSON_OUTPUT_VERSION pseudo-tag provides a change +client-tools to handle the changes. Current version is "0.0". A +client-tool can extract the version with path key from the +pseudo-tag.
+The JSON output format is newly designed and has no limitation found +in the default tags file format.
+Values for the most of all keys are represented in JSON string type. +However, some of them are represented in string, integer, and/or boolean type.
+"--output-format=json --list-fields" options show What kind of data type +used in a field of JSON.
++$ ctags --output-format=json --list-fields +#LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION +F input yes NONE s-- no input file +... +P pattern yes NONE s-b no pattern +... +f file yes NONE --b no File-restricted scoping +... +e end no NONE -i- no end lines of various items +... ++
JSTYPE column shows the data types.
+For an example, the value for pattern field of ctags takes a string or a boolean value.
+ctags(1), ctags-lang-python(7), ctags-incompatibilities(7), tags(5), readtags(1)
+| Version: | +5.9.0 |
|---|---|
| Manual group: | Universal Ctags | +
| Manual section: | 7 | +
This is the Universal Ctags FAQ (Frequently-Asked Questions). +It is based on Exuberant Ctags FAQ
+Contents
+Universal Ctags is an unofficial fork of Exuberant Ctags. +The differences are summarized in ctags-incompatibilities(7) man page.
+The most notable one is that Universal Ctags doesn't read ~/.ctags file. +Instead, it reads *.ctags under ~/.ctags.d directory.
+Either by setting the environment variable CTAGS to your custom +options, or putting them into a ~/.ctags.d/anyname.ctags file in your home +directory.
+These are extension flags. They are added in order to provide extra +information about the tag that may be utilized by the editor in order to +more intelligently handle tags. They are appended to the EX command part of +the tag line in a manner that provides backwards compatibility with existing +implementations of the Vi editor. The semicolon is an EX command separator +and the double quote begins an EX comment. Thus, the extension flags appear +as an EX comment and should be ignored by the editor when it processes the +EX command.
+Some non-vi editors, however, implement only the bare minimum of EX commands +in order to process the search command or line number in the third field of +the tag file. If you encounter this problem, use the option --format=1 to +generate a tag file without these extensions (remember that you can set the +CTAGS environment variable to any default arguments you wish to supply). Then +ask the supplier of your editor to implement handling of this feature of EX +commands.
+Because, by default, ctags only generates tags for the separate identifiers +found in the source files. If you specify the --extra=+q option, then +ctags will also generate a second, class-qualified tag for each class member +(data and function/method) in the form class::member for C++, and in the form +class.method for Eiffel and Java.
+By default, ctags encodes the line number in the file where macro (#define) +tags are found. This was done to remain compatible with the original UNIX +version of ctags. If you change the file containing the tag without +rebuilding the tag file, the location of tag in the tag file may no longer +match the current location.
+In order to avoid this problem, you can specify the option --excmd=p, +which causes ctags to use a search pattern to locate macro tags. I have +never uncovered the reason why the original UNIX ctags used line numbers +exclusively for macro tags, but have so far resisted changing the default +behavior of Exuberant (and Universal) Ctags to behave differently.
+A tag file is simple a list of tag names and where to find them. If there +are duplicate entries, you often end up going to the wrong one because the +tag file is sorted and your editor locates the first one in the tag file.
+Standard Vi provides no facilities to alter this behavior. However, Vim +has some nice features to minimize this problem, primarily by examining all +matches and choosing the best one under the circumstances. Vim also provides +commands which allow for selection of the desired matching tag.
+There are several packages already available which provide this capability. +Namely, these are: GLOBAL source code tag system, GNU id-utils, cscope, +and cflow. As of this writing, they can be found in the following locations:
+Sometimes, in an attempt to build a global tag file for all source files in +a large source tree of many directories, someone will make an attempt to run +ctags in append (-a) mode on every directory in the hierarchy. Each time +ctags is invoked, its default behavior is to sort the tag file once the tags +for that execution have been added. As the cumulative tag file grows, the sort +time increases arithmetically.
+The best way to avoid this problem (and the most efficient) is to make +use of the --recurse (or -R) option of ctags by executing the following +command in the root of the directory hierarchy (thus running ctags only once):
++++ctags -R ++
If you really insist on running ctags separately on each directory, you can +avoid the sort pass each time by specifying the option --sort=no. Once the +tag file is completely built, use the sort command to manually sort the +final tag file, or let the final invocation of ctags sort the file.
+There are a few ways of approaching this:
+Each of these approaches has its own set of advantages and disadvantages, +depending upon your particular conditions. Which approach is deemed best +depends upon the following factors:
+The ability of your editor to use multiple tag files.
+If your editor cannot make use of multiple tag files (original vi +implementations could not), then one large tag file is the only way to +go if you ever desire to jump to tags located in other directories. If +you never need to jump to tags in another directory (i.e. the source +in each directory is entirely self-contained), then a local tag file +in each directory will fit your needs.
+The time is takes for your editor to look up a tag in the tag file.
+The significance of this factor depends upon the size of your source +tree and on whether the source files are located on a local or remote +file system. For source and tag files located on a local file system, +looking up a tag is not as big a hit as one might first imagine, since +vi implementations typically perform a binary search on a sorted tag +file. This may or may not be true for the editor you use. For files +located on a remote file system, reading a large file is an expensive +operation.
+Whether or not you expect the source code to change and the time it +takes to rebuild a tag file to account for changes to the source code.
+While Universal Ctags is particularly fast in scanning source code +(around 1-2 MB/sec), a large project may still result in objectionable +delays if one wishes to keep their tag file(s) up to date on a +frequent basis, or if the files are located on a remote file system.
+The presence of duplicate tags in the source code and the ability to +handle them.
+The impact of this factor is influenced by the following three issues:
+How common are duplicate tags in your project?
+Does your editor provide any facilities for dealing with duplicate +tags?
+While standard vi does not, many modern vi implementations, such +as Vim have good facilities for selecting the desired match from +the list of duplicates. If your editor does not support duplicate +tags, then it will typically send you to only one of them, whether +or not that is the one you wanted (and not even notifying you that +there are other potential matches).
+What is the significance of duplicate tags?
+For example, if you have two tags of the same name from entirely +isolated software components, jumping first to the match found +in component B while working in component A may be entirely +misleading, distracting or inconvenient (to keep having to choose +which one if your editor provides you with a list of matches). +However, if you have two tags of the same name for parallel builds +(say two initialization routines for different hosts), you may +always want to specify which one you want.
+Of the approaches listed above, I tend to favor Approach 3. My editor of +choice is Vim, which provides a rich set of features for handling multiple +tag files, which partly influences my choice. If you are working with +source files on a remote file system, then I would recommend either +Approach 3 or Approach 4, depending upon the hit when reading the global +tag file.
+The advantages of Approach 3 are many (assuming that your editor has +the ability to support both multiple tag files and duplicate tags). All +lookups of tag located in the current directory are fast and the local +tag file can be quickly and easily regenerated in one second or less +(I have even mapped a keystroke to do this easily). A lookup of a +(necessarily non-static) tag found in another directory fails a lookup in +the local tag file, but is found in the global tag file, which satisfies +all cross-directory lookups. The global tag file can be automatically +regenerated periodically with a cron job (and perhaps the local tag files +also).
+Now I give an example of how you would implement Approach 3. Means of +implementing the other approaches can be performed in a similar manner.
+Here is a visual representation of an example directory hierarchy:
++project +`-----misccomp +| `... +`-----sysint + `-----client + | `-----hdrs + | `-----lib + | `-----src + | `-----test + `-----common + | `-----hdrs + | `-----lib + | `-----src + | `-----test + `-----server + `-----hdrs + `-----lib + `-----src + `-----test ++
Here is a recommended solution (conceptually) to build the tag files:
+Within each of the leaf nodes (i.e. hdrs, lib, src, test) build a tag +file using "ctags *.[ch]". This can be easily be done for the whole +hierarchy by making a shell script, call it dirtags, containing the +following lines:
++++#!/bin/sh +cd $1 +ctags * ++
Now execute the following command:
++++find * -type d -exec dirtags {} \; ++
These tag files are trivial (and extremely quick) to rebuild while +making changes within a directory. The following Vim key mapping is +quite useful to rebuild the tag file in the directory of the current +source file:
++++:nmap ,t :!(cd %:p:h;ctags *.[ch])&<CR><CR> ++
Build the global tag file:
++++cd ~/project +ctags --file-scope=no -R ++
thus constructing a tag file containing only non-static tags for all +source files in all descendent directories.
+Configure your editor to read the local tag file first, then consult +the global tag file when not found in the local tag file. In Vim, +this is done as follows:
++++:set tags=./tags,tags,~/project/tags ++
If you wish to implement Approach 4, you would need to replace the +dirtags script of step 1 with the following:
++++#!/bin/sh +cd $1 +ctags * +# Now append the non-static tags from descendent directories +find * -type d -prune -print | ctags -aR --file-scope=no -L- ++
And replace the configuration of step 3 with this:
++++:set tags=./tags;$HOME,tags ++
As a caveat, it should be noted that step 2 builds a global tag file whose +file names will be relative to the directory in which the global tag file +is being built. This takes advantage of the Vim tagrelative option, +which causes the path to be interpreted a relative to the location of the +tag file instead of the current directory. For standard vi, which always +interprets the paths as relative to the current directory, we need to +build the global tag file with absolute path names. This can be +accomplished by replacing step 2 with the following:
++++cd ~/project +ctags --file-scope=no -R `pwd` ++
Yes, Unicode file names are supported on unix-like platforms (Linux, macOS, +Cygwin, etc.).
+However, on Windows, you need to use Windows 10 version 1903 or later to use +Unicode file names. (This is an experimental feature, though.) On older versions +on Windows, Universal Ctags only support file names represented in the current +code page. If you still want to use Unicode file names on them, use Cygwin or +MSYS2 version of Universal Ctags as a workaround.
+zsh causes error on the following cases;
++++ctags --extra=+* ... +ctags --exclude=foo/* ... ++
This is the 2nd most significant incompatibility feature of zsh.
+Cited from "Z-Shell Frequently-Asked Questions", "2.1: Differences from sh and +ksh";
++... The next most classic difference is that unmatched glob patterns cause +the command to abort; set NO_NOMATCH for those.+
You may add "setopt nonomatch" on your ~/.zshrc. Or you can escape glob +patterns with backslash;
++++ctags --extra=+\* ... +ctags --exclude=foo/\* ... ++
Or quote them;
++++ctags '--extra=+*' ... +ctags '--exclude=foo/*' ... ++
This FAQ is based on Exuberant Ctags FAQ by +Darren Hiebert and vberthoux@users.sourceforge.net
+Universal Ctags project: https://ctags.io/
+| Version: | +5.9.0 |
|---|---|
| Manual group: | Universal Ctags | +
| Manual section: | 7 | +
This page describes major incompatible changes introduced to +Universal Ctags forked from Exuberant Ctags.
+Universal Ctags doesn't load ~/.ctags at starting up time. +File paths for preload files are changed. +See "FILES" section of ctags(1).
+Universal Ctags doesn't read CTAGS and/or ETAGS environment +variables.
+The command line format of Universal Ctags is "ctags [options] +[source_file(s)]" following the standard POSIX convention.
+Exuberant Ctags accepts a option following a source file.
++$ ctags -o - foo.c --list-kinds=Sh +f functions ++
Universal Ctags warns and ignores the option --list-kinds=Sh as follows.
++$ ctags -o - foo.c --list-kinds=Sh +ctags: Warning: cannot open input file "--list-kinds=Sh" : No such file or directory +a foo.c /^void a () {}$/;" f typeref:typename:void +b foo.c /^void b () {}$/;" f typeref:typename:void ++
When applying mappings for a name of given source file, +Exuberant Ctags tests file name patterns AFTER file extensions +(e-map-order). Universal Ctags does this differently; it tests file +name patterns BEFORE file extensions (u-map-order).
+This incompatible change is introduced to deal with the following +situation:
++++
+- build.xml as a source file,
+- The Ant parser declares it handles a file name pattern build.xml, and
+- The XML parser declares it handles a file extension .xml.
+
Which parser should be used for parsing build.xml? The assumption +of Universal Ctags is the user may want to use the Ant parser; the +file name pattern it declares is more specific than the file extension +that the XML parser declares. However, e-map-order chooses the XML +parser.
+So Universal Ctags uses the u-map-order even though it introduces an +incompatibility.
+--list-map-extensions=<language> and --list-map-patterns=<language> +options are helpful to verify and the file extensions and the file +name patterns of given <language>.
+Even in Exuberant Ctags, --file-tags is not documented in its man page. +Instead of specifying --file-tags or --file-tags=yes, use +--extras=+f or --extras=+{inputFile}.
+Instead of specifying --file-tags=no, use +--extras=-f or --extras=-{inputFile}.
+Universal Ctags introduces F/fileScope extra as the replacement for +--file-scope option.
+Instead of specifying --file-tags or --file-tags=yes, use +--extras=+F or --extras=+{fileScope}.
+Instead of specifying --file-tags=no, use +--extras=-F or --extras=-{fileScope}.
+The characters you can use are more restricted than Exuberant Ctags. +For more details, see the description of --langdef=name in ctags-optlib(7).
+Some options have <LANG> as parameterized parts in their name like +--foo-<LANG>=... or --<LANG>-foo=.... The most of all such +options in Exuberant Ctags have the former form, --foo-<LANG>=.... +The exception is --<LANG>-kinds.
+Universal Ctags uses the former form for all <LANG> parameterized +option. Use --kinds-<LANG> instead of --<LANG>-kinds in +Universal Ctags. --<LANG>-kinds still works but it will be +removed in the future.
+The former form may be friendly to shell completion engines.
+The kind name file is reserved. Using it as part of kind spec in +--regex-<LANG> option is now disallowed.
+The kind letter 'F' is reserved. Using it as part of a kind spec in +--regex-<LANG> option is now disallowed.
+Exuberant Ctags accepts a character other than alphabetical character +as kind letter in --regex-<LANG>=... option. Universal Ctags +accepts only an alphabetical character.
+Exuberant Ctags accepts any character as a part of a kind name +defined with --regex-<LANG>=/regex/replacement/kind-spec/.
+Universal Ctags accepts only an alphabetical character as +the initial letter of a kind name. +Universal Ctags accepts only an alphabetical character or +numerical character as the rest letters.
+An example:
++--regex-Foo=/abstract +class +([a-z]+)/\1/a,abstract class/i ++
Universal Ctags rejects this because the kind name, abstract class, +includes a whitespace character.
+This requirement is for making the output of Universal Ctags follow +the tags file format.
+In Universal Ctags, the combination of +a kind letter and a kind name must be unique in a language.
+You cannot define more than one kind reusing a kind letter with +different kind names. You cannot define more than one kind reusing a +kind name with different kind letters.
+An example:
++--regex-Foo=/abstract +class +([a-z]+)/\1/a,abstractClass/i +--regex-Foo=/attribute +([a-z]+)/\1/a,attribute/i ++
Universal Ctags rejects this because the kind letter, 'a', used twice +for defining a kind abstractClass and attribute.
+The version 2 tags file format, the default output format of +Exuberant Ctags, accepts only alphabetical characters in the name part +of tag tagfield.
+Universal Ctags introduces an exception to this specification; it may +use numerical characters in addition to alphabetical characters as the +letters other than initial letter of the name part.
+The kinds heading1, heading2, and heading3 in the HTML parser +are the examples.
+To prevent generating overly large tags files, a pattern field is +truncated, by default, when its size exceeds 96 bytes. A different +limit can be specified with --pattern-length-limit=N. Specifying +0 as N results no truncation as Exuberant Ctags does not.
+A kind letter 'F' and a kind name file are reserved in the +main part. A parser cannot have a kind conflicting with +these reserved ones. Some incompatible changes are introduced +to follow the above rule.
+ctags(1), ctags-optlib(7), and tags(5).
+| Version: | +5.9.0 |
|---|---|
| Manual group: | Universal Ctags | +
| Manual section: | 7 | +
iPythonCell is a subparser stacked on top of the Python parser. +It works when:
+iPythonCell extracts cells explained as in vim-ipython-cell +(https://github.com/hanschen/vim-ipython-cell/blob/master/README.md).
+The iPythonCell parser defines only a cell kind.
+Tagging cells staring with ##... is disabled by default because +the pattern is too generic; with that pattern unwanted tags can be extracted.
+Enable doubleSharps language specific extra for tagging cells +staring with ##....
+If your favorite cell pattern is not supported in the parser, you can +define the pattern in your .ctagd.d/your.ctags or command lines. +Here is an example how to support "# CTAGS: ...":
+"input.py"
++x=1 +# CTAGS: DEFINE F +def F(): + # CTAGS: DO NOTING + pass ++
"output.tags" +with "--options=NONE --sort=no --extras=+{subparser} --regex-IPythonCell=/[ t]*# CTAGS:[ ]?(.*)$/1/c/ -o - input.py"
+ +You can put "--regex-IPythonCell=/[ \t]*# CTAGS:[ ]?(.*)$/\1/c/" in your.ctags +to avoid specifying the pattern repeatedly.
+ctags(1), ctags-client-tools(7), ctags-lang-python(7)
+| Version: | +5.9.0 |
|---|---|
| Manual group: | Universal Ctags | +
| Manual section: | 7 | +
This man page describes the Inko parser for Universal Ctags.
+The input file is expected to be valid Inko source code, otherwise the output of +ctags is undefined.
+Tags are generated for objects, traits, methods, attributes, and constants. +String literals are ignored.
+ctags(1), ctags-client-tools(7)
+| Version: | +5.9.0 |
|---|---|
| Manual group: | Universal-ctags | +
| Manual section: | 7 | +
This man page gathers random notes about tagging Julia source code.
+using X
++++
++ + ++ + + + + + + name +kind +role +other noticeable fields ++ + X +module +used +N/A +
using X: a, b
++++
++ + ++ + + + + + + name +kind +role +other noticeable fields ++ X +module +namespace +N/A ++ + a, b +unknown +used +scope:module:X +
import X
++++
++ + ++ + + + + + + name +kind +role +other noticeable fields ++ + X +module +imported +N/A +
import X.a, Y.b
++++
++ + ++ + + + + + + name +kind +role +other noticeable fields ++ X, Y +module +namespace +N/A ++ a +unknown +imported +scope:module:X ++ + b +unknown +imported +scope:module:Y +
import X: a, b
++++
++ + ++ + + + + + + name +kind +role +other noticeable fields ++ X +module +namespace +N/A ++ + a,b +unknown +imported +scope:module:X +
"input.jl"
++using X0 ++
"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzK input.jl"
+ +--extras=+r (or --extras=+{reference}) option is needed for this tag, +since it's a reference tag. This is because module X is not defined here. +It is defined in another file. Enable roles: field with --fields=+r is +for recording that the module is "used", i.e., loaded by using.
+"input.jl"
++import X1.a, X2.b, X3 ++
"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzKZ input.jl"
+ +Why X1 and X2 have role "namespace", while X3 have role "imported"? +It's because the symbol a in module X1, and b in module X2 are +brought to the current scope, but X1 and X2 themselves are not. We use +"namespace" role for such modules.
+X3 is different. The symbol X3, together with all exported symbols in +X3, is brought to current scope. For such modules, we use "imported" or +"used" role depending whether they are loaded by import or using.
+Also, notice that a and b have the "unknown" kind. This is because we +cannot know whether it's a function, constant, or macro, etc.
+ctags(1), ctags-client-tools(7)
+| Version: | +5.9.0 |
|---|---|
| Manual group: | Universal Ctags | +
| Manual section: | 7 | +
This man page gathers random notes about tagging python source code.
+import X
++++
++ + ++ + + + + + + name +kind +role +other noticeable fields ++ + X +module +imported +N/A +
import X as Y
++++
++ + ++ + + + + + + name +kind +role +other noticeable fields ++ X +module +indirectlyImported +N/A ++ + Y +namespace +definition +nameref:module:X +
from X import *
++++
++ + ++ + + + + + + name +kind +role +other noticeable fields ++ + X +module +namespace +N/A +
from X import Y
++++
++ + ++ + + + + + + name +kind +role +other noticeable fields ++ X +module +namespace +N/A ++ + Y +unknown +imported +scope:module:X +
from X import Y as Z
+++ + + ++
++ + ++ + + + + + + name +kind +role +other noticeable fields ++ X +module +namespace +N/A ++ Y +unknown +indirectlyImported +scope:module:X ++ + Z +unknown +definition +nameref:unknown:X +
"input.py"
++import X0 ++
"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzK input.py"
+ +A tag for an imported module has module kind with imported role. The +module is not defined here; it is defined in another file. So the tag for the +imported module is a reference tag; specify --extras=+r (or +--extras=+{reference}) option for tagging it. "roles:" field enabled with +--fields=+r is for recording the module is "imported" to the tag file.
+"input.py"
++import X1 as Y1 ++
"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzK --fields-Python=+{nameref} input.py"
+ +"Y1" introduces a new name and is defined here. So "Y1" is tagged as a +definition tag. "X1" is imported in a way that its name cannot be used +in this source file. For letting client tools know that the name cannot be used, +indirectlyImported role is assigned for "X1". "Y1" is the name for +accessing objects defined in the module imported via "X1". For recording this +relationship, nameref: field is attached to the tag of "Y1". Instead of +module kind, namespace kind is assigned to "Y1" because "Y1" itself +isn't a module.
+"input.py"
++from X2 import * ++
"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzK input.py"
+ +The module is not defined here; it is defined in another file. So the tag for +the imported module is a reference tag. Unlike "X0" in "import X0", "X2" may not +be used because the names defined in "X2" can be used in this source file. To represent +the difference namespace role is attached to "X2" instead of imported.
+"input.py"
++from X3 import Y3 ++
"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzKZ input.py"
+ +"Y3" is a name for a language object defined in "X3" module. "scope:module:X3" +attached to "Y3" represents this relation between "Y3" and "X3". ctags +assigns unknown kind to "Y3" because ctags cannot know whether "Y3" is a +class, a variable, or a function from the input file.
+"input.py"
++from X4 import Y4 as Z4 ++
"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzKZ input.py"
+ +"Y4" is similar to "Y3" of "from X3 import Y3" but the name cannot be used here. +indirectlyImported role assigned to "Y4" representing this. "Z4" is the name for +accessing the language object named in "Y4" in "X4" module. "nameref:unknown:Y4" +attached to "Z4" and "scope:module:X4" attached to "Y4" represent the relations.
+id = lambda var0: var0
++++
++ + ++ + + + + + + name +kind +role +other noticeable fields ++ + id +function +definition +signature:(var0) +
id_t: Callable[[int], int] = lambda var1: var1
++++
++ + ++ + + + + + + name +kind +role +other noticeable fields ++ id_t +variable +definition +typeref:typename:Callable[[int], int] nameref:function:anonFuncN ++ + anonFuncN +function +definition +signature:(var1) +
"input.py"
++from typing import Callable +id = lambda var0: var0 +id_t: Callable[[int], int] = lambda var1: var1 ++
"output.tags" +with "--options=NONE -o - --sort=no --fields=+KS --fields-Python=+{nameref} --extras=+{anonymous} input.py"
+ +If a variable ("id") with no type hint is initialized with a lambda expression, +ctags assigns function kind for the tag of "id".
+If a variable ("id_t") with a type hint is initialized with a lambda expression, +ctags assigns variable kind for the tag of "id_t" with typeref: and +nameref: fields. ctags fills typeref: field with the value of the type +hint. The way of filling nameref: is a bit complicated.
+For the lambda expression used in initializing the type-hint'ed variable, ctags +creates anonymous extra tag ("anonFunc84011d2c0101"). ctags fills the +nameref: field of "id_t" with the name of anonymous extra tag: +"nameref:function:anonFunc84011d2c0101".
+You may think why ctags does so complicated, and why ctags doesn't emit +following tags output for the input:
++id input.py /^id = \\$/;" function signature:(var0) +id_t input.py /^id_t: \\$/;" function typeref:typename:Callable[[int], int] signature:(var1) ++
There is a reason. The other languages of ctags obey the following rule: ctags fills +typeref: field for a tag of a callable object (like function) with the type +of its return value. If we consider "id_t" is a function, its typeref: field +should have "typename:int". However, for filling typeref: with "typename:int", +ctags has to analyze "Callable[[int], int]" deeper. We don't want to do so.
+ctags(1), ctags-client-tools(7), ctags-lang-iPythonCell(7)
+| Version: | +5.9.0 |
|---|---|
| Manual group: | Universal Ctags | +
| Manual section: | 7 | +
This man page gathers random notes about tagging R source code +with Universal Ctags.
+If a variable gets a value returned from a well-known constructor +and the variable appears for the first time in the current input file, +the R parser makes a tag for the variable and attaches a kind +associated with the constructor to the tag regardless of whether +the variable appears in the top-level context or a function.
+Well-known constructor and kind mapping
++++
++ + ++ + + + + Constructor +kind ++ function() +function ++ c() +vector ++ list() +list ++ + data.frame() +dataframe +
If a variable doesn't get a value returned from one of well-known +constructors, the R parser attaches globalVar or functionVar kind +to the tag for the variable depending on the context.
+Here is an example demonstrating the usage of the kinds:
+"input.r"
++G <- 1 +v <- c(1, 2) +l <- list(3, 4) +d <- data.frame(n = v) +f <- function(a) { + g <- function (b) a + b + w <- c(1, 2) + m <- list (3, 4) + e <- data.frame(n = w) + L <- 2 +} ++
"output.tags" +with "--options=NONE --sort=no --fields=+KZ -o - input.r"
+ + +ctags(1)
+| Version: | +5.9.0 |
|---|---|
| Manual group: | Universal Ctags | +
| Manual section: | 7 | +
The SQL parser supports various SQL dialects. PostgreSQL is one of them.
+PostgreSQL allows user-defined functions to be written in other +languages (procedural languages) besides SQL and C [PL].
+The SQL parser makes tags for language objects in the user-defined +functions written in the procedural languages if the guest extra +is enabled.
+The SQL parser looks for a token coming after LANGUAGE keyword in +the source code to choose a proper guest parser.
++... LANGUAGE plpythonu AS '... user-defined function ' ... +... AS $$ user-defined function $$ LANGUAGE plv8 ... ++
In the above examples, plpythonu and plv8 are the names of +procedural languages. The SQL parser trims pl at the start and u +at the end of the name before finding a parser ctags having. For +plpythonu and `plv8, the SQL parser extracts python and +v8 as the candidates of guest parsers.
+For plpythonu, ctags can run its Python parser. ctags doesn't +have a parser named v8. However, JavaScript parser of ctags has +v8 as an alias. So ctags can run the JavaScript parser as the +guest parser for plv8.
+tagging code including a user-defined function in a string literal [GH3006]:
+"input.sql"
++CREATE OR REPLACE FUNCTION fun1() RETURNS VARCHAR AS ' +DECLARE + test1_var1 VARCHAR(64) := $$ABC$$; + test1_var2 VARCHAR(64) := $xyz$XYZ$xyz$; + test1_var3 INTEGER := 1; +BEGIN + RETURN TO_CHAR(test_var3, ''000'') || test1_var1 || test1_var2; +END; +' LANGUAGE plpgsql; ++
"output.tags" +with "--options=NONE -o - --sort=no --extras=+{guest} input.sql"
+ +tagging code including a user-defined function in a dollar quote [GH3006]:
+"input.sql"
++CREATE OR REPLACE FUNCTION fun2() RETURNS VARCHAR LANGUAGE plpgsql AS $$ +DECLARE + test2_var1 VARCHAR(64) := 'ABC2'; + test2_var2 VARCHAR(64) := 'XYZ2'; + test2_var3 INTEGER := 2; +BEGIN + RETURN TO_CHAR(test2_var3, '000') || test2_var1 || test2_var2; +END; +$$; ++
"output.tags" +with "--options=NONE -o - --sort=no --extras=+{guest} input.sql"
+ +tagging code including a user-defined written in JavaScript:
++-- Derived from https://github.com/plv8/plv8/blob/r3.0alpha/sql/plv8.sql +CREATE FUNCTION test(keys text[], vals text[]) RETURNS text AS +$$ + var o = {}; + for (var i = 0; i < keys.length; i++) + o[keys[i]] = vals[i]; + return JSON.stringify(o); +$$ +LANGUAGE plv8 IMMUTABLE STRICT; ++
"output.tags" +with "--options=NONE -o - --sort=no --extras=+{guest} input.sql"
+ +Escape sequences ('') in a string literal may make a guest parser confused.
+ctags(1), ctags-client-tools(7)
+| [PL] | PostgreSQL 9.5.25 Documentation, "Chapter 39. Procedural Languages", https://www.postgresql.org/docs/9.5/xplang.html |
| [GH3006] | (1, 2) @bagl's comment submitted to https://github.com/universal-ctags/ctags/issues/3006 |
| Version: | +5.9.0 |
|---|---|
| Manual group: | Universal Ctags | +
| Manual section: | 7 | +
+++
++ + ++ + + + + + Language +Language ID +File Mapping ++ SystemVerilog +SystemVerilog +.sv, .svh, svi ++ + Verilog +Verilog +.v +
This man page describes about the SystemVerilog/Verilog parser for Universal Ctags. +SystemVerilog parser supports IEEE Std 1800-2017 keywords. +Verilog parser supports IEEE Std 1364-2005 keywords.
++$ ctags --list-kinds-full=SystemVerilog +#LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +A assert yes no 0 NONE assertions (assert, assume, cover, restrict) +C class yes no 0 NONE classes +E enum yes no 0 NONE enumerators +H checker yes no 0 NONE checkers +I interface yes no 0 NONE interfaces +K package yes no 0 NONE packages +L clocking yes no 0 NONE clocking +M modport yes no 0 NONE modports +N nettype yes no 0 NONE nettype declarations +O constraint yes no 0 NONE constraints +P program yes no 0 NONE programs +Q prototype no no 0 NONE prototypes (extern, pure) +R property yes no 0 NONE properties +S struct yes no 0 NONE structs and unions +T typedef yes no 0 NONE type declarations +V covergroup yes no 0 NONE covergroups +b block yes no 0 NONE blocks (begin, fork) +c constant yes no 0 NONE constants (define, parameter, specparam, enum values) +e event yes no 0 NONE events +f function yes no 0 NONE functions +i instance yes no 0 NONE instances of module or interface +l ifclass yes no 0 NONE interface class +m module yes no 0 NONE modules +n net yes no 0 NONE net data types +p port yes no 0 NONE ports +q sequence yes no 0 NONE sequences +r register yes no 0 NONE variable data types +t task yes no 0 NONE tasks +w member yes no 0 NONE struct and union members ++
Note that prototype (Q) is disabled by default.
++$ ctags --list-kinds-full=Verilog +#LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +b block yes no 0 NONE blocks (begin, fork) +c constant yes no 0 NONE constants (define, parameter, specparam) +e event yes no 0 NONE events +f function yes no 0 NONE functions +i instance yes no 0 NONE instances of module +m module yes no 0 NONE modules +n net yes no 0 NONE net data types +p port yes no 0 NONE ports +r register yes no 0 NONE variable data types +t task yes no 0 NONE tasks ++
+$ ctags --list-fields=Verilog +#LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION +- parameter no Verilog --b no parameter whose value can be overridden. +$ ctags --list-fields=SystemVerilog +#LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION +- parameter no SystemVerilog --b no parameter whose value can be overridden. ++
If the field parameter is enabled, a field parameter: is added on a parameter whose +value can be overridden on an instantiated module, interface, or program. +This is useful for a editor plugin or extension to enable auto-instantiation of modules with +parameters which can be overridden.
++$ ctags ... --fields-Verilog=+{parameter} ... +$ ctags ... --fields-SystemVerilog=+{parameter} ... ++
On the following source code fields parameter: are added on +parameters P*, not on ones L*. Note that L4 and L6 is declared by +parameter statement, but fields parameter: are not added, +because they cannot be overridden.
+"input.sv"
++// compilation unit scope +parameter L1 = "synonym for the localparam"; + +module with_parameter_port_list #( + P1, + localparam L2 = P1+1, + parameter P2) + ( /*port list...*/ ); + parameter L3 = "synonym for the localparam"; + localparam L4 = "localparam"; + // ... +endmodule + +module with_empty_parameter_port_list #() + ( /*port list...*/ ); + parameter L5 = "synonym for the localparam"; + localparam L6 = "localparam"; + // ... +endmodule + +module no_parameter_port_list + ( /*port list...*/ ); + parameter P3 = "parameter"; + localparam L7 = "localparam"; + // ... +endmodule ++
+$ ctags -uo - --fields-SystemVerilog=+{parameter} input.sv +L1 input.sv /^parameter L1 = "synonym for the localparam";$/;" c parameter: +with_parameter_port_list input.sv /^module with_parameter_port_list #($/;" m +P1 input.sv /^ P1,$/;" c module:with_parameter_port_list parameter: +L2 input.sv /^ localparam L2 = P1+1,$/;" c module:with_parameter_port_list +P2 input.sv /^ parameter P2)$/;" c module:with_parameter_port_list parameter: +L3 input.sv /^ parameter L3 = "synonym for the localparam";$/;" c module:with_parameter_port_list +L4 input.sv /^ localparam L4 = "localparam";$/;" c module:with_parameter_port_list +with_empty_parameter_port_list input.sv /^module with_empty_parameter_port_list #()$/;" m +L5 input.sv /^ parameter L5 = "synonym for the localparam";$/;" c module:with_empty_parameter_port_list +L6 input.sv /^ localparam L6 = "localparam";$/;" c module:with_empty_parameter_port_list +no_parameter_port_list input.sv /^module no_parameter_port_list$/;" m +P3 input.sv /^ parameter P3 = "parameter";$/;" c module:no_parameter_port_list parameter: +L7 input.sv /^ localparam L7 = "localparam";$/;" c module:no_parameter_port_list ++
If you want to map files *.v to SystemVerilog, add +--langmap=SystemVerilog:.v option.
+See https://github.com/universal-ctags/ctags/issues/2674 for more information.
+| Version: | +5.9.0 |
|---|---|
| Manual group: | Universal Ctags | +
| Manual section: | 7 | +
Exuberant Ctags, the ancestor of Universal Ctags, has provided +the way to define a new parser from command line. Universal Ctags +extends and refines this feature. optlib parser is the name for such +parser in Universal Ctags. "opt" intends a parser is defined with +combination of command line options. "lib" intends an optlib parser +can be more than ad-hoc personal configuration.
+This man page is for people who want to define an optlib parser. The +readers should read ctags(1) of Universal Ctags first.
+Following options are for defining (or customizing) a parser:
+Following options are for controlling loading parser definition:
+The design of options and notations for defining a parser in +Exuberant Ctags may focus on reducing the number of typing by user. +Reducing the number of typing is important for users who want to +define (or customize) a parser quickly.
+On the other hand, the design in Universal Ctags focuses on +maintainability. The notation of Universal Ctags is redundant than +that of Exuberant Ctags; the newly introduced kind should be declared +explicitly, (long) names are approved than one-letter flags +specifying kinds, and naming rules are stricter.
+This man page explains only stable options and flags. Universal Ctags +also introduces experimental options and flags which have names starting +with _. For documentation on these options and flags, visit +Universal Ctags web site at https://ctags.io/.
+Though it is possible to define a parser from command line, you don't +want to type the same command line each time when you need the parser. +You can store options for defining a parser into a file.
+ctags loads files (preload files) listed in "FILES" +section of ctags(1) at program starting up. You can put your parser +definition needed usually to the files.
+--options=<pathname>, --options-maybe=<pathname>, and +--optlib-dir=[+]<directory> are for loading optlib files you need +occasionally. See "Option File Options" section of ctags(1) for +these options.
+As explained in "FILES" section of ctags(1), options for defining a +parser listed line by line in an optlib file. Prefixed white spaces are +ignored. A line starting with '#' is treated as a comment. Escaping +shell meta character is not needed.
+Use .ctags as file extension for optlib file. You can define +multiple parsers in an optlib file but it is better to make a file for +each parser definition.
+--_echo=<msg> and --_force-quit=<num> options are for debugging +optlib parser.
+Design the parser
+You need know both the target language and the ctags' +concepts (definition, reference, kind, role, field, extra). About +the concepts, ctags(1) of Universal Ctags may help you.
+Give a name to the parser
+Use --langdef=<name> option. <name> is referred as <LANG> in +the later steps.
+Give a file pattern or file extension for activating the parser
+Use --map-<LANG>=[+|-]<extension>|<pattern>.
+Define kinds
+Use --kinddef-<LANG>=<letter>,<name>,<description> option. +Universal Ctags introduces this option. Exuberant Ctags doesn't +have. In Exuberant Ctags, a kind is defined as a side effect of +specifying --regex-<LANG>= option. So user doesn't have a +chance to recognize how important the definition of kind.
+Define patterns
+Use --regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>] +option for a single-line regular expression. You can also use +--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>] +option for a multi-line regular expression.
+As <kind-spec>, you can use the one-letter flag defined with +--kinddef-<LANG>=<letter>,<name>,<description> option.
+Defines a new user-defined language, <name>, to be parsed with regular +expressions. Once defined, <name> may be used in other options taking +language names.
+<name> must consist of alphanumeric characters, '#', or '+' +('[a-zA-Z0-9#+]+'). The graph characters other than '#' and +'+' are disallowed (or reserved). Some of them ([-=:{.]) are +disallowed because they can make the command line parser of +ctags confused. The rest of them are just +reserved for future extending ctags.
+all is an exception. all as <name> is not acceptable. It is +a reserved word. See the description of +--kinds-(<LANG>|all)=[+|-](<kinds>|*) option in ctags(1) about how the +reserved word is used.
+The names of built-in parsers are capitalized. When +ctags evaluates an option in a command line, and +chooses a parser, ctags uses the names of +parsers in a case-insensitive way. Therefore, giving a name +started from a lowercase character doesn't help you to avoid the +parser name confliction. However, in a tags file, +ctags prints parser names in a case-sensitive +way; it prints a parser name as specified in --langdef=<name> +option. Therefore, we recommend you to give a name started from a +lowercase character to your private optlib parser. With this +convention, people can know where a tag entry in a tag file comes +from a built-in parser or a private optlib parser.
+Define a kind for <LANG>. +Be not confused this with --kinds-<LANG>.
+<letter> must be an alphabetical character ('[a-zA-EG-Z]') +other than "F". "F" has been reserved for representing a file +since Exuberant Ctags.
+<name> must start with an alphabetic character, and the rest +must be alphanumeric ('[a-zA-Z][a-zA-Z0-9]*'). Do not use +"file" as <name>. It has been reserved for representing a file +since Exuberant Ctags.
+Note that using a number character in a <name> violates the +version 2 of tags file format though ctags +accepts it. For more detail, see tags(5).
+<description> comes from any printable ASCII characters. The +exception is { and \. { is reserved for adding flags +this option in the future. So put \ before { to include +{ to a description. To include \ itself to a description, +put \ before \.
+Both <letter>, <name> and their combination must be unique in +a <LANG>.
+This option is newly introduced in Universal Ctags. This option +reduces the typing defining a regex pattern with +--regex-<LANG>=, and keeps the consistency of kind +definitions in a language.
+The <letter> can be used as an argument for --kinds-<LANG> +option to enable or disable the kind. Unless K field is +enabled, the <letter> is used as value in the "kind" extension +field in tags output.
+The <name> surrounded by braces can be used as an argument for +--kind-<LANG> option. If K field is enabled, the <name> +is used as value in the "kind" extension field in tags output.
+The <description> and <letter> are listed in --list-kinds +output. All three elements of the kind-spec are listed in +--list-kinds-full output. Don't use braces in the +<description>. They will be used meta characters in the future.
+Define a single-line regular expression.
+The /<line_pattern>/<name_pattern>/ pair defines a regular expression +replacement pattern, similar in style to sed substitution +commands, s/regexp/replacement/, with which to generate tags from source files mapped to +the named language, <LANG>, (case-insensitive; either a built-in +or user-defined language).
+The regular expression, <line_pattern>, defines +an extended regular expression (roughly that used by egrep(1)), +which is used to locate a single source line containing a tag and +may specify tab characters using \t.
+When a matching line is +found, a tag will be generated for the name defined by +<name_pattern>, which generally will contain the special +back-references \1 through \9 to refer to matching sub-expression +groups within <line_pattern>.
+The '/' separator characters shown in the +parameter to the option can actually be replaced by any +character. Note that whichever separator character is used will +have to be escaped with a backslash ('\') character wherever it is +used in the parameter as something other than a separator. The +regular expression defined by this option is added to the current +list of regular expressions for the specified language unless the +parameter is omitted, in which case the current list is cleared.
+Unless modified by <flags>, <line_pattern> is interpreted as a POSIX +extended regular expression. The <name_pattern> should expand for all +matching lines to a non-empty string of characters, or a warning +message will be reported unless {placeholder} regex flag is +specified.
+A kind specifier (<kind-spec>) for tags matching regexp may +follow <name_pattern>, which will determine what kind of tag is +reported in the kind extension field (see tags(5)).
+<kind-spec> has two forms: one-letter form and full form.
+The one-letter form in the form of <letter>. It just refers a kind +<letter> defined with --kinddef-<LANG>. This form is recommended in +Universal Ctags.
+The full form of <kind-spec> is in the form of +<letter>,<name>,<description>. Either the kind <name> and/or the +<description> can be omitted. See the description of +--kinddef-<LANG>=<letter>,<name>,<description> option about the +elements.
+The full form is supported only for keeping the compatibility with Exuberant +Ctags which does not have --kinddef-<LANG> option. Supporting the +form will be removed from Universal Ctags in the future.
+ +About <flags>, see "FLAGS FOR --regex-<LANG> OPTION".
+For more information on the regular expressions used by +ctags, see either the regex(5,7) man page, or +the GNU info documentation for regex (e.g. "info regex").
+Define a multi-line regular expression.
+This option is similar to --regex-<LANG> option except the pattern is +applied to the whole file’s contents, not line by line.
+You can specify more than one flag, <letter>|{<name>}, at the end of --regex-<LANG> to +control how Universal Ctags uses the pattern.
+Exuberant Ctags uses a <letter> to represent a flag. In +Universal Ctags, a <name> surrounded by braces (name form) can be used +in addition to <letter>. The name form makes a user reading an optlib +file easier.
+The most of all flags newly added in Universal Ctags +don't have the one-letter representation. All of them have only the name +representation. --list-regex-flags lists all the flags.
+scope=(ref|push|pop|clear|set)
+++Specify what to do with the internal scope stack.
+A parser programmed with --regex-<LANG> has a stack (scope +stack) internally. You can use it for tracking scope +information. The scope=... flag is for manipulating and +utilizing the scope stack.
+If {scope=push} is specified, a tag captured with +--regex-<LANG> is pushed to the stack. {scope=push} +implies {scope=ref}.
+You can fill the scope field of captured tag with +{scope=ref}. If {scope=ref} flag is given, +ctags attaches the tag at the top to the tag +captured with --regex-<LANG> as the value for the scope: +field.
+ctags pops the tag at the top of the stack when +--regex-<LANG> with {scope=pop} is matched to the input +line.
+Specifying {scope=clear} removes all the tags in the scope. +Specifying {scope=set} removes all the tags in the scope, and +then pushes the captured tag as {scope=push} does.
+In some cases, you may want to use --regex-<LANG> only for its +side effects: using it only to manipulate the stack but not for +capturing a tag. In such a case, make <name_pattern> component of +--regex-<LANG> option empty while specifying {placeholder} +as a regex flag. For example, a non-named tag can be put on +the stack by giving a regex flag "{scope=push}{placeholder}".
+You may wonder what happens if a regex pattern with +{scope=ref} flag matches an input line but the stack is empty, +or a non-named tag is at the top. If the regex pattern contains a +{scope=ref} flag and the stack is empty, the {scope=ref} +flag is ignored and nothing is attached to the scope: field.
+If the top of the stack contains an unnamed tag, +ctags searches deeper into the stack to find the +top-most named tag. If it reaches the bottom of the stack without +finding a named tag, the {scope=ref} flag is ignored and +nothing is attached to the scope: field.
+When a named tag on the stack is popped or cleared as the side +effect of a pattern matching, ctags attaches the +line number of the match to the end: field of +the named tag.
+ctags clears all of the tags on the stack when it +reaches the end of the input source file. The line number of the +end is attached to the end: field of the cleared tags.
+
This is the definition (pod.ctags) used in ctags for parsing Pod +(https://perldoc.perl.org/perlpod.html) file.
+ +Let's think about writing a parser for a very small subset of the Ruby +language.
+input source file (input.srb):
++class Example + def methodA + puts "in class_method" + end + def methodB + puts "in class_method" + end +end ++
The parser for the input should capture Example with class kind, +methodA, and methodB with method kind. methodA and methodB +should have Example as their scope. end: fields of each tag +should have proper values.
+optlib file (sub-ruby.ctags):
+ +command line and output:
++$ ctags --quiet --fields=+eK \ +--options=./sub-ruby.ctags -o - input.srb +Example input.srb /^class Example$/;" class end:8 +methodA input.srb /^ def methodA$/;" method class:Example end:4 +methodB input.srb /^ def methodB$/;" method class:Example end:7 ++
The official Universal Ctags web site at:
+ +ctags(1), tags(5), regex(3), regex(7), egrep(1)
+Universal Ctags project +https://ctags.io/ +(This man page partially derived from ctags(1) of +Executable-ctags)
+Darren Hiebert <dhiebert@users.sourceforge.net> +http://DarrenHiebert.com/
+| Version: | +5.9.0 |
|---|---|
| Manual group: | Universal Ctags | +
| Manual section: | 1 | +
The ctags and etags (see -e option) programs +(hereinafter collectively referred to as ctags, +except where distinguished) generate an index (or "tag") file for a +variety of language objects found in source file(s). This tag file allows +these items to be quickly and easily located by a text editor or other +utilities (client tools). A tag signifies a language object for which an index entry is +available (or, alternatively, the index entry created for that object).
+Alternatively, ctags can generate a cross reference +file which lists, in human readable form, information about the various +language objects found in a set of source files.
+Tag index files are supported by numerous editors, which allow the user to +locate the object associated with a name appearing in a source file and +jump to the file and line which defines the name. See the manual of your +favorite editor about utilizing ctags command and +the tag index files in the editor.
+ctags is capable of generating different kinds of tags +for each of many different languages. For a complete list of supported +languages, the names by which they are recognized, and the kinds of tags +which are generated for each, see the --list-languages and --list-kinds-full +options.
+This man page describes Universal Ctags, an implementation of ctags +derived from Exuberant Ctags. The major incompatible changes between +Universal Ctags and Exuberant Ctags are enumerated in +ctags-incompatibilities(7).
+One of the advantages of Exuberant Ctags is that it allows a user to +define a new parser from the command line. Extending this capability is one +of the major features of Universal Ctags. ctags-optlib(7) +describes how the capability is extended.
+Newly introduced experimental features are not explained here. If you +are interested in such features and ctags internals, +visit https://docs.ctags.io/.
+Despite the wealth of available options, defaults are set so that +ctags is most commonly executed without any options (e.g. +"ctags *", or "ctags -R"), which will +create a tag file in the current directory for all recognized source +files. The options described below are provided merely to allow custom +tailoring to meet special needs.
+Note that spaces separating the single-letter options from their parameters +are optional.
+Note also that the boolean parameters to the long form options (those +beginning with -- and that take a [=(yes|no)] parameter) may be omitted, +in which case =yes is implied. (e.g. --sort is equivalent to --sort=yes). +Note further that =1, =on, and =true are considered synonyms for =yes, +and that =0, =off, and =false are considered synonyms for =no.
+Some options are either ignored or useful only when used while running in +etags mode (see -e option). Such options will be noted.
+<options> must precede the <source_file(s)> following the standard POSIX +convention.
+Options taking language names will accept those names in either upper or +lower case. See the --list-languages option for a complete list of the +built-in language names.
+Some options take one-letter flags as parameters (e.g. --kinds-<LANG> option). +Specifying just letters help a user create a complicated command line +quickly. However, a command line including sequences of one-letter flags +becomes difficult to understand.
+Universal Ctags accepts long-name flags in +addition to such one-letter flags. The long-name and one-letter flags can be mixed in an +option parameter by surrounding each long-name by braces. Thus, for an +example, the following three notations for --kinds-C option have +the same meaning:
+
+--kinds-C=+pLl
+--kinds-C=+{prototype}{label}{local}
+--kinds-C=+{prototype}L{local}
+
+Note that braces may be meta characters in your shell. Put +single quotes in such case.
+--list-... options shows one-letter flags and associated long-name flags.
+Universal Ctags introduces many --list-... options that provide +the internal data of Universal Ctags (See "Listing Options"). Both users and client tools may +use the data. --with-list-header and --machinable options +adjust the output of the most of --list-... options.
+The default setting (--with-list-header=yes and --machinable=no) +is for using interactively from a terminal. The header that explains +the meaning of columns is simply added to the output, and each column is +aligned in all lines. The header line starts with a hash ('#') character.
+For scripting in a client tool, --with-list-header=no and +--machinable=yes may be useful. The header is not added to the +output, and each column is separated by tab characters.
+Note the order of columns will change in the future release. +However, labels in the header will not change. So by scanning +the header, a client tool can find the index for the target +column.
+ +ctags has more options than listed here. +Options starting with an underscore character, such as --_echo=<msg>, +are not listed here. They are experimental or for debugging purpose.
+Notation: <foo> is for a variable string foo, [ ... ] for optional, +| for selection, and ( ... ) for grouping. For example +--foo[=(yes|no)]'' means ``--foo, -foo=yes, or -foo=no.
+Add <pattern> to a list of excluded files and directories. This option may +be specified as many times as desired. For each file name considered +by ctags, each pattern specified using this option +will be compared against both the complete path (e.g. +some/path/base.ext) and the base name (e.g. base.ext) of the file, thus +allowing patterns which match a given file name irrespective of its +path, or match only a specific path.
+If appropriate support is available +from the runtime library of your C compiler, then pattern may +contain the usual shell wildcards (not regular expressions) common on +Unix (be sure to quote the option parameter to protect the wildcards from +being expanded by the shell before being passed to ctags; +also be aware that wildcards can match the slash character, '/'). +You can determine if shell wildcards are available on your platform by +examining the output of the --list-features option, which will include +wildcards in the compiled feature list; otherwise, pattern is matched +against file names using a simple textual comparison.
+If <pattern> begins with the character '@', then the rest of the string +is interpreted as a file name from which to read exclusion patterns, +one per line. If pattern is empty, the list of excluded patterns is +cleared.
+Note that at program startup, the default exclude list contains names of +common hidden and system files, patterns for binary files, and directories +for which it is generally not desirable to descend while processing the +--recurse option. To see the list of built-in exclude patterns, use +--list-excludes.
+See also the description for --exclude-exception= option.
+Add <pattern> to a list of included files and directories. The pattern +affects the files and directories that are excluded by the pattern +specified with --exclude= option.
+For an example, you want ctags to ignore all files +under foo directory except foo/main.c, use the following command +line: --exclude=foo/* --exclude-exception=foo/main.c.
+Specifies a <string> to print to standard output following the tags for +each file name parsed when the --filter option is enabled. This may +permit an application reading the output of ctags +to determine when the output for each file is finished.
+Note that if the +file name read is a directory and --recurse is enabled, this string will +be printed only once at the end of all tags found for by descending +the directory. This string will always be separated from the last tag +line for the file by its terminating newline.
+This option is quite esoteric and is empty by default.
+Recurse into directories encountered in the list of supplied files.
+If the list of supplied files is empty and no file list is specified with +the -L option, then the current directory (i.e. '.') is assumed. +Symbolic links are followed by default (See --links option). If you don't like these behaviors, either +explicitly specify the files or pipe the output of find(1) into +"ctags -L -" instead. See, also, the --exclude and +--maxdepth to limit recursion.
+Note: This option is not supported on +all platforms at present. It is available if the output of the --help +option includes this option.
+Read from <file> a list of file names for which tags should be generated.
+If file is specified as '-', then file names are read from standard +input. File names read using this option are processed following file +names appearing on the command line. Options are also accepted in this +input. If this option is specified more than once, only the last will +apply.
+Note: file is read in line-oriented mode, where a new line is +the only delimiter and non-trailing white space is considered significant, +in order that file names containing spaces may be supplied +(however, trailing white space is stripped from lines); this can affect +how options are parsed if included in the input.
+Use the name specified by <tagfile> for the tag file (default is "tags", +or "TAGS" when running in etags mode). If <tagfile> is specified as '-', +then the tags are written to standard output instead.
+ctags +will stubbornly refuse to take orders if tagfile exists and +its first line contains something other than a valid tags line. This +will save your neck if you mistakenly type "ctags -f +*.c", which would otherwise overwrite your first C file with the tags +generated by the rest! It will also refuse to accept a multi-character +file name which begins with a '-' (dash) character, since this most +likely means that you left out the tag file name and this option tried to +grab the next option as the file name. If you really want to name your +output tag file -ugly, specify it as "-f ./-ugly".
+This option must +appear before the first file name. If this option is specified more +than once, only the last will apply.
+Same as --output-format=xref. +Print a tabular, human-readable cross reference (xref) file to standard +output instead of generating a tag file. The information contained in +the output includes: the tag name; the kind of tag; the line number, +file name, and source line (with extra white space condensed) of the +file which defines the tag. No tag file is written and all options +affecting tag file output will be ignored.
+Example applications for this +feature are generating a listing of all functions located in a source +file (e.g. "ctags -x --kinds-c=f file"), or generating +a list of all externally visible global variables located in a source +file (e.g. "ctags -x --kinds-c=v --extras=-F file").
+Specifies the <encoding> of the tags file. +Universal Ctags converts the encoding of input files from the encoding +specified by --input-encoding=<encoding> to this encoding.
+In addition <encoding> is specified at the top the tags file as the +value for the TAG_FILE_ENCODING pseudo-tag. The default value of +<encoding> is UTF-8.
+By default, ctags automatically selects the language +of a source file, ignoring those files whose language cannot be +determined (see "Determining file language"). This option forces the specified +language (case-insensitive; either built-in or user-defined) to be used +for every supplied file instead of automatically selecting the language +based upon its extension.
+In addition, the special value auto indicates +that the language should be automatically selected (which effectively +disables this option).
+Specifies the languages for which tag generation is enabled, with <list> +containing a comma-separated list of language names (case-insensitive; +either built-in or user-defined).
+If the first language of <list> is not +preceded by either a '+' or '-', the current list (the current settings +of enabled/disabled languages managed in ctags internally) +will be cleared before adding or removing the languages in <list>. Until a '-' is +encountered, each language in the <list> will be added to the current list.
+As either the '+' or '-' is encountered in the <list>, the languages +following it are added or removed from the current list, respectively. +Thus, it becomes simple to replace the current list with a new one, or +to add or remove languages from the current list.
+The actual list of +files for which tags will be generated depends upon the language +extension mapping in effect (see the --langmap option). Note that the most of +languages, including user-defined languages, are enabled unless explicitly +disabled using this option. Language names included in list may be any +built-in language or one previously defined with --langdef.
+The default +is all, which is also accepted as a valid argument. See the +--list-languages option for a list of the all (built-in and user-defined) +language names.
+Note --languages= option works cumulative way; the option can be +specified with different arguments multiple times in a command line.
+Adds ('+') or removes ('-') an alias <pattern> to a language specified +with <LANG>. ctags refers to the alias pattern in +"Determining file language" stage.
+The parameter <pattern> is not a list. Use this option multiple +times in a command line to add or remove multiple alias +patterns.
+To restore the default language aliases, specify default.
+Using all for <LANG> has meaning in following two cases:
+Controls how file names are mapped to languages (see the --list-maps +option). Each comma-separated <map> consists of the language name (either +a built-in or user-defined language), a colon, and a list of file +extensions and/or file name patterns. A file extension is specified by +preceding the extension with a period (e.g. .c). A file name pattern +is specified by enclosing the pattern in parentheses (e.g. +([Mm]akefile)).
+If appropriate support is available from the runtime +library of your C compiler, then the file name pattern may contain the usual +shell wildcards common on Unix (be sure to quote the option parameter to +protect the wildcards from being expanded by the shell before being +passed to ctags). You can determine if shell wildcards +are available on your platform by examining the output of the +--list-features option, which will include wildcards in the compiled +feature list; otherwise, the file name patterns are matched against +file names using a simple textual comparison.
+When mapping a file extension with --langmap option, +it will first be unmapped from any other languages. (--map-<LANG> +option provides more fine-grained control.)
+If the first character in a <map> is a plus sign ('+'), then the extensions and +file name patterns in that map will be appended to the current map +for that language; otherwise, the map will replace the current map. +For example, to specify that only files with extensions of .c and .x are +to be treated as C language files, use --langmap=c:.c.x; to also add +files with extensions of .j as Java language files, specify +--langmap=c:.c.x,java:+.j. To map makefiles (e.g. files named either +Makefile, makefile, or having the extension .mak) to a language +called make, specify --langmap=make:([Mm]akefile).mak. To map files +having no extension, specify a period not followed by a non-period +character (e.g. '.', ..x, .x.).
+To clear the mapping for a +particular language (thus inhibiting automatic generation of tags for +that language), specify an empty extension list (e.g. --langmap=fortran:). +To restore the default language mappings for a particular language, +supply the keyword default for the mapping. To specify restore the +default language mappings for all languages, specify --langmap=default.
+Note that file name patterns are tested before file extensions when inferring +the language of a file. This order of Universal Ctags is different from +Exuberant Ctags. See ctags-incompatibilities(7) for the background of +this incompatible change.
+This option provides the way to control mapping(s) of file names to +languages in a more fine-grained way than --langmap option.
+In ctags, more than one language can map to a +file name <pattern> or file <extension> (N:1 map). Alternatively, +--langmap option handle only 1:1 map, only one language +mapping to one file name <pattern> or file <extension>. A typical N:1 +map is seen in C++ and ObjectiveC language; both languages have +a map to .h as a file extension.
+A file extension is specified by preceding the extension with a period (e.g. .c). +A file name pattern is specified by enclosing the pattern in parentheses (e.g. +([Mm]akefile)). A prefixed plus ('+') sign is for adding, and +minus ('-') is for removing. No prefix means replacing the map of <LANG>.
+Unlike --langmap, <extension> (or <pattern>) is not a list. +--map-<LANG> takes one extension (or pattern). However, +the option can be specified with different arguments multiple times +in a command line.
+See "TAG ENTRIES" about fields, kinds, roles, and extras.
+Determines the type of EX command used to locate tags in the source +file. [Ignored in etags mode]
+The valid values for type (either the entire word or the first letter +is accepted) are:
+Use only line numbers in the tag file for locating tags. This has +four advantages:
+However, this option has one significant drawback: changes to the +source files can cause the line numbers recorded in the tag file +to no longer correspond to the lines in the source file, causing +jumps to some tags to miss the target definition by one or more +lines. Basically, this option is best used when the source code +to which it is applied is not subject to change. Selecting this +option type causes the following options to be ignored: -B, -F.
+number type is ignored in Xref and JSON output formats. Use +--_xformat="...%n" for Xref output format, or --fields=+n-P for +JSON output format.
+ +In this mode, patterns are generally used with a few exceptions. +For C, line numbers are used for macro definition tags. For Fortran, line numbers +are used for common blocks because their corresponding source lines +are generally identical, making pattern searches useless +for finding all matches.
+This was the default format generated by the original ctags and is, +therefore, retained as the default for this option.
+Specifies whether to include extra tag entries for certain kinds of +information. See also "Extras" subsection to know what are extras.
+The parameter <flags> is a set of one-letter flags (and/or long-name flags), each +representing one kind of extra tag entry to include in the tag file. +If flags is preceded by either the '+' or '-' character, the effect of +each flag is added to, or removed from, those currently enabled; +otherwise the flags replace any current settings. All entries are +included if '*' is given.
+This --extras= option is for controlling extras common in all +languages (or language-independent extras). Universal Ctags also +supports language-specific extras. (See "Language-specific fields and +extras" about the concept). Use --extras-<LANG>= option for +controlling them.
+Specifies whether to include extra tag entries for certain kinds of +information for language <LANG>. Universal Ctags +introduces language-specific extras. See "Language-specific fields and +extras" about the concept. This option is for controlling them.
+Specifies all as <LANG> to apply the parameter <flags> to all +languages; all extras are enabled with specifying '*' as the +parameter flags. If specifying nothing as the parameter flags +(--extras-all=), all extras are disabled. These two combinations +are useful for testing.
+Check the output of the --list-extras=<LANG> option for the +extras of specific language <LANG>.
+Specifies which language-independent fields are to be included in the tag +entries. Language-independent fields are extension fields which are common +in all languages. See "TAG FILE FORMAT" section, and "Extension fields" +subsection, for details of extension fields.
+The parameter <flags> is a set of one-letter or long-name flags, +each representing one type of extension field to include. +Each flag or group of flags may be preceded by either '+' to add it +to the default set, or '-' to exclude it. In the absence of any +preceding '+' or '-' sign, only those fields explicitly listed in flags +will be included in the output (i.e. overriding the default set). All +fields are included if '*' is given.
+This option is ignored if the +option --format=1 (legacy tag file format) has been specified.
+Use --fields-<LANG>= option for controlling language-specific fields.
+Specifies which language-specific fields are to be included in +the tag entries. Universal Ctags +supports language-specific fields. (See "Language-specific fields and +extras" about the concept).
+Specify all as <LANG> to apply the parameter <flags> to all +languages; all fields are enabled with specifying '*' as the +parameter flags. If specifying nothing as the parameter <flags> +(i.e. --fields-all=), all fields are disabled. These two combinations +are useful for testing.
+See the description of --fields=[+|-][<flags>|*] about <flags>.
+Use --fields= option for controlling language-independent fields.
+Specifies a list of language-specific <kinds> of tags (or kinds) to +include in the output file for a particular language, where <LANG> is +case-insensitive and is one of the built-in language names (see the +--list-languages option for a complete list).
+The parameter <kinds> is a group +of one-letter or long-name flags designating kinds of tags (particular to the language) +to either include or exclude from the output. The specific sets of +flags recognized for each language, their meanings and defaults may be +list using the --list-kinds-full option.
+Each letter or group of letters +may be preceded by either '+' to add it to, or '-' to remove it from, +the default set. In the absence of any preceding '+' or '-' sign, only +those kinds explicitly listed in kinds will be included in the output +(i.e. overriding the default for the specified language).
+Specify '*' as the parameter to include all kinds implemented +in <LANG> in the output. Furthermore if all is given as <LANG>, +specification of the parameter kinds affects all languages defined +in ctags. Giving all makes sense only when '*' or +'F' is given as the parameter kinds.
+As an example for the C language, in order to add prototypes and +external variable declarations to the default set of tag kinds, +but exclude macros, use --kinds-c=+px-d; to include only tags for +functions, use --kinds-c=f.
+Some kinds of C and C++ languages are synchronized; enabling +(or disabling) a kind in one language enables the kind having +the same one-letter and long-name in the other language. See also the +description of MASTER column of --list-kinds-full.
+Truncate patterns of tag entries after <N> characters. Disable by setting to 0 +(default is 96).
+An input source file with long lines and multiple tag matches per +line can generate an excessively large tags file with an +unconstrained pattern length. For example, running ctags on a +minified JavaScript source file often exhibits this behavior.
+The truncation avoids cutting in the middle of a UTF-8 code point +spanning multiple bytes to prevent writing invalid byte sequences from +valid input files. This handling allows for an extra 3 bytes above the +configured limit in the worse case of a 4 byte code point starting +right before the limit. Please also note that this handling is fairly +naive and fast, and although it is resistant against any input, it +requires a valid input to work properly; it is not guaranteed to work +as the user expects when dealing with partially invalid UTF-8 input. +This also partially affect non-UTF-8 input, if the byte sequence at +the truncation length looks like a multibyte UTF-8 sequence. This +should however be rare, and in the worse case will lead to including +up to an extra 3 bytes above the limit.
+Put UCTAGS as prefix for the name of fields newly introduced in +Universal Ctags.
+Some fields are newly introduced in Universal Ctags and more will +be introduced in the future. Other tags generators may also +introduce their specific fields.
+In such a situation, there is a concern about conflicting field +names; mixing tags files generated by multiple tags generators +including Universal Ctags is difficult. This option provides a +workaround for such station.
++$ ctags --fields='{line}{end}' -o - hello.c +main hello.c /^main(int argc, char **argv)$/;" f line:3 end:6 +$ ctags --put-field-prefix --fields='{line}{end}' -o - hello.c +main hello.c /^main(int argc, char **argv)$/;" f line:3 UCTAGSend:6 ++
In the above example, the prefix is put to end field which is +newly introduced in Universal Ctags.
+Specifies a list of kind-specific roles of tags to include in the +output file for a particular language. +<kind> specifies the kind where the <roles> are defined. +<LANG> specifies the language where the kind is defined. +Each role in <roles> must be surrounded by braces (e.g. {system} +for a role named "system").
+Like --kinds-<LANG> option, '+' is for adding the role to the +list, and '-' is for removing from the list. '*' is for including +all roles of the kind to the list. The option with no argument +makes the list empty.
+Both a one-letter flag or a long name flag surrounded by braces are +acceptable for specifying a kind (e.g. --roles-C.h=+{system}{local} +or --roles-C.{header}=+{system}{local}). '*' can be used for <KIND> +only for adding/removing all roles of all kinds in a language to/from +the list (e.g. --roles-C.*=* or --roles-C.*=).
+all can be used for <LANG> only for adding/removing all roles of +all kinds in all languages to/from the list +(e.g. --roles-all.*=* or --roles-all.*=).
+Specifies how the file paths recorded in the tag file. +The default is yes when running in etags mode (see +the -e option), no otherwise.
+Uses slash ('/') character as filename separators instead of backslash +('\') character when printing input: field. +The default is yes for the default "u-ctags" output format, and +no for the other formats.
+This option is available on MS Windows only.
+Read additional options from file or directory.
+ctags searches <pathname> in the optlib path list +first. If ctags cannot find a file or directory +in the list, ctags reads a file or directory +at the specified <pathname>.
+If a file is specified, it should contain one option per line. If +a directory is specified, files suffixed with .ctags under it +are read in alphabetical order.
+As a special case, if --options=NONE is specified as the first +option on the command line, preloading is disabled; the option +will disable the automatic reading of any configuration options +from a file (see "FILES").
+See ctags-optlib(7) for details of each option.
+Indicates a preference as to whether code within an "#if 0" branch of a +preprocessor conditional should be examined for non-macro tags (macro +tags are always included). Because the intent of this construct is to +disable code, the default value of this option is no (disabled).
+Note that this +indicates a preference only and does not guarantee skipping code within +an "#if 0" branch, since the fall-back algorithm used to generate +tags when preprocessor conditionals are too complex follows all branches +of a conditional.
+Specifies whether #line directives should be recognized. These are +present in the output of a preprocessor and contain the line number, and +possibly the file name, of the original source file(s) from which the +preprocessor output file was generated. This option is off by default.
+When enabled, this option will +cause ctags to generate tag entries marked with the +file names and line numbers of their locations original source file(s), +instead of their actual locations in the preprocessor output. The actual +file names placed into the tag file will have the same leading path +components as the preprocessor output file, since it is assumed that +the original source files are located relative to the preprocessor +output file (unless, of course, the #line directive specifies an +absolute path).
+Note: This option is generally +only useful when used together with the --excmd=number (-n) option. +Also, you may have to use either the --langmap or --language-force option +if the extension of the preprocessor output file is not known to +ctags.
+Specifies a <list> of file extensions, separated by periods, which are +to be interpreted as include (or header) files. To indicate files having +no extension, use a period not followed by a non-period character +(e.g. '.', ..x, .x.).
+This option only affects how the scoping of +particular kinds of tags are interpreted (i.e. whether or not they are +considered as globally visible or visible only within the file in which +they are defined); it does not map the extension to any particular +language. Any tag which is located in a non-include file and cannot be +seen (e.g. linked to) from another file is considered to have file-limited +(e.g. static) scope. No kind of tag appearing in an include file +will be considered to have file-limited scope.
+If the first character in the list is '+', then the extensions in the list will be +appended to the current list; otherwise, the list will replace the +current list. See, also, the fileScope/F flag of --extras option.
+The default list is +.h.H.hh.hpp.hxx.h++.inc.def. To restore the default list, specify "-h +default".
+Note that if an extension supplied to this option is not +already mapped to a particular language (see "Determining file language", above), +you will also need to use either the --map-<LANG>, --langmap or +--language-force option.
+Specifies a <identifier-list> of identifiers which are to be specially handled while +parsing C and C++ source files. This option is specifically provided +to handle special cases arising through the use of preprocessor macros. +When the identifiers listed are simple identifiers, these identifiers +will be ignored during parsing of the source files.
+If an identifier is +suffixed with a '+' character (i.e. "-I FOO+"), ctags will also +ignore any parenthesis-enclosed argument list which may immediately +follow the identifier in the source files. See the example of "-I +MODULE_VERSION+" below.
+If two identifiers are +separated with the '=' character (i.e. -I FOO=BAR), the first identifiers is replaced by +the second identifiers for parsing purposes. The list of identifiers may +be supplied directly on the command line or read in from a separate file. +See the example of "-I CLASS=class" below.
+If the first character of <identifier-list> is '@', '.' or a pathname +separator ('/' or '\'), or the first two characters specify a drive +letter (e.g. C:), the parameter <identifier-list> will be interpreted as +a filename from which to read a list of identifiers, one per input line.
+Otherwise, <identifier-list> is a list of identifiers (or identifier +pairs) to be specially handled, each delimited by either a comma or +by white space (in which case the list should be quoted to keep the +entire list as one command line argument).
+Multiple -I options may be +supplied. To clear the list of ignore identifiers, supply a single +dash ('-') for <identifier-list>.
+This feature is useful when preprocessor macros are used in such a way +that they cause syntactic confusion due to their presence. Indeed, +this is the best way of working around a number of problems caused by +the presence of syntax-busting macros in source files (see "CAVEATS"). +Some examples will illustrate this point.
++int foo ARGDECL4(void *, ptr, long int, nbytes) ++
In the above example, the macro ARGDECL4 would be mistakenly +interpreted to be the name of the function instead of the correct name +of foo. Specifying "-I ARGDECL4" results in the correct behavior.
++/* creates an RCS version string in module */ +MODULE_VERSION("$Revision$") ++
In the above example the macro invocation looks too much like a function +definition because it is not followed by a semicolon (indeed, it +could even be followed by a global variable definition that would look +much like a K&R style function parameter declaration). In fact, this +seeming function definition could possibly even cause the rest of the +file to be skipped over while trying to complete the definition. +Specifying "-I MODULE_VERSION+" would avoid such a problem.
++CLASS Example { + // your content here +}; ++
The example above uses CLASS as a preprocessor macro which expands to +something different for each platform. For instance CLASS may be +defined as class __declspec(dllexport) on Win32 platforms and simply +class on UNIX. Normally, the absence of the C++ keyword class +would cause the source file to be incorrectly parsed. Correct behavior +can be restored by specifying "-I CLASS=class".
+Set a <LANG> specific parameter, a parameter specific to the <LANG>.
+Available parameters can be listed with --list-params.
+Lists the extras recognized for either the specified <language> or +all languages. See "Extras" subsection to know what are extras. +all is used as default value if the option argument is omitted.
+An extra can be enabled or disabled with --extras= for common +extras in all languages, or --extras-<LANG>= for the specified +language. These option takes one-letter flag or long-name flag as a parameter +for specifying an extra.
+The meaning of columns in output are as follows:
+Lists the fields recognized for either the specified <language> or +all languages. See "Extension fields" subsection to know what are fields. +all is used as default value if the option argument is omitted.
+The meaning of columns are as follows:
+Whether this field can be disabled or not in tags output.
+Some fields are printed always in tags output. +They have yes as the value for this column.
+Unlike the tag output mode, JSON output mode allows disabling +any fields.
+Subset of --list-kinds-full. This option is kept for +backward-compatibility with Exuberant Ctags.
+This option prints only LETTER, DESCRIPTION, and ENABLED fields +of --list-kinds-full output. However, the presentation of +ENABLED column is different from that of --list-kinds-full +option; [off] follows after description if the kind is disabled, +and nothing follows if enabled. The most of all kinds are enabled +by default.
+The critical weakness of this option is that this option does not +print the name of kind. Universal Ctags introduces +--list-kinds-full because it considers that names are +important.
+This option does not work with --machinable nor +--with-list-header.
+Lists the tag kinds recognized for either the specified <language> +or all languages, and then exits. See "Kinds" subsection to +learn what kinds are. +all is used as default value if the option argument is omitted.
+Each kind of tag recorded in the tag file is represented by a +one-letter flag, or a long-name flag. They are also used to filter the tags +placed into the output through use of the --kinds-<LANG> +option.
+The meaning of columns are as follows:
+The master parser controlling enablement of the kind. +A kind belongs to a language (owner) in Universal Ctags; +enabling and disabling a kind in a language has no effect on +a kind in another language even if both kinds has the +same one-letter flag and/or the same long-name flag. In other words, +the namespace of kinds are separated by language.
+However, Exuberant Ctags does not separate the kinds of C and +C++. Enabling/disabling kindX in C language enables/disables a +kind in C++ language having the same long-name flag with kindX. To +emulate this behavior in Universal Ctags, a concept named +master parser is introduced. Enabling/disabling some kinds +are synchronized under the control of a master language.
++$ ctags --kinds-C=+'{local}' --list-kinds-full \ + | grep -E '^(#|C\+\+ .* local)' +#LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +C++ l local yes no 0 C local variables +$ ctags --kinds-C=-'{local}' --list-kinds-full \ + | grep -E '^(#|C\+\+ .* local)' +#LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +C++ l local no no 0 C local variables ++
You see ENABLED field of local kind of C++ language is changed +Though local kind of C language is enabled/disabled. If you swap the languages, you +see the same result.
+ +Lists the names of the languages understood by ctags, +and then exits. These language names are case insensitive and may be +used in many other options like --language-force, +--languages, --kinds-<LANG>, --regex-<LANG>, and so on.
+Each language listed is disabled if followed by [disabled]. +To use the parser for such a language, specify the language as an +argument of --languages=+ option.
+--machinable and --with-list-header options are ignored if they are +specified with this option.
+Lists file name patterns and the file extensions which associate a file +name with a language for either the specified <language> or all +languages, and then exits. +all is used as default value if the option argument is omitted.
+To list the file extensions or file name patterns individually, use +--list-map-extensions or --list-map-patterns option. +See the --langmap option, and "Determining file language", above.
+This option does not work with --machinable nor +--with-list-header.
+List the roles for either the specified <language> or all languages. +all is used as default value if the option argument is omitted.
+If the parameter <kindspecs> is given after the parameter +<language> or all with concatenating with '.', list only roles +defined in the kinds. Both one-letter flags and long name flags surrounded +by braces are acceptable as the parameter <kindspecs>.
+The meaning of columns are as follows:
+Prints statistics about the source files read and the tag file written +during the current invocation of ctags. This option +is no by default.
+The extra value prints parser specific statistics for parsers +gathering such information.
+These options are kept for backward-compatibility with Exuberant Ctags.
+As ctags considers each source file name in turn, it tries to +determine the language of the file by applying tests described in +"Determining file language".
+If a language was identified, the file is opened and then the appropriate +language parser is called to operate on the currently open file. The parser +parses through the file and adds an entry to the tag file for each +language object it is written to handle. See "TAG FILE FORMAT", below, +for details on these entries.
+This implementation of ctags imposes no formatting +requirements on C code as do legacy implementations. Older implementations +of ctags tended to rely upon certain formatting assumptions in order to +help it resolve coding dilemmas caused by preprocessor conditionals.
+In general, ctags tries to be smart about conditional +preprocessor directives. If a preprocessor conditional is encountered +within a statement which defines a tag, ctags follows +only the first branch of that conditional (except in the special case of +#if 0, in which case it follows only the last branch). The reason for +this is that failing to pursue only one branch can result in ambiguous +syntax, as in the following example:
++#ifdef TWO_ALTERNATIVES +struct { +#else +union { +#endif + short a; + long b; +} ++
Both branches cannot be followed, or braces become unbalanced and +ctags would be unable to make sense of the syntax.
+If the application of this heuristic fails to properly parse a file, +generally due to complicated and inconsistent pairing within the +conditionals, ctags will retry the file using a +different heuristic which does not selectively follow conditional +preprocessor branches, but instead falls back to relying upon a closing +brace ('}') in column 1 as indicating the end of a block once any brace +imbalance results from following a #if conditional branch.
+ctags will also try to specially handle arguments lists +enclosed in double sets of parentheses in order to accept the following +conditional construct:
++extern void foo __ARGS((int one, char two)); ++
Any name immediately preceding the '((' will be automatically ignored and +the previous name will be used.
+C++ operator definitions are specially handled. In order for consistency +with all types of operators (overloaded and conversion), the operator +name in the tag file will always be preceded by the string "operator " +(i.e. even if the actual operator definition was written as "operator<<").
+After creating or appending to the tag file, it is sorted by the tag name, +removing identical tag lines.
+Unless the --language-force option is specified, the language of each source +file is automatically selected based upon a mapping of file names to +languages. The mappings in effect for each language may be displayed using +the --list-maps option and may be changed using the --langmap or +--map-<LANG> options.
+If the name of a file is not mapped to a language, ctags tries +to heuristically guess the language for the file by inspecting its content.
+All files that have no file name mapping and no guessed parser are +ignored. This permits running ctags on all files in +either a single directory (e.g. "ctags *"), or on +all files in an entire source directory tree +(e.g. "ctags -R"), since only those files whose +names are mapped to languages will be scanned.
+An extension may be mapped to multiple parsers. For example, .h +are mapped to C++, C and ObjectiveC. These mappings can cause +issues. ctags tries to select the proper parser +for the source file by applying heuristics to its content, however +it is not perfect. In case of issues one can use --language-force=<language>, +--langmap=<map>[,<map>[...]], or the --map-<LANG>=[+|-]<extension>|<pattern> +options. (Some of the heuristics are applied whether --guess-language-eagerly +is given or not.)
+ +If ctags cannot select a parser from the mapping of file names, +various heuristic tests are conducted to determine the language:
+The first line of the file is checked to see if the file is a #! +script for a recognized language. ctags looks for +a parser having the same name.
+If ctags finds no such parser, +ctags looks for the name in alias lists. For +example, consider if the first line is #!/bin/sh. Though +ctags has a "shell" parser, it doesn't have a "sh" +parser. However, sh is listed as an alias for shell, therefore +ctags selects the "shell" parser for the file.
+An exception is env. If env is specified (for example +"#!/usr/bin/env python"), ctags +reads more lines to find real interpreter specification.
+To display the list of aliases, use --list-aliases option. +To add an item to the list or to remove an item from the list, use the +--alias-<LANG>=+<pattern> or --alias-<LANG>=-<pattern> option +respectively.
+The Emacs editor has multiple editing modes specialized for programming +languages. Emacs can recognize a marker called modeline in a file +and utilize the marker for the mode selection. This heuristic test does +the same as what Emacs does.
+ctags treats MODE as a name of interpreter and applies the same +rule of "interpreter" testing if the first line has one of +the following patterns:
++-*- mode: MODE -*- ++
or
++-*- MODE -*- ++
Emacs editor recognizes another marker at the end of file as a +mode specifier. This heuristic test does the same as what Emacs does.
+ctags treats MODE as a name of an interpreter and applies the same +rule of "interpreter" heuristic testing, if the lines at the tail of the file +have the following pattern:
++Local Variables: +... +mode: MODE +... +End: ++
3000 characters are sought from the end of file to find the pattern.
+Like the modeline of the Emacs editor, Vim editor has the same concept. +ctags treats TYPE as a name of interpreter and applies the same +rule of "interpreter" heuristic testing if the last 5 lines of the file +have one of the following patterns:
++filetype=TYPE ++
or
++ft=TYPE ++
Looking into the file contents is a more expensive operation than file +name matching. So ctags runs the testings in limited +conditions. "interpreter" testing is enabled only when a file is an +executable or the --guess-language-eagerly (-G in short) option is +given. The other heuristic tests are enabled only when -G option is +given.
+The --print-language option can be used just to print the results of +parser selections for given files instead of generating a tags file.
+Examples:
++$ ctags --print-language config.h.in input.m input.unknown +config.h.in: C++ +input.m: MatLab +input.unknown: NONE ++
NONE means that ctags does not select any parser for the file.
+This section describes the tag file format briefly. See tags(5) and +ctags-client-tools(7) for more details.
+When not running in etags mode, each entry in the tag file consists of a +separate line, each looking like this, called regular tags, in the most general case:
++<tag_name><TAB><file_name><TAB><ex_cmd>;"<TAB><extension_fields> ++
The fields and separators of these lines are specified as follows:
++++
+- +
<tag_name>: tag name
+- +
<TAB>: single tab character
+- +
<file_name>: name of the file in which the object associated with the tag is located
+- +
<TAB>: single tab character
+- +
<ex_cmd>: EX command used to locate the tag within the file; generally a +search pattern (either /pattern/ or ?pattern?) or line number (see +--excmd=<type> option).
+- +
;"<TAB><extension_fields>: a set of extension fields. See +"Extension fields" for more details.
+Tag file format 2 (see --format) extends the EX command +to include the extension fields embedded in an EX comment immediately appended +to the EX command, which leaves it backward-compatible with original +vi(1) implementations.
+
A few special tags, called pseudo tags, are written into the tag file for internal purposes.
++!_TAG_FILE_FORMAT 2 /extended format; --format=1 will not append ;" to lines/ +!_TAG_FILE_SORTED 1 /0=unsorted, 1=sorted, 2=foldcase/ +... ++
--pseudo-tags=[+|-](<pseudo-tag>|*) option enables or disables emitting pseudo-tags.
+See the output of "ctags --list-pseudo-tags" for the list of +the kinds. +See also tags(5) and ctags-client-tools(7) for more details of the pseudo tags.
+These tags are composed in such a way that they always sort to the top of +the file. Therefore, the first two characters of these tags are used a magic +number to detect a tag file for purposes of determining whether a +valid tag file is being overwritten rather than a source file.
+Note that the name of each source file will be recorded in the tag file +exactly as it appears on the command line. Therefore, if the path you +specified on the command line was relative to the current directory, then +it will be recorded in that same manner in the tag file. See, however, +the --tag-relative=(yes|no|always|never) option for how this behavior can be +modified.
+A tag is an index for a language object. The concept of a tag and related +items in Exuberant Ctags are refined and extended in Universal Ctags.
+A tag is categorized into definition tags or reference tags. +In general, Exuberant Ctags only tags definitions of +language objects: places where newly named language objects are introduced. +Universal Ctags, on the other hand, can also tag references of language +objects: places where named language objects are used. However, support +for generating reference tags is new and limited to specific areas of +specific languages in the current version.
+A tag can record various information, called extension fields.
+Extension fields are tab-separated key-value pairs appended to the end of +the EX command as a comment, as described above. These key value pairs +appear in the general form key:value.
+In addition, information on the scope of the tag definition may be +available, with the key portion equal to some language-dependent construct +name and its value the name declared for that construct in the program. +This scope entry indicates the scope in which the tag was found. +For example, a tag generated for a C structure member would have a scope +looking like struct:myStruct.
+--fields=[+|-][<flags>|*] and --fields-(<LANG>|all)=[+|-][<flags>|*] options specifies +which available extension fields are to be included in the tag entries.
+See the output of "ctags --list-fields" for the list of +extension fields. +The essential fields are name, input, pattern, and line. +The meaning of major fields is as follows (long-name flag/one-letter flag):
+kind is a field which represents the kind of language object +specified by a tag. Kinds used and defined are very different between +parsers. For example, C language defines macro, function, +variable, typedef, etc.
+--kinds-(<LANG>|all)=[+|-](<kinds>|*) option specifies a list of language-specific +kinds of tags (or kinds) to include in the output file for a particular +language.
+See the output of "ctags --list-kinds-full" for the complete +list of the kinds.
+Its value is either one of the +corresponding one-letter flags or a long-name flag. It is permitted +(and is, in fact, the default) for the key portion of this field to be +omitted. The optional behaviors are controlled with the --fields option as follows.
++$ ctags -o - kinds.c +foo kinds.c /^int foo() {$/;" f typeref:typename:int +$ ctags --fields=+k -o - kinds.c +foo kinds.c /^int foo() {$/;" f typeref:typename:int +$ ctags --fields=+K -o - kinds.c +foo kinds.c /^int foo() {$/;" function typeref:typename:int +$ ctags --fields=+z -o - kinds.c +foo kinds.c /^int foo() {$/;" kind:f typeref:typename:int +$ ctags --fields=+zK -o - kinds.c +foo kinds.c /^int foo() {$/;" kind:function typeref:typename:int ++
Role is a newly introduced concept in Universal Ctags. Role is a +concept associated with reference tags, and is not implemented widely yet.
+As described previously in "Kinds", the kind field represents the type +of language object specified with a tag, such as a function vs. a variable. +Specific kinds are defined for reference tags, such as the C++ kind header for +header file, or Java kind package for package statements. For such reference +kinds, a roles field can be added to distinguish the role of the reference +kind. In other words, the kind field identifies the what of the language +object, whereas the roles field identifies the how of a referenced language +object. Roles are only used with specific kinds.
+For a definition tag, this field takes def as a value.
+For example, Baz is tagged as a reference tag with kind package and with +role imported with the following code.
++package Bar; +import Baz; + +class Foo { + // ... +} ++
+$ ctags --fields=+KEr -uo - roles.java +Bar roles.java /^package Bar;$/;" package roles:def +Foo roles.java /^class Foo {$/;" class roles:def +$ ctags --fields=+EKr --extras=+r -uo - roles.java +Bar roles.java /^package Bar;$/;" package roles:def +Baz roles.java /^import Baz;$/;" package roles:imported extras:reference +Foo roles.java /^class Foo {$/;" class roles:def ++
--roles-(<LANG>|all).(<kind>|all)=[+|-][<roles>|*] option specifies a list of kind-specific +roles of tags to include in the output file for a particular language.
+Inquire the output of "ctags --list-roles" for the list of +roles.
+Generally, ctags tags only language objects appearing +in source files, as is. In other words, a value for a name: field +should be found on the source file associated with the name:. An +extra type tag (extra) is for tagging a language object with a processed +name, or for tagging something not associated with a language object. A typical +extra tag is qualified, which tags a language object with a +class-qualified or scope-qualified name.
+--extras-(<LANG>|all)=[+|-][<flags>|*] option specifies +whether to include extra tag entries for certain kinds of information.
+Inquire the output of ctags --list-extras for the list of extras. +The meaning of major extras is as follows (long-name flag/one-letter flag):
+Include an entry for the language object that has no name like lambda +function. This extra has no one-letter flag and is enabled by +default.
+The extra tag is useful as a placeholder to fill scope fields +for language objects defined in a language object with no name.
++struct { + double x, y; +} p = { .x = 0.0, .y = 0.0 }; ++
'x' and 'y' are the members of a structure. When filling the scope +fields for them, ctags has trouble because the struct +where 'x' and 'y' belong to has no name. For overcoming the trouble, +ctags generates an anonymous extra tag for the struct +and fills the scope fields with the name of the extra tag.
++$ ctags --fields=-f -uo - input.c +__anon9f26d2460108 input.c /^struct {$/;" s +x input.c /^ double x, y;$/;" m struct:__anon9f26d2460108 +y input.c /^ double x, y;$/;" m struct:__anon9f26d2460108 +p input.c /^} p = { .x = 0.0, .y = 0.0 };$/;" v typeref:struct:__anon9f26d2460108 ++
The above tag output has __anon9f26d2460108 as an anonymous extra tag. +The typeref field of 'p' also receives the benefit of it.
+Indicates whether tags scoped only for a single file (i.e. tags which +cannot be seen outside of the file in which they are defined, such as +language objects with static modifier of C language) should be included +in the output. See also the -h option.
+This extra tag is enabled by default. Add --extras=-F option not to +output tags scoped only for a single-file. This is the replacement for +--file-scope option of Exuberant Ctags.
++static int f() { + return 0; +} +int g() { + return 0; +} ++
+$ ctags -uo - filescope.c +f filescope.c /^static int f() {$/;" f typeref:typename:int file: +g filescope.c /^int g() {$/;" f typeref:typename:int +$ ctags --extras=-F -uo - filescope.c +g filescope.c /^int g() {$/;" f typeref:typename:int ++
Include an entry for the base file name of every source file +(e.g. example.c), which addresses the first line of the file. +This flag is the replacement for --file-tags hidden option of +Exuberant Ctags.
+If the end: field is enabled, the end line number of the file can be +attached to the tag. (However, ctags omits the end: field +if no newline is in the file like an empty file.)
+By default, ctags doesn't create the inputFile/f extra +tag for the source file when ctags doesn't find a parser +for it. Enabling Unknown parser with --languages=+Unknown forces +ctags to create the extra tags for any source files.
+The etags mode enables the Unknown parser implicitly.
+Include an extra class-qualified or namespace-qualified tag entry +for each tag which is a member of a class or a namespace.
+This may allow easier location of a specific tags when +multiple occurrences of a tag name occur in the tag file. +Note, however, that this could potentially more than double +the size of the tag file.
+The actual form of the qualified tag depends upon the language +from which the tag was derived (using a form that is most +natural for how qualified calls are specified in the +language). For C++ and Perl, it is in the form +class::member; for Eiffel and Java, it is in the form +class.member.
+Note: Using backslash characters as separators forming +qualified name in PHP. However, in tags output of +Universal Ctags, a backslash character in a name is escaped +with a backslash character. See tags(5) about the escaping.
+The following example demonstrates the qualified extra tag.
++class point { + double x; +}; ++
For the above source file, ctags tags point and x by +default. If the qualified extra is enabled from the command line +(--extras=+q), then point.x is also tagged even though the string +"point.x" is not in the source code.
++$ ctags --fields=+K -uo - qualified.java +point qualified.java /^class point {$/;" class +x qualified.java /^ double x;$/;" field class:point +$ ctags --fields=+K --extras=+q -uo - qualified.java +point qualified.java /^class point {$/;" class +x qualified.java /^ double x;$/;" field class:point +point.x qualified.java /^ double x;$/;" field class:point ++
Include reference tags. See "TAG ENTRIES" about reference tags.
+The following example demonstrates the reference extra tag.
++#include <stdio.h> +#include "utils.h" +#define X +#undef X ++
The roles:system or roles:local fields will be +added depending on whether the include file name begins with '<' or not.
+"#define X" emits a definition tag. On the other hand "#undef X" emits a +reference tag.
++$ ctags --fields=+EKr -uo - inc.c +X inc.c /^#define X$/;" macro file: roles:def extras:fileScope +$ ctags --fields=+EKr --extras=+r -uo - inc.c +stdio.h inc.c /^#include <stdio.h>/;" header roles:system extras:reference +utils.h inc.c /^#include "utils.h"/;" header roles:local extras:reference +X inc.c /^#define X$/;" macro file: roles:def extras:fileScope +X inc.c /^#undef X$/;" macro file: roles:undef extras:fileScope,reference ++
Exuberant Ctags has the concept of fields and extras. They are common +between parsers of different languages. Universal Ctags extends this concept +by providing language-specific fields and extras.
+ + +vi(1) will, by default, expect a tag file by the name tags in the current +directory. Once the tag file is built, the following commands exercise +the tag indexing feature:
+emacs(1) will, by default, expect a tag file by the name TAGS in the +current directory. Once the tag file is built, the following commands +exercise the tag indexing feature:
+For more commands, see the Tags topic in the Emacs info document.
+NEdit version 5.1 and later can handle the new extended tag file format +(see --format).
+NEdit 5.1 can read multiple tag files from different +directories. Setting the X resource nedit.tagFile to the name of a tag +file instructs NEdit to automatically load that tag file at startup time.
+Because ctags is neither a preprocessor nor a compiler, +use of preprocessor macros can fool ctags into either +missing tags or improperly generating inappropriate tags. Although +ctags has been designed to handle certain common cases, +this is the single biggest cause of reported problems. In particular, +the use of preprocessor constructs which alter the textual syntax of C +can fool ctags. You can work around many such problems +by using the -I option.
+Note that since ctags generates patterns for locating +tags (see the --excmd option), it is entirely possible that the wrong line +may be found by your editor if there exists another source line which is +identical to the line containing the tag. The following example +demonstrates this condition:
++int variable; + +/* ... */ +void foo(variable) +int variable; +{ + /* ... */ +} ++
Depending upon which editor you use and where in the code you happen to be, +it is possible that the search pattern may locate the local parameter +declaration before it finds the actual global variable definition, +since the lines (and therefore their search patterns) are +identical.
+This can be avoided by use of the --excmd=n option.
+ctags has more options than ls(1).
+ctags assumes the input file is written in the correct +grammar. Otherwise output of ctags is undefined. In other words it has garbage +in, garbage out (GIGO) feature.
+ +When parsing a C++ member function definition (e.g. className::function), +ctags cannot determine whether the scope specifier +is a class name or a namespace specifier and always lists it as a class name +in the scope portion of the extension fields. Also, if a C++ function +is defined outside of the class declaration (the usual case), the access +specification (i.e. public, protected, or private) and implementation +information (e.g. virtual, pure virtual) contained in the function +declaration are not known when the tag is generated for the function +definition. It will, however be available for prototypes (e.g. --kinds-c++=+p).
+No qualified tags are generated for language objects inherited into a class.
+On Unix-like hosts where mkstemp(3) is available, the value of this +variable specifies the directory in which to place temporary files. +This can be useful if the size of a temporary file becomes too large +to fit on the partition holding the default temporary directory +defined at compilation time.
+ctags creates temporary +files only if either (1) an emacs-style tag file is being +generated, (2) the tag file is being sent to standard output, or +(3) the program was compiled to use an internal sort algorithm to sort +the tag files instead of the sort(1) utility of the operating system. +If the sort(1) utility of the operating system is being used, it will +generally observe this variable also.
+Note that if ctags +is setuid, the value of TMPDIR will be ignored.
+$XDG_CONFIG_HOME/ctags/*.ctags, or $HOME/.config/ctags/*.ctags if +$XDG_CONFIG_HOME is not defined +(on other than MS Windows)
+$HOME/.ctags.d/*.ctags
+$HOMEDRIVE$HOMEPATH/ctags.d/*.ctags (on MS Windows only)
+.ctags.d/*.ctags
+ctags.d/*.ctags
+++If any of these configuration files exist, each will be expected to +contain a set of default options which are read in the order listed +when ctags starts, but before any command line options +are read. This makes it possible to set up personal or project-level defaults.
+It +is possible to compile ctags to read an additional +configuration file before any of those shown above, which will be +indicated if the output produced by the --version option lists the +custom-conf feature.
+Options appearing on the command line will override options +specified in these files. Only options will be read from these +files.
+Note that the option +files are read in line-oriented mode in which spaces are significant +(since shell quoting is not possible) but spaces at the beginning +of a line are ignored. Each line of the file is read as +one command line parameter (as if it were quoted with single quotes). +Therefore, use new lines to indicate separate command-line arguments.
+A line starting with '#' is treated as a comment.
+*.ctags files in a directory are loaded in alphabetical order.
+
See ctags-optlib(7) for defining (or extending) a parser +in a configuration file.
+See tags(5) for the format of tag files.
+See ctags-incompatibilities(7) about known incompatible changes +with Exuberant Ctags.
+See ctags-client-tools(7) if you are interested in writing +a tool for processing tags files.
+See ctags-lang-python(7) about python input specific notes.
+See readtags(1) about a client tool for binary searching a +name in a sorted tags file.
+The official Universal Ctags web site at: https://ctags.io/
+Also ex(1), vi(1), elvis(1), or, better yet, vim(1), the official editor of ctags. +For more information on vim(1), see the Vim web site at: https://www.vim.org/
+Universal Ctags project +https://ctags.io/
+Darren Hiebert <dhiebert@users.sourceforge.net> +http://DarrenHiebert.com/
+"Think ye at all times of rendering some service to every member of the +human race."
+"All effort and exertion put forth by man from the fullness of his heart is +worship, if it is prompted by the highest motives and the will to do +service to humanity."
+-- From the Baha'i Writings
+This version of ctags (Universal Ctags) derived from +the repository, known as fishman-ctags, started by Reza Jelveh.
+The fishman-ctags was derived from Exuberant Ctags.
+Some parsers are taken from tagmanager of the Geany (https://www.geany.org/) +project.
+Exuberant Ctags was originally derived from and +inspired by the ctags program by Steve Kirkendall <kirkenda@cs.pdx.edu> +that comes with the Elvis vi clone (though virtually none of the original +code remains).
+Credit is also due Bram Moolenaar <Bram@vim.org>, the author of vim, +who has devoted so much of his time and energy both to developing the editor +as a service to others, and to helping the orphans of Uganda.
+The section entitled "HOW TO USE WITH GNU EMACS" was shamelessly stolen +from the info page for GNU etags.
+| Version: | +5.9.0 |
|---|---|
| Manual group: | Universal Ctags | +
| Manual section: | 1 | +
The readtags program filters, sorts and prints tag entries in a tags file. +The basic filtering is done using actions, by which you can list all +regular tags, pseudo tags or regular tags matching specific name. Then, further +filtering and sorting can be done using post processors, namely filter +expressions and sorter expressions.
+The behavior of reading tags can be controlled using these options:
+The NAME action will perform binary search on sorted (including "foldcase") +tags files, which is much faster then on unsorted tags files.
+The behavior of the NAME action can be controlled using these options:
+By default, the output of readtags contains only the name, input and pattern +field. The Output can be tweaked using these options:
+About the -E option: certain characters are escaped in a tags file, to make +it machine-readable. e.g., ensuring no tabs character appear in fields other +than the pattern field. By default, readtags translates them to make it +human-readable, but when utilizing readtags output in a script or a client +tool, -E option should be used. See ctags-client-tools(7) for more +discussion on this.
+Further filtering and sorting on the tags listed by actions are performed using:
+These are discussed in the EXPRESSION section.
+List all tags in "/path/to/tags":
+
+$ readtags -t /path/to/tags -l
+
+List all tags in "tags" that start with "mymethod":
+
+$ readtags -p - mymethod
+
+List all tags matching "mymethod", case insensitively:
+
+$ readtags -i - mymethod
+
+List all tags start with "myvar", and printing all fields (i.e., the whole line):
+
+$ readtags -p -ne - myvar
+
+Scheme-style expressions are used for the -Q and -S options. For those +who doesn't know Scheme or Lisp, just remember:
+So, (+ 1 (+ 2 3)) means add 2 and 3 first, then add the result with 1. +(and "string" 1 #t) means logical AND on "string", 1 and #t, +and the result is true since there is no #f.
+The tag entries that make the filter expression produces true value are printed +by readtags.
+The basic operators for filtering are eq?, prefix?, suffix?, +substr?, and #/PATTERN/. Language common fields can be accessed using +variables starting with $, e.g., $language represents the language field. +For example:
+List all tags start with "myfunc" in Python code files:
++$ readtags -p -Q '(eq? $language "Python")' - myfunc ++
downcase or upcase operators can be used to perform case-insensitive +matching:
+List all tags containing "my", case insensitively:
++++$ readtags -Q '(substr? (downcase $name) "my")' -l ++
We have logical operators like and, or and not. The value of a +missing field is #f, so we could deal with missing fields:
+List all tags containing "impl" in Python code files, but allow the +language: field to be missing:
++$ readtags -Q '(and (substr? $name "impl")\ + (or (not $language)\ + (eq? $language "Python")))' -l ++
#/PATTERN/ is for the case when string predicates (prefix?, suffix?, +and substr?) are not enough. You can use "Posix extended regular expression" +as PATTERN.
+List all tags inherits from the class "A":
++$ readtags -Q '(#/(^|,) ?A(,|$)/ $inherits)' -l ++
Here $inherits is a comma-separated class list like "A,B,C", "P, A, Q", or +just "A". Notice that this filter works on both situations where there's a +space after each comma or there's not.
+Case-insensitive matching can be performed by #/PATTERN/i:
+List all tags inherits from the class "A" or "a":
++$ readtags -Q '(#/(^|,) ?A(,|$)/i $inherits)' -l ++
To include "/" in a pattern, prefix \ to the "/".
+NOTE: The above regular expression pattern for inspecting inheritances is just +an example to show how to use #/PATTERN/ expression. Tags file generators +have no consensus about the format of inherits:, e.g., whether there should +be a space after a comma. Even parsers in ctags have no consensus. Noticing the +format of the inherits: field of specific languages is needed for such +queries.
+The expressions #/PATTERN/ and #/PATTERN/i are for interactive use. +Readtags also offers an alias string->regexp, so #/PATTERN/ is equal to +(string->regexp "PATTERN"), and #/PATTERN/i is equal to +(string->regexp "PATTERN" :case-fold #t). string->regexp doesn't need +to prefix \ for including "/" in a pattern. string->regexp may simplify +a client tool building an expression. See also ctags-client-tools(7) for +building expressions in your tool.
+Let's now consider missing fields. The tags file may have tag entries that has +no inherits: field. In that case $inherits is #f, and the regular +expression matching raises an error, since string operators only work for +strings. To avoid this problem:
+Safely list all tags inherits from the class "A":
++$ readtags -Q '(and $inherits (#/(^|,) ?A(,|$)/ $inherits))' -l ++
This makes sure $inherits is not missing first, then match it by regexp.
+Sometimes you want to keep tags where the field is missing. For example, your +want to exclude reference tags, which is marked by the extras: field, then +you want to keep tags who doesn't have extras: field since they are also +not reference tags. Here's how to do it:
+List all tags but the reference tags:
++$ readtags -Q '(or (not $extras) (#/(^|,) ?reference(,|$)/ $extras))' -l ++
Notice that (not $extras) produces #t when $extras is missing, so +the whole or expression produces #t.
+Run "readtags -H filter" to know about all valid functions and variables.
+When sorting, the sorter expression is evaluated on two tag entries to decide +which should sort before the other one, until the order of all tag entries is +decided.
+In a sorter expression, $ and & are used to access the fields in the +two tag entries, and let's call them $-entry and &-entry. The sorter expression +should have a value of -1, 0 or 1. The value -1 means the $-entry should be put +above the &-entry, 1 means the contrary, and 0 makes their order in the output +uncertain.
+The core operator of sorting is <>. It's used to compare two strings or two +numbers (numbers are for the line: or end: fields). In (<> a b), if +a < b, the result is -1; a > b produces 1, and a = b +produces 0. Strings are compared using the strcmp function, see strcmp(3).
+For example, sort by names, and make those shorter or alphabetically smaller +ones appear before the others:
++$ readtags -S '(<> $name &name)' -l ++
This reads "If the tag name in the $-entry is smaller, it goes before the +&-entry".
+The <or> operator is used to chain multiple expressions until one returns +-1 or 1. For example, sort by input file names, then line numbers if in the +same file:
++$ readtags -S '(<or> (<> $input &input) (<> $line &line))' -l ++
The *- operator is used to flip the compare result. i.e., (*- (<> a b)) +is the same as (<> b a).
+Filter expressions can be used in sorter expressions. The technique is use +if to produce integers that can be compared based on the filter, like:
++(<> (if filter-expr-on-$-entry -1 1) + (if filter-expr-on-&-entry -1 1)) ++
So if $-entry satisfies the filter, while &-entry doesn't, it's the same as +(<> -1 1), which produces -1.
+For example, we want to put tags with "file" kind below other tags, then the +sorter would look like:
++(<> (if (eq? $kind "file") 1 -1) + (if (eq? &kind "file") 1 -1)) ++
A quick read tells us: If $-entry has "file" kind, and &-entry doesn't, the +sorter becomes (<> 1 -1), which produces 1, so the $-entry is put below +the &-entry, exactly what we want.
+The print operator can be used to print the value of an expression. For +example:
++$ readtags -Q '(print $name)' -l ++
prints the name of each tag entry before it. Since the return value of +print is not #f, all the tag entries are printed. We could control this +using the begin or begin0 operator. begin returns the value of its +last argument, and begin0 returns the value of its first argument. For +example:
++$ readtags -Q '(begin0 #f (print (prefix? "ctags" "ct")))' -l ++
prints a bunch of "#t" (depending on how many lines are in the tags file), and +the actual tag entries are not printed.
+See tags(5) for the details of tags file format.
+See ctags-client-tools(7) for the tips writing a +tool utilizing tags file.
+The official Universal Ctags web site at:
+ +The git repository for the library used in readtags command:
+ +Universal Ctags project +https://ctags.io/
+Darren Hiebert <dhiebert@users.sourceforge.net> +http://DarrenHiebert.com/
+The readtags command and libreadtags maintained at Universal Ctags +are derived from readtags.c and readtags.h developd at +http://ctags.sourceforge.net.
+| Version: | +2+ |
|---|---|
| Manual group: | Universal Ctags | +
| Manual section: | 5 | +
The contents of next section is a copy of FORMAT file in Exuberant +Ctags source code in its subversion repository at sourceforge.net.
+Exceptions introduced in Universal Ctags are explained inline with +"EXCEPTION" marker.
+The file format for the "tags" file, as used by Vi and many of its +descendants, has limited capabilities.
+This additional functionality is desired:
+To make this proposal into a standard for tags files, it needs to be supported +by most people working on versions of Vi, ctags, etc.. Currently this +standard is supported by:
+These have been or will be asked to support this standard:
+A tags file that is generated in the new format should still be usable by Vi. +This makes it possible to distribute tags files that are usable by all +versions and descendants of Vi.
+This restricts the format to what Vi can handle. The format is:
+The tags file is a list of lines, each line in the format:
+
+{tagname}<Tab>{tagfile}<Tab>{tagaddress}
+
+Any identifier, not containing white space..
+EXCEPTION: Universal Ctags violates this item of the proposal; +tagname may contain spaces. However, tabs are not allowed.
+Exactly one TAB character (although many versions of Vi can +handle any amount of white space).
+The name of the file where {tagname} is defined, relative to +the current directory (or location of the tags file?).
+Any Ex command. When executed, it behaves like 'magic' was +not set.
+The tags file is sorted on {tagname}. This allows for a binary search in +the file.
+Duplicate tags are allowed, but which one is actually used is +unpredictable (because of the binary search).
+The best way to add extra text to the line for the new functionality, without +breaking it for Vi, is to put a comment in the {tagaddress}. This gives the +freedom to use any text, and should work in any traditional Vi implementation.
+For example, when the old tags file contains:
++main main.c /^main(argc, argv)$/ +DEBUG defines.c 89 ++
The new lines can be:
++main main.c /^main(argc, argv)$/;"any additional text +DEBUG defines.c 89;"any additional text ++
Note that the ';' is required to put the cursor in the right line, and then +the '"' is recognized as the start of a comment.
+For Posix compliant Vi versions this will NOT work, since only a line number +or a search command is recognized. I hope Posix can be adjusted. Nvi suffers +from this.
+Vi allows the use of any Ex command in a tags file. This has the potential of +a trojan horse security leak.
+The proposal is to allow only Ex commands that position the cursor in a single +file. Other commands, like editing another file, quitting the editor, +changing a file or writing a file, are not allowed. It is therefore logical +to call the command a tagaddress.
+Specifically, these two Ex commands are allowed:
+A decimal line number:
++89 ++
A search command. It is a regular expression pattern, as used by Vi, +enclosed in // or ??:
++/^int c;$/ +?main()? ++
There are two combinations possible:
+Concatenation of the above, with ';' in between. The meaning is that the +first line number or search command is used, the cursor is positioned in +that line, and then the second search command is used (a line number would +not be useful). This can be done multiple times. This is useful when the +information in a single line is not unique, and the search needs to start +in a specified line.
+
+/struct xyz {/;/int count;/
+389;/struct foo/;/char *s;/
+
+A trailing comment can be added, starting with ';"' (two characters: +semi-colon and double-quote). This is used below.
++89;" foo bar ++
This might be extended in the future. What is currently missing is a way to +position the cursor in a certain column.
+Now the usage of the comment text has to be defined. The following is aimed +at:
+Use a comment after the {tagaddress} field. The format would be:
+
+{tagname}<Tab>{tagfile}<Tab>{tagaddress}[;"<Tab>{tagfield}..]
+
+Any identifier, not containing white space..
+EXCEPTION: Universal Ctags violates this item of the proposal; +name may contain spaces. However, tabs are not allowed. +Conversion, for some characters including <Tab> in the "value", +explained in the last of this section is applied.
+Optionally:
+A tagfield has a name, a colon, and a value: "name:value".
+The name consist only out of alphabetical characters. Upper and lower case +are allowed. Lower case is recommended. Case matters ("kind:" and "Kind: +are different tagfields).
+EXCEPTION: Universal Ctags allows users to use a numerical character +in the name other than its initial letter.
+The value may be empty. +It cannot contain a <Tab>.
+Other use of the backslash character is reserved for future expansion. +Warning: When a tagfield value holds an MS-DOS file name, the backslashes +must be doubled!
+EXCEPTION: Universal Ctags introduces more conversion rules.
+Proposed tagfield names:
+| FIELD-NAME | +DESCRIPTION | +
|---|---|
| arity | +Number of arguments for a function tag. | +
| class | +Name of the class for which this tag is a member or method. | +
| enum | +Name of the enumeration in which this tag is an enumerator. | +
| file | +Static (local) tag, with a scope of the specified file. When +the value is empty, {tagfile} is used. | +
| function | +Function in which this tag is defined. Useful for local +variables (and functions). When functions nest (e.g., in +Pascal), the function names are concatenated, separated with +'/', so it looks like a path. | +
| kind | +Kind of tag. The value depends on the language. For C and +C++ these kinds are recommended: +
When this field is omitted, the kind of tag is undefined. + |
+
| struct | +Name of the struct in which this tag is a member. | +
| union | +Name of the union in which this tag is a member. | +
Note that these are mostly for C and C++. When tags programs are written for +other languages, this list should be extended to include the used field names. +This will help users to be independent of the tags program used.
+Examples:
++asdf sub.cc /^asdf()$/;" new_field:some\svalue file: +foo_t sub.h /^typedef foo_t$/;" kind:t +func3 sub.p /^func3()$/;" function:/func1/func2 file: +getflag sub.c /^getflag(arg)$/;" kind:f file: +inc sub.cc /^inc()$/;" file: class:PipeBuf ++
The name of the "kind:" field can be omitted. This is to reduce the size of +the tags file by about 15%. A program reading the tags file can recognize the +"kind:" field by the missing ':'. Examples:
++foo_t sub.h /^typedef foo_t$/;" t +getflag sub.c /^getflag(arg)$/;" f file: ++
Additional remarks:
+Note about line separators:
+Vi traditionally runs on Unix systems, where the line separator is a single +linefeed character <NL>. On MS-DOS and compatible systems <CR><NL> is the +standard line separator. To increase portability, this line separator is also +supported.
+On the Macintosh a single <CR> is used for line separator. Supporting this on +Unix systems causes problems, because most fgets() implementation don't see +the <CR> as a line separator. Therefore the support for a <CR> as line +separator is limited to the Macintosh.
+Summary:
+| line separator | +generated on | +accepted on | +
|---|---|---|
| <LF> | +Unix | +Unix, MS-DOS, Macintosh | +
| <CR> | +Macintosh | +Macintosh | +
| <CR><LF> | +MS-DOS | +Unix, MS-DOS, Macintosh | +
The characters <CR> and <LF> cannot be used inside a tag line. This is not +mentioned elsewhere (because it's obvious).
+Note about white space:
+Vi allowed any white space to separate the tagname from the tagfile, and the +filename from the tagaddress. This would need to be allowed for backwards +compatibility. However, all known programs that generate tags use a single +<Tab> to separate fields.
+There is a problem for using file names with embedded white space in the +tagfile field. To work around this, the same special characters could be used +as in the new fields, for example \s. But, unfortunately, in MS-DOS the +backslash character is used to separate file names. The file name +c:\vim\sap contains \s, but this is not a <Space>. The number of +backslashes could be doubled, but that will add a lot of characters, and make +parsing the tags file slower and clumsy.
+To avoid these problems, we will only allow a <Tab> to separate fields, and +not support a file name or tagname that contains a <Tab> character. This +means that we are not 100% Vi compatible. However, there is no known tags +program that uses something else than a <Tab> to separate the fields. Only +when a user typed the tags file himself, or made his own program to generate a +tags file, we could run into problems. To solve this, the tags file should be +filtered, to replace the arbitrary white space with a single <Tab>. This Vi +command can be used:
++:%s/^\([^ ^I]*\)[ ^I]*\([^ ^I]*\)[ ^I]*/\1^I\2^I/ ++
(replace ^I with a real <Tab>).
+TAG FILE INFORMATION:
+Pseudo-tag lines can be used to encode information into the tag file regarding +details about its content (e.g. have the tags been sorted?, are the optional +tagfields present?), and regarding the program used to generate the tag file. +This information can be used both to optimize use of the tag file (e.g. +enable/disable binary searching) and provide general information (what version +of the generator was used).
+The names of the tags used in these lines may be suitably chosen to ensure +that when sorted, they will always be located near the first lines of the tag +file. The use of "!_TAG_" is recommended. Note that a rare tag like "!" +can sort to before these lines. The program reading the tags file should be +smart enough to skip over these tags.
+The lines described below have been chosen to convey a select set of +information.
+Tag lines providing information about the content of the tag file:
+
+!_TAG_FILE_FORMAT {version-number} /optional comment/
+!_TAG_FILE_SORTED {0|1} /0=unsorted, 1=sorted/
+
+The {version-number} used in the tag file format line reserves the value of +"1" for tag files complying with the original UNIX vi/ctags format, and +reserves the value "2" for tag files complying with this proposal. This value +may be used to determine if the extended features described in this proposal +are present.
+Tag lines providing information about the program used to generate the tag +file, and provided solely for documentation purposes:
+
+!_TAG_PROGRAM_AUTHOR {author-name} /{email-address}/
+!_TAG_PROGRAM_NAME {program-name} /optional comment/
+!_TAG_PROGRAM_URL {URL} /optional comment/
+!_TAG_PROGRAM_VERSION {version-id} /optional comment/
+
+EXCEPTION: Universal Ctags introduces more kinds of pseudo-tags. +See ctags-client-tools(7) about them.
+Universal Ctags supports this proposal with some +exceptions.
+Default behavior (--output-format=u-ctags option) has the +exceptions. In other hand, with --output-format=e-ctags option +ctags has no exception; Universal Ctags command may use the same file +format as Exuberant Ctags. However, --output-format=e-ctags throws +away a tag entry which name includes a space or a tab +character. TAG_OUTPUT_MODE pseudo-tag tells which format is +used when ctags generating tags file.
+ctags(1), ctags-client-tools(7), ctags-incompatibilities(7), readtags(1)
+