xref: /Universal-ctags/man/readtags.1.rst.in (revision 7ba043c2158a3da81e149a70a65fb9b4a8d5b208)

.. _readtags(1):

==============================================================
readtags
==============================================================
--------------------------------------------------------------
Find tag file entries matching specified names
--------------------------------------------------------------
:Version: @VERSION@
:Manual group: Universal Ctags
:Manual section: 1

SYNOPSIS
--------
|	**readtags** -h | --help
|	**readtags** (-H | --help-expression) (filter|sorter|formatter)
|	**readtags** [OPTION]... ACTION

DESCRIPTION
-----------
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, sorting, and formatting can be done using **post processors**, namely
**filter expressions**, **sorter expressions**, and **formatter expressions**.

ACTIONS
-------
``-l``, ``--list``
	List regular tags.

``[-] NAME``
	List regular tags matching NAME.
	"-" as NAME indicates arguments after this as NAME even if they start with -.

``-D``, ``--list-pseudo-tags``
	Equivalent to ``--list-pseudo-tags``.

OPTIONS
-------

Controlling the Tags Reading Behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The behavior of reading tags can be controlled using these options:

``-t TAGFILE``, ``--tag-file TAGFILE``
	Use specified tag file (default: "tags").
	Giving "-" as TAGFILE indicates reading the tags file content from the
	standard input. "-" can make the command line simpler. However,
	it doesn't mean efficient; readtags stores the data to a temorary
	file and reads that file for taking the ACTION.

``-s[0|1|2]``, ``--override-sort-detection METHOD``
	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:

``-i``, ``--icase-match``
	Perform case-insensitive matching in the NAME action.

``-p``, ``--prefix-match``
	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:

``-d``, ``--debug``
	Turn on debugging output.

``-E``, ``--escape-output``
	Escape characters like tabs in output as described in tags(5).

``-e``, ``--extension-fields``
	Include extension fields in output.

``-n``, ``--line-number``
	Also include the line number field when ``-e`` option is give.

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, Sorting, and Formatting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Further filtering, sorting, and formatting on the tags listed by actions
are performed using:

``-Q EXP``, ``--filter EXP``
	Filter the tags listed by ACTION with EXP before printing.

``-S EXP``, ``--sorter EXP``
	Sort the tags listed by ACTION with EXP before printing.

``-F EXP``, ``--formatter EXP``
	Format the tags listed by ACTION with EXP when printing.

These are discussed in the `EXPRESSION`_ section.

Examples
~~~~~~~~
* List all tags in "/path/to/tags":

  .. code-block:: console

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

* List all tags in "tags" that start with "mymethod":

  .. code-block:: console

     $ readtags -p - mymethod

* List all tags matching "mymethod", case insensitively:

  .. code-block:: console

     $ readtags -i - mymethod

* List all tags start with "myvar", and printing all fields (i.e., the whole line):

  .. code-block:: console

     $ readtags -p -ne - myvar

EXPRESSION
----------
Scheme-style expressions are used for the ``-Q``, ``-S``, and ``-F`` 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 ``#f``. ``#t`` and all
  other values are considered to be true.

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

Filtering
~~~~~~~~~
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:

  .. code-block:: console

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

    .. code-block:: console

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

  .. code-block:: console

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

  .. code-block:: console

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

  .. code-block:: console

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

  .. code-block:: console

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

  .. code-block:: console

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


The combination of ``ctags -o -`` and ``readtags -t -`` is handy for inspecting
a source file as far as the source file is enough short.

* List all the large (> 100 lines) functions in a file:

  .. code-block:: console

     $ ctags -o - --fields=+neKz input.c \
       | ./readtags -t - -en \
                    -Q '(and (eq? $kind "function") $end $line (> (- $end $line) 100))' \
                    -l

* List all the tags including line 80 in a file:

  .. code-block:: console

     $ ctags -o - --fields=+neKz input.c \
       | readtags -t - -ne \
                  -Q '(and $line
                           (or (eq? $line 80)
                               (and $end (< $line 80) (< 80 $end))))' \
         -l

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

.. code-block:: console

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

.. code-block:: console

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

.. code-block:: lisp

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

.. code-block:: lisp

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

Formatting
~~~~~~~~~~
A formatter expression defines how readtags prints tag entries.

A formatter expression may produce a string, a boolean, an integer,
or a list. Readtags prints the produced string, and integer as is.
Readtags prints nothing for ``#f``, and a newline for ``#t``.

A list could contain any number of strings, booleans,
integers, and/or lists. Readtags prints the elements of a list
sequentially and recursively.

All the operators for filtering are also available in formatter
expressions. In addition to the operators, ``list`` is available
in formatter expressions. As the name shows, ``list`` is for
making a list. ``list`` makes a list containing arguments passed to
the operator. e.g., the following expression makes a list contains
``1``, ``#f``, and ``"hello"``:

.. code-block:: lisp

   (list 1 #f "hello")

NOTE: Unlike real-Lisp, backquote constructs are not available.

To show some examples, the following tags file (``output.tags``) is assumed
as input for readtags:

.. code-block:: tags

   M	input.c	4;"	macro	file:
   N	input.c	3;"	macro	file:
   bar	input.c	11;"	f	typeref:typename:void	file:	signature:(char ** argv,int * r)
   foo	input.c	6;"	f	typeref:typename:int	file:	signature:(int v)
   main	input.c	16;"	f	typeref:typename:int	signature:(int argc,char ** argv)

An exapmle for printing only function names:

.. code-block:: console

   $ readtags -t output.tags -Q '(eq? $kind "function")' -F '(list $name #t)' -l
   bar
   foo
   main

Doing the same only with a formatter expression:

.. code-block:: console

   $ readtags -t output.tags -F '(if (eq? $kind "function") (list $name #t) #f)' -l
   bar
   foo
   main

Generating declarations for the functions:

.. code-block:: console

   $ readtags -t output.tags -F \
     '(if (eq? $kind "function")
         (list (if $file "static " #f) $typeref-name " " $name $signature ";" #t)
        #f)' -l
   static void bar(char ** argv,int * r);
   static int foo(int v);
   int main(int argc,char ** argv);

Inspecting the Behavior of Expressions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `print` operator can be used to print the value of an expression. For
example:

.. code-block:: console

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

.. code-block:: console

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

https://ctags.io/

The git repository for the library used in readtags command:

https://github.com/universal-ctags/libreadtags

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