NAME

       ctags-incompatibilities - Incompatibilities between Universal Ctags and Exuberant Ctags

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.

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