update
Applies an eager transformation to the current value of the property "in place", without explicitly obtaining it. The provided transformer is applied to the provider of the current value, and the returned provider is used as a new value. The provider of the value can be used to derive the new value, but doesn't have to. Returning null from the transformer unsets the property. For example, the current value of a string map property can be filtered to retain only vowel keys:
def property = objects.mapProperty(String, String).value(a: "a", b: "b")
property.update { it.map { value -> value.subMap("a", "e", "i", "o", "u") } }
println(property.get()) // [a: "a"]
property.set(property.map { ... }
doesn't work and will cause an exception because of a circular reference evaluation at runtime. Further changes to the value of the property, such as calls to set, are not transformed, and override the update instead. Because of this, this method inherently depends on the order of property changes, and therefore must be used sparingly.
If the value of the property is specified via a provider, then the current value provider tracks that provider. For example, changes to the upstream property are visible:
def upstream = objects.mapProperty(String, String).value(a: "a", b: "b")
def property = objects.mapProperty(String, String).value(upstream)
property.update { it.map { value -> value.subMap("a", "e", "i", "o", "u") } }
upstream.value(e: "e", f: "f")
println(property.get()) // [e: "e"]
If the property has no explicit value set, then the current value comes from the convention. Changes to convention of this property do not affect the current value provider in this case, though upstream changes are still visible if the convention was set to a provider. If there is no convention too, then the current value is a provider without a value. The updated value becomes the explicit value of the property.
Parameters
the transformation to apply to the current value. May return null, which unsets the property.