From a4dab0fead3badc19f9f6a2acc3d790abfa64396 Mon Sep 17 00:00:00 2001 From: melontini <104443436+melontini@users.noreply.github.com> Date: Mon, 5 Aug 2024 01:22:47 +0700 Subject: [PATCH] Add javadoc for `api` package. + inline ConstantBooleanExpression instances. --- .../commander/api/command/Command.java | 21 ++++++++++++++++++ .../commander/api/command/CommandType.java | 9 ++++++++ .../commander/api/command/Selector.java | 13 +++++++++++ .../commander/api/event/EventType.java | 20 +++++++++++++++++ .../commander/api/event/Subscription.java | 22 ++++++++++++++++++- .../commander/api/expression/Arithmetica.java | 8 +++---- .../api/expression/BooleanExpression.java | 8 +++---- .../api/expression/BrigadierMacro.java | 12 ++++++++++ .../commander/api/expression/Expression.java | 6 +++++ .../api/expression/ExpressionLibrary.java | 5 +++++ .../api/expression/LongExpression.java | 14 ++++++++---- .../extensions/AbstractProxyMap.java | 3 +-- .../extensions/CustomDataAccessor.java | 15 ++++++++++++- .../api/expression/extensions/ProxyMap.java | 2 ++ .../commander/api/util/EventExecutors.java | 4 ++++ .../ConstantBooleanExpression.java | 6 ++++- 16 files changed, 151 insertions(+), 17 deletions(-) diff --git a/src/main/java/me/melontini/commander/api/command/Command.java b/src/main/java/me/melontini/commander/api/command/Command.java index 672ae14..fa5144b 100644 --- a/src/main/java/me/melontini/commander/api/command/Command.java +++ b/src/main/java/me/melontini/commander/api/command/Command.java @@ -16,10 +16,25 @@ public interface Command { MapCodec CODEC = (MapCodec) ConditionedCommand.CODEC; + /** + * Executes the command with the provided event context. + * @param context {@link EventContext} + * @return If the execution was successful. + */ boolean execute(EventContext context); + /** + * @return The registered command type. + * @see CommandType#register(Identifier, MapCodec) + */ CommandType type(); + /** + * Validates that a command can used with the event type. + * Internally this is only used for the cancel command. + * @param type The {@link EventType} expected to for this command. + * @return {@link DataResult}. + */ default DataResult validate(EventType type) { return DataResult.success(null); } @@ -28,8 +43,14 @@ public interface Command { * Executable command proxy. This interface is to be used when you nest additional commands in your base command. */ interface Conditioned { + /** + * @see Command#execute(EventContext) + */ boolean execute(EventContext context); + /** + * @see Command#validate(EventType) + */ DataResult validate(EventType type); } } diff --git a/src/main/java/me/melontini/commander/api/command/CommandType.java b/src/main/java/me/melontini/commander/api/command/CommandType.java index 6f301e6..60b4618 100644 --- a/src/main/java/me/melontini/commander/api/command/CommandType.java +++ b/src/main/java/me/melontini/commander/api/command/CommandType.java @@ -3,9 +3,18 @@ package me.melontini.commander.api.command; import com.mojang.serialization.MapCodec; import me.melontini.commander.impl.event.data.types.CommandTypes; import net.minecraft.util.Identifier; +import org.jetbrains.annotations.ApiStatus; +@ApiStatus.NonExtendable public interface CommandType { + /** + * Registers a command to be used in events. + * @param identifier The command identifier. + * @param codec The codec to decode the command from JSON. + * @return The command type to be returned in {@link Command#type()} + * @see Command#type() + */ static CommandType register(Identifier identifier, MapCodec codec) { return CommandTypes.register(identifier, () -> codec); } diff --git a/src/main/java/me/melontini/commander/api/command/Selector.java b/src/main/java/me/melontini/commander/api/command/Selector.java index 92a5c0f..783bee7 100644 --- a/src/main/java/me/melontini/commander/api/command/Selector.java +++ b/src/main/java/me/melontini/commander/api/command/Selector.java @@ -19,6 +19,12 @@ public interface Selector extends Function { Codec CODEC = (Codec) ConditionedSelector.CODEC; + /** + * Registers a selector to be used with {@link Command}. + * @param identifier The selector identifier. + * @param selector Selector to be registered. + * @return the provided selector instance. + */ static Selector register(Identifier identifier, Selector selector) { return SelectorTypes.register(identifier, selector); } @@ -28,12 +34,19 @@ public interface Selector extends Function { return this.select(context); } + /** + * Selects a {@link ServerCommandSource} based on the provided {@link LootContext}. + * @return {@link ServerCommandSource} extracted from the context or null. + */ @Nullable ServerCommandSource select(LootContext context); /** * Executable selector proxy. */ interface Conditioned { + /** + * @see Selector#select(LootContext) + */ Optional select(EventContext context); } } diff --git a/src/main/java/me/melontini/commander/api/event/EventType.java b/src/main/java/me/melontini/commander/api/event/EventType.java index 74bb4dd..a7031bc 100644 --- a/src/main/java/me/melontini/commander/api/event/EventType.java +++ b/src/main/java/me/melontini/commander/api/event/EventType.java @@ -5,9 +5,12 @@ import static me.melontini.commander.impl.Commander.id; import com.mojang.serialization.Codec; import java.util.List; import java.util.function.Function; + +import com.mojang.serialization.MapCodec; import me.melontini.commander.impl.event.EventTypeImpl; import me.melontini.dark_matter.api.base.util.Context; import net.minecraft.util.Identifier; +import org.jetbrains.annotations.Contract; import org.jetbrains.annotations.Nullable; /** @@ -32,11 +35,28 @@ public interface EventType extends Context { } interface Builder { + /** + * Adds parameters to event declarations. Prefer using a {@link MapCodec} to avoid conflicts in the future. + * @param extension The codec to decode parameters from JSON. + * @param finalizer The function to process event {@link Subscription}s with parameters. + */ + @Contract("_, _ -> this") Builder extension( @Nullable Codec extension, Function>, C> finalizer); + /** + * Adds a "cancel term" to the event. + * This allows invoking the {@code commander:cancel} command from JSON to modify the return type. + * @param returnCodec The codec to decode the object from JSON. + */ + @Contract("_ -> this") Builder cancelTerm(Codec returnCodec); + /** + * Builds and registers the {@link EventType}. + * @param identifier The event type identifier. + * @return Newly constructed {@link EventType} instance. + */ EventType build(Identifier identifier); } } diff --git a/src/main/java/me/melontini/commander/api/event/Subscription.java b/src/main/java/me/melontini/commander/api/event/Subscription.java index 8b73aa1..1764fe2 100644 --- a/src/main/java/me/melontini/commander/api/event/Subscription.java +++ b/src/main/java/me/melontini/commander/api/event/Subscription.java @@ -1,20 +1,40 @@ package me.melontini.commander.api.event; import java.util.List; +import java.util.function.Function; + +import com.mojang.serialization.Codec; import me.melontini.commander.api.command.Command; import me.melontini.commander.impl.event.data.DynamicEventManager; import net.minecraft.server.MinecraftServer; +import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.Nullable; +@ApiStatus.NonExtendable public interface Subscription { + /** + * Returns all data for the event from the current server. + * @param server The current server instance. + * @param type The event type. + * @return Data associated with the event or null if the {@link EventType.Builder#extension(Codec, Function)} returns null. + */ static @Nullable T getData(MinecraftServer server, EventType type) { return DynamicEventManager.getData(server, type); } + /** + * @return Subscribed event type. + */ EventType type(); - E parameters(); + /** + * @return Event parameters or null if {@link EventType.Builder#extension(Codec, Function)} was not specified. + */ + @Nullable E parameters(); + /** + * @return {@link Command.Conditioned} parsed from the subscription file. + */ List list(); } diff --git a/src/main/java/me/melontini/commander/api/expression/Arithmetica.java b/src/main/java/me/melontini/commander/api/expression/Arithmetica.java index 6f5f4b9..e7fe342 100644 --- a/src/main/java/me/melontini/commander/api/expression/Arithmetica.java +++ b/src/main/java/me/melontini/commander/api/expression/Arithmetica.java @@ -9,6 +9,7 @@ import java.util.function.ToDoubleFunction; import me.melontini.commander.impl.expression.intermediaries.ConstantArithmetica; import me.melontini.commander.impl.expression.intermediaries.DynamicArithmetica; import net.minecraft.loot.context.LootContext; +import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.Contract; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; @@ -19,6 +20,7 @@ import org.jetbrains.annotations.Nullable; * * @see Expression */ +@ApiStatus.NonExtendable public interface Arithmetica extends ToDoubleFunction, ToDoubleBiFunction> { @@ -63,13 +65,11 @@ public interface Arithmetica @Contract("_ -> new") static @NotNull Arithmetica constant(double d) { - Either either = Either.left(d); - return new ConstantArithmetica(either, d); + return new ConstantArithmetica(Either.left(d), d); } static @NotNull Arithmetica of(Expression expression) { - Either either = Either.right(expression.original()); - return new DynamicArithmetica(either, expression); + return new DynamicArithmetica(Either.right(expression.original()), expression); } @Override diff --git a/src/main/java/me/melontini/commander/api/expression/BooleanExpression.java b/src/main/java/me/melontini/commander/api/expression/BooleanExpression.java index 7114a54..9158559 100644 --- a/src/main/java/me/melontini/commander/api/expression/BooleanExpression.java +++ b/src/main/java/me/melontini/commander/api/expression/BooleanExpression.java @@ -10,6 +10,7 @@ import me.melontini.commander.impl.expression.intermediaries.ConstantBooleanExpr import me.melontini.commander.impl.expression.intermediaries.DynamicBooleanExpression; import me.melontini.commander.impl.expression.intermediaries.NegatedBooleanExpression; import net.minecraft.loot.context.LootContext; +import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.Contract; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; @@ -20,6 +21,7 @@ import org.jetbrains.annotations.Nullable; * * @see Expression */ +@ApiStatus.NonExtendable public interface BooleanExpression extends Predicate, BiPredicate> { @@ -39,14 +41,12 @@ public interface BooleanExpression @Contract("_ -> new") static @NotNull BooleanExpression constant(boolean b) { - Either either = Either.left(b); - return new ConstantBooleanExpression(either, b); + return b ? ConstantBooleanExpression.TRUE : ConstantBooleanExpression.FALSE; } @Contract("_ -> new") static @NotNull BooleanExpression of(Expression expression) { - Either either = Either.right(expression.original()); - return new DynamicBooleanExpression(either, expression); + return new DynamicBooleanExpression(Either.right(expression.original()), expression); } @Override diff --git a/src/main/java/me/melontini/commander/api/expression/BrigadierMacro.java b/src/main/java/me/melontini/commander/api/expression/BrigadierMacro.java index b70dce8..f3816a4 100644 --- a/src/main/java/me/melontini/commander/api/expression/BrigadierMacro.java +++ b/src/main/java/me/melontini/commander/api/expression/BrigadierMacro.java @@ -13,6 +13,7 @@ import org.jetbrains.annotations.Nullable; * A special type of string function with support for {@code ${{}}} macros. *

The main purpose is to enable command macros in {@code commander:commands}, but can be used anywhere else.

*/ +@ApiStatus.NonExtendable public interface BrigadierMacro extends Function { Codec CODEC = @@ -22,13 +23,24 @@ public interface BrigadierMacro extends Function { return PatternParser.parse(input); } + /** + * @return The command string with expression results inserted as strings. + * @see Expression#eval(LootContext) + */ default String build(LootContext context) { return this.build(context, null); } + /** + * @see #build(LootContext) + * @see Expression#eval(LootContext, Map) + */ @ApiStatus.Experimental String build(LootContext context, @Nullable Map params); + /** + * @return The original input string. + */ String original(); @Override diff --git a/src/main/java/me/melontini/commander/api/expression/Expression.java b/src/main/java/me/melontini/commander/api/expression/Expression.java index d90ae78..2a80473 100644 --- a/src/main/java/me/melontini/commander/api/expression/Expression.java +++ b/src/main/java/me/melontini/commander/api/expression/Expression.java @@ -11,9 +11,11 @@ import java.util.function.Function; import me.melontini.commander.impl.expression.EvalUtils; import me.melontini.commander.impl.expression.extensions.ReflectiveValueConverter; import net.minecraft.loot.context.LootContext; +import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; +@ApiStatus.NonExtendable public interface Expression extends Function { Codec CODEC = Codec.STRING.comapFlatMap(Expression::parse, Expression::original); @@ -36,8 +38,12 @@ public interface Expression extends Function { */ Result eval(LootContext context, @Nullable Map parameters); + /** + * @return The original expression string. + */ String original(); + @ApiStatus.NonExtendable interface Result { Result NULL = (Result) (Object) NullValue.of(); diff --git a/src/main/java/me/melontini/commander/api/expression/ExpressionLibrary.java b/src/main/java/me/melontini/commander/api/expression/ExpressionLibrary.java index 98d0d60..5c6cbe3 100644 --- a/src/main/java/me/melontini/commander/api/expression/ExpressionLibrary.java +++ b/src/main/java/me/melontini/commander/api/expression/ExpressionLibrary.java @@ -4,8 +4,13 @@ import java.util.Map; import me.melontini.commander.impl.expression.library.ExpressionLibraryLoader; import net.minecraft.server.MinecraftServer; import net.minecraft.util.Identifier; +import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.UnmodifiableView; +/** + * Provides access to user defined expression library. + */ +@ApiStatus.NonExtendable public interface ExpressionLibrary { static ExpressionLibrary get(MinecraftServer server) { diff --git a/src/main/java/me/melontini/commander/api/expression/LongExpression.java b/src/main/java/me/melontini/commander/api/expression/LongExpression.java index 703c09b..ba01821 100644 --- a/src/main/java/me/melontini/commander/api/expression/LongExpression.java +++ b/src/main/java/me/melontini/commander/api/expression/LongExpression.java @@ -9,10 +9,18 @@ import java.util.function.ToLongFunction; import me.melontini.commander.impl.expression.intermediaries.ConstantLongExpression; import me.melontini.commander.impl.expression.intermediaries.DynamicLongExpression; import net.minecraft.loot.context.LootContext; +import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.Contract; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; +/** + * A simple {@code context -> long} functions, which is encoded as either a long or an expression. + *

Can be used as a substitute for {@link Codec#LONG} if {@link LootContext} is available

+ * + * @see Expression + */ +@ApiStatus.NonExtendable public interface LongExpression extends ToLongFunction, ToLongBiFunction> { @@ -40,13 +48,11 @@ public interface LongExpression @Contract("_ -> new") static @NotNull LongExpression constant(long j) { - Either either = Either.left(j); - return new ConstantLongExpression(either, j); + return new ConstantLongExpression(Either.left(j), j); } static @NotNull LongExpression of(Expression expression) { - Either either = Either.right(expression.original()); - return new DynamicLongExpression(either, expression); + return new DynamicLongExpression(Either.right(expression.original()), expression); } @Override diff --git a/src/main/java/me/melontini/commander/api/expression/extensions/AbstractProxyMap.java b/src/main/java/me/melontini/commander/api/expression/extensions/AbstractProxyMap.java index ee330d0..adb40f1 100644 --- a/src/main/java/me/melontini/commander/api/expression/extensions/AbstractProxyMap.java +++ b/src/main/java/me/melontini/commander/api/expression/extensions/AbstractProxyMap.java @@ -5,8 +5,7 @@ import me.melontini.commander.api.expression.Expression; import org.jetbrains.annotations.ApiStatus; /** - * These maps must implement 3 methods: {@link #containsKey(Object)}, {@link #get(Object)} and {@link #entrySet()}. - * It's recommended to lazily convert map entries, especially if the map is large. + * @see ProxyMap */ @ApiStatus.Experimental public abstract class AbstractProxyMap extends AbstractMap diff --git a/src/main/java/me/melontini/commander/api/expression/extensions/CustomDataAccessor.java b/src/main/java/me/melontini/commander/api/expression/extensions/CustomDataAccessor.java index 7cb0dd9..d04166e 100644 --- a/src/main/java/me/melontini/commander/api/expression/extensions/CustomDataAccessor.java +++ b/src/main/java/me/melontini/commander/api/expression/extensions/CustomDataAccessor.java @@ -6,10 +6,23 @@ import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.Nullable; /** - * A contextual data accessor. Can be implemented on objects to automatically support expression access. + * A contextual data accessor. Can be implemented on objects to automatically support expression access.
+ * You might prefer using {@link ProxyMap} if your implementation is backed by a map. */ +@ApiStatus.OverrideOnly @ApiStatus.Experimental public interface CustomDataAccessor { + /** + * Returns {@link Expression.Result} or null if there's no such field. + * {@code null} and {@link Expression.Result#NULL} mean different things here: + *
    + *
  • {@link Expression.Result#NULL} represents a present value which is null.
    • + *
  • {@code null} represents no value.
    • + *
+ * @param variable The requested variable or field. + * @param context The current loot context. + * @return {@link Expression.Result} or null if there's no such field. + */ @Nullable Expression.Result getExpressionData(String variable, LootContext context) throws Exception; } diff --git a/src/main/java/me/melontini/commander/api/expression/extensions/ProxyMap.java b/src/main/java/me/melontini/commander/api/expression/extensions/ProxyMap.java index 9236f9b..a7a0daa 100644 --- a/src/main/java/me/melontini/commander/api/expression/extensions/ProxyMap.java +++ b/src/main/java/me/melontini/commander/api/expression/extensions/ProxyMap.java @@ -5,5 +5,7 @@ import me.melontini.commander.api.expression.Expression; /** * A special type of map which guarantees the type of {@code }.
+ * These maps must implement 3 methods: {@link #containsKey(Object)}, {@link #get(Object)} and {@link #entrySet()}. + * It's recommended to lazily convert map entries, especially if the map is large. */ public interface ProxyMap extends Map {} diff --git a/src/main/java/me/melontini/commander/api/util/EventExecutors.java b/src/main/java/me/melontini/commander/api/util/EventExecutors.java index 000a894..16c8a4a 100644 --- a/src/main/java/me/melontini/commander/api/util/EventExecutors.java +++ b/src/main/java/me/melontini/commander/api/util/EventExecutors.java @@ -18,6 +18,10 @@ import net.minecraft.util.ActionResult; import net.minecraft.world.World; import org.jetbrains.annotations.Nullable; +/** + * A utility to execute generic event types. + * Cannot be used if the {@link EventType} specifies parameters. + */ @UtilityClass public class EventExecutors { public static void runVoid(EventType type, @NonNull World world, Supplier supplier) { diff --git a/src/main/java/me/melontini/commander/impl/expression/intermediaries/ConstantBooleanExpression.java b/src/main/java/me/melontini/commander/impl/expression/intermediaries/ConstantBooleanExpression.java index d59c639..88d70c6 100644 --- a/src/main/java/me/melontini/commander/impl/expression/intermediaries/ConstantBooleanExpression.java +++ b/src/main/java/me/melontini/commander/impl/expression/intermediaries/ConstantBooleanExpression.java @@ -9,12 +9,16 @@ import org.jetbrains.annotations.Nullable; @EqualsAndHashCode public final class ConstantBooleanExpression implements BooleanExpression { + + public static final ConstantBooleanExpression TRUE = new ConstantBooleanExpression(Either.left(true), true); + public static final ConstantBooleanExpression FALSE = new ConstantBooleanExpression(Either.left(false), false); + @EqualsAndHashCode.Exclude private final Either either; private final boolean value; - public ConstantBooleanExpression(Either either, boolean value) { + private ConstantBooleanExpression(Either either, boolean value) { this.either = either; this.value = value; } -- 2.51.2