Find tag file entries matching specified names
|Manual group:||Universal Ctags|
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.
- List regular tags.
- List regular tags matching NAME. “-” as NAME indicates arguments after this as NAME even if they start with -.
- Equivalent to
Controlling the Tags Reading Behavior¶
The behavior of reading tags can be controlled using these options:
- Use specified tag file (default: “tags”).
- Override sort detection of tag file. METHOD: unsorted|sorted|foldcase
The NAME action will perform binary search on sorted (including “foldcase”) tags files, which is much faster then on unsorted tags files.
Controlling the NAME Action Behavior¶
The behavior of the NAME action can be controlled using these options:
- Perform case-insensitive matching in the NAME action.
- Perform prefix matching in the NAME action.
Controlling the Output¶
By default, the output of readtags contains only the name, input and pattern field. The Output can be tweaked using these options:
- Turn on debugging output.
- Escape characters like tabs in output as described in tags(5).
- Include extension fields in output.
- Also include the line number field when
-eoption is give.
-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
-E option should be used. See ctags-client-tools(7) for more
discussion on this.
Filtering and Sorting¶
Further filtering and sorting on the tags listed by actions are performed using:
- Filter the tags listed by ACTION with EXP before printing.
- Sort the tags listed by ACTION with EXP before printing.
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
-S options. For those
who doesn’t know Scheme or Lisp, just remember:
- A function call is wrapped in a pair of parenthesis. The first item in it is the function/operator name, the others are arguments.
- Function calls can be nested.
- Missing values and boolean false are represented by
#tand all other values are considered to be true.
(+ 1 (+ 2 3)) means add 2 and 3 first, then add the result with 1.
(and "string" 1 #t) means logical AND on
and the result is true since there is no
The tag entries that make the filter expression produces true value are printed by readtags.
The basic operators for filtering are
#/PATTERN/. Language common fields can be accessed using
variables starting with
$language represents the language field.
List all tags start with “myfunc” in Python code files:
$ readtags -p -Q '(eq? $language "Python")' - myfunc
upcase operators can be used to perform case-insensitive
List all tags containing “my”, case insensitively:
$ readtags -Q '(substr? (downcase $name) "my")' -l
We have logical operators like
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 (
substr?) are not enough. You can use “Posix extended regular expression”
List all tags inherits from the class “A”:
$ readtags -Q '(#/(^|,) ?A(,|$)/ $inherits)' -l
$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
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
#/PATTERN/i are for interactive use.
Readtags also offers an alias
#/PATTERN/ is equal to
(string->regexp "PATTERN"), and
#/PATTERN/i is equal to
(string->regexp "PATTERN" :case-fold #t).
string->regexp doesn’t need
\ 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
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
(not $extras) produces
$extras is missing, so
or expression produces
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,
& 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
The core operator of sorting is
<>. It’s used to compare two strings or two
numbers (numbers are for the
end: fields). In
(<> a b), if
b, the result is -1;
b produces 1, and
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”.
<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
$ readtags -S '(<or> (<> $input &input) (<> $line &line))' -l
*- 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
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
(<> 1 -1), which produces
1, so the $-entry is put below
the &-entry, exactly what we want.
Inspecting the Behavior of Expressions¶
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
begin returns the value of its
last argument, and
begin0 returns the value of its first argument. For
$ 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: