282 lines
40 KiB
HTML
282 lines
40 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Ctags Support</title>
|
|
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<meta name="viewport" content="width=device-width initial-scale=1">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta http-equiv="Content-Language" content="en-gb">
|
|
|
|
<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<script src="http://code.jquery.com/jquery-1.12.4.min.js"
|
|
integrity="sha256-ZosEbRLbNQzLpnKIkEdrPv7lOy9C27hHQ+Xp8a4MxAQ=" crossorigin="anonymous"></script>
|
|
|
|
<script src="../docs-assets/Bigfoot.js"></script>
|
|
<link href="../docs-assets/Bigfoot.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<script>
|
|
function togglePopup(material_id) {
|
|
var popup = document.getElementById(material_id);
|
|
popup.classList.toggle("show");
|
|
}
|
|
</script>
|
|
|
|
<link href="../docs-assets/Popups.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
|
|
</head>
|
|
<body class="commentary-font">
|
|
<nav role="navigation">
|
|
<h1><a href="../index.html">
|
|
<img src="../docs-assets/Octagram.png" width=72 height=72">
|
|
</a></h1>
|
|
<ul><li><a href="index.html"><span class="selectedlink">inweb</span></a></li>
|
|
</ul><h2>Foundation Module</h2><ul>
|
|
<li><a href="../foundation-module/index.html">foundation</a></li>
|
|
<li><a href="../foundation-test/index.html">foundation-test</a></li>
|
|
</ul><h2>Example Webs</h2><ul>
|
|
<li><a href="../goldbach/index.html">goldbach</a></li>
|
|
<li><a href="../twinprimes/twinprimes.html">twinprimes</a></li>
|
|
<li><a href="../eastertide/index.html">eastertide</a></li>
|
|
</ul><h2>Repository</h2><ul>
|
|
<li><a href="https://github.com/ganelson/inweb"><img src="../docs-assets/github.png" height=18> github</a></li>
|
|
</ul><h2>Related Projects</h2><ul>
|
|
<li><a href="../../../inform/docs/index.html">inform</a></li>
|
|
<li><a href="../../../intest/docs/index.html">intest</a></li>
|
|
|
|
</ul>
|
|
</nav>
|
|
<main role="main">
|
|
<!--Weave of 'Ctags Support' generated by Inweb-->
|
|
<div class="breadcrumbs">
|
|
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inweb</a></li><li><a href="index.html#6">Chapter 6: Extras</a></li><li><b>Ctags Support</b></li></ul></div>
|
|
<p class="purpose">Constructing a suitable ctags file for a web.</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>§1. </b>On every tangle, Inweb writes a simple Universal Ctags file to the root
|
|
directory of the web: this can then be used by text editors (such as BBEdit
|
|
on MacOS) to provide code completion and jump-to-definition features when
|
|
editing the sections in the web.
|
|
</p>
|
|
|
|
<p class="commentary">A ctags file is essentially just a list of identifiers called "tagnames",
|
|
which are usually names of functions or data types, along with details of
|
|
where they are defined in a program. Ctags files are almost never written by
|
|
hand, but are instead generated by a tool such as the eponymous <span class="extract"><span class="extract-syntax">ctags</span></span>. Here,
|
|
though, Inweb is going to do the generation, because it can make sense of the
|
|
web structure of source code in a way which the <span class="extract"><span class="extract-syntax">ctags</span></span> parser cannot.
|
|
</p>
|
|
|
|
<p class="commentary">The original <span class="extract"><span class="extract-syntax">ctags</span></span> dates to 1992, and was devised by Ken Arnold. This was
|
|
much extended as Exuberant Ctags, by Darren Hiebert, which was then forked and
|
|
re-maintained as Universal Ctags by Reza Jelveh and others. The result is
|
|
nearly standard now, though as with a lot of early Unix infrastructure (compare
|
|
<span class="extract"><span class="extract-syntax">make</span></span>, for example), that standard design feels very antique: white space is
|
|
significant, filename extensions are not standard practice, and so on. See
|
|
<a href="https://ctags.io" class="external">Universal Ctags</a> for more.<sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup>
|
|
</p>
|
|
|
|
<ul class="footnotetexts"><li class="footnote" id="fn:1"><p class="inwebfootnote"><sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup> If there is an exact specification for the file format we need to write
|
|
here, though, I have been unable to find it. There is a sketch "proposal" for one,
|
|
but it omits details of, e.g., exactly what characters must be escaped and how;
|
|
what characters can legally be part of a tagname; and so on.
|
|
<a href="#fnref:1" title="return to text"> ↩</a></p></li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>§2. </b>As mentioned above, Ctags go back to an age before filenames necessarily had
|
|
extensions, and just as the defaukt make file is <span class="extract"><span class="extract-syntax">makefile</span></span> and not <span class="extract"><span class="extract-syntax">makefile.mk</span></span>,
|
|
so the default Ctags file is called <span class="extract"><span class="extract-syntax">tags</span></span> and not <span class="extract"><span class="extract-syntax">tags.ctag</span></span>.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Ctags::write</span><button class="popup" onclick="togglePopup('usagePopup1')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup1">Usage of <span class="code-font"><span class="function-syntax">Ctags::write</span></span>:<br/>Program Control - <a href="1-pc.html#SP7_4_2">§7.4.2</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">) {</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> </span><span class="identifier-syntax">ctags_file</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">F</span><span class="plain-syntax">) {</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><a href="../foundation-module/3-fln.html#SP6" class="function-link"><span class="function-syntax">Filenames::up</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><span class="identifier-syntax">W</span><span class="plain-syntax">-></span><span class="element-syntax">md</span><span class="plain-syntax">-></span><span class="element-syntax">path_to_web</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">F</span><span class="plain-syntax"> = </span><a href="../foundation-module/3-fln.html#SP2" class="function-link"><span class="function-syntax">Filenames::in</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"tags"</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> }</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OUT</span><span class="plain-syntax"> = &</span><span class="identifier-syntax">ctags_file</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">STREAM_OPEN_TO_FILE</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="constant-syntax">UTF8_ENC</span><span class="plain-syntax">) == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">)</span>
|
|
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP2" class="function-link"><span class="function-syntax">Errors::fatal_with_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"unable to write ctags file"</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="6-cs.html#SP2_1" class="named-paragraph-link"><span class="named-paragraph">Write header</span><span class="named-paragraph-number">2.1</span></a></span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="6-cs.html#SP2_2" class="named-paragraph-link"><span class="named-paragraph">List defined constants</span><span class="named-paragraph-number">2.2</span></a></span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="6-cs.html#SP2_3" class="named-paragraph-link"><span class="named-paragraph">List structures</span><span class="named-paragraph-number">2.3</span></a></span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="6-cs.html#SP2_4" class="named-paragraph-link"><span class="named-paragraph">List functions</span><span class="named-paragraph-number">2.4</span></a></span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">STREAM_CLOSE</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax">}</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP2_1" class="paragraph-anchor"></a><b>§2.1. </b>Unless you really want to monkey with identifiers or filenames containing
|
|
line break characters or tabs, a ctags file has a simple format to read or
|
|
write: there's one tag on each line, and each line has three or more fields
|
|
divided by tab characters. If we write <span class="extract"><span class="extract-syntax"> -> </span></span> for a tab, a line looks like:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> tagname -> filename -> /find/;" -> more</span>
|
|
</pre>
|
|
<p class="commentary">The stranded double-quote there is not a misprint. For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Frogs::spawn -> pond/Chapter 1/Amphibians.w -> /^void Frogs::spawn(species *S) {$/;" -> f</span>
|
|
</pre>
|
|
<p class="commentary">Here the tagname is <span class="extract"><span class="extract-syntax">Frogs::spawn</span></span>. The filename <span class="extract"><span class="extract-syntax">pond/Chapter 1/Amphibians.w</span></span>
|
|
is the file defining this function. The <span class="extract"><span class="extract-syntax">find</span></span> field is an EX-format command for
|
|
finding the line in question: see below. Finally, the <span class="extract"><span class="extract-syntax">more</span></span> field is actually
|
|
a run of optional extra information, presented in a free-form sort of way, but
|
|
we will use it only the simplest of ways. In this example it is just <span class="extract"><span class="extract-syntax">f</span></span>,
|
|
meaning "I am a function declaration".
|
|
</p>
|
|
|
|
<p class="commentary">The opening lines of the file, however, are usually metadata, i.e., describing the
|
|
file itself and where it came from. In those lines, tagnames begin with <span class="extract"><span class="extract-syntax">!_</span></span> and are
|
|
called "pseudotags". The <span class="extract"><span class="extract-syntax">filename</span></span> field is instead a value, while the <span class="extract"><span class="extract-syntax">find</span></span>
|
|
field is instead an optional comment.
|
|
</p>
|
|
|
|
<p class="commentary">The first two keys here are essential: the other three seem just to be good practice.
|
|
These are the five keys which Universal <span class="extract"><span class="extract-syntax">ctags</span></span> writes by default, so we'll follow
|
|
suit.
|
|
</p>
|
|
|
|
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Write header</span><span class="named-paragraph-number">2.1</span></span><span class="comment-syntax"> =</span>
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"!_TAG_FILE_FORMAT\t2\t/extended format; --format=1 will not append ;\" to lines/\n"</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"!_TAG_FILE_SORTED\t0\t/0=unsorted, 1=sorted, 2=foldcase/\n"</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"!_TAG_PROGRAM_AUTHOR\tGraham Nelson\t/graham.nelson@mod-langs.ox.ac.uk/\n"</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"!_TAG_PROGRAM_NAME\t[[Title]]\t</span><span class="comment-syntax">\n");</span>
|
|
<span class="string-syntax"> WRITE("</span><span class="plain-syntax">!</span><span class="identifier-syntax">_TAG_PROGRAM_VERSION</span><span class="plain-syntax">\</span><span class="identifier-syntax">t</span><span class="plain-syntax">[[</span><span class="identifier-syntax">Semantic</span><span class="plain-syntax"> </span><span class="identifier-syntax">Version</span><span class="plain-syntax"> </span><span class="identifier-syntax">Number</span><span class="plain-syntax">]]\</span><span class="identifier-syntax">t</span><span class="plain-syntax">/</span><span class="identifier-syntax">built</span><span class="plain-syntax"> [[</span><span class="identifier-syntax">Build</span><span class="plain-syntax"> </span><span class="identifier-syntax">Date</span><span class="plain-syntax">]]/\</span><span class="identifier-syntax">n</span><span class="string-syntax">");</span>
|
|
</pre>
|
|
<ul class="endnotetexts"><li>This code is used in <a href="6-cs.html#SP2">§2</a>.</li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP2_2" class="paragraph-anchor"></a><b>§2.2. </b>Having prudently opted to give the tags in an unsorted way, we're free to list
|
|
them in any order convenient to us, and here goes.
|
|
</p>
|
|
|
|
<p class="commentary">The <span class="extract"><span class="extract-syntax">more</span></span> field <span class="extract"><span class="extract-syntax">d</span></span> says that a tagname is a defined constant:
|
|
</p>
|
|
|
|
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">List defined constants</span><span class="named-paragraph-number">2.2</span></span><span class="comment-syntax"> =</span>
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">defined_constant</span><span class="plain-syntax"> *</span><span class="identifier-syntax">str</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER</span><span class="plain-syntax">(</span><span class="identifier-syntax">str</span><span class="plain-syntax">, </span><span class="reserved-syntax">defined_constant</span><span class="plain-syntax">)</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">str</span><span class="plain-syntax">-></span><span class="element-syntax">at</span><span class="plain-syntax">-></span><span class="element-syntax">owning_section</span><span class="plain-syntax">-></span><span class="element-syntax">owning_web</span><span class="plain-syntax"> == </span><span class="identifier-syntax">W</span><span class="plain-syntax">) {</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"%S\t"</span><span class="plain-syntax">, </span><span class="identifier-syntax">str</span><span class="plain-syntax">-></span><span class="element-syntax">name</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><a href="6-cs.html#SP3" class="function-link"><span class="function-syntax">Ctags::write_line_ref</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">str</span><span class="plain-syntax">-></span><span class="element-syntax">at</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">";\"\t"</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"d"</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\n"</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> }</span>
|
|
</pre>
|
|
<ul class="endnotetexts"><li>This code is used in <a href="6-cs.html#SP2">§2</a>.</li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP2_3" class="paragraph-anchor"></a><b>§2.3. </b>The <span class="extract"><span class="extract-syntax">more</span></span> field <span class="extract"><span class="extract-syntax">t</span></span> says that a tagname is a type, and we add a clarifying
|
|
detail to say that it results from a <span class="extract"><span class="extract-syntax">typedef struct</span></span>. (Note that <span class="extract"><span class="extract-syntax">typeref</span></span>
|
|
here, with an "r", is not a mistake. This is what Universal <span class="extract"><span class="extract-syntax">ctags</span></span> calls it.)
|
|
</p>
|
|
|
|
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">List structures</span><span class="named-paragraph-number">2.3</span></span><span class="comment-syntax"> =</span>
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">language_type</span><span class="plain-syntax"> *</span><span class="identifier-syntax">str</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER</span><span class="plain-syntax">(</span><span class="identifier-syntax">str</span><span class="plain-syntax">, </span><span class="reserved-syntax">language_type</span><span class="plain-syntax">)</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">str</span><span class="plain-syntax">-></span><span class="element-syntax">structure_header_at</span><span class="plain-syntax">-></span><span class="element-syntax">owning_section</span><span class="plain-syntax">-></span><span class="element-syntax">owning_web</span><span class="plain-syntax"> == </span><span class="identifier-syntax">W</span><span class="plain-syntax">) {</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"%S\t"</span><span class="plain-syntax">, </span><span class="identifier-syntax">str</span><span class="plain-syntax">-></span><span class="element-syntax">structure_name</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><a href="6-cs.html#SP3" class="function-link"><span class="function-syntax">Ctags::write_line_ref</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">str</span><span class="plain-syntax">-></span><span class="element-syntax">structure_header_at</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">";\"\t"</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"t\ttyperef:struct:%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">str</span><span class="plain-syntax">-></span><span class="element-syntax">structure_name</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\n"</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> }</span>
|
|
</pre>
|
|
<ul class="endnotetexts"><li>This code is used in <a href="6-cs.html#SP2">§2</a>.</li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP2_4" class="paragraph-anchor"></a><b>§2.4. </b>The <span class="extract"><span class="extract-syntax">more</span></span> field <span class="extract"><span class="extract-syntax">f</span></span> says that a tagname is a function:
|
|
</p>
|
|
|
|
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">List functions</span><span class="named-paragraph-number">2.4</span></span><span class="comment-syntax"> =</span>
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">language_function</span><span class="plain-syntax"> *</span><span class="identifier-syntax">fn</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="reserved-syntax">language_function</span><span class="plain-syntax">)</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">fn</span><span class="plain-syntax">-></span><span class="element-syntax">function_header_at</span><span class="plain-syntax">-></span><span class="element-syntax">owning_section</span><span class="plain-syntax">-></span><span class="element-syntax">owning_web</span><span class="plain-syntax"> == </span><span class="identifier-syntax">W</span><span class="plain-syntax">) {</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"%S\t"</span><span class="plain-syntax">, </span><span class="identifier-syntax">fn</span><span class="plain-syntax">-></span><span class="element-syntax">function_name</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><a href="6-cs.html#SP3" class="function-link"><span class="function-syntax">Ctags::write_line_ref</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">fn</span><span class="plain-syntax">-></span><span class="element-syntax">function_header_at</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">";\"\t"</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"f"</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\n"</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> }</span>
|
|
</pre>
|
|
<ul class="endnotetexts"><li>This code is used in <a href="6-cs.html#SP2">§2</a>.</li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>§3. </b>So, then, here we write the <span class="extract"><span class="extract-syntax">filename</span></span> and <span class="extract"><span class="extract-syntax">find</span></span> fields for a given
|
|
source line <span class="extract"><span class="extract-syntax">L</span></span> in our web. Note that:
|
|
</p>
|
|
|
|
<ul class="items"><li>(a) The filename must be given relative to the directory containing the tags
|
|
file, so for us that will be the home directory of the web.
|
|
</li><li>(b) The <span class="extract"><span class="extract-syntax">find</span></span> field looks like a regular expression but is not one, despite
|
|
the suggestive positional markers <span class="extract"><span class="extract-syntax">^</span></span> and <span class="extract"><span class="extract-syntax">$</span></span>. Note in particular that round
|
|
brackets and asterisk characters are not escaped, as they would be in a regex.
|
|
The Ctags documentation is vague here but does note that <span class="extract"><span class="extract-syntax">^</span></span> and <span class="extract"><span class="extract-syntax">$</span></span> should
|
|
be escaped only where they occur in the first or last positions. Tabs do
|
|
not need to be escaped.
|
|
</li></ul>
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Ctags::write_line_ref</span><button class="popup" onclick="togglePopup('usagePopup2')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup2">Usage of <span class="code-font"><span class="function-syntax">Ctags::write_line_ref</span></span>:<br/><a href="6-cs.html#SP2_2">§2.2</a>, <a href="6-cs.html#SP2_3">§2.3</a>, <a href="6-cs.html#SP2_4">§2.4</a></span></button><span class="plain-syntax">(</span><span class="constant-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">L</span><span class="plain-syntax">, </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">) {</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">)</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="string-syntax">"%f"</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">-></span><span class="element-syntax">owning_section</span><span class="plain-syntax">-></span><span class="element-syntax">md</span><span class="plain-syntax">-></span><span class="element-syntax">source_file_for_section</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/1-wp.html#SP4" class="function-link"><span class="function-syntax">Platform::is_folder_separator</span></a><span class="plain-syntax">(</span><a href="../foundation-module/4-sm.html#SP13" class="function-link"><span class="function-syntax">Str::get_first_char</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">)) == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">) {</span>
|
|
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP15" class="function-link"><span class="function-syntax">Str::clear</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><a href="../foundation-module/3-fln.html#SP5" class="function-link"><span class="function-syntax">Filenames::to_text_relative</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">-></span><span class="element-syntax">owning_section</span><span class="plain-syntax">-></span><span class="element-syntax">md</span><span class="plain-syntax">-></span><span class="element-syntax">source_file_for_section</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> }</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"%S\t/^"</span><span class="plain-syntax">, </span><span class="identifier-syntax">fn</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">)</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">i</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">; </span><span class="identifier-syntax">i</span><span class="plain-syntax"> < </span><a href="../foundation-module/4-sm.html#SP8" class="function-link"><span class="function-syntax">Str::len</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">L</span><span class="plain-syntax">-></span><span class="element-syntax">text</span><span class="plain-syntax">); </span><span class="identifier-syntax">i</span><span class="plain-syntax">++) {</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">wchar_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">c</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP13" class="function-link"><span class="function-syntax">Str::get_at</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">L</span><span class="plain-syntax">-></span><span class="element-syntax">text</span><span class="plain-syntax">, </span><span class="identifier-syntax">i</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">switch</span><span class="plain-syntax"> (</span><span class="identifier-syntax">c</span><span class="plain-syntax">) {</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="character-syntax">'/'</span><span class="plain-syntax">: </span><span class="identifier-syntax">PUT</span><span class="plain-syntax">(</span><span class="character-syntax">'\\'</span><span class="plain-syntax">); </span><span class="identifier-syntax">PUT</span><span class="plain-syntax">(</span><span class="identifier-syntax">c</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="character-syntax">'^'</span><span class="plain-syntax">: </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">i</span><span class="plain-syntax"> == </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">PUT</span><span class="plain-syntax">(</span><span class="character-syntax">'\\'</span><span class="plain-syntax">); </span><span class="identifier-syntax">PUT</span><span class="plain-syntax">(</span><span class="identifier-syntax">c</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="character-syntax">'$'</span><span class="plain-syntax">: </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">i</span><span class="plain-syntax"> < </span><a href="../foundation-module/4-sm.html#SP8" class="function-link"><span class="function-syntax">Str::len</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">L</span><span class="plain-syntax">-></span><span class="element-syntax">text</span><span class="plain-syntax">) - </span><span class="constant-syntax">1</span><span class="plain-syntax">) </span><span class="identifier-syntax">PUT</span><span class="plain-syntax">(</span><span class="character-syntax">'\\'</span><span class="plain-syntax">); </span><span class="identifier-syntax">PUT</span><span class="plain-syntax">(</span><span class="identifier-syntax">c</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">default:</span><span class="plain-syntax"> </span><span class="identifier-syntax">PUT</span><span class="plain-syntax">(</span><span class="identifier-syntax">c</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> }</span>
|
|
<span class="plain-syntax"> }</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"$/"</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax">}</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>§4. </b>To make the above work, we need to keep a list of defined constant names.
|
|
We could laboriously extract that from the hash table of reserved words
|
|
(see <a href="3-ta.html" class="internal">The Analyser</a>), but this is one of those times when life is short and
|
|
memory is cheap. It's easier to keep a duplicate list.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">defined_constant</span><span class="plain-syntax"> {</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">at</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> </span><span class="constant-syntax">CLASS_DEFINITION</span>
|
|
<span class="plain-syntax">} </span><span class="reserved-syntax">defined_constant</span><span class="plain-syntax">;</span>
|
|
</pre>
|
|
<ul class="endnotetexts"><li>The structure defined_constant is accessed in 2/trs, 1/apacs, 5/wt, 6/rw, 6/cln and here.</li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>§5. </b>This is called for any <span class="extract"><span class="extract-syntax">@d</span></span> or <span class="extract"><span class="extract-syntax">@e</span></span> constant name, then:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Ctags::note_defined_constant</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">Ctags::note_defined_constant</span></span>:<br/>The Parser - <a href="2-tp.html#SP1_1_7_5_1_6">§1.1.7.5.1.6</a>, <a href="2-tp.html#SP1_1_7_5_1_7">§1.1.7.5.1.7</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">L</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">defined_constant</span><span class="plain-syntax"> *</span><span class="identifier-syntax">dc</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">defined_constant</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">dc</span><span class="plain-syntax">-></span><span class="element-syntax">name</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">dc</span><span class="plain-syntax">-></span><span class="element-syntax">at</span><span class="plain-syntax"> = </span><span class="identifier-syntax">L</span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax">}</span>
|
|
</pre>
|
|
<nav role="progress"><div class="progresscontainer">
|
|
<ul class="progressbar"><li class="progressprev"><a href="6-gs.html">❮</a></li><li class="progresschapter"><a href="M-iti.html">M</a></li><li class="progresschapter"><a href="P-htpw.html">P</a></li><li class="progresschapter"><a href="1-bsc.html">1</a></li><li class="progresschapter"><a href="2-tr.html">2</a></li><li class="progresschapter"><a href="3-ta.html">3</a></li><li class="progresschapter"><a href="4-pl.html">4</a></li><li class="progresschapter"><a href="5-wt.html">5</a></li><li class="progresscurrentchapter">6</li><li class="progresssection"><a href="6-mkf.html">mkf</a></li><li class="progresssection"><a href="6-gs.html">gs</a></li><li class="progresscurrent">cs</li><li class="progresssection"><a href="6-rw.html">rw</a></li><li class="progresssection"><a href="6-cln.html">cln</a></li><li class="progressnext"><a href="6-rw.html">❯</a></li></ul></div>
|
|
</nav><!--End of weave-->
|
|
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|