|
|
<codewalk title="How to Write a Codewalk">
|
|
|
|
|
|
<step title="Introduction" src="doc/codewalk/codewalk.xml">
|
|
|
A codewalk is a guided tour through a piece of code.
|
|
|
It consists of a sequence of steps, each typically explaining
|
|
|
a highlighted section of code.
|
|
|
<br/><br/>
|
|
|
|
|
|
The <a href="/cmd/godoc">godoc</a> web server translates
|
|
|
an XML file like the one in the main window pane into the HTML
|
|
|
page that you're viewing now.
|
|
|
<br/><br/>
|
|
|
|
|
|
The codewalk with URL path <code>/doc/codewalk/</code><i>name</i>
|
|
|
is loaded from the input file <code>$GOROOT/doc/codewalk/</code><i>name</i><code>.xml</code>.
|
|
|
<br/><br/>
|
|
|
|
|
|
This codewalk explains how to write a codewalk by examining
|
|
|
its own source code,
|
|
|
<code><a href="/doc/codewalk/codewalk.xml">$GOROOT/doc/codewalk/codewalk.xml</a></code>,
|
|
|
shown in the main window pane to the left.
|
|
|
</step>
|
|
|
|
|
|
<step title="Title" src="doc/codewalk/codewalk.xml:/title=/">
|
|
|
The codewalk input file is an XML file containing a single
|
|
|
<code><codewalk></code> element.
|
|
|
That element's <code>title</code> attribute gives the title
|
|
|
that is used both on the codewalk page and in the codewalk list.
|
|
|
</step>
|
|
|
|
|
|
<step title="Steps" src="doc/codewalk/codewalk.xml:/<step/,/step>/">
|
|
|
Each step in the codewalk is a <code><step></code> element
|
|
|
nested inside the main <code><codewalk></code>.
|
|
|
The step element's <code>title</code> attribute gives the step's title,
|
|
|
which is shown in a shaded bar above the main step text.
|
|
|
The element's <code>src</code> attribute specifies the source
|
|
|
code to show in the main window pane and, optionally, a range of
|
|
|
lines to highlight.
|
|
|
<br/><br/>
|
|
|
|
|
|
The first step in this codewalk does not highlight any lines:
|
|
|
its <code>src</code> is just a file name.
|
|
|
</step>
|
|
|
|
|
|
<step title="Specifying a source line" src='doc/codewalk/codewalk.xml:/title="Title"/'>
|
|
|
The most complex part of the codewalk specification is
|
|
|
saying what lines to highlight.
|
|
|
Instead of ordinary line numbers,
|
|
|
the codewalk uses an address syntax that makes it possible
|
|
|
to describe the match by its content.
|
|
|
As the file gets edited, this descriptive address has a better
|
|
|
chance to continue to refer to the right section of the file.
|
|
|
<br/><br/>
|
|
|
|
|
|
To specify a source line, use a <code>src</code> attribute of the form
|
|
|
<i>filename</i><code>:</code><i>address</i>,
|
|
|
where <i>address</i> is an address in the syntax used by the text editors <i>sam</i> and <i>acme</i>.
|
|
|
<br/><br/>
|
|
|
|
|
|
The simplest address is a single regular expression.
|
|
|
The highlighted line in the main window pane shows that the
|
|
|
address for the “Title” step was <code>/title=/</code>,
|
|
|
which matches the first instance of that <a href="/pkg/regexp">regular expression</a> (<code>title=</code>) in the file.
|
|
|
</step>
|
|
|
|
|
|
<step title="Specifying a source range" src='doc/codewalk/codewalk.xml:/title="Steps"/'>
|
|
|
To highlight a range of source lines, the simplest address to use is
|
|
|
a pair of regular expressions
|
|
|
<code>/</code><i>regexp1</i><code>/,/</code><i>regexp2</i><code>/</code>.
|
|
|
The highlight begins with the line containing the first match for <i>regexp1</i>
|
|
|
and ends with the line containing the first match for <i>regexp2</i>
|
|
|
after the end of the match for <i>regexp1</i>.
|
|
|
Ignoring the HTML quoting,
|
|
|
The line containing the first match for <i>regexp1</i> will be the first one highlighted,
|
|
|
and the line containing the first match for <i>regexp2</i>.
|
|
|
<br/><br/>
|
|
|
|
|
|
The address <code>/<step/,/step>/</code> looks for the first instance of
|
|
|
<code><step</code> in the file, and then starting after that point,
|
|
|
looks for the first instance of <code>step></code>.
|
|
|
(Click on the “Steps” step above to see the highlight in action.)
|
|
|
Note that the <code><</code> and <code>></code> had to be written
|
|
|
using XML escapes in order to be valid XML.
|
|
|
</step>
|
|
|
|
|
|
<step title="Advanced addressing" src="doc/codewalk/codewalk.xml:/Advanced/,/step>/">
|
|
|
The <code>/</code><i>regexp</i><code>/</code>
|
|
|
and <code>/</code><i>regexp1</i><code>/,/</code><i>regexp2</i><code>/</code>
|
|
|
forms suffice for most highlighting.
|
|
|
<br/><br/>
|
|
|
|
|
|
The full address syntax is summarized in this table
|
|
|
(an excerpt of Table II from
|
|
|
<a href="https://9p.io/sys/doc/sam/sam.html">The text editor <code>sam</code></a>):
|
|
|
<br/><br/>
|
|
|
|
|
|
<table>
|
|
|
<tr><td colspan="2"><b>Simple addresses</b></td></tr>
|
|
|
<tr><td><code>#</code><i>n</i></td>
|
|
|
<td>The empty string after character <i>n</i></td></tr>
|
|
|
<tr><td><i>n</i></td>
|
|
|
<td>Line <i>n</i></td></tr>
|
|
|
<tr><td><code>/</code><i>regexp</i><code>/</code></td>
|
|
|
<td>The first following match of the regular expression</td></tr>
|
|
|
<!-- not supported (yet?)
|
|
|
<tr><td><code>–/</code><i>regexp</i><code>/</code></td>
|
|
|
<td>The first previous match of the regular expression</td></tr>
|
|
|
-->
|
|
|
<tr><td><code>$</code></td>
|
|
|
<td>The null string at the end of the file</td></tr>
|
|
|
|
|
|
<tr><td colspan="2"><b>Compound addresses</b></td></tr>
|
|
|
<tr><td><i>a1</i><code>+</code><i>a2</i></td>
|
|
|
<td>The address <i>a2</i> evaluated starting at the right of <i>a1</i></td></tr>
|
|
|
<tr><td><i>a1</i><code>-</code><i>a2</i></td>
|
|
|
<td>The address <i>a2</i> evaluated in the reverse direction starting at the left of <i>a1</i></td></tr>
|
|
|
<tr><td><i>a1</i><code>,</code><i>a2</i></td>
|
|
|
<td>From the left of <i>a1</i> to the right of <i>a2</i> (default <code>0,$</code>).</td></tr>
|
|
|
</table>
|
|
|
</step>
|
|
|
|
|
|
|
|
|
|
|
|
</codewalk>
|
