Add additional mutation helpers for containers (#786)

* Add additional mutation helpers for containers

Author: CedNaru

kt/api-generator/src/main/kotlin/godot/codegen/generation/rule/PropertyRule.kt

@@ -1,7 +1,9 @@
 package godot.codegen.generation.rule
 
 import com.squareup.kotlinpoet.AnnotationSpec
+import com.squareup.kotlinpoet.ClassName
 import com.squareup.kotlinpoet.FunSpec
+import com.squareup.kotlinpoet.INT
 import com.squareup.kotlinpoet.KModifier
 import com.squareup.kotlinpoet.LambdaTypeName
 import com.squareup.kotlinpoet.ParameterSpec
@@ -15,6 +17,7 @@ import godot.codegen.models.enriched.EnrichedClass
 import godot.codegen.models.enriched.EnrichedProperty
 import godot.tools.common.constants.CORE_TYPE_HELPER
 import godot.tools.common.constants.CORE_TYPE_LOCAL_COPY
+import godot.tools.common.constants.GodotTypes.localCopyCoreTypesMap
 
 class PropertyRule : GodotApiRule<EnrichedPropertyTask>() {
     override fun apply(task: EnrichedPropertyTask, context: GenerationContext) = configure(task.builder) {
@@ -113,28 +116,36 @@ class PropertyRule : GodotApiRule<EnrichedPropertyTask>() {
                     .build()
             )
         }
-
-        if (property.type.isLocalCopyCoreTypes()) {
-            addAnnotation(CORE_TYPE_LOCAL_COPY)
-        }
-
         addKdoc(property)
     }
 }
 
