Add standalone structure channel definitions

src/main/java/com/gtnewhorizon/structurelib/alignment/constructable/ChannelDataAccessor.java

@@ -38,7 +38,9 @@ private ChannelDataAccessor() {}
      * If given subchannel does not exist, masterStack may or may not be returned to save performance. Code within
      * StructureLib can depend on this behavior, you cannot.
      *
-     * @param masterStack trigger item. can be the return value of another {@link #withChannel(ItemStack, String)} call
+     * @param masterStack trigger item. can be the return value of another
+     *                    {@link com.gtnewhorizon.structurelib.alignment.constructable.ChannelDataAccessor#withChannel(net.minecraft.item.ItemStack, String)}
+     *                    call
      * @param channel     subchannel to use. will use current master channel data instead if this channel does not exist
      *                    Note: all channel identifiers are supposed to be lower case and not empty.
      * @return a trigger item with new master channel
@@ -107,13 +109,13 @@ public static int getChannelData(ItemStack masterStack, String channel) {
      * 
      * @param masterStack trigger stack to check
      * @param channel     channel identifier. Note: all channel identifiers are supposed to be lower case and not empty.
-     * @param data        subchannel data. should always be a positive value
+     * @param data        positive subchannel data
      */
     public static void setChannelData(ItemStack masterStack, String channel, int data) {
         if (StringUtils.isEmpty(channel) || masterStack == null) throw new IllegalArgumentException();
+        if (data < 1) throw new IllegalArgumentException("Channel data must be positive");
         if (StructureLibAPI.isDebugEnabled() && !channel.toLowerCase(Locale.ROOT).equals(channel))
             throw new IllegalArgumentException("Channel name can be lower case ONLY");
-        if (data <= 0) throw new IllegalArgumentException();
         if (masterStack.stackTagCompound == null) masterStack.stackTagCompound = new NBTTagCompound();
         NBTTagCompound main = masterStack.stackTagCompound;
         if (!main.hasKey(SECONDARY_HINT_TAG, TAG_COMPOUND)) main.setTag(SECONDARY_HINT_TAG, new NBTTagCompound());

src/main/java/com/gtnewhorizon/structurelib/command/CommandConfigureChannels.java

@@ -26,7 +26,7 @@ public String getCommandName() {
     public String getCommandUsage(ICommandSender p_71518_1_) {
         return "/sl_channel <wipe/getall>\n" + "/sl_channel <get/unset> <channel name>\n"
                 + "/sl_channel <set> <channel name> <value>\n"
-                + "<channel name> can have space in it. <value> must be positive integer";
+                + "<channel name> can have space in it. Values below 1 clear the channel";
     }
 
     @Override
@@ -108,11 +108,14 @@ public void processCommand(ICommandSender sender, String[] args) {
                     throw new WrongUsageException("%s not a valid value", args[args.length - 1]);
                 }
 
-                if (value <= 0) throw new WrongUsageException("%s not a valid value", args[args.length - 1]);
-
-                ChannelDataAccessor.setChannelData(heldItem, channel, value);
+                if (value < 1) {
+                    ChannelDataAccessor.unsetChannelData(heldItem, channel);
+                } else {
+                    ChannelDataAccessor.setChannelData(heldItem, channel, value);
+                }
                 player.inventoryContainer.detectAndSendChanges();
-                sender.addChatMessage(new ChatComponentText(channel + " value: " + value));
+                sender.addChatMessage(
+                        new ChatComponentText(value < 1 ? channel + " no value" : channel + " value: " + value));
                 break;
         }
     }

src/main/java/com/gtnewhorizon/structurelib/structure/IChannelDefinition.java

@@ -0,0 +1,98 @@
+package com.gtnewhorizon.structurelib.structure;
+
+/**
+ * Describes a channel used by one structure definition.
+ *
+ * <p>
+ * Channel values are integers stored on the constructable trigger item. Implementations may override the default
+ * validation and normalization policy when a simple bounded range is not sufficient.
+ * </p>
+ */
+public interface IChannelDefinition {
+
+    /**
+     * Creates a channel with a bounded inclusive range and clamping normalization.
+     *
+     * @param channel      channel identifier
+     * @param minimumValue inclusive minimum value
+     * @param maximumValue inclusive maximum value
+     * @return bounded channel definition
+     */
+    static IChannelDefinition bounded(String channel, int minimumValue, int maximumValue) {
+        if (minimumValue < 1 || maximumValue < minimumValue) {
+            throw new IllegalArgumentException("Invalid channel bounds");
+        }
+        return new IChannelDefinition() {
+
+            @Override
+            public String getChannel() {
+                return channel;
+            }
+
+            @Override
+            public int getMinimumValue() {
+                return minimumValue;
+            }
+
+            @Override
+            public int getMaximumValue() {
+                return maximumValue;
+            }
+        };
+    }
+
+    /**
+     * Creates a channel accepting every positive integer.
+     *
+     * @param channel channel identifier
+     * @return unbounded channel definition
+     */
+    static IChannelDefinition unbounded(String channel) {
+        return () -> channel;
+    }
+
+    /**
+     * Returns the lower-case channel identifier.
+     *
+     * @return channel identifier
+     */
+    String getChannel();
+
+    /**
+     * Returns the smallest value advertised by this definition. The default is {@code 1}.
+     *
+     * @return minimum value
+     */
+    default int getMinimumValue() {
+        return 1;
+    }
+
+    /**
+     * Returns the largest value advertised by this definition. The default is {@link java.lang.Integer#MAX_VALUE}.
+     *
+     * @return maximum value
+     */
+    default int getMaximumValue() {
+        return Integer.MAX_VALUE;
+    }
+
+    /**
+     * Checks whether a value is already valid without normalization.
+     *
+     * @param value value to check
+     * @return true when the value is valid
+     */
+    default boolean isValueValid(int value) {
+        return value >= getMinimumValue() && value <= getMaximumValue();
+    }
+
+    /**
+     * Converts a stored value to the value used by the structure definition.
+     *
+     * @param value stored value
+     * @return normalized value
+     */
+    default int normalizeValue(int value) {
+        return Math.max(getMinimumValue(), Math.min(getMaximumValue(), value));
+    }
+}

src/main/java/com/gtnewhorizon/structurelib/structure/IStructureDefinition.java

@@ -3,6 +3,8 @@
 import static com.gtnewhorizon.structurelib.structure.IStructureWalker.ignoreBlockUnloaded;
 import static com.gtnewhorizon.structurelib.structure.IStructureWalker.skipBlockUnloaded;
 
+import java.util.Collection;
+import java.util.Collections;
 import java.util.function.Function;
 
 import net.minecraft.entity.player.EntityPlayer;
@@ -26,7 +28,7 @@
  * have a template for subclass. You can also use {@link StructureUtility#defer(Function) defer()} or its overloads for
  * simpler cases, but it is slightly less performant as it will allocate new objects on each structure check, whereas
  * {@link ClassValue} will allocate once and cache it onwards.
  * <p>
  * <h2>Constructing</h2>
  * <p>
  * {@linkplain IStructureDefinition} is constructed using {@link IStructureDefinition#builder()}
@@ -56,6 +58,48 @@
  */
 public interface IStructureDefinition<T> {
 
+    /**
+     * Returns channel definitions declared by this structure.
+     *
+     * @return an immutable or otherwise read-only channel collection
+     */
+    default Collection<IChannelDefinition> getChannelDefinitions() {
+        return Collections.emptyList();
+    }
+
+    /**
+     * Returns channel definitions explicitly added by the structure builder.
+     *
+     * @return explicitly declared channel definitions
+     */
+    default Collection<IChannelDefinition> getExplicitChannelDefinitions() {
+        return getChannelDefinitions();
+    }
+
+    /**
+     * Finds a channel definition by identifier.
+     *
+     * @param channel channel identifier
+     * @return channel definition, or {@code null} when it is not declared
+     */
+    default IChannelDefinition getChannelDefinition(String channel) {
+        for (IChannelDefinition definition : getChannelDefinitions()) {
+            if (definition.getChannel().equals(channel)) return definition;
+        }
+        return null;
+    }
+
+    /**
+     * Reads one channel using the standard trigger-item channel semantics.
+     *
+     * @param trigger trigger item containing channel data
+     * @param channel channel identifier
+     * @return stored channel data, or the trigger stack size when absent
+     */
+    default int getChannelData(ItemStack trigger, String channel) {
+        return ChannelDataAccessor.getChannelData(trigger, channel);
+    }
+
     /**
      * Used internally
      * <p>

src/main/java/com/gtnewhorizon/structurelib/structure/IStructureElement.java

@@ -4,6 +4,7 @@
 import static com.gtnewhorizon.structurelib.StructureLib.PANIC_MODE;
 
 import java.util.Arrays;
+import java.util.Collection;
 import java.util.Collections;
 import java.util.List;
 import java.util.function.Consumer;
@@ -29,10 +30,19 @@
  * Use StructureUtility to instantiate. These are the building blocks for your {@link IStructureDefinition}. It
  * represents what a particular element can be and how this particular element should be autoplaced.
  */
 public interface IStructureElement<T> {
 
     boolean check(T t, World world, int x, int y, int z);
 
+    /**
+     * Returns the channels used by this element.
+     *
+     * @return lower-case channel identifiers
+     */
+    default Collection<String> getChannels() {
+        return Collections.emptySet();
+    }
+
     /**
      * Pure (stateless and side effect free) function to test if current block could be valid. Used to give user hints
      * about incorrectly placed blocks given a controller and trigger item. If couldBeValid(...) == false for a set of