1CTAGS-INCOMPATIBILITIES(7) Universal Ctags CTAGS-INCOMPATIBILITIES(7)
2
6 ctags-incompatibilities - Incompatibilities between Universal Ctags and
7 Exuberant Ctags
8
10 ctags [options] [file(s)]
11 etags [options] [file(s)]
12
15 This page describes major incompatible changes introduced to Universal
16 Ctags forked from Exuberant Ctags.
17 Option files loading at starting up time (preload files)
19 Universal Ctags doesn't load ~/.ctags at starting up time. File paths
20 for preload files are changed. See "FILES" section of ctags(1).
21 Environment variables for arranging command lines
23 Universal Ctags doesn't read CTAGS and/or ETAGS environment variables.
24 Behavior when --excmd=mixed is given
26 Exuberant Ctags uses line numbers as addresses for C preprocessor macro
27 definition tags. Universal Ctags uses patterns for the tags.
28 Incompatibilities in command line interface
30 Ordering in a command line
31 The command line format of Universal Ctags is "ctags [options]
32 [source_file(s)]" following the standard POSIX convention.
33 Exuberant Ctags accepts a option following a source file.
35 $ ctags -o - foo.c --list-kinds=Sh
37 f functions
38 Universal Ctags warns and ignores the option --list-kinds=Sh as fol‐
40 lows.
41 $ ctags -o - foo.c --list-kinds=Sh
43 ctags: Warning: cannot open input file "--list-kinds=Sh" : No such file or directory
44 a foo.c /^void a () {}$/;" f typeref:typename:void
45 b foo.c /^void b () {}$/;" f typeref:typename:void
46 The order of application of patterns and extensions in --langmap
48 When applying mappings for a name of given source file, Exuberant Ctags
49 tests file name patterns AFTER file extensions (e-map-order). Universal
50 Ctags does this differently; it tests file name patterns BEFORE file
51 extensions (u-map-order).
52 This incompatible change is introduced to deal with the following situ‐
54 ation:
55 • build.xml as a source file,
57 • The Ant parser declares it handles a file name pattern build.xml,
59 and
60 • The XML parser declares it handles a file extension .xml.
62 Which parser should be used for parsing build.xml? The assumption of
64 Universal Ctags is the user may want to use the Ant parser; the file
65 name pattern it declares is more specific than the file extension that
66 the XML parser declares. However, e-map-order chooses the XML parser.
67 So Universal Ctags uses the u-map-order even though it introduces an
69 incompatibility.
70 --list-map-extensions=<language> and --list-map-patterns=<language> op‐
72 tions are helpful to verify and the file extensions and the file name
73 patterns of given <language>.
74 Remove --file-tags and --file-scope options
76 Even in Exuberant Ctags, --file-tags is not documented in its man page.
77 Instead of specifying --file-tags or --file-tags=yes, use --extras=+f
78 or --extras=+{inputFile}.
79 Instead of specifying --file-tags=no, use --extras=-f or --extras=-{in‐
81 putFile}.
82 Universal Ctags introduces F/fileScope extra as the replacement for
84 --file-scope option.
85 Instead of specifying --file-tags or --file-tags=yes, use --extras=+F
87 or --extras=+{fileScope}.
88 Instead of specifying --file-tags=no, use --extras=-F or --ex‐
90 tras=-{fileScope}.
91 Incompatibilities in language and kind definitions
93 Language name defined with --langdef=name option
94 The characters you can use are more restricted than Exuberant Ctags.
95 For more details, see the description of --langdef=name in
96 ctags-optlib(7).
97 Obsoleting --<LANG>-kinds option
99 Some options have <LANG> as parameterized parts in their name like
100 --foo-<LANG>=... or --<LANG>-foo=.... The most of all such options in
101 Exuberant Ctags have the former form, --foo-<LANG>=.... The exception
102 is --<LANG>-kinds.
103 Universal Ctags uses the former form for all <LANG> parameterized op‐
105 tion. Use --kinds-<LANG> instead of --<LANG>-kinds in Universal Ctags.
106 --<LANG>-kinds still works but it will be removed in the future.
107 The former form may be friendly to shell completion engines.
109 Disallowing to define a kind with file as name
111 The kind name file is reserved. Using it as part of kind spec in
112 --regex-<LANG> option is now disallowed.
113 Disallowing to define a kind with 'F' as letter
115 The kind letter 'F' is reserved. Using it as part of a kind spec in
116 --regex-<LANG> option is now disallowed.
117 Disallowing to use other than alphabetical character as kind letter
119 Exuberant Ctags accepts a character other than alphabetical character
120 as kind letter in --regex-<LANG>=... option. Universal Ctags accepts
121 only an alphabetical character.
122 Acceptable characters as parts of a kind name
124 Exuberant Ctags accepts any character as a part of a kind name defined
125 with --regex-<LANG>=/regex/replacement/kind-spec/.
126 Universal Ctags accepts only an alphabetical character as the initial
128 letter of a kind name. Universal Ctags accepts only an alphabetical
129 character or numerical character as the rest letters.
130 An example:
132 --regex-Foo=/abstract +class +([a-z]+)/\1/a,abstract class/i
134 Universal Ctags rejects this because the kind name, abstract class, in‐
136 cludes a whitespace character.
137 This requirement is for making the output of Universal Ctags follow the
139 tags file format.
140 A combination of a kind letter and a kind name
142 In Universal Ctags, the combination of a kind letter and a kind name
143 must be unique in a language.
144 You cannot define more than one kind reusing a kind letter with differ‐
146 ent kind names. You cannot define more than one kind reusing a kind
147 name with different kind letters.
148 An example:
150 --regex-Foo=/abstract +class +([a-z]+)/\1/a,abstractClass/i
152 --regex-Foo=/attribute +([a-z]+)/\1/a,attribute/i
153 Universal Ctags rejects this because the kind letter, 'a', used twice
155 for defining a kind abstractClass and attribute.
156 Incompatibilities in tags file format
158 Using numerical character in the name part of tag tagfield
159 The version 2 tags file format, the default output format of Exuberant
160 Ctags, accepts only alphabetical characters in the name part of tag
161 tagfield.
162 Universal Ctags introduces an exception to this specification; it may
164 use numerical characters in addition to alphabetical characters as the
165 letters other than initial letter of the name part.
166 The kinds heading1, heading2, and heading3 in the HTML parser are the
168 examples.
169 Truncating the pattern for long input lines
171 To prevent generating overly large tags files, a pattern field is trun‐
172 cated, by default, when its size exceeds 96 bytes. A different limit
173 can be specified with --pattern-length-limit=N. Specifying 0 as N re‐
174 sults no truncation as Exuberant Ctags does not.
175 Kind letters and names
177 A kind letter 'F' and a kind name file are reserved in the main part. A
178 parser cannot have a kind conflicting with these reserved ones. Some
179 incompatible changes are introduced to follow the above rule.
180 • Cobol's file kind is renamed to fileDesc because the kind name file
182 is reserved.
183 • Ruby's 'F' (singletonMethod) is changed to 'S'.
185 • SQL's 'F' (field) is changed to 'E'.
187
189 ctags(1), ctags-optlib(7), and tags(5).
1906.0.0 CTAGS-INCOMPATIBILITIES(7)