code review 5711043: spec: clarifications around exports

spec: clarifications around exports, uniqueness of identifiers

- Define what it means for two identifiers to be unique.

- The current spec is incorrect about exported
identifiers: for instance, it excluded fields
of non-exported types of exported variables
from being exported. It is easier to leave
the detailed specification away and let the
rest of the spec govern access of exported
identifiers.

- The current spec is incorrect about qualified
identifiers: It simply required that an identifier
be exported to be valid in a qualified identifier.
However, qualified identifiers can only access
exported identifiers declared in the package
block of the imported package.

Fixes issue 1551.

[gri, 2012-02-29 20:59:43]

Hello r@golang.org, rsc@golang.org, iant@golang.org, ken@golang.org (cc:
golang-dev@googlegroups.com),

I'd like you to review this change to
https://code.google.com/p/go

[iant2, 2012-02-29 21:15:53]

LGTM

gri@golang.org writes:

> Reviewers: r, rsc, iant, ken2,
>
> Message:
> Hello r@golang.org, rsc@golang.org, iant@golang.org, ken@golang.org (cc:
> golang-dev@googlegroups.com),
>
> I'd like you to review this change to
> https://code.google.com/p/go
>
>
> Description:
> spec: clarifications around exports
>
> Steps towards clarifying issue 1551.
>
> The current spec is incorrect about exported
> identifiers: for instance, it excluded fields
> of non-exported types of exported variables
> from being exported. It is easier to leave
> the detailed specification away and let the
> rest of the spec govern access of exported
> identifiers.
>
> The current spec is incorrect about qualified
> identifiers: It simply required that an identifier
> be exported to be valid in a qualified identifier.
> However, qualified identifiers can only access
> exported identifiers declared in the package
> block of the imported package.
>
> Please review this at http://codereview.appspot.com/5711043/
>
> Affected files:
>   M doc/go_spec.html
>
>
> Index: doc/go_spec.html
> ===================================================================
> --- a/doc/go_spec.html
> +++ b/doc/go_spec.html
> @@ -1541,7 +1541,8 @@
>  <h3 id="Predeclared_identifiers">Predeclared identifiers</h3>
>
>  <p>
> -The following identifiers are implicitly declared in the universe block:
> +The following identifiers are implicitly declared in the
> +<a href="#Blocks">universe block</a>:
>  </p>
>  <pre class="grammar">
>  Types:
> @@ -1564,17 +1565,11 @@
>  <h3 id="Exported_identifiers">Exported identifiers</h3>
>
>  <p>
> -An identifier may be <i>exported</i> to permit access to it from
> another package
> -using a <a href="#Qualified_identifiers">qualified identifier</a>. An
> identifier
> -is exported if both:
> -</p>
> -<ol>
> -	<li>the first character of the identifier's name is a Unicode
> upper case letter (Unicode class "Lu"); and</li>
> -	<li>the identifier is declared in the <a
> href="#Blocks">package block</a> or denotes a field or method of a
> type
> -	    declared in that block.</li>
> -</ol>
> -<p>
> -All other identifiers are not exported.
> +Identifiers that start with a Unicode upper case letter (Unicode
> class "Lu")
> +are <i>exported</i>. An exported identifier may be accessible from
> another package
> +via a <a href="#Qualified_identifiers">qualified identifier</a> or a
> field or
> +method <a href="#Selectors">selector</a>. Non-exported identifiers
> are never
> +accessible from another package.
>  </p>
>
>
> @@ -2020,14 +2015,17 @@
>  </pre>
>
>  <p>
> -A qualified identifier accesses an identifier in a different package, which
> -must be <a href="#Import_declarations">imported</a>.
> -The identifier must be <a href="#Exported_identifiers">exported</a> by that
> -package, which means that it must begin with a Unicode upper case letter.
> +A qualified identifier <code>p.X</code> accesses an identifier
> <code>X</code>
> +in a different package <code>p</code>, which must be
> +<a href="#Import_declarations">imported</a>.
> +<code>X</code> must be declared in the <a href="#Blocks">package
> block</a> of
> +<code>p</code> and <a href="#Exported_identifiers">exported</a>.
> +In the current package, <code>p.X</code> denotes the constant, type,
> variable,
> +or function that <code>X</code> denotes in <code>p</code>.
>  </p>
>
>  <pre>
> -math.Sin
> +math.Sin	// denotes the Sin function in package math
>  </pre>
>
>  <h3 id="Composite_literals">Composite literals</h3>

