Add wildcard matching

2 files changed, 111 insertions, 0 deletions

diff --git a/api/src/main/java/me/shedaniel/rei/api/common/entry/EntryStack.java b/api/src/main/java/me/shedaniel/rei/api/common/entry/EntryStack.java
index 74529de5c..da37a0432 100644
--- a/api/src/main/java/me/shedaniel/rei/api/common/entry/EntryStack.java
+++ b/api/src/main/java/me/shedaniel/rei/api/common/entry/EntryStack.java
@@ -52,6 +52,7 @@ import java.util.function.Function;
 /**
  * @see me.shedaniel.rei.api.common.util.EntryStacks
  */
+@ApiStatus.NonExtendable
 public interface EntryStack<T> extends TextRepresentable, Renderer {
     static EntryStack<Unit> empty() {
         return Internals.getEntryStackProvider().empty();
@@ -122,14 +123,54 @@ public interface EntryStack<T> extends TextRepresentable, Renderer {
     
     boolean isEmpty();
     
+    /**
+     * Returns a copy of this stack.
+     * The copied stack will retain the same settings applied, with a copied value.
+     *
+     * @return a copy for an entry
+     */
     EntryStack<T> copy();
     
+    /**
+     * Returns a copy of this stack.
+     * The copied stack will retain the value object, with no settings applied.
+     *
+     * @return a copy for an entry
+     */
     default EntryStack<T> rewrap() {
         return copy();
     }
     
+    /**
+     * Returns a copy of this stack.
+     * The copied stack will have no settings applied.
+     * <p>
+     * The new value should be functionally equivalent to the original value,
+     * but should have a normalized state.
+     * <p>
+     * For example, an {@link net.minecraft.world.item.ItemStack} should have its
+     * amount removed, but its tags kept.
+     *
+     * @return a copy for an entry
+     */
     EntryStack<T> normalize();
     
+    /**
+     * Returns a copy of this stack.
+     * The copied stack will have no settings applied.
+     * <p>
+     * The new value should be the bare minimum to match the original value.
+     * <p>
+     * For example, an {@link net.minecraft.world.item.ItemStack} should have its
+     * amount and tags removed.
+     *
+     * @return a copy for an entry
+     * @since 6.2
+     */
+    default EntryStack<T> wildcard() {
+        return normalize();
+    }
+    
     Collection<ResourceLocation> getTagsFor();
     
     @Deprecated
diff --git a/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryDefinition.java b/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryDefinition.java
index 81e2a93dd..343a3491c 100644
--- a/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryDefinition.java
+++ b/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryDefinition.java
@@ -46,22 +46,92 @@ import java.util.Collection;
  * @see EntryTypeRegistry
  */
 public interface EntryDefinition<T> {
+    /**
+     * Returns the type of the entry.
+     *
+     * @return the type of the entry
+     */
     Class<T> getValueType();
     
+    /**
+     * Returns the type of this definition. The type is also used for comparing the type of two definitions,
+     * as the definition does not guarantee object and reference equality.
+     *
+     * @return the type of this definition
+     */
     EntryType<T> getType();
     
+    /**
+     * Returns the renderer for this entry, this is used to render the entry, and provide tooltip.
+     * External plugins can extend this method using {@link me.shedaniel.rei.api.client.entry.renderer.EntryRendererRegistry}
+     * to provide custom renderers.
+     *
+     * @return the renderer for this entry
+     */
     @Environment(EnvType.CLIENT)
     EntryRenderer<T> getRenderer();
     
+    /**
+     * Returns the identifier for an entry, used in identifier search argument type,
+     * and appending the mod name to the tooltip.
+     *
+     * @param entry the entry
+     * @param value the value of the entry
+     * @return the identifier for an entry
+     */
     @Nullable
     ResourceLocation getIdentifier(EntryStack<T> entry, T value);
     
+    /**
+     * Returns whether the entry is empty, empty entries are not displayed,
+     * and are considered invalid.
+     * Empty entries will be treated equally to {@link EntryStack#empty()}.
+     *
+     * @param entry the entry
+     * @param value the value of the entry
+     * @return whether the entry is empty
+     */
     boolean isEmpty(EntryStack<T> entry, T value);
     
+    /**
+     * Returns a copy for an entry.
+     *
+     * @param entry the entry
+     * @param value the value of the entry
+     * @return a copy for an entry
+     */
     T copy(EntryStack<T> entry, T value);
     
+    /**
+     * Returns a normalized copy for an entry.
+     * The returned stack should be functionally equivalent to the original stack,
+     * but should have a normalized state.
+     * <p>
+     * For example, an {@link net.minecraft.world.item.ItemStack} should have its
+     * amount removed, but its tags kept.
+     *
+     * @param entry the entry
+     * @param value the value of the entry
+     * @return a normalized copy for an entry
+     */
     T normalize(EntryStack<T> entry, T value);
     
+    /**
+     * Returns a wildcard copy for an entry.
+     * The returned stack should be the bare minimum to match the original stack.
+     * <p>
+     * For example, an {@link net.minecraft.world.item.ItemStack} should have its
+     * amount and tags removed.
+     *
+     * @param entry the entry
+     * @param value the value of the entry
+     * @return a wildcard copy for an entry
+     * @since 6.2
+     */
+    default T wildcard(EntryStack<T> entry, T value) {
+        return normalize(entry, value);
+    }
+    
     long hash(EntryStack<T> entry, T value, ComparisonContext context);
     
     boolean equals(T o1, T o2, ComparisonContext context);