Skip to content

Add rules to allow omission of certain default values #4393

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 58 additions & 5 deletions working/augmentation-libraries/feature-specification.md
Original file line number Diff line number Diff line change
Expand Up @@ -450,7 +450,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:
Expand Down Expand Up @@ -768,13 +768,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; in this case, 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this might be a little more readable as: "More than one declaration in the augmentation chain specifies a default value for some optional parameter."

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Likewise here: "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
Expand Down Expand Up @@ -845,13 +877,27 @@ 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This touches on #3690. With augmentations, it's also not a compile error for a static method declaration to have a ; body, for a constructor declaration to not have initializers are all final instance fields, etc. As long as the final declaration ("definition"?) once all augmentations have been applied is valid, it's fine.

I'm not sure to what degree we want to spell this all out in the proposal but I'm cautious about having too much normative text that is potentially redundant or implied by other parts of the proposal. I don't want implementers to have to read between the lines to figure out what the proposal is saying, but I also don't want them to have to compare paragraphs and try to tell if the two paragraphs are defining different things or just restating a point. Finding the right balance here is hard.

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this error needed? This means that if the introductory declaration has a default value, the augmentation is prohibited from filling in a redirectory factory.

How about we just treat default values in redirecting factory constructors the same way we do abstract methods: they are meaningless documentation. You can write it but it won't do anything.


* 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
Expand All @@ -863,6 +909,13 @@ It's a **compile-time error** if:
not a constructor is generative because that affects whether users are
allowed to call the constructor in a subclass's initializer list.*

* More than one constructor declaration in an augmentation chain specifies
a default value for the same parameter.

* A constructor declaration in an augmentation chain is a redirecting
factory, and some declaration in the chain specifies a default value
for one or more parameters.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See my previous comment. :)


An incomplete constructor can be completed by adding an initializer list and/or
a body, or by adding a redirection:

Expand Down