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 [OPTION]... ACTION
12
15 The readtags program filters, sorts and prints tag entries in a tags
16 file. The basic filtering is done using actions, by which you can list
17 all regular tags, pseudo tags or regular tags matching specific name.
18 Then, further filtering, sorting, and formatting can be done using post
19 processors, namely filter expressions, sorter expressions, and format‐
20 ter expressions.
21
23 -l, --list
24 List regular tags.
25 [-] NAME
27 List regular tags matching NAME. "-" as NAME indicates argu‐
28 ments after this as NAME even if they start with -.
29 -D, --list-pseudo-tags
31 Equivalent to --list-pseudo-tags.
32
34 Controlling the Tags Reading Behavior
35 The behavior of reading tags can be controlled using these options:
36 -t TAGFILE, --tag-file TAGFILE
38 Use specified tag file (default: "tags"). Giving "-" as TAGFILE
39 indicates reading the tags file content from the standard input.
40 "-" can make the command line simpler. However, it doesn't mean
41 efficient; readtags stores the data to a temorary file and reads
42 that file for taking the ACTION.
43 -s[0|1|2], --override-sort-detection METHOD
45 Override sort detection of tag file. METHOD: un‐
46 sorted|sorted|foldcase
47 The NAME action will perform binary search on sorted (including "fold‐
49 case") tags files, which is much faster then on unsorted tags files.
50 Controlling the NAME Action Behavior
52 The behavior of the NAME action can be controlled using these options:
53 -i, --icase-match
55 Perform case-insensitive matching in the NAME action.
56 -p, --prefix-match
58 Perform prefix matching in the NAME action.
59 Controlling the Output
61 By default, the output of readtags contains only the name, input and
62 pattern field. The Output can be tweaked using these options:
63 -d, --debug
65 Turn on debugging output.
66 -E, --escape-output
68 Escape characters like tabs in output as described in tags(5).
69 -e, --extension-fields
71 Include extension fields in output.
72 -n, --line-number
74 Also include the line number field when -e option is give.
75 About the -E option: certain characters are escaped in a tags file, to
77 make it machine-readable. e.g., ensuring no tabs character appear in
78 fields other than the pattern field. By default, readtags translates
79 them to make it human-readable, but when utilizing readtags output in a
80 script or a client tool, -E option should be used. See
81 ctags-client-tools(7) for more discussion on this.
82 Filtering, Sorting, and Formatting
84 Further filtering, sorting, and formatting on the tags listed by ac‐
85 tions are performed using:
86 -Q EXP, --filter EXP
88 Filter the tags listed by ACTION with EXP before printing.
89 -S EXP, --sorter EXP
91 Sort the tags listed by ACTION with EXP before printing.
92 -F EXP, --formatter EXP
94 Format the tags listed by ACTION with EXP when printing.
95 These are discussed in the EXPRESSION section.
97 Examples
99 • List all tags in "/path/to/tags":
100 $ readtags -t /path/to/tags -l
102 • List all tags in "tags" that start with "mymethod":
104 $ readtags -p - mymethod
106 • List all tags matching "mymethod", case insensitively:
108 $ readtags -i - mymethod
110 • List all tags start with "myvar", and printing all fields (i.e., the
112 whole line):
113 $ readtags -p -ne - myvar
115
117 Scheme-style expressions are used for the -Q, -S, and -F options. For
118 those who doesn't know Scheme or Lisp, just remember:
119 • A function call is wrapped in a pair of parenthesis. The first item
121 in it is the function/operator name, the others are arguments.
122 • Function calls can be nested.
124 • Missing values and boolean false are represented by #f. #t and all
126 other values are considered to be true.
127 So, (+ 1 (+ 2 3)) means add 2 and 3 first, then add the result with 1.
129 (and "string" 1 #t) means logical AND on "string", 1 and #t, and the
130 result is true since there is no #f.
131 Filtering
133 The tag entries that make the filter expression produces true value are
134 printed by readtags.
135 The basic operators for filtering are eq?, prefix?, suffix?, substr?,
137 and #/PATTERN/. Language common fields can be accessed using variables
138 starting with $, e.g., $language represents the language field. For
139 example:
140 • List all tags start with "myfunc" in Python code files:
142 $ readtags -p -Q '(eq? $language "Python")' - myfunc
144 downcase or upcase operators can be used to perform case-insensitive
146 matching:
147 • List all tags containing "my", case insensitively:
149 $ readtags -Q '(substr? (downcase $name) "my")' -l
151 We have logical operators like and, or and not. The value of a missing
153 field is #f, so we could deal with missing fields:
154 • List all tags containing "impl" in Python code files, but allow the
156 language: field to be missing:
157 $ readtags -Q '(and (substr? $name "impl")\
159 (or (not $language)\
160 (eq? $language "Python")))' -l
161 #/PATTERN/ is for the case when string predicates (prefix?, suffix?,
163 and substr?) are not enough. You can use "Posix extended regular ex‐
164 pression" as PATTERN.
165 • List all tags inherits from the class "A":
167 $ readtags -Q '(#/(^|,) ?A(,|$)/ $inherits)' -l
169 Here $inherits is a comma-separated class list like "A,B,C", "P, A, Q",
171 or just "A". Notice that this filter works on both situations where
172 there's a space after each comma or there's not.
173 Case-insensitive matching can be performed by #/PATTERN/i:
175 • List all tags inherits from the class "A" or "a":
177 $ readtags -Q '(#/(^|,) ?A(,|$)/i $inherits)' -l
179 To include "/" in a pattern, prefix \ to the "/".
181 NOTE: The above regular expression pattern for inspecting inheritances
183 is just an example to show how to use #/PATTERN/ expression. Tags file
184 generators have no consensus about the format of inherits:, e.g.,
185 whether there should be a space after a comma. Even parsers in ctags
186 have no consensus. Noticing the format of the inherits: field of spe‐
187 cific languages is needed for such queries.
188 The expressions #/PATTERN/ and #/PATTERN/i are for interactive use.
190 Readtags also offers an alias string->regexp, so #/PATTERN/ is equal to
191 (string->regexp "PATTERN"), and #/PATTERN/i is equal to (string->regexp
192 "PATTERN" :case-fold #t). string->regexp doesn't need to prefix \ for
193 including "/" in a pattern. string->regexp may simplify a client tool
194 building an expression. See also ctags-client-tools(7) for building ex‐
195 pressions in your tool.
196 Let's now consider missing fields. The tags file may have tag entries
198 that has no inherits: field. In that case $inherits is #f, and the reg‐
199 ular expression matching raises an error, since string operators only
200 work for strings. To avoid this problem:
201 • Safely list all tags inherits from the class "A":
203 $ readtags -Q '(and $inherits (#/(^|,) ?A(,|$)/ $inherits))' -l
205 This makes sure $inherits is not missing first, then match it by reg‐
207 exp.
208 Sometimes you want to keep tags where the field is missing. For exam‐
210 ple, your want to exclude reference tags, which is marked by the ex‐
211 tras: field, then you want to keep tags who doesn't have extras: field
212 since they are also not reference tags. Here's how to do it:
213 • List all tags but the reference tags:
215 $ readtags -Q '(or (not $extras) (#/(^|,) ?reference(,|$)/ $extras))' -l
217 Notice that (not $extras) produces #t when $extras is missing, so the
219 whole or expression produces #t.
220 The combination of ctags -o - and readtags -t - is handy for inspecting
222 a source file as far as the source file is enough short.
223 • List all the large (> 100 lines) functions in a file:
225 $ ctags -o - --fields=+neKz input.c \
227 | ./readtags -t - -en \
228 -Q '(and (eq? $kind "function") $end $line (> (- $end $line) 100))' \
229 -l
230 • List all the tags including line 80 in a file:
232 $ ctags -o - --fields=+neKz input.c \
234 | readtags -t - -ne \
235 -Q '(and $line
236 (or (eq? $line 80)
237 (and $end (< $line 80) (< 80 $end))))' \
238 -l
239 Run "readtags -H filter" to know about all valid functions and vari‐
241 ables.
242 Sorting
244 When sorting, the sorter expression is evaluated on two tag entries to
245 decide which should sort before the other one, until the order of all
246 tag entries is decided.
247 In a sorter expression, $ and & are used to access the fields in the
249 two tag entries, and let's call them $-entry and &-entry. The sorter
250 expression should have a value of -1, 0 or 1. The value -1 means the
251 $-entry should be put above the &-entry, 1 means the contrary, and 0
252 makes their order in the output uncertain.
253 The core operator of sorting is <>. It's used to compare two strings or
255 two numbers (numbers are for the line: or end: fields). In (<> a b), if
256 a < b, the result is -1; a > b produces 1, and a = b produces 0.
257 Strings are compared using the strcmp function, see strcmp(3).
258 For example, sort by names, and make those shorter or alphabetically
260 smaller ones appear before the others:
261 $ readtags -S '(<> $name &name)' -l
263 This reads "If the tag name in the $-entry is smaller, it goes before
265 the &-entry".
266 The <or> operator is used to chain multiple expressions until one re‐
268 turns -1 or 1. For example, sort by input file names, then line numbers
269 if in the same file:
270 $ readtags -S '(<or> (<> $input &input) (<> $line &line))' -l
272 The *- operator is used to flip the compare result. i.e., (*- (<> a b))
274 is the same as (<> b a).
275 Filter expressions can be used in sorter expressions. The technique is
277 use if to produce integers that can be compared based on the filter,
278 like:
279 (<> (if filter-expr-on-$-entry -1 1)
281 (if filter-expr-on-&-entry -1 1))
282 So if $-entry satisfies the filter, while &-entry doesn't, it's the
284 same as (<> -1 1), which produces -1.
285 For example, we want to put tags with "file" kind below other tags,
287 then the sorter would look like:
288 (<> (if (eq? $kind "file") 1 -1)
290 (if (eq? &kind "file") 1 -1))
291 A quick read tells us: If $-entry has "file" kind, and &-entry doesn't,
293 the sorter becomes (<> 1 -1), which produces 1, so the $-entry is put
294 below the &-entry, exactly what we want.
295 Formatting
297 A formatter expression defines how readtags prints tag entries.
298 A formatter expression may produce a string, a boolean, an integer, or
300 a list. Readtags prints the produced string, and integer as is. Read‐
301 tags prints nothing for #f, and a newline for #t.
302 A list could contain any number of strings, booleans, integers, and/or
304 lists. Readtags prints the elements of a list sequentially and recur‐
305 sively.
306 All the operators for filtering are also available in formatter expres‐
308 sions. In addition to the operators, list is available in formatter ex‐
309 pressions. As the name shows, list is for making a list. list makes a
310 list containing arguments passed to the operator. e.g., the following
311 expression makes a list contains 1, #f, and "hello":
312 (list 1 #f "hello")
314 NOTE: Unlike real-Lisp, backquote constructs are not available.
316 To show some examples, the following tags file (output.tags) is assumed
318 as input for readtags:
319 M input.c 4;" macro file:
321 N input.c 3;" macro file:
322 bar input.c 11;" f typeref:typename:void file: signature:(char ** argv,int * r)
323 foo input.c 6;" f typeref:typename:int file: signature:(int v)
324 main input.c 16;" f typeref:typename:int signature:(int argc,char ** argv)
325 An exapmle for printing only function names:
327 $ readtags -t output.tags -Q '(eq? $kind "function")' -F '(list $name #t)' -l
329 bar
330 foo
331 main
332 Doing the same only with a formatter expression:
334 $ readtags -t output.tags -F '(if (eq? $kind "function") (list $name #t) #f)' -l
336 bar
337 foo
338 main
339 Generating declarations for the functions:
341 $ readtags -t output.tags -F \
343 '(if (eq? $kind "function")
344 (list (if $file "static " #f) $typeref-name " " $name $signature ";" #t)
345 #f)' -l
346 static void bar(char ** argv,int * r);
347 static int foo(int v);
348 int main(int argc,char ** argv);
349 Inspecting the Behavior of Expressions
351 The print operator can be used to print the value of an expression. For
352 example:
353 $ readtags -Q '(print $name)' -l
355 prints the name of each tag entry before it. Since the return value of
357 print is not #f, all the tag entries are printed. We could control this
358 using the begin or begin0 operator. begin returns the value of its last
359 argument, and begin0 returns the value of its first argument. For exam‐
360 ple:
361 $ readtags -Q '(begin0 #f (print (prefix? "ctags" "ct")))' -l
363 prints a bunch of "#t" (depending on how many lines are in the tags
365 file), and the actual tag entries are not printed.
366
368 See tags(5) for the details of tags file format.
369 See ctags-client-tools(7) for the tips writing a tool utilizing tags
371 file.
372 The official Universal Ctags web site at:
374 https://ctags.io/
376 The git repository for the library used in readtags command:
378 https://github.com/universal-ctags/libreadtags
380
382 Universal Ctags project https://ctags.io/
383 Darren Hiebert <dhiebert@users.sourceforge.net>
385 http://DarrenHiebert.com/
386 The readtags command and libreadtags maintained at Universal Ctags are
388 derived from readtags.c and readtags.h developd at
389 http://ctags.sourceforge.net.
3905.9.0 READTAGS(1)