Changes in 6.0.0¶
- Maintainer:
Masatake YAMATO <yamato@redhat.com>
Many changes have been introduced in Universal Ctags. Use git-log to review changes not enumerated here, especially in language parsers.
New and extended options¶
--exclude-exception
, an option complementing --exclude
¶
See Input/Output File Options in ctags(1).
--maxdepth
option¶
See Input/Output File Options in ctags(1).
--input-encoding=ENCODING
and --output-encoding=ENCODING
¶
People may use their own native language in source code comments (or sometimes in identifiers) and in such cases encoding may become an issue. Nowadays UTF-8 is the most widely used encoding, but some source codes still use legacy encodings like latin1, cp932 and so on. These options are useful for such files.
ctags doesn’t consider the input encoding; it just reads input as a sequence of bytes and uses them as is when writing tags entries.
On the other hand Vim does consider input encoding. When loading a file, Vim converts the file contents into an internal format with one of the encodings specified in its fileencodings option.
As a result of this difference, Vim cannot always move the cursor to the definition of a tag as users expect when attempting to match the patterns in a tags file.
The good news is that there is a way to notify Vim of the encoding
used in a tags file with the TAG_FILE_ENCODING
pseudo-tag.
Two new options have been introduced (--input-encoding=IN
and
--output-encoding=OUT
).
Using the encoding specified with these options ctags converts input
from IN
to OUT
. ctags uses the converted strings when writing
the pattern parts of each tag line. As a result the tags output is
encoded in OUT
encoding.
In addition OUT
is specified at the top the tags file as the
value for the TAG_FILE_ENCODING
pseudo-tag. The default value of
OUT
is UTF-8.
NOTE: Converted input is NOT passed to language parsers. The parsers still deal with input as a byte sequence.
With --input-encoding-<LANG>=IN
, you can specify a specific input
encoding for LANG
. It overrides the global default value given
with --input-encoding
.
The example usage can be found in Tmain/{input,output}-encoding-option.d.
Acceptable IN
and OUT
values can be listed with iconv -l or
iconv --list. It is platform dependant.
To enable the option, libiconv is needed on your platform.
On Windows mingw (without msys2), you must specify WITH_ICONV=yes
like this:
C:\dev\ctags>mingw32-make -f mk_mingw.mak WITH_ICONV=yes
--list-features
helps you to know whether your ctags executable
links to libiconv or not. You will find iconv
in the output if it
links to.
See also Output Format Options in ctags(1).
--map-<LANG>
option¶
--map-<LANG>
is newly introduced to control the file name
to language mappings (langmap) with finer granularity than
--langmap
allows.
A langmap entry is defined as a pair; the name of the language and a file name extension (or pattern).
Here we use “spec” as a generic term representing both file name extensions and patterns.
--langmap
maps specs to languages exclusively:
$ ctags --langdef=FOO --langmap=FOO:+.ABC \
--langdef=BAR --langmap=BAR:+.ABC \
--list-maps | grep '\*.ABC$'
BAR *.ABC
Though language FOO is added before BAR, only BAR is set as a handler for the spec *.ABC.
Universal Ctags enables multiple parsers to be configured for a spec. The appropriate parser for a given input file can then be chosen by a variety of internal guessing strategies (see Determining file language).
Let’s see how specs can be mapped non-exclusively with
--map-<LANG>
:
$ ctags --langdef=FOO --map-FOO=+.ABC \
--langdef=BAR --map-BAR=+.ABC \
--list-maps | grep '\*.ABC$'
FOO *.ABC
BAR *.ABC
Both FOO and BAR are registered as handlers for the spec *.ABC.
--map-<LANG>
can also be used for removing a langmap entry.:
$ ctags --langdef=FOO --map-FOO=+.ABC \
--langdef=BAR --map-BAR=+.ABC \
--map-FOO=-.ABC --list-maps | grep '\*.ABC$'
BAR *.ABC
$ ctags --langdef=FOO --map-FOO=+.ABC \
--langdef=BAR --map-BAR=+.ABC \
--map-BAR=-.ABC --list-maps | grep '\*.ABC$'
FOO *.ABC
$ ctags --langdef=FOO --map-FOO=+.ABC \
--langdef=BAR --map-BAR=+.ABC \
--map-BAR=-.ABC --map-FOO=-.ABC --list-maps | grep '\*.ABC$'
(NOTHING)
--langmap
provides a way to manipulate the langmap in a
spec-centric manner and --map-<LANG>
provides a way to manipulate
the langmap in a parser-centric manner.
See also Language Selection and Mapping Options in ctags(1).
Guessing parser from file contents (-G
option)¶
See Determining file language in ctags(1).
Including line number to pattern field¶
Use --excmd=number
.
See Tags File Contents Options in ctags(1).
Long names in kinds, fields, and extra options¶
A letter is used for specifying a kind, a field, or an extra entry. In Universal Ctags a name can also be used.
Surround the name with braces ({ and }) in values assigned to the
options, --kind-<LANG>=
, --fields=
, or --extras=
.
$ ctags --kinds-C=+L-d ...
This command line uses the letters, L for enabling the label kind and d for disabling the macro kind of C. The command line can be rewritten with the associated names.
$ ctags --kinds-C='+{label}-{macro}' ...
The quotes are needed because braces are interpreted as meta characters by the shell.
The available names can be listed with --list-kinds-full
,
--list-fields
, or --list-extras
.
See also Tags File Contents Options in ctags(1).
Wildcard in options¶
For the purpose of gathering as much as information as possible from
source code the “wildcard”(*
) option value has been introduced.
--extras=*
Enables all extra tags.
--fields=*
Enables all available fields.
--kinds-<LANG>=*
Enables all available kinds for
LANG
.--kinds-all=*
Enables all available kinds for all available language parsers.
See also Tags File Contents Options in ctags(1).
Extra tag entries (--extras
)¶
--extra
option in Exuberant Ctags is renamed to --extras
(plural) in
Universal Ctags for making consistent with --kinds-<LANG>
and --fields
.
These extra tag entries are newly introduced.
F
Replacement for --file-scope.
p
Include pseudo-tags.
See also Tags File Contents Options in ctags(1).
Kinds synchronization¶
See the description about --kinds-<LANG>
and --list-kinds-full
option on Tags File Contents Options in ctags(1).
--put-field-prefix
options¶
See Tags File Contents Options in ctags(1).
“always” and “never” as an argument for --tag-relative
¶
--tag-relative
option is extend.
See Tags File Contents Options in ctags(1).
Defining a parser specific extra¶
A new --_extradef-<LANG>=name,description
option allows you to
defining a parser specific extra which turning on and off can be
referred from a regex based parser for <LANG>
.
See Conditional tagging with extras for more details.
Defining a CPreProcessor macro from command line¶
Newly introduced -D
option extends the function provided by
-I
option.
-D
emulates the behaviour of the corresponding gcc option:
it defines a C preprocessor macro.
See Tags File Contents Options in ctags(1) and The new C/C++ parser for more details.
Notice messages and --quiet
¶
There were 3 classes of message in Exuberant Ctags. In addition to them Universal Ctags introduced a new class of message, notice.
- fatal
A critical error has occurred and ctags aborts the execution.
- warning
An error has occurred but ctags continues the execution.
- notice (new)
It is less important than warning but more important for users than verbose.
- verbose
Mainly used for debugging purposes.
Generally the user can ignore notice class messages and --quiet
can be used to disable them.
verbose class messages are disabled by default, and --verbose
or -V
can be used to enable them.
See also Miscellaneous Options in ctags(1).
Skipping utf-8 BOM¶
The three bytes sequence(\xEF\xBB\xBF
) at the head of an input
file is skipped when parsing.
TODO:
Do the same in guessing and selecting parser stage.
Refect the BOM detection to encoding option
Interactive mode¶
A new --_interactive
option launches a JSON based command REPL which
can be used to control ctags generation programmatically.
See Interactive mode for more details.
PCRE2 regular expression¶
With {pcre2}
(or p
) flag, PCRE2 expressions can be used in
--regex-<LANG>=
, --mline-regex-<LANG>=
, and
--_mtable-regex-<LANG>=
if the ctags is built with pcre2
library.
Incompatible changes in command line¶
-D
option¶
For a ctags binary that had debugging output enabled in the build config
stage, -D
was used for specifying the level of debugging
output. It is changed to -d
. This change is not critical because
-D
option was not described in ctags.1 man page.
Instead -D
is used for defining a macro in CPreProcessor parser.