code review 14415043: spec: clarify rules for blank identifiers

doc/go_spec.html

 <!--{
         "Title": "The Go Programming Language Specification",
-        "Subtitle": "Version of Oct 4, 2013",
+        "Subtitle": "Version of Nov 13, 2013",
         "Path": "/ref/spec"
 }-->
 
 <!--
 TODO
 [ ] need language about function/method calls and parameter passing rules
 [ ] last paragraph of #Assignments (constant promotion) should be elsewhere
     and mention assignment to empty interface.
 [ ] need to say something about "scope" of selectors?
 [ ] clarify what a field name is in struct declarations
@@ skipping 818 matching lines @@
 [32]byte
 [2*N] struct { x, y int32 }
 [1000]*float64
 [3][5]int
 [2][2][2]float64  // same as [2]([2]([2]float64))
 </pre>
 
 <h3 id="Slice_types">Slice types</h3>
 
 <p>
-A slice is a descriptor for a contiguous segment of an array and
+A slice is a descriptor for a contiguous segment of an <i>underlying array</i> and
 provides access to a numbered sequence of elements from that array.
 A slice type denotes the set of all slices of arrays of its element type.
 The value of an uninitialized slice is <code>nil</code>.
 </p>
 
 <pre class="ebnf">
 SliceType = "[" "]" ElementType .
 </pre>
 
 <p>
@@ skipping 19 matching lines @@
 <a href="#Slice_expressions"><i>slicing</i></a> a new one from the original slice.
 The capacity of a slice <code>a</code> can be discovered using the
 built-in function <a href="#Length_and_capacity"><code>cap(a)</code></a>.
 </p>
 
 <p>
 A new, initialized slice value for a given element type <code>T</code> is
 made using the built-in function
 <a href="#Making_slices_maps_and_channels"><code>make</code></a>,
 which takes a slice type
-and parameters specifying the length and optionally the capacity:
-</p>
-
-<pre>
-make([]T, length)
+and parameters specifying the length and optionally the capacity.
+A slice created with <code>make</code> always allocates a new, hidden array
+to which the returned slice value refers. That is, executing
+</p>
+
+<pre>
 make([]T, length, capacity)
 </pre>
 
 <p>
-A call to <code>make</code> allocates a new, hidden array to which the returned
-slice value refers. That is, executing
-</p>
-
-<pre>
-make([]T, length, capacity)
-</pre>
-
-<p>
-produces the same slice as allocating an array and slicing it, so these two examples
-result in the same slice:
+produces the same slice as allocating an array and <a href="#Slice_expressions">slicing</a>
+it, so these two expressions are equivalent:
 </p>
 
 <pre>
 make([]int, 50, 100)
 new([100]int)[0:50]
 </pre>
 
 <p>
 Like arrays, slices are always one-dimensional but may be composed to construct
 higher-dimensional objects.
 With arrays of arrays, the inner arrays are, by construction, always the same length;
-however with slices of slices (or arrays of slices), the lengths may vary dynamically.
-Moreover, the inner slices must be allocated individually (with <code>make</code>).
+however with slices of slices (or arrays of slices), the inner lengths may vary dynamically.
+Moreover, the inner slices must be initialized individually.
 </p>
 
 <h3 id="Struct_types">Struct types</h3>
 
 <p>
 A struct is a sequence of named elements, called fields, each of which has a
 name and a type. Field names may be specified explicitly (IdentifierList) or
 implicitly (AnonymousField).
 Within a struct, non-<a href="#Blank_identifier">blank</a> field names must
 be <a href="#Uniqueness_of_identifiers">unique</a>.
@@ skipping 589 matching lines @@
 <a href="#Variable_declarations">variable</a>,
 <a href="#Function_declarations">function</a>,
 <a href="#Labeled_statements">label</a>, or
 <a href="#Import_declarations">package</a>.
 Every identifier in a program must be declared.
 No identifier may be declared twice in the same block, and
 no identifier may be declared in both the file and package block.
 </p>
 
 <p>
-The <a href="#Blank_identifier">blank identifier</a> may be used in a declaration
-like any other identifier, but it does not introduce a binding and thus is not

[r, 2013/10/05 16:02:36]

grammar depends on order.

may be used like any other identifier in a declaration, ...

[gri, 2013/10/07 19:58:30]

Done.

-declared.
+The <a href="#Blank_identifier">blank identifier</a> may be used like any other identifier
+in a declaration, but it does not introduce a binding and thus is not declared.
 </p>
 
 <pre class="ebnf">
 Declaration   = ConstDecl | TypeDecl | VarDecl .
 TopLevelDecl  = Declaration | FunctionDecl | MethodDecl .
 </pre>
 
 <p>
 The <i>scope</i> of a declared identifier is the extent of source text in which
 the identifier denotes the specified constant, type, variable, function, label, or package.
@@ skipping 51 matching lines @@
 In contrast to other identifiers, labels are not block scoped and do
 not conflict with identifiers that are not labels. The scope of a label
 is the body of the function in which it is declared and excludes
 the body of any nested function.
 </p>
 
 
 <h3 id="Blank_identifier">Blank identifier</h3>
 
 <p>
