Many improvements, based on reviews of both documents

Author: eernstg

working/0723-static-extensions/feature-specification-variant1.md

@@ -68,22 +68,27 @@ constructors in the static extension must return an object whose type is
 For example:
 
 ```dart
-// Omit extension type parameters when the static extension only has static
-// members. Type parameters are just noise for static members, anyway.
+// Omit extension type parameters when the static extension only
+// has static members. Type parameters are just noise for static
+// members, anyway.
 static extension E2 on Map {
   static Map<K2, V> castFromKey<K, V, K2>(Map<K, V> source) =>
       Map.castFrom<K, V, K2, V>(source);
 }
 
-// Declare extension type parameters, to be used by constructors. The
-// type parameters can have stronger bounds than the on-declaration.
+// Declare extension type parameters, to be used by constructors.
+// The type parameters can have stronger bounds than the
+// on-declaration.
 static extension E3<K extends String, V> on Map<K, V> {
-  factory Map.fromJson(Map<String, Object?> source) => Map.from(source);
+  factory Map.fromJson(Map<String, Object?> source) =>
+      Map.from(source);
 }
 
 var jsonMap = <String, Object?>{"key": 42};
 var typedMap = Map<String, int>.fromJson(jsonMap);
-// `Map<int, int>.fromJson(...)` is an error: Violates the bound of `K`.
+
+// But `Map<int, int>.fromJson(...)` is an error: It violates the
+// bound of `K`.
 ```
 
 Another motivation for this mechanism is that it supports constructors of
@@ -120,14 +125,14 @@ static extension E4<X> on Map<X, List<X>> {
   factory Map.listValue(X x) => {x: [x]};
 }
 
-var int2intList = Map.listValue(1); // Inferred as `Map<int, List<int>>`.
+var int2intList = Map.listValue(1); // `Map<int, List<int>>`.
 // `Map<int, double>.listValue(...)` is an error.
 
 static extension E6<Y> on Map<String, Y> {
   factory Map.fromString(Y y) => {y.toString(): y};
 }
 
-var string2bool = Map.fromString(true); // Inferred as `Map<String, bool>`.
+var string2bool = Map.fromString(true); // `Map<String, bool>`.
 Map<String, List<bool>> string2listOfBool = Map.fromString([]);
 ```
 
@@ -147,7 +152,8 @@ The grammar is modified as follows:
     ...;
 
 <staticExtensionDeclaration> ::= // New rule.
-    'static' 'extension' <identifier>? <typeParameters>? 'on' <type>
+    'static' 'extension' <identifier>? <typeParameters>?
+    'on' <type>
     '{' (<metadata> <staticExtensionMemberDeclaration>)* '}';
 
 <staticExtensionMemberDeclaration> ::= // New rule.
@@ -168,9 +174,6 @@ The grammar is modified as follows:
     ('final' | 'const') <type>? <staticFinalDeclarationList> |
     'late' 'final' <type>? <initializedIdentifierList> |
     'late'? <varOrType> <initializedIdentifierList>;
-
-<constructorNameList> ::=
-    <constructorName> (',' <constructorName>)*;
 ```
 
 In a static extension of the form `static extension E on C {...}` where `C`
@@ -257,7 +260,9 @@ constructor or a static member with the same basename as a constructor or a
 static member in the on-declaration of _D_.
 
 *In other words, a static extension should not have name clashes with its
-on-declaration.*
+on-declaration. The warning above is aimed at static members and
+constructors, but a similar warning would probably be useful for name
+clashes with instance members as well.*
 
 #### Static extension scopes
 
@@ -278,10 +283,10 @@ type parameter scope, if any, and otherwise the library scope.
 Static members in a static extension are subject to the same static
 analysis as static members in other declarations.
 
-A factory constructor in a static extension introduces scopes in the same
-way as other factory constructor declarations. The return type of the
-factory constructor is the constructor return type of the static
-extension *(that is, the type in the `on` clause)*.
+A constructor in a static extension introduces scopes in the same way as
+other constructor declarations. The return type of the constructor is the
+constructor return type of the static extension *(that is, the type in the
+`on` clause)*.
 
 Type variables of a static extension `E` are in scope in static member
 declarations in `E`, but any reference to such type variables in a static
@@ -295,46 +300,95 @@ the current library, or if _D_ is imported and not hidden.
 
 *In particular, it is accessible even in the case where there is a name
 clash with another locally declared or imported declaration with the same
