Merge pull request #724 from ascopes/task/GH-721-refactor-varargs-apis

GH-721: Refactor varargs APIs

Author: ascopes

java-compiler-testing/pom.xml

@@ -22,7 +22,7 @@
   <parent>
     <groupId>io.github.ascopes.jct</groupId>
     <artifactId>java-compiler-testing-parent</artifactId>
-    <version>3.2.4-SNAPSHOT</version>
+    <version>4.0.0-RC1-SNAPSHOT</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 

java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/AbstractEnumAssert.java

@@ -15,11 +15,11 @@
  */
 package io.github.ascopes.jct.assertions;
 
+import static io.github.ascopes.jct.utils.IterableUtils.requireAtLeastOne;
 import static io.github.ascopes.jct.utils.IterableUtils.requireNonNullValues;
-import static java.util.Objects.requireNonNull;
 import static org.assertj.core.api.Assertions.assertThat;
 
-import io.github.ascopes.jct.utils.IterableUtils;
+import java.util.Collection;
 import java.util.List;
 import org.apiguardian.api.API;
 import org.apiguardian.api.API.Status;
@@ -52,33 +52,40 @@ protected AbstractEnumAssert(@Nullable E value, Class<?> selfType) {
   /**
    * Assert that the value is one of the given values.
    *
-   * @param first the first value to check for.
-   * @param more  any additional values to check for.
+   * @param elements the elements to check for.
    * @return this assertion object.
-   * @throws NullPointerException if any of the elements to test against are null.
-   * @throws AssertionError       if the actual value is null, or if the value is not in the given
-   *                              group of acceptable values.
+   * @throws NullPointerException     if any of the elements to test against are null.
+   * @throws IllegalArgumentException if the elements array is empty.
+   * @throws AssertionError           if the actual value is null, or if the value is not in the
+   *                                  given group of acceptable values.
    */
   @SafeVarargs
-  public final A isAnyOf(E first, E... more) {
-    requireNonNull(first, "first must not be null");
-    requireNonNullValues(more, "more");
+  @SuppressWarnings("varargs")
+  public final A isAnyOf(E... elements) {
+    requireNonNullValues(elements, "elements");
+    requireAtLeastOne(elements, "elements");
+    isNotNull();
+
+    assertThat(List.of(actual))
+        .as(description())
+        .containsAnyOf(elements);
 
-    return isAnyOfElements(IterableUtils.combineOneOrMore(first, more));
+    return myself;
   }
 
   /**
    * Assert that the value is one of the given values.
    *
    * @param elements the elements to check for.
    * @return this assertion object.
-   * @throws NullPointerException if any of the elements to test against are null.
-   * @throws AssertionError       if the actual value is null, or if the value is not in the given
-   *                              iterable of acceptable values.
+   * @throws NullPointerException     if any of the elements to test against are null.
+   * @throws IllegalArgumentException if the elements collection is empty.
+   * @throws AssertionError           if the actual value is null, or if the value is not in the
+   *                                  given iterable of acceptable values.
    */
-  public final A isAnyOfElements(Iterable<E> elements) {
+  public final A isAnyOfElements(Collection<E> elements) {
     requireNonNullValues(elements, "elements");
-
+    requireAtLeastOne(elements, "elements");
     isNotNull();
 
     assertThat(List.of(actual))
@@ -91,33 +98,39 @@ public final A isAnyOfElements(Iterable<E> elements) {
   /**
    * Assert that the value is none of the given values.
    *
-   * @param first the first value to check for.
-   * @param more  any additional values to check for.
+   * @param elements any elements to check for.
    * @return this assertion object.
-   * @throws NullPointerException if any of the elements to test against are null.
-   * @throws AssertionError       if the actual value is null, or if the value is in the given group
-   *                              of acceptable values.
+   * @throws NullPointerException     if any of the elements to test against are null.
+   * @throws IllegalArgumentException if the elements array is empty.
+   * @throws AssertionError           if the actual value is null, or if the value is in the given
+   *                                  group of acceptable values.
    */
   @SafeVarargs
-  public final A isNoneOf(E first, E... more) {
-    requireNonNull(first, "first must not be null");
-    requireNonNullValues(more, "more");
+  public final A isNoneOf(E... elements) {
+    requireNonNullValues(elements, "elements");
+    requireAtLeastOne(elements, "elements");
+    isNotNull();
 
-    return isNoneOfElements(IterableUtils.combineOneOrMore(first, more));
+    assertThat(List.of(actual))
+        .as(description())
+        .doesNotContain(elements);
+
+    return myself;
   }
 
   /**
    * Assert that the value is one of the given values.
    *
    * @param elements the elements to check for.
    * @return this assertion object.
-   * @throws NullPointerException if any of the elements to test against are null.
-   * @throws AssertionError       if the actual value is null, or if the value is in the given
-   *                              iterable of acceptable values.
+   * @throws NullPointerException     if any of the elements to test against are null.
+   * @throws IllegalArgumentException if the elements collection is empty.
+   * @throws AssertionError           if the actual value is null, or if the value is in the given
+   *                                  iterable of acceptable values.
    */
-  public final A isNoneOfElements(Iterable<E> elements) {
+  public final A isNoneOfElements(Collection<E> elements) {
     requireNonNullValues(elements, "elements");
-
+    requireAtLeastOne(elements, "elements");
     isNotNull();
 
     assertThat(List.of(actual))

java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/PackageContainerGroupAssert.java

@@ -16,11 +16,10 @@
 package io.github.ascopes.jct.assertions;
 
 import static io.github.ascopes.jct.utils.IoExceptionUtils.uncheckedIo;
-import static io.github.ascopes.jct.utils.IterableUtils.combineOneOrMore;
+import static io.github.ascopes.jct.utils.IterableUtils.requireAtLeastOne;
 import static io.github.ascopes.jct.utils.IterableUtils.requireNonNullValues;
 import static io.github.ascopes.jct.utils.StringUtils.quoted;
 import static io.github.ascopes.jct.utils.StringUtils.quotedIterable;
-import static java.util.Objects.requireNonNull;
 import static java.util.function.Predicate.not;
 import static org.assertj.core.api.Assertions.assertThat;
 
@@ -29,6 +28,7 @@
 import io.github.ascopes.jct.utils.StringUtils;
 import java.nio.file.Path;
 import java.util.ArrayList;
+import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
@@ -63,18 +63,18 @@ public PackageContainerGroupAssert(@Nullable PackageContainerGroup containerGrou
   /**
    * Assert that all given files exist.
    *
-   * @param path  the first path to check for
-   * @param paths additional paths to check for.
+   * @param paths paths to check for.
    * @return this object for further call chaining.
-   * @throws AssertionError       if the container group is null, or if any of the files do not
-   *                              exist.
-   * @throws NullPointerException if any of the paths are null.
+   * @throws AssertionError           if the container group is null, or if any of the files do not
+   *                                  exist.
+   * @throws NullPointerException     if any of the paths are null.
+   * @throws IllegalArgumentException if no fragments are provided.
    */
-  public PackageContainerGroupAssert allFilesExist(String path, String... paths) {
-    requireNonNull(path, "path");
+  public PackageContainerGroupAssert allFilesExist(String... paths) {
     requireNonNullValues(paths, "paths");
+    requireAtLeastOne(paths, "paths");
 
-    allFilesExist(combineOneOrMore(path, paths));
+    allFilesExist(List.of(paths));
     return this;
   }
 
@@ -138,27 +138,27 @@ public ClassLoaderAssert classLoader() {
    *   assertions.fileDoesNotExist("foo", "bar", "baz.txt");
    * </code></pre>
    *
-   * @param fragment  the first part of the path.
    * @param fragments any additional parts of the path.
    * @return this assertion object for further assertions.
-   * @throws AssertionError       if the file exists, or if the container group is null.
-   * @throws NullPointerException if any of the fragments are null.
+   * @throws AssertionError           if the file exists, or if the container group is null.
+   * @throws NullPointerException     if any of the fragments are null.
+   * @throws IllegalArgumentException if no fragments are provided.
    */
-  public PackageContainerGroupAssert fileDoesNotExist(String fragment, String... fragments) {
-    requireNonNull(fragment, "fragment");
+  public PackageContainerGroupAssert fileDoesNotExist(String... fragments) {
     requireNonNullValues(fragments, "fragments");
+    requireAtLeastOne(fragments, "fragments");
 
     isNotNull();
 
-    var actualFile = actual.getFile(fragment, fragments);
+    var actualFile = actual.getFile(fragments);
 
     if (actualFile == null) {
       return this;
     }
 
     throw failure(
         "Expected path %s to not exist in %s but it was found at %s",
-        quotedUserProvidedPath(combineOneOrMore(fragment, fragments)),
+        quotedUserProvidedPath(List.of(fragments)),
         LocationRepresentation.getInstance().toStringOf(actual.getLocation()),
         quoted(actualFile)
     );
@@ -178,27 +178,28 @@ public PackageContainerGroupAssert fileDoesNotExist(String fragment, String... f
    * <p>If the file does not exist, then this object will attempt to find the
    * closest matches and list them in an error message along with the assertion error.
    *
-   * @param fragment  the first part of the path.
-   * @param fragments any additional parts of the path.
+   * @param fragments parts of the path.
    * @return assertions to perform on the path of the file that exists.
-   * @throws AssertionError       if the file does not exist, or if the container group is null.
-   * @throws NullPointerException if any of the fragments are null.
+   * @throws AssertionError           if the file does not exist, or if the container group is
+   *                                  null.
+   * @throws NullPointerException     if any of the fragments are null.
+   * @throws IllegalArgumentException if no fragments are provided.
    */
 
-  public AbstractPathAssert<?> fileExists(String fragment, String... fragments) {
-    requireNonNull(fragment, "fragment");
+  public AbstractPathAssert<?> fileExists(String... fragments) {
     requireNonNullValues(fragments, "fragments");
+    requireAtLeastOne(fragments, "fragments");
 
     isNotNull();
 
-    var actualFile = actual.getFile(fragment, fragments);
+    var actualFile = actual.getFile(fragments);
 
     if (actualFile != null) {
       // File exists with this path. Hooray, lets return assertions on it.
       return assertThat(actualFile);
     }
 
-    var expected = combineOneOrMore(fragment, fragments);
+    var expected = List.of(fragments);
     var message = StringUtils.resultNotFoundWithFuzzySuggestions(
         fuzzySafePath(expected),
         quotedUserProvidedPath(expected),

java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/TraceDiagnosticListAssert.java

@@ -15,9 +15,8 @@
  */
 package io.github.ascopes.jct.assertions;
 
-import static io.github.ascopes.jct.utils.IterableUtils.combineOneOrMore;
+import static io.github.ascopes.jct.utils.IterableUtils.requireAtLeastOne;
 import static io.github.ascopes.jct.utils.IterableUtils.requireNonNullValues;
-import static java.util.Objects.requireNonNull;
 import static java.util.function.Predicate.not;
 import static java.util.stream.Collectors.collectingAndThen;
 import static java.util.stream.Collectors.toUnmodifiableList;
@@ -47,7 +46,8 @@
  */
 @API(since = "0.0.1", status = Status.STABLE)
 public final class TraceDiagnosticListAssert
-    extends AbstractListAssert<TraceDiagnosticListAssert, List<? extends TraceDiagnostic<? extends JavaFileObject>>, TraceDiagnostic<? extends JavaFileObject>, TraceDiagnosticAssert> {
+    extends
+    AbstractListAssert<TraceDiagnosticListAssert, List<? extends TraceDiagnostic<? extends JavaFileObject>>, TraceDiagnostic<? extends JavaFileObject>, TraceDiagnosticAssert> {
 
   /**
    * Initialize this assertion.
@@ -133,16 +133,16 @@ public TraceDiagnosticListAssert others() {
    * Get a {@link TraceDiagnosticListAssert} that contains diagnostics corresponding to any of the
    * given {@link Kind kinds}.
    *
-   * @param kind      the first kind to match.
-   * @param moreKinds additional kinds to match.
+   * @param kinds the kinds to match.
    * @return the assertion object for the filtered diagnostics.
-   * @throws AssertionError       if this list is null.
-   * @throws NullPointerException if any of the kinds are null.
+   * @throws AssertionError           if this list is null.
+   * @throws NullPointerException     if any of the kinds are null.
+   * @throws IllegalArgumentException if no kinds are provided.
    */
-  public TraceDiagnosticListAssert filteringByKinds(Kind kind, Kind... moreKinds) {
-    requireNonNull(kind, "kind");
-    requireNonNullValues(moreKinds, "moreKinds");
-    return filteringByKinds(combineOneOrMore(kind, moreKinds));
+  public TraceDiagnosticListAssert filteringByKinds(Kind... kinds) {
+    requireNonNullValues(kinds, "kinds");
+    requireAtLeastOne(kinds, "kinds");
+    return filteringByKinds(List.of(kinds));
   }
 
   /**
@@ -163,16 +163,16 @@ public TraceDiagnosticListAssert filteringByKinds(Iterable<Kind> kinds) {
    * Get a {@link TraceDiagnosticListAssert} that contains diagnostics corresponding to none of the
    * given {@link Kind kinds}.
    *
-   * @param kind      the first kind to ensure are not matched.
-   * @param moreKinds additional kinds to ensure are not matched.
+   * @param kinds kinds to ensure are not matched.
    * @return the assertion object for the filtered diagnostics.
-   * @throws AssertionError       if this list is null.
-   * @throws NullPointerException if any of the kinds are null.
+   * @throws AssertionError           if this list is null.
+   * @throws NullPointerException     if any of the kinds are null.
+   * @throws IllegalArgumentException if no kinds are provided.
    */
-  public TraceDiagnosticListAssert excludingKinds(Kind kind, Kind... moreKinds) {
-    requireNonNull(kind, "kind");
-    requireNonNullValues(moreKinds, "moreKinds");
-    return excludingKinds(combineOneOrMore(kind, moreKinds));
+  public TraceDiagnosticListAssert excludingKinds(Kind... kinds) {
+    requireNonNullValues(kinds, "kinds");
+    requireAtLeastOne(kinds, "kinds");
+    return excludingKinds(List.of(kinds));
   }
 
   /**
@@ -184,10 +184,10 @@ public TraceDiagnosticListAssert excludingKinds(Kind kind, Kind... moreKinds) {
    * @throws AssertionError       if this list is null.
    * @throws NullPointerException if any of the kinds are null.
    */
+  @SuppressWarnings("ConstantValue")  // actual CAN be null, IntelliJ just doesn't realise this.
   public TraceDiagnosticListAssert excludingKinds(Iterable<Kind> kinds) {
     requireNonNullValues(kinds, "kinds");
     isNotNull();
-    //noinspection ConstantValue -- actual CAN be null, IntelliJ just doesn't realise this.
     return actual
         .stream()
         .filter(Objects::nonNull)
@@ -270,16 +270,15 @@ public TraceDiagnosticListAssert hasNoOtherDiagnostics() {
   /**
    * Assert that this list has no diagnostics matching any of the given kinds.
    *
-   * @param kind      the first kind to check for.
-   * @param moreKinds any additional kinds to check for.
+   * @param kinds kinds to check for.
    * @return this assertion object for further call chaining.
    * @throws AssertionError       if the diagnostic list is null.
    * @throws NullPointerException if the kind or more kinds are null.
    */
-  public TraceDiagnosticListAssert hasNoDiagnosticsOfKinds(Kind kind, Kind... moreKinds) {
-    requireNonNull(kind, "kind");
-    requireNonNullValues(moreKinds, "moreKinds");
-    return hasNoDiagnosticsOfKinds(combineOneOrMore(kind, moreKinds));
+  public TraceDiagnosticListAssert hasNoDiagnosticsOfKinds(Kind... kinds) {
+    requireNonNullValues(kinds, "kinds");
+    requireAtLeastOne(kinds, "kinds");
+    return hasNoDiagnosticsOfKinds(List.of(kinds));
   }
 
   /**
@@ -355,7 +354,8 @@ protected TraceDiagnosticListAssert newAbstractIterableAssert(
     return new TraceDiagnosticListAssert(list);
   }
 
-  private Predicate<@Nullable TraceDiagnostic<? extends JavaFileObject>> kindIsOneOf(Iterable<Kind> kinds) {
+  private Predicate<@Nullable TraceDiagnostic<? extends JavaFileObject>> kindIsOneOf(
+      Iterable<Kind> kinds) {
     var kindsSet = new LinkedHashSet<Kind>();
     kinds.forEach(kindsSet::add);
 

java-compiler-testing/src/main/java/io/github/ascopes/jct/compilers/DebuggingInfo.java

@@ -15,6 +15,7 @@
  */
 package io.github.ascopes.jct.compilers;
 
+import java.util.Collections;
 import java.util.EnumSet;
 import java.util.Set;
 import org.apiguardian.api.API;
@@ -60,12 +61,13 @@ public static Set<DebuggingInfo> none() {
   /**
    * Return a set of the given debugger info flags.
    *
-   * @param flag  the first flag.
-   * @param flags additional flags.
+   * @param flags flags.
    * @return the set of the debugger info flags.
    */
-  public static Set<DebuggingInfo> just(DebuggingInfo flag, DebuggingInfo... flags) {
-    return EnumSet.of(flag, flags);
+  public static Set<DebuggingInfo> just(DebuggingInfo... flags) {
+    var set = none();
+    Collections.addAll(set, flags);
+    return set;
   }
 
   /**