include ../src/Make.inc
-TARG=htmlgen
+TARG=tmpltohtml
GOFILES=\
- htmlgen.go\
+ tmpltohtml.go\
include ../src/Make.cmd
<p>
Let's start in the usual way:
<p>
-<pre><!-- progs/helloworld.go /package/ $
+<pre><!--{{code "progs/helloworld.go" `/package/` "$"}}
-->package main
import fmt "fmt" // Package implementing formatted I/O.
<p>
Next up, here's a version of the Unix utility <code>echo(1)</code>:
<p>
-<pre><!-- progs/echo.go /package/ $
+<pre><!--{{code "progs/echo.go" `/package/` "$"}}
-->package main
import (
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/
+<pre><!--{{code "progs/echo.go" `/for/`}}
--> for i := 0; i < flag.NArg(); i++ {
</pre>
<p>
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/
+<pre><!--{{code "progs/strings.go" `/hello/` `/ciao/`}}
--> s := "hello"
- if s[1] != 'e' {
+ if s[1] != 'e' {
os.Exit(1)
}
s = "good bye"
<p>
Using slices one can write this function (from <code>sum.go</code>):
<p>
-<pre><!-- progs/sum.go /sum/ /^}/
+<pre><!--{{code "progs/sum.go" `/sum/` `/^}/`}}
-->func sum(a []int) int { // returns an int
s := 0
for i := 0; i < len(a); i++ {
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/ /^}/
+<pre><!--{{code "progs/file.go" `/package/` `/^}/`}}
-->package file
import (
<p>
First, though, here is a factory to create a <code>File</code>:
<p>
-<pre><!-- progs/file.go /newFile/ /^}/
+<pre><!--{{code "progs/file.go" `/newFile/` `/^}/`}}
-->func newFile(fd int, name string) *File {
if fd < 0 {
return nil
<p>
We can use the factory to construct some familiar, exported variables of type <code>*File</code>:
<p>
-<pre><!-- progs/file.go /var/ /^.$/
+<pre><!--{{code "progs/file.go" `/var/` `/^.$/`}}
-->var (
Stdin = newFile(syscall.Stdin, "/dev/stdin")
Stdout = newFile(syscall.Stdout, "/dev/stdout")
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/ /^}/
+<pre><!--{{code "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 {
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/ /^}/
+<pre><!--{{code "progs/file.go" `/^const/` `/^}/`}}
-->const (
O_RDONLY = syscall.O_RDONLY
O_RDWR = syscall.O_RDWR
}
</pre>
<p>
-<pre><!-- progs/file.go /func.Create/ /^}/
+<pre><!--{{code "progs/file.go" `/func.Create/` `/^}/`}}
-->func Create(name string) (file *File, err os.Error) {
return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
}
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/ $
+<pre><!--{{code "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
+ file.fd = -1 // so it can't be closed again
if e != 0 {
return os.Errno(e)
}
<p>
We can now use our new package:
<p>
-<pre><!-- progs/helloworld3.go /package/ $
+<pre><!--{{code "progs/helloworld3.go" `/package/` "$"}}
-->package main
import (
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/ $
+<pre><!--{{code "progs/cat.go" `/package/` "$"}}
-->package main
import (
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/ /^}/
+<pre><!--{{code "progs/cat_rot13.go" `/type.reader/` `/^}/`}}
-->type reader interface {
Read(b []byte) (ret int, err os.Error)
String() string
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/
+<pre><!--{{code "progs/cat_rot13.go" `/type.rotate13/` `/end.of.rotate13/`}}
-->type rotate13 struct {
source reader
}
<p>
To use the new feature, we define a flag:
<p>
-<pre><!-- progs/cat_rot13.go /rot13Flag/
+<pre><!--{{code "progs/cat_rot13.go" `/rot13Flag/`}}
-->var rot13Flag = flag.Bool("rot13", false, "rot13 the input")
</pre>
<p>
and use it from within a mostly unchanged <code>cat</code> function:
<p>
-<pre><!-- progs/cat_rot13.go /func.cat/ /^}/
+<pre><!--{{code "progs/cat_rot13.go" `/func.cat/` `/^}/`}}
-->func cat(r reader) {
const NBUF = 512
var buf [NBUF]byte
<p>
As an example, consider this simple sort algorithm taken from <code>progs/sort.go</code>:
<p>
-<pre><!-- progs/sort.go /func.Sort/ /^}/
+<pre><!--{{code "progs/sort.go" `/func.Sort/` `/^}/`}}
-->func Sort(data Interface) {
for i := 1; i < data.Len(); i++ {
for j := i; j > 0 && data.Less(j, j-1); j-- {
<p>
The code needs only three methods, which we wrap into sort's <code>Interface</code>:
<p>
-<pre><!-- progs/sort.go /interface/ /^}/
+<pre><!--{{code "progs/sort.go" `/interface/` `/^}/`}}
-->type Interface interface {
Len() int
Less(i, j int) bool
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.*IntSlice/ /Swap/
+<pre><!--{{code "progs/sort.go" `/type.*IntSlice/` `/Swap/`}}
-->type IntSlice []int
func (p IntSlice) Len() int { return len(p) }
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/ /^}/
+<pre><!--{{code "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)
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/
+<pre><!--{{code "progs/sortmain.go" `/type.day/` `/Swap/`}}
-->type day struct {
num int
shortName string
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 10 11
+<pre><!--{{code "progs/print.go" 10 11}}
--> var u64 uint64 = 1<<64 - 1
fmt.Printf("%d %d\n", u64, int64(u64))
</pre>
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 14 20
+<pre><!--{{code "progs/print.go" 14 20}}
--> type T struct {
a int
b string
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 21 22
+<pre><!--{{code "progs/print.go" 21 22}}
--> fmt.Print(u64, " ", t, " ", a, "\n")
fmt.Println(u64, t, a)
</pre>
the method and if so, use it rather than some other formatting.
Here's a simple example.
<p>
-<pre><!-- progs/print_string.go 9 $
+<pre><!--{{code "progs/print_string.go" 9 "$"}}
-->type testType struct {
a int
b string
<p>
Here is the first function in <code>progs/sieve.go</code>:
<p>
-<pre><!-- progs/sieve.go /Send/ /^}/
--->// Send the sequence 2, 3, 4, ... to channel 'ch'.
+<pre><!--{{code "progs/sieve.go" `/Send/` `/^}/`}}
+-->// Send the sequence 2, 3, 4, ... to channel 'ch'.
func generate(ch chan int) {
for i := 2; ; i++ {
ch <- i // Send 'i' to channel 'ch'.
output, discarding anything divisible by the prime. The unary communications
operator <code><-</code> (receive) retrieves the next value on the channel.
<p>
-<pre><!-- progs/sieve.go /Copy.the/ /^}/
--->// Copy the values from channel 'in' to channel 'out',
-// removing those divisible by 'prime'.
+<pre><!--{{code "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 := <-in // Receive value of new variable 'i' from 'in'.
Back to our prime sieve. Here's how the sieve pipeline is stitched
together:
<p>
-<pre><!-- progs/sieve.go /func.main/ /^}/
+<pre><!--{{code "progs/sieve.go" `/func.main/` `/^}/`}}
-->func main() {
ch := make(chan int) // Create a new channel.
go generate(ch) // Start generate() as a goroutine.
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/ /^}/
+<pre><!--{{code "progs/sieve1.go" `/func.generate/` `/^}/`}}
-->func generate() chan int {
ch := make(chan int)
go func() {
<p>
The same change can be made to <code>filter</code>:
<p>
-<pre><!-- progs/sieve1.go /func.filter/ /^}/
+<pre><!--{{code "progs/sieve1.go" `/func.filter/` `/^}/`}}
-->func filter(in chan int, prime int) chan int {
out := make(chan int)
go func() {
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/ /^}/
+<pre><!--{{code "progs/sieve1.go" `/func.sieve/` `/^}/`}}
-->func sieve() chan int {
out := make(chan int)
go func() {
<p>
Now <code>main</code>'s interface to the prime sieve is a channel of primes:
<p>
-<pre><!-- progs/sieve1.go /func.main/ /^}/
+<pre><!--{{code "progs/sieve1.go" `/func.main/` `/^}/`}}
-->func main() {
primes := sieve()
for i := 0; i < 100; i++ { // Print the first hundred primes.
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/ /^}/
+<pre><!--{{code "progs/server.go" `/type.request/` `/^}/`}}
-->type request struct {
a, b int
replyc chan int
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/ /^}/
+<pre><!--{{code "progs/server.go" `/type.binOp/` `/^}/`}}
-->type binOp func(a, b int) int
func run(op binOp, req *request) {
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/ /^}/
+<pre><!--{{code "progs/server.go" `/func.server/` `/^}/`}}
-->func server(op binOp, service chan *request) {
for {
req := <-service
- go run(op, req) // don't wait for it
+ go run(op, req) // don't wait for it
}
}
</pre>
We construct a server in a familiar way, starting it and returning a channel
connected to it:
<p>
-<pre><!-- progs/server.go /func.startServer/ /^}/
+<pre><!--{{code "progs/server.go" `/func.startServer/` `/^}/`}}
-->func startServer(op binOp) chan *request {
req := make(chan *request)
go server(op, req)
<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/ /^}/
+<pre><!--{{code "progs/server.go" `/func.main/` `/^}/`}}
-->func main() {
adder := startServer(func(a, b int) int { return a + b })
const N = 100
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/ /^}/
+<pre><!--{{code "progs/server1.go" `/func.startServer/` `/^}/`}}
-->func startServer(op binOp) (service chan *request, quit chan bool) {
service = make(chan *request)
quit = make(chan bool)
<p>
It passes the quit channel to the <code>server</code> function, which uses it like this:
<p>
-<pre><!-- progs/server1.go /func.server/ /^}/
+<pre><!--{{code "progs/server1.go" `/func.server/` `/^}/`}}
-->func server(op binOp, service chan *request, quit chan bool) {
for {
select {
case req := <-service:
- go run(op, req) // don't wait for it
+ go run(op, req) // don't wait for it
case <-quit:
return
}
All that's left is to strobe the <code>quit</code> channel
at the end of main:
<p>
-<pre><!-- progs/server1.go /adder,.quit/
+<pre><!--{{code "progs/server1.go" `/adder,.quit/`}}
--> adder, quit := startServer(func(a, b int) int { return a + b })
</pre>
...
-<pre><!-- progs/server1.go /quit....true/
+<pre><!--{{code "progs/server1.go" `/quit....true/`}}
--> quit <- true
</pre>
<p>
--- /dev/null
+<!-- A Tutorial for the Go Programming Language -->
+<h2>Introduction</h2>
+<p>
+This document is a tutorial introduction to the basics of the Go programming
+language, intended for programmers familiar with C or C++. It is not a comprehensive
+guide to the language; at the moment the document closest to that is the
+<a href='/doc/go_spec.html'>language specification</a>.
+After you've read this tutorial, you should look at
+<a href='/doc/effective_go.html'>Effective Go</a>,
+which digs deeper into how the language is used and
+talks about the style and idioms of programming in Go.
+Also, slides from a 3-day course about Go are available.
+They provide some background and a lot of examples:
+<a href='/doc/GoCourseDay1.pdf'>Day 1</a>,
+<a href='/doc/GoCourseDay2.pdf'>Day 2</a>,
+<a href='/doc/GoCourseDay3.pdf'>Day 3</a>.
+<p>
+The presentation here proceeds through a series of modest programs to illustrate
+key features of the language. All the programs work (at time of writing) and are
+checked into the repository in the directory <a href='/doc/progs'><code>/doc/progs/</code></a>.
+<p>
+<h2>Hello, World</h2>
+<p>
+Let's start in the usual way:
+<p>
+{{code "progs/helloworld.go" `/package/` "$"}}
+<p>
+Every Go source file declares, using a <code>package</code> statement, which package it's part of.
+It may also import other packages to use their facilities.
+This program imports the package <code>fmt</code> to gain access to
+our old, now capitalized and package-qualified, friend, <code>fmt.Printf</code>.
+<p>
+Functions are introduced with the <code>func</code> keyword.
+The <code>main</code> package's <code>main</code> function is where the program starts running (after
+any initialization).
+<p>
+String constants can contain Unicode characters, encoded in UTF-8.
+(In fact, Go source files are defined to be encoded in UTF-8.)
+<p>
+The comment convention is the same as in C++:
+<p>
+<pre>
+/* ... */
+// ...
+</pre>
+<p>
+Later we'll have much more to say about printing.
+<p>
+<h2>Semicolons</h2>
+<p>
+You might have noticed that our program has no semicolons. In Go
+code, the only place you typically see semicolons is separating the
+clauses of <code>for</code> loops and the like; they are not necessary after
+every statement.
+<p>
+In fact, what happens is that the formal language uses semicolons,
+much as in C or Java, but they are inserted automatically
+at the end of every line that looks like the end of a statement. You
+don't need to type them yourself.
+<p>
+For details about how this is done you can see the language
+specification, but in practice all you need to know is that you
+never need to put a semicolon at the end of a line. (You can put
+them in if you want to write multiple statements per line.) As an
+extra help, you can also leave out a semicolon immediately before
+a closing brace.
+<p>
+This approach makes for clean-looking, semicolon-free code. The
+one surprise is that it's important to put the opening
+brace of a construct such as an <code>if</code> statement on the same line as
+the <code>if</code>; if you don't, there are situations that may not compile
+or may give the wrong result. The language forces the brace style
+to some extent.
+<p>
+<h2>Compiling</h2>
+<p>
+Go is a compiled language. At the moment there are two compilers.
+<code>Gccgo</code> is a Go compiler that uses the GCC back end. There is also a
+suite of compilers with different (and odd) names for each architecture:
+<code>6g</code> for the 64-bit x86, <code>8g</code> for the 32-bit x86, and more. These
+compilers run significantly faster but generate less efficient code
+than <code>gccgo</code>. At the time of writing (late 2009), they also have
+a more robust run-time system although <code>gccgo</code> is catching up.
+<p>
+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 こんにちは 世界
+$
+</pre>
+<p>
+With <code>gccgo</code> it looks a little more traditional.
+<p>
+<pre>
+$ 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>
+{{code "progs/echo.go" `/package/` "$"}}
+<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 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"
+</pre>
+<p>
+This program imports the <code>"os"</code> package to access its <code>Stdout</code> variable, of type
+<code>*os.File</code>. The <code>import</code> statement is actually a declaration: in its general form,
+as used in our ``hello world'' program,
+it names the identifier (<code>fmt</code>)
+that will be used to access members of the package imported from the file (<code>"fmt"</code>),
+found in the current directory or in a standard location.
+In this program, though, we've dropped the explicit name from the imports; by default,
+packages are imported using the name defined by the imported package,
+which by convention is of course the file name itself. Our ``hello world'' program
+could have said just <code>import "fmt"</code>.
+<p>
+You can specify your
+own import names if you want but it's only necessary if you need to resolve
+a naming conflict.
+<p>
+Given <code>os.Stdout</code> we can use its <code>WriteString</code> method to print the string.
+<p>
+After importing the <code>flag</code> package, we use a <code>var</code> declaration
+to create and initialize a global variable, called <code>omitNewline</code>,
+to hold the value of echo's <code>-n</code> flag.
+The variable has type <code>*bool</code>, pointer to <code>bool</code>.
+<p>
+In <code>main.main</code>, we parse the arguments (the call to <code>flag.Parse</code>) and then create a local
+string variable with which to build the output.
+<p>
+The declaration statement has the form
+<p>
+<pre>
+var s string = ""
+</pre>
+<p>
+This is the <code>var</code> keyword, followed by the name of the variable, followed by
+its type, followed by an equals sign and an initial value for the variable.
+<p>
+Go tries to be terse, and this declaration could be shortened. Since the
+string constant is of type string, we don't have to tell the compiler that.
+We could write
+<p>
+<pre>
+var s = ""
+</pre>
+<p>
+or we could go even shorter and write the idiom
+<p>
+<pre>
+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>
+{{code "progs/echo.go" `/for/`}}
+<p>
+The <code>flag</code> package has parsed the arguments and left the non-flag arguments
+in a list that can be iterated over in the obvious way.
+<p>
+The Go <code>for</code> statement differs from that of C in a number of ways. First,
+it's the only looping construct; there is no <code>while</code> or <code>do</code>. Second,
+there are no parentheses on the clause, but the braces on the body
+are mandatory. The same applies to the <code>if</code> and <code>switch</code> statements.
+Later examples will show some other ways <code>for</code> can be written.
+<p>
+The body of the loop builds up the string <code>s</code> by appending (using <code>+=</code>)
+the arguments and separating spaces. After the loop, if the <code>-n</code> flag is not
+set, the program appends a newline. Finally, it writes the result.
+<p>
+Notice that <code>main.main</code> is a niladic function with no return type.
+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)
+</pre>
+<p>
+The <code>os</code> package contains other essentials for getting
+started; for instance, <code>os.Args</code> is a slice used by the
+<code>flag</code> package to access the command-line arguments.
+<p>
+<h2>An Interlude about Types</h2>
+<p>
+Go has some familiar types such as <code>int</code> and <code>uint</code> (unsigned <code>int</code>), which represent
+values of the ''appropriate'' size for the machine. It also defines
+explicitly-sized types such as <code>int8</code>, <code>float64</code>, and so on, plus
+unsigned integer types such as <code>uint</code>, <code>uint32</code>, etc.
+These are distinct types; even if <code>int</code> and <code>int32</code> are both 32 bits in size,
+they are not the same type. There is also a <code>byte</code> synonym for
+<code>uint8</code>, which is the element type for strings.
+<p>
+Floating-point types are always sized: <code>float32</code> and <code>float64</code>,
+plus <code>complex64</code> (two <code>float32s</code>) and <code>complex128</code>
+(two <code>float64s</code>). Complex numbers are outside the
+scope of this tutorial.
+<p>
+Speaking of <code>string</code>, that's a built-in type as well. Strings are
+<i>immutable values</i>—they are not just arrays of <code>byte</code> values.
+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>
+{{code "progs/strings.go" `/hello/` `/ciao/`}}
+<p>
+However the following statements are illegal because they would modify
+a <code>string</code> value:
+<p>
+<pre>
+s[0] = 'x'
+(*p)[1] = 'y'
+</pre>
+<p>
+In C++ terms, Go strings are a bit like <code>const strings</code>, while pointers
+to strings are analogous to <code>const string</code> references.
+<p>
+Yes, there are pointers. However, Go simplifies their use a little;
+read on.
+<p>
+Arrays are declared like this:
+<p>
+<pre>
+var arrayOfInt [10]int
+</pre>
+<p>
+Arrays, like strings, are values, but they are mutable. This differs
+from C, in which <code>arrayOfInt</code> would be usable as a pointer to <code>int</code>.
+In Go, since arrays are values, it's meaningful (and useful) to talk
+about pointers to arrays.
+<p>
+The size of the array is part of its type; however, one can declare
+a <i>slice</i> variable to hold a reference to any array, of any size,
+with the same element type.
+A <i>slice
+expression</i> has the form <code>a[low : high]</code>, representing
+the internal array indexed from <code>low</code> through <code>high-1</code>; the resulting
+slice is indexed from <code>0</code> through <code>high-low-1</code>.
+In short, slices look a lot like arrays but with
+no explicit size (<code>[]</code> vs. <code>[10]</code>) and they reference a segment of
+an underlying, usually anonymous, regular array. Multiple slices
+can share data if they represent pieces of the same array;
+multiple arrays can never share data.
+<p>
+Slices are much more common in Go programs than
+regular arrays; they're more flexible, have reference semantics,
+and are efficient. What they lack is the precise control of storage
+layout of a regular array; if you want to have a hundred elements
+of an array stored within your structure, you should use a regular
+array. To create one, use a compound value <i>constructor</i>—an
+expression formed
+from a type followed by a brace-bounded expression like this:
+<p>
+<pre>
+[3]int{1,2,3}
+</pre>
+<p>
+In this case the constructor builds an array of 3 <code>ints</code>.
+<p>
+When passing an array to a function, you almost always want
+to declare the formal parameter to be a slice. When you call
+the function, slice the array to create
+(efficiently) a slice reference and pass that.
+By default, the lower and upper bounds of a slice match the
+ends of the existing object, so the concise notation <code>[:]</code>
+will slice the whole array.
+<p>
+Using slices one can write this function (from <code>sum.go</code>):
+<p>
+{{code "progs/sum.go" `/sum/` `/^}/`}}
+<p>
+Note how the return type (<code>int</code>) is defined for <code>sum</code> by stating it
+after the parameter list.
+<p>
+To call the function, we slice the array. This intricate call (we'll show
+a simpler way in a moment) constructs
+an array and slices it:
+<p>
+<pre>
+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}[:])
+</pre>
+<p>
+That's fussier than necessary, though.
+In practice, unless you're meticulous about storage layout within a
+data structure, a slice itself—using empty brackets with no size—is all you need:
+<p>
+<pre>
+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}
+</pre>
+<p>
+The built-in function <code>len</code>, which returns number of elements,
+makes its first appearance in <code>sum</code>. It works on strings, arrays,
+slices, maps, and channels.
+<p>
+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 < 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 { ... }
+</pre>
+<p>
+This assigns <code>i</code> to the index and <code>v</code> to the value of the successive
+elements of the target of the range. See
+<a href='/doc/effective_go.html'>Effective Go</a>
+for more examples of its use.
+<p>
+<p>
+<h2>An Interlude about Allocation</h2>
+<p>
+Most types in Go are values. If you have an <code>int</code> or a <code>struct</code>
+or an array, assignment
+copies the contents of the object.
+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)
+</pre>
+<p>
+or the more idiomatic
+<p>
+<pre>
+t := new(T)
+</pre>
+<p>
+Some types—maps, slices, and channels (see below)—have reference semantics.
+If you're holding a slice or a map and you modify its contents, other variables
+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)
+</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
+</pre>
+<p>
+it creates a <code>nil</code> reference that cannot hold anything. To use the map,
+you must first initialize the reference using <code>make</code> or by assignment from an
+existing map.
+<p>
+Note that <code>new(T)</code> returns type <code>*T</code> while <code>make(T)</code> returns type
+<code>T</code>. If you (mistakenly) allocate a reference object with <code>new</code> rather than <code>make</code>,
+you receive a pointer to a nil reference, equivalent to
+declaring an uninitialized variable and taking its address.
+<p>
+<h2>An Interlude about Constants</h2>
+<p>
+Although integers come in lots of sizes in Go, integer constants do not.
+There are no constants like <code>0LL</code> or <code>0x0UL</code>. Instead, integer
+constants are evaluated as large-precision values that
+can overflow only when they are assigned to an integer variable with
+too little precision to represent the value.
+<p>
+<pre>
+const hardEight = (1 << 100) >> 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
+</pre>
+<p>
+Conversions only work for simple cases such as converting <code>ints</code> of one
+sign or size to another and between integers and floating-point numbers,
+plus a couple of other instances outside the scope of a tutorial.
+There are no automatic numeric conversions of any kind in Go,
+other than that of making constants have concrete size and type when
+assigned to a variable.
+<p>
+<h2>An I/O Package</h2>
+<p>
+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>
+{{code "progs/file.go" `/package/` `/^}/`}}
+<p>
+The first few lines declare the name of the
+package—<code>file</code>—and then import two packages. The <code>os</code>
+package hides the differences
+between various operating systems to give a consistent view of files and
+so on; here we're going to use its error handling utilities
+and reproduce the rudiments of its file I/O.
+<p>
+The other item is the low-level, external <code>syscall</code> package, which provides
+a primitive interface to the underlying operating system's calls.
+<p>
+Next is a type definition: the <code>type</code> keyword introduces a type declaration,
+in this case a data structure called <code>File</code>.
+To make things a little more interesting, our <code>File</code> includes the name of the file
+that the file descriptor refers to.
+<p>
+Because <code>File</code> starts with a capital letter, the type is available outside the package,
+that is, by users of the package. In Go the rule about visibility of information is
+simple: if a name (of a top-level type, function, method, constant or variable, or of
+a structure field or method) is capitalized, users of the package may see it. Otherwise, the
+name and hence the thing being named is visible only inside the package in which
+it is declared. This is more than a convention; the rule is enforced by the compiler.
+In Go, the term for publicly visible names is ''exported''.
+<p>
+In the case of <code>File</code>, all its fields are lower case and so invisible to users, but we
+will soon give it some exported, upper-case methods.
+<p>
+First, though, here is a factory to create a <code>File</code>:
+<p>
+{{code "progs/file.go" `/newFile/` `/^}/`}}
+<p>
+This returns a pointer to a new <code>File</code> structure with the file descriptor and name
+filled in. This code uses Go's notion of a ''composite literal'', analogous to
+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
+</pre>
+<p>
+but for simple structures like <code>File</code> it's easier to return the address of a
+composite literal, as is done here in the <code>return</code> statement from <code>newFile</code>.
+<p>
+We can use the factory to construct some familiar, exported variables of type <code>*File</code>:
+<p>
+{{code "progs/file.go" `/var/` `/^.$/`}}
+<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>
+{{code "progs/file.go" `/func.OpenFile/` `/^}/`}}
+<p>
+There are a number of new things in these few lines. First, <code>OpenFile</code> returns
+multiple values, a <code>File</code> and an error (more about errors in a moment).
+We declare the
+multi-value return as a parenthesized list of declarations; syntactically
+they look just like a second parameter list. The function
+<code>syscall.Open</code>
+also has a multi-value return, which we can grab with the multi-variable
+declaration on the first line; it declares <code>r</code> and <code>e</code> to hold the two values,
+both of type <code>int</code> (although you'd have to look at the <code>syscall</code> package
+to see that). Finally, <code>OpenFile</code> returns two values: a pointer to the new <code>File</code>
+and the error. If <code>syscall.Open</code> fails, the file descriptor <code>r</code> will
+be negative and <code>newFile</code> will return <code>nil</code>.
+<p>
+About those errors: The <code>os</code> library includes a general notion of an error.
+It's a good idea to use its facility in your own interfaces, as we do here, for
+consistent error handling throughout Go code. In <code>Open</code> we use a
+conversion to translate Unix's integer <code>errno</code> value into the integer type
+<code>os.Errno</code>, which implements <code>os.Error</code>.
+<p>
+Why <code>OpenFile</code> and not <code>Open</code>? To mimic Go's <code>os</code> package, which
+our exercise is emulating. The <code>os</code> package takes the opportunity
+to make the two commonest cases - open for read and create for
+write - the simplest, just <code>Open</code> and <code>Create</code>. <code>OpenFile</code> is the
+general case, analogous to the Unix system call <code>Open</code>. Here is
+the implementation of our <code>Open</code> and <code>Create</code>; they're trivial
+wrappers that eliminate common errors by capturing
+the tricky standard arguments to open and, especially, to create a file:
+<p>
+{{code "progs/file.go" `/^const/` `/^}/`}}
+<p>
+{{code "progs/file.go" `/func.Create/` `/^}/`}}
+<p>
+Back to our main story.
+Now that we can build <code>Files</code>, we can write methods for them. To declare
+a method of a type, we define a function to have an explicit receiver
+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>
+{{code "progs/file.go" `/Close/` "$"}}
+<p>
+There is no implicit <code>this</code> and the receiver variable must be used to access
+members of the structure. Methods are not declared within
+the <code>struct</code> declaration itself. The <code>struct</code> declaration defines only data members.
+In fact, methods can be created for almost any type you name, such as an integer or
+array, not just for <code>structs</code>. We'll see an example with arrays later.
+<p>
+The <code>String</code> method is so called because of a printing convention we'll
+describe later.
+<p>
+The methods use the public variable <code>os.EINVAL</code> to return the (<code>os.Error</code>
+version of the) Unix error code <code>EINVAL</code>. The <code>os</code> library defines a standard
+set of such error values.
+<p>
+We can now use our new package:
+<p>
+{{code "progs/helloworld3.go" `/package/` "$"}}
+<p>
+The ''<code>./</code>'' in the import of ''<code>./file</code>'' tells the compiler
+to use our own package rather than
+something from the directory of installed packages.
+(Also, ''<code>file.go</code>'' must be compiled before we can import the
+package.)
+<p>
+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
+$
+</pre>
+<p>
+<h2>Rotting cats</h2>
+<p>
+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>
+{{code "progs/cat.go" `/package/` "$"}}
+<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> 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
+they all have the same type.
+<p>
+Since the <code>switch</code> value is just <code>true</code>, we could leave it off—as is also
+the situation
+in a <code>for</code> statement, a missing value means <code>true</code>. In fact, such a <code>switch</code>
+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>
+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.
+It's easy to do by just processing the bytes, but instead we will exploit
+Go's notion of an <i>interface</i>.
+<p>
+The <code>cat</code> subroutine uses only two methods of <code>f</code>: <code>Read</code> and <code>String</code>,
+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>
+{{code "progs/cat_rot13.go" `/type.reader/` `/^}/`}}
+<p>
+Any type that has the two methods of <code>reader</code>—regardless of whatever
+other methods the type may also have—is said to <i>implement</i> the
+interface. Since <code>file.File</code> implements these methods, it implements the
+<code>reader</code> interface. We could tweak the <code>cat</code> subroutine to accept a <code>reader</code>
+instead of a <code>*file.File</code> and it would work just fine, but let's embellish a little
+first by writing a second type that implements <code>reader</code>, one that wraps an
+existing <code>reader</code> and does <code>rot13</code> 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 <code>reader</code> interface.
+<p>
+{{code "progs/cat_rot13.go" `/type.rotate13/` `/end.of.rotate13/`}}
+<p>
+(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>
+{{code "progs/cat_rot13.go" `/rot13Flag/`}}
+<p>
+and use it from within a mostly unchanged <code>cat</code> function:
+<p>
+{{code "progs/cat_rot13.go" `/func.cat/` `/^}/`}}
+<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.)
+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>.
+<p>
+Here it is in action:
+<p>
+<pre>
+$ echo abcdefghijklmnopqrstuvwxyz | ./cat
+abcdefghijklmnopqrstuvwxyz
+$ echo abcdefghijklmnopqrstuvwxyz | ./cat --rot13
+nopqrstuvwxyzabcdefghijklm
+$
+</pre>
+<p>
+Fans of dependency injection may take cheer from how easily interfaces
+allow us to substitute the implementation of a file descriptor.
+<p>
+Interfaces are a distinctive feature of Go. An interface is implemented by a
+type if the type implements all the methods declared in the interface.
+This means
+that a type may implement an arbitrary number of different interfaces.
+There is no type hierarchy; things can be much more <i>ad hoc</i>,
+as we saw with <code>rot13</code>. The type <code>file.File</code> implements <code>reader</code>; it could also
+implement a <code>writer</code>, or any other interface built from its methods that
+fits the current situation. Consider the <i>empty interface</i>
+<p>
+<pre>
+type Empty interface {}
+</pre>
+<p>
+<i>Every</i> type implements the empty interface, which makes it
+useful for things like containers.
+<p>
+<h2>Sorting</h2>
+<p>
+Interfaces provide a simple form of polymorphism. They completely
+separate the definition of what an object does from how it does it, allowing
+distinct implementations to be represented at different times by the
+same interface variable.
+<p>
+As an example, consider this simple sort algorithm taken from <code>progs/sort.go</code>:
+<p>
+{{code "progs/sort.go" `/func.Sort/` `/^}/`}}
+<p>
+The code needs only three methods, which we wrap into sort's <code>Interface</code>:
+<p>
+{{code "progs/sort.go" `/interface/` `/^}/`}}
+<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>
+{{code "progs/sort.go" `/type.*IntSlice/` `/Swap/`}}
+<p>
+Here we see methods defined for non-<code>struct</code> types. You can define methods
+for any type you define and name in your package.
+<p>
+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>
+{{code "progs/sortmain.go" `/func.ints/` `/^}/`}}
+<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>
+{{code "progs/sortmain.go" `/type.day/` `/Swap/`}}
+<p>
+<p>
+<h2>Printing</h2>
+<p>
+The examples of formatted printing so far have been modest. In this section
+we'll talk about how formatted I/O can be done well in Go.
+<p>
+We've seen simple uses of the package <code>fmt</code>, which
+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)
+</pre>
+<p>
+The token <code>...</code> introduces a variable-length argument list that in C would
+be handled using the <code>stdarg.h</code> macros.
+In Go, variadic functions are passed a slice of the arguments of the
+specified type. In <code>Printf</code>'s case, the declaration says <code>...interface{}</code>
+so the actual type is a slice of empty interface values, <code>[]interface{}</code>.
+<code>Printf</code> can examine the arguments by iterating over the slice
+and, for each element, using a type switch or the reflection library
+to interpret the value.
+It's off topic here but such run-time type analysis
+helps explain some of the nice properties of Go's <code>Printf</code>,
+due to the ability of <code>Printf</code> to discover the type of its arguments
+dynamically.
+<p>
+For example, in C each format must correspond to the type of its
+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>
+{{code "progs/print.go" 10 11}}
+<p>
+prints
+<p>
+<pre>
+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>
+{{code "progs/print.go" 14 20}}
+<p>
+is
+<p>
+<pre>
+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>
+instead of <code>Printf</code>. Those routines do fully automatic formatting.
+The <code>Print</code> function just prints its elements out using the equivalent
+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>
+{{code "progs/print.go" 21 22}}
+<p>
+If you have your own type you'd like <code>Printf</code> or <code>Print</code> to format,
+just give it a <code>String</code> method that returns a string. The print
+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>
+{{code "progs/print_string.go" 9 "$"}}
+<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
+</pre>
+<p>
+Observe that the <code>String</code> method calls <code>Sprint</code> (the obvious Go
+variant that returns a string) to do its formatting; special formatters
+can use the <code>fmt</code> library recursively.
+<p>
+Another feature of <code>Printf</code> is that the format <code>%T</code> will print a string
+representation of the type of a value, which can be handy when debugging
+polymorphic code.
+<p>
+It's possible to write full custom print formats with flags and precisions
+and such, but that's getting a little off the main thread so we'll leave it
+as an exploration exercise.
+<p>
+You might ask, though, how <code>Printf</code> can tell whether a type implements
+the <code>String</code> method. Actually what it does is ask if the value can
+be converted to an interface variable that implements the method.
+Schematically, given a value <code>v</code>, it does this:
+<p>
+<p>
+<pre>
+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)
+}
+</pre>
+<p>
+The code uses a ``type assertion'' (<code>v.(Stringer)</code>) to test if the value stored in
+<code>v</code> satisfies the <code>Stringer</code> interface; if it does, <code>s</code>
+will become an interface variable implementing the method and <code>ok</code> will
+be <code>true</code>. We then use the interface variable to call the method.
+(The ''comma, ok'' pattern is a Go idiom used to test the success of
+operations such as type conversion, map update, communications, and so on,
+although this is the only appearance in this tutorial.)
+If the value does not satisfy the interface, <code>ok</code> will be false.
+<p>
+In this snippet the name <code>Stringer</code> follows the convention that we add ''[e]r''
+to interfaces describing simple method sets like this.
+<p>
+One last wrinkle. To complete the suite, besides <code>Printf</code> etc. and <code>Sprintf</code>
+etc., there are also <code>Fprintf</code> etc. Unlike in C, <code>Fprintf</code>'s first argument is
+not a file. Instead, it is a variable of type <code>io.Writer</code>, which is an
+interface type defined in the <code>io</code> library:
+<p>
+<pre>
+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
+<code>io.Reader</code>, <code>io.ReadWriter</code>, and so on.)
+Thus you can call <code>Fprintf</code> on any type that implements a standard <code>Write</code>
+method, not just files but also network channels, buffers, whatever
+you want.
+<p>
+<h2>Prime numbers</h2>
+<p>
+Now we come to processes and communication—concurrent programming.
+It's a big subject so to be brief we assume some familiarity with the topic.
+<p>
+A classic program in the style is a prime sieve.
+(The sieve of Eratosthenes is computationally more efficient than
+the algorithm presented here, but we are more interested in concurrency than
+algorithmics at the moment.)
+It works by taking a stream of all the natural numbers and introducing
+a sequence of filters, one for each prime, to winnow the multiples of
+that prime. At each step we have a sequence of filters of the primes
+so far, and the next number to pop out is the next prime, which triggers
+the creation of the next filter in the chain.
+<p>
+Here's a flow diagram; each box represents a filter element whose
+creation is triggered by the first number that flowed from the
+elements before it.
+<p>
+<br>
+<p>
+ <img src='sieve.gif'>
+<p>
+<br>
+<p>
+To create a stream of integers, we use a Go <i>channel</i>, which,
+borrowing from CSP's descendants, represents a communications
+channel that can connect two concurrent computations.
+In Go, channel variables are references to a run-time object that
+coordinates the communication; as with maps and slices, use
+<code>make</code> to create a new channel.
+<p>
+Here is the first function in <code>progs/sieve.go</code>:
+<p>
+{{code "progs/sieve.go" `/Send/` `/^}/`}}
+<p>
+The <code>generate</code> function sends the sequence 2, 3, 4, 5, ... to its
+argument channel, <code>ch</code>, using the binary communications operator <code><-</code>.
+Channel operations block, so if there's no recipient for the value on <code>ch</code>,
+the send operation will wait until one becomes available.
+<p>
+The <code>filter</code> function has three arguments: an input channel, an output
+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><-</code> (receive) retrieves the next value on the channel.
+<p>
+{{code "progs/sieve.go" `/Copy.the/` `/^}/`}}
+<p>
+The generator and filters execute concurrently. Go has
+its own model of process/threads/light-weight processes/coroutines,
+so to avoid notational confusion we call concurrently executing
+computations in Go <i>goroutines</i>. To start a goroutine,
+invoke the function, prefixing the call with the keyword <code>go</code>;
+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
+</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 := <-ch // wait for, and retrieve, result
+</pre>
+<p>
+Back to our prime sieve. Here's how the sieve pipeline is stitched
+together:
+<p>
+{{code "progs/sieve.go" `/func.main/` `/^}/`}}
+<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>.
+<p>
+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>
+{{code "progs/sieve1.go" `/func.generate/` `/^}/`}}
+<p>
+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.
+<p>
+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>
+{{code "progs/sieve1.go" `/func.filter/` `/^}/`}}
+<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>
+{{code "progs/sieve1.go" `/func.sieve/` `/^}/`}}
+<p>
+Now <code>main</code>'s interface to the prime sieve is a channel of primes:
+<p>
+{{code "progs/sieve1.go" `/func.main/` `/^}/`}}
+<p>
+<h2>Multiplexing</h2>
+<p>
+With channels, it's possible to serve multiple independent client goroutines without
+writing an explicit multiplexer. The trick is to send the server a channel in the message,
+which it will then use to reply to the original sender.
+A realistic client-server program is a lot of code, so here is a very simple substitute
+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>
+{{code "progs/server.go" `/type.request/` `/^}/`}}
+<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>
+{{code "progs/server.go" `/type.binOp/` `/^}/`}}
+<p>
+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>
+{{code "progs/server.go" `/func.server/` `/^}/`}}
+<p>
+We construct a server in a familiar way, starting it and returning a channel
+connected to it:
+<p>
+{{code "progs/server.go" `/func.startServer/` `/^}/`}}
+<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>
+{{code "progs/server.go" `/func.main/` `/^}/`}}
+<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>
+{{code "progs/server1.go" `/func.startServer/` `/^}/`}}
+<p>
+It passes the quit channel to the <code>server</code> function, which uses it like this:
+<p>
+{{code "progs/server1.go" `/func.server/` `/^}/`}}
+<p>
+Inside <code>server</code>, the <code>select</code> statement chooses which of the multiple communications
+listed by its cases can proceed. If all are blocked, it waits until one can proceed; if
+multiple can proceed, it chooses one at random. In this instance, the <code>select</code> allows
+the server to honor requests until it receives a quit message, at which point it
+returns, terminating its execution.
+<p>
+<p>
+All that's left is to strobe the <code>quit</code> channel
+at the end of main:
+<p>
+{{code "progs/server1.go" `/adder,.quit/`}}
+...
+{{code "progs/server1.go" `/quit....true/`}}
+<p>
+There's a lot more to Go programming and concurrent programming in general but this
+quick tour should give you some of the basics.
+++ /dev/null
-<!-- A Tutorial for the Go Programming Language -->
-Introduction
-----
-
-This document is a tutorial introduction to the basics of the Go programming
-language, intended for programmers familiar with C or C++. It is not a comprehensive
-guide to the language; at the moment the document closest to that is the
-<a href='/doc/go_spec.html'>language specification</a>.
-After you've read this tutorial, you should look at
-<a href='/doc/effective_go.html'>Effective Go</a>,
-which digs deeper into how the language is used and
-talks about the style and idioms of programming in Go.
-Also, slides from a 3-day course about Go are available.
-They provide some background and a lot of examples:
-<a href='/doc/GoCourseDay1.pdf'>Day 1</a>,
-<a href='/doc/GoCourseDay2.pdf'>Day 2</a>,
-<a href='/doc/GoCourseDay3.pdf'>Day 3</a>.
-
-The presentation here proceeds through a series of modest programs to illustrate
-key features of the language. All the programs work (at time of writing) and are
-checked into the repository in the directory <a href='/doc/progs'>"/doc/progs/"</a>.
-
-Hello, World
-----
-
-Let's start in the usual way:
-
-!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.
-This program imports the package "fmt" to gain access to
-our old, now capitalized and package-qualified, friend, "fmt.Printf".
-
-Functions are introduced with the "func" keyword.
-The "main" package's "main" function is where the program starts running (after
-any initialization).
-
-String constants can contain Unicode characters, encoded in UTF-8.
-(In fact, Go source files are defined to be encoded in UTF-8.)
-
-The comment convention is the same as in C++:
-
- /* ... */
- // ...
-
-Later we'll have much more to say about printing.
-
-Semicolons
-----
-
-You might have noticed that our program has no semicolons. In Go
-code, the only place you typically see semicolons is separating the
-clauses of "for" loops and the like; they are not necessary after
-every statement.
-
-In fact, what happens is that the formal language uses semicolons,
-much as in C or Java, but they are inserted automatically
-at the end of every line that looks like the end of a statement. You
-don't need to type them yourself.
-
-For details about how this is done you can see the language
-specification, but in practice all you need to know is that you
-never need to put a semicolon at the end of a line. (You can put
-them in if you want to write multiple statements per line.) As an
-extra help, you can also leave out a semicolon immediately before
-a closing brace.
-
-This approach makes for clean-looking, semicolon-free code. The
-one surprise is that it's important to put the opening
-brace of a construct such as an "if" statement on the same line as
-the "if"; if you don't, there are situations that may not compile
-or may give the wrong result. The language forces the brace style
-to some extent.
-
-Compiling
-----
-
-Go is a compiled language. At the moment there are two compilers.
-"Gccgo" is a Go compiler that uses the GCC back end. There is also a
-suite of compilers with different (and odd) names for each architecture:
-"6g" for the 64-bit x86, "8g" for the 32-bit x86, and more. These
-compilers run significantly faster but generate less efficient code
-than "gccgo". At the time of writing (late 2009), they also have
-a more robust run-time system although "gccgo" is catching up.
-
-Here's how to compile and run our program. With "6g", say,
-
- $ 6g helloworld.go # compile; object goes into helloworld.6
- $ 6l helloworld.6 # link; output goes into 6.out
- $ 6.out
- Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
- $
-
-With "gccgo" it looks a little more traditional.
-
- $ gccgo helloworld.go
- $ a.out
- Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
- $
-
-Echo
-----
-
-Next up, here's a version of the Unix utility "echo(1)":
-
-!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 in the "import" and "const" clauses here.
-But it's not necessary to do so; we could have said
-
- const Space = " "
- const Newline = "\n"
-
-This program imports the ""os"" package to access its "Stdout" variable, of type
-"*os.File". The "import" statement is actually a declaration: in its general form,
-as used in our ``hello world'' program,
-it names the identifier ("fmt")
-that will be used to access members of the package imported from the file (""fmt""),
-found in the current directory or in a standard location.
-In this program, though, we've dropped the explicit name from the imports; by default,
-packages are imported using the name defined by the imported package,
-which by convention is of course the file name itself. Our ``hello world'' program
-could have said just "import "fmt"".
-
-You can specify your
-own import names if you want but it's only necessary if you need to resolve
-a naming conflict.
-
-Given "os.Stdout" we can use its "WriteString" method to print the string.
-
-After importing the "flag" package, we use a "var" declaration
-to create and initialize a global variable, called "omitNewline",
-to hold the value of echo's "-n" flag.
-The variable has type "*bool", pointer to "bool".
-
-In "main.main", we parse the arguments (the call to "flag.Parse") and then create a local
-string variable with which to build the output.
-
-The declaration statement has the form
-
- var s string = ""
-
-This is the "var" keyword, followed by the name of the variable, followed by
-its type, followed by an equals sign and an initial value for the variable.
-
-Go tries to be terse, and this declaration could be shortened. Since the
-string constant is of type string, we don't have to tell the compiler that.
-We could write
-
- var s = ""
-
-or we could go even shorter and write the idiom
-
- s := ""
-
-The ":=" operator is used a lot in Go to represent an initializing declaration.
-There's one in the "for" clause on the next line:
-
-!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.
-
-The Go "for" statement differs from that of C in a number of ways. First,
-it's the only looping construct; there is no "while" or "do". Second,
-there are no parentheses on the clause, but the braces on the body
-are mandatory. The same applies to the "if" and "switch" statements.
-Later examples will show some other ways "for" can be written.
-
-The body of the loop builds up the string "s" by appending (using "+=")
-the arguments and separating spaces. After the loop, if the "-n" flag is not
-set, the program appends a newline. Finally, it writes the result.
-
-Notice that "main.main" is a niladic function with no return type.
-It's defined that way. Falling off the end of "main.main" means
-''success''; if you want to signal an erroneous return, call
-
- os.Exit(1)
-
-The "os" package contains other essentials for getting
-started; for instance, "os.Args" is a slice used by the
-"flag" package to access the command-line arguments.
-
-An Interlude about Types
-----
-
-Go has some familiar types such as "int" and "uint" (unsigned "int"), which represent
-values of the ''appropriate'' size for the machine. It also defines
-explicitly-sized types such as "int8", "float64", and so on, plus
-unsigned integer types such as "uint", "uint32", etc.
-These are distinct types; even if "int" and "int32" are both 32 bits in size,
-they are not the same type. There is also a "byte" synonym for
-"uint8", which is the element type for strings.
-
-Floating-point types are always sized: "float32" and "float64",
-plus "complex64" (two "float32s") and "complex128"
-(two "float64s"). Complex numbers are outside the
-scope of this tutorial.
-
-Speaking of "string", that's a built-in type as well. Strings are
-<i>immutable values</i>—they are not just arrays of "byte" values.
-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:
-
-!src progs/strings.go /hello/ /ciao/
-
-However the following statements are illegal because they would modify
-a "string" value:
-
- s[0] = 'x'
- (*p)[1] = 'y'
-
-In C++ terms, Go strings are a bit like "const strings", while pointers
-to strings are analogous to "const string" references.
-
-Yes, there are pointers. However, Go simplifies their use a little;
-read on.
-
-Arrays are declared like this:
-
- var arrayOfInt [10]int
-
-Arrays, like strings, are values, but they are mutable. This differs
-from C, in which "arrayOfInt" would be usable as a pointer to "int".
-In Go, since arrays are values, it's meaningful (and useful) to talk
-about pointers to arrays.
-
-The size of the array is part of its type; however, one can declare
-a <i>slice</i> variable to hold a reference to any array, of any size,
-with the same element type.
-A <i>slice
-expression</i> has the form "a[low : high]", representing
-the internal array indexed from "low" through "high-1"; the resulting
-slice is indexed from "0" through "high-low-1".
-In short, slices look a lot like arrays but with
-no explicit size ("[]" vs. "[10]") and they reference a segment of
-an underlying, usually anonymous, regular array. Multiple slices
-can share data if they represent pieces of the same array;
-multiple arrays can never share data.
-
-Slices are much more common in Go programs than
-regular arrays; they're more flexible, have reference semantics,
-and are efficient. What they lack is the precise control of storage
-layout of a regular array; if you want to have a hundred elements
-of an array stored within your structure, you should use a regular
-array. To create one, use a compound value <i>constructor</i>—an
-expression formed
-from a type followed by a brace-bounded expression like this:
-
- [3]int{1,2,3}
-
-In this case the constructor builds an array of 3 "ints".
-
-When passing an array to a function, you almost always want
-to declare the formal parameter to be a slice. When you call
-the function, slice the array to create
-(efficiently) a slice reference and pass that.
-By default, the lower and upper bounds of a slice match the
-ends of the existing object, so the concise notation "[:]"
-will slice the whole array.
-
-Using slices one can write this function (from "sum.go"):
-
-!src progs/sum.go /sum/ /^}/
-
-Note how the return type ("int") is defined for "sum" by stating it
-after the parameter list.
-
-To call the function, we slice the array. This intricate call (we'll show
-a simpler way in a moment) constructs
-an array and slices it:
-
- s := sum([3]int{1,2,3}[:])
-
-If you are creating a regular array but want the compiler to count the
-elements for you, use "..." as the array size:
-
- s := sum([...]int{1,2,3}[:])
-
-That's fussier than necessary, though.
-In practice, unless you're meticulous about storage layout within a
-data structure, a slice itself—using empty brackets with no size—is all you need:
-
- s := sum([]int{1,2,3})
-
-There are also maps, which you can initialize like this:
-
- m := map[string]int{"one":1 , "two":2}
-
-The built-in function "len", which returns number of elements,
-makes its first appearance in "sum". It works on strings, arrays,
-slices, maps, and channels.
-
-By the way, another thing that works on strings, arrays, slices, maps
-and channels is the "range" clause on "for" loops. Instead of writing
-
- for i := 0; i < len(a); i++ { ... }
-
-to loop over the elements of a slice (or map or ...) , we could write
-
- for i, v := range a { ... }
-
-This assigns "i" to the index and "v" to the value of the successive
-elements of the target of the range. See
-<a href='/doc/effective_go.html'>Effective Go</a>
-for more examples of its use.
-
-
-An Interlude about Allocation
-----
-
-Most types in Go are values. If you have an "int" or a "struct"
-or an array, assignment
-copies the contents of the object.
-To allocate a new variable, use the built-in function "new", which
-returns a pointer to the allocated storage.
-
- type T struct { a, b int }
- var t *T = new(T)
-
-or the more idiomatic
-
- t := new(T)
-
-Some types—maps, slices, and channels (see below)—have reference semantics.
-If you're holding a slice or a map and you modify its contents, other variables
-referencing the same underlying data will see the modification. For these three
-types you want to use the built-in function "make":
-
- m := make(map[string]int)
-
-This statement initializes a new map ready to store entries.
-If you just declare the map, as in
-
- var m map[string]int
-
-it creates a "nil" reference that cannot hold anything. To use the map,
-you must first initialize the reference using "make" or by assignment from an
-existing map.
-
-Note that "new(T)" returns type "*T" while "make(T)" returns type
-"T". If you (mistakenly) allocate a reference object with "new" rather than "make",
-you receive a pointer to a nil reference, equivalent to
-declaring an uninitialized variable and taking its address.
-
-An Interlude about Constants
-----
-
-Although integers come in lots of sizes in Go, integer constants do not.
-There are no constants like "0LL" or "0x0UL". Instead, integer
-constants are evaluated as large-precision values that
-can overflow only when they are assigned to an integer variable with
-too little precision to represent the value.
-
- const hardEight = (1 << 100) >> 97 // legal
-
-There are nuances that deserve redirection to the legalese of the
-language specification but here are some illustrative examples:
-
- 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
-
-Conversions only work for simple cases such as converting "ints" of one
-sign or size to another and between integers and floating-point numbers,
-plus a couple of other instances outside the scope of a tutorial.
-There are no automatic numeric conversions of any kind in Go,
-other than that of making constants have concrete size and type when
-assigned to a variable.
-
-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":
-
-!src progs/file.go /package/ /^}/
-
-The first few lines declare the name of the
-package—"file"—and then import two packages. The "os"
-package hides the differences
-between various operating systems to give a consistent view of files and
-so on; here we're going to use its error handling utilities
-and reproduce the rudiments of its file I/O.
-
-The other item is the low-level, external "syscall" package, which provides
-a primitive interface to the underlying operating system's calls.
-
-Next is a type definition: the "type" keyword introduces a type declaration,
-in this case a data structure called "File".
-To make things a little more interesting, our "File" includes the name of the file
-that the file descriptor refers to.
-
-Because "File" starts with a capital letter, the type is available outside the package,
-that is, by users of the package. In Go the rule about visibility of information is
-simple: if a name (of a top-level type, function, method, constant or variable, or of
-a structure field or method) is capitalized, users of the package may see it. Otherwise, the
-name and hence the thing being named is visible only inside the package in which
-it is declared. This is more than a convention; the rule is enforced by the compiler.
-In Go, the term for publicly visible names is ''exported''.
-
-In the case of "File", all its fields are lower case and so invisible to users, but we
-will soon give it some exported, upper-case methods.
-
-First, though, here is a factory to create a "File":
-
-!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
-the ones used to build maps and arrays, to construct a new heap-allocated
-object. We could write
-
- n := new(File)
- n.fd = fd
- n.name = name
- return n
-
-but for simple structures like "File" it's easier to return the address of a
-composite literal, as is done here in the "return" statement from "newFile".
-
-We can use the factory to construct some familiar, exported variables of type "*File":
-
-!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):
-
-!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).
-We declare the
-multi-value return as a parenthesized list of declarations; syntactically
-they look just like a second parameter list. The function
-"syscall.Open"
-also has a multi-value return, which we can grab with the multi-variable
-declaration on the first line; it declares "r" and "e" to hold the two values,
-both of type "int" (although you'd have to look at the "syscall" package
-to see that). Finally, "OpenFile" returns two values: a pointer to the new "File"
-and the error. If "syscall.Open" fails, the file descriptor "r" will
-be negative and "newFile" will return "nil".
-
-About those errors: The "os" library includes a general notion of an error.
-It's a good idea to use its facility in your own interfaces, as we do here, for
-consistent error handling throughout Go code. In "Open" we use a
-conversion to translate Unix's integer "errno" value into the integer type
-"os.Errno", which implements "os.Error".
-
-Why "OpenFile" and not "Open"? To mimic Go's "os" package, which
-our exercise is emulating. The "os" package takes the opportunity
-to make the two commonest cases - open for read and create for
-write - the simplest, just "Open" and "Create". "OpenFile" is the
-general case, analogous to the Unix system call "Open". Here is
-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:
-
-!src progs/file.go /^const/ /^}/
-
-!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
-a method of a type, we define a function to have an explicit receiver
-of that type, placed
-in parentheses before the function name. Here are some methods for "*File",
-each of which declares a receiver variable "file".
-
-!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
-the "struct" declaration itself. The "struct" declaration defines only data members.
-In fact, methods can be created for almost any type you name, such as an integer or
-array, not just for "structs". We'll see an example with arrays later.
-
-The "String" method is so called because of a printing convention we'll
-describe later.
-
-The methods use the public variable "os.EINVAL" to return the ("os.Error"
-version of the) Unix error code "EINVAL". The "os" library defines a standard
-set of such error values.
-
-We can now use our new package:
-
-!src progs/helloworld3.go /package/ $
-
-The ''"./"'' in the import of ''"./file"'' tells the compiler
-to use our own package rather than
-something from the directory of installed packages.
-(Also, ''"file.go"'' must be compiled before we can import the
-package.)
-
-Now we can compile and run the program. On Unix, this would be the result:
-
- $ 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
- $
-
-Rotting cats
-----
-
-Building on the "file" package, here's a simple version of the Unix utility "cat(1)",
-"progs/cat.go":
-
-!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" 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
-they all have the same type.
-
-Since the "switch" value is just "true", we could leave it off—as is also
-the situation
-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".
-
-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.
-It's easy to do by just processing the bytes, but instead we will exploit
-Go's notion of an <i>interface</i>.
-
-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":
-
-!src progs/cat_rot13.go /type.reader/ /^}/
-
-Any type that has the two methods of "reader"—regardless of whatever
-other methods the type may also have—is said to <i>implement</i> the
-interface. Since "file.File" implements these methods, it implements the
-"reader" interface. We could tweak the "cat" subroutine to accept a "reader"
-instead of a "*file.File" and it would work just fine, but let's embellish a little
-first by writing a second type that implements "reader", one that wraps an
-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.
-
-!src progs/cat_rot13.go /type.rotate13/ /end.of.rotate13/
-
-(The "rot13" function called in "Read" is trivial and not worth reproducing here.)
-
-To use the new feature, we define a flag:
-
-!src progs/cat_rot13.go /rot13Flag/
-
-and use it from within a mostly unchanged "cat" function:
-
-!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.)
-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:
-
- $ echo abcdefghijklmnopqrstuvwxyz | ./cat
- abcdefghijklmnopqrstuvwxyz
- $ echo abcdefghijklmnopqrstuvwxyz | ./cat --rot13
- nopqrstuvwxyzabcdefghijklm
- $
-
-Fans of dependency injection may take cheer from how easily interfaces
-allow us to substitute the implementation of a file descriptor.
-
-Interfaces are a distinctive feature of Go. An interface is implemented by a
-type if the type implements all the methods declared in the interface.
-This means
-that a type may implement an arbitrary number of different interfaces.
-There is no type hierarchy; things can be much more <i>ad hoc</i>,
-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>
-
- type Empty interface {}
-
-<i>Every</i> type implements the empty interface, which makes it
-useful for things like containers.
-
-Sorting
-----
-
-Interfaces provide a simple form of polymorphism. They completely
-separate the definition of what an object does from how it does it, allowing
-distinct implementations to be represented at different times by the
-same interface variable.
-
-As an example, consider this simple sort algorithm taken from "progs/sort.go":
-
-!src progs/sort.go /func.Sort/ /^}/
-
-The code needs only three methods, which we wrap into sort's "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"
-
-!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.
-
-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.
-
-!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:
-
-!src progs/sortmain.go /type.day/ /Swap/
-
-
-Printing
-----
-
-The examples of formatted printing so far have been modest. In this section
-we'll talk about how formatted I/O can be done well in Go.
-
-We've seen simple uses of the package "fmt", which
-implements "Printf", "Fprintf", and so on.
-Within the "fmt" package, "Printf" is declared with this signature:
-
- Printf(format string, v ...interface{}) (n int, errno os.Error)
-
-The token "..." introduces a variable-length argument list that in C would
-be handled using the "stdarg.h" macros.
-In Go, variadic functions are passed a slice of the arguments of the
-specified type. In "Printf"'s case, the declaration says "...interface{}"
-so the actual type is a slice of empty interface values, "[]interface{}".
-"Printf" can examine the arguments by iterating over the slice
-and, for each element, using a type switch or the reflection library
-to interpret the value.
-It's off topic here but such run-time type analysis
-helps explain some of the nice properties of Go's "Printf",
-due to the ability of "Printf" to discover the type of its arguments
-dynamically.
-
-For example, in C each format must correspond to the type of its
-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
-
-!src progs/print.go 10 11
-
-prints
-
- 18446744073709551615 -1
-
-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
-
-!src progs/print.go 14 20
-
-is
-
- 18446744073709551615 {77 Sunset Strip} [1 2 3 4]
-
-You can drop the formatting altogether if you use "Print" or "Println"
-instead of "Printf". Those routines do fully automatic formatting.
-The "Print" function just prints its elements out using the equivalent
-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.
-
-!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
-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.
-
-!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
-
- 77 Sunset Strip
-
-Observe that the "String" method calls "Sprint" (the obvious Go
-variant that returns a string) to do its formatting; special formatters
-can use the "fmt" library recursively.
-
-Another feature of "Printf" is that the format "%T" will print a string
-representation of the type of a value, which can be handy when debugging
-polymorphic code.
-
-It's possible to write full custom print formats with flags and precisions
-and such, but that's getting a little off the main thread so we'll leave it
-as an exploration exercise.
-
-You might ask, though, how "Printf" can tell whether a type implements
-the "String" method. Actually what it does is ask if the value can
-be converted to an interface variable that implements the method.
-Schematically, given a value "v", it does this:
-
-
- type Stringer interface {
- String() string
- }
-
- s, ok := v.(Stringer) // Test whether v implements "String()"
- if ok {
- result = s.String()
- } else {
- result = defaultOutput(v)
- }
-
-The code uses a ``type assertion'' ("v.(Stringer)") to test if the value stored in
-"v" satisfies the "Stringer" interface; if it does, "s"
-will become an interface variable implementing the method and "ok" will
-be "true". We then use the interface variable to call the method.
-(The ''comma, ok'' pattern is a Go idiom used to test the success of
-operations such as type conversion, map update, communications, and so on,
-although this is the only appearance in this tutorial.)
-If the value does not satisfy the interface, "ok" will be false.
-
-In this snippet the name "Stringer" follows the convention that we add ''[e]r''
-to interfaces describing simple method sets like this.
-
-One last wrinkle. To complete the suite, besides "Printf" etc. and "Sprintf"
-etc., there are also "Fprintf" etc. Unlike in C, "Fprintf"'s first argument is
-not a file. Instead, it is a variable of type "io.Writer", which is an
-interface type defined in the "io" library:
-
- type Writer interface {
- Write(p []byte) (n int, err os.Error)
- }
-
-(This interface is another conventional name, this time for "Write"; there are also
-"io.Reader", "io.ReadWriter", and so on.)
-Thus you can call "Fprintf" on any type that implements a standard "Write"
-method, not just files but also network channels, buffers, whatever
-you want.
-
-Prime numbers
-----
-
-Now we come to processes and communication—concurrent programming.
-It's a big subject so to be brief we assume some familiarity with the topic.
-
-A classic program in the style is a prime sieve.
-(The sieve of Eratosthenes is computationally more efficient than
-the algorithm presented here, but we are more interested in concurrency than
-algorithmics at the moment.)
-It works by taking a stream of all the natural numbers and introducing
-a sequence of filters, one for each prime, to winnow the multiples of
-that prime. At each step we have a sequence of filters of the primes
-so far, and the next number to pop out is the next prime, which triggers
-the creation of the next filter in the chain.
-
-Here's a flow diagram; each box represents a filter element whose
-creation is triggered by the first number that flowed from the
-elements before it.
-
-<br>
-
- <img src='sieve.gif'>
-
-<br>
-
-To create a stream of integers, we use a Go <i>channel</i>, which,
-borrowing from CSP's descendants, represents a communications
-channel that can connect two concurrent computations.
-In Go, channel variables are references to a run-time object that
-coordinates the communication; as with maps and slices, use
-"make" to create a new channel.
-
-Here is the first function in "progs/sieve.go":
-
-!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 "<-".
-Channel operations block, so if there's no recipient for the value on "ch",
-the send operation will wait until one becomes available.
-
-The "filter" function has three arguments: an input channel, an output
-channel, and a prime number. It copies values from the input to the
-output, discarding anything divisible by the prime. The unary communications
-operator "<-" (receive) retrieves the next value on the channel.
-
-!src progs/sieve.go /Copy.the/ /^}/
-
-The generator and filters execute concurrently. Go has
-its own model of process/threads/light-weight processes/coroutines,
-so to avoid notational confusion we call concurrently executing
-computations in Go <i>goroutines</i>. To start a goroutine,
-invoke the function, prefixing the call with the keyword "go";
-this starts the function running in parallel with the current
-computation but in the same address space:
-
- go sum(hugeArray) // calculate sum in the background
-
-If you want to know when the calculation is done, pass a channel
-on which it can report back:
-
- ch := make(chan int)
- go sum(hugeArray, ch)
- // ... do something else for a while
- result := <-ch // wait for, and retrieve, result
-
-Back to our prime sieve. Here's how the sieve pipeline is stitched
-together:
-
-!src progs/sieve.go /func.main/ /^}/
-
-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".
-
-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":
-
-!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 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":
-
-!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:
-
-!src progs/sieve1.go /func.sieve/ /^}/
-
-Now "main"'s interface to the prime sieve is a channel of primes:
-
-!src progs/sieve1.go /func.main/ /^}/
-
-Multiplexing
-----
-
-With channels, it's possible to serve multiple independent client goroutines without
-writing an explicit multiplexer. The trick is to send the server a channel in the message,
-which it will then use to reply to the original sender.
-A realistic client-server program is a lot of code, so here is a very simple substitute
-to illustrate the idea. It starts by defining a "request" type, which embeds a channel
-that will be used for the reply.
-
-!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:
-
-!src progs/server.go /type.binOp/ /^}/
-
-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.
-
-!src progs/server.go /func.server/ /^}/
-
-We construct a server in a familiar way, starting it and returning a channel
-connected to it:
-
-!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.
-
-!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:
-
-!src progs/server1.go /func.startServer/ /^}/
-
-It passes the quit channel to the "server" function, which uses it like this:
-
-!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
-multiple can proceed, it chooses one at random. In this instance, the "select" allows
-the server to honor requests until it receives a quit message, at which point it
-returns, terminating its execution.
-
-
-All that's left is to strobe the "quit" channel
-at the end of main:
-
-!src progs/server1.go /adder,.quit/
-...
-!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.
+++ /dev/null
-// 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.
-
-// 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 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 (
- 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(" ")
-
- sectionMarker = []byte("----\n")
- preStart = []byte("<pre>")
- preEnd = []byte("</pre>\n")
- pp = []byte("<p>\n")
-
- srcPrefix = []byte("!src")
-)
-
-func main() {
- flag.Parse()
- read()
- 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 {
- line, err := b.ReadBytes('\n')
- if err == os.EOF {
- break
- }
- if err != nil {
- log.Fatal(err)
- }
- lines = append(lines, line)
- }
-}
-
-// write puts the result on standard output.
-func write() {
- b := bufio.NewWriter(os.Stdout)
- for _, line := range lines {
- b.Write(expandTabs(line))
- }
- b.Flush()
-}
-
-// 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); {
- if bytes.HasPrefix(lines[i], prefix) {
- nlines, block := fold(i)
- lines[j] = block
- i += nlines
- } else {
- lines[j] = lines[i]
- i++
- }
- j++
- }
- lines = lines[0:j]
-}
-
-// 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) {
- buf.Write(lines[i])
- n++
- if bytes.Equal(lines[i], preEnd) {
- break
- }
- i++
- }
- return n, buf.Bytes()
-}
-
-// 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")
- for i < len(lines) {
- if !bytes.HasPrefix(lines[i], tab) {
- break
- }
- buf.Write(lines[i][1:]) // delete leading tab.
- n++
- i++
- }
- buf.WriteString("</pre>\n")
- return n, buf.Bytes()
-}
-
-// headings turns sections into HTML sections.
-func headings() {
- b := bufio.NewWriter(os.Stdout)
- for i, l := range lines {
- if i > 0 && bytes.Equal(l, sectionMarker) {
- lines[i-1] = []byte("<h2>" + string(trim(lines[i-1])) + "</h2>\n")
- lines[i] = empty
- }
- }
- b.Flush()
-}
-
-// paragraphs turns blank lines into paragraph marks.
-func paragraphs() {
- for i, l := range lines {
- if bytes.Equal(l, newline) {
- lines[i] = pp
- }
- }
-}
-
-// 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
- }
- n := bytes.Index(l, quote)
- if n < 0 {
- return l
- }
- buf := new(bytes.Buffer)
- inQuote := false
- for _, c := range l {
- if c == '"' {
- if inQuote {
- buf.WriteString("</code>")
- } else {
- buf.WriteString("<code>")
- }
- inQuote = !inQuote
- } else {
- buf.WriteByte(c)
- }
- }
- return buf.Bytes()
-}
-
-// trim drops the trailing newline, if present.
-func trim(l []byte) []byte {
- n := len(l)
- if n > 0 && l[n-1] == '\n' {
- return l[0 : n-1]
- }
- return l
-}
-
-// expandTabs expands tabs to spaces. It doesn't worry about columns.
-func expandTabs(l []byte) []byte {
- return bytes.Replace(l, tab, indent, -1)
-}
set -e
-TXT=${1:-go_tutorial.txt} # input file
-HTML=$(basename $TXT .txt).html # output file (basename)
+TMPL=${1:-go_tutorial.tmpl} # input file
+HTML=$(basename $TMPL .tmpl).html # output file (basename)
if ! test -w $HTML
then
exit 1
fi
-make && ./htmlgen < $TXT > $HTML
+make && ./tmpltohtml $TMPL > $HTML
--- /dev/null
+// Copyright 2011 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.
+
+
+// The template uses the function "code" to inject program
+// source into the output by extracting code from files and
+// injecting them as HTML-escaped <pre> blocks.
+//
+// The syntax is simple: 1, 2, or 3 space-separated arguments:
+//
+// Whole file:
+// {{code "foo.go"}}
+// One line (here the signature of main):
+// {{code "foo.go" `/^func.main/`}}
+// Block of text, determined by start and end (here the body of main):
+// {{code "foo.go" `/^func.main/` `/^}/`
+//
+// Patterns can be `/regular expression/`, a decimal number, or "$"
+// to signify the end of the file.
+package main
+
+import (
+ "exp/template"
+ "flag"
+ "fmt"
+ "io/ioutil"
+ "log"
+ "os"
+ "regexp"
+ "strings"
+)
+
+func Usage() {
+ fmt.Fprintf(os.Stderr, "usage: tmpltohtml file\n")
+ os.Exit(2)
+}
+
+func main() {
+ flag.Usage = Usage
+ flag.Parse()
+ if len(flag.Args()) != 1 {
+ Usage()
+ }
+
+ // Read and parse the input.
+ name := flag.Args()[0]
+ tmpl := template.New(name).Funcs(template.FuncMap{"code": code})
+ if err := tmpl.ParseFile(name); err != nil {
+ log.Fatal(err)
+ }
+
+ // Execute the template.
+ if err := tmpl.Execute(os.Stdout, 0); err != nil {
+ log.Fatal(err)
+ }
+}
+
+// contents reads a file by name and returns its contents as a string.
+func contents(name string) string {
+ file, err := ioutil.ReadFile(name)
+ if err != nil {
+ log.Fatal(err)
+ }
+ return string(file)
+}
+
+// format returns a textual representation of the arg, formatted according to its nature.
+func format(arg interface{}) string {
+ switch arg := arg.(type) {
+ case int:
+ return fmt.Sprintf("%d", arg)
+ case string:
+ if len(arg) > 2 && arg[0] == '/' && arg[len(arg)-1] == '/' {
+ return fmt.Sprintf("%#q", arg)
+ }
+ return fmt.Sprintf("%q", arg)
+ default:
+ log.Fatalf("unrecognized argument: %v type %T", arg, arg)
+ }
+ return ""
+}
+
+func code(file string, arg ...interface{}) (string, os.Error) {
+ text := contents(file)
+ var command string
+ switch len(arg) {
+ case 0:
+ // text is already whole file.
+ command = fmt.Sprintf("code %q", file)
+ case 1:
+ command = fmt.Sprintf("code %q %s", file, format(arg[0]))
+ text = oneLine(file, text, arg[0])
+ case 2:
+ command = fmt.Sprintf("code %q %s %s", file, format(arg[0]), format(arg[1]))
+ text = multipleLines(file, text, arg[0], arg[1])
+ default:
+ return "", fmt.Errorf("incorrect code invocation: code %q %q", file, arg)
+ }
+ // Replace tabs by spaces, which work better in HTML.
+ text = strings.Replace(text, "\t", " ", -1)
+ // Escape the program text for HTML.
+ text = template.HTMLEscapeString(text)
+ // Include the command as a comment.
+ text = fmt.Sprintf("<pre><!--{{%s}}\n-->%s</pre>", command, text)
+ return text, nil
+}
+
+// parseArg returns the integer or string value of the argument and tells which it is.
+func parseArg(arg interface{}, file string, max int) (ival int, sval string, isInt bool) {
+ switch n := arg.(type) {
+ case int:
+ if n <= 0 || n > max {
+ log.Fatalf("%q:%d is out of range", file, n)
+ }
+ return n, "", true
+ case string:
+ return 0, n, false
+ }
+ log.Fatalf("unrecognized argument %v type %T", arg, arg)
+ return
+}
+
+// oneLine returns the single line generated by a two-argument code invocation.
+func oneLine(file, text string, arg interface{}) string {
+ lines := strings.SplitAfter(contents(file), "\n")
+ line, pattern, isInt := parseArg(arg, file, len(lines))
+ if isInt {
+ return lines[line-1]
+ }
+ return lines[match(file, 0, lines, pattern)-1]
+}
+
+// multipleLines returns the text generated by a three-argument code invocation.
+func multipleLines(file, text string, arg1, arg2 interface{}) string {
+ lines := strings.SplitAfter(contents(file), "\n")
+ line1, pattern1, isInt1 := parseArg(arg1, file, len(lines))
+ line2, pattern2, isInt2 := parseArg(arg2, file, len(lines))
+ if !isInt1 {
+ line1 = match(file, 0, lines, pattern1)
+ }
+ if !isInt2 {
+ line2 = match(file, line1, lines, pattern2)
+ } else if line2 < line1 {
+ log.Fatal("lines out of order for %q: %d %d", line1, line2)
+ }
+ return strings.Join(lines[line1-1:line2], "")
+}
+
+// match identifies the input line that matches the pattern in a code invocation.
+// If start>0, match lines starting there rather than at the beginning.
+// The return value is 1-indexed.
+func match(file string, start int, lines []string, pattern string) int {
+ // $ matches the end of the file.
+ if pattern == "$" {
+ if len(lines) == 0 {
+ log.Fatal("%q: empty file", file)
+ }
+ return len(lines)
+ }
+ // /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.MatchString(lines[i]) {
+ return i + 1
+ }
+ }
+ log.Fatalf("%s: no match for %#q", file, pattern)
+ }
+ log.Fatalf("unrecognized pattern: %q", pattern)
+ return 0
+}