.. _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=`` and ``--list-map-patterns=`` options are helpful to verify and the file extensions and the file name patterns of given **. 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 ``---kinds`` option .................................................................................... Some options have ** as parameterized parts in their name like ``--foo-=...`` or ``---foo=...``. The most of all such options in Exuberant Ctags have the former form, ``--foo-=...``. The exception is ``---kinds``. Universal Ctags uses the former form for all ** parameterized option. Use ``--kinds-`` instead of ``---kinds`` in Universal Ctags. ``---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-`` 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-`` 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-=...`` 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-=/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).