.\" Man page generated from reStructuredText.
.
.TH CTAGS-CLIENT-TOOLS 7 "" "0.0.0" "Universal-ctags"
.SH NAME
ctags-client-tools \- Hints for developing a tool using ctags-universal command and tags output
.
.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
\fBctags\-universal\fP [options] [file(s)]
\fBetags\fP [options] [file(s)]
.fi
.sp
.SH DESCRIPTION
.sp
\fBClient tool\fP means a tool running the ctags\-universal command
and/or reading a tags file generated by ctags\-universal command.
This man page gathers hints for people who develop client tools.
.SH PSEUDO-TAGS
.sp
\fBPseudo\-tags\fP, stored in a tag file, indicate how
ctags\-universal generated the tags file: whether the
tags file is sorted or not, which version of tags file format is used,
the name of tags generator, and so on. The opposite term for
pseudo\-tags is \fBregular\-tags\fP\&. A regular\-tag is for a language
object in an input file. A pseudo\-tag is for the tags file
itself. Client tools may use pseudo\-tags as reference for processing
regular\-tags.
.sp
A pseudo\-tag is stored in a tags file in the same format as
regular\-tags as described in tags(5), except that pseudo\-tag names
are prefixed with "!_". For the general information about
pseudo\-tags, see "TAG FILE INFORMATION" in tags(5).
.sp
An example of a pseudo tag:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
!_TAG_PROGRAM_NAME      Universal Ctags /Derived from Exuberant Ctags/
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The value, "2", associated with the pseudo tag "TAG_PROGRAM_NAME", is
used in the field for input file. The description, "Derived from
Exuberant Ctags", is used in the field for pattern.
.sp
Universal\-ctags extends the naming scheme of the classical pseudo\-tags
available in Exuberant\-ctags for emitting language specific
information as pseudo tags:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
!_{pseudo\-tag\-name}!{language\-name}     {associated\-value}      /{description}/
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The language\-name is appended to the pseudo\-tag name with a separator, "!".
.sp
An example of pseudo tag with a language suffix:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
!_TAG_KIND_DESCRIPTION!C        f,function      /function definitions/
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This pseudo\-tag says "the function kind of C language is enabled
when generating this tags file." \fB\-\-pseudo\-tags\fP is the option for
enabling/disabling individual pseudo\-tags. When enabling/disabling a
pseudo tag with the option, specify the tag name only
"TAG_KIND_DESCRIPTION", without the prefix ("!_") or the suffix ("!C").
.SS Options for Pseudo\-tags
.INDENT 0.0
.TP
.B \fB\-\-extras=+p\fP (or \fB\-\-extras=+{pseudo}\fP)
Forces writing pseudo\-tags.
.sp
ctags\-universal emits pseudo\-tags by default when writing tags
to a regular file (e.g. "tags\(aq.) However, when specifying \fB\-o \-\fP
or \fB\-f \-\fP for writing tags to standard output,
ctags\-universal doesn\(aqt emit pseudo\-tags. \fB\-\-extras=+p\fP or
\fB\-\-extras=+{pseudo}\fP will force pseudo\-tags to be written.
.TP
.B \fB\-\-list\-pseudo\-tags\fP
Lists available types of pseudo\-tags and shows whether they are enabled or disabled.
.sp
Running ctags\-universal with \fB\-\-list\-pseudo\-tags\fP option
lists available pseudo\-tags. Some of pseudo\-tags newly introduced
in Universal\-ctags project are disabled by default. Use
\fB\-\-pseudo\-tags=...\fP to enable them.
.TP
.B \fB\-\-pseudo\-tags=[+|\-]names|*\fP
Specifies a list of pseudo\-tag types to include in the output.
.sp
The parameters are a set of pseudo tag names. Valid pseudo tag names
can be listed with \fB\-\-list\-pseudo\-tags\fP\&. Surround each name in the set
with braces, like "{TAG_PROGRAM_AUTHOR}". You don\(aqt have to include the "!_"
pseudo tag prefix when specifying a name in the option argument for \fB\-\-pseudo\-tags=\fP
option.
.sp
pseudo\-tags don\(aqt have a notation using one\-letter flags.
.sp
If a name is preceded by either the \(aq+\(aq or \(aq\-\(aq characters, that
tags\(aqs effect has been added or removed. Otherwise the names replace
any current settings. All entries are included if \(aq*\(aq is given.
.TP
.B \fB\-\-fields=+E\fP (or \fB\-\-fields=+{extras}\fP)
Attach "extras:pseudo" field to pseudo\-tags.
.sp
An example of pseudo tags with the field:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
!_TAG_PROGRAM_NAME      Universal Ctags /Derived from Exuberant Ctags/  extras:pseudo
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the name of a normal tag in a tag file starts with "!_", a
client tool cannot distinguish whether the tag is a regular\-tag or
pseudo\-tag.  The fields attached with this option help the tool
distinguish them.
.UNINDENT
.SS List of notable pseudo\-tags
.sp
Running ctags with \fB\-\-list\-pseudo\-tags\fP option lists available types
of pseudo\-tags with short descriptions. This subsection shows hints
for using notable ones.
.INDENT 0.0
.TP
.B \fBTAG_EXTRA_DESCRIPTION\fP  (new in Universal\-ctags)
Indicates the names and descriptions of enabled extras:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
!_TAG_EXTRA_DESCRIPTION       {extra\-name}    /description/
!_TAG_EXTRA_DESCRIPTION!{language\-name}       {extra\-name}    /description/
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If your tool relies on some extra tags (extras), refer to
the pseudo\-tags of this type. A tool can reject the tags file that
doesn\(aqt include expected extras, and raise an error in an early
stage of processing.
.sp
An example of the pseudo\-tags:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
$ ctags\-universal \-\-extras=+p \-\-pseudo\-tags=\(aq{TAG_EXTRA_DESCRIPTION}\(aq \-o \- input.c
!_TAG_EXTRA_DESCRIPTION       anonymous       /Include tags for non\-named objects like lambda/
!_TAG_EXTRA_DESCRIPTION       fileScope       /Include tags of file scope/
!_TAG_EXTRA_DESCRIPTION       pseudo  /Include pseudo tags/
!_TAG_EXTRA_DESCRIPTION       subparser       /Include tags generated by subparsers/
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A client tool can know "{anonymous}", "{fileScope}", "{pseudo}",
and "{subparser}" extras are enabled from the output.
.TP
.B \fBTAG_FIELD_DESCRIPTION\fP  (new in Universal\-ctags)
Indicates the names and descriptions of enabled fields:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
!_TAG_FIELD_DESCRIPTION       {field\-name}    /description/
!_TAG_FIELD_DESCRIPTION!{language\-name}       {field\-name}    /description/
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If your tool relies on some fields, refer to the pseudo\-tags of
this type.  A tool can reject a tags file that doesn\(aqt include
expected fields, and raise an error in an early stage of
processing.
.sp
An example of the pseudo\-tags:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
$ ctags\-universal \-\-fields\-C=+\(aq{macrodef}\(aq \-\-extras=+p \-\-pseudo\-tags=\(aq{TAG_FIELD_DESCRIPTION}\(aq \-o \- input.c
!_TAG_FIELD_DESCRIPTION       file    /File\-restricted scoping/
!_TAG_FIELD_DESCRIPTION       input   /input file/
!_TAG_FIELD_DESCRIPTION       name    /tag name/
!_TAG_FIELD_DESCRIPTION       pattern /pattern/
!_TAG_FIELD_DESCRIPTION       typeref /Type and name of a variable or typedef/
!_TAG_FIELD_DESCRIPTION!C     macrodef        /macro definition/
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A client tool can know "{file}", "{input}", "{name}", "{pattern}",
and "{typeref}" fields are enabled from the output.
The fields are common in languages. In addition to the common fields,
the tool can known "{macrodef}" field of C language is also enabled.
.TP
.B \fBTAG_FILE_ENCODING\fP  (new in Universal\-ctags)
TBW
.TP
.B \fBTAG_FILE_FORMAT\fP
See also tags(5).
.TP
.B \fBTAG_FILE_SORTED\fP
See also tags(5).
.TP
.B \fBTAG_KIND_DESCRIPTION\fP (new in Universal\-ctags)
Indicates the names and descriptions of enabled kinds:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
!_TAG_KIND_DESCRIPTION!{language\-name}        {kind\-letter},{kind\-name}       /description/
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If your tool relies on some kinds, refer to the pseudo\-tags of
this type.  A tool can reject the tags file that doesn\(aqt include
expected kinds, and raise an error in an early stage of
processing.
.sp
Kinds are language specific, so a language name is  always
appended to the tag name as suffix.
.sp
An example of the pseudo\-tags:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
$ ctags\-universal \-\-extras=+p \-\-kinds\-C=vfm \-\-pseudo\-tags=\(aq{TAG_KIND_DESCRIPTION}\(aq \-o \- input.c
!_TAG_KIND_DESCRIPTION!C      f,function      /function definitions/
!_TAG_KIND_DESCRIPTION!C      m,member        /struct, and union members/
!_TAG_KIND_DESCRIPTION!C      v,variable      /variable definitions/
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A client tool can know "{function}", "{member}", and "{variable}"
kinds of C language are enabled from the output.
.TP
.B \fBTAG_KIND_SEPARATOR\fP (new in Universal\-ctags)
TBW
.TP
.B \fBTAG_OUTPUT_FILESEP\fP (new in Universal\-ctags)
TBW
.TP
.B \fBTAG_OUTPUT_MODE\fP (new in Universal\-ctags)
TBW
.TP
.B \fBTAG_PATTERN_LENGTH_LIMIT\fP (new in Universal\-ctags)
TBW
.TP
.B \fBTAG_PROC_CWD\fP (new in Universal\-ctags)
Indicates the working directory of ctags\-universal during processing.
.sp
This pseudo\-tag helps a client tool solve the absolute paths for
the input files for tag entries even when they are tagged with
relative paths.
.sp
An example of the pseudo\-tags:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
$ cat tags
!_TAG_PROC_CWD        /tmp/   //
main  input.c /^int main (void) { return 0; }$/;"     f       typeref:typename:int
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
From the regular tag for "main", the client tool can know the
"main" is at "input.c".  However, it is a relative path. So if the
directory where ctags\-universal run and the directory
where the client tool runs are different, the client tool cannot
find "input.c" from the file system. In that case,
\fBTAG_PROC_CWD\fP gives the tool a hint; "input.c" may be at "/tmp".
.TP
.B \fBTAG_PROGRAM_NAME\fP
TBW
.UNINDENT
.SH REDUNDANT-KINDS
.sp
TBW
.SH MULTIPE-LANGUAGES FOR AN INPUT FILE
.sp
TBW
.SH UTILIZING READTAGS
.sp
See readtags(1) to know how to use readtags. This section is for discussing
some notable topics for client tools.
.SS Build Filter/Sorter Expressions
.sp
Certain escape sequences in expressions are recognized by readtags. For
example, when searching for a tag that matches \fBa\e?b\fP, if using a filter
expression like \fB\(aq(eq? $name "a\e?b")\(aq\fP, since \fB\e?\fP is translated into a
single \fB?\fP by readtags, it actually searches for \fBa?b\fP\&.
.sp
Another problem is if a single quote appear in filter expressions (which is
also wrapped by single quotes), it terminates the expression, producing broken
expressions, and may even cause unintended shell injection. Single quotes can
be escaped using \fB\(aq"\(aq"\(aq\fP\&.
.sp
So, client tools need to:
.INDENT 0.0
.IP \(bu 2
Replace \fB\e\fP by \fB\e\e\fP
.IP \(bu 2
Replace \fB\(aq\fP by \fB\(aq"\(aq"\(aq\fP
.UNINDENT
.sp
inside the expressions. If the expression also contains strings, \fB"\fP in the
strings needs to be replaced by \fB\e"\fP\&.
.sp
Client tools written in Lisp could build the expression using lists. \fBprin1\fP
(in Common Lisp style Lisps) and \fBwrite\fP (in Scheme style Lisps) can
translate the list into a string that can be directly used. For example, in
EmacsLisp:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(let ((name "hi"))
  (prin1 \(ga(eq? $name ,name)))
=> "(eq\e\e? $name "hi")"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The "?" is escaped, and readtags can handle it. Scheme style Lisps should do
proper escaping so the expression readtags gets is just the expression passed
into \fBwrite\fP\&. Common Lisp style Lisps may produce unrecognized escape
sequences by readtags, like \fB\e#\fP\&. Readtags provides some aliases for these
Lisps:
.INDENT 0.0
.IP \(bu 2
Use \fBtrue\fP for \fB#t\fP\&.
.IP \(bu 2
Use \fBfalse\fP for \fB#f\fP\&.
.IP \(bu 2
Use \fBnil\fP or \fB()\fP for \fB()\fP\&.
.IP \(bu 2
Use \fB(string\->regexp "PATTERN")\fP for \fB#/PATTERN/\fP\&. Use
\fB(string\->regexp "PATTERN" :case\-fold true)\fP for \fB#/PATTERN/i\fP\&. Notice
that \fBstring\->regexp\fP doesn\(aqt require escaping "/" in the pattern.
.UNINDENT
.sp
Notice that even when the client tool uses this method, \fB\(aq\fP still needs to be
replaced by \fB\(aq"\(aq"\(aq\fP to prevent broken expressions and shell injection.
.SS Parse Readtags Output
.sp
In the output of readtags, tabs can appear in all field values (e.g., the tag
name itself could contain tabs), which makes it hard to split the line into
fields. Client tools should use the \fB\-E\fP option, which keeps the escape
sequences in the tags file, so the only field that could contain tabs is the
pattern field.
.sp
Client tools could then split the line using the following steps:
.INDENT 0.0
.IP \(bu 2
Find the first 2 tabs in the line, so we get the name and input field.
.IP \(bu 2
From the 2nd tab
.INDENT 2.0
.IP \(bu 2
If a "/" follows, then the pattern delimiter is "/".
.IP \(bu 2
If a "?" follows, then the pattern delimiter is "?".
.IP \(bu 2
If a number follows, then if after the end of the number is a ";/", then
the pattern delimiter is "/"; If it\(aqs a ";?", then the delimiter is "?".
.UNINDENT
.IP \(bu 2
Find the 3rd tab, and count the delimiters between it and the 2nd tab. Notice
that delimiters can be escaped, so only the ones with a even number
(including 0) of backslashes before should be counted.
.IP \(bu 2
If there are even numbers of delimiters, then the 3rd tab is the end of the
pattern. If not, keep searching tabs forward until this condition is
satisfied.
.IP \(bu 2
From here, split the rest of the line into fields by tabs.
.UNINDENT
.sp
Then, the escape sequences in fields other than the pattern field should be
translated. See "Proposal" in tags(5) to know about all the escape sequences.
The pattern field needs no special treatment. It can be directly used by
editors supporting Ex commands.
.SH SEE ALSO
.sp
ctags(1), ctags\-incompatibilities(7), tags(5), readtags(1)
.\" Generated by docutils manpage writer.
.