-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/html4/transitional.dtd">
-<html>
-<head>
+<!-- Effective Go -->
<!-- interfaces; slices; embedding; value vs. pointer receivers; methods on anything; errors; testing -->
- <meta http-equiv="content-type" content="text/html; charset=utf-8">
- <title>Effective Go</title>
-
- <link rel="stylesheet" type="text/css" href="style.css">
- <script type="text/javascript" src="godocs.js"></script>
-
-<style type="text/css">
-pre.bad {
- background-color: #ffeeee;
-}
-</style>
-
-</head>
-
-
-<body> <!-- onload="prettyPrint()" will color the programs -->
-
-<div id="topnav">
-<table summary=""><tr>
-<td id="headerImage">
-<a href="./"><img src="./logo_blue.png" height="44" width="120" alt="Go Home Page" style="border:0" /></a>
-</td>
-<td id="headerDocSetTitle">The Go Programming Language</td>
-</tr>
-</table>
-</div>
-
-<div id="linkList" style="clear:both">
- <ul>
- <li class="navhead">Related Guides</li>
- <li><a href="go_spec.html">Language Specification</a></li>
- <li><a href="go_mem.html">Memory Model</a></li>
- <li><a href="go_tutorial.html">Tutorial</a></li>
- <li><a href="effective_go.html">Effective Go</a></li>
- <li class="blank"> </li>
- <li class="navhead">Other Resources</li>
- <li><a href="go_faq.html">FAQ</a></li>
- <li><a href="go_lang_faq.html">Language Design FAQ</a></li>
- <li><a href="go_for_cpp_programmers.html">Go for C++ Programmers</a></li>
- <li class="blank"> </li>
- <li class="navhead">Home</li>
- <li><a href="/">Go documentation home</a></li>
- </ul>
-</div>
-
-<div id="content">
-
-<h1 id="effective_go">Effective Go</h1>
-
-
- <!-- The Table of Contents is automatically inserted in this <div>.
- Do not delete this <div>. -->
- <div id="nav"></div>
-
<h2 id="introduction">Introduction</h2>
<p>
<h2>Commentary</h2>
<p>
-Go provides C-style <code>/* */</code> block comments
+Go provides C-style <code>/* */</code> block comments
and C++-style <code>//</code> line comments.
Line comments are the norm;
block comments appear mostly as package comments and
used as regular variables, just like the incoming parameters.
When named, they are initialized to the zero for their type when
the function begins; if the function executes a <code>return</code> statement
-with no arguments, the current values of the result parameters are
+with no arguments, the current values of the result parameters are
used as the returned values.
</p>
A slice, for example, is a three-item descriptor
containing a pointer to the data (inside an array), the length, and the
capacity; until those items are initialized, the slice is <code>nil</code>.
-For slices, maps, and channels,
+For slices, maps, and channels,
<code>make</code> initializes the internal data structure and prepares
the value for use.
For instance,
Especially in libraries, functions tend to have multiple error modes.
Instead of returning a boolean to signal success,
return an <code>os.Error</code> that describes the failure.
-Even if there is only one failure mode now,
+Even if there is only one failure mode now,
there may be more later.
</p>
<p>
The <code>reflect.DeepEqual</code> function tests
whether two complex data structures have equal values.
-If a function returns a complex data structure,
+If a function returns a complex data structure,
<code>reflect.DeepEqual</code> combined with table-driven testing
-makes it easy to check that the return value is
+makes it easy to check that the return value is
exactly as expected.
</p>
</p>
-->
-
-</div>
-</body>
-</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/html4/transitional.dtd">
-<html>
-<head>
-
-<!--
-To convert <h2>Foo</h2> into <h2 id="Foo">Foo</h2>
-and convert §Foo into §<a href="#Foo">Foo</a>:
-
- Edit ,s/<(h.)>(.*)(<\/h.>)/<\1 id="\2">\2\3/g
- Edit ,x g/id="/ x/id="[^"]+"/ s/ /_/g
- Edit ,s/§([^),.]+)/§<a href="#\1">\1<\/a>/g
- Edit ,x/href="#[^"]+"/ s/ /_/g
--->
-
- <meta http-equiv="content-type" content="text/html; charset=utf-8">
- <title>Go For C++ Programmers</title>
-
- <link rel="stylesheet" type="text/css" href="style.css">
- <script type="text/javascript" src="godocs.js"></script>
-
-</head>
-
-<body>
-
-<div id="topnav">
-<table summary=""><tr>
-<td id="headerImage">
-<a href="./"><img src="./logo_blue.png" height="44" width="120" alt="Go Home Page" style="border:0" /></a>
-</td>
-<td id="headerDocSetTitle">The Go Programming Language</td>
-</tr>
-</table>
-</div>
-
-<div id="linkList">
- <ul>
- <li class="navhead">Related Guides</li>
- <li><a href="go_spec.html">Language Specification</a></li>
- <li><a href="go_mem.html">Memory Model</a></li>
- <li><a href="go_tutorial.html">Tutorial</a></li>
- <li><a href="effective_go.html">Effective Go</a></li>
- <li class="blank"> </li>
- <li class="navhead">Other Resources</li>
- <li><a href="go_faq.html">FAQ</a></li>
- <li><a href="go_lang_faq.html">Language Design FAQ</a></li>
- <li><a href="go_for_cpp_programmers.html">Go for C++ Programmers</a></li>
- <li class="blank"> </li>
- <li class="navhead">Home</li>
- <li><a href="/">Go documentation home</a></li>
- </ul>
-</div>
-
-<div id="content">
-
-<h1 id="The_Go_Programming_Language_Specification">Go For C++ Programmers</h1>
+<!-- Go For C++ Programmers -->
<p>
Go is a systems programming language intended as an alternative to C++.
<p>
There is more <a href="./">documentation about go</a>.
-
- <!-- The Table of Contents is automatically inserted in this <div>.
- Do not delete this <div>. -->
- <div id="nav"></div>
-
<h2 id="Conceptual_Differences">Conceptual Differences</h2>
<ul>
return <- my_ch;
}
</pre>
-
-</div>
-
-<div id="footer">
-<p>Except as noted, this content is
- licensed under <a href="http://creativecommons.org/licenses/by/3.0/">
- Creative Commons Attribution 3.0</a>.
-</div>
-
-</body>
-</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/html4/transitional.dtd">
-<html>
-<head>
-
- <meta http-equiv="content-type" content="text/html; charset=utf-8">
- <title>The Go Programming Language Design FAQ</title>
-
- <link rel="stylesheet" type="text/css" href="style.css">
- <script type="text/javascript" src="godocs.js"></script>
-
-</head>
-
-<body>
-
-<div id="topnav">
-<table summary=""><tr>
-<td id="headerImage">
-<a href="./"><img src="./logo_blue.png" height="44" width="120" alt="Go Home Page" style="border:0" /></a>
-</td>
-<td id="headerDocSetTitle">The Go Programming Language</td>
-</tr>
-</table>
-</div>
-
-<div id="linkList">
- <ul>
- <li class="navhead">Related Guides</li>
- <li><a href="go_spec.html">Language Specification</a></li>
- <li><a href="go_mem.html">Memory Model</a></li>
- <li><a href="go_tutorial.html">Tutorial</a></li>
- <li><a href="effective_go.html">Effective Go</a></li>
- <li class="blank"> </li>
- <li class="navhead">Other Resources</li>
- <li><a href="go_faq.html">FAQ</a></li>
- <li><a href="go_lang_faq.html">Language Design FAQ</a></li>
- <li><a href="go_for_cpp_programmers.html">Go for C++ Programmers</a></li>
- <li class="blank"> </li>
- <li class="navhead">Home</li>
- <li><a href="/">Go documentation home</a></li>
- </ul>
-</div>
-
-<div id="content">
-
-<h1 id="The_Go_Programming_Language_Design_FAQ">The Go Programming Language Design FAQ</h1>
-
-
- <!-- The Table of Contents is automatically inserted in this <div>.
- Do not delete this <div>. -->
- <div id="nav"></div>
+<!-- The Go Programming Language Design FAQ -->
<h2 id="origins">Origins</h2>
make vs new
</pre>
-
-
-</div>
-
-<div id="footer">
-<p>Except as noted, this content is
- licensed under <a href="http://creativecommons.org/licenses/by/3.0/">
- Creative Commons Attribution 3.0</a>.
-</div>
-
-</body>
-</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/html4/transitional.dtd">
-<html>
-<head>
-
-<!--
-To convert <h2>Foo</h2> into <h2 id="Foo">Foo</h2>
-and convert §Foo into §<a href="#Foo">Foo</a>:
-
- Edit ,s/<(h.)>(.*)(<\/h.>)/<\1 id="\2">\2\3/g
- Edit ,x g/id="/ x/id="[^"]+"/ s/ /_/g
- Edit ,s/§([^),.]+)/§<a href="#\1">\1<\/a>/g
- Edit ,x/href="#[^"]+"/ s/ /_/g
--->
-
- <meta http-equiv="content-type" content="text/html; charset=utf-8">
- <title>The Go Memory Model</title>
-
- <link rel="stylesheet" type="text/css" href="style.css">
- <script type="text/javascript" src="godocs.js"></script>
-
-</head>
-
-<body>
-
-<div id="topnav">
-<table summary=""><tr>
-<td id="headerImage">
-<a href="./"><img src="./logo_blue.png" height="44" width="120" alt="Go Home Page" style="border:0" /></a>
-</td>
-<td id="headerDocSetTitle">The Go Programming Language</td>
-</tr>
-</table>
-</div>
-
-<div id="linkList">
- <ul>
- <li class="navhead">Related Guides</li>
- <li><a href="go_spec.html">Language Specification</a></li>
- <li><a href="go_mem.html">Memory Model</a></li>
- <li><a href="go_tutorial.html">Tutorial</a></li>
- <li><a href="effective_go.html">Effective Go</a></li>
- <li class="blank"> </li>
- <li class="navhead">Other Resources</li>
- <li><a href="go_faq.html">FAQ</a></li>
- <li><a href="go_lang_faq.html">Language Design FAQ</a></li>
- <li><a href="go_for_cpp_programmers.html">Go for C++ Programmers</a></li>
- <li class="blank"> </li>
- <li class="navhead">Home</li>
- <li><a href="/">Go documentation home</a></li>
- </ul>
-</div>
-
-<div id="content">
-
-<h1 id="The_Go_Programming_Language_Specification">The Go Memory Model</h1>
-
-
- <!-- The Table of Contents is automatically inserted in this <div>.
- Do not delete this <div>. -->
- <div id="nav"></div>
+<!-- The Go Memory Model -->
<h2>Introduction</h2>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/html4/transitional.dtd">
-<html>
-<head>
-
-<!--
-To convert <h2>Foo</h2> into <h2 id="Foo">Foo</h2>
-and convert §Foo into §<a href="#Foo">Foo</a>:
-
- Edit ,s/<(h.)>(.*)(<\/h.>)/<\1 id="\2">\2\3/g
- Edit ,x g/id="/ x/id="[^"]+"/ s/ /_/g
- Edit ,s/§([^),.]+)/§<a href="#\1">\1<\/a>/g
- Edit ,x/href="#[^"]+"/ s/ /_/g
--->
-
- <meta http-equiv="content-type" content="text/html; charset=utf-8">
- <title>The Go Programming Language Specification</title>
-
- <link rel="stylesheet" type="text/css" href="style.css">
- <script type="text/javascript" src="godocs.js"></script>
-
-</head>
-
-<body>
-
-<div id="topnav">
-<table summary=""><tr>
-<td id="headerImage">
-<a href="./"><img src="./logo_blue.png" height="44" width="120" alt="Go Home Page" style="border:0" /></a>
-</td>
-<td id="headerDocSetTitle">The Go Programming Language</td>
-</tr>
-</table>
-</div>
-
-<div id="linkList" style="clear:both">
- <ul>
- <li class="navhead">Related Guides</li>
- <li><a href="go_spec.html">Language Specification</a></li>
- <li><a href="go_mem.html">Memory Model</a></li>
- <li><a href="go_tutorial.html">Tutorial</a></li>
- <li><a href="effective_go.html">Effective Go</a></li>
- <li class="blank"> </li>
- <li class="navhead">Other Resources</li>
- <li><a href="go_faq.html">FAQ</a></li>
- <li><a href="go_lang_faq.html">Language Design FAQ</a></li>
- <li><a href="go_for_cpp_programmers.html">Go for C++ Programmers</a></li>
- <li class="blank"> </li>
- <li class="navhead">Home</li>
- <li><a href="/">Go documentation home</a></li>
- </ul>
-</div>
-
-<div id="content">
-
-<h1 id="The_Go_Programming_Language_Specification">The Go Programming Language Specification</h1>
-
-
- <!-- The Table of Contents is automatically inserted in this <div>.
- Do not delete this <div>. -->
- <div id="nav"></div>
+<!-- The Go Programming Language Specification -->
<!--
Todo
<li><font color=red>Gccgo does not implement the blank identifier.</font></li>
<li><font color=red>Method expressions are not implemented.</font></li>
</ul>
-
-</div>
-
-<div id="footer">
-<p>Except as noted, this content is
- licensed under <a href="http://creativecommons.org/licenses/by/3.0/">
- Creative Commons Attribution 3.0</a>.
-</div>
-
-</body>
-</html>
-<div id="content">
-<h1 id="Lets_Go">Let's Go</h1>
-
- <!-- The Table of Contents is automatically inserted in this <div>.
- Do not delete this <div>. -->
- <div id="nav"></div>
+<!-- Let's Go -->
<h2>Introduction</h2>
-<h1 id="Lets_Go">Let's Go</h1>
-
- <!-- The Table of Contents is automatically inserted in this <div>.
- Do not delete this <div>. -->
- <div id="nav"></div>
+<!-- Let's Go -->
<h2>Introduction</h2>
<p>
% helloworld3
hello, world
can't open file; err=No such file or directory
- %
+ %
</pre>
<h2>Rotting cats</h2>
abcdefghijklmnopqrstuvwxyz
% echo abcdefghijklmnopqrstuvwxyz | ./cat --rot13
nopqrstuvwxyzabcdefghijklm
- %
+ %
</pre>
<p>
Fans of dependency injection may take cheer from how easily interfaces
There's a lot more to Go programming and concurrent programming in general but this
quick tour should give you some of the basics.
</table>
-</body>
-</html>
license that can be found in the LICENSE file.
-->
-{.section Dirs}
- <h2>Subdirectories</h2>
- {.repeated section @}
- <a href="{Name|html}">{Name|html}</a><br />
- {.end}
-{.end}
{.section PDoc}
- <h1>package {PackageName|html}</h1>
+ <!-- PackageName is printed as title by the top-level template -->
<p><code>import "{ImportPath|html}"</code></p>
{Doc|html-comment}
{.section Filenames}
{.end}
{.end}
{.end}
+{.section Dirs}
+ <h2>Subdirectories</h2>
+ {.repeated section @}
+ <a href="{Name|html}">{Name|html}</a><br />
+ {.end}
+{.end}
-{.section Dirs}
-SUBDIRECTORIES
-{.repeated section @}
- {Name}
-{.end}
-
-{.end}
{.section PDoc}
PACKAGE
{.end}
{.end}
{.end}
+{.section Dirs}
+
+SUBDIRECTORIES
+
+{.repeated section @}
+ {Name}
+{.end}
+{.end}
license that can be found in the LICENSE file.
-->
-<h1>Parse errors in {filename}</h1>
<pre>
{.repeated section list}
-{src}{.section msg}<b><font color=red>«{msg|html}»</font></b>{.end}{.end}</pre>
+{src}{.section msg}<b><font color=red>«{msg|html}»</font></b>{.end}{.end}
+</pre>
)
-const (
- Pkg = "/pkg/"; // name for auto-generated package documentation tree
- Spec = "/doc/go_spec.html";
-)
+const Pkg = "/pkg/"; // name for auto-generated package documentation tree
type delayTime struct {
func parse(path string, mode uint) (*ast.File, *parseErrors) {
src, err := io.ReadFile(path);
if err != nil {
- log.Stderrf("ReadFile %s: %v", path, err);
+ log.Stderrf("%v", err);
errs := []parseError{parseError{nil, 0, err.String()}};
return nil, &parseErrors{path, errs, nil};
}
func servePage(c *http.Conn, title, content interface{}) {
type Data struct {
title interface{};
- header interface{};
timestamp string;
content interface{};
}
- var d Data;
- d.title = title;
- d.header = title;
- d.timestamp = time.SecondsToLocalTime(syncTime.get()).String();
- d.content = content;
+ d := Data{
+ title: title,
+ timestamp: time.SecondsToLocalTime(syncTime.get()).String(),
+ content: content,
+ };
+
if err := godocHtml.Execute(&d, c); err != nil {
log.Stderrf("godocHtml.Execute: %s", err);
}
// ----------------------------------------------------------------------------
// Files
+var (
+ tagBegin = strings.Bytes("<!--");
+ tagEnd = strings.Bytes("-->");
+)
+
+// commentText returns the text of the first HTML comment in src.
+func commentText(src []byte) (text string) {
+ i := bytes.Index(src, tagBegin);
+ j := bytes.Index(src, tagEnd);
+ if i >= 0 && j >= i+len(tagBegin) {
+ text = string(bytes.TrimSpace(src[i+len(tagBegin) : j]));
+ }
+ return;
+}
+
+
+func serveHtmlDoc(c *http.Conn, r *http.Request, filename string) {
+ // get HTML body contents
+ path := pathutil.Join(goroot, filename);
+ src, err := io.ReadFile(path);
+ if err != nil {
+ log.Stderrf("%v", err);
+ http.NotFound(c, r);
+ return;
+ }
+
+ // if it's the language spec, add tags to EBNF productions
+ if strings.HasSuffix(path, "go_spec.html") {
+ var buf bytes.Buffer;
+ linkify(&buf, src);
+ src = buf.Bytes();
+ }
+
+ title := commentText(src);
+ servePage(c, title, src);
+}
+
+
func serveParseErrors(c *http.Conn, errors *parseErrors) {
// format errors
var buf bytes.Buffer;
if err := parseerrorHtml.Execute(errors, &buf); err != nil {
log.Stderrf("parseerrorHtml.Execute: %s", err);
}
- servePage(c, errors.filename + " - Parse Errors", buf.Bytes());
+ servePage(c, "Parse errors in source file " + errors.filename, buf.Bytes());
}
-func serveGoSource(c *http.Conn, name string) {
- prog, errors := parse(name, parser.ParseComments);
+func serveGoSource(c *http.Conn, filename string) {
+ path := pathutil.Join(goroot, filename);
+ prog, errors := parse(path, parser.ParseComments);
if errors != nil {
serveParseErrors(c, errors);
return;
writeNode(&buf, prog, true);
fmt.Fprintln(&buf, "</pre>");
- servePage(c, name + " - Go source", buf.Bytes());
-}
-
-
-func serveGoSpec(c *http.Conn, r *http.Request) {
- src, err := io.ReadFile(pathutil.Join(goroot, Spec));
- if err != nil {
- http.NotFound(c, r);
- return;
- }
- linkify(c, src);
+ servePage(c, "Source file " + filename, buf.Bytes());
}
var fileServer = http.FileServer(".", "");
-func serveFile(c *http.Conn, req *http.Request) {
+func serveFile(c *http.Conn, r *http.Request) {
+ path := r.Url.Path;
+
// pick off special cases and hand the rest to the standard file server
- switch {
- case req.Url.Path == "/":
- // serve landing page.
- // TODO: hide page from ordinary file serving.
- // writing doc/index.html will take care of that.
- http.ServeFile(c, req, "doc/root.html");
+ switch ext := pathutil.Ext(path); {
+ case path == "/":
+ serveHtmlDoc(c, r, "doc/root.html");
- case req.Url.Path == "/doc/root.html":
+ case r.Url.Path == "/doc/root.html":
// hide landing page from its real name
- // TODO why - there is no reason for this (remove eventually)
- http.NotFound(c, req);
+ http.NotFound(c, r);
+
+ case ext == ".html":
+ serveHtmlDoc(c, r, path);
- case pathutil.Ext(req.Url.Path) == ".go":
- serveGoSource(c, req.Url.Path[1 : len(req.Url.Path)]); // strip leading '/' from name
+ case ext == ".go":
+ serveGoSource(c, path);
default:
- // TODO not good enough - don't want to download files
- // want to see them
- fileServer.ServeHTTP(c, req);
+ // TODO:
+ // - need to decide what to serve and what not to serve
+ // - don't want to download files, want to see them
+ fileServer.ServeHTTP(c, r);
}
}
// get package AST
pkg, err := parser.ParsePackage(dirname, filter, parser.ParseComments);
if err != nil {
+ // TODO: parse errors should be shown instead of an empty directory
log.Stderr(err);
}
if path == "" {
path = "."; // don't display an empty path
}
- servePage(c, path + " - Go package documentation", buf.Bytes());
+ title := "Directory " + path;
+ if info.PDoc != nil {
+ title = "Package " + info.PDoc.PackageName;
+ }
+
+ servePage(c, title, buf.Bytes());
}
handler = loggingHandler(handler);
}
- http.Handle(Spec, http.HandlerFunc(serveGoSpec));
http.Handle(Pkg, http.HandlerFunc(servePkg));
if *syncCmd != "" {
http.Handle("/debug/sync", http.HandlerFunc(dosync));