-name.*
-
-#### Invocation of a static member of a static extension
-
-An _explicitly resolved invocation_ of a static member of a static
-extension named `E` is an expression of the form `E.m()` (or any other
-member access, *e.g., `E.m`, `E.m = e`, etc*), where `m` is a static member
-declared by `E`.
+name. This is also true if _D_ is imported with a prefix. Similarly, it is
+accessible even in the case where _D_ does not have a name, if it is
+declared in the current library.*
+
+#### Invocation of a static member
+
+*The language specification defines the notion of a _member invocation_ in
+the section [Member Invocations][], which is used below. This concept
+includes method invocations like `e.aMethod<int>(24)`, property extractions
+like `e.aGetter` or `e.aMethod` (tear-offs), operator invocations like
+`e1 + e2` or `aListOrNull?[1] = e`, function invocations like `f()`.  Each
+of these expressions has a _syntactic receiver_ and an _associated member
+name_.  With `e.aMethod<int>(24)`, the receiver is `e` and the associated
+member name is `aMethod`, with `e1 + e2` the receiver is `e1` and the
+member name is `+`, and with `f()` the receiver is `f` and the member name
+is `call`. Note that the syntactic receiver is a type literal in the case
+where the member invocation invokes a static member. In the following we
+will specify invocations of static members using this concept.*
+
+[Member Invocations]: https://github.com/dart-lang/language/blob/94194cee07d7deadf098b1f1e0475cb424f3d4be/specification/dartLangSpec.tex#L13903
+
+Consider an expression `e` which is a member invocation with syntactic
+receiver `E` and associated member name `m`, where `E` denotes a static
+extension and `m` is a static member declared by `E`. We say that `e` is an
+_explicitly resolved invocation_ of said static member of `E`.
 
 *This can be used to invoke a static member of a specific static extension
-in order to manually resolve a name clash.*
-
-A static member invocation on a class `C`, of the form `C.m()` (or any
-other member access), is resolved by looking up static members in `C` named
-`m` and looking up static members of every accessible static extension with
-on-declaration `C` and a member named `m`.
-
-If `C` contains such a declaration then the expression is an invocation of
-that static member of `C`, with the same static analysis and dynamic
-semantics as before the introduction of this feature.
-
-Otherwise, an error occurs if no declarations named `m` or more than one
-declaration named `m` were found. *They would necessarily be declared in
-static extensions.*
-
-Otherwise, the invocation is resolved to the given static member
-declaration in a static extension named `Ej`, and the invocation is treated
-as `Ej.m()` *(this is an explicitly resolved invocation, which is specified
-above)*.
+in order to manually resolve a name clash.
+
+Consider an expression `e` which is a member invocation with syntactic
+receiver `C` and an associated member name `m`, where `C` denotes a class
+and `m` is a static member declared by `C`. The static analysis and dynamic
+semantics of this expression is the same as in Dart before the introduction
+of this feature.
+
+When `C` declares a static member whose basename is the basename of `m`,
+but `C` does not declare a static member named `m` or a constructor named
+`C.m`, a compile-time error occurs. *This is the same behavior as in
+pre-feature Dart. It's about "near name clashes" involving a setter.*
+
+In the case where `C` does not declare any static members whose basename is
+the basename of `m`, and `C` does not declare any constructors named `C.m2`
+where `m2` is the basename of `m`, let _M_ be the set containing each
+accessible extension whose on-declaration is `C`, and whose static members
+include one with the name `m`, or which declares a constructor named `C.m`.
+
+*If `C` does declare a constructor with such a name `C.m2` then the given
+expression is not a static member invocation. This case is described in a
+section below.*
+
+Otherwise *(when `C` does not declare such a constructor)*, an error occurs
+if _M_ is empty or _M_ contains more than one member.
+
+Otherwise *(when no error occurred)*, assume that _M_ contains exactly one
+element which is an extension `E` that declares a static member named
+`m`. The invocation is then treated as `E.m()` *(this is an explicitly
+resolved invocation, which is specified above)*.
+
+Otherwise *(when `E` does not declare such a static member)*, _M_ will
+contain exactly one element which is a constructor named `C.m`. This is not
+a static member invocation, and it is specified in a section below.
+
+In addition to these rules for invocations of static members of a static
+extension or a class, a corresponding set of rules exist for a static
+extension and the following: An enumerated declaration *(`enum ...`)*, a
+mixin class, a mixin, and an extension type. They only differ by being
+concerned with a different kind of on-declaration.
+
+In addition to the member invocations specified above, it is also possible
+to invoke a static member of the enclosing declaration based on lexical
+lookup. This case is applicable when an expression in a class, enum, mixin
+or extension type resolves to an invocation of a static member of the
+enclosing declaration.
+
+*This invocation will never invoke a static member of a static extension
+which is not the enclosing declaration. In other words, there is nothing
+new in this case.*
 
 #### The instantiated constructor return type of a static extension
 
