From bd43d371536abb051d61ce8aac1cf7a233a87267 Mon Sep 17 00:00:00 2001 From: Erik Ernst Date: Fri, 22 Aug 2025 16:40:32 +0200 Subject: [PATCH 1/2] Indroduce changes from pre-move version of the feature specification of augmentations --- .../augmentations/feature-specification.md | 64 +++++++++++++++++-- 1 file changed, 57 insertions(+), 7 deletions(-) diff --git a/working/augmentations/feature-specification.md b/working/augmentations/feature-specification.md index 527bbb5f74..c4fb1e795b 100644 --- a/working/augmentations/feature-specification.md +++ b/working/augmentations/feature-specification.md @@ -2,7 +2,7 @@ Author: rnystrom@google.com, jakemac@google.com, lrn@google.com -Version: 1.37 (see [Changelog](#Changelog) at end) +Version: 1.38 (see [Changelog](#Changelog) at end) Experiment flag: augmentations @@ -453,7 +453,7 @@ scope. *We could say that it attaches itself to the existing name.* Augmentations aren't allowed to *replace* code, so they mostly add entirely new declarations to the surrounding type. However, function and constructor -augmentations can fill in a body for an augmented declaration that is lacks one. +augmentations can fill in a body for an augmented declaration that lacks one. More precisely, a function or constructor declaration (introductory or augmenting) is *incomplete* if all of: @@ -771,13 +771,45 @@ augment class Person { } ``` +A top-level function, static method, or instance method may be augmented to +provide default values for optional parameters: + +```dart +class C { + void m1([int i]); + void m2({String name}); + void m3({String otherName = "Smith"}); // OK, too. +} + +augment class C { + augment m1([i = 1]) {} + augment m2({name = "John"}) {} + augment m3({otherName}) {} +} +``` + +An optional formal parameter has the default value _d_ if exactly one +declaration of that formal parameter in the augmentation chain specifies a +default value, and it is _d_. An optional formal parameter does not have an +explicitly specified default value if none of its declarations in the +augmentation chain specifies a default value. The default value is +introduced implicitly with the value null in the case where the parameter +has a nullable declared type, and no default values for that parameter are +specified in the augmentation chain. + It's a **compile-time** error if: * The signature of the augmenting function does not [match][signature matching] the signature of the augmented function. -* The augmenting function specifies any default values. *Default values are - defined solely by the introductory function.* +* The augmentation chain has two or more specifications of a default value + for the same optional parameter. This is an error even in the case where + all of them are identical. *Default values are defined by the introductory + function or an augmentation, but at most once.* + +* The augmentation chain has no specifications of a default value for an + optional parameter whose declared type is potentially non-nullable, and + the declared function is not abstract. * A function is not complete after all augmentations are applied, unless it's an instance member and the surrounding class is abstract. *Every function @@ -848,16 +880,30 @@ Augmenting constructors works similar to augmenting a function, with some extra rules to handle features unique to constructors like redirections and initializer lists. +It is **not** a compile-time error for an incomplete factory constructor to +omit default values. *That is, they are treated similarly to abstract +instance methods in this respect. This allows the augmenting declaration to +implement the constructor by adding a redirection or a body.* + It's a **compile-time error** if: * The signature of the augmenting function does not [match][signature matching] the signature of the augmented function. -* The augmenting constructor parameters specify any default values. - *Default values are defined solely by the introductory constructor.* +* The augmentation chain has two or more specifications of a default value + for the same optional parameter. This is an error even in the case where + all of them are identical. *Default values are defined by the introductory + declaration or an augmentation, but at most once.* + +* The augmentation chain has exactly one specification of a default value + for an optional parameter, and the constructor is a redirecting factory. + +* The augmentation chain has no specifications of a default value for an + optional parameter whose declared type is potentially non-nullable, and + the constructor is not a redirecting factory. * The introductory constructor is `const` and the augmenting constructor - is not or vice versa. *An augmentation can't change whether or not a + is not, or vice versa. *An augmentation can't change whether or not a constructor is const because that affects whether users are allowed to use the constructor in a const context.* @@ -1128,6 +1174,10 @@ and assume the third point is always true. ## Changelog +### 1.38 + +* Generalize the treatment of default values of optional parameters. + ### 1.37 * Rename to "augmentations" (from "augmentation libraries") and define the From b7154078811882e4671875dea9198866433066fd Mon Sep 17 00:00:00 2001 From: Erik Ernst Date: Sun, 24 Aug 2025 13:03:14 +0200 Subject: [PATCH 2/2] Review response --- .../augmentations/feature-specification.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/working/augmentations/feature-specification.md b/working/augmentations/feature-specification.md index c4fb1e795b..34eeeeaf19 100644 --- a/working/augmentations/feature-specification.md +++ b/working/augmentations/feature-specification.md @@ -802,14 +802,14 @@ It's a **compile-time** error if: * The signature of the augmenting function does not [match][signature matching] the signature of the augmented function. -* The augmentation chain has two or more specifications of a default value - for the same optional parameter. This is an error even in the case where - all of them are identical. *Default values are defined by the introductory - function or an augmentation, but at most once.* +* More than one declaration in the augmentation chain specifies a default + value for the same optional parameter. This is an error even in the + case where all of them are identical. *Default values are defined by + the introductory function or an augmentation, but at most once.* -* The augmentation chain has no specifications of a default value for an - optional parameter whose declared type is potentially non-nullable, and - the declared function is not abstract. +* No declaration in the augmentation chain specifies a default value for + an optional parameter whose declared type is potentially non-nullable, + and the declared function is not abstract. * A function is not complete after all augmentations are applied, unless it's an instance member and the surrounding class is abstract. *Every function @@ -890,17 +890,17 @@ It's a **compile-time error** if: * The signature of the augmenting function does not [match][signature matching] the signature of the augmented function. -* The augmentation chain has two or more specifications of a default value - for the same optional parameter. This is an error even in the case where - all of them are identical. *Default values are defined by the introductory - declaration or an augmentation, but at most once.* +* More than one declaration in the augmentation chain specifies a default + value for the same optional parameter. This is an error even in the + case where all of them are identical. *Default values are defined by + the introductory declaration or an augmentation, but at most once.* * The augmentation chain has exactly one specification of a default value for an optional parameter, and the constructor is a redirecting factory. -* The augmentation chain has no specifications of a default value for an - optional parameter whose declared type is potentially non-nullable, and - the constructor is not a redirecting factory. +* No declaration in the augmentation chain specifies a default value for + an optional parameter whose declared type is potentially non-nullable, + and the constructor is not a redirecting factory. * The introductory constructor is `const` and the augmenting constructor is not, or vice versa. *An augmentation can't change whether or not a