From 826fe08cfc8508cfefe4666c744054413cf5455d Mon Sep 17 00:00:00 2001 From: benwoo1110 <30431861+benwoo1110@users.noreply.github.com> Date: Fri, 5 Mar 2021 13:51:52 +0800 Subject: [PATCH] Add documentation to flag classes, --- .../commandTools/flags/CommandFlag.java | 94 ++++++++++++++++++- .../commandTools/flags/FlagGroup.java | 33 +++---- .../commandTools/flags/MVFlags.java | 52 +++++++--- .../flags/NoValueCommandFlag.java | 14 +++ .../flags/OptionalCommandFlag.java | 5 + .../flags/RequiredCommandFlag.java | 10 ++ .../commands/CreateCommand.java | 3 +- .../commands/ImportCommand.java | 2 +- .../MultiverseCore/commands/RegenCommand.java | 2 +- 9 files changed, 176 insertions(+), 39 deletions(-) diff --git a/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/CommandFlag.java b/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/CommandFlag.java index 7100fc8d..0543e0a1 100644 --- a/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/CommandFlag.java +++ b/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/CommandFlag.java @@ -4,17 +4,34 @@ import org.jetbrains.annotations.NotNull; import java.util.ArrayList; import java.util.Collection; -import java.util.List; +import java.util.Collections; +/** + *

Represents a flag that can be used in commands. This works as a key value pair.

+ * + *

Key is the {@link #identifier} and {@link #aliases} set.

+ *

Value is the {@link T} parsed based on 3 scenarios during command input:

+ *
    + *
  1. Flag completely not present. {@link #getDefaultValue()}
    2. + *
  2. Flag key present but no value. {@link #getValue()}
    3. + *
  3. Flag key and value present. {@link #getValue(String)}
    4. + *
+ * + * @param The flag Type. + */ public abstract class CommandFlag { protected final String name; protected final String identifier; protected final Class type; protected final ValueRequirement valueRequirement; - protected final List aliases; + protected final Collection aliases; + + protected CommandFlag(@NotNull String name, + @NotNull String identifier, + @NotNull Class type, + @NotNull ValueRequirement valueRequirement) { - public CommandFlag(String name, String identifier, Class type, ValueRequirement valueRequirement) { this.name = name; this.identifier = identifier; this.type = type; @@ -22,39 +39,95 @@ public abstract class CommandFlag { this.aliases = new ArrayList<>(); } + /** + * Gets name of the Command Flag. + * + * @return The Command Flag name. + */ + @NotNull public String getName() { return this.name; } + /** + * Gets identifier of the Command Flag. + * + * @return The Command Flag identifier. + */ + @NotNull public String getIdentifier() { return this.identifier; } + /** + * Gets {@link T} Type of the Command Flag. + * + * @return The Command Flag type. + */ + @NotNull public Class getType() { return this.type; } + /** + * Gets the requirements of this Command Flag user input value. + * + * @return The {@link ValueRequirement}. + */ + @NotNull public ValueRequirement getValueRequirement() { return this.valueRequirement; } + /** + * Gets all the alternative key identifiers set for this Command Flag. + * + * @return Collection of aliases. + */ + @NotNull public Collection getAliases() { return this.aliases; } - CommandFlag addAlias(String alias) { - this.aliases.add(alias); + /** + * Add alternative key identifiers for this Command Flag. + * + * @param aliases Alias(es) to be added. + * @return A {@link CommandFlag}. + */ + public CommandFlag addAliases(String...aliases) { + Collections.addAll(this.aliases, aliases); return this; } + /** + * Tab-complete suggestion for this Command Flag values. + * + * @return Collection of suggested values available. + */ public abstract Collection suggestValue(); + /** + * When this Command Flag can get value by a user input. + * + * @return The {@link T} value. + */ public abstract T getValue(@NotNull String input) throws FlagParseFailedException; + /** + * When this Command Flag user input value is null/not present. + * + * @return The {@link T} value. + */ public T getValue() throws FlagParseFailedException { return null; } + /** + * When this Command Flag is not present in command input. + * + * @return The {@link T} value. + */ public T getDefaultValue() { return null; } @@ -71,8 +144,19 @@ public abstract class CommandFlag { } public enum ValueRequirement { + /** + * No user input needed for value. + */ NONE, + + /** + * User input for value is optional. + */ OPTIONAL, + + /** + * User input is required for Command Flag value. + */ REQUIRED } } diff --git a/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/FlagGroup.java b/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/FlagGroup.java index 0b59a234..d41fd515 100644 --- a/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/FlagGroup.java +++ b/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/FlagGroup.java @@ -1,12 +1,13 @@ package com.onarandombox.MultiverseCore.commandtools.flags; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; + import java.util.ArrayList; import java.util.Collection; import java.util.HashMap; -import java.util.HashSet; import java.util.List; import java.util.Map; -import java.util.Set; public class FlagGroup { @@ -14,36 +15,36 @@ public class FlagGroup { return new FlagGroup(flags); } - private final Set> flags; private final List flagIdentifiers; - private final Map> keyFlagMap; + private final Map> flagKeyMap; private FlagGroup(CommandFlag[] commandFlags) { - this.flags = new HashSet<>(commandFlags.length); this.flagIdentifiers = new ArrayList<>(commandFlags.length); - this.keyFlagMap = new HashMap<>(); + this.flagKeyMap = new HashMap<>(); for (CommandFlag flag : commandFlags) { addFlag(flag); } } private void addFlag(CommandFlag flag) { - this.flags.add(flag); this.flagIdentifiers.add(flag.getIdentifier()); - this.keyFlagMap.put(flag.getIdentifier(), flag); + this.flagKeyMap.put(flag.getIdentifier(), flag); for (String flagAlias : flag.getAliases()) { - this.keyFlagMap.put(flagAlias, flag); + this.flagKeyMap.put(flagAlias, flag); } } + @NotNull + public FlagResult calculateResult(String[] args) { + return FlagResult.parse(args,this); + } + + @Nullable public CommandFlag getByKey(String key) { - return this.keyFlagMap.get(key); - } - - public Collection> getFlags() { - return this.flags; + return this.flagKeyMap.get(key); } + @NotNull public Collection getFlagIdentifiers() { return flagIdentifiers; } @@ -51,8 +52,8 @@ public class FlagGroup { @Override public String toString() { return "FlagGroup{" + - "flags=" + flags + - ", keyFlagMap=" + keyFlagMap + + "flagIdentifiers=" + flagIdentifiers + + ", keyFlagMap=" + flagKeyMap + '}'; } } diff --git a/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/MVFlags.java b/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/MVFlags.java index bba12a50..eab8f1bc 100644 --- a/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/MVFlags.java +++ b/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/MVFlags.java @@ -22,8 +22,11 @@ public class MVFlags { multiverse = plugin; } + /** + * Flag for custom seed. + */ public static final CommandFlag SEED = new RequiredCommandFlag - ("Seed", "-s", String.class) { + ("Seed", "--seed", String.class) { @Override public Collection suggestValue() { return Arrays.asList("seed", String.valueOf(new Random().nextLong())); @@ -33,10 +36,13 @@ public class MVFlags { public String getValue(@NotNull String input) throws FlagParseFailedException { return input; } - }; + }.addAliases("-s"); + /** + * Flag for custom seed. No value means random seed. + */ public static final CommandFlag RANDOM_SEED = new OptionalCommandFlag - ("Seed", "-s", String.class) { + ("Seed", "--seed", String.class) { @Override public Collection suggestValue() { return Arrays.asList("seed", String.valueOf(new Random().nextLong())); @@ -46,10 +52,13 @@ public class MVFlags { public String getValue(@NotNull String input) throws FlagParseFailedException { return input; } - }; + }.addAliases("-s"); + /** + * Flag for world type used. + */ public static final CommandFlag WORLD_TYPE = new RequiredCommandFlag - ("WorldType", "-t", WorldType.class) { + ("WorldType", "--type", WorldType.class) { private final Map typeAlias = new HashMap(4){{ put("normal", WorldType.NORMAL); @@ -81,10 +90,13 @@ public class MVFlags { public WorldType getDefaultValue() { return WorldType.NORMAL; } - }; + }.addAliases("-t"); + /** + * Flag for world generator. + */ public static final CommandFlag GENERATOR = new RequiredCommandFlag - ("Generator", "-g", String.class) { + ("Generator", "--gen", String.class) { @Override public Collection suggestValue() { return multiverse.getMVWorldManager().getAvailableWorldGenerators(); @@ -104,10 +116,13 @@ public class MVFlags { } return input; } - }; + }.addAliases("-g"); + /** + * Flag to toggle if world should generate structures. + */ public static final CommandFlag GENERATE_STRUCTURES = new RequiredCommandFlag - ("GenerateStructures", "-a", Boolean.class) { + ("GenerateStructures", "--structures", Boolean.class) { @Override public Collection suggestValue() { return Arrays.asList("true", "false"); @@ -122,10 +137,13 @@ public class MVFlags { public Boolean getDefaultValue() { return true; } - }; + }.addAliases("--structure", "-a"); + /** + * Flag to toggle if world spawn should be adjusted. + */ public static final CommandFlag SPAWN_ADJUST = new NoValueCommandFlag - ("AdjustSpawn", "-n", Boolean.class) { + ("AdjustSpawn", "--dont-adjust-spawn", Boolean.class) { @Override public Boolean getValue() throws FlagParseFailedException { return false; @@ -135,8 +153,11 @@ public class MVFlags { public Boolean getDefaultValue() { return true; } - }; + }.addAliases("-n"); + /** + * Flag to specify a paste service. + */ public static final CommandFlag PASTE_SERVICE_TYPE = new OptionalCommandFlag ("PasteServiceType", "--paste", PasteServiceType.class) { @@ -169,8 +190,11 @@ public class MVFlags { public PasteServiceType getDefaultValue() { return PasteServiceType.NONE; } - }.addAlias("-p"); + }.addAliases("-p"); + /** + * Flag to toggle if plugin list should be included. + */ public static final CommandFlag INCLUDE_PLUGIN_LIST = new NoValueCommandFlag ("IncludePlugins", "--include-plugin-list", Boolean.class) { @Override @@ -182,5 +206,5 @@ public class MVFlags { public Boolean getDefaultValue() { return true; } - }.addAlias("-pl"); + }.addAliases("-pl"); } diff --git a/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/NoValueCommandFlag.java b/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/NoValueCommandFlag.java index c2eb2690..895eda77 100644 --- a/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/NoValueCommandFlag.java +++ b/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/NoValueCommandFlag.java @@ -5,17 +5,31 @@ import org.jetbrains.annotations.NotNull; import java.util.Collection; import java.util.Collections; +/** + * Command Flag with {@link ValueRequirement#NONE}. + * This flag will always not require a user input to parse value. + * + * @param The flag Type. + */ public abstract class NoValueCommandFlag extends CommandFlag { public NoValueCommandFlag(String name, String identifier, Class type) { super(name, identifier, type, ValueRequirement.NONE); } + /** + * {@link NoValueCommandFlag} will always not require a user input to parse value. + * Thus, no value suggestion needed. + */ @Override public final Collection suggestValue() { return Collections.emptyList(); } + /** + * {@link NoValueCommandFlag} will always not require a user input to parse value. + * Thus, this operation is not allowed. + */ @Override public final T getValue(@NotNull String input) throws FlagParseFailedException { throw new FlagParseFailedException("%s flag '%s' does not require a value.", this.name, this.identifier); diff --git a/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/OptionalCommandFlag.java b/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/OptionalCommandFlag.java index 72848294..264e18ed 100644 --- a/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/OptionalCommandFlag.java +++ b/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/OptionalCommandFlag.java @@ -1,5 +1,10 @@ package com.onarandombox.MultiverseCore.commandtools.flags; +/** + * Command Flag with {@link ValueRequirement#OPTIONAL}. + * + * @param The flag Type. + */ public abstract class OptionalCommandFlag extends CommandFlag { public OptionalCommandFlag(String name, String identifier, Class type) { diff --git a/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/RequiredCommandFlag.java b/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/RequiredCommandFlag.java index 5d124961..d77f1221 100644 --- a/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/RequiredCommandFlag.java +++ b/src/main/java/com/onarandombox/MultiverseCore/commandTools/flags/RequiredCommandFlag.java @@ -1,11 +1,21 @@ package com.onarandombox.MultiverseCore.commandtools.flags; +/** + * Command Flag with {@link ValueRequirement#REQUIRED}. + * This flag will always require a user input to parse value. + * + * @param The flag Type. + */ public abstract class RequiredCommandFlag extends CommandFlag { public RequiredCommandFlag(String name, String identifier, Class type) { super(name, identifier, type, ValueRequirement.REQUIRED); } + /** + * {@link RequiredCommandFlag} will always require a user input to parse value. + * Thus, this operation is not allowed. + */ @Override public final T getValue() throws FlagParseFailedException { throw new FlagParseFailedException("%s flag '%s' requires a value input.", this.name, this.identifier); diff --git a/src/main/java/com/onarandombox/MultiverseCore/commands/CreateCommand.java b/src/main/java/com/onarandombox/MultiverseCore/commands/CreateCommand.java index a35400ce..28aa6eca 100644 --- a/src/main/java/com/onarandombox/MultiverseCore/commands/CreateCommand.java +++ b/src/main/java/com/onarandombox/MultiverseCore/commands/CreateCommand.java @@ -65,8 +65,7 @@ public class CreateCommand extends MultiverseCoreCommand { @Description("Other world settings. See: http://gg.gg/nn8bl") String[] flagsArray) { - FlagResult flags = FlagResult.parse(flagsArray, this.getFlagGroup()); - Logging.info(String.valueOf(flags)); + FlagResult flags = this.getFlagGroup().calculateResult(flagsArray); Command.broadcastCommandMessage(sender, String.format("Starting creation of world '%s'...", worldName)); Command.broadcastCommandMessage(sender, (this.plugin.getMVWorldManager().addWorld( diff --git a/src/main/java/com/onarandombox/MultiverseCore/commands/ImportCommand.java b/src/main/java/com/onarandombox/MultiverseCore/commands/ImportCommand.java index a28ecc77..7d4ce542 100644 --- a/src/main/java/com/onarandombox/MultiverseCore/commands/ImportCommand.java +++ b/src/main/java/com/onarandombox/MultiverseCore/commands/ImportCommand.java @@ -55,7 +55,7 @@ public class ImportCommand extends MultiverseCoreCommand { @Description("Other world settings. See: http://gg.gg/nn8c2") String[] flagsArray) { - FlagResult flags = FlagResult.parse(flagsArray, this.getFlagGroup()); + FlagResult flags = this.getFlagGroup().calculateResult(flagsArray); Command.broadcastCommandMessage(sender, String.format("Starting import of world '%s'...", worldName)); Command.broadcastCommandMessage(sender, (this.plugin.getMVWorldManager().addWorld(worldName, diff --git a/src/main/java/com/onarandombox/MultiverseCore/commands/RegenCommand.java b/src/main/java/com/onarandombox/MultiverseCore/commands/RegenCommand.java index 83cc79fd..8cf7d0df 100644 --- a/src/main/java/com/onarandombox/MultiverseCore/commands/RegenCommand.java +++ b/src/main/java/com/onarandombox/MultiverseCore/commands/RegenCommand.java @@ -50,7 +50,7 @@ public class RegenCommand extends MultiverseCoreCommand { @Description("Other world settings. See: http://gg.gg/nn8lk") String[] flagsArray) { - FlagResult flags = FlagResult.parse(flagsArray, this.getFlagGroup()); + FlagResult flags = this.getFlagGroup().calculateResult(flagsArray); this.plugin.getMVCommandManager().getQueueManager().addToQueue(new QueuedCommand.Builder() .sender(sender)