Added support for the array:append Metapath function.

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/function/library/ArrayAppend.java

@@ -0,0 +1,100 @@
+/*
+ * Portions of this software was developed by employees of the National Institute
+ * of Standards and Technology (NIST), an agency of the Federal Government and is
+ * being made available as a public service. Pursuant to title 17 United States
+ * Code Section 105, works of NIST employees are not subject to copyright
+ * protection in the United States. This software may be subject to foreign
+ * copyright. Permission in the United States and in foreign countries, to the
+ * extent that NIST may hold copyright, to use, copy, modify, create derivative
+ * works, and distribute this software and its documentation without fee is hereby
+ * granted on a non-exclusive basis, provided that this notice and disclaimer
+ * of warranty appears in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND, EITHER
+ * EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY
+ * THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND FREEDOM FROM
+ * INFRINGEMENT, AND ANY WARRANTY THAT THE DOCUMENTATION WILL CONFORM TO THE
+ * SOFTWARE, OR ANY WARRANTY THAT THE SOFTWARE WILL BE ERROR FREE.  IN NO EVENT
+ * SHALL NIST BE LIABLE FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT,
+ * INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM,
+ * OR IN ANY WAY CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY,
+ * CONTRACT, TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY PERSONS OR
+ * PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED FROM, OR AROSE OUT
+ * OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR SERVICES PROVIDED HEREUNDER.
+ */
+
+package gov.nist.secauto.metaschema.core.metapath.function.library;
+
+import gov.nist.secauto.metaschema.core.metapath.DynamicContext;
+import gov.nist.secauto.metaschema.core.metapath.ISequence;
+import gov.nist.secauto.metaschema.core.metapath.MetapathConstants;
+import gov.nist.secauto.metaschema.core.metapath.function.FunctionUtils;
+import gov.nist.secauto.metaschema.core.metapath.function.IArgument;
+import gov.nist.secauto.metaschema.core.metapath.function.IFunction;
+import gov.nist.secauto.metaschema.core.metapath.item.IItem;
+import gov.nist.secauto.metaschema.core.metapath.item.function.IArrayItem;
+import gov.nist.secauto.metaschema.core.util.ObjectUtils;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import edu.umd.cs.findbugs.annotations.NonNull;
+
+public class ArrayAppend {
+  @NonNull
+  public static final IFunction SIGNATURE = IFunction.builder()
+      .name("append")
+      .namespace(MetapathConstants.NS_METAPATH_FUNCTIONS_ARRAY)
+      .argument(IArgument.builder()
+          .name("array")
+          .type(IArrayItem.class)
+          .one()
+          .build())
+      .argument(IArgument.builder()
+          .name("appendage")
+          .type(IItem.class)
+          .zeroOrMore()
+          .build())
+      .returnType(IArrayItem.class)
+      .returnOne()
+      .functionHandler(ArrayAppend::execute)
+      .build();
+
+  @SuppressWarnings("unused")
+  @NonNull
+  private static <T extends IItem> ISequence<IArrayItem<T>> execute(@NonNull IFunction function,
+      @NonNull List<ISequence<?>> arguments,
+      @NonNull DynamicContext dynamicContext,
+      IItem focus) {
+    IArrayItem<T> array = FunctionUtils.asType(ObjectUtils.requireNonNull(
+        arguments.get(0).getFirstItem(true)));
+    T appendage = FunctionUtils.asType(arguments.get(1).toArrayMember());
+
+    return ISequence.of(append(array, appendage));
+  }
+
+  /**
+   * An implementation of XPath 3.1 <a href=
+   * "https://www.w3.org/TR/xpath-functions-31/#func-array-append">array:append</a>.
+   *
+   * @param <T>
+   *          the type of items in the given Metapath array
+   * @param array
+   *          the target Metapath array
+   * @param appendage
+   *          the Metapath item to append to the identified array
+   * @return a new array containing the modification
+   */
+  @SuppressWarnings("PMD.OnlyOneReturn")
+  @NonNull
+  public static <T extends IItem> IArrayItem<T> append(
+      @NonNull IArrayItem<T> array,
+      @NonNull T appendage) {
+
+    List<T> copy = new ArrayList<>(array);
+    copy.add(appendage);
+
+    return IArrayItem.ofCollection(copy);
+  }
+}

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/function/library/DefaultFunctionLibrary.java

