What's a good term describing the syntax where a primary constructor can occur?

[eernstg]

The declaring constructors feature introduces several new non-terminals in the Dart grammar. In particular:

<classNameMaybePrimary> ::= // New rule.
     <primaryConstructor>
   | <typeWithParameters>;

To give some context, it is used together with rules such as the following:

<classDeclaration> ::= // First alternative modified.
     (<classModifiers> | <mixinClassModifiers>)
     'class' <classNameMaybePrimary> <superclass>? <interfaces>? <classBody>
   | ...;

<primaryConstructor> ::= // New rule.
     'const'? <typeWithParameters> ('.' <identifierOrNew>)?
     <declaringParameterList>;

In short, <classNameMaybePrimary> is the syntactic construct that occurs in the header of classes (and other declarations like mixin classes, enums, and extension types), right after the keyword(s) specifying the kind of declaration (class, mixin class, etc). For example:

class A {} // The `<classNameMaybePrimary>` is `A`.

class B<X> // The `<classNameMaybePrimary>` is `B<X>`.

class C.name(final int i); // The `<classNameMaybePrimary>` is `C.name(final int i)`.

The <classNameMaybePrimary> is invariably the location where the name of the declaration can be found (in the examples: A, B, C). This constructor used to be called the <className> previously, even though it may also contain a formal type parameter list (<X>).

So there's precedence for not mentioning the type parameters in the non-terminal name.

With the declaring constructors feature we can add a substantial amount of new constructs at this location: We can declare a primary constructor, which includes (in addition to the class name and potential type parameters):

• optionally the keyword const, before the class name, to indicate that the primary constructor is constant,
• optionally the second part of the name of the primary constructor (.name in the last example above), and
• a formal parameter list ((final int i) above).

I've chosen the non-terminal name <classNameMaybePrimary> to indicate that this is

• definitely the location where we'll find the name of the declaration as a whole (and type parameters), and
• optionally the location where we can find a primary constructor.

However, this name seems to create a substantial amount of controversy, and it would be great if anybody could come up with a word (that is, a short sequence of words that we'll squeeze together to a camel cased thingy) that everybody loves. ;-)

In particular, @dart-lang/language-team, WDYT?

[bwilkerson]

However, this name seems to create a substantial amount of controversy ...

I think it's worth understanding the source of the controversy. It's my understanding that it comes from a desire for the analyzer package's AST structure to match the BNF, and an observation that ClassNameMaybePrimary isn't a very good class name. If my understanding is wrong, please correct me and ignore the rest of this comment. (I'll note that the AST structure did not previously have a class named ClassName because historically it has not tried to follow the BNF.)

It isn't at all clear to me that keeping the two in sync is a desirable goal [1], but if we assume for the moment that that's the goal we have set ourselves, then I would argue that the quality of the API used to access the AST has a much bigger impact on more people than the structure or names used in the BNF. That would imply that the question shouldn't be "can we find a better name for this production", but should rather be "what should the AST structure look like" and then we simply write the BNF to match the AST. [2]

[1] I think the needs of an API design and the needs of a BNF design are different enough that having this as a goal will lead to suboptimal design in at least one area.

[2] Yes, I'm aware that that isn't always possible because of constraints related to good BNF design. Hence footnote [1].

[eernstg]

I do agree that the API of AST nodes matters to more people than the names of non-terminals, but it would be nice to have a useful terminology in both cases, also because it can serve as a starting point for natural language habits.

For example, I think it's useful to have a non-terminal named <classDeclaration> and an AST node named ClassDeclaration and a natural language phrase like "class declaration", which are denoting approximately the same thing.

This kind of terminological consistency could arguably be even more important in the case where the terminology isn't so well-established and obvious.

We do have a history, of course. For example, a <forInitializerStatement> can be an <expression> followed by a semicolon, and it can be a <localVariableDeclaration>, and those things don't sound a lot like "statements", but I do think we should try to make the terminology about the language more consistent and understandable whenever we can, in all those domains I mentioned above.

[bwilkerson]

For example, I think it's useful to have a non-terminal named and an AST node named ClassDeclaration and a natural language phrase like "class declaration", which are denoting approximately the same thing.

This kind of terminological consistency could arguably be even more important in the case where the terminology isn't so well-established and obvious.

I agree, terminology is very important. (I'm still waiting to find a good word to mean 'class', 'enum', 'mixin', 'extension', or 'extension type'.)

But I don't think we're ever going to want to talk about the portion of the grammar described by the production <classNameMaybePrimary>. We'll talk about the 'class header', and the 'primary constructor' (even though the portions of the grammar covered by that term aren't contiguous), but not the 'class name maybe primary'. And if I'm wrong and we do need to talk about it, then I think that 'class name maybe primary' would be a really confusing term to use for it.

For example, a <forInitializerStatement> ...

Thanks, that's a great example.

The grammar for the for loop [1] looks like this:

⟨forStatement⟩ ::= await? for ‘(’ ⟨forLoopParts⟩ ‘)’ ⟨statement⟩
⟨forLoopParts⟩ ::= ⟨forInitializerStatement⟩ ⟨expression⟩? ‘;’ ⟨expressionList⟩?
    | ⟨forInLoopPrefix⟩ in ⟨expression⟩
⟨forInLoopPrefix⟩ ::= ⟨metadata⟩ ⟨declaredIdentifier⟩
    | ⟨identifier⟩
⟨forInitializerStatement⟩ ::= ⟨localVariableDeclaration⟩
    | ⟨expression⟩? ‘;’

[1] This is from the language spec. The patterns feature changed this, but the feature spec doesn't contain an updated grammar as far as I could tell. I'm guessing that when the pattern syntax gets folded into the language spec there will be an additional alternative in each of forInLoopPrefix and forInitializerStatement.

In the AST, a ForStatement has the same structure, but ForLoopParts is the root of a type hierarchy of the form

ForLoopParts
.  ForParts
.  . ForPartsWithDeclarations
.  . ForPartsWithExpression
.  . ForPartsWithPattern
.  ForEachParts
.  . ForEachPartsWithDeclaration
.  . ForEachPartsWithIdentifier
.  . ForEachPartsWithPattern

If we assume that every use of | in the grammar introduces a new subclass of the production's class, then a straight translation of the grammar would yield the same number of concrete classes (though I think there would be 2 more classes if the grammar were extended to include patterns), but a deeper structure of AST nodes (2 for for-each loops, 3 for normal for loops).

If we were to make the AST conform to the grammar I think we'd have a worse API. If we were to make the grammar conform to the API then it probably wouldn't be a valid grammar.