# ctags-incompatibilities

## Incompatibilities between Universal Ctags and Exuberant Ctags

Version: | 6.2.1
Manual group: | Universal Ctags
Manual section: | 7

# SYNOPSIS

ctags [options] [file(s)]
etags [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.

## Behavior when `--excmd=mixed` is given

Exuberant Ctags uses line numbers as addresses for C preprocessor macro definition tags. Universal Ctags uses patterns for the tags.

## Incompatibilities in command line interface

### Ordering in a command line

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.

    $ ctags -o - foo.c --list-kinds=Sh
    f  functions

Universal Ctags warns and ignores the option `--list-kinds=Sh` as follows.

    $ 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).