Skip to content

Commit f9d21e7

Browse files
masatakemasatake
authored
Merge pull request #3573 from masatake/revise-json-writer
[SELF-INCOMPATIBLE] revise json writer for version 1.0 of json-output format
2 parents 60cc214 + 8cab33d commit f9d21e7

File tree

9 files changed

+279
-155
lines changed

9 files changed

+279
-155
lines changed

‎docs/man-pages.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Man pages
88
:maxdepth: 3
99

1010
ctags(1) <man/ctags.1.rst>
11+
ctags-json-output(5) <man/ctags-json-output.5.rst>
1112
tags(5) <man/tags.5.rst>
1213

1314
ctags-optlib(7) <man/ctags-optlib.7.rst>

‎docs/man/ctags-client-tools.7.rst‎

Lines changed: 2 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -470,81 +470,7 @@ nearest occurrence from the line" gives good result on both schemes.
470470

471471
JSON OUTPUT
472472
-----------
473-
Universal Ctags supports `JSON <https://www.json.org/>`_ (strictly
474-
speaking `JSON Lines <https://jsonlines.org/>`_) output format if the
475-
ctags executable is built with ``libjansson``. JSON output goes to
476-
standard output by default.
477-
478-
Format
479-
~~~~~~
480-
Each JSON line represents a tag.
481-
482-
.. code-block:: console
483-
484-
$ ctags --extras=+p --output-format=json --fields=-s input.py
485-
{"_type": "ptag", "name": "JSON_OUTPUT_VERSION", "path": "0.0", "pattern": "in development"}
486-
{"_type": "ptag", "name": "TAG_FILE_SORTED", "path": "1", "pattern": "0=unsorted, 1=sorted, 2=foldcase"}
487-
...
488-
{"_type": "tag", "name": "Klass", "path": "/tmp/input.py", "pattern": "/^class Klass:$/", "language": "Python", "kind": "class"}
489-
{"_type": "tag", "name": "method", "path": "/tmp/input.py", "pattern": "/^ def method(self):$/", "language": "Python", "kind": "member", "scope": "Klass", "scopeKind": "class"}
490-
...
491-
492-
A key not starting with ``_`` is mapped to a field of ctags.
493-
"``--output-format=json --list-fields``" options list the fields.
494-
495-
A key starting with ``_`` represents meta information of the JSON
496-
line. Currently only ``_type`` key is used. If the value for the key
497-
is ``tag``, the JSON line represents a regular tag. If the value is
498-
``ptag``, the line represents a pseudo-tag.
499-
500-
The output format can be changed in the
501-
future. ``JSON_OUTPUT_VERSION`` pseudo-tag provides a change
502-
client-tools to handle the changes. Current version is "0.0". A
503-
client-tool can extract the version with ``path`` key from the
504-
pseudo-tag.
505-
506-
The JSON output format is newly designed and has no limitation found
507-
in the default tags file format.
508-
509-
* The values for ``kind`` key are represented in long-name flags.
510-
No one-letter is here.
511-
512-
* Scope names and scope kinds have distinguished keys: ``scope`` and ``scopeKind``.
513-
They are combined in the default tags file format.
514-
515-
Data type used in a field
516-
~~~~~~~~~~~~~~~~~~~~~~~~~
517-
Values for the most of all keys are represented in JSON string type.
518-
However, some of them are represented in string, integer, and/or boolean type.
519-
520-
"``--output-format=json --list-fields``" options show What kind of data type
521-
used in a field of JSON.
522-
523-
.. code-block:: console
524-
525-
$ ctags --output-format=json --list-fields
526-
#LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION
527-
F input yes NONE s-- no input file
528-
...
529-
P pattern yes NONE s-b no pattern
530-
...
531-
f file yes NONE --b no File-restricted scoping
532-
...
533-
e end no NONE -i- no end lines of various items
534-
...
535-
536-
``JSTYPE`` column shows the data types.
537-
538-
'``s``'
539-
string
540-
541-
'``i``'
542-
integer
543-
544-
'``b``'
545-
boolean (true or false)
546-
547-
For an example, the value for ``pattern`` field of ctags takes a string or a boolean value.
473+
See :ref:`ctags-json-output(5) <ctags-json-output(5)>`.
548474

549475
CHANGES
550476
-----------
@@ -555,4 +481,4 @@ Version 6.0
555481

