From f154da9e12608589e8d5f0508f908a0c3e88a1bb Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Thu, 15 Jan 2015 11:54:00 -0700 Subject: Imported Upstream version 1.4 --- doc/code.html | 187 ++++++++++++++++++++++++++++++---------------------------- 1 file changed, 98 insertions(+), 89 deletions(-) (limited to 'doc/code.html') diff --git a/doc/code.html b/doc/code.html index f019306fa..a4638f9ff 100644 --- a/doc/code.html +++ b/doc/code.html @@ -60,37 +60,35 @@ To give you an idea of how a workspace looks in practice, here's an example: 
 bin/
-    streak                         # command executable
-    todo                           # command executable
+    hello                          # command executable
+    outyet                         # command executable
 pkg/
     linux_amd64/
-        code.google.com/p/goauth2/
-            oauth.a                # package object
-        github.com/nf/todo/
-            task.a                 # package object
+        github.com/golang/example/
+            stringutil.a           # package object
 src/
-    code.google.com/p/goauth2/
-        .hg/                       # mercurial repository metadata
-        oauth/
-            oauth.go               # package source
-            oauth_test.go          # test source
-    github.com/nf/
-        streak/
-            .git/                  # git repository metadata
-            oauth.go               # command source
-            streak.go              # command source
-        todo/
-            .git/                  # git repository metadata
-            task/
-                task.go            # package source
-            todo.go                # command source
+    github.com/golang/example/
+        .git/                      # Git repository metadata
+	hello/
+	    hello.go               # command source
+	outyet/
+	    main.go                # command source
+	    main_test.go           # test source
+	stringutil/
+	    reverse.go             # package source
+	    reverse_test.go        # test source

-This workspace contains three repositories (goauth2, -streak, and todo) comprising two commands -(streak and todo) and two libraries -(oauth and task). +This workspace contains one repository (example) +comprising two commands (hello and outyet) +and one library (stringutil). +

+ +

+A typical workspace would contain many source repositories containing many +packages and commands. Most Go programmers keep all their Go source code +and dependencies in a single workspace.

@@ -277,29 +275,29 @@ Let's write a library and use it from the hello program.

