API functions: Parameters with "Optional" tag should pass nullptr

[juliansader]

Optional parameters can be added to extension-provided API functions by adding the "Optional" suffix to parameter names:

// When defining/documenting API function parameters:
// - if a (char*,int) pair is encountered, name them buf, buf_sz
// - if a (const char*,int) pair is encountered, buf, buf_sz as well
// - if a lone basicType *, use varNameOut or varNameIn or
// varNameInOptional (if last parameter(s))

However, there are two problems with optional parameters, both of which (as far as I can see) make it impossible for extensions to know which arguments were passed by the script and which were not:

* Even though extensions should register a "vararg" wrapper function for each API function, and this "vararg" function takes two arguments, (void* arglist[], int numparms), this isn't truly a variadic function since numparms is always the same, namely the total number of possible parameters, including all optional ones.

* As implied by the previous point, optional parameters that are omitted by the scripts are still all included in the arglist[]. This would have been acceptable, if the extension could somehow distinguish omitted parameters, for example if omitted parameters were NULL pointers (NB: optional parameters are always pointers). However, omitted parameters are not NULL pointers; instead they look like normal parameters and they simply point to zero values. From the extension's perspective, there is no difference between an omitted parameter and a parameter with argument 0.


Optional parameters are very useful, particularly to expand the features of an existing API function without breaking existing scripts.

There are two possible solutions:
* numparms should reflect the actual number of arguments passed, or
* omitted parameters should be nullptr.

[nofish]

I ran into this too:
https://forum.cockos.com/showthread.php?t=221102

[schwa]

Looking at the code on our side, optional arguments from Lua to extension-provided functions should work for REAPER-specific datatypes (like MediaTrack*, etc), but not int, double, etc. Does that match what you're seeing?

[nofish]

Thanks schwa.
I can define an extension-provided function which takes e.g. an int* as optional argument and that function can be called fine (i.e. without error) from ReaScript also if the caller doesn't provide the optional argument. (In case the caller does provide the argument, it gets assigned to the pointer correctly.)
edit:
I haven't tried this with REAPER-specific datatypes yet though.

The issue is that the extension can't differentiate if the caller provided the additional argument or not because Reaper always assigns 0 (zero value) to it (see OP).

Therefore we're suggesting that a nullptr is assigned / passed in case the caller doesn't provide an optional argument instead of assigning zero value.
Does this address your question?

[schwa]

I'm saying that for REAPER-specific datatypes like MediaTrack*, NULL is passed if the script doesn't supply the parameter. The missing piece is that this doesn't also happen for pointers to plain datatypes.

[nofish]

Sorry, wasn't sure what you mean by 'should work' exactly but yep, that seems it.

[juliansader]

v5.979 has improved this problem:

Originally Posted by Edgemeal

+ ReaScript: support optional arguments in extension-supplied functions when called from Lua [t=219455]

However, there are still a few remaining problems:

* If the "Optional" suffix is added to a parameter name, only char* is named "optional string" in the API help -- all the others have incorrect names such as "identifier" or "unsupported".

* If the "InOptional" suffix is used, double* is now correctly named "optional number", while int* becomes "optional number" instead of "optional integer", and the rest remain incorrect. (Unlike the "Optional" suffix, the "In" suffix is not removed by the API help.)

* An optional char* parameter doesn't pass a NULL pointer to the extension when the script doesn't supply the parameter.