forked from universal-ctags/ctags
-
Notifications
You must be signed in to change notification settings - Fork 0
/
ctags-incompatibilities.7.rst.in
236 lines (165 loc) · 8.68 KB
/
ctags-incompatibilities.7.rst.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
.. _ctags-incompatibilities(7):
==============================================================
ctags-incompatibilities
==============================================================
--------------------------------------------------------------
Incompatibilities between Universal Ctags and Exuberant Ctags
--------------------------------------------------------------
:Version: @VERSION@
:Manual group: Universal Ctags
:Manual section: 7
SYNOPSIS
--------
| **@CTAGS_NAME_EXECUTABLE@** [options] [file(s)]
| **@ETAGS_NAME_EXECUTABLE@** [options] [file(s)]
DESCRIPTION
-----------
This page describes major incompatible changes introduced to
Universal Ctags forked from Exuberant Ctags.
Option files loading at starting up time (preload files)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Universal Ctags doesn't load ``~/.ctags`` at starting up time.
File paths for preload files are changed.
See "FILES" section of ctags(1).
Environment variables for arranging command lines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Universal Ctags doesn't read ``CTAGS`` and/or ``ETAGS`` environment
variables.
Incompatibilities in command line interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Ordering in a command line
....................................................................................
.. NOTE: #1889
The command line format of Universal Ctags is "``ctags [options]
[source_file(s)]``" following the standard POSIX convention.
Exuberant Ctags accepts a option following a source file.
.. code-block:: console
$ ctags -o - foo.c --list-kinds=Sh
f functions
Universal Ctags warns and ignores the option ``--list-kinds=Sh`` as follows.
.. code-block:: console
$ ctags -o - foo.c --list-kinds=Sh
ctags: Warning: cannot open input file "--list-kinds=Sh" : No such file or directory
a foo.c /^void a () {}$/;" f typeref:typename:void
b foo.c /^void b () {}$/;" f typeref:typename:void
The order of application of patterns and extensions in ``--langmap``
....................................................................................
When applying mappings for a name of given source file,
Exuberant Ctags tests file name patterns *AFTER* file extensions
(*e-map-order*). Universal Ctags does this differently; it tests file
name patterns *BEFORE* file extensions (*u-map-order*).
This incompatible change is introduced to deal with the following
situation:
* ``build.xml`` as a source file,
* The Ant parser declares it handles a file name pattern ``build.xml``, and
* The XML parser declares it handles a file extension ``.xml``.
Which parser should be used for parsing ``build.xml``? The assumption
of Universal Ctags is the user may want to use the Ant parser; the
file name pattern it declares is more specific than the file extension
that the XML parser declares. However, e-map-order chooses the XML
parser.
So Universal Ctags uses the u-map-order even though it introduces an
incompatibility.
``--list-map-extensions=<language>`` and ``--list-map-patterns=<language>``
options are helpful to verify and the file extensions and the file
name patterns of given *<language>*.
Remove ``--file-tags`` and ``--file-scope`` options
....................................................................................
Even in Exuberant Ctags, ``--file-tags`` is not documented in its man page.
Instead of specifying ``--file-tags`` or ``--file-tags=yes``, use
``--extras=+f`` or ``--extras=+{inputFile}``.
Instead of specifying ``--file-tags=no``, use
``--extras=-f`` or ``--extras=-{inputFile}``.
Universal Ctags introduces ``F/fileScope`` extra as the replacement for
``--file-scope`` option.
Instead of specifying ``--file-tags`` or ``--file-tags=yes``, use
``--extras=+F`` or ``--extras=+{fileScope}``.
Instead of specifying ``--file-tags=no``, use
``--extras=-F`` or ``--extras=-{fileScope}``.
Incompatibilities in language and kind definitions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Language name defined with ``--langdef=name`` option
....................................................................................
The characters you can use are more restricted than Exuberant Ctags.
For more details, see the description of ``--langdef=name`` in ctags-optlib(7).
Obsoleting ``--<LANG>-kinds`` option
....................................................................................
Some options have *<LANG>* as parameterized parts in their name like
``--foo-<LANG>=...`` or ``--<LANG>-foo=...``. The most of all such
options in Exuberant Ctags have the former form, ``--foo-<LANG>=...``.
The exception is ``--<LANG>-kinds``.
Universal Ctags uses the former form for all *<LANG>* parameterized
option. Use ``--kinds-<LANG>`` instead of ``--<LANG>-kinds`` in
Universal Ctags. ``--<LANG>-kinds`` still works but it will be
removed in the future.
The former form may be friendly to shell completion engines.
Disallowing to define a kind with ``file`` as name
....................................................................................
The kind name ``file`` is reserved. Using it as part of kind spec in
``--regex-<LANG>`` option is now disallowed.
Disallowing to define a kind with '``F``' as letter
....................................................................................
The kind letter '``F``' is reserved. Using it as part of a kind spec in
``--regex-<LANG>`` option is now disallowed.
Disallowing to use other than alphabetical character as kind letter
....................................................................................
Exuberant Ctags accepts a character other than alphabetical character
as kind letter in ``--regex-<LANG>=...`` option. Universal Ctags
accepts only an alphabetical character.
Acceptable characters as parts of a kind name
....................................................................................
Exuberant Ctags accepts any character as a part of a kind name
defined with ``--regex-<LANG>=/regex/replacement/kind-spec/``.
Universal Ctags accepts only an alphabetical character as
the initial letter of a kind name.
Universal Ctags accepts only an alphabetical character or
numerical character as the rest letters.
An example::
--regex-Foo=/abstract +class +([a-z]+)/\1/a,abstract class/i
Universal Ctags rejects this because the kind name, ``abstract class``,
includes a whitespace character.
This requirement is for making the output of Universal Ctags follow
the tags file format.
A combination of a kind letter and a kind name
....................................................................................
In Universal Ctags, the combination of
a kind letter and a kind name must be unique in a language.
You cannot define more than one kind reusing a kind letter with
different kind names. You cannot define more than one kind reusing a
kind name with different kind letters.
An example::
--regex-Foo=/abstract +class +([a-z]+)/\1/a,abstractClass/i
--regex-Foo=/attribute +([a-z]+)/\1/a,attribute/i
Universal Ctags rejects this because the kind letter, '``a``', used twice
for defining a kind ``abstractClass`` and ``attribute``.
Incompatibilities in tags file format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using numerical character in the name part of tag tagfield
....................................................................................
The version 2 tags file format, the default output format of
Exuberant Ctags, accepts only alphabetical characters in the name part
of tag tagfield.
Universal Ctags introduces an exception to this specification; it may
use numerical characters in addition to alphabetical characters as the
letters other than initial letter of the name part.
The kinds ``heading1``, ``heading2``, and ``heading3`` in the HTML parser
are the examples.
Truncating the pattern for long input lines
....................................................................................
To prevent generating overly large tags files, a pattern field is
truncated, by default, when its size exceeds 96 bytes. A different
limit can be specified with ``--pattern-length-limit=N``. Specifying
0 as *N* results no truncation as Exuberant Ctags does not.
Kind letters and names
....................................................................................
A kind letter '``F``' and a kind name ``file`` are reserved in the
main part. A parser cannot have a kind conflicting with
these reserved ones. Some incompatible changes are introduced
to follow the above rule.
* Cobol's ``file`` kind is renamed to ``fileDesc`` because the
kind name ``file`` is reserved.
* Ruby's '``F``' (singletonMethod) is changed to '``S``'.
* SQL's '``F``' (field) is changed to '``E``'.
SEE ALSO
--------
ctags(1), ctags-optlib(7), and tags(5).