Controlling the Tags Reading Behavior

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.

Controlling the NAME Action Behavior

The behavior of the NAME action can be controlled using these options:

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:

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.

Filtering and Sorting

Further filtering and sorting on the tags listed by actions are performed using:

These are discussed in the EXPRESSION section.

Examples

$ readtags -t /path/to/tags -l

$ readtags -p - mymethod

$ readtags -i - mymethod

$ readtags -p -ne - myvar

Filtering

The tag entries that makes the filter expression produces non-#f values are filtered out (#f means false).

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:

$ readtags -p -Q '(eq? $language "Python")' - myfunc

downcase or upcase operators can be used to perform case-insensitive matching:

$ 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:

$ readtags -Q '(and (substr? $name "impl")\


                    (or (eq? $language "Python")\


                        (not $language)))' -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.

$ readtags -Q '(#/(^|, )A(,|$)/ $inherits)' -l

Here $inherits is a comma-separated class list like "A, B, C", "Z, A", "P, A, Q", or just "A". 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 it works only for strings. To avoid this problem:

$ readtags -Q '(and $inherits (#/(^|, )A(,|$)/ $inherits))' -l

Case-insensitive matching can be performed by #/PATTERN/i.

$ readtags -Q '(and $inherits (#/(^|, )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:. 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 making an expression in your tool.

Run "readtags -H filter" to know about all valid functions and variables.

Sorting

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 sort before 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. 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).

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 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.