Rework javascript getProperty API to handle missing properties better

fishface60 commented 2 weeks ago

Identify the Bug or Feature request

closes https://github.com/RPTools/maptool/issues/3028

Description of the Change

This changes the javascript getProperty function to look up the value in the campaign property type defaults if it's missing, and return null instead of "null" if you don't have permission to get that token's properties or the campaign doesn't have that property either, for improved ergonomics of null-handling in javascript.

This also adds getRawProperty which returns null if it's not set, and getEvaluatedProperty which may evaluate the value as a macro.

Possible Drawbacks

If users of getProperty were checking for the value being missing with something like:

let value = token.getProperty(name);
if (value == "null") {
    value = "10";
}

then this will now end up with value being null.

getProperty is the most desirable name for the most common operation. It's possible that most campaigns use properties that should be evaluated so should use the shorter name, and the form of getProperty that only falls back to the default value should be called something like getUnevaluatedProperty or getDefaultedProperty.

Release Notes

Made token.getProperty return null instead of the string "null" when properties are missing or not permitted to be read.
Make token.getProperty return the default value for the token type if the value was not set on the token.
Added token.getRawProperty for uses that shouldn't fall back to defaults and token.getEvaluatedProperty for uses that should use calculated defaults.

This change is

fishface60 commented 2 weeks ago

I'll have a poke at CI failures this evening.

cwisniew commented 2 weeks ago

I'll have a poke at CI failures this evening.

They are formatting errors you can fix with ./gradlew spotlessApply (or .\grqladlew.bat spotlessApply of using windows)

fishface60 commented 2 weeks ago

I'll have a poke at CI failures this evening.

They are formatting errors you can fix with ./gradlew spotlessApply (or .\grqladlew.bat spotlessApply of using windows)

I even told myself "You should run that before submitting". I blame staying up until 11PM because the current token behaviour had been bothering me for long enough and doing bindings token status bars brought me close enough to the code to feel like I could do something about it.

RPTools / maptool