Merge pull request #698 from KyoriPowered/4/new-builder

New builder

api/src/main/java/net/kyori/adventure/builder/AbstractBuilder.java

@@ -0,0 +1,65 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2022 KyoriPowered
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package net.kyori.adventure.builder;
+
+import java.util.function.Consumer;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * A builder.
+ *
+ * @param <R> the type to be built
+ * @since 4.10.0
+ */
+@FunctionalInterface
+public interface AbstractBuilder<R> {
+  /**
+   * Configures {@code builder} using {@code consumer} and then builds.
+   *
+   * @param builder the builder
+   * @param consumer the builder consume
+   * @param <R> the type to be built
+   * @param <B> the builder type
+   * @return the built thing
+   * @since 4.10.0
+   */
+  @Contract(mutates = "param1")
+  static <R, B extends AbstractBuilder<R>> @NotNull R configureAndBuild(final @NotNull B builder, final @Nullable Consumer<? super B> consumer) {
+    if (consumer != null) {
+      consumer.accept(builder);
+    }
+    return builder.build();
+  }
+
+  /**
+   * Builds.
+   *
+   * @return the built thing
+   * @since 4.10.0
+   */
+  @Contract(value = "-> new", pure = true)
+  @NotNull R build();
+}

api/src/main/java/net/kyori/adventure/builder/package-info.java

@@ -0,0 +1,27 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2022 KyoriPowered
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * Common builder-related gizmos.
+ */
+package net.kyori.adventure.builder;

api/src/main/java/net/kyori/adventure/inventory/Book.java

@@ -28,6 +28,7 @@
 import java.util.Collection;
 import java.util.List;
 import net.kyori.adventure.audience.Audience;
+import net.kyori.adventure.builder.AbstractBuilder;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.util.Buildable;
 import net.kyori.examination.Examinable;