-We associate a static extension declaration _D_ named `E` with formal type
-parameters `X1 extends B1 .. Xs extends Bs` and an actual type argument
-list `T1 .. Ts` with a type known as the _instantiated constructor return
-type of_ _D_ _with type arguments_ `T1 .. Ts`.
+Assume that _D_ is a generic static extension declaration named `E` with
+formal type parameters `X1 extends B1, ..., Xs extends Bs` and constructor
+return type `C<S1 .. Sk>`. Let `T1, ..., Ts` be a list of types. The
+_instantiated constructor return type_ of _D_ _with actual type arguments_
+`T1 .. Ts` is then the type `[T1/X1 .. Ts/Xs]C<S1 .. Sk>`.
 
-When a static extension declaration _D_ named `E` has an on-clause which
-denotes a non-generic class `C`, the instantiated constructor return type
-is `C`, for any list of actual type arguments.
+*As a special case, assume that _D_ has an on-type which denotes a
+non-generic class `C`. In this case, the instantiated constructor return
+type is `C`, for any list of actual type arguments.*
 
 *Note that such type arguments can be useful, in spite of the fact that
 they do not occur in the type of the newly created object. For example:*
@@ -352,25 +406,16 @@ static extension E<X> on A {
 void main() {
   // We can create an `A` "directly".
   A a = A(42);
-  
+
   // We can also use a function to compute the `int`.
   a = A.computed('Hello!', (s) => s.length);
 }
 ```
 
-When a static extension declaration _D_ has no formal type parameters, and
-it has an on-type `C<S1 .. Sk>`, the instantiated constructor return type
-of _D_ is `C<S1 .. Sk>`.
-
-*In this case the on-type is a fixed type (also known as a ground type),
-e.g., `List<int>`. This implies that the constructor return type of D is
-the same for every call site.*
-
-Finally we have the general case: Consider a static extension declaration
-_D_ named `E` with formal type parameters `X1 extends B1 .. Xs extends Bs`
-and a constructor return type `C<S1 .. Sk>`. With actual type arguments
-`T1 .. Ts`, the instantiated constructor return type of _D_ with type
-arguments `T1 .. Ts` is `[T1/X1 .. Ts/Xs]C<S1 .. Sk>`.
+*As another special case, assume that _D_ has no formal type parameters,
+and it has a constructor return type of the form `C<S1 .. Sk>`. In this
+case the instantiated constructor return type of _D_ is `C<S1 .. Sk>`,
+which is a ground type, and it is the same for all call sites.*
 
 #### Invocation of a constructor in a static extension
 
@@ -391,7 +436,7 @@ information. In particular, the actual type arguments passed to the
 extension determines the actual type arguments passed to the class, which
 means that the explicitly resolved invocation typically has quite some
 redundancy (but it is very easy to check whether it is consistent, and it
-is an error if it is inconsistent). Every other form is reduced to the
+is an error if it is inconsistent). Every other form is reduced to this
 explicitly resolved form.*
 
 A compile-time error occurs if the type arguments passed to `E` violate the
@@ -415,10 +460,10 @@ normalization occurs. *In other words, the types must be equal, not
 just mutual subtypes.*
 
 *Note that explicitly resolved invocations of constructors declared in
-static extensions are an exception in real code, usable in the case where a
-name clash prevents an implicitly resolved invocation. However, implicitly
-resolved invocations are specified in the rest of this section by reducing
-them to explicitly resolved ones.*
+static extensions are a rare exception in real code, usable in the case
+where a name clash prevents an implicitly resolved invocation. However,
+implicitly resolved invocations are specified in the rest of this section
+by reducing them to explicitly resolved ones.*
 
 A constructor invocation of the form `C<T1 .. Tm>.name(args)` is partially
 resolved by looking up a constructor named `C.name` in the class `C` and in
@@ -437,46 +482,65 @@ Otherwise, the invocation is partially resolved to a set of candidate
 constructors found in static extensions. Each of the candidates _kj_ is
 vetted as follows:
 
-Assume that _kj_ is a constructor declared by a static extension _D_ named
-`E` with type parameters `X1 extends B1 .. Xs extends Bs` and on-type
-`C<S1 .. Sm>`.  Find actual values `U1 .. Us` for `X1 .. Xs` satisfying the
-bounds `B1 .. Bs`, such that `([U1/X1 .. Us/Xs]C<S1 .. Sm>) == C<T1 .. Tm>`.
-If this fails then remove _kj_ from the set of candidate constructors.
-Otherwise note that _kj_ uses actual type arguments `U1 .. Us`.
+If `m` is zero and `E` is an accessible extension with on-declaration `C`
+that declares a static member whose basename is `name` then the invocation
+is a static member invocation *(which is specified in an earlier section)*.
+
+Otherwise, assume that _kj_ is a constructor declared by a static extension
+_D_ named `E` with type parameters `X1 extends B1 .. Xs extends Bs`,
+on-declaration `C`, and on-type `C<S1 .. Sm>`. Find actual values
+`U1 .. Us` for `X1 .. Xs` satisfying the bounds `B1 .. Bs`, such that
+`([U1/X1 .. Us/Xs]C<S1 .. Sm>) == C<T1 .. Tm>`. This may determine the
+value of some of the actual type arguments `U1 .. Us`, and others may be
+unconstrained (because they do not occur in `C<T1 .. Tm>`). Actual type
+arguments corresponding to unconstrained type parameters are given as `_`
+(and they are subject to inference later on, where the types of the actual
+arguments `args` may influence their value). If this inference fails
+then remove _kj_ from the set of candidate constructors.  Otherwise note
+that _kj_ uses actual type arguments `U1 .. Us`.
 
 If all candidate constructors have been removed, or more than one candidate
 remains, a compile-time error occurs. Otherwise, the invocation is
 henceforth treated as `E<U1 .. Us>.C<T1 .. Tm>.name(args)` (respectively
-`E<U1 .. Us>.C<T1 .. Tm>(args)`).
+`E<U1 .. Us>.C<T1 .. Tm>(args)`). *This is an explicitly resolved static
+extension constructor invocation, which is specified above.*
 
 A constructor invocation of the form `C.name(args)` (respectively
 `C(args)`) where `C` denotes a non-generic class is resolved in the
-same manner, with `m == 0`. 
-
-*In this case, type parameters declared by `E` may be inferred based on the
-constructor signature (similarly to the example with `A.computed` above),
-or they will be bound to values selected by instantiation to bound.*
+same manner, with `m == 0`.
 
 Consider a constructor invocation of the form `C.name(args)` (and similarly
 for `C(args)`) where `C` denotes a generic class. As usual, the
 invocation is treated as in the pre-feature language when it denotes a
 constructor declared by the class `C`.
 
-In the case where the context type schema for this invocation fully
-determines the actual type arguments of `C`, the expression is changed to
-receive said actual type arguments, `C<T1 .. Tm>.name(args)`, and treated
-as described above.
+In the case where the context type schema for this invocation
+determines some actual type arguments of `C`, the expression is changed to
+receive said actual type arguments, `C<T1 .. Tm>.name(args)` (where the
+unconstrained actual type arguments are given as `_` and inferred later).
+The expression is then treated as described above.
+
+Next, we construct a set _M_ containing all accessible static extensions
+with on-declaration `C` that declare a constructor named `C.name`
+(respectively `C`).
 
-In the case where the invocation resolves to exactly one constructor
-`C.name` (or `C`) declared by a static extension named `E`, the invocation
-is treated as `E.C.name(args)` (respectively `E.C(args)`).
+In the case where _M_ contains exactly one extension `E` that declares a
+constructor named `C.name` (respectively `C`), the invocation is treated as
+`E.C.name(args)` (respectively `E.C(args)`).
 
-Otherwise, when there are two or more candidates from static extensions,
-an error occurs. *We do not wish to specify an approach whereby `args` is
+Otherwise, when there are two or more candidates from static extensions, an
+error occurs. *We do not wish to specify an approach whereby `args` is
 subject to type inference multiple times, and hence we do not support type
 inference for `C.name(args)` in the case where there are multiple distinct
 declarations whose signature could be used during the static analysis of
-that expression.*
+that expression. The workaround is to specify the actual type arguments
+explicitly.*
+
+In addition to these rules for invocations of constructors of a static
+extension or a class, a corresponding set of rules exist for a static
+extension and the following: An enumerated declaration *(`enum ...`)*, a
+mixin class, a mixin, and an extension type. They only differ by being
+concerned with a different kind of declaration.
 
 ### Dynamic Semantics
 
@@ -495,7 +559,7 @@ This fully determines the dynamic semantics of this feature.
 
 ### Changelog
 
-1.1 - August 28, 2024
+1.1 - August 30, 2024
 
 * Clarify many parts.