code review 5689054: doc: add The Laws of Reflection article

doc/articles/laws_of_reflection.html

 <!--{
         "Title": "The Laws of Reflection"
 }-->
 <!--
   DO NOT EDIT: created by
     tmpltohtml articles/laws_of_reflection.tmpl
 -->
 
 
 <p>
 Reflection in computing is the
 ability of a program to examine its own structure, particularly
 through types; it's a form of metaprogramming. It's also a great
 source of confusion.
 </p>
 
 <p>
 In this article we attempt to clarify things by explaining how
-reflection works in Go. Each language&rsquo;s reflection model is
-different (and many languages don&rsquo;t support it at all), but
+reflection works in Go. Each language's reflection model is
+different (and many languages don't support it at all), but
 this article is about Go, so for the rest of this article the word
 "reflection" should be taken to mean "reflection in Go".
 </p>
 
 <p><b>Types and interfaces</b></p>
 
 <p>
 Because reflection builds on the type system, let's start with a
 refresher about types in Go.
 </p>
 
 <p>
 Go is statically typed. Every variable has a static type, that is,
 exactly one type known and fixed at compile time: <code>int</code>,
 <code>float32</code>, <code>*MyType</code>, <code>[]byte</code>,
 and so on. If we declare
 </p>
 
 <pre><!--{{code "progs/interface.go" `/type MyInt/` `/STOP/`}}
 -->type MyInt int
+
 var i int
 var j MyInt</pre>
 
 <p>
 then <code>i</code> has type <code>int</code> and <code>j</code>
 has type <code>MyInt</code>. The variables <code>i</code> and
 <code>j</code> have distinct static types and, although they have
 the same underlying type, they cannot be assigned to one another
 without a conversion.
 </p>
 
 <p>
 One important category of type is interface types, which represent
 fixed sets of methods. An interface variable can store any concrete
 (non-interface) value as long as that value implements the
-interface&rsquo;s methods. A well-known pair of examples is
+interface's methods. A well-known pair of examples is
 <code>io.Reader</code> and <code>io.Writer</code>, the types
 <code>Reader</code> and <code>Writer</code> from the <a href=
 "http://golang.org/pkg/io/">io package</a>:
 </p>
 
 <pre><!--{{code "progs/interface.go" `/// Reader/` `/STOP/`}}
 -->// Reader is the interface that wraps the basic Read method.
 type Reader interface {
     Read(p []byte) (n int, err error)
 }
@@ skipping 17 matching lines @@
     r = os.Stdin
     r = bufio.NewReader(r)
     r = new(bytes.Buffer)
     // and so on</pre>
 
 <p>
 It's important to be clear that whatever concrete value
 <code>r</code> may hold, <code>r</code>'s type is always
 <code>io.Reader</code>: Go is statically typed and the static type
 of <code>r</code> is <code>io.Reader</code>.</p>
+
+<p>
 An extremely important example of an interface type is the empty
 interface:
 </p>
 
 <pre>
 interface{}
 </pre>
 
 <p>
 It represents the empty set of methods and is satisfied by any
-value at all, since any value has zero or more methods.</p>
+value at all, since any value has zero or more methods.
+</p>
+
+<p>
 Some people say that Go's interfaces are dynamically typed, but
 that is misleading. They are statically typed: a variable of
 interface type always has the same static type, and even though at
 run time the value stored in the interface variable may change
-type, that value will always satisfy the interface.</p>
+type, that value will always satisfy the interface.
+</p>
+
+<p>
 We need to be precise about all this because reflection and
 interfaces are closely related.
 </p>
 
 <p><b>The representation of an interface</b></p>
 
 <p>
 Russ Cox has written a <a href=
 "http://research.swtch.com/2009/12/go-data-structures-interfaces.html">
 detailed blog post</a> about the representation of interface values
 in Go. It's not necessary to repeat the full story here, but a
 simplified summary is in order.
 </p>
 
 <p>
 A variable of interface type stores a pair: the concrete value
-assigned to the variable, and that value&rsquo;s type descriptor.
+assigned to the variable, and that value's type descriptor.
 To be more precise, the value is the underlying concrete data item
 that implements the interface and the type describes the full type
 of that item. For instance, after
 </p>
 
 <pre><!--{{code "progs/interface.go" `/func typeAssertions/` `/STOP/`}}
 -->    var r io.Reader
-    tty, err = os.OpenFile(&#34;/dev/tty&#34;, os.O_RDWR, 0)
-    if err != nil { return nil, err }
+    tty, err := os.OpenFile(&#34;/dev/tty&#34;, os.O_RDWR, 0)
+    if err != nil {
+        return nil, err
+    }
     r = tty</pre>
 
 <p>
 <code>r</code> contains, schematically, the (value, type) pair,
 (<code>tty</code>, <code>*os.File</code>). Notice that the type
 <code>*os.File</code> implements methods other than
 <code>Read</code>; even though the interface value provides access
 only to the <code>Read</code> method, the value inside carries all
 the type information about that value. That's why we can do things
 like this:
@@ skipping 28 matching lines @@
 that same pair, (<code>tty</code>, <code>*os.File</code>). That's
 handy: an empty interface can hold any value and contains all the
 information we could ever need about that value.
 </p>
 
 <p>
 (We don't need a type assertion here because it's known statically
 that <code>w</code> satisfies the empty interface. In the example
 where we moved a value from a <code>Reader</code> to a
 <code>Writer</code>, we needed to be explicit and use a type
-assertion because <code>Writer</code>&rsquo;s methods are not a
-subset of <code>Reader</code>&rsquo;s.)</p>
+assertion because <code>Writer</code>'s methods are not a
+subset of <code>Reader</code>'s.)
+</p>
+
+<p>
 One important detail is that the pair inside an interface always
 has the form (value, concrete type) and cannot have the form
 (value, interface type). Interfaces do not hold interface
 values.
 </p>
 
 <p>
 Now we're ready to reflect.
 </p>
 
 <p><b>The first law of reflection</b></p>
+
 <p><b>1. Reflection goes from interface value to reflection object.</b></p>
 
 <p>
 At the basic level, reflection is just a mechanism to examine the
 type and value pair stored inside an interface variable. To get
-started, there are two types we need to know about in <a href=
-"http://golang.org/pkg/reflect">package reflect</a>: <a href=
-"http://golang.org/pkg/reflect/#Type">Type</a> and <a href=
-"http://golang.org/pkg/reflect/#Value">Value</a>. Those two types
+started, there are two types we need to know about in
+<a href="http://golang.org/pkg/reflect">package reflect</a>:
+<a href="http://golang.org/pkg/reflect/#Type">Type</a>and
+<a href="http://golang.org/pkg/reflect/#Value">Value</a>. Those two types
 give access to the contents of an interface variable, and two
 simple functions, called <code>reflect.TypeOf</code> and
 <code>reflect.ValueOf</code>, retrieve <code>reflect.Type</code>
 and <code>reflect.Value</code> pieces out of an interface value.
-(Also, from the <code>reflect.Value</code> it&rsquo;s easy to get
-to the <code>reflect.Type</code>, but let&rsquo;s keep the
+(Also, from the <code>reflect.Value</code> it's easy to get
+to the <code>reflect.Type</code>, but let's keep the
 <code>Value</code> and <code>Type</code> concepts separate for
 now.)
 </p>
 
 <p>
 Let's start with <code>TypeOf</code>:
 </p>
 
 <pre><!--{{code "progs/interface2.go" `/package main/` `/STOP main/`}}
 -->package main
 
 import (
-        &#34;fmt&#34;
-        &#34;reflect&#34;
+    &#34;fmt&#34;
+    &#34;reflect&#34;
 )
 
 func main() {
-        var x float64 = 3.4
-        fmt.Println(&#34;type:&#34;, reflect.TypeOf(x))
+    var x float64 = 3.4
+    fmt.Println(&#34;type:&#34;, reflect.TypeOf(x))
 }</pre>
 
 <p>
 This program prints
 </p>
 
 <pre>
 type: float64
 </pre>
 
 <p>
 You might be wondering where the interface is here, since the
-program looks like it&rsquo;s passing the <code>float64</code>
+program looks like it's passing the <code>float64</code>
 variable <code>x</code>, not an interface value, to
 <code>reflect.TypeOf</code>. But it's there; as <a href=
 "http://golang.org/pkg/reflect/#Type.TypeOf">godoc reports</a>, the
 signature of <code>reflect.TypeOf</code> includes an empty
 interface:
 </p>
 
 <pre>
 // TypeOf returns the reflection Type of the value in the interface{}.
 func TypeOf(i interface{}) Type
 </pre>
 
 <p>
 When we call <code>reflect.TypeOf(x)</code>, <code>x</code> is
 first stored in an empty interface, which is then passed as the
 argument; <code>reflect.TypeOf</code> unpacks that empty interface
 to recover the type information.
 </p>
 
 <p>
 The <code>reflect.ValueOf</code> function, of course, recovers the
 value (from here on we'll elide the boilerplate and focus just on
 the executable code):
 </p>
 
 <pre><!--{{code "progs/interface2.go" `/var x/` `/STOP/`}}
--->        var x float64 = 3.4
-        fmt.Println(&#34;type:&#34;, reflect.TypeOf(x))</pre>
+-->    var x float64 = 3.4
+    fmt.Println(&#34;type:&#34;, reflect.TypeOf(x))</pre>
 
 <p>
 prints
 </p>
 
 <pre>
 value: &lt;float64 Value&gt;
 </pre>
 
 <p>
@@ skipping 41 matching lines @@
 hold the value: <code>int64</code> for all the signed integers, for
 instance. That is, the <code>Int</code> method of
 <code>Value</code> returns an <code>int64</code> and the
 <code>SetInt</code> value takes an <code>int64</code>; it may be
 necessary to convert to the actual type involved:
 </p>
 
 <pre><!--{{code "progs/interface2.go" `/START f2/` `/STOP/`}}
 -->    var x uint8 = &#39;x&#39;
     v := reflect.ValueOf(x)
-    fmt.Println(&#34;type:&#34;, v.Type()) // uint8.
+    fmt.Println(&#34;type:&#34;, v.Type())                            // uint8.
     fmt.Println(&#34;kind is uint8: &#34;, v.Kind() == reflect.Uint8) // true.
-    x = uint8(v.Uint()) // v.Uint returns a uint64.</pre>
+    x = uint8(v.Uint())                                       // v.Uint returns a uint64.</pre>
 
 <p>
 The second property is that the <code>Kind</code> of a reflection
 object describes the underlying type, not the static type. If a
 reflection object contains a value of a user-defined integer type,
 as in
 </p>
 
 <pre><!--{{code "progs/interface2.go" `/START f3/` `/START/`}}
 -->    type MyInt int
     var x MyInt = 7
     v := reflect.ValueOf(x)</pre>
 
 <p>
 the <code>Kind</code> of <code>v</code> is still
 <code>reflect.Int</code>, even though the static type of
 <code>x</code> is <code>MyInt</code>, not <code>int</code>. In
 other words, the <code>Kind</code> cannot discriminate an int from
-a <code>MyInt</code> even though the <code>Type</code> can.</p>
-<p><b>The second law of reflection</b></p></p>
+a <code>MyInt</code> even though the <code>Type</code> can.
+</p>
+
+<p><b>The second law of reflection</b></p>
+
 <p><b>2. Reflection goes from reflection object to interface
-value.</b></p></p>
+value.</b></p>
+
+<p>
 Like physical reflection, reflection in Go generates its own
-inverse.</p>
+inverse.
+</p>
+
+<p>
 Given a <code>reflect.Value</code> we can recover an interface
 value using the <code>Interface</code> method; in effect the method
 packs the type and value information back into an interface
 representation and returns the result:
 </p>
 
 <pre>
 // Interface returns v's value as an interface{}.
 func (v Value) Interface() interface{}
 </pre>
@@ skipping 54 matching lines @@
 In short, the <code>Interface</code> method is the inverse of the
 <code>ValueOf</code> function, except that its result is always of
 static type <code>interface{}</code>.
 </p>
 
 <p>
 Reiterating: Reflection goes from interface values to reflection
 objects and back again.
 </p>
 
-<p><b>The third law of reflection</b></p
+<p><b>The third law of reflection</b></p>
+
 <p><b>3. To modify a reflection object, the value must be settable.</b></p>
 
 <p>
 The third law is the most subtle and confusing, but it's easy
 enough to understand if we start from first principles.
 </p>
 
 <p>
 Here is some code that does not work, but is worth studying.
 </p>
@@ skipping 19 matching lines @@
 </p>
 
 <p>
 The <code>CanSet</code> method of <code>Value</code> reports the
 settability of a <code>Value</code>; in our case,
 </p>
 
 <pre><!--{{code "progs/interface2.go" `/START f5/` `/STOP/`}}
 -->    var x float64 = 3.4
     v := reflect.ValueOf(x)
-    fmt.Println(&#34;settability of v:&#34; , v.CanSet())</pre>
+    fmt.Println(&#34;settability of v:&#34;, v.CanSet())</pre>
 
 <p>
 prints
 </p>
 
 <pre>
 settability of v: false
 </pre>
 
 <p>
@@ skipping 43 matching lines @@
 <pre>
 f(x)
 </pre>
 
 <p>
 We would not expect <code>f</code> to be able to modify
 <code>x</code> because we passed a copy of <code>x</code>'s value,
 not <code>x</code> itself. If we want <code>f</code> to modify
 <code>x</code> directly we must pass our function the address of
 <code>x</code> (that is, a pointer to <code>x</code>):</p>
+
+<p>
 <code>f(&amp;x)</code>
 </p>
 
 <p>
 This is straightforward and familiar, and reflection works the same
 way. If we want to modify <code>x</code> by reflection, we must
 give the reflection library a pointer to the value we want to
 modify.
 </p>
 
 <p>
-Let&rsquo;s do that. First we initialize <code>x</code> as usual
+Let's do that. First we initialize <code>x</code> as usual
 and then create a reflection value that points to it, called
 <code>p</code>.
 </p>
 
 <pre><!--{{code "progs/interface2.go" `/START f7/` `/START/`}}
 -->    var x float64 = 3.4
     p := reflect.ValueOf(&amp;x) // Note: take the address of x.
     fmt.Println(&#34;type of p:&#34;, p.Type())
-    fmt.Println(&#34;settability of p:&#34; , p.CanSet())</pre>
+    fmt.Println(&#34;settability of p:&#34;, p.CanSet())</pre>
 
 <p>
 The output so far is
 </p>
 
 <pre>
 type of p: *float64
 settability of p: false
 </pre>
 
 <p>
 The reflection object <code>p</code> isn't settable, but it's not
 <code>p</code> we want to set, it's (in effect) <code>*p</code>. To
 get to what <code>p</code> points to, we call the <code>Elem</code>
 method of <code>Value</code>, which indirects through the pointer,
 and save the result in a reflection <code>Value</code> called
 <code>v</code>:
 </p>
 
 <pre><!--{{code "progs/interface2.go" `/START f7b/` `/START/`}}
 -->    v := p.Elem()
-    fmt.Println(&#34;settability of v:&#34; , v.CanSet())</pre>
+    fmt.Println(&#34;settability of v:&#34;, v.CanSet())</pre>
 
 <p>
 Now <code>v</code> is a settable reflection object, as the output
 demonstrates,
 </p>
 
 <pre>
 settability of v: true
 </pre>
 
@@ skipping 33 matching lines @@
 is when using reflection to modify the fields of a structure. As
 long as we have the address of the structure, we can modify its
 fields.
 </p>
 
 <p>
 Here's a simple example that analyzes a struct value,
 <code>t</code>. We create the reflection object with the address of
 the struct because we'll want to modify it later. Then we set
 <code>typeOfT</code> to its type and iterate over the fields using
-straightforward method calls (see <a href=
-"http://golang.org/pkg/reflect/">package reflect</a> for details).
+straightforward method calls (see 
+<a href="http://golang.org/pkg/reflect/">package reflect</a> for details).
 Note that we extract the names of the fields from the struct type,
 but the fields themselves are regular <code>reflect.Value</code>
 objects.
 </p>
 
-<pre>
 <pre><!--{{code "progs/interface2.go" `/START f8/` `/STOP/`}}
 -->    type T struct {
-            A int
-            B string
+        A int
+        B string
     }
     t := T{23, &#34;skidoo&#34;}
     s := reflect.ValueOf(&amp;t).Elem()
     typeOfT := s.Type()
     for i := 0; i &lt; s.NumField(); i++ {
-           f := s.Field(i)
-            fmt.Printf(&#34;%d: %s %s = %v\n&#34;, i,
-                typeOfT.Field(i).Name, f.Type(), f.Interface())
+        f := s.Field(i)
+        fmt.Printf(&#34;%d: %s %s = %v\n&#34;, i,
+            typeOfT.Field(i).Name, f.Type(), f.Interface())
     }
     s.Field(0).SetInt(77)
     s.Field(1).SetString(&#34;Sunset Strip&#34;)
     fmt.Println(&#34;t is now&#34;, t)</pre>
-</pre>
 
 <p>
 The output of this program is
 </p>
 
 <pre>
 0: A int = 23
 1: B string = skidoo
 </pre>
 
 <p>
-There&rsquo;s one more point about settability introduced in
+There's one more point about settability introduced in
 passing here: the field names of <code>T</code> are upper case
 (exported) because only exported fields of a struct are
-settable.</p>
+settable.
+</p>
+
+<p>
 Because <code>s</code> contains a settable reflection object, we
 can modify the fields of the structure.
 </p>
 
 <pre><!--{{code "progs/interface2.go" `/START f8b/` `/STOP/`}}
 -->    s.Field(0).SetInt(77)
     s.Field(1).SetString(&#34;Sunset Strip&#34;)
     fmt.Println(&#34;t is now&#34;, t)</pre>
 
 <p>
@@ skipping 20 matching lines @@
 <ol>
 <li>Reflection goes from interface value to reflection
 object.</li>
 <li>Reflection goes from reflection object to interface
 value.</li>
 <li>To modify a reflection object, the value must be settable.</li>
 </ol>
 
 <p>
 Once you understand these laws reflection in Go becomes much easier
-to use, although it remains subtle. It&rsquo;s a powerful tool that
+to use, although it remains subtle. It's a powerful tool that
 should be used with care and avoided unless strictly
 necessary.
 </p>
 
 <p>
 There's plenty more to reflection that we haven't covered &mdash;
 sending and receiving on channels, allocating memory, using slices
 and maps, calling methods and functions &mdash; but this post is
 long enough. We'll cover some of those topics in a later
-article.</p>
-
-<i>By Rob Pike, September 2011</i>
+article.
+</p>