1.. _readtags(1): 2 3============================================================== 4readtags 5============================================================== 6-------------------------------------------------------------- 7Find tag file entries matching specified names 8-------------------------------------------------------------- 9:Version: @VERSION@ 10:Manual group: Universal Ctags 11:Manual section: 1 12 13SYNOPSIS 14-------- 15| **readtags** -h | --help 16| **readtags** (-H | --help-expression) (filter|sorter|formatter) 17| **readtags** [OPTION]... ACTION 18 19DESCRIPTION 20----------- 21The **readtags** program filters, sorts and prints tag entries in a tags file. 22The basic filtering is done using **actions**, by which you can list all 23regular tags, pseudo tags or regular tags matching specific name. Then, further 24filtering, sorting, and formatting can be done using **post processors**, namely 25**filter expressions**, **sorter expressions**, and **formatter expressions**. 26 27ACTIONS 28------- 29``-l``, ``--list`` 30 List regular tags. 31 32``[-] NAME`` 33 List regular tags matching NAME. 34 "-" as NAME indicates arguments after this as NAME even if they start with -. 35 36``-D``, ``--list-pseudo-tags`` 37 Equivalent to ``--list-pseudo-tags``. 38 39OPTIONS 40------- 41 42Controlling the Tags Reading Behavior 43~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 44The behavior of reading tags can be controlled using these options: 45 46``-t TAGFILE``, ``--tag-file TAGFILE`` 47 Use specified tag file (default: "tags"). 48 Giving "-" as TAGFILE indicates reading the tags file content from the 49 standard input. "-" can make the command line simpler. However, 50 it doesn't mean efficient; readtags stores the data to a temorary 51 file and reads that file for taking the ACTION. 52 53``-s[0|1|2]``, ``--override-sort-detection METHOD`` 54 Override sort detection of tag file. 55 METHOD: unsorted|sorted|foldcase 56 57The NAME action will perform binary search on sorted (including "foldcase") 58tags files, which is much faster then on unsorted tags files. 59 60Controlling the NAME Action Behavior 61~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 62The behavior of the NAME action can be controlled using these options: 63 64``-i``, ``--icase-match`` 65 Perform case-insensitive matching in the NAME action. 66 67``-p``, ``--prefix-match`` 68 Perform prefix matching in the NAME action. 69 70Controlling the Output 71~~~~~~~~~~~~~~~~~~~~~~ 72By default, the output of readtags contains only the name, input and pattern 73field. The Output can be tweaked using these options: 74 75``-d``, ``--debug`` 76 Turn on debugging output. 77 78``-E``, ``--escape-output`` 79 Escape characters like tabs in output as described in tags(5). 80 81``-e``, ``--extension-fields`` 82 Include extension fields in output. 83 84``-n``, ``--line-number`` 85 Also include the line number field when ``-e`` option is give. 86 87About the ``-E`` option: certain characters are escaped in a tags file, to make 88it machine-readable. e.g., ensuring no tabs character appear in fields other 89than the pattern field. By default, readtags translates them to make it 90human-readable, but when utilizing readtags output in a script or a client 91tool, ``-E`` option should be used. See ctags-client-tools(7) for more 92discussion on this. 93 94Filtering, Sorting, and Formatting 95~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 96Further filtering, sorting, and formatting on the tags listed by actions 97are performed using: 98 99``-Q EXP``, ``--filter EXP`` 100 Filter the tags listed by ACTION with EXP before printing. 101 102``-S EXP``, ``--sorter EXP`` 103 Sort the tags listed by ACTION with EXP before printing. 104 105``-F EXP``, ``--formatter EXP`` 106 Format the tags listed by ACTION with EXP when printing. 107 108These are discussed in the `EXPRESSION`_ section. 109 110Examples 111~~~~~~~~ 112* List all tags in "/path/to/tags": 113 114 .. code-block:: console 115 116 $ readtags -t /path/to/tags -l 117 118* List all tags in "tags" that start with "mymethod": 119 120 .. code-block:: console 121 122 $ readtags -p - mymethod 123 124* List all tags matching "mymethod", case insensitively: 125 126 .. code-block:: console 127 128 $ readtags -i - mymethod 129 130* List all tags start with "myvar", and printing all fields (i.e., the whole line): 131 132 .. code-block:: console 133 134 $ readtags -p -ne - myvar 135 136EXPRESSION 137---------- 138Scheme-style expressions are used for the ``-Q``, ``-S``, and ``-F`` options. 139For those who doesn't know Scheme or Lisp, just remember: 140 141* A function call is wrapped in a pair of parenthesis. The first item in it is 142 the function/operator name, the others are arguments. 143* Function calls can be nested. 144* Missing values and boolean false are represented by ``#f``. ``#t`` and all 145 other values are considered to be true. 146 147So, ``(+ 1 (+ 2 3))`` means add 2 and 3 first, then add the result with 1. 148``(and "string" 1 #t)`` means logical AND on ``"string"``, ``1`` and ``#t``, 149and the result is true since there is no ``#f``. 150 151Filtering 152~~~~~~~~~ 153The tag entries that make the filter expression produces true value are printed 154by readtags. 155 156The basic operators for filtering are ``eq?``, ``prefix?``, ``suffix?``, 157``substr?``, and ``#/PATTERN/``. Language common fields can be accessed using 158variables starting with ``$``, e.g., ``$language`` represents the language field. 159For example: 160 161* List all tags start with "myfunc" in Python code files: 162 163 .. code-block:: console 164 165 $ readtags -p -Q '(eq? $language "Python")' - myfunc 166 167``downcase`` or ``upcase`` operators can be used to perform case-insensitive 168matching: 169 170* List all tags containing "my", case insensitively: 171 172 .. code-block:: console 173 174 $ readtags -Q '(substr? (downcase $name) "my")' -l 175 176We have logical operators like ``and``, ``or`` and ``not``. The value of a 177missing field is #f, so we could deal with missing fields: 178 179* List all tags containing "impl" in Python code files, but allow the 180 ``language:`` field to be missing: 181 182 .. code-block:: console 183 184 $ readtags -Q '(and (substr? $name "impl")\ 185 (or (not $language)\ 186 (eq? $language "Python")))' -l 187 188``#/PATTERN/`` is for the case when string predicates (``prefix?``, ``suffix?``, 189and ``substr?``) are not enough. You can use "Posix extended regular expression" 190as PATTERN. 191 192* List all tags inherits from the class "A": 193 194 .. code-block:: console 195 196 $ readtags -Q '(#/(^|,) ?A(,|$)/ $inherits)' -l 197 198Here ``$inherits`` is a comma-separated class list like "A,B,C", "P, A, Q", or 199just "A". Notice that this filter works on both situations where there's a 200space after each comma or there's not. 201 202Case-insensitive matching can be performed by ``#/PATTERN/i``: 203 204* List all tags inherits from the class "A" or "a": 205 206 .. code-block:: console 207 208 $ readtags -Q '(#/(^|,) ?A(,|$)/i $inherits)' -l 209 210To include "/" in a pattern, prefix ``\`` to the "/". 211 212NOTE: The above regular expression pattern for inspecting inheritances is just 213an example to show how to use ``#/PATTERN/`` expression. Tags file generators 214have no consensus about the format of ``inherits:``, e.g., whether there should 215be a space after a comma. Even parsers in ctags have no consensus. Noticing the 216format of the ``inherits:`` field of specific languages is needed for such 217queries. 218 219The expressions ``#/PATTERN/`` and ``#/PATTERN/i`` are for interactive use. 220Readtags also offers an alias ``string->regexp``, so ``#/PATTERN/`` is equal to 221``(string->regexp "PATTERN")``, and ``#/PATTERN/i`` is equal to 222``(string->regexp "PATTERN" :case-fold #t)``. ``string->regexp`` doesn't need 223to prefix ``\`` for including "/" in a pattern. ``string->regexp`` may simplify 224a client tool building an expression. See also ctags-client-tools(7) for 225building expressions in your tool. 226 227Let's now consider missing fields. The tags file may have tag entries that has 228no ``inherits:`` field. In that case ``$inherits`` is #f, and the regular 229expression matching raises an error, since string operators only work for 230strings. To avoid this problem: 231 232* Safely list all tags inherits from the class "A": 233 234 .. code-block:: console 235 236 $ readtags -Q '(and $inherits (#/(^|,) ?A(,|$)/ $inherits))' -l 237 238This makes sure ``$inherits`` is not missing first, then match it by regexp. 239 240Sometimes you want to keep tags where the field *is* missing. For example, your 241want to exclude reference tags, which is marked by the ``extras:`` field, then 242you want to keep tags who doesn't have ``extras:`` field since they are also 243not reference tags. Here's how to do it: 244 245* List all tags but the reference tags: 246 247 .. code-block:: console 248 249 $ readtags -Q '(or (not $extras) (#/(^|,) ?reference(,|$)/ $extras))' -l 250 251Notice that ``(not $extras)`` produces ``#t`` when ``$extras`` is missing, so 252the whole ``or`` expression produces ``#t``. 253 254 255The combination of ``ctags -o -`` and ``readtags -t -`` is handy for inspecting 256a source file as far as the source file is enough short. 257 258* List all the large (> 100 lines) functions in a file: 259 260 .. code-block:: console 261 262 $ ctags -o - --fields=+neKz input.c \ 263 | ./readtags -t - -en \ 264 -Q '(and (eq? $kind "function") $end $line (> (- $end $line) 100))' \ 265 -l 266 267* List all the tags including line 80 in a file: 268 269 .. code-block:: console 270 271 $ ctags -o - --fields=+neKz input.c \ 272 | readtags -t - -ne \ 273 -Q '(and $line 274 (or (eq? $line 80) 275 (and $end (< $line 80) (< 80 $end))))' \ 276 -l 277 278Run "readtags -H filter" to know about all valid functions and variables. 279 280Sorting 281~~~~~~~ 282When sorting, the sorter expression is evaluated on two tag entries to decide 283which should sort before the other one, until the order of all tag entries is 284decided. 285 286In a sorter expression, ``$`` and ``&`` are used to access the fields in the 287two tag entries, and let's call them $-entry and &-entry. The sorter expression 288should have a value of -1, 0 or 1. The value -1 means the $-entry should be put 289above the &-entry, 1 means the contrary, and 0 makes their order in the output 290uncertain. 291 292The core operator of sorting is ``<>``. It's used to compare two strings or two 293numbers (numbers are for the ``line:`` or ``end:`` fields). In ``(<> a b)``, if 294``a`` < ``b``, the result is -1; ``a`` > ``b`` produces 1, and ``a`` = ``b`` 295produces 0. Strings are compared using the ``strcmp`` function, see strcmp(3). 296 297For example, sort by names, and make those shorter or alphabetically smaller 298ones appear before the others: 299 300.. code-block:: console 301 302 $ readtags -S '(<> $name &name)' -l 303 304This reads "If the tag name in the $-entry is smaller, it goes before the 305&-entry". 306 307The ``<or>`` operator is used to chain multiple expressions until one returns 308-1 or 1. For example, sort by input file names, then line numbers if in the 309same file: 310 311.. code-block:: console 312 313 $ readtags -S '(<or> (<> $input &input) (<> $line &line))' -l 314 315The ``*-`` operator is used to flip the compare result. i.e., ``(*- (<> a b))`` 316is the same as ``(<> b a)``. 317 318Filter expressions can be used in sorter expressions. The technique is use 319``if`` to produce integers that can be compared based on the filter, like: 320 321.. code-block:: lisp 322 323 (<> (if filter-expr-on-$-entry -1 1) 324 (if filter-expr-on-&-entry -1 1)) 325 326So if $-entry satisfies the filter, while &-entry doesn't, it's the same as 327``(<> -1 1)``, which produces ``-1``. 328 329For example, we want to put tags with "file" kind below other tags, then the 330sorter would look like: 331 332.. code-block:: lisp 333 334 (<> (if (eq? $kind "file") 1 -1) 335 (if (eq? &kind "file") 1 -1)) 336 337A quick read tells us: If $-entry has "file" kind, and &-entry doesn't, the 338sorter becomes ``(<> 1 -1)``, which produces ``1``, so the $-entry is put below 339the &-entry, exactly what we want. 340 341Formatting 342~~~~~~~~~~ 343A formatter expression defines how readtags prints tag entries. 344 345A formatter expression may produce a string, a boolean, an integer, 346or a list. Readtags prints the produced string, and integer as is. 347Readtags prints nothing for ``#f``, and a newline for ``#t``. 348 349A list could contain any number of strings, booleans, 350integers, and/or lists. Readtags prints the elements of a list 351sequentially and recursively. 352 353All the operators for filtering are also available in formatter 354expressions. In addition to the operators, ``list`` is available 355in formatter expressions. As the name shows, ``list`` is for 356making a list. ``list`` makes a list containing arguments passed to 357the operator. e.g., the following expression makes a list contains 358``1``, ``#f``, and ``"hello"``: 359 360.. code-block:: lisp 361 362 (list 1 #f "hello") 363 364NOTE: Unlike real-Lisp, backquote constructs are not available. 365 366To show some examples, the following tags file (``output.tags``) is assumed 367as input for readtags: 368 369.. code-block:: tags 370 371 M input.c 4;" macro file: 372 N input.c 3;" macro file: 373 bar input.c 11;" f typeref:typename:void file: signature:(char ** argv,int * r) 374 foo input.c 6;" f typeref:typename:int file: signature:(int v) 375 main input.c 16;" f typeref:typename:int signature:(int argc,char ** argv) 376 377An exapmle for printing only function names: 378 379.. code-block:: console 380 381 $ readtags -t output.tags -Q '(eq? $kind "function")' -F '(list $name #t)' -l 382 bar 383 foo 384 main 385 386Doing the same only with a formatter expression: 387 388.. code-block:: console 389 390 $ readtags -t output.tags -F '(if (eq? $kind "function") (list $name #t) #f)' -l 391 bar 392 foo 393 main 394 395Generating declarations for the functions: 396 397.. code-block:: console 398 399 $ readtags -t output.tags -F \ 400 '(if (eq? $kind "function") 401 (list (if $file "static " #f) $typeref-name " " $name $signature ";" #t) 402 #f)' -l 403 static void bar(char ** argv,int * r); 404 static int foo(int v); 405 int main(int argc,char ** argv); 406 407Inspecting the Behavior of Expressions 408~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 409The `print` operator can be used to print the value of an expression. For 410example: 411 412.. code-block:: console 413 414 $ readtags -Q '(print $name)' -l 415 416prints the name of each tag entry before it. Since the return value of 417``print`` is not #f, all the tag entries are printed. We could control this 418using the ``begin`` or ``begin0`` operator. ``begin`` returns the value of its 419last argument, and ``begin0`` returns the value of its first argument. For 420example: 421 422.. code-block:: console 423 424 $ readtags -Q '(begin0 #f (print (prefix? "ctags" "ct")))' -l 425 426prints a bunch of "#t" (depending on how many lines are in the tags file), and 427the actual tag entries are not printed. 428 429SEE ALSO 430-------- 431See tags(5) for the details of tags file format. 432 433See ctags-client-tools(7) for the tips writing a 434tool utilizing tags file. 435 436The official Universal Ctags web site at: 437 438https://ctags.io/ 439 440The git repository for the library used in readtags command: 441 442https://github.com/universal-ctags/libreadtags 443 444CREDITS 445------- 446Universal Ctags project 447https://ctags.io/ 448 449Darren Hiebert <dhiebert@users.sourceforge.net> 450http://DarrenHiebert.com/ 451 452The readtags command and libreadtags maintained at Universal Ctags 453are derived from readtags.c and readtags.h developd at 454http://ctags.sourceforge.net. 455