-class CoreTypeHelperRule : GodotApiRule<EnrichedClassTask>() {
+class LocalCopyHelperRule : GodotApiRule<EnrichedClassTask>() {
     override fun apply(task: EnrichedClassTask, context: GenerationContext) = with(task.builder) {
         val clazz = task.clazz
         for (propertyTask in task.enrichedProperties) {
             val property = propertyTask.property
-            if (property.hasSetter && property.type.isLocalCopyCoreTypes()) {
-                addFunction(getHelper(clazz, property))
-            }
+            if (!property.hasSetter || !property.type.isLocalCopyCoreTypes()) continue
+
+            propertyTask.builder.addAnnotation(CORE_TYPE_LOCAL_COPY)
+            propertyTask.builder.addKdoc(
+                """|
+                   |
+                   |**Warning:**
+                   |Be careful when trying to modify a local [copy](https://godot-kotl.in/en/stable/user-guide/api-differences/#core-types) obtained from this getter.
+                   |Mutating it alone won't have any effect on the actual property, it has to be reassigned again afterward.
+                   |""".trimMargin()
+            )
+            addFunction(getMutateHelper(clazz, property))
+
+            if (!property.type.isLocalIndexedCopyCoreTypes()) continue
 
+            val className = localCopyCoreTypesMap[property.type.identifier]!!
+            addFunction(getMutateEachHelper(property, className))
         }
     }
 
-    private fun getHelper(clazz: EnrichedClass, property: EnrichedProperty): FunSpec {
+    private fun getMutateHelper(clazz: EnrichedClass, property: EnrichedProperty): FunSpec {
         val parameterTypeName = property.getCastedType()
         val parameterName = property.name
 
@@ -153,24 +164,14 @@ class CoreTypeHelperRule : GodotApiRule<EnrichedClassTask>() {
             .addAnnotation(CORE_TYPE_HELPER)
             .returns(parameterTypeName)
             .addStatement(
-                """return $parameterName.apply{
-                |    block(this)
-                |    $parameterName = this
-                |}
-                |""".trimMargin()
+                """return·$parameterName.apply·{
+                |   block(this)
+                |   $parameterName·=·this
+                |}""".trimMargin()
             ).apply {
                 val kDoc = buildString {
-                    val propertyKdoc = property.description
-                    if (propertyKdoc != null && propertyKdoc.isNotBlank()) {
-                        appendLine(propertyKdoc)
-                        appendLine()
-                    }
-
                     appendLine(
-                        """This is a helper function to make dealing with local copies easier.
-                        |
-                        |For more information, see our [documentation](https://godot-kotl.in/en/stable/user-guide/api-differences/#core-types).
-                        |
+                        """This is a helper function for [$parameterName] to make dealing with local copies easier.
                         |Allow to directly modify the local copy of the property and assign it back to the Object.
                         |
                         |Prefer that over writing:
@@ -181,6 +182,59 @@ class CoreTypeHelperRule : GodotApiRule<EnrichedClassTask>() {
                         |``````
                         |""".trimMargin()
                     )
+
+
+                    val propertyKdoc = property.description
+                    if (propertyKdoc != null && propertyKdoc.isNotBlank()) {
+                        appendLine(propertyKdoc)
+                        appendLine()
+                    }
+                }
+                addKdoc(kDoc)
+            }.build()
+    }
+
+    private fun getMutateEachHelper(property: EnrichedProperty, elementType: ClassName): FunSpec {
+        val parameterTypeName = property.getCastedType()
+        val parameterName = property.name
+
+        val propertyFunSpec = FunSpec.builder("${parameterName}MutateEach").addModifiers(KModifier.FINAL)
+
+        val lambdaType =  ParameterSpec.builder(
+            "block",
+            LambdaTypeName.get(
+                parameters = listOf(
+                    ParameterSpec.builder("index", INT).build(),
+                    ParameterSpec.builder("value", elementType).build()
+                ),
+                returnType = UNIT
+            )).build()
+
+        return propertyFunSpec
+            .addParameter(lambdaType)
+            .addAnnotation(CORE_TYPE_HELPER)
+            .returns(parameterTypeName)
+            .addStatement(
+                """return·$parameterName.apply·{
+                |   this.forEachIndexed {·index,·value·->
+                |       block(index,·value)
+                |       this[index]·=·value
+                |   }
+                |   $parameterName·=·this
+                |}""".trimMargin()
+            ).apply {
+                val kDoc = buildString {
+                    appendLine(
+                        """This is a helper function for [$parameterName] to make dealing with local copies easier.
+                        |Allow to directly modify each element of the local copy of the property and assign it back to the Object.
+                        |""".trimMargin()
+                    )
+
+                    val propertyKdoc = property.description
+                    if (propertyKdoc != null && propertyKdoc.isNotBlank()) {
+                        appendLine(propertyKdoc)
+                        appendLine()
+                    }
                 }
                 addKdoc(kDoc)
             }.build()

kt/api-generator/src/main/kotlin/godot/codegen/models/traits/GenerationType.kt

@@ -83,6 +83,7 @@ interface TypeGenerationTrait {
     fun isCoreType() = nature == Nature.CORE || nature == Nature.TYPED_ARRAY
     fun isPrimitive() = nature == Nature.PRIMITIVE
     fun isLocalCopyCoreTypes() = GodotTypes.localCopyCoreTypes.find { s -> s == identifier } != null
+    fun isLocalIndexedCopyCoreTypes() = GodotTypes.indexedLocalCopyCoreTypes.find { s -> s == identifier } != null
     fun isEnum() = nature == Nature.ENUM
     fun isBitField() = nature == Nature.BITFIELD
     fun isTypedArray() = nature == Nature.TYPED_ARRAY

kt/api-generator/src/main/kotlin/godot/codegen/services/impl/ApiGenerationService.kt

@@ -6,7 +6,7 @@ import godot.codegen.generation.rule.BindingRule
 import godot.codegen.generation.rule.BitfieldExtensionRule
 import godot.codegen.generation.rule.ConstantRule
 import godot.codegen.generation.rule.CoreRule
-import godot.codegen.generation.rule.CoreTypeHelperRule
+import godot.codegen.generation.rule.LocalCopyHelperRule
 import godot.codegen.generation.rule.DocumentationRule
 import godot.codegen.generation.rule.EnrichedClassRule
 import godot.codegen.generation.rule.EnrichedCoreRule
@@ -63,7 +63,7 @@ class ApiGenerationService(
                     subRule(EnrichedClassTask::enrichedMethods, ::OverLoadRule)
                     subRule(EnrichedClassTask::enrichedStaticMethods, ::OverLoadRule)
                     rule(::BindingRule)
-                    rule(::CoreTypeHelperRule)
+                    rule(::LocalCopyHelperRule)
                 }
                 subRule(FileTask::enums, ::EnumRule)
                 rule(::StaticRule)

kt/godot-library/godot-api-library/src/main/kotlin/godot/api/AStarGrid2D.kt

@@ -79,6 +79,13 @@ public open class AStarGrid2D : RefCounted() {
   /**
    * The region of grid cells available for pathfinding. If changed, [update] needs to be called
    * before finding the next path.
+   *
+   * **Warning:**
+   * Be careful when trying to modify a local
+   * [copy](https://godot-kotl.in/en/stable/user-guide/api-differences/#core-types) obtained from this
+   * getter.
+   * Mutating it alone won't have any effect on the actual property, it has to be reassigned again
+   * afterward.
    */
   @CoreTypeLocalCopy
   public final inline var region: Rect2i
@@ -92,6 +99,13 @@ public open class AStarGrid2D : RefCounted() {
   /**
    * The size of the grid (number of cells of size [cellSize] on each axis). If changed, [update]
    * needs to be called before finding the next path.
+   *
+   * **Warning:**
+   * Be careful when trying to modify a local
+   * [copy](https://godot-kotl.in/en/stable/user-guide/api-differences/#core-types) obtained from this
+   * getter.
+   * Mutating it alone won't have any effect on the actual property, it has to be reassigned again
+   * afterward.
    */
   @CoreTypeLocalCopy
   public final inline var size: Vector2i
@@ -105,6 +119,13 @@ public open class AStarGrid2D : RefCounted() {
   /**
    * The offset of the grid which will be applied to calculate the resulting point position returned
    * by [getPointPath]. If changed, [update] needs to be called before finding the next path.
+   *
+   * **Warning:**
+   * Be careful when trying to modify a local
+   * [copy](https://godot-kotl.in/en/stable/user-guide/api-differences/#core-types) obtained from this
+   * getter.
+   * Mutating it alone won't have any effect on the actual property, it has to be reassigned again
+   * afterward.
    */
   @CoreTypeLocalCopy
   public final inline var offset: Vector2
@@ -118,6 +139,13 @@ public open class AStarGrid2D : RefCounted() {
   /**
    * The size of the point cell which will be applied to calculate the resulting point position
    * returned by [getPointPath]. If changed, [update] needs to be called before finding the next path.
+   *
+   * **Warning:**
+   * Be careful when trying to modify a local
+   * [copy](https://godot-kotl.in/en/stable/user-guide/api-differences/#core-types) obtained from this
+   * getter.
+   * Mutating it alone won't have any effect on the actual property, it has to be reassigned again
+   * afterward.
    */
   @CoreTypeLocalCopy
   public final inline var cellSize: Vector2
@@ -196,14 +224,7 @@ public open class AStarGrid2D : RefCounted() {
   }
 
   /**
-   * The region of grid cells available for pathfinding. If changed, [update] needs to be called
-   * before finding the next path.
-   *
-   * This is a helper function to make dealing with local copies easier.
-   *
-   * For more information, see our
-   * [documentation](https://godot-kotl.in/en/stable/user-guide/api-differences/#core-types).
-   *
+   * This is a helper function for [region] to make dealing with local copies easier.
    * Allow to directly modify the local copy of the property and assign it back to the Object.
    *
    * Prefer that over writing:
@@ -212,23 +233,18 @@ public open class AStarGrid2D : RefCounted() {
    * //Your changes
    * astargrid2d.region = myCoreType
    * ``````
+   *
+   * The region of grid cells available for pathfinding. If changed, [update] needs to be called
+   * before finding the next path.
    */
   @CoreTypeHelper
-  public final fun regionMutate(block: Rect2i.() -> Unit): Rect2i = region.apply{
-      block(this)
-      region = this
+  public final fun regionMutate(block: Rect2i.() -> Unit): Rect2i = region.apply {
+     block(this)
+     region = this
   }
 
-
   /**
-   * The size of the grid (number of cells of size [cellSize] on each axis). If changed, [update]
-   * needs to be called before finding the next path.
-   *
-   * This is a helper function to make dealing with local copies easier.
-   *
-   * For more information, see our
-   * [documentation](https://godot-kotl.in/en/stable/user-guide/api-differences/#core-types).
-   *
+   * This is a helper function for [size] to make dealing with local copies easier.
    * Allow to directly modify the local copy of the property and assign it back to the Object.
    *
    * Prefer that over writing:
@@ -237,23 +253,18 @@ public open class AStarGrid2D : RefCounted() {
    * //Your changes
    * astargrid2d.size = myCoreType
    * ``````
+   *
+   * The size of the grid (number of cells of size [cellSize] on each axis). If changed, [update]
+   * needs to be called before finding the next path.
    */
   @CoreTypeHelper
-  public final fun sizeMutate(block: Vector2i.() -> Unit): Vector2i = size.apply{
-      block(this)
-      size = this
+  public final fun sizeMutate(block: Vector2i.() -> Unit): Vector2i = size.apply {
+     block(this)
+     size = this
   }
 
-
   /**
-   * The offset of the grid which will be applied to calculate the resulting point position returned
-   * by [getPointPath]. If changed, [update] needs to be called before finding the next path.
-   *
-   * This is a helper function to make dealing with local copies easier.
-   *
-   * For more information, see our
-   * [documentation](https://godot-kotl.in/en/stable/user-guide/api-differences/#core-types).
-   *
+   * This is a helper function for [offset] to make dealing with local copies easier.
    * Allow to directly modify the local copy of the property and assign it back to the Object.
    *
    * Prefer that over writing:
@@ -262,23 +273,18 @@ public open class AStarGrid2D : RefCounted() {
    * //Your changes
    * astargrid2d.offset = myCoreType
    * ``````
+   *
+   * The offset of the grid which will be applied to calculate the resulting point position returned
+   * by [getPointPath]. If changed, [update] needs to be called before finding the next path.
    */
   @CoreTypeHelper
-  public final fun offsetMutate(block: Vector2.() -> Unit): Vector2 = offset.apply{
-      block(this)
-      offset = this
+  public final fun offsetMutate(block: Vector2.() -> Unit): Vector2 = offset.apply {
+     block(this)
+     offset = this
   }
 
-
   /**
-   * The size of the point cell which will be applied to calculate the resulting point position
-   * returned by [getPointPath]. If changed, [update] needs to be called before finding the next path.
-   *
-   * This is a helper function to make dealing with local copies easier.
-   *
-   * For more information, see our
-   * [documentation](https://godot-kotl.in/en/stable/user-guide/api-differences/#core-types).
-   *
+   * This is a helper function for [cellSize] to make dealing with local copies easier.
    * Allow to directly modify the local copy of the property and assign it back to the Object.
    *
    * Prefer that over writing:
@@ -287,14 +293,16 @@ public open class AStarGrid2D : RefCounted() {
    * //Your changes
    * astargrid2d.cellSize = myCoreType
    * ``````
+   *
+   * The size of the point cell which will be applied to calculate the resulting point position
+   * returned by [getPointPath]. If changed, [update] needs to be called before finding the next path.
    */
   @CoreTypeHelper
-  public final fun cellSizeMutate(block: Vector2.() -> Unit): Vector2 = cellSize.apply{
-      block(this)
-      cellSize = this
+  public final fun cellSizeMutate(block: Vector2.() -> Unit): Vector2 = cellSize.apply {
+     block(this)
+     cellSize = this
   }
 
-
   /**
    * Called when estimating the cost between a point and the path's ending point.
    *