summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/devel/release.html107
-rw-r--r--doc/devel/weekly.html220
-rw-r--r--doc/effective_go.html17
-rw-r--r--doc/go_mem.html5
-rw-r--r--doc/go_spec.html137
-rw-r--r--doc/go_tutorial.html1049
-rw-r--r--doc/go_tutorial.txt108
-rw-r--r--doc/gopher/appenginegopher.jpgbin0 -> 135882 bytes
-rw-r--r--doc/gopher/appenginegophercolor.jpgbin0 -> 162023 bytes
-rw-r--r--doc/gopher/appenginelogo.gifbin0 -> 2105 bytes
-rw-r--r--doc/htmlgen.go167
-rw-r--r--doc/install.html6
-rwxr-xr-xdoc/makehtml16
-rwxr-xr-xdoc/prog.sh72
-rw-r--r--doc/progs/file_windows.go89
-rwxr-xr-xdoc/progs/run7
-rw-r--r--doc/progs/sort.go36
-rw-r--r--doc/progs/sortmain.go4
18 files changed, 1290 insertions, 750 deletions
diff --git a/doc/devel/release.html b/doc/devel/release.html
index e1a1cabe5..feb433f14 100644
--- a/doc/devel/release.html
+++ b/doc/devel/release.html
@@ -14,6 +14,113 @@ hg pull
hg update release.r<i>NN</i>
</pre>
+<h2 id="r59">r59 (released 2011/08/01)</h2>
+
+<p>
+The r59 release corresponds to
+<code><a href="weekly.html#2011-07-07">weekly.2011-07-07</a></code>.
+This section highlights the most significant changes in this release.
+For a more detailed summary, see the
+<a href="weekly.html#2011-07-07">weekly release notes</a>.
+For complete information, see the
+<a href="http://code.google.com/p/go/source/list?r=release-branch.r59">Mercurial change list</a>.
+</p>
+
+<h3 id="r59.lang">Language</h3>
+
+<p>
+This release includes a language change that restricts the use of
+<code>goto</code>. In essence, a <code>goto</code> statement outside a block
+cannot jump to a label inside that block. Your code may require changes if it
+uses <code>goto</code>.
+See <a href="http://code.google.com/p/go/source/detail?r=dc6d3cf9279d">this
+changeset</a> for how the new rule affected the Go tree.
+</p>
+
+<h3 id="r59.pkg">Packages</h3>
+
+<p>
+As usual, <a href="/cmd/gofix/">gofix</a> will handle the bulk of the rewrites
+necessary for these changes to package APIs.
+</p>
+
+<p>
+<a href="/pkg/http">Package http</a> has a new
+<a href="/pkg/http/#FileSystem">FileSystem</a> interface that provides access
+to files. The <a href="/pkg/http/#FileServer">FileServer</a> helper now takes a
+<code>FileSystem</code> argument instead of an explicit file system root. By
+implementing your own <code>FileSystem</code> you can use the
+<code>FileServer</code> to serve arbitrary data.
+</p>
+
+<p>
+<a href="/pkg/os/">Package os</a>'s <code>ErrorString</code> type has been
+hidden. Most uses of <code>os.ErrorString</code> can be replaced with
+<a href="/pkg/os/#NewError">os.NewError</a>.
+</p>
+
+<p>
+<a href="/pkg/reflect/">Package reflect</a> supports a new struct tag scheme
+that enables sharing of struct tags between multiple packages.
+In this scheme, the tags must be of the form:
+</p>
+<pre>
+ `key:"value" key2:"value2"`
+</pre>
+<p>
+The <a href="/pkg/reflect/#StructField">StructField</a> type's Tag field now
+has type <a href="/pkg/reflect/#StructTag">StructTag</a>, which has a
+<code>Get</code> method. Clients of <a href="/pkg/json">json</a> and
+<a href="/pkg/xml">xml</a> will need to be updated. Code that says
+</p>
+<pre>
+ type T struct {
+ X int "name"
+ }
+</pre>
+<p>
+should become
+</p>
+<pre>
+ type T struct {
+ X int `json:"name"` // or `xml:"name"`
+ }
+</pre>
+<p>
+Use <a href="/cmd/govet/">govet</a> to identify struct tags that need to be
+changed to use the new syntax.
+</p>
+
+<p>
+<a href="/pkg/sort/">Package sort</a>'s <code>IntArray</code> type has been
+renamed to <a href="/pkg/sort/#IntSlice">IntSlice</a>, and similarly for
+<a href="/pkg/sort/#Float64Slice">Float64Slice</a> and
+<a href="/pkg/sort/#StringSlice">StringSlice</a>.
+</p>
+
+<p>
+<a href="/pkg/strings/">Package strings</a>'s <code>Split</code> function has
+itself been split into <a href="/pkg/strings/#Split">Split</a> and
+<a href="/pkg/strings/#SplitN">SplitN</a>.
+<code>SplitN</code> is the same as the old <code>Split</code>.
+The new <code>Split</code> is equivalent to <code>SplitN</code> with a final
+argument of -1.
+</p>
+
+<a href="/pkg/image/draw/">Package image/draw</a>'s
+<a href="/pkg/image/draw/#Draw">Draw</a> function now takes an additional
+argument, a compositing operator.
+If in doubt, use <a href="/pkg/image/draw/#Op">draw.Over</a>.
+</p>
+
+<h3 id="r59.cmd">Tools</h3>
+
+<p>
+<a href="/cmd/goinstall/">Goinstall</a> now installs packages and commands from
+arbitrary remote repositories (not just Google Code, Github, and so on).
+See the <a href="/cmd/goinstall/">goinstall documentation</a> for details.
+</p>
+
<h2 id="r58">r58 (released 2011/06/29)</h2>
<p>
diff --git a/doc/devel/weekly.html b/doc/devel/weekly.html
index b576a910d..0fb6483f4 100644
--- a/doc/devel/weekly.html
+++ b/doc/devel/weekly.html
@@ -14,6 +14,226 @@ hg pull
hg update weekly.<i>YYYY-MM-DD</i>
</pre>
+<h2 id="2011-07-07">2011-07-07 (<a href="release.html#r59">base for r59</a>)</h2>
+
+<pre>
+This weekly snapshot includes changes to the strings, http, reflect, json, and
+xml packages. Code that uses these packages will need changes. Most of these
+changes can be made automatically with gofix.
+
+The strings package's Split function has itself been split into Split and
+SplitN. SplitN is the same as the old Split. The new Split is equivalent to
+SplitN with a final argument of -1.
+
+The http package has a new FileSystem interface that provides access to files.
+The FileServer helper now takes a FileSystem argument instead of an explicit
+file system root. By implementing your own FileSystem you can use the
+FileServer to serve arbitrary data.
+
+The reflect package supports a new struct tag scheme that enables sharing of
+struct tags between multiple packages.
+In this scheme, the tags must be of the form:
+ key:"value" key2:"value2"
+reflect.StructField's Tag field now has type StructTag (a string type), which
+has method Get(key string) string that returns the associated value.
+Clients of json and xml will need to be updated. Code that says
+ type T struct {
+ X int "name"
+ }
+should become
+ type T struct {
+ X int `json:"name"` // or `xml:"name"`
+ }
+Use govet to identify struct tags that need to be changed to use the new syntax.
+
+Other changes:
+* 5l, 6l, 8l: drop use of ed during build.
+* asn1: support T61 and UTF8 string.
+* bufio: do not cache Read errors (thanks Graham Miller).
+* build: make version.bash aware of branches.
+* cgi: don't depend on CGI.pm for tests.
+* codereview: make --ignore_hgpatch_failure work again,
+ restrict sync to default branch.
+* crypto/openpgp: add ability to reserialize keys,
+ bug fix (thanks Gideon Jan-Wessel Redelinghuys).
+* crypto/tls: fix generate_cert.go.
+* crypto/x509: prevent chain cycles in Verify.
+* csv: new package.
+* doc: remove ed from apt-get package list.
+* docs: fold the prog.sh scripting from makehtml into htmlgen itself.
+* ebnflint: better handling of stdin.
+* exp/regexp/syntax: new experimental RE2-based regexp implementation.
+* exp/template: a new experimental templating package.
+* fmt: add SkipSpace to fmt's ScanState interface.
+* fmt: rename errno and error to err for doc consistency.
+* gc: avoid package name ambiguity in error messages,
+ fix package quoting logic,
+ fixes for Plan 9 (thanks Lucio De Re).
+* go/build: evaluate symlinks before comparing path to GOPATH.
+* gob: use exported fields in structs in the package documentation.
+* godoc: ignore directories that begin with '.',
+ search GOPATH for documentation.
+* gofix: os/signal, path/filepath, and sort fixes (thanks Robert Hencke),
+* goinstall: add support for generic hosts (thanks Julian Phillips),
+ only report successfully-installed packages to the dashboard,
+ try to access via https (thanks Yasuhiro Matsumoto).
+* gotest: add -test.benchtime and -test.cpu flags.
+* html: fixes and improvements (thanks Yasuhiro Matsumoto).
+* http/cgi: add Handler.Dir to specify working directory (thanks Yasuhiro Matsumoto).
+* http: add StripPrefix handler wrapper,
+ assume ContentLength 0 on GET requests,
+ better handling of 0-length Request.Body,
+ do TLS handshake explicitly before copying TLS state,
+ document that ServerConn and ClientConn are low-level,
+ make NewChunkedReader public (thanks Andrew Balholm),
+ respect Handlers setting Connection: close in their response.
+* image: more tests, Paletted.Opaque optimization.
+* io.WriteString: if the object has a WriteString method, use it (thanks Evan Shaw).
+* ld: elide the Go symbol table when using -s (thanks Anthony Martin).
+* ld: fix ELF strip by removing overlap of sections (thanks Gustavo Niemeyer).
+* mime/multipart: parse LF-delimited messages, not just CRLF.
+* mime: permit lower-case media type parameters (thanks Pascal S. de Kloe).
+* misc/dashboard: new features and improvements (not yet deployed).
+* misc/emacs: update list of builtins (thanks Quan Yong Zhai).
+* misc/vim: allow only utf-8 for file encoding (thanks Yasuhiro Matsumoto).
+* os: fix documentation for FileInfo.Name,
+ simplify WriteString,
+ use a different symbol from syscall in mkunixsignals.sh.
+* path/filepath: enable TestWalk to run on windows (thanks Alex Brainman).
+* reflect: add MethodByName,
+ allow Len on String values.
+* regexp: document that Regexp is thread-safe.
+* runtime/cgo: check for errors from pthread_create (thanks Albert Strasheim).
+* runtime: add Semacquire/Semrelease benchmarks,
+ improved Semacquire/Semrelease implementation,
+ windows/amd64 port (thanks Wei Guangjing).
+* sync: add fast path to Once,
+ improve Mutex to allow successive acquisitions,
+ new and improved benchmarks.
+* syscall: regenerate zerrors for darwin/linux/freebsd,
+ support for tty options in StartProcess (thanks Ken Rockot).
+* testing: make ResetTimer not start/stop the timer,
+ scale benchmark precision to 0.01ns if needed.
+* time: zero-pad two-digit years.
+* unicode/maketables: update debugging data.
+* windows: define and use syscall.Handle (thanks Wei Guangjing).
+* xml: add Marshal and MarshalIndent.
+</pre>
+
+<h2 id="2011-06-23">2011-06-23</h2>
+
+<pre>
+This release includes a language change that restricts the use of goto.
+In essence, a "goto" statement outside a block cannot jump to a label inside
+that block. Your code may require changes if it uses goto.
+This changeset shows how the new rule affected the Go tree:
+ http://code.google.com/p/go/source/detail?r=dc6d3cf9279d
+
+The os.ErrorString type has been hidden. If your code uses os.ErrorString it
+must be changed. Most uses of os.ErrorString can be replaced with os.NewError.
+
+Other changes:
+* 5c: do not use R9 and R10.
+* 8l: more fixes for Plan 9 (thanks Lucio De Re).
+* build: Make.ccmd: link with mach lib (thanks Joe Poirier).
+* build: exclude packages that fail on Plan 9 (thanks Anthony Martin).
+* cc: nit: silence comment warnings (thanks Dave Cheney).
+* codereview.py: note that hg change -d abandons a change list (thanks Robert Hencke).
+* crypto/openpgp: add ElGamal support.
+* doc/faq: add question about converting from []T to []interface{}.
+* doc: Effective Go: fix variadic function example (thanks Ben Lynn).
+* exec: LookPath should not search %PATH% for files like c:cmd.exe (thanks Alex Brainman),
+ add support for Plan 9 (thanks Anthony Martin),
+ better error message for windows LookPath (thanks Alex Brainman).
+* fmt: catch panics from calls to String etc.
+* gc: descriptive panic for nil pointer -> value method call,
+ implement goto restriction,
+ unsafe.Alignof, unsafe.Offsetof, unsafe.Sizeof now return uintptr.
+* go/build: include Import objects in Script Inputs.
+* godefs: rudimentary tests (thanks Robert Hencke).
+* goinstall: refactor and generalize repo handling code (thanks Julian Phillips),
+ temporarily use Makefiles by default (override with -make=false).
+* gopprof: update list of memory allocators.
+* http: add Server.ListenAndServeTLS,
+ buffer request.Write,
+ fix req.Cookie(name) with cookies in one header,
+ permit handlers to explicitly remove the Date header,
+ write Header keys with empty values.
+* image: basic test for the 16-bits-per-color-channel types.
+* io: clarify Read, ReadAt, Copy, Copyn EOF behavior.
+* ld: don't attempt to build dynamic sections unnecessarily (thanks Gustavo Niemeyer).
+* libmach: fix disassembly of FCMOVcc and FCOMI (thanks Anthony Martin),
+ fix tracing on linux (for cov) (thanks Anthony Martin).
+* mime: fix RFC references (thanks Pascal S. de Kloe).
+* misc/gobuilder: run make single-threaded on windows (thanks Alex Brainman).
+* misc/godashboard: Accept sub-directories for goinstall's report (thanks Yasuhiro Matsumoto).
+* nacl, tiny: remove vestiges (thanks Robert Hencke).
+* net, syscall: interface for windows (thanks Yasuhiro Matsumoto).
+* os: change Waitmsg String method to use pointer receiver (thanks Graham Miller).
+* runtime: don't use twice the memory with grsec-like kernels (thanks Gustavo Niemeyer),
+* spec: disallow goto into blocks.
+* sync: restore GOMAXPROCS during benchmarks.
+* syscall: add LSF support for linux (thanks Mikio Hara),
+ add socket control message support for darwin, freebsd, linux (thanks Mikio Hara),
+ add tty support to StartProcess (thanks Ken Rockot),
+ fix build for Sizeof change.
+* test: test of goto restrictions.
+* time: add support for Plan 9 (thanks Anthony Martin).
+</pre>
+
+<h2 id="2011-06-16">2011-06-16</h2>
+
+<pre>
+This release includes changes to the sort and image/draw packages that will
+require changes to client code.
+
+The sort.IntArray type has been renamed to IntSlice, and similarly for
+StringArray and Float64Array.
+
+The image/draw package’s Draw function now takes an additional argument,
+a compositing operator. If in doubt, use draw.Over.
+
+Other changes:
+* build: fix header files for Plan 9 (thanks Lucio De Re).
+* cgo: handle new Apple LLVM-based gcc from Xcode 4.2.
+* crypto/openpgp: add ability to encrypt and sign messages.
+* doc/gopher: add goggled gopher logo for App Engine.
+* doc: Update notes for 3-day Go course.
+* exec: make LookPath work when PATHEXT var not set on Windows (thanks Alex Brainman).
+* exp/regexp/syntax: syntax data structures, parser, escapes, character classes.
+* exp/template: lexical scanner for new template package.
+* fmt: debugging formats for characters: %+q %#U.
+* gc: frame compaction for arm,
+ handle go print() and go println(),
+ work around goto bug.
+* go/build: fixes, self-contained tests.
+* go/printer, gofmt: print "select {}" on one line.
+* godoc: replace OS file system accesses in favor of a FileSystem interface.
+* gofix: fix inconsistent indentation in help output (thanks Scott Lawrence).
+* goinstall: use go/build package to scan and build packages.
+* http/spdy: improve error handling (thanks William Chan).
+* http: use runtime/debug.Stack() to dump stack trace on panic.
+* ld: dwarf emit filenames in debug_line header instead of as extended opcodes,
+ fix link Windows PE __declspec(dllimport) symbol (thanks Wei Guangjing),
+ make .rodata section read-only (thanks Gustavo Niemeyer).
+* mail: decode RFC 2047 "B" encoding.
+* mime/multipart: remove temp files after tests on Windows (thanks Alex Brainman).
+* net: export all fields in Interface (thanks Mikio Hara),
+ rearrange source to run more tests on Windows (thanks Alex Brainman),
+ sendfile for win32 (thanks Yasuhiro Matsumoto).
+* os: Plan 9, fix OpenFile & Chmod, add Process.Kill (thanks Yuval Pavel Zholkover).
+* runtime: fix Plan 9 "lingering goroutines bug" (thanks Yuval Pavel Zholkover).
+* spec: clarify rules for append, scope rules for :=,
+ specify constant conversions,
+ unsafe.Alignof/Offsetof/Sizeof return uintptr.
+* syscall, os, exec: add *syscall.SysProcAttr field to os.ProcAttr and exec.Cmd.
+* syscall: add ptrace on darwin (thanks Jeff Hodges),
+ mksyscall_windows.pl should output unix newline (thanks Yasuhiro Matsumoto).
+ update BPF support for BSD variants (thanks Mikio Hara),
+ use strict in perl scripts (thanks Yasuhiro Matsumoto).
+* xml: handle non-string attribute fields (thanks Maxim Ushakov).
+</pre>
+
<h2 id="2011-06-09">2011-06-09 (<a href="release.html#r58">base for r58</a>)</h2>
<pre>
diff --git a/doc/effective_go.html b/doc/effective_go.html
index 972772d33..2ecef44f4 100644
--- a/doc/effective_go.html
+++ b/doc/effective_go.html
@@ -233,9 +233,9 @@ Since the whole declaration is presented, such a comment can often be perfunctor
<pre>
// Error codes returned by failures to parse an expression.
var (
- ErrInternal = os.NewError("internal error")
- ErrUnmatchedLpar = os.NewError("unmatched '('")
- ErrUnmatchedRpar = os.NewError("unmatched ')'")
+ ErrInternal = os.NewError("regexp: internal error")
+ ErrUnmatchedLpar = os.NewError("regexp: unmatched '('")
+ ErrUnmatchedRpar = os.NewError("regexp: unmatched ')'")
...
)
</pre>
@@ -350,7 +350,7 @@ Both names read well in practice:
<pre>
owner := obj.Owner()
if owner != user {
- obj.SetOwner(user)
+ obj.SetOwner(user)
}
</pre>
@@ -2245,7 +2245,7 @@ we would write <code>job.Logger</code>.
This would be useful if we wanted to refine the methods of <code>Logger</code>.
</p>
<pre>
-func (job *Job) Logf(format string, args ...) {
+func (job *Job) Logf(format string, args ...interface{}) {
job.Logger.Logf("%q: %s", job.Command, fmt.Sprintf(format, args))
}
</pre>
@@ -2674,6 +2674,13 @@ it is much more informative than the plain
</p>
<p>
+When feasible, error strings should identify their origin, such as by having
+a prefix naming the package that generated the error. For example, in package
+image, the string representation for a decoding error due to an unknown format
+is "image: unknown format".
+</p>
+
+<p>
Callers that care about the precise error details can
use a type switch or a type assertion to look for specific
errors and extract details. For <code>PathErrors</code>
diff --git a/doc/go_mem.html b/doc/go_mem.html
index 906b858e8..a38828358 100644
--- a/doc/go_mem.html
+++ b/doc/go_mem.html
@@ -1,4 +1,5 @@
<!-- The Go Memory Model -->
+<!-- subtitle Version of June 10, 2011 -->
<style>
p.rule {
@@ -42,8 +43,8 @@ Also, if <span class="event">e<sub>1</sub></span> does not happen before <span c
after <span class="event">e<sub>2</sub></span>, then we say that <span class="event">e<sub>1</sub></span> and <span class="event">e<sub>2</sub></span> happen concurrently.
</p>
-<p>
-Within a single goroutine, the happens before order is the
+<p class="rule">
+Within a single goroutine, the happens-before order is the
order expressed by the program.
</p>
diff --git a/doc/go_spec.html b/doc/go_spec.html
index abf5b8f50..489ad4db3 100644
--- a/doc/go_spec.html
+++ b/doc/go_spec.html
@@ -1,5 +1,5 @@
<!-- title The Go Programming Language Specification -->
-<!-- subtitle Version of June 7, 2011 -->
+<!-- subtitle Version of June 17, 2011 -->
<!--
TODO
@@ -10,7 +10,6 @@ TODO
[ ] clarify what a field name is in struct declarations
(struct{T} vs struct {T T} vs struct {t T})
[ ] need explicit language about the result type of operations
-[ ] should string(1<<s) and float32(1<<s) be valid?
[ ] should probably write something about evaluation order of statements even
though obvious
[ ] review language on implicit dereferencing
@@ -529,7 +528,8 @@ A constant value is represented by an
<a href="#Character_literals">character</a>, or
<a href="#String_literals">string</a> literal,
an identifier denoting a constant,
-a <a href="#Constant_expressions">constant expression</a>, or
+a <a href="#Constant_expressions">constant expression</a>,
+a <a href="#Conversions">conversion</a> with a result that is a constant, or
the result value of some built-in functions such as
<code>unsafe.Sizeof</code> applied to any value,
<code>cap</code> or <code>len</code> applied to
@@ -1452,6 +1452,7 @@ Go is lexically scoped using blocks:
<li>The scope of a constant or variable identifier declared
inside a function begins at the end of the ConstSpec or VarSpec
+ (ShortVarDecl for short variable declarations)
and ends at the end of the innermost containing block.</li>
<li>The scope of a type identifier declared inside a function
@@ -3227,8 +3228,42 @@ If the type starts with an operator it must be parenthesized:
</pre>
<p>
-A value <code>x</code> can be converted to type <code>T</code> in any
-of these cases:
+A <a href="#Constants">constant</a> value <code>x</code> can be converted to
+type <code>T</code> in any of these cases:
+</p>
+
+<ul>
+ <li>
+ <code>x</code> is representable by a value of type <code>T</code>.
+ </li>
+ <li>
+ <code>x</code> is an integer constant and <code>T</code> is a
+ <a href="#String_types">string type</a>.
+ The same rule as for non-constant <code>x</code> applies in this case
+ (§<a href="#Conversions_to_and_from_a_string_type">Conversions to and from a string type</a>).
+ </li>
+</ul>
+
+<p>
+Converting a constant yields a typed constant as result.
+</p>
+
+<pre>
+uint(iota) // iota value of type uint
+float32(2.718281828) // 2.718281828 of type float32
+complex128(1) // 1.0 + 0.0i of type complex128
+string('x') // "x" of type string
+string(0x266c) // "♬" of type string
+MyString("foo" + "bar") // "foobar" of type MyString
+string([]byte{'a'}) // not a constant: []byte{'a'} is not a constant
+(*int)(nil) // not a constant: nil is not a constant, *int is not a boolean, numeric, or string type
+int(1.2) // illegal: 1.2 cannot be represented as an int
+string(65.0) // illegal: 65.0 is not an integer constant
+</pre>
+
+<p>
+A non-constant value <code>x</code> can be converted to type <code>T</code>
+in any of these cases:
</p>
<ul>
@@ -3262,15 +3297,27 @@ of these cases:
</ul>
<p>
-Specific rules apply to conversions between numeric types or to and from
-a string type.
+Specific rules apply to (non-constant) conversions between numeric types or
+to and from a string type.
These conversions may change the representation of <code>x</code>
and incur a run-time cost.
All other conversions only change the type but not the representation
of <code>x</code>.
</p>
+<p>
+There is no linguistic mechanism to convert between pointers and integers.
+The package <a href="#Package_unsafe"><code>unsafe</code></a>
+implements this functionality under
+restricted circumstances.
+</p>
+
<h4>Conversions between numeric types</h4>
+
+<p>
+For the conversion of non-constant numeric values, the following rules apply:
+</p>
+
<ol>
<li>
When converting between integer types, if the value is a signed integer, it is
@@ -3296,13 +3343,12 @@ of precision, but <code>float32(x + 0.1)</code> does not.
</ol>
<p>
-In all conversions involving floating-point or complex values,
+In all non-constant conversions involving floating-point or complex values,
if the result type cannot represent the value the conversion
-succeeds but the result value is
-implementation-dependent.
+succeeds but the result value is implementation-dependent.
</p>
-<h4>Conversions to and from a string type</h4>
+<h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string type</h4>
<ol>
<li>
@@ -3360,12 +3406,6 @@ If the string is empty, the result is <code>[]int(nil)</code>.
</li>
</ol>
-<p>
-There is no linguistic mechanism to convert between pointers and integers.
-The package <a href="#Package_unsafe"><code>unsafe</code></a>
-implements this functionality under
-restricted circumstances.
-</p>
<h3 id="Constant_expressions">Constant expressions</h3>
@@ -4353,8 +4393,8 @@ goto Error
<p>
Executing the "goto" statement must not cause any variables to come into
-scope that were not already in scope at the point of the goto. For
-instance, this example:
+<a href="#Declarations_and_scope">scope</a> that were not already in scope at the point of the goto.
+For instance, this example:
</p>
<pre>
@@ -4366,9 +4406,29 @@ L:
<p>
is erroneous because the jump to label <code>L</code> skips
the creation of <code>v</code>.
-<!--
-(<span class="alert">TODO: Eliminate in favor of used and not set errors?</span>)
--->
+</p>
+
+<p>
+A "goto" statement outside a <a href="#Blocks">block</a> cannot jump to a label inside that block.
+For instance, this example:
+</p>
+
+<pre>
+if n%2 == 1 {
+ goto L1
+}
+for n &gt; 0 {
+ f()
+ n--
+L1:
+ f()
+ n--
+}
+</pre>
+
+<p>
+is erroneous because the label <code>L1</code> is inside
+the "for" statement's block but the <code>goto</code> is not.
</p>
<h3 id="Fallthrough_statements">Fallthrough statements</h3>
@@ -4590,11 +4650,14 @@ Two built-in functions assist in common slice operations.
</p>
<p>
-The function <code>append</code> appends zero or more values <code>x</code>
+The <a href="#Function_types">variadic</a> function <code>append</code>
+appends zero or more values <code>x</code>
to <code>s</code> of type <code>S</code>, which must be a slice type, and
returns the resulting slice, also of type <code>S</code>.
-Each value <code>x</code> must be <a href="#Assignability">assignable</a> to
-the <a href="#Slice_types">element type</a> of <code>S</code>.
+The values <code>x</code> are passed to a parameter of type <code>...T</code>
+where <code>T</code> is the <a href="#Slice_types">element type</a> of
+<code>S</code> and the respective
+<a href="#Passing_arguments_to_..._parameters">parameter passing rules</a> apply.
</p>
<pre class="grammar">
@@ -5102,9 +5165,9 @@ package unsafe
type ArbitraryType int // shorthand for an arbitrary Go type; it is not a real type
type Pointer *ArbitraryType
-func Alignof(variable ArbitraryType) int
-func Offsetof(selector ArbitraryType) int
-func Sizeof(variable ArbitraryType) int
+func Alignof(variable ArbitraryType) uintptr
+func Offsetof(selector ArbitraryType) uinptr
+func Sizeof(variable ArbitraryType) uintptr
func Reflect(val interface{}) (typ runtime.Type, addr uintptr)
func Typeof(val interface{}) (typ interface{})
@@ -5127,7 +5190,7 @@ For a struct <code>s</code> with field <code>f</code>:
</p>
<pre>
-uintptr(unsafe.Pointer(&amp;s)) + uintptr(unsafe.Offsetof(s.f)) == uintptr(unsafe.Pointer(&amp;s.f))
+uintptr(unsafe.Pointer(&amp;s)) + unsafe.Offsetof(s.f) == uintptr(unsafe.Pointer(&amp;s.f))
</pre>
<p>
@@ -5140,12 +5203,12 @@ alignment of the (type of the) variable in bytes. For a variable
</p>
<pre>
-uintptr(unsafe.Pointer(&amp;x)) % uintptr(unsafe.Alignof(x)) == 0
+uintptr(unsafe.Pointer(&amp;x)) % unsafe.Alignof(x) == 0
</pre>
<p>
Calls to <code>Alignof</code>, <code>Offsetof</code>, and
-<code>Sizeof</code> are compile-time constant expressions of type <code>int</code>.
+<code>Sizeof</code> are compile-time constant expressions of type <code>uintptr</code>.
</p>
<p>
The functions <code>unsafe.Typeof</code>,
@@ -5198,10 +5261,12 @@ The following minimal alignment properties are guaranteed:
</li>
</ol>
-<h2 id="Implementation_differences"><span class="alert">Implementation differences - TODO</span></h2>
+<span class="alert">
+<h2 id="Implementation_differences">Implementation differences - TODO</h2>
<ul>
- <li><span class="alert">The restriction on <code>goto</code> statements and targets (no intervening declarations) is not honored.</span></li>
- <li><span class="alert"><code>len(a)</code> is only a constant if <code>a</code> is a (qualified) identifier denoting an array or pointer to an array.</span></li>
- <li><span class="alert"><code>nil</code> maps are not treated like empty maps.</span></li>
- <li><span class="alert">Trying to send/receive from a <code>nil</code> channel causes a run-time panic.</span></li>
+ <li><code>len(a)</code> is only a constant if <code>a</code> is a (qualified) identifier denoting an array or pointer to an array.</li>
+ <li><code>nil</code> maps are not treated like empty maps.</li>
+ <li>Trying to send/receive from a <code>nil</code> channel causes a run-time panic.</li>
+ <li><code>unsafe.Alignof</code>, <code>unsafe.Offsetof</code>, and <code>unsafe.Sizeof</code> return an <code>int</code>.</li>
</ul>
+</span>
diff --git a/doc/go_tutorial.html b/doc/go_tutorial.html
index aa85134b3..822f9626e 100644
--- a/doc/go_tutorial.html
+++ b/doc/go_tutorial.html
@@ -26,14 +26,14 @@ cleanliness, blank lines remain blank.
<p>
Let's start in the usual way:
<p>
-<pre> <!-- progs/helloworld.go /package/ END -->
-05 package main
+<pre><!-- progs/helloworld.go /package/ $
+-->package main
-07 import fmt &quot;fmt&quot; // Package implementing formatted I/O.
+import fmt &#34;fmt&#34; // Package implementing formatted I/O.
-09 func main() {
-10 fmt.Printf(&quot;Hello, world; or Καλημέρα κόσμε; or こんにちは 世界\n&quot;)
-11 }
+func main() {
+ fmt.Printf(&#34;Hello, world; or Καλημέρα κόσμε; or こんにちは 世界\n&#34;)
+}
</pre>
<p>
Every Go source file declares, using a <code>package</code> statement, which package it's part of.
@@ -51,8 +51,8 @@ String constants can contain Unicode characters, encoded in UTF-8.
The comment convention is the same as in C++:
<p>
<pre>
- /* ... */
- // ...
+/* ... */
+// ...
</pre>
<p>
Later we'll have much more to say about printing.
@@ -96,67 +96,67 @@ a more robust run-time system although <code>gccgo</code> is catching up.
Here's how to compile and run our program. With <code>6g</code>, say,
<p>
<pre>
- $ 6g helloworld.go # compile; object goes into helloworld.6
- $ 6l helloworld.6 # link; output goes into 6.out
- $ 6.out
- Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
- $
+$ 6g helloworld.go # compile; object goes into helloworld.6
+$ 6l helloworld.6 # link; output goes into 6.out
+$ 6.out
+Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
+$
</pre>
<p>
With <code>gccgo</code> it looks a little more traditional.
<p>
<pre>
- $ gccgo helloworld.go
- $ a.out
- Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
- $
+$ gccgo helloworld.go
+$ a.out
+Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
+$
</pre>
<p>
<h2>Echo</h2>
<p>
Next up, here's a version of the Unix utility <code>echo(1)</code>:
<p>
-<pre> <!-- progs/echo.go /package/ END -->
-05 package main
+<pre><!-- progs/echo.go /package/ $
+-->package main
-07 import (
-08 &quot;os&quot;
-09 &quot;flag&quot; // command line option parser
-10 )
+import (
+ &#34;os&#34;
+ &#34;flag&#34; // command line option parser
+)
-12 var omitNewline = flag.Bool(&quot;n&quot;, false, &quot;don't print final newline&quot;)
+var omitNewline = flag.Bool(&#34;n&#34;, false, &#34;don&#39;t print final newline&#34;)
-14 const (
-15 Space = &quot; &quot;
-16 Newline = &quot;\n&quot;
-17 )
+const (
+ Space = &#34; &#34;
+ Newline = &#34;\n&#34;
+)
-19 func main() {
-20 flag.Parse() // Scans the arg list and sets up flags
-21 var s string = &quot;&quot;
-22 for i := 0; i &lt; flag.NArg(); i++ {
-23 if i &gt; 0 {
-24 s += Space
-25 }
-26 s += flag.Arg(i)
-27 }
-28 if !*omitNewline {
-29 s += Newline
-30 }
-31 os.Stdout.WriteString(s)
-32 }
+func main() {
+ flag.Parse() // Scans the arg list and sets up flags
+ var s string = &#34;&#34;
+ for i := 0; i &lt; flag.NArg(); i++ {
+ if i &gt; 0 {
+ s += Space
+ }
+ s += flag.Arg(i)
+ }
+ if !*omitNewline {
+ s += Newline
+ }
+ os.Stdout.WriteString(s)
+}
</pre>
<p>
This program is small but it's doing a number of new things. In the last example,
we saw <code>func</code> introduce a function. The keywords <code>var</code>, <code>const</code>, and <code>type</code>
(not used yet) also introduce declarations, as does <code>import</code>.
Notice that we can group declarations of the same sort into
-parenthesized lists, one item per line, as on lines 7-10 and 14-17.
+parenthesized lists, one item per line, as in the <code>import</code> and <code>const</code> clauses here.
But it's not necessary to do so; we could have said
<p>
<pre>
- const Space = " "
- const Newline = "\n"
+const Space = " "
+const Newline = "\n"
</pre>
<p>
This program imports the <code>&quot;os&quot;</code> package to access its <code>Stdout</code> variable, of type
@@ -186,7 +186,7 @@ string variable we will use to build the output.
The declaration statement has the form
<p>
<pre>
- var s string = ""
+var s string = ""
</pre>
<p>
This is the <code>var</code> keyword, followed by the name of the variable, followed by
@@ -197,20 +197,20 @@ string constant is of type string, we don't have to tell the compiler that.
We could write
<p>
<pre>
- var s = ""
+var s = ""
</pre>
<p>
or we could go even shorter and write the idiom
<p>
<pre>
- s := ""
+s := ""
</pre>
<p>
The <code>:=</code> operator is used a lot in Go to represent an initializing declaration.
There's one in the <code>for</code> clause on the next line:
<p>
-<pre> <!-- progs/echo.go /for/ -->
-22 for i := 0; i &lt; flag.NArg(); i++ {
+<pre><!-- progs/echo.go /for/
+--> for i := 0; i &lt; flag.NArg(); i++ {
</pre>
<p>
The <code>flag</code> package has parsed the arguments and left the non-flag arguments
@@ -231,7 +231,7 @@ It's defined that way. Falling off the end of <code>main.main</code> means
''success''; if you want to signal an erroneous return, call
<p>
<pre>
- os.Exit(1)
+os.Exit(1)
</pre>
<p>
The <code>os</code> package contains other essentials for getting
@@ -259,20 +259,20 @@ Once you've built a string <i>value</i>, you can't change it, although
of course you can change a string <i>variable</i> simply by
reassigning it. This snippet from <code>strings.go</code> is legal code:
<p>
-<pre> <!-- progs/strings.go /hello/ /ciao/ -->
-10 s := &quot;hello&quot;
-11 if s[1] != 'e' { os.Exit(1) }
-12 s = &quot;good bye&quot;
-13 var p *string = &amp;s
-14 *p = &quot;ciao&quot;
+<pre><!-- progs/strings.go /hello/ /ciao/
+--> s := &#34;hello&#34;
+ if s[1] != 'e' { os.Exit(1) }
+ s = &#34;good bye&#34;
+ var p *string = &amp;s
+ *p = &#34;ciao&#34;
</pre>
<p>
However the following statements are illegal because they would modify
a <code>string</code> value:
<p>
<pre>
- s[0] = 'x'
- (*p)[1] = 'y'
+s[0] = 'x'
+(*p)[1] = 'y'
</pre>
<p>
In C++ terms, Go strings are a bit like <code>const strings</code>, while pointers
@@ -284,7 +284,7 @@ read on.
Arrays are declared like this:
<p>
<pre>
- var arrayOfInt [10]int
+var arrayOfInt [10]int
</pre>
<p>
Arrays, like strings, are values, but they are mutable. This differs
@@ -315,7 +315,7 @@ expression formed
from a type followed by a brace-bounded expression like this:
<p>
<pre>
- [3]int{1,2,3}
+[3]int{1,2,3}
</pre>
<p>
In this case the constructor builds an array of 3 <code>ints</code>.
@@ -330,14 +330,14 @@ will slice the whole array.
<p>
Using slices one can write this function (from <code>sum.go</code>):
<p>
-<pre> <!-- progs/sum.go /sum/ /^}/ -->
-09 func sum(a []int) int { // returns an int
-10 s := 0
-11 for i := 0; i &lt; len(a); i++ {
-12 s += a[i]
-13 }
-14 return s
-15 }
+<pre><!-- progs/sum.go /sum/ /^}/
+-->func sum(a []int) int { // returns an int
+ s := 0
+ for i := 0; i &lt; len(a); i++ {
+ s += a[i]
+ }
+ return s
+}
</pre>
<p>
Note how the return type (<code>int</code>) is defined for <code>sum</code> by stating it
@@ -348,14 +348,14 @@ a simpler way in a moment) constructs
an array and slices it:
<p>
<pre>
- s := sum([3]int{1,2,3}[:])
+s := sum([3]int{1,2,3}[:])
</pre>
<p>
If you are creating a regular array but want the compiler to count the
elements for you, use <code>...</code> as the array size:
<p>
<pre>
- s := sum([...]int{1,2,3}[:])
+s := sum([...]int{1,2,3}[:])
</pre>
<p>
That's fussier than necessary, though.
@@ -363,13 +363,13 @@ In practice, unless you're meticulous about storage layout within a
data structure, a slice itself&mdash;using empty brackets with no size&mdash;is all you need:
<p>
<pre>
- s := sum([]int{1,2,3})
+s := sum([]int{1,2,3})
</pre>
<p>
There are also maps, which you can initialize like this:
<p>
<pre>
- m := map[string]int{"one":1 , "two":2}
+m := map[string]int{"one":1 , "two":2}
</pre>
<p>
The built-in function <code>len</code>, which returns number of elements,
@@ -380,13 +380,13 @@ By the way, another thing that works on strings, arrays, slices, maps
and channels is the <code>range</code> clause on <code>for</code> loops. Instead of writing
<p>
<pre>
- for i := 0; i &lt; len(a); i++ { ... }
+for i := 0; i &lt; len(a); i++ { ... }
</pre>
<p>
to loop over the elements of a slice (or map or ...) , we could write
<p>
<pre>
- for i, v := range a { ... }
+for i, v := range a { ... }
</pre>
<p>
This assigns <code>i</code> to the index and <code>v</code> to the value of the successive
@@ -404,14 +404,14 @@ To allocate a new variable, use the built-in function <code>new</code>, which
returns a pointer to the allocated storage.
<p>
<pre>
- type T struct { a, b int }
- var t *T = new(T)
+type T struct { a, b int }
+var t *T = new(T)
</pre>
<p>
or the more idiomatic
<p>
<pre>
- t := new(T)
+t := new(T)
</pre>
<p>
Some types&mdash;maps, slices, and channels (see below)&mdash;have reference semantics.
@@ -420,14 +420,14 @@ referencing the same underlying data will see the modification. For these three
types you want to use the built-in function <code>make</code>:
<p>
<pre>
- m := make(map[string]int)
+m := make(map[string]int)
</pre>
<p>
This statement initializes a new map ready to store entries.
If you just declare the map, as in
<p>
<pre>
- var m map[string]int
+var m map[string]int
</pre>
<p>
it creates a <code>nil</code> reference that cannot hold anything. To use the map,
@@ -448,20 +448,20 @@ can overflow only when they are assigned to an integer variable with
too little precision to represent the value.
<p>
<pre>
- const hardEight = (1 &lt;&lt; 100) &gt;&gt; 97 // legal
+const hardEight = (1 &lt;&lt; 100) &gt;&gt; 97 // legal
</pre>
<p>
There are nuances that deserve redirection to the legalese of the
language specification but here are some illustrative examples:
<p>
<pre>
- var a uint64 = 0 // a has type uint64, value 0
- a := uint64(0) // equivalent; uses a "conversion"
- i := 0x1234 // i gets default type: int
- var j int = 1e6 // legal - 1000000 is representable in an int
- x := 1.5 // a float64, the default type for floating constants
- i3div2 := 3/2 // integer division - result is 1
- f3div2 := 3./2. // floating-point division - result is 1.5
+var a uint64 = 0 // a has type uint64, value 0
+a := uint64(0) // equivalent; uses a "conversion"
+i := 0x1234 // i gets default type: int
+var j int = 1e6 // legal - 1000000 is representable in an int
+x := 1.5 // a float64, the default type for floating constants
+i3div2 := 3/2 // integer division - result is 1
+f3div2 := 3./2. // floating-point division - result is 1.5
</pre>
<p>
Conversions only work for simple cases such as converting <code>ints</code> of one
@@ -476,18 +476,18 @@ assigned to a variable.
Next we'll look at a simple package for doing file I/O with an
open/close/read/write interface. Here's the start of <code>file.go</code>:
<p>
-<pre> <!-- progs/file.go /package/ /^}/ -->
-05 package file
+<pre><!-- progs/file.go /package/ /^}/
+-->package file
-07 import (
-08 &quot;os&quot;
-09 &quot;syscall&quot;
-10 )
+import (
+ &#34;os&#34;
+ &#34;syscall&#34;
+)
-12 type File struct {
-13 fd int // file descriptor number
-14 name string // file name at Open time
-15 }
+type File struct {
+ fd int // file descriptor number
+ name string // file name at Open time
+}
</pre>
<p>
The first few lines declare the name of the
@@ -518,13 +518,13 @@ will soon give it some exported, upper-case methods.
<p>
First, though, here is a factory to create a <code>File</code>:
<p>
-<pre> <!-- progs/file.go /newFile/ /^}/ -->
-17 func newFile(fd int, name string) *File {
-18 if fd &lt; 0 {
-19 return nil
-20 }
-21 return &amp;File{fd, name}
-22 }
+<pre><!-- progs/file.go /newFile/ /^}/
+-->func newFile(fd int, name string) *File {
+ if fd &lt; 0 {
+ return nil
+ }
+ return &amp;File{fd, name}
+}
</pre>
<p>
This returns a pointer to a new <code>File</code> structure with the file descriptor and name
@@ -533,10 +533,10 @@ the ones used to build maps and arrays, to construct a new heap-allocated
object. We could write
<p>
<pre>
- n := new(File)
- n.fd = fd
- n.name = name
- return n
+n := new(File)
+n.fd = fd
+n.name = name
+return n
</pre>
<p>
but for simple structures like <code>File</code> it's easier to return the address of a
@@ -544,25 +544,26 @@ composite literal, as is done here on line 21.
<p>
We can use the factory to construct some familiar, exported variables of type <code>*File</code>:
<p>
-<pre> <!-- progs/file.go /var/ /^.$/ -->
-24 var (
-25 Stdin = newFile(syscall.Stdin, &quot;/dev/stdin&quot;)
-26 Stdout = newFile(syscall.Stdout, &quot;/dev/stdout&quot;)
-27 Stderr = newFile(syscall.Stderr, &quot;/dev/stderr&quot;)
-28 )
+<pre><!-- progs/file.go /var/ /^.$/
+-->var (
+ Stdin = newFile(syscall.Stdin, &#34;/dev/stdin&#34;)
+ Stdout = newFile(syscall.Stdout, &#34;/dev/stdout&#34;)
+ Stderr = newFile(syscall.Stderr, &#34;/dev/stderr&#34;)
+)
+
</pre>
<p>
The <code>newFile</code> function was not exported because it's internal. The proper,
exported factory to use is <code>OpenFile</code> (we'll explain that name in a moment):
<p>
-<pre> <!-- progs/file.go /func.OpenFile/ /^}/ -->
-30 func OpenFile(name string, mode int, perm uint32) (file *File, err os.Error) {
-31 r, e := syscall.Open(name, mode, perm)
-32 if e != 0 {
-33 err = os.Errno(e)
-34 }
-35 return newFile(r, name), err
-36 }
+<pre><!-- progs/file.go /func.OpenFile/ /^}/
+-->func OpenFile(name string, mode int, perm uint32) (file *File, err os.Error) {
+ r, e := syscall.Open(name, mode, perm)
+ if e != 0 {
+ err = os.Errno(e)
+ }
+ return newFile(r, name), err
+}
</pre>
<p>
There are a number of new things in these few lines. First, <code>OpenFile</code> returns
@@ -593,23 +594,23 @@ the implementation of our <code>Open</code> and <code>Create</code>; they're tri
wrappers that eliminate common errors by capturing
the tricky standard arguments to open and, especially, to create a file:
<p>
-<pre> <!-- progs/file.go /^const/ /^}/ -->
-38 const (
-39 O_RDONLY = syscall.O_RDONLY
-40 O_RDWR = syscall.O_RDWR
-41 O_CREATE = syscall.O_CREAT
-42 O_TRUNC = syscall.O_TRUNC
-43 )
+<pre><!-- progs/file.go /^const/ /^}/
+-->const (
+ O_RDONLY = syscall.O_RDONLY
+ O_RDWR = syscall.O_RDWR
+ O_CREATE = syscall.O_CREAT
+ O_TRUNC = syscall.O_TRUNC
+)
-45 func Open(name string) (file *File, err os.Error) {
-46 return OpenFile(name, O_RDONLY, 0)
-47 }
+func Open(name string) (file *File, err os.Error) {
+ return OpenFile(name, O_RDONLY, 0)
+}
</pre>
<p>
-<pre> <!-- progs/file.go /func.Create/ /^}/ -->
-49 func Create(name string) (file *File, err os.Error) {
-50 return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
-51 }
+<pre><!-- progs/file.go /func.Create/ /^}/
+-->func Create(name string) (file *File, err os.Error) {
+ return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
+}
</pre>
<p>
Back to our main story.
@@ -619,44 +620,44 @@ of that type, placed
in parentheses before the function name. Here are some methods for <code>*File</code>,
each of which declares a receiver variable <code>file</code>.
<p>
-<pre> <!-- progs/file.go /Close/ END -->
-53 func (file *File) Close() os.Error {
-54 if file == nil {
-55 return os.EINVAL
-56 }
-57 e := syscall.Close(file.fd)
-58 file.fd = -1 // so it can't be closed again
-59 if e != 0 {
-60 return os.Errno(e)
-61 }
-62 return nil
-63 }
+<pre><!-- progs/file.go /Close/ $
+-->func (file *File) Close() os.Error {
+ if file == nil {
+ return os.EINVAL
+ }
+ e := syscall.Close(file.fd)
+ file.fd = -1 // so it can't be closed again
+ if e != 0 {
+ return os.Errno(e)
+ }
+ return nil
+}
-65 func (file *File) Read(b []byte) (ret int, err os.Error) {
-66 if file == nil {
-67 return -1, os.EINVAL
-68 }
-69 r, e := syscall.Read(file.fd, b)
-70 if e != 0 {
-71 err = os.Errno(e)
-72 }
-73 return int(r), err
-74 }
+func (file *File) Read(b []byte) (ret int, err os.Error) {
+ if file == nil {
+ return -1, os.EINVAL
+ }
+ r, e := syscall.Read(file.fd, b)
+ if e != 0 {
+ err = os.Errno(e)
+ }
+ return int(r), err
+}
-76 func (file *File) Write(b []byte) (ret int, err os.Error) {
-77 if file == nil {
-78 return -1, os.EINVAL
-79 }
-80 r, e := syscall.Write(file.fd, b)
-81 if e != 0 {
-82 err = os.Errno(e)
-83 }
-84 return int(r), err
-85 }
+func (file *File) Write(b []byte) (ret int, err os.Error) {
+ if file == nil {
+ return -1, os.EINVAL
+ }
+ r, e := syscall.Write(file.fd, b)
+ if e != 0 {
+ err = os.Errno(e)
+ }
+ return int(r), err
+}
-87 func (file *File) String() string {
-88 return file.name
-89 }
+func (file *File) String() string {
+ return file.name
+}
</pre>
<p>
There is no implicit <code>this</code> and the receiver variable must be used to access
@@ -674,24 +675,24 @@ set of such error values.
<p>
We can now use our new package:
<p>
-<pre> <!-- progs/helloworld3.go /package/ END -->
-05 package main
+<pre><!-- progs/helloworld3.go /package/ $
+-->package main
-07 import (
-08 &quot;./file&quot;
-09 &quot;fmt&quot;
-10 &quot;os&quot;
-11 )
+import (
+ &#34;./file&#34;
+ &#34;fmt&#34;
+ &#34;os&#34;
+)
-13 func main() {
-14 hello := []byte(&quot;hello, world\n&quot;)
-15 file.Stdout.Write(hello)
-16 f, err := file.Open(&quot;/does/not/exist&quot;)
-17 if f == nil {
-18 fmt.Printf(&quot;can't open file; err=%s\n&quot;, err.String())
-19 os.Exit(1)
-20 }
-21 }
+func main() {
+ hello := []byte(&#34;hello, world\n&#34;)
+ file.Stdout.Write(hello)
+ f, err := file.Open(&#34;/does/not/exist&#34;)
+ if f == nil {
+ fmt.Printf(&#34;can&#39;t open file; err=%s\n&#34;, err.String())
+ os.Exit(1)
+ }
+}
</pre>
<p>
The ''<code>./</code>'' in the import of ''<code>./file</code>'' tells the compiler
@@ -703,13 +704,13 @@ package.)
Now we can compile and run the program. On Unix, this would be the result:
<p>
<pre>
- $ 6g file.go # compile file package
- $ 6g helloworld3.go # compile main package
- $ 6l -o helloworld3 helloworld3.6 # link - no need to mention "file"
- $ helloworld3
- hello, world
- can't open file; err=No such file or directory
- $
+$ 6g file.go # compile file package
+$ 6g helloworld3.go # compile main package
+$ 6l -o helloworld3 helloworld3.6 # link - no need to mention "file"
+$ helloworld3
+hello, world
+can't open file; err=No such file or directory
+$
</pre>
<p>
<h2>Rotting cats</h2>
@@ -717,56 +718,56 @@ Now we can compile and run the program. On Unix, this would be the result:
Building on the <code>file</code> package, here's a simple version of the Unix utility <code>cat(1)</code>,
<code>progs/cat.go</code>:
<p>
-<pre> <!-- progs/cat.go /package/ END -->
-05 package main
+<pre><!-- progs/cat.go /package/ $
+-->package main
-07 import (
-08 &quot;./file&quot;
-09 &quot;flag&quot;
-10 &quot;fmt&quot;
-11 &quot;os&quot;
-12 )
+import (
+ &#34;./file&#34;
+ &#34;flag&#34;
+ &#34;fmt&#34;
+ &#34;os&#34;
+)
-14 func cat(f *file.File) {
-15 const NBUF = 512
-16 var buf [NBUF]byte
-17 for {
-18 switch nr, er := f.Read(buf[:]); true {
-19 case nr &lt; 0:
-20 fmt.Fprintf(os.Stderr, &quot;cat: error reading from %s: %s\n&quot;, f.String(), er.String())
-21 os.Exit(1)
-22 case nr == 0: // EOF
-23 return
-24 case nr &gt; 0:
-25 if nw, ew := file.Stdout.Write(buf[0:nr]); nw != nr {
-26 fmt.Fprintf(os.Stderr, &quot;cat: error writing from %s: %s\n&quot;, f.String(), ew.String())
-27 os.Exit(1)
-28 }
-29 }
-30 }
-31 }
+func cat(f *file.File) {
+ const NBUF = 512
+ var buf [NBUF]byte
+ for {
+ switch nr, er := f.Read(buf[:]); true {
+ case nr &lt; 0:
+ fmt.Fprintf(os.Stderr, &#34;cat: error reading from %s: %s\n&#34;, f.String(), er.String())
+ os.Exit(1)
+ case nr == 0: // EOF
+ return
+ case nr &gt; 0:
+ if nw, ew := file.Stdout.Write(buf[0:nr]); nw != nr {
+ fmt.Fprintf(os.Stderr, &#34;cat: error writing from %s: %s\n&#34;, f.String(), ew.String())
+ os.Exit(1)
+ }
+ }
+ }
+}
-33 func main() {
-34 flag.Parse() // Scans the arg list and sets up flags
-35 if flag.NArg() == 0 {
-36 cat(file.Stdin)
-37 }
-38 for i := 0; i &lt; flag.NArg(); i++ {
-39 f, err := file.Open(flag.Arg(i))
-40 if f == nil {
-41 fmt.Fprintf(os.Stderr, &quot;cat: can't open %s: error %s\n&quot;, flag.Arg(i), err)
-42 os.Exit(1)
-43 }
-44 cat(f)
-45 f.Close()
-46 }
-47 }
+func main() {
+ flag.Parse() // Scans the arg list and sets up flags
+ if flag.NArg() == 0 {
+ cat(file.Stdin)
+ }
+ for i := 0; i &lt; flag.NArg(); i++ {
+ f, err := file.Open(flag.Arg(i))
+ if f == nil {
+ fmt.Fprintf(os.Stderr, &#34;cat: can&#39;t open %s: error %s\n&#34;, flag.Arg(i), err)
+ os.Exit(1)
+ }
+ cat(f)
+ f.Close()
+ }
+}
</pre>
<p>
By now this should be easy to follow, but the <code>switch</code> statement introduces some
new features. Like a <code>for</code> loop, an <code>if</code> or <code>switch</code> can include an
-initialization statement. The <code>switch</code> on line 18 uses one to create variables
-<code>nr</code> and <code>er</code> to hold the return values from the call to <code>f.Read</code>. (The <code>if</code> on line 25
+initialization statement. The <code>switch</code> statement in <code>cat</code> uses one to create variables
+<code>nr</code> and <code>er</code> to hold the return values from the call to <code>f.Read</code>. (The <code>if</code> a few lines later
has the same idea.) The <code>switch</code> statement is general: it evaluates the cases
from top to bottom looking for the first case that matches the value; the
case expressions don't need to be constants or even integers, as long as
@@ -778,7 +779,7 @@ in a <code>for</code> statement, a missing value means <code>true</code>. In fa
is a form of <code>if-else</code> chain. While we're here, it should be mentioned that in
<code>switch</code> statements each <code>case</code> has an implicit <code>break</code>.
<p>
-Line 25 calls <code>Write</code> by slicing the incoming buffer, which is itself a slice.
+The argument to <code>file.Stdout.Write</code> is created by slicing the array <code>buf</code>.
Slices provide the standard Go way to handle I/O buffers.
<p>
Now let's make a variant of <code>cat</code> that optionally does <code>rot13</code> on its input.
@@ -789,11 +790,11 @@ The <code>cat</code> subroutine uses only two methods of <code>f</code>: <code>R
so let's start by defining an interface that has exactly those two methods.
Here is code from <code>progs/cat_rot13.go</code>:
<p>
-<pre> <!-- progs/cat_rot13.go /type.reader/ /^}/ -->
-26 type reader interface {
-27 Read(b []byte) (ret int, err os.Error)
-28 String() string
-29 }
+<pre><!-- progs/cat_rot13.go /type.reader/ /^}/
+-->type reader interface {
+ Read(b []byte) (ret int, err os.Error)
+ String() string
+}
</pre>
<p>
Any type that has the two methods of <code>reader</code>&mdash;regardless of whatever
@@ -806,68 +807,68 @@ existing <code>reader</code> and does <code>rot13</code> on the data. To do this
the type and implement the methods and with no other bookkeeping,
we have a second implementation of the <code>reader</code> interface.
<p>
-<pre> <!-- progs/cat_rot13.go /type.rotate13/ /end.of.rotate13/ -->
-31 type rotate13 struct {
-32 source reader
-33 }
+<pre><!-- progs/cat_rot13.go /type.rotate13/ /end.of.rotate13/
+-->type rotate13 struct {
+ source reader
+}
-35 func newRotate13(source reader) *rotate13 {
-36 return &amp;rotate13{source}
-37 }
+func newRotate13(source reader) *rotate13 {
+ return &amp;rotate13{source}
+}
-39 func (r13 *rotate13) Read(b []byte) (ret int, err os.Error) {
-40 r, e := r13.source.Read(b)
-41 for i := 0; i &lt; r; i++ {
-42 b[i] = rot13(b[i])
-43 }
-44 return r, e
-45 }
+func (r13 *rotate13) Read(b []byte) (ret int, err os.Error) {
+ r, e := r13.source.Read(b)
+ for i := 0; i &lt; r; i++ {
+ b[i] = rot13(b[i])
+ }
+ return r, e
+}
-47 func (r13 *rotate13) String() string {
-48 return r13.source.String()
-49 }
-50 // end of rotate13 implementation
+func (r13 *rotate13) String() string {
+ return r13.source.String()
+}
+// end of rotate13 implementation
</pre>
<p>
-(The <code>rot13</code> function called on line 42 is trivial and not worth reproducing here.)
+(The <code>rot13</code> function called in <code>Read</code> is trivial and not worth reproducing here.)
<p>
To use the new feature, we define a flag:
<p>
-<pre> <!-- progs/cat_rot13.go /rot13Flag/ -->
-14 var rot13Flag = flag.Bool(&quot;rot13&quot;, false, &quot;rot13 the input&quot;)
+<pre><!-- progs/cat_rot13.go /rot13Flag/
+-->var rot13Flag = flag.Bool(&#34;rot13&#34;, false, &#34;rot13 the input&#34;)
</pre>
<p>
and use it from within a mostly unchanged <code>cat</code> function:
<p>
-<pre> <!-- progs/cat_rot13.go /func.cat/ /^}/ -->
-52 func cat(r reader) {
-53 const NBUF = 512
-54 var buf [NBUF]byte
+<pre><!-- progs/cat_rot13.go /func.cat/ /^}/
+-->func cat(r reader) {
+ const NBUF = 512
+ var buf [NBUF]byte
-56 if *rot13Flag {
-57 r = newRotate13(r)
-58 }
-59 for {
-60 switch nr, er := r.Read(buf[:]); {
-61 case nr &lt; 0:
-62 fmt.Fprintf(os.Stderr, &quot;cat: error reading from %s: %s\n&quot;, r.String(), er.String())
-63 os.Exit(1)
-64 case nr == 0: // EOF
-65 return
-66 case nr &gt; 0:
-67 nw, ew := file.Stdout.Write(buf[0:nr])
-68 if nw != nr {
-69 fmt.Fprintf(os.Stderr, &quot;cat: error writing from %s: %s\n&quot;, r.String(), ew.String())
-70 os.Exit(1)
-71 }
-72 }
-73 }
-74 }
+ if *rot13Flag {
+ r = newRotate13(r)
+ }
+ for {
+ switch nr, er := r.Read(buf[:]); {
+ case nr &lt; 0:
+ fmt.Fprintf(os.Stderr, &#34;cat: error reading from %s: %s\n&#34;, r.String(), er.String())
+ os.Exit(1)
+ case nr == 0: // EOF
+ return
+ case nr &gt; 0:
+ nw, ew := file.Stdout.Write(buf[0:nr])
+ if nw != nr {
+ fmt.Fprintf(os.Stderr, &#34;cat: error writing from %s: %s\n&#34;, r.String(), ew.String())
+ os.Exit(1)
+ }
+ }
+ }
+}
</pre>
<p>
(We could also do the wrapping in <code>main</code> and leave <code>cat</code> mostly alone, except
for changing the type of the argument; consider that an exercise.)
-Lines 56 through 58 set it all up: If the <code>rot13</code> flag is true, wrap the <code>reader</code>
+The <code>if</code> at the top of <code>cat</code> sets it all up: If the <code>rot13</code> flag is true, wrap the <code>reader</code>
we received into a <code>rotate13</code> and proceed. Note that the interface variables
are values, not pointers: the argument is of type <code>reader</code>, not <code>*reader</code>,
even though under the covers it holds a pointer to a <code>struct</code>.
@@ -875,11 +876,11 @@ even though under the covers it holds a pointer to a <code>struct</code>.
Here it is in action:
<p>
<pre>
- $ echo abcdefghijklmnopqrstuvwxyz | ./cat
- abcdefghijklmnopqrstuvwxyz
- $ echo abcdefghijklmnopqrstuvwxyz | ./cat --rot13
- nopqrstuvwxyzabcdefghijklm
- $
+$ echo abcdefghijklmnopqrstuvwxyz | ./cat
+abcdefghijklmnopqrstuvwxyz
+$ echo abcdefghijklmnopqrstuvwxyz | ./cat --rot13
+nopqrstuvwxyzabcdefghijklm
+$
</pre>
<p>
Fans of dependency injection may take cheer from how easily interfaces
@@ -895,7 +896,7 @@ implement a <code>writer</code>, or any other interface built from its methods t
fits the current situation. Consider the <i>empty interface</i>
<p>
<pre>
- type Empty interface {}
+type Empty interface {}
</pre>
<p>
<i>Every</i> type implements the empty interface, which makes it
@@ -910,36 +911,36 @@ same interface variable.
<p>
As an example, consider this simple sort algorithm taken from <code>progs/sort.go</code>:
<p>
-<pre> <!-- progs/sort.go /func.Sort/ /^}/ -->
-13 func Sort(data Interface) {
-14 for i := 1; i &lt; data.Len(); i++ {
-15 for j := i; j &gt; 0 &amp;&amp; data.Less(j, j-1); j-- {
-16 data.Swap(j, j-1)
-17 }
-18 }
-19 }
+<pre><!-- progs/sort.go /func.Sort/ /^}/
+-->func Sort(data Interface) {
+ for i := 1; i &lt; data.Len(); i++ {
+ for j := i; j &gt; 0 &amp;&amp; data.Less(j, j-1); j-- {
+ data.Swap(j, j-1)
+ }
+ }
+}
</pre>
<p>
The code needs only three methods, which we wrap into sort's <code>Interface</code>:
<p>
-<pre> <!-- progs/sort.go /interface/ /^}/ -->
-07 type Interface interface {
-08 Len() int
-09 Less(i, j int) bool
-10 Swap(i, j int)
-11 }
+<pre><!-- progs/sort.go /interface/ /^}/
+-->type Interface interface {
+ Len() int
+ Less(i, j int) bool
+ Swap(i, j int)
+}
</pre>
<p>
We can apply <code>Sort</code> to any type that implements <code>Len</code>, <code>Less</code>, and <code>Swap</code>.
The <code>sort</code> package includes the necessary methods to allow sorting of
arrays of integers, strings, etc.; here's the code for arrays of <code>int</code>
<p>
-<pre> <!-- progs/sort.go /type.*IntArray/ /Swap/ -->
-33 type IntArray []int
+<pre><!-- progs/sort.go /type.*IntSlice/ /Swap/
+-->type IntSlice []int
-35 func (p IntArray) Len() int { return len(p) }
-36 func (p IntArray) Less(i, j int) bool { return p[i] &lt; p[j] }
-37 func (p IntArray) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
+func (p IntSlice) Len() int { return len(p) }
+func (p IntSlice) Less(i, j int) bool { return p[i] &lt; p[j] }
+func (p IntSlice) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
</pre>
<p>
Here we see methods defined for non-<code>struct</code> types. You can define methods
@@ -949,34 +950,34 @@ And now a routine to test it out, from <code>progs/sortmain.go</code>. This
uses a function in the <code>sort</code> package, omitted here for brevity,
to test that the result is sorted.
<p>
-<pre> <!-- progs/sortmain.go /func.ints/ /^}/ -->
-12 func ints() {
-13 data := []int{74, 59, 238, -784, 9845, 959, 905, 0, 0, 42, 7586, -5467984, 7586}
-14 a := sort.IntArray(data)
-15 sort.Sort(a)
-16 if !sort.IsSorted(a) {
-17 panic(&quot;fail&quot;)
-18 }
-19 }
+<pre><!-- progs/sortmain.go /func.ints/ /^}/
+-->func ints() {
+ data := []int{74, 59, 238, -784, 9845, 959, 905, 0, 0, 42, 7586, -5467984, 7586}
+ a := sort.IntSlice(data)
+ sort.Sort(a)
+ if !sort.IsSorted(a) {
+ panic(&#34;fail&#34;)
+ }
+}
</pre>
<p>
If we have a new type we want to be able to sort, all we need to do is
to implement the three methods for that type, like this:
<p>
-<pre> <!-- progs/sortmain.go /type.day/ /Swap/ -->
-30 type day struct {
-31 num int
-32 shortName string
-33 longName string
-34 }
+<pre><!-- progs/sortmain.go /type.day/ /Swap/
+-->type day struct {
+ num int
+ shortName string
+ longName string
+}
-36 type dayArray struct {
-37 data []*day
-38 }
+type dayArray struct {
+ data []*day
+}
-40 func (p *dayArray) Len() int { return len(p.data) }
-41 func (p *dayArray) Less(i, j int) bool { return p.data[i].num &lt; p.data[j].num }
-42 func (p *dayArray) Swap(i, j int) { p.data[i], p.data[j] = p.data[j], p.data[i] }
+func (p *dayArray) Len() int { return len(p.data) }
+func (p *dayArray) Less(i, j int) bool { return p.data[i].num &lt; p.data[j].num }
+func (p *dayArray) Swap(i, j int) { p.data[i], p.data[j] = p.data[j], p.data[i] }
</pre>
<p>
<p>
@@ -990,7 +991,7 @@ implements <code>Printf</code>, <code>Fprintf</code>, and so on.
Within the <code>fmt</code> package, <code>Printf</code> is declared with this signature:
<p>
<pre>
- Printf(format string, v ...interface{}) (n int, errno os.Error)
+Printf(format string, v ...interface{}) (n int, errno os.Error)
</pre>
<p>
The token <code>...</code> introduces a variable-length argument list that in C would
@@ -1011,34 +1012,34 @@ argument. It's easier in many cases in Go. Instead of <code>%llud</code> you
can just say <code>%d</code>; <code>Printf</code> knows the size and signedness of the
integer and can do the right thing for you. The snippet
<p>
-<pre> <!-- progs/print.go NR==10 NR==11 -->
-10 var u64 uint64 = 1&lt;&lt;64-1
-11 fmt.Printf(&quot;%d %d\n&quot;, u64, int64(u64))
+<pre><!-- progs/print.go 10 11
+--> var u64 uint64 = 1&lt;&lt;64-1
+ fmt.Printf(&#34;%d %d\n&#34;, u64, int64(u64))
</pre>
<p>
prints
<p>
<pre>
- 18446744073709551615 -1
+18446744073709551615 -1
</pre>
<p>
In fact, if you're lazy the format <code>%v</code> will print, in a simple
appropriate style, any value, even an array or structure. The output of
<p>
-<pre> <!-- progs/print.go NR==14 NR==20 -->
-14 type T struct {
-15 a int
-16 b string
-17 }
-18 t := T{77, &quot;Sunset Strip&quot;}
-19 a := []int{1, 2, 3, 4}
-20 fmt.Printf(&quot;%v %v %v\n&quot;, u64, t, a)
+<pre><!-- progs/print.go 14 20
+--> type T struct {
+ a int
+ b string
+ }
+ t := T{77, &#34;Sunset Strip&#34;}
+ a := []int{1, 2, 3, 4}
+ fmt.Printf(&#34;%v %v %v\n&#34;, u64, t, a)
</pre>
<p>
is
<p>
<pre>
- 18446744073709551615 {77 Sunset Strip} [1 2 3 4]
+18446744073709551615 {77 Sunset Strip} [1 2 3 4]
</pre>
<p>
You can drop the formatting altogether if you use <code>Print</code> or <code>Println</code>
@@ -1048,9 +1049,9 @@ of <code>%v</code> while <code>Println</code> inserts spaces between arguments
and adds a newline. The output of each of these two lines is identical
to that of the <code>Printf</code> call above.
<p>
-<pre> <!-- progs/print.go NR==21 NR==22 -->
-21 fmt.Print(u64, &quot; &quot;, t, &quot; &quot;, a, &quot;\n&quot;)
-22 fmt.Println(u64, t, a)
+<pre><!-- progs/print.go 21 22
+--> fmt.Print(u64, &#34; &#34;, t, &#34; &#34;, a, &#34;\n&#34;)
+ fmt.Println(u64, t, a)
</pre>
<p>
If you have your own type you'd like <code>Printf</code> or <code>Print</code> to format,
@@ -1059,27 +1060,27 @@ routines will examine the value to inquire whether it implements
the method and if so, use it rather than some other formatting.
Here's a simple example.
<p>
-<pre> <!-- progs/print_string.go NR==9 END -->
-09 type testType struct {
-10 a int
-11 b string
-12 }
+<pre><!-- progs/print_string.go 9 $
+-->type testType struct {
+ a int
+ b string
+}
-14 func (t *testType) String() string {
-15 return fmt.Sprint(t.a) + &quot; &quot; + t.b
-16 }
+func (t *testType) String() string {
+ return fmt.Sprint(t.a) + &#34; &#34; + t.b
+}
-18 func main() {
-19 t := &amp;testType{77, &quot;Sunset Strip&quot;}
-20 fmt.Println(t)
-21 }
+func main() {
+ t := &amp;testType{77, &#34;Sunset Strip&#34;}
+ fmt.Println(t)
+}
</pre>
<p>
Since <code>*testType</code> has a <code>String</code> method, the
default formatter for that type will use it and produce the output
<p>
<pre>
- 77 Sunset Strip
+77 Sunset Strip
</pre>
<p>
Observe that the <code>String</code> method calls <code>Sprint</code> (the obvious Go
@@ -1101,18 +1102,18 @@ Schematically, given a value <code>v</code>, it does this:
<p>
<p>
<pre>
- type Stringer interface {
- String() string
- }
+type Stringer interface {
+ String() string
+}
</pre>
<p>
<pre>
- s, ok := v.(Stringer) // Test whether v implements "String()"
- if ok {
- result = s.String()
- } else {
- result = defaultOutput(v)
- }
+s, ok := v.(Stringer) // Test whether v implements "String()"
+if ok {
+ result = s.String()
+} else {
+ result = defaultOutput(v)
+}
</pre>
<p>
The code uses a ``type assertion'' (<code>v.(Stringer)</code>) to test if the value stored in
@@ -1133,9 +1134,9 @@ not a file. Instead, it is a variable of type <code>io.Writer</code>, which is
interface type defined in the <code>io</code> library:
<p>
<pre>
- type Writer interface {
- Write(p []byte) (n int, err os.Error)
- }
+type Writer interface {
+ Write(p []byte) (n int, err os.Error)
+}
</pre>
<p>
(This interface is another conventional name, this time for <code>Write</code>; there are also
@@ -1178,13 +1179,13 @@ coordinates the communication; as with maps and slices, use
<p>
Here is the first function in <code>progs/sieve.go</code>:
<p>
-<pre> <!-- progs/sieve.go /Send/ /^}/ -->
-09 // Send the sequence 2, 3, 4, ... to channel 'ch'.
-10 func generate(ch chan int) {
-11 for i := 2; ; i++ {
-12 ch &lt;- i // Send 'i' to channel 'ch'.
-13 }
-14 }
+<pre><!-- progs/sieve.go /Send/ /^}/
+-->// Send the sequence 2, 3, 4, ... to channel 'ch'.
+func generate(ch chan int) {
+ for i := 2; ; i++ {
+ ch &lt;- i // Send &#39;i&#39; to channel &#39;ch&#39;.
+ }
+}
</pre>
<p>
The <code>generate</code> function sends the sequence 2, 3, 4, 5, ... to its
@@ -1197,17 +1198,17 @@ channel, and a prime number. It copies values from the input to the
output, discarding anything divisible by the prime. The unary communications
operator <code>&lt;-</code> (receive) retrieves the next value on the channel.
<p>
-<pre> <!-- progs/sieve.go /Copy.the/ /^}/ -->
-16 // Copy the values from channel 'in' to channel 'out',
-17 // removing those divisible by 'prime'.
-18 func filter(in, out chan int, prime int) {
-19 for {
-20 i := &lt;-in // Receive value of new variable 'i' from 'in'.
-21 if i % prime != 0 {
-22 out &lt;- i // Send 'i' to channel 'out'.
-23 }
-24 }
-25 }
+<pre><!-- progs/sieve.go /Copy.the/ /^}/
+-->// Copy the values from channel 'in' to channel 'out',
+// removing those divisible by 'prime'.
+func filter(in, out chan int, prime int) {
+ for {
+ i := &lt;-in // Receive value of new variable &#39;i&#39; from &#39;in&#39;.
+ if i % prime != 0 {
+ out &lt;- i // Send &#39;i&#39; to channel &#39;out&#39;.
+ }
+ }
+}
</pre>
<p>
The generator and filters execute concurrently. Go has
@@ -1219,37 +1220,37 @@ this starts the function running in parallel with the current
computation but in the same address space:
<p>
<pre>
- go sum(hugeArray) // calculate sum in the background
+go sum(hugeArray) // calculate sum in the background
</pre>
<p>
If you want to know when the calculation is done, pass a channel
on which it can report back:
<p>
<pre>
- ch := make(chan int)
- go sum(hugeArray, ch)
- // ... do something else for a while
- result := &lt;-ch // wait for, and retrieve, result
+ch := make(chan int)
+go sum(hugeArray, ch)
+// ... do something else for a while
+result := &lt;-ch // wait for, and retrieve, result
</pre>
<p>
Back to our prime sieve. Here's how the sieve pipeline is stitched
together:
<p>
-<pre> <!-- progs/sieve.go /func.main/ /^}/ -->
-28 func main() {
-29 ch := make(chan int) // Create a new channel.
-30 go generate(ch) // Start generate() as a goroutine.
-31 for i := 0; i &lt; 100; i++ { // Print the first hundred primes.
-32 prime := &lt;-ch
-33 fmt.Println(prime)
-34 ch1 := make(chan int)
-35 go filter(ch, ch1, prime)
-36 ch = ch1
-37 }
-38 }
-</pre>
-<p>
-Line 29 creates the initial channel to pass to <code>generate</code>, which it
+<pre><!-- progs/sieve.go /func.main/ /^}/
+-->func main() {
+ ch := make(chan int) // Create a new channel.
+ go generate(ch) // Start generate() as a goroutine.
+ for i := 0; i &lt; 100; i++ { // Print the first hundred primes.
+ prime := &lt;-ch
+ fmt.Println(prime)
+ ch1 := make(chan int)
+ go filter(ch, ch1, prime)
+ ch = ch1
+ }
+}
+</pre>
+<p>
+The first line of <code>main</code> creates the initial channel to pass to <code>generate</code>, which it
then starts up. As each prime pops out of the channel, a new <code>filter</code>
is added to the pipeline and <i>its</i> output becomes the new value
of <code>ch</code>.
@@ -1258,16 +1259,16 @@ The sieve program can be tweaked to use a pattern common
in this style of programming. Here is a variant version
of <code>generate</code>, from <code>progs/sieve1.go</code>:
<p>
-<pre> <!-- progs/sieve1.go /func.generate/ /^}/ -->
-10 func generate() chan int {
-11 ch := make(chan int)
-12 go func(){
-13 for i := 2; ; i++ {
-14 ch &lt;- i
-15 }
-16 }()
-17 return ch
-18 }
+<pre><!-- progs/sieve1.go /func.generate/ /^}/
+-->func generate() chan int {
+ ch := make(chan int)
+ go func(){
+ for i := 2; ; i++ {
+ ch &lt;- i
+ }
+ }()
+ return ch
+}
</pre>
<p>
This version does all the setup internally. It creates the output
@@ -1275,54 +1276,54 @@ channel, launches a goroutine running a function literal, and
returns the channel to the caller. It is a factory for concurrent
execution, starting the goroutine and returning its connection.
<p>
-The function literal notation (lines 12-16) allows us to construct an
+The function literal notation used in the <code>go</code> statement allows us to construct an
anonymous function and invoke it on the spot. Notice that the local
variable <code>ch</code> is available to the function literal and lives on even
after <code>generate</code> returns.
<p>
The same change can be made to <code>filter</code>:
<p>
-<pre> <!-- progs/sieve1.go /func.filter/ /^}/ -->
-21 func filter(in chan int, prime int) chan int {
-22 out := make(chan int)
-23 go func() {
-24 for {
-25 if i := &lt;-in; i % prime != 0 {
-26 out &lt;- i
-27 }
-28 }
-29 }()
-30 return out
-31 }
+<pre><!-- progs/sieve1.go /func.filter/ /^}/
+-->func filter(in chan int, prime int) chan int {
+ out := make(chan int)
+ go func() {
+ for {
+ if i := &lt;-in; i % prime != 0 {
+ out &lt;- i
+ }
+ }
+ }()
+ return out
+}
</pre>
<p>
The <code>sieve</code> function's main loop becomes simpler and clearer as a
result, and while we're at it let's turn it into a factory too:
<p>
-<pre> <!-- progs/sieve1.go /func.sieve/ /^}/ -->
-33 func sieve() chan int {
-34 out := make(chan int)
-35 go func() {
-36 ch := generate()
-37 for {
-38 prime := &lt;-ch
-39 out &lt;- prime
-40 ch = filter(ch, prime)
-41 }
-42 }()
-43 return out
-44 }
+<pre><!-- progs/sieve1.go /func.sieve/ /^}/
+-->func sieve() chan int {
+ out := make(chan int)
+ go func() {
+ ch := generate()
+ for {
+ prime := &lt;-ch
+ out &lt;- prime
+ ch = filter(ch, prime)
+ }
+ }()
+ return out
+}
</pre>
<p>
Now <code>main</code>'s interface to the prime sieve is a channel of primes:
<p>
-<pre> <!-- progs/sieve1.go /func.main/ /^}/ -->
-46 func main() {
-47 primes := sieve()
-48 for i := 0; i &lt; 100; i++ { // Print the first hundred primes.
-49 fmt.Println(&lt;-primes)
-50 }
-51 }
+<pre><!-- progs/sieve1.go /func.main/ /^}/
+-->func main() {
+ primes := sieve()
+ for i := 0; i &lt; 100; i++ { // Print the first hundred primes.
+ fmt.Println(&lt;-primes)
+ }
+}
</pre>
<p>
<h2>Multiplexing</h2>
@@ -1334,102 +1335,102 @@ A realistic client-server program is a lot of code, so here is a very simple sub
to illustrate the idea. It starts by defining a <code>request</code> type, which embeds a channel
that will be used for the reply.
<p>
-<pre> <!-- progs/server.go /type.request/ /^}/ -->
-09 type request struct {
-10 a, b int
-11 replyc chan int
-12 }
+<pre><!-- progs/server.go /type.request/ /^}/
+-->type request struct {
+ a, b int
+ replyc chan int
+}
</pre>
<p>
The server will be trivial: it will do simple binary operations on integers. Here's the
code that invokes the operation and responds to the request:
<p>
-<pre> <!-- progs/server.go /type.binOp/ /^}/ -->
-14 type binOp func(a, b int) int
+<pre><!-- progs/server.go /type.binOp/ /^}/
+-->type binOp func(a, b int) int
-16 func run(op binOp, req *request) {
-17 reply := op(req.a, req.b)
-18 req.replyc &lt;- reply
-19 }
+func run(op binOp, req *request) {
+ reply := op(req.a, req.b)
+ req.replyc &lt;- reply
+}
</pre>
<p>
-Line 14 defines the name <code>binOp</code> to be a function taking two integers and
+The type declaration makes <code>binOp</code> represent a function taking two integers and
returning a third.
<p>
The <code>server</code> routine loops forever, receiving requests and, to avoid blocking due to
a long-running operation, starting a goroutine to do the actual work.
<p>
-<pre> <!-- progs/server.go /func.server/ /^}/ -->
-21 func server(op binOp, service chan *request) {
-22 for {
-23 req := &lt;-service
-24 go run(op, req) // don't wait for it
-25 }
-26 }
+<pre><!-- progs/server.go /func.server/ /^}/
+-->func server(op binOp, service chan *request) {
+ for {
+ req := &lt;-service
+ go run(op, req) // don't wait for it
+ }
+}
</pre>
<p>
We construct a server in a familiar way, starting it and returning a channel
connected to it:
<p>
-<pre> <!-- progs/server.go /func.startServer/ /^}/ -->
-28 func startServer(op binOp) chan *request {
-29 req := make(chan *request)
-30 go server(op, req)
-31 return req
-32 }
+<pre><!-- progs/server.go /func.startServer/ /^}/
+-->func startServer(op binOp) chan *request {
+ req := make(chan *request)
+ go server(op, req)
+ return req
+}
</pre>
<p>
Here's a simple test. It starts a server with an addition operator and sends out
<code>N</code> requests without waiting for the replies. Only after all the requests are sent
does it check the results.
<p>
-<pre> <!-- progs/server.go /func.main/ /^}/ -->
-34 func main() {
-35 adder := startServer(func(a, b int) int { return a + b })
-36 const N = 100
-37 var reqs [N]request
-38 for i := 0; i &lt; N; i++ {
-39 req := &amp;reqs[i]
-40 req.a = i
-41 req.b = i + N
-42 req.replyc = make(chan int)
-43 adder &lt;- req
-44 }
-45 for i := N-1; i &gt;= 0; i-- { // doesn't matter what order
-46 if &lt;-reqs[i].replyc != N + 2*i {
-47 fmt.Println(&quot;fail at&quot;, i)
-48 }
-49 }
-50 fmt.Println(&quot;done&quot;)
-51 }
+<pre><!-- progs/server.go /func.main/ /^}/
+-->func main() {
+ adder := startServer(func(a, b int) int { return a + b })
+ const N = 100
+ var reqs [N]request
+ for i := 0; i &lt; N; i++ {
+ req := &amp;reqs[i]
+ req.a = i
+ req.b = i + N
+ req.replyc = make(chan int)
+ adder &lt;- req
+ }
+ for i := N-1; i &gt;= 0; i-- { // doesn&#39;t matter what order
+ if &lt;-reqs[i].replyc != N + 2*i {
+ fmt.Println(&#34;fail at&#34;, i)
+ }
+ }
+ fmt.Println(&#34;done&#34;)
+}
</pre>
<p>
One annoyance with this program is that it doesn't shut down the server cleanly; when <code>main</code> returns
there are a number of lingering goroutines blocked on communication. To solve this,
we can provide a second, <code>quit</code> channel to the server:
<p>
-<pre> <!-- progs/server1.go /func.startServer/ /^}/ -->
-32 func startServer(op binOp) (service chan *request, quit chan bool) {
-33 service = make(chan *request)
-34 quit = make(chan bool)
-35 go server(op, service, quit)
-36 return service, quit
-37 }
+<pre><!-- progs/server1.go /func.startServer/ /^}/
+-->func startServer(op binOp) (service chan *request, quit chan bool) {
+ service = make(chan *request)
+ quit = make(chan bool)
+ go server(op, service, quit)
+ return service, quit
+}
</pre>
<p>
It passes the quit channel to the <code>server</code> function, which uses it like this:
<p>
-<pre> <!-- progs/server1.go /func.server/ /^}/ -->
-21 func server(op binOp, service chan *request, quit chan bool) {
-22 for {
-23 select {
-24 case req := &lt;-service:
-25 go run(op, req) // don't wait for it
-26 case &lt;-quit:
-27 return
-28 }
-29 }
-30 }
+<pre><!-- progs/server1.go /func.server/ /^}/
+-->func server(op binOp, service chan *request, quit chan bool) {
+ for {
+ select {
+ case req := &lt;-service:
+ go run(op, req) // don't wait for it
+ case &lt;-quit:
+ return
+ }
+ }
+}
</pre>
<p>
Inside <code>server</code>, the <code>select</code> statement chooses which of the multiple communications
@@ -1442,12 +1443,12 @@ returns, terminating its execution.
All that's left is to strobe the <code>quit</code> channel
at the end of main:
<p>
-<pre> <!-- progs/server1.go /adder,.quit/ -->
-40 adder, quit := startServer(func(a, b int) int { return a + b })
+<pre><!-- progs/server1.go /adder,.quit/
+--> adder, quit := startServer(func(a, b int) int { return a + b })
</pre>
...
-<pre> <!-- progs/server1.go /quit....true/ -->
-55 quit &lt;- true
+<pre><!-- progs/server1.go /quit....true/
+--> quit &lt;- true
</pre>
<p>
There's a lot more to Go programming and concurrent programming in general but this
diff --git a/doc/go_tutorial.txt b/doc/go_tutorial.txt
index 513190ef2..17ef6eee9 100644
--- a/doc/go_tutorial.txt
+++ b/doc/go_tutorial.txt
@@ -28,7 +28,7 @@ Hello, World
Let's start in the usual way:
---PROG progs/helloworld.go /package/ END
+!src progs/helloworld.go /package/ $
Every Go source file declares, using a "package" statement, which package it's part of.
It may also import other packages to use their facilities.
@@ -107,13 +107,13 @@ Echo
Next up, here's a version of the Unix utility "echo(1)":
---PROG progs/echo.go /package/ END
+!src progs/echo.go /package/ $
This program is small but it's doing a number of new things. In the last example,
we saw "func" introduce a function. The keywords "var", "const", and "type"
(not used yet) also introduce declarations, as does "import".
Notice that we can group declarations of the same sort into
-parenthesized lists, one item per line, as on lines 7-10 and 14-17.
+parenthesized lists, one item per line, as in the "import" and "const" clauses here.
But it's not necessary to do so; we could have said
const Space = " "
@@ -163,7 +163,7 @@ or we could go even shorter and write the idiom
The ":=" operator is used a lot in Go to represent an initializing declaration.
There's one in the "for" clause on the next line:
---PROG progs/echo.go /for/
+!src progs/echo.go /for/
The "flag" package has parsed the arguments and left the non-flag arguments
in a list that can be iterated over in the obvious way.
@@ -210,7 +210,7 @@ Once you've built a string <i>value</i>, you can't change it, although
of course you can change a string <i>variable</i> simply by
reassigning it. This snippet from "strings.go" is legal code:
---PROG progs/strings.go /hello/ /ciao/
+!src progs/strings.go /hello/ /ciao/
However the following statements are illegal because they would modify
a "string" value:
@@ -269,7 +269,7 @@ will slice the whole array.
Using slices one can write this function (from "sum.go"):
---PROG progs/sum.go /sum/ /^}/
+!src progs/sum.go /sum/ /^}/
Note how the return type ("int") is defined for "sum" by stating it
after the parameter list.
@@ -386,7 +386,7 @@ An I/O Package
Next we'll look at a simple package for doing file I/O with an
open/close/read/write interface. Here's the start of "file.go":
---PROG progs/file.go /package/ /^}/
+!src progs/file.go /package/ /^}/
The first few lines declare the name of the
package&mdash;"file"&mdash;and then import two packages. The "os"
@@ -416,7 +416,7 @@ will soon give it some exported, upper-case methods.
First, though, here is a factory to create a "File":
---PROG progs/file.go /newFile/ /^}/
+!src progs/file.go /newFile/ /^}/
This returns a pointer to a new "File" structure with the file descriptor and name
filled in. This code uses Go's notion of a ''composite literal'', analogous to
@@ -433,12 +433,12 @@ composite literal, as is done here on line 21.
We can use the factory to construct some familiar, exported variables of type "*File":
---PROG progs/file.go /var/ /^.$/
+!src progs/file.go /var/ /^.$/
The "newFile" function was not exported because it's internal. The proper,
exported factory to use is "OpenFile" (we'll explain that name in a moment):
---PROG progs/file.go /func.OpenFile/ /^}/
+!src progs/file.go /func.OpenFile/ /^}/
There are a number of new things in these few lines. First, "OpenFile" returns
multiple values, a "File" and an error (more about errors in a moment).
@@ -468,9 +468,9 @@ the implementation of our "Open" and "Create"; they're trivial
wrappers that eliminate common errors by capturing
the tricky standard arguments to open and, especially, to create a file:
---PROG progs/file.go /^const/ /^}/
+!src progs/file.go /^const/ /^}/
---PROG progs/file.go /func.Create/ /^}/
+!src progs/file.go /func.Create/ /^}/
Back to our main story.
Now that we can build "Files", we can write methods for them. To declare
@@ -479,7 +479,7 @@ of that type, placed
in parentheses before the function name. Here are some methods for "*File",
each of which declares a receiver variable "file".
---PROG progs/file.go /Close/ END
+!src progs/file.go /Close/ $
There is no implicit "this" and the receiver variable must be used to access
members of the structure. Methods are not declared within
@@ -496,7 +496,7 @@ set of such error values.
We can now use our new package:
---PROG progs/helloworld3.go /package/ END
+!src progs/helloworld3.go /package/ $
The ''"./"'' in the import of ''"./file"'' tells the compiler
to use our own package rather than
@@ -520,12 +520,12 @@ Rotting cats
Building on the "file" package, here's a simple version of the Unix utility "cat(1)",
"progs/cat.go":
---PROG progs/cat.go /package/ END
+!src progs/cat.go /package/ $
By now this should be easy to follow, but the "switch" statement introduces some
new features. Like a "for" loop, an "if" or "switch" can include an
-initialization statement. The "switch" on line 18 uses one to create variables
-"nr" and "er" to hold the return values from the call to "f.Read". (The "if" on line 25
+initialization statement. The "switch" statement in "cat" uses one to create variables
+"nr" and "er" to hold the return values from the call to "f.Read". (The "if" a few lines later
has the same idea.) The "switch" statement is general: it evaluates the cases
from top to bottom looking for the first case that matches the value; the
case expressions don't need to be constants or even integers, as long as
@@ -537,7 +537,7 @@ in a "for" statement, a missing value means "true". In fact, such a "switch"
is a form of "if-else" chain. While we're here, it should be mentioned that in
"switch" statements each "case" has an implicit "break".
-Line 25 calls "Write" by slicing the incoming buffer, which is itself a slice.
+The argument to "file.Stdout.Write" is created by slicing the array "buf".
Slices provide the standard Go way to handle I/O buffers.
Now let's make a variant of "cat" that optionally does "rot13" on its input.
@@ -548,7 +548,7 @@ The "cat" subroutine uses only two methods of "f": "Read" and "String",
so let's start by defining an interface that has exactly those two methods.
Here is code from "progs/cat_rot13.go":
---PROG progs/cat_rot13.go /type.reader/ /^}/
+!src progs/cat_rot13.go /type.reader/ /^}/
Any type that has the two methods of "reader"&mdash;regardless of whatever
other methods the type may also have&mdash;is said to <i>implement</i> the
@@ -560,34 +560,32 @@ existing "reader" and does "rot13" on the data. To do this, we just define
the type and implement the methods and with no other bookkeeping,
we have a second implementation of the "reader" interface.
---PROG progs/cat_rot13.go /type.rotate13/ /end.of.rotate13/
+!src progs/cat_rot13.go /type.rotate13/ /end.of.rotate13/
-(The "rot13" function called on line 42 is trivial and not worth reproducing here.)
+(The "rot13" function called in "Read" is trivial and not worth reproducing here.)
To use the new feature, we define a flag:
---PROG progs/cat_rot13.go /rot13Flag/
+!src progs/cat_rot13.go /rot13Flag/
and use it from within a mostly unchanged "cat" function:
---PROG progs/cat_rot13.go /func.cat/ /^}/
+!src progs/cat_rot13.go /func.cat/ /^}/
(We could also do the wrapping in "main" and leave "cat" mostly alone, except
for changing the type of the argument; consider that an exercise.)
-Lines 56 through 58 set it all up: If the "rot13" flag is true, wrap the "reader"
+The "if" at the top of "cat" sets it all up: If the "rot13" flag is true, wrap the "reader"
we received into a "rotate13" and proceed. Note that the interface variables
are values, not pointers: the argument is of type "reader", not "*reader",
even though under the covers it holds a pointer to a "struct".
Here it is in action:
-<pre>
$ echo abcdefghijklmnopqrstuvwxyz | ./cat
abcdefghijklmnopqrstuvwxyz
$ echo abcdefghijklmnopqrstuvwxyz | ./cat --rot13
nopqrstuvwxyzabcdefghijklm
$
-</pre>
Fans of dependency injection may take cheer from how easily interfaces
allow us to substitute the implementation of a file descriptor.
@@ -601,9 +599,7 @@ as we saw with "rot13". The type "file.File" implements "reader"; it could also
implement a "writer", or any other interface built from its methods that
fits the current situation. Consider the <i>empty interface</i>
-<pre>
type Empty interface {}
-</pre>
<i>Every</i> type implements the empty interface, which makes it
useful for things like containers.
@@ -618,17 +614,17 @@ same interface variable.
As an example, consider this simple sort algorithm taken from "progs/sort.go":
---PROG progs/sort.go /func.Sort/ /^}/
+!src progs/sort.go /func.Sort/ /^}/
The code needs only three methods, which we wrap into sort's "Interface":
---PROG progs/sort.go /interface/ /^}/
+!src progs/sort.go /interface/ /^}/
We can apply "Sort" to any type that implements "Len", "Less", and "Swap".
The "sort" package includes the necessary methods to allow sorting of
arrays of integers, strings, etc.; here's the code for arrays of "int"
---PROG progs/sort.go /type.*IntArray/ /Swap/
+!src progs/sort.go /type.*IntSlice/ /Swap/
Here we see methods defined for non-"struct" types. You can define methods
for any type you define and name in your package.
@@ -637,12 +633,12 @@ And now a routine to test it out, from "progs/sortmain.go". This
uses a function in the "sort" package, omitted here for brevity,
to test that the result is sorted.
---PROG progs/sortmain.go /func.ints/ /^}/
+!src progs/sortmain.go /func.ints/ /^}/
If we have a new type we want to be able to sort, all we need to do is
to implement the three methods for that type, like this:
---PROG progs/sortmain.go /type.day/ /Swap/
+!src progs/sortmain.go /type.day/ /Swap/
Printing
@@ -675,7 +671,7 @@ argument. It's easier in many cases in Go. Instead of "%llud" you
can just say "%d"; "Printf" knows the size and signedness of the
integer and can do the right thing for you. The snippet
---PROG progs/print.go 'NR==10' 'NR==11'
+!src progs/print.go 10 11
prints
@@ -684,7 +680,7 @@ prints
In fact, if you're lazy the format "%v" will print, in a simple
appropriate style, any value, even an array or structure. The output of
---PROG progs/print.go 'NR==14' 'NR==20'
+!src progs/print.go 14 20
is
@@ -697,7 +693,7 @@ of "%v" while "Println" inserts spaces between arguments
and adds a newline. The output of each of these two lines is identical
to that of the "Printf" call above.
---PROG progs/print.go 'NR==21' 'NR==22'
+!src progs/print.go 21 22
If you have your own type you'd like "Printf" or "Print" to format,
just give it a "String" method that returns a string. The print
@@ -705,7 +701,7 @@ routines will examine the value to inquire whether it implements
the method and if so, use it rather than some other formatting.
Here's a simple example.
---PROG progs/print_string.go 'NR==9' END
+!src progs/print_string.go 9 $
Since "*testType" has a "String" method, the
default formatter for that type will use it and produce the output
@@ -803,7 +799,7 @@ coordinates the communication; as with maps and slices, use
Here is the first function in "progs/sieve.go":
---PROG progs/sieve.go /Send/ /^}/
+!src progs/sieve.go /Send/ /^}/
The "generate" function sends the sequence 2, 3, 4, 5, ... to its
argument channel, "ch", using the binary communications operator "&lt;-".
@@ -815,7 +811,7 @@ channel, and a prime number. It copies values from the input to the
output, discarding anything divisible by the prime. The unary communications
operator "&lt;-" (receive) retrieves the next value on the channel.
---PROG progs/sieve.go /Copy.the/ /^}/
+!src progs/sieve.go /Copy.the/ /^}/
The generator and filters execute concurrently. Go has
its own model of process/threads/light-weight processes/coroutines,
@@ -838,9 +834,9 @@ on which it can report back:
Back to our prime sieve. Here's how the sieve pipeline is stitched
together:
---PROG progs/sieve.go /func.main/ /^}/
+!src progs/sieve.go /func.main/ /^}/
-Line 29 creates the initial channel to pass to "generate", which it
+The first line of "main" creates the initial channel to pass to "generate", which it
then starts up. As each prime pops out of the channel, a new "filter"
is added to the pipeline and <i>its</i> output becomes the new value
of "ch".
@@ -849,30 +845,30 @@ The sieve program can be tweaked to use a pattern common
in this style of programming. Here is a variant version
of "generate", from "progs/sieve1.go":
---PROG progs/sieve1.go /func.generate/ /^}/
+!src progs/sieve1.go /func.generate/ /^}/
This version does all the setup internally. It creates the output
channel, launches a goroutine running a function literal, and
returns the channel to the caller. It is a factory for concurrent
execution, starting the goroutine and returning its connection.
-The function literal notation (lines 12-16) allows us to construct an
+The function literal notation used in the "go" statement allows us to construct an
anonymous function and invoke it on the spot. Notice that the local
variable "ch" is available to the function literal and lives on even
after "generate" returns.
The same change can be made to "filter":
---PROG progs/sieve1.go /func.filter/ /^}/
+!src progs/sieve1.go /func.filter/ /^}/
The "sieve" function's main loop becomes simpler and clearer as a
result, and while we're at it let's turn it into a factory too:
---PROG progs/sieve1.go /func.sieve/ /^}/
+!src progs/sieve1.go /func.sieve/ /^}/
Now "main"'s interface to the prime sieve is a channel of primes:
---PROG progs/sieve1.go /func.main/ /^}/
+!src progs/sieve1.go /func.main/ /^}/
Multiplexing
----
@@ -884,41 +880,41 @@ A realistic client-server program is a lot of code, so here is a very simple sub
to illustrate the idea. It starts by defining a "request" type, which embeds a channel
that will be used for the reply.
---PROG progs/server.go /type.request/ /^}/
+!src progs/server.go /type.request/ /^}/
The server will be trivial: it will do simple binary operations on integers. Here's the
code that invokes the operation and responds to the request:
---PROG progs/server.go /type.binOp/ /^}/
+!src progs/server.go /type.binOp/ /^}/
-Line 14 defines the name "binOp" to be a function taking two integers and
+The type declaration makes "binOp" represent a function taking two integers and
returning a third.
The "server" routine loops forever, receiving requests and, to avoid blocking due to
a long-running operation, starting a goroutine to do the actual work.
---PROG progs/server.go /func.server/ /^}/
+!src progs/server.go /func.server/ /^}/
We construct a server in a familiar way, starting it and returning a channel
connected to it:
---PROG progs/server.go /func.startServer/ /^}/
+!src progs/server.go /func.startServer/ /^}/
Here's a simple test. It starts a server with an addition operator and sends out
"N" requests without waiting for the replies. Only after all the requests are sent
does it check the results.
---PROG progs/server.go /func.main/ /^}/
+!src progs/server.go /func.main/ /^}/
One annoyance with this program is that it doesn't shut down the server cleanly; when "main" returns
there are a number of lingering goroutines blocked on communication. To solve this,
we can provide a second, "quit" channel to the server:
---PROG progs/server1.go /func.startServer/ /^}/
+!src progs/server1.go /func.startServer/ /^}/
It passes the quit channel to the "server" function, which uses it like this:
---PROG progs/server1.go /func.server/ /^}/
+!src progs/server1.go /func.server/ /^}/
Inside "server", the "select" statement chooses which of the multiple communications
listed by its cases can proceed. If all are blocked, it waits until one can proceed; if
@@ -930,9 +926,9 @@ returns, terminating its execution.
All that's left is to strobe the "quit" channel
at the end of main:
---PROG progs/server1.go /adder,.quit/
+!src progs/server1.go /adder,.quit/
...
---PROG progs/server1.go /quit....true/
+!src progs/server1.go /quit....true/
There's a lot more to Go programming and concurrent programming in general but this
quick tour should give you some of the basics.
diff --git a/doc/gopher/appenginegopher.jpg b/doc/gopher/appenginegopher.jpg
new file mode 100644
index 000000000..0a6430666
--- /dev/null
+++ b/doc/gopher/appenginegopher.jpg
Binary files differ
diff --git a/doc/gopher/appenginegophercolor.jpg b/doc/gopher/appenginegophercolor.jpg
new file mode 100644
index 000000000..68795a99b
--- /dev/null
+++ b/doc/gopher/appenginegophercolor.jpg
Binary files differ
diff --git a/doc/gopher/appenginelogo.gif b/doc/gopher/appenginelogo.gif
new file mode 100644
index 000000000..46b3c1eeb
--- /dev/null
+++ b/doc/gopher/appenginelogo.gif
Binary files differ
diff --git a/doc/htmlgen.go b/doc/htmlgen.go
index 3a8feb8bc..5318a07dc 100644
--- a/doc/htmlgen.go
+++ b/doc/htmlgen.go
@@ -2,46 +2,80 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Process plain text into HTML.
+// If --html is set, process plain text into HTML.
// - h2's are made from lines followed by a line "----\n"
-// - tab-indented blocks become <pre> blocks
+// - tab-indented blocks become <pre> blocks with the first tab deleted
// - blank lines become <p> marks (except inside <pre> tags)
// - "quoted strings" become <code>quoted strings</code>
+// Lines beginning !src define pieces of program source to be
+// extracted from other files and injected as <pre> blocks.
+// The syntax is simple: 1, 2, or 3 space-separated arguments:
+//
+// Whole file:
+// !src foo.go
+// One line (here the signature of main):
+// !src foo.go /^func.main/
+// Block of text, determined by start and end (here the body of main):
+// !src foo.go /^func.main/ /^}/
+//
+// Patterns can be /regular.expression/, a decimal number, or $
+// to signify the end of the file.
+// TODO: the regular expression cannot contain spaces; does this matter?
+
package main
import (
"bufio"
"bytes"
+ "flag"
+ "fmt"
+ "io/ioutil"
"log"
"os"
+ "regexp"
+ "strconv"
+ "strings"
+ "template"
)
var (
- lines = make([][]byte, 0, 2000) // probably big enough; grows if not
+ html = flag.Bool("html", true, "process text into HTML")
+)
+
+var (
+ // lines holds the input and is reworked in place during processing.
+ lines = make([][]byte, 0, 20000)
empty = []byte("")
newline = []byte("\n")
tab = []byte("\t")
quote = []byte(`"`)
- indent = []byte{' ', ' ', ' ', ' '}
+ indent = []byte(" ")
sectionMarker = []byte("----\n")
preStart = []byte("<pre>")
preEnd = []byte("</pre>\n")
pp = []byte("<p>\n")
+
+ srcPrefix = []byte("!src")
)
func main() {
+ flag.Parse()
read()
- headings()
- coalesce(preStart, foldPre)
- coalesce(tab, foldTabs)
- paragraphs()
- quotes()
+ programs()
+ if *html {
+ headings()
+ coalesce(preStart, foldPre)
+ coalesce(tab, foldTabs)
+ paragraphs()
+ quotes()
+ }
write()
}
+// read turns standard input into a slice of lines.
func read() {
b := bufio.NewReader(os.Stdin)
for {
@@ -56,6 +90,7 @@ func read() {
}
}
+// write puts the result on standard output.
func write() {
b := bufio.NewWriter(os.Stdout)
for _, line := range lines {
@@ -64,8 +99,104 @@ func write() {
b.Flush()
}
-// each time prefix is found on a line, call fold and replace
-// line with return value from fold.
+// programs injects source code from !src invocations.
+func programs() {
+ nlines := make([][]byte, 0, len(lines)*3/2)
+ for _, line := range lines {
+ if bytes.HasPrefix(line, srcPrefix) {
+ line = trim(line)[len(srcPrefix):]
+ prog := srcCommand(string(line))
+ if *html {
+ nlines = append(nlines, []byte(fmt.Sprintf("<pre><!--%s\n-->", line)))
+ }
+ for _, l := range prog {
+ nlines = append(nlines, htmlEscape(l))
+ }
+ if *html {
+ nlines = append(nlines, preEnd)
+ }
+ } else {
+ nlines = append(nlines, line)
+ }
+ }
+ lines = nlines
+}
+
+// srcCommand processes one !src invocation.
+func srcCommand(command string) [][]byte {
+ // TODO: quoted args so we can have 'a b'?
+ args := strings.Fields(command)
+ if len(args) == 0 || len(args) > 3 {
+ log.Fatal("bad syntax for src command: %s", command)
+ }
+ file := args[0]
+ lines := bytes.SplitAfter(readFile(file), newline)
+ // File plus zero args: whole file:
+ // !src file.go
+ if len(args) == 1 {
+ return lines
+ }
+ start := match(file, 0, lines, string(args[1]))
+ // File plus one arg: one line:
+ // !src file.go /foo/
+ if len(args) == 2 {
+ return [][]byte{lines[start]}
+ }
+ // File plus two args: range:
+ // !src file.go /foo/ /^}/
+ end := match(file, start, lines, string(args[2]))
+ return lines[start : end+1] // +1 to include matched line.
+}
+
+// htmlEscape makes sure input is HTML clean, if necessary.
+func htmlEscape(input []byte) []byte {
+ if !*html || bytes.IndexAny(input, `&"<>`) < 0 {
+ return input
+ }
+ var b bytes.Buffer
+ template.HTMLEscape(&b, input)
+ return b.Bytes()
+}
+
+// readFile reads and returns a file as part of !src processing.
+func readFile(name string) []byte {
+ file, err := ioutil.ReadFile(name)
+ if err != nil {
+ log.Fatal(err)
+ }
+ return file
+}
+
+// match identifies the input line that matches the pattern in a !src invocation.
+// If start>0, match lines starting there rather than at the beginning.
+func match(file string, start int, lines [][]byte, pattern string) int {
+ // $ matches the end of the file.
+ if pattern == "$" {
+ return len(lines) - 1
+ }
+ // Number matches the line.
+ if i, err := strconv.Atoi(pattern); err == nil {
+ return i - 1 // Lines are 1-indexed.
+ }
+ // /regexp/ matches the line that matches the regexp.
+ if len(pattern) > 2 && pattern[0] == '/' && pattern[len(pattern)-1] == '/' {
+ re, err := regexp.Compile(pattern[1 : len(pattern)-1])
+ if err != nil {
+ log.Fatal(err)
+ }
+ for i := start; i < len(lines); i++ {
+ if re.Match(lines[i]) {
+ return i
+ }
+ }
+ log.Fatalf("%s: no match for %s", file, pattern)
+ }
+ log.Fatalf("unrecognized pattern: %s", pattern)
+ return 0
+}
+
+// coalesce combines lines. Each time prefix is found on a line,
+// it calls fold and replaces the line with return value from fold.
func coalesce(prefix []byte, fold func(i int) (n int, line []byte)) {
j := 0 // output line number goes up by one each loop
for i := 0; i < len(lines); {
@@ -82,7 +213,7 @@ func coalesce(prefix []byte, fold func(i int) (n int, line []byte)) {
lines = lines[0:j]
}
-// return the <pre> block as a single slice
+// foldPre returns the <pre> block as a single slice.
func foldPre(i int) (n int, line []byte) {
buf := new(bytes.Buffer)
for i < len(lines) {
@@ -96,7 +227,7 @@ func foldPre(i int) (n int, line []byte) {
return n, buf.Bytes()
}
-// return the tab-indented block as a single <pre>-bounded slice
+// foldTabs returns the tab-indented block as a single <pre>-bounded slice.
func foldTabs(i int) (n int, line []byte) {
buf := new(bytes.Buffer)
buf.WriteString("<pre>\n")
@@ -104,7 +235,7 @@ func foldTabs(i int) (n int, line []byte) {
if !bytes.HasPrefix(lines[i], tab) {
break
}
- buf.Write(lines[i])
+ buf.Write(lines[i][1:]) // delete leading tab.
n++
i++
}
@@ -112,6 +243,7 @@ func foldTabs(i int) (n int, line []byte) {
return n, buf.Bytes()
}
+// headings turns sections into HTML sections.
func headings() {
b := bufio.NewWriter(os.Stdout)
for i, l := range lines {
@@ -123,6 +255,7 @@ func headings() {
b.Flush()
}
+// paragraphs turns blank lines into paragraph marks.
func paragraphs() {
for i, l := range lines {
if bytes.Equal(l, newline) {
@@ -131,12 +264,14 @@ func paragraphs() {
}
}
+// quotes turns "x" in the file into <code>x</code>.
func quotes() {
for i, l := range lines {
lines[i] = codeQuotes(l)
}
}
+// quotes turns "x" in the line into <code>x</code>.
func codeQuotes(l []byte) []byte {
if bytes.HasPrefix(l, preStart) {
return l
@@ -162,7 +297,7 @@ func codeQuotes(l []byte) []byte {
return buf.Bytes()
}
-// drop trailing newline
+// trim drops the trailing newline, if present.
func trim(l []byte) []byte {
n := len(l)
if n > 0 && l[n-1] == '\n' {
@@ -171,7 +306,7 @@ func trim(l []byte) []byte {
return l
}
-// expand tabs to spaces. don't worry about columns.
+// expandTabs expands tabs to spaces. It doesn't worry about columns.
func expandTabs(l []byte) []byte {
return bytes.Replace(l, tab, indent, -1)
}
diff --git a/doc/install.html b/doc/install.html
index 2256123ec..a1bc89982 100644
--- a/doc/install.html
+++ b/doc/install.html
@@ -81,8 +81,8 @@ To build it, you need these programs installed:
<li>the standard C libraries,
<li>the parser generator Bison,
<li>GNU <tt>make</tt> (version 3.81 or later),
-<li><tt>awk</tt>, and
-<li>the text editor <tt>ed</tt>.
+and
+<li><tt>awk</tt>.
</ul>
</p>
@@ -91,7 +91,7 @@ installed as part of
<a href="http://developer.apple.com/TOOLS/Xcode/">Xcode</a>.
</p>
-<p>On Ubuntu/Debian, use <code>sudo apt-get install bison ed gawk gcc libc6-dev
+<p>On Ubuntu/Debian, use <code>sudo apt-get install bison gawk gcc libc6-dev
make</code>. If you want to build 32-bit binaries on a 64-bit system you'll
also need the <code>libc6-dev-i386</code> package.
</p>
diff --git a/doc/makehtml b/doc/makehtml
index c9ac0c8e8..1b8caed69 100755
--- a/doc/makehtml
+++ b/doc/makehtml
@@ -7,7 +7,6 @@ set -e
TXT=${1:-go_tutorial.txt} # input file
HTML=$(basename $TXT .txt).html # output file (basename)
-TMP=TEMP.txt # input to htmlgen
if ! test -w $HTML
then
@@ -15,17 +14,4 @@ then
exit 1
fi
-if grep -q '^--PROG' $TXT
-then
- echo >&2 makehtml: processing PROG sections
- <$TXT >$TMP awk '
- /^--PROG/ { system("sh ./prog.sh "$2" "$3" "$4" "); getline }
- /^/ {print}
- '
-else
- cp $TXT $TMP
-fi
-
-make htmlgen && ./htmlgen < $TMP > $HTML
-
-rm -f $TMP
+make htmlgen && ./htmlgen < $TXT > $HTML
diff --git a/doc/prog.sh b/doc/prog.sh
deleted file mode 100755
index 6a540980a..000000000
--- a/doc/prog.sh
+++ /dev/null
@@ -1,72 +0,0 @@
-#!/bin/sh
-# Copyright 2009 The Go Authors. All rights reserved.
-# Use of this source code is governed by a BSD-style
-# license that can be found in the LICENSE file.
-
-# generate HTML for a program excerpt.
-# first arg is file name
-# second arg is awk pattern to match start line
-# third arg is awk pattern to stop processing
-#
-# missing third arg means print one line
-# third arg "END" means proces rest of file
-# missing second arg means process whole file
-#
-# examples:
-#
-# prog.sh foo.go # whole file
-# prog.sh foo.go "/^func.main/" # signature of main
-# prog.sh foo.go "/^func.main/" "/^}/ # body of main
-#
-# non-blank lines are annotated with line number in file
-
-# line numbers are printed %.2d to make them equal-width for nice formatting.
-# the format gives a leading 0. the format %2d gives a leading space but
-# that appears to confuse sanjay's makehtml formatter into bungling quotes
-# because it makes some lines look indented.
-
-echo "<pre> <!-- $* -->"
-
-case $# in
-3)
- if test "$3" = "END" # $2 to end of file
- then
- awk '
- function LINE() { printf("%.2d\t%s\n", NR, $0) }
- BEGIN { printing = 0 }
- '$2' { printing = 1; LINE(); getline }
- printing { if($0 ~ /./) { LINE() } else { print "" } }
- '
- else # $2 through $3
- awk '
- function LINE() { printf("%.2d\t%s\n", NR, $0) }
- BEGIN { printing = 0 }
- '$2' { printing = 1; LINE(); getline }
- '$3' && printing { if(printing) {printing = 0; LINE(); exit} }
- printing { if($0 ~ /./) { LINE() } else { print "" } }
- '
- fi
- ;;
-2) # one line
- awk '
- function LINE() { printf("%.2d\t%s\n", NR, $0) }
- '$2' { LINE(); getline; exit }
- '
- ;;
-1) # whole file
- awk '
- function LINE() { printf("%.2d\t%s\n", NR, $0) }
- { if($0 ~ /./) { LINE() } else { print "" } }
- '
- ;;
-*)
- echo >&2 usage: prog.sh file.go /func.main/ /^}/
-esac <$1 |
-sed '
- s/&/\&amp;/g
- s/"/\&quot;/g
- s/</\&lt;/g
- s/>/\&gt;/g
-'
-
-echo '</pre>'
diff --git a/doc/progs/file_windows.go b/doc/progs/file_windows.go
new file mode 100644
index 000000000..d5e7c00d3
--- /dev/null
+++ b/doc/progs/file_windows.go
@@ -0,0 +1,89 @@
+// Copyright 2009 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package file
+
+import (
+ "os"
+ "syscall"
+)
+
+type File struct {
+ fd syscall.Handle // file descriptor number
+ name string // file name at Open time
+}
+
+func newFile(fd syscall.Handle, name string) *File {
+ if fd < 0 {
+ return nil
+ }
+ return &File{fd, name}
+}
+
+var (
+ Stdin = newFile(syscall.Stdin, "/dev/stdin")
+ Stdout = newFile(syscall.Stdout, "/dev/stdout")
+ Stderr = newFile(syscall.Stderr, "/dev/stderr")
+)
+
+func OpenFile(name string, mode int, perm uint32) (file *File, err os.Error) {
+ r, e := syscall.Open(name, mode, perm)
+ if e != 0 {
+ err = os.Errno(e)
+ }
+ return newFile(r, name), err
+}
+
+const (
+ O_RDONLY = syscall.O_RDONLY
+ O_RDWR = syscall.O_RDWR
+ O_CREATE = syscall.O_CREAT
+ O_TRUNC = syscall.O_TRUNC
+)
+
+func Open(name string) (file *File, err os.Error) {
+ return OpenFile(name, O_RDONLY, 0)
+}
+
+func Create(name string) (file *File, err os.Error) {
+ return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
+}
+
+func (file *File) Close() os.Error {
+ if file == nil {
+ return os.EINVAL
+ }
+ e := syscall.Close(file.fd)
+ file.fd = syscall.InvalidHandle // so it can't be closed again
+ if e != 0 {
+ return os.Errno(e)
+ }
+ return nil
+}
+
+func (file *File) Read(b []byte) (ret int, err os.Error) {
+ if file == nil {
+ return -1, os.EINVAL
+ }
+ r, e := syscall.Read(file.fd, b)
+ if e != 0 {
+ err = os.Errno(e)
+ }
+ return int(r), err
+}
+
+func (file *File) Write(b []byte) (ret int, err os.Error) {
+ if file == nil {
+ return -1, os.EINVAL
+ }
+ r, e := syscall.Write(file.fd, b)
+ if e != 0 {
+ err = os.Errno(e)
+ }
+ return int(r), err
+}
+
+func (file *File) String() string {
+ return file.name
+}
diff --git a/doc/progs/run b/doc/progs/run
index 241e65dfa..81781c9d2 100755
--- a/doc/progs/run
+++ b/doc/progs/run
@@ -14,8 +14,13 @@ fi
rm -f *.$O
+if [ "$GOOS" = "windows" ];then
+ $GC -o file.8 file_windows.go
+else
+ $GC file.go
+fi
+
for i in \
- file.go \
helloworld.go \
helloworld3.go \
echo.go \
diff --git a/doc/progs/sort.go b/doc/progs/sort.go
index 79e7f563e..47df9b351 100644
--- a/doc/progs/sort.go
+++ b/doc/progs/sort.go
@@ -30,34 +30,34 @@ func IsSorted(data Interface) bool {
// Convenience types for common cases
-type IntArray []int
+type IntSlice []int
-func (p IntArray) Len() int { return len(p) }
-func (p IntArray) Less(i, j int) bool { return p[i] < p[j] }
-func (p IntArray) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
+func (p IntSlice) Len() int { return len(p) }
+func (p IntSlice) Less(i, j int) bool { return p[i] < p[j] }
+func (p IntSlice) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
-type Float64Array []float64
+type Float64Slice []float64
-func (p Float64Array) Len() int { return len(p) }
-func (p Float64Array) Less(i, j int) bool { return p[i] < p[j] }
-func (p Float64Array) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
+func (p Float64Slice) Len() int { return len(p) }
+func (p Float64Slice) Less(i, j int) bool { return p[i] < p[j] }
+func (p Float64Slice) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
-type StringArray []string
+type StringSlice []string
-func (p StringArray) Len() int { return len(p) }
-func (p StringArray) Less(i, j int) bool { return p[i] < p[j] }
-func (p StringArray) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
+func (p StringSlice) Len() int { return len(p) }
+func (p StringSlice) Less(i, j int) bool { return p[i] < p[j] }
+func (p StringSlice) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
// Convenience wrappers for common cases
-func SortInts(a []int) { Sort(IntArray(a)) }
-func SortFloat64s(a []float64) { Sort(Float64Array(a)) }
-func SortStrings(a []string) { Sort(StringArray(a)) }
+func SortInts(a []int) { Sort(IntSlice(a)) }
+func SortFloat64s(a []float64) { Sort(Float64Slice(a)) }
+func SortStrings(a []string) { Sort(StringSlice(a)) }
-func IntsAreSorted(a []int) bool { return IsSorted(IntArray(a)) }
-func Float64sAreSorted(a []float64) bool { return IsSorted(Float64Array(a)) }
-func StringsAreSorted(a []string) bool { return IsSorted(StringArray(a)) }
+func IntsAreSorted(a []int) bool { return IsSorted(IntSlice(a)) }
+func Float64sAreSorted(a []float64) bool { return IsSorted(Float64Slice(a)) }
+func StringsAreSorted(a []string) bool { return IsSorted(StringSlice(a)) }
diff --git a/doc/progs/sortmain.go b/doc/progs/sortmain.go
index a77ae7381..28eec8d4f 100644
--- a/doc/progs/sortmain.go
+++ b/doc/progs/sortmain.go
@@ -11,7 +11,7 @@ import (
func ints() {
data := []int{74, 59, 238, -784, 9845, 959, 905, 0, 0, 42, 7586, -5467984, 7586}
- a := sort.IntArray(data)
+ a := sort.IntSlice(data)
sort.Sort(a)
if !sort.IsSorted(a) {
panic("fail")
@@ -20,7 +20,7 @@ func ints() {
func strings() {
data := []string{"monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"}
- a := sort.StringArray(data)
+ a := sort.StringSlice(data)
sort.Sort(a)
if !sort.IsSorted(a) {
panic("fail")