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
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>ctags-client-tools — Universal Ctags 0.3.0 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css" />
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="ctags-faq" href="ctags-faq.7.html" />
<link rel="prev" title="ctags-optlib" href="ctags-optlib.7.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="ctags-faq.7.html" title="ctags-faq"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="ctags-optlib.7.html" title="ctags-optlib"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li>
<li class="nav-item nav-item-this"><a href="">ctags-client-tools</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="ctags-client-tools">
<span id="ctags-client-tools-7"></span><h1>ctags-client-tools<a class="headerlink" href="#ctags-client-tools" title="Permalink to this headline">¶</a></h1>
<p>Hints for developing a tool using ctags command and tags output</p>
<dl class="field-list simple">
<dt class="field-odd">Version</dt>
<dd class="field-odd"><p>5.9.0</p>
</dd>
<dt class="field-even">Manual group</dt>
<dd class="field-even"><p>Universal Ctags</p>
</dd>
<dt class="field-odd">Manual section</dt>
<dd class="field-odd"><p>7</p>
</dd>
</dl>
<section id="synopsis">
<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
<div class="line-block">
<div class="line"><strong>ctags</strong> [options] [file(s)]</div>
<div class="line"><strong>etags</strong> [options] [file(s)]</div>
</div>
</section>
<section id="description">
<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p><strong>Client tool</strong> 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.</p>
</section>
<section id="pseudo-tags">
<h2>PSEUDO-TAGS<a class="headerlink" href="#pseudo-tags" title="Permalink to this headline">¶</a></h2>
<p><strong>Pseudo-tags</strong>, 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 <strong>regular-tags</strong>. 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.</p>
<p>A pseudo-tag is stored in a tags file in the same format as
regular-tags as described in <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>, except that pseudo-tag names
are prefixed with “!_”. For the general information about
pseudo-tags, see “TAG FILE INFORMATION” in <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>.</p>
<p>An example of a pseudo tag:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_PROGRAM_NAME Universal Ctags /Derived from Exuberant Ctags/
</pre></div>
</div>
<p>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.</p>
<p>Universal Ctags extends the naming scheme of the classical pseudo-tags
available in Exuberant Ctags for emitting language specific
information as pseudo tags:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_{pseudo-tag-name}!{language-name} {associated-value} /{description}/
</pre></div>
</div>
<p>The language-name is appended to the pseudo-tag name with a separator, “!”.</p>
<p>An example of pseudo tag with a language suffix:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_KIND_DESCRIPTION!C f,function /function definitions/
</pre></div>
</div>
<p>This pseudo-tag says “the function kind of C language is enabled
when generating this tags file.” <code class="docutils literal notranslate"><span class="pre">--pseudo-tags</span></code> 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”).</p>
<section id="options-for-pseudo-tags">
<h3>Options for Pseudo-tags<a class="headerlink" href="#options-for-pseudo-tags" title="Permalink to this headline">¶</a></h3>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">--extras=+p</span></code> (or <code class="docutils literal notranslate"><span class="pre">--extras=+{pseudo}</span></code>)</dt><dd><p>Forces writing pseudo-tags.</p>
<p>ctags emits pseudo-tags by default when writing tags
to a regular file (e.g. “tags’.) However, when specifying <code class="docutils literal notranslate"><span class="pre">-o</span> <span class="pre">-</span></code>
or <code class="docutils literal notranslate"><span class="pre">-f</span> <span class="pre">-</span></code> for writing tags to standard output,
ctags doesn’t emit pseudo-tags. <code class="docutils literal notranslate"><span class="pre">--extras=+p</span></code> or
<code class="docutils literal notranslate"><span class="pre">--extras=+{pseudo}</span></code> will force pseudo-tags to be written.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code></dt><dd><p>Lists available types of pseudo-tags and shows whether they are enabled or disabled.</p>
<p>Running ctags with <code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code> option
lists available pseudo-tags. Some of pseudo-tags newly introduced
in Universal Ctags project are disabled by default. Use
<code class="docutils literal notranslate"><span class="pre">--pseudo-tags=...</span></code> to enable them.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--pseudo-tags=[+|-]names|*</span></code></dt><dd><p>Specifies a list of pseudo-tag types to include in the output.</p>
<p>The parameters are a set of pseudo tag names. Valid pseudo tag names
can be listed with <code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code>. Surround each name in the set
with braces, like “{TAG_PROGRAM_AUTHOR}”. You don’t have to include the “!_”
pseudo tag prefix when specifying a name in the option argument for <code class="docutils literal notranslate"><span class="pre">--pseudo-tags=</span></code>
option.</p>
<p>pseudo-tags don’t have a notation using one-letter flags.</p>
<p>If a name is preceded by either the ‘+’ or ‘-’ characters, that
tags’s effect has been added or removed. Otherwise the names replace
any current settings. All entries are included if ‘*’ is given.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--fields=+E</span></code> (or <code class="docutils literal notranslate"><span class="pre">--fields=+{extras}</span></code>)</dt><dd><p>Attach “extras:pseudo” field to pseudo-tags.</p>
<p>An example of pseudo tags with the field:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_PROGRAM_NAME Universal Ctags /Derived from Exuberant Ctags/ extras:pseudo
</pre></div>
</div>
<p>If the name of a normal tag in a tag file starts with “!_”, a
client tool cannot distinguish whether the tag is a regular-tag or
pseudo-tag. The fields attached with this option help the tool
distinguish them.</p>
</dd>
</dl>
</section>
<section id="list-of-notable-pseudo-tags">
<h3>List of notable pseudo-tags<a class="headerlink" href="#list-of-notable-pseudo-tags" title="Permalink to this headline">¶</a></h3>
<p>Running ctags with <code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code> option lists available types
of pseudo-tags with short descriptions. This subsection shows hints
for using notable ones.</p>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">TAG_EXTRA_DESCRIPTION</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the names and descriptions of enabled extras:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_EXTRA_DESCRIPTION {extra-name} /description/
!_TAG_EXTRA_DESCRIPTION!{language-name} {extra-name} /description/
</pre></div>
</div>
<p>If your tool relies on some extra tags (extras), refer to
the pseudo-tags of this type. A tool can reject the tags file that
doesn’t include expected extras, and raise an error in an early
stage of processing.</p>
<p>An example of the pseudo-tags:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --extras=+p --pseudo-tags='{TAG_EXTRA_DESCRIPTION}' -o - input.c
!_TAG_EXTRA_DESCRIPTION anonymous /Include tags for non-named objects like lambda/
!_TAG_EXTRA_DESCRIPTION fileScope /Include tags of file scope/
!_TAG_EXTRA_DESCRIPTION pseudo /Include pseudo tags/
!_TAG_EXTRA_DESCRIPTION subparser /Include tags generated by subparsers/
...
</pre></div>
</div>
<p>A client tool can know “{anonymous}”, “{fileScope}”, “{pseudo}”,
and “{subparser}” extras are enabled from the output.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">TAG_FIELD_DESCRIPTION</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the names and descriptions of enabled fields:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_FIELD_DESCRIPTION {field-name} /description/
!_TAG_FIELD_DESCRIPTION!{language-name} {field-name} /description/
</pre></div>
</div>
<p>If your tool relies on some fields, refer to the pseudo-tags of
this type. A tool can reject a tags file that doesn’t include
expected fields, and raise an error in an early stage of
processing.</p>
<p>An example of the pseudo-tags:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --fields-C=+'{macrodef}' --extras=+p --pseudo-tags='{TAG_FIELD_DESCRIPTION}' -o - input.c
!_TAG_FIELD_DESCRIPTION file /File-restricted scoping/
!_TAG_FIELD_DESCRIPTION input /input file/
!_TAG_FIELD_DESCRIPTION name /tag name/
!_TAG_FIELD_DESCRIPTION pattern /pattern/
!_TAG_FIELD_DESCRIPTION typeref /Type and name of a variable or typedef/
!_TAG_FIELD_DESCRIPTION!C macrodef /macro definition/
...
</pre></div>
</div>
<p>A client tool can know “{file}”, “{input}”, “{name}”, “{pattern}”,
and “{typeref}” fields are enabled from the output.
The fields are common in languages. In addition to the common fields,
the tool can known “{macrodef}” field of C language is also enabled.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">TAG_FILE_ENCODING</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">TAG_FILE_FORMAT</span></code></dt><dd><p>See also <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">TAG_FILE_SORTED</span></code></dt><dd><p>See also <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">TAG_KIND_DESCRIPTION</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the names and descriptions of enabled kinds:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_KIND_DESCRIPTION!{language-name} {kind-letter},{kind-name} /description/
</pre></div>
</div>
<p>If your tool relies on some kinds, refer to the pseudo-tags of
this type. A tool can reject the tags file that doesn’t include
expected kinds, and raise an error in an early stage of
processing.</p>
<p>Kinds are language specific, so a language name is always
appended to the tag name as suffix.</p>
<p>An example of the pseudo-tags:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --extras=+p --kinds-C=vfm --pseudo-tags='{TAG_KIND_DESCRIPTION}' -o - input.c
!_TAG_KIND_DESCRIPTION!C f,function /function definitions/
!_TAG_KIND_DESCRIPTION!C m,member /struct, and union members/
!_TAG_KIND_DESCRIPTION!C v,variable /variable definitions/
...
</pre></div>
</div>
<p>A client tool can know “{function}”, “{member}”, and “{variable}”
kinds of C language are enabled from the output.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">TAG_KIND_SEPARATOR</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_EXCMD</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the specified type of EX command with <code class="docutils literal notranslate"><span class="pre">--excmd</span></code> option.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_FILESEP</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_MODE</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">TAG_PATTERN_LENGTH_LIMIT</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">TAG_PROC_CWD</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the working directory of ctags during processing.</p>
<p>This pseudo-tag helps a client tool solve the absolute paths for
the input files for tag entries even when they are tagged with
relative paths.</p>
<p>An example of the pseudo-tags:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cat tags
!_TAG_PROC_CWD /tmp/ //
main input.c /^int main (void) { return 0; }$/;" f typeref:typename:int
...
</pre></div>
</div>
<p>From the regular tag for “main”, the client tool can know the
“main” is at “input.c”. However, it is a relative path. So if the
directory where ctags run and the directory
where the client tool runs are different, the client tool cannot
find “input.c” from the file system. In that case,
<code class="docutils literal notranslate"><span class="pre">TAG_PROC_CWD</span></code> gives the tool a hint; “input.c” may be at “/tmp”.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">TAG_PROGRAM_NAME</span></code></dt><dd><p>TBW</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">TAG_ROLE_DESCRIPTION</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the names and descriptions of enabled roles:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_ROLE_DESCRIPTION!{language-name}!{kind-name} {role-name} /description/
</pre></div>
</div>
<p>If your tool relies on some roles, refer to the pseudo-tags of
this type. Note that a role owned by a disabled kind is not listed
even if the role itself is enabled.</p>
</dd>
</dl>
</section>
</section>
<section id="redundant-kinds">
<h2>REDUNDANT-KINDS<a class="headerlink" href="#redundant-kinds" title="Permalink to this headline">¶</a></h2>
<p>TBW</p>
</section>
<section id="multiple-languages-for-an-input-file">
<h2>MULTIPLE-LANGUAGES FOR AN INPUT FILE<a class="headerlink" href="#multiple-languages-for-an-input-file" title="Permalink to this headline">¶</a></h2>
<p>Universal ctags can run multiple parsers.
That means a parser, which supports multiple parsers, may output tags for
different languages. <code class="docutils literal notranslate"><span class="pre">language</span></code>/<code class="docutils literal notranslate"><span class="pre">l</span></code> field can be used to show the language
for each tag.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat /tmp/foo.html
<span class="go"><html></span>
<span class="go"><script>var x = 1</script></span>
<span class="go"><h1>title</h1></span>
<span class="go"></html></span>
<span class="gp">$ </span>./ctags -o - --extras<span class="o">=</span>+g /tmp/foo.html
<span class="go">title /tmp/foo.html /^ <h1>title<\/h1>$/;" h</span>
<span class="go">x /tmp/foo.html /var x = 1/;" v</span>
<span class="gp">$ </span>./ctags -o - --extras<span class="o">=</span>+g --fields<span class="o">=</span>+l /tmp/foo.html
<span class="go">title /tmp/foo.html /^ <h1>title<\/h1>$/;" h language:HTML</span>
<span class="go">x /tmp/foo.html /var x = 1/;" v language:JavaScript</span>
</pre></div>
</div>
</section>
<section id="utilizing-readtags">
<h2>UTILIZING READTAGS<a class="headerlink" href="#utilizing-readtags" title="Permalink to this headline">¶</a></h2>
<p>See <a class="reference internal" href="readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a> to know how to use readtags. This section is for discussing
some notable topics for client tools.</p>
<section id="build-filter-sorter-expressions">
<h3>Build Filter/Sorter Expressions<a class="headerlink" href="#build-filter-sorter-expressions" title="Permalink to this headline">¶</a></h3>
<p>Certain escape sequences in expressions are recognized by readtags. For
example, when searching for a tag that matches <code class="docutils literal notranslate"><span class="pre">a\?b</span></code>, if using a filter
expression like <code class="docutils literal notranslate"><span class="pre">'(eq?</span> <span class="pre">$name</span> <span class="pre">"a\?b")'</span></code>, since <code class="docutils literal notranslate"><span class="pre">\?</span></code> is translated into a
single <code class="docutils literal notranslate"><span class="pre">?</span></code> by readtags, it actually searches for <code class="docutils literal notranslate"><span class="pre">a?b</span></code>.</p>
<p>Another problem is if a single quote appear in filter expressions (which is
also wrapped by single quotes), it terminates the expression, producing broken
expressions, and may even cause unintended shell injection. Single quotes can
be escaped using <code class="docutils literal notranslate"><span class="pre">'"'"'</span></code>.</p>
<p>So, client tools need to:</p>
<ul class="simple">
<li><p>Replace <code class="docutils literal notranslate"><span class="pre">\</span></code> by <code class="docutils literal notranslate"><span class="pre">\\</span></code></p></li>
<li><p>Replace <code class="docutils literal notranslate"><span class="pre">'</span></code> by <code class="docutils literal notranslate"><span class="pre">'"'"'</span></code></p></li>
</ul>
<p>inside the expressions. If the expression also contains strings, <code class="docutils literal notranslate"><span class="pre">"</span></code> in the
strings needs to be replaced by <code class="docutils literal notranslate"><span class="pre">\"</span></code>.</p>
<p>Client tools written in Lisp could build the expression using lists. <code class="docutils literal notranslate"><span class="pre">prin1</span></code>
(in Common Lisp style Lisps) and <code class="docutils literal notranslate"><span class="pre">write</span></code> (in Scheme style Lisps) can
translate the list into a string that can be directly used. For example, in
EmacsLisp:</p>
<div class="highlight-EmacsLisp notranslate"><div class="highlight"><pre><span></span>(let ((name "hi"))
(prin1 `(eq? $name ,name)))
=> "(eq\\? $name "hi")"
</pre></div>
</div>
<p>The “?” is escaped, and readtags can handle it. Scheme style Lisps should do
proper escaping so the expression readtags gets is just the expression passed
into <code class="docutils literal notranslate"><span class="pre">write</span></code>. Common Lisp style Lisps may produce unrecognized escape
sequences by readtags, like <code class="docutils literal notranslate"><span class="pre">\#</span></code>. Readtags provides some aliases for these
Lisps:</p>
<ul class="simple">
<li><p>Use <code class="docutils literal notranslate"><span class="pre">true</span></code> for <code class="docutils literal notranslate"><span class="pre">#t</span></code>.</p></li>
<li><p>Use <code class="docutils literal notranslate"><span class="pre">false</span></code> for <code class="docutils literal notranslate"><span class="pre">#f</span></code>.</p></li>
<li><p>Use <code class="docutils literal notranslate"><span class="pre">nil</span></code> or <code class="docutils literal notranslate"><span class="pre">()</span></code> for <code class="docutils literal notranslate"><span class="pre">()</span></code>.</p></li>
<li><p>Use <code class="docutils literal notranslate"><span class="pre">(string->regexp</span> <span class="pre">"PATTERN")</span></code> for <code class="docutils literal notranslate"><span class="pre">#/PATTERN/</span></code>. Use
<code class="docutils literal notranslate"><span class="pre">(string->regexp</span> <span class="pre">"PATTERN"</span> <span class="pre">:case-fold</span> <span class="pre">true)</span></code> for <code class="docutils literal notranslate"><span class="pre">#/PATTERN/i</span></code>. Notice
that <code class="docutils literal notranslate"><span class="pre">string->regexp</span></code> doesn’t require escaping “/” in the pattern.</p></li>
</ul>
<p>Notice that even when the client tool uses this method, <code class="docutils literal notranslate"><span class="pre">'</span></code> still needs to be
replaced by <code class="docutils literal notranslate"><span class="pre">'"'"'</span></code> to prevent broken expressions and shell injection.</p>
<p>Another thing to notice is that missing fields are represented by <code class="docutils literal notranslate"><span class="pre">#f</span></code>, and
applying string operators to them will produce an error. You should always
check if a field is missing before applying string operators. See the
“Filtering” section in <a class="reference internal" href="readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a> to know how to do this. Run “readtags -H
filter” to see which operators take string arguments.</p>
</section>
<section id="parse-readtags-output">
<h3>Parse Readtags Output<a class="headerlink" href="#parse-readtags-output" title="Permalink to this headline">¶</a></h3>
<p>In the output of readtags, tabs can appear in all field values (e.g., the tag
name itself could contain tabs), which makes it hard to split the line into
fields. Client tools should use the <code class="docutils literal notranslate"><span class="pre">-E</span></code> option, which keeps the escape
sequences in the tags file, so the only field that could contain tabs is the
pattern field.</p>
<p>The pattern field could:</p>
<ul class="simple">
<li><p>Use a line number. It will look like <code class="docutils literal notranslate"><span class="pre">number;"</span></code> (e.g. <code class="docutils literal notranslate"><span class="pre">10;"</span></code>).</p></li>
<li><p>Use a search pattern. It will look like <code class="docutils literal notranslate"><span class="pre">/pattern/;"</span></code> or <code class="docutils literal notranslate"><span class="pre">?pattern?;"</span></code>.
Notice that the search pattern could contain tabs.</p></li>
<li><p>Combine these two, like <code class="docutils literal notranslate"><span class="pre">number;/pattern/;"</span></code> or <code class="docutils literal notranslate"><span class="pre">number;?pattern?;"</span></code>.</p></li>
</ul>
<p>These are true for tags files using extended format, which is the default one.
The legacy format (i.e. <code class="docutils literal notranslate"><span class="pre">--format=1</span></code>) doesn’t include the semicolons. It’s
old and barely used, so we won’t discuss it here.</p>
<p>Client tools could split the line using the following steps:</p>
<ul class="simple">
<li><p>Find the first 2 tabs in the line, so we get the name and input field.</p></li>
<li><p>From the 2nd tab:</p>
<ul>
<li><p>If a <code class="docutils literal notranslate"><span class="pre">/</span></code> follows, then the pattern delimiter is <code class="docutils literal notranslate"><span class="pre">/</span></code>.</p></li>
<li><p>If a <code class="docutils literal notranslate"><span class="pre">?</span></code> follows, then the pattern delimiter is <code class="docutils literal notranslate"><span class="pre">?</span></code>.</p></li>
<li><p>If a number follows, then:</p>
<ul>
<li><p>If a <code class="docutils literal notranslate"><span class="pre">;/</span></code> follows the number, then the delimiter is <code class="docutils literal notranslate"><span class="pre">/</span></code>.</p></li>
<li><p>If a <code class="docutils literal notranslate"><span class="pre">;?</span></code> follows the number, then the delimiter is <code class="docutils literal notranslate"><span class="pre">?</span></code>.</p></li>
<li><p>If a <code class="docutils literal notranslate"><span class="pre">;"</span></code> follows the number, then the field uses only line number, and
there’s no pattern delimiter (since there’s no regex pattern). In this
case the pattern field ends at the 3rd tab.</p></li>
</ul>
</li>
</ul>
</li>
<li><p>After the opening delimiter, find the next unescaped pattern delimiter, and
that’s the closing delimiter. It will be followed by <code class="docutils literal notranslate"><span class="pre">;"</span></code> and then a tab.
That’s the end of the pattern field. By “unescaped pattern delimiter”, we
mean there’s an even number (including 0) of backslashes before it.</p></li>
<li><p>From here, split the rest of the line into fields by tabs.</p></li>
</ul>
<p>Then, the escape sequences in fields other than the pattern field should be
translated. See “Proposal” in <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> to know about all the escape sequences.</p>
</section>
<section id="make-use-of-the-pattern-field">
<h3>Make Use of the Pattern Field<a class="headerlink" href="#make-use-of-the-pattern-field" title="Permalink to this headline">¶</a></h3>
<p>The pattern field specifies how to find a tag in its source file. The code
generating this field seems to have a long history, so there are some pitfalls
and it’s a bit hard to handle. A client tool could simply require the <code class="docutils literal notranslate"><span class="pre">line:</span></code>
field and jump to the line it specifies, to avoid using the pattern field. But
anyway, we’ll discuss how to make the best use of it here.</p>
<p>You should take the words here merely as suggestions, and not standards. A
client tool could definitely develop better (or simpler) ways to use the
pattern field.</p>
<p>From the last section, we know the pattern field could contain a line number
and a search pattern. When it only contains the line number, handling it is
easy: you simply go to that line.</p>
<p>The search pattern resembles an EX command, but as we’ll see later, it’s
actually not a valid one, so some manual work are required to process it.</p>
<p>The search pattern could look like <code class="docutils literal notranslate"><span class="pre">/pat/</span></code>, called “forward search pattern”,
or <code class="docutils literal notranslate"><span class="pre">?pat?</span></code>, called “backward search pattern”. Using a search pattern means
even if the source file is updated, as long as the part containing the tag
doesn’t change, we could still locate the tag correctly by searching.</p>
<p>When the pattern field only contains the search pattern, you just search for
it. The search direction (forward/backward) doesn’t matter, as it’s decided
solely by whether the <code class="docutils literal notranslate"><span class="pre">-B</span></code> option is enabled, and not the actual context. You
could always start the search from say the beginning of the file.</p>
<p>When both the search pattern and the line number are presented, you could make
good use of the line number, by going to the line first, then searching for the
nearest occurence of the pattern. A way to do this is to search both forward
and backward for the pattern, and when there is a occurence on both sides, go
to the nearer one.</p>
<p>What’s good about this is when there are multiple identical lines in the source
file (e.g. the COMMON block in Fortran), this could help us find the correct
one, even after the source file is updated and the tag position is shifted by a
few lines.</p>
<p>Now let’s discuss how to search for the pattern. After you trim the <code class="docutils literal notranslate"><span class="pre">/</span></code> or
<code class="docutils literal notranslate"><span class="pre">?</span></code> around it, the pattern resembles a regex pattern. It should be a regex
pattern, as required by being a valid EX command, but it’s actually not, as
you’ll see below.</p>
<p>It could begin with a <code class="docutils literal notranslate"><span class="pre">^</span></code>, which means the pattern starts from the beginning
of a line. It could also end with an <em>unescaped</em> <code class="docutils literal notranslate"><span class="pre">$</span></code> which means the pattern
ends at the end of a line. Let’s keep this information, and trim them too.</p>
<p>Now the remaining part is the actual string containing the tag. Some characters
are escaped:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">\</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$</span></code>, but only at the end of the string.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">/</span></code>, but only in forward search patterns.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">?</span></code>, but only in backward search patterns.</p></li>
</ul>
<p>You need to unescape these to get the literal string. Now you could convert
this literal string to a regexp that matches it (by escaping, like
<code class="docutils literal notranslate"><span class="pre">re.escape</span></code> in Python or <code class="docutils literal notranslate"><span class="pre">regexp-quote</span></code> in Elisp), and assemble it with
<code class="docutils literal notranslate"><span class="pre">^</span></code> or <code class="docutils literal notranslate"><span class="pre">$</span></code> if the pattern originally has it, and finally search for the tag
using this regexp.</p>
</section>
<section id="remark-about-a-previous-format-of-the-pattern-field">
<h3>Remark: About a Previous Format of the Pattern Field<a class="headerlink" href="#remark-about-a-previous-format-of-the-pattern-field" title="Permalink to this headline">¶</a></h3>
<p>In some earlier versions of Universal Ctags, the line number in the pattern
field is the actual line number minus one, for forward search patterns; or plus
one, for backward search patterns. The idea is to resemble an EX command: you
go to the line, then search forward/backward for the pattern, and you can
always find the correct one. But this denies the purpose of using a search
pattern: to tolerate file updates. For example, the tag is at line 50,
according to this scheme, the pattern field should be:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">49</span><span class="p">;</span><span class="o">/</span><span class="n">pat</span><span class="o">/</span><span class="p">;</span><span class="s2">"</span>
</pre></div>
</div>
<p>Then let’s assume that some code above are removed, and the tag is now at
line 45. Now you can’t find it if you search forward from line 49.</p>
<p>Due to this reason, Universal Ctags turns to use the actual line number. A
client tool could distinguish them by the <code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_EXCMD</span></code> pseudo tag, it’s
“combine” for the old scheme, and “combineV2” for the present scheme. But
probably there’s no need to treat them differently, since “search for the
nearest occurence from the line” gives good result on both schemes.</p>
</section>
</section>
<section id="json-output">
<h2>JSON OUTPUT<a class="headerlink" href="#json-output" title="Permalink to this headline">¶</a></h2>
<p>Universal Ctags supports <a class="reference external" href="https://www.json.org/">JSON</a> (strictly
speaking <a class="reference external" href="https://jsonlines.org/">JSON Lines</a>) output format if the
ctags executable is built with <code class="docutils literal notranslate"><span class="pre">libjansson</span></code>. JSON output goes to
standard output by default.</p>
<section id="format">
<h3>Format<a class="headerlink" href="#format" title="Permalink to this headline">¶</a></h3>
<p>Each JSON line represents a tag.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --extras<span class="o">=</span>+p --output-format<span class="o">=</span>json --fields<span class="o">=</span>-s input.py
<span class="go">{"_type": "ptag", "name": "JSON_OUTPUT_VERSION", "path": "0.0", "pattern": "in development"}</span>
<span class="go">{"_type": "ptag", "name": "TAG_FILE_SORTED", "path": "1", "pattern": "0=unsorted, 1=sorted, 2=foldcase"}</span>
<span class="go">...</span>
<span class="go">{"_type": "tag", "name": "Klass", "path": "/tmp/input.py", "pattern": "/^class Klass:$/", "language": "Python", "kind": "class"}</span>
<span class="go">{"_type": "tag", "name": "method", "path": "/tmp/input.py", "pattern": "/^ def method(self):$/", "language": "Python", "kind": "member", "scope": "Klass", "scopeKind": "class"}</span>
<span class="go">...</span>
</pre></div>
</div>
<p>A key not starting with <code class="docutils literal notranslate"><span class="pre">_</span></code> is mapped to a field of ctags.
“<code class="docutils literal notranslate"><span class="pre">--output-format=json</span> <span class="pre">--list-fields</span></code>” options list the fields.</p>
<p>A key starting with <code class="docutils literal notranslate"><span class="pre">_</span></code> represents meta information of the JSON
line. Currently only <code class="docutils literal notranslate"><span class="pre">_type</span></code> key is used. If the value for the key
is <code class="docutils literal notranslate"><span class="pre">tag</span></code>, the JSON line represents a normal tag. If the value is
<code class="docutils literal notranslate"><span class="pre">ptag</span></code>, the line represents a pseudo-tag.</p>
<p>The output format can be changed in the
future. <code class="docutils literal notranslate"><span class="pre">JSON_OUTPUT_VERSION</span></code> pseudo-tag provides a change
client-tools to handle the changes. Current version is “0.0”. A
client-tool can extract the version with <code class="docutils literal notranslate"><span class="pre">path</span></code> key from the
pseudo-tag.</p>
<p>The JSON output format is newly designed and has no limitation found
in the default tags file format.</p>
<ul class="simple">
<li><p>The values for <code class="docutils literal notranslate"><span class="pre">kind</span></code> key are represented in long-name flags.
No one-letter is here.</p></li>
<li><p>Scope names and scope kinds have distinguished keys: <code class="docutils literal notranslate"><span class="pre">scope</span></code> and <code class="docutils literal notranslate"><span class="pre">scopeKind</span></code>.
They are combined in the default tags file format.</p></li>
</ul>
</section>
<section id="data-type-used-in-a-field">
<h3>Data type used in a field<a class="headerlink" href="#data-type-used-in-a-field" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>“<code class="docutils literal notranslate"><span class="pre">--output-format=json</span> <span class="pre">--list-fields</span></code>” options show What kind of data type
used in a field of JSON.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --output-format<span class="o">=</span>json --list-fields
<span class="gp">#</span>LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION
<span class="go">F input yes NONE s-- no input file</span>
<span class="go">...</span>
<span class="go">P pattern yes NONE s-b no pattern</span>
<span class="go">...</span>
<span class="go">f file yes NONE --b no File-restricted scoping</span>
<span class="go">...</span>
<span class="go">e end no NONE -i- no end lines of various items</span>
<span class="go">...</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">JSTYPE</span></code> column shows the data types.</p>
<dl class="simple">
<dt>‘<code class="docutils literal notranslate"><span class="pre">s</span></code>’</dt><dd><p>string</p>
</dd>
<dt>‘<code class="docutils literal notranslate"><span class="pre">i</span></code>’</dt><dd><p>integer</p>
</dd>
<dt>‘<code class="docutils literal notranslate"><span class="pre">b</span></code>’</dt><dd><p>boolean (true or false)</p>
</dd>
</dl>
<p>For an example, the value for <code class="docutils literal notranslate"><span class="pre">pattern</span></code> field of ctags takes a string or a boolean value.</p>
</section>
</section>
<section id="see-also">
<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, <a class="reference internal" href="ctags-lang-python.7.html#ctags-lang-python-7"><span class="std std-ref">ctags-lang-python(7)</span></a>, <a class="reference internal" href="ctags-incompatibilities.7.html#ctags-incompatibilities-7"><span class="std std-ref">ctags-incompatibilities(7)</span></a>, <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>, <a class="reference internal" href="readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a></p>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">ctags-client-tools</a><ul>
<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li>
<li><a class="reference internal" href="#description">DESCRIPTION</a></li>
<li><a class="reference internal" href="#pseudo-tags">PSEUDO-TAGS</a><ul>
<li><a class="reference internal" href="#options-for-pseudo-tags">Options for Pseudo-tags</a></li>
<li><a class="reference internal" href="#list-of-notable-pseudo-tags">List of notable pseudo-tags</a></li>
</ul>
</li>
<li><a class="reference internal" href="#redundant-kinds">REDUNDANT-KINDS</a></li>
<li><a class="reference internal" href="#multiple-languages-for-an-input-file">MULTIPLE-LANGUAGES FOR AN INPUT FILE</a></li>
<li><a class="reference internal" href="#utilizing-readtags">UTILIZING READTAGS</a><ul>
<li><a class="reference internal" href="#build-filter-sorter-expressions">Build Filter/Sorter Expressions</a></li>
<li><a class="reference internal" href="#parse-readtags-output">Parse Readtags Output</a></li>
<li><a class="reference internal" href="#make-use-of-the-pattern-field">Make Use of the Pattern Field</a></li>
<li><a class="reference internal" href="#remark-about-a-previous-format-of-the-pattern-field">Remark: About a Previous Format of the Pattern Field</a></li>
</ul>
</li>
<li><a class="reference internal" href="#json-output">JSON OUTPUT</a><ul>
<li><a class="reference internal" href="#format">Format</a></li>
<li><a class="reference internal" href="#data-type-used-in-a-field">Data type used in a field</a></li>
</ul>
</li>
<li><a class="reference internal" href="#see-also">SEE ALSO</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="ctags-optlib.7.html"
title="previous chapter">ctags-optlib</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="ctags-faq.7.html"
title="next chapter">ctags-faq</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="ctags-faq.7.html" title="ctags-faq"
>next</a> |</li>
<li class="right" >
<a href="ctags-optlib.7.html" title="ctags-optlib"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li>
<li class="nav-item nav-item-this"><a href="">ctags-client-tools</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2015, Universal Ctags Team.
Last updated on 11 Jun 2021.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2.
</div>
</body>
</html>
|
