1.. 2 NOT REVIEWED YET 3 4====================================================================== 5Request for extending a parser (or Reporting a bug of parser) 6====================================================================== 7 8:Maintainer: Masatake YAMATO <yamato@redhat.com> 9 10.. contents:: `Table of contents` 11 :depth: 3 12 :local: 13 14---- 15 16Sometimes you will find u-ctags doesn't make a tag for a language 17object unexpectedly. Writing a patch for making the tag is 18appreciate. However, you may not have time to do so. In that case, you 19can open an issue on the GitHub page of u-ctags. 20 21This section tells you how to drive u-ctags developers effectively. 22 23Before reporting 24--------------------------------------------------------------------- 25 26U-Ctags just captures the definitions of language objects. U-ctags 27has an infrastructure for capturing references for language objects. 28However, we implement reference tagging limited area. We will not 29work on writing new code for capturing references for your favorite 30language. About requests for capturing reference tags, we will say 31"patches are welcome.". 32 33What kind of language objects u-ctags captures is controlled by 34`--kind-<LANG>` option. Some kinds are disabled by default because we 35assume people don't want too large `tags` file. When you cannot find a 36language object you want in a tags file, it is worth for checking the 37status of kinds. `--list-kinds=<LANG>` or (`--list-kinds-full=<LANG>`) 38option lists the status of the given language. 39 40Let's see an example. 41 42Consider following input (foo.h): 43 44.. code-block:: C 45 46 struct point { 47 int x, y; 48 }; 49 50 struct point *make_point(int x0, int y0); 51 52tags output generated with `u-ctags -o - /tmp/foo.h` is as following. 53:: 54 55 point foo.h /^struct point {$/;" s 56 x foo.h /^ int x, y;$/;" m struct:point typeref:typename:int 57 y foo.h /^ int x, y;$/;" m struct:point typeref:typename:int 58 59Though `point`, `x` and `y` are tagged, the declaration `make_point` 60is not tagged because `prototype` kind of C++ is disabled by default. 61You can know it from the output of `ctags --list-kinds-full=C++`. 62:: 63 64 #LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION 65 A alias no no 0 NONE namespace aliases 66 L label no no 0 C goto labels 67 N name no no 0 NONE names imported via using scope::symbol 68 ... 69 p prototype no no 0 C function prototypes 70 71By turning on the kind with `--kinds-C++=+p`, u-ctags tags 72`make_point`:: 73 74 make_point foo.h /^struct point *make_point(int x0, int y0);$/;" p typeref:struct:point * 75 point foo.h /^struct point {$/;" s 76 x foo.h /^ int x, y;$/;" m struct:point typeref:typename:int 77 y foo.h /^ int x, y;$/;" m struct:point typeref:typename:int 78 79Wildcard `*` is for enabling all kinds of a language at once. 80`--kinds-C++=*` option enables all kinds of C++ parser. If you specify `all` 81as the name of `<LANG>`, you can enable all kinds of all languages at once. 82 83The content of report 84--------------------------------------------------------------------- 85 86Don't assume following three things. 87 88U-ctags developers know vi. 89 90 If you explain the expectation about how tags related functions of vi 91 and its plugins, U-ctags developers don't understand it. 92 The answer from them can be "it can be a bug of vi." 93 94U-ctags developers know the programming language that you are talking. 95 96 U-ctags developers need your help to understand the meaning of 97 language object you asked tagging especially about kind. A person 98 extending a parser have to decide a kind of newly tagging language 99 object: reusing an existing kind or introducing a new kind. 100 U-ctags developers expect a report know the concept kind, field, 101 and extra. ctags.1 man page of u-ctags explains them. 102 103English is the native language of the head maintainer. 104 105 I don't want to write this but I have to write this. 106 Following are my private request for reporters. 107 108 Instead of long explanation, showing code or output 109 examples make me understand what you want. 110 111 Don't omit sentences. Please, write your sentence 112 in full. 113 114 Use pronounce fewer. 115 116U-ctags can generate something meaningful from a broken input. 117 118 From garbage, u-ctags generates garbage. 119 For a syntactically broken input source file, U-ctags 120 does not work well. U-ctags developers will not work 121 on improving u-ctags for handing such input. 122 The exception is that macro related input. Well known 123 one is C and C++. 124 125Following a tuple with three items helps us to understand what you want. 126 1271. Input file 128 129 A shorter input file is better. However, it must be syntactically 130 valid. Show the URL (or something) where you get the input 131 file. It is needed to incorporate the input file to the u-ctags 132 source tree as a test case. 133 1342. Command line running u-ctags 135 1363. Expected output 137 138These three items should be rendered preformatted form on an issue 139page of GitHub. Use triple backquotes notation of GitHub's 140markdown notation. I will close an issue with a bad notation 141like this `issue <https://github.com/universal-ctags/ctags/issues/1547>`_. 142 143An example of good report 144--------------------------------------------------------------------- 145 146For the following input file(input.f90), u-ctags reports incomplete pattern 147for function `f` at the line 23. 148 149:: 150 151 ! input.f90, taken from https://github.com/universal-ctags/ctags/issues/1616 152 module example_mod 153 154 ! This module contains two interfaces: 155 ! 1. f_interface, which is an interface to the local f function 156 ! 2. g, which is implemented in the example_smod submodule 157 158 interface f_interface 159 ! The function `f` is defined below, within the `contains` statement 160 module function f(x) result(y) 161 integer :: x, y 162 end function f 163 end interface f_interface 164 165 interface 166 ! The function `g` is implemented in example_smod.f90 167 module function g(x) result(y) 168 integer :: x,y 169 end function g 170 end interface 171 172 contains 173 function f(x) result(y) 174 integer :: x, y 175 176 y = x * 2 177 end function f 178 end module example_mod 179 180I run ctags with following command line:: 181 182 u-ctags --fields=+n -o - /tmp/input.f90 183 184What I got:: 185 186 example_mod /tmp/input.f90 /^module example_mod$/;" m line:2 187 f /tmp/input.f90 /^ fu/;" f line:23 188 f_interface /tmp/input.f90 /^ interface f_interface$/;" i line:8 module:example_mod 189 190I think this should be:: 191 192 example_mod /tmp/input.f90 /^module example_mod$/;" m line:2 193 f /tmp/input.f90 /^ function f/;" f line:23 194 f_interface /tmp/input.f90 /^ interface f_interface$/;" i line:8 module:example_mod 195 196or:: 197 198 example_mod /tmp/input.f90 /^module example_mod$/;" m line:2 199 f /tmp/input.f90 /^ function f(x) result(y)/;" f line:23 200 f_interface /tmp/input.f90 /^ interface f_interface$/;" i line:8 module:example_mod 201 202 203Either way, `/^ fu/` is too short as a pattern. 204 205The version of u-ctags is `83b0d1f6`:: 206 207 $ u-ctags --version 208 Universal Ctags 0.0.0(83b0d1f6), Copyright (C) 2015 Universal Ctags Team 209 Universal Ctags is derived from Exuberant Ctags. 210 Exuberant Ctags 5.8, Copyright (C) 1996-2009 Darren Hiebert 211 Compiled: Dec 15 2017, 08:07:36 212 URL: https://ctags.io/ 213 Optional compiled features: +wildcards, +regex, +multibyte, +debug, +option-directory, +xpath, +json, +interactive, +sandbox, +yaml 214