Standardization of Macro Function

[stolkun]

Is your feature request related to a problem? Please describe.
It's rather unclear when i have to use macros with grid distance wether i should precise the units or not.
For example copyToken argument "useDistance" is default to false meaning it use Distance per Cell.
While getTokenX or getTokenY argument "units" is default to true meaning it use Distance in pixel.
Example of use: i wanted to copyToken to my current token so i used getToken and because i didn't precise the units for any thinking it would be the same, my pixels units of getToken transformed in cell which copied my token extremely far.

Describe the solution you'd like
I would like a standardization of macro function on the units they use if possible so that there is no confusion in the usage of those macros.

Additional context
https://lmwcs.com/rptools/wiki/getTokenX
https://lmwcs.com/rptools/wiki/copyToken

[Merudo]

I would love that too.

Unfortunately, wouldn't such a standardization break backward compatibility?

[stolkun]

Well i guess it would but better to change early and not always have this problem. Anyway in the release note they could warn of this change no ?

[JamzTheMan]

Change early? Both of those functions have been around for quite a while (1.3b51) so they are going to be used in frameworks all over the place unfortunately.

The sad thing is, there's not an easy way (yet) to search and replace through all macros to make a change in a framework. And with UDF's and macro calls, it's hard to tell from just the error what macro that function would be called in to make the change.

Furthermore, a lot of people "use" other people's frameworks and unless the author corrected the framework a lot of people would be unable to fix it themselves.

It's not a bad idea, there are a LOT of functions that have grown and morphed over the decade but the ramifications on changing function signatures is bad.

[Azhrei]

All true. :)

Part of the problem, as Jamz says, is the sheer number of functions that currently exist. As new functions are created, an approach that unifies parameters (perhaps using JSON objects and/or arrays) should be adopted. Over time, older functions can be deprecated, and because the newer ones are using this mystical "unified" API, we end up with a more consistent function API.

The key phrase there is over time...

[Merudo]

Personally I would love for function names to be standardized to something similar to what Mote was doing with their dot notation.

My proposed change would be something like

getTokenX -> token.x.get
setTokenHeight -> token.height.set
hasSight -> token.sight.has
hasLightSource -> token.lightsource.has
setMapName -> map.name.set
playStream -> media.stream.play
closeFrame -> frame.close
addToInitiative -> initiative.add

The main benefit is that MapTool could then provide the list of functions related to an element. So for example if the user types token., a list pops up to display every function that works on tokens.

[Azhrei]

Yeah, that sounds good. I was originally thinking of JSON as parameters because it makes it flexible. The problem with lots of function names is that invoking them generically isn't possible without a lot of rigamarole in MTscript. But I definitely like the idea of the popup help in the macro editor...

[stolkun]

Well then i will left the thread open to let the idea open but if you deem it useless close it :)

[bubblobill]

Right then, so all we need is a refactoring tool and all those existing uses will be sorted. I vote for not me.