1READTAGS(1) Universal Ctags READTAGS(1)
2
6 readtags - Find tag file entries matching specified names
7
9 readtags -h | --help
10 readtags (-H | --help-expression) (filter|sorter|formatter)
11 readtags -v | --version
12 readtags [OPTION]... ACTION
13
16 The readtags program filters, sorts and prints tag entries in a tags
17 file. The basic filtering is done using actions, by which you can list
18 all regular tags, pseudo tags or regular tags matching specific name.
19 Then, further filtering, sorting, and formatting can be done using post
20 processors, namely filter expressions, sorter expressions, and format‐
21 ter expressions.
22
24 -l, --list
25 List regular tags.
26 [-] NAME
28 List regular tags matching NAME. "-" as NAME indicates argu‐
29 ments after this as NAME even if they start with -.
30 -D, --list-pseudo-tags
32 Equivalent to --list-pseudo-tags.
33
35 Controlling the Tags Reading Behavior
36 The behavior of reading tags can be controlled using these options:
37 -t TAGFILE, --tag-file TAGFILE
39 Use specified tag file (default: "tags"). Giving "-" as TAGFILE
40 indicates reading the tags file content from the standard input.
41 "-" can make the command line simpler. However, it doesn't mean
42 efficient; readtags stores the data to a temorary file and reads
43 that file for taking the ACTION.
44 -s[0|1|2], --override-sort-detection METHOD
46 Override sort detection of tag file. METHOD: un‐
47 sorted|sorted|foldcase
48 The NAME action will perform binary search on sorted (including "fold‐
50 case") tags files, which is much faster then on unsorted tags files.
51 Controlling the NAME Action Behavior
53 The behavior of the NAME action can be controlled using these options:
54 -i, --icase-match
56 Perform case-insensitive matching in the NAME action.
57 -p, --prefix-match
59 Perform prefix matching in the NAME action.
60 Controlling the Output
62 By default, the output of readtags contains only the name, input and
63 pattern field. The Output can be tweaked using these options:
64 -d, --debug
66 Turn on debugging output.
67 -E, --escape-output
69 Escape characters like tabs in output as described in tags(5).
70 -e, --extension-fields
72 Include extension fields in output.
73 -n, --line-number
75 Also include the line number field when -e option is give.
76 About the -E option: certain characters are escaped in a tags file, to
78 make it machine-readable. e.g., ensuring no tabs character appear in
79 fields other than the pattern field. By default, readtags translates
80 them to make it human-readable, but when utilizing readtags output in a
81 script or a client tool, -E option should be used. See
82 ctags-client-tools(7) for more discussion on this.
83 Filtering, Sorting, and Formatting
85 Further filtering, sorting, and formatting on the tags listed by ac‐
86 tions are performed using:
87 -Q EXP, --filter EXP
89 Filter the tags listed by ACTION with EXP before printing.
90 -S EXP, --sorter EXP
92 Sort the tags listed by ACTION with EXP before printing.
93 -F EXP, --formatter EXP
95 Format the tags listed by ACTION with EXP when printing.
96 These are discussed in the EXPRESSION section.
98 Examples
100 • List all tags in "/path/to/tags":
101 $ readtags -t /path/to/tags -l
103 • List all tags in "tags" that start with "mymethod":
105 $ readtags -p - mymethod
107 • List all tags matching "mymethod", case insensitively:
109 $ readtags -i - mymethod
111 • List all tags start with "myvar", and printing all fields (i.e., the
113 whole line):
114 $ readtags -p -ne - myvar
116
118 Scheme-style expressions are used for the -Q, -S, and -F options. For
119 those who doesn't know Scheme or Lisp, just remember:
120 • A function call is wrapped in a pair of parenthesis. The first item
122 in it is the function/operator name, the others are arguments.
123 • Function calls can be nested.
125 • Missing values and boolean false are represented by #f. #t and all
127 other values are considered to be true.
128 So, (+ 1 (+ 2 3)) means add 2 and 3 first, then add the result with 1.
130 (and "string" 1 #t) means logical AND on "string", 1 and #t, and the
131 result is true since there is no #f.
132 Filtering
134 The tag entries that make the filter expression produces true value are
135 printed by readtags.
136 The basic operators for filtering are eq?, prefix?, suffix?, substr?,
138 and #/PATTERN/. Language common fields can be accessed using variables
139 starting with $, e.g., $language represents the language field. For
140 example:
141 • List all tags start with "myfunc" in Python code files:
143 $ readtags -p -Q '(eq? $language "Python")' - myfunc
145 downcase or upcase operators can be used to perform case-insensitive
147 matching:
148 • List all tags containing "my", case insensitively:
150 $ readtags -Q '(substr? (downcase $name) "my")' -l
152 We have logical operators like and, or and not. The value of a missing
154 field is #f, so we could deal with missing fields:
155 • List all tags containing "impl" in Python code files, but allow the
157 language: field to be missing:
158 $ readtags -Q '(and (substr? $name "impl")\
160 (or (not $language)\
161 (eq? $language "Python")))' -l
162 #/PATTERN/ is for the case when string predicates (prefix?, suffix?,
164 and substr?) are not enough. You can use "Posix extended regular ex‐
165 pression" as PATTERN.
166 • List all tags inherits from the class "A":
168 $ readtags -Q '(#/(^|,) ?A(,|$)/ $inherits)' -l
170 Here $inherits is a comma-separated class list like "A,B,C", "P, A, Q",
172 or just "A". Notice that this filter works on both situations where
173 there's a space after each comma or there's not.
174 Case-insensitive matching can be performed by #/PATTERN/i:
176 • List all tags inherits from the class "A" or "a":
178 $ readtags -Q '(#/(^|,) ?A(,|$)/i $inherits)' -l
180 To include "/" in a pattern, prefix \ to the "/".
182 NOTE: The above regular expression pattern for inspecting inheritances
184 is just an example to show how to use #/PATTERN/ expression. Tags file
185 generators have no consensus about the format of inherits:, e.g.,
186 whether there should be a space after a comma. Even parsers in ctags
187 have no consensus. Noticing the format of the inherits: field of spe‐
188 cific languages is needed for such queries.
189 The expressions #/PATTERN/ and #/PATTERN/i are for interactive use.
191 Readtags also offers an alias string->regexp, so #/PATTERN/ is equal to
192 (string->regexp "PATTERN"), and #/PATTERN/i is equal to (string->regexp
193 "PATTERN" :case-fold #t). string->regexp doesn't need to prefix \ for
194 including "/" in a pattern. string->regexp may simplify a client tool
195 building an expression. See also ctags-client-tools(7) for building ex‐
196 pressions in your tool.
197 Let's now consider missing fields. The tags file may have tag entries
199 that has no inherits: field. In that case $inherits is #f, and the reg‐
200 ular expression matching raises an error, since string operators only
201 work for strings. To avoid this problem:
202 • Safely list all tags inherits from the class "A":
204 $ readtags -Q '(and $inherits (#/(^|,) ?A(,|$)/ $inherits))' -l
206 This makes sure $inherits is not missing first, then match it by reg‐
208 exp.
209 Sometimes you want to keep tags where the field is missing. For exam‐
211 ple, your want to exclude reference tags, which is marked by the ex‐
212 tras: field, then you want to keep tags who doesn't have extras: field
213 since they are also not reference tags. Here's how to do it:
214 • List all tags but the reference tags:
216 $ readtags -Q '(or (not $extras) (#/(^|,) ?reference(,|$)/ $extras))' -l
218 Notice that (not $extras) produces #t when $extras is missing, so the
220 whole or expression produces #t.
221 The combination of ctags -o - and readtags -t - is handy for inspecting
223 a source file as far as the source file is enough short.
224 • List all the large (> 100 lines) functions in a file:
226 $ ctags -o - --fields=+neKz input.c \
228 | ./readtags -t - -en \
229 -Q '(and (eq? $kind "function") $end $line (> (- $end $line) 100))' \
230 -l
231 • List all the tags including line 80 in a file:
233 $ ctags -o - --fields=+neKz input.c \
235 | readtags -t - -ne \
236 -Q '(and $line
237 (or (eq? $line 80)
238 (and $end (< $line 80) (< 80 $end))))' \
239 -l
240 Run "readtags -H filter" to know about all valid functions and vari‐
242 ables.
243 Sorting
245 When sorting, the sorter expression is evaluated on two tag entries to
246 decide which should sort before the other one, until the order of all
247 tag entries is decided.
248 In a sorter expression, $ and & are used to access the fields in the
250 two tag entries, and let's call them $-entry and &-entry. The sorter
251 expression should have a value of -1, 0 or 1. The value -1 means the
252 $-entry should be put above the &-entry, 1 means the contrary, and 0
253 makes their order in the output uncertain.
254 The core operator of sorting is <>. It's used to compare two strings or
256 two numbers (numbers are for the line: or end: fields). In (<> a b), if
257 a < b, the result is -1; a > b produces 1, and a = b produces 0.
258 Strings are compared using the strcmp function, see strcmp(3).
259 For example, sort by names, and make those shorter or alphabetically
261 smaller ones appear before the others:
262 $ readtags -S '(<> $name &name)' -l
264 This reads "If the tag name in the $-entry is smaller, it goes before
266 the &-entry".
267 The <or> operator is used to chain multiple expressions until one re‐
269 turns -1 or 1. For example, sort by input file names, then line numbers
270 if in the same file:
271 $ readtags -S '(<or> (<> $input &input) (<> $line &line))' -l
273 The *- operator is used to flip the compare result. i.e., (*- (<> a b))
275 is the same as (<> b a).
276 Filter expressions can be used in sorter expressions. The technique is
278 use if to produce integers that can be compared based on the filter,
279 like:
280 (<> (if filter-expr-on-$-entry -1 1)
282 (if filter-expr-on-&-entry -1 1))
283 So if $-entry satisfies the filter, while &-entry doesn't, it's the
285 same as (<> -1 1), which produces -1.
286 For example, we want to put tags with "file" kind below other tags,
288 then the sorter would look like:
289 (<> (if (eq? $kind "file") 1 -1)
291 (if (eq? &kind "file") 1 -1))
292 A quick read tells us: If $-entry has "file" kind, and &-entry doesn't,
294 the sorter becomes (<> 1 -1), which produces 1, so the $-entry is put
295 below the &-entry, exactly what we want.
296 Formatting
298 A formatter expression defines how readtags prints tag entries.
299 A formatter expression may produce a string, a boolean, an integer, or
301 a list. Readtags prints the produced string, and integer as is. Read‐
302 tags prints nothing for #f, and a newline for #t.
303 A list could contain any number of strings, booleans, integers, and/or
305 lists. Readtags prints the elements of a list sequentially and recur‐
306 sively.
307 All the operators for filtering are also available in formatter expres‐
309 sions. In addition to the operators, list is available in formatter ex‐
310 pressions. As the name shows, list is for making a list. list makes a
311 list containing arguments passed to the operator. e.g., the following
312 expression makes a list contains 1, #f, and "hello":
313 (list 1 #f "hello")
315 NOTE: Unlike real-Lisp, backquote constructs are not available.
317 To show some examples, the following tags file (output.tags) is assumed
319 as input for readtags:
320 M input.c 4;" macro file:
322 N input.c 3;" macro file:
323 bar input.c 11;" f typeref:typename:void file: signature:(char ** argv,int * r)
324 foo input.c 6;" f typeref:typename:int file: signature:(int v)
325 main input.c 16;" f typeref:typename:int signature:(int argc,char ** argv)
326 An exapmle for printing only function names:
328 $ readtags -t output.tags -Q '(eq? $kind "function")' -F '(list $name #t)' -l
330 bar
331 foo
332 main
333 Doing the same only with a formatter expression:
335 $ readtags -t output.tags -F '(if (eq? $kind "function") (list $name #t) #f)' -l
337 bar
338 foo
339 main
340 Generating declarations for the functions:
342 $ readtags -t output.tags -F \
344 '(if (eq? $kind "function")
345 (list (if $file "static " #f) $typeref-name " " $name $signature ";" #t)
346 #f)' -l
347 static void bar(char ** argv,int * r);
348 static int foo(int v);
349 int main(int argc,char ** argv);
350 Inspecting the Behavior of Expressions
352 The print operator can be used to print the value of an expression. For
353 example:
354 $ readtags -Q '(print $name)' -l
356 prints the name of each tag entry before it. Since the return value of
358 print is not #f, all the tag entries are printed. We could control this
359 using the begin or begin0 operator. begin returns the value of its last
360 argument, and begin0 returns the value of its first argument. For exam‐
361 ple:
362 $ readtags -Q '(begin0 #f (print (prefix? "ctags" "ct")))' -l
364 prints a bunch of "#t" (depending on how many lines are in the tags
366 file), and the actual tag entries are not printed.
367
369 See tags(5) for the details of tags file format.
370 See ctags-client-tools(7) for the tips writing a tool utilizing tags
372 file.
373 The official Universal Ctags web site at:
375 https://ctags.io/
377 The git repository for the library used in readtags command:
379 https://github.com/universal-ctags/libreadtags
381
383 Universal Ctags project https://ctags.io/
384 Darren Hiebert <dhiebert@users.sourceforge.net>
386 http://DarrenHiebert.com/
387 The readtags command and libreadtags maintained at Universal Ctags are
389 derived from readtags.c and readtags.h developd at
390 http://ctags.sourceforge.net.
3916.0.0 READTAGS(1)