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