[r, 2012-02-29 21:21:45]

http://codereview.appspot.com/5711043/diff/7001/doc/go_spec.html
File doc/go_spec.html (right):

http://codereview.appspot.com/5711043/diff/7001/doc/go_spec.html#newcode1568
doc/go_spec.html:1568: Identifiers that start with a Unicode upper case letter
(Unicode class "Lu")
not all identifiers like that are exported, although they may be "exported".
function-scope variables A are not exported, for instance. do you care to
clarify? you half-clarify later. it can stay as is if you don't want to get into
it, but it may be sufficient to define it in this sentence and s/may/is/ in the
next.

Identifiers declared at package scope, or as methods are struct fields, are
"exported" if they start with....

not sure that's an improvement, but this definition has always bothered me and
you're editing it now.

http://codereview.appspot.com/5711043/diff/7001/doc/go_spec.html#newcode2020
doc/go_spec.html:2020: <a href="#Import_declarations">imported</a>.
in a.B.C, C need not be explicitly imported.

[rsc, 2012-02-29 21:29:38]

The implementation in 6g and, I believe, in gccgo is this:

A non-uppercase name that appears in package p1
is treated as distinct from any name that appears in
package p2, even if the two names are spelled the same.

Instead of trying to get there from exported identifiers,
maybe we should start with that definition and derive
exported identifiers as the consequence.

[gri, 2012-02-29 21:32:38]

On Wed, Feb 29, 2012 at 1:29 PM, Russ Cox <rsc@golang.org> wrote:
> The implementation in 6g and, I believe, in gccgo is this:
>
> A non-uppercase name that appears in package p1
> is treated as distinct from any name that appears in
> package p2, even if the two names are spelled the same.
>
> Instead of trying to get there from exported identifiers,
> maybe we should start with that definition and derive
> exported identifiers as the consequence.

Yes, my plan was to have a section on equality of identifiers along those lines.
Let me try again.

[gri, 2012-02-29 22:53:07]

PTAL

http://codereview.appspot.com/5711043/diff/7001/doc/go_spec.html
File doc/go_spec.html (right):

http://codereview.appspot.com/5711043/diff/7001/doc/go_spec.html#newcode1568
doc/go_spec.html:1568: Identifiers that start with a Unicode upper case letter
(Unicode class "Lu")
On 2012/02/29 21:21:45, r wrote:
> not all identifiers like that are exported, although they may be "exported".
> function-scope variables A are not exported, for instance. do you care to
> clarify? you half-clarify later. it can stay as is if you don't want to get
into
> it, but it may be sufficient to define it in this sentence and s/may/is/ in
the
> next.
> 
> Identifiers declared at package scope, or as methods are struct fields, are
> "exported" if they start with....
> 
> not sure that's an improvement, but this definition has always bothered me and
> you're editing it now.

I think the intuitive notion of what "exported" means is not correct: when a
package p is imported, all of it is imported, but not all of it may be
accessible via an identifier.

So, one could go ahead and define a special term (say "CapitalIdent") and use it
to define a more fine-grained notion of "export", but at the end it's just the
same. It seems easier to just say capitalized identifiers are called "exported"
and that is the definition of "exported".

It does fit with the next section on equality of identifiers.

http://codereview.appspot.com/5711043/diff/7001/doc/go_spec.html#newcode2020
doc/go_spec.html:2020: <a href="#Import_declarations">imported</a>.
On 2012/02/29 21:21:45, r wrote:
> in a.B.C, C need not be explicitly imported.

In a.B.C, a.B is the qualified identifier, and a must be imported. C would be a
selector.

But I am probably misunderstanding your comment.

[r, 2012-03-01 00:46:14]

http://codereview.appspot.com/5711043/diff/4005/doc/go_spec.html
File doc/go_spec.html (right):

http://codereview.appspot.com/5711043/diff/4005/doc/go_spec.html#newcode1577
doc/go_spec.html:1577: are called <i>exported</i>. All other identifiers are
called <i>non-exported</i>.
that first sentence still rubs me the wrong way: "exported" does not mean
exported, it just means Capitalized.