Again, the first step is to choose a package path (we'll use -github.com/user/newmath) and create the package directory: +github.com/user/stringutil) and create the package directory: 

-$ mkdir $GOPATH/src/github.com/user/newmath
+$ mkdir $GOPATH/src/github.com/user/stringutil

-Next, create a file named sqrt.go in that directory with the +Next, create a file named reverse.go in that directory with the following contents. 

-// Package newmath is a trivial example package.
-package newmath
-
-// Sqrt returns an approximation to the square root of x.
-func Sqrt(x float64) float64 {
-	z := 1.0
-	for i := 0; i < 1000; i++ {
-		z -= (z*z - x) / (2 * z)
+// Package stringutil contains utility functions for working with strings.
+package stringutil
+
+// Reverse returns its argument string reversed rune-wise left to right.
+func Reverse(s string) string {
+	r := []rune(s)
+	for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
+		r[i], r[j] = r[j], r[i]
 	}
-	return z
+	return string(r)
 }
@@ -308,7 +306,7 @@ Now, test that the package compiles with go build: 

-$ go build github.com/user/newmath
+$ go build github.com/user/stringutil

@@ -326,7 +324,7 @@ directory of the workspace.

-After confirming that the newmath package builds, +After confirming that the stringutil package builds, modify your original hello.go (which is in $GOPATH/src/github.com/user/hello) to use it:

@@ -337,18 +335,18 @@ package main import ( "fmt" - "github.com/user/newmath" + "github.com/user/stringutil" ) func main() { - fmt.Printf("Hello, world. Sqrt(2) = %v\n", newmath.Sqrt(2)) + fmt.Printf(stringutil.Reverse("!oG ,olleH")) }

Whenever the go tool installs a package or binary, it also -installs whatever dependencies it has. So when you install the hello -program +installs whatever dependencies it has. +So when you install the hello program 

@@ -356,16 +354,16 @@ $ go install github.com/user/hello

-the newmath package will be installed as well, automatically. +the stringutil package will be installed as well, automatically.

-Running the new version of the program, you should see some numerical output: +Running the new version of the program, you should see a new, reversed message: 

 $ hello
-Hello, world.  Sqrt(2) = 1.414213562373095
+Hello, Go!

@@ -374,22 +372,22 @@ After the steps above, your workspace should look like this: 

 bin/
-    hello              # command executable
+    hello                 # command executable
 pkg/
-    linux_amd64/       # this will reflect your OS and architecture
+    linux_amd64/          # this will reflect your OS and architecture
         github.com/user/
-            newmath.a  # package object
+            stringutil.a  # package object
 src/
     github.com/user/
         hello/
-            hello.go   # command source
-        newmath/
-            sqrt.go    # package source
+            hello.go      # command source
+        stringutil/
+            reverse.go    # package source

-Note that go install placed the newmath.a object in a -directory inside pkg/linux_amd64 that mirrors its source +Note that go install placed the stringutil.a object +in a directory inside pkg/linux_amd64 that mirrors its source directory. This is so that future invocations of the go tool can find the package object and avoid recompiling the package unnecessarily. @@ -457,20 +455,29 @@ if the function calls a failure function such as t.Error or

-Add a test to the newmath package by creating the file -$GOPATH/src/github.com/user/newmath/sqrt_test.go containing the -following Go code. +Add a test to the stringutil package by creating the file +$GOPATH/src/github.com/user/stringutil/reverse_test.go containing +the following Go code. 

-package newmath
+package stringutil
 
 import "testing"
 
-func TestSqrt(t *testing.T) {
-	const in, out = 4, 2
-	if x := Sqrt(in); x != out {
-		t.Errorf("Sqrt(%v) = %v, want %v", in, x, out)
+func TestReverse(t *testing.T) {
+	cases := []struct {
+		in, want string
+	}{
+		{"Hello, world", "dlrow ,olleH"},
+		{"Hello, 世界", "界世 ,olleH"},
+		{"", ""},
+	}
+	for _, c := range cases {
+		got := Reverse(c.in)
+		if got != c.want {
+			t.Errorf("Reverse(%q) == %q, want %q", c.in, got, c.want)
+		}
 	}
 }
@@ -480,8 +487,8 @@ Then run the test with go test: 

-$ go test github.com/user/newmath
-ok  	github.com/user/newmath 0.165s
+$ go test github.com/user/stringutil
+ok  	github.com/user/stringutil 0.165s

@@ -491,7 +498,7 @@ directory, you can omit the package path: 

 $ go test
-ok  	github.com/user/newmath 0.165s
+ok  	github.com/user/stringutil 0.165s

@@ -507,16 +514,16 @@ An import path can describe how to obtain the package source code using a revision control system such as Git or Mercurial. The go tool uses this property to automatically fetch packages from remote repositories. For instance, the examples described in this document are also kept in a -Mercurial repository hosted at Google Code, -code.google.com/p/go.example. +Git repository hosted at GitHub +github.com/golang/example. If you include the repository URL in the package's import path, go get will fetch, build, and install it automatically: 

-$ go get code.google.com/p/go.example/hello
+$ go get github.com/golang/example/hello
 $ $GOPATH/bin/hello
-Hello, world.  Sqrt(2) = 1.414213562373095
+Hello, Go examples!

@@ -533,43 +540,45 @@ tree should now look like this: 

 bin/
-    hello                 # command executable
+    hello                           # command executable
 pkg/
     linux_amd64/
-        code.google.com/p/go.example/
-            newmath.a     # package object
+        github.com/golang/example/
+            stringutil.a            # package object
         github.com/user/
-            newmath.a     # package object
+            stringutil.a            # package object
 src/
-    code.google.com/p/go.example/
+    github.com/golang/example/
+	.git/                       # Git repository metadata
         hello/
-            hello.go      # command source
-        newmath/
-            sqrt.go       # package source
-            sqrt_test.go  # test source
+            hello.go                # command source
+        stringutil/
+            reverse.go              # package source
+            reverse_test.go         # test source
     github.com/user/
         hello/
-            hello.go      # command source
-        newmath/
-            sqrt.go       # package source
-            sqrt_test.go  # test source
+            hello.go                # command source
+        stringutil/
+            reverse.go              # package source
+            reverse_test.go         # test source

-The hello command hosted at Google Code depends on the -newmath package within the same repository. The imports in -hello.go file use the same import path convention, so the go -get command is able to locate and install the dependent package, too. +The hello command hosted at GitHub depends on the +stringutil package within the same repository. The imports in +hello.go file use the same import path convention, so the +go get command is able to locate and install the dependent +package, too. 

-import "code.google.com/p/go.example/newmath"
+import "github.com/golang/example/stringutil"

This convention is the easiest way to make your Go packages available for others to use. -The Go Wiki +The Go Wiki and godoc.org provide lists of external Go projects.

@@ -618,5 +627,5 @@ The official mailing list for discussion of the Go language is

Report bugs using the -Go issue tracker. +Go issue tracker.

-- cgit v1.2.3