Skip to content

Commit 573fd7b

Browse files
masatakemasatake
committed
docs(man): add ctags-json-output(5)
1 parent 60cc214 commit 573fd7b

File tree

6 files changed

+200
-152
lines changed

6 files changed

+200
-152
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: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
.. _ctags-json-output(5):
2+
3+
==============================================================
4+
ctags-json-output
5+
==============================================================
6+
7+
JSON based ctags output
8+
9+
:Version: 0.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": "0.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 "0.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+
SEE ALSO
96+
--------
97+
:ref:`ctags(1) <ctags(1)>`, :ref:`tags(5) <tags(5)>`, :ref:`ctags-client-tools(7) <ctags-client-tools(7)>`

‎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)

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

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
.. _ctags-json-output(5):
2+
3+
==============================================================
4+
ctags-json-output
5+
==============================================================
6+
---------------------------------------------------------------------------------
7+
JSON based ctags output
8+
---------------------------------------------------------------------------------
9+
:Version: 0.0
10+
:Manual group: Universal Ctags
11+
:Manual section: 5
12+
13+
SYNOPSIS
14+
--------
15+
| **@CTAGS_NAME_EXECUTABLE@** --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": "0.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 "0.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+
SEE ALSO
96+
--------
97+
ctags(1), tags(5), ctags-client-tools(7)

0 commit comments

Comments
 (0)