ctags-client-tools - Man Page
Hints for developing a tool using ctags command and tags output
Synopsis
ctags [options] [file(s)] etags [options] [file(s)]
Description
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
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").
Redundant-Kinds
TBW
Multiple-Languages for an Input File
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
JSON Output
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.
Format
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.
- The values for kind key are represented in long-name flags. No one-letter is here.
- Scope names and scope kinds have distinguished keys: scope and scopeKind. They are combined in the default tags file format.
Data type used in a field
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.
- 's'
string
- 'i'
integer
- 'b'
boolean (true or false)
For an example, the value for pattern field of ctags takes a string or a boolean value.
See Also
ctags(1), ctags-lang-python(7), ctags-incompatibilities(7), tags(5), readtags(1)
Referenced By
ctags(1), ctags-lang-inko(7), ctags-lang-iPythonCell(7), ctags-lang-julia(7), ctags-lang-python(7), ctags-lang-sql(7), ctags-lang-verilog(7), readtags(1), tags(5).