.\" Man page generated from reStructuredText. . .TH READTAGS 1 "" "0.0.0" "Universal-ctags" .SH NAME readtags \- Find tag file entries matching specified names . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH SYNOPSIS .nf \fBreadtags\fP \-h | \-\-help \fBreadtags\fP (\-H | \-\-help\-expression) (filter|sorter) \fBreadtags\fP [OPTION]... ACTION .fi .sp .SH DESCRIPTION .sp The \fBreadtags\fP program filters, sorts and prints tag entries in a tags file. The basic filtering is done using \fBactions\fP, 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 \fBpost processors\fP, namely \fBfilter expressions\fP and \fBsorter expressions\fP\&. .SH ACTIONS .INDENT 0.0 .TP .B \fB\-l\fP, \fB\-\-list\fP List regular tags. .TP .B \fB[\-] NAME\fP List regular tags matching NAME. "\-" as NAME indicates arguments after this as NAME even if they start with \-. .TP .B \fB\-D\fP, \fB\-\-list\-pseudo\-tags\fP Equivalent to \fB\-\-list\-pseudo\-tags\fP\&. .UNINDENT .SH OPTIONS .SS Controlling the Tags Reading Behavior .sp The behavior of reading tags can be controlled using these options: .INDENT 0.0 .TP .B \fB\-t TAGFILE\fP, \fB\-\-tag\-file TAGFILE\fP Use specified tag file (default: "tags"). .TP .B \fB\-s[0|1|2]\fP, \fB\-\-override\-sort\-detection METHOD\fP Override sort detection of tag file. METHOD: unsorted|sorted|foldcase .UNINDENT .sp The NAME action will perform binary search on sorted (including "foldcase") tags files, which is much faster then on unsorted tags files. .SS Controlling the NAME Action Behavior .sp The behavior of the NAME action can be controlled using these options: .INDENT 0.0 .TP .B \fB\-i\fP, \fB\-\-icase\-match\fP Perform case\-insensitive matching in the NAME action. .TP .B \fB\-p\fP, \fB\-\-prefix\-match\fP Perform prefix matching in the NAME action. .UNINDENT .SS Controlling the Output .sp By default, the output of readtags contains only the name, input and pattern field. The Output can be tweaked using these options: .INDENT 0.0 .TP .B \fB\-d\fP, \fB\-\-debug\fP Turn on debugging output. .TP .B \fB\-E\fP, \fB\-\-escape\-output\fP Escape characters like tabs in output as described in tags(5). .TP .B \fB\-e\fP, \fB\-\-extension\-fields\fP Include extension fields in output. .TP .B \fB\-n\fP, \fB\-\-line\-number\fP Also include the line number field when \fB\-e\fP option is give. .UNINDENT .sp About the \fB\-E\fP 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, \fB\-E\fP option should be used. See ctags\-client\-tools(7) for more discussion on this. .SS Filtering and Sorting .sp Further filtering and sorting on the tags listed by actions are performed using: .INDENT 0.0 .TP .B \fB\-Q EXP\fP, \fB\-\-filter EXP\fP Filter the tags listed by ACTION with EXP before printing. .TP .B \fB\-S EXP\fP, \fB\-\-sorter EXP\fP Sort the tags listed by ACTION with EXP before printing. .UNINDENT .sp These are discussed in the \fI\%EXPRESSION\fP section. .SS Examples .INDENT 0.0 .IP \(bu 2 List all tags in "/path/to/tags": .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C $ readtags \-t /path/to/tags \-l .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 List all tags in "tags" that start with "mymethod": .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C $ readtags \-p \- mymethod .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 List all tags matching "mymethod", case insensitively: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C $ readtags \-i \- mymethod .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 List all tags start with "myvar", and printing all fields (i.e., the whole line): .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C $ readtags \-p \-ne \- myvar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SH EXPRESSION .sp Scheme\-style expressions are used for the \fB\-Q\fP and \fB\-S\fP options. For those who doesn\(aqt know Scheme or Lisp, just remember: .INDENT 0.0 .IP \(bu 2 A function call is wrapped in a pair of parenthesis. The first item in it is the function/operator name, the others are arguments. .IP \(bu 2 Function calls can be nested. .UNINDENT .sp So, \fB(+ 1 (+ 2 3))\fP means add 2 and 3 first, then add the result with 1. .SS Filtering .sp The tag entries that makes the filter expression produces non\-#f values are filtered out (#f means false). .sp The basic operators for filtering are \fBeq?\fP, \fBprefix?\fP, \fBsuffix?\fP, \fBsubstr?\fP, and \fB#/PATTERN/\fP\&. Language common fields can be accessed using variables starting with \fB$\fP, e.g., \fB$language\fP represents the language field. For example: .INDENT 0.0 .IP \(bu 2 List all tags start with "myfunc" in Python code files: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C $ readtags \-p \-Q \(aq(eq? $language "Python")\(aq \- myfunc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp \fBdowncase\fP or \fBupcase\fP operators can be used to perform case\-insensitive matching: .INDENT 0.0 .IP \(bu 2 List all tags containing "my", case insensitively: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ readtags \-Q \(aq(substr? (downcase $name) "my")\(aq \-l .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp We have logical operators like \fBand\fP, \fBor\fP and \fBnot\fP\&. The value of a missing field is #f, so we could deal with missing fields: .INDENT 0.0 .IP \(bu 2 List all tags containing "impl" in Python code files, but allow the \fBlanguage:\fP field to be missing: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C $ readtags \-Q \(aq(and (substr? $name "impl")\e (or (eq? $language "Python")\e (not $language)))\(aq \-l .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp \fB#/PATTERN/\fP is for the case when string predicates (\fBprefix?\fP, \fBsuffix\fP, and \fBsubstr?\fP) are not enough. You can use "Posix extended regular expression" as PATTERN. .INDENT 0.0 .IP \(bu 2 List all tags inherits from the class "A": .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C $ readtags \-Q \(aq(#/(^|, )A(,|$)/ $inherits)\(aq \-l .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Here \fB$inherits\fP 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 \fBinherits:\fP field. In that case \fB$inherits\fP is #f, and the regular expression matching raises an error, since it works only for strings. To avoid this problem: .INDENT 0.0 .IP \(bu 2 Safely list all tags inherits from the class "A": .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C $ readtags \-Q \(aq(and $inherits (#/(^|, )A(,|$)/ $inherits))\(aq \-l .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Case\-insensitive matching can be performed by \fB#/PATTERN/i\fP\&. .INDENT 0.0 .IP \(bu 2 Safely list all tags inherits from the class "A" or "a": .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C $ readtags \-Q \(aq(and $inherits (#/(^|, )A(,|$)/i $inherits))\(aq \-l .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp To include "/" in a pattern, prefix "" to the "/". .sp NOTE: The above regular expression pattern for inspecting inheritances is just an example to show how to use \fB#/PATTERN/\fP expression. Tags file generators have no consensus about the format of \fBinherits:\fP\&. Even parsers in ctags have no consensus. Noticing the format of the \fBinherits:\fP field of specific languages is needed for such queries. .sp The expressions \fB#/PATTERN/\fP and \fB#/PATTERN/i\fP are for interactive use. Readtags also offers an alias \fBstring\->regexp\fP, so \fB#/PATTERN/\fP is equal to \fB(string\->regexp "PATTERN")\fP, and \fB#/PATTERN/i\fP is equal to \fB(string\->regexp "PATTERN" :case\-fold #t)\fP\&. \fBstring\->regexp\fP doesn\(aqt need to prefix "" for including "/" in a pattern. \fBstring\->regexp\fP may simplify a client tool building an expression. See also ctags\-client\-tools(7) for making an expression in your tool. .sp Run "readtags \-H filter" to know about all valid functions and variables. .SS Sorting .sp 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. .sp In a sorter expression, \fB$\fP and \fB&\fP are used to access the fields in the two tag entries, and let\(aqs 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. .sp The core operator of sorting is \fB<>\fP\&. It\(aqs used to compare two strings or two numbers (numbers are for the \fBline:\fP or \fBend:\fP fields). In \fB(<> a b)\fP, if \fBa\fP < \fBb\fP, the result is \-1; \fBa\fP > \fBb\fP produces 1, and \fBa\fP = \fBb\fP produces 0. Strings are compared using the \fBstrcmp\fP function, see strcmp(3). .sp For example, sort by names, and make those shorter or alphabetically smaller ones appear before the others: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ readtags \-S \(aq(<> $name &name)\(aq \-l .ft P .fi .UNINDENT .UNINDENT .sp This reads "If the tag name in the $\-entry is smaller, it goes before the &\-entry". .sp The \fB\fP 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ readtags \-S \(aq( (<> $input &input) (<> $line &line))\(aq \-l .ft P .fi .UNINDENT .UNINDENT .sp The \fB*\-\fP operator is used to flip the compare result. i.e., \fB(*\- (<> a b))\fP is the same as \fB(<> b a)\fP\&. .SS Inspecting the Behavior of Expressions .sp The \fIprint\fP operator can be used to print the value of an expression. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ readtags \-Q \(aq(print $name)\(aq \-l .ft P .fi .UNINDENT .UNINDENT .sp prints the name of each tag entry before it. Since the return value of \fBprint\fP is not #f, all the tag entries are printed. We could control this using the \fBbegin\fP or \fBbegin0\fP operator. \fBbegin\fP returns the value of its last argument, and \fBbegin0\fP returns the value of its first argument. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ readtags \-Q \(aq(begin0 #f (print (prefix? "ctags" "ct")))\(aq \-l .ft P .fi .UNINDENT .UNINDENT .sp prints a bunch of "#t" (depending on how many lines are in the tags file), and the actual tag entries are not printed. .SH BUGS .sp Sometimes readtags exits with status 0 even when an error occurs, e.g., when a directory is passed to the \fB\-t\fP option. .SH SEE ALSO .sp See tags(5) for the details of tags file format. .sp See ctags\-client\-tools(7) for the tips writing a tool utilizing tags file. .sp The official Universal\-ctags web site at: .sp \fI\%https://ctags.io/\fP .sp The git repository for the library used in readtags command: .sp \fI\%https://github.com/universal\-ctags/libreadtags\fP .SH CREDITS .sp Universal\-ctags project \fI\%https://ctags.io/\fP .sp Darren Hiebert <\fI\%dhiebert@users.sourceforge.net\fP> \fI\%http://DarrenHiebert.com/\fP .sp The readtags command and libreadtags maintained at Universal\-ctags are derived from readtags.c and readtags.h developd at \fI\%http://ctags.sourceforge.net\fP\&. .\" Generated by docutils manpage writer. .