@@ -199,6 +199,8 @@ public DefaultFunctionLibrary() { // NOPMD - intentional
     registerFunction(ArraySize.SIGNATURE);
     // https://www.w3.org/TR/xpath-functions-31/#func-array-put
     registerFunction(ArrayPut.SIGNATURE);
+    // https://www.w3.org/TR/xpath-functions-31/#func-array-append
+    registerFunction(ArrayAppend.SIGNATURE);
 
     // xpath casting functions
     registerFunction(

core/src/test/java/gov/nist/secauto/metaschema/core/metapath/function/library/ArrayAppendTest.java

@@ -0,0 +1,65 @@
+/*
+ * Portions of this software was developed by employees of the National Institute
+ * of Standards and Technology (NIST), an agency of the Federal Government and is
+ * being made available as a public service. Pursuant to title 17 United States
+ * Code Section 105, works of NIST employees are not subject to copyright
+ * protection in the United States. This software may be subject to foreign
+ * copyright. Permission in the United States and in foreign countries, to the
+ * extent that NIST may hold copyright, to use, copy, modify, create derivative
+ * works, and distribute this software and its documentation without fee is hereby
+ * granted on a non-exclusive basis, provided that this notice and disclaimer
+ * of warranty appears in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND, EITHER
+ * EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY
+ * THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND FREEDOM FROM
+ * INFRINGEMENT, AND ANY WARRANTY THAT THE DOCUMENTATION WILL CONFORM TO THE
+ * SOFTWARE, OR ANY WARRANTY THAT THE SOFTWARE WILL BE ERROR FREE.  IN NO EVENT
+ * SHALL NIST BE LIABLE FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT,
+ * INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM,
+ * OR IN ANY WAY CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY,
+ * CONTRACT, TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY PERSONS OR
+ * PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED FROM, OR AROSE OUT
+ * OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR SERVICES PROVIDED HEREUNDER.
+ */
+
+package gov.nist.secauto.metaschema.core.metapath.function.library;
+
+import static gov.nist.secauto.metaschema.core.metapath.TestUtils.array;
+import static gov.nist.secauto.metaschema.core.metapath.TestUtils.string;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import gov.nist.secauto.metaschema.core.metapath.ExpressionTestBase;
+import gov.nist.secauto.metaschema.core.metapath.MetapathExpression;
+import gov.nist.secauto.metaschema.core.metapath.item.IItem;
+
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+
+import java.util.stream.Stream;
+
+import edu.umd.cs.findbugs.annotations.NonNull;
+
+class ArrayAppendTest
+    extends ExpressionTestBase {
+  private static Stream<Arguments> provideValues() { // NOPMD - false positive
+    return Stream.of(
+        Arguments.of(
+            array(string("a"), string("b"), string("c"), string("d")),
+            "array:append([\"a\", \"b\", \"c\"], \"d\")"),
+        Arguments.of(
+            array(string("a"), string("b"), string("c"), array(string("d"), string("e"))),
+            "array:append([\"a\", \"b\", \"c\"], (\"d\", \"e\"))"));
+  }
+
+  @ParameterizedTest
+  @MethodSource("provideValues")
+  void testExpression(@NonNull IItem expected, @NonNull String metapath) {
+
+    IItem result = MetapathExpression.compile(metapath)
+        .evaluateAs(null, MetapathExpression.ResultType.NODE, newDynamicContext());
+    assertEquals(expected, result);
+  }
+}