From a26eb31a041c9657ab3c0a80e6ab91a3a3817fd5 Mon Sep 17 00:00:00 2001 From: MiniDigger Date: Thu, 8 Mar 2018 21:44:02 +0100 Subject: [PATCH 1/3] help improvements --- .../co/aikar/commands/CommandContexts.java | 9 ++++ .../java/co/aikar/commands/CommandHelp.java | 53 +++++++++++++++++++ .../java/co/aikar/commands/HelpEntry.java | 21 +++++++- .../java/co/aikar/commands/MessageKeys.java | 8 ++- languages/core/acf-core_en.properties | 6 ++- 5 files changed, 93 insertions(+), 4 deletions(-) diff --git a/core/src/main/java/co/aikar/commands/CommandContexts.java b/core/src/main/java/co/aikar/commands/CommandContexts.java index 7a0407ce..56b92577 100644 --- a/core/src/main/java/co/aikar/commands/CommandContexts.java +++ b/core/src/main/java/co/aikar/commands/CommandContexts.java @@ -232,6 +232,15 @@ public class CommandContexts helpEntries = new ArrayList<>(); + private final String commandName; private int page; private int perPage; private List search; + private HelpEntry selectedEntry; public CommandHelp(CommandManager manager, RootCommand rootCommand, CommandIssuer issuer) { this.manager = manager; this.issuer = issuer; this.perPage = manager.defaultHelpPerPage; + this.commandName = "/" + rootCommand.getCommandName(); SetMultimap subCommands = rootCommand.getSubCommands(); Set seen = new HashSet<>(); @@ -103,6 +106,16 @@ public class CommandHelp { return manager; } + public boolean isExactMatch(String command){ + for (HelpEntry helpEntry : helpEntries) { + if(helpEntry.getCommand().endsWith(" " + command)){ + selectedEntry = helpEntry; + return true; + } + } + return false; + } + public void showHelp() { showHelp(issuer, MessageKeys.HELP_FORMAT); } @@ -112,6 +125,11 @@ public class CommandHelp { } public void showHelp(CommandIssuer issuer, MessageKeyProvider format) { + if(selectedEntry != null){ + showDetailedHelp(selectedEntry, issuer); + return; + } + List helpEntries = getHelpEntries(); Iterator results = helpEntries.stream() .filter(HelpEntry::shouldShow) @@ -130,6 +148,14 @@ public class CommandHelp { return; } + if(search == null){ + issuer.sendMessage(MessageType.HELP, MessageKeys.HELP_HEADER, "{command}", commandName); + }else{ + issuer.sendMessage(MessageType.HELP, MessageKeys.HELP_SEARCH_HEADER, + "{command}", commandName, + "{search}", String.join(" ", search)); + } + while (results.hasNext()) { HelpEntry e = results.next(); if (i >= max) { @@ -153,6 +179,24 @@ public class CommandHelp { } } + public void showDetailedHelp(HelpEntry page, CommandIssuer issuer){ + issuer.sendMessage(MessageType.HELP, MessageKeys.HELP_DETAILED_HEADER, "{command}", page.getCommand()); + + // normal help line + String formatted = this.manager.formatMessage(issuer, MessageType.HELP, MessageKeys.HELP_FORMAT, getFormatReplacements(page)); + for (String msg : ACFPatterns.NEWLINE.split(formatted)) { + issuer.sendMessageInternal(ACFUtil.rtrim(msg)); + } + + // additionally detailed help for params + page.getParameters().forEach((cmd, help) -> { + String formattedMsg = this.manager.formatMessage(issuer, MessageType.HELP, MessageKeys.HELP_DETAILED_FORMAT, getDetailedFormatReplacements(cmd, help, page)); + for (String msg : ACFPatterns.NEWLINE.split(formattedMsg)) { + issuer.sendMessageInternal(ACFUtil.rtrim(msg)); + } + }); + } + /** * Override this to control replacements * @param e @@ -169,6 +213,15 @@ public class CommandHelp { }; } + @NotNull + public String[] getDetailedFormatReplacements(String cmd, String help, HelpEntry page) { + //{name} {description} + return new String[] { + "{name}", cmd, + "{description}", help + }; + } + public List getHelpEntries() { return helpEntries; } diff --git a/core/src/main/java/co/aikar/commands/HelpEntry.java b/core/src/main/java/co/aikar/commands/HelpEntry.java index 9bbce995..02d3ebe8 100644 --- a/core/src/main/java/co/aikar/commands/HelpEntry.java +++ b/core/src/main/java/co/aikar/commands/HelpEntry.java @@ -23,25 +23,40 @@ package co.aikar.commands; +import co.aikar.commands.annotation.Description; import co.aikar.commands.annotation.HelpSearchTags; +import java.lang.reflect.Parameter; +import java.util.LinkedHashMap; +import java.util.Map; + public class HelpEntry { private final RegisteredCommand command; private final String searchTags; private int searchScore = 1; + private Map parameters = new LinkedHashMap<>(); HelpEntry(RegisteredCommand command) { this.command = command; HelpSearchTags tagsAnno = command.method.getAnnotation(HelpSearchTags.class); this.searchTags = tagsAnno != null ? tagsAnno.value() : null; + + // search for parameter descriptions + for (Parameter parameter : command.method.getParameters()) { + Description description = parameter.getAnnotation(Description.class); + if(description != null){ + parameters.put(parameter.getName(), description.value()); + }else{ + //TODO also add parameters with not description? + } + } } RegisteredCommand getRegisteredCommand() { return this.command; } - public String getCommand(){ return "/" + this.command.command; } @@ -69,4 +84,8 @@ public class HelpEntry { public String getSearchTags() { return searchTags; } + + public Map getParameters() { + return parameters; + } } diff --git a/core/src/main/java/co/aikar/commands/MessageKeys.java b/core/src/main/java/co/aikar/commands/MessageKeys.java index fd7be9ba..1732f25f 100644 --- a/core/src/main/java/co/aikar/commands/MessageKeys.java +++ b/core/src/main/java/co/aikar/commands/MessageKeys.java @@ -45,10 +45,14 @@ public enum MessageKeys implements MessageKeyProvider { PLEASE_SPECIFY_AT_MOST, NOT_ALLOWED_ON_CONSOLE, COULD_NOT_FIND_PLAYER, - HELP_FORMAT, NO_COMMAND_MATCHED_SEARCH, HELP_PAGE_INFORMATION, - HELP_NO_RESULTS + HELP_NO_RESULTS, + HELP_HEADER, + HELP_FORMAT, + HELP_DETAILED_HEADER, + HELP_DETAILED_FORMAT, + HELP_SEARCH_HEADER, ; private final MessageKey key = MessageKey.of("acf-core." + this.name().toLowerCase()); diff --git a/languages/core/acf-core_en.properties b/languages/core/acf-core_en.properties index fb3a9a9e..a0f8e898 100644 --- a/languages/core/acf-core_en.properties +++ b/languages/core/acf-core_en.properties @@ -34,7 +34,11 @@ acf-core.must_be_max_length = Error: Must be at most {max} characters long. acf-core.please_specify_at_most = Error: Please specify a value at most {max}. acf-core.not_allowed_on_console = Error: Console may not execute this command. acf-core.could_not_find_player = Error: Could not find a player by the name: {search} -acf-core.help_format = {command} {parameters} {separator} {description} acf-core.no_command_matched_search = No command matched {search}. acf-core.help_page_information = - Showing page {page} of {totalpages} ({results} results). acf-core.help_no_results = Error: No more results. +acf-core.help_header = === Showing help for {command} === +acf-core.help_format = {command} {parameters} {separator} {description} +acf-core.help_detailed_header = === Showing detailed help for {command} === +acf-core.help_detailed_format = {name}: {description} +acf-core.help_search_header = === Showing help for {command} {search} === From a4c67f66a2bbdb413a87d380d678183a46883073 Mon Sep 17 00:00:00 2001 From: MiniDigger Date: Thu, 8 Mar 2018 22:39:31 +0100 Subject: [PATCH 2/3] make sure to only treat a type as sender if its not annotated with "other" --- .../co/aikar/commands/RegisteredCommand.java | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/core/src/main/java/co/aikar/commands/RegisteredCommand.java b/core/src/main/java/co/aikar/commands/RegisteredCommand.java index 3fcf2151..d5d2b223 100644 --- a/core/src/main/java/co/aikar/commands/RegisteredCommand.java +++ b/core/src/main/java/co/aikar/commands/RegisteredCommand.java @@ -28,6 +28,7 @@ import co.aikar.commands.annotation.CommandCompletion; import co.aikar.commands.annotation.CommandPermission; import co.aikar.commands.annotation.Default; import co.aikar.commands.annotation.Description; +import co.aikar.commands.annotation.Flags; import co.aikar.commands.annotation.Optional; import co.aikar.commands.annotation.Syntax; import co.aikar.commands.annotation.Values; @@ -105,11 +106,23 @@ public class RegisteredCommand "); + }else{ + // optional issuer aware context resolver + optionalResolvers++; + } + }else{ + // some other optional resolver + optionalResolvers++; syntaxB.append('[').append(name).append("] "); } } else { From 2f80fd4fdf204f21e53e4db61d7f1cb53986b157 Mon Sep 17 00:00:00 2001 From: MiniDigger Date: Sat, 10 Mar 2018 00:58:06 +0100 Subject: [PATCH 3/3] start with abstracting help messages out --- .../java/co/aikar/commands/CommandHelp.java | 89 ++++------- .../aikar/commands/CommandHelpFormatter.java | 138 ++++++++++++++++++ .../co/aikar/commands/CommandManager.java | 10 ++ 3 files changed, 176 insertions(+), 61 deletions(-) create mode 100644 core/src/main/java/co/aikar/commands/CommandHelpFormatter.java diff --git a/core/src/main/java/co/aikar/commands/CommandHelp.java b/core/src/main/java/co/aikar/commands/CommandHelp.java index 91f988f7..7bbab221 100644 --- a/core/src/main/java/co/aikar/commands/CommandHelp.java +++ b/core/src/main/java/co/aikar/commands/CommandHelp.java @@ -56,7 +56,7 @@ public class CommandHelp { Set seen = new HashSet<>(); subCommands.entries().forEach(e -> { String key = e.getKey(); - if (key.equals(BaseCommand.DEFAULT) || key.equals(BaseCommand.CATCHUNKNOWN)){ + if (key.equals(BaseCommand.DEFAULT) || key.equals(BaseCommand.CATCHUNKNOWN)) { return; } @@ -106,9 +106,9 @@ public class CommandHelp { return manager; } - public boolean isExactMatch(String command){ + public boolean isExactMatch(String command) { for (HelpEntry helpEntry : helpEntries) { - if(helpEntry.getCommand().endsWith(" " + command)){ + if (helpEntry.getCommand().endsWith(" " + command)) { selectedEntry = helpEntry; return true; } @@ -117,15 +117,11 @@ public class CommandHelp { } public void showHelp() { - showHelp(issuer, MessageKeys.HELP_FORMAT); + showHelp(issuer); } public void showHelp(CommandIssuer issuer) { - showHelp(issuer, MessageKeys.HELP_FORMAT); - } - - public void showHelp(CommandIssuer issuer, MessageKeyProvider format) { - if(selectedEntry != null){ + if (selectedEntry != null) { showDetailedHelp(selectedEntry, issuer); return; } @@ -140,20 +136,19 @@ public class CommandHelp { results = helpEntries.iterator(); } int totalResults = helpEntries.size(); - int min = (this.page-1) * this.perPage; // TODO: per page configurable? + int min = (this.page - 1) * this.perPage; // TODO: per page configurable? int max = min + this.perPage; + int totalPages = (int) Math.ceil((float) totalResults / (float) this.perPage); int i = 0; if (min >= totalResults) { issuer.sendMessage(MessageType.HELP, MessageKeys.HELP_NO_RESULTS); return; } - if(search == null){ - issuer.sendMessage(MessageType.HELP, MessageKeys.HELP_HEADER, "{command}", commandName); - }else{ - issuer.sendMessage(MessageType.HELP, MessageKeys.HELP_SEARCH_HEADER, - "{command}", commandName, - "{search}", String.join(" ", search)); + if (search == null) { + manager.getHelpFormatter().printHelpHeader(issuer, commandName, page, totalPages, totalResults); + } else { + manager.getHelpFormatter().printSearchHeader(issuer, commandName, page, totalPages, totalResults, search); } while (results.hasNext()) { @@ -165,61 +160,33 @@ public class CommandHelp { continue; } - String formatted = this.manager.formatMessage(issuer, MessageType.HELP, format, getFormatReplacements(e)); - for (String msg : ACFPatterns.NEWLINE.split(formatted)) { - issuer.sendMessageInternal(ACFUtil.rtrim(msg)); + if (search == null) { + manager.getHelpFormatter().printHelpLine(issuer, commandName, e); + } else { + manager.getHelpFormatter().printSearchLine(issuer, commandName, e, e.getSearchScore()); } } - if (min > 0 || results.hasNext()) { - issuer.sendMessage(MessageType.HELP, MessageKeys.HELP_PAGE_INFORMATION, - "{page}", "" + this.page, - "{totalpages}", ""+ (int)Math.ceil((float)totalResults / (float)this.perPage), - "{results}", "" + totalResults - ); + + boolean lastPage = !(min > 0 || results.hasNext()); + if (search == null) { + manager.getHelpFormatter().printHelpFooter(issuer, commandName, page, totalPages, totalResults, lastPage); + } else { + manager.getHelpFormatter().printSearchFooter(issuer, commandName, page, totalPages, totalResults, search, lastPage); } } - public void showDetailedHelp(HelpEntry page, CommandIssuer issuer){ - issuer.sendMessage(MessageType.HELP, MessageKeys.HELP_DETAILED_HEADER, "{command}", page.getCommand()); + public void showDetailedHelp(HelpEntry page, CommandIssuer issuer) { + // header + manager.getHelpFormatter().printDetailedHelpHeader(issuer, commandName, page); // normal help line - String formatted = this.manager.formatMessage(issuer, MessageType.HELP, MessageKeys.HELP_FORMAT, getFormatReplacements(page)); - for (String msg : ACFPatterns.NEWLINE.split(formatted)) { - issuer.sendMessageInternal(ACFUtil.rtrim(msg)); - } + manager.getHelpFormatter().printHelpLine(issuer, commandName, page); // additionally detailed help for params - page.getParameters().forEach((cmd, help) -> { - String formattedMsg = this.manager.formatMessage(issuer, MessageType.HELP, MessageKeys.HELP_DETAILED_FORMAT, getDetailedFormatReplacements(cmd, help, page)); - for (String msg : ACFPatterns.NEWLINE.split(formattedMsg)) { - issuer.sendMessageInternal(ACFUtil.rtrim(msg)); - } - }); - } + page.getParameters().forEach((cmd, help) -> manager.getHelpFormatter().printDetailedHelpLine(issuer, commandName, page, cmd, help)); - /** - * Override this to control replacements - * @param e - * @return - */ - @NotNull - public String[] getFormatReplacements(HelpEntry e) { - //{command} {parameters} {separator} {description} - return new String[] { - "{command}", e.getCommand(), - "{parameters}", e.getParameterSyntax(), - "{separator}", e.getDescription().isEmpty() ? "" : "-", - "{description}", e.getDescription() - }; - } - - @NotNull - public String[] getDetailedFormatReplacements(String cmd, String help, HelpEntry page) { - //{name} {description} - return new String[] { - "{name}", cmd, - "{description}", help - }; + // footer + manager.getHelpFormatter().printDetailedHelpFooter(issuer, commandName, page); } public List getHelpEntries() { diff --git a/core/src/main/java/co/aikar/commands/CommandHelpFormatter.java b/core/src/main/java/co/aikar/commands/CommandHelpFormatter.java new file mode 100644 index 00000000..1de111c7 --- /dev/null +++ b/core/src/main/java/co/aikar/commands/CommandHelpFormatter.java @@ -0,0 +1,138 @@ +/* + * Copyright (c) 2016-2018 Daniel Ennis (Aikar) - MIT License + * + * 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 co.aikar.commands; + +import org.jetbrains.annotations.NotNull; + +import java.util.List; + +public class CommandHelpFormatter { + + private final CommandManager manager; + + public CommandHelpFormatter(CommandManager manager) { + this.manager = manager; + } + + // ######## + // # help # + // ######## + + public void printHelpHeader(CommandIssuer issuer, String commandName, int page, int totalPages, int totalResults) { + issuer.sendMessage(MessageType.HELP, MessageKeys.HELP_HEADER, "{command}", commandName); + } + + public void printHelpLine(CommandIssuer issuer, String commandName, HelpEntry page) { + String formatted = this.manager.formatMessage(issuer, MessageType.HELP, MessageKeys.HELP_FORMAT, getFormatReplacements(page)); + for (String msg : ACFPatterns.NEWLINE.split(formatted)) { + issuer.sendMessageInternal(ACFUtil.rtrim(msg)); + } + } + + public void printHelpFooter(CommandIssuer issuer, String commandName, int page, int totalPages, int totalResults, boolean lastPage) { + if(lastPage)return; + issuer.sendMessage(MessageType.HELP, MessageKeys.HELP_PAGE_INFORMATION, + "{page}", "" + page, + "{totalpages}", ""+ totalPages, + "{results}", "" + totalResults + ); + } + + // ########## + // # search # + // ########## + + public void printSearchHeader(CommandIssuer issuer, String commandName, int page, int totalPages, int totalResults, List search) { + issuer.sendMessage(MessageType.HELP, MessageKeys.HELP_SEARCH_HEADER, + "{command}", commandName, + "{search}", String.join(" ", search)); + } + + public void printSearchLine(CommandIssuer issuer, String commandName, HelpEntry page, int score) { + String formatted = this.manager.formatMessage(issuer, MessageType.HELP, MessageKeys.HELP_FORMAT, getFormatReplacements(page)); + for (String msg : ACFPatterns.NEWLINE.split(formatted)) { + issuer.sendMessageInternal(ACFUtil.rtrim(msg)); + } + } + + public void printSearchFooter(CommandIssuer issuer, String commandName, int page, int totalPages, int totalResults, List search, boolean lastPage) { + if(lastPage)return; + issuer.sendMessage(MessageType.HELP, MessageKeys.HELP_PAGE_INFORMATION, + "{page}", "" + page, + "{totalpages}", ""+ totalPages, + "{results}", "" + totalResults + ); + } + + // ############ + // # detailed # + // ############ + + public void printDetailedHelpHeader(CommandIssuer issuer, String commandName, HelpEntry page) { + issuer.sendMessage(MessageType.HELP, MessageKeys.HELP_DETAILED_HEADER, "{command}", page.getCommand()); + } + + public void printDetailedHelpLine(CommandIssuer issuer, String commandName, HelpEntry page, String subCommand, String paramDescription) { + String formattedMsg = this.manager.formatMessage(issuer, MessageType.HELP, MessageKeys.HELP_DETAILED_FORMAT, getDetailedFormatReplacements(subCommand, paramDescription, page)); + for (String msg : ACFPatterns.NEWLINE.split(formattedMsg)) { + issuer.sendMessageInternal(ACFUtil.rtrim(msg)); + } + } + + public void printDetailedHelpFooter(CommandIssuer issuer, String commandName, HelpEntry page) { + // default doesn't have a footer + } + + /** + * Override this to control replacements + * @param e + * @return + */ + @NotNull + public String[] getFormatReplacements(HelpEntry e) { + //{command} {parameters} {separator} {description} + return new String[] { + "{command}", e.getCommand(), + "{parameters}", e.getParameterSyntax(), + "{separator}", e.getDescription().isEmpty() ? "" : "-", + "{description}", e.getDescription() + }; + } + + /** + * Override this to control replacements + * @param cmd + * @param help + * @param page + * @return + */ + @NotNull + public String[] getDetailedFormatReplacements(String cmd, String help, HelpEntry page) { + //{name} {description} + return new String[] { + "{name}", cmd, + "{description}", help + }; + } +} diff --git a/core/src/main/java/co/aikar/commands/CommandManager.java b/core/src/main/java/co/aikar/commands/CommandManager.java index 1f2b0e85..513ca694 100644 --- a/core/src/main/java/co/aikar/commands/CommandManager.java +++ b/core/src/main/java/co/aikar/commands/CommandManager.java @@ -71,6 +71,7 @@ public abstract class CommandManager < protected final CommandConditions conditions = new CommandConditions<>(this); protected ExceptionHandler defaultExceptionHandler = null; protected Table, String, Object> dependencies = HashBasedTable.create(); + protected CommandHelpFormatter helpFormatter = new CommandHelpFormatter(this); protected boolean usePerIssuerLocale = false; protected List> localeChangedCallbacks = Lists.newArrayList(); @@ -185,6 +186,15 @@ public abstract class CommandManager < verifyUnstableAPI("help"); this.defaultHelpPerPage = defaultHelpPerPage; } + /** @deprecated Unstable API */ @Deprecated @UnstableAPI + public void setHelpFormatter(CommandHelpFormatter helpFormatter) { + this.helpFormatter = helpFormatter; + } + + /** @deprecated Unstable API */ @Deprecated @UnstableAPI + public CommandHelpFormatter getHelpFormatter() { + return helpFormatter; + } /** * Registers a command with ACF