diff options
Diffstat (limited to 'ctags/docs/man/ctags-client-tools.7.html')
| -rw-r--r-- | ctags/docs/man/ctags-client-tools.7.html | 615 |
1 files changed, 615 insertions, 0 deletions
diff --git a/ctags/docs/man/ctags-client-tools.7.html b/ctags/docs/man/ctags-client-tools.7.html new file mode 100644 index 0000000..8acd0ef --- /dev/null +++ b/ctags/docs/man/ctags-client-tools.7.html @@ -0,0 +1,615 @@ + +<!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>ctags-client-tools — 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="ctags-faq" href="ctags-faq.7.html" /> + <link rel="prev" title="ctags-optlib" href="ctags-optlib.7.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="ctags-faq.7.html" title="ctags-faq" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-optlib.7.html" title="ctags-optlib" + 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="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-client-tools</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-client-tools"> +<span id="ctags-client-tools-7"></span><h1>ctags-client-tools<a class="headerlink" href="#ctags-client-tools" title="Permalink to this headline">¶</a></h1> +<p>Hints for developing a tool using ctags command and tags output</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>5.9.0</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal Ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>7</p> +</dd> +</dl> +<section id="synopsis"> +<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line"><strong>ctags</strong> [options] [file(s)]</div> +<div class="line"><strong>etags</strong> [options] [file(s)]</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p><strong>Client tool</strong> means a tool running the ctags command +and/or reading a tags file generated by ctags command. +This man page gathers hints for people who develop client tools.</p> +</section> +<section id="pseudo-tags"> +<h2>PSEUDO-TAGS<a class="headerlink" href="#pseudo-tags" title="Permalink to this headline">¶</a></h2> +<p><strong>Pseudo-tags</strong>, stored in a tag file, indicate how +ctags generated the tags file: whether the +tags file is sorted or not, which version of tags file format is used, +the name of tags generator, and so on. The opposite term for +pseudo-tags is <strong>regular-tags</strong>. A regular-tag is for a language +object in an input file. A pseudo-tag is for the tags file +itself. Client tools may use pseudo-tags as reference for processing +regular-tags.</p> +<p>A pseudo-tag is stored in a tags file in the same format as +regular-tags as described in <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>, except that pseudo-tag names +are prefixed with “!_”. For the general information about +pseudo-tags, see “TAG FILE INFORMATION” in <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>.</p> +<p>An example of a pseudo tag:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_PROGRAM_NAME Universal Ctags /Derived from Exuberant Ctags/ +</pre></div> +</div> +<p>The value, “2”, associated with the pseudo tag “TAG_PROGRAM_NAME”, is +used in the field for input file. The description, “Derived from +Exuberant Ctags”, is used in the field for pattern.</p> +<p>Universal Ctags extends the naming scheme of the classical pseudo-tags +available in Exuberant Ctags for emitting language specific +information as pseudo tags:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_{pseudo-tag-name}!{language-name} {associated-value} /{description}/ +</pre></div> +</div> +<p>The language-name is appended to the pseudo-tag name with a separator, “!”.</p> +<p>An example of pseudo tag with a language suffix:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_KIND_DESCRIPTION!C f,function /function definitions/ +</pre></div> +</div> +<p>This pseudo-tag says “the function kind of C language is enabled +when generating this tags file.” <code class="docutils literal notranslate"><span class="pre">--pseudo-tags</span></code> is the option for +enabling/disabling individual pseudo-tags. When enabling/disabling a +pseudo tag with the option, specify the tag name only +“TAG_KIND_DESCRIPTION”, without the prefix (“!_”) or the suffix (“!C”).</p> +<section id="options-for-pseudo-tags"> +<h3>Options for Pseudo-tags<a class="headerlink" href="#options-for-pseudo-tags" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--extras=+p</span></code> (or <code class="docutils literal notranslate"><span class="pre">--extras=+{pseudo}</span></code>)</dt><dd><p>Forces writing pseudo-tags.</p> +<p>ctags emits pseudo-tags by default when writing tags +to a regular file (e.g. “tags’.) However, when specifying <code class="docutils literal notranslate"><span class="pre">-o</span> <span class="pre">-</span></code> +or <code class="docutils literal notranslate"><span class="pre">-f</span> <span class="pre">-</span></code> for writing tags to standard output, +ctags doesn’t emit pseudo-tags. <code class="docutils literal notranslate"><span class="pre">--extras=+p</span></code> or +<code class="docutils literal notranslate"><span class="pre">--extras=+{pseudo}</span></code> will force pseudo-tags to be written.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code></dt><dd><p>Lists available types of pseudo-tags and shows whether they are enabled or disabled.</p> +<p>Running ctags with <code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code> option +lists available pseudo-tags. Some of pseudo-tags newly introduced +in Universal Ctags project are disabled by default. Use +<code class="docutils literal notranslate"><span class="pre">--pseudo-tags=...</span></code> to enable them.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--pseudo-tags=[+|-]names|*</span></code></dt><dd><p>Specifies a list of pseudo-tag types to include in the output.</p> +<p>The parameters are a set of pseudo tag names. Valid pseudo tag names +can be listed with <code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code>. Surround each name in the set +with braces, like “{TAG_PROGRAM_AUTHOR}”. You don’t have to include the “!_” +pseudo tag prefix when specifying a name in the option argument for <code class="docutils literal notranslate"><span class="pre">--pseudo-tags=</span></code> +option.</p> +<p>pseudo-tags don’t have a notation using one-letter flags.</p> +<p>If a name is preceded by either the ‘+’ or ‘-’ characters, that +tags’s effect has been added or removed. Otherwise the names replace +any current settings. All entries are included if ‘*’ is given.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--fields=+E</span></code> (or <code class="docutils literal notranslate"><span class="pre">--fields=+{extras}</span></code>)</dt><dd><p>Attach “extras:pseudo” field to pseudo-tags.</p> +<p>An example of pseudo tags with the field:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_PROGRAM_NAME Universal Ctags /Derived from Exuberant Ctags/ extras:pseudo +</pre></div> +</div> +<p>If the name of a normal tag in a tag file starts with “!_”, a +client tool cannot distinguish whether the tag is a regular-tag or +pseudo-tag. The fields attached with this option help the tool +distinguish them.</p> +</dd> +</dl> +</section> +<section id="list-of-notable-pseudo-tags"> +<h3>List of notable pseudo-tags<a class="headerlink" href="#list-of-notable-pseudo-tags" title="Permalink to this headline">¶</a></h3> +<p>Running ctags with <code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code> option lists available types +of pseudo-tags with short descriptions. This subsection shows hints +for using notable ones.</p> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_EXTRA_DESCRIPTION</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the names and descriptions of enabled extras:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_EXTRA_DESCRIPTION {extra-name} /description/ +!_TAG_EXTRA_DESCRIPTION!{language-name} {extra-name} /description/ +</pre></div> +</div> +<p>If your tool relies on some extra tags (extras), refer to +the pseudo-tags of this type. A tool can reject the tags file that +doesn’t include expected extras, and raise an error in an early +stage of processing.</p> +<p>An example of the pseudo-tags:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --extras=+p --pseudo-tags='{TAG_EXTRA_DESCRIPTION}' -o - input.c +!_TAG_EXTRA_DESCRIPTION anonymous /Include tags for non-named objects like lambda/ +!_TAG_EXTRA_DESCRIPTION fileScope /Include tags of file scope/ +!_TAG_EXTRA_DESCRIPTION pseudo /Include pseudo tags/ +!_TAG_EXTRA_DESCRIPTION subparser /Include tags generated by subparsers/ +... +</pre></div> +</div> +<p>A client tool can know “{anonymous}”, “{fileScope}”, “{pseudo}”, +and “{subparser}” extras are enabled from the output.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_FIELD_DESCRIPTION</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the names and descriptions of enabled fields:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_FIELD_DESCRIPTION {field-name} /description/ +!_TAG_FIELD_DESCRIPTION!{language-name} {field-name} /description/ +</pre></div> +</div> +<p>If your tool relies on some fields, refer to the pseudo-tags of +this type. A tool can reject a tags file that doesn’t include +expected fields, and raise an error in an early stage of +processing.</p> +<p>An example of the pseudo-tags:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --fields-C=+'{macrodef}' --extras=+p --pseudo-tags='{TAG_FIELD_DESCRIPTION}' -o - input.c +!_TAG_FIELD_DESCRIPTION file /File-restricted scoping/ +!_TAG_FIELD_DESCRIPTION input /input file/ +!_TAG_FIELD_DESCRIPTION name /tag name/ +!_TAG_FIELD_DESCRIPTION pattern /pattern/ +!_TAG_FIELD_DESCRIPTION typeref /Type and name of a variable or typedef/ +!_TAG_FIELD_DESCRIPTION!C macrodef /macro definition/ +... +</pre></div> +</div> +<p>A client tool can know “{file}”, “{input}”, “{name}”, “{pattern}”, +and “{typeref}” fields are enabled from the output. +The fields are common in languages. In addition to the common fields, +the tool can known “{macrodef}” field of C language is also enabled.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_FILE_ENCODING</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_FILE_FORMAT</span></code></dt><dd><p>See also <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_FILE_SORTED</span></code></dt><dd><p>See also <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_KIND_DESCRIPTION</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the names and descriptions of enabled kinds:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_KIND_DESCRIPTION!{language-name} {kind-letter},{kind-name} /description/ +</pre></div> +</div> +<p>If your tool relies on some kinds, refer to the pseudo-tags of +this type. A tool can reject the tags file that doesn’t include +expected kinds, and raise an error in an early stage of +processing.</p> +<p>Kinds are language specific, so a language name is always +appended to the tag name as suffix.</p> +<p>An example of the pseudo-tags:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --extras=+p --kinds-C=vfm --pseudo-tags='{TAG_KIND_DESCRIPTION}' -o - input.c +!_TAG_KIND_DESCRIPTION!C f,function /function definitions/ +!_TAG_KIND_DESCRIPTION!C m,member /struct, and union members/ +!_TAG_KIND_DESCRIPTION!C v,variable /variable definitions/ +... +</pre></div> +</div> +<p>A client tool can know “{function}”, “{member}”, and “{variable}” +kinds of C language are enabled from the output.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_KIND_SEPARATOR</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_EXCMD</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the specified type of EX command with <code class="docutils literal notranslate"><span class="pre">--excmd</span></code> option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_FILESEP</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_MODE</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_PATTERN_LENGTH_LIMIT</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_PROC_CWD</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the working directory of ctags during processing.</p> +<p>This pseudo-tag helps a client tool solve the absolute paths for +the input files for tag entries even when they are tagged with +relative paths.</p> +<p>An example of the pseudo-tags:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cat tags +!_TAG_PROC_CWD /tmp/ // +main input.c /^int main (void) { return 0; }$/;" f typeref:typename:int +... +</pre></div> +</div> +<p>From the regular tag for “main”, the client tool can know the +“main” is at “input.c”. However, it is a relative path. So if the +directory where ctags run and the directory +where the client tool runs are different, the client tool cannot +find “input.c” from the file system. In that case, +<code class="docutils literal notranslate"><span class="pre">TAG_PROC_CWD</span></code> gives the tool a hint; “input.c” may be at “/tmp”.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_PROGRAM_NAME</span></code></dt><dd><p>TBW</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_ROLE_DESCRIPTION</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the names and descriptions of enabled roles:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_ROLE_DESCRIPTION!{language-name}!{kind-name} {role-name} /description/ +</pre></div> +</div> +<p>If your tool relies on some roles, refer to the pseudo-tags of +this type. Note that a role owned by a disabled kind is not listed +even if the role itself is enabled.</p> +</dd> +</dl> +</section> +</section> +<section id="redundant-kinds"> +<h2>REDUNDANT-KINDS<a class="headerlink" href="#redundant-kinds" title="Permalink to this headline">¶</a></h2> +<p>TBW</p> +</section> +<section id="multiple-languages-for-an-input-file"> +<h2>MULTIPLE-LANGUAGES FOR AN INPUT FILE<a class="headerlink" href="#multiple-languages-for-an-input-file" title="Permalink to this headline">¶</a></h2> +<p>Universal ctags can run multiple parsers. +That means a parser, which supports multiple parsers, may output tags for +different languages. <code class="docutils literal notranslate"><span class="pre">language</span></code>/<code class="docutils literal notranslate"><span class="pre">l</span></code> field can be used to show the language +for each tag.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat /tmp/foo.html +<span class="go"><html></span> +<span class="go"><script>var x = 1</script></span> +<span class="go"><h1>title</h1></span> +<span class="go"></html></span> +<span class="gp">$ </span>./ctags -o - --extras<span class="o">=</span>+g /tmp/foo.html +<span class="go">title /tmp/foo.html /^ <h1>title<\/h1>$/;" h</span> +<span class="go">x /tmp/foo.html /var x = 1/;" v</span> +<span class="gp">$ </span>./ctags -o - --extras<span class="o">=</span>+g --fields<span class="o">=</span>+l /tmp/foo.html +<span class="go">title /tmp/foo.html /^ <h1>title<\/h1>$/;" h language:HTML</span> +<span class="go">x /tmp/foo.html /var x = 1/;" v language:JavaScript</span> +</pre></div> +</div> +</section> +<section id="utilizing-readtags"> +<h2>UTILIZING READTAGS<a class="headerlink" href="#utilizing-readtags" title="Permalink to this headline">¶</a></h2> +<p>See <a class="reference internal" href="readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a> to know how to use readtags. This section is for discussing +some notable topics for client tools.</p> +<section id="build-filter-sorter-expressions"> +<h3>Build Filter/Sorter Expressions<a class="headerlink" href="#build-filter-sorter-expressions" title="Permalink to this headline">¶</a></h3> +<p>Certain escape sequences in expressions are recognized by readtags. For +example, when searching for a tag that matches <code class="docutils literal notranslate"><span class="pre">a\?b</span></code>, if using a filter +expression like <code class="docutils literal notranslate"><span class="pre">'(eq?</span> <span class="pre">$name</span> <span class="pre">"a\?b")'</span></code>, since <code class="docutils literal notranslate"><span class="pre">\?</span></code> is translated into a +single <code class="docutils literal notranslate"><span class="pre">?</span></code> by readtags, it actually searches for <code class="docutils literal notranslate"><span class="pre">a?b</span></code>.</p> +<p>Another problem is if a single quote appear in filter expressions (which is +also wrapped by single quotes), it terminates the expression, producing broken +expressions, and may even cause unintended shell injection. Single quotes can +be escaped using <code class="docutils literal notranslate"><span class="pre">'"'"'</span></code>.</p> +<p>So, client tools need to:</p> +<ul class="simple"> +<li><p>Replace <code class="docutils literal notranslate"><span class="pre">\</span></code> by <code class="docutils literal notranslate"><span class="pre">\\</span></code></p></li> +<li><p>Replace <code class="docutils literal notranslate"><span class="pre">'</span></code> by <code class="docutils literal notranslate"><span class="pre">'"'"'</span></code></p></li> +</ul> +<p>inside the expressions. If the expression also contains strings, <code class="docutils literal notranslate"><span class="pre">"</span></code> in the +strings needs to be replaced by <code class="docutils literal notranslate"><span class="pre">\"</span></code>.</p> +<p>Client tools written in Lisp could build the expression using lists. <code class="docutils literal notranslate"><span class="pre">prin1</span></code> +(in Common Lisp style Lisps) and <code class="docutils literal notranslate"><span class="pre">write</span></code> (in Scheme style Lisps) can +translate the list into a string that can be directly used. For example, in +EmacsLisp:</p> +<div class="highlight-EmacsLisp notranslate"><div class="highlight"><pre><span></span>(let ((name "hi")) + (prin1 `(eq? $name ,name))) +=> "(eq\\? $name "hi")" +</pre></div> +</div> +<p>The “?” is escaped, and readtags can handle it. Scheme style Lisps should do +proper escaping so the expression readtags gets is just the expression passed +into <code class="docutils literal notranslate"><span class="pre">write</span></code>. Common Lisp style Lisps may produce unrecognized escape +sequences by readtags, like <code class="docutils literal notranslate"><span class="pre">\#</span></code>. Readtags provides some aliases for these +Lisps:</p> +<ul class="simple"> +<li><p>Use <code class="docutils literal notranslate"><span class="pre">true</span></code> for <code class="docutils literal notranslate"><span class="pre">#t</span></code>.</p></li> +<li><p>Use <code class="docutils literal notranslate"><span class="pre">false</span></code> for <code class="docutils literal notranslate"><span class="pre">#f</span></code>.</p></li> +<li><p>Use <code class="docutils literal notranslate"><span class="pre">nil</span></code> or <code class="docutils literal notranslate"><span class="pre">()</span></code> for <code class="docutils literal notranslate"><span class="pre">()</span></code>.</p></li> +<li><p>Use <code class="docutils literal notranslate"><span class="pre">(string->regexp</span> <span class="pre">"PATTERN")</span></code> for <code class="docutils literal notranslate"><span class="pre">#/PATTERN/</span></code>. Use +<code class="docutils literal notranslate"><span class="pre">(string->regexp</span> <span class="pre">"PATTERN"</span> <span class="pre">:case-fold</span> <span class="pre">true)</span></code> for <code class="docutils literal notranslate"><span class="pre">#/PATTERN/i</span></code>. Notice +that <code class="docutils literal notranslate"><span class="pre">string->regexp</span></code> doesn’t require escaping “/” in the pattern.</p></li> +</ul> +<p>Notice that even when the client tool uses this method, <code class="docutils literal notranslate"><span class="pre">'</span></code> still needs to be +replaced by <code class="docutils literal notranslate"><span class="pre">'"'"'</span></code> to prevent broken expressions and shell injection.</p> +<p>Another thing to notice is that missing fields are represented by <code class="docutils literal notranslate"><span class="pre">#f</span></code>, and +applying string operators to them will produce an error. You should always +check if a field is missing before applying string operators. See the +“Filtering” section in <a class="reference internal" href="readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a> to know how to do this. Run “readtags -H +filter” to see which operators take string arguments.</p> +</section> +<section id="parse-readtags-output"> +<h3>Parse Readtags Output<a class="headerlink" href="#parse-readtags-output" title="Permalink to this headline">¶</a></h3> +<p>In the output of readtags, tabs can appear in all field values (e.g., the tag +name itself could contain tabs), which makes it hard to split the line into +fields. Client tools should use the <code class="docutils literal notranslate"><span class="pre">-E</span></code> option, which keeps the escape +sequences in the tags file, so the only field that could contain tabs is the +pattern field.</p> +<p>The pattern field could:</p> +<ul class="simple"> +<li><p>Use a line number. It will look like <code class="docutils literal notranslate"><span class="pre">number;"</span></code> (e.g. <code class="docutils literal notranslate"><span class="pre">10;"</span></code>).</p></li> +<li><p>Use a search pattern. It will look like <code class="docutils literal notranslate"><span class="pre">/pattern/;"</span></code> or <code class="docutils literal notranslate"><span class="pre">?pattern?;"</span></code>. +Notice that the search pattern could contain tabs.</p></li> +<li><p>Combine these two, like <code class="docutils literal notranslate"><span class="pre">number;/pattern/;"</span></code> or <code class="docutils literal notranslate"><span class="pre">number;?pattern?;"</span></code>.</p></li> +</ul> +<p>These are true for tags files using extended format, which is the default one. +The legacy format (i.e. <code class="docutils literal notranslate"><span class="pre">--format=1</span></code>) doesn’t include the semicolons. It’s +old and barely used, so we won’t discuss it here.</p> +<p>Client tools could split the line using the following steps:</p> +<ul class="simple"> +<li><p>Find the first 2 tabs in the line, so we get the name and input field.</p></li> +<li><p>From the 2nd tab:</p> +<ul> +<li><p>If a <code class="docutils literal notranslate"><span class="pre">/</span></code> follows, then the pattern delimiter is <code class="docutils literal notranslate"><span class="pre">/</span></code>.</p></li> +<li><p>If a <code class="docutils literal notranslate"><span class="pre">?</span></code> follows, then the pattern delimiter is <code class="docutils literal notranslate"><span class="pre">?</span></code>.</p></li> +<li><p>If a number follows, then:</p> +<ul> +<li><p>If a <code class="docutils literal notranslate"><span class="pre">;/</span></code> follows the number, then the delimiter is <code class="docutils literal notranslate"><span class="pre">/</span></code>.</p></li> +<li><p>If a <code class="docutils literal notranslate"><span class="pre">;?</span></code> follows the number, then the delimiter is <code class="docutils literal notranslate"><span class="pre">?</span></code>.</p></li> +<li><p>If a <code class="docutils literal notranslate"><span class="pre">;"</span></code> follows the number, then the field uses only line number, and +there’s no pattern delimiter (since there’s no regex pattern). In this +case the pattern field ends at the 3rd tab.</p></li> +</ul> +</li> +</ul> +</li> +<li><p>After the opening delimiter, find the next unescaped pattern delimiter, and +that’s the closing delimiter. It will be followed by <code class="docutils literal notranslate"><span class="pre">;"</span></code> and then a tab. +That’s the end of the pattern field. By “unescaped pattern delimiter”, we +mean there’s an even number (including 0) of backslashes before it.</p></li> +<li><p>From here, split the rest of the line into fields by tabs.</p></li> +</ul> +<p>Then, the escape sequences in fields other than the pattern field should be +translated. See “Proposal” in <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> to know about all the escape sequences.</p> +</section> +<section id="make-use-of-the-pattern-field"> +<h3>Make Use of the Pattern Field<a class="headerlink" href="#make-use-of-the-pattern-field" title="Permalink to this headline">¶</a></h3> +<p>The pattern field specifies how to find a tag in its source file. The code +generating this field seems to have a long history, so there are some pitfalls +and it’s a bit hard to handle. A client tool could simply require the <code class="docutils literal notranslate"><span class="pre">line:</span></code> +field and jump to the line it specifies, to avoid using the pattern field. But +anyway, we’ll discuss how to make the best use of it here.</p> +<p>You should take the words here merely as suggestions, and not standards. A +client tool could definitely develop better (or simpler) ways to use the +pattern field.</p> +<p>From the last section, we know the pattern field could contain a line number +and a search pattern. When it only contains the line number, handling it is +easy: you simply go to that line.</p> +<p>The search pattern resembles an EX command, but as we’ll see later, it’s +actually not a valid one, so some manual work are required to process it.</p> +<p>The search pattern could look like <code class="docutils literal notranslate"><span class="pre">/pat/</span></code>, called “forward search pattern”, +or <code class="docutils literal notranslate"><span class="pre">?pat?</span></code>, called “backward search pattern”. Using a search pattern means +even if the source file is updated, as long as the part containing the tag +doesn’t change, we could still locate the tag correctly by searching.</p> +<p>When the pattern field only contains the search pattern, you just search for +it. The search direction (forward/backward) doesn’t matter, as it’s decided +solely by whether the <code class="docutils literal notranslate"><span class="pre">-B</span></code> option is enabled, and not the actual context. You +could always start the search from say the beginning of the file.</p> +<p>When both the search pattern and the line number are presented, you could make +good use of the line number, by going to the line first, then searching for the +nearest occurence of the pattern. A way to do this is to search both forward +and backward for the pattern, and when there is a occurence on both sides, go +to the nearer one.</p> +<p>What’s good about this is when there are multiple identical lines in the source +file (e.g. the COMMON block in Fortran), this could help us find the correct +one, even after the source file is updated and the tag position is shifted by a +few lines.</p> +<p>Now let’s discuss how to search for the pattern. After you trim the <code class="docutils literal notranslate"><span class="pre">/</span></code> or +<code class="docutils literal notranslate"><span class="pre">?</span></code> around it, the pattern resembles a regex pattern. It should be a regex +pattern, as required by being a valid EX command, but it’s actually not, as +you’ll see below.</p> +<p>It could begin with a <code class="docutils literal notranslate"><span class="pre">^</span></code>, which means the pattern starts from the beginning +of a line. It could also end with an <em>unescaped</em> <code class="docutils literal notranslate"><span class="pre">$</span></code> which means the pattern +ends at the end of a line. Let’s keep this information, and trim them too.</p> +<p>Now the remaining part is the actual string containing the tag. Some characters +are escaped:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">\</span></code>.</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">$</span></code>, but only at the end of the string.</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">/</span></code>, but only in forward search patterns.</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">?</span></code>, but only in backward search patterns.</p></li> +</ul> +<p>You need to unescape these to get the literal string. Now you could convert +this literal string to a regexp that matches it (by escaping, like +<code class="docutils literal notranslate"><span class="pre">re.escape</span></code> in Python or <code class="docutils literal notranslate"><span class="pre">regexp-quote</span></code> in Elisp), and assemble it with +<code class="docutils literal notranslate"><span class="pre">^</span></code> or <code class="docutils literal notranslate"><span class="pre">$</span></code> if the pattern originally has it, and finally search for the tag +using this regexp.</p> +</section> +<section id="remark-about-a-previous-format-of-the-pattern-field"> +<h3>Remark: About a Previous Format of the Pattern Field<a class="headerlink" href="#remark-about-a-previous-format-of-the-pattern-field" title="Permalink to this headline">¶</a></h3> +<p>In some earlier versions of Universal Ctags, the line number in the pattern +field is the actual line number minus one, for forward search patterns; or plus +one, for backward search patterns. The idea is to resemble an EX command: you +go to the line, then search forward/backward for the pattern, and you can +always find the correct one. But this denies the purpose of using a search +pattern: to tolerate file updates. For example, the tag is at line 50, +according to this scheme, the pattern field should be:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">49</span><span class="p">;</span><span class="o">/</span><span class="n">pat</span><span class="o">/</span><span class="p">;</span><span class="s2">"</span> +</pre></div> +</div> +<p>Then let’s assume that some code above are removed, and the tag is now at +line 45. Now you can’t find it if you search forward from line 49.</p> +<p>Due to this reason, Universal Ctags turns to use the actual line number. A +client tool could distinguish them by the <code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_EXCMD</span></code> pseudo tag, it’s +“combine” for the old scheme, and “combineV2” for the present scheme. But +probably there’s no need to treat them differently, since “search for the +nearest occurence from the line” gives good result on both schemes.</p> +</section> +</section> +<section id="json-output"> +<h2>JSON OUTPUT<a class="headerlink" href="#json-output" title="Permalink to this headline">¶</a></h2> +<p>Universal Ctags supports <a class="reference external" href="https://www.json.org/">JSON</a> (strictly +speaking <a class="reference external" href="https://jsonlines.org/">JSON Lines</a>) output format if the +ctags executable is built with <code class="docutils literal notranslate"><span class="pre">libjansson</span></code>. JSON output goes to +standard output by default.</p> +<section id="format"> +<h3>Format<a class="headerlink" href="#format" title="Permalink to this headline">¶</a></h3> +<p>Each JSON line represents a tag.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --extras<span class="o">=</span>+p --output-format<span class="o">=</span>json --fields<span class="o">=</span>-s input.py +<span class="go">{"_type": "ptag", "name": "JSON_OUTPUT_VERSION", "path": "0.0", "pattern": "in development"}</span> +<span class="go">{"_type": "ptag", "name": "TAG_FILE_SORTED", "path": "1", "pattern": "0=unsorted, 1=sorted, 2=foldcase"}</span> +<span class="go">...</span> +<span class="go">{"_type": "tag", "name": "Klass", "path": "/tmp/input.py", "pattern": "/^class Klass:$/", "language": "Python", "kind": "class"}</span> +<span class="go">{"_type": "tag", "name": "method", "path": "/tmp/input.py", "pattern": "/^ def method(self):$/", "language": "Python", "kind": "member", "scope": "Klass", "scopeKind": "class"}</span> +<span class="go">...</span> +</pre></div> +</div> +<p>A key not starting with <code class="docutils literal notranslate"><span class="pre">_</span></code> is mapped to a field of ctags. +“<code class="docutils literal notranslate"><span class="pre">--output-format=json</span> <span class="pre">--list-fields</span></code>” options list the fields.</p> +<p>A key starting with <code class="docutils literal notranslate"><span class="pre">_</span></code> represents meta information of the JSON +line. Currently only <code class="docutils literal notranslate"><span class="pre">_type</span></code> key is used. If the value for the key +is <code class="docutils literal notranslate"><span class="pre">tag</span></code>, the JSON line represents a normal tag. If the value is +<code class="docutils literal notranslate"><span class="pre">ptag</span></code>, the line represents a pseudo-tag.</p> +<p>The output format can be changed in the +future. <code class="docutils literal notranslate"><span class="pre">JSON_OUTPUT_VERSION</span></code> pseudo-tag provides a change +client-tools to handle the changes. Current version is “0.0”. A +client-tool can extract the version with <code class="docutils literal notranslate"><span class="pre">path</span></code> key from the +pseudo-tag.</p> +<p>The JSON output format is newly designed and has no limitation found +in the default tags file format.</p> +<ul class="simple"> +<li><p>The values for <code class="docutils literal notranslate"><span class="pre">kind</span></code> key are represented in long-name flags. +No one-letter is here.</p></li> +<li><p>Scope names and scope kinds have distinguished keys: <code class="docutils literal notranslate"><span class="pre">scope</span></code> and <code class="docutils literal notranslate"><span class="pre">scopeKind</span></code>. +They are combined in the default tags file format.</p></li> +</ul> +</section> +<section id="data-type-used-in-a-field"> +<h3>Data type used in a field<a class="headerlink" href="#data-type-used-in-a-field" title="Permalink to this headline">¶</a></h3> +<p>Values for the most of all keys are represented in JSON string type. +However, some of them are represented in string, integer, and/or boolean type.</p> +<p>“<code class="docutils literal notranslate"><span class="pre">--output-format=json</span> <span class="pre">--list-fields</span></code>” options show What kind of data type +used in a field of JSON.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --output-format<span class="o">=</span>json --list-fields +<span class="gp">#</span>LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION +<span class="go">F input yes NONE s-- no input file</span> +<span class="go">...</span> +<span class="go">P pattern yes NONE s-b no pattern</span> +<span class="go">...</span> +<span class="go">f file yes NONE --b no File-restricted scoping</span> +<span class="go">...</span> +<span class="go">e end no NONE -i- no end lines of various items</span> +<span class="go">...</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">JSTYPE</span></code> column shows the data types.</p> +<dl class="simple"> +<dt>‘<code class="docutils literal notranslate"><span class="pre">s</span></code>’</dt><dd><p>string</p> +</dd> +<dt>‘<code class="docutils literal notranslate"><span class="pre">i</span></code>’</dt><dd><p>integer</p> +</dd> +<dt>‘<code class="docutils literal notranslate"><span class="pre">b</span></code>’</dt><dd><p>boolean (true or false)</p> +</dd> +</dl> +<p>For an example, the value for <code class="docutils literal notranslate"><span class="pre">pattern</span></code> field of ctags takes a string or a boolean value.</p> +</section> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, <a class="reference internal" href="ctags-lang-python.7.html#ctags-lang-python-7"><span class="std std-ref">ctags-lang-python(7)</span></a>, <a class="reference internal" href="ctags-incompatibilities.7.html#ctags-incompatibilities-7"><span class="std std-ref">ctags-incompatibilities(7)</span></a>, <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>, <a class="reference internal" href="readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a></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="#">ctags-client-tools</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a></li> +<li><a class="reference internal" href="#pseudo-tags">PSEUDO-TAGS</a><ul> +<li><a class="reference internal" href="#options-for-pseudo-tags">Options for Pseudo-tags</a></li> +<li><a class="reference internal" href="#list-of-notable-pseudo-tags">List of notable pseudo-tags</a></li> +</ul> +</li> +<li><a class="reference internal" href="#redundant-kinds">REDUNDANT-KINDS</a></li> +<li><a class="reference internal" href="#multiple-languages-for-an-input-file">MULTIPLE-LANGUAGES FOR AN INPUT FILE</a></li> +<li><a class="reference internal" href="#utilizing-readtags">UTILIZING READTAGS</a><ul> +<li><a class="reference internal" href="#build-filter-sorter-expressions">Build Filter/Sorter Expressions</a></li> +<li><a class="reference internal" href="#parse-readtags-output">Parse Readtags Output</a></li> +<li><a class="reference internal" href="#make-use-of-the-pattern-field">Make Use of the Pattern Field</a></li> +<li><a class="reference internal" href="#remark-about-a-previous-format-of-the-pattern-field">Remark: About a Previous Format of the Pattern Field</a></li> +</ul> +</li> +<li><a class="reference internal" href="#json-output">JSON OUTPUT</a><ul> +<li><a class="reference internal" href="#format">Format</a></li> +<li><a class="reference internal" href="#data-type-used-in-a-field">Data type used in a field</a></li> +</ul> +</li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-optlib.7.html" + title="previous chapter">ctags-optlib</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-faq.7.html" + title="next chapter">ctags-faq</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="ctags-faq.7.html" title="ctags-faq" + >next</a> |</li> + <li class="right" > + <a href="ctags-optlib.7.html" title="ctags-optlib" + >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="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-client-tools</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 |