readtags(1)

1READTAGS(1)                     Universal Ctags                    READTAGS(1)
2
3
4

NAME

6       readtags - Find tag file entries matching specified names
7

SYNOPSIS

9       readtags -h | --help
10       readtags (-H | --help-expression) (filter|sorter)
11       readtags [OPTION]... ACTION
12
13

DESCRIPTION

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 and sorting can be done using post  processors,
19       namely filter expressions and sorter expressions.
20

ACTIONS

22       -l, --list
23              List regular tags.
24
25       [-] NAME
26              List  regular  tags  matching NAME.  "-" as NAME indicates argu‐
27              ments after this as NAME even if they start with -.
28
29       -D, --list-pseudo-tags
30              Equivalent to --list-pseudo-tags.
31

OPTIONS

33   Controlling the Tags Reading Behavior
34       The behavior of reading tags can be controlled using these options:
35
36       -t TAGFILE, --tag-file TAGFILE
37              Use specified tag file (default: "tags").
38
39       -s[0|1|2], --override-sort-detection METHOD
40              Override   sort   detection   of   tag   file.    METHOD:    un‐
41              sorted|sorted|foldcase
42
43       The  NAME action will perform binary search on sorted (including "fold‐
44       case") tags files, which is much faster then on unsorted tags files.
45
46   Controlling the NAME Action Behavior
47       The behavior of the NAME action can be controlled using these options:
48
49       -i, --icase-match
50              Perform case-insensitive matching in the NAME action.
51
52       -p, --prefix-match
53              Perform prefix matching in the NAME action.
54
55   Controlling the Output
56       By default, the output of readtags contains only the  name,  input  and
57       pattern field. The Output can be tweaked using these options:
58
59       -d, --debug
60              Turn on debugging output.
61
62       -E, --escape-output
63              Escape characters like tabs in output as described in tags(5).
64
65       -e, --extension-fields
66              Include extension fields in output.
67
68       -n, --line-number
69              Also include the line number field when -e option is give.
70
71       About  the -E option: certain characters are escaped in a tags file, to
72       make it machine-readable. e.g., ensuring no tabs  character  appear  in
73       fields  other  than  the pattern field. By default, readtags translates
74       them to make it human-readable, but when utilizing readtags output in a
75       script   or   a   client   tool,   -E   option   should  be  used.  See
76       ctags-client-tools(7) for more discussion on this.
77
78   Filtering and Sorting
79       Further filtering and sorting on the tags listed by  actions  are  per‐
80       formed using:
81
82       -Q EXP, --filter EXP
83              Filter the tags listed by ACTION with EXP before printing.
84
85       -S EXP, --sorter EXP
86              Sort the tags listed by ACTION with EXP before printing.
87
88       These are discussed in the EXPRESSION section.
89
90   Examples
91       • List all tags in "/path/to/tags":
92
93            $ readtags -t /path/to/tags -l
94
95       • List all tags in "tags" that start with "mymethod":
96
97            $ readtags -p - mymethod
98
99       • List all tags matching "mymethod", case insensitively:
100
101            $ readtags -i - mymethod
102
103       • List  all tags start with "myvar", and printing all fields (i.e., the
104         whole line):
105
106            $ readtags -p -ne - myvar
107

EXPRESSION

109       Scheme-style expressions are used for the -Q and -S options. For  those
110       who doesn't know Scheme or Lisp, just remember:
111
112       • A  function  call is wrapped in a pair of parenthesis. The first item
113         in it is the function/operator name, the others are arguments.
114
115       • Function calls can be nested.
116
117       • Missing values and boolean false are represented by #f.  #t  and  all
118         other values are considered to be true.
119
120       So,  (+ 1 (+ 2 3)) means add 2 and 3 first, then add the result with 1.
121       (and "string" 1 #t) means logical AND on "string", 1 and  #t,  and  the
122       result is true since there is no #f.
123
124   Filtering
125       The tag entries that make the filter expression produces true value are
126       printed by readtags.
127
128       The basic operators for filtering are eq?, prefix?,  suffix?,  substr?,
129       and  #/PATTERN/. Language common fields can be accessed using variables
130       starting with $, e.g., $language represents the  language  field.   For
131       example:
132
133       • List all tags start with "myfunc" in Python code files:
134
135            $ readtags -p -Q '(eq? $language "Python")' - myfunc
136
137       downcase  or  upcase  operators can be used to perform case-insensitive
138       matching:
139
140       • List all tags containing "my", case insensitively:
141
142                $ readtags -Q '(substr? (downcase $name) "my")' -l
143
144       We have logical operators like and, or and not. The value of a  missing
145       field is #f, so we could deal with missing fields:
146
147       • List  all  tags containing "impl" in Python code files, but allow the
148         language: field to be missing:
149
150            $ readtags -Q '(and (substr? $name "impl")\
151                                (or (not $language)\
152                                    (eq? $language "Python")))' -l
153
154       #/PATTERN/ is for the case when string  predicates  (prefix?,  suffix?,
155       and  substr?)  are  not enough. You can use "Posix extended regular ex‐
156       pression" as PATTERN.
157
158       • List all tags inherits from the class "A":
159
160            $ readtags -Q '(#/(^|,) ?A(,|$)/ $inherits)' -l
161
162       Here $inherits is a comma-separated class list like "A,B,C", "P, A, Q",
163       or  just  "A".  Notice  that this filter works on both situations where
164       there's a space after each comma or there's not.
165
166       Case-insensitive matching can be performed by #/PATTERN/i:
167
168       • List all tags inherits from the class "A" or "a":
169
170            $ readtags -Q '(#/(^|,) ?A(,|$)/i $inherits)' -l
171
172       To include "/" in a pattern, prefix \ to the "/".
173
174       NOTE: The above regular expression pattern for inspecting  inheritances
175       is  just an example to show how to use #/PATTERN/ expression. Tags file
176       generators have no consensus  about  the  format  of  inherits:,  e.g.,
177       whether  there  should  be a space after a comma. Even parsers in ctags
178       have no consensus. Noticing the format of the inherits: field  of  spe‐
179       cific languages is needed for such queries.
180
181       The  expressions  #/PATTERN/  and  #/PATTERN/i are for interactive use.
182       Readtags also offers an alias string->regexp, so #/PATTERN/ is equal to
183       (string->regexp "PATTERN"), and #/PATTERN/i is equal to (string->regexp
184       "PATTERN" :case-fold #t). string->regexp doesn't need to prefix  \  for
185       including  "/"  in a pattern. string->regexp may simplify a client tool
186       building an expression. See also ctags-client-tools(7) for building ex‐
187       pressions in your tool.
188
189       Let's  now  consider missing fields. The tags file may have tag entries
190       that has no inherits: field. In that case $inherits is #f, and the reg‐
191       ular  expression  matching raises an error, since string operators only
192       work for strings. To avoid this problem:
193
194       • Safely list all tags inherits from the class "A":
195
196            $ readtags -Q '(and $inherits (#/(^|,) ?A(,|$)/ $inherits))' -l
197
198       This makes sure $inherits is not missing first, then match it  by  reg‐
199       exp.
200
201       Sometimes  you  want to keep tags where the field is missing. For exam‐
202       ple, your want to exclude reference tags, which is marked  by  the  ex‐
203       tras:  field, then you want to keep tags who doesn't have extras: field
204       since they are also not reference tags. Here's how to do it:
205
206       • List all tags but the reference tags:
207
208            $ readtags -Q '(or (not $extras) (#/(^|,) ?reference(,|$)/ $extras))' -l
209
210       Notice that (not $extras) produces #t when $extras is missing,  so  the
211       whole or expression produces #t.
212
213       Run  "readtags  -H  filter" to know about all valid functions and vari‐
214       ables.
215
216   Sorting
217       When sorting, the sorter expression is evaluated on two tag entries  to
218       decide  which  should sort before the other one, until the order of all
219       tag entries is decided.
220
221       In a sorter expression, $ and & are used to access the  fields  in  the
222       two  tag  entries,  and let's call them $-entry and &-entry. The sorter
223       expression should have a value of -1, 0 or 1. The value  -1  means  the
224       $-entry  should  be  put above the &-entry, 1 means the contrary, and 0
225       makes their order in the output uncertain.
226
227       The core operator of sorting is <>. It's used to compare two strings or
228       two numbers (numbers are for the line: or end: fields). In (<> a b), if
229       a < b, the result is -1; a > b produces  1,  and  a  =  b  produces  0.
230       Strings are compared using the strcmp function, see strcmp(3).
231
232       For  example,  sort  by names, and make those shorter or alphabetically
233       smaller ones appear before the others:
234
235          $ readtags -S '(<> $name &name)' -l
236
237       This reads "If the tag name in the $-entry is smaller, it  goes  before
238       the &-entry".
239
240       The  <or>  operator is used to chain multiple expressions until one re‐
241       turns -1 or 1. For example, sort by input file names, then line numbers
242       if in the same file:
243
244          $ readtags -S '(<or> (<> $input &input) (<> $line &line))' -l
245
246       The *- operator is used to flip the compare result. i.e., (*- (<> a b))
247       is the same as (<> b a).
248
249       Filter expressions can be used in sorter expressions. The technique  is
250       use  if  to  produce integers that can be compared based on the filter,
251       like:
252
253          (<> (if filter-expr-on-$-entry -1 1)
254              (if filter-expr-on-&-entry -1 1))
255
256       So if $-entry satisfies the filter, while  &-entry  doesn't,  it's  the
257       same as (<> -1 1), which produces -1.
258
259       For  example,  we  want  to put tags with "file" kind below other tags,
260       then the sorter would look like:
261
262          (<> (if (eq? $kind "file") 1 -1)
263              (if (eq? &kind "file") 1 -1))
264
265       A quick read tells us: If $-entry has "file" kind, and &-entry doesn't,
266       the  sorter  becomes (<> 1 -1), which produces 1, so the $-entry is put
267       below the &-entry, exactly what we want.
268
269   Inspecting the Behavior of Expressions
270       The print operator can be used to print the value of an expression. For
271       example:
272
273          $ readtags -Q '(print $name)' -l
274
275       prints  the name of each tag entry before it. Since the return value of
276       print is not #f, all the tag entries are printed. We could control this
277       using the begin or begin0 operator. begin returns the value of its last
278       argument, and begin0 returns the value of its first argument. For exam‐
279       ple:
280
281          $ readtags -Q '(begin0 #f (print (prefix? "ctags" "ct")))' -l
282
283       prints  a  bunch  of  "#t" (depending on how many lines are in the tags
284       file), and the actual tag entries are not printed.
285

CREDITS

301       Universal Ctags project https://ctags.io/
302
303       Darren             Hiebert             <dhiebert@users.sourceforge.net>
304       http://DarrenHiebert.com/
305
306       The readtags command and libreadtags maintained at Universal Ctags  are
307       derived     from     readtags.c     and    readtags.h    developd    at
308       http://ctags.sourceforge.net.
309
310
311
312
3135.9.0                                                              READTAGS(1)