doc: add The Laws of Reflection article

Originally published on The Go Programming Language Blog, September 6, 2011.

http://blog.golang.org/2011/09/laws-of-reflection.html

Update #2547

R=golang-dev, r, adg
CC=golang-dev
https://golang.org/cl/5689054

doc/Makefile

@@ -6,6 +6,7 @@ HTML=\
 	articles/defer_panic_recover.html\
 	articles/error_handling.html\
 	articles/slices_usage_and_internals.html\
+	articles/laws_of_reflection.html\
 	effective_go.html\
 	go1.html\
 

doc/docs.html

@@ -91,7 +91,7 @@ Guided tours of Go programs.
 <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="http://blog.golang.org/2011/09/laws-of-reflection.html">The Laws of Reflection</a> - the fundamentals of the <a href="/pkg/reflect/">reflect</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="http://blog.golang.org/2011/09/go-imagedraw-package.html">The Go image/draw package</a> - the fundamentals of the <a href="/pkg/image/draw/">image/draw</a> package.</li>
 </ul>
@@ -253,4 +253,3 @@ Go libraries.</p>
 <li><a href="http://go-tour-kr.appspot.com">A Tour of Go</a></li>
 <li><a href="http://code.google.com/p/golang-korea">golang-korea</a> - Go documentation and news.</li>
 </ul>
-

doc/progs/interface.go

+package main
+
+import (
+	"bufio"
+	"bytes"
+	"io"
+	"os"
+)
+
+type MyInt int
+
+var i int
+var j MyInt
+
+// STOP OMIT
+
+// Reader is the interface that wraps the basic Read method.
+type Reader interface {
+	Read(p []byte) (n int, err error)
+}
+
+// Writer is the interface that wraps the basic Write method.
+type Writer interface {
+	Write(p []byte) (n int, err error)
+}
+
+// STOP OMIT
+
+func readers() { // OMIT
+	var r io.Reader
+	r = os.Stdin
+	r = bufio.NewReader(r)
+	r = new(bytes.Buffer)
+	// and so on
+	// STOP OMIT
+}
+
+func typeAssertions() (interface{}, error) { // OMIT
+	var r io.Reader
+	tty, err := os.OpenFile("/dev/tty", os.O_RDWR, 0)
+	if err != nil {
+		return nil, err
+	}
+	r = tty
+	// STOP OMIT
+	var w io.Writer
+	w = r.(io.Writer)
+	// STOP OMIT
+	var empty interface{}
+	empty = w
+	// STOP OMIT
+	return empty, err
+}
+
+func main() {
+}

doc/progs/interface2.go

+package main
+
+import (
+	"fmt"
+	"reflect"
+)
+
+func main() {
+	var x float64 = 3.4
+	fmt.Println("type:", reflect.TypeOf(x))
+	// STOP OMIT
+	// TODO(proppy): test output OMIT
+}
+
+// STOP main OMIT
+
+func f1() {
+	// START f1 OMIT
+	var x float64 = 3.4
+	v := reflect.ValueOf(x)
+	fmt.Println("type:", v.Type())
+	fmt.Println("kind is float64:", v.Kind() == reflect.Float64)
+	fmt.Println("value:", v.Float())
+	// STOP OMIT
+}
+
+func f2() {
+	// START f2 OMIT
+	var x uint8 = 'x'
+	v := reflect.ValueOf(x)
+	fmt.Println("type:", v.Type())                            // uint8.
+	fmt.Println("kind is uint8: ", v.Kind() == reflect.Uint8) // true.
+	x = uint8(v.Uint())                                       // v.Uint returns a uint64.
+	// STOP OMIT
+}
+
+func f3() {
+	// START f3 OMIT
+	type MyInt int
+	var x MyInt = 7
+	v := reflect.ValueOf(x)
+	// START f3b OMIT
+	y := v.Interface().(float64) // y will have type float64.
+	fmt.Println(y)
+	// START f3c OMIT
+	fmt.Println(v.Interface())
+	// START f3d OMIT
+	fmt.Printf("value is %7.1e\n", v.Interface())
+	// STOP OMIT
+}
+
+func f4() {
+	// START f4 OMIT
+	var x float64 = 3.4
+	v := reflect.ValueOf(x)
+	v.SetFloat(7.1) // Error: will panic.
+	// STOP OMIT
+}
+
+func f5() {
+	// START f5 OMIT
+	var x float64 = 3.4
+	v := reflect.ValueOf(x)
+	fmt.Println("settability of v:", v.CanSet())
+	// STOP OMIT
+}
+
+func f6() {
+	// START f6 OMIT
+	var x float64 = 3.4
+	v := reflect.ValueOf(x)
+	// START f6b OMIT
+	v.SetFloat(7.1)
+	// STOP OMIT
+}
+
+func f7() {
+	// START f7 OMIT
+	var x float64 = 3.4
+	p := reflect.ValueOf(&x) // Note: take the address of x.
+	fmt.Println("type of p:", p.Type())
+	fmt.Println("settability of p:", p.CanSet())
+	// START f7b OMIT
+	v := p.Elem()
+	fmt.Println("settability of v:", v.CanSet())
+	// START f7c OMIT
+	v.SetFloat(7.1)
+	fmt.Println(v.Interface())
+	fmt.Println(x)
+	// STOP OMIT
+}
+
+func f8() {
+	// START f8 OMIT
+	type T struct {
+		A int
+		B string
+	}
+	t := T{23, "skidoo"}
+	s := reflect.ValueOf(&t).Elem()
+	typeOfT := s.Type()
+	for i := 0; i < s.NumField(); i++ {
+		f := s.Field(i)
+		fmt.Printf("%d: %s %s = %v\n", i,
+			typeOfT.Field(i).Name, f.Type(), f.Interface())
+	}
+	// START f8b OMIT
+	s.Field(0).SetInt(77)
+	s.Field(1).SetString("Sunset Strip")
+	fmt.Println("t is now", t)
+	// STOP OMIT
+}

src/pkg/reflect/type.go

@@ -12,7 +12,7 @@
 // for that type.
 //
 // See "The Laws of Reflection" for an introduction to reflection in Go:
-// http://blog.golang.org/2011/09/laws-of-reflection.html
+// http://golang.org/doc/articles/laws_of_reflection.html
 package reflect
 
 import (