doc: add Gobs of data article

Originally published on The Go Programming Language Blog, March 24, 2011.

http://blog.golang.org/2011/03/gobs-of-data.html

R=adg
CC=golang-dev
https://golang.org/cl/5834043

doc/Makefile

@@ -10,6 +10,7 @@ RAWHTML=\
 	articles/c_go_cgo.rawhtml\
 	articles/go_concurrency_patterns_timing_out_moving_on.rawhtml\
 	articles/godoc_documenting_go_code.rawhtml\
+	articles/gobs_of_data.rawhtml\
 	articles/image_draw.rawhtml\
 	effective_go.rawhtml\
 	go1.rawhtml\

doc/docs.html

@@ -114,7 +114,7 @@ Guided tours of Go programs.
 <h4>Packages</h4>
 <ul>
 <li><a href="http://blog.golang.org/2011/01/json-and-go.html">JSON and Go</a> - using the <a href="/pkg/encoding/json/">json</a> package.</li>
-<li><a href="http://blog.golang.org/2011/03/gobs-of-data.html">Gobs of data</a> - the design and use of the <a href="/pkg/encoding/gob/">gob</a> package.</li>
+<li><a href="/doc/articles/gobs_of_data.html">Gobs of data</a> - the design and use of the <a href="/pkg/encoding/gob/">gob</a> package.</li>
 <li><a href="/doc/articles/laws_of_reflection.html">The Laws of Reflection</a> - the fundamentals of the <a href="/pkg/reflect/">reflect</a> package.</li>
 <li><a href="http://blog.golang.org/2011/09/go-image-package.html">The Go image package</a> - the fundamentals of the <a href="/pkg/image/">image</a> package.</li>
 <li><a href="/doc/articles/image_draw.html">The Go image/draw package</a> - the fundamentals of the <a href="/pkg/image/draw/">image/draw</a> package.</li>

doc/progs/gobs1.go

+// 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.
+
+package gobs1
+
+type T struct{ X, Y, Z int } // Only exported fields are encoded and decoded.
+var t = T{X: 7, Y: 0, Z: 8}
+
+// STOP OMIT
+
+type U struct{ X, Y *int8 } // Note: pointers to int8s
+var u U
+
+// STOP OMIT
+
+type Node struct {
+	Value       int
+	Left, Right *Node
+}
+
+// STOP OMIT

doc/progs/gobs2.go

+// 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.
+
+package main
+
+import (
+	"bytes"
+	"encoding/gob"
+	"fmt"
+	"log"
+)
+
+type P struct {
+	X, Y, Z int
+	Name    string
+}
+
+type Q struct {
+	X, Y *int32
+	Name string
+}
+
+func main() {
+	// Initialize the encoder and decoder.  Normally enc and dec would be
+	// bound to network connections and the encoder and decoder would
+	// run in different processes.
+	var network bytes.Buffer        // Stand-in for a network connection
+	enc := gob.NewEncoder(&network) // Will write to network.
+	dec := gob.NewDecoder(&network) // Will read from network.
+	// Encode (send) the value.
+	err := enc.Encode(P{3, 4, 5, "Pythagoras"})
+	if err != nil {
+		log.Fatal("encode error:", err)
+	}
+	// Decode (receive) the value.
+	var q Q
+	err = dec.Decode(&q)
+	if err != nil {
+		log.Fatal("decode error:", err)
+	}
+	fmt.Printf("%q: {%d,%d}\n", q.Name, *q.X, *q.Y)
+}

doc/progs/run

@@ -46,7 +46,12 @@ timeout="
 	timeout2
 "
 
-all=$(echo $defer_panic_recover $effective_go $error_handling $law_of_reflection $c_go_cgo $timeout slices go1)
+gobs="
+	gobs1
+	gobs2
+"
+
+all=$(echo $defer_panic_recover $effective_go $error_handling $law_of_reflection $c_go_cgo $timeout $gobs slices go1)
 
 for i in $all; do
 	go build $i.go

src/pkg/encoding/gob/doc.go

@@ -226,7 +226,7 @@ where * signifies zero or more repetitions and the type id of a value must
 be predefined or be defined before the value in the stream.
 
 See "Gobs of data" for a design discussion of the gob wire format:
-http://blog.golang.org/2011/03/gobs-of-data.html
+http://golang.org/doc/articles/gobs_of_data.html
 */
 package gob