ctags-json-output(5)

💖 NAME 💖

ctags-json-output — the JSON based ctags output, bestie!! this is page 5 of the Universal Ctags manual and it's literally the glow-up era of tag output 🦋

---

✨ SYNOPSIS ✨

ctags --output-format=json ...

---

🌸 DESCRIPTION 🌸

okay so. Universal Ctags supports JSON output — and when I say JSON I mean <https://www.json.org/>, and strictly speaking it's actually JSON Lines <https://jsonlines.org/> (iykyk, one object per line, no giant array, chef's kiss 💅).

⚠️ the catch: this only works if the ctags executable was built with libjansson. no jansson, no JSON, periodt.

and where does it go? standard output, by default. no cap. 🎀

---

🎀 FORMAT 🎀

every single JSON line = one tag. that's the whole vibe. one line, one tag, slay.

$ 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"}
...

so here's the key situation, and it's giving very much "read the first character" energy:

• a key that does not start with _ maps to a field of ctags. wanna see the whole field list? run the --output-format=json --list-fields options, they will literally list the fields for you. 🫶
• a key that does start with _ is meta information about that JSON line. right now only the _type key is used. if its value is tag, the line is a regular tag. if the value is ptag, the line is a pseudo-tag. iconic.

💀 real talk: the output format can change in the future. that's not me being dramatic, that's the actual deal. the JSON_OUTPUT_VERSION pseudo-tag exists so client-tools get a heads up about those changes. current version is "1.0". a client-tool can extract the version with the path key from that pseudo-tag. yes bestie, that's your version check, use it.

the JSON output format is newly designed and has no limitation found in the default tags file format. let me say that again for the people in the back:

• the values for the kind key are represented in long-name flags. there is no one-letter situation here. none. zero. 🙈
• scope names and scope kinds have distinguished keys: scope and scopeKind. in the default tags file format they're combined — here they get to live their separate lives. main character energy for both. 👑

---

🧚 DATA TYPE USED IN A FIELD 🧚

values for most of all the keys are represented in JSON string type. but some of them are represented in string, integer, and/or boolean type. it's a mixed bag, and honestly? it works.

the --output-format=json --list-fields options show what kind of data type is 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
...

the JSTYPE column is the one you wanna stare at — that's where the data types live. here's the decoder ring 🔥

• 's' — string
• 'i' — integer
• 'b' — boolean (true or false)

for an example, the value for the pattern field of ctags takes a string or a boolean value. see? told you. 😌

---

🕰️ 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:

{"_type": "ptag", "name": "TAG_ROLE_DESCRIPTION",
                  "parserName": "LANG!KIND", }

in 1.0, it is printed like:

{"_type": "ptag", "name": "TAG_ROLE_DESCRIPTION",
                  "parserName": "LANG",
                  "kindName": "KIND",  }

---

👑 SEE ALSO 👑

ctags(1), tags(5), ctags-client-tools(7)

---

okay that's the whole page, bestie!! this was ctags-json-output(5) at version 1.0, coming to you straight from Universal Ctags 💖 go forth and parse responsibly. bye bestie!! 🎀✨🦋