556482
SEE ALSO
557483
--------
558-
:ref:`ctags(1) <ctags(1)>`, :ref:`ctags-lang-python(7) <ctags-lang-python(7)>`, :ref:`ctags-incompatibilities(7) <ctags-incompatibilities(7)>`, :ref:`tags(5) <tags(5)>`, :ref:`readtags(1) <readtags(1)>`
484+
:ref:`ctags(1) <ctags(1)>`, :ref:`ctags-lang-python(7) <ctags-lang-python(7)>`, :ref:`ctags-incompatibilities(7) <ctags-incompatibilities(7)>`, :ref:`tags(5) <tags(5)>`, :ref:`ctags-json-output(5) <ctags-json-output(5)>`, :ref:`readtags(1) <readtags(1)>`

‎docs/man/ctags-json-output.5.rst‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
.. _ctags-json-output(5):
2+
3+
==============================================================
4+
ctags-json-output
5+
==============================================================
6+
7+
JSON based ctags output
8+
9+
:Version: 1.0
10+
:Manual group: Universal Ctags
11+
:Manual section: 5
12+
13+
SYNOPSIS
14+
--------
15+
| **ctags** --output-format=json ...
16+
17+
DESCRIPTION
18+
-----------
19+
Universal Ctags supports `JSON <https://www.json.org/>`_ (strictly
20+
speaking `JSON Lines <https://jsonlines.org/>`_) output format if the
21+
ctags executable is built with ``libjansson``. JSON output goes to
22+
standard output by default.
23+
24+
Format
25+
------
26+
Each JSON line represents a tag.
27+
28+
.. code-block:: console
29+
30+
$ ctags --extras=+p --output-format=json --fields=-s input.py
31+
{"_type": "ptag", "name": "JSON_OUTPUT_VERSION", "path": "1.0", "pattern": "in development"}
32+
{"_type": "ptag", "name": "TAG_FILE_SORTED", "path": "1", "pattern": "0=unsorted, 1=sorted, 2=foldcase"}
33+
...
34+
{"_type": "tag", "name": "Klass", "path": "/tmp/input.py", "pattern": "/^class Klass:$/", "language": "Python", "kind": "class"}
35+
{"_type": "tag", "name": "method", "path": "/tmp/input.py", "pattern": "/^ def method(self):$/", "language": "Python", "kind": "member", "scope": "Klass", "scopeKind": "class"}
36+
...
37+
38+
A key not starting with ``_`` is mapped to a field of ctags.
39+
"``--output-format=json --list-fields``" options list the fields.
40+
41+
A key starting with ``_`` represents meta information of the JSON
42+
line. Currently only ``_type`` key is used. If the value for the key
43+
is ``tag``, the JSON line represents a regular tag. If the value is
44+
``ptag``, the line represents a pseudo-tag.
45+
46+
The output format can be changed in the
47+
future. ``JSON_OUTPUT_VERSION`` pseudo-tag provides a change
48+
client-tools to handle the changes. Current version is "1.0". A
49+
client-tool can extract the version with ``path`` key from the
50+
pseudo-tag.
51+
52+
The JSON output format is newly designed and has no limitation found
53+
in the default tags file format.
54+
55+
* The values for ``kind`` key are represented in long-name flags.
56+
No one-letter is here.
57+
58+
* Scope names and scope kinds have distinguished keys: ``scope`` and ``scopeKind``.
59+
They are combined in the default tags file format.
60+
61+
Data type used in a field
62+
-------------------------
63+
Values for the most of all keys are represented in JSON string type.
64+
However, some of them are represented in string, integer, and/or boolean type.
65+
66+
"``--output-format=json --list-fields``" options show What kind of data type
67+
used in a field of JSON.
68+
69+
.. code-block:: console
70+
71+
$ ctags --output-format=json --list-fields
72+
#LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION
73+
F input yes NONE s-- no input file
74+
...
75+
P pattern yes NONE s-b no pattern
76+
...
77+
f file yes NONE --b no File-restricted scoping
78+
...
79+
e end no NONE -i- no end lines of various items
80+
...
81+
82+
``JSTYPE`` column shows the data types.
83+
84+
'``s``'
85+
string
86+
87+
'``i``'
88+
integer
89+
90+
'``b``'
91+
boolean (true or false)
92+
93+
For an example, the value for ``pattern`` field of ctags takes a string or a boolean value.
94+
95+
VERSIONS
96+
--------
97+
98+
Cnages since "0.0"
99+
~~~~~~~~~~~~~~~~~~
100+
101+
* New key ``kindName`` for ``TAG_ROLE_DESCRIPTION`` pseudo tag
102+
103+
``kindName`` is added to store the name of the kind in ``TAG_ROLE_DESCRIPTION``
104+
pseudo tags.
105+
106+
In 0.0, a "TAG_ROLE_DESCRIPTION" pseudo tag was printed like:
107+
108+
.. code-block:: JSON
109+
110+
{"_type": "ptag", "name": "TAG_ROLE_DESCRIPTION",
111+
"parserName": "LANG!KIND", }
112+
113+
In 1.0, it is printed like:
114+
115+
.. code-block:: JSON
116+
117+
{"_type": "ptag", "name": "TAG_ROLE_DESCRIPTION",
118+
"parserName": "LANG",
119+
"kindName": "KIND", }
120+
121+
SEE ALSO
122+
--------
123+
:ref:`ctags(1) <ctags(1)>`, :ref:`tags(5) <tags(5)>`, :ref:`ctags-client-tools(7) <ctags-client-tools(7)>`