this is another CL that's growing tentacles, though. maybe best to back off and
take a simpler approach.

http://codereview.appspot.com/5711043/diff/4005/doc/go_spec.html#newcode5091
doc/go_spec.html:5091: of the <i>imported</i> package and enables access to
them.  The import names an
maybe, but that's not the whole story. it runs init too, and it's possible to
access things that aren't exported.

[gri, 2012-03-01 01:56:31]

PTAL

http://codereview.appspot.com/5711043/diff/4005/doc/go_spec.html
File doc/go_spec.html (right):

http://codereview.appspot.com/5711043/diff/4005/doc/go_spec.html#newcode1577
doc/go_spec.html:1577: are called <i>exported</i>. All other identifiers are
called <i>non-exported</i>.
On 2012/03/01 00:46:14, r wrote:
> that first sentence still rubs me the wrong way: "exported" does not mean
> exported, it just means Capitalized.
> 
> this is another CL that's growing tentacles, though. maybe best to back off
and
> take a simpler approach.

There's a different way of looking at it: "Exported" means that the identifier
is exported - which is true. It doesn't really matter that say identifiers in
function bodies are never really exported - they cannot be accessed anyway
(enforced through other rules).

Anyway, tried again, this time by adjusting the existing definition. I think
it's more clumsy, though.

http://codereview.appspot.com/5711043/diff/4005/doc/go_spec.html#newcode5091
doc/go_spec.html:5091: of the <i>imported</i> package and enables access to
them.  The import names an
On 2012/03/01 00:46:14, r wrote:
> maybe, but that's not the whole story. it runs init too, and it's possible to
> access things that aren't exported.

Inits are explained elsewhere.

"Exported" defines access to identifiers, not to language entities. When a
package is imported, everything in it is "imported", but not all of it may be
denoted with an identifier.

Slightly reformulated and added link to program init section.

[r, 2012-03-01 03:07:59]

http://codereview.appspot.com/5711043/diff/3006/doc/go_spec.html
File doc/go_spec.html (right):

http://codereview.appspot.com/5711043/diff/3006/doc/go_spec.html#newcode1584
doc/go_spec.html:1584: expression starting with an identifier declared in the
package block.</li>
or identifies a field or method ....

"expression starting with" is weird and i'm not even sure correct. in f.X, f
could be my local variable; what matters is its type.

and even then, if it's embedded it gets harder.

what's wrong with what i said before, an identifer starting Lu that is declared
at package level or is a method or struct field?  the item need not be package
level.

[gri, 2012-03-01 04:11:39]

PTAL.
- gri

http://codereview.appspot.com/5711043/diff/3006/doc/go_spec.html
File doc/go_spec.html (right):

http://codereview.appspot.com/5711043/diff/3006/doc/go_spec.html#newcode1584
doc/go_spec.html:1584: expression starting with an identifier declared in the
package block.</li>
On 2012/03/01 03:07:59, r wrote:
> or identifies a field or method ....
> 
> "expression starting with" is weird and i'm not even sure correct. in f.X, f
> could be my local variable; what matters is its type.
> 
> and even then, if it's embedded it gets harder.
> 
> what's wrong with what i said before, an identifer starting Lu that is
declared
> at package level or is a method or struct field?  the item need not be package
> level.

Mostly reverted to the start. F is indeed exported in this case, and so is M:

func f() interface{} {
   return struct{F int}{42}
}

func f() interface{} {
   var x interface{ M() } = something_implementing_this_interface
   return x
}

[r, 2012-03-01 04:15:43]

this is close. i'll let others chime in now, but i'm happy enough

[iant, 2012-03-01 05:04:17]

http://codereview.appspot.com/5711043/diff/3007/doc/go_spec.html
File doc/go_spec.html (right):

http://codereview.appspot.com/5711043/diff/3007/doc/go_spec.html#newcode1584
doc/go_spec.html:1584: or denotes a struct field or method.</li>
Perhaps write "a method or a struct field", as the current wording suggests that
only struct methods are exported.