-The <i>blank identifier</i> is the underscore character <code>_</code>.
+The <i>blank identifier</i> is represented by the underscore character <code>_</code>.
 It serves as an anonymous placeholder instead of a regular (non-blank)
 identifier and has special meaning in <a href="#Declarations_and_scope">declarations</a>,
 as an <a href="#Operands">operand</a>, and in <a href="#Assignments">assignments</a>.
 </p>
 
 
 <h3 id="Predeclared_identifiers">Predeclared identifiers</h3>
 
 <p>
 The following identifiers are implicitly declared in the
@@ skipping 483 matching lines @@
 literal, a (possibly <a href="#Qualified_identifiers">qualified</a>)
 non-<a href="#Blank_identifier">blank</a> identifier denoting a
 <a href="#Constant_declarations">constant</a>,
 <a href="#Variable_declarations">variable</a>, or
 <a href="#Function_declarations">function</a>,
 a <a href="#Method_expressions">method expression</a> yielding a function,
 or a parenthesized expression.
 </p>
 
 <p>
-The <a href="#Blank_identifier">blank identifier</a> is not permitted
-as an operand except as an expression on the left-hand side of an
-<a href="#Assignments">assignment</a>.
+The <a href="#Blank_identifier">blank identifier</a> may appear as an
+operand only on the left-hand side of an <a href="#Assignments">assignment</a>.
 </p>

[r, 2013/10/05 16:02:36]

or short declaration? i know they're not operands on the left of := but this
seems to contradict reality. also the negation with exception makes this hard to
parse. how about:

The <>blank identifier<> may appear as an operand only as the operand on the
left-hand side of an <>assignment<>.

[gri, 2013/10/07 19:58:30]

Done.

 
 <pre class="ebnf">
 Operand    = Literal | OperandName | MethodExpr | "(" Expression ")" .
 Literal    = BasicLit | CompositeLit | FunctionLit .
 BasicLit   = int_lit | float_lit | imaginary_lit | rune_lit | string_lit .
 OperandName = identifier | QualifiedIdent.
 </pre>
 
 <h3 id="Qualified_identifiers">Qualified identifiers</h3>
 
@@ skipping 594 matching lines @@
 <p>
 Except for <a href="#Constants">untyped strings</a>, if the sliced operand is a string or slice,
 the result of the slice operation is a non-constant value of the same type as the operand.
 For untyped string operands the result is a non-constant value of type <code>string</code>.
 If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>
 and the result of the slice operation is a slice with the same element type as the array.
 </p>
 
 <p>
 If the sliced operand of a valid slice expression is a <code>nil</code> slice, the result
-is a <code>nil</code> slice.
+is a <code>nil</code> slice. Otherwise, the result shares its underlying array with the
+operand.
 </p>
 
 <h4>Full slice expressions</h4>
 
 <p>
 For an array, pointer to array, or slice <code>a</code> (but not a string), the primary expression
 </p>
 
 <pre>
 a[low : high : max]
@@ skipping 1548 matching lines @@
 
 <pre>
 x = 1
 *p = f()
 a[i] = 23
 (k) = &lt;-ch  // same as: k = &lt;-ch
 </pre>
 
 <p>
 An <i>assignment operation</i> <code>x</code> <i>op</i><code>=</code>
-<code>y</code> where <i>op</i> is a binary arithmetic operation is equivalent
+<code>y</code> where <i>op</i> is a binary arithmetic operation equivalent
 to <code>x</code> <code>=</code> <code>x</code> <i>op</i>
 <code>y</code> but evaluates <code>x</code>
 only once.  The <i>op</i><code>=</code> construct is a single token.
 In assignment operations, both the left- and right-hand expression lists
 must contain exactly one single-valued expression, and the left-hand
 expression must not be the blank identifier.
 </p>
 
 <pre>
 a[i] &lt;&lt;= 2
@@ skipping 27 matching lines @@
 one, two, three = '一', '二', '三'
 </pre>
 
 <p>
 The <a href="#Blank_identifier">blank identifier</a> provides a way to
 ignore right-hand side values in an assignment:
 </p>
 
 <pre>
 _ = x       // evaluate x but ignore it
 x, _ = f()  // evaluate f() but ignore second result value

[r, 2013/10/05 16:02:36]

a, _, c = f(), g(), h() // evaluate all three functions but discard return value
of call to g

 </pre>
 
 <p>
 The assignment proceeds in two phases.
 First, the operands of <a href="#Index_expressions">index expressions</a>
 and <a href="#Address_operators">pointer indirections</a>
 (including implicit pointer indirections in <a href="#Selectors">selectors</a>)
 on the left and the expressions on the right are all
 <a href="#Order_of_evaluation">evaluated in the usual order</a>.
 Second, the assignments are carried out in left-to-right order.
@@ skipping 19 matching lines @@
 
 i = 2
 x = []int{3, 5, 7}
 for i, x[i] = range x {  // set i, x[2] = 0, x[0]
         break
 }
 // after this loop, i == 0 and x == []int{3, 5, 3}
 </pre>
 
 <p>
