| Version: | +5.9.0 |
|---|---|
| Manual group: | Universal Ctags | +
| Manual section: | 1 | +
The readtags program filters, sorts and prints tag entries in a tags file. +The basic filtering is done using actions, by which you can list all +regular tags, pseudo tags or regular tags matching specific name. Then, further +filtering and sorting can be done using post processors, namely filter +expressions and sorter expressions.
+The behavior of reading tags can be controlled using these options:
+The NAME action will perform binary search on sorted (including "foldcase") +tags files, which is much faster then on unsorted tags files.
+The behavior of the NAME action can be controlled using these options:
+By default, the output of readtags contains only the name, input and pattern +field. The Output can be tweaked using these options:
+About the -E option: certain characters are escaped in a tags file, to make +it machine-readable. e.g., ensuring no tabs character appear in fields other +than the pattern field. By default, readtags translates them to make it +human-readable, but when utilizing readtags output in a script or a client +tool, -E option should be used. See ctags-client-tools(7) for more +discussion on this.
+Further filtering and sorting on the tags listed by actions are performed using:
+These are discussed in the EXPRESSION section.
+List all tags in "/path/to/tags":
+
+$ readtags -t /path/to/tags -l
+
+List all tags in "tags" that start with "mymethod":
+
+$ readtags -p - mymethod
+
+List all tags matching "mymethod", case insensitively:
+
+$ readtags -i - mymethod
+
+List all tags start with "myvar", and printing all fields (i.e., the whole line):
+
+$ readtags -p -ne - myvar
+
+Scheme-style expressions are used for the -Q and -S options. For those +who doesn't know Scheme or Lisp, just remember:
+So, (+ 1 (+ 2 3)) means add 2 and 3 first, then add the result with 1. +(and "string" 1 #t) means logical AND on "string", 1 and #t, +and the result is true since there is no #f.
+The tag entries that make the filter expression produces true value are printed +by readtags.
+The basic operators for filtering are eq?, prefix?, suffix?, +substr?, and #/PATTERN/. Language common fields can be accessed using +variables starting with $, e.g., $language represents the language field. +For example:
+List all tags start with "myfunc" in Python code files:
++$ readtags -p -Q '(eq? $language "Python")' - myfunc ++
downcase or upcase operators can be used to perform case-insensitive +matching:
+List all tags containing "my", case insensitively:
++++$ readtags -Q '(substr? (downcase $name) "my")' -l ++
We have logical operators like and, or and not. The value of a +missing field is #f, so we could deal with missing fields:
+List all tags containing "impl" in Python code files, but allow the +language: field to be missing:
++$ readtags -Q '(and (substr? $name "impl")\ + (or (not $language)\ + (eq? $language "Python")))' -l ++
#/PATTERN/ is for the case when string predicates (prefix?, suffix?, +and substr?) are not enough. You can use "Posix extended regular expression" +as PATTERN.
+List all tags inherits from the class "A":
++$ readtags -Q '(#/(^|,) ?A(,|$)/ $inherits)' -l ++
Here $inherits is a comma-separated class list like "A,B,C", "P, A, Q", or +just "A". Notice that this filter works on both situations where there's a +space after each comma or there's not.
+Case-insensitive matching can be performed by #/PATTERN/i:
+List all tags inherits from the class "A" or "a":
++$ readtags -Q '(#/(^|,) ?A(,|$)/i $inherits)' -l ++
To include "/" in a pattern, prefix \ to the "/".
+NOTE: The above regular expression pattern for inspecting inheritances is just +an example to show how to use #/PATTERN/ expression. Tags file generators +have no consensus about the format of inherits:, e.g., whether there should +be a space after a comma. Even parsers in ctags have no consensus. Noticing the +format of the inherits: field of specific languages is needed for such +queries.
+The expressions #/PATTERN/ and #/PATTERN/i are for interactive use. +Readtags also offers an alias string->regexp, so #/PATTERN/ is equal to +(string->regexp "PATTERN"), and #/PATTERN/i is equal to +(string->regexp "PATTERN" :case-fold #t). string->regexp doesn't need +to prefix \ for including "/" in a pattern. string->regexp may simplify +a client tool building an expression. See also ctags-client-tools(7) for +building expressions in your tool.
+Let's now consider missing fields. The tags file may have tag entries that has +no inherits: field. In that case $inherits is #f, and the regular +expression matching raises an error, since string operators only work for +strings. To avoid this problem:
+Safely list all tags inherits from the class "A":
++$ readtags -Q '(and $inherits (#/(^|,) ?A(,|$)/ $inherits))' -l ++
This makes sure $inherits is not missing first, then match it by regexp.
+Sometimes you want to keep tags where the field is missing. For example, your +want to exclude reference tags, which is marked by the extras: field, then +you want to keep tags who doesn't have extras: field since they are also +not reference tags. Here's how to do it:
+List all tags but the reference tags:
++$ readtags -Q '(or (not $extras) (#/(^|,) ?reference(,|$)/ $extras))' -l ++
Notice that (not $extras) produces #t when $extras is missing, so +the whole or expression produces #t.
+Run "readtags -H filter" to know about all valid functions and variables.
+When sorting, the sorter expression is evaluated on two tag entries to decide +which should sort before the other one, until the order of all tag entries is +decided.
+In a sorter expression, $ and & are used to access the fields in the +two tag entries, and let's call them $-entry and &-entry. The sorter expression +should have a value of -1, 0 or 1. The value -1 means the $-entry should be put +above the &-entry, 1 means the contrary, and 0 makes their order in the output +uncertain.
+The core operator of sorting is <>. It's used to compare two strings or two +numbers (numbers are for the line: or end: fields). In (<> a b), if +a < b, the result is -1; a > b produces 1, and a = b +produces 0. Strings are compared using the strcmp function, see strcmp(3).
+For example, sort by names, and make those shorter or alphabetically smaller +ones appear before the others:
++$ readtags -S '(<> $name &name)' -l ++
This reads "If the tag name in the $-entry is smaller, it goes before the +&-entry".
+The <or> operator is used to chain multiple expressions until one returns +-1 or 1. For example, sort by input file names, then line numbers if in the +same file:
++$ readtags -S '(<or> (<> $input &input) (<> $line &line))' -l ++
The *- operator is used to flip the compare result. i.e., (*- (<> a b)) +is the same as (<> b a).
+Filter expressions can be used in sorter expressions. The technique is use +if to produce integers that can be compared based on the filter, like:
++(<> (if filter-expr-on-$-entry -1 1) + (if filter-expr-on-&-entry -1 1)) ++
So if $-entry satisfies the filter, while &-entry doesn't, it's the same as +(<> -1 1), which produces -1.
+For example, we want to put tags with "file" kind below other tags, then the +sorter would look like:
++(<> (if (eq? $kind "file") 1 -1) + (if (eq? &kind "file") 1 -1)) ++
A quick read tells us: If $-entry has "file" kind, and &-entry doesn't, the +sorter becomes (<> 1 -1), which produces 1, so the $-entry is put below +the &-entry, exactly what we want.
+The print operator can be used to print the value of an expression. For +example:
++$ readtags -Q '(print $name)' -l ++
prints the name of each tag entry before it. Since the return value of +print is not #f, all the tag entries are printed. We could control this +using the begin or begin0 operator. begin returns the value of its +last argument, and begin0 returns the value of its first argument. For +example:
++$ readtags -Q '(begin0 #f (print (prefix? "ctags" "ct")))' -l ++
prints a bunch of "#t" (depending on how many lines are in the tags file), and +the actual tag entries are not printed.
+See tags(5) for the details of tags file format.
+See ctags-client-tools(7) for the tips writing a +tool utilizing tags file.
+The official Universal Ctags web site at:
+ +The git repository for the library used in readtags command:
+ +Universal Ctags project +https://ctags.io/
+Darren Hiebert <dhiebert@users.sourceforge.net> +http://DarrenHiebert.com/
+The readtags command and libreadtags maintained at Universal Ctags +are derived from readtags.c and readtags.h developd at +http://ctags.sourceforge.net.
+