@@ -170,7 +171,7 @@ public interface Book extends Buildable<Book, Book.Builder>, Examinable {
    *
    * @since 4.0.0
    */
-  interface Builder extends Buildable.Builder<Book> {
+  interface Builder extends AbstractBuilder<Book>, Buildable.Builder<Book> {
     /**
      * Set the title.
      *

api/src/main/java/net/kyori/adventure/pointer/Pointers.java

@@ -25,6 +25,7 @@
 
 import java.util.Optional;
 import java.util.function.Supplier;
+import net.kyori.adventure.builder.AbstractBuilder;
 import net.kyori.adventure.util.Buildable;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
@@ -121,7 +122,7 @@ public interface Pointers extends Buildable<Pointers, Pointers.Builder> {
    * @see Pointers
    * @since 4.8.0
    */
-  interface Builder extends Buildable.Builder<Pointers> {
+  interface Builder extends AbstractBuilder<Pointers>, Buildable.Builder<Pointers> {
     /**
      * Adds a pointer with a static, optional value.
      *

api/src/main/java/net/kyori/adventure/text/Component.java

@@ -40,6 +40,7 @@
 import java.util.regex.Pattern;
 import java.util.stream.Collector;
 import java.util.stream.Stream;
+import net.kyori.adventure.builder.AbstractBuilder;
 import net.kyori.adventure.key.Key;
 import net.kyori.adventure.text.event.ClickEvent;
 import net.kyori.adventure.text.event.HoverEvent;
@@ -51,7 +52,6 @@
 import net.kyori.adventure.text.format.TextDecoration;
 import net.kyori.adventure.text.serializer.ComponentSerializer;
 import net.kyori.adventure.translation.Translatable;
-import net.kyori.adventure.util.Buildable;
 import net.kyori.adventure.util.ForwardingIterator;
 import net.kyori.adventure.util.IntFunction2;
 import net.kyori.adventure.util.MonkeyBars;
@@ -287,7 +287,7 @@ public interface Component extends ComponentBuilderApplicable, ComponentLike, Ex
    */
   @Contract("_ -> new")
   static @NotNull BlockNBTComponent blockNBT(final @NotNull Consumer<? super BlockNBTComponent.Builder> consumer) {
-    return Buildable.configureAndBuild(blockNBT(), consumer);
+    return AbstractBuilder.configureAndBuild(blockNBT(), consumer);
   }
 
   /**
@@ -358,7 +358,7 @@ public interface Component extends ComponentBuilderApplicable, ComponentLike, Ex
    */
   @Contract("_ -> new")
   static @NotNull EntityNBTComponent entityNBT(final @NotNull Consumer<? super EntityNBTComponent.Builder> consumer) {
-    return Buildable.configureAndBuild(entityNBT(), consumer);
+    return AbstractBuilder.configureAndBuild(entityNBT(), consumer);
   }
 
   /**
@@ -400,7 +400,7 @@ public interface Component extends ComponentBuilderApplicable, ComponentLike, Ex
    */
   @Contract("_ -> new")
   static @NotNull KeybindComponent keybind(final @NotNull Consumer<? super KeybindComponent.Builder> consumer) {
-    return Buildable.configureAndBuild(keybind(), consumer);
+    return AbstractBuilder.configureAndBuild(keybind(), consumer);
   }
 
   /**
@@ -561,7 +561,7 @@ public interface Component extends ComponentBuilderApplicable, ComponentLike, Ex
    */
   @Contract("_ -> new")
   static @NotNull ScoreComponent score(final @NotNull Consumer<? super ScoreComponent.Builder> consumer) {
-    return Buildable.configureAndBuild(score(), consumer);
+    return AbstractBuilder.configureAndBuild(score(), consumer);
   }
 
   /**
@@ -619,7 +619,7 @@ public interface Component extends ComponentBuilderApplicable, ComponentLike, Ex
    */
   @Contract("_ -> new")
   static @NotNull SelectorComponent selector(final @NotNull Consumer<? super SelectorComponent.Builder> consumer) {
-    return Buildable.configureAndBuild(selector(), consumer);
+    return AbstractBuilder.configureAndBuild(selector(), consumer);
   }
 
   /**
@@ -673,7 +673,7 @@ public interface Component extends ComponentBuilderApplicable, ComponentLike, Ex
    */
   @Contract("_ -> new")
   static @NotNull StorageNBTComponent storageNBT(final @NotNull Consumer<? super StorageNBTComponent.Builder> consumer) {
-    return Buildable.configureAndBuild(storageNBT(), consumer);
+    return AbstractBuilder.configureAndBuild(storageNBT(), consumer);
   }
 
   /**
@@ -756,7 +756,7 @@ public interface Component extends ComponentBuilderApplicable, ComponentLike, Ex
    */
   @Contract("_ -> new")
   static @NotNull TextComponent text(final @NotNull Consumer<? super TextComponent.Builder> consumer) {
-    return Buildable.configureAndBuild(text(), consumer);
+    return AbstractBuilder.configureAndBuild(text(), consumer);
   }
 
   /**
@@ -1250,7 +1250,7 @@ public interface Component extends ComponentBuilderApplicable, ComponentLike, Ex
    */
   @Contract("_ -> new")
   static @NotNull TranslatableComponent translatable(final @NotNull Consumer<? super TranslatableComponent.Builder> consumer) {
-    return Buildable.configureAndBuild(translatable(), consumer);
+    return AbstractBuilder.configureAndBuild(translatable(), consumer);
   }
 
   /**
@@ -2077,7 +2077,7 @@ default boolean hasStyling() {
   @Contract(pure = true)
   default @NotNull Component replaceText(final @NotNull Consumer<TextReplacementConfig.Builder> configurer) {
     requireNonNull(configurer, "configurer");
-    return this.replaceText(Buildable.configureAndBuild(TextReplacementConfig.builder(), configurer));
+    return this.replaceText(AbstractBuilder.configureAndBuild(TextReplacementConfig.builder(), configurer));
   }
 
   /**

api/src/main/java/net/kyori/adventure/text/ComponentBuilder.java

@@ -28,6 +28,7 @@
 import java.util.Set;
 import java.util.function.Consumer;
 import java.util.function.Function;
+import net.kyori.adventure.builder.AbstractBuilder;
 import net.kyori.adventure.key.Key;
 import net.kyori.adventure.text.event.ClickEvent;
 import net.kyori.adventure.text.event.HoverEventSource;
@@ -49,7 +50,7 @@
  * @since 4.0.0
  */
 @ApiStatus.NonExtendable
-public interface ComponentBuilder<C extends BuildableComponent<C, B>, B extends ComponentBuilder<C, B>> extends Buildable.Builder<C>, ComponentBuilderApplicable, ComponentLike, MutableStyleSetter<B> {
+public interface ComponentBuilder<C extends BuildableComponent<C, B>, B extends ComponentBuilder<C, B>> extends AbstractBuilder<C>, Buildable.Builder<C>, ComponentBuilderApplicable, ComponentLike, MutableStyleSetter<B> {
   /**
    * Appends a component to this component.
    *

api/src/main/java/net/kyori/adventure/text/JoinConfiguration.java

@@ -25,6 +25,7 @@
 
 import java.util.function.Function;
 import java.util.function.Predicate;
+import net.kyori.adventure.builder.AbstractBuilder;
 import net.kyori.adventure.util.Buildable;
 import net.kyori.examination.Examinable;
 import org.jetbrains.annotations.ApiStatus;
@@ -232,7 +233,7 @@ public interface JoinConfiguration extends Buildable<JoinConfiguration, JoinConf
    *
    * @since 4.9.0
    */
-  interface Builder extends Buildable.Builder<JoinConfiguration> {
+  interface Builder extends AbstractBuilder<JoinConfiguration>, Buildable.Builder<JoinConfiguration> {
     /**
      * Sets the prefix of this join configuration builder.
      *

api/src/main/java/net/kyori/adventure/text/TextReplacementConfig.java

@@ -27,6 +27,7 @@
 import java.util.function.Function;
 import java.util.regex.MatchResult;
 import java.util.regex.Pattern;
+import net.kyori.adventure.builder.AbstractBuilder;
 import net.kyori.adventure.util.Buildable;
 import net.kyori.adventure.util.IntFunction2;
 import net.kyori.examination.Examinable;
@@ -69,7 +70,7 @@ public interface TextReplacementConfig extends Buildable<TextReplacementConfig,
    *
    * @since 4.2.0
    */
-  interface Builder extends Buildable.Builder<TextReplacementConfig> {
+  interface Builder extends AbstractBuilder<TextReplacementConfig>, Buildable.Builder<TextReplacementConfig> {
     /*
      * -------------------
      * ---- Patterns -----

api/src/main/java/net/kyori/adventure/text/flattener/ComponentFlattener.java

@@ -26,6 +26,7 @@
 import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 import java.util.function.Function;
+import net.kyori.adventure.builder.AbstractBuilder;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.util.Buildable;
 import org.jetbrains.annotations.NotNull;
@@ -88,7 +89,7 @@ public interface ComponentFlattener extends Buildable<ComponentFlattener, Compon
    *
    * @since 4.7.0
    */
-  interface Builder extends Buildable.Builder<ComponentFlattener> {
+  interface Builder extends AbstractBuilder<ComponentFlattener>, Buildable.Builder<ComponentFlattener> {
     /**
      * Register a type of component to be handled.
      *

api/src/main/java/net/kyori/adventure/text/format/Style.java

@@ -27,6 +27,7 @@
 import java.util.Map;
 import java.util.Set;
 import java.util.function.Consumer;
+import net.kyori.adventure.builder.AbstractBuilder;
 import net.kyori.adventure.key.Key;
 import net.kyori.adventure.sound.Sound;
 import net.kyori.adventure.text.Component;
@@ -97,7 +98,7 @@ public interface Style extends Buildable<Style, Style.Builder>, Examinable, Styl
    * @since 4.0.0
    */
   static @NotNull Style style(final @NotNull Consumer<Builder> consumer) {
-    return Buildable.configureAndBuild(style(), consumer);
+    return AbstractBuilder.configureAndBuild(style(), consumer);
   }
 
   /**
@@ -655,7 +656,7 @@ public enum Strategy {
    *
    * @since 4.0.0
    */
-  interface Builder extends Buildable.Builder<Style>, MutableStyleSetter<Builder> {
+  interface Builder extends AbstractBuilder<Style>, Buildable.Builder<Style>, MutableStyleSetter<Builder> {
     /**
      * Sets the font.
      *

api/src/main/java/net/kyori/adventure/util/Buildable.java

@@ -24,6 +24,7 @@
 package net.kyori.adventure.util;
 
 import java.util.function.Consumer;
+import net.kyori.adventure.builder.AbstractBuilder;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -45,11 +46,12 @@ public interface Buildable<R, B extends Buildable.Builder<R>> {
    * @param <B> the builder type
    * @return the built thing
    * @since 4.0.0
+   * @deprecated since 4.10.0, use {@link AbstractBuilder#configureAndBuild(AbstractBuilder, Consumer)}
    */
   @Contract(mutates = "param1")
+  @Deprecated
   static <R extends Buildable<R, B>, B extends Builder<R>> @NotNull R configureAndBuild(final @NotNull B builder, final @Nullable Consumer<? super B> consumer) {
-    if (consumer != null) consumer.accept(builder);
-    return builder.build();
+    return AbstractBuilder.configureAndBuild(builder, consumer);
   }
 
   /**
@@ -66,15 +68,18 @@ public interface Buildable<R, B extends Buildable.Builder<R>> {
    *
    * @param <R> the type to be built
    * @since 4.0.0
+   * @deprecated since 4.10.0, use {@link AbstractBuilder}
    */
-  interface Builder<R> {
+  @Deprecated
+  interface Builder<R> extends AbstractBuilder<R> {
     /**
      * Builds.
      *
      * @return the built thing
      * @since 4.0.0
      */
     @Contract(value = "-> new", pure = true)
+    @Override
     @NotNull R build();
   }
 }

text-minimessage/src/main/java/net/kyori/adventure/text/minimessage/MiniMessage.java

@@ -25,11 +25,11 @@
 
 import java.util.function.Consumer;
 import java.util.function.UnaryOperator;
+import net.kyori.adventure.builder.AbstractBuilder;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.minimessage.tag.resolver.TagResolver;
 import net.kyori.adventure.text.minimessage.tree.Node;
 import net.kyori.adventure.text.serializer.ComponentSerializer;
-import net.kyori.adventure.util.Buildable;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -41,7 +41,7 @@
  *
  * @since 4.10.0
  */
-public interface MiniMessage extends ComponentSerializer<Component, Component, String>, Buildable<MiniMessage, MiniMessage.Builder> {
+public interface MiniMessage extends ComponentSerializer<Component, Component, String> {
 
   /**
    * Gets a simple instance without markdown support.
@@ -210,7 +210,7 @@ static Builder builder() {
    *
    * @since 4.10.0
    */
-  interface Builder extends Buildable.Builder<MiniMessage> {
+  interface Builder extends AbstractBuilder<MiniMessage> {
 
     /**
      * Set the known tags to the provided tag resolver.