tc39
Editorial: Convert @@ notation to intrinsics notation for well-known Symbols
- this avoids a conceptual conflict with decorators, when they land
Open to bikesheds; other alternatives I considered:
- explicitly using intrinsics, ie,
%SymbolSpecies%, and hardcoding that table, while removing the "well-known symbols table". This felt like it would lose some clarity around intrinsics vs well-known-symbols. - Using
%Symbol%species%- this would require upstream support in ecmarkup, so i opted not to do it for now. - something else?
Will this interact with special treatment of %% by ecmarkup (e.g., for "%%Internal%%" in spec → HTML)? And as a meta question, do we want to introduce auto-linking of well-known symbols if we're changing their representation?
@gibson042 i would love to see auto-linking of well-known symbols, with or without this change.
I've tested the HTML output locally and atm they don't link anywhere, before or after.
Happy with whatever. It would be nice cross-SDO citizenship work to make a corresponding HTML Standard PR, but it's certainly not required.
@domenic i'm happy to try my hand at that once an approach gets consensus here, prior to merging this one.
Would it be possible to use a syntax more similar to Symbol.foo, so that it looks more similar to how JavaScript developers refer to the same thing?
What’d you have in mind? It would have to be apparent that it’s not a property lookup on %Symbol%, i suspect.
Sorry, I don't have a concrete suggestion, and agree it shouldn't imply actual property access. But I would prefer that editorial churn like this would somehow inch us closer to being readable by normal programmers. @@ is now understood by a small set of people outside TC39; using a new syntax will make it harder to understand for that see while keeping it unintuitive for the big majority.
My preference would be to use the %SymbolSpecies% notation and move the well-known symbols table to immediately following the intrinsics table. That way we reduce the total number of novel syntaxes in the spec. I don't actually think there is much of an important distinction between intrinsics and well-known symbols except for the cross-realm interaction. They're similar enough that it makes sense to put them near each other and use the same syntax, IMO.
@bakkot i initially looked at doing that, but it seemed like a loss to remove the useful info in this section.
I'm thinking that we should leave things the way they are for now, since @@ is well-understood, fairly readable, and used by other specs.
Decision from the editor call today was to change @@symbolName notation to %Symbol.symbolName% for consistency with other instrinsics.
@ljharb Don't forget @bakkot's comment about the usage in figures: https://github.com/tc39/ecma262/pull/1314#issuecomment-441111136
Also would be good to have a NOTE near the symbol table mentioning the old notation, I think.
In this PR, do well-known symbols qualify as intrinsics?
-
If they do, that would require some changes to 6.1.7.4 Well-Known Intrinsic Objects, which indicates that intrinsics (or at least, the well-known ones) are all objects.
-
If they don't, then the preamble to the "Well-Known Symbols" table shouldn't say that it lists intrinsics.
~~Either way, it would be nice if the definition of the %X.Y% notation didn't say that it means an object.~~
(For reference, here are some other discussions about the definition of intrinsics:
- how-we-work PR #64
- comment in PR #1376
- issue #1540
- issue #1703
)
I think it's easier if we don't try to make them into intrinsics. Apart from being primitives, they also do not have different identities across realms. They're really a different kin of thing.
If they don't, then the preamble to the "Well-Known Symbols" table shouldn't say that it lists intrinsics.
Agreed. I think it needn't mention that at all: just "Within this specification a well-known symbol is referred to using the standard intrinsic notation", possibly followed by "defined in section 6.1.7.4", is probably sufficient.
Either way, it would be nice if the definition of the %X.Y% notation didn't say that it means an object.
Where does it say that? The only relevant text I see says
Within this specification a reference such as %name% means the intrinsic object, associated with the current realm, corresponding to the name. A reference such as %name.a.b% means, as if the "b" property of the "a" property of the intrinsic object %name% was accessed prior to any ECMAScript code being evaluated.
Which indicates that %X% is an object (which will still be the case after this PR), but does not say that %X.Y% must be.
This is exactly why two distinct notations were used in the first place. Well known symbols are not intrinsics and the distinction is emphasized by using two notations.
This change seems like pointless churm that in the end blurs the important semantic distinctions.
Either way, it would be nice if the definition of the %X.Y% notation didn't say that it means an object.
Where does it say that?
Whoops, right. I saw "means the intrinsic object" and failed to see that it only applied to the dotless form.
I agree with Allen's comment and think that, in general, the use of %X.Y% does not result in an overall increase in spec clarity.
Well-known symbols are nonconfigurable nonwritable properties on an intrinsic; what's the important semantic distinction?
@bakkot @michaelficarra note added and image updated.
@michaelficarra the previous feeling on it had been that it would cause too much churn for not enough gain. Let's chat about it next week!
@ljharb I'm happy to talk about it more if you want, but we already made the call to make this change: https://github.com/tc39/ecma262/pull/1314#issuecomment-556553406. Has something changed since then?
oh oops :-) i guess i forgot/missed it. In that case, I’ll convert it back, and rebase!
Eh, revisiting this since the last time it was discussed in light of the significant amount of other nontrivial churn we've made recently or propose to make soon (#1914, #1964, #1796, #1950, #1889, #1595, etc), my preference is now to hold off on this until we've dealt with some of the higher-value stuff and let things rest for a while.
That’s fine too; but the work is already done and won’t likely impact those other PRs much (and I’m happy to rebase them all myself after this lands, if that’s a concern)
I am less concerned with rebasing and more concerned with the amount of change that readers of the spec need to keep up with over time.
Personally, I'm really positive about this change. The @@ syntax has caused some confusing spill-over into documentation and design discussions, and it really doesn't make sense given that ES6 didn't end up including that syntax in the language. This PR adds a lot of clarity, and can help guide others towards communicating with clarity. Good work, @ljharb .