diff options
Diffstat (limited to 'ctags/docs/output-tags.html')
| -rw-r--r-- | ctags/docs/output-tags.html | 551 |
1 files changed, 551 insertions, 0 deletions
diff --git a/ctags/docs/output-tags.html b/ctags/docs/output-tags.html new file mode 100644 index 0000000..7b58d4d --- /dev/null +++ b/ctags/docs/output-tags.html @@ -0,0 +1,551 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Changes to the tags file format — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Xref output" href="output-xref.html" /> + <link rel="prev" title="Output formats" href="output-format.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="output-xref.html" title="Xref output" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="output-format.html" title="Output formats" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="output-format.html" accesskey="U">Output formats</a> »</li> + <li class="nav-item nav-item-this"><a href="">Changes to the tags file format</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="changes-to-the-tags-file-format"> +<span id="changes-tags-file"></span><h1>Changes to the tags file format<a class="headerlink" href="#changes-to-the-tags-file-format" title="Permalink to this headline">¶</a></h1> +<section id="f-kind-usage"> +<h2><code class="docutils literal notranslate"><span class="pre">F</span></code> kind usage<a class="headerlink" href="#f-kind-usage" title="Permalink to this headline">¶</a></h2> +<p>You cannot use <code class="docutils literal notranslate"><span class="pre">F</span></code> (<code class="docutils literal notranslate"><span class="pre">file</span></code>) kind in your .ctags because Universal Ctags +reserves it. See <a class="reference internal" href="man/ctags-incompatibilities.7.html#ctags-incompatibilities-7"><span class="std std-ref">ctags-incompatibilities(7)</span></a>.</p> +</section> +<section id="reference-tags"> +<h2>Reference tags<a class="headerlink" href="#reference-tags" title="Permalink to this headline">¶</a></h2> +<p>Traditionally ctags collects the information for locating where a +language object is DEFINED.</p> +<p>In addition Universal Ctags supports reference tags. If the extra-tag +<code class="docutils literal notranslate"><span class="pre">r</span></code> is enabled, Universal Ctags also collects the information for +locating where a language object is REFERENCED. This feature was +proposed by @shigio in <a class="reference external" href="https://github.com/universal-ctags/ctags/issues/569">#569</a> for GNU GLOBAL.</p> +<p>Here are some examples. Here is the target input file named reftag.c.</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><stdio.h></span><span class="cp"></span> +<span class="cp">#include</span> <span class="cpf">"foo.h"</span><span class="cp"></span> +<span class="cp">#define TYPE point</span> +<span class="k">struct</span> <span class="nc">TYPE</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">;</span> <span class="p">};</span> +<span class="n">TYPE</span> <span class="n">p</span><span class="p">;</span> +<span class="cp">#undef TYPE</span> +</pre></div> +</div> +<p>Traditional output:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -o - reftag.c +<span class="go">TYPE reftag.c /^#define TYPE /;" d file:</span> +<span class="go">TYPE reftag.c /^struct TYPE { int x, y; };$/;" s file:</span> +<span class="go">p reftag.c /^TYPE p;$/;" v typeref:typename:TYPE</span> +<span class="go">x reftag.c /^struct TYPE { int x, y; };$/;" m struct:TYPE typeref:typename:int file:</span> +<span class="go">y reftag.c /^struct TYPE { int x, y; };$/;" m struct:TYPE typeref:typename:int file:</span> +</pre></div> +</div> +<p>Output with the extra-tag <code class="docutils literal notranslate"><span class="pre">r</span></code> enabled:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-extras <span class="p">|</span> grep ^r +<span class="go">r Include reference tags off</span> +<span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>+r reftag.c +<span class="go">TYPE reftag.c /^#define TYPE /;" d file:</span> +<span class="go">TYPE reftag.c /^#undef TYPE$/;" d file:</span> +<span class="go">TYPE reftag.c /^struct TYPE { int x, y; };$/;" s file:</span> +<span class="go">foo.h reftag.c /^#include "foo.h"/;" h</span> +<span class="go">p reftag.c /^TYPE p;$/;" v typeref:typename:TYPE</span> +<span class="go">stdio.h reftag.c /^#include <stdio.h>/;" h</span> +<span class="go">x reftag.c /^struct TYPE { int x, y; };$/;" m struct:TYPE typeref:typename:int file:</span> +<span class="go">y reftag.c /^struct TYPE { int x, y; };$/;" m struct:TYPE typeref:typename:int file:</span> +</pre></div> +</div> +<p><cite>#undef X</cite> and two <cite>#include</cite> are newly collected.</p> +<p>“roles” is a newly introduced field in Universal Ctags. The field +named is for recording how a tag is referenced. If a tag is definition +tag, the roles field has “def” as its value.</p> +<p>Universal Ctags prints the role information when the <cite>r</cite> +field is enabled with <code class="docutils literal notranslate"><span class="pre">--fields=+r</span></code>.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>+r --fields<span class="o">=</span>+r reftag.c +<span class="go">TYPE reftag.c /^#define TYPE /;" d file:</span> +<span class="go">TYPE reftag.c /^#undef TYPE$/;" d file: roles:undef</span> +<span class="go">TYPE reftag.c /^struct TYPE { int x, y; };$/;" s file: roles:def</span> +<span class="go">foo.h reftag.c /^#include "foo.h"/;" h roles:local</span> +<span class="go">p reftag.c /^TYPE p;$/;" v typeref:typename:TYPE roles:def</span> +<span class="go">stdio.h reftag.c /^#include <stdio.h>/;" h roles:system</span> +<span class="go">x reftag.c /^struct TYPE { int x, y; };$/;" m struct:TYPE typeref:typename:int file: roles:def</span> +<span class="go">y reftag.c /^struct TYPE { int x, y; };$/;" m struct:TYPE typeref:typename:int file: roles:def</span> +</pre></div> +</div> +<p>The <cite>Reference tag marker</cite> field, <code class="docutils literal notranslate"><span class="pre">R</span></code>, is a specialized GNU global +requirement; D is used for the traditional definition tags, and R is +used for the new reference tags. The field can be used only with +<code class="docutils literal notranslate"><span class="pre">--_xformat</span></code>.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -x --_xformat<span class="o">=</span><span class="s2">"%R %-16N %4n %-16F %C"</span> --extras<span class="o">=</span>+r reftag.c +<span class="go">D TYPE 3 reftag.c #define TYPE point</span> +<span class="go">D TYPE 4 reftag.c struct TYPE { int x, y; };</span> +<span class="go">D p 5 reftag.c TYPE p;</span> +<span class="go">D x 4 reftag.c struct TYPE { int x, y; };</span> +<span class="go">D y 4 reftag.c struct TYPE { int x, y; };</span> +<span class="go">R TYPE 6 reftag.c #undef TYPE</span> +<span class="go">R foo.h 2 reftag.c #include "foo.h"</span> +<span class="go">R stdio.h 1 reftag.c #include <stdio.h></span> +</pre></div> +</div> +<p>See <a class="reference internal" href="output-xref.html#xformat"><span class="std std-ref">Customizing xref output</span></a> for more details about +<code class="docutils literal notranslate"><span class="pre">--_xformat</span></code>.</p> +<p>Although the facility for collecting reference tags is implemented, +only a few parsers currently utilize it. All available roles can be +listed with <code class="docutils literal notranslate"><span class="pre">--list-roles</span></code>:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-roles +<span class="gp">#</span>LANGUAGE KIND<span class="o">(</span>L/N<span class="o">)</span> NAME ENABLED DESCRIPTION +<span class="go">SystemdUnit u/unit Requires on referred in Requires key</span> +<span class="go">SystemdUnit u/unit Wants on referred in Wants key</span> +<span class="go">SystemdUnit u/unit After on referred in After key</span> +<span class="go">SystemdUnit u/unit Before on referred in Before key</span> +<span class="go">SystemdUnit u/unit RequiredBy on referred in RequiredBy key</span> +<span class="go">SystemdUnit u/unit WantedBy on referred in WantedBy key</span> +<span class="go">Yaml a/anchor alias on alias</span> +<span class="go">DTD e/element attOwner on attributes owner</span> +<span class="go">Automake c/condition branched on used for branching</span> +<span class="go">Cobol S/sourcefile copied on copied in source file</span> +<span class="go">Maven2 g/groupId dependency on dependency</span> +<span class="go">DTD p/parameterEntity elementName on element names</span> +<span class="go">DTD p/parameterEntity condition on conditions</span> +<span class="go">LdScript s/symbol entrypoint on entry points</span> +<span class="go">LdScript i/inputSection discarded on discarded when linking</span> +<span class="go">...</span> +</pre></div> +</div> +<p>The first column shows the name of the parser. +The second column shows the letter/name of the kind. +The third column shows the name of the role. +The fourth column shows whether the role is enabled or not. +The fifth column shows the description of the role.</p> +<p>You can define a role in an optlib parser for capturing reference +tags. See <a class="reference internal" href="optlib.html#roles"><span class="std std-ref">Capturing reference tags</span></a> for more +details.</p> +<p><code class="docutils literal notranslate"><span class="pre">--roles-<LANG>.<KIND></span></code> is the option for enabling/disabling +specified roles.</p> +</section> +<section id="pseudo-tags"> +<h2>Pseudo-tags<a class="headerlink" href="#pseudo-tags" title="Permalink to this headline">¶</a></h2> +<p>See <a class="reference internal" href="man/ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> about the +concept of the pseudo-tags.</p> +<section id="tag-kind-description"> +<h3><code class="docutils literal notranslate"><span class="pre">TAG_KIND_DESCRIPTION</span></code><a class="headerlink" href="#tag-kind-description" title="Permalink to this headline">¶</a></h3> +<p>This is a newly introduced pseudo-tag. It is not emitted by default. +It is emitted only when <code class="docutils literal notranslate"><span class="pre">--pseudo-tags=+TAG_KIND_DESCRIPTION</span></code> is +given.</p> +<p>This is for describing kinds; their letter, name, and description are +enumerated in the tag.</p> +<p>ctags emits <code class="docutils literal notranslate"><span class="pre">TAG_KIND_DESCRIPTION</span></code> with following format:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_KIND_SEPARATOR!{parser} {letter},{name} /{description}/ +</pre></div> +</div> +<p>A backslash and a slash in {description} is escaped with a backslash.</p> +</section> +<section id="tag-kind-separator"> +<h3><code class="docutils literal notranslate"><span class="pre">TAG_KIND_SEPARATOR</span></code><a class="headerlink" href="#tag-kind-separator" title="Permalink to this headline">¶</a></h3> +<p>This is a newly introduced pseudo-tag. It is not emitted by default. +It is emitted only when <code class="docutils literal notranslate"><span class="pre">--pseudo-tags=+TAG_KIND_SEPARATOR</span></code> is +given.</p> +<p>This is for describing separators placed between two kinds in a +language.</p> +<p>Tag entries including the separators are emitted when <code class="docutils literal notranslate"><span class="pre">--extras=+q</span></code> +is given; fully qualified tags contain the separators. The separators +are used in scope information, too.</p> +<p>ctags emits <code class="docutils literal notranslate"><span class="pre">TAG_KIND_SEPARATOR</span></code> with following format:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_KIND_SEPARATOR!{parser} {sep} /{upper}{lower}/ +</pre></div> +</div> +<p>or</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_KIND_SEPARATOR!{parser} {sep} /{lower}/ +</pre></div> +</div> +<p>Here {parser} is the name of language. e.g. PHP. +{lower} is the letter representing the kind of the lower item. +{upper} is the letter representing the kind of the upper item. +{sep} is the separator placed between the upper item and the lower +item.</p> +<p>The format without {upper} is for representing a root separator. The +root separator is used as prefix for an item which has no upper scope.</p> +<p><cite>*</cite> given as {upper} is a fallback wild card; if it is given, the +{sep} is used in combination with any upper item and the item +specified with {lower}.</p> +<p>Each backslash character used in {sep} is escaped with an extra +backslash character.</p> +<p>Example output:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>+p --pseudo-tags<span class="o">=</span> --pseudo-tags<span class="o">=</span>+TAG_KIND_SEPARATOR input.php +<span class="go">!_TAG_KIND_SEPARATOR!PHP :: /*c/</span> +<span class="go">...</span> +<span class="go">!_TAG_KIND_SEPARATOR!PHP \\ /c/</span> +<span class="go">...</span> +<span class="go">!_TAG_KIND_SEPARATOR!PHP \\ /nc/</span> +<span class="go">...</span> +</pre></div> +</div> +<p>The first line means <code class="docutils literal notranslate"><span class="pre">::</span></code> is used when combining something with an +item of the class kind.</p> +<p>The second line means <code class="docutils literal notranslate"><span class="pre">\\</span></code> is used when a class item is at the top +level; no upper item is specified.</p> +<p>The third line means <code class="docutils literal notranslate"><span class="pre">\\</span></code> is used when for combining a namespace item +(upper) and a class item (lower).</p> +<p>Of course, ctags uses the more specific line when choosing a +separator; the third line has higher priority than the first.</p> +</section> +<section id="tag-output-filesep"> +<h3><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_FILESEP</span></code><a class="headerlink" href="#tag-output-filesep" title="Permalink to this headline">¶</a></h3> +<p>This pseudo-tag represents the separator used in file name: slash or +backslash. This is always ‘slash’ on Unix-like environments. +This is also ‘slash’ by default on Windows, however when +<code class="docutils literal notranslate"><span class="pre">--output-format=e-tags</span></code> or <code class="docutils literal notranslate"><span class="pre">--use-slash-as-filename-separator=no</span></code> +is specified, it becomes ‘backslash’.</p> +</section> +<section id="tag-output-mode"> +<h3><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_MODE</span></code><a class="headerlink" href="#tag-output-mode" title="Permalink to this headline">¶</a></h3> +<p>This pseudo-tag represents output mode: u-ctags or e-ctags. +This is controlled by <code class="docutils literal notranslate"><span class="pre">--output-format</span></code> option.</p> +<p>See also <a class="reference internal" href="man/tags.5.html#compat-output"><span class="std std-ref">Compatible output and weakness</span></a>.</p> +</section> +</section> +<section id="truncating-the-pattern-for-long-input-lines"> +<h2>Truncating the pattern for long input lines<a class="headerlink" href="#truncating-the-pattern-for-long-input-lines" title="Permalink to this headline">¶</a></h2> +<p>See <code class="docutils literal notranslate"><span class="pre">--pattern-length-limit=N</span></code> option in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="parser-specific-fields"> +<span id="id2"></span><h2>Parser specific fields<a class="headerlink" href="#parser-specific-fields" title="Permalink to this headline">¶</a></h2> +<p>A tag has a <cite>name</cite>, an <cite>input</cite> file name, and a <cite>pattern</cite> as basic +information. Some fields like <cite>language:</cite>, <cite>signature:</cite>, etc are +attached to the tag as optional information.</p> +<p>In Exuberant Ctags, fields are common to all languages. +Universal Ctags extends the concept of fields; a parser can define +its specific field. This extension was proposed by @pragmaware in +<a class="reference external" href="https://github.com/universal-ctags/ctags/issues/857">#857</a>.</p> +<p>For implementing the parser specific fields, the options for listing and +enabling/disabling fields are also extended.</p> +<p>In the output of <code class="docutils literal notranslate"><span class="pre">--list-fields</span></code>, the owner of the field is printed +in the <cite>LANGUAGE</cite> column:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-fields +<span class="gp">#</span>LETTER NAME ENABLED LANGUAGE XFMT DESCRIPTION +<span class="go">...</span> +<span class="go">- end off C TRUE end lines of various constructs</span> +<span class="go">- properties off C TRUE properties (static, inline, mutable,...)</span> +<span class="go">- end off C++ TRUE end lines of various constructs</span> +<span class="go">- template off C++ TRUE template parameters</span> +<span class="go">- captures off C++ TRUE lambda capture list</span> +<span class="go">- properties off C++ TRUE properties (static, virtual, inline, mutable,...)</span> +<span class="go">- sectionMarker off reStructuredText TRUE character used for declaring section</span> +<span class="go">- version off Maven2 TRUE version of artifact</span> +</pre></div> +</div> +<p>e.g. reStructuredText is the owner of the sectionMarker field and +both C and C++ own the end field.</p> +<p><code class="docutils literal notranslate"><span class="pre">--list-fields</span></code> takes one optional argument, <cite>LANGUAGE</cite>. If it is +given, <code class="docutils literal notranslate"><span class="pre">--list-fields</span></code> prints only the fields for that parser:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-fields<span class="o">=</span>Maven2 +<span class="gp">#</span>LETTER NAME ENABLED LANGUAGE XFMT DESCRIPTION +<span class="go">- version off Maven2 TRUE version of artifact</span> +</pre></div> +</div> +<p>A parser specific field only has a long name, no letter. For +enabling/disabling such fields, the name must be passed to +<code class="docutils literal notranslate"><span class="pre">--fields-<LANG></span></code>.</p> +<p>e.g. for enabling the <cite>sectionMarker</cite> field owned by the +<cite>reStructuredText</cite> parser, use the following command line:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields-reStructuredText<span class="o">=</span>+<span class="o">{</span>sectionMarker<span class="o">}</span> ... +</pre></div> +</div> +<p>The wild card notation can be used for enabling/disabling parser specific +fields, too. The following example enables all fields owned by the +<cite>C++</cite> parser.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields-C++<span class="o">=</span><span class="s1">'*'</span> ... +</pre></div> +</div> +<p><cite>*</cite> can also be used for specifying languages.</p> +<p>The next example is for enabling <cite>end</cite> fields for all languages which +have such a field.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields-<span class="s1">'*'</span><span class="o">=</span>+<span class="s1">'{end}'</span> ... +<span class="go">...</span> +</pre></div> +</div> +<p>In this case, using wild card notation to specify the language, not +only fields owned by parsers but also common fields having the name +specified (<cite>end</cite> in this example) are enabled/disabled.</p> +<p>Using the wild card notation to specify the language is helpful to +avoid incompatibilities between versions of Universal Ctags itself +(SELF INCOMPATIBLY).</p> +<p>In Universal Ctags development, a parser developer may add a new +parser specific field for a certain language. Sometimes other developers +then recognize it is meaningful not only for the original language +but also other languages. In this case the field may be promoted to a +common field. Such a promotion will break the command line +compatibility for <code class="docutils literal notranslate"><span class="pre">--fields-<LANG></span></code> usage. The wild card for +<cite><LANG></cite> will help in avoiding this unwanted effect of the promotion.</p> +<p>With respect to the tags file format, nothing is changed when +introducing parser specific fields; <cite><fieldname></cite>:<cite><value></cite> is used as +before and the name of field owner is never prefixed. The <cite>language:</cite> +field of the tag identifies the owner.</p> +</section> +<section id="parser-specific-extras"> +<h2>Parser specific extras<a class="headerlink" href="#parser-specific-extras" title="Permalink to this headline">¶</a></h2> +<p>As man page of Exuberant Ctags says, <code class="docutils literal notranslate"><span class="pre">--extras</span></code> option specifies +whether to include extra tag entries for certain kinds of information. +This option is available in Universal Ctags, too.</p> +<p>In Universal Ctags it is extended; a parser can define its specific +extra flags. They can be controlled with <code class="docutils literal notranslate"><span class="pre">--extras-<LANG>=[+|-]{...}</span></code>.</p> +<p>See some examples:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-extras +<span class="gp">#</span>LETTER NAME ENABLED LANGUAGE DESCRIPTION +<span class="go">F fileScope TRUE NONE Include tags ...</span> +<span class="go">f inputFile FALSE NONE Include an entry ...</span> +<span class="go">p pseudo FALSE NONE Include pseudo tags</span> +<span class="go">q qualified FALSE NONE Include an extra ...</span> +<span class="go">r reference FALSE NONE Include reference tags</span> +<span class="go">g guest FALSE NONE Include tags ...</span> +<span class="go">- whitespaceSwapped TRUE Robot Include tags swapping ...</span> +</pre></div> +</div> +<p>See the <cite>LANGUAGE</cite> column. NONE means the extra flags are language +independent (common). They can be enabled or disabled with <cite>--extras=</cite> as before.</p> +<p>Look at <cite>whitespaceSwapped</cite>. Its language is <cite>Robot</cite>. This flag is enabled +by default but can be disabled with <cite>--extras-Robot=-{whitespaceSwapped}</cite>.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat input.robot +<span class="go">*** Keywords ***</span> +<span class="go">it's ok to be correct</span> +<span class="go"> Python_keyword_2</span> + +<span class="gp">$ </span>ctags -o - input.robot +<span class="go">it's ok to be correct input.robot /^it's ok to be correct$/;" k</span> +<span class="go">it's_ok_to_be_correct input.robot /^it's ok to be correct$/;" k</span> + +<span class="gp">$ </span>ctags -o - --extras-Robot<span class="o">=</span>-<span class="s1">'{whitespaceSwapped}'</span> input.robot +<span class="go">it's ok to be correct input.robot /^it's ok to be correct$/;" k</span> +</pre></div> +</div> +<p>When disabled the name <cite>it’s_ok_to_be_correct</cite> is not included in the +tags output. In other words, the name <cite>it’s_ok_to_be_correct</cite> is +derived from the name <cite>it’s ok to be correct</cite> when the extra flag is +enabled.</p> +<section id="discussion"> +<h3>Discussion<a class="headerlink" href="#discussion" title="Permalink to this headline">¶</a></h3> +<p>(This subsection should move to somewhere for developers.)</p> +<p>The question is what are extra tag entries. As far as I know none has +answered explicitly. I have two ideas in Universal Ctags. I +write “ideas”, not “definitions” here because existing parsers don’t +follow the ideas. They are kept as is in variety reasons but the +ideas may be good guide for people who wants to write a new parser +or extend an exiting parser.</p> +<p>The first idea is that a tag entry whose name is appeared in the input +file as is, the entry is NOT an extra. (If you want to control the +inclusion of such entries, the classical <code class="docutils literal notranslate"><span class="pre">--kind-<LANG>=[+|-]...</span></code> is +what you want.)</p> +<p>Qualified tags, whose inclusion is controlled by <code class="docutils literal notranslate"><span class="pre">--extras=+q</span></code>, is +explained well with this idea. +Let’s see an example:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat input.py +<span class="go">class Foo:</span> +<span class="go"> def func (self):</span> +<span class="go"> pass</span> + +<span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>+q --fields<span class="o">=</span>+E input.py +<span class="go">Foo input.py /^class Foo:$/;" c</span> +<span class="go">Foo.func input.py /^ def func (self):$/;" m class:Foo extra:qualified</span> +<span class="go">func input.py /^ def func (self):$/;" m class:Foo</span> +</pre></div> +</div> +<p><cite>Foo</cite> and <cite>func</cite> are in <cite>input.py</cite>. So they are no extra tags. In +other hand, <cite>Foo.func</cite> is not in <cite>input.py</cite> as is. The name is +generated by ctags as a qualified extra tag entry. +<cite>whitespaceSwapped</cite> extra flag of <cite>Robot</cite> parser is also aligned well +on the idea.</p> +<p>I don’t say all parsers follows this idea.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat input.cc +<span class="go">class A</span> +<span class="go">{</span> +<span class="go"> A operator+ (int);</span> +<span class="go">};</span> + +<span class="gp">$ </span>ctags --kinds-all<span class="o">=</span><span class="s1">'*'</span> --fields<span class="o">=</span> -o - input.cc +<span class="go">A input.cc /^class A$/</span> +<span class="go">operator + input.cc /^ A operator+ (int);$/</span> +</pre></div> +</div> +<p>In this example <cite>operator+</cite> is in <cite>input.cc</cite>. +In other hand, <cite>operator +</cite> is in the ctags output as non extra tag entry. +See a whitespace between the keyword <cite>operator</cite> and <cite>+</cite> operator. +This is an exception of the first idea.</p> +<p>The second idea is that if the <em>inclusion</em> of a tag cannot be +controlled well with <code class="docutils literal notranslate"><span class="pre">--kind-<LANG>=[+|-]...</span></code>, the tag may be an +extra.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat input.c +<span class="go">static int foo (void)</span> +<span class="go">{</span> +<span class="go"> return 0;</span> +<span class="go">}</span> +<span class="go">int bar (void)</span> +<span class="go">{</span> +<span class="go"> return 1;</span> +<span class="go">}</span> + +<span class="gp">$ </span>ctags --sort<span class="o">=</span>no -o - --extras<span class="o">=</span>+F input.c +<span class="go">foo input.c /^static int foo (void)$/;" f typeref:typename:int file:</span> +<span class="go">bar input.c /^int bar (void)$/;" f typeref:typename:int</span> + +<span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>-F input.c +<span class="go">foo input.c /^static int foo (void)$/;" f typeref:typename:int file:</span> + +<span class="gp">$</span> +</pre></div> +</div> +<p>Function <cite>foo</cite> of C language is included only when <cite>F</cite> extra flag +is enabled. Both <cite>foo</cite> and <cite>bar</cite> are functions. Their inclusions +can be controlled with <cite>f</cite> kind of C language: <code class="docutils literal notranslate"><span class="pre">--kind-C=[+|-]f</span></code>.</p> +<p>The difference between static modifier or implicit extern modifier in +a function definition is handled by <cite>F</cite> extra flag.</p> +<p>Basically the concept kind is for handling the kinds of language +objects: functions, variables, macros, types, etc. The concept extra +can handle the other aspects like scope (static or extern).</p> +<p>However, a parser developer can take another approach instead of +introducing parser specific extra; one can prepare <cite>staticFunction</cite> and +<cite>exportedFunction</cite> as kinds of one’s parser. The second idea is a +just guide; the parser developer must decide suitable approach for the +target language.</p> +<p>Anyway, in the second idea, <code class="docutils literal notranslate"><span class="pre">--extras</span></code> is for controlling inclusion +of tags. If what you want is not about inclusion, <code class="docutils literal notranslate"><span class="pre">--param-<LANG></span></code> +can be used as the last resort.</p> +</section> +</section> +<section id="parser-specific-parameter"> +<h2>Parser specific parameter<a class="headerlink" href="#parser-specific-parameter" title="Permalink to this headline">¶</a></h2> +<p>To control the detail of a parser, <code class="docutils literal notranslate"><span class="pre">--param-<LANG></span></code> option is introduced. +<code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code>, <code class="docutils literal notranslate"><span class="pre">--fields-<LANG></span></code>, <code class="docutils literal notranslate"><span class="pre">--extras-<LANG></span></code> +can be used for customizing the behavior of a parser specified with <code class="docutils literal notranslate"><span class="pre"><LANG></span></code>.</p> +<p><code class="docutils literal notranslate"><span class="pre">--param-<LANG></span></code> should be used for aspects of the parser that +the options(kinds, fields, extras) cannot handle well.</p> +<p>A parser defines a set of parameters. Each parameter has name and +takes an argument. A user can set a parameter with following notation</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">param</span><span class="o">-<</span><span class="n">LANG</span><span class="o">></span><span class="p">:</span><span class="n">name</span><span class="o">=</span><span class="n">arg</span> +</pre></div> +</div> +<p>An example of specifying a parameter</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">param</span><span class="o">-</span><span class="n">CPreProcessor</span><span class="p">:</span><span class="n">if0</span><span class="o">=</span><span class="n">true</span> +</pre></div> +</div> +<p>Here <cite>if0</cite> is a name of parameter of CPreProcessor parser and +<cite>true</cite> is the value of it.</p> +<p>All available parameters can be listed with <code class="docutils literal notranslate"><span class="pre">--list-params</span></code> option.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-params +<span class="gp">#</span>PARSER NAME DESCRIPTION +<span class="go">CPreProcessor if0 examine code within "#if 0" branch (true or [false])</span> +<span class="go">CPreProcessor ignore a token to be specially handled</span> +</pre></div> +</div> +<p>(At this time only CPreProcessor parser has parameters.)</p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Changes to the tags file format</a><ul> +<li><a class="reference internal" href="#f-kind-usage"><code class="docutils literal notranslate"><span class="pre">F</span></code> kind usage</a></li> +<li><a class="reference internal" href="#reference-tags">Reference tags</a></li> +<li><a class="reference internal" href="#pseudo-tags">Pseudo-tags</a><ul> +<li><a class="reference internal" href="#tag-kind-description"><code class="docutils literal notranslate"><span class="pre">TAG_KIND_DESCRIPTION</span></code></a></li> +<li><a class="reference internal" href="#tag-kind-separator"><code class="docutils literal notranslate"><span class="pre">TAG_KIND_SEPARATOR</span></code></a></li> +<li><a class="reference internal" href="#tag-output-filesep"><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_FILESEP</span></code></a></li> +<li><a class="reference internal" href="#tag-output-mode"><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_MODE</span></code></a></li> +</ul> +</li> +<li><a class="reference internal" href="#truncating-the-pattern-for-long-input-lines">Truncating the pattern for long input lines</a></li> +<li><a class="reference internal" href="#parser-specific-fields">Parser specific fields</a></li> +<li><a class="reference internal" href="#parser-specific-extras">Parser specific extras</a><ul> +<li><a class="reference internal" href="#discussion">Discussion</a></li> +</ul> +</li> +<li><a class="reference internal" href="#parser-specific-parameter">Parser specific parameter</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="output-format.html" + title="previous chapter">Output formats</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="output-xref.html" + title="next chapter">Xref output</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="output-xref.html" title="Xref output" + >next</a> |</li> + <li class="right" > + <a href="output-format.html" title="Output formats" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="output-format.html" >Output formats</a> »</li> + <li class="nav-item nav-item-this"><a href="">Changes to the tags file format</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file |