diff options
| author | Indrajith K L | 2022-12-03 17:00:20 +0530 |
|---|---|---|
| committer | Indrajith K L | 2022-12-03 17:00:20 +0530 |
| commit | f5c4671bfbad96bf346bd7e9a21fc4317b4959df (patch) | |
| tree | 2764fc62da58f2ba8da7ed341643fc359873142f /ctags/docs/man | |
| download | cli-tools-windows-master.tar.gz cli-tools-windows-master.tar.bz2 cli-tools-windows-master.zip | |
Diffstat (limited to 'ctags/docs/man')
| -rw-r--r-- | ctags/docs/man/ctags-client-tools.7.html | 615 | ||||
| -rw-r--r-- | ctags/docs/man/ctags-faq.7.html | 510 | ||||
| -rw-r--r-- | ctags/docs/man/ctags-incompatibilities.7.html | 337 | ||||
| -rw-r--r-- | ctags/docs/man/ctags-lang-iPythonCell.7.html | 186 | ||||
| -rw-r--r-- | ctags/docs/man/ctags-lang-inko.7.html | 141 | ||||
| -rw-r--r-- | ctags/docs/man/ctags-lang-julia.7.html | 332 | ||||
| -rw-r--r-- | ctags/docs/man/ctags-lang-python.7.html | 476 | ||||
| -rw-r--r-- | ctags/docs/man/ctags-lang-r.7.html | 210 | ||||
| -rw-r--r-- | ctags/docs/man/ctags-lang-sql.7.html | 237 | ||||
| -rw-r--r-- | ctags/docs/man/ctags-lang-verilog.7.html | 318 | ||||
| -rw-r--r-- | ctags/docs/man/ctags-optlib.7.html | 520 | ||||
| -rw-r--r-- | ctags/docs/man/ctags.1.html | 1989 | ||||
| -rw-r--r-- | ctags/docs/man/readtags.1.html | 449 | ||||
| -rw-r--r-- | ctags/docs/man/tags.5.html | 619 |
14 files changed, 6939 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 diff --git a/ctags/docs/man/ctags-faq.7.html b/ctags/docs/man/ctags-faq.7.html new file mode 100644 index 0000000..433e5e7 --- /dev/null +++ b/ctags/docs/man/ctags-faq.7.html @@ -0,0 +1,510 @@ + +<!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-faq — 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-lang-iPythonCell" href="ctags-lang-iPythonCell.7.html" /> + <link rel="prev" title="ctags-client-tools" href="ctags-client-tools.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-lang-iPythonCell.7.html" title="ctags-lang-iPythonCell" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-client-tools.7.html" title="ctags-client-tools" + 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-faq</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-faq"> +<span id="ctags-faq-7"></span><h1><a class="toc-backref" href="#id2">ctags-faq</a><a class="headerlink" href="#ctags-faq" title="Permalink to this headline">¶</a></h1> +<p>Universal Ctags FAQ</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> +<p>This is the Universal Ctags FAQ (Frequently-Asked Questions). +It is based on <a class="reference external" href="http://ctags.sourceforge.net/faq.html">Exuberant Ctags FAQ</a></p> +<div class="contents topic" id="contents"> +<p class="topic-title">Contents</p> +<ul class="simple"> +<li><p><a class="reference internal" href="#ctags-faq" id="id2">ctags-faq</a></p> +<ul> +<li><p><a class="reference internal" href="#description" id="id3">DESCRIPTION</a></p> +<ul> +<li><p><a class="reference internal" href="#what-is-the-difference-between-universal-ctags-and-exuberant-ctags" id="id4">What is the difference between Universal Ctags and Exuberant Ctags?</a></p></li> +<li><p><a class="reference internal" href="#how-can-i-avoid-having-to-specify-my-favorite-option-every-time" id="id5">How can I avoid having to specify my favorite option every time?</a></p></li> +<li><p><a class="reference internal" href="#what-are-these-strange-bits-of-text-beginning-with-which-follow-many-of-the-lines-in-the-tag-file" id="id6">What are these strange bits of text beginning with <code class="docutils literal notranslate"><span class="pre">;"</span></code> which follow many of the lines in the tag file?</a></p></li> +<li><p><a class="reference internal" href="#why-can-t-i-jump-to-class-member" id="id7">Why can’t I jump to <code class="docutils literal notranslate"><span class="pre">class::member</span></code>?</a></p></li> +<li><p><a class="reference internal" href="#why-do-i-end-up-on-the-wrong-line-when-i-jump-to-a-tag" id="id8">Why do I end up on the wrong line when I jump to a tag?</a></p></li> +<li><p><a class="reference internal" href="#how-do-i-jump-to-the-tag-i-want-instead-of-the-wrong-one-by-the-same-name" id="id9">How do I jump to the tag I want instead of the wrong one by the same name?</a></p></li> +<li><p><a class="reference internal" href="#how-can-i-locate-all-references-to-a-specific-function-or-variable" id="id10">How can I locate all references to a specific function or variable?</a></p></li> +<li><p><a class="reference internal" href="#why-does-appending-tags-to-a-tag-file-tag-so-long" id="id11">Why does appending tags to a tag file tag so long?</a></p></li> +<li><p><a class="reference internal" href="#how-should-i-set-up-tag-files-for-a-multi-level-directory-hierarchy" id="id12">How should I set up tag files for a multi-level directory hierarchy?</a></p></li> +<li><p><a class="reference internal" href="#does-universal-ctags-support-unicode-file-names" id="id13">Does Universal Ctags support Unicode file names?</a></p></li> +<li><p><a class="reference internal" href="#why-does-zsh-cause-zsh-no-matches-found-error" id="id14">Why does zsh cause “zsh: no matches found” error?</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#see-also" id="id15">SEE ALSO</a></p></li> +<li><p><a class="reference internal" href="#author" id="id16">AUTHOR</a></p></li> +</ul> +</li> +</ul> +</div> +<section id="description"> +<h2><a class="toc-backref" href="#id3">DESCRIPTION</a><a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<section id="what-is-the-difference-between-universal-ctags-and-exuberant-ctags"> +<h3><a class="toc-backref" href="#id4">What is the difference between Universal Ctags and Exuberant Ctags?</a><a class="headerlink" href="#what-is-the-difference-between-universal-ctags-and-exuberant-ctags" title="Permalink to this headline">¶</a></h3> +<p>Universal Ctags is an unofficial fork of Exuberant Ctags. +The differences are summarized in <a class="reference internal" href="ctags-incompatibilities.7.html#ctags-incompatibilities-7"><span class="std std-ref">ctags-incompatibilities(7)</span></a> man page.</p> +<p>The most notable one is that Universal Ctags doesn’t read <code class="docutils literal notranslate"><span class="pre">~/.ctags</span></code> file. +Instead, it reads <code class="docutils literal notranslate"><span class="pre">*.ctags</span></code> under <code class="docutils literal notranslate"><span class="pre">~/.ctags.d</span></code> directory.</p> +</section> +<section id="how-can-i-avoid-having-to-specify-my-favorite-option-every-time"> +<h3><a class="toc-backref" href="#id5">How can I avoid having to specify my favorite option every time?</a><a class="headerlink" href="#how-can-i-avoid-having-to-specify-my-favorite-option-every-time" title="Permalink to this headline">¶</a></h3> +<p>Either by setting the environment variable <code class="docutils literal notranslate"><span class="pre">CTAGS</span></code> to your custom +options, or putting them into a <code class="docutils literal notranslate"><span class="pre">~/.ctags.d/anyname.ctags</span></code> file in your home +directory.</p> +</section> +<section id="what-are-these-strange-bits-of-text-beginning-with-which-follow-many-of-the-lines-in-the-tag-file"> +<h3><a class="toc-backref" href="#id6">What are these strange bits of text beginning with <code class="docutils literal notranslate"><span class="pre">;"</span></code> which follow many of the lines in the tag file?</a><a class="headerlink" href="#what-are-these-strange-bits-of-text-beginning-with-which-follow-many-of-the-lines-in-the-tag-file" title="Permalink to this headline">¶</a></h3> +<p>These are <em>extension flags</em>. They are added in order to provide extra +information about the tag that may be utilized by the editor in order to +more intelligently handle tags. They are appended to the EX command part of +the tag line in a manner that provides backwards compatibility with existing +implementations of the Vi editor. The semicolon is an EX command separator +and the double quote begins an EX comment. Thus, the extension flags appear +as an EX comment and should be ignored by the editor when it processes the +EX command.</p> +<p>Some non-vi editors, however, implement only the bare minimum of EX commands +in order to process the search command or line number in the third field of +the tag file. If you encounter this problem, use the option <code class="docutils literal notranslate"><span class="pre">--format=1</span></code> to +generate a tag file without these extensions (remember that you can set the +CTAGS environment variable to any default arguments you wish to supply). Then +ask the supplier of your editor to implement handling of this feature of EX +commands.</p> +</section> +<section id="why-can-t-i-jump-to-class-member"> +<h3><a class="toc-backref" href="#id7">Why can’t I jump to <code class="docutils literal notranslate"><span class="pre">class::member</span></code>?</a><a class="headerlink" href="#why-can-t-i-jump-to-class-member" title="Permalink to this headline">¶</a></h3> +<p>Because, by default, ctags only generates tags for the separate identifiers +found in the source files. If you specify the <code class="docutils literal notranslate"><span class="pre">--extra=+q</span></code> option, then +ctags will also generate a second, class-qualified tag for each class member +(data and function/method) in the form <code class="docutils literal notranslate"><span class="pre">class::member</span></code> for C++, and in the form +<code class="docutils literal notranslate"><span class="pre">class.method</span></code> for Eiffel and Java.</p> +</section> +<section id="why-do-i-end-up-on-the-wrong-line-when-i-jump-to-a-tag"> +<h3><a class="toc-backref" href="#id8">Why do I end up on the wrong line when I jump to a tag?</a><a class="headerlink" href="#why-do-i-end-up-on-the-wrong-line-when-i-jump-to-a-tag" title="Permalink to this headline">¶</a></h3> +<p>By default, ctags encodes the line number in the file where macro (<code class="docutils literal notranslate"><span class="pre">#define</span></code>) +tags are found. This was done to remain compatible with the original UNIX +version of ctags. If you change the file containing the tag without +rebuilding the tag file, the location of tag in the tag file may no longer +match the current location.</p> +<p>In order to avoid this problem, you can specify the option <code class="docutils literal notranslate"><span class="pre">--excmd=p</span></code>, +which causes ctags to use a search pattern to locate macro tags. I have +never uncovered the reason why the original UNIX ctags used line numbers +exclusively for macro tags, but have so far resisted changing the default +behavior of Exuberant (and Universal) Ctags to behave differently.</p> +</section> +<section id="how-do-i-jump-to-the-tag-i-want-instead-of-the-wrong-one-by-the-same-name"> +<h3><a class="toc-backref" href="#id9">How do I jump to the tag I want instead of the wrong one by the same name?</a><a class="headerlink" href="#how-do-i-jump-to-the-tag-i-want-instead-of-the-wrong-one-by-the-same-name" title="Permalink to this headline">¶</a></h3> +<p>A tag file is simple a list of tag names and where to find them. If there +are duplicate entries, you often end up going to the wrong one because the +tag file is sorted and your editor locates the first one in the tag file.</p> +<p>Standard Vi provides no facilities to alter this behavior. However, Vim +has some nice features to minimize this problem, primarily by examining all +matches and choosing the best one under the circumstances. Vim also provides +commands which allow for selection of the desired matching tag.</p> +</section> +<section id="how-can-i-locate-all-references-to-a-specific-function-or-variable"> +<h3><a class="toc-backref" href="#id10">How can I locate all references to a specific function or variable?</a><a class="headerlink" href="#how-can-i-locate-all-references-to-a-specific-function-or-variable" title="Permalink to this headline">¶</a></h3> +<p>There are several packages already available which provide this capability. +Namely, these are: GLOBAL source code tag system, GNU id-utils, cscope, +and cflow. As of this writing, they can be found in the following locations:</p> +<ul class="simple"> +<li><p>GLOBAL: <a class="reference external" href="http://www.gnu.org/software/global">http://www.gnu.org/software/global</a></p></li> +<li><p>id-utils: <a class="reference external" href="http://www.gnu.org/software/idutils/idutils.html">http://www.gnu.org/software/idutils/idutils.html</a></p></li> +<li><p>cscope: <a class="reference external" href="http://cscope.sourceforge.net">http://cscope.sourceforge.net</a></p></li> +<li><p>cflow: <a class="reference external" href="ftp://www.ibiblio.org/pub/Linux/devel/lang/c">ftp://www.ibiblio.org/pub/Linux/devel/lang/c</a></p></li> +</ul> +</section> +<section id="why-does-appending-tags-to-a-tag-file-tag-so-long"> +<h3><a class="toc-backref" href="#id11">Why does appending tags to a tag file tag so long?</a><a class="headerlink" href="#why-does-appending-tags-to-a-tag-file-tag-so-long" title="Permalink to this headline">¶</a></h3> +<p>Sometimes, in an attempt to build a global tag file for all source files in +a large source tree of many directories, someone will make an attempt to run +ctags in append (<code class="docutils literal notranslate"><span class="pre">-a</span></code>) mode on every directory in the hierarchy. Each time +ctags is invoked, its default behavior is to sort the tag file once the tags +for that execution have been added. As the cumulative tag file grows, the sort +time increases arithmetically.</p> +<p>The best way to avoid this problem (and the most efficient) is to make +use of the <code class="docutils literal notranslate"><span class="pre">--recurse</span></code> (or <code class="docutils literal notranslate"><span class="pre">-R</span></code>) option of ctags by executing the following +command in the root of the directory hierarchy (thus running ctags only once):</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>ctags -R +</pre></div> +</div> +</div></blockquote> +<p>If you really insist on running ctags separately on each directory, you can +avoid the sort pass each time by specifying the option <code class="docutils literal notranslate"><span class="pre">--sort=no</span></code>. Once the +tag file is completely built, use the sort command to manually sort the +final tag file, or let the final invocation of ctags sort the file.</p> +</section> +<section id="how-should-i-set-up-tag-files-for-a-multi-level-directory-hierarchy"> +<h3><a class="toc-backref" href="#id12">How should I set up tag files for a multi-level directory hierarchy?</a><a class="headerlink" href="#how-should-i-set-up-tag-files-for-a-multi-level-directory-hierarchy" title="Permalink to this headline">¶</a></h3> +<p>There are a few ways of approaching this:</p> +<ol class="arabic simple"> +<li><p>A local tag file in each directory containing only the tags for source +files in that directory.</p></li> +<li><p>One single big, global tag file present in the root directory of your +hierarchy, containing all tags present in all source files in the +hierarchy.</p></li> +<li><p>A local tag file in each directory containing only the tags for source +files in that directory, in addition to one single global tag file +present in the root directory of your hierarchy, containing all +non-static tags present in all source files in the hierarchy.</p></li> +<li><p>A local tag file in each directory of the hierarchy, each one +containing all tags present in source files in that directory and all +non-static tags in every directory below it (note that this implies +also having one big tag file in the root directory of the hierarchy).</p></li> +</ol> +<p>Each of these approaches has its own set of advantages and disadvantages, +depending upon your particular conditions. Which approach is deemed best +depends upon the following factors:</p> +<ol class="upperalpha"> +<li><p>The ability of your editor to use multiple tag files.</p> +<p>If your editor cannot make use of multiple tag files (original vi +implementations could not), then one large tag file is the only way to +go if you ever desire to jump to tags located in other directories. If +you never need to jump to tags in another directory (i.e. the source +in each directory is entirely self-contained), then a local tag file +in each directory will fit your needs.</p> +</li> +<li><p>The time is takes for your editor to look up a tag in the tag file.</p> +<p>The significance of this factor depends upon the size of your source +tree and on whether the source files are located on a local or remote +file system. For source and tag files located on a local file system, +looking up a tag is not as big a hit as one might first imagine, since +vi implementations typically perform a binary search on a sorted tag +file. This may or may not be true for the editor you use. For files +located on a remote file system, reading a large file is an expensive +operation.</p> +</li> +<li><p>Whether or not you expect the source code to change and the time it +takes to rebuild a tag file to account for changes to the source code.</p> +<p>While Universal Ctags is particularly fast in scanning source code +(around 1-2 MB/sec), a large project may still result in objectionable +delays if one wishes to keep their tag file(s) up to date on a +frequent basis, or if the files are located on a remote file system.</p> +</li> +<li><p>The presence of duplicate tags in the source code and the ability to +handle them.</p> +<p>The impact of this factor is influenced by the following three issues:</p> +<ol class="arabic"> +<li><p>How common are duplicate tags in your project?</p></li> +<li><p>Does your editor provide any facilities for dealing with duplicate +tags?</p> +<p>While standard vi does not, many modern vi implementations, such +as Vim have good facilities for selecting the desired match from +the list of duplicates. If your editor does not support duplicate +tags, then it will typically send you to only one of them, whether +or not that is the one you wanted (and not even notifying you that +there are other potential matches).</p> +</li> +<li><p>What is the significance of duplicate tags?</p> +<p>For example, if you have two tags of the same name from entirely +isolated software components, jumping first to the match found +in component B while working in component A may be entirely +misleading, distracting or inconvenient (to keep having to choose +which one if your editor provides you with a list of matches). +However, if you have two tags of the same name for parallel builds +(say two initialization routines for different hosts), you may +always want to specify which one you want.</p> +</li> +</ol> +</li> +</ol> +<p>Of the approaches listed above, I tend to favor Approach 3. My editor of +choice is Vim, which provides a rich set of features for handling multiple +tag files, which partly influences my choice. If you are working with +source files on a remote file system, then I would recommend either +Approach 3 or Approach 4, depending upon the hit when reading the global +tag file.</p> +<p>The advantages of Approach 3 are many (assuming that your editor has +the ability to support both multiple tag files and duplicate tags). All +lookups of tag located in the current directory are fast and the local +tag file can be quickly and easily regenerated in one second or less +(I have even mapped a keystroke to do this easily). A lookup of a +(necessarily non-static) tag found in another directory fails a lookup in +the local tag file, but is found in the global tag file, which satisfies +all cross-directory lookups. The global tag file can be automatically +regenerated periodically with a cron job (and perhaps the local tag files +also).</p> +<p>Now I give an example of how you would implement Approach 3. Means of +implementing the other approaches can be performed in a similar manner.</p> +<p>Here is a visual representation of an example directory hierarchy:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>project +`-----misccomp +| `... +`-----sysint + `-----client + | `-----hdrs + | `-----lib + | `-----src + | `-----test + `-----common + | `-----hdrs + | `-----lib + | `-----src + | `-----test + `-----server + `-----hdrs + `-----lib + `-----src + `-----test +</pre></div> +</div> +<p>Here is a recommended solution (conceptually) to build the tag files:</p> +<ol class="arabic"> +<li><p>Within each of the leaf nodes (i.e. <code class="docutils literal notranslate"><span class="pre">hdrs</span></code>, <code class="docutils literal notranslate"><span class="pre">lib</span></code>, <code class="docutils literal notranslate"><span class="pre">src</span></code>, <code class="docutils literal notranslate"><span class="pre">test</span></code>) build a tag +file using “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">*.[ch]</span></code>”. This can be easily be done for the whole +hierarchy by making a shell script, call it <code class="docutils literal notranslate"><span class="pre">dirtags</span></code>, containing the +following lines:</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/bin/sh</span> +<span class="nb">cd</span> <span class="nv">$1</span> +ctags * +</pre></div> +</div> +</div></blockquote> +<p>Now execute the following command:</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>find * -type d -exec dirtags <span class="o">{}</span> <span class="se">\;</span> +</pre></div> +</div> +</div></blockquote> +<p>These tag files are trivial (and extremely quick) to rebuild while +making changes within a directory. The following Vim key mapping is +quite useful to rebuild the tag file in the directory of the current +source file:</p> +<blockquote> +<div><div class="highlight-text notranslate"><div class="highlight"><pre><span></span>:nmap ,t :!(cd %:p:h;ctags *.[ch])&<CR><CR> +</pre></div> +</div> +</div></blockquote> +</li> +<li><p>Build the global tag file:</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span> ~/project +ctags --file-scope<span class="o">=</span>no -R +</pre></div> +</div> +</div></blockquote> +<p>thus constructing a tag file containing only non-static tags for all +source files in all descendent directories.</p> +</li> +<li><p>Configure your editor to read the local tag file first, then consult +the global tag file when not found in the local tag file. In Vim, +this is done as follows:</p> +<blockquote> +<div><div class="highlight-text notranslate"><div class="highlight"><pre><span></span>:set tags=./tags,tags,~/project/tags +</pre></div> +</div> +</div></blockquote> +</li> +</ol> +<p>If you wish to implement Approach 4, you would need to replace the +<code class="docutils literal notranslate"><span class="pre">dirtags</span></code> script of step 1 with the following:</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/bin/sh</span> +<span class="nb">cd</span> <span class="nv">$1</span> +ctags * +<span class="c1"># Now append the non-static tags from descendent directories</span> +find * -type d -prune -print <span class="p">|</span> ctags -aR --file-scope<span class="o">=</span>no -L- +</pre></div> +</div> +</div></blockquote> +<p>And replace the configuration of step 3 with this:</p> +<blockquote> +<div><div class="highlight-text notranslate"><div class="highlight"><pre><span></span>:set tags=./tags;$HOME,tags +</pre></div> +</div> +</div></blockquote> +<p>As a caveat, it should be noted that step 2 builds a global tag file whose +file names will be relative to the directory in which the global tag file +is being built. This takes advantage of the Vim <code class="docutils literal notranslate"><span class="pre">tagrelative</span></code> option, +which causes the path to be interpreted a relative to the location of the +tag file instead of the current directory. For standard vi, which always +interprets the paths as relative to the current directory, we need to +build the global tag file with absolute path names. This can be +accomplished by replacing step 2 with the following:</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span> ~/project +ctags --file-scope<span class="o">=</span>no -R <span class="sb">`</span><span class="nb">pwd</span><span class="sb">`</span> +</pre></div> +</div> +</div></blockquote> +</section> +<section id="does-universal-ctags-support-unicode-file-names"> +<h3><a class="toc-backref" href="#id13">Does Universal Ctags support Unicode file names?</a><a class="headerlink" href="#does-universal-ctags-support-unicode-file-names" title="Permalink to this headline">¶</a></h3> +<p>Yes, Unicode file names are supported on unix-like platforms (Linux, macOS, +Cygwin, etc.).</p> +<p>However, on Windows, you need to use Windows 10 version 1903 or later to use +Unicode file names. (This is an experimental feature, though.) On older versions +on Windows, Universal Ctags only support file names represented in the current +code page. If you still want to use Unicode file names on them, use Cygwin or +MSYS2 version of Universal Ctags as a workaround.</p> +</section> +<section id="why-does-zsh-cause-zsh-no-matches-found-error"> +<h3><a class="toc-backref" href="#id14">Why does zsh cause “zsh: no matches found” error?</a><a class="headerlink" href="#why-does-zsh-cause-zsh-no-matches-found-error" title="Permalink to this headline">¶</a></h3> +<p>zsh causes error on the following cases;</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>ctags --extra<span class="o">=</span>+* ... +ctags --exclude<span class="o">=</span>foo/* ... +</pre></div> +</div> +</div></blockquote> +<p>This is the 2nd most significant incompatibility <em>feature</em> of zsh.</p> +<p>Cited from “Z-Shell Frequently-Asked Questions”, “<a class="reference external" href="http://zsh.sourceforge.net/FAQ/zshfaq02.html">2.1: Differences from sh and +ksh</a>”;</p> +<blockquote> +<div><p>… The next most classic difference is that unmatched glob patterns cause +the command to abort; set <code class="docutils literal notranslate"><span class="pre">NO_NOMATCH</span></code> for those.</p> +</div></blockquote> +<p>You may add “<code class="docutils literal notranslate"><span class="pre">setopt</span> <span class="pre">nonomatch</span></code>” on your <code class="docutils literal notranslate"><span class="pre">~/.zshrc</span></code>. Or you can escape glob +patterns with backslash;</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>ctags --extra<span class="o">=</span>+<span class="se">\*</span> ... +ctags --exclude<span class="o">=</span>foo/<span class="se">\*</span> ... +</pre></div> +</div> +</div></blockquote> +<p>Or quote them;</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>ctags <span class="s1">'--extra=+*'</span> ... +ctags <span class="s1">'--exclude=foo/*'</span> ... +</pre></div> +</div> +</div></blockquote> +</section> +</section> +<section id="see-also"> +<h2><a class="toc-backref" href="#id15">SEE ALSO</a><a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p>The official Universal Ctags web site at:</p> +<p><a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<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="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a></p> +</section> +<section id="author"> +<h2><a class="toc-backref" href="#id16">AUTHOR</a><a class="headerlink" href="#author" title="Permalink to this headline">¶</a></h2> +<p>This FAQ is based on <a class="reference external" href="http://ctags.sourceforge.net/faq.html">Exuberant Ctags FAQ</a> by +Darren Hiebert and <a class="reference external" href="mailto:vberthoux%40users.sourceforge.net">vberthoux<span>@</span>users<span>.</span>sourceforge<span>.</span>net</a></p> +<p>Universal Ctags project: <a class="reference external" href="https://ctags.io/">https://ctags.io/</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-faq</a><ul> +<li><a class="reference internal" href="#description">DESCRIPTION</a><ul> +<li><a class="reference internal" href="#what-is-the-difference-between-universal-ctags-and-exuberant-ctags">What is the difference between Universal Ctags and Exuberant Ctags?</a></li> +<li><a class="reference internal" href="#how-can-i-avoid-having-to-specify-my-favorite-option-every-time">How can I avoid having to specify my favorite option every time?</a></li> +<li><a class="reference internal" href="#what-are-these-strange-bits-of-text-beginning-with-which-follow-many-of-the-lines-in-the-tag-file">What are these strange bits of text beginning with <code class="docutils literal notranslate"><span class="pre">;"</span></code> which follow many of the lines in the tag file?</a></li> +<li><a class="reference internal" href="#why-can-t-i-jump-to-class-member">Why can’t I jump to <code class="docutils literal notranslate"><span class="pre">class::member</span></code>?</a></li> +<li><a class="reference internal" href="#why-do-i-end-up-on-the-wrong-line-when-i-jump-to-a-tag">Why do I end up on the wrong line when I jump to a tag?</a></li> +<li><a class="reference internal" href="#how-do-i-jump-to-the-tag-i-want-instead-of-the-wrong-one-by-the-same-name">How do I jump to the tag I want instead of the wrong one by the same name?</a></li> +<li><a class="reference internal" href="#how-can-i-locate-all-references-to-a-specific-function-or-variable">How can I locate all references to a specific function or variable?</a></li> +<li><a class="reference internal" href="#why-does-appending-tags-to-a-tag-file-tag-so-long">Why does appending tags to a tag file tag so long?</a></li> +<li><a class="reference internal" href="#how-should-i-set-up-tag-files-for-a-multi-level-directory-hierarchy">How should I set up tag files for a multi-level directory hierarchy?</a></li> +<li><a class="reference internal" href="#does-universal-ctags-support-unicode-file-names">Does Universal Ctags support Unicode file names?</a></li> +<li><a class="reference internal" href="#why-does-zsh-cause-zsh-no-matches-found-error">Why does zsh cause “zsh: no matches found” error?</a></li> +</ul> +</li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +<li><a class="reference internal" href="#author">AUTHOR</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-client-tools.7.html" + title="previous chapter">ctags-client-tools</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-lang-iPythonCell.7.html" + title="next chapter">ctags-lang-iPythonCell</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-lang-iPythonCell.7.html" title="ctags-lang-iPythonCell" + >next</a> |</li> + <li class="right" > + <a href="ctags-client-tools.7.html" title="ctags-client-tools" + >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-faq</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 diff --git a/ctags/docs/man/ctags-incompatibilities.7.html b/ctags/docs/man/ctags-incompatibilities.7.html new file mode 100644 index 0000000..4e15f59 --- /dev/null +++ b/ctags/docs/man/ctags-incompatibilities.7.html @@ -0,0 +1,337 @@ + +<!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-incompatibilities — 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="readtags" href="readtags.1.html" /> + <link rel="prev" title="ctags-lang-sql" href="ctags-lang-sql.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="readtags.1.html" title="readtags" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-lang-sql.7.html" title="ctags-lang-sql" + 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-incompatibilities</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-incompatibilities"> +<span id="ctags-incompatibilities-7"></span><h1>ctags-incompatibilities<a class="headerlink" href="#ctags-incompatibilities" title="Permalink to this headline">¶</a></h1> +<p>Incompatibilities between Universal Ctags and Exuberant Ctags</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>This page describes major incompatible changes introduced to +Universal Ctags forked from Exuberant Ctags.</p> +<section id="option-files-loading-at-starting-up-time-preload-files"> +<h3>Option files loading at starting up time (preload files)<a class="headerlink" href="#option-files-loading-at-starting-up-time-preload-files" title="Permalink to this headline">¶</a></h3> +<p>Universal Ctags doesn’t load <code class="docutils literal notranslate"><span class="pre">~/.ctags</span></code> at starting up time. +File paths for preload files are changed. +See “FILES” section of <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="environment-variables-for-arranging-command-lines"> +<h3>Environment variables for arranging command lines<a class="headerlink" href="#environment-variables-for-arranging-command-lines" title="Permalink to this headline">¶</a></h3> +<p>Universal Ctags doesn’t read <code class="docutils literal notranslate"><span class="pre">CTAGS</span></code> and/or <code class="docutils literal notranslate"><span class="pre">ETAGS</span></code> environment +variables.</p> +</section> +<section id="incompatibilities-in-command-line-interface"> +<h3>Incompatibilities in command line interface<a class="headerlink" href="#incompatibilities-in-command-line-interface" title="Permalink to this headline">¶</a></h3> +<section id="ordering-in-a-command-line"> +<h4>Ordering in a command line<a class="headerlink" href="#ordering-in-a-command-line" title="Permalink to this headline">¶</a></h4> +<p>The command line format of Universal Ctags is “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">[options]</span> +<span class="pre">[source_file(s)]</span></code>” following the standard POSIX convention.</p> +<p>Exuberant Ctags accepts a option following a source file.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -o - foo.c --list-kinds<span class="o">=</span>Sh +<span class="go">f functions</span> +</pre></div> +</div> +<p>Universal Ctags warns and ignores the option <code class="docutils literal notranslate"><span class="pre">--list-kinds=Sh</span></code> as follows.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -o - foo.c --list-kinds<span class="o">=</span>Sh +<span class="go">ctags: Warning: cannot open input file "--list-kinds=Sh" : No such file or directory</span> +<span class="go">a foo.c /^void a () {}$/;" f typeref:typename:void</span> +<span class="go">b foo.c /^void b () {}$/;" f typeref:typename:void</span> +</pre></div> +</div> +</section> +<section id="the-order-of-application-of-patterns-and-extensions-in-langmap"> +<h4>The order of application of patterns and extensions in <code class="docutils literal notranslate"><span class="pre">--langmap</span></code><a class="headerlink" href="#the-order-of-application-of-patterns-and-extensions-in-langmap" title="Permalink to this headline">¶</a></h4> +<p>When applying mappings for a name of given source file, +Exuberant Ctags tests file name patterns <em>AFTER</em> file extensions +(<em>e-map-order</em>). Universal Ctags does this differently; it tests file +name patterns <em>BEFORE</em> file extensions (<em>u-map-order</em>).</p> +<p>This incompatible change is introduced to deal with the following +situation:</p> +<blockquote> +<div><ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">build.xml</span></code> as a source file,</p></li> +<li><p>The Ant parser declares it handles a file name pattern <code class="docutils literal notranslate"><span class="pre">build.xml</span></code>, and</p></li> +<li><p>The XML parser declares it handles a file extension <code class="docutils literal notranslate"><span class="pre">.xml</span></code>.</p></li> +</ul> +</div></blockquote> +<p>Which parser should be used for parsing <code class="docutils literal notranslate"><span class="pre">build.xml</span></code>? The assumption +of Universal Ctags is the user may want to use the Ant parser; the +file name pattern it declares is more specific than the file extension +that the XML parser declares. However, e-map-order chooses the XML +parser.</p> +<p>So Universal Ctags uses the u-map-order even though it introduces an +incompatibility.</p> +<p><code class="docutils literal notranslate"><span class="pre">--list-map-extensions=<language></span></code> and <code class="docutils literal notranslate"><span class="pre">--list-map-patterns=<language></span></code> +options are helpful to verify and the file extensions and the file +name patterns of given <em><language></em>.</p> +</section> +<section id="remove-file-tags-and-file-scope-options"> +<h4>Remove <code class="docutils literal notranslate"><span class="pre">--file-tags</span></code> and <code class="docutils literal notranslate"><span class="pre">--file-scope</span></code> options<a class="headerlink" href="#remove-file-tags-and-file-scope-options" title="Permalink to this headline">¶</a></h4> +<p>Even in Exuberant Ctags, <code class="docutils literal notranslate"><span class="pre">--file-tags</span></code> is not documented in its man page. +Instead of specifying <code class="docutils literal notranslate"><span class="pre">--file-tags</span></code> or <code class="docutils literal notranslate"><span class="pre">--file-tags=yes</span></code>, use +<code class="docutils literal notranslate"><span class="pre">--extras=+f</span></code> or <code class="docutils literal notranslate"><span class="pre">--extras=+{inputFile}</span></code>.</p> +<p>Instead of specifying <code class="docutils literal notranslate"><span class="pre">--file-tags=no</span></code>, use +<code class="docutils literal notranslate"><span class="pre">--extras=-f</span></code> or <code class="docutils literal notranslate"><span class="pre">--extras=-{inputFile}</span></code>.</p> +<p>Universal Ctags introduces <code class="docutils literal notranslate"><span class="pre">F/fileScope</span></code> extra as the replacement for +<code class="docutils literal notranslate"><span class="pre">--file-scope</span></code> option.</p> +<p>Instead of specifying <code class="docutils literal notranslate"><span class="pre">--file-tags</span></code> or <code class="docutils literal notranslate"><span class="pre">--file-tags=yes</span></code>, use +<code class="docutils literal notranslate"><span class="pre">--extras=+F</span></code> or <code class="docutils literal notranslate"><span class="pre">--extras=+{fileScope}</span></code>.</p> +<p>Instead of specifying <code class="docutils literal notranslate"><span class="pre">--file-tags=no</span></code>, use +<code class="docutils literal notranslate"><span class="pre">--extras=-F</span></code> or <code class="docutils literal notranslate"><span class="pre">--extras=-{fileScope}</span></code>.</p> +</section> +</section> +<section id="incompatibilities-in-language-and-kind-definitions"> +<h3>Incompatibilities in language and kind definitions<a class="headerlink" href="#incompatibilities-in-language-and-kind-definitions" title="Permalink to this headline">¶</a></h3> +<section id="language-name-defined-with-langdef-name-option"> +<h4>Language name defined with <code class="docutils literal notranslate"><span class="pre">--langdef=name</span></code> option<a class="headerlink" href="#language-name-defined-with-langdef-name-option" title="Permalink to this headline">¶</a></h4> +<p>The characters you can use are more restricted than Exuberant Ctags. +For more details, see the description of <code class="docutils literal notranslate"><span class="pre">--langdef=name</span></code> in <a class="reference internal" href="ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a>.</p> +</section> +<section id="obsoleting-lang-kinds-option"> +<h4>Obsoleting <code class="docutils literal notranslate"><span class="pre">--<LANG>-kinds</span></code> option<a class="headerlink" href="#obsoleting-lang-kinds-option" title="Permalink to this headline">¶</a></h4> +<p>Some options have <em><LANG></em> as parameterized parts in their name like +<code class="docutils literal notranslate"><span class="pre">--foo-<LANG>=...</span></code> or <code class="docutils literal notranslate"><span class="pre">--<LANG>-foo=...</span></code>. The most of all such +options in Exuberant Ctags have the former form, <code class="docutils literal notranslate"><span class="pre">--foo-<LANG>=...</span></code>. +The exception is <code class="docutils literal notranslate"><span class="pre">--<LANG>-kinds</span></code>.</p> +<p>Universal Ctags uses the former form for all <em><LANG></em> parameterized +option. Use <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code> instead of <code class="docutils literal notranslate"><span class="pre">--<LANG>-kinds</span></code> in +Universal Ctags. <code class="docutils literal notranslate"><span class="pre">--<LANG>-kinds</span></code> still works but it will be +removed in the future.</p> +<p>The former form may be friendly to shell completion engines.</p> +</section> +<section id="disallowing-to-define-a-kind-with-file-as-name"> +<h4>Disallowing to define a kind with <code class="docutils literal notranslate"><span class="pre">file</span></code> as name<a class="headerlink" href="#disallowing-to-define-a-kind-with-file-as-name" title="Permalink to this headline">¶</a></h4> +<p>The kind name <code class="docutils literal notranslate"><span class="pre">file</span></code> is reserved. Using it as part of kind spec in +<code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> option is now disallowed.</p> +</section> +<section id="disallowing-to-define-a-kind-with-f-as-letter"> +<h4>Disallowing to define a kind with ‘<code class="docutils literal notranslate"><span class="pre">F</span></code>’ as letter<a class="headerlink" href="#disallowing-to-define-a-kind-with-f-as-letter" title="Permalink to this headline">¶</a></h4> +<p>The kind letter ‘<code class="docutils literal notranslate"><span class="pre">F</span></code>’ is reserved. Using it as part of a kind spec in +<code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> option is now disallowed.</p> +</section> +<section id="disallowing-to-use-other-than-alphabetical-character-as-kind-letter"> +<h4>Disallowing to use other than alphabetical character as kind letter<a class="headerlink" href="#disallowing-to-use-other-than-alphabetical-character-as-kind-letter" title="Permalink to this headline">¶</a></h4> +<p>Exuberant Ctags accepts a character other than alphabetical character +as kind letter in <code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=...</span></code> option. Universal Ctags +accepts only an alphabetical character.</p> +</section> +<section id="acceptable-characters-as-parts-of-a-kind-name"> +<h4>Acceptable characters as parts of a kind name<a class="headerlink" href="#acceptable-characters-as-parts-of-a-kind-name" title="Permalink to this headline">¶</a></h4> +<p>Exuberant Ctags accepts any character as a part of a kind name +defined with <code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=/regex/replacement/kind-spec/</span></code>.</p> +<p>Universal Ctags accepts only an alphabetical character as +the initial letter of a kind name. +Universal Ctags accepts only an alphabetical character or +numerical character as the rest letters.</p> +<p>An example:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>--regex-Foo=/abstract +class +([a-z]+)/\1/a,abstract class/i +</pre></div> +</div> +<p>Universal Ctags rejects this because the kind name, <code class="docutils literal notranslate"><span class="pre">abstract</span> <span class="pre">class</span></code>, +includes a whitespace character.</p> +<p>This requirement is for making the output of Universal Ctags follow +the tags file format.</p> +</section> +<section id="a-combination-of-a-kind-letter-and-a-kind-name"> +<h4>A combination of a kind letter and a kind name<a class="headerlink" href="#a-combination-of-a-kind-letter-and-a-kind-name" title="Permalink to this headline">¶</a></h4> +<p>In Universal Ctags, the combination of +a kind letter and a kind name must be unique in a language.</p> +<p>You cannot define more than one kind reusing a kind letter with +different kind names. You cannot define more than one kind reusing a +kind name with different kind letters.</p> +<p>An example:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>--regex-Foo=/abstract +class +([a-z]+)/\1/a,abstractClass/i +--regex-Foo=/attribute +([a-z]+)/\1/a,attribute/i +</pre></div> +</div> +<p>Universal Ctags rejects this because the kind letter, ‘<code class="docutils literal notranslate"><span class="pre">a</span></code>’, used twice +for defining a kind <code class="docutils literal notranslate"><span class="pre">abstractClass</span></code> and <code class="docutils literal notranslate"><span class="pre">attribute</span></code>.</p> +</section> +</section> +<section id="incompatibilities-in-tags-file-format"> +<h3>Incompatibilities in tags file format<a class="headerlink" href="#incompatibilities-in-tags-file-format" title="Permalink to this headline">¶</a></h3> +<section id="using-numerical-character-in-the-name-part-of-tag-tagfield"> +<h4>Using numerical character in the name part of tag tagfield<a class="headerlink" href="#using-numerical-character-in-the-name-part-of-tag-tagfield" title="Permalink to this headline">¶</a></h4> +<p>The version 2 tags file format, the default output format of +Exuberant Ctags, accepts only alphabetical characters in the name part +of tag tagfield.</p> +<p>Universal Ctags introduces an exception to this specification; it may +use numerical characters in addition to alphabetical characters as the +letters other than initial letter of the name part.</p> +<p>The kinds <code class="docutils literal notranslate"><span class="pre">heading1</span></code>, <code class="docutils literal notranslate"><span class="pre">heading2</span></code>, and <code class="docutils literal notranslate"><span class="pre">heading3</span></code> in the HTML parser +are the examples.</p> +</section> +<section id="truncating-the-pattern-for-long-input-lines"> +<h4>Truncating the pattern for long input lines<a class="headerlink" href="#truncating-the-pattern-for-long-input-lines" title="Permalink to this headline">¶</a></h4> +<p>To prevent generating overly large tags files, a pattern field is +truncated, by default, when its size exceeds 96 bytes. A different +limit can be specified with <code class="docutils literal notranslate"><span class="pre">--pattern-length-limit=N</span></code>. Specifying +0 as <em>N</em> results no truncation as Exuberant Ctags does not.</p> +</section> +<section id="kind-letters-and-names"> +<h4>Kind letters and names<a class="headerlink" href="#kind-letters-and-names" title="Permalink to this headline">¶</a></h4> +<p>A kind letter ‘<code class="docutils literal notranslate"><span class="pre">F</span></code>’ and a kind name <code class="docutils literal notranslate"><span class="pre">file</span></code> are reserved in the +main part. A parser cannot have a kind conflicting with +these reserved ones. Some incompatible changes are introduced +to follow the above rule.</p> +<ul class="simple"> +<li><p>Cobol’s <code class="docutils literal notranslate"><span class="pre">file</span></code> kind is renamed to <code class="docutils literal notranslate"><span class="pre">fileDesc</span></code> because the +kind name <code class="docutils literal notranslate"><span class="pre">file</span></code> is reserved.</p></li> +<li><p>Ruby’s ‘<code class="docutils literal notranslate"><span class="pre">F</span></code>’ (singletonMethod) is changed to ‘<code class="docutils literal notranslate"><span class="pre">S</span></code>’.</p></li> +<li><p>SQL’s ‘<code class="docutils literal notranslate"><span class="pre">F</span></code>’ (field) is changed to ‘<code class="docutils literal notranslate"><span class="pre">E</span></code>’.</p></li> +</ul> +</section> +</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-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a>, and <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</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-incompatibilities</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a><ul> +<li><a class="reference internal" href="#option-files-loading-at-starting-up-time-preload-files">Option files loading at starting up time (preload files)</a></li> +<li><a class="reference internal" href="#environment-variables-for-arranging-command-lines">Environment variables for arranging command lines</a></li> +<li><a class="reference internal" href="#incompatibilities-in-command-line-interface">Incompatibilities in command line interface</a><ul> +<li><a class="reference internal" href="#ordering-in-a-command-line">Ordering in a command line</a></li> +<li><a class="reference internal" href="#the-order-of-application-of-patterns-and-extensions-in-langmap">The order of application of patterns and extensions in <code class="docutils literal notranslate"><span class="pre">--langmap</span></code></a></li> +<li><a class="reference internal" href="#remove-file-tags-and-file-scope-options">Remove <code class="docutils literal notranslate"><span class="pre">--file-tags</span></code> and <code class="docutils literal notranslate"><span class="pre">--file-scope</span></code> options</a></li> +</ul> +</li> +<li><a class="reference internal" href="#incompatibilities-in-language-and-kind-definitions">Incompatibilities in language and kind definitions</a><ul> +<li><a class="reference internal" href="#language-name-defined-with-langdef-name-option">Language name defined with <code class="docutils literal notranslate"><span class="pre">--langdef=name</span></code> option</a></li> +<li><a class="reference internal" href="#obsoleting-lang-kinds-option">Obsoleting <code class="docutils literal notranslate"><span class="pre">--<LANG>-kinds</span></code> option</a></li> +<li><a class="reference internal" href="#disallowing-to-define-a-kind-with-file-as-name">Disallowing to define a kind with <code class="docutils literal notranslate"><span class="pre">file</span></code> as name</a></li> +<li><a class="reference internal" href="#disallowing-to-define-a-kind-with-f-as-letter">Disallowing to define a kind with ‘<code class="docutils literal notranslate"><span class="pre">F</span></code>’ as letter</a></li> +<li><a class="reference internal" href="#disallowing-to-use-other-than-alphabetical-character-as-kind-letter">Disallowing to use other than alphabetical character as kind letter</a></li> +<li><a class="reference internal" href="#acceptable-characters-as-parts-of-a-kind-name">Acceptable characters as parts of a kind name</a></li> +<li><a class="reference internal" href="#a-combination-of-a-kind-letter-and-a-kind-name">A combination of a kind letter and a kind name</a></li> +</ul> +</li> +<li><a class="reference internal" href="#incompatibilities-in-tags-file-format">Incompatibilities in tags file format</a><ul> +<li><a class="reference internal" href="#using-numerical-character-in-the-name-part-of-tag-tagfield">Using numerical character in the name part of tag tagfield</a></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="#kind-letters-and-names">Kind letters and names</a></li> +</ul> +</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-lang-sql.7.html" + title="previous chapter">ctags-lang-sql</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="readtags.1.html" + title="next chapter">readtags</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="readtags.1.html" title="readtags" + >next</a> |</li> + <li class="right" > + <a href="ctags-lang-sql.7.html" title="ctags-lang-sql" + >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-incompatibilities</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 diff --git a/ctags/docs/man/ctags-lang-iPythonCell.7.html b/ctags/docs/man/ctags-lang-iPythonCell.7.html new file mode 100644 index 0000000..84be1b1 --- /dev/null +++ b/ctags/docs/man/ctags-lang-iPythonCell.7.html @@ -0,0 +1,186 @@ + +<!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-lang-iPythonCell — 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-lang-julia" href="ctags-lang-julia.7.html" /> + <link rel="prev" title="ctags-faq" href="ctags-faq.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-lang-julia.7.html" title="ctags-lang-julia" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-faq.7.html" title="ctags-faq" + 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-lang-iPythonCell</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-lang-ipythoncell"> +<span id="ctags-lang-ipythoncell-7"></span><h1>ctags-lang-iPythonCell<a class="headerlink" href="#ctags-lang-ipythoncell" title="Permalink to this headline">¶</a></h1> +<p>The man page of the iPythonCell parser for Universal Ctags</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> … --extras={subparser} --languages=+iPythonCell,Python \</div> +<div class="line-block"> +<div class="line">[--extras-IPythonCell=+{doubleSharps}] \</div> +<div class="line">[--regex-IPythonCell=/<PATTERN>/\n/c/] …</div> +</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>iPythonCell is a subparser stacked on top of the Python parser. +It works when:</p> +<ul class="simple"> +<li><p>The Python parser is enabled,</p></li> +<li><p>the <code class="docutils literal notranslate"><span class="pre">subparser</span></code> extra is enabeld, and</p></li> +<li><p>the iPythonCell parser itself is enabled.</p></li> +</ul> +<p>iPythonCell extracts cells explained as in vim-ipython-cell +(<a class="reference external" href="https://github.com/hanschen/vim-ipython-cell/blob/master/README.md">https://github.com/hanschen/vim-ipython-cell/blob/master/README.md</a>).</p> +</section> +<section id="kind-s"> +<h2>KIND(S)<a class="headerlink" href="#kind-s" title="Permalink to this headline">¶</a></h2> +<p>The iPythonCell parser defines only a <code class="docutils literal notranslate"><span class="pre">cell</span></code> kind.</p> +</section> +<section id="extra-s"> +<h2>EXTRA(S)<a class="headerlink" href="#extra-s" title="Permalink to this headline">¶</a></h2> +<p>Tagging cells staring with <code class="docutils literal notranslate"><span class="pre">##...</span></code> is disabled by default because +the pattern is too generic; with that pattern unwanted tags can be extracted.</p> +<p>Enable <code class="docutils literal notranslate"><span class="pre">doubleSharps</span></code> language specific extra for tagging cells +staring with <code class="docutils literal notranslate"><span class="pre">##...</span></code>.</p> +</section> +<section id="customizing"> +<h2>CUSTOMIZING<a class="headerlink" href="#customizing" title="Permalink to this headline">¶</a></h2> +<p>If your favorite cell pattern is not supported in the parser, you can +define the pattern in your <code class="docutils literal notranslate"><span class="pre">.ctagd.d/your.ctags</span></code> or command lines. +Here is an example how to support “<code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">CTAGS:</span> <span class="pre">...</span></code>”:</p> +<p>“input.py”</p> +<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="n">x</span><span class="o">=</span><span class="mi">1</span> +<span class="c1"># CTAGS: DEFINE F</span> +<span class="k">def</span> <span class="nf">F</span><span class="p">():</span> + <span class="c1"># CTAGS: DO NOTING</span> + <span class="k">pass</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE --sort=no --extras=+{subparser} --regex-IPythonCell=/[ t]*# CTAGS:[ ]?(.*)$/1/c/ -o - input.py”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>x input.py /^x=1$/;" v +DEFINE F input.py /^# CTAGS: DEFINE F$/;" c +F input.py /^def F():$/;" f +DO NOTING input.py /^ # CTAGS: DO NOTING$/;" c +</pre></div> +</div> +<p>You can put “<code class="docutils literal notranslate"><span class="pre">--regex-IPythonCell=/[</span> <span class="pre">\t]*#</span> <span class="pre">CTAGS:[</span> <span class="pre">]?(.*)$/\1/c/</span></code>” in <code class="docutils literal notranslate"><span class="pre">your.ctags</span></code> +to avoid specifying the pattern repeatedly.</p> +</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-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</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></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-lang-iPythonCell</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="#kind-s">KIND(S)</a></li> +<li><a class="reference internal" href="#extra-s">EXTRA(S)</a></li> +<li><a class="reference internal" href="#customizing">CUSTOMIZING</a></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-faq.7.html" + title="previous chapter">ctags-faq</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-lang-julia.7.html" + title="next chapter">ctags-lang-julia</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-lang-julia.7.html" title="ctags-lang-julia" + >next</a> |</li> + <li class="right" > + <a href="ctags-faq.7.html" title="ctags-faq" + >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-lang-iPythonCell</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 diff --git a/ctags/docs/man/ctags-lang-inko.7.html b/ctags/docs/man/ctags-lang-inko.7.html new file mode 100644 index 0000000..78d9968 --- /dev/null +++ b/ctags/docs/man/ctags-lang-inko.7.html @@ -0,0 +1,141 @@ + +<!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-lang-inko — 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-lang-r" href="ctags-lang-r.7.html" /> + <link rel="prev" title="ctags-lang-verilog" href="ctags-lang-verilog.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-lang-r.7.html" title="ctags-lang-r" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-lang-verilog.7.html" title="ctags-lang-verilog" + 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-lang-inko</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-lang-inko"> +<span id="ctags-lang-inko-7"></span><h1>ctags-lang-inko<a class="headerlink" href="#ctags-lang-inko" title="Permalink to this headline">¶</a></h1> +<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> … --languages=+Inko …</div> +<div class="line"><strong>ctags</strong> … --language-force=Inko …</div> +<div class="line"><strong>ctags</strong> … --map-Inko=+.inko …</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>This man page describes the Inko parser for Universal Ctags.</p> +<p>The input file is expected to be valid Inko source code, otherwise the output of +ctags is undefined.</p> +<p>Tags are generated for objects, traits, methods, attributes, and constants. +String literals are ignored.</p> +</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-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</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-lang-inko</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="#see-also">SEE ALSO</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-lang-verilog.7.html" + title="previous chapter">ctags-lang-verilog</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-lang-r.7.html" + title="next chapter">ctags-lang-r</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-lang-r.7.html" title="ctags-lang-r" + >next</a> |</li> + <li class="right" > + <a href="ctags-lang-verilog.7.html" title="ctags-lang-verilog" + >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-lang-inko</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 diff --git a/ctags/docs/man/ctags-lang-julia.7.html b/ctags/docs/man/ctags-lang-julia.7.html new file mode 100644 index 0000000..a420c5e --- /dev/null +++ b/ctags/docs/man/ctags-lang-julia.7.html @@ -0,0 +1,332 @@ + +<!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-lang-julia — 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-lang-python" href="ctags-lang-python.7.html" /> + <link rel="prev" title="ctags-lang-iPythonCell" href="ctags-lang-iPythonCell.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-lang-python.7.html" title="ctags-lang-python" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-lang-iPythonCell.7.html" title="ctags-lang-iPythonCell" + 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-lang-julia</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-lang-julia"> +<span id="ctags-lang-julia-7"></span><h1>ctags-lang-julia<a class="headerlink" href="#ctags-lang-julia" title="Permalink to this headline">¶</a></h1> +<p>Random notes about tagging Julia source code with Universal-ctags</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> … --languages=+Julia …</div> +<div class="line"><strong>ctags</strong> … --language-force=Julia …</div> +<div class="line"><strong>ctags</strong> … --map-Julia=+.jl …</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>This man page gathers random notes about tagging Julia source code.</p> +</section> +<section id="tagging-import-and-using-expressions"> +<h2>TAGGING <code class="docutils literal notranslate"><span class="pre">import</span></code> AND <code class="docutils literal notranslate"><span class="pre">using</span></code> EXPRESSIONS<a class="headerlink" href="#tagging-import-and-using-expressions" title="Permalink to this headline">¶</a></h2> +<section id="summary"> +<h3>Summary<a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h3> +<p><cite>using X</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>X</p></td> +<td><p>module</p></td> +<td><p>used</p></td> +<td><p>N/A</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>using X: a, b</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>X</p></td> +<td><p>module</p></td> +<td><p>namespace</p></td> +<td><p>N/A</p></td> +</tr> +<tr class="row-odd"><td><p>a, b</p></td> +<td><p>unknown</p></td> +<td><p>used</p></td> +<td><p>scope:module:X</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>import X</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>X</p></td> +<td><p>module</p></td> +<td><p>imported</p></td> +<td><p>N/A</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>import X.a, Y.b</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>X, Y</p></td> +<td><p>module</p></td> +<td><p>namespace</p></td> +<td><p>N/A</p></td> +</tr> +<tr class="row-odd"><td><p>a</p></td> +<td><p>unknown</p></td> +<td><p>imported</p></td> +<td><p>scope:module:X</p></td> +</tr> +<tr class="row-even"><td><p>b</p></td> +<td><p>unknown</p></td> +<td><p>imported</p></td> +<td><p>scope:module:Y</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>import X: a, b</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>X</p></td> +<td><p>module</p></td> +<td><p>namespace</p></td> +<td><p>N/A</p></td> +</tr> +<tr class="row-odd"><td><p>a,b</p></td> +<td><p>unknown</p></td> +<td><p>imported</p></td> +<td><p>scope:module:X</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +</section> +<section id="examples"> +<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3> +<p>“input.jl”</p> +<div class="highlight-Julia notranslate"><div class="highlight"><pre><span></span><span class="k">using</span> <span class="n">X0</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --extras=+r --fields=+rzK input.jl”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>X0 input.jl /^using X0$/;" kind:module roles:used +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">--extras=+r</span></code> (or <code class="docutils literal notranslate"><span class="pre">--extras=+{reference}</span></code>) option is needed for this tag, +since it’s a reference tag. This is because module <code class="docutils literal notranslate"><span class="pre">X</span></code> is not defined here. +It is defined in another file. Enable <code class="docutils literal notranslate"><span class="pre">roles:</span></code> field with <code class="docutils literal notranslate"><span class="pre">--fields=+r</span></code> is +for recording that the module is “used”, i.e., loaded by <code class="docutils literal notranslate"><span class="pre">using</span></code>.</p> +<p>“input.jl”</p> +<div class="highlight-Julia notranslate"><div class="highlight"><pre><span></span><span class="k">import</span> <span class="n">X1</span><span class="o">.</span><span class="n">a</span><span class="p">,</span> <span class="n">X2</span><span class="o">.</span><span class="n">b</span><span class="p">,</span> <span class="n">X3</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --extras=+r --fields=+rzKZ input.jl”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>X1 input.jl /^import X1.a, X2.b, X3$/;" kind:module roles:namespace +X2 input.jl /^import X1.a, X2.b, X3$/;" kind:module roles:namespace +X3 input.jl /^import X1.a, X2.b, X3$/;" kind:module roles:imported +a input.jl /^import X1.a, X2.b, X3$/;" kind:unknown scope:module:X1 roles:imported +b input.jl /^import X1.a, X2.b, X3$/;" kind:unknown scope:module:X2 roles:imported +</pre></div> +</div> +<p>Why <code class="docutils literal notranslate"><span class="pre">X1</span></code> and <code class="docutils literal notranslate"><span class="pre">X2</span></code> have role “namespace”, while <code class="docutils literal notranslate"><span class="pre">X3</span></code> have role “imported”? +It’s because the symbol <code class="docutils literal notranslate"><span class="pre">a</span></code> in module <code class="docutils literal notranslate"><span class="pre">X1</span></code>, and <code class="docutils literal notranslate"><span class="pre">b</span></code> in module <code class="docutils literal notranslate"><span class="pre">X2</span></code> are +brought to the current scope, but <code class="docutils literal notranslate"><span class="pre">X1</span></code> and <code class="docutils literal notranslate"><span class="pre">X2</span></code> themselves are not. We use +“namespace” role for such modules.</p> +<p><code class="docutils literal notranslate"><span class="pre">X3</span></code> is different. The symbol <code class="docutils literal notranslate"><span class="pre">X3</span></code>, together with all exported symbols in +<code class="docutils literal notranslate"><span class="pre">X3</span></code>, is brought to current scope. For such modules, we use “imported” or +“used” role depending whether they are loaded by <code class="docutils literal notranslate"><span class="pre">import</span></code> or <code class="docutils literal notranslate"><span class="pre">using</span></code>.</p> +<p>Also, notice that <code class="docutils literal notranslate"><span class="pre">a</span></code> and <code class="docutils literal notranslate"><span class="pre">b</span></code> have the “unknown” kind. This is because we +cannot know whether it’s a function, constant, or macro, etc.</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-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</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-lang-julia</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="#tagging-import-and-using-expressions">TAGGING <code class="docutils literal notranslate"><span class="pre">import</span></code> AND <code class="docutils literal notranslate"><span class="pre">using</span></code> EXPRESSIONS</a><ul> +<li><a class="reference internal" href="#summary">Summary</a></li> +<li><a class="reference internal" href="#examples">Examples</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-lang-iPythonCell.7.html" + title="previous chapter">ctags-lang-iPythonCell</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-lang-python.7.html" + title="next chapter">ctags-lang-python</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-lang-python.7.html" title="ctags-lang-python" + >next</a> |</li> + <li class="right" > + <a href="ctags-lang-iPythonCell.7.html" title="ctags-lang-iPythonCell" + >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-lang-julia</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 diff --git a/ctags/docs/man/ctags-lang-python.7.html b/ctags/docs/man/ctags-lang-python.7.html new file mode 100644 index 0000000..fcd72c4 --- /dev/null +++ b/ctags/docs/man/ctags-lang-python.7.html @@ -0,0 +1,476 @@ + +<!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-lang-python — 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-lang-verilog" href="ctags-lang-verilog.7.html" /> + <link rel="prev" title="ctags-lang-julia" href="ctags-lang-julia.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-lang-verilog.7.html" title="ctags-lang-verilog" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-lang-julia.7.html" title="ctags-lang-julia" + 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-lang-python</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-lang-python"> +<span id="ctags-lang-python-7"></span><h1>ctags-lang-python<a class="headerlink" href="#ctags-lang-python" title="Permalink to this headline">¶</a></h1> +<p>Random notes about tagging python source code with Universal Ctags</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> … --languages=+Python …</div> +<div class="line"><strong>ctags</strong> … --language-force=Python …</div> +<div class="line"><strong>ctags</strong> … --map-Python=+.py …</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>This man page gathers random notes about tagging python source code.</p> +</section> +<section id="tagging-import-statements"> +<h2>TAGGING <code class="docutils literal notranslate"><span class="pre">import</span></code> STATEMENTS<a class="headerlink" href="#tagging-import-statements" title="Permalink to this headline">¶</a></h2> +<section id="summary"> +<h3>Summary<a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h3> +<p><cite>import X</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>X</p></td> +<td><p>module</p></td> +<td><p>imported</p></td> +<td><p>N/A</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>import X as Y</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>X</p></td> +<td><p>module</p></td> +<td><p>indirectlyImported</p></td> +<td><p>N/A</p></td> +</tr> +<tr class="row-odd"><td><p>Y</p></td> +<td><p>namespace</p></td> +<td><p>definition</p></td> +<td><p>nameref:module:X</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>from X import *</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><cite>X</cite></p></td> +<td><p>module</p></td> +<td><p>namespace</p></td> +<td><p>N/A</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>from X import Y</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><cite>X</cite></p></td> +<td><p>module</p></td> +<td><p>namespace</p></td> +<td><p>N/A</p></td> +</tr> +<tr class="row-odd"><td><p><cite>Y</cite></p></td> +<td><p>unknown</p></td> +<td><p>imported</p></td> +<td><p>scope:module:<cite>X</cite></p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>from X import Y as Z</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><cite>X</cite></p></td> +<td><p>module</p></td> +<td><p>namespace</p></td> +<td><p>N/A</p></td> +</tr> +<tr class="row-odd"><td><p><cite>Y</cite></p></td> +<td><p>unknown</p></td> +<td><p>indirectlyImported</p></td> +<td><p>scope:module:<cite>X</cite></p></td> +</tr> +<tr class="row-even"><td><p><cite>Z</cite></p></td> +<td><p>unknown</p></td> +<td><p>definition</p></td> +<td><p>nameref:unknown:<cite>X</cite></p></td> +</tr> +</tbody> +</table> +</div></blockquote> +</section> +<section id="examples"> +<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3> +<p>“input.py”</p> +<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">X0</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --extras=+r --fields=+rzK input.py”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>X0 input.py /^import X0$/;" kind:module roles:imported +</pre></div> +</div> +<p>A tag for an imported module has <code class="docutils literal notranslate"><span class="pre">module</span></code> kind with <code class="docutils literal notranslate"><span class="pre">imported</span></code> role. The +module is not defined here; it is defined in another file. So the tag for the +imported module is a reference tag; specify <code class="docutils literal notranslate"><span class="pre">--extras=+r</span></code> (or +<code class="docutils literal notranslate"><span class="pre">--extras=+{reference}</span></code>) option for tagging it. “roles:” field enabled with +<code class="docutils literal notranslate"><span class="pre">--fields=+r</span></code> is for recording the module is “imported” to the tag file.</p> +<p>“input.py”</p> +<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">X1</span> <span class="k">as</span> <span class="nn">Y1</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --extras=+r --fields=+rzK --fields-Python=+{nameref} input.py”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>X1 input.py /^import X1 as Y1$/;" kind:module roles:indirectlyImported +Y1 input.py /^import X1 as Y1$/;" kind:namespace roles:def nameref:module:X1 +</pre></div> +</div> +<p>“Y1” introduces a new name and is defined here. So “Y1” is tagged as a +definition tag. “X1” is imported in a way that its name cannot be used +in this source file. For letting client tools know that the name cannot be used, +<code class="docutils literal notranslate"><span class="pre">indirectlyImported</span></code> role is assigned for “X1”. “Y1” is the name for +accessing objects defined in the module imported via “X1”. For recording this +relationship, <code class="docutils literal notranslate"><span class="pre">nameref:</span></code> field is attached to the tag of “Y1”. Instead of +<code class="docutils literal notranslate"><span class="pre">module</span></code> kind, <code class="docutils literal notranslate"><span class="pre">namespace</span></code> kind is assigned to “Y1” because “Y1” itself +isn’t a module.</p> +<p>“input.py”</p> +<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">X2</span> <span class="kn">import</span> <span class="o">*</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --extras=+r --fields=+rzK input.py”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>X2 input.py /^from X2 import *$/;" kind:module roles:namespace +</pre></div> +</div> +<p>The module is not defined here; it is defined in another file. So the tag for +the imported module is a reference tag. Unlike “X0” in “import X0”, “X2” may not +be used because the names defined in “X2” can be used in this source file. To represent +the difference <code class="docutils literal notranslate"><span class="pre">namespace</span></code> role is attached to “X2” instead of <code class="docutils literal notranslate"><span class="pre">imported</span></code>.</p> +<p>“input.py”</p> +<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">X3</span> <span class="kn">import</span> <span class="n">Y3</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --extras=+r --fields=+rzKZ input.py”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>X3 input.py /^from X3 import Y3$/;" kind:module roles:namespace +Y3 input.py /^from X3 import Y3$/;" kind:unknown scope:module:X3 roles:imported +</pre></div> +</div> +<p>“Y3” is a name for a language object defined in “X3” module. “scope:module:X3” +attached to “Y3” represents this relation between “Y3” and “X3”. ctags +assigns <code class="docutils literal notranslate"><span class="pre">unknown</span></code> kind to “Y3” because ctags cannot know whether “Y3” is a +class, a variable, or a function from the input file.</p> +<p>“input.py”</p> +<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">X4</span> <span class="kn">import</span> <span class="n">Y4</span> <span class="k">as</span> <span class="n">Z4</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --extras=+r --fields=+rzKZ input.py”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>X4 input.py /^from X4 import Y4 as Z4$/;" kind:module roles:namespace +Y4 input.py /^from X4 import Y4 as Z4$/;" kind:unknown scope:module:X4 roles:indirectlyImported +Z4 input.py /^from X4 import Y4 as Z4$/;" kind:unknown roles:def nameref:unknown:Y4 +</pre></div> +</div> +<p>“Y4” is similar to “Y3” of “from X3 import Y3” but the name cannot be used here. +<code class="docutils literal notranslate"><span class="pre">indirectlyImported</span></code> role assigned to “Y4” representing this. “Z4” is the name for +accessing the language object named in “Y4” in “X4” module. “nameref:unknown:Y4” +attached to “Z4” and “scope:module:X4” attached to “Y4” represent the relations.</p> +</section> +</section> +<section id="lambda-expression-and-type-hint"> +<h2>LAMBDA EXPRESSION AND TYPE HINT<a class="headerlink" href="#lambda-expression-and-type-hint" title="Permalink to this headline">¶</a></h2> +<section id="id1"> +<h3>Summary<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3> +<p><cite>id = lambda var0: var0</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 18%" /> +<col style="width: 16%" /> +<col style="width: 29%" /> +<col style="width: 37%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><cite>id</cite></p></td> +<td><p>function</p></td> +<td><p>definition</p></td> +<td><p>signature:(<cite>var0</cite>)</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>id_t: Callable[[int], int] = lambda var1: var1</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 10%" /> +<col style="width: 10%" /> +<col style="width: 17%" /> +<col style="width: 63%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><cite>id_t</cite></p></td> +<td><p>variable</p></td> +<td><p>definition</p></td> +<td><p>typeref:typename:<cite>Callable[[int], int]</cite> nameref:function:anonFuncN</p></td> +</tr> +<tr class="row-odd"><td><p>anonFuncN</p></td> +<td><p>function</p></td> +<td><p>definition</p></td> +<td><p>signature:(<cite>var1</cite>)</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +</section> +<section id="id2"> +<h3>Examples<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3> +<p>“input.py”</p> +<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Callable</span> +<span class="nb">id</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">var0</span><span class="p">:</span> <span class="n">var0</span> +<span class="n">id_t</span><span class="p">:</span> <span class="n">Callable</span><span class="p">[[</span><span class="nb">int</span><span class="p">],</span> <span class="nb">int</span><span class="p">]</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">var1</span><span class="p">:</span> <span class="n">var1</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --sort=no --fields=+KS --fields-Python=+{nameref} --extras=+{anonymous} input.py”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>id input.py /^id = lambda var0: var0$/;" function signature:(var0) +id_t input.py /^id_t: Callable[[int], int] = lambda var1: var1$/;"\ + variable typeref:typename:Callable[[int], int] nameref:function:anonFunc84011d2c0101 +anonFunc84011d2c0101 input.py /^id_t: Callable[[int], int] = lambda var1: var1$/;"\ + function signature:(var1) +</pre></div> +</div> +<p>If a variable (“id”) with no type hint is initialized with a lambda expression, +ctags assigns <code class="docutils literal notranslate"><span class="pre">function</span></code> kind for the tag of “id”.</p> +<p>If a variable (“id_t”) with a type hint is initialized with a lambda expression, +ctags assigns <code class="docutils literal notranslate"><span class="pre">variable</span></code> kind for the tag of “id_t” with <code class="docutils literal notranslate"><span class="pre">typeref:</span></code> and +<code class="docutils literal notranslate"><span class="pre">nameref:</span></code> fields. ctags fills <code class="docutils literal notranslate"><span class="pre">typeref:</span></code> field with the value of the type +hint. The way of filling <code class="docutils literal notranslate"><span class="pre">nameref:</span></code> is a bit complicated.</p> +<p>For the lambda expression used in initializing the type-hint’ed variable, ctags +creates <code class="docutils literal notranslate"><span class="pre">anonymous</span></code> extra tag (“anonFunc84011d2c0101”). ctags fills the +<code class="docutils literal notranslate"><span class="pre">nameref:</span></code> field of “id_t” with the name of <code class="docutils literal notranslate"><span class="pre">anonymous</span></code> extra tag: +“nameref:function:anonFunc84011d2c0101”.</p> +<p>You may think why ctags does so complicated, and why ctags doesn’t emit +following tags output for the input:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>id input.py /^id = \\$/;" function signature:(var0) +id_t input.py /^id_t: \\$/;" function typeref:typename:Callable[[int], int] signature:(var1) +</pre></div> +</div> +<p>There is a reason. The other languages of ctags obey the following rule: ctags fills +<code class="docutils literal notranslate"><span class="pre">typeref:</span></code> field for a tag of a callable object (like function) with the type +of its return value. If we consider “id_t” is a function, its <code class="docutils literal notranslate"><span class="pre">typeref:</span></code> field +should have “typename:int”. However, for filling <code class="docutils literal notranslate"><span class="pre">typeref:</span></code> with “typename:int”, +ctags has to analyze “Callable[[int], int]” deeper. We don’t want to do so.</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-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a>, <a class="reference internal" href="ctags-lang-iPythonCell.7.html#ctags-lang-ipythoncell-7"><span class="std std-ref">ctags-lang-iPythonCell(7)</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-lang-python</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="#tagging-import-statements">TAGGING <code class="docutils literal notranslate"><span class="pre">import</span></code> STATEMENTS</a><ul> +<li><a class="reference internal" href="#summary">Summary</a></li> +<li><a class="reference internal" href="#examples">Examples</a></li> +</ul> +</li> +<li><a class="reference internal" href="#lambda-expression-and-type-hint">LAMBDA EXPRESSION AND TYPE HINT</a><ul> +<li><a class="reference internal" href="#id1">Summary</a></li> +<li><a class="reference internal" href="#id2">Examples</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-lang-julia.7.html" + title="previous chapter">ctags-lang-julia</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-lang-verilog.7.html" + title="next chapter">ctags-lang-verilog</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-lang-verilog.7.html" title="ctags-lang-verilog" + >next</a> |</li> + <li class="right" > + <a href="ctags-lang-julia.7.html" title="ctags-lang-julia" + >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-lang-python</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 diff --git a/ctags/docs/man/ctags-lang-r.7.html b/ctags/docs/man/ctags-lang-r.7.html new file mode 100644 index 0000000..f7f93e7 --- /dev/null +++ b/ctags/docs/man/ctags-lang-r.7.html @@ -0,0 +1,210 @@ + +<!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-lang-r — 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-lang-sql" href="ctags-lang-sql.7.html" /> + <link rel="prev" title="ctags-lang-inko" href="ctags-lang-inko.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-lang-sql.7.html" title="ctags-lang-sql" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-lang-inko.7.html" title="ctags-lang-inko" + 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-lang-r</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-lang-r"> +<span id="ctags-lang-r-7"></span><h1>ctags-lang-r<a class="headerlink" href="#ctags-lang-r" title="Permalink to this headline">¶</a></h1> +<p>Random notes about tagging R source code with Universal Ctags</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> … --languages=+R …</div> +<div class="line"><strong>ctags</strong> … --language-force=R …</div> +<div class="line"><strong>ctags</strong> … --map-Python=+.r …</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>This man page gathers random notes about tagging R source code +with Universal Ctags.</p> +</section> +<section id="kinds"> +<h2>Kinds<a class="headerlink" href="#kinds" title="Permalink to this headline">¶</a></h2> +<p>If a variable gets a value returned from a <em>well-known constructor</em> +and the variable appears for the first time in the current input file, +the R parser makes a tag for the variable and attaches a kind +associated with the constructor to the tag regardless of whether +the variable appears in the top-level context or a function.</p> +<p>Well-known constructor and kind mapping</p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 40%" /> +<col style="width: 60%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>Constructor</p></th> +<th class="head"><p>kind</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>function()</p></td> +<td><p>function</p></td> +</tr> +<tr class="row-odd"><td><p>c()</p></td> +<td><p>vector</p></td> +</tr> +<tr class="row-even"><td><p>list()</p></td> +<td><p>list</p></td> +</tr> +<tr class="row-odd"><td><p>data.frame()</p></td> +<td><p>dataframe</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p>If a variable doesn’t get a value returned from one of well-known +constructors, the R parser attaches <code class="docutils literal notranslate"><span class="pre">globalVar</span></code> or <code class="docutils literal notranslate"><span class="pre">functionVar</span></code> kind +to the tag for the variable depending on the context.</p> +<p>Here is an example demonstrating the usage of the kinds:</p> +<p>“input.r”</p> +<div class="highlight-R notranslate"><div class="highlight"><pre><span></span><span class="n">G</span> <span class="o"><-</span> <span class="m">1</span> +<span class="n">v</span> <span class="o"><-</span> <span class="nf">c</span><span class="p">(</span><span class="m">1</span><span class="p">,</span> <span class="m">2</span><span class="p">)</span> +<span class="n">l</span> <span class="o"><-</span> <span class="nf">list</span><span class="p">(</span><span class="m">3</span><span class="p">,</span> <span class="m">4</span><span class="p">)</span> +<span class="n">d</span> <span class="o"><-</span> <span class="nf">data.frame</span><span class="p">(</span><span class="n">n</span> <span class="o">=</span> <span class="n">v</span><span class="p">)</span> +<span class="n">f</span> <span class="o"><-</span> <span class="nf">function</span><span class="p">(</span><span class="n">a</span><span class="p">)</span> <span class="p">{</span> + <span class="n">g</span> <span class="o"><-</span> <span class="nf">function </span><span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="n">a</span> <span class="o">+</span> <span class="n">b</span> + <span class="n">w</span> <span class="o"><-</span> <span class="nf">c</span><span class="p">(</span><span class="m">1</span><span class="p">,</span> <span class="m">2</span><span class="p">)</span> + <span class="n">m</span> <span class="o"><-</span> <span class="nf">list </span><span class="p">(</span><span class="m">3</span><span class="p">,</span> <span class="m">4</span><span class="p">)</span> + <span class="n">e</span> <span class="o"><-</span> <span class="nf">data.frame</span><span class="p">(</span><span class="n">n</span> <span class="o">=</span> <span class="n">w</span><span class="p">)</span> + <span class="n">L</span> <span class="o"><-</span> <span class="m">2</span> +<span class="p">}</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE --sort=no --fields=+KZ -o - input.r”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>G input.r /^G <- 1$/;" globalVar +v input.r /^v <- c(1, 2)$/;" vector +l input.r /^l <- list(3, 4)$/;" list +d input.r /^d <- data.frame(n = v)$/;" dataframe +n input.r /^d <- data.frame(n = v)$/;" nameattr scope:dataframe:d +f input.r /^f <- function(a) {$/;" function +g input.r /^ g <- function (b) a + b$/;" function scope:function:f +w input.r /^ w <- c(1, 2)$/;" vector scope:function:f +m input.r /^ m <- list (3, 4)$/;" list scope:function:f +e input.r /^ e <- data.frame(n = w)$/;" dataframe scope:function:f +n input.r /^ e <- data.frame(n = w)$/;" nameattr scope:dataframe:f.e +L input.r /^ L <- 2$/;" functionVar scope:function:f +</pre></div> +</div> +</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></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-lang-r</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="#kinds">Kinds</a></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-lang-inko.7.html" + title="previous chapter">ctags-lang-inko</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-lang-sql.7.html" + title="next chapter">ctags-lang-sql</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-lang-sql.7.html" title="ctags-lang-sql" + >next</a> |</li> + <li class="right" > + <a href="ctags-lang-inko.7.html" title="ctags-lang-inko" + >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-lang-r</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 diff --git a/ctags/docs/man/ctags-lang-sql.7.html b/ctags/docs/man/ctags-lang-sql.7.html new file mode 100644 index 0000000..6046469 --- /dev/null +++ b/ctags/docs/man/ctags-lang-sql.7.html @@ -0,0 +1,237 @@ + +<!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-lang-sql — 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-incompatibilities" href="ctags-incompatibilities.7.html" /> + <link rel="prev" title="ctags-lang-r" href="ctags-lang-r.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-incompatibilities.7.html" title="ctags-incompatibilities" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-lang-r.7.html" title="ctags-lang-r" + 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-lang-sql</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-lang-sql"> +<span id="ctags-lang-sql-7"></span><h1>ctags-lang-sql<a class="headerlink" href="#ctags-lang-sql" title="Permalink to this headline">¶</a></h1> +<p>The man page of the SQL parser for Universal Ctags</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> … [--extras={guest}] --languages=+SQL …</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>The SQL parser supports various SQL dialects. PostgreSQL is one of them.</p> +<p>PostgreSQL allows user-defined functions to be written in other +languages (<em>procedural languages</em>) besides SQL and C <a class="reference internal" href="#pl" id="id1"><span>[PL]</span></a>.</p> +<p>The SQL parser makes tags for language objects in the user-defined +functions written in the procedural languages if the <code class="docutils literal notranslate"><span class="pre">guest</span></code> extra +is enabled.</p> +<p>The SQL parser looks for a token coming after <code class="docutils literal notranslate"><span class="pre">LANGUAGE</span></code> keyword in +the source code to choose a proper guest parser.</p> +<div class="highlight-SQL notranslate"><div class="highlight"><pre><span></span>... LANGUAGE plpythonu AS '... user-defined function ' ... +... AS $$ user-defined function $$ LANGUAGE plv8 ... +</pre></div> +</div> +<p>In the above examples, <code class="docutils literal notranslate"><span class="pre">plpythonu</span></code> and <code class="docutils literal notranslate"><span class="pre">plv8</span></code> are the names of +procedural languages. The SQL parser trims <cite>pl</cite> at the start and <cite>u</cite> +at the end of the name before finding a parser ctags having. For +<code class="docutils literal notranslate"><span class="pre">plpythonu</span></code> and <code class="docutils literal notranslate"><span class="pre">`plv8</span></code>, the SQL parser extracts <code class="docutils literal notranslate"><span class="pre">python</span></code> and +<code class="docutils literal notranslate"><span class="pre">v8</span></code> as the candidates of guest parsers.</p> +<p>For <code class="docutils literal notranslate"><span class="pre">plpythonu</span></code>, ctags can run its Python parser. ctags doesn’t +have a parser named <code class="docutils literal notranslate"><span class="pre">v8</span></code>. However, JavaScript parser of ctags has +<code class="docutils literal notranslate"><span class="pre">v8</span></code> as an alias. So ctags can run the JavaScript parser as the +guest parser for <code class="docutils literal notranslate"><span class="pre">plv8</span></code>.</p> +</section> +<section id="examples"> +<h2>EXAMPLES<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2> +<p>tagging code including a user-defined function in a string literal <a class="reference internal" href="#gh3006" id="id2"><span>[GH3006]</span></a>:</p> +<p>“input.sql”</p> +<div class="highlight-SQL notranslate"><div class="highlight"><pre><span></span><span class="k">CREATE</span> <span class="k">OR</span> <span class="k">REPLACE</span> <span class="k">FUNCTION</span> <span class="n">fun1</span><span class="p">()</span> <span class="k">RETURNS</span> <span class="nb">VARCHAR</span> <span class="k">AS</span> <span class="s1">'</span> +<span class="s1">DECLARE</span> +<span class="s1"> test1_var1 VARCHAR(64) := $$ABC$$;</span> +<span class="s1"> test1_var2 VARCHAR(64) := $xyz$XYZ$xyz$;</span> +<span class="s1"> test1_var3 INTEGER := 1;</span> +<span class="s1">BEGIN</span> +<span class="s1"> RETURN TO_CHAR(test_var3, ''000'') || test1_var1 || test1_var2;</span> +<span class="s1">END;</span> +<span class="s1">'</span> <span class="k">LANGUAGE</span> <span class="n">plpgsql</span><span class="p">;</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --sort=no --extras=+{guest} input.sql”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>fun1 input.sql /^CREATE OR REPLACE FUNCTION fun1() RETURNS VARCHAR AS '$/;" f +test1_var1 input.sql /^ test1_var1 VARCHAR(64) := $$ABC$$;$/;" v +test1_var2 input.sql /^ test1_var2 VARCHAR(64) := $xyz$XYZ$xyz$;$/;" v +test1_var3 input.sql /^ test1_var3 INTEGER := 1;$/;" v +</pre></div> +</div> +<p>tagging code including a user-defined function in a dollar quote <a class="reference internal" href="#gh3006" id="id3"><span>[GH3006]</span></a>:</p> +<p>“input.sql”</p> +<div class="highlight-SQL notranslate"><div class="highlight"><pre><span></span>CREATE OR REPLACE FUNCTION fun2() RETURNS VARCHAR LANGUAGE plpgsql AS $$ +DECLARE + test2_var1 VARCHAR(64) := 'ABC2'; + test2_var2 VARCHAR(64) := 'XYZ2'; + test2_var3 INTEGER := 2; +BEGIN + RETURN TO_CHAR(test2_var3, '000') || test2_var1 || test2_var2; +END; +$$; +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --sort=no --extras=+{guest} input.sql”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>fun2 input.sql /^CREATE OR REPLACE FUNCTION fun2() RETURNS VARCHAR LANGUAGE plpgsql AS $\$$/;" f +test2_var1 input.sql /^ test2_var1 VARCHAR(64) := 'ABC2';$/;" v +test2_var2 input.sql /^ test2_var2 VARCHAR(64) := 'XYZ2';$/;" v +test2_var3 input.sql /^ test2_var3 INTEGER := 2;$/;" v +</pre></div> +</div> +<p>tagging code including a user-defined written in JavaScript:</p> +<div class="highlight-SQL notranslate"><div class="highlight"><pre><span></span>-- Derived from https://github.com/plv8/plv8/blob/r3.0alpha/sql/plv8.sql +CREATE FUNCTION test(keys text[], vals text[]) RETURNS text AS +$$ + var o = {}; + for (var i = 0; i < keys.length; i++) + o[keys[i]] = vals[i]; + return JSON.stringify(o); +$$ +LANGUAGE plv8 IMMUTABLE STRICT; +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --sort=no --extras=+{guest} input.sql”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>test input.sql /^CREATE FUNCTION test(keys text[], vals text[]) RETURNS text AS$/;" f +o input.sql /^ var o = {};$/;" v +</pre></div> +</div> +</section> +<section id="known-bugs"> +<h2>KNOWN BUGS<a class="headerlink" href="#known-bugs" title="Permalink to this headline">¶</a></h2> +<p>Escape sequences (<cite>‘’</cite>) in a string literal may make a guest parser confused.</p> +</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-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a></p> +</section> +<section id="references"> +<h2>REFERENCES<a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2> +<dl class="citation"> +<dt class="label" id="pl"><span class="brackets"><a class="fn-backref" href="#id1">PL</a></span></dt> +<dd><p>PostgreSQL 9.5.25 Documentation, “Chapter 39. Procedural Languages”, <a class="reference external" href="https://www.postgresql.org/docs/9.5/xplang.html">https://www.postgresql.org/docs/9.5/xplang.html</a></p> +</dd> +<dt class="label" id="gh3006"><span class="brackets">GH3006</span><span class="fn-backref">(<a href="#id2">1</a>,<a href="#id3">2</a>)</span></dt> +<dd><p>@bagl’s comment submitted to <a class="reference external" href="https://github.com/universal-ctags/ctags/issues/3006">https://github.com/universal-ctags/ctags/issues/3006</a></p> +</dd> +</dl> +</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-lang-sql</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="#examples">EXAMPLES</a></li> +<li><a class="reference internal" href="#known-bugs">KNOWN BUGS</a></li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +<li><a class="reference internal" href="#references">REFERENCES</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-lang-r.7.html" + title="previous chapter">ctags-lang-r</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-incompatibilities.7.html" + title="next chapter">ctags-incompatibilities</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-incompatibilities.7.html" title="ctags-incompatibilities" + >next</a> |</li> + <li class="right" > + <a href="ctags-lang-r.7.html" title="ctags-lang-r" + >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-lang-sql</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 diff --git a/ctags/docs/man/ctags-lang-verilog.7.html b/ctags/docs/man/ctags-lang-verilog.7.html new file mode 100644 index 0000000..2114fac --- /dev/null +++ b/ctags/docs/man/ctags-lang-verilog.7.html @@ -0,0 +1,318 @@ + +<!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-lang-verilog — 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-lang-inko" href="ctags-lang-inko.7.html" /> + <link rel="prev" title="ctags-lang-python" href="ctags-lang-python.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-lang-inko.7.html" title="ctags-lang-inko" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-lang-python.7.html" title="ctags-lang-python" + 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-lang-verilog</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-lang-verilog"> +<span id="ctags-lang-verilog-7"></span><h1>ctags-lang-verilog<a class="headerlink" href="#ctags-lang-verilog" title="Permalink to this headline">¶</a></h1> +<p>The man page about SystemVerilog/Verilog parser for Universal Ctags</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> … [--kinds-systemverilog=+Q] [--fields-SystemVerilog=+{parameter}] …</div> +<div class="line"><strong>ctags</strong> … [--fields-Verilog=+{parameter}] …</div> +</div> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 31%" /> +<col style="width: 31%" /> +<col style="width: 39%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>Language</p></th> +<th class="head"><p>Language ID</p></th> +<th class="head"><p>File Mapping</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>SystemVerilog</p></td> +<td><p>SystemVerilog</p></td> +<td><p>.sv, .svh, svi</p></td> +</tr> +<tr class="row-odd"><td><p>Verilog</p></td> +<td><p>Verilog</p></td> +<td><p>.v</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>This man page describes about the SystemVerilog/Verilog parser for Universal Ctags. +SystemVerilog parser supports IEEE Std 1800-2017 keywords. +Verilog parser supports IEEE Std 1364-2005 keywords.</p> +<section id="supported-kinds"> +<h3>Supported Kinds<a class="headerlink" href="#supported-kinds" title="Permalink to this headline">¶</a></h3> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-kinds-full<span class="o">=</span>SystemVerilog +<span class="gp">#</span>LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +<span class="go">A assert yes no 0 NONE assertions (assert, assume, cover, restrict)</span> +<span class="go">C class yes no 0 NONE classes</span> +<span class="go">E enum yes no 0 NONE enumerators</span> +<span class="go">H checker yes no 0 NONE checkers</span> +<span class="go">I interface yes no 0 NONE interfaces</span> +<span class="go">K package yes no 0 NONE packages</span> +<span class="go">L clocking yes no 0 NONE clocking</span> +<span class="go">M modport yes no 0 NONE modports</span> +<span class="go">N nettype yes no 0 NONE nettype declarations</span> +<span class="go">O constraint yes no 0 NONE constraints</span> +<span class="go">P program yes no 0 NONE programs</span> +<span class="go">Q prototype no no 0 NONE prototypes (extern, pure)</span> +<span class="go">R property yes no 0 NONE properties</span> +<span class="go">S struct yes no 0 NONE structs and unions</span> +<span class="go">T typedef yes no 0 NONE type declarations</span> +<span class="go">V covergroup yes no 0 NONE covergroups</span> +<span class="go">b block yes no 0 NONE blocks (begin, fork)</span> +<span class="go">c constant yes no 0 NONE constants (define, parameter, specparam, enum values)</span> +<span class="go">e event yes no 0 NONE events</span> +<span class="go">f function yes no 0 NONE functions</span> +<span class="go">i instance yes no 0 NONE instances of module or interface</span> +<span class="go">l ifclass yes no 0 NONE interface class</span> +<span class="go">m module yes no 0 NONE modules</span> +<span class="go">n net yes no 0 NONE net data types</span> +<span class="go">p port yes no 0 NONE ports</span> +<span class="go">q sequence yes no 0 NONE sequences</span> +<span class="go">r register yes no 0 NONE variable data types</span> +<span class="go">t task yes no 0 NONE tasks</span> +<span class="go">w member yes no 0 NONE struct and union members</span> +</pre></div> +</div> +<p>Note that <code class="docutils literal notranslate"><span class="pre">prototype</span></code> (<code class="docutils literal notranslate"><span class="pre">Q</span></code>) is disabled by default.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-kinds-full<span class="o">=</span>Verilog +<span class="gp">#</span>LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +<span class="go">b block yes no 0 NONE blocks (begin, fork)</span> +<span class="go">c constant yes no 0 NONE constants (define, parameter, specparam)</span> +<span class="go">e event yes no 0 NONE events</span> +<span class="go">f function yes no 0 NONE functions</span> +<span class="go">i instance yes no 0 NONE instances of module</span> +<span class="go">m module yes no 0 NONE modules</span> +<span class="go">n net yes no 0 NONE net data types</span> +<span class="go">p port yes no 0 NONE ports</span> +<span class="go">r register yes no 0 NONE variable data types</span> +<span class="go">t task yes no 0 NONE tasks</span> +</pre></div> +</div> +</section> +<section id="supported-language-specific-fields"> +<h3>Supported Language Specific Fields<a class="headerlink" href="#supported-language-specific-fields" title="Permalink to this headline">¶</a></h3> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-fields<span class="o">=</span>Verilog +<span class="gp">#</span>LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION +<span class="go">- parameter no Verilog --b no parameter whose value can be overridden.</span> +<span class="gp">$ </span>ctags --list-fields<span class="o">=</span>SystemVerilog +<span class="gp">#</span>LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION +<span class="go">- parameter no SystemVerilog --b no parameter whose value can be overridden.</span> +</pre></div> +</div> +<section id="parameter-field"> +<h4><code class="docutils literal notranslate"><span class="pre">parameter</span></code> field<a class="headerlink" href="#parameter-field" title="Permalink to this headline">¶</a></h4> +<p>If the field <code class="docutils literal notranslate"><span class="pre">parameter</span></code> is enabled, a field <code class="docutils literal notranslate"><span class="pre">parameter:</span></code> is added on a parameter whose +value can be overridden on an instantiated module, interface, or program. +This is useful for a editor plugin or extension to enable auto-instantiation of modules with +parameters which can be overridden.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags ... --fields-Verilog<span class="o">=</span>+<span class="o">{</span>parameter<span class="o">}</span> ... +<span class="gp">$ </span>ctags ... --fields-SystemVerilog<span class="o">=</span>+<span class="o">{</span>parameter<span class="o">}</span> ... +</pre></div> +</div> +<p>On the following source code fields <code class="docutils literal notranslate"><span class="pre">parameter:</span></code> are added on +parameters <code class="docutils literal notranslate"><span class="pre">P*</span></code>, not on ones <code class="docutils literal notranslate"><span class="pre">L*</span></code>. Note that <code class="docutils literal notranslate"><span class="pre">L4</span></code> and <code class="docutils literal notranslate"><span class="pre">L6</span></code> is declared by +<code class="docutils literal notranslate"><span class="pre">parameter</span></code> statement, but fields <code class="docutils literal notranslate"><span class="pre">parameter:</span></code> are not added, +because they cannot be overridden.</p> +<p>“input.sv”</p> +<div class="highlight-systemverilog notranslate"><div class="highlight"><pre><span></span><span class="c1">// compilation unit scope</span> +<span class="k">parameter</span> <span class="n">L1</span> <span class="o">=</span> <span class="s">"synonym for the localparam"</span><span class="p">;</span> + +<span class="k">module</span> <span class="n">with_parameter_port_list</span> <span class="p">#(</span> + <span class="n">P1</span><span class="p">,</span> + <span class="k">localparam</span> <span class="n">L2</span> <span class="o">=</span> <span class="n">P1</span><span class="o">+</span><span class="mi">1</span><span class="p">,</span> + <span class="k">parameter</span> <span class="n">P2</span><span class="p">)</span> + <span class="p">(</span> <span class="cm">/*port list...*/</span> <span class="p">);</span> + <span class="k">parameter</span> <span class="n">L3</span> <span class="o">=</span> <span class="s">"synonym for the localparam"</span><span class="p">;</span> + <span class="k">localparam</span> <span class="n">L4</span> <span class="o">=</span> <span class="s">"localparam"</span><span class="p">;</span> + <span class="c1">// ...</span> +<span class="k">endmodule</span> + +<span class="k">module</span> <span class="n">with_empty_parameter_port_list</span> <span class="p">#()</span> + <span class="p">(</span> <span class="cm">/*port list...*/</span> <span class="p">);</span> + <span class="k">parameter</span> <span class="n">L5</span> <span class="o">=</span> <span class="s">"synonym for the localparam"</span><span class="p">;</span> + <span class="k">localparam</span> <span class="n">L6</span> <span class="o">=</span> <span class="s">"localparam"</span><span class="p">;</span> + <span class="c1">// ...</span> +<span class="k">endmodule</span> + +<span class="k">module</span> <span class="n">no_parameter_port_list</span> + <span class="p">(</span> <span class="cm">/*port list...*/</span> <span class="p">);</span> + <span class="k">parameter</span> <span class="n">P3</span> <span class="o">=</span> <span class="s">"parameter"</span><span class="p">;</span> + <span class="k">localparam</span> <span class="n">L7</span> <span class="o">=</span> <span class="s">"localparam"</span><span class="p">;</span> + <span class="c1">// ...</span> +<span class="k">endmodule</span> +</pre></div> +</div> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -uo - --fields-SystemVerilog<span class="o">=</span>+<span class="o">{</span>parameter<span class="o">}</span> input.sv +<span class="go">L1 input.sv /^parameter L1 = "synonym for the localparam";$/;" c parameter:</span> +<span class="go">with_parameter_port_list input.sv /^module with_parameter_port_list #($/;" m</span> +<span class="go">P1 input.sv /^ P1,$/;" c module:with_parameter_port_list parameter:</span> +<span class="go">L2 input.sv /^ localparam L2 = P1+1,$/;" c module:with_parameter_port_list</span> +<span class="go">P2 input.sv /^ parameter P2)$/;" c module:with_parameter_port_list parameter:</span> +<span class="go">L3 input.sv /^ parameter L3 = "synonym for the localparam";$/;" c module:with_parameter_port_list</span> +<span class="go">L4 input.sv /^ localparam L4 = "localparam";$/;" c module:with_parameter_port_list</span> +<span class="go">with_empty_parameter_port_list input.sv /^module with_empty_parameter_port_list #()$/;" m</span> +<span class="go">L5 input.sv /^ parameter L5 = "synonym for the localparam";$/;" c module:with_empty_parameter_port_list</span> +<span class="go">L6 input.sv /^ localparam L6 = "localparam";$/;" c module:with_empty_parameter_port_list</span> +<span class="go">no_parameter_port_list input.sv /^module no_parameter_port_list$/;" m</span> +<span class="go">P3 input.sv /^ parameter P3 = "parameter";$/;" c module:no_parameter_port_list parameter:</span> +<span class="go">L7 input.sv /^ localparam L7 = "localparam";$/;" c module:no_parameter_port_list</span> +</pre></div> +</div> +</section> +</section> +<section id="tips"> +<h3>TIPS<a class="headerlink" href="#tips" title="Permalink to this headline">¶</a></h3> +<p>If you want to map files <code class="docutils literal notranslate"><span class="pre">*.v</span></code> to SystemVerilog, add +<code class="docutils literal notranslate"><span class="pre">--langmap=SystemVerilog:.v</span></code> option.</p> +</section> +</section> +<section id="known-issues"> +<h2>KNOWN ISSUES<a class="headerlink" href="#known-issues" title="Permalink to this headline">¶</a></h2> +<p>See <a class="reference external" href="https://github.com/universal-ctags/ctags/issues/2674">https://github.com/universal-ctags/ctags/issues/2674</a> for more information.</p> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a></p></li> +<li><p><a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a></p></li> +<li><dl class="simple"> +<dt>Language Reference Manuals (LRM)</dt><dd><ul> +<li><p>IEEE Standard for SystemVerilog — Unified Hardware Design, Specification, and +Verification Language, IEEE Std 1800-2017, +<a class="reference external" href="https://ieeexplore.ieee.org/document/8299595">https://ieeexplore.ieee.org/document/8299595</a></p></li> +<li><p>IEEE Standard for Verilog Hardware Description Language, IEEE Std 1364-2005, +<a class="reference external" href="https://ieeexplore.ieee.org/document/1620780">https://ieeexplore.ieee.org/document/1620780</a></p></li> +</ul> +</dd> +</dl> +</li> +</ul> +</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-lang-verilog</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a><ul> +<li><a class="reference internal" href="#supported-kinds">Supported Kinds</a></li> +<li><a class="reference internal" href="#supported-language-specific-fields">Supported Language Specific Fields</a><ul> +<li><a class="reference internal" href="#parameter-field"><code class="docutils literal notranslate"><span class="pre">parameter</span></code> field</a></li> +</ul> +</li> +<li><a class="reference internal" href="#tips">TIPS</a></li> +</ul> +</li> +<li><a class="reference internal" href="#known-issues">KNOWN ISSUES</a></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-lang-python.7.html" + title="previous chapter">ctags-lang-python</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-lang-inko.7.html" + title="next chapter">ctags-lang-inko</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-lang-inko.7.html" title="ctags-lang-inko" + >next</a> |</li> + <li class="right" > + <a href="ctags-lang-python.7.html" title="ctags-lang-python" + >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-lang-verilog</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 diff --git a/ctags/docs/man/ctags-optlib.7.html b/ctags/docs/man/ctags-optlib.7.html new file mode 100644 index 0000000..0f73ed2 --- /dev/null +++ b/ctags/docs/man/ctags-optlib.7.html @@ -0,0 +1,520 @@ + +<!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-optlib — 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-client-tools" href="ctags-client-tools.7.html" /> + <link rel="prev" title="tags" href="tags.5.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-client-tools.7.html" title="ctags-client-tools" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="tags.5.html" title="tags" + 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-optlib</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-optlib"> +<span id="ctags-optlib-7"></span><h1>ctags-optlib<a class="headerlink" href="#ctags-optlib" title="Permalink to this headline">¶</a></h1> +<p>Universal Ctags parser definition language</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><em>Exuberant Ctags</em>, the ancestor of <em>Universal Ctags</em>, has provided +the way to define a new parser from command line. Universal Ctags +extends and refines this feature. <em>optlib parser</em> is the name for such +parser in Universal Ctags. “opt” intends a parser is defined with +combination of command line options. “lib” intends an optlib parser +can be more than ad-hoc personal configuration.</p> +<p>This man page is for people who want to define an optlib parser. The +readers should read <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> of Universal Ctags first.</p> +<p>Following options are for defining (or customizing) a parser:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">--langdef=<name></span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">--map-<LANG>=[+|-]<extension>|<pattern></span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code></p></li> +</ul> +<p>Following options are for controlling loading parser definition:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">--options=<pathname></span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">--options-maybe=<pathname></span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">--optlib-dir=[+]<directory></span></code></p></li> +</ul> +<p>The design of options and notations for defining a parser in +Exuberant Ctags may focus on reducing the number of typing by user. +Reducing the number of typing is important for users who want to +define (or customize) a parser quickly.</p> +<p>On the other hand, the design in Universal Ctags focuses on +maintainability. The notation of Universal Ctags is redundant than +that of Exuberant Ctags; the newly introduced kind should be declared +explicitly, (long) names are approved than one-letter flags +specifying kinds, and naming rules are stricter.</p> +<p>This man page explains only stable options and flags. Universal Ctags +also introduces experimental options and flags which have names starting +with <code class="docutils literal notranslate"><span class="pre">_</span></code>. For documentation on these options and flags, visit +Universal Ctags web site at <a class="reference external" href="https://ctags.io/">https://ctags.io/</a>.</p> +<section id="storing-a-parser-definition-to-a-file"> +<h3>Storing a parser definition to a file<a class="headerlink" href="#storing-a-parser-definition-to-a-file" title="Permalink to this headline">¶</a></h3> +<p>Though it is possible to define a parser from command line, you don’t +want to type the same command line each time when you need the parser. +You can store options for defining a parser into a file.</p> +<p>ctags loads files (preload files) listed in “FILES” +section of <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> at program starting up. You can put your parser +definition needed usually to the files.</p> +<p><code class="docutils literal notranslate"><span class="pre">--options=<pathname></span></code>, <code class="docutils literal notranslate"><span class="pre">--options-maybe=<pathname></span></code>, and +<code class="docutils literal notranslate"><span class="pre">--optlib-dir=[+]<directory></span></code> are for loading optlib files you need +occasionally. See “Option File Options” section of <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> for +these options.</p> +<p>As explained in “FILES” section of <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, options for defining a +parser listed line by line in an optlib file. Prefixed white spaces are +ignored. A line starting with ‘#’ is treated as a comment. Escaping +shell meta character is not needed.</p> +<p>Use <code class="docutils literal notranslate"><span class="pre">.ctags</span></code> as file extension for optlib file. You can define +multiple parsers in an optlib file but it is better to make a file for +each parser definition.</p> +<p><code class="docutils literal notranslate"><span class="pre">--_echo=<msg></span></code> and <code class="docutils literal notranslate"><span class="pre">--_force-quit=<num></span></code> options are for debugging +optlib parser.</p> +</section> +<section id="overview-for-defining-a-parser"> +<h3>Overview for defining a parser<a class="headerlink" href="#overview-for-defining-a-parser" title="Permalink to this headline">¶</a></h3> +<ol class="arabic"> +<li><p>Design the parser</p> +<p>You need know both the target language and the ctags’ +concepts (definition, reference, kind, role, field, extra). About +the concepts, <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> of Universal Ctags may help you.</p> +</li> +<li><p>Give a name to the parser</p> +<p>Use <code class="docutils literal notranslate"><span class="pre">--langdef=<name></span></code> option. <em><name></em> is referred as <em><LANG></em> in +the later steps.</p> +</li> +<li><p>Give a file pattern or file extension for activating the parser</p> +<p>Use <code class="docutils literal notranslate"><span class="pre">--map-<LANG>=[+|-]<extension>|<pattern></span></code>.</p> +</li> +<li><p>Define kinds</p> +<p>Use <code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></code> option. +Universal Ctags introduces this option. Exuberant Ctags doesn’t +have. In Exuberant Ctags, a kind is defined as a side effect of +specifying <code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=</span></code> option. So user doesn’t have a +chance to recognize how important the definition of kind.</p> +</li> +<li><p>Define patterns</p> +<p>Use <code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code> +option for a single-line regular expression. You can also use +<code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code> +option for a multi-line regular expression.</p> +<p>As <em><kind-spec></em>, you can use the one-letter flag defined with +<code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></code> option.</p> +</li> +</ol> +</section> +</section> +<section id="options"> +<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--langdef=<name></span></code></dt><dd><p>Defines a new user-defined language, <em><name></em>, to be parsed with regular +expressions. Once defined, <em><name></em> may be used in other options taking +language names.</p> +<p><em><name></em> must consist of alphanumeric characters, ‘<code class="docutils literal notranslate"><span class="pre">#</span></code>’, or ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ +(‘[a-zA-Z0-9#+]+’). The graph characters other than ‘<code class="docutils literal notranslate"><span class="pre">#</span></code>’ and +‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ are disallowed (or reserved). Some of them (<code class="docutils literal notranslate"><span class="pre">[-=:{.]</span></code>) are +disallowed because they can make the command line parser of +ctags confused. The rest of them are just +reserved for future extending ctags.</p> +<p><code class="docutils literal notranslate"><span class="pre">all</span></code> is an exception. <code class="docutils literal notranslate"><span class="pre">all</span></code> as <em><name></em> is not acceptable. It is +a reserved word. See the description of +<code class="docutils literal notranslate"><span class="pre">--kinds-(<LANG>|all)=[+|-](<kinds>|*)</span></code> option in <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> about how the +reserved word is used.</p> +<p>The names of built-in parsers are capitalized. When +ctags evaluates an option in a command line, and +chooses a parser, ctags uses the names of +parsers in a case-insensitive way. Therefore, giving a name +started from a lowercase character doesn’t help you to avoid the +parser name confliction. However, in a tags file, +ctags prints parser names in a case-sensitive +way; it prints a parser name as specified in <code class="docutils literal notranslate"><span class="pre">--langdef=<name></span></code> +option. Therefore, we recommend you to give a name started from a +lowercase character to your private optlib parser. With this +convention, people can know where a tag entry in a tag file comes +from a built-in parser or a private optlib parser.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></code></dt><dd><p>Define a kind for <em><LANG></em>. +Be not confused this with <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code>.</p> +<p><em><letter></em> must be an alphabetical character (‘[a-zA-EG-Z]’) +other than “F”. “F” has been reserved for representing a file +since Exuberant Ctags.</p> +<p><em><name></em> must start with an alphabetic character, and the rest +must be alphanumeric (‘[a-zA-Z][a-zA-Z0-9]*’). Do not use +“file” as <em><name></em>. It has been reserved for representing a file +since Exuberant Ctags.</p> +<p>Note that using a number character in a <em><name></em> violates the +version 2 of tags file format though ctags +accepts it. For more detail, see <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>.</p> +<p><em><description></em> comes from any printable ASCII characters. The +exception is <code class="docutils literal notranslate"><span class="pre">{</span></code> and <code class="docutils literal notranslate"><span class="pre">\</span></code>. <code class="docutils literal notranslate"><span class="pre">{</span></code> is reserved for adding flags +this option in the future. So put <code class="docutils literal notranslate"><span class="pre">\</span></code> before <code class="docutils literal notranslate"><span class="pre">{</span></code> to include +<code class="docutils literal notranslate"><span class="pre">{</span></code> to a description. To include <code class="docutils literal notranslate"><span class="pre">\</span></code> itself to a description, +put <code class="docutils literal notranslate"><span class="pre">\</span></code> before <code class="docutils literal notranslate"><span class="pre">\</span></code>.</p> +<p>Both <em><letter></em>, <em><name></em> and their combination must be unique in +a <em><LANG></em>.</p> +<p>This option is newly introduced in Universal Ctags. This option +reduces the typing defining a regex pattern with +<code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=</span></code>, and keeps the consistency of kind +definitions in a language.</p> +<p>The <em><letter></em> can be used as an argument for <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code> +option to enable or disable the kind. Unless <code class="docutils literal notranslate"><span class="pre">K</span></code> field is +enabled, the <em><letter></em> is used as value in the “kind” extension +field in tags output.</p> +<p>The <em><name></em> surrounded by braces can be used as an argument for +<code class="docutils literal notranslate"><span class="pre">--kind-<LANG></span></code> option. If <code class="docutils literal notranslate"><span class="pre">K</span></code> field is enabled, the <em><name></em> +is used as value in the “kind” extension field in tags output.</p> +<p>The <em><description></em> and <em><letter></em> are listed in <code class="docutils literal notranslate"><span class="pre">--list-kinds</span></code> +output. All three elements of the kind-spec are listed in +<code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code> output. Don’t use braces in the +<em><description></em>. They will be used meta characters in the future.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code></dt><dd><p>Define a single-line regular expression.</p> +<p>The <em>/<line_pattern>/<name_pattern>/</em> pair defines a regular expression +replacement pattern, similar in style to <code class="docutils literal notranslate"><span class="pre">sed</span></code> substitution +commands, <code class="docutils literal notranslate"><span class="pre">s/regexp/replacement/</span></code>, with which to generate tags from source files mapped to +the named language, <em><LANG></em>, (case-insensitive; either a built-in +or user-defined language).</p> +<p>The regular expression, <em><line_pattern></em>, defines +an extended regular expression (roughly that used by egrep(1)), +which is used to locate a single source line containing a tag and +may specify tab characters using <code class="docutils literal notranslate"><span class="pre">\t</span></code>.</p> +<p>When a matching line is +found, a tag will be generated for the name defined by +<em><name_pattern></em>, which generally will contain the special +back-references <code class="docutils literal notranslate"><span class="pre">\1</span></code> through <code class="docutils literal notranslate"><span class="pre">\9</span></code> to refer to matching sub-expression +groups within <em><line_pattern></em>.</p> +<p>The ‘<code class="docutils literal notranslate"><span class="pre">/</span></code>’ separator characters shown in the +parameter to the option can actually be replaced by any +character. Note that whichever separator character is used will +have to be escaped with a backslash (’<code class="docutils literal notranslate"><span class="pre">\</span></code>’) character wherever it is +used in the parameter as something other than a separator. The +regular expression defined by this option is added to the current +list of regular expressions for the specified language unless the +parameter is omitted, in which case the current list is cleared.</p> +<p>Unless modified by <em><flags></em>, <em><line_pattern></em> is interpreted as a POSIX +extended regular expression. The <em><name_pattern></em> should expand for all +matching lines to a non-empty string of characters, or a warning +message will be reported unless <code class="docutils literal notranslate"><span class="pre">{placeholder}</span></code> regex flag is +specified.</p> +<p>A kind specifier (<em><kind-spec></em>) for tags matching regexp may +follow <em><name_pattern></em>, which will determine what kind of tag is +reported in the <code class="docutils literal notranslate"><span class="pre">kind</span></code> extension field (see <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>).</p> +<p><em><kind-spec></em> has two forms: <em>one-letter form</em> and <em>full form</em>.</p> +<p>The one-letter form in the form of <code class="docutils literal notranslate"><span class="pre"><letter></span></code>. It just refers a kind +<em><letter></em> defined with <code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG></span></code>. This form is recommended in +Universal Ctags.</p> +<p>The full form of <em><kind-spec></em> is in the form of +<code class="docutils literal notranslate"><span class="pre"><letter>,<name>,<description></span></code>. Either the kind <em><name></em> and/or the +<em><description></em> can be omitted. See the description of +<code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></code> option about the +elements.</p> +<p>The full form is supported only for keeping the compatibility with Exuberant +Ctags which does not have <code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG></span></code> option. Supporting the +form will be removed from Universal Ctags in the future.</p> +<p>About <em><flags></em>, see “FLAGS FOR <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> OPTION”.</p> +<p>For more information on the regular expressions used by +ctags, see either the regex(5,7) man page, or +the GNU info documentation for regex (e.g. “<code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">regex</span></code>”).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-regex-flags</span></code></dt><dd><p>Lists the flags that can be used in <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-mline-regex-flags</span></code></dt><dd><p>Lists the flags that can be used in <code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code> option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code></dt><dd><p>Define a multi-line regular expression.</p> +<p>This option is similar to <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> option except the pattern is +applied to the whole file’s contents, not line by line.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--_echo=<message></span></code></dt><dd><p>Print <em><message></em> to the standard error stream. This is helpful to +understand (and debug) optlib loading feature of Universal Ctags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--_force-quit[=<num>]</span></code></dt><dd><p>Exits immediately when this option is processed. If <em><num></em> is used +as exit status. The default is 0. This is helpful to debug optlib +loading feature of Universal Ctags.</p> +</dd> +</dl> +<section id="flags-for-regex-lang-option"> +<h3>FLAGS FOR <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> OPTION<a class="headerlink" href="#flags-for-regex-lang-option" title="Permalink to this headline">¶</a></h3> +<p>You can specify more than one flag, <code class="docutils literal notranslate"><span class="pre"><letter>|{<name>}</span></code>, at the end of <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> to +control how Universal Ctags uses the pattern.</p> +<p>Exuberant Ctags uses a <em><letter></em> to represent a flag. In +Universal Ctags, a <em><name></em> surrounded by braces (name form) can be used +in addition to <em><letter></em>. The name form makes a user reading an optlib +file easier.</p> +<p>The most of all flags newly added in Universal Ctags +don’t have the one-letter representation. All of them have only the name +representation. <code class="docutils literal notranslate"><span class="pre">--list-regex-flags</span></code> lists all the flags.</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">basic</span></code> (one-letter form <code class="docutils literal notranslate"><span class="pre">b</span></code>)</dt><dd><p>The pattern is interpreted as a POSIX basic regular expression.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">exclusive</span></code> (one-letter form <code class="docutils literal notranslate"><span class="pre">x</span></code>)</dt><dd><p>Skip testing the other patterns if a line is matched to this +pattern. This is useful to avoid using CPU to parse line comments.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">extend</span></code> (one-letter form <code class="docutils literal notranslate"><span class="pre">e</span></code>)</dt><dd><p>The pattern is interpreted as a POSIX extended regular +expression (default).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">icase</span></code> (one-letter form <code class="docutils literal notranslate"><span class="pre">i</span></code>)</dt><dd><p>The regular expression is to be applied in a case-insensitive +manner.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">placeholder</span></code></dt><dd><p>Don’t emit a tag captured with a regex pattern. The replacement +can be an empty string. See the following description of +<code class="docutils literal notranslate"><span class="pre">scope=...</span></code> flag about how this is useful.</p> +</dd> +</dl> +<p><code class="docutils literal notranslate"><span class="pre">scope=(ref|push|pop|clear|set)</span></code></p> +<blockquote> +<div><p>Specify what to do with the internal scope stack.</p> +<p>A parser programmed with <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> has a stack (scope +stack) internally. You can use it for tracking scope +information. The <code class="docutils literal notranslate"><span class="pre">scope=...</span></code> flag is for manipulating and +utilizing the scope stack.</p> +<p>If <code class="docutils literal notranslate"><span class="pre">{scope=push}</span></code> is specified, a tag captured with +<code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> is pushed to the stack. <code class="docutils literal notranslate"><span class="pre">{scope=push}</span></code> +implies <code class="docutils literal notranslate"><span class="pre">{scope=ref}</span></code>.</p> +<p>You can fill the scope field of captured tag with +<code class="docutils literal notranslate"><span class="pre">{scope=ref}</span></code>. If <code class="docutils literal notranslate"><span class="pre">{scope=ref}</span></code> flag is given, +ctags attaches the tag at the top to the tag +captured with <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> as the value for the <code class="docutils literal notranslate"><span class="pre">scope:</span></code> +field.</p> +<p>ctags pops the tag at the top of the stack when +<code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> with <code class="docutils literal notranslate"><span class="pre">{scope=pop}</span></code> is matched to the input +line.</p> +<p>Specifying <code class="docutils literal notranslate"><span class="pre">{scope=clear}</span></code> removes all the tags in the scope. +Specifying <code class="docutils literal notranslate"><span class="pre">{scope=set}</span></code> removes all the tags in the scope, and +then pushes the captured tag as <code class="docutils literal notranslate"><span class="pre">{scope=push}</span></code> does.</p> +<p>In some cases, you may want to use <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> only for its +side effects: using it only to manipulate the stack but not for +capturing a tag. In such a case, make <em><name_pattern></em> component of +<code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> option empty while specifying <code class="docutils literal notranslate"><span class="pre">{placeholder}</span></code> +as a regex flag. For example, a non-named tag can be put on +the stack by giving a regex flag “<code class="docutils literal notranslate"><span class="pre">{scope=push}{placeholder}</span></code>”.</p> +<p>You may wonder what happens if a regex pattern with +<code class="docutils literal notranslate"><span class="pre">{scope=ref}</span></code> flag matches an input line but the stack is empty, +or a non-named tag is at the top. If the regex pattern contains a +<code class="docutils literal notranslate"><span class="pre">{scope=ref}</span></code> flag and the stack is empty, the <code class="docutils literal notranslate"><span class="pre">{scope=ref}</span></code> +flag is ignored and nothing is attached to the <code class="docutils literal notranslate"><span class="pre">scope:</span></code> field.</p> +<p>If the top of the stack contains an unnamed tag, +ctags searches deeper into the stack to find the +top-most named tag. If it reaches the bottom of the stack without +finding a named tag, the <code class="docutils literal notranslate"><span class="pre">{scope=ref}</span></code> flag is ignored and +nothing is attached to the <code class="docutils literal notranslate"><span class="pre">scope:</span></code> field.</p> +<p>When a named tag on the stack is popped or cleared as the side +effect of a pattern matching, ctags attaches the +line number of the match to the <code class="docutils literal notranslate"><span class="pre">end:</span></code> field of +the named tag.</p> +<p>ctags clears all of the tags on the stack when it +reaches the end of the input source file. The line number of the +end is attached to the <code class="docutils literal notranslate"><span class="pre">end:</span></code> field of the cleared tags.</p> +</div></blockquote> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">warning=<message></span></code></dt><dd><p>print the given <em><message></em> at WARNING level</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">fatal=<message></span></code></dt><dd><p>print the given <em><message></em> and exit</p> +</dd> +</dl> +</section> +</section> +<section id="examples"> +<h2>EXAMPLES<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2> +<section id="perl-pod"> +<h3>Perl Pod<a class="headerlink" href="#perl-pod" title="Permalink to this headline">¶</a></h3> +<p>This is the definition (pod.ctags) used in ctags for parsing Pod +(<a class="reference external" href="https://perldoc.perl.org/perlpod.html">https://perldoc.perl.org/perlpod.html</a>) file.</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kn">--langdef</span><span class="p">=</span><span class="nn">pod</span> +<span class="kd">--map-</span><span class="nn">pod</span><span class="p">=+</span>.pod + +<span class="kd">--kinddef-</span><span class="nn">pod</span><span class="p">=</span><span class="ni">c</span><span class="p">,</span><span class="ni">chapter</span><span class="p">,</span><span class="sd">chapters</span> +<span class="kd">--kinddef-</span><span class="nn">pod</span><span class="p">=</span><span class="ni">s</span><span class="p">,</span><span class="ni">section</span><span class="p">,</span><span class="sd">sections</span> +<span class="kd">--kinddef-</span><span class="nn">pod</span><span class="p">=</span><span class="ni">S</span><span class="p">,</span><span class="ni">subsection</span><span class="p">,</span><span class="sd">subsections</span> +<span class="kd">--kinddef-</span><span class="nn">pod</span><span class="p">=</span><span class="ni">t</span><span class="p">,</span><span class="ni">subsubsection</span><span class="p">,</span><span class="sd">subsubsections</span> + +<span class="kd">--regex-</span><span class="nn">pod</span><span class="p">=</span>/^=head1[ \t]+(.+)/\1/c/ +<span class="kd">--regex-</span><span class="nn">pod</span><span class="p">=</span>/^=head2[ \t]+(.+)/\1/s/ +<span class="kd">--regex-</span><span class="nn">pod</span><span class="p">=</span>/^=head3[ \t]+(.+)/\1/S/ +<span class="kd">--regex-</span><span class="nn">pod</span><span class="p">=</span>/^=head4[ \t]+(.+)/\1/t/ +</pre></div> +</div> +</section> +<section id="using-scope-regex-flags"> +<h3>Using scope regex flags<a class="headerlink" href="#using-scope-regex-flags" title="Permalink to this headline">¶</a></h3> +<p>Let’s think about writing a parser for a very small subset of the Ruby +language.</p> +<p>input source file (<code class="docutils literal notranslate"><span class="pre">input.srb</span></code>):</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Example</span> + <span class="k">def</span> <span class="nf">methodA</span> + <span class="n">puts</span> <span class="s2">"in class_method"</span> + <span class="n">end</span> + <span class="k">def</span> <span class="nf">methodB</span> + <span class="n">puts</span> <span class="s2">"in class_method"</span> + <span class="n">end</span> +<span class="n">end</span> +</pre></div> +</div> +<p>The parser for the input should capture <code class="docutils literal notranslate"><span class="pre">Example</span></code> with <code class="docutils literal notranslate"><span class="pre">class</span></code> kind, +<code class="docutils literal notranslate"><span class="pre">methodA</span></code>, and <code class="docutils literal notranslate"><span class="pre">methodB</span></code> with <code class="docutils literal notranslate"><span class="pre">method</span></code> kind. <code class="docutils literal notranslate"><span class="pre">methodA</span></code> and <code class="docutils literal notranslate"><span class="pre">methodB</span></code> +should have <code class="docutils literal notranslate"><span class="pre">Example</span></code> as their scope. <code class="docutils literal notranslate"><span class="pre">end:</span></code> fields of each tag +should have proper values.</p> +<p>optlib file (<code class="docutils literal notranslate"><span class="pre">sub-ruby.ctags</span></code>):</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kn">--langdef</span><span class="p">=</span><span class="nn">subRuby</span> +<span class="kd">--map-</span><span class="nn">subRuby</span><span class="p">=</span>.srb +<span class="kd">--kinddef-</span><span class="nn">subRuby</span><span class="p">=</span><span class="ni">c</span><span class="p">,</span><span class="ni">class</span><span class="p">,</span><span class="sd">classes</span> +<span class="kd">--kinddef-</span><span class="nn">subRuby</span><span class="p">=</span><span class="ni">m</span><span class="p">,</span><span class="ni">method</span><span class="p">,</span><span class="sd">methods</span> +<span class="kd">--regex-</span><span class="nn">subRuby</span><span class="p">=</span>/^class[ \t]+([a-zA-Z][a-zA-Z0-9]+)/\1/c/{scope=push} +<span class="kd">--regex-</span><span class="nn">subRuby</span><span class="p">=</span>/^end///{scope=pop}{placeholder} +<span class="kd">--regex-</span><span class="nn">subRuby</span><span class="p">=</span>/^[ \t]+def[ \t]+([a-zA-Z][a-zA-Z0-9_]+)/\1/m/{scope=push} +<span class="kd">--regex-</span><span class="nn">subRuby</span><span class="p">=</span>/^[ \t]+end///{scope=pop}{placeholder} +</pre></div> +</div> +<p>command line and output:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --quiet --fields=+eK \ +--options=./sub-ruby.ctags -o - input.srb +Example input.srb /^class Example$/;" class end:8 +methodA input.srb /^ def methodA$/;" method class:Example end:4 +methodB input.srb /^ def methodB$/;" method class:Example end:7 +</pre></div> +</div> +</section> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p>The official Universal Ctags web site at:</p> +<p><a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<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="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>, regex(3), regex(7), egrep(1)</p> +</section> +<section id="author"> +<h2>AUTHOR<a class="headerlink" href="#author" title="Permalink to this headline">¶</a></h2> +<p>Universal Ctags project +<a class="reference external" href="https://ctags.io/">https://ctags.io/</a> +(This man page partially derived from <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> of +Executable-ctags)</p> +<p>Darren Hiebert <<a class="reference external" href="mailto:dhiebert%40users.sourceforge.net">dhiebert<span>@</span>users<span>.</span>sourceforge<span>.</span>net</a>> +<a class="reference external" href="http://DarrenHiebert.com/">http://DarrenHiebert.com/</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-optlib</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a><ul> +<li><a class="reference internal" href="#storing-a-parser-definition-to-a-file">Storing a parser definition to a file</a></li> +<li><a class="reference internal" href="#overview-for-defining-a-parser">Overview for defining a parser</a></li> +</ul> +</li> +<li><a class="reference internal" href="#options">OPTIONS</a><ul> +<li><a class="reference internal" href="#flags-for-regex-lang-option">FLAGS FOR <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> OPTION</a></li> +</ul> +</li> +<li><a class="reference internal" href="#examples">EXAMPLES</a><ul> +<li><a class="reference internal" href="#perl-pod">Perl Pod</a></li> +<li><a class="reference internal" href="#using-scope-regex-flags">Using scope regex flags</a></li> +</ul> +</li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +<li><a class="reference internal" href="#author">AUTHOR</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="tags.5.html" + title="previous chapter">tags</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-client-tools.7.html" + title="next chapter">ctags-client-tools</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-client-tools.7.html" title="ctags-client-tools" + >next</a> |</li> + <li class="right" > + <a href="tags.5.html" title="tags" + >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-optlib</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 diff --git a/ctags/docs/man/ctags.1.html b/ctags/docs/man/ctags.1.html new file mode 100644 index 0000000..18730d5 --- /dev/null +++ b/ctags/docs/man/ctags.1.html @@ -0,0 +1,1989 @@ + +<!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 — 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="tags" href="tags.5.html" /> + <link rel="prev" title="Man pages" href="../man-pages.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="tags.5.html" title="tags" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="../man-pages.html" title="Man pages" + 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</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags"> +<span id="ctags-1"></span><h1>ctags<a class="headerlink" href="#ctags" title="Permalink to this headline">¶</a></h1> +<p>Generate tag files for source code</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>1</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>] [<source_file(s)>]</div> +<div class="line"><strong>etags</strong> [<options>] [<source_file(s)>]</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>The <em>ctags</em> and <em>etags</em> (see <code class="docutils literal notranslate"><span class="pre">-e</span></code> option) programs +(hereinafter collectively referred to as ctags, +except where distinguished) generate an index (or “tag”) file for a +variety of <em>language objects</em> found in <em>source file(s)</em>. This tag file allows +these items to be quickly and easily located by a text editor or other +utilities (<em>client tools</em>). A <em>tag</em> signifies a language object for which an index entry is +available (or, alternatively, the index entry created for that object).</p> +<p>Alternatively, ctags can generate a cross reference +file which lists, in human readable form, information about the various +language objects found in a set of source files.</p> +<p>Tag index files are supported by numerous editors, which allow the user to +locate the object associated with a name appearing in a source file and +jump to the file and line which defines the name. See the manual of your +favorite editor about utilizing ctags command and +the tag index files in the editor.</p> +<p>ctags is capable of generating different <em>kinds</em> of tags +for each of many different <em>languages</em>. For a complete list of supported +languages, the names by which they are recognized, and the kinds of tags +which are generated for each, see the <code class="docutils literal notranslate"><span class="pre">--list-languages</span></code> and <code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code> +options.</p> +<p>This man page describes <em>Universal Ctags</em>, an implementation of ctags +derived from <em>Exuberant Ctags</em>. The major incompatible changes between +Universal Ctags and Exuberant Ctags are enumerated in +<a class="reference internal" href="ctags-incompatibilities.7.html#ctags-incompatibilities-7"><span class="std std-ref">ctags-incompatibilities(7)</span></a>.</p> +<p>One of the advantages of Exuberant Ctags is that it allows a user to +define a new parser from the command line. Extending this capability is one +of the major features of Universal Ctags. <a class="reference internal" href="ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a> +describes how the capability is extended.</p> +<p>Newly introduced experimental features are not explained here. If you +are interested in such features and ctags internals, +visit <a class="reference external" href="https://docs.ctags.io/">https://docs.ctags.io/</a>.</p> +</section> +<section id="command-line-interface"> +<h2>COMMAND LINE INTERFACE<a class="headerlink" href="#command-line-interface" title="Permalink to this headline">¶</a></h2> +<p>Despite the wealth of available options, defaults are set so that +ctags is most commonly executed without any options (e.g. +“<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">*</span></code>”, or “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">-R</span></code>”), which will +create a tag file in the current directory for all recognized source +files. The options described below are provided merely to allow custom +tailoring to meet special needs.</p> +<p>Note that spaces separating the single-letter options from their parameters +are optional.</p> +<p>Note also that the boolean parameters to the long form options (those +beginning with <code class="docutils literal notranslate"><span class="pre">--</span></code> and that take a <code class="docutils literal notranslate"><span class="pre">[=(yes|no)]</span></code> parameter) may be omitted, +in which case <code class="docutils literal notranslate"><span class="pre">=yes</span></code> is implied. (e.g. <code class="docutils literal notranslate"><span class="pre">--sort</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">--sort=yes</span></code>). +Note further that <code class="docutils literal notranslate"><span class="pre">=1</span></code>, <code class="docutils literal notranslate"><span class="pre">=on</span></code>, and <code class="docutils literal notranslate"><span class="pre">=true</span></code> are considered synonyms for <code class="docutils literal notranslate"><span class="pre">=yes</span></code>, +and that <code class="docutils literal notranslate"><span class="pre">=0</span></code>, <code class="docutils literal notranslate"><span class="pre">=off</span></code>, and <code class="docutils literal notranslate"><span class="pre">=false</span></code> are considered synonyms for <code class="docutils literal notranslate"><span class="pre">=no</span></code>.</p> +<p>Some options are either ignored or useful only when used while running in +etags mode (see <code class="docutils literal notranslate"><span class="pre">-e</span></code> option). Such options will be noted.</p> +<p><em><options></em> must precede the <em><source_file(s)></em> following the standard POSIX +convention.</p> +<p>Options taking language names will accept those names in either upper or +lower case. See the <code class="docutils literal notranslate"><span class="pre">--list-languages</span></code> option for a complete list of the +built-in language names.</p> +<section id="letters-and-names"> +<h3>Letters and names<a class="headerlink" href="#letters-and-names" title="Permalink to this headline">¶</a></h3> +<p>Some options take one-letter flags as parameters (e.g. <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code> option). +Specifying just letters help a user create a complicated command line +quickly. However, a command line including sequences of one-letter flags +becomes difficult to understand.</p> +<p>Universal Ctags accepts long-name flags in +addition to such one-letter flags. The long-name and one-letter flags can be mixed in an +option parameter by surrounding each long-name by braces. Thus, for an +example, the following three notations for <code class="docutils literal notranslate"><span class="pre">--kinds-C</span></code> option have +the same meaning:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">kinds</span><span class="o">-</span><span class="n">C</span><span class="o">=+</span><span class="n">pLl</span> +<span class="o">--</span><span class="n">kinds</span><span class="o">-</span><span class="n">C</span><span class="o">=+</span><span class="p">{</span><span class="n">prototype</span><span class="p">}{</span><span class="n">label</span><span class="p">}{</span><span class="n">local</span><span class="p">}</span> +<span class="o">--</span><span class="n">kinds</span><span class="o">-</span><span class="n">C</span><span class="o">=+</span><span class="p">{</span><span class="n">prototype</span><span class="p">}</span><span class="n">L</span><span class="p">{</span><span class="n">local</span><span class="p">}</span> +</pre></div> +</div> +<p>Note that braces may be meta characters in your shell. Put +single quotes in such case.</p> +<p><code class="docutils literal notranslate"><span class="pre">--list-...</span></code> options shows one-letter flags and associated long-name flags.</p> +</section> +<section id="list-options"> +<h3>List options<a class="headerlink" href="#list-options" title="Permalink to this headline">¶</a></h3> +<p>Universal Ctags introduces many <code class="docutils literal notranslate"><span class="pre">--list-...</span></code> options that provide +the internal data of Universal Ctags (See “<a class="reference internal" href="#listing-options">Listing Options</a>”). Both users and client tools may +use the data. <code class="docutils literal notranslate"><span class="pre">--with-list-header</span></code> and <code class="docutils literal notranslate"><span class="pre">--machinable</span></code> options +adjust the output of the most of <code class="docutils literal notranslate"><span class="pre">--list-...</span></code> options.</p> +<p>The default setting (<code class="docutils literal notranslate"><span class="pre">--with-list-header=yes</span></code> and <code class="docutils literal notranslate"><span class="pre">--machinable=no</span></code>) +is for using interactively from a terminal. The header that explains +the meaning of columns is simply added to the output, and each column is +aligned in all lines. The header line starts with a hash (’<code class="docutils literal notranslate"><span class="pre">#</span></code>’) character.</p> +<p>For scripting in a client tool, <code class="docutils literal notranslate"><span class="pre">--with-list-header=no</span></code> and +<code class="docutils literal notranslate"><span class="pre">--machinable=yes</span></code> may be useful. The header is not added to the +output, and each column is separated by tab characters.</p> +<p>Note the order of columns will change in the future release. +However, labels in the header will not change. So by scanning +the header, a client tool can find the index for the target +column.</p> +</section> +</section> +<section id="options"> +<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2> +<p>ctags has more options than listed here. +Options starting with an underscore character, such as <code class="docutils literal notranslate"><span class="pre">--_echo=<msg></span></code>, +are not listed here. They are experimental or for debugging purpose.</p> +<p>Notation: <code class="docutils literal notranslate"><span class="pre"><foo></span></code> is for a variable string <code class="docutils literal notranslate"><span class="pre">foo</span></code>, <code class="docutils literal notranslate"><span class="pre">[</span> <span class="pre">...</span> <span class="pre">]</span></code> for optional, +<code class="docutils literal notranslate"><span class="pre">|</span></code> for selection, and <code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">...</span> <span class="pre">)</span></code> for grouping. For example +<code class="docutils literal notranslate"><span class="pre">--foo[=(yes|no)]''</span> <span class="pre">means</span> <span class="pre">``--foo</span></code>, <code class="docutils literal notranslate"><span class="pre">-foo=yes</span></code>, or <code class="docutils literal notranslate"><span class="pre">-foo=no</span></code>.</p> +<section id="input-output-file-options"> +<span id="option-input-output-file"></span><h3>Input/Output File Options<a class="headerlink" href="#input-output-file-options" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--exclude=<pattern></span></code></dt><dd><p>Add <em><pattern></em> to a list of excluded files and directories. This option may +be specified as many times as desired. For each file name considered +by ctags, each pattern specified using this option +will be compared against both the complete path (e.g. +<code class="docutils literal notranslate"><span class="pre">some/path/base.ext</span></code>) and the base name (e.g. <code class="docutils literal notranslate"><span class="pre">base.ext</span></code>) of the file, thus +allowing patterns which match a given file name irrespective of its +path, or match only a specific path.</p> +<p>If appropriate support is available +from the runtime library of your C compiler, then pattern may +contain the usual shell wildcards (not regular expressions) common on +Unix (be sure to quote the option parameter to protect the wildcards from +being expanded by the shell before being passed to ctags; +also be aware that wildcards can match the slash character, ‘<code class="docutils literal notranslate"><span class="pre">/</span></code>’). +You can determine if shell wildcards are available on your platform by +examining the output of the <code class="docutils literal notranslate"><span class="pre">--list-features</span></code> option, which will include +<code class="docutils literal notranslate"><span class="pre">wildcards</span></code> in the compiled feature list; otherwise, pattern is matched +against file names using a simple textual comparison.</p> +<p>If <em><pattern></em> begins with the character ‘<code class="docutils literal notranslate"><span class="pre">@</span></code>’, then the rest of the string +is interpreted as a file name from which to read exclusion patterns, +one per line. If pattern is empty, the list of excluded patterns is +cleared.</p> +<p>Note that at program startup, the default exclude list contains names of +common hidden and system files, patterns for binary files, and directories +for which it is generally not desirable to descend while processing the +<code class="docutils literal notranslate"><span class="pre">--recurse</span></code> option. To see the list of built-in exclude patterns, use +<code class="docutils literal notranslate"><span class="pre">--list-excludes</span></code>.</p> +<p>See also the description for <code class="docutils literal notranslate"><span class="pre">--exclude-exception=</span></code> option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--exclude-exception=<pattern></span></code></dt><dd><p>Add <em><pattern></em> to a list of included files and directories. The pattern +affects the files and directories that are excluded by the pattern +specified with <code class="docutils literal notranslate"><span class="pre">--exclude=</span></code> option.</p> +<p>For an example, you want ctags to ignore all files +under <code class="docutils literal notranslate"><span class="pre">foo</span></code> directory except <code class="docutils literal notranslate"><span class="pre">foo/main.c</span></code>, use the following command +line: <code class="docutils literal notranslate"><span class="pre">--exclude=foo/*</span> <span class="pre">--exclude-exception=foo/main.c</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--filter[=(yes|no)]</span></code></dt><dd><p>Makes ctags behave as a filter, reading source +file names from standard input and printing their tags to standard +output on a file-by-file basis. If <code class="docutils literal notranslate"><span class="pre">--sort</span></code> is enabled, tags are sorted +only within the source file in which they are defined. File names are +read from standard input in line-oriented input mode (see note for <code class="docutils literal notranslate"><span class="pre">-L</span></code> +option) and only after file names listed on the command line or from +any file supplied using the <code class="docutils literal notranslate"><span class="pre">-L</span></code> option. When this option is enabled, +the options <code class="docutils literal notranslate"><span class="pre">-f</span></code>, <code class="docutils literal notranslate"><span class="pre">-o</span></code>, and <code class="docutils literal notranslate"><span class="pre">--totals</span></code> are ignored. This option is quite +esoteric and is disabled by default.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--filter-terminator=<string></span></code></dt><dd><p>Specifies a <em><string></em> to print to standard output following the tags for +each file name parsed when the <code class="docutils literal notranslate"><span class="pre">--filter</span></code> option is enabled. This may +permit an application reading the output of ctags +to determine when the output for each file is finished.</p> +<p>Note that if the +file name read is a directory and <code class="docutils literal notranslate"><span class="pre">--recurse</span></code> is enabled, this string will +be printed only once at the end of all tags found for by descending +the directory. This string will always be separated from the last tag +line for the file by its terminating newline.</p> +<p>This option is quite esoteric and is empty by default.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--links[=(yes|no)]</span></code></dt><dd><p>Indicates whether symbolic links (if supported) should be followed. +When disabled, symbolic links are ignored. This option is on by default.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--maxdepth=<N></span></code></dt><dd><p>Limits the depth of directory recursion enabled with the <code class="docutils literal notranslate"><span class="pre">--recurse</span></code> +(<code class="docutils literal notranslate"><span class="pre">-R</span></code>) option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--recurse[=(yes|no)]</span></code></dt><dd><p>Recurse into directories encountered in the list of supplied files.</p> +<p>If the list of supplied files is empty and no file list is specified with +the <code class="docutils literal notranslate"><span class="pre">-L</span></code> option, then the current directory (i.e. ‘<code class="docutils literal notranslate"><span class="pre">.</span></code>’) is assumed. +Symbolic links are followed by default (See <code class="docutils literal notranslate"><span class="pre">--links</span></code> option). If you don’t like these behaviors, either +explicitly specify the files or pipe the output of <code class="docutils literal notranslate"><span class="pre">find(1)</span></code> into +“<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">-L</span> <span class="pre">-</span></code>” instead. See, also, the <code class="docutils literal notranslate"><span class="pre">--exclude</span></code> and +<code class="docutils literal notranslate"><span class="pre">--maxdepth</span></code> to limit recursion.</p> +<p>Note: This option is not supported on +all platforms at present. It is available if the output of the <code class="docutils literal notranslate"><span class="pre">--help</span></code> +option includes this option.</p> +</dd> +</dl> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">-R</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--recurse</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-L</span> <span class="pre"><file></span></code></dt><dd><p>Read from <em><file></em> a list of file names for which tags should be generated.</p> +<p>If file is specified as ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’, then file names are read from standard +input. File names read using this option are processed following file +names appearing on the command line. Options are also accepted in this +input. If this option is specified more than once, only the last will +apply.</p> +<p>Note: file is read in line-oriented mode, where a new line is +the only delimiter and non-trailing white space is considered significant, +in order that file names containing spaces may be supplied +(however, trailing white space is stripped from lines); this can affect +how options are parsed if included in the input.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--append[=(yes|no)]</span></code></dt><dd><p>Indicates whether tags generated from the specified files should be +appended to those already present in the tag file or should replace them. +This option is <code class="docutils literal notranslate"><span class="pre">no</span></code> by default.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-a</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--append</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-f</span> <span class="pre"><tagfile></span></code></dt><dd><p>Use the name specified by <em><tagfile></em> for the tag file (default is “<code class="docutils literal notranslate"><span class="pre">tags</span></code>”, +or “<code class="docutils literal notranslate"><span class="pre">TAGS</span></code>” when running in etags mode). If <em><tagfile></em> is specified as ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>‘, +then the tags are written to standard output instead.</p> +<p>ctags +will stubbornly refuse to take orders if tagfile exists and +its first line contains something other than a valid tags line. This +will save your neck if you mistakenly type “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">-f</span> +<span class="pre">*.c</span></code>”, which would otherwise overwrite your first C file with the tags +generated by the rest! It will also refuse to accept a multi-character +file name which begins with a ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ (dash) character, since this most +likely means that you left out the tag file name and this option tried to +grab the next option as the file name. If you really want to name your +output tag file <code class="docutils literal notranslate"><span class="pre">-ugly</span></code>, specify it as “<code class="docutils literal notranslate"><span class="pre">-f</span> <span class="pre">./-ugly</span></code>”.</p> +<p>This option must +appear before the first file name. If this option is specified more +than once, only the last will apply.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-o</span> <span class="pre"><tagfile></span></code></dt><dd><p>Equivalent to “<code class="docutils literal notranslate"><span class="pre">-f</span> <span class="pre">tagfile</span></code>”.</p> +</dd> +</dl> +</section> +<section id="output-format-options"> +<span id="option-output-format"></span><h3>Output Format Options<a class="headerlink" href="#output-format-options" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--format=(1|2)</span></code></dt><dd><p>Change the format of the output tag file. Currently the only valid +values for level are 1 or 2. Level 1 specifies the original tag file +format and level 2 specifies a new extended format containing extension +fields (but in a manner which retains backward-compatibility with +original <code class="docutils literal notranslate"><span class="pre">vi(1)</span></code> implementations). The default level is 2. +[Ignored in etags mode]</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--output-format=(u-ctags|e-ctags|etags|xref|json)</span></code></dt><dd><p>Specify the output format. The default is <code class="docutils literal notranslate"><span class="pre">u-ctags</span></code>. +See <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> for <code class="docutils literal notranslate"><span class="pre">u-ctags</span></code> and <code class="docutils literal notranslate"><span class="pre">e-ctags</span></code>. +See <code class="docutils literal notranslate"><span class="pre">-e</span></code> for <code class="docutils literal notranslate"><span class="pre">etags</span></code>, and <code class="docutils literal notranslate"><span class="pre">-x</span></code> for <code class="docutils literal notranslate"><span class="pre">xref</span></code>. +<code class="docutils literal notranslate"><span class="pre">json</span></code> format is available only if +the ctags executable is built with <code class="docutils literal notranslate"><span class="pre">libjansson</span></code>. +See <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> for more about <code class="docutils literal notranslate"><span class="pre">json</span></code> format.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-e</span></code></dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">--output-format=etags</span></code>. +Enable etags mode, which will create a tag file for use with the Emacs +editor. Alternatively, if ctags is invoked by a +name containing the string “etags” (either by renaming, +or creating a link to, the executable), etags mode will be enabled.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-x</span></code></dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">--output-format=xref</span></code>. +Print a tabular, human-readable cross reference (xref) file to standard +output instead of generating a tag file. The information contained in +the output includes: the tag name; the kind of tag; the line number, +file name, and source line (with extra white space condensed) of the +file which defines the tag. No tag file is written and all options +affecting tag file output will be ignored.</p> +<p>Example applications for this +feature are generating a listing of all functions located in a source +file (e.g. “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">-x</span> <span class="pre">--kinds-c=f</span> <span class="pre">file</span></code>”), or generating +a list of all externally visible global variables located in a source +file (e.g. “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">-x</span> <span class="pre">--kinds-c=v</span> <span class="pre">--extras=-F</span> <span class="pre">file</span></code>”).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--sort=(yes|no|foldcase)</span></code></dt><dd><p>Indicates whether the tag file should be sorted on the tag name +(default is <code class="docutils literal notranslate"><span class="pre">yes</span></code>). Note that the original <code class="docutils literal notranslate"><span class="pre">vi(1)</span></code> required sorted tags. +The <code class="docutils literal notranslate"><span class="pre">foldcase</span></code> value specifies case insensitive (or case-folded) sorting. +Fast binary searches of tag files sorted with case-folding will require +special support from tools using tag files, such as that found in the +ctags readtags library, or Vim version 6.2 or higher +(using “<code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">ignorecase</span></code>”). +[Ignored in etags mode]</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-u</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--sort=no</span></code> (i.e. “unsorted”).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--etags-include=<file></span></code></dt><dd><p>Include a reference to <em><file></em> in the tag file. This option may be specified +as many times as desired. This supports Emacs’ capability to use a +tag file which <em>includes</em> other tag files. [Available only in etags mode]</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--input-encoding=<encoding></span></code></dt><dd><p>Specifies the <em><encoding></em> of the input files. +If this option is specified, Universal Ctags converts the input from this +encoding to the encoding specified by <code class="docutils literal notranslate"><span class="pre">--output-encoding=encoding</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--input-encoding-<LANG>=<encoding></span></code></dt><dd><p>Specifies a specific input <em><encoding></em> for <em><LANG></em>. It overrides the global +default value given with <code class="docutils literal notranslate"><span class="pre">--input-encoding</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--output-encoding=<encoding></span></code></dt><dd><p>Specifies the <em><encoding></em> of the tags file. +Universal Ctags converts the encoding of input files from the encoding +specified by <code class="docutils literal notranslate"><span class="pre">--input-encoding=<encoding></span></code> to this encoding.</p> +<p>In addition <em><encoding></em> is specified at the top the tags file as the +value for the <code class="docutils literal notranslate"><span class="pre">TAG_FILE_ENCODING</span></code> pseudo-tag. The default value of +<em><encoding></em> is <code class="docutils literal notranslate"><span class="pre">UTF-8</span></code>.</p> +</dd> +</dl> +</section> +<section id="language-selection-and-mapping-options"> +<span id="option-lang-mapping"></span><h3>Language Selection and Mapping Options<a class="headerlink" href="#language-selection-and-mapping-options" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--language-force=(<language>|auto)</span></code></dt><dd><p>By default, ctags automatically selects the language +of a source file, ignoring those files whose language cannot be +determined (see “<a class="reference internal" href="#determining-file-language">Determining file language</a>”). This option forces the specified +<em>language</em> (case-insensitive; either built-in or user-defined) to be used +for every supplied file instead of automatically selecting the language +based upon its extension.</p> +<p>In addition, the special value <code class="docutils literal notranslate"><span class="pre">auto</span></code> indicates +that the language should be automatically selected (which effectively +disables this option).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--languages=[+|-](<list>|all)</span></code></dt><dd><p>Specifies the languages for which tag generation is enabled, with <em><list></em> +containing a comma-separated list of language names (case-insensitive; +either built-in or user-defined).</p> +<p>If the first language of <em><list></em> is not +preceded by either a ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ or ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’, the current list (the current settings +of enabled/disabled languages managed in ctags internally) +will be cleared before adding or removing the languages in <em><list></em>. Until a ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ is +encountered, each language in the <em><list></em> will be added to the current list.</p> +<p>As either the ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ or ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ is encountered in the <em><list></em>, the languages +following it are added or removed from the current list, respectively. +Thus, it becomes simple to replace the current list with a new one, or +to add or remove languages from the current list.</p> +<p>The actual list of +files for which tags will be generated depends upon the language +extension mapping in effect (see the <code class="docutils literal notranslate"><span class="pre">--langmap</span></code> option). Note that the most of +languages, including user-defined languages, are enabled unless explicitly +disabled using this option. Language names included in list may be any +built-in language or one previously defined with <code class="docutils literal notranslate"><span class="pre">--langdef</span></code>.</p> +<p>The default +is <code class="docutils literal notranslate"><span class="pre">all</span></code>, which is also accepted as a valid argument. See the +<code class="docutils literal notranslate"><span class="pre">--list-languages</span></code> option for a list of the all (built-in and user-defined) +language names.</p> +<p>Note <code class="docutils literal notranslate"><span class="pre">--languages=</span></code> option works cumulative way; the option can be +specified with different arguments multiple times in a command line.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--alias-<LANG>=[+|-](<pattern>|default)</span></code></dt><dd><p>Adds (’<code class="docutils literal notranslate"><span class="pre">+</span></code>’) or removes (’<code class="docutils literal notranslate"><span class="pre">-</span></code>’) an alias <em><pattern></em> to a language specified +with <em><LANG></em>. ctags refers to the alias pattern in +“<a class="reference internal" href="#determining-file-language">Determining file language</a>” stage.</p> +<p>The parameter <em><pattern></em> is not a list. Use this option multiple +times in a command line to add or remove multiple alias +patterns.</p> +<p>To restore the default language aliases, specify <code class="docutils literal notranslate"><span class="pre">default</span></code>.</p> +<p>Using <code class="docutils literal notranslate"><span class="pre">all</span></code> for <em><LANG></em> has meaning in following two cases:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">--alias-all=</span></code></dt><dd><p>This clears aliases setting of all languages.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--alias-all=default</span></code></dt><dd><p>This restores the default languages aliases for all languages.</p> +</dd> +</dl> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--guess-language-eagerly</span></code></dt><dd><p>Looks into the file contents for heuristically guessing the proper language parser. +See “<a class="reference internal" href="#determining-file-language">Determining file language</a>”.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-G</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--guess-language-eagerly</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--langmap=<map>[,<map>[...]]</span></code></dt><dd><p>Controls how file names are mapped to languages (see the <code class="docutils literal notranslate"><span class="pre">--list-maps</span></code> +option). Each comma-separated <em><map></em> consists of the language name (either +a built-in or user-defined language), a colon, and a list of <em>file +extensions</em> and/or <em>file name patterns</em>. A file extension is specified by +preceding the extension with a period (e.g. <code class="docutils literal notranslate"><span class="pre">.c</span></code>). A file name pattern +is specified by enclosing the pattern in parentheses (e.g. +<code class="docutils literal notranslate"><span class="pre">([Mm]akefile)</span></code>).</p> +<p>If appropriate support is available from the runtime +library of your C compiler, then the file name pattern may contain the usual +shell wildcards common on Unix (be sure to quote the option parameter to +protect the wildcards from being expanded by the shell before being +passed to ctags). You can determine if shell wildcards +are available on your platform by examining the output of the +<code class="docutils literal notranslate"><span class="pre">--list-features</span></code> option, which will include <code class="docutils literal notranslate"><span class="pre">wildcards</span></code> in the compiled +feature list; otherwise, the file name patterns are matched against +file names using a simple textual comparison.</p> +<p>When mapping a file extension with <code class="docutils literal notranslate"><span class="pre">--langmap</span></code> option, +it will first be unmapped from any other languages. (<code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code> +option provides more fine-grained control.)</p> +<p>If the first character in a <em><map></em> is a plus sign (’<code class="docutils literal notranslate"><span class="pre">+</span></code>’), then the extensions and +file name patterns in that map will be appended to the current map +for that language; otherwise, the map will replace the current map. +For example, to specify that only files with extensions of <code class="docutils literal notranslate"><span class="pre">.c</span></code> and <code class="docutils literal notranslate"><span class="pre">.x</span></code> are +to be treated as C language files, use <code class="docutils literal notranslate"><span class="pre">--langmap=c:.c.x</span></code>; to also add +files with extensions of <code class="docutils literal notranslate"><span class="pre">.j</span></code> as Java language files, specify +<code class="docutils literal notranslate"><span class="pre">--langmap=c:.c.x,java:+.j</span></code>. To map makefiles (e.g. files named either +<code class="docutils literal notranslate"><span class="pre">Makefile</span></code>, <code class="docutils literal notranslate"><span class="pre">makefile</span></code>, or having the extension <code class="docutils literal notranslate"><span class="pre">.mak</span></code>) to a language +called <code class="docutils literal notranslate"><span class="pre">make</span></code>, specify <code class="docutils literal notranslate"><span class="pre">--langmap=make:([Mm]akefile).mak</span></code>. To map files +having no extension, specify a period not followed by a non-period +character (e.g. ‘<code class="docutils literal notranslate"><span class="pre">.</span></code>’, <code class="docutils literal notranslate"><span class="pre">..x</span></code>, <code class="docutils literal notranslate"><span class="pre">.x.</span></code>).</p> +<p>To clear the mapping for a +particular language (thus inhibiting automatic generation of tags for +that language), specify an empty extension list (e.g. <code class="docutils literal notranslate"><span class="pre">--langmap=fortran:</span></code>). +To restore the default language mappings for a particular language, +supply the keyword <code class="docutils literal notranslate"><span class="pre">default</span></code> for the mapping. To specify restore the +default language mappings for all languages, specify <code class="docutils literal notranslate"><span class="pre">--langmap=default</span></code>.</p> +<p>Note that file name patterns are tested before file extensions when inferring +the language of a file. This order of Universal Ctags is different from +Exuberant Ctags. See <a class="reference internal" href="ctags-incompatibilities.7.html#ctags-incompatibilities-7"><span class="std std-ref">ctags-incompatibilities(7)</span></a> for the background of +this incompatible change.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--map-<LANG>=[+|-]<extension>|<pattern></span></code></dt><dd><p>This option provides the way to control mapping(s) of file names to +languages in a more fine-grained way than <code class="docutils literal notranslate"><span class="pre">--langmap</span></code> option.</p> +<p>In ctags, more than one language can map to a +file name <em><pattern></em> or file <em><extension></em> (<em>N:1 map</em>). Alternatively, +<code class="docutils literal notranslate"><span class="pre">--langmap</span></code> option handle only <em>1:1 map</em>, only one language +mapping to one file name <em><pattern></em> or file <em><extension></em>. A typical N:1 +map is seen in C++ and ObjectiveC language; both languages have +a map to <code class="docutils literal notranslate"><span class="pre">.h</span></code> as a file extension.</p> +<p>A file extension is specified by preceding the extension with a period (e.g. <code class="docutils literal notranslate"><span class="pre">.c</span></code>). +A file name pattern is specified by enclosing the pattern in parentheses (e.g. +<code class="docutils literal notranslate"><span class="pre">([Mm]akefile)</span></code>). A prefixed plus (’<code class="docutils literal notranslate"><span class="pre">+</span></code>’) sign is for adding, and +minus (’<code class="docutils literal notranslate"><span class="pre">-</span></code>’) is for removing. No prefix means replacing the map of <em><LANG></em>.</p> +<p>Unlike <code class="docutils literal notranslate"><span class="pre">--langmap</span></code>, <em><extension></em> (or <em><pattern></em>) is not a list. +<code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code> takes one extension (or pattern). However, +the option can be specified with different arguments multiple times +in a command line.</p> +</dd> +</dl> +</section> +<section id="tags-file-contents-options"> +<span id="option-tags-file-contents"></span><h3>Tags File Contents Options<a class="headerlink" href="#tags-file-contents-options" title="Permalink to this headline">¶</a></h3> +<p>See “<a class="reference internal" href="#id1">TAG ENTRIES</a>” about fields, kinds, roles, and extras.</p> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--excmd=(number|pattern|mix|combine)</span></code></dt><dd><p>Determines the type of <code class="docutils literal notranslate"><span class="pre">EX</span></code> command used to locate tags in the source +file. [Ignored in etags mode]</p> +<p>The valid values for type (either the entire word or the first letter +is accepted) are:</p> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">number</span></code></dt><dd><p>Use only line numbers in the tag file for locating tags. This has +four advantages:</p> +<ol class="arabic simple"> +<li><p>Significantly reduces the size of the resulting tag file.</p></li> +<li><p>Eliminates failures to find tags because the line defining the +tag has changed, causing the pattern match to fail (note that +some editors, such as <code class="docutils literal notranslate"><span class="pre">vim</span></code>, are able to recover in many such +instances).</p></li> +<li><p>Eliminates finding identical matching, but incorrect, source +lines (see “<a class="reference internal" href="#bugs">BUGS</a>”).</p></li> +<li><p>Retains separate entries in the tag file for lines which are +identical in content. In pattern mode, duplicate entries are +dropped because the search patterns they generate are identical, +making the duplicate entries useless.</p></li> +</ol> +<p>However, this option has one significant drawback: changes to the +source files can cause the line numbers recorded in the tag file +to no longer correspond to the lines in the source file, causing +jumps to some tags to miss the target definition by one or more +lines. Basically, this option is best used when the source code +to which it is applied is not subject to change. Selecting this +option type causes the following options to be ignored: <code class="docutils literal notranslate"><span class="pre">-B</span></code>, <code class="docutils literal notranslate"><span class="pre">-F</span></code>.</p> +<p><code class="docutils literal notranslate"><span class="pre">number</span></code> type is ignored in Xref and JSON output formats. Use +<code class="docutils literal notranslate"><span class="pre">--_xformat="...%n"</span></code> for Xref output format, or <code class="docutils literal notranslate"><span class="pre">--fields=+n-P</span></code> for +JSON output format.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">pattern</span></code></dt><dd><p>Use only search patterns for all tags, rather than the line numbers +usually used for macro definitions. This has the advantage of +not referencing obsolete line numbers when lines have been added or +removed since the tag file was generated.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">mixed</span></code></dt><dd><p>In this mode, patterns are generally used with a few exceptions. +For C, line numbers are used for macro definition tags. For Fortran, line numbers +are used for common blocks because their corresponding source lines +are generally identical, making pattern searches useless +for finding all matches.</p> +<p>This was the default format generated by the original ctags and is, +therefore, retained as the default for this option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">combine</span></code></dt><dd><p>Concatenate the line number and pattern with a semicolon in between.</p> +</dd> +</dl> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-n</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--excmd=number</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-N</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--excmd=pattern</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--extras=[+|-][<flags>|*]</span></code></dt><dd><p>Specifies whether to include extra tag entries for certain kinds of +information. See also “<a class="reference internal" href="#extras">Extras</a>” subsection to know what are extras.</p> +<p>The parameter <em><flags></em> is a set of one-letter flags (and/or long-name flags), each +representing one kind of extra tag entry to include in the tag file. +If flags is preceded by either the ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ or ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ character, the effect of +each flag is added to, or removed from, those currently enabled; +otherwise the flags replace any current settings. All entries are +included if ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ is given.</p> +<p>This <code class="docutils literal notranslate"><span class="pre">--extras=</span></code> option is for controlling extras common in all +languages (or language-independent extras). Universal Ctags also +supports language-specific extras. (See “<a class="reference internal" href="#language-specific-fields-and-extras">Language-specific fields and +extras</a>” about the concept). Use <code class="docutils literal notranslate"><span class="pre">--extras-<LANG>=</span></code> option for +controlling them.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--extras-(<LANG>|all)=[+|-][<flags>|*]</span></code></dt><dd><p>Specifies whether to include extra tag entries for certain kinds of +information for language <em><LANG></em>. Universal Ctags +introduces language-specific extras. See “<a class="reference internal" href="#language-specific-fields-and-extras">Language-specific fields and +extras</a>” about the concept. This option is for controlling them.</p> +<p>Specifies <code class="docutils literal notranslate"><span class="pre">all</span></code> as <em><LANG></em> to apply the parameter <em><flags></em> to all +languages; all extras are enabled with specifying ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ as the +parameter flags. If specifying nothing as the parameter flags +(<code class="docutils literal notranslate"><span class="pre">--extras-all=</span></code>), all extras are disabled. These two combinations +are useful for testing.</p> +<p>Check the output of the <code class="docutils literal notranslate"><span class="pre">--list-extras=<LANG></span></code> option for the +extras of specific language <em><LANG></em>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--fields=[+|-][<flags>|*]</span></code></dt><dd><p>Specifies which language-independent fields are to be included in the tag +entries. Language-independent fields are extension fields which are common +in all languages. See “<a class="reference internal" href="#tag-file-format">TAG FILE FORMAT</a>” section, and “<a class="reference internal" href="#extension-fields">Extension fields</a>” +subsection, for details of extension fields.</p> +<p>The parameter <em><flags></em> is a set of one-letter or long-name flags, +each representing one type of extension field to include. +Each flag or group of flags may be preceded by either ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ to add it +to the default set, or ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ to exclude it. In the absence of any +preceding ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ or ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ sign, only those fields explicitly listed in flags +will be included in the output (i.e. overriding the default set). All +fields are included if ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ is given.</p> +<p>This option is ignored if the +option <code class="docutils literal notranslate"><span class="pre">--format=1</span></code> (legacy tag file format) has been specified.</p> +<p>Use <code class="docutils literal notranslate"><span class="pre">--fields-<LANG>=</span></code> option for controlling language-specific fields.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--fields-(<LANG>|all)=[+|-][<flags>|*]</span></code></dt><dd><p>Specifies which language-specific fields are to be included in +the tag entries. Universal Ctags +supports language-specific fields. (See “<a class="reference internal" href="#language-specific-fields-and-extras">Language-specific fields and +extras</a>” about the concept).</p> +<p>Specify <code class="docutils literal notranslate"><span class="pre">all</span></code> as <em><LANG></em> to apply the parameter <em><flags></em> to all +languages; all fields are enabled with specifying ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ as the +parameter flags. If specifying nothing as the parameter <em><flags></em> +(i.e. <code class="docutils literal notranslate"><span class="pre">--fields-all=</span></code>), all fields are disabled. These two combinations +are useful for testing.</p> +<p>See the description of <code class="docutils literal notranslate"><span class="pre">--fields=[+|-][<flags>|*]</span></code> about <em><flags></em>.</p> +<p>Use <code class="docutils literal notranslate"><span class="pre">--fields=</span></code> option for controlling language-independent fields.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--kinds-(<LANG>|all)=[+|-](<kinds>|*)</span></code></dt><dd><p>Specifies a list of language-specific <em><kinds></em> of tags (or kinds) to +include in the output file for a particular language, where <em><LANG></em> is +case-insensitive and is one of the built-in language names (see the +<code class="docutils literal notranslate"><span class="pre">--list-languages</span></code> option for a complete list).</p> +<p>The parameter <em><kinds></em> is a group +of one-letter or long-name flags designating kinds of tags (particular to the language) +to either include or exclude from the output. The specific sets of +flags recognized for each language, their meanings and defaults may be +list using the <code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code> option.</p> +<p>Each letter or group of letters +may be preceded by either ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ to add it to, or ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ to remove it from, +the default set. In the absence of any preceding ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ or ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ sign, only +those kinds explicitly listed in kinds will be included in the output +(i.e. overriding the default for the specified language).</p> +<p>Specify ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ as the parameter to include all kinds implemented +in <em><LANG></em> in the output. Furthermore if <code class="docutils literal notranslate"><span class="pre">all</span></code> is given as <em><LANG></em>, +specification of the parameter <code class="docutils literal notranslate"><span class="pre">kinds</span></code> affects all languages defined +in ctags. Giving <code class="docutils literal notranslate"><span class="pre">all</span></code> makes sense only when ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ or +‘<code class="docutils literal notranslate"><span class="pre">F</span></code>’ is given as the parameter <code class="docutils literal notranslate"><span class="pre">kinds</span></code>.</p> +<p>As an example for the C language, in order to add prototypes and +external variable declarations to the default set of tag kinds, +but exclude macros, use <code class="docutils literal notranslate"><span class="pre">--kinds-c=+px-d</span></code>; to include only tags for +functions, use <code class="docutils literal notranslate"><span class="pre">--kinds-c=f</span></code>.</p> +<p>Some kinds of C and C++ languages are synchronized; enabling +(or disabling) a kind in one language enables the kind having +the same one-letter and long-name in the other language. See also the +description of <code class="docutils literal notranslate"><span class="pre">MASTER</span></code> column of <code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code>.</p> +</dd> +</dl> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--pattern-length-limit=<N></span></code></dt><dd><p>Truncate patterns of tag entries after <em><N></em> characters. Disable by setting to 0 +(default is 96).</p> +<p>An input source file with long lines and multiple tag matches per +line can generate an excessively large tags file with an +unconstrained pattern length. For example, running ctags on a +minified JavaScript source file often exhibits this behavior.</p> +<p>The truncation avoids cutting in the middle of a UTF-8 code point +spanning multiple bytes to prevent writing invalid byte sequences from +valid input files. This handling allows for an extra 3 bytes above the +configured limit in the worse case of a 4 byte code point starting +right before the limit. Please also note that this handling is fairly +naive and fast, and although it is resistant against any input, it +requires a valid input to work properly; it is not guaranteed to work +as the user expects when dealing with partially invalid UTF-8 input. +This also partially affect non-UTF-8 input, if the byte sequence at +the truncation length looks like a multibyte UTF-8 sequence. This +should however be rare, and in the worse case will lead to including +up to an extra 3 bytes above the limit.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--pseudo-tags=[+|-](<pseudo-tag>|*)</span></code></dt><dd><p>Enable/disable emitting pseudo-tag named <em><pseudo-tag></em>. +If ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ is given, enable/disable emitting all pseudo-tags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--put-field-prefix</span></code></dt><dd><p>Put <code class="docutils literal notranslate"><span class="pre">UCTAGS</span></code> as prefix for the name of fields newly introduced in +Universal Ctags.</p> +<p>Some fields are newly introduced in Universal Ctags and more will +be introduced in the future. Other tags generators may also +introduce their specific fields.</p> +<p>In such a situation, there is a concern about conflicting field +names; mixing tags files generated by multiple tags generators +including Universal Ctags is difficult. This option provides a +workaround for such station.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields<span class="o">=</span><span class="s1">'{line}{end}'</span> -o - hello.c +<span class="go">main hello.c /^main(int argc, char **argv)$/;" f line:3 end:6</span> +<span class="gp">$ </span>ctags --put-field-prefix --fields<span class="o">=</span><span class="s1">'{line}{end}'</span> -o - hello.c +<span class="go">main hello.c /^main(int argc, char **argv)$/;" f line:3 UCTAGSend:6</span> +</pre></div> +</div> +<p>In the above example, the prefix is put to <code class="docutils literal notranslate"><span class="pre">end</span></code> field which is +newly introduced in Universal Ctags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--roles-(<LANG>|all).(<kind>|all)=[+|-][<roles>|*]</span></code></dt><dd><p>Specifies a list of kind-specific roles of tags to include in the +output file for a particular language. +<em><kind></em> specifies the kind where the <em><roles></em> are defined. +<em><LANG></em> specifies the language where the kind is defined. +Each role in <em><roles></em> must be surrounded by braces (e.g. <code class="docutils literal notranslate"><span class="pre">{system}</span></code> +for a role named “system”).</p> +<p>Like <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code> option, ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ is for adding the role to the +list, and ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ is for removing from the list. ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ is for including +all roles of the kind to the list. The option with no argument +makes the list empty.</p> +<p>Both a one-letter flag or a long name flag surrounded by braces are +acceptable for specifying a kind (e.g. <code class="docutils literal notranslate"><span class="pre">--roles-C.h=+{system}{local}</span></code> +or <code class="docutils literal notranslate"><span class="pre">--roles-C.{header}=+{system}{local}</span></code>). ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ can be used for <em><KIND></em> +only for adding/removing all roles of all kinds in a language to/from +the list (e.g. <code class="docutils literal notranslate"><span class="pre">--roles-C.*=*</span></code> or <code class="docutils literal notranslate"><span class="pre">--roles-C.*=</span></code>).</p> +<p><code class="docutils literal notranslate"><span class="pre">all</span></code> can be used for <em><LANG></em> only for adding/removing all roles of +all kinds in all languages to/from the list +(e.g. <code class="docutils literal notranslate"><span class="pre">--roles-all.*=*</span></code> or <code class="docutils literal notranslate"><span class="pre">--roles-all.*=</span></code>).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--tag-relative=(yes|no|always|never)</span></code></dt><dd><p>Specifies how the file paths recorded in the tag file. +The default is <code class="docutils literal notranslate"><span class="pre">yes</span></code> when running in etags mode (see +the <code class="docutils literal notranslate"><span class="pre">-e</span></code> option), <code class="docutils literal notranslate"><span class="pre">no</span></code> otherwise.</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">yes</span></code></dt><dd><p>indicates that the file paths recorded in the tag file should be +<em>relative to the directory containing the tag file</em> +unless the files supplied on the command line +are specified with absolute paths.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">no</span></code></dt><dd><p>indicates that the file paths recorded in the tag file should be +<em>relative to the current directory</em> +unless the files supplied on the command line +are specified with absolute paths.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">always</span></code></dt><dd><p>indicates the recorded file paths should be relative +even if source file names are passed in with absolute paths.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">never</span></code></dt><dd><p>indicates the recorded file paths should be absolute +even if source file names are passed in with relative paths.</p> +</dd> +</dl> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--use-slash-as-filename-separator[=(yes|no)]</span></code></dt><dd><p>Uses slash (’<code class="docutils literal notranslate"><span class="pre">/</span></code>’) character as filename separators instead of backslash +(’<code class="docutils literal notranslate"><span class="pre">\</span></code>’) character when printing <code class="docutils literal notranslate"><span class="pre">input:</span></code> field. +The default is <code class="docutils literal notranslate"><span class="pre">yes</span></code> for the default “u-ctags” output format, and +<code class="docutils literal notranslate"><span class="pre">no</span></code> for the other formats.</p> +<p>This option is available on MS Windows only.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-B</span></code></dt><dd><p>Use backward searching patterns (e.g. <code class="docutils literal notranslate"><span class="pre">?pattern?</span></code>). [Ignored in etags mode]</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-F</span></code></dt><dd><p>Use forward searching patterns (e.g. <code class="docutils literal notranslate"><span class="pre">/pattern/</span></code>) (default). [Ignored +in etags mode]</p> +</dd> +</dl> +</section> +<section id="option-file-options"> +<h3>Option File Options<a class="headerlink" href="#option-file-options" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--options=<pathname></span></code></dt><dd><p>Read additional options from file or directory.</p> +<p>ctags searches <em><pathname></em> in the optlib path list +first. If ctags cannot find a file or directory +in the list, ctags reads a file or directory +at the specified <em><pathname></em>.</p> +<p>If a file is specified, it should contain one option per line. If +a directory is specified, files suffixed with <code class="docutils literal notranslate"><span class="pre">.ctags</span></code> under it +are read in alphabetical order.</p> +<p>As a special case, if <code class="docutils literal notranslate"><span class="pre">--options=NONE</span></code> is specified as the first +option on the command line, preloading is disabled; the option +will disable the automatic reading of any configuration options +from a file (see “<a class="reference internal" href="#files">FILES</a>”).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--options-maybe=<pathname></span></code></dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">--options</span></code> but doesn’t cause an error if file +(or directory) specified with <em><pathname></em> doesn’t exist.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--optlib-dir=[+]<directory></span></code></dt><dd><p>Add an optlib <em><directory></em> to or reset the optlib path list. +By default, the optlib path list is empty.</p> +</dd> +</dl> +</section> +<section id="optlib-options"> +<h3>optlib Options<a class="headerlink" href="#optlib-options" title="Permalink to this headline">¶</a></h3> +<p>See <a class="reference internal" href="ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a> for details of each option.</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></code></dt><dd><p>Define a kind for <em><LANG></em>. +Don’t be confused this with <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--langdef=<name></span></code></dt><dd><p>Defines a new user-defined language, <em><name></em>, to be parsed with regular +expressions.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code></dt><dd><p>Define multi-line regular expression for locating tags in specific language.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code></dt><dd><p>Define single-line regular expression for locating tags in specific language.</p> +</dd> +</dl> +</section> +<section id="language-specific-options"> +<span id="option-lang-specific"></span><h3>Language Specific Options<a class="headerlink" href="#language-specific-options" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--if0[=(yes|no)]</span></code></dt><dd><p>Indicates a preference as to whether code within an “<code class="docutils literal notranslate"><span class="pre">#if</span> <span class="pre">0</span></code>” branch of a +preprocessor conditional should be examined for non-macro tags (macro +tags are always included). Because the intent of this construct is to +disable code, the default value of this option is <code class="docutils literal notranslate"><span class="pre">no</span></code> (disabled).</p> +<p>Note that this +indicates a preference only and does not guarantee skipping code within +an “<code class="docutils literal notranslate"><span class="pre">#if</span> <span class="pre">0</span></code>” branch, since the fall-back algorithm used to generate +tags when preprocessor conditionals are too complex follows all branches +of a conditional.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--line-directives[=(yes|no)]</span></code></dt><dd><p>Specifies whether <code class="docutils literal notranslate"><span class="pre">#line</span></code> directives should be recognized. These are +present in the output of a preprocessor and contain the line number, and +possibly the file name, of the original source file(s) from which the +preprocessor output file was generated. This option is off by default.</p> +<p>When enabled, this option will +cause ctags to generate tag entries marked with the +file names and line numbers of their locations original source file(s), +instead of their actual locations in the preprocessor output. The actual +file names placed into the tag file will have the same leading path +components as the preprocessor output file, since it is assumed that +the original source files are located relative to the preprocessor +output file (unless, of course, the <code class="docutils literal notranslate"><span class="pre">#line</span></code> directive specifies an +absolute path).</p> +<p>Note: This option is generally +only useful when used together with the <code class="docutils literal notranslate"><span class="pre">--excmd=number</span></code> (<code class="docutils literal notranslate"><span class="pre">-n</span></code>) option. +Also, you may have to use either the <code class="docutils literal notranslate"><span class="pre">--langmap</span></code> or <code class="docutils literal notranslate"><span class="pre">--language-force</span></code> option +if the extension of the preprocessor output file is not known to +ctags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-D</span> <span class="pre"><macro>=<definition></span></code></dt><dd><p>Defines a C preprocessor <em><macro></em>. This emulates the behavior of the +corresponding gcc option. All types of macros are supported, +including the ones with parameters and variable arguments. +Stringification, token pasting and recursive macro expansion are also +supported. +This extends the function provided by <code class="docutils literal notranslate"><span class="pre">-I</span></code> option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-h</span> <span class="pre">(<list>|default)</span></code></dt><dd><p>Specifies a <em><list></em> of file extensions, separated by periods, which are +to be interpreted as include (or header) files. To indicate files having +no extension, use a period not followed by a non-period character +(e.g. ‘<code class="docutils literal notranslate"><span class="pre">.</span></code>’, <code class="docutils literal notranslate"><span class="pre">..x</span></code>, <code class="docutils literal notranslate"><span class="pre">.x.</span></code>).</p> +<p>This option only affects how the scoping of +particular kinds of tags are interpreted (i.e. whether or not they are +considered as globally visible or visible only within the file in which +they are defined); it does not map the extension to any particular +language. Any tag which is located in a non-include file and cannot be +seen (e.g. linked to) from another file is considered to have file-limited +(e.g. static) scope. No kind of tag appearing in an include file +will be considered to have file-limited scope.</p> +<p>If the first character in the list is ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’, then the extensions in the list will be +appended to the current list; otherwise, the list will replace the +current list. See, also, the <code class="docutils literal notranslate"><span class="pre">fileScope</span></code>/<code class="docutils literal notranslate"><span class="pre">F</span></code> flag of <code class="docutils literal notranslate"><span class="pre">--extras</span></code> option.</p> +<p>The default list is +<code class="docutils literal notranslate"><span class="pre">.h.H.hh.hpp.hxx.h++.inc.def</span></code>. To restore the default list, specify “<code class="docutils literal notranslate"><span class="pre">-h</span> +<span class="pre">default</span></code>”.</p> +<p>Note that if an extension supplied to this option is not +already mapped to a particular language (see “<a class="reference internal" href="#determining-file-language">Determining file language</a>”, above), +you will also need to use either the <code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code>, <code class="docutils literal notranslate"><span class="pre">--langmap</span></code> or +<code class="docutils literal notranslate"><span class="pre">--language-force</span></code> option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-I</span> <span class="pre"><identifier-list></span></code></dt><dd><p>Specifies a <em><identifier-list></em> of identifiers which are to be specially handled while +parsing C and C++ source files. This option is specifically provided +to handle special cases arising through the use of preprocessor macros. +When the identifiers listed are simple identifiers, these identifiers +will be ignored during parsing of the source files.</p> +<p>If an identifier is +suffixed with a ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ character (i.e. “<code class="docutils literal notranslate"><span class="pre">-I</span> <span class="pre">FOO+</span></code>”), ctags will also +ignore any parenthesis-enclosed argument list which may immediately +follow the identifier in the source files. See the example of “<code class="docutils literal notranslate"><span class="pre">-I</span> +<span class="pre">MODULE_VERSION+</span></code>” below.</p> +<p>If two identifiers are +separated with the ‘<code class="docutils literal notranslate"><span class="pre">=</span></code>’ character (i.e. <code class="docutils literal notranslate"><span class="pre">-I</span> <span class="pre">FOO=BAR</span></code>), the first identifiers is replaced by +the second identifiers for parsing purposes. The list of identifiers may +be supplied directly on the command line or read in from a separate file. +See the example of “<code class="docutils literal notranslate"><span class="pre">-I</span> <span class="pre">CLASS=class</span></code>” below.</p> +<p>If the first character of <em><identifier-list></em> is ‘<code class="docutils literal notranslate"><span class="pre">@</span></code>’, ‘<code class="docutils literal notranslate"><span class="pre">.</span></code>’ or a pathname +separator (’<code class="docutils literal notranslate"><span class="pre">/</span></code>’ or ‘<code class="docutils literal notranslate"><span class="pre">\</span></code>’), or the first two characters specify a drive +letter (e.g. <code class="docutils literal notranslate"><span class="pre">C:</span></code>), the parameter <em><identifier-list></em> will be interpreted as +a filename from which to read a list of identifiers, one per input line.</p> +<p>Otherwise, <em><identifier-list></em> is a list of identifiers (or identifier +pairs) to be specially handled, each delimited by either a comma or +by white space (in which case the list should be quoted to keep the +entire list as one command line argument).</p> +<p>Multiple <code class="docutils literal notranslate"><span class="pre">-I</span></code> options may be +supplied. To clear the list of ignore identifiers, supply a single +dash (’<code class="docutils literal notranslate"><span class="pre">-</span></code>’) for <em><identifier-list></em>.</p> +<p>This feature is useful when preprocessor macros are used in such a way +that they cause syntactic confusion due to their presence. Indeed, +this is the best way of working around a number of problems caused by +the presence of syntax-busting macros in source files (see “<a class="reference internal" href="#caveats">CAVEATS</a>”). +Some examples will illustrate this point.</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">foo</span> <span class="n">ARGDECL4</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="p">,</span> <span class="n">ptr</span><span class="p">,</span> <span class="kt">long</span> <span class="kt">int</span><span class="p">,</span> <span class="n">nbytes</span><span class="p">)</span> +</pre></div> +</div> +<p>In the above example, the macro <code class="docutils literal notranslate"><span class="pre">ARGDECL4</span></code> would be mistakenly +interpreted to be the name of the function instead of the correct name +of <code class="docutils literal notranslate"><span class="pre">foo</span></code>. Specifying “<code class="docutils literal notranslate"><span class="pre">-I</span> <span class="pre">ARGDECL4</span></code>” results in the correct behavior.</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="cm">/* creates an RCS version string in module */</span> +<span class="n">MODULE_VERSION</span><span class="p">(</span><span class="s">"$Revision$"</span><span class="p">)</span> +</pre></div> +</div> +<p>In the above example the macro invocation looks too much like a function +definition because it is not followed by a semicolon (indeed, it +could even be followed by a global variable definition that would look +much like a K&R style function parameter declaration). In fact, this +seeming function definition could possibly even cause the rest of the +file to be skipped over while trying to complete the definition. +Specifying “<code class="docutils literal notranslate"><span class="pre">-I</span> <span class="pre">MODULE_VERSION+</span></code>” would avoid such a problem.</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="n">CLASS</span> <span class="n">Example</span> <span class="p">{</span> + <span class="c1">// your content here</span> +<span class="p">};</span> +</pre></div> +</div> +<p>The example above uses <code class="docutils literal notranslate"><span class="pre">CLASS</span></code> as a preprocessor macro which expands to +something different for each platform. For instance <code class="docutils literal notranslate"><span class="pre">CLASS</span></code> may be +defined as <code class="docutils literal notranslate"><span class="pre">class</span> <span class="pre">__declspec(dllexport)</span></code> on Win32 platforms and simply +<code class="docutils literal notranslate"><span class="pre">class</span></code> on UNIX. Normally, the absence of the C++ keyword <code class="docutils literal notranslate"><span class="pre">class</span></code> +would cause the source file to be incorrectly parsed. Correct behavior +can be restored by specifying “<code class="docutils literal notranslate"><span class="pre">-I</span> <span class="pre">CLASS=class</span></code>”.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--param-<LANG>:<name>=<argument></span></code></dt><dd><p>Set a <em><LANG></em> specific parameter, a parameter specific to the <em><LANG></em>.</p> +<p>Available parameters can be listed with <code class="docutils literal notranslate"><span class="pre">--list-params</span></code>.</p> +</dd> +</dl> +</section> +<section id="listing-options"> +<span id="option-listing"></span><h3>Listing Options<a class="headerlink" href="#listing-options" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--list-aliases[=(<language>|all)]</span></code></dt><dd><p>Lists the aliases for either the specified <em><language></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> +languages, and then exits. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted. +The aliases are used when heuristically testing a language parser for a +source file.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-excludes</span></code></dt><dd><p>Lists the current exclusion patterns used to exclude files.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-extras[=(<language>|all)]</span></code></dt><dd><p>Lists the extras recognized for either the specified <em><language></em> or +<code class="docutils literal notranslate"><span class="pre">all</span></code> languages. See “<a class="reference internal" href="#extras">Extras</a>” subsection to know what are extras. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +<p>An extra can be enabled or disabled with <code class="docutils literal notranslate"><span class="pre">--extras=</span></code> for common +extras in all languages, or <code class="docutils literal notranslate"><span class="pre">--extras-<LANG>=</span></code> for the specified +language. These option takes one-letter flag or long-name flag as a parameter +for specifying an extra.</p> +<p>The meaning of columns in output are as follows:</p> +<dl class="simple"> +<dt>LETTER</dt><dd><p>One-letter flag. ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ means the extra does not have one-letter flag.</p> +</dd> +<dt>NAME</dt><dd><p>Long-name flag. The long-name is used in <code class="docutils literal notranslate"><span class="pre">extras</span></code> field.</p> +</dd> +<dt>ENABLED</dt><dd><p>Whether the extra is enabled or not. It takes <code class="docutils literal notranslate"><span class="pre">yes</span></code> or <code class="docutils literal notranslate"><span class="pre">no</span></code>.</p> +</dd> +<dt>LANGUAGE</dt><dd><p>The name of language if the extra is owned by a parser. +<code class="docutils literal notranslate"><span class="pre">NONE</span></code> means the extra is common in parsers.</p> +</dd> +<dt>DESCRIPTION</dt><dd><p>Human readable description for the extra.</p> +</dd> +</dl> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-features</span></code></dt><dd><p>Lists the compiled features.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-fields[=(<language>|all)]</span></code></dt><dd><p>Lists the fields recognized for either the specified <em><language></em> or +<code class="docutils literal notranslate"><span class="pre">all</span></code> languages. See “<a class="reference internal" href="#extension-fields">Extension fields</a>” subsection to know what are fields. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +<p>The meaning of columns are as follows:</p> +<dl> +<dt>LETTER</dt><dd><p>One-letter flag. ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ means the field does not have one-letter flag.</p> +</dd> +<dt>NAME</dt><dd><p>Long-name of field.</p> +</dd> +<dt>ENABLED</dt><dd><p>Whether the field is enabled or not. It takes <code class="docutils literal notranslate"><span class="pre">yes</span></code> or <code class="docutils literal notranslate"><span class="pre">no</span></code>.</p> +</dd> +<dt>LANGUAGE</dt><dd><p>The name of language if the field is owned by a parser. +<code class="docutils literal notranslate"><span class="pre">NONE</span></code> means that the field is a language-independent field which is +common in all languages.</p> +</dd> +<dt>JSTYPE</dt><dd><p>JSON type used in printing the value of field when <code class="docutils literal notranslate"><span class="pre">--output-format=json</span></code> +is specified. See <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a>.</p> +</dd> +<dt>FIXED</dt><dd><p>Whether this field can be disabled or not in tags output.</p> +<p>Some fields are printed always in tags output. +They have <code class="docutils literal notranslate"><span class="pre">yes</span></code> as the value for this column.</p> +<p>Unlike the tag output mode, JSON output mode allows disabling +any fields.</p> +</dd> +<dt>OP</dt><dd><p>How this field can be accessed from optscript code. +This field is for Universal Ctags developers.</p> +</dd> +<dt>DESCRIPTION</dt><dd><p>Human readable description for the field.</p> +</dd> +</dl> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-kinds[=(<language>|all)]</span></code></dt><dd><p>Subset of <code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code>. This option is kept for +backward-compatibility with Exuberant Ctags.</p> +<p>This option prints only LETTER, DESCRIPTION, and ENABLED fields +of <code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code> output. However, the presentation of +ENABLED column is different from that of <code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code> +option; <code class="docutils literal notranslate"><span class="pre">[off]</span></code> follows after description if the kind is disabled, +and nothing follows if enabled. The most of all kinds are enabled +by default.</p> +<p>The critical weakness of this option is that this option does not +print the name of kind. Universal Ctags introduces +<code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code> because it considers that names are +important.</p> +<p>This option does not work with <code class="docutils literal notranslate"><span class="pre">--machinable</span></code> nor +<code class="docutils literal notranslate"><span class="pre">--with-list-header</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-kinds-full[=(<language>|all)]</span></code></dt><dd><p>Lists the tag kinds recognized for either the specified <em><language></em> +or <code class="docutils literal notranslate"><span class="pre">all</span></code> languages, and then exits. See “<a class="reference internal" href="#kinds">Kinds</a>” subsection to +learn what kinds are. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +<p>Each kind of tag recorded in the tag file is represented by a +one-letter flag, or a long-name flag. They are also used to filter the tags +placed into the output through use of the <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code> +option.</p> +<p>The meaning of columns are as follows:</p> +<dl> +<dt>LANGUAGE</dt><dd><p>The name of language having the kind.</p> +</dd> +<dt>LETTER</dt><dd><p>One-letter flag. This must be unique in a language.</p> +</dd> +<dt>NAME</dt><dd><p>The long-name flag of the kind. This can be used as the alternative +to the one-letter flag described above. If enabling <code class="docutils literal notranslate"><span class="pre">K</span></code> field with +<code class="docutils literal notranslate"><span class="pre">--fields=+K</span></code>, ctags uses long-names instead of +one-letters in tags output. To enable/disable a kind with +<code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code> option, long-name surrounded by braces instead +of one-letter. See “<a class="reference internal" href="#letters-and-names">Letters and names</a>” for details. This must be +unique in a language.</p> +</dd> +<dt>ENABLED</dt><dd><p>Whether the kind is enabled or not. It takes <code class="docutils literal notranslate"><span class="pre">yes</span></code> or <code class="docutils literal notranslate"><span class="pre">no</span></code>.</p> +</dd> +<dt>REFONLY</dt><dd><p>Whether the kind is specialized for reference tagging or not. +If the column is <code class="docutils literal notranslate"><span class="pre">yes</span></code>, the kind is for reference tagging, and +it is never used for definition tagging. See also “<a class="reference internal" href="#id1">TAG ENTRIES</a>”.</p> +</dd> +<dt>NROLES</dt><dd><p>The number of roles this kind has. See also “<a class="reference internal" href="#roles">Roles</a>”.</p> +</dd> +<dt>MASTER</dt><dd><p>The master parser controlling enablement of the kind. +A kind belongs to a language (owner) in Universal Ctags; +enabling and disabling a kind in a language has no effect on +a kind in another language even if both kinds has the +same one-letter flag and/or the same long-name flag. In other words, +the namespace of kinds are separated by language.</p> +<p>However, Exuberant Ctags does not separate the kinds of C and +C++. Enabling/disabling kindX in C language enables/disables a +kind in C++ language having the same long-name flag with kindX. To +emulate this behavior in Universal Ctags, a concept named +<em>master parser</em> is introduced. Enabling/disabling some kinds +are synchronized under the control of a master language.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --kinds-C<span class="o">=</span>+<span class="s1">'{local}'</span> --list-kinds-full <span class="se">\</span> +<span class="go"> | grep -E '^(#|C\+\+ .* local)'</span> +<span class="gp">#</span>LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +<span class="go">C++ l local yes no 0 C local variables</span> +<span class="gp">$ </span>ctags --kinds-C<span class="o">=</span>-<span class="s1">'{local}'</span> --list-kinds-full <span class="se">\</span> +<span class="go"> | grep -E '^(#|C\+\+ .* local)'</span> +<span class="gp">#</span>LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +<span class="go">C++ l local no no 0 C local variables</span> +</pre></div> +</div> +<p>You see <code class="docutils literal notranslate"><span class="pre">ENABLED</span></code> field of <code class="docutils literal notranslate"><span class="pre">local</span></code> kind of C++ language is changed +Though <code class="docutils literal notranslate"><span class="pre">local</span></code> kind of C language is enabled/disabled. If you swap the languages, you +see the same result.</p> +</dd> +<dt>DESCRIPTION</dt><dd><p>Human readable description for the kind.</p> +</dd> +</dl> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-languages</span></code></dt><dd><p>Lists the names of the languages understood by ctags, +and then exits. These language names are case insensitive and may be +used in many other options like <code class="docutils literal notranslate"><span class="pre">--language-force</span></code>, +<code class="docutils literal notranslate"><span class="pre">--languages</span></code>, <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code>, <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code>, and so on.</p> +<p>Each language listed is disabled if followed by <code class="docutils literal notranslate"><span class="pre">[disabled]</span></code>. +To use the parser for such a language, specify the language as an +argument of <code class="docutils literal notranslate"><span class="pre">--languages=+</span></code> option.</p> +<p><code class="docutils literal notranslate"><span class="pre">--machinable</span></code> and <code class="docutils literal notranslate"><span class="pre">--with-list-header</span></code> options are ignored if they are +specified with this option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-map-extensions[=(<language>|all)]</span></code></dt><dd><p>Lists the file extensions which associate a file +name with a language for either the specified <em><language></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> +languages, and then exits. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-map-patterns[=(<language>|all)]</span></code></dt><dd><p>Lists the file name patterns which associate a file +name with a language for either the specified <em><language></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> +languages, and then exits. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-maps[=(<language>|all)]</span></code></dt><dd><p>Lists file name patterns and the file extensions which associate a file +name with a language for either the specified <em><language></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> +languages, and then exits. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +<p>To list the file extensions or file name patterns individually, use +<code class="docutils literal notranslate"><span class="pre">--list-map-extensions</span></code> or <code class="docutils literal notranslate"><span class="pre">--list-map-patterns</span></code> option. +See the <code class="docutils literal notranslate"><span class="pre">--langmap</span></code> option, and “<a class="reference internal" href="#determining-file-language">Determining file language</a>”, above.</p> +<p>This option does not work with <code class="docutils literal notranslate"><span class="pre">--machinable</span></code> nor +<code class="docutils literal notranslate"><span class="pre">--with-list-header</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-mline-regex-flags</span></code></dt><dd><p>Output list of flags which can be used in a multiline regex parser +definition. +See <a class="reference internal" href="ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-params[=(<language>|all)]</span></code></dt><dd><p>Lists the parameters for either the specified <em><language></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> +languages, and then exits. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code></dt><dd><p>Output list of pseudo-tags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-regex-flags</span></code></dt><dd><p>Lists the flags that can be used in <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> option. +See <a class="reference internal" href="ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-roles[=(<language>|all)[.(<kind-specs>|*)]]</span></code></dt><dd><p>List the roles for either the specified <em><language></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> languages. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +<p>If the parameter <em><kindspecs></em> is given after the parameter +<em><language></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> with concatenating with ‘<code class="docutils literal notranslate"><span class="pre">.</span></code>’, list only roles +defined in the kinds. Both one-letter flags and long name flags surrounded +by braces are acceptable as the parameter <em><kindspecs></em>.</p> +<p>The meaning of columns are as follows:</p> +<dl class="simple"> +<dt>LANGUAGE</dt><dd><p>The name of language having the role.</p> +</dd> +<dt>KIND(L/N)</dt><dd><p>The one-letter flag and the long-name flag of kind having the role.</p> +</dd> +<dt>NAME</dt><dd><p>The long-name flag of the role.</p> +</dd> +<dt>ENABLED</dt><dd><p>Whether the kind is enabled or not. It takes <code class="docutils literal notranslate"><span class="pre">yes</span></code> or <code class="docutils literal notranslate"><span class="pre">no</span></code>.</p> +</dd> +<dt>DESCRIPTION</dt><dd><p>Human readable description for the role.</p> +</dd> +</dl> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-subparsers[=(<baselang>|all)]</span></code></dt><dd><p>Lists the subparsers for a base language for either the specified +<em><baselang></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> languages, and then exits. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--machinable[=(yes|no)]</span></code></dt><dd><p>Use tab character as separators for <code class="docutils literal notranslate"><span class="pre">--list-</span></code> option output. It +may be suitable for scripting. See “<a class="reference internal" href="#list-options">List options</a>” for considered +use cases. Disabled by default.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--with-list-header[=(yes|no)]</span></code></dt><dd><p>Print headers describing columns in <code class="docutils literal notranslate"><span class="pre">--list-</span></code> option output. +See also “<a class="reference internal" href="#list-options">List options</a>”.</p> +</dd> +</dl> +</section> +<section id="miscellaneous-options"> +<span id="option-misc"></span><h3>Miscellaneous Options<a class="headerlink" href="#miscellaneous-options" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--help</span></code></dt><dd><p>Prints to standard output a detailed usage description, and then exits.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-?</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--help</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--help-full</span></code></dt><dd><p>Prints to standard output a detailed usage description including experimental +features, and then exits. Visit <a class="reference external" href="https://docs.ctags.io/">https://docs.ctags.io/</a> for information +about the latest exciting experimental features.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--license</span></code></dt><dd><p>Prints a summary of the software license to standard output, and then exits.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--print-language</span></code></dt><dd><p>Just prints the language parsers for specified source files, and then exits.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--quiet[=(yes|no)]</span></code></dt><dd><p>Write fewer messages (default is <code class="docutils literal notranslate"><span class="pre">no</span></code>).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--totals[=(yes|no|extra)]</span></code></dt><dd><p>Prints statistics about the source files read and the tag file written +during the current invocation of ctags. This option +is <code class="docutils literal notranslate"><span class="pre">no</span></code> by default.</p> +<p>The <code class="docutils literal notranslate"><span class="pre">extra</span></code> value prints parser specific statistics for parsers +gathering such information.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--verbose[=(yes|no)]</span></code></dt><dd><p>Enable verbose mode. This prints out information on option processing +and a brief message describing what action is being taken for each file +considered by ctags. Normally, ctags +does not read command line arguments until after options are read +from the configuration files (see “<a class="reference internal" href="#files">FILES</a>”, below). +However, if this option is the first argument on +the command line, it will take effect before any options are read from +these sources. The default is <code class="docutils literal notranslate"><span class="pre">no</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-V</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--verbose</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--version</span></code></dt><dd><p>Prints a version identifier for ctags to standard +output, and then exits. This is guaranteed to always contain the string +“Universal Ctags”.</p> +</dd> +</dl> +</section> +<section id="obsoleted-options"> +<h3>Obsoleted Options<a class="headerlink" href="#obsoleted-options" title="Permalink to this headline">¶</a></h3> +<p>These options are kept for backward-compatibility with Exuberant Ctags.</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">-w</span></code></dt><dd><p>This option is silently ignored for backward-compatibility with the +ctags of SVR4 Unix.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--file-scope[=(yes|no)]</span></code></dt><dd><p>This options is removed. Use <code class="docutils literal notranslate"><span class="pre">--extras=[+|-]F</span></code> or +<code class="docutils literal notranslate"><span class="pre">--extras=[+|-]{fileScope}</span></code> instead.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--extra=[+|-][<flags>|*]</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--extras=[+|-][<flags>|*]</span></code>, which was introduced to make +the option naming convention align to the other options like +<code class="docutils literal notranslate"><span class="pre">--kinds-<LANG>=</span></code> and <code class="docutils literal notranslate"><span class="pre">--fields=</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--<LANG>-kinds=[+|-](<kinds>|*)</span></code></dt><dd><p>This option is obsolete. Use <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG>=...</span></code> instead.</p> +</dd> +</dl> +</section> +</section> +<section id="operational-details"> +<h2>OPERATIONAL DETAILS<a class="headerlink" href="#operational-details" title="Permalink to this headline">¶</a></h2> +<p>As ctags considers each source file name in turn, it tries to +determine the language of the file by applying tests described in +“<a class="reference internal" href="#determining-file-language">Determining file language</a>”.</p> +<p>If a language was identified, the file is opened and then the appropriate +language parser is called to operate on the currently open file. The parser +parses through the file and adds an entry to the tag file for each +language object it is written to handle. See “<a class="reference internal" href="#tag-file-format">TAG FILE FORMAT</a>”, below, +for details on these entries.</p> +<section id="notes-for-c-c-parser"> +<h3>Notes for C/C++ Parser<a class="headerlink" href="#notes-for-c-c-parser" title="Permalink to this headline">¶</a></h3> +<p>This implementation of ctags imposes no formatting +requirements on C code as do legacy implementations. Older implementations +of ctags tended to rely upon certain formatting assumptions in order to +help it resolve coding dilemmas caused by preprocessor conditionals.</p> +<p>In general, ctags tries to be smart about conditional +preprocessor directives. If a preprocessor conditional is encountered +within a statement which defines a tag, ctags follows +only the first branch of that conditional (except in the special case of +<code class="docutils literal notranslate"><span class="pre">#if</span> <span class="pre">0</span></code>, in which case it follows only the last branch). The reason for +this is that failing to pursue only one branch can result in ambiguous +syntax, as in the following example:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="cp">#ifdef TWO_ALTERNATIVES</span> +<span class="k">struct</span> <span class="p">{</span> +<span class="cp">#else</span> +<span class="k">union</span> <span class="p">{</span> +<span class="cp">#endif</span> + <span class="kt">short</span> <span class="n">a</span><span class="p">;</span> + <span class="kt">long</span> <span class="n">b</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Both branches cannot be followed, or braces become unbalanced and +ctags would be unable to make sense of the syntax.</p> +<p>If the application of this heuristic fails to properly parse a file, +generally due to complicated and inconsistent pairing within the +conditionals, ctags will retry the file using a +different heuristic which does not selectively follow conditional +preprocessor branches, but instead falls back to relying upon a closing +brace (’<code class="docutils literal notranslate"><span class="pre">}</span></code>’) in column 1 as indicating the end of a block once any brace +imbalance results from following a <code class="docutils literal notranslate"><span class="pre">#if</span></code> conditional branch.</p> +<p>ctags will also try to specially handle arguments lists +enclosed in double sets of parentheses in order to accept the following +conditional construct:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">extern</span> <span class="n">void</span> <span class="n">foo</span> <span class="n">__ARGS</span><span class="p">((</span><span class="nb">int</span> <span class="n">one</span><span class="p">,</span> <span class="n">char</span> <span class="n">two</span><span class="p">));</span> +</pre></div> +</div> +<p>Any name immediately preceding the ‘<code class="docutils literal notranslate"><span class="pre">((</span></code>’ will be automatically ignored and +the previous name will be used.</p> +<p>C++ operator definitions are specially handled. In order for consistency +with all types of operators (overloaded and conversion), the operator +name in the tag file will always be preceded by the string “operator ” +(i.e. even if the actual operator definition was written as “operator<<”).</p> +<p>After creating or appending to the tag file, it is sorted by the tag name, +removing identical tag lines.</p> +</section> +<section id="determining-file-language"> +<span id="guessing"></span><h3>Determining file language<a class="headerlink" href="#determining-file-language" title="Permalink to this headline">¶</a></h3> +<section id="file-name-mapping"> +<h4>File name mapping<a class="headerlink" href="#file-name-mapping" title="Permalink to this headline">¶</a></h4> +<p>Unless the <code class="docutils literal notranslate"><span class="pre">--language-force</span></code> option is specified, the language of each source +file is automatically selected based upon a <em>mapping</em> of file names to +languages. The mappings in effect for each language may be displayed using +the <code class="docutils literal notranslate"><span class="pre">--list-maps</span></code> option and may be changed using the <code class="docutils literal notranslate"><span class="pre">--langmap</span></code> or +<code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code> options.</p> +<p>If the name of a file is not mapped to a language, ctags tries +to heuristically guess the language for the file by inspecting its content.</p> +<p>All files that have no file name mapping and no guessed parser are +ignored. This permits running ctags on all files in +either a single directory (e.g. “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">*</span></code>”), or on +all files in an entire source directory tree +(e.g. “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">-R</span></code>”), since only those files whose +names are mapped to languages will be scanned.</p> +<p>An extension may be mapped to multiple parsers. For example, <code class="docutils literal notranslate"><span class="pre">.h</span></code> +are mapped to C++, C and ObjectiveC. These mappings can cause +issues. ctags tries to select the proper parser +for the source file by applying heuristics to its content, however +it is not perfect. In case of issues one can use <code class="docutils literal notranslate"><span class="pre">--language-force=<language></span></code>, +<code class="docutils literal notranslate"><span class="pre">--langmap=<map>[,<map>[...]]</span></code>, or the <code class="docutils literal notranslate"><span class="pre">--map-<LANG>=[+|-]<extension>|<pattern></span></code> +options. (Some of the heuristics are applied whether <code class="docutils literal notranslate"><span class="pre">--guess-language-eagerly</span></code> +is given or not.)</p> +</section> +<section id="heuristically-guessing"> +<h4>Heuristically guessing<a class="headerlink" href="#heuristically-guessing" title="Permalink to this headline">¶</a></h4> +<p>If ctags cannot select a parser from the mapping of file names, +various heuristic tests are conducted to determine the language:</p> +<dl> +<dt>template file name testing</dt><dd><p>If the file name has an <code class="docutils literal notranslate"><span class="pre">.in</span></code> extension, ctags applies +the mapping to the file name without the extension. For example, +<code class="docutils literal notranslate"><span class="pre">config.h</span></code> is tested for a file named <code class="docutils literal notranslate"><span class="pre">config.h.in</span></code>.</p> +</dd> +<dt>“interpreter” testing</dt><dd><p>The first line of the file is checked to see if the file is a <code class="docutils literal notranslate"><span class="pre">#!</span></code> +script for a recognized language. ctags looks for +a parser having the same name.</p> +<p>If ctags finds no such parser, +ctags looks for the name in alias lists. For +example, consider if the first line is <code class="docutils literal notranslate"><span class="pre">#!/bin/sh</span></code>. Though +ctags has a “shell” parser, it doesn’t have a “sh” +parser. However, <code class="docutils literal notranslate"><span class="pre">sh</span></code> is listed as an alias for <code class="docutils literal notranslate"><span class="pre">shell</span></code>, therefore +ctags selects the “shell” parser for the file.</p> +<p>An exception is <code class="docutils literal notranslate"><span class="pre">env</span></code>. If <code class="docutils literal notranslate"><span class="pre">env</span></code> is specified (for example +“<code class="docutils literal notranslate"><span class="pre">#!/usr/bin/env</span> <span class="pre">python</span></code>”), ctags +reads more lines to find real interpreter specification.</p> +<p>To display the list of aliases, use <code class="docutils literal notranslate"><span class="pre">--list-aliases</span></code> option. +To add an item to the list or to remove an item from the list, use the +<code class="docutils literal notranslate"><span class="pre">--alias-<LANG>=+<pattern></span></code> or <code class="docutils literal notranslate"><span class="pre">--alias-<LANG>=-<pattern></span></code> option +respectively.</p> +</dd> +<dt>“zsh autoload tag” testing</dt><dd><p>If the first line starts with <code class="docutils literal notranslate"><span class="pre">#compdef</span></code> or <code class="docutils literal notranslate"><span class="pre">#autoload</span></code>, +ctags regards the line as “zsh”.</p> +</dd> +<dt>“emacs mode at the first line” testing</dt><dd><p>The Emacs editor has multiple editing modes specialized for programming +languages. Emacs can recognize a marker called modeline in a file +and utilize the marker for the mode selection. This heuristic test does +the same as what Emacs does.</p> +<p>ctags treats <code class="docutils literal notranslate"><span class="pre">MODE</span></code> as a name of interpreter and applies the same +rule of “interpreter” testing if the first line has one of +the following patterns:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-*-</span> <span class="n">mode</span><span class="p">:</span> <span class="n">MODE</span> <span class="o">-*-</span> +</pre></div> +</div> +<p>or</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-*-</span> <span class="n">MODE</span> <span class="o">-*-</span> +</pre></div> +</div> +</dd> +<dt>“emacs mode at the EOF” testing</dt><dd><p>Emacs editor recognizes another marker at the end of file as a +mode specifier. This heuristic test does the same as what Emacs does.</p> +<p>ctags treats <code class="docutils literal notranslate"><span class="pre">MODE</span></code> as a name of an interpreter and applies the same +rule of “interpreter” heuristic testing, if the lines at the tail of the file +have the following pattern:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Local</span> <span class="n">Variables</span><span class="p">:</span> +<span class="o">...</span> +<span class="n">mode</span><span class="p">:</span> <span class="n">MODE</span> +<span class="o">...</span> +<span class="n">End</span><span class="p">:</span> +</pre></div> +</div> +<p>3000 characters are sought from the end of file to find the pattern.</p> +</dd> +<dt>“vim modeline” testing</dt><dd><p>Like the modeline of the Emacs editor, Vim editor has the same concept. +ctags treats <code class="docutils literal notranslate"><span class="pre">TYPE</span></code> as a name of interpreter and applies the same +rule of “interpreter” heuristic testing if the last 5 lines of the file +have one of the following patterns:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">filetype</span><span class="o">=</span><span class="n">TYPE</span> +</pre></div> +</div> +<p>or</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ft</span><span class="o">=</span><span class="n">TYPE</span> +</pre></div> +</div> +</dd> +<dt>“PHP marker” testing</dt><dd><p>If the first line is started with <code class="docutils literal notranslate"><span class="pre"><?php</span></code>, +ctags regards the line as “php”.</p> +</dd> +</dl> +<p>Looking into the file contents is a more expensive operation than file +name matching. So ctags runs the testings in limited +conditions. “interpreter” testing is enabled only when a file is an +executable or the <code class="docutils literal notranslate"><span class="pre">--guess-language-eagerly</span></code> (<code class="docutils literal notranslate"><span class="pre">-G</span></code> in short) option is +given. The other heuristic tests are enabled only when <code class="docutils literal notranslate"><span class="pre">-G</span></code> option is +given.</p> +<p>The <code class="docutils literal notranslate"><span class="pre">--print-language</span></code> option can be used just to print the results of +parser selections for given files instead of generating a tags file.</p> +<p>Examples:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --print-language config.h.in input.m input.unknown +<span class="go">config.h.in: C++</span> +<span class="go">input.m: MatLab</span> +<span class="go">input.unknown: NONE</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">NONE</span></code> means that ctags does not select any parser for the file.</p> +</section> +</section> +</section> +<section id="tag-file-format"> +<h2>TAG FILE FORMAT<a class="headerlink" href="#tag-file-format" title="Permalink to this headline">¶</a></h2> +<p>This section describes the tag file format briefly. See <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> and +<a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> for more details.</p> +<p>When not running in etags mode, each entry in the tag file consists of a +separate line, each looking like this, called <em>regular tags</em>, in the most general case:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">tag_name</span><span class="o">><</span><span class="n">TAB</span><span class="o">><</span><span class="n">file_name</span><span class="o">><</span><span class="n">TAB</span><span class="o">><</span><span class="n">ex_cmd</span><span class="o">></span><span class="p">;</span><span class="s2">"<TAB><extension_fields></span> +</pre></div> +</div> +<p>The fields and separators of these lines are specified as follows:</p> +<blockquote> +<div><ol class="arabic"> +<li><p><code class="docutils literal notranslate"><span class="pre"><tag_name></span></code>: tag name</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre"><TAB></span></code>: single tab character</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre"><file_name></span></code>: name of the file in which the object associated with the tag is located</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre"><TAB></span></code>: single tab character</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre"><ex_cmd></span></code>: EX command used to locate the tag within the file; generally a +search pattern (either <code class="docutils literal notranslate"><span class="pre">/pattern/</span></code> or <code class="docutils literal notranslate"><span class="pre">?pattern?</span></code>) or line number (see +<code class="docutils literal notranslate"><span class="pre">--excmd=<type></span></code> option).</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">;"<TAB><extension_fields></span></code>: a set of extension fields. See +“<a class="reference internal" href="#extension-fields">Extension fields</a>” for more details.</p> +<p>Tag file format 2 (see <code class="docutils literal notranslate"><span class="pre">--format</span></code>) extends the EX command +to include the extension fields embedded in an EX comment immediately appended +to the EX command, which leaves it backward-compatible with original +<code class="docutils literal notranslate"><span class="pre">vi(1)</span></code> implementations.</p> +</li> +</ol> +</div></blockquote> +<p>A few special tags, called <em>pseudo tags</em>, are written into the tag file for internal purposes.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_FILE_FORMAT 2 /extended format; --format=1 will not append ;" to lines/ +!_TAG_FILE_SORTED 1 /0=unsorted, 1=sorted, 2=foldcase/ +... +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">--pseudo-tags=[+|-](<pseudo-tag>|*)</span></code> option enables or disables emitting pseudo-tags.</p> +<p>See the output of “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">--list-pseudo-tags</span></code>” for the list of +the kinds. +See also <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> and <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> for more details of the pseudo tags.</p> +<p>These tags are composed in such a way that they always sort to the top of +the file. Therefore, the first two characters of these tags are used a magic +number to detect a tag file for purposes of determining whether a +valid tag file is being overwritten rather than a source file.</p> +<p>Note that the name of each source file will be recorded in the tag file +exactly as it appears on the command line. Therefore, if the path you +specified on the command line was relative to the current directory, then +it will be recorded in that same manner in the tag file. See, however, +the <code class="docutils literal notranslate"><span class="pre">--tag-relative=(yes|no|always|never)</span></code> option for how this behavior can be +modified.</p> +</section> +<section id="tag-entries"> +<span id="id1"></span><h2>TAG ENTRIES<a class="headerlink" href="#tag-entries" title="Permalink to this headline">¶</a></h2> +<p>A tag is an index for a language object. The concept of a tag and related +items in Exuberant Ctags are refined and extended in Universal Ctags.</p> +<p>A tag is categorized into <em>definition tags</em> or <em>reference tags</em>. +In general, Exuberant Ctags only tags <em>definitions</em> of +language objects: places where newly named language objects <em>are introduced</em>. +Universal Ctags, on the other hand, can also tag <em>references</em> of language +objects: places where named language objects <em>are used</em>. However, support +for generating reference tags is new and limited to specific areas of +specific languages in the current version.</p> +<section id="extension-fields"> +<h3>Extension fields<a class="headerlink" href="#extension-fields" title="Permalink to this headline">¶</a></h3> +<p>A tag can record various information, called <em>extension fields</em>.</p> +<p>Extension fields are tab-separated key-value pairs appended to the end of +the EX command as a comment, as described above. These key value pairs +appear in the general form <code class="docutils literal notranslate"><span class="pre">key:value</span></code>.</p> +<p>In addition, information on the scope of the tag definition may be +available, with the key portion equal to some language-dependent construct +name and its value the name declared for that construct in the program. +This scope entry indicates the scope in which the tag was found. +For example, a tag generated for a C structure member would have a scope +looking like <code class="docutils literal notranslate"><span class="pre">struct:myStruct</span></code>.</p> +<p><code class="docutils literal notranslate"><span class="pre">--fields=[+|-][<flags>|*]</span></code> and <code class="docutils literal notranslate"><span class="pre">--fields-(<LANG>|all)=[+|-][<flags>|*]</span></code> options specifies +which available extension fields are to be included in the tag entries.</p> +<p>See the output of “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">--list-fields</span></code>” for the list of +extension fields. +The essential fields are <code class="docutils literal notranslate"><span class="pre">name</span></code>, <code class="docutils literal notranslate"><span class="pre">input</span></code>, <code class="docutils literal notranslate"><span class="pre">pattern</span></code>, and <code class="docutils literal notranslate"><span class="pre">line</span></code>. +The meaning of major fields is as follows (long-name flag/one-letter flag):</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">access</span></code>/<code class="docutils literal notranslate"><span class="pre">a</span></code></dt><dd><p>Indicates the visibility of this class member, where value is specific +to the language.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">end</span></code>/<code class="docutils literal notranslate"><span class="pre">e</span></code></dt><dd><p>Indicates the line number of the end lines of the language object.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">extras</span></code>/<code class="docutils literal notranslate"><span class="pre">E</span></code></dt><dd><p>Extra tag type information. See “<a class="reference internal" href="#extras">Extras</a>” for details.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">file</span></code>/<code class="docutils literal notranslate"><span class="pre">f</span></code></dt><dd><p>Indicates that the tag has file-limited visibility. This key has no +corresponding value. Enabled by default.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">implementation</span></code>/<code class="docutils literal notranslate"><span class="pre">m</span></code></dt><dd><p>When present, this indicates a limited implementation (abstract vs. +concrete) of a routine or class, where value is specific to the +language (<code class="docutils literal notranslate"><span class="pre">virtual</span></code> or <code class="docutils literal notranslate"><span class="pre">pure</span> <span class="pre">virtual</span></code> for C++; <code class="docutils literal notranslate"><span class="pre">abstract</span></code> for Java).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">inherits</span></code>/<code class="docutils literal notranslate"><span class="pre">i</span></code></dt><dd><p>When present, value is a comma-separated list of classes from which +this class is derived (i.e. inherits from).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">input</span></code>/<code class="docutils literal notranslate"><span class="pre">F</span></code></dt><dd><p>The name of source file where <code class="docutils literal notranslate"><span class="pre">name</span></code> is defined or referenced.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">k</span></code></dt><dd><p><a class="reference external" href="Kinds">Kind</a> of tag as one-letter. Enabled by default. +This field has no long-name. +See also <code class="docutils literal notranslate"><span class="pre">kind</span></code>/<code class="docutils literal notranslate"><span class="pre">z</span></code> flag.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">K</span></code></dt><dd><p><a class="reference external" href="Kinds">Kind</a> of tag as long-name. +This field has no long-name. +See also <code class="docutils literal notranslate"><span class="pre">kind</span></code>/<code class="docutils literal notranslate"><span class="pre">z</span></code> flag.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">kind</span></code>/<code class="docutils literal notranslate"><span class="pre">z</span></code></dt><dd><p>Include the <code class="docutils literal notranslate"><span class="pre">kind:</span></code> key in <a class="reference external" href="Kinds">kind field</a>. See also <code class="docutils literal notranslate"><span class="pre">k</span></code> and <code class="docutils literal notranslate"><span class="pre">K</span></code> flags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">language</span></code>/<code class="docutils literal notranslate"><span class="pre">l</span></code></dt><dd><p>Language of source file containing tag</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">line</span></code>/<code class="docutils literal notranslate"><span class="pre">n</span></code></dt><dd><p>The line number where <code class="docutils literal notranslate"><span class="pre">name</span></code> is defined or referenced in <code class="docutils literal notranslate"><span class="pre">input</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">name</span></code>/<code class="docutils literal notranslate"><span class="pre">N</span></code></dt><dd><p>The name of language objects.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">pattern</span></code>/<code class="docutils literal notranslate"><span class="pre">P</span></code></dt><dd><p>Can be used to search the <code class="docutils literal notranslate"><span class="pre">name</span></code> in <code class="docutils literal notranslate"><span class="pre">input</span></code></p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">roles</span></code>/<code class="docutils literal notranslate"><span class="pre">r</span></code></dt><dd><p>Roles assigned to the tag. See “<a class="reference internal" href="#roles">Roles</a>” for more details.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">s</span></code></dt><dd><p>Scope of tag definition. Enabled by default. +This field has no long-name. +See also <code class="docutils literal notranslate"><span class="pre">scope</span></code>/<code class="docutils literal notranslate"><span class="pre">Z</span></code> flag.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">scope</span></code>/<code class="docutils literal notranslate"><span class="pre">Z</span></code></dt><dd><p>Prepend the <code class="docutils literal notranslate"><span class="pre">scope:</span></code> key to scope (<code class="docutils literal notranslate"><span class="pre">s</span></code>) field. +See also <code class="docutils literal notranslate"><span class="pre">s</span></code> flag.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">scopeKind</span></code>/<code class="docutils literal notranslate"><span class="pre">p</span></code></dt><dd><p>Kind of scope as long-name</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">signature</span></code>/<code class="docutils literal notranslate"><span class="pre">S</span></code></dt><dd><p>When present, value is a language-dependent representation of the +signature of a routine (e.g. prototype or parameter list). A routine signature in its complete form +specifies the return type of a routine and its formal argument list. +This extension field is presently supported only for C-based +languages and does not include the return type.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">typeref</span></code>/<code class="docutils literal notranslate"><span class="pre">t</span></code></dt><dd><p>Type and name of a variable, typedef, or return type of +callable like function as <code class="docutils literal notranslate"><span class="pre">typeref:</span></code> field. +Enabled by default.</p> +</dd> +</dl> +<section id="kinds"> +<h4>Kinds<a class="headerlink" href="#kinds" title="Permalink to this headline">¶</a></h4> +<p><code class="docutils literal notranslate"><span class="pre">kind</span></code> is a field which represents the <em>kind</em> of language object +specified by a tag. Kinds used and defined are very different between +parsers. For example, C language defines <code class="docutils literal notranslate"><span class="pre">macro</span></code>, <code class="docutils literal notranslate"><span class="pre">function</span></code>, +<code class="docutils literal notranslate"><span class="pre">variable</span></code>, <code class="docutils literal notranslate"><span class="pre">typedef</span></code>, etc.</p> +<p><code class="docutils literal notranslate"><span class="pre">--kinds-(<LANG>|all)=[+|-](<kinds>|*)</span></code> option specifies a list of language-specific +kinds of tags (or kinds) to include in the output file for a particular +language.</p> +<p>See the output of “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">--list-kinds-full</span></code>” for the complete +list of the kinds.</p> +<p>Its value is either one of the +corresponding one-letter flags or a long-name flag. It is permitted +(and is, in fact, the default) for the key portion of this field to be +omitted. The optional behaviors are controlled with the <code class="docutils literal notranslate"><span class="pre">--fields</span></code> option as follows.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -o - kinds.c +<span class="go">foo kinds.c /^int foo() {$/;" f typeref:typename:int</span> +<span class="gp">$ </span>ctags --fields<span class="o">=</span>+k -o - kinds.c +<span class="go">foo kinds.c /^int foo() {$/;" f typeref:typename:int</span> +<span class="gp">$ </span>ctags --fields<span class="o">=</span>+K -o - kinds.c +<span class="go">foo kinds.c /^int foo() {$/;" function typeref:typename:int</span> +<span class="gp">$ </span>ctags --fields<span class="o">=</span>+z -o - kinds.c +<span class="go">foo kinds.c /^int foo() {$/;" kind:f typeref:typename:int</span> +<span class="gp">$ </span>ctags --fields<span class="o">=</span>+zK -o - kinds.c +<span class="go">foo kinds.c /^int foo() {$/;" kind:function typeref:typename:int</span> +</pre></div> +</div> +</section> +<section id="roles"> +<h4>Roles<a class="headerlink" href="#roles" title="Permalink to this headline">¶</a></h4> +<p><em>Role</em> is a newly introduced concept in Universal Ctags. Role is a +concept associated with reference tags, and is not implemented widely yet.</p> +<p>As described previously in “<a class="reference internal" href="#kinds">Kinds</a>”, the <code class="docutils literal notranslate"><span class="pre">kind</span></code> field represents the type +of language object specified with a tag, such as a function vs. a variable. +Specific kinds are defined for reference tags, such as the C++ kind <code class="docutils literal notranslate"><span class="pre">header</span></code> for +header file, or Java kind <code class="docutils literal notranslate"><span class="pre">package</span></code> for package statements. For such reference +kinds, a <code class="docutils literal notranslate"><span class="pre">roles</span></code> field can be added to distinguish the role of the reference +kind. In other words, the <code class="docutils literal notranslate"><span class="pre">kind</span></code> field identifies the <em>what</em> of the language +object, whereas the <code class="docutils literal notranslate"><span class="pre">roles</span></code> field identifies the <em>how</em> of a referenced language +object. Roles are only used with specific kinds.</p> +<p>For a definition tag, this field takes <code class="docutils literal notranslate"><span class="pre">def</span></code> as a value.</p> +<p>For example, <code class="docutils literal notranslate"><span class="pre">Baz</span></code> is tagged as a reference tag with kind <code class="docutils literal notranslate"><span class="pre">package</span></code> and with +role <code class="docutils literal notranslate"><span class="pre">imported</span></code> with the following code.</p> +<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kn">package</span> <span class="nn">Bar</span><span class="p">;</span> +<span class="kn">import</span> <span class="nn">Baz</span><span class="p">;</span> + +<span class="kd">class</span> <span class="nc">Foo</span> <span class="p">{</span> + <span class="c1">// ...</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields<span class="o">=</span>+KEr -uo - roles.java +<span class="go">Bar roles.java /^package Bar;$/;" package roles:def</span> +<span class="go">Foo roles.java /^class Foo {$/;" class roles:def</span> +<span class="gp">$ </span>ctags --fields<span class="o">=</span>+EKr --extras<span class="o">=</span>+r -uo - roles.java +<span class="go">Bar roles.java /^package Bar;$/;" package roles:def</span> +<span class="go">Baz roles.java /^import Baz;$/;" package roles:imported extras:reference</span> +<span class="go">Foo roles.java /^class Foo {$/;" class roles:def</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">--roles-(<LANG>|all).(<kind>|all)=[+|-][<roles>|*]</span></code> option specifies a list of kind-specific +roles of tags to include in the output file for a particular language.</p> +<p>Inquire the output of “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">--list-roles</span></code>” for the list of +roles.</p> +</section> +</section> +<section id="extras"> +<h3>Extras<a class="headerlink" href="#extras" title="Permalink to this headline">¶</a></h3> +<p>Generally, ctags tags only language objects appearing +in source files, as is. In other words, a value for a <code class="docutils literal notranslate"><span class="pre">name:</span></code> field +should be found on the source file associated with the <code class="docutils literal notranslate"><span class="pre">name:</span></code>. An +<code class="docutils literal notranslate"><span class="pre">extra</span></code> type tag (<em>extra</em>) is for tagging a language object with a processed +name, or for tagging something not associated with a language object. A typical +extra tag is <code class="docutils literal notranslate"><span class="pre">qualified</span></code>, which tags a language object with a +class-qualified or scope-qualified name.</p> +<p><code class="docutils literal notranslate"><span class="pre">--extras-(<LANG>|all)=[+|-][<flags>|*]</span></code> option specifies +whether to include extra tag entries for certain kinds of information.</p> +<p>Inquire the output of <code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">--list-extras</span></code> for the list of extras. +The meaning of major extras is as follows (long-name flag/one-letter flag):</p> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">anonymous</span></code>/none</dt><dd><p>Include an entry for the language object that has no name like lambda +function. This extra has no one-letter flag and is enabled by +default.</p> +<p>The extra tag is useful as a placeholder to fill scope fields +for language objects defined in a language object with no name.</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="p">{</span> + <span class="kt">double</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">p</span> <span class="o">=</span> <span class="p">{</span> <span class="p">.</span><span class="n">x</span> <span class="o">=</span> <span class="mf">0.0</span><span class="p">,</span> <span class="p">.</span><span class="n">y</span> <span class="o">=</span> <span class="mf">0.0</span> <span class="p">};</span> +</pre></div> +</div> +<p>‘<code class="docutils literal notranslate"><span class="pre">x</span></code>’ and ‘<code class="docutils literal notranslate"><span class="pre">y</span></code>’ are the members of a structure. When filling the scope +fields for them, ctags has trouble because the struct +where ‘<code class="docutils literal notranslate"><span class="pre">x</span></code>’ and ‘<code class="docutils literal notranslate"><span class="pre">y</span></code>’ belong to has no name. For overcoming the trouble, +ctags generates an anonymous extra tag for the struct +and fills the scope fields with the name of the extra tag.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields<span class="o">=</span>-f -uo - input.c +<span class="go">__anon9f26d2460108 input.c /^struct {$/;" s</span> +<span class="go">x input.c /^ double x, y;$/;" m struct:__anon9f26d2460108</span> +<span class="go">y input.c /^ double x, y;$/;" m struct:__anon9f26d2460108</span> +<span class="go">p input.c /^} p = { .x = 0.0, .y = 0.0 };$/;" v typeref:struct:__anon9f26d2460108</span> +</pre></div> +</div> +<p>The above tag output has <code class="docutils literal notranslate"><span class="pre">__anon9f26d2460108</span></code> as an anonymous extra tag. +The typeref field of ‘<code class="docutils literal notranslate"><span class="pre">p</span></code>’ also receives the benefit of it.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">fileScope</span></code>/<code class="docutils literal notranslate"><span class="pre">F</span></code></dt><dd><p>Indicates whether tags scoped only for a single file (i.e. tags which +cannot be seen outside of the file in which they are defined, such as +language objects with <code class="docutils literal notranslate"><span class="pre">static</span></code> modifier of C language) should be included +in the output. See also the <code class="docutils literal notranslate"><span class="pre">-h</span></code> option.</p> +<p>This extra tag is enabled by default. Add <code class="docutils literal notranslate"><span class="pre">--extras=-F</span></code> option not to +output tags scoped only for a single-file. This is the replacement for +<code class="docutils literal notranslate"><span class="pre">--file-scope</span></code> option of Exuberant Ctags.</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">int</span> <span class="nf">f</span><span class="p">()</span> <span class="p">{</span> + <span class="k">return</span> <span class="mi">0</span><span class="p">;</span> +<span class="p">}</span> +<span class="kt">int</span> <span class="nf">g</span><span class="p">()</span> <span class="p">{</span> + <span class="k">return</span> <span class="mi">0</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -uo - filescope.c +<span class="go">f filescope.c /^static int f() {$/;" f typeref:typename:int file:</span> +<span class="go">g filescope.c /^int g() {$/;" f typeref:typename:int</span> +<span class="gp">$ </span>ctags --extras<span class="o">=</span>-F -uo - filescope.c +<span class="go">g filescope.c /^int g() {$/;" f typeref:typename:int</span> +</pre></div> +</div> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">inputFile</span></code>/<code class="docutils literal notranslate"><span class="pre">f</span></code></dt><dd><p>Include an entry for the base file name of every source file +(e.g. <code class="docutils literal notranslate"><span class="pre">example.c</span></code>), which addresses the first line of the file. +This flag is the replacement for <code class="docutils literal notranslate"><span class="pre">--file-tags</span></code> hidden option of +Exuberant Ctags.</p> +<p>If the <code class="docutils literal notranslate"><span class="pre">end:</span></code> field is enabled, the end line number of the file can be +attached to the tag. (However, ctags omits the <code class="docutils literal notranslate"><span class="pre">end:</span></code> field +if no newline is in the file like an empty file.)</p> +<p>By default, ctags doesn’t create the <code class="docutils literal notranslate"><span class="pre">inputFile</span></code>/<code class="docutils literal notranslate"><span class="pre">f</span></code> extra +tag for the source file when ctags doesn’t find a parser +for it. Enabling <code class="docutils literal notranslate"><span class="pre">Unknown</span></code> parser with <code class="docutils literal notranslate"><span class="pre">--languages=+Unknown</span></code> forces +ctags to create the extra tags for any source files.</p> +<p>The etags mode enables the <code class="docutils literal notranslate"><span class="pre">Unknown</span></code> parser implicitly.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">pseudo</span></code>/<code class="docutils literal notranslate"><span class="pre">p</span></code></dt><dd><p>Include pseudo-tags. Enabled by default unless the tag file is +written to standard output. See <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> about +the detail of pseudo-tags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">qualified</span></code>/<code class="docutils literal notranslate"><span class="pre">q</span></code></dt><dd><p>Include an extra class-qualified or namespace-qualified tag entry +for each tag which is a member of a class or a namespace.</p> +<p>This may allow easier location of a specific tags when +multiple occurrences of a tag name occur in the tag file. +Note, however, that this could potentially more than double +the size of the tag file.</p> +<p>The actual form of the qualified tag depends upon the language +from which the tag was derived (using a form that is most +natural for how qualified calls are specified in the +language). For C++ and Perl, it is in the form +<code class="docutils literal notranslate"><span class="pre">class::member</span></code>; for Eiffel and Java, it is in the form +<code class="docutils literal notranslate"><span class="pre">class.member</span></code>.</p> +<p>Note: Using backslash characters as separators forming +qualified name in PHP. However, in tags output of +Universal Ctags, a backslash character in a name is escaped +with a backslash character. See <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> about the escaping.</p> +<p>The following example demonstrates the <code class="docutils literal notranslate"><span class="pre">qualified</span></code> extra tag.</p> +<div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="kd">class</span> <span class="nc">point</span> <span class="p">{</span> + <span class="kt">double</span> <span class="n">x</span><span class="p">;</span> +<span class="p">};</span> +</pre></div> +</div> +<p>For the above source file, ctags tags <code class="docutils literal notranslate"><span class="pre">point</span></code> and <code class="docutils literal notranslate"><span class="pre">x</span></code> by +default. If the <code class="docutils literal notranslate"><span class="pre">qualified</span></code> extra is enabled from the command line +(<code class="docutils literal notranslate"><span class="pre">--extras=+q</span></code>), then <code class="docutils literal notranslate"><span class="pre">point.x</span></code> is also tagged even though the string +“<code class="docutils literal notranslate"><span class="pre">point.x</span></code>” is not in the source code.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields<span class="o">=</span>+K -uo - qualified.java +<span class="go">point qualified.java /^class point {$/;" class</span> +<span class="go">x qualified.java /^ double x;$/;" field class:point</span> +<span class="gp">$ </span>ctags --fields<span class="o">=</span>+K --extras<span class="o">=</span>+q -uo - qualified.java +<span class="go">point qualified.java /^class point {$/;" class</span> +<span class="go">x qualified.java /^ double x;$/;" field class:point</span> +<span class="go">point.x qualified.java /^ double x;$/;" field class:point</span> +</pre></div> +</div> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">reference</span></code>/<code class="docutils literal notranslate"><span class="pre">r</span></code></dt><dd><p>Include reference tags. See “<a class="reference internal" href="#id1">TAG ENTRIES</a>” about reference tags.</p> +<p>The following example demonstrates the <code class="docutils literal notranslate"><span class="pre">reference</span></code> extra tag.</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">"utils.h"</span><span class="cp"></span> +<span class="cp">#define X</span> +<span class="cp">#undef X</span> +</pre></div> +</div> +<p>The <code class="docutils literal notranslate"><span class="pre">roles:system</span></code> or <code class="docutils literal notranslate"><span class="pre">roles:local</span></code> fields will be +added depending on whether the include file name begins with ‘<code class="docutils literal notranslate"><span class="pre"><</span></code>’ or not.</p> +<p>“<code class="docutils literal notranslate"><span class="pre">#define</span> <span class="pre">X</span></code>” emits a definition tag. On the other hand “<code class="docutils literal notranslate"><span class="pre">#undef</span> <span class="pre">X</span></code>” emits a +reference tag.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields<span class="o">=</span>+EKr -uo - inc.c +<span class="go">X inc.c /^#define X$/;" macro file: roles:def extras:fileScope</span> +<span class="gp">$ </span>ctags --fields<span class="o">=</span>+EKr --extras<span class="o">=</span>+r -uo - inc.c +<span class="go">stdio.h inc.c /^#include <stdio.h>/;" header roles:system extras:reference</span> +<span class="go">utils.h inc.c /^#include "utils.h"/;" header roles:local extras:reference</span> +<span class="go">X inc.c /^#define X$/;" macro file: roles:def extras:fileScope</span> +<span class="go">X inc.c /^#undef X$/;" macro file: roles:undef extras:fileScope,reference</span> +</pre></div> +</div> +</dd> +</dl> +</section> +<section id="language-specific-fields-and-extras"> +<h3>Language-specific fields and extras<a class="headerlink" href="#language-specific-fields-and-extras" title="Permalink to this headline">¶</a></h3> +<p>Exuberant Ctags has the concept of <em>fields</em> and <em>extras</em>. They are common +between parsers of different languages. Universal Ctags extends this concept +by providing language-specific fields and extras.</p> +</section> +</section> +<section id="how-to-use-with-vi"> +<h2>HOW TO USE WITH VI<a class="headerlink" href="#how-to-use-with-vi" title="Permalink to this headline">¶</a></h2> +<p><code class="docutils literal notranslate"><span class="pre">vi(1)</span></code> will, by default, expect a tag file by the name <code class="docutils literal notranslate"><span class="pre">tags</span></code> in the current +directory. Once the tag file is built, the following commands exercise +the tag indexing feature:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">vi</span> <span class="pre">-t</span> <span class="pre">tag</span></code></dt><dd><p>Start vi and position the cursor at the file and line where <code class="docutils literal notranslate"><span class="pre">tag</span></code> +is defined.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">:ta</span> <span class="pre">tag</span></code></dt><dd><p>Find a tag.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">Ctrl-]</span></code></dt><dd><p>Find the tag under the cursor.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">Ctrl-T</span></code></dt><dd><p>Return to previous location before jump to tag (not widely implemented).</p> +</dd> +</dl> +</section> +<section id="how-to-use-with-gnu-emacs"> +<h2>HOW TO USE WITH GNU EMACS<a class="headerlink" href="#how-to-use-with-gnu-emacs" title="Permalink to this headline">¶</a></h2> +<p><code class="docutils literal notranslate"><span class="pre">emacs(1)</span></code> will, by default, expect a tag file by the name <code class="docutils literal notranslate"><span class="pre">TAGS</span></code> in the +current directory. Once the tag file is built, the following commands +exercise the tag indexing feature:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">M-x</span> <span class="pre">visit-tags-table</span> <span class="pre"><RET></span> <span class="pre">FILE</span> <span class="pre"><RET></span></code></dt><dd><p>Select the tag file, <code class="docutils literal notranslate"><span class="pre">FILE</span></code>, to use.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">M-.</span> <span class="pre">[TAG]</span> <span class="pre"><RET></span></code></dt><dd><p>Find the first definition of TAG. The default tag is the identifier +under the cursor.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">M-*</span></code></dt><dd><p>Pop back to where you previously invoked <code class="docutils literal notranslate"><span class="pre">M-.</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">C-u</span> <span class="pre">M-.</span></code></dt><dd><p>Find the next definition for the last tag.</p> +</dd> +</dl> +<p>For more commands, see the Tags topic in the Emacs info document.</p> +</section> +<section id="how-to-use-with-nedit"> +<h2>HOW TO USE WITH NEDIT<a class="headerlink" href="#how-to-use-with-nedit" title="Permalink to this headline">¶</a></h2> +<p>NEdit version 5.1 and later can handle the new extended tag file format +(see <code class="docutils literal notranslate"><span class="pre">--format</span></code>).</p> +<ul class="simple"> +<li><p>To make NEdit use the tag file, select “File->Load Tags File”.</p></li> +<li><p>To jump to the definition for a tag, highlight the word, then press <code class="docutils literal notranslate"><span class="pre">Ctrl-D</span></code>.</p></li> +</ul> +<p>NEdit 5.1 can read multiple tag files from different +directories. Setting the X resource <code class="docutils literal notranslate"><span class="pre">nedit.tagFile</span></code> to the name of a tag +file instructs NEdit to automatically load that tag file at startup time.</p> +</section> +<section id="caveats"> +<h2>CAVEATS<a class="headerlink" href="#caveats" title="Permalink to this headline">¶</a></h2> +<p>Because ctags is neither a preprocessor nor a compiler, +use of preprocessor macros can fool ctags into either +missing tags or improperly generating inappropriate tags. Although +ctags has been designed to handle certain common cases, +this is the single biggest cause of reported problems. In particular, +the use of preprocessor constructs which alter the textual syntax of C +can fool ctags. You can work around many such problems +by using the <code class="docutils literal notranslate"><span class="pre">-I</span></code> option.</p> +<p>Note that since ctags generates patterns for locating +tags (see the <code class="docutils literal notranslate"><span class="pre">--excmd</span></code> option), it is entirely possible that the wrong line +may be found by your editor if there exists another source line which is +identical to the line containing the tag. The following example +demonstrates this condition:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">variable</span><span class="p">;</span> + +<span class="cm">/* ... */</span> +<span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="n">variable</span><span class="p">)</span> +<span class="kt">int</span> <span class="n">variable</span><span class="p">;</span> +<span class="p">{</span> + <span class="cm">/* ... */</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Depending upon which editor you use and where in the code you happen to be, +it is possible that the search pattern may locate the local parameter +declaration before it finds the actual global variable definition, +since the lines (and therefore their search patterns) are +identical.</p> +<p>This can be avoided by use of the <code class="docutils literal notranslate"><span class="pre">--excmd=n</span></code> option.</p> +</section> +<section id="bugs"> +<h2>BUGS<a class="headerlink" href="#bugs" title="Permalink to this headline">¶</a></h2> +<p>ctags has more options than <code class="docutils literal notranslate"><span class="pre">ls(1)</span></code>.</p> +<p>ctags assumes the input file is written in the correct +grammar. Otherwise output of ctags is undefined. In other words it has garbage +in, garbage out (GIGO) feature.</p> +<p>When parsing a C++ member function definition (e.g. <code class="docutils literal notranslate"><span class="pre">className::function</span></code>), +ctags cannot determine whether the scope specifier +is a class name or a namespace specifier and always lists it as a class name +in the scope portion of the extension fields. Also, if a C++ function +is defined outside of the class declaration (the usual case), the access +specification (i.e. public, protected, or private) and implementation +information (e.g. virtual, pure virtual) contained in the function +declaration are not known when the tag is generated for the function +definition. It will, however be available for prototypes (e.g. <code class="docutils literal notranslate"><span class="pre">--kinds-c++=+p</span></code>).</p> +<p>No qualified tags are generated for language objects inherited into a class.</p> +</section> +<section id="environment-variables"> +<h2>ENVIRONMENT VARIABLES<a class="headerlink" href="#environment-variables" title="Permalink to this headline">¶</a></h2> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">TMPDIR</span></code></dt><dd><p>On Unix-like hosts where <code class="docutils literal notranslate"><span class="pre">mkstemp(3)</span></code> is available, the value of this +variable specifies the directory in which to place temporary files. +This can be useful if the size of a temporary file becomes too large +to fit on the partition holding the default temporary directory +defined at compilation time.</p> +<p>ctags creates temporary +files only if either (1) an emacs-style tag file is being +generated, (2) the tag file is being sent to standard output, or +(3) the program was compiled to use an internal sort algorithm to sort +the tag files instead of the <code class="docutils literal notranslate"><span class="pre">sort(1)</span></code> utility of the operating system. +If the <code class="docutils literal notranslate"><span class="pre">sort(1)</span></code> utility of the operating system is being used, it will +generally observe this variable also.</p> +<p>Note that if ctags +is setuid, the value of <code class="docutils literal notranslate"><span class="pre">TMPDIR</span></code> will be ignored.</p> +</dd> +</dl> +</section> +<section id="files"> +<h2>FILES<a class="headerlink" href="#files" title="Permalink to this headline">¶</a></h2> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">tags</span></code></dt><dd><p>The default tag file created by ctags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAGS</span></code></dt><dd><p>The default tag file created by etags.</p> +</dd> +</dl> +<p><code class="docutils literal notranslate"><span class="pre">$XDG_CONFIG_HOME/ctags/*.ctags</span></code>, or <code class="docutils literal notranslate"><span class="pre">$HOME/.config/ctags/*.ctags</span></code> if +<code class="docutils literal notranslate"><span class="pre">$XDG_CONFIG_HOME</span></code> is not defined +(on other than MS Windows)</p> +<p><code class="docutils literal notranslate"><span class="pre">$HOME/.ctags.d/*.ctags</span></code></p> +<p><code class="docutils literal notranslate"><span class="pre">$HOMEDRIVE$HOMEPATH/ctags.d/*.ctags</span></code> (on MS Windows only)</p> +<p><code class="docutils literal notranslate"><span class="pre">.ctags.d/*.ctags</span></code></p> +<p><code class="docutils literal notranslate"><span class="pre">ctags.d/*.ctags</span></code></p> +<blockquote> +<div><p>If any of these configuration files exist, each will be expected to +contain a set of default options which are read in the order listed +when ctags starts, but before any command line options +are read. This makes it possible to set up personal or project-level defaults.</p> +<p>It +is possible to compile ctags to read an additional +configuration file before any of those shown above, which will be +indicated if the output produced by the <code class="docutils literal notranslate"><span class="pre">--version</span></code> option lists the +<code class="docutils literal notranslate"><span class="pre">custom-conf</span></code> feature.</p> +<p>Options appearing on the command line will override options +specified in these files. Only options will be read from these +files.</p> +<p>Note that the option +files are read in line-oriented mode in which spaces are significant +(since shell quoting is not possible) but spaces at the beginning +of a line are ignored. Each line of the file is read as +one command line parameter (as if it were quoted with single quotes). +Therefore, use new lines to indicate separate command-line arguments.</p> +<p>A line starting with ‘<code class="docutils literal notranslate"><span class="pre">#</span></code>’ is treated as a comment.</p> +<p><code class="docutils literal notranslate"><span class="pre">*.ctags</span></code> files in a directory are loaded in alphabetical order.</p> +</div></blockquote> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p>See <a class="reference internal" href="ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a> for defining (or extending) a parser +in a configuration file.</p> +<p>See <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> for the format of tag files.</p> +<p>See <a class="reference internal" href="ctags-incompatibilities.7.html#ctags-incompatibilities-7"><span class="std std-ref">ctags-incompatibilities(7)</span></a> about known incompatible changes +with Exuberant Ctags.</p> +<p>See <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> if you are interested in writing +a tool for processing tags files.</p> +<p>See <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> about python input specific notes.</p> +<p>See <a class="reference internal" href="readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a> about a client tool for binary searching a +name in a sorted tags file.</p> +<p>The official Universal Ctags web site at: <a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p>Also <code class="docutils literal notranslate"><span class="pre">ex(1)</span></code>, <code class="docutils literal notranslate"><span class="pre">vi(1)</span></code>, <code class="docutils literal notranslate"><span class="pre">elvis(1)</span></code>, or, better yet, <code class="docutils literal notranslate"><span class="pre">vim(1)</span></code>, the official editor of ctags. +For more information on <code class="docutils literal notranslate"><span class="pre">vim(1)</span></code>, see the Vim web site at: <a class="reference external" href="https://www.vim.org/">https://www.vim.org/</a></p> +</section> +<section id="author"> +<h2>AUTHOR<a class="headerlink" href="#author" title="Permalink to this headline">¶</a></h2> +<p>Universal Ctags project +<a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p>Darren Hiebert <<a class="reference external" href="mailto:dhiebert%40users.sourceforge.net">dhiebert<span>@</span>users<span>.</span>sourceforge<span>.</span>net</a>> +<a class="reference external" href="http://DarrenHiebert.com/">http://DarrenHiebert.com/</a></p> +</section> +<section id="motivation"> +<h2>MOTIVATION<a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h2> +<p>“Think ye at all times of rendering some service to every member of the +human race.”</p> +<p>“All effort and exertion put forth by man from the fullness of his heart is +worship, if it is prompted by the highest motives and the will to do +service to humanity.”</p> +<p>-- From the Baha’i Writings</p> +</section> +<section id="credits"> +<h2>CREDITS<a class="headerlink" href="#credits" title="Permalink to this headline">¶</a></h2> +<p>This version of ctags (Universal Ctags) derived from +the repository, known as fishman-ctags, started by Reza Jelveh.</p> +<p>The fishman-ctags was derived from Exuberant Ctags.</p> +<p>Some parsers are taken from <code class="docutils literal notranslate"><span class="pre">tagmanager</span></code> of the Geany (<a class="reference external" href="https://www.geany.org/">https://www.geany.org/</a>) +project.</p> +<p>Exuberant Ctags was originally derived from and +inspired by the ctags program by Steve Kirkendall <<a class="reference external" href="mailto:kirkenda%40cs.pdx.edu">kirkenda<span>@</span>cs<span>.</span>pdx<span>.</span>edu</a>> +that comes with the Elvis vi clone (though virtually none of the original +code remains).</p> +<p>Credit is also due Bram Moolenaar <<a class="reference external" href="mailto:Bram%40vim.org">Bram<span>@</span>vim<span>.</span>org</a>>, the author of vim, +who has devoted so much of his time and energy both to developing the editor +as a service to others, and to helping the orphans of Uganda.</p> +<p>The section entitled “<a class="reference internal" href="#how-to-use-with-gnu-emacs">HOW TO USE WITH GNU EMACS</a>” was shamelessly stolen +from the info page for GNU etags.</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</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="#command-line-interface">COMMAND LINE INTERFACE</a><ul> +<li><a class="reference internal" href="#letters-and-names">Letters and names</a></li> +<li><a class="reference internal" href="#list-options">List options</a></li> +</ul> +</li> +<li><a class="reference internal" href="#options">OPTIONS</a><ul> +<li><a class="reference internal" href="#input-output-file-options">Input/Output File Options</a></li> +<li><a class="reference internal" href="#output-format-options">Output Format Options</a></li> +<li><a class="reference internal" href="#language-selection-and-mapping-options">Language Selection and Mapping Options</a></li> +<li><a class="reference internal" href="#tags-file-contents-options">Tags File Contents Options</a></li> +<li><a class="reference internal" href="#option-file-options">Option File Options</a></li> +<li><a class="reference internal" href="#optlib-options">optlib Options</a></li> +<li><a class="reference internal" href="#language-specific-options">Language Specific Options</a></li> +<li><a class="reference internal" href="#listing-options">Listing Options</a></li> +<li><a class="reference internal" href="#miscellaneous-options">Miscellaneous Options</a></li> +<li><a class="reference internal" href="#obsoleted-options">Obsoleted Options</a></li> +</ul> +</li> +<li><a class="reference internal" href="#operational-details">OPERATIONAL DETAILS</a><ul> +<li><a class="reference internal" href="#notes-for-c-c-parser">Notes for C/C++ Parser</a></li> +<li><a class="reference internal" href="#determining-file-language">Determining file language</a><ul> +<li><a class="reference internal" href="#file-name-mapping">File name mapping</a></li> +<li><a class="reference internal" href="#heuristically-guessing">Heuristically guessing</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference internal" href="#tag-file-format">TAG FILE FORMAT</a></li> +<li><a class="reference internal" href="#tag-entries">TAG ENTRIES</a><ul> +<li><a class="reference internal" href="#extension-fields">Extension fields</a><ul> +<li><a class="reference internal" href="#kinds">Kinds</a></li> +<li><a class="reference internal" href="#roles">Roles</a></li> +</ul> +</li> +<li><a class="reference internal" href="#extras">Extras</a></li> +<li><a class="reference internal" href="#language-specific-fields-and-extras">Language-specific fields and extras</a></li> +</ul> +</li> +<li><a class="reference internal" href="#how-to-use-with-vi">HOW TO USE WITH VI</a></li> +<li><a class="reference internal" href="#how-to-use-with-gnu-emacs">HOW TO USE WITH GNU EMACS</a></li> +<li><a class="reference internal" href="#how-to-use-with-nedit">HOW TO USE WITH NEDIT</a></li> +<li><a class="reference internal" href="#caveats">CAVEATS</a></li> +<li><a class="reference internal" href="#bugs">BUGS</a></li> +<li><a class="reference internal" href="#environment-variables">ENVIRONMENT VARIABLES</a></li> +<li><a class="reference internal" href="#files">FILES</a></li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +<li><a class="reference internal" href="#author">AUTHOR</a></li> +<li><a class="reference internal" href="#motivation">MOTIVATION</a></li> +<li><a class="reference internal" href="#credits">CREDITS</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="../man-pages.html" + title="previous chapter">Man pages</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="tags.5.html" + title="next chapter">tags</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="tags.5.html" title="tags" + >next</a> |</li> + <li class="right" > + <a href="../man-pages.html" title="Man pages" + >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</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 diff --git a/ctags/docs/man/readtags.1.html b/ctags/docs/man/readtags.1.html new file mode 100644 index 0000000..0a8e867 --- /dev/null +++ b/ctags/docs/man/readtags.1.html @@ -0,0 +1,449 @@ + +<!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>readtags — 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="Parsers" href="../parsers.html" /> + <link rel="prev" title="ctags-incompatibilities" href="ctags-incompatibilities.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="../parsers.html" title="Parsers" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-incompatibilities.7.html" title="ctags-incompatibilities" + 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="">readtags</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="readtags"> +<span id="readtags-1"></span><h1>readtags<a class="headerlink" href="#readtags" title="Permalink to this headline">¶</a></h1> +<p>Find tag file entries matching specified names</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>1</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>readtags</strong> -h | --help</div> +<div class="line"><strong>readtags</strong> (-H | --help-expression) (filter|sorter)</div> +<div class="line"><strong>readtags</strong> [OPTION]… ACTION</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>The <strong>readtags</strong> program filters, sorts and prints tag entries in a tags file. +The basic filtering is done using <strong>actions</strong>, by which you can list all +regular tags, pseudo tags or regular tags matching specific name. Then, further +filtering and sorting can be done using <strong>post processors</strong>, namely <strong>filter +expressions</strong> and <strong>sorter expressions</strong>.</p> +</section> +<section id="actions"> +<h2>ACTIONS<a class="headerlink" href="#actions" title="Permalink to this headline">¶</a></h2> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">-l</span></code>, <code class="docutils literal notranslate"><span class="pre">--list</span></code></dt><dd><p>List regular tags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">[-]</span> <span class="pre">NAME</span></code></dt><dd><p>List regular tags matching NAME. +“-” as NAME indicates arguments after this as NAME even if they start with -.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-D</span></code>, <code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code>.</p> +</dd> +</dl> +</section> +<section id="options"> +<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2> +<section id="controlling-the-tags-reading-behavior"> +<h3>Controlling the Tags Reading Behavior<a class="headerlink" href="#controlling-the-tags-reading-behavior" title="Permalink to this headline">¶</a></h3> +<p>The behavior of reading tags can be controlled using these options:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">-t</span> <span class="pre">TAGFILE</span></code>, <code class="docutils literal notranslate"><span class="pre">--tag-file</span> <span class="pre">TAGFILE</span></code></dt><dd><p>Use specified tag file (default: “tags”).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-s[0|1|2]</span></code>, <code class="docutils literal notranslate"><span class="pre">--override-sort-detection</span> <span class="pre">METHOD</span></code></dt><dd><p>Override sort detection of tag file. +METHOD: unsorted|sorted|foldcase</p> +</dd> +</dl> +<p>The NAME action will perform binary search on sorted (including “foldcase”) +tags files, which is much faster then on unsorted tags files.</p> +</section> +<section id="controlling-the-name-action-behavior"> +<h3>Controlling the NAME Action Behavior<a class="headerlink" href="#controlling-the-name-action-behavior" title="Permalink to this headline">¶</a></h3> +<p>The behavior of the NAME action can be controlled using these options:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">-i</span></code>, <code class="docutils literal notranslate"><span class="pre">--icase-match</span></code></dt><dd><p>Perform case-insensitive matching in the NAME action.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-p</span></code>, <code class="docutils literal notranslate"><span class="pre">--prefix-match</span></code></dt><dd><p>Perform prefix matching in the NAME action.</p> +</dd> +</dl> +</section> +<section id="controlling-the-output"> +<h3>Controlling the Output<a class="headerlink" href="#controlling-the-output" title="Permalink to this headline">¶</a></h3> +<p>By default, the output of readtags contains only the name, input and pattern +field. The Output can be tweaked using these options:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">-d</span></code>, <code class="docutils literal notranslate"><span class="pre">--debug</span></code></dt><dd><p>Turn on debugging output.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-E</span></code>, <code class="docutils literal notranslate"><span class="pre">--escape-output</span></code></dt><dd><p>Escape characters like tabs in output as described in <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">-e</span></code>, <code class="docutils literal notranslate"><span class="pre">--extension-fields</span></code></dt><dd><p>Include extension fields in output.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-n</span></code>, <code class="docutils literal notranslate"><span class="pre">--line-number</span></code></dt><dd><p>Also include the line number field when <code class="docutils literal notranslate"><span class="pre">-e</span></code> option is give.</p> +</dd> +</dl> +<p>About the <code class="docutils literal notranslate"><span class="pre">-E</span></code> option: certain characters are escaped in a tags file, to make +it machine-readable. e.g., ensuring no tabs character appear in fields other +than the pattern field. By default, readtags translates them to make it +human-readable, but when utilizing readtags output in a script or a client +tool, <code class="docutils literal notranslate"><span class="pre">-E</span></code> option should be used. See <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> for more +discussion on this.</p> +</section> +<section id="filtering-and-sorting"> +<h3>Filtering and Sorting<a class="headerlink" href="#filtering-and-sorting" title="Permalink to this headline">¶</a></h3> +<p>Further filtering and sorting on the tags listed by actions are performed using:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">-Q</span> <span class="pre">EXP</span></code>, <code class="docutils literal notranslate"><span class="pre">--filter</span> <span class="pre">EXP</span></code></dt><dd><p>Filter the tags listed by ACTION with EXP before printing.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-S</span> <span class="pre">EXP</span></code>, <code class="docutils literal notranslate"><span class="pre">--sorter</span> <span class="pre">EXP</span></code></dt><dd><p>Sort the tags listed by ACTION with EXP before printing.</p> +</dd> +</dl> +<p>These are discussed in the <a class="reference internal" href="#expression">EXPRESSION</a> section.</p> +</section> +<section id="examples"> +<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3> +<ul> +<li><p>List all tags in “/path/to/tags”:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -t /path/to/tags -l +</pre></div> +</div> +</li> +<li><p>List all tags in “tags” that start with “mymethod”:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -p - mymethod +</pre></div> +</div> +</li> +<li><p>List all tags matching “mymethod”, case insensitively:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -i - mymethod +</pre></div> +</div> +</li> +<li><p>List all tags start with “myvar”, and printing all fields (i.e., the whole line):</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -p -ne - myvar +</pre></div> +</div> +</li> +</ul> +</section> +</section> +<section id="expression"> +<h2>EXPRESSION<a class="headerlink" href="#expression" title="Permalink to this headline">¶</a></h2> +<p>Scheme-style expressions are used for the <code class="docutils literal notranslate"><span class="pre">-Q</span></code> and <code class="docutils literal notranslate"><span class="pre">-S</span></code> options. For those +who doesn’t know Scheme or Lisp, just remember:</p> +<ul class="simple"> +<li><p>A function call is wrapped in a pair of parenthesis. The first item in it is +the function/operator name, the others are arguments.</p></li> +<li><p>Function calls can be nested.</p></li> +<li><p>Missing values and boolean false are represented by <code class="docutils literal notranslate"><span class="pre">#f</span></code>. <code class="docutils literal notranslate"><span class="pre">#t</span></code> and all +other values are considered to be true.</p></li> +</ul> +<p>So, <code class="docutils literal notranslate"><span class="pre">(+</span> <span class="pre">1</span> <span class="pre">(+</span> <span class="pre">2</span> <span class="pre">3))</span></code> means add 2 and 3 first, then add the result with 1. +<code class="docutils literal notranslate"><span class="pre">(and</span> <span class="pre">"string"</span> <span class="pre">1</span> <span class="pre">#t)</span></code> means logical AND on <code class="docutils literal notranslate"><span class="pre">"string"</span></code>, <code class="docutils literal notranslate"><span class="pre">1</span></code> and <code class="docutils literal notranslate"><span class="pre">#t</span></code>, +and the result is true since there is no <code class="docutils literal notranslate"><span class="pre">#f</span></code>.</p> +<section id="filtering"> +<h3>Filtering<a class="headerlink" href="#filtering" title="Permalink to this headline">¶</a></h3> +<p>The tag entries that make the filter expression produces true value are printed +by readtags.</p> +<p>The basic operators for filtering are <code class="docutils literal notranslate"><span class="pre">eq?</span></code>, <code class="docutils literal notranslate"><span class="pre">prefix?</span></code>, <code class="docutils literal notranslate"><span class="pre">suffix?</span></code>, +<code class="docutils literal notranslate"><span class="pre">substr?</span></code>, and <code class="docutils literal notranslate"><span class="pre">#/PATTERN/</span></code>. Language common fields can be accessed using +variables starting with <code class="docutils literal notranslate"><span class="pre">$</span></code>, e.g., <code class="docutils literal notranslate"><span class="pre">$language</span></code> represents the language field. +For example:</p> +<ul> +<li><p>List all tags start with “myfunc” in Python code files:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -p -Q <span class="s1">'(eq? $language "Python")'</span> - myfunc +</pre></div> +</div> +</li> +</ul> +<p><code class="docutils literal notranslate"><span class="pre">downcase</span></code> or <code class="docutils literal notranslate"><span class="pre">upcase</span></code> operators can be used to perform case-insensitive +matching:</p> +<ul> +<li><p>List all tags containing “my”, case insensitively:</p> +<blockquote> +<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -Q <span class="s1">'(substr? (downcase $name) "my")'</span> -l +</pre></div> +</div> +</div></blockquote> +</li> +</ul> +<p>We have logical operators like <code class="docutils literal notranslate"><span class="pre">and</span></code>, <code class="docutils literal notranslate"><span class="pre">or</span></code> and <code class="docutils literal notranslate"><span class="pre">not</span></code>. The value of a +missing field is #f, so we could deal with missing fields:</p> +<ul> +<li><p>List all tags containing “impl” in Python code files, but allow the +<code class="docutils literal notranslate"><span class="pre">language:</span></code> field to be missing:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span>$ readtags -Q '(and (substr? $name "impl")\ + (or (not $language)\ + (eq? $language "Python")))' -l +</pre></div> +</div> +</li> +</ul> +<p><code class="docutils literal notranslate"><span class="pre">#/PATTERN/</span></code> is for the case when string predicates (<code class="docutils literal notranslate"><span class="pre">prefix?</span></code>, <code class="docutils literal notranslate"><span class="pre">suffix?</span></code>, +and <code class="docutils literal notranslate"><span class="pre">substr?</span></code>) are not enough. You can use “Posix extended regular expression” +as PATTERN.</p> +<ul> +<li><p>List all tags inherits from the class “A”:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -Q <span class="s1">'(#/(^|,) ?A(,|$)/ $inherits)'</span> -l +</pre></div> +</div> +</li> +</ul> +<p>Here <code class="docutils literal notranslate"><span class="pre">$inherits</span></code> is a comma-separated class list like “A,B,C”, “P, A, Q”, or +just “A”. Notice that this filter works on both situations where there’s a +space after each comma or there’s not.</p> +<p>Case-insensitive matching can be performed by <code class="docutils literal notranslate"><span class="pre">#/PATTERN/i</span></code>:</p> +<ul> +<li><p>List all tags inherits from the class “A” or “a”:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -Q <span class="s1">'(#/(^|,) ?A(,|$)/i $inherits)'</span> -l +</pre></div> +</div> +</li> +</ul> +<p>To include “/” in a pattern, prefix <code class="docutils literal notranslate"><span class="pre">\</span></code> to the “/”.</p> +<p>NOTE: The above regular expression pattern for inspecting inheritances is just +an example to show how to use <code class="docutils literal notranslate"><span class="pre">#/PATTERN/</span></code> expression. Tags file generators +have no consensus about the format of <code class="docutils literal notranslate"><span class="pre">inherits:</span></code>, e.g., whether there should +be a space after a comma. Even parsers in ctags have no consensus. Noticing the +format of the <code class="docutils literal notranslate"><span class="pre">inherits:</span></code> field of specific languages is needed for such +queries.</p> +<p>The expressions <code class="docutils literal notranslate"><span class="pre">#/PATTERN/</span></code> and <code class="docutils literal notranslate"><span class="pre">#/PATTERN/i</span></code> are for interactive use. +Readtags also offers an alias <code class="docutils literal notranslate"><span class="pre">string->regexp</span></code>, so <code class="docutils literal notranslate"><span class="pre">#/PATTERN/</span></code> is equal to +<code class="docutils literal notranslate"><span class="pre">(string->regexp</span> <span class="pre">"PATTERN")</span></code>, and <code class="docutils literal notranslate"><span class="pre">#/PATTERN/i</span></code> is equal to +<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">#t)</span></code>. <code class="docutils literal notranslate"><span class="pre">string->regexp</span></code> doesn’t need +to prefix <code class="docutils literal notranslate"><span class="pre">\</span></code> for including “/” in a pattern. <code class="docutils literal notranslate"><span class="pre">string->regexp</span></code> may simplify +a client tool building an expression. See also <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> for +building expressions in your tool.</p> +<p>Let’s now consider missing fields. The tags file may have tag entries that has +no <code class="docutils literal notranslate"><span class="pre">inherits:</span></code> field. In that case <code class="docutils literal notranslate"><span class="pre">$inherits</span></code> is #f, and the regular +expression matching raises an error, since string operators only work for +strings. To avoid this problem:</p> +<ul> +<li><p>Safely list all tags inherits from the class “A”:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -Q <span class="s1">'(and $inherits (#/(^|,) ?A(,|$)/ $inherits))'</span> -l +</pre></div> +</div> +</li> +</ul> +<p>This makes sure <code class="docutils literal notranslate"><span class="pre">$inherits</span></code> is not missing first, then match it by regexp.</p> +<p>Sometimes you want to keep tags where the field <em>is</em> missing. For example, your +want to exclude reference tags, which is marked by the <code class="docutils literal notranslate"><span class="pre">extras:</span></code> field, then +you want to keep tags who doesn’t have <code class="docutils literal notranslate"><span class="pre">extras:</span></code> field since they are also +not reference tags. Here’s how to do it:</p> +<ul> +<li><p>List all tags but the reference tags:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -Q <span class="s1">'(or (not $extras) (#/(^|,) ?reference(,|$)/ $extras))'</span> -l +</pre></div> +</div> +</li> +</ul> +<p>Notice that <code class="docutils literal notranslate"><span class="pre">(not</span> <span class="pre">$extras)</span></code> produces <code class="docutils literal notranslate"><span class="pre">#t</span></code> when <code class="docutils literal notranslate"><span class="pre">$extras</span></code> is missing, so +the whole <code class="docutils literal notranslate"><span class="pre">or</span></code> expression produces <code class="docutils literal notranslate"><span class="pre">#t</span></code>.</p> +<p>Run “readtags -H filter” to know about all valid functions and variables.</p> +</section> +<section id="sorting"> +<h3>Sorting<a class="headerlink" href="#sorting" title="Permalink to this headline">¶</a></h3> +<p>When sorting, the sorter expression is evaluated on two tag entries to decide +which should sort before the other one, until the order of all tag entries is +decided.</p> +<p>In a sorter expression, <code class="docutils literal notranslate"><span class="pre">$</span></code> and <code class="docutils literal notranslate"><span class="pre">&</span></code> are used to access the fields in the +two tag entries, and let’s call them $-entry and &-entry. The sorter expression +should have a value of -1, 0 or 1. The value -1 means the $-entry should be put +above the &-entry, 1 means the contrary, and 0 makes their order in the output +uncertain.</p> +<p>The core operator of sorting is <code class="docutils literal notranslate"><span class="pre"><></span></code>. It’s used to compare two strings or two +numbers (numbers are for the <code class="docutils literal notranslate"><span class="pre">line:</span></code> or <code class="docutils literal notranslate"><span class="pre">end:</span></code> fields). In <code class="docutils literal notranslate"><span class="pre">(<></span> <span class="pre">a</span> <span class="pre">b)</span></code>, if +<code class="docutils literal notranslate"><span class="pre">a</span></code> < <code class="docutils literal notranslate"><span class="pre">b</span></code>, the result is -1; <code class="docutils literal notranslate"><span class="pre">a</span></code> > <code class="docutils literal notranslate"><span class="pre">b</span></code> produces 1, and <code class="docutils literal notranslate"><span class="pre">a</span></code> = <code class="docutils literal notranslate"><span class="pre">b</span></code> +produces 0. Strings are compared using the <code class="docutils literal notranslate"><span class="pre">strcmp</span></code> function, see strcmp(3).</p> +<p>For example, sort by names, and make those shorter or alphabetically smaller +ones appear before the others:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -S <span class="s1">'(<> $name &name)'</span> -l +</pre></div> +</div> +<p>This reads “If the tag name in the $-entry is smaller, it goes before the +&-entry”.</p> +<p>The <code class="docutils literal notranslate"><span class="pre"><or></span></code> operator is used to chain multiple expressions until one returns +-1 or 1. For example, sort by input file names, then line numbers if in the +same file:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -S <span class="s1">'(<or> (<> $input &input) (<> $line &line))'</span> -l +</pre></div> +</div> +<p>The <code class="docutils literal notranslate"><span class="pre">*-</span></code> operator is used to flip the compare result. i.e., <code class="docutils literal notranslate"><span class="pre">(*-</span> <span class="pre">(<></span> <span class="pre">a</span> <span class="pre">b))</span></code> +is the same as <code class="docutils literal notranslate"><span class="pre">(<></span> <span class="pre">b</span> <span class="pre">a)</span></code>.</p> +<p>Filter expressions can be used in sorter expressions. The technique is use +<code class="docutils literal notranslate"><span class="pre">if</span></code> to produce integers that can be compared based on the filter, like:</p> +<div class="highlight-lisp notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="nv"><></span> <span class="p">(</span><span class="k">if</span> <span class="nv">filter-expr-on-$-entry</span> <span class="mi">-1</span> <span class="mi">1</span><span class="p">)</span> + <span class="p">(</span><span class="k">if</span> <span class="nv">filter-expr-on-&-entry</span> <span class="mi">-1</span> <span class="mi">1</span><span class="p">))</span> +</pre></div> +</div> +<p>So if $-entry satisfies the filter, while &-entry doesn’t, it’s the same as +<code class="docutils literal notranslate"><span class="pre">(<></span> <span class="pre">-1</span> <span class="pre">1)</span></code>, which produces <code class="docutils literal notranslate"><span class="pre">-1</span></code>.</p> +<p>For example, we want to put tags with “file” kind below other tags, then the +sorter would look like:</p> +<div class="highlight-lisp notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="nv"><></span> <span class="p">(</span><span class="k">if</span> <span class="p">(</span><span class="nv">eq?</span> <span class="nv">$kind</span> <span class="s">"file"</span><span class="p">)</span> <span class="mi">1</span> <span class="mi">-1</span><span class="p">)</span> + <span class="p">(</span><span class="k">if</span> <span class="p">(</span><span class="nv">eq?</span> <span class="nv">&kind</span> <span class="s">"file"</span><span class="p">)</span> <span class="mi">1</span> <span class="mi">-1</span><span class="p">))</span> +</pre></div> +</div> +<p>A quick read tells us: If $-entry has “file” kind, and &-entry doesn’t, the +sorter becomes <code class="docutils literal notranslate"><span class="pre">(<></span> <span class="pre">1</span> <span class="pre">-1)</span></code>, which produces <code class="docutils literal notranslate"><span class="pre">1</span></code>, so the $-entry is put below +the &-entry, exactly what we want.</p> +</section> +<section id="inspecting-the-behavior-of-expressions"> +<h3>Inspecting the Behavior of Expressions<a class="headerlink" href="#inspecting-the-behavior-of-expressions" title="Permalink to this headline">¶</a></h3> +<p>The <cite>print</cite> operator can be used to print the value of an expression. For +example:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -Q <span class="s1">'(print $name)'</span> -l +</pre></div> +</div> +<p>prints the name of each tag entry before it. Since the return value of +<code class="docutils literal notranslate"><span class="pre">print</span></code> is not #f, all the tag entries are printed. We could control this +using the <code class="docutils literal notranslate"><span class="pre">begin</span></code> or <code class="docutils literal notranslate"><span class="pre">begin0</span></code> operator. <code class="docutils literal notranslate"><span class="pre">begin</span></code> returns the value of its +last argument, and <code class="docutils literal notranslate"><span class="pre">begin0</span></code> returns the value of its first argument. For +example:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -Q <span class="s1">'(begin0 #f (print (prefix? "ctags" "ct")))'</span> -l +</pre></div> +</div> +<p>prints a bunch of “#t” (depending on how many lines are in the tags file), and +the actual tag entries are not printed.</p> +</section> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p>See <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> for the details of tags file format.</p> +<p>See <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> for the tips writing a +tool utilizing tags file.</p> +<p>The official Universal Ctags web site at:</p> +<p><a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p>The git repository for the library used in readtags command:</p> +<p><a class="reference external" href="https://github.com/universal-ctags/libreadtags">https://github.com/universal-ctags/libreadtags</a></p> +</section> +<section id="credits"> +<h2>CREDITS<a class="headerlink" href="#credits" title="Permalink to this headline">¶</a></h2> +<p>Universal Ctags project +<a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p>Darren Hiebert <<a class="reference external" href="mailto:dhiebert%40users.sourceforge.net">dhiebert<span>@</span>users<span>.</span>sourceforge<span>.</span>net</a>> +<a class="reference external" href="http://DarrenHiebert.com/">http://DarrenHiebert.com/</a></p> +<p>The readtags command and libreadtags maintained at Universal Ctags +are derived from readtags.c and readtags.h developd at +<a class="reference external" href="http://ctags.sourceforge.net">http://ctags.sourceforge.net</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="#">readtags</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="#actions">ACTIONS</a></li> +<li><a class="reference internal" href="#options">OPTIONS</a><ul> +<li><a class="reference internal" href="#controlling-the-tags-reading-behavior">Controlling the Tags Reading Behavior</a></li> +<li><a class="reference internal" href="#controlling-the-name-action-behavior">Controlling the NAME Action Behavior</a></li> +<li><a class="reference internal" href="#controlling-the-output">Controlling the Output</a></li> +<li><a class="reference internal" href="#filtering-and-sorting">Filtering and Sorting</a></li> +<li><a class="reference internal" href="#examples">Examples</a></li> +</ul> +</li> +<li><a class="reference internal" href="#expression">EXPRESSION</a><ul> +<li><a class="reference internal" href="#filtering">Filtering</a></li> +<li><a class="reference internal" href="#sorting">Sorting</a></li> +<li><a class="reference internal" href="#inspecting-the-behavior-of-expressions">Inspecting the Behavior of Expressions</a></li> +</ul> +</li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +<li><a class="reference internal" href="#credits">CREDITS</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-incompatibilities.7.html" + title="previous chapter">ctags-incompatibilities</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="../parsers.html" + title="next chapter">Parsers</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="../parsers.html" title="Parsers" + >next</a> |</li> + <li class="right" > + <a href="ctags-incompatibilities.7.html" title="ctags-incompatibilities" + >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="">readtags</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 diff --git a/ctags/docs/man/tags.5.html b/ctags/docs/man/tags.5.html new file mode 100644 index 0000000..e9747f4 --- /dev/null +++ b/ctags/docs/man/tags.5.html @@ -0,0 +1,619 @@ + +<!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>tags — 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-optlib" href="ctags-optlib.7.html" /> + <link rel="prev" title="ctags" href="ctags.1.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-optlib.7.html" title="ctags-optlib" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags.1.html" title="ctags" + 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="">tags</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="tags"> +<span id="tags-5"></span><h1>tags<a class="headerlink" href="#tags" title="Permalink to this headline">¶</a></h1> +<p>Vi tags file format extended in ctags projects</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>2+</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>5</p> +</dd> +</dl> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>The contents of next section is a copy of FORMAT file in Exuberant +Ctags source code in its subversion repository at sourceforge.net.</p> +<p>Exceptions introduced in Universal Ctags are explained inline with +“EXCEPTION” marker.</p> +</section> +<hr class="docutils" /> +<section id="proposal-for-extended-vi-tags-file-format"> +<h2>Proposal for extended Vi tags file format<a class="headerlink" href="#proposal-for-extended-vi-tags-file-format" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line">Version: 0.06 DRAFT</div> +<div class="line">Date: 1998 Feb 8</div> +<div class="line">Author: Bram Moolenaar <Bram at vim.org> and Darren Hiebert <dhiebert at users.sourceforge.net></div> +</div> +<section id="introduction"> +<h3>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h3> +<p>The file format for the “tags” file, as used by Vi and many of its +descendants, has limited capabilities.</p> +<p>This additional functionality is desired:</p> +<ol class="arabic simple"> +<li><p>Static or local tags. +The scope of these tags is the file where they are defined. The same tag +can appear in several files, without really being a duplicate.</p></li> +<li><p>Duplicate tags. +Allow the same tag to occur more then once. They can be located in +a different file and/or have a different command.</p></li> +<li><p>Support for C++. +A tag is not only specified by its name, but also by the context (the +class name).</p></li> +<li><p>Future extension. +When even more additional functionality is desired, it must be possible to +add this later, without breaking programs that don’t support it.</p></li> +</ol> +</section> +<section id="from-proposal-to-standard"> +<h3>From proposal to standard<a class="headerlink" href="#from-proposal-to-standard" title="Permalink to this headline">¶</a></h3> +<p>To make this proposal into a standard for tags files, it needs to be supported +by most people working on versions of Vi, ctags, etc.. Currently this +standard is supported by:</p> +<dl class="simple"> +<dt>Darren Hiebert <dhiebert at users.sourceforge.net></dt><dd><p>Exuberant Ctags</p> +</dd> +<dt>Bram Moolenaar <Bram at vim.org></dt><dd><p>Vim (Vi IMproved)</p> +</dd> +</dl> +<p>These have been or will be asked to support this standard:</p> +<dl class="simple"> +<dt>Nvi</dt><dd><p>Keith Bostic <bostic at bsdi.com></p> +</dd> +<dt>Vile</dt><dd><p>Tom E. Dickey <dickey at clark.net></p> +</dd> +<dt>NEdit</dt><dd><p>Mark Edel <edel at ltx.com></p> +</dd> +<dt>CRiSP</dt><dd><p>Paul Fox <fox at crisp.demon.co.uk></p> +</dd> +<dt>Lemmy</dt><dd><p>James Iuliano <jai at accessone.com></p> +</dd> +<dt>Zeus</dt><dd><p>Jussi Jumppanen <jussij at ca.com.au></p> +</dd> +<dt>Elvis</dt><dd><p>Steve Kirkendall <kirkenda at cs.pdx.edu></p> +</dd> +<dt>FTE</dt><dd><p>Marko Macek <Marko.Macek at snet.fri.uni-lj.si></p> +</dd> +</dl> +</section> +<section id="backwards-compatibility"> +<h3>Backwards compatibility<a class="headerlink" href="#backwards-compatibility" title="Permalink to this headline">¶</a></h3> +<p>A tags file that is generated in the new format should still be usable by Vi. +This makes it possible to distribute tags files that are usable by all +versions and descendants of Vi.</p> +<p>This restricts the format to what Vi can handle. The format is:</p> +<ol class="arabic"> +<li><p>The tags file is a list of lines, each line in the format:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="n">tagname</span><span class="p">}</span><span class="o"><</span><span class="n">Tab</span><span class="o">></span><span class="p">{</span><span class="n">tagfile</span><span class="p">}</span><span class="o"><</span><span class="n">Tab</span><span class="o">></span><span class="p">{</span><span class="n">tagaddress</span><span class="p">}</span> +</pre></div> +</div> +<dl> +<dt>{tagname}</dt><dd><p>Any identifier, not containing white space..</p> +<p>EXCEPTION: Universal Ctags violates this item of the proposal; +tagname may contain spaces. However, tabs are not allowed.</p> +</dd> +<dt><Tab></dt><dd><p>Exactly one TAB character (although many versions of Vi can +handle any amount of white space).</p> +</dd> +<dt>{tagfile}</dt><dd><p>The name of the file where {tagname} is defined, relative to +the current directory (or location of the tags file?).</p> +</dd> +<dt>{tagaddress}</dt><dd><p>Any Ex command. When executed, it behaves like ‘magic’ was +not set.</p> +</dd> +</dl> +</li> +<li><p>The tags file is sorted on {tagname}. This allows for a binary search in +the file.</p></li> +<li><p>Duplicate tags are allowed, but which one is actually used is +unpredictable (because of the binary search).</p></li> +</ol> +<p>The best way to add extra text to the line for the new functionality, without +breaking it for Vi, is to put a comment in the {tagaddress}. This gives the +freedom to use any text, and should work in any traditional Vi implementation.</p> +<p>For example, when the old tags file contains:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>main main.c /^main(argc, argv)$/ +DEBUG defines.c 89 +</pre></div> +</div> +<p>The new lines can be:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>main main.c /^main(argc, argv)$/;"any additional text +DEBUG defines.c 89;"any additional text +</pre></div> +</div> +<p>Note that the ‘;’ is required to put the cursor in the right line, and then +the ‘”’ is recognized as the start of a comment.</p> +<p>For Posix compliant Vi versions this will NOT work, since only a line number +or a search command is recognized. I hope Posix can be adjusted. Nvi suffers +from this.</p> +</section> +<section id="security"> +<h3>Security<a class="headerlink" href="#security" title="Permalink to this headline">¶</a></h3> +<p>Vi allows the use of any Ex command in a tags file. This has the potential of +a trojan horse security leak.</p> +<p>The proposal is to allow only Ex commands that position the cursor in a single +file. Other commands, like editing another file, quitting the editor, +changing a file or writing a file, are not allowed. It is therefore logical +to call the command a tagaddress.</p> +<p>Specifically, these two Ex commands are allowed:</p> +<ul> +<li><p>A decimal line number:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">89</span> +</pre></div> +</div> +</li> +<li><p>A search command. It is a regular expression pattern, as used by Vi, +enclosed in // or ??:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>/^int c;$/ +?main()? +</pre></div> +</div> +</li> +</ul> +<p>There are two combinations possible:</p> +<ul> +<li><p>Concatenation of the above, with ‘;’ in between. The meaning is that the +first line number or search command is used, the cursor is positioned in +that line, and then the second search command is used (a line number would +not be useful). This can be done multiple times. This is useful when the +information in a single line is not unique, and the search needs to start +in a specified line.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">struct</span> <span class="n">xyz</span> <span class="p">{</span><span class="o">/</span><span class="p">;</span><span class="o">/</span><span class="nb">int</span> <span class="n">count</span><span class="p">;</span><span class="o">/</span> +<span class="mi">389</span><span class="p">;</span><span class="o">/</span><span class="n">struct</span> <span class="n">foo</span><span class="o">/</span><span class="p">;</span><span class="o">/</span><span class="n">char</span> <span class="o">*</span><span class="n">s</span><span class="p">;</span><span class="o">/</span> +</pre></div> +</div> +</li> +<li><p>A trailing comment can be added, starting with ‘;”’ (two characters: +semi-colon and double-quote). This is used below.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">89</span><span class="p">;</span><span class="s2">" foo bar</span> +</pre></div> +</div> +</li> +</ul> +<p>This might be extended in the future. What is currently missing is a way to +position the cursor in a certain column.</p> +</section> +<section id="goals"> +<h3>Goals<a class="headerlink" href="#goals" title="Permalink to this headline">¶</a></h3> +<p>Now the usage of the comment text has to be defined. The following is aimed +at:</p> +<ol class="arabic simple"> +<li><p>Keep the text short, because:</p> +<ul class="simple"> +<li><p>The line length that Vi can handle is limited to 512 characters.</p></li> +<li><p>Tags files can contain thousands of tags. I have seen tags files of +several Mbytes.</p></li> +<li><p>More text makes searching slower.</p></li> +</ul> +</li> +<li><p>Keep the text readable, because:</p> +<ul class="simple"> +<li><p>It is often necessary to check the output of a new ctags program.</p></li> +<li><p>Be able to edit the file by hand.</p></li> +<li><p>Make it easier to write a program to produce or parse the file.</p></li> +</ul> +</li> +<li><p>Don’t use special characters, because:</p> +<ul class="simple"> +<li><p>It should be possible to treat a tags file like any normal text file.</p></li> +</ul> +</li> +</ol> +</section> +<section id="proposal"> +<h3>Proposal<a class="headerlink" href="#proposal" title="Permalink to this headline">¶</a></h3> +<p>Use a comment after the {tagaddress} field. The format would be:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="n">tagname</span><span class="p">}</span><span class="o"><</span><span class="n">Tab</span><span class="o">></span><span class="p">{</span><span class="n">tagfile</span><span class="p">}</span><span class="o"><</span><span class="n">Tab</span><span class="o">></span><span class="p">{</span><span class="n">tagaddress</span><span class="p">}[;</span><span class="s2">"<Tab></span><span class="si">{tagfield}</span><span class="s2">..]</span> +</pre></div> +</div> +<dl> +<dt>{tagname}</dt><dd><p>Any identifier, not containing white space..</p> +<p>EXCEPTION: Universal Ctags violates this item of the proposal; +name may contain spaces. However, tabs are not allowed. +Conversion, for some characters including <Tab> in the “value”, +explained in the last of this section is applied.</p> +</dd> +<dt><Tab></dt><dd><p>Exactly one TAB character (although many versions of Vi can +handle any amount of white space).</p> +</dd> +<dt>{tagfile}</dt><dd><p>The name of the file where {tagname} is defined, relative to +the current directory (or location of the tags file?).</p> +</dd> +<dt>{tagaddress}</dt><dd><p>Any Ex command. When executed, it behaves like ‘magic’ was +not set. It may be restricted to a line number or a search +pattern (Posix).</p> +</dd> +</dl> +<p>Optionally:</p> +<dl class="simple"> +<dt>;”</dt><dd><p>semicolon + doublequote: Ends the tagaddress in way that looks +like the start of a comment to Vi.</p> +</dd> +<dt>{tagfield}</dt><dd><p>See below.</p> +</dd> +</dl> +<p>A tagfield has a name, a colon, and a value: “name:value”.</p> +<ul> +<li><p>The name consist only out of alphabetical characters. Upper and lower case +are allowed. Lower case is recommended. Case matters (“kind:” and “Kind: +are different tagfields).</p> +<p>EXCEPTION: Universal Ctags allows users to use a numerical character +in the name other than its initial letter.</p> +</li> +<li><p>The value may be empty. +It cannot contain a <Tab>.</p> +<ul class="simple"> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\t</span></code>, this stands for a <Tab>.</p></li> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\r</span></code>, this stands for a <CR>.</p></li> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\n</span></code>, this stands for a <NL>.</p></li> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\\</span></code>, this stands for a single <code class="docutils literal notranslate"><span class="pre">\</span></code> character.</p></li> +</ul> +<p>Other use of the backslash character is reserved for future expansion. +Warning: When a tagfield value holds an MS-DOS file name, the backslashes +must be doubled!</p> +<p>EXCEPTION: Universal Ctags introduces more conversion rules.</p> +<ul class="simple"> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\a</span></code>, this stands for a <BEL> (0x07).</p></li> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\b</span></code>, this stands for a <BS> (0x08).</p></li> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\v</span></code>, this stands for a <VT> (0x0b).</p></li> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\f</span></code>, this stands for a <FF> (0x0c).</p></li> +<li><p>The characters in range 0x01 to 0x1F included, and 0x7F are +converted to <code class="docutils literal notranslate"><span class="pre">\x</span></code> prefixed hexadecimal number if the characters are +not handled in the above “value” rules.</p></li> +<li><p>The leading space (0x20) and <code class="docutils literal notranslate"><span class="pre">!</span></code> (0x21) in {tagname} are converted +to <code class="docutils literal notranslate"><span class="pre">\x</span></code> prefixed hexadecimal number (<code class="docutils literal notranslate"><span class="pre">\x20</span></code> and <code class="docutils literal notranslate"><span class="pre">\x21</span></code>) if the +tag is not a pseudo-tag. As described later, a pseudo-tag starts with +<code class="docutils literal notranslate"><span class="pre">!</span></code>. These rules are for distinguishing pseudo-tags and non pseudo-tags +(regular tags) when tags lines in a tag file are sorted.</p></li> +</ul> +</li> +</ul> +<p>Proposed tagfield names:</p> +<table class="docutils align-default"> +<colgroup> +<col style="width: 16%" /> +<col style="width: 84%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>FIELD-NAME</p></th> +<th class="head"><p>DESCRIPTION</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>arity</p></td> +<td><p>Number of arguments for a function tag.</p></td> +</tr> +<tr class="row-odd"><td><p>class</p></td> +<td><p>Name of the class for which this tag is a member or method.</p></td> +</tr> +<tr class="row-even"><td><p>enum</p></td> +<td><p>Name of the enumeration in which this tag is an enumerator.</p></td> +</tr> +<tr class="row-odd"><td><p>file</p></td> +<td><p>Static (local) tag, with a scope of the specified file. When +the value is empty, {tagfile} is used.</p></td> +</tr> +<tr class="row-even"><td><p>function</p></td> +<td><p>Function in which this tag is defined. Useful for local +variables (and functions). When functions nest (e.g., in +Pascal), the function names are concatenated, separated with +‘/’, so it looks like a path.</p></td> +</tr> +<tr class="row-odd"><td><p>kind</p></td> +<td><p>Kind of tag. The value depends on the language. For C and +C++ these kinds are recommended:</p> +<dl class="simple"> +<dt>c</dt><dd><p>class name</p> +</dd> +<dt>d</dt><dd><p>define (from #define XXX)</p> +</dd> +<dt>e</dt><dd><p>enumerator</p> +</dd> +<dt>f</dt><dd><p>function or method name</p> +</dd> +<dt>F</dt><dd><p>file name</p> +</dd> +<dt>g</dt><dd><p>enumeration name</p> +</dd> +<dt>m</dt><dd><p>member (of structure or class data)</p> +</dd> +<dt>p</dt><dd><p>function prototype</p> +</dd> +<dt>s</dt><dd><p>structure name</p> +</dd> +<dt>t</dt><dd><p>typedef</p> +</dd> +<dt>u</dt><dd><p>union name</p> +</dd> +<dt>v</dt><dd><p>variable</p> +</dd> +</dl> +<p>When this field is omitted, the kind of tag is undefined.</p> +</td> +</tr> +<tr class="row-even"><td><p>struct</p></td> +<td><p>Name of the struct in which this tag is a member.</p></td> +</tr> +<tr class="row-odd"><td><p>union</p></td> +<td><p>Name of the union in which this tag is a member.</p></td> +</tr> +</tbody> +</table> +<p>Note that these are mostly for C and C++. When tags programs are written for +other languages, this list should be extended to include the used field names. +This will help users to be independent of the tags program used.</p> +<p>Examples:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>asdf sub.cc /^asdf()$/;" new_field:some\svalue file: +foo_t sub.h /^typedef foo_t$/;" kind:t +func3 sub.p /^func3()$/;" function:/func1/func2 file: +getflag sub.c /^getflag(arg)$/;" kind:f file: +inc sub.cc /^inc()$/;" file: class:PipeBuf +</pre></div> +</div> +<p>The name of the “kind:” field can be omitted. This is to reduce the size of +the tags file by about 15%. A program reading the tags file can recognize the +“kind:” field by the missing ‘:’. Examples:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>foo_t sub.h /^typedef foo_t$/;" t +getflag sub.c /^getflag(arg)$/;" f file: +</pre></div> +</div> +<p>Additional remarks:</p> +<ul class="simple"> +<li><p>When a tagfield appears twice in a tag line, only the last one is used.</p></li> +</ul> +<p>Note about line separators:</p> +<p>Vi traditionally runs on Unix systems, where the line separator is a single +linefeed character <NL>. On MS-DOS and compatible systems <CR><NL> is the +standard line separator. To increase portability, this line separator is also +supported.</p> +<p>On the Macintosh a single <CR> is used for line separator. Supporting this on +Unix systems causes problems, because most fgets() implementation don’t see +the <CR> as a line separator. Therefore the support for a <CR> as line +separator is limited to the Macintosh.</p> +<p>Summary:</p> +<table class="docutils align-default"> +<colgroup> +<col style="width: 23%" /> +<col style="width: 36%" /> +<col style="width: 41%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>line separator</p></th> +<th class="head"><p>generated on</p></th> +<th class="head"><p>accepted on</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><LF></p></td> +<td><p>Unix</p></td> +<td><p>Unix, MS-DOS, Macintosh</p></td> +</tr> +<tr class="row-odd"><td><p><CR></p></td> +<td><p>Macintosh</p></td> +<td><p>Macintosh</p></td> +</tr> +<tr class="row-even"><td><p><CR><LF></p></td> +<td><p>MS-DOS</p></td> +<td><p>Unix, MS-DOS, Macintosh</p></td> +</tr> +</tbody> +</table> +<p>The characters <CR> and <LF> cannot be used inside a tag line. This is not +mentioned elsewhere (because it’s obvious).</p> +<p>Note about white space:</p> +<p>Vi allowed any white space to separate the tagname from the tagfile, and the +filename from the tagaddress. This would need to be allowed for backwards +compatibility. However, all known programs that generate tags use a single +<Tab> to separate fields.</p> +<p>There is a problem for using file names with embedded white space in the +tagfile field. To work around this, the same special characters could be used +as in the new fields, for example <code class="docutils literal notranslate"><span class="pre">\s</span></code>. But, unfortunately, in MS-DOS the +backslash character is used to separate file names. The file name +<code class="docutils literal notranslate"><span class="pre">c:\vim\sap</span></code> contains <code class="docutils literal notranslate"><span class="pre">\s</span></code>, but this is not a <Space>. The number of +backslashes could be doubled, but that will add a lot of characters, and make +parsing the tags file slower and clumsy.</p> +<p>To avoid these problems, we will only allow a <Tab> to separate fields, and +not support a file name or tagname that contains a <Tab> character. This +means that we are not 100% Vi compatible. However, there is no known tags +program that uses something else than a <Tab> to separate the fields. Only +when a user typed the tags file himself, or made his own program to generate a +tags file, we could run into problems. To solve this, the tags file should be +filtered, to replace the arbitrary white space with a single <Tab>. This Vi +command can be used:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">:</span><span class="o">%</span><span class="n">s</span><span class="o">/^</span>\<span class="p">([</span><span class="o">^</span> <span class="o">^</span><span class="n">I</span><span class="p">]</span><span class="o">*</span>\<span class="p">)[</span> <span class="o">^</span><span class="n">I</span><span class="p">]</span><span class="o">*</span>\<span class="p">([</span><span class="o">^</span> <span class="o">^</span><span class="n">I</span><span class="p">]</span><span class="o">*</span>\<span class="p">)[</span> <span class="o">^</span><span class="n">I</span><span class="p">]</span><span class="o">*/</span>\<span class="mi">1</span><span class="o">^</span><span class="n">I</span>\<span class="mi">2</span><span class="o">^</span><span class="n">I</span><span class="o">/</span> +</pre></div> +</div> +<p>(replace ^I with a real <Tab>).</p> +<p>TAG FILE INFORMATION:</p> +<p>Pseudo-tag lines can be used to encode information into the tag file regarding +details about its content (e.g. have the tags been sorted?, are the optional +tagfields present?), and regarding the program used to generate the tag file. +This information can be used both to optimize use of the tag file (e.g. +enable/disable binary searching) and provide general information (what version +of the generator was used).</p> +<p>The names of the tags used in these lines may be suitably chosen to ensure +that when sorted, they will always be located near the first lines of the tag +file. The use of “!_TAG_” is recommended. Note that a rare tag like “!” +can sort to before these lines. The program reading the tags file should be +smart enough to skip over these tags.</p> +<p>The lines described below have been chosen to convey a select set of +information.</p> +<p>Tag lines providing information about the content of the tag file:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_FILE_FORMAT {version-number} /optional comment/ +!_TAG_FILE_SORTED {0|1} /0=unsorted, 1=sorted/ +</pre></div> +</div> +<p>The {version-number} used in the tag file format line reserves the value of +“1” for tag files complying with the original UNIX vi/ctags format, and +reserves the value “2” for tag files complying with this proposal. This value +may be used to determine if the extended features described in this proposal +are present.</p> +<p>Tag lines providing information about the program used to generate the tag +file, and provided solely for documentation purposes:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_PROGRAM_AUTHOR {author-name} /{email-address}/ +!_TAG_PROGRAM_NAME {program-name} /optional comment/ +!_TAG_PROGRAM_URL {URL} /optional comment/ +!_TAG_PROGRAM_VERSION {version-id} /optional comment/ +</pre></div> +</div> +<p>EXCEPTION: Universal Ctags introduces more kinds of pseudo-tags. +See <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> about them.</p> +</section> +</section> +<hr class="docutils" /> +<section id="exceptions-in-universal-ctags"> +<h2>Exceptions in Universal Ctags<a class="headerlink" href="#exceptions-in-universal-ctags" title="Permalink to this headline">¶</a></h2> +<p>Universal Ctags supports this proposal with some +exceptions.</p> +<section id="exceptions"> +<h3>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li><p>{tagname} in tags file generated by Universal Ctags may contain +spaces and several escape sequences. Parsers for documents like Tex and +reStructuredText, or liberal languages such as JavaScript need these +exceptions. See {tagname} of Proposal section for more detail about the +conversion.</p></li> +<li><p>“name” part of {tagfield} in a tag generated by Universal Ctags may +contain numeric characters, but the first character of the “name” +must be alphabetic.</p> +</li> +</ol> +</section> +<section id="compatible-output-and-weakness"> +<span id="compat-output"></span><h3>Compatible output and weakness<a class="headerlink" href="#compatible-output-and-weakness" title="Permalink to this headline">¶</a></h3> +<p>Default behavior (<code class="docutils literal notranslate"><span class="pre">--output-format=u-ctags</span></code> option) has the +exceptions. In other hand, with <code class="docutils literal notranslate"><span class="pre">--output-format=e-ctags</span></code> option +ctags has no exception; Universal Ctags command may use the same file +format as Exuberant Ctags. However, <code class="docutils literal notranslate"><span class="pre">--output-format=e-ctags</span></code> throws +away a tag entry which name includes a space or a tab +character. <code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_MODE</span></code> pseudo-tag tells which format is +used when ctags generating tags file.</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-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(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="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="#">tags</a><ul> +<li><a class="reference internal" href="#description">DESCRIPTION</a></li> +<li><a class="reference internal" href="#proposal-for-extended-vi-tags-file-format">Proposal for extended Vi tags file format</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#from-proposal-to-standard">From proposal to standard</a></li> +<li><a class="reference internal" href="#backwards-compatibility">Backwards compatibility</a></li> +<li><a class="reference internal" href="#security">Security</a></li> +<li><a class="reference internal" href="#goals">Goals</a></li> +<li><a class="reference internal" href="#proposal">Proposal</a></li> +</ul> +</li> +<li><a class="reference internal" href="#exceptions-in-universal-ctags">Exceptions in Universal Ctags</a><ul> +<li><a class="reference internal" href="#exceptions">Exceptions</a></li> +<li><a class="reference internal" href="#compatible-output-and-weakness">Compatible output and weakness</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.1.html" + title="previous chapter">ctags</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-optlib.7.html" + title="next chapter">ctags-optlib</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-optlib.7.html" title="ctags-optlib" + >next</a> |</li> + <li class="right" > + <a href="ctags.1.html" title="ctags" + >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="">tags</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 |