‎main/ptag.c‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -185,7 +185,8 @@ static ptagDesc ptagDescs [] = {
185185
{ true, "TAG_ROLE_DESCRIPTION",
186186
"the names and descriptions of enabled roles",
187187
ptagMakeRoleDescriptions,
188-
PTAGF_PARSER },
188+
PTAGF_PARSER,
189+
.jsonObjectKey = "kindName" },
189190
{ true, "TAG_OUTPUT_MODE",
190191
"the output mode: u-ctags or e-ctags",
191192
ptagMakeCtagsOutputMode,

‎main/ptag_p.h‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,9 @@ struct sPtagDesc {
6969
bool (* makeTag) (ptagDesc *, langType, const void *);
7070

7171
ptagFlag flags;
72+
73+
/* See writer-json.c */
74+
const char *jsonObjectKey;
7275
};
7376

7477
extern bool makePtagIfEnabled (ptagType type, langType language, const void *data);

‎main/writer-json.c‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,9 @@
2525
#ifdef HAVE_JANSSON
2626
#include <jansson.h>
2727

28+
#define JSON_WRITER_MAJOR 0
29+
#define JSON_WRITER_MINOR 0
30+
2831
#ifndef json_boolean /* compat with jansson < 2.4 */
2932
#define json_boolean(val) ((val) ? json_true() : json_false())
3033
#endif
@@ -238,8 +241,23 @@ static int writeJsonPtagEntry (tagWriter *writer CTAGS_ATTR_UNUSED,
238241
{
239242
#define OPT(X) ((X)?(X):"")
240243
json_t *response;
244+
char *parserName0 = NULL;
241245

242-
if (parserName)
246+
const char *rest = ((JSON_WRITER_MAJOR > 0) && parserName && desc->jsonObjectKey)
247+
? strchr(parserName, '!')
248+
: NULL;
249+
if (rest)
250+
{
251+
parserName0 = eStrndup(parserName, rest - parserName);
252+
response = json_pack ("{ss ss ss ss ss ss}",
253+
"_type", "ptag",
254+
"name", desc->name,
255+
"parserName", parserName0,
256+
desc->jsonObjectKey, rest + 1,
257+
"path", OPT(fileName),
258+
"pattern", OPT(pattern));
259+
}
260+
else if (parserName)
243261
{
244262
response = json_pack ("{ss ss ss ss ss}",
245263
"_type", "ptag",
@@ -261,6 +279,8 @@ static int writeJsonPtagEntry (tagWriter *writer CTAGS_ATTR_UNUSED,
261279
int length = mio_printf (mio, "%s\n", buf);
262280
free (buf);
263281
json_decref (response);
282+
if (parserName0)
283+
eFree(parserName0);
264284

265285
return length;
266286
#undef OPT
@@ -270,7 +290,7 @@ extern bool ptagMakeJsonOutputVersion (ptagDesc *desc, langType language CTAGS_A
270290
const void *data CTAGS_ATTR_UNUSED)
271291
{
272292
return writePseudoTag (desc,
273-
"0.0",
293+
STRINGIFY(JSON_WRITER_MAJOR) "." STRINGIFY(JSON_WRITER_MINOR),
274294
"in development",
275295
NULL);
276296
}

‎man/GNUmakefile.am‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ GEN_IN_MAN_FILES = \
4343
\
4444
readtags.1 \
4545
tags.5 \
46+
ctags-json-output.5 \
4647
\
4748
$(NULL)
4849

‎man/ctags-client-tools.7.rst.in‎

Lines changed: 2 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -470,81 +470,7 @@ nearest occurrence from the line" gives good result on both schemes.
470470

471471
JSON OUTPUT
472472
-----------
473-
Universal Ctags supports `JSON <https://www.json.org/>`_ (strictly
474-
speaking `JSON Lines <https://jsonlines.org/>`_) output format if the
475-
ctags executable is built with ``libjansson``. JSON output goes to
476-
standard output by default.
477-
478-
Format
479-
~~~~~~
480-
Each JSON line represents a tag.
481-
482-
.. code-block:: console
483-
484-
$ ctags --extras=+p --output-format=json --fields=-s input.py
485-
{"_type": "ptag", "name": "JSON_OUTPUT_VERSION", "path": "0.0", "pattern": "in development"}
486-
{"_type": "ptag", "name": "TAG_FILE_SORTED", "path": "1", "pattern": "0=unsorted, 1=sorted, 2=foldcase"}
487-
...
488-
{"_type": "tag", "name": "Klass", "path": "/tmp/input.py", "pattern": "/^class Klass:$/", "language": "Python", "kind": "class"}
489-
{"_type": "tag", "name": "method", "path": "/tmp/input.py", "pattern": "/^ def method(self):$/", "language": "Python", "kind": "member", "scope": "Klass", "scopeKind": "class"}
490-
...
491-
492-
A key not starting with ``_`` is mapped to a field of ctags.
493-
"``--output-format=json --list-fields``" options list the fields.
494-
495-
A key starting with ``_`` represents meta information of the JSON
496-
line. Currently only ``_type`` key is used. If the value for the key
497-
is ``tag``, the JSON line represents a regular tag. If the value is
498-
``ptag``, the line represents a pseudo-tag.
499-
500-
The output format can be changed in the
501-
future. ``JSON_OUTPUT_VERSION`` pseudo-tag provides a change
502-
client-tools to handle the changes. Current version is "0.0". A
503-
client-tool can extract the version with ``path`` key from the
504-
pseudo-tag.
505-
506-
The JSON output format is newly designed and has no limitation found
507-
in the default tags file format.
508-
509-
* The values for ``kind`` key are represented in long-name flags.
510-
No one-letter is here.
511-
512-
* Scope names and scope kinds have distinguished keys: ``scope`` and ``scopeKind``.
513-
They are combined in the default tags file format.
514-
515-
Data type used in a field
516-
~~~~~~~~~~~~~~~~~~~~~~~~~
517-
Values for the most of all keys are represented in JSON string type.
518-
However, some of them are represented in string, integer, and/or boolean type.
519-
520-
"``--output-format=json --list-fields``" options show What kind of data type
521-
used in a field of JSON.
522-
523-
.. code-block:: console
524-
525-
$ ctags --output-format=json --list-fields
526-
#LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION
527-
F input yes NONE s-- no input file
528-
...
529-
P pattern yes NONE s-b no pattern
530-
...
531-
f file yes NONE --b no File-restricted scoping
532-
...
533-
e end no NONE -i- no end lines of various items
534-
...
535-
536-
``JSTYPE`` column shows the data types.
537-
538-
'``s``'
539-
string
540-
541-
'``i``'
542-
integer
543-
544-
'``b``'
545-
boolean (true or false)
546-
547-
For an example, the value for ``pattern`` field of ctags takes a string or a boolean value.
473+
See ctags-json-output(5).
548474

549475
CHANGES
550476
-----------
@@ -555,4 +481,4 @@ Version 6.0
555481

556482
SEE ALSO
557483
--------
558-
ctags(1), ctags-lang-python(7), ctags-incompatibilities(7), tags(5), readtags(1)
484+
ctags(1), ctags-lang-python(7), ctags-incompatibilities(7), tags(5), ctags-json-output(5), readtags(1)

0 commit comments

Comments
 (0)