Deprecate buildStruct() in favor of idiomatic ionStructOf() overloads (#99)

Author: popematt

api/IonElement.api

@@ -301,13 +301,19 @@ public final class com/amazon/ionelement/api/Ion {
 	public static final fun ionStructOf (Ljava/lang/Iterable;Ljava/util/List;)Lcom/amazon/ionelement/api/StructElement;
 	public static final fun ionStructOf (Ljava/lang/Iterable;Ljava/util/List;Ljava/util/Map;)Lcom/amazon/ionelement/api/StructElement;
 	public static final fun ionStructOf (Ljava/lang/Iterable;Ljava/util/Map;)Lcom/amazon/ionelement/api/StructElement;
+	public static final fun ionStructOf (Ljava/util/List;Ljava/util/Map;Ljava/util/function/Consumer;)Lcom/amazon/ionelement/api/StructElement;
+	public static final synthetic fun ionStructOf (Ljava/util/List;Ljava/util/Map;Lkotlin/jvm/functions/Function1;)Lcom/amazon/ionelement/api/StructElement;
+	public static final fun ionStructOf (Ljava/util/List;Ljava/util/function/Consumer;)Lcom/amazon/ionelement/api/StructElement;
+	public static final fun ionStructOf (Ljava/util/function/Consumer;)Lcom/amazon/ionelement/api/StructElement;
 	public static final fun ionStructOf ([Lcom/amazon/ionelement/api/StructField;)Lcom/amazon/ionelement/api/StructElement;
 	public static final fun ionStructOf ([Lcom/amazon/ionelement/api/StructField;Ljava/util/List;)Lcom/amazon/ionelement/api/StructElement;
 	public static final fun ionStructOf ([Lcom/amazon/ionelement/api/StructField;Ljava/util/List;Ljava/util/Map;)Lcom/amazon/ionelement/api/StructElement;
 	public static final fun ionStructOf ([Lkotlin/Pair;)Lcom/amazon/ionelement/api/StructElement;
 	public static final fun ionStructOf ([Lkotlin/Pair;Ljava/util/List;)Lcom/amazon/ionelement/api/StructElement;
 	public static final fun ionStructOf ([Lkotlin/Pair;Ljava/util/List;Ljava/util/Map;)Lcom/amazon/ionelement/api/StructElement;
 	public static synthetic fun ionStructOf$default (Ljava/lang/Iterable;Ljava/util/List;Ljava/util/Map;ILjava/lang/Object;)Lcom/amazon/ionelement/api/StructElement;
+	public static synthetic fun ionStructOf$default (Ljava/util/List;Ljava/util/Map;Ljava/util/function/Consumer;ILjava/lang/Object;)Lcom/amazon/ionelement/api/StructElement;
+	public static synthetic fun ionStructOf$default (Ljava/util/List;Ljava/util/Map;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/amazon/ionelement/api/StructElement;
 	public static synthetic fun ionStructOf$default ([Lcom/amazon/ionelement/api/StructField;Ljava/util/List;Ljava/util/Map;ILjava/lang/Object;)Lcom/amazon/ionelement/api/StructElement;
 	public static synthetic fun ionStructOf$default ([Lkotlin/Pair;Ljava/util/List;Ljava/util/Map;ILjava/lang/Object;)Lcom/amazon/ionelement/api/StructElement;
 	public static final fun ionSymbol (Ljava/lang/String;)Lcom/amazon/ionelement/api/SymbolElement;

src/main/kotlin/com/amazon/ionelement/api/Ion.kt

@@ -18,6 +18,7 @@ package com.amazon.ionelement.api
 
 import com.amazon.ion.Decimal
 import com.amazon.ion.Timestamp
+import com.amazon.ionelement.impl.*
 import com.amazon.ionelement.impl.BigIntIntElementImpl
 import com.amazon.ionelement.impl.BlobElementImpl
 import com.amazon.ionelement.impl.BoolElementImpl
@@ -34,6 +35,7 @@ import com.amazon.ionelement.impl.StructFieldImpl
 import com.amazon.ionelement.impl.SymbolElementImpl
 import com.amazon.ionelement.impl.TimestampElementImpl
 import java.math.BigInteger
+import java.util.function.Consumer
 import kotlinx.collections.immutable.PersistentList
 import kotlinx.collections.immutable.persistentListOf
 import kotlinx.collections.immutable.toPersistentList
@@ -472,7 +474,45 @@ public fun ionStructOf(
         metas
     )
 
+@JvmSynthetic
+public fun ionStructOf(
+    annotations: Annotations = emptyList(),
+    metas: MetaContainer = emptyMetaContainer(),
+    builder: MutableStructFields.() -> Unit
+): StructElement {
+    return ionStructOf(emptyIonStruct().mutableFields().apply(builder), annotations, metas)
+}
+
+@JvmOverloads
+public fun ionStructOf(
+    annotations: Annotations = emptyList(),
+    metas: MetaContainer = emptyMetaContainer(),
+    builder: Consumer<MutableStructFields>
+): StructElement {
+    val fields = emptyIonStruct().mutableFields()
+    builder.accept(fields)
+    return ionStructOf(fields, annotations, metas)
+}
+
+@Deprecated("Use `com.amazon.ionelement.api.Ion.ionStructOf()` instead")
 @JvmOverloads
+/**
+ * For Kotlin, replace with:
+ * ```
+ * fun ionStructOf(
+ *     annotations: Annotations = emptyList(),
+ *     metas: MetaContainer = emptyMetaContainer(),
+ *     builder: MutableStructFields.() -> Unit
+ * ): StructElement
+ * ```
+ *
+ * For Java, replace with one of:
+ * ```
+ * StructElement ionStructOf(Consumer<MutableStructFields> builder)
+ * StructElement ionStructOf(List<String> annotations, Consumer<MutableStructFields> builder)
+ * StructElement ionStructOf(List<String> annotations, Map<String, Object> metas, Consumer<MutableStructFields> builder)
+ * ```
+ */
 public fun buildStruct(
     annotations: Annotations = emptyList(),
     metas: MetaContainer = emptyMetaContainer(),

src/main/kotlin/com/amazon/ionelement/api/MutableStructFields.kt

@@ -45,24 +45,32 @@ public interface MutableStructFields : MutableCollection<StructField> {
      */
     public fun add(fieldName: String, value: IonElement): Boolean
 
-    /** Adds the given field to the collection. The collection may have multiple fields with the same name.
+    /**
+     * Adds the given field to the collection. The collection may have multiple fields with the same name.
      *
-     * Repeated fields are allowed, so this will always return true. */
+     * Repeated fields are allowed, so this will always return true.
+     */
     public override fun add(element: StructField): Boolean
 
-    /** Removes a random occurrence of a field the matches the given field, or does nothing if no field exists.
+    /**
+     * Removes an arbitrary occurrence of a field the matches the given field, or does nothing if no field exists.
      *
-     * Returns true is a field was removed. */
+     * Returns true is a field was removed.
+     */
     public override fun remove(element: StructField): Boolean
 
-    /** Removes all occurrence of a field the matches the given field name, or does nothing if no field exists.
+    /**
+     * Removes all occurrences of a field the matches the given field name, or does nothing if no field exists.
      *
-     * Returns true if a field was removed. */
+     * Returns true if a field was removed.
+     */
     public fun clearField(fieldName: String): Boolean
 
-    /** Removes all of this collection's elements that are also contained in the specified collection.
+    /**
+     * Removes all of this collection's elements that are also contained in the specified collection.
      *
-     *  At most one field per element in the give collection is removed. */
+     * At most one field per element in the give collection is removed.
+     */
     public override fun removeAll(elements: Collection<StructField>): Boolean
 
     /** Adds all the given fields to the collection */

src/test/java/com/amazon/ionelement/demos/ConstructionDemo.java

@@ -1,4 +1,4 @@
-package com.amazon.ionelement.demos.java;
+package com.amazon.ionelement.demos;
 
 import com.amazon.ion.Decimal;
 import com.amazon.ion.Timestamp;

src/test/java/com/amazon/ionelement/demos/DemoBase.java

@@ -1,4 +1,4 @@
-package com.amazon.ionelement.demos.java;
+package com.amazon.ionelement.demos;
 
 import com.amazon.ionelement.api.AnyElement;
 import com.amazon.ionelement.api.ElementLoader;

src/test/java/com/amazon/ionelement/demos/ElementLoaderDemo.java

@@ -1,4 +1,4 @@
-package com.amazon.ionelement.demos.java;
+package com.amazon.ionelement.demos;
 
 import com.amazon.ion.IonReader;
 import com.amazon.ionelement.api.AnyElement;

src/test/java/com/amazon/ionelement/demos/MutableStructFieldsDemo.java renamed to src/test/java/com/amazon/ionelement/demos/MutableStructFieldsJavaDemo.java

@@ -1,22 +1,28 @@
-package com.amazon.ionelement.demos.java;
+package com.amazon.ionelement.demos;
 
 import com.amazon.ionelement.api.Ion;
 import com.amazon.ionelement.api.StructElement;
-import kotlin.Unit;
 import org.junit.jupiter.api.Test;
 
 import static com.amazon.ionelement.api.ElementLoader.loadSingleElement;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
-public class MutableStructFieldsDemo {
+public class MutableStructFieldsJavaDemo {
 
     @Test
     void createUpdatedStructFromExistingStruct() {
         StructElement original = loadSingleElement(
                 "{name:\"Alice\",scores:{darts:100,billiards:15,}}").asStruct();
 
-        StructElement expected = loadSingleElement(
-                "{name:\"Alice\",scores:{darts:100,billiards:30,pingPong:200,}}").asStruct();
+        StructElement expected = Ion.ionStructOf(a -> {
+            a.add("name", Ion.ionString("Alice"));
+            a.add("scores", Ion.ionStructOf(b -> {
+                    b.add("darts", Ion.ionInt(100));
+                    b.add("billiards", Ion.ionInt(30));
+                    b.add("pingPong", Ion.ionInt(200));
+                }
+            ));
+        });
 
         StructElement updated = original.update(fields ->
             fields.set("scores",

src/test/kotlin/com/amazon/ionelement/demos/AnyElementAccessorsDemo.kt

@@ -13,7 +13,7 @@
  *  permissions and limitations under the License.
  */
 
-package com.amazon.ionelement.demos.kotlin
+package com.amazon.ionelement.demos
 
 import com.amazon.ion.Decimal
 import com.amazon.ionelement.api.AnyElement

src/test/kotlin/com/amazon/ionelement/demos/MutableStructFieldsDemo.kt renamed to src/test/kotlin/com/amazon/ionelement/demos/MutableStructFieldsKotlinDemo.kt

@@ -1,11 +1,10 @@
-package com.amazon.ionelement.demos.kotlin
+package com.amazon.ionelement.demos
 
-import com.amazon.ionelement.api.ionInt
-import com.amazon.ionelement.api.loadSingleElement
+import com.amazon.ionelement.api.*
 import kotlin.test.assertEquals
 import org.junit.jupiter.api.Test
 
-class MutableStructFieldsDemo {
+class MutableStructFieldsKotlinDemo {
     @Test
     fun `create updated struct from existing struct`() {
         val original = loadSingleElement(
@@ -20,18 +19,17 @@ class MutableStructFieldsDemo {
             """.trimIndent()
         ).asStruct()
 
-        val expected = loadSingleElement(
-            """
-                {
-                    name: "Alice",               
-                    scores: {
-                        darts: 100,
-                        billiards: 30,
-                        pingPong: 200,
-                    }
+        val expected = ionStructOf {
+            add("name", ionString("Alice"))
+            add(
+                "scores",
+                ionStructOf {
+                    add("darts", ionInt(100))
+                    add("billiards", ionInt(30))
+                    add("pingPong", ionInt(200))
                 }
-            """.trimIndent()
-        ).asStruct()
+            )
+        }
 
         val updated = original.update {
             set(

src/test/kotlin/com/amazon/ionelement/demos/NarrowingDemo.kt

@@ -1,4 +1,4 @@
-package com.amazon.ionelement.demos.kotlin
+package com.amazon.ionelement.demos
 
 import com.amazon.ionelement.api.IntElement
 import com.amazon.ionelement.api.IonElement