From 85cafef129c3826b0c5e290c89cfc7251fba43d5 Mon Sep 17 00:00:00 2001
From: Ondřej Surý
+The r58 release corresponds to
+
+This release fixes a use of uninitialized memory in programs that misuse
+As usual, gofix will handle the bulk of the rewrites
+necessary for these changes to package APIs.
+
+Package http drops the
+Package exec has been redesigned with a more
+convenient and succinct API.
+
+Package strconv's Quote
+function now escapes only those Unicode code points not classified as printable
+by unicode.IsPrint.
+Previously Quote would escape all non-ASCII characters.
+This also affects the fmt package's
+Package os/signal's
+Signal and
+UnixSignal types have been moved to the
+os package.
+
+Package image/draw is the new name for
+
+Goinstall now observes the GOPATH environment
+variable to build and install your own code and external libraries outside of
+the Go tree (and avoid writing Makefiles).
+
diff --git a/doc/devel/weekly.html b/doc/devel/weekly.html
index 0a043d410..bf16c8370 100644
--- a/doc/devel/weekly.html
+++ b/doc/devel/weekly.html
@@ -14,6 +14,112 @@ hg pull
hg update weekly.YYYY-MM-DD
+
Let's start in the usual way:
-
Every Go source file declares, using a
Later we'll have much more to say about printing.
@@ -96,67 +96,67 @@ a more robust run-time system although
With
Next up, here's a version of the Unix utility
-
This program is small but it's doing a number of new things. In the last example,
we saw
This program imports the
This is the
or we could go even shorter and write the idiom
The
-
The
The
-
However the following statements are illegal because they would modify
a
In C++ terms, Go strings are a bit like
Arrays, like strings, are values, but they are mutable. This differs
@@ -315,7 +315,7 @@ expression formed
from a type followed by a brace-bounded expression like this:
In this case the constructor builds an array of 3
Using slices one can write this function (from
-
Note how the return type (
If you are creating a regular array but want the compiler to count the
elements for you, use
That's fussier than necessary, though.
@@ -363,13 +363,13 @@ In practice, unless you're meticulous about storage layout within a
data structure, a slice itself—using empty brackets with no size—is all you need:
There are also maps, which you can initialize like this:
The built-in function
to loop over the elements of a slice (or map or ...) , we could write
This assigns
or the more idiomatic
Some types—maps, slices, and channels (see below)—have reference semantics.
@@ -420,14 +420,14 @@ referencing the same underlying data will see the modification. For these three
types you want to use the built-in function
This statement initializes a new map ready to store entries.
If you just declare the map, as in
it creates a
There are nuances that deserve redirection to the legalese of the
language specification but here are some illustrative examples:
Conversions only work for simple cases such as converting
-
The first few lines declare the name of the
@@ -518,13 +518,13 @@ will soon give it some exported, upper-case methods.
First, though, here is a factory to create a
-
This returns a pointer to a new
but for simple structures like
We can use the factory to construct some familiar, exported variables of type
-
The
-
There are a number of new things in these few lines. First,
-
-
Back to our main story.
@@ -619,44 +620,44 @@ of that type, placed
in parentheses before the function name. Here are some methods for
-
There is no implicit
We can now use our new package:
-
The ''
-
By now this should be easy to follow, but the
-Line 25 calls
Now let's make a variant of
-
Any type that has the two methods of
-
-(The
To use the new feature, we define a flag:
-
and use it from within a mostly unchanged
-
(We could also do the wrapping in
Fans of dependency injection may take cheer from how easily interfaces
@@ -895,7 +896,7 @@ implement a
Every type implements the empty interface, which makes it
@@ -910,36 +911,36 @@ same interface variable.
As an example, consider this simple sort algorithm taken from
-
The code needs only three methods, which we wrap into sort's
-
We can apply
-
Here we see methods defined for non-
-
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:
-
@@ -990,7 +991,7 @@ implements
The token
-
prints
In fact, if you're lazy the format
-
is
You can drop the formatting altogether if you use
-
If you have your own type you'd like
-
Since
Observe that the
The code uses a ``type assertion'' (
(This interface is another conventional name, this time for
Here is the first function in
-
The
-
The generator and filters execute concurrently. Go has
@@ -1219,37 +1220,37 @@ this starts the function running in parallel with the current
computation but in the same address space:
If you want to know when the calculation is done, pass a channel
on which it can report back:
Back to our prime sieve. Here's how the sieve pipeline is stitched
together:
-
-Line 29 creates the initial channel to pass to
+The first line of
-
This version does all the setup internally. It creates the output
@@ -1275,54 +1276,54 @@ channel, launches a goroutine running a function literal, and
returns the channel to the caller. It is a factory for concurrent
execution, starting the goroutine and returning its connection.
-The function literal notation (lines 12-16) allows us to construct an
+The function literal notation used in the
The same change can be made to
-
The
-
Now
-
-
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:
-
-Line 14 defines the name
The
-
We construct a server in a familiar way, starting it and returning a channel
connected to it:
-
Here's a simple test. It starts a server with an addition operator and sends out
-
One annoyance with this program is that it doesn't shut down the server cleanly; when
-
It passes the quit channel to the
-
Inside
-
There's a lot more to Go programming and concurrent programming in general but this
diff --git a/doc/go_tutorial.txt b/doc/go_tutorial.txt
index 7e2bc7c4b..17ef6eee9 100644
--- a/doc/go_tutorial.txt
+++ b/doc/go_tutorial.txt
@@ -28,7 +28,7 @@ Hello, World
Let's start in the usual way:
---PROG progs/helloworld.go /package/ END
+!src progs/helloworld.go /package/ $
Every Go source file declares, using a "package" statement, which package it's part of.
It may also import other packages to use their facilities.
@@ -107,13 +107,13 @@ Echo
Next up, here's a version of the Unix utility "echo(1)":
---PROG progs/echo.go /package/ END
+!src progs/echo.go /package/ $
This program is small but it's doing a number of new things. In the last example,
we saw "func" introduce a function. The keywords "var", "const", and "type"
(not used yet) also introduce declarations, as does "import".
Notice that we can group declarations of the same sort into
-parenthesized lists, one item per line, as on lines 7-10 and 14-17.
+parenthesized lists, one item per line, as in the "import" and "const" clauses here.
But it's not necessary to do so; we could have said
const Space = " "
@@ -163,7 +163,7 @@ or we could go even shorter and write the idiom
The ":=" operator is used a lot in Go to represent an initializing declaration.
There's one in the "for" clause on the next line:
---PROG progs/echo.go /for/
+!src progs/echo.go /for/
The "flag" package has parsed the arguments and left the non-flag arguments
in a list that can be iterated over in the obvious way.
@@ -210,7 +210,7 @@ Once you've built a string value, you can't change it, although
of course you can change a string variable simply by
reassigning it. This snippet from "strings.go" is legal code:
---PROG progs/strings.go /hello/ /ciao/
+!src progs/strings.go /hello/ /ciao/
However the following statements are illegal because they would modify
a "string" value:
@@ -269,7 +269,7 @@ will slice the whole array.
Using slices one can write this function (from "sum.go"):
---PROG progs/sum.go /sum/ /^}/
+!src progs/sum.go /sum/ /^}/
Note how the return type ("int") is defined for "sum" by stating it
after the parameter list.
@@ -386,7 +386,7 @@ An I/O Package
Next we'll look at a simple package for doing file I/O with an
open/close/read/write interface. Here's the start of "file.go":
---PROG progs/file.go /package/ /^}/
+!src progs/file.go /package/ /^}/
The first few lines declare the name of the
package—"file"—and then import two packages. The "os"
@@ -416,7 +416,7 @@ will soon give it some exported, upper-case methods.
First, though, here is a factory to create a "File":
---PROG progs/file.go /newFile/ /^}/
+!src progs/file.go /newFile/ /^}/
This returns a pointer to a new "File" structure with the file descriptor and name
filled in. This code uses Go's notion of a ''composite literal'', analogous to
@@ -433,12 +433,12 @@ composite literal, as is done here on line 21.
We can use the factory to construct some familiar, exported variables of type "*File":
---PROG progs/file.go /var/ /^.$/
+!src progs/file.go /var/ /^.$/
The "newFile" function was not exported because it's internal. The proper,
exported factory to use is "OpenFile" (we'll explain that name in a moment):
---PROG progs/file.go /func.OpenFile/ /^}/
+!src progs/file.go /func.OpenFile/ /^}/
There are a number of new things in these few lines. First, "OpenFile" returns
multiple values, a "File" and an error (more about errors in a moment).
@@ -468,9 +468,9 @@ the implementation of our "Open" and "Create"; they're trivial
wrappers that eliminate common errors by capturing
the tricky standard arguments to open and, especially, to create a file:
---PROG progs/file.go /^const/ /^}/
+!src progs/file.go /^const/ /^}/
---PROG progs/file.go /func.Create/ /^}/
+!src progs/file.go /func.Create/ /^}/
Back to our main story.
Now that we can build "Files", we can write methods for them. To declare
@@ -479,7 +479,7 @@ of that type, placed
in parentheses before the function name. Here are some methods for "*File",
each of which declares a receiver variable "file".
---PROG progs/file.go /Close/ END
+!src progs/file.go /Close/ $
There is no implicit "this" and the receiver variable must be used to access
members of the structure. Methods are not declared within
@@ -496,7 +496,7 @@ set of such error values.
We can now use our new package:
---PROG progs/helloworld3.go /package/ END
+!src progs/helloworld3.go /package/ $
The ''"./"'' in the import of ''"./file"'' tells the compiler
to use our own package rather than
@@ -520,12 +520,12 @@ Rotting cats
Building on the "file" package, here's a simple version of the Unix utility "cat(1)",
"progs/cat.go":
---PROG progs/cat.go /package/ END
+!src progs/cat.go /package/ $
By now this should be easy to follow, but the "switch" statement introduces some
new features. Like a "for" loop, an "if" or "switch" can include an
-initialization statement. The "switch" on line 18 uses one to create variables
-"nr" and "er" to hold the return values from the call to "f.Read". (The "if" on line 25
+initialization statement. The "switch" statement in "cat" uses one to create variables
+"nr" and "er" to hold the return values from the call to "f.Read". (The "if" a few lines later
has the same idea.) The "switch" statement is general: it evaluates the cases
from top to bottom looking for the first case that matches the value; the
case expressions don't need to be constants or even integers, as long as
@@ -537,7 +537,7 @@ in a "for" statement, a missing value means "true". In fact, such a "switch"
is a form of "if-else" chain. While we're here, it should be mentioned that in
"switch" statements each "case" has an implicit "break".
-Line 25 calls "Write" by slicing the incoming buffer, which is itself a slice.
+The argument to "file.Stdout.Write" is created by slicing the array "buf".
Slices provide the standard Go way to handle I/O buffers.
Now let's make a variant of "cat" that optionally does "rot13" on its input.
@@ -548,7 +548,7 @@ The "cat" subroutine uses only two methods of "f": "Read" and "String",
so let's start by defining an interface that has exactly those two methods.
Here is code from "progs/cat_rot13.go":
---PROG progs/cat_rot13.go /type.reader/ /^}/
+!src progs/cat_rot13.go /type.reader/ /^}/
Any type that has the two methods of "reader"—regardless of whatever
other methods the type may also have—is said to implement the
@@ -560,34 +560,32 @@ existing "reader" and does "rot13" on the data. To do this, we just define
the type and implement the methods and with no other bookkeeping,
we have a second implementation of the "reader" interface.
---PROG progs/cat_rot13.go /type.rotate13/ /end.of.rotate13/
+!src progs/cat_rot13.go /type.rotate13/ /end.of.rotate13/
-(The "rot13" function called on line 42 is trivial and not worth reproducing here.)
+(The "rot13" function called in "Read" is trivial and not worth reproducing here.)
To use the new feature, we define a flag:
---PROG progs/cat_rot13.go /rot13Flag/
+!src progs/cat_rot13.go /rot13Flag/
and use it from within a mostly unchanged "cat" function:
---PROG progs/cat_rot13.go /func.cat/ /^}/
+!src progs/cat_rot13.go /func.cat/ /^}/
(We could also do the wrapping in "main" and leave "cat" mostly alone, except
for changing the type of the argument; consider that an exercise.)
-Lines 56 through 58 set it all up: If the "rot13" flag is true, wrap the "reader"
+The "if" at the top of "cat" sets it all up: If the "rot13" flag is true, wrap the "reader"
we received into a "rotate13" and proceed. Note that the interface variables
are values, not pointers: the argument is of type "reader", not "*reader",
even though under the covers it holds a pointer to a "struct".
Here it is in action:
- marks (except inside \n")
+
+ srcPrefix = []byte("!src")
)
func main() {
+ flag.Parse()
read()
- headings()
- coalesce(preStart, foldPre)
- coalesce(tab, foldTabs)
- paragraphs()
- quotes()
+ programs()
+ if *html {
+ headings()
+ coalesce(preStart, foldPre)
+ coalesce(tab, foldTabs)
+ paragraphs()
+ quotes()
+ }
write()
}
+// read turns standard input into a slice of lines.
func read() {
b := bufio.NewReader(os.Stdin)
for {
@@ -56,6 +90,7 @@ func read() {
}
}
+// write puts the result on standard output.
func write() {
b := bufio.NewWriter(os.Stdout)
for _, line := range lines {
@@ -64,8 +99,104 @@ func write() {
b.Flush()
}
-// each time prefix is found on a line, call fold and replace
-// line with return value from fold.
+// programs injects source code from !src invocations.
+func programs() {
+ nlines := make([][]byte, 0, len(lines)*3/2)
+ for _, line := range lines {
+ if bytes.HasPrefix(line, srcPrefix) {
+ line = trim(line)[len(srcPrefix):]
+ prog := srcCommand(string(line))
+ if *html {
+ nlines = append(nlines, []byte(fmt.Sprintf("r58 (released 2011/06/29)
+
+weekly.2011-06-09
+with additional bug fixes.
+This section highlights the most significant changes in this release.
+For a more detailed summary, see the
+weekly release notes.
+For complete information, see the
+Mercurial change list.
+Language
+
+goto.
+Packages
+
+finalURL return
+value from the Client.Get method. The value
+is now available via the new Request field on http.Response.
+Most instances of the type map[string][]string in have been
+replaced with the new Values type.
+"%q"
+formatting directive. The previous quoting behavior is still available via
+strconv's new QuoteToASCII function.
+exp/draw. The GUI-related code from exp/draw is now
+located in the exp/gui package.
+Tools
+
+r57 (released 2011/05/03)
2011-07-07
+
+
+This weekly snapshot includes changes to the strings, http, reflect, json, and
+xml packages. Code that uses these packages will need changes. Most of these
+changes can be made automatically with gofix.
+
+The strings package's Split function has itself been split into Split and
+SplitN. SplitN is the same as the old Split. The new Split is equivalent to
+SplitN with a final argument of -1.
+
+The http package has a new FileSystem interface that provides access to files.
+The FileServer helper now takes a FileSystem argument instead of an explicit
+file system root. By implementing your own FileSystem you can use the
+FileServer to serve arbitrary data.
+
+The reflect package supports a new struct tag scheme that enables sharing of
+struct tags between multiple packages.
+In this scheme, the tags must be of the form:
+ key:"value" key2:"value2"
+reflect.StructField's Tag field now has type StructTag (a string type), which
+has method Get(key string) string that returns the associated value.
+Clients of json and xml will need to be updated. Code that says
+ type T struct {
+ X int "name"
+ }
+should become
+ type T struct {
+ X int `json:"name"` // or `xml:"name"`
+ }
+Use govet to identify struct tags that need to be changed to use the new syntax.
+
+Other changes:
+* 5l, 6l, 8l: drop use of ed during build.
+* asn1: support T61 and UTF8 string.
+* bufio: do not cache Read errors (thanks Graham Miller).
+* build: make version.bash aware of branches.
+* cgi: don't depend on CGI.pm for tests.
+* codereview: make --ignore_hgpatch_failure work again,
+ restrict sync to default branch.
+* crypto/openpgp: add ability to reserialize keys,
+ bug fix (thanks Gideon Jan-Wessel Redelinghuys).
+* crypto/tls: fix generate_cert.go.
+* crypto/x509: prevent chain cycles in Verify.
+* csv: new package.
+* doc: remove ed from apt-get package list.
+* docs: fold the prog.sh scripting from makehtml into htmlgen itself.
+* ebnflint: better handling of stdin.
+* exp/regexp/syntax: new experimental RE2-based regexp implementation.
+* exp/template: a new experimental templating package.
+* fmt: add SkipSpace to fmt's ScanState interface.
+* fmt: rename errno and error to err for doc consistency.
+* gc: avoid package name ambiguity in error messages,
+ fix package quoting logic,
+ fixes for Plan 9 (thanks Lucio De Re).
+* go/build: evaluate symlinks before comparing path to GOPATH.
+* gob: use exported fields in structs in the package documentation.
+* godoc: ignore directories that begin with '.',
+ search GOPATH for documentation.
+* gofix: os/signal, path/filepath, and sort fixes (thanks Robert Hencke),
+* goinstall: add support for generic hosts (thanks Julian Phillips),
+ only report successfully-installed packages to the dashboard,
+ try to access via https (thanks Yasuhiro Matsumoto).
+* gotest: add -test.benchtime and -test.cpu flags.
+* html: fixes and improvements (thanks Yasuhiro Matsumoto).
+* http/cgi: add Handler.Dir to specify working directory (thanks Yasuhiro Matsumoto).
+* http: add StripPrefix handler wrapper,
+ assume ContentLength 0 on GET requests,
+ better handling of 0-length Request.Body,
+ do TLS handshake explicitly before copying TLS state,
+ document that ServerConn and ClientConn are low-level,
+ make NewChunkedReader public (thanks Andrew Balholm),
+ respect Handlers setting Connection: close in their response.
+* image: more tests, Paletted.Opaque optimization.
+* io.WriteString: if the object has a WriteString method, use it (thanks Evan Shaw).
+* ld: elide the Go symbol table when using -s (thanks Anthony Martin).
+* ld: fix ELF strip by removing overlap of sections (thanks Gustavo Niemeyer).
+* mime/multipart: parse LF-delimited messages, not just CRLF.
+* mime: permit lower-case media type parameters (thanks Pascal S. de Kloe).
+* misc/dashboard: new features and improvements (not yet deployed).
+* misc/emacs: update list of builtins (thanks Quan Yong Zhai).
+* misc/vim: allow only utf-8 for file encoding (thanks Yasuhiro Matsumoto).
+* os: fix documentation for FileInfo.Name,
+ simplify WriteString,
+ use a different symbol from syscall in mkunixsignals.sh.
+* path/filepath: enable TestWalk to run on windows (thanks Alex Brainman).
+* reflect: add MethodByName,
+ allow Len on String values.
+* regexp: document that Regexp is thread-safe.
+* runtime/cgo: check for errors from pthread_create (thanks Albert Strasheim).
+* runtime: add Semacquire/Semrelease benchmarks,
+ improved Semacquire/Semrelease implementation,
+ windows/amd64 port (thanks Wei Guangjing).
+* sync: add fast path to Once,
+ improve Mutex to allow successive acquisitions,
+ new and improved benchmarks.
+* syscall: regenerate zerrors for darwin/linux/freebsd,
+ support for tty options in StartProcess (thanks Ken Rockot).
+* testing: make ResetTimer not start/stop the timer,
+ scale benchmark precision to 0.01ns if needed.
+* time: zero-pad two-digit years.
+* unicode/maketables: update debugging data.
+* windows: define and use syscall.Handle (thanks Wei Guangjing).
+* xml: add Marshal and MarshalIndent.
+
+
2011-06-23
@@ -128,7 +234,7 @@ Other changes:
* xml: handle non-string attribute fields (thanks Maxim Ushakov).
-2011-06-09
+2011-06-09 (base for r58)
This release includes changes to the strconv, http, and exp/draw packages.
diff --git a/doc/go_tutorial.html b/doc/go_tutorial.html
index 4f3f6b94b..822f9626e 100644
--- a/doc/go_tutorial.html
+++ b/doc/go_tutorial.html
@@ -26,14 +26,14 @@ cleanliness, blank lines remain blank.
-05 package main
+
package main
-07 import fmt "fmt" // Package implementing formatted I/O.
+import fmt "fmt" // Package implementing formatted I/O.
-09 func main() {
-10 fmt.Printf("Hello, world; or Καλημέρα κόσμε; or こんにちは 世界\n")
-11 }
+func main() {
+ fmt.Printf("Hello, world; or Καλημέρα κόσμε; or こんにちは 世界\n")
+}
package statement, which package it's part of.
@@ -51,8 +51,8 @@ String constants can contain Unicode characters, encoded in UTF-8.
The comment convention is the same as in C++:
- /* ... */
- // ...
+/* ... */
+// ...
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 こんにちは 世界
- $
+$ 6g helloworld.go # compile; object goes into helloworld.6
+$ 6l helloworld.6 # link; output goes into 6.out
+$ 6.out
+Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
+$
gccgo it looks a little more traditional.
- $ gccgo helloworld.go
- $ a.out
- Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
- $
+$ gccgo helloworld.go
+$ a.out
+Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
+$
Echo
echo(1):
-05 package main
+
package main
-07 import (
-08 "os"
-09 "flag" // command line option parser
-10 )
+import (
+ "os"
+ "flag" // command line option parser
+)
-12 var omitNewline = flag.Bool("n", false, "don't print final newline")
+var omitNewline = flag.Bool("n", false, "don't print final newline")
-14 const (
-15 Space = " "
-16 Newline = "\n"
-17 )
+const (
+ Space = " "
+ Newline = "\n"
+)
-19 func main() {
-20 flag.Parse() // Scans the arg list and sets up flags
-21 var s string = ""
-22 for i := 0; i < flag.NArg(); i++ {
-23 if i > 0 {
-24 s += Space
-25 }
-26 s += flag.Arg(i)
-27 }
-28 if !*omitNewline {
-29 s += Newline
-30 }
-31 os.Stdout.WriteString(s)
-32 }
+func main() {
+ flag.Parse() // Scans the arg list and sets up flags
+ var s string = ""
+ for i := 0; i < flag.NArg(); i++ {
+ if i > 0 {
+ s += Space
+ }
+ s += flag.Arg(i)
+ }
+ if !*omitNewline {
+ s += Newline
+ }
+ os.Stdout.WriteString(s)
+}
func introduce a function. The keywords var, const, and type
(not used yet) also introduce declarations, as does import.
Notice that we can group declarations of the same sort into
-parenthesized lists, one item per line, as on lines 7-10 and 14-17.
+parenthesized lists, one item per line, as in the import and const clauses here.
But it's not necessary to do so; we could have said
- const Space = " "
- const Newline = "\n"
+const Space = " "
+const Newline = "\n"
"os" package to access its Stdout variable, of type
@@ -186,7 +186,7 @@ string variable we will use to build the output.
The declaration statement has the form
- var s string = ""
+var s string = ""
var keyword, followed by the name of the variable, followed by
@@ -197,20 +197,20 @@ string constant is of type string, we don't have to tell the compiler that.
We could write
- var s = ""
+var s = ""
- s := ""
+s := ""
:= operator is used a lot in Go to represent an initializing declaration.
There's one in the for clause on the next line:
-22 for i := 0; i < flag.NArg(); i++ {
+ for i := 0; i < flag.NArg(); i++ {
flag package has parsed the arguments and left the non-flag arguments
@@ -231,7 +231,7 @@ It's defined that way. Falling off the end of main.main means
''success''; if you want to signal an erroneous return, call
- os.Exit(1)
+os.Exit(1)
os package contains other essentials for getting
@@ -259,20 +259,20 @@ Once you've built a string value, you can't change it, although
of course you can change a string variable simply by
reassigning it. This snippet from strings.go is legal code:
-10 s := "hello"
-11 if s[1] != 'e' { os.Exit(1) }
-12 s = "good bye"
-13 var p *string = &s
-14 *p = "ciao"
+ s := "hello"
+ if s[1] != 'e' { os.Exit(1) }
+ s = "good bye"
+ var p *string = &s
+ *p = "ciao"
string value:
- s[0] = 'x'
- (*p)[1] = 'y'
+s[0] = 'x'
+(*p)[1] = 'y'
const strings, while pointers
@@ -284,7 +284,7 @@ read on.
Arrays are declared like this:
- var arrayOfInt [10]int
+var arrayOfInt [10]int
- [3]int{1,2,3}
+[3]int{1,2,3}
ints.
@@ -330,14 +330,14 @@ will slice the whole array.
sum.go):
-09 func sum(a []int) int { // returns an int
-10 s := 0
-11 for i := 0; i < len(a); i++ {
-12 s += a[i]
-13 }
-14 return s
-15 }
+func sum(a []int) int { // returns an int
+ s := 0
+ for i := 0; i < len(a); i++ {
+ s += a[i]
+ }
+ return s
+}
int) is defined for sum by stating it
@@ -348,14 +348,14 @@ a simpler way in a moment) constructs
an array and slices it:
- s := sum([3]int{1,2,3}[:])
+s := sum([3]int{1,2,3}[:])
... as the array size:
- s := sum([...]int{1,2,3}[:])
+s := sum([...]int{1,2,3}[:])
- s := sum([]int{1,2,3})
+s := sum([]int{1,2,3})
- m := map[string]int{"one":1 , "two":2}
+m := map[string]int{"one":1 , "two":2}
len, which returns number of elements,
@@ -380,13 +380,13 @@ By the way, another thing that works on strings, arrays, slices, maps
and channels is the range clause on for loops. Instead of writing
- for i := 0; i < len(a); i++ { ... }
+for i := 0; i < len(a); i++ { ... }
- for i, v := range a { ... }
+for i, v := range a { ... }
i to the index and v to the value of the successive
@@ -404,14 +404,14 @@ 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)
+type T struct { a, b int }
+var t *T = new(T)
- t := new(T)
+t := new(T)
make:
- m := make(map[string]int)
+m := make(map[string]int)
- var m map[string]int
+var m map[string]int
nil reference that cannot hold anything. To use the map,
@@ -448,20 +448,20 @@ can overflow only when they are assigned to an integer variable with
too little precision to represent the value.
- const hardEight = (1 << 100) >> 97 // legal
+const hardEight = (1 << 100) >> 97 // legal
- var a uint64 = 0 // a has type uint64, value 0
- a := uint64(0) // equivalent; uses a "conversion"
- i := 0x1234 // i gets default type: int
- var j int = 1e6 // legal - 1000000 is representable in an int
- x := 1.5 // a float64, the default type for floating constants
- i3div2 := 3/2 // integer division - result is 1
- f3div2 := 3./2. // floating-point division - result is 1.5
+var a uint64 = 0 // a has type uint64, value 0
+a := uint64(0) // equivalent; uses a "conversion"
+i := 0x1234 // i gets default type: int
+var j int = 1e6 // legal - 1000000 is representable in an int
+x := 1.5 // a float64, the default type for floating constants
+i3div2 := 3/2 // integer division - result is 1
+f3div2 := 3./2. // floating-point division - result is 1.5
ints of one
@@ -476,18 +476,18 @@ assigned to a variable.
Next we'll look at a simple package for doing file I/O with an
open/close/read/write interface. Here's the start of file.go:
-05 package file
+
package file
-07 import (
-08 "os"
-09 "syscall"
-10 )
+import (
+ "os"
+ "syscall"
+)
-12 type File struct {
-13 fd int // file descriptor number
-14 name string // file name at Open time
-15 }
+type File struct {
+ fd int // file descriptor number
+ name string // file name at Open time
+}
File:
-17 func newFile(fd int, name string) *File {
-18 if fd < 0 {
-19 return nil
-20 }
-21 return &File{fd, name}
-22 }
+func newFile(fd int, name string) *File {
+ if fd < 0 {
+ return nil
+ }
+ return &File{fd, name}
+}
File structure with the file descriptor and name
@@ -533,10 +533,10 @@ the ones used to build maps and arrays, to construct a new heap-allocated
object. We could write
- n := new(File)
- n.fd = fd
- n.name = name
- return n
+n := new(File)
+n.fd = fd
+n.name = name
+return n
File it's easier to return the address of a
@@ -544,25 +544,26 @@ composite literal, as is done here on line 21.
*File:
-24 var (
-25 Stdin = newFile(syscall.Stdin, "/dev/stdin")
-26 Stdout = newFile(syscall.Stdout, "/dev/stdout")
-27 Stderr = newFile(syscall.Stderr, "/dev/stderr")
-28 )
+
var (
+ Stdin = newFile(syscall.Stdin, "/dev/stdin")
+ Stdout = newFile(syscall.Stdout, "/dev/stdout")
+ Stderr = newFile(syscall.Stderr, "/dev/stderr")
+)
+
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):
-30 func OpenFile(name string, mode int, perm uint32) (file *File, err os.Error) {
-31 r, e := syscall.Open(name, mode, perm)
-32 if e != 0 {
-33 err = os.Errno(e)
-34 }
-35 return newFile(r, name), err
-36 }
+func OpenFile(name string, mode int, perm uint32) (file *File, err os.Error) {
+ r, e := syscall.Open(name, mode, perm)
+ if e != 0 {
+ err = os.Errno(e)
+ }
+ return newFile(r, name), err
+}
OpenFile returns
@@ -593,23 +594,23 @@ the implementation of our Open and Create; they're tri
wrappers that eliminate common errors by capturing
the tricky standard arguments to open and, especially, to create a file:
-38 const (
-39 O_RDONLY = syscall.O_RDONLY
-40 O_RDWR = syscall.O_RDWR
-41 O_CREATE = syscall.O_CREAT
-42 O_TRUNC = syscall.O_TRUNC
-43 )
+
const (
+ O_RDONLY = syscall.O_RDONLY
+ O_RDWR = syscall.O_RDWR
+ O_CREATE = syscall.O_CREAT
+ O_TRUNC = syscall.O_TRUNC
+)
-45 func Open(name string) (file *File, err os.Error) {
-46 return OpenFile(name, O_RDONLY, 0)
-47 }
+func Open(name string) (file *File, err os.Error) {
+ return OpenFile(name, O_RDONLY, 0)
+}
-49 func Create(name string) (file *File, err os.Error) {
-50 return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
-51 }
+func Create(name string) (file *File, err os.Error) {
+ return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
+}
*File,
each of which declares a receiver variable file.
-53 func (file *File) Close() os.Error {
-54 if file == nil {
-55 return os.EINVAL
-56 }
-57 e := syscall.Close(file.fd)
-58 file.fd = -1 // so it can't be closed again
-59 if e != 0 {
-60 return os.Errno(e)
-61 }
-62 return nil
-63 }
+func (file *File) Close() os.Error {
+ if file == nil {
+ return os.EINVAL
+ }
+ e := syscall.Close(file.fd)
+ file.fd = -1 // so it can't be closed again
+ if e != 0 {
+ return os.Errno(e)
+ }
+ return nil
+}
-65 func (file *File) Read(b []byte) (ret int, err os.Error) {
-66 if file == nil {
-67 return -1, os.EINVAL
-68 }
-69 r, e := syscall.Read(file.fd, b)
-70 if e != 0 {
-71 err = os.Errno(e)
-72 }
-73 return int(r), err
-74 }
+func (file *File) Read(b []byte) (ret int, err os.Error) {
+ if file == nil {
+ return -1, os.EINVAL
+ }
+ r, e := syscall.Read(file.fd, b)
+ if e != 0 {
+ err = os.Errno(e)
+ }
+ return int(r), err
+}
-76 func (file *File) Write(b []byte) (ret int, err os.Error) {
-77 if file == nil {
-78 return -1, os.EINVAL
-79 }
-80 r, e := syscall.Write(file.fd, b)
-81 if e != 0 {
-82 err = os.Errno(e)
-83 }
-84 return int(r), err
-85 }
+func (file *File) Write(b []byte) (ret int, err os.Error) {
+ if file == nil {
+ return -1, os.EINVAL
+ }
+ r, e := syscall.Write(file.fd, b)
+ if e != 0 {
+ err = os.Errno(e)
+ }
+ return int(r), err
+}
-87 func (file *File) String() string {
-88 return file.name
-89 }
+func (file *File) String() string {
+ return file.name
+}
this and the receiver variable must be used to access
@@ -674,24 +675,24 @@ set of such error values.
-05 package main
+
package main
-07 import (
-08 "./file"
-09 "fmt"
-10 "os"
-11 )
+import (
+ "./file"
+ "fmt"
+ "os"
+)
-13 func main() {
-14 hello := []byte("hello, world\n")
-15 file.Stdout.Write(hello)
-16 f, err := file.Open("/does/not/exist")
-17 if f == nil {
-18 fmt.Printf("can't open file; err=%s\n", err.String())
-19 os.Exit(1)
-20 }
-21 }
+func main() {
+ hello := []byte("hello, world\n")
+ file.Stdout.Write(hello)
+ f, err := file.Open("/does/not/exist")
+ if f == nil {
+ fmt.Printf("can't open file; err=%s\n", err.String())
+ os.Exit(1)
+ }
+}
./'' in the import of ''./file'' tells the compiler
@@ -703,13 +704,13 @@ 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
- $
+$ 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
@@ -717,56 +718,56 @@ Now we can compile and run the program. On Unix, this would be the result:
Building on the file package, here's a simple version of the Unix utility cat(1),
progs/cat.go:
-05 package main
+
package main
-07 import (
-08 "./file"
-09 "flag"
-10 "fmt"
-11 "os"
-12 )
+import (
+ "./file"
+ "flag"
+ "fmt"
+ "os"
+)
-14 func cat(f *file.File) {
-15 const NBUF = 512
-16 var buf [NBUF]byte
-17 for {
-18 switch nr, er := f.Read(buf[:]); true {
-19 case nr < 0:
-20 fmt.Fprintf(os.Stderr, "cat: error reading from %s: %s\n", f.String(), er.String())
-21 os.Exit(1)
-22 case nr == 0: // EOF
-23 return
-24 case nr > 0:
-25 if nw, ew := file.Stdout.Write(buf[0:nr]); nw != nr {
-26 fmt.Fprintf(os.Stderr, "cat: error writing from %s: %s\n", f.String(), ew.String())
-27 os.Exit(1)
-28 }
-29 }
-30 }
-31 }
+func cat(f *file.File) {
+ const NBUF = 512
+ var buf [NBUF]byte
+ for {
+ switch nr, er := f.Read(buf[:]); true {
+ case nr < 0:
+ fmt.Fprintf(os.Stderr, "cat: error reading from %s: %s\n", f.String(), er.String())
+ os.Exit(1)
+ case nr == 0: // EOF
+ return
+ case nr > 0:
+ if nw, ew := file.Stdout.Write(buf[0:nr]); nw != nr {
+ fmt.Fprintf(os.Stderr, "cat: error writing from %s: %s\n", f.String(), ew.String())
+ os.Exit(1)
+ }
+ }
+ }
+}
-33 func main() {
-34 flag.Parse() // Scans the arg list and sets up flags
-35 if flag.NArg() == 0 {
-36 cat(file.Stdin)
-37 }
-38 for i := 0; i < flag.NArg(); i++ {
-39 f, err := file.Open(flag.Arg(i))
-40 if f == nil {
-41 fmt.Fprintf(os.Stderr, "cat: can't open %s: error %s\n", flag.Arg(i), err)
-42 os.Exit(1)
-43 }
-44 cat(f)
-45 f.Close()
-46 }
-47 }
+func main() {
+ flag.Parse() // Scans the arg list and sets up flags
+ if flag.NArg() == 0 {
+ cat(file.Stdin)
+ }
+ for i := 0; i < flag.NArg(); i++ {
+ f, err := file.Open(flag.Arg(i))
+ if f == nil {
+ fmt.Fprintf(os.Stderr, "cat: can't open %s: error %s\n", flag.Arg(i), err)
+ os.Exit(1)
+ }
+ cat(f)
+ f.Close()
+ }
+}
switch statement introduces some
new features. Like a for loop, an if or switch can include an
-initialization statement. The switch on line 18 uses one to create variables
-nr and er to hold the return values from the call to f.Read. (The if on line 25
+initialization statement. The switch statement in cat uses one to create variables
+nr and er to hold the return values from the call to f.Read. (The if a few lines later
has the same idea.) The switch statement is general: it evaluates the cases
from top to bottom looking for the first case that matches the value; the
case expressions don't need to be constants or even integers, as long as
@@ -778,7 +779,7 @@ in a for statement, a missing value means true. In fa
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.
Write by slicing the incoming buffer, which is itself a slice.
+The argument to file.Stdout.Write is created by slicing the array buf.
Slices provide the standard Go way to handle I/O buffers.
cat that optionally does rot13 on its input.
@@ -789,11 +790,11 @@ The cat subroutine uses only two methods of f: R
so let's start by defining an interface that has exactly those two methods.
Here is code from progs/cat_rot13.go:
-26 type reader interface {
-27 Read(b []byte) (ret int, err os.Error)
-28 String() string
-29 }
+type reader interface {
+ Read(b []byte) (ret int, err os.Error)
+ String() string
+}
reader—regardless of whatever
@@ -806,68 +807,68 @@ existing reader and does rot13 on the data. To do this
the type and implement the methods and with no other bookkeeping,
we have a second implementation of the reader interface.
-31 type rotate13 struct {
-32 source reader
-33 }
+type rotate13 struct {
+ source reader
+}
-35 func newRotate13(source reader) *rotate13 {
-36 return &rotate13{source}
-37 }
+func newRotate13(source reader) *rotate13 {
+ return &rotate13{source}
+}
-39 func (r13 *rotate13) Read(b []byte) (ret int, err os.Error) {
-40 r, e := r13.source.Read(b)
-41 for i := 0; i < r; i++ {
-42 b[i] = rot13(b[i])
-43 }
-44 return r, e
-45 }
+func (r13 *rotate13) Read(b []byte) (ret int, err os.Error) {
+ r, e := r13.source.Read(b)
+ for i := 0; i < r; i++ {
+ b[i] = rot13(b[i])
+ }
+ return r, e
+}
-47 func (r13 *rotate13) String() string {
-48 return r13.source.String()
-49 }
-50 // end of rotate13 implementation
+func (r13 *rotate13) String() string {
+ return r13.source.String()
+}
+// end of rotate13 implementation
rot13 function called on line 42 is trivial and not worth reproducing here.)
+(The rot13 function called in Read is trivial and not worth reproducing here.)
-14 var rot13Flag = flag.Bool("rot13", false, "rot13 the input")
+var rot13Flag = flag.Bool("rot13", false, "rot13 the input")
cat function:
-52 func cat(r reader) {
-53 const NBUF = 512
-54 var buf [NBUF]byte
+func cat(r reader) {
+ const NBUF = 512
+ var buf [NBUF]byte
-56 if *rot13Flag {
-57 r = newRotate13(r)
-58 }
-59 for {
-60 switch nr, er := r.Read(buf[:]); {
-61 case nr < 0:
-62 fmt.Fprintf(os.Stderr, "cat: error reading from %s: %s\n", r.String(), er.String())
-63 os.Exit(1)
-64 case nr == 0: // EOF
-65 return
-66 case nr > 0:
-67 nw, ew := file.Stdout.Write(buf[0:nr])
-68 if nw != nr {
-69 fmt.Fprintf(os.Stderr, "cat: error writing from %s: %s\n", r.String(), ew.String())
-70 os.Exit(1)
-71 }
-72 }
-73 }
-74 }
+ if *rot13Flag {
+ r = newRotate13(r)
+ }
+ for {
+ switch nr, er := r.Read(buf[:]); {
+ case nr < 0:
+ fmt.Fprintf(os.Stderr, "cat: error reading from %s: %s\n", r.String(), er.String())
+ os.Exit(1)
+ case nr == 0: // EOF
+ return
+ case nr > 0:
+ nw, ew := file.Stdout.Write(buf[0:nr])
+ if nw != nr {
+ fmt.Fprintf(os.Stderr, "cat: error writing from %s: %s\n", r.String(), ew.String())
+ os.Exit(1)
+ }
+ }
+ }
+}
main and leave cat mostly alone, except
for changing the type of the argument; consider that an exercise.)
-Lines 56 through 58 set it all up: If the rot13 flag is true, wrap the reader
+The if at the top of cat sets it all up: If the rot13 flag is true, wrap the reader
we received into a rotate13 and proceed. Note that the interface variables
are values, not pointers: the argument is of type reader, not *reader,
even though under the covers it holds a pointer to a struct.
@@ -875,11 +876,11 @@ 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
- $
+$ echo abcdefghijklmnopqrstuvwxyz | ./cat
+abcdefghijklmnopqrstuvwxyz
+$ echo abcdefghijklmnopqrstuvwxyz | ./cat --rot13
+nopqrstuvwxyzabcdefghijklm
+$
writer, or any other interface built from its methods t
fits the current situation. Consider the empty interface
- type Empty interface {}
+type Empty interface {}
progs/sort.go:
-13 func Sort(data Interface) {
-14 for i := 1; i < data.Len(); i++ {
-15 for j := i; j > 0 && data.Less(j, j-1); j-- {
-16 data.Swap(j, j-1)
-17 }
-18 }
-19 }
+func Sort(data Interface) {
+ for i := 1; i < data.Len(); i++ {
+ for j := i; j > 0 && data.Less(j, j-1); j-- {
+ data.Swap(j, j-1)
+ }
+ }
+}
Interface:
-07 type Interface interface {
-08 Len() int
-09 Less(i, j int) bool
-10 Swap(i, j int)
-11 }
+type Interface interface {
+ Len() int
+ Less(i, j int) bool
+ Swap(i, j int)
+}
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
-33 type IntSlice []int
+
type IntSlice []int
-35 func (p IntSlice) Len() int { return len(p) }
-36 func (p IntSlice) Less(i, j int) bool { return p[i] < p[j] }
-37 func (p IntSlice) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
+func (p IntSlice) Len() int { return len(p) }
+func (p IntSlice) Less(i, j int) bool { return p[i] < p[j] }
+func (p IntSlice) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
struct types. You can define methods
@@ -949,34 +950,34 @@ 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.
-12 func ints() {
-13 data := []int{74, 59, 238, -784, 9845, 959, 905, 0, 0, 42, 7586, -5467984, 7586}
-14 a := sort.IntSlice(data)
-15 sort.Sort(a)
-16 if !sort.IsSorted(a) {
-17 panic("fail")
-18 }
-19 }
+func ints() {
+ data := []int{74, 59, 238, -784, 9845, 959, 905, 0, 0, 42, 7586, -5467984, 7586}
+ a := sort.IntSlice(data)
+ sort.Sort(a)
+ if !sort.IsSorted(a) {
+ panic("fail")
+ }
+}
-30 type day struct {
-31 num int
-32 shortName string
-33 longName string
-34 }
+type day struct {
+ num int
+ shortName string
+ longName string
+}
-36 type dayArray struct {
-37 data []*day
-38 }
+type dayArray struct {
+ data []*day
+}
-40 func (p *dayArray) Len() int { return len(p.data) }
-41 func (p *dayArray) Less(i, j int) bool { return p.data[i].num < p.data[j].num }
-42 func (p *dayArray) Swap(i, j int) { p.data[i], p.data[j] = p.data[j], p.data[i] }
+func (p *dayArray) Len() int { return len(p.data) }
+func (p *dayArray) Less(i, j int) bool { return p.data[i].num < p.data[j].num }
+func (p *dayArray) Swap(i, j int) { p.data[i], p.data[j] = p.data[j], p.data[i] }
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)
+Printf(format string, v ...interface{}) (n int, errno os.Error)
... introduces a variable-length argument list that in C would
@@ -1011,34 +1012,34 @@ argument. It's easier in many cases in Go. Instead of %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
-10 var u64 uint64 = 1<<64-1
-11 fmt.Printf("%d %d\n", u64, int64(u64))
+ var u64 uint64 = 1<<64-1
+ fmt.Printf("%d %d\n", u64, int64(u64))
- 18446744073709551615 -1
+18446744073709551615 -1
%v will print, in a simple
appropriate style, any value, even an array or structure. The output of
-14 type T struct {
-15 a int
-16 b string
-17 }
-18 t := T{77, "Sunset Strip"}
-19 a := []int{1, 2, 3, 4}
-20 fmt.Printf("%v %v %v\n", u64, t, a)
+ type T struct {
+ a int
+ b string
+ }
+ t := T{77, "Sunset Strip"}
+ a := []int{1, 2, 3, 4}
+ fmt.Printf("%v %v %v\n", u64, t, a)
- 18446744073709551615 {77 Sunset Strip} [1 2 3 4]
+18446744073709551615 {77 Sunset Strip} [1 2 3 4]
Print or Println
@@ -1048,9 +1049,9 @@ 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.
-21 fmt.Print(u64, " ", t, " ", a, "\n")
-22 fmt.Println(u64, t, a)
+
fmt.Print(u64, " ", t, " ", a, "\n")
+ fmt.Println(u64, t, a)
Printf or Print to format,
@@ -1059,27 +1060,27 @@ routines will examine the value to inquire whether it implements
the method and if so, use it rather than some other formatting.
Here's a simple example.
-09 type testType struct {
-10 a int
-11 b string
-12 }
+type testType struct {
+ a int
+ b string
+}
-14 func (t *testType) String() string {
-15 return fmt.Sprint(t.a) + " " + t.b
-16 }
+func (t *testType) String() string {
+ return fmt.Sprint(t.a) + " " + t.b
+}
-18 func main() {
-19 t := &testType{77, "Sunset Strip"}
-20 fmt.Println(t)
-21 }
+func main() {
+ t := &testType{77, "Sunset Strip"}
+ fmt.Println(t)
+}
*testType has a String method, the
default formatter for that type will use it and produce the output
- 77 Sunset Strip
+77 Sunset Strip
String method calls Sprint (the obvious Go
@@ -1101,18 +1102,18 @@ Schematically, given a value v, it does this:
- type Stringer interface {
- String() string
- }
+type Stringer interface {
+ String() string
+}
- s, ok := v.(Stringer) // Test whether v implements "String()"
- if ok {
- result = s.String()
- } else {
- result = defaultOutput(v)
- }
+s, ok := v.(Stringer) // Test whether v implements "String()"
+if ok {
+ result = s.String()
+} else {
+ result = defaultOutput(v)
+}
v.(Stringer)) to test if the value stored in
@@ -1133,9 +1134,9 @@ not a file. Instead, it is a variable of type io.Writer, which is
interface type defined in the io library:
- type Writer interface {
- Write(p []byte) (n int, err os.Error)
- }
+type Writer interface {
+ Write(p []byte) (n int, err os.Error)
+}
Write; there are also
@@ -1178,13 +1179,13 @@ coordinates the communication; as with maps and slices, use
progs/sieve.go:
-09 // Send the sequence 2, 3, 4, ... to channel 'ch'.
-10 func generate(ch chan int) {
-11 for i := 2; ; i++ {
-12 ch <- i // Send 'i' to channel 'ch'.
-13 }
-14 }
+// 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'.
+ }
+}
generate function sends the sequence 2, 3, 4, 5, ... to its
@@ -1197,17 +1198,17 @@ channel, and a prime number. It copies values from the input to the
output, discarding anything divisible by the prime. The unary communications
operator <- (receive) retrieves the next value on the channel.
-16 // Copy the values from channel 'in' to channel 'out',
-17 // removing those divisible by 'prime'.
-18 func filter(in, out chan int, prime int) {
-19 for {
-20 i := <-in // Receive value of new variable 'i' from 'in'.
-21 if i % prime != 0 {
-22 out <- i // Send 'i' to channel 'out'.
-23 }
-24 }
-25 }
+// 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'.
+ if i % prime != 0 {
+ out <- i // Send 'i' to channel 'out'.
+ }
+ }
+}
- go sum(hugeArray) // calculate sum in the background
+go sum(hugeArray) // calculate sum in the background
- ch := make(chan int)
- go sum(hugeArray, ch)
- // ... do something else for a while
- result := <-ch // wait for, and retrieve, result
+ch := make(chan int)
+go sum(hugeArray, ch)
+// ... do something else for a while
+result := <-ch // wait for, and retrieve, result
-28 func main() {
-29 ch := make(chan int) // Create a new channel.
-30 go generate(ch) // Start generate() as a goroutine.
-31 for i := 0; i < 100; i++ { // Print the first hundred primes.
-32 prime := <-ch
-33 fmt.Println(prime)
-34 ch1 := make(chan int)
-35 go filter(ch, ch1, prime)
-36 ch = ch1
-37 }
-38 }
-
-generate, which it
+func main() {
+ ch := make(chan int) // Create a new channel.
+ go generate(ch) // Start generate() as a goroutine.
+ for i := 0; i < 100; i++ { // Print the first hundred primes.
+ prime := <-ch
+ fmt.Println(prime)
+ ch1 := make(chan int)
+ go filter(ch, ch1, prime)
+ ch = ch1
+ }
+}
+
+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 its output becomes the new value
of ch.
@@ -1258,16 +1259,16 @@ The sieve program can be tweaked to use a pattern common
in this style of programming. Here is a variant version
of generate, from progs/sieve1.go:
-10 func generate() chan int {
-11 ch := make(chan int)
-12 go func(){
-13 for i := 2; ; i++ {
-14 ch <- i
-15 }
-16 }()
-17 return ch
-18 }
+func generate() chan int {
+ ch := make(chan int)
+ go func(){
+ for i := 2; ; i++ {
+ ch <- i
+ }
+ }()
+ return ch
+}
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.
filter:
-21 func filter(in chan int, prime int) chan int {
-22 out := make(chan int)
-23 go func() {
-24 for {
-25 if i := <-in; i % prime != 0 {
-26 out <- i
-27 }
-28 }
-29 }()
-30 return out
-31 }
+func filter(in chan int, prime int) chan int {
+ out := make(chan int)
+ go func() {
+ for {
+ if i := <-in; i % prime != 0 {
+ out <- i
+ }
+ }
+ }()
+ return out
+}
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:
-33 func sieve() chan int {
-34 out := make(chan int)
-35 go func() {
-36 ch := generate()
-37 for {
-38 prime := <-ch
-39 out <- prime
-40 ch = filter(ch, prime)
-41 }
-42 }()
-43 return out
-44 }
+func sieve() chan int {
+ out := make(chan int)
+ go func() {
+ ch := generate()
+ for {
+ prime := <-ch
+ out <- prime
+ ch = filter(ch, prime)
+ }
+ }()
+ return out
+}
main's interface to the prime sieve is a channel of primes:
-46 func main() {
-47 primes := sieve()
-48 for i := 0; i < 100; i++ { // Print the first hundred primes.
-49 fmt.Println(<-primes)
-50 }
-51 }
+func main() {
+ primes := sieve()
+ for i := 0; i < 100; i++ { // Print the first hundred primes.
+ fmt.Println(<-primes)
+ }
+}
Multiplexing
@@ -1334,102 +1335,102 @@ A realistic client-server program is a lot of code, so here is a very simple sub
to illustrate the idea. It starts by defining a request type, which embeds a channel
that will be used for the reply.
-09 type request struct {
-10 a, b int
-11 replyc chan int
-12 }
+type request struct {
+ a, b int
+ replyc chan int
+}
-14 type binOp func(a, b int) int
+
type binOp func(a, b int) int
-16 func run(op binOp, req *request) {
-17 reply := op(req.a, req.b)
-18 req.replyc <- reply
-19 }
+func run(op binOp, req *request) {
+ reply := op(req.a, req.b)
+ req.replyc <- reply
+}
binOp to be a function taking two integers and
+The type declaration makes binOp represent a function taking two integers and
returning a third.
server routine loops forever, receiving requests and, to avoid blocking due to
a long-running operation, starting a goroutine to do the actual work.
-21 func server(op binOp, service chan *request) {
-22 for {
-23 req := <-service
-24 go run(op, req) // don't wait for it
-25 }
-26 }
+func server(op binOp, service chan *request) {
+ for {
+ req := <-service
+ go run(op, req) // don't wait for it
+ }
+}
-28 func startServer(op binOp) chan *request {
-29 req := make(chan *request)
-30 go server(op, req)
-31 return req
-32 }
+func startServer(op binOp) chan *request {
+ req := make(chan *request)
+ go server(op, req)
+ return req
+}
N requests without waiting for the replies. Only after all the requests are sent
does it check the results.
-34 func main() {
-35 adder := startServer(func(a, b int) int { return a + b })
-36 const N = 100
-37 var reqs [N]request
-38 for i := 0; i < N; i++ {
-39 req := &reqs[i]
-40 req.a = i
-41 req.b = i + N
-42 req.replyc = make(chan int)
-43 adder <- req
-44 }
-45 for i := N-1; i >= 0; i-- { // doesn't matter what order
-46 if <-reqs[i].replyc != N + 2*i {
-47 fmt.Println("fail at", i)
-48 }
-49 }
-50 fmt.Println("done")
-51 }
+func main() {
+ adder := startServer(func(a, b int) int { return a + b })
+ const N = 100
+ var reqs [N]request
+ for i := 0; i < N; i++ {
+ req := &reqs[i]
+ req.a = i
+ req.b = i + N
+ req.replyc = make(chan int)
+ adder <- req
+ }
+ for i := N-1; i >= 0; i-- { // doesn't matter what order
+ if <-reqs[i].replyc != N + 2*i {
+ fmt.Println("fail at", i)
+ }
+ }
+ fmt.Println("done")
+}
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:
-32 func startServer(op binOp) (service chan *request, quit chan bool) {
-33 service = make(chan *request)
-34 quit = make(chan bool)
-35 go server(op, service, quit)
-36 return service, quit
-37 }
+func startServer(op binOp) (service chan *request, quit chan bool) {
+ service = make(chan *request)
+ quit = make(chan bool)
+ go server(op, service, quit)
+ return service, quit
+}
server function, which uses it like this:
-21 func server(op binOp, service chan *request, quit chan bool) {
-22 for {
-23 select {
-24 case req := <-service:
-25 go run(op, req) // don't wait for it
-26 case <-quit:
-27 return
-28 }
-29 }
-30 }
+func server(op binOp, service chan *request, quit chan bool) {
+ for {
+ select {
+ case req := <-service:
+ go run(op, req) // don't wait for it
+ case <-quit:
+ return
+ }
+ }
+}
server, the select statement chooses which of the multiple communications
@@ -1442,12 +1443,12 @@ returns, terminating its execution.
All that's left is to strobe the quit channel
at the end of main:
-40 adder, quit := startServer(func(a, b int) int { return a + b })
+ adder, quit := startServer(func(a, b int) int { return a + b })
...
-
-55 quit <- true
+
quit <- true
$ 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.
@@ -601,9 +599,7 @@ as we saw with "rot13". The type "file.File" implements "reader"; it could also
implement a "writer", or any other interface built from its methods that
fits the current situation. Consider the empty interface
-
type Empty interface {}
-
Every type implements the empty interface, which makes it
useful for things like containers.
@@ -618,17 +614,17 @@ same interface variable.
As an example, consider this simple sort algorithm taken from "progs/sort.go":
---PROG progs/sort.go /func.Sort/ /^}/
+!src progs/sort.go /func.Sort/ /^}/
The code needs only three methods, which we wrap into sort's "Interface":
---PROG progs/sort.go /interface/ /^}/
+!src progs/sort.go /interface/ /^}/
We can apply "Sort" to any type that implements "Len", "Less", and "Swap".
The "sort" package includes the necessary methods to allow sorting of
arrays of integers, strings, etc.; here's the code for arrays of "int"
---PROG progs/sort.go /type.*IntSlice/ /Swap/
+!src progs/sort.go /type.*IntSlice/ /Swap/
Here we see methods defined for non-"struct" types. You can define methods
for any type you define and name in your package.
@@ -637,12 +633,12 @@ And now a routine to test it out, from "progs/sortmain.go". This
uses a function in the "sort" package, omitted here for brevity,
to test that the result is sorted.
---PROG progs/sortmain.go /func.ints/ /^}/
+!src progs/sortmain.go /func.ints/ /^}/
If we have a new type we want to be able to sort, all we need to do is
to implement the three methods for that type, like this:
---PROG progs/sortmain.go /type.day/ /Swap/
+!src progs/sortmain.go /type.day/ /Swap/
Printing
@@ -675,7 +671,7 @@ argument. It's easier in many cases in Go. Instead of "%llud" you
can just say "%d"; "Printf" knows the size and signedness of the
integer and can do the right thing for you. The snippet
---PROG progs/print.go 'NR==10' 'NR==11'
+!src progs/print.go 10 11
prints
@@ -684,7 +680,7 @@ prints
In fact, if you're lazy the format "%v" will print, in a simple
appropriate style, any value, even an array or structure. The output of
---PROG progs/print.go 'NR==14' 'NR==20'
+!src progs/print.go 14 20
is
@@ -697,7 +693,7 @@ of "%v" while "Println" inserts spaces between arguments
and adds a newline. The output of each of these two lines is identical
to that of the "Printf" call above.
---PROG progs/print.go 'NR==21' 'NR==22'
+!src progs/print.go 21 22
If you have your own type you'd like "Printf" or "Print" to format,
just give it a "String" method that returns a string. The print
@@ -705,7 +701,7 @@ routines will examine the value to inquire whether it implements
the method and if so, use it rather than some other formatting.
Here's a simple example.
---PROG progs/print_string.go 'NR==9' END
+!src progs/print_string.go 9 $
Since "*testType" has a "String" method, the
default formatter for that type will use it and produce the output
@@ -803,7 +799,7 @@ coordinates the communication; as with maps and slices, use
Here is the first function in "progs/sieve.go":
---PROG progs/sieve.go /Send/ /^}/
+!src progs/sieve.go /Send/ /^}/
The "generate" function sends the sequence 2, 3, 4, 5, ... to its
argument channel, "ch", using the binary communications operator "<-".
@@ -815,7 +811,7 @@ channel, and a prime number. It copies values from the input to the
output, discarding anything divisible by the prime. The unary communications
operator "<-" (receive) retrieves the next value on the channel.
---PROG progs/sieve.go /Copy.the/ /^}/
+!src progs/sieve.go /Copy.the/ /^}/
The generator and filters execute concurrently. Go has
its own model of process/threads/light-weight processes/coroutines,
@@ -838,9 +834,9 @@ on which it can report back:
Back to our prime sieve. Here's how the sieve pipeline is stitched
together:
---PROG progs/sieve.go /func.main/ /^}/
+!src progs/sieve.go /func.main/ /^}/
-Line 29 creates the initial channel to pass to "generate", which it
+The first line of "main" creates the initial channel to pass to "generate", which it
then starts up. As each prime pops out of the channel, a new "filter"
is added to the pipeline and its output becomes the new value
of "ch".
@@ -849,30 +845,30 @@ The sieve program can be tweaked to use a pattern common
in this style of programming. Here is a variant version
of "generate", from "progs/sieve1.go":
---PROG progs/sieve1.go /func.generate/ /^}/
+!src progs/sieve1.go /func.generate/ /^}/
This version does all the setup internally. It creates the output
channel, launches a goroutine running a function literal, and
returns the channel to the caller. It is a factory for concurrent
execution, starting the goroutine and returning its connection.
-The function literal notation (lines 12-16) allows us to construct an
+The function literal notation used in the "go" statement allows us to construct an
anonymous function and invoke it on the spot. Notice that the local
variable "ch" is available to the function literal and lives on even
after "generate" returns.
The same change can be made to "filter":
---PROG progs/sieve1.go /func.filter/ /^}/
+!src progs/sieve1.go /func.filter/ /^}/
The "sieve" function's main loop becomes simpler and clearer as a
result, and while we're at it let's turn it into a factory too:
---PROG progs/sieve1.go /func.sieve/ /^}/
+!src progs/sieve1.go /func.sieve/ /^}/
Now "main"'s interface to the prime sieve is a channel of primes:
---PROG progs/sieve1.go /func.main/ /^}/
+!src progs/sieve1.go /func.main/ /^}/
Multiplexing
----
@@ -884,41 +880,41 @@ A realistic client-server program is a lot of code, so here is a very simple sub
to illustrate the idea. It starts by defining a "request" type, which embeds a channel
that will be used for the reply.
---PROG progs/server.go /type.request/ /^}/
+!src progs/server.go /type.request/ /^}/
The server will be trivial: it will do simple binary operations on integers. Here's the
code that invokes the operation and responds to the request:
---PROG progs/server.go /type.binOp/ /^}/
+!src progs/server.go /type.binOp/ /^}/
-Line 14 defines the name "binOp" to be a function taking two integers and
+The type declaration makes "binOp" represent a function taking two integers and
returning a third.
The "server" routine loops forever, receiving requests and, to avoid blocking due to
a long-running operation, starting a goroutine to do the actual work.
---PROG progs/server.go /func.server/ /^}/
+!src progs/server.go /func.server/ /^}/
We construct a server in a familiar way, starting it and returning a channel
connected to it:
---PROG progs/server.go /func.startServer/ /^}/
+!src progs/server.go /func.startServer/ /^}/
Here's a simple test. It starts a server with an addition operator and sends out
"N" requests without waiting for the replies. Only after all the requests are sent
does it check the results.
---PROG progs/server.go /func.main/ /^}/
+!src progs/server.go /func.main/ /^}/
One annoyance with this program is that it doesn't shut down the server cleanly; when "main" returns
there are a number of lingering goroutines blocked on communication. To solve this,
we can provide a second, "quit" channel to the server:
---PROG progs/server1.go /func.startServer/ /^}/
+!src progs/server1.go /func.startServer/ /^}/
It passes the quit channel to the "server" function, which uses it like this:
---PROG progs/server1.go /func.server/ /^}/
+!src progs/server1.go /func.server/ /^}/
Inside "server", the "select" statement chooses which of the multiple communications
listed by its cases can proceed. If all are blocked, it waits until one can proceed; if
@@ -930,9 +926,9 @@ returns, terminating its execution.
All that's left is to strobe the "quit" channel
at the end of main:
---PROG progs/server1.go /adder,.quit/
+!src progs/server1.go /adder,.quit/
...
---PROG progs/server1.go /quit....true/
+!src progs/server1.go /quit....true/
There's a lot more to Go programming and concurrent programming in general but this
quick tour should give you some of the basics.
diff --git a/doc/htmlgen.go b/doc/htmlgen.go
index 3a8feb8bc..5318a07dc 100644
--- a/doc/htmlgen.go
+++ b/doc/htmlgen.go
@@ -2,46 +2,80 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Process plain text into HTML.
+// If --html is set, process plain text into HTML.
// - h2's are made from lines followed by a line "----\n"
-// - tab-indented blocks become blocks
+// - tab-indented blocks become
blocks with the first tab deleted
// - blank lines become
tags)
// - "quoted strings" become
quoted strings
+// Lines beginning !src define pieces of program source to be
+// extracted from other files and injected as blocks.
+// The syntax is simple: 1, 2, or 3 space-separated arguments:
+//
+// Whole file:
+// !src foo.go
+// One line (here the signature of main):
+// !src foo.go /^func.main/
+// Block of text, determined by start and end (here the body of main):
+// !src foo.go /^func.main/ /^}/
+//
+// Patterns can be /regular.expression/, a decimal number, or $
+// to signify the end of the file.
+// TODO: the regular expression cannot contain spaces; does this matter?
+
package main
import (
"bufio"
"bytes"
+ "flag"
+ "fmt"
+ "io/ioutil"
"log"
"os"
+ "regexp"
+ "strconv"
+ "strings"
+ "template"
)
var (
- lines = make([][]byte, 0, 2000) // probably big enough; grows if not
+ html = flag.Bool("html", true, "process text into HTML")
+)
+
+var (
+ // lines holds the input and is reworked in place during processing.
+ lines = make([][]byte, 0, 20000)
empty = []byte("")
newline = []byte("\n")
tab = []byte("\t")
quote = []byte(`"`)
- indent = []byte{' ', ' ', ' ', ' '}
+ indent = []byte(" ")
sectionMarker = []byte("----\n")
preStart = []byte("")
preEnd = []byte("\n")
pp = []byte("", line)))
+ }
+ for _, l := range prog {
+ nlines = append(nlines, htmlEscape(l))
+ }
+ if *html {
+ nlines = append(nlines, preEnd)
+ }
+ } else {
+ nlines = append(nlines, line)
+ }
+ }
+ lines = nlines
+}
+
+// srcCommand processes one !src invocation.
+func srcCommand(command string) [][]byte {
+ // TODO: quoted args so we can have 'a b'?
+ args := strings.Fields(command)
+ if len(args) == 0 || len(args) > 3 {
+ log.Fatal("bad syntax for src command: %s", command)
+ }
+ file := args[0]
+ lines := bytes.SplitAfter(readFile(file), newline)
+ // File plus zero args: whole file:
+ // !src file.go
+ if len(args) == 1 {
+ return lines
+ }
+ start := match(file, 0, lines, string(args[1]))
+ // File plus one arg: one line:
+ // !src file.go /foo/
+ if len(args) == 2 {
+ return [][]byte{lines[start]}
+ }
+ // File plus two args: range:
+ // !src file.go /foo/ /^}/
+ end := match(file, start, lines, string(args[2]))
+ return lines[start : end+1] // +1 to include matched line.
+}
+
+// htmlEscape makes sure input is HTML clean, if necessary.
+func htmlEscape(input []byte) []byte {
+ if !*html || bytes.IndexAny(input, `&"<>`) < 0 {
+ return input
+ }
+ var b bytes.Buffer
+ template.HTMLEscape(&b, input)
+ return b.Bytes()
+}
+
+// readFile reads and returns a file as part of !src processing.
+func readFile(name string) []byte {
+ file, err := ioutil.ReadFile(name)
+ if err != nil {
+ log.Fatal(err)
+ }
+ return file
+}
+
+// match identifies the input line that matches the pattern in a !src invocation.
+// If start>0, match lines starting there rather than at the beginning.
+func match(file string, start int, lines [][]byte, pattern string) int {
+ // $ matches the end of the file.
+ if pattern == "$" {
+ return len(lines) - 1
+ }
+ // Number matches the line.
+ if i, err := strconv.Atoi(pattern); err == nil {
+ return i - 1 // Lines are 1-indexed.
+ }
+ // /regexp/ matches the line that matches the regexp.
+ if len(pattern) > 2 && pattern[0] == '/' && pattern[len(pattern)-1] == '/' {
+ re, err := regexp.Compile(pattern[1 : len(pattern)-1])
+ if err != nil {
+ log.Fatal(err)
+ }
+ for i := start; i < len(lines); i++ {
+ if re.Match(lines[i]) {
+ return i
+ }
+ }
+ log.Fatalf("%s: no match for %s", file, pattern)
+ }
+ log.Fatalf("unrecognized pattern: %s", pattern)
+ return 0
+}
+
+// coalesce combines lines. Each time prefix is found on a line,
+// it calls fold and replaces the line with return value from fold.
func coalesce(prefix []byte, fold func(i int) (n int, line []byte)) {
j := 0 // output line number goes up by one each loop
for i := 0; i < len(lines); {
@@ -82,7 +213,7 @@ func coalesce(prefix []byte, fold func(i int) (n int, line []byte)) {
lines = lines[0:j]
}
-// return the block as a single slice
+// foldPre returns the
block as a single slice.
func foldPre(i int) (n int, line []byte) {
buf := new(bytes.Buffer)
for i < len(lines) {
@@ -96,7 +227,7 @@ func foldPre(i int) (n int, line []byte) {
return n, buf.Bytes()
}
-// return the tab-indented block as a single -bounded slice
+// foldTabs returns the tab-indented block as a single
-bounded slice.
func foldTabs(i int) (n int, line []byte) {
buf := new(bytes.Buffer)
buf.WriteString("\n")
@@ -104,7 +235,7 @@ func foldTabs(i int) (n int, line []byte) {
if !bytes.HasPrefix(lines[i], tab) {
break
}
- buf.Write(lines[i])
+ buf.Write(lines[i][1:]) // delete leading tab.
n++
i++
}
@@ -112,6 +243,7 @@ func foldTabs(i int) (n int, line []byte) {
return n, buf.Bytes()
}
+// headings turns sections into HTML sections.
func headings() {
b := bufio.NewWriter(os.Stdout)
for i, l := range lines {
@@ -123,6 +255,7 @@ func headings() {
b.Flush()
}
+// paragraphs turns blank lines into paragraph marks.
func paragraphs() {
for i, l := range lines {
if bytes.Equal(l, newline) {
@@ -131,12 +264,14 @@ func paragraphs() {
}
}
+// quotes turns "x" in the file into x.
func quotes() {
for i, l := range lines {
lines[i] = codeQuotes(l)
}
}
+// quotes turns "x" in the line into x.
func codeQuotes(l []byte) []byte {
if bytes.HasPrefix(l, preStart) {
return l
@@ -162,7 +297,7 @@ func codeQuotes(l []byte) []byte {
return buf.Bytes()
}
-// drop trailing newline
+// trim drops the trailing newline, if present.
func trim(l []byte) []byte {
n := len(l)
if n > 0 && l[n-1] == '\n' {
@@ -171,7 +306,7 @@ func trim(l []byte) []byte {
return l
}
-// expand tabs to spaces. don't worry about columns.
+// expandTabs expands tabs to spaces. It doesn't worry about columns.
func expandTabs(l []byte) []byte {
return bytes.Replace(l, tab, indent, -1)
}
diff --git a/doc/install.html b/doc/install.html
index 2256123ec..a1bc89982 100644
--- a/doc/install.html
+++ b/doc/install.html
@@ -81,8 +81,8 @@ To build it, you need these programs installed:
On Ubuntu/Debian, use On Ubuntu/Debian, use sudo apt-get install bison ed gawk gcc libc6-dev
+sudo apt-get install bison gawk gcc libc6-dev
make. If you want to build 32-bit binaries on a 64-bit system you'll
also need the libc6-dev-i386 package.
"
-
-case $# in
-3)
- if test "$3" = "END" # $2 to end of file
- then
- awk '
- function LINE() { printf("%.2d\t%s\n", NR, $0) }
- BEGIN { printing = 0 }
- '$2' { printing = 1; LINE(); getline }
- printing { if($0 ~ /./) { LINE() } else { print "" } }
- '
- else # $2 through $3
- awk '
- function LINE() { printf("%.2d\t%s\n", NR, $0) }
- BEGIN { printing = 0 }
- '$2' { printing = 1; LINE(); getline }
- '$3' && printing { if(printing) {printing = 0; LINE(); exit} }
- printing { if($0 ~ /./) { LINE() } else { print "" } }
- '
- fi
- ;;
-2) # one line
- awk '
- function LINE() { printf("%.2d\t%s\n", NR, $0) }
- '$2' { LINE(); getline; exit }
- '
- ;;
-1) # whole file
- awk '
- function LINE() { printf("%.2d\t%s\n", NR, $0) }
- { if($0 ~ /./) { LINE() } else { print "" } }
- '
- ;;
-*)
- echo >&2 usage: prog.sh file.go /func.main/ /^}/
-esac <$1 |
-sed '
- s/&/\&/g
- s/"/\"/g
- s/\</g
- s/>/\>/g
-'
-
-echo ''
diff --git a/doc/progs/file_windows.go b/doc/progs/file_windows.go
new file mode 100644
index 000000000..d5e7c00d3
--- /dev/null
+++ b/doc/progs/file_windows.go
@@ -0,0 +1,89 @@
+// Copyright 2009 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package file
+
+import (
+ "os"
+ "syscall"
+)
+
+type File struct {
+ fd syscall.Handle // file descriptor number
+ name string // file name at Open time
+}
+
+func newFile(fd syscall.Handle, name string) *File {
+ if fd < 0 {
+ return nil
+ }
+ return &File{fd, name}
+}
+
+var (
+ Stdin = newFile(syscall.Stdin, "/dev/stdin")
+ Stdout = newFile(syscall.Stdout, "/dev/stdout")
+ Stderr = newFile(syscall.Stderr, "/dev/stderr")
+)
+
+func OpenFile(name string, mode int, perm uint32) (file *File, err os.Error) {
+ r, e := syscall.Open(name, mode, perm)
+ if e != 0 {
+ err = os.Errno(e)
+ }
+ return newFile(r, name), err
+}
+
+const (
+ O_RDONLY = syscall.O_RDONLY
+ O_RDWR = syscall.O_RDWR
+ O_CREATE = syscall.O_CREAT
+ O_TRUNC = syscall.O_TRUNC
+)
+
+func Open(name string) (file *File, err os.Error) {
+ return OpenFile(name, O_RDONLY, 0)
+}
+
+func Create(name string) (file *File, err os.Error) {
+ return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
+}
+
+func (file *File) Close() os.Error {
+ if file == nil {
+ return os.EINVAL
+ }
+ e := syscall.Close(file.fd)
+ file.fd = syscall.InvalidHandle // so it can't be closed again
+ if e != 0 {
+ return os.Errno(e)
+ }
+ return nil
+}
+
+func (file *File) Read(b []byte) (ret int, err os.Error) {
+ if file == nil {
+ return -1, os.EINVAL
+ }
+ r, e := syscall.Read(file.fd, b)
+ if e != 0 {
+ err = os.Errno(e)
+ }
+ return int(r), err
+}
+
+func (file *File) Write(b []byte) (ret int, err os.Error) {
+ if file == nil {
+ return -1, os.EINVAL
+ }
+ r, e := syscall.Write(file.fd, b)
+ if e != 0 {
+ err = os.Errno(e)
+ }
+ return int(r), err
+}
+
+func (file *File) String() string {
+ return file.name
+}
diff --git a/doc/progs/run b/doc/progs/run
index 241e65dfa..81781c9d2 100755
--- a/doc/progs/run
+++ b/doc/progs/run
@@ -14,8 +14,13 @@ fi
rm -f *.$O
+if [ "$GOOS" = "windows" ];then
+ $GC -o file.8 file_windows.go
+else
+ $GC file.go
+fi
+
for i in \
- file.go \
helloworld.go \
helloworld3.go \
echo.go \
diff --git a/lib/codereview/codereview.py b/lib/codereview/codereview.py
index a222919d8..385ac2c06 100644
--- a/lib/codereview/codereview.py
+++ b/lib/codereview/codereview.py
@@ -1316,7 +1316,7 @@ def clpatch_or_undo(ui, repo, clname, opts, mode):
# Create fresh CL and start with patch that would reverse the change.
vers = short(rev.node())
cl = CL("new")
- desc = rev.description()
+ desc = str(rev.description())
if mode == "undo":
cl.desc = (undoHeader % (clname, vers)) + desc + undoFooter
else:
@@ -1352,10 +1352,12 @@ def clpatch_or_undo(ui, repo, clname, opts, mode):
repo[vers].description()
except:
return "local repository is out of date; sync to get %s" % (vers)
- patch, err = portPatch(repo, patch, vers, id)
+ patch1, err = portPatch(repo, patch, vers, id)
if err != "":
- return "codereview issue %s is out of date: %s (%s->%s)" % (clname, err, vers, id)
-
+ if not opts["ignore_hgpatch_failure"]:
+ return "codereview issue %s is out of date: %s (%s->%s)" % (clname, err, vers, id)
+ else:
+ patch = patch1
argv = ["hgpatch"]
if opts["no_incoming"] or mode == "backport":
argv += ["--checksync=false"]
@@ -1369,7 +1371,7 @@ def clpatch_or_undo(ui, repo, clname, opts, mode):
return "hgpatch failed"
cl.local = True
cl.files = out.strip().split()
- if not cl.files:
+ if not cl.files and not opts["ignore_hgpatch_failure"]:
return "codereview issue %s has no changed files" % clname
files = ChangedFiles(ui, repo, [], opts)
extra = Sub(cl.files, files)
@@ -1781,7 +1783,7 @@ def sync(ui, repo, **opts):
err = commands.postincoming(ui, repo, modheads, True, "tip")
if err:
return err
- commands.update(ui, repo)
+ commands.update(ui, repo, rev="default")
sync_changes(ui, repo)
def sync_note(msg):
diff --git a/misc/dashboard/builder/http.go b/misc/dashboard/builder/http.go
index 5e1da0c87..98400c51a 100644
--- a/misc/dashboard/builder/http.go
+++ b/misc/dashboard/builder/http.go
@@ -112,16 +112,15 @@ func packages() (pkgs []string, err os.Error) {
return
}
-// updatePackage sends package build results and info to the dashboard
-func (b *Builder) updatePackage(pkg string, state bool, buildLog, info string, hash string) os.Error {
+// updatePackage sends package build results and info dashboard
+func (b *Builder) updatePackage(pkg string, ok bool, buildLog, info string) os.Error {
return dash("POST", "package", nil, param{
"builder": b.name,
"key": b.key,
"path": pkg,
- "state": strconv.Btoa(state),
+ "ok": strconv.Btoa(ok),
"log": buildLog,
"info": info,
- "go_rev": hash[:12],
})
}
diff --git a/misc/dashboard/builder/main.go b/misc/dashboard/builder/main.go
index 9a714fe79..989965bc4 100644
--- a/misc/dashboard/builder/main.go
+++ b/misc/dashboard/builder/main.go
@@ -60,8 +60,9 @@ var (
)
var (
- goroot string
- releaseRegexp = regexp.MustCompile(`^(release|weekly)\.[0-9\-.]+`)
+ goroot string
+ binaryTagRe = regexp.MustCompile(`^(release\.r|weekly\.)[0-9\-.]+`)
+ releaseRe = regexp.MustCompile(`^release\.r[0-9\-.]+`)
)
func main() {
@@ -161,7 +162,7 @@ func NewBuilder(builder string) (*Builder, os.Error) {
b := &Builder{name: builder}
// get goos/goarch from builder string
- s := strings.Split(builder, "-", 3)
+ s := strings.SplitN(builder, "-", 3)
if len(s) >= 2 {
b.goos, b.goarch = s[0], s[1]
} else {
@@ -177,7 +178,7 @@ func NewBuilder(builder string) (*Builder, os.Error) {
if err != nil {
return nil, fmt.Errorf("readKeys %s (%s): %s", b.name, fn, err)
}
- v := strings.Split(string(c), "\n", -1)
+ v := strings.Split(string(c), "\n")
b.key = v[0]
if len(v) >= 3 {
b.codeUsername, b.codePassword = v[1], v[2]
@@ -200,7 +201,7 @@ func (b *Builder) buildExternal() {
log.Println("hg pull failed:", err)
continue
}
- hash, tag, err := firstTag(releaseRegexp)
+ hash, tag, err := firstTag(releaseRe)
if err != nil {
log.Println(err)
continue
@@ -321,7 +322,7 @@ func (b *Builder) buildHash(hash string) (err os.Error) {
}
// if this is a release, create tgz and upload to google code
- releaseHash, release, err := firstTag(releaseRegexp)
+ releaseHash, release, err := firstTag(binaryTagRe)
if hash == releaseHash {
// clean out build state
err = run(b.envv(), srcDir, "./clean.bash", "--nopkg")
@@ -392,7 +393,7 @@ func (b *Builder) envvWindows() []string {
skip[name] = true
}
for _, kv := range os.Environ() {
- s := strings.Split(kv, "=", 2)
+ s := strings.SplitN(kv, "=", 2)
name := strings.ToUpper(s[0])
switch {
case name == "":
@@ -591,7 +592,7 @@ func fullHash(rev string) (hash string, err os.Error) {
if s == "" {
return "", fmt.Errorf("cannot find revision")
}
- if len(s) != 20 {
+ if len(s) != 40 {
return "", fmt.Errorf("hg returned invalid hash " + s)
}
return s, nil
@@ -602,7 +603,7 @@ var revisionRe = regexp.MustCompile(`^([^ ]+) +[0-9]+:([0-9a-f]+)$`)
// firstTag returns the hash and tag of the most recent tag matching re.
func firstTag(re *regexp.Regexp) (hash string, tag string, err os.Error) {
o, _, err := runLog(nil, "", goroot, "hg", "tags")
- for _, l := range strings.Split(o, "\n", -1) {
+ for _, l := range strings.Split(o, "\n") {
if l == "" {
continue
}
@@ -615,7 +616,7 @@ func firstTag(re *regexp.Regexp) (hash string, tag string, err os.Error) {
continue
}
tag = s[1]
- hash, err = fullHash(s[3])
+ hash, err = fullHash(s[2])
return
}
err = os.NewError("no matching tag found")
diff --git a/misc/dashboard/builder/package.go b/misc/dashboard/builder/package.go
index ee65d7669..b6674428d 100644
--- a/misc/dashboard/builder/package.go
+++ b/misc/dashboard/builder/package.go
@@ -10,35 +10,47 @@ import (
"go/token"
"log"
"os"
- "path"
+ "path/filepath"
+ "strings"
)
+const MaxCommentLength = 500 // App Engine won't store more in a StringProperty.
+
func (b *Builder) buildPackages(workpath string, hash string) os.Error {
pkgs, err := packages()
if err != nil {
return err
}
for _, p := range pkgs {
- goroot := path.Join(workpath, "go")
- goinstall := path.Join(goroot, "bin", "goinstall")
+ goroot := filepath.Join(workpath, "go")
+ gobin := filepath.Join(goroot, "bin")
+ goinstall := filepath.Join(gobin, "goinstall")
envv := append(b.envv(), "GOROOT="+goroot)
+ // add GOBIN to path
+ for i, v := range envv {
+ if strings.HasPrefix(v, "PATH=") {
+ p := filepath.SplitList(v[5:])
+ p = append([]string{gobin}, p...)
+ s := strings.Join(p, string(filepath.ListSeparator))
+ envv[i] = "PATH=" + s
+ }
+ }
+
// goinstall
- buildLog, code, err := runLog(envv, "", goroot, goinstall, p)
+ buildLog, code, err := runLog(envv, "", goroot, goinstall, "-log=false", p)
if err != nil {
log.Printf("goinstall %v: %v", p, err)
- continue
}
- built := code != 0
// get doc comment from package source
- info, err := packageComment(p, path.Join(goroot, "pkg", p))
+ info, err := packageComment(p, filepath.Join(goroot, "src", "pkg", p))
if err != nil {
- log.Printf("goinstall %v: %v", p, err)
+ log.Printf("packageComment %v: %v", p, err)
}
// update dashboard with build state + info
- err = b.updatePackage(p, built, buildLog, info, hash)
+ err = b.updatePackage(p, code == 0, buildLog, info)
if err != nil {
log.Printf("updatePackage %v: %v", p, err)
}
@@ -46,9 +58,15 @@ func (b *Builder) buildPackages(workpath string, hash string) os.Error {
return nil
}
+func isGoFile(fi *os.FileInfo) bool {
+ return fi.IsRegular() && // exclude directories
+ !strings.HasPrefix(fi.Name, ".") && // ignore .files
+ filepath.Ext(fi.Name) == ".go"
+}
+
func packageComment(pkg, pkgpath string) (info string, err os.Error) {
fset := token.NewFileSet()
- pkgs, err := parser.ParseDir(fset, pkgpath, nil, parser.PackageClauseOnly|parser.ParseComments)
+ pkgs, err := parser.ParseDir(fset, pkgpath, isGoFile, parser.PackageClauseOnly|parser.ParseComments)
if err != nil {
return
}
@@ -62,5 +80,15 @@ func packageComment(pkg, pkgpath string) (info string, err os.Error) {
pdoc := doc.NewPackageDoc(pkgs[name], pkg)
info = pdoc.Doc
}
+ // grab only first paragraph
+ if parts := strings.SplitN(info, "\n\n", 2); len(parts) > 1 {
+ info = parts[0]
+ }
+ // replace newlines with spaces
+ info = strings.Replace(info, "\n", " ", -1)
+ // truncate
+ if len(info) > MaxCommentLength {
+ info = info[:MaxCommentLength]
+ }
return
}
diff --git a/misc/dashboard/godashboard/auth.py b/misc/dashboard/godashboard/auth.py
new file mode 100644
index 000000000..73a54c0d4
--- /dev/null
+++ b/misc/dashboard/godashboard/auth.py
@@ -0,0 +1,13 @@
+# 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.
+
+import hmac
+
+# local imports
+import key
+
+def auth(req):
+ k = req.get('key')
+ return k == hmac.new(key.accessKey, req.get('builder')).hexdigest() or k == key.accessKey
+
diff --git a/misc/dashboard/godashboard/gobuild.py b/misc/dashboard/godashboard/gobuild.py
index 5678f2e1b..685dc83a9 100644
--- a/misc/dashboard/godashboard/gobuild.py
+++ b/misc/dashboard/godashboard/gobuild.py
@@ -14,14 +14,13 @@ from google.appengine.ext.webapp import template
from google.appengine.ext.webapp.util import run_wsgi_app
import datetime
import hashlib
-import hmac
import logging
import os
import re
import bz2
# local imports
-import key
+from auth import auth
import const
# The majority of our state are commit objects. One of these exists for each of
@@ -142,10 +141,6 @@ class DashboardHandler(webapp.RequestHandler):
simplejson.dump(obj, self.response.out)
return
-def auth(req):
- k = req.get('key')
- return k == hmac.new(key.accessKey, req.get('builder')).hexdigest() or k == key.accessKey
-
# Todo serves /todo. It tells the builder which commits need to be built.
class Todo(DashboardHandler):
def get(self):
diff --git a/misc/dashboard/godashboard/index.yaml b/misc/dashboard/godashboard/index.yaml
index 4a00c4a6f..f39299d5d 100644
--- a/misc/dashboard/godashboard/index.yaml
+++ b/misc/dashboard/godashboard/index.yaml
@@ -49,4 +49,3 @@ indexes:
# manually, move them above the marker line. The index.yaml file is
# automatically uploaded to the admin console when you next deploy
# your application using appcfg.py.
-
diff --git a/misc/dashboard/godashboard/package.html b/misc/dashboard/godashboard/package.html
index 9332b5a79..043080b5b 100644
--- a/misc/dashboard/godashboard/package.html
+++ b/misc/dashboard/godashboard/package.html
@@ -19,37 +19,43 @@
Packages listed on this page are written by third parties and
may or may not build or be safe to use.
+ An "ok" in the build column indicates that the package is + goinstallable + with the latest + release of Go. +
+ ++ The info column shows the first paragraph from the + package doc comment. +
| last install | count | path | project | ||
|---|---|---|---|---|---|
| last install | count | build | path | info | |
| {{r.last_install|date:"Y-M-d H:i"}} | {{r.count}} | +{% if r.ok %}ok{% else %} {% endif %} | {{r.path}} | -- {% for p in r.project_set %} - {{p.name}} - {{p.descr}} - {% endfor %} - | +{% if r.info %}{{r.info|escape}}{% endif %} |
| last install | count | path | project | ||
|---|---|---|---|---|---|
| last install | count | build | path | info | |
| {{r.last_install|date:"Y-M-d H:i"}} | {{r.count}} | +{% if r.ok %}ok{% else %} {% endif %} | {{r.path}} | -- {% for p in r.project_set %} - {{p.name}} - {{p.descr}} - {% endfor %} - | +{% if r.info %}{{r.info|escape}}{% endif %} |