Expose default values for parameters to macros?

[jakemac53]

The macro apis today do not give access to default values for parameters (or initializer expressions for variables either).

When augmenting a function today you are not allowed to specify default values, so we probably don't need them in that case. However, when overriding a method with a new declaration in a class (so you aren't augmenting an existing method/constructor, you are specifying a new one, which is an override), you do likely need access to the default values of the original parameters.

We could likely only provide these as Code objects and not values (the values might be user types, have unresolved identifiers, etc). But that should be sufficient as the use case is really just plopping in the same default value.

Concerns

I am concerned that in the case of unresolved identifiers (that will be produced in phase 2), we can't even always produce a valid augmentation library (at least in phase 1, although it would be challenging even in phase 2).

Consider a macro that runs in phase one, but it creates a type that extends some other type and overrides some members. Generally that would be hard to actually do since you can't introspect over members, but the macro could actually live on a member, something like this:

class A {
  @SomeMacro()
  void foo([int x = y]); // y is generated in phase 2!
}

// Generated in phase one, how do we refer to y properly if we don't know where it comes from?
class B extends A {
  void foo([int x = y])
}

Possibly we could just assume that any unresolved identifier will eventually exist in the current library, and not do any prefix. But that seems sketchy.

Other options

Alternatively, could we add a way of referring to the overridden default value? This would be generally useful, and would avoid the issue entirely. Maybe something like void foo({super.x}) or void foo({int x = super.default})?

[jakemac53]

cc @yanok @munificent

[lrhn]

If you can add a default value later, you can start by declaring

class B extends A {
  void foo([int x]);
}

in phase one, then add the = y in phase two.

I'm more interested in how you give access to an existing default value to the macro, so that it can use it elsewhere, like:

class C {
  C([int x = _someConstant]);
}

and you want to create a class:

class D extends C {
  C([int x = _someConstant]) : assert(x > 0), super(x);
}

in another library. You can't necessarily copy expressions from one context to another, and there isn't always a way to express a constant value in another library using Dart source at all.

[jakemac53]

If you can add a default value later

This is explicitly disallowed right now (augmentations in general cannot alter default values). For new methods in an augmentation if you define them in phase one (can only do this if also declaring a type), then if you do anything to them in phase two that is an augmentation of the one defined in phase one.

We could change how that works but it is much easier to think about things that way generally (each phases output is essentially an augmentation of the original library + previous phases augmentations).

I'm more interested in how you give access to an existing default value to the macro, so that it can use it elsewhere, like:

Good point regarding private identifiers, this is not something we can allow. It is a general problem for overrides though. Maybe this is another reason to go with a language feature, as it does solve a general problem that isn't macro specific?

[yanok]

+1 to what Lasse says. I think semantically default values are part of definition, not declaration. So maybe you should allow producing default values as part of definition phase and maybe this will simplify the resolution?

This of course means that function augmentation would have to support adding arguments' default parameters; for this use case it would be fine to restrict it to only support declarations with no definition, so we are not altering default values, just delaying their generation till the definition phase where they belong.

Private identifiers are painful in this respect, language feature would be nice. It doesn't help with my plans to rewrite Mockito, since I would need to grab v from A.m([int x = v]) while generating a class that doesn't extend A. A more general way to access default arguments, something like A.m.defaultArguments.x would help, but I don't really expect this to be ever implemented.

[jakemac53]

I think semantically default values are part of definition, not declaration. So maybe you should allow producing default values as part of definition phase and maybe this will simplify the resolution?

I consider them more a part of the API, they are an interesting/important part of the declaration itself. It is a grey area though, I could see an argument either way. But you generally can't change the default value and consider that non-breaking, as an example.

This of course means that function augmentation would have to support adding arguments' default parameters; for this use case it would be fine to restrict it to only support declarations with no definition, so we are not altering default values, just delaying their generation till the definition phase where they belong.

My main concern with this is just that it isn't something we can enforce statically - so it introduces a new category of runtime error that macro authors will have to manage (if they try to add a default value but one already exists).

I would much rather go with a language feature of some sort to avoid the situation entirely.

[jakemac53]

Also from a more concrete design perspective, the definition phase currently has the property that ordering does not matter, it can be fully concurrent (at least in terms of running the macros, their results must appear in a certain order still though to get a consistent augmentation).

If you can add default values, but only once, we lose that property. We also have to keep track during execution of macros whether or not a previous macro has added a default value, which adds an extra complication and cost that we don't have today. I don't think it provides enough value to be worth the complication or the runtime cost.

[lrhn]

Can an augmentation add a default value, if used by itself?

I'd personally expect the choice of everywhere to have a default value, or at least which default value, to be a late choice, like when you choose whether the function body is async or not. It's part of the function implementation, not its signature.
Maybe having a non-nullable optional parameter screams "must have a default value", but that just means it'll be an error if you don't add one before the program must be complete, like other macro "full in the blanks".

[jakemac53]

Can an augmentation add a default value, if used by itself?

The general principle we have been following is that augmentations cannot affect the API of functions. You should be able to use them exactly as they appear in code, and not have magic extra parameters appear (and especially not have a parameter change types or something).

Whether that same logic should apply to default values is not is not very clear-cut, but the current decision is that yes it does. We do not allow adding default values at all via augmentation.

Personally I think that is the correct choice, because I do think they are a part of the API contract - at least sometimes. For instance if I have this function String substring(String original, [int length = 1]), clearly the default value of length is a part of the API contract. If it changed, lots of code would break.

Maybe having a non-nullable optional parameter screams "must have a default value", but that just means it'll be an error if you don't add one before the program must be complete, like other macro "full in the blanks".

I think this argument is sensible, a savvy enough reader should know that there must be a default value somewhere, and a smart enough IDE plugin could even show it to you inline as if it was there.

But, I don't think there is a lot of value in it. For hand written augmentations you can just as easily put it in the original function. For macros I see a lot of issues (listed in previous comments).

[scheglov]

Personally I think that is the correct choice, because I do think they are a part of the API contract - at least sometimes. For instance if I have this function String substring(String original, [int length = 1]), clearly the default value of length is a part of the API contract. If it changed, lots of code would break.

Isn't the breakage orthogonal to where the default value is?
Is you change the "default" value here, clients also might break.

void f({int? a}) {
  a ??= 42;
  print(a);
}

[jakemac53]

Is you change the "default" value here, clients also might break.

That is a fair argument 🤷 . I am still hesitant about allowing macros to add default values though because it is difficult to enforce the "only allow it if it isn't already there" part. But we do already have some similar things, in the declarations phase. I would like to keep them at least constrained to that phase.

We could also just tell macro authors to use that pattern instead of regular default values.

[jakemac53]

cc @munificent thoughts?

[jakemac53]

#2269 looks like it would work as the language feature if we went that route