ctags-incompatibilities(7)

1CTAGS-INCOMPATIBILITIES(7)      Universal Ctags     CTAGS-INCOMPATIBILITIES(7)
2
3
4

NAME

6       ctags-incompatibilities - Incompatibilities between Universal Ctags and
7       Exuberant Ctags
8

SYNOPSIS

10       ctags [options] [file(s)]
11       etags [options] [file(s)]
12
13

DESCRIPTION

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

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO