1.. NOT REVIEWED YET 2 3.. _output-xref: 4 5====================================================================== 6Xref output 7====================================================================== 8 9Xref output is a tabular, human-readable cross reference (xref) format. 10 11The default information contained in the output includes: 12 13* the tag name 14* the kind of tag 15* the line number 16* file name 17* source line (with extra white space condensed) of the file 18 19``--_xformat`` option allows a user to customize the output information. See 20:ref:`Customizing xref output <xformat>` for more details. 21 22Xref output goes to standard output by default. 23 24Notes: 25 26 * Printing `z`{kind} field in xref format doesn't include `kind:` prefix. 27 * Printing `Z`{scope} field in xref format doesn't include `scope:` prefix. 28 29.. _xformat: 30 31Customizing xref output 32~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 33 34``--_xformat`` option allows a user to customize the cross reference 35(xref) output enabled with ``-x``. 36:: 37 38 --_xformat=FORMAT 39 40 41The notation for FORMAT is similar to that employed by `printf(3)` in 42the C language; `%` represents a slot which is substituted with a 43field value when printing. You can specify multiple slots in FORMAT. 44Here field means an item listed with ``--list-fields`` option. 45 46The notation of a slot:: 47 48 %[-][.][WIDTH-AND-ADJUSTMENT]FIELD-SPECIFIER 49 50``FIELD-SPECIFIER`` specifies a field whose value is printed. 51Short notation and long notation are available. They can be mixed 52in a FORMAT. Specifying a field with either notation, one or more 53fields are activated internally. 54 55The short notation is just a letter listed in the LETTER column of 56the ``--list-fields`` output. 57 58The long notation is a name string surrounded by braces(`{` and 59`}`). The name string is listed in the NAME column of the output of 60the same option. To specify a field owned by a parser, prepend 61the parser name to the name string with `.` as a separator. 62 63Wild card (`*`) can be used where a parser name is specified. In this 64case both common and parser specific fields are activated and printed. 65If a common field and a parser specific field have the same name, 66the common field has higher priority. 67 68`WIDTH-AND-ADJUSTMENT` is a positive number. 69The value of the number is used as the width of 70the column where a field is printed. The printing is 71right adjusted by default, and left 72adjusted when `-` is given as prefix. 73The output is not truncated by default even if its field width is 74specified and smaller than width of output value. For truncating 75the output to the specified width, use `.` as prefix. 76 77An example of specifying common fields: 78 79.. code-block:: console 80 81 $ ctags -x --_xformat="%-20N %4n %-16{input}|" main/main.c | head 82 CLOCKS_PER_SEC 360 main/main.c | 83 CLOCKS_PER_SEC 364 main/main.c | 84 CLOCK_AVAILABLE 358 main/main.c | 85 CLOCK_AVAILABLE 363 main/main.c | 86 Totals 87 main/main.c | 87 __anonae81ef0f0108 87 main/main.c | 88 addTotals 100 main/main.c | 89 batchMakeTags 436 main/main.c | 90 bytes 87 main/main.c | 91 clock 365 main/main.c | 92 93Here `%-20N %4n %-16{input}|` is a format string. Let's look at the 94elements of the format. 95 96`%-20N` 97 98 The short notation is used here. 99 The element means filling the slot with the name of the tag. 100 The width of the column is 20 characters and left adjusted. 101 102`%4n` 103 104 The short notation is used here. 105 The element means filling the slot with the line number of 106 the tag. The width of the column is 4 characters and right 107 adjusted. 108 109`%-16{input}` 110 111 The long notation is used here. 112 The element means filling the slot with the input file name 113 where the tag is defined. The width of column is 16 114 characters and left adjusted. 115 116`|` 117 118 Printed as is. 119 120Another example of specifying parser specific fields: 121 122.. code-block:: console 123 124 $ ctags -x --_xformat="%-20N [%10{C.properties}]" main/main.c 125 CLOCKS_PER_SEC [ ] 126 CLOCK_AVAILABLE [ ] 127 Totals [ ] 128 __anonae81ef0f0108 [ ] 129 addTotals [ extern] 130 batchMakeTags [ static] 131 bytes [ ] 132 clock [ ] 133 clock [ static] 134 ... 135 136Here `"%-20N [%10{C.properties}]"` is a format string. Let's look at 137the elements of the format. 138 139`%-20N` 140 141 Already explained in the first example. 142 143`[` and `]` 144 145 Printed as is. 146 147`%10{C.properties}` 148 149 The long notation is used here. 150 The element means filling the slot with the value 151 of the properties field of the C parser. 152 The width of the column is 10 characters and right adjusted. 153 154 155.. TODO: An example of using WILDCARD 156