Merge constructor augmentation changes into the augmentations proposal

working/augmentation-libraries/feature-specification.md

@@ -239,14 +239,14 @@ An augmentation that replaces the body of a function may also want to
 preserve and run the code of the augmented declaration (hence the name
 "augmentation").  It may want to run its own code before the augmented
 code, after it, or both.  To support that, we allow a new expression syntax
-inside the "bodies" of augmenting declarations (function bodies,
-constructor bodies, and variable initializers). Inside an expression in an
-augmenting member declaration, the identifier `augmented` can be used to
-refer to the augmented function, getter, or setter body, or variable
-initializer. This is a contextual reserved word within `augment`
-declarations, and has no special meaning outside of that context. See the
-next section for a full specification of what `augmented` means, and how it
-must be used, in the various contexts.
+inside the "bodies" of certain augmenting declarations (some function bodies and
+variable initializers). Inside an expression in an augmenting member
+declaration, the identifier `augmented` can be used to refer to the augmented
+function, getter, or setter body, or variable initializer. This is a contextual
+reserved word within `augment` declarations, and has no special meaning outside
+of that context. See the [augmented expression](#augmented-expression) section
+for a full specification of what `augmented` means, and how it must be used, in
+the various contexts.
 
 *Note that within an augmenting member declaration, a reference to a member
 by the same name refers to the final version of the member (and not the one
@@ -343,9 +343,20 @@ augmented, but it generally follows the same rules as any normal identifier:
     variable's initializer if the member being augmented is not a variable
     declaration with an initializing expression.
 
-*   **Augmenting functions**: When augmenting a function, `augmented`
-    refers to the augmented function. Tear offs are not allowed, so this
-    function must immediately be invoked.
+*   **Augmenting functions**: Inside an augmenting function body (including
+    factory constructors but not generative constructors) `augmented` refers to
+    the augmented function. Tear-offs are not allowed, and this function must
+    immediately be invoked.
+
+*   **Augmenting non-redirecting generative constructors**: Unlike other
+    functions, `augmented` has no special meaning in non-redirecting generative
+    constructors. It is still a reserved word inside the body of these
+    constructors, since they are within the scope of an augmenting declaration.
+
+    There is instead an implicit order in which these augmented constructors are
+    invoked, and they all receive the same arguments. See
+    [this section](#non-redirecting-generative-constructors) for more
+    information.
 
 *   **Augmenting operators**: When augmenting an operator, `augmented`
     refers to the augmented operator method, which must be immediately
@@ -869,49 +880,187 @@ It is a compile-time error if:
 
 These are probably the most complex constructor, but also the most common.
 
-A non-redirecting generative constructor marked `augment` may:
+At a high level, a non-redirecting generative constructor marked `augment` may:
+
+*   Augment the constructor with an _additional_ constructor body (all bodies
+    eventually invoked as described below).
+
+*   Add initializers (and/or asserts) to the initializer list, as well as a
+    `super` call at the end of the initializer list.
+
+*   Opt a previously normal parameter into being either an initializing formal
+    parameter or super parameter.
+
+The full process for evaluating a non-redirecting generative constructor is as
+follows.
+
+When we invoke a non-redirecting generative constructor named *g* (for example
+`C.id` or `C`) on a class definition *C* with type parameters `X1`,..,`Xn`,
+instantiated with type arguments *T1*,…,*Tn*, with an argument list *L* to
+initialize an object *o* (with a runtime type that is known to extend *C* and
+implement *C*\<*T1*,..,*Tn*\>):
+
+*   Let *d* be the constructor definition named *g* of *C*.
+
+*   For each *instance variable definition* of *C* in
+    *introductory declaration order* (the order of the *introductory*
+    declaration in the total traversal ordering of a library), where the
+    variable definition *has an initializer expression*, and is not declared
+    `late`:
+
+    *   Evaluate the initializer expression of that definition to a value *v*
+        (taking any augmentations of it into account).
+
+    *   Initialize the corresponding instance variable of *o* to the value *v*.
+
+*   Let *S* be an uninitialized argument list with the number of positional
+    arguments and names of named arguments of *superParameters* of *d* (which is
+    the shape of the argument list of the super-constructor invocation including
+    all explicit arguments and super parameters).
+
+*   Invoke the constructor definition *d* of *C*\<*T1*,…,*Tn*> with argument
+    list *L*, super parameters *S*, and uninitialized super initializer *s* to
+    initialize the value *o*.
+
+We then define the invocation of a *constructor definition* as follows, allowing
+an augmenting constructor’s definition to delegate to the definition it
+augments.
+
+An invocation of a non-redirecting generative constructor definition *d* on an
+instantiated class definition *C*\<*T1*,…,*Tn*\> with argument list *L*, super
+parameters *S*, and uninitialized super initializer *s* to initialize an object
+*o* proceeds as follows (at least for any class other than `Object`, which just
+completes immediately):
+
+*   Bind actual arguments to formal parameters. For each parameter in the
+    *parameterList* of *d* (in sequence order):
+
+    *   If the argument list *L* has a value for the corresponding positional
+        position or named argument name, let *v* be that value.
+
+    *   Otherwise, the parameter is guaranteed to be optional.
+
+        *   If the parameter has a default value expression, let *v* be the
+            value of that expression.
+
+        *   Otherwise let *v* be the `null` value.
+
+    *   If the parameter is an initializing formal with name *n*,
+
+        *   It is an error if *d* has an *augmentedDefinition* *d’* in which the
+            same parameter is anything other than a normal parameter.
+
+        *   Initialize the variable of *o* corresponding to the instance
+            variable named *n* of *C* to the value *v*. It is an error if this
+            variable is already initialized.
+
+        *   Bind the name *n* to *v* in the initializer-list scope.
+
+    *   Otherwise, if the parameter is a super-parameter,
+
+        *   It is an error if *d* has a *augmentedDefinition* *d’* in which the
+            same parameter is anything other than a normal parameter.
+
+        *   It is an error if *d* has a *augmentedDefinition* *d’*, which has
+            any super parameters. Only one declaration may contain super
+            parameters.
 
-*   Add or replace the body of the augmented constructor with a new body.
+        *   It is an error if *s* is initialized. Super parameters must appear
+            before any super constructor invocations.
 
-    *   If the augmenting constructor has an explicit block body, then that body
-        replaces any existing constructor body.
+        *   If the parameter is named, set the value of the argument with name
+            *n* of *S* to *v*.
 
-    *   In the augmenting constructor's body, an `augmented()` call executes the
-        augmented constructor's body in the same parameter scope that the
-        augmenting body is executing in. The expression has type `void` and
-        evaluates to `null`. **(TODO: This is slightly under-specified. We can
-        use the current bindings of the parameters of the augmenting constructor
-        as the initial binding of parameter variables in the augmented body, or
-        we can execute the body in the current *scope*, using the same variables
-        as the current body. The latter is not what we do with functions
-        elsewhere, and allows the `augmented()` expression to modify local
-        variables, but the former introduces different variables than the ones
-        that existed when evaluating the initializer list. If the initializer
-        list captures variables in closures, that body may not work.)**
+        *   Otherwise the parameter is positional:
 
-    *   Initializer lists _are not_ re-run, they have already executed and
-        shouldn't be executed twice. The same goes for initializing formals and
-        super parameters.
+            *   Let *i* be one plus the number of prior positional super
+                parameters in the parameter list of *d*.
 
-    *   If a parameter variable is overwritten prior to calling `augmented()`,
-        the augmented body will see the updated value, because the parameter
-        scope is identical.
+            *   Otherwise if *d* has a *superInitializer*, add the number of
+                positional arguments in the argument list of that invocation.
 
-    *   Local variables in scope where `augmented()` is evaluated are not in
-        scope for the execution of the augmented constructor's body.
+            *   Set the positional argument value with position *i* in *S* to
+                *v*.
 
-*   Add initializers to the initializer list. If the augmenting constructor has
-    an initializer list then:
+        *   Bind the name of the parameter to *v* in the initializer-list scope.
 
-    *   It's a compile-time error if the augmented constructor has
-        super-initializer, and the augmenting constructor's initializer list
-        also contains a super-initializer.
+    *   Otherwise the parameter is a normal parameter. Bind the name of the
+        parameter to *v* in the parameter scope.
 
-    *   Otherwise the result of applying the augmenting constructor has an
-        initializer list containing first the assertions and field initializers
-        of the augmented constructor, if any, then the assertions and field
-        initializers of the augmenting constructor, and finally any
-        super-initializer of either the augmeted or augmenting constructor.
+*   For each entry in the initializer list of *d*, in sequence order:
+
+    *   If assert entry, evaluate the first operand in the initializer list
+        scope. If evaluate to `false`, evaluate the second operand to a message
+        value *m*, if there is a second operand, otherwise let *m* be the
+        `null` value. Throw an `AssertionError` with *m* as message.
+
+    *   If variable intializer entry, evaluate expression in initializer list
+        scope to value *v*. Initialize the variable of *o* corresponding to
+        variable with the initializer entry name in *C* to the value *v*.
+
+*   If *d* has a *superInitializer*.
+
+    * It is an error if *s* is already initialized.
+
+    * Initialize *s* to the *superInitializer* of *d*.
+
+*   If *d* has an *augmentedDefinition* *d’*
+
+    *   Invoke *d’* on *C\<T1,…,Tn>* with arguments *L*, super-arguments *S*,
+        and super constructor invocation *s* to initialize *o*.
+
+    *   *This recurses on the augmented definition*.
+
+*   Otherwise:
+
+    *   Let *U* be be the instantiated *superclass definition* of
+        *C*\<*T1*,…,*Tn*\>.
+
+    *   If *s* is initialized:
+
+        *   Evaluate each argument of the argument list of the super-constructor
+            invocation in the initializer list scope, in source order, and set
+            the entry of *S* with the same position or name to the resulting
+            value.
+
+        *   Let *g1* be the name of the superclass constructor of *U* targeted
+            by the *superInitializer* (class-name of *U* plus `.id` if
+            referenced as `super.id`).
+
+    *   Otherwise let *g1* be the name of the unnamed constructor of *U*.
+
+    *   Invoke the constructor named *g1* on *U* with arguments *S* to
+        initialize *o*.
+
+    *   *This recurses on the superclass constructor.*
+
+*   When this has completed, execute the *body* of *d*, if any, in a scope which
+    has the parameter scope of the invocation of *d* as parent scope.
+
+*   Then invocation of *d* completes normally.
+
+The consequence of this definition is an execution order for initialization of
+an instance of a class of:
+
+*   Field initializers of class, from all augmentations, in “introductory
+    declaration source order”.
+
+*   Augmenting declaration parameter lists and initializer lists, for
+    augmentations in last-to-first order.
+
+*   Introductory declaration parameter list, initializer list
+
+*   Introductory declaration super initializer, recurses to this entire list on
+    superclass.
+
+*   Body of the introductory declaration.
+
+*   Bodies of any augmenting declarations in first-to-last order.
+
+It ensures that we only recurse in *one* place, keeping a stack discipline. The
+parameter scope of the invocation can be stack-allocated, and be on top of the
+stack when the scope is used. (If we execute initializer list entries *after*
+the ones of an augmented definition, we fail to maintain that stack order.)
 
 #### Non-redirecting factory constructors
 
@@ -932,8 +1081,12 @@ potentially non-redirecting property of the constructor.
 
 It is a compile-time error if:
 
-*   The augmented constructor has an initializer list or a body, or it has a
-    redirection.
+*   The augmented constructor has any initializers.
+*   The augmented constructor has a body.
+*   The augmented constructor has a redirection.
+
+This redirecting generative constructor now behaves exactly like any other
+redirecting generative constructor when it is invoked.
 
 #### Redirecting factory constructors