1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
.. _ctags-json-output(5):
==============================================================
ctags-json-output
==============================================================
JSON based ctags output
:Version: 1.0
:Manual group: Universal Ctags
:Manual section: 5
SYNOPSIS
--------
| **ctags** --output-format=json ...
DESCRIPTION
-----------
Universal Ctags supports `JSON <https://www.json.org/>`_ (strictly
speaking `JSON Lines <https://jsonlines.org/>`_) 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.
.. code-block:: console
$ ctags --extras=+p --output-format=json --fields=-s input.py
{"_type": "ptag", "name": "JSON_OUTPUT_VERSION", "path": "1.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 regular 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 "1.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.
.. code-block:: console
$ 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.
VERSIONS
--------
Change since "0.0"
~~~~~~~~~~~~~~~~~~
* New key ``kindName`` for ``TAG_ROLE_DESCRIPTION`` pseudo tag
``kindName`` is added to store the name of the kind in ``TAG_ROLE_DESCRIPTION``
pseudo tags.
In 0.0, a "TAG_ROLE_DESCRIPTION" pseudo tag was printed like:
.. code-block:: JSON
{"_type": "ptag", "name": "TAG_ROLE_DESCRIPTION",
"parserName": "LANG!KIND", }
In 1.0, it is printed like:
.. code-block:: JSON
{"_type": "ptag", "name": "TAG_ROLE_DESCRIPTION",
"parserName": "LANG",
"kindName": "KIND", }
SEE ALSO
--------
:ref:`ctags(1) <ctags(1)>`, :ref:`tags(5) <tags(5)>`, :ref:`ctags-client-tools(7) <ctags-client-tools(7)>`
|