-In assignments, each value must be
-<a href="#Assignability">assignable</a> to the type of the
-operand to which it is assigned. If an untyped <a href="#Constants">constant</a>
-is assigned to a variable of interface type, the constant is <a href="#Conversions">converted</a>
-to type <code>bool</code>, <code>rune</code>, <code>int</code>, <code>float64</code>,
-<code>complex128</code> or <code>string</code>
-respectively, depending on whether the value is a
-boolean, rune, integer, floating-point, complex, or string constant.
-</p>
-
-<!-- TODO(gri) specify rules for assignment to blank identifiers -->
+In assignments, each value must be <a href="#Assignability">assignable</a>
+to the type of the operand to which it is assigned, with the following special cases:
+</p>
+
+<ol>
+<li><p>
+        If an untyped <a href="#Constants">constant</a>
+        is assigned to a variable of interface type or the blank identifier,
+        the constant is first <a href="#Conversions">converted</a> to type
+        <code>bool</code>, <code>rune</code>, <code>int</code>, <code>float64</code>,
+        <code>complex128</code> or <code>string</code> respectively, depending on
+        whether the value is a boolean, rune, integer, floating-point, complex, or
+        string constant.
+</p></li>
+
+<li><p>
+        <!-- Note that the result of a comparison is an untyped bool that may not be constant. -->
+        If a left-hand side is the blank identifier, any typed or non-constant
+        value except for the predeclared identifier
+        <a href="#Predeclared_identifiers"><code>nil</code></a>
+        may be assigned to it.
+</p></li>
+</ol>
 
 <h3 id="If_statements">If statements</h3>
 
 <p>
 "If" statements specify the conditional execution of two branches
 according to the value of a boolean expression.  If the expression
 evaluates to true, the "if" branch is executed, otherwise, if
 present, the "else" branch is executed.
 </p>
 
@@ skipping 974 matching lines @@
 string type followed by <code>...</code>. This form appends the
 bytes of the string.
 </p>
 
 <pre class="grammar">
 append(s S, x ...T) S  // T is the element type of S
 </pre>
 
 <p>
 If the capacity of <code>s</code> is not large enough to fit the additional
-values, <code>append</code> allocates a new, sufficiently large slice that fits
-both the existing slice elements and the additional values. Thus, the returned
-slice may refer to a different underlying array.
+values, <code>append</code> allocates a new, sufficiently large underlying
+array that fits both the existing slice elements and the additional values.
+Otherwise, <code>append</code> re-uses the underlying array.
 </p>
 
 <pre>
 s0 := []int{0, 0}
 s1 := append(s0, 2)                // append a single element     s1 == []int{0, 0, 2}
 s2 := append(s1, 3, 5, 7)          // append multiple elements    s2 == []int{0, 0, 2, 3, 5, 7}
 s3 := append(s2, s0...)            // append a slice              s3 == []int{0, 0, 2, 3, 5, 7, 0, 0}
 s4 := append(s3[3:6], s3[2:]...)   // append overlapping slice    s4 == []int{3, 5, 7, 2, 3, 5, 7, 0, 0}
 
 var t []interface{}
@@ skipping 570 matching lines @@
 type Pointer *ArbitraryType
 
 func Alignof(variable ArbitraryType) uintptr
 func Offsetof(selector ArbitraryType) uintptr
 func Sizeof(variable ArbitraryType) uintptr
 </pre>
 
 <p>
 Any pointer or value of <a href="#Types">underlying type</a> <code>uintptr</code> can be converted to
 a <code>Pointer</code> type and vice versa.
+A <code>Pointer</code> is a <a href="#Pointer_types">pointer type</a> but a <code>Pointer</code>
+value may not be <a href="#Address_operators">dereferenced</a>.
 </p>
 
 <pre>
 var f float64
 bits = *(*uint64)(unsafe.Pointer(&amp;f))
 
 type ptr unsafe.Pointer
 bits = *(*uint64)(ptr(&amp;f))
+
+var p ptr = nil
 </pre>
 
 <p>
 The functions <code>Alignof</code> and <code>Sizeof</code> take an expression <code>x</code>
 of any type and return the alignment or size, respectively, of a hypothetical variable <code>v</code>
 as if <code>v</code> was declared via <code>var v = x</code>.
 </p>
 <p>
 The function <code>Offsetof</code> takes a (possibly parenthesized) <a href="#Selectors">selector</a>
 <code>s.f</code>, denoting a field <code>f</code> of the struct denoted by <code>s</code>
@@ skipping 53 matching lines @@
 </li>
 
 <li>For a variable <code>x</code> of array type: <code>unsafe.Alignof(x)</code> is the same as
    <code>unsafe.Alignof(x[0])</code>, but at least 1.
 </li>
 </ol>
 
 <p>
 A struct or array type has size zero if it contains no fields (or elements, respectively) that have a size greater than zero. Two distinct zero-size variables may have the same address in memory.
 </p>