http://codereview.appspot.com/5711043/diff/3007/doc/go_spec.html#newcode1594
doc/go_spec.html:1594: Two identifiers are equal if they are spelled the same
and if either:
I find this a bit confusing.  I don't normally think of identifiers as being
equal.  I think of whether they refer to the same object or not.  But that is
not what you care about here.  I think you are trying to describe the normal
case, and that makes this confusing.  Suppose you instead describe the unusual
case:

If two identifiers are declared in different packages and are not exported, then
they are never the same even if they are spelled the same.  For example

package p1
type S1 { f int }
package p2
type S2 { f int }
type S3 { S1; S2 }
func f(s3 S3) int { return s3.f }

The identifier f here is the one in p2, not the one in p1.

[rsc, 2012-03-01 16:39:29]

I like this a lot.  The CL description says towards fixing 1551
but I think this completely resolves it.

http://codereview.appspot.com/5711043/diff/3009/doc/go_spec.html
File doc/go_spec.html (right):

http://codereview.appspot.com/5711043/diff/3009/doc/go_spec.html#newcode1600
doc/go_spec.html:1600: <li>both are declared in the same package</li>
I think "declared" is a loaded word here.  s/are declared/appear/?
This is a purely syntactic/lexical condition.

[gri, 2012-03-01 18:24:35]

PTAL.

Changed the  section on "Equality of identifiers" to define "Uniqueness of
identifiers" instead. We use the term "unique" several times in the spec already
and it was not defined. This ties this up, and also lends itself better to
different phrasing as suggested by iant.

http://codereview.appspot.com/5711043/diff/3009/doc/go_spec.html
File doc/go_spec.html (right):

http://codereview.appspot.com/5711043/diff/3009/doc/go_spec.html#newcode1600
doc/go_spec.html:1600: <li>both are declared in the same package</li>
On 2012/03/01 16:39:29, rsc wrote:
> I think "declared" is a loaded word here.  s/are declared/appear/?
> This is a purely syntactic/lexical condition.

Done.

[rsc, 2012-03-01 18:41:40]

LGTM

http://codereview.appspot.com/5711043/diff/6012/doc/go_spec.html
File doc/go_spec.html (right):

http://codereview.appspot.com/5711043/diff/6012/doc/go_spec.html#newcode1596
doc/go_spec.html:1596: Given a set of identifiers, the identifiers are called
<i>unique</i>
Sets are not unique.

Given a set of identifiers, an identifier is called unique if it is different
from any other in the set.

[gri, 2012-03-01 18:47:25]

PTAL.

http://codereview.appspot.com/5711043/diff/6012/doc/go_spec.html
File doc/go_spec.html (right):

http://codereview.appspot.com/5711043/diff/6012/doc/go_spec.html#newcode1596
doc/go_spec.html:1596: Given a set of identifiers, the identifiers are called
<i>unique</i>
On 2012/03/01 18:41:40, rsc wrote:
> Sets are not unique.
> 
> Given a set of identifiers, an identifier is called unique if it is different
> from any other in the set.

Done.

[iant, 2012-03-01 19:01:57]

LGTM

[r, 2012-03-01 21:38:20]

LGTM
it's a bit lawyery and takes hard thinking, but i believe it works

http://codereview.appspot.com/5711043/diff/3012/doc/go_spec.html
File doc/go_spec.html (right):

http://codereview.appspot.com/5711043/diff/3012/doc/go_spec.html#newcode1597
doc/go_spec.html:1597: <i>different</i> from any other in the set.
s/any/every/

[gri, 2012-03-01 21:57:54]

*** Submitted as http://code.google.com/p/go/source/detail?r=51404e3bab77 ***

spec: clarifications around exports, uniqueness of identifiers

- Define what it means for two identifiers to be unique.

- The current spec is incorrect about exported
identifiers: for instance, it excluded fields
of non-exported types of exported variables
from being exported. It is easier to leave
the detailed specification away and let the
rest of the spec govern access of exported
identifiers.

- The current spec is incorrect about qualified
identifiers: It simply required that an identifier
be exported to be valid in a qualified identifier.
However, qualified identifiers can only access
exported identifiers declared in the package
block of the imported package.

Fixes issue 1551.

R=r, rsc, iant, ken
CC=golang-dev
http://codereview.appspot.com/5711043