Update to Piston 0.5.2 + Doctools/Deprecation improvements (#523)

* Update to Piston 0.5.2

* [Doctools] Fix output, be verbose about deprecations

* Improve deprecation system, doctools output

worldedit-core/doctools/src/main/kotlin/com/sk89q/worldedit/internal/util/DocumentationPrinter.kt

@@ -24,7 +24,6 @@ import com.sk89q.worldedit.WorldEdit
 import com.sk89q.worldedit.command.BiomeCommands
 import com.sk89q.worldedit.command.ChunkCommands
 import com.sk89q.worldedit.command.ClipboardCommands
-import com.sk89q.worldedit.command.ExpandCommands
 import com.sk89q.worldedit.command.GeneralCommands
 import com.sk89q.worldedit.command.GenerationCommands
 import com.sk89q.worldedit.command.HistoryCommands
@@ -37,11 +36,10 @@ import com.sk89q.worldedit.command.ToolCommands
 import com.sk89q.worldedit.command.ToolUtilCommands
 import com.sk89q.worldedit.command.UtilityCommands
 import com.sk89q.worldedit.command.util.PermissionCondition
+import com.sk89q.worldedit.internal.command.CommandUtil
 import com.sk89q.worldedit.util.formatting.text.TextComponent
-import com.sk89q.worldedit.util.formatting.text.TranslatableComponent
-import com.sk89q.worldedit.util.formatting.text.serializer.plain.PlainComponentSerializer
 import org.enginehub.piston.Command
-import org.enginehub.piston.TextConfig
+import org.enginehub.piston.config.TextConfig
 import org.enginehub.piston.part.SubCommandPart
 import org.enginehub.piston.util.HelpGenerator
 import java.nio.file.Files
@@ -52,7 +50,6 @@ import kotlin.streams.toList
 class DocumentationPrinter private constructor() {
 
     private val nameRegex = Regex("name = \"(.+?)\"")
-    private val serializer = PlainComponentSerializer({ "" }, TranslatableComponent::key)
     private val commands = WorldEdit.getInstance().platformManager.platformCommandManager.commandManager.allCommands
             .map { it.name to it }.toList().toMap()
     private val cmdOutput = StringBuilder()
@@ -111,6 +108,7 @@ class DocumentationPrinter private constructor() {
         }
 
         dumpSection("Tool Commands") {
+            yield("tool")
             yieldAllCommandsIn<ToolCommands>()
             yieldAllCommandsIn<ToolUtilCommands>()
         }
@@ -216,7 +214,7 @@ Other Permissions
     private fun dumpSection(title: String, addCommandNames: suspend SequenceScope<String>.() -> Unit) {
         cmdOutput.append("\n").append(title).append("\n").append(Strings.repeat("~", title.length)).append("\n")
 
-        val prefix = TextConfig.getCommandPrefix()
+        val prefix = reduceToRst(TextConfig.commandPrefixValue())
         val commands = sequence(addCommandNames).map { this.commands.getValue(it) }.toList()
         matchedCommands.addAll(commands.map { it.name })
 
@@ -269,14 +267,19 @@ Other Permissions
         }
         cmdOutput.appendln()
         cmdOutput.appendln("    :class: command-topic").appendln()
+        CommandUtil.deprecationWarning(command).ifPresent { warning ->
+            cmdOutput.appendln("""
+                |    .. WARNING::
+                |        ${reduceToRst(warning).makeRstSafe("\n\n")}
+            """.trimMargin())
+        }
         cmdOutput.appendln("""
             |    .. csv-table::
             |        :widths: 8, 15
         """.trimMargin())
         cmdOutput.appendln()
         for ((k, v) in entries) {
-            val rstSafe = v.trim().replace("\"", "\\\"").replace("\n", "\n" + "    ".repeat(2))
-                .lineSequence().map { line -> line.ifBlank { "" } }.joinToString(separator = "\n")
+            val rstSafe = v.makeRstSafe("\n")
             cmdOutput.append("    ".repeat(2))
                     .append(k)
                     .append(",")
@@ -287,32 +290,39 @@ Other Permissions
         cmdOutput.appendln()
     }
 
+    private fun String.makeRstSafe(lineJoiner: String) = trim()
+        .replace("\"", "\\\"").replace("\n", "\n" + "    ".repeat(2))
+        .lineSequence()
+        .map { line -> line.ifBlank { "" } }
+        .joinToString(separator = lineJoiner)
+
     private fun linkSafe(text: String) = text.replace(" ", "-")
 
     private fun commandTableEntries(command: Command, parents: Stream<Command>): Map<String, String> {
         return sequence {
             val desc = command.description.run {
+                val footer = CommandUtil.footerWithoutDeprecation(command)
                 when {
-                    command.footer.isPresent -> append(
-                            TextComponent.builder("\n\n").append(command.footer.get())
+                    footer.isPresent -> append(
+                            TextComponent.builder("\n\n").append(footer.get())
                     )
                     else -> this
                 }
             }
-            yield("**Description**" to serializer.serialize(desc))
+            yield("**Description**" to reduceToRst(desc))
             val cond = command.condition
             if (cond is PermissionCondition && cond.permissions.isNotEmpty()) {
                 val perms = cond.permissions.joinToString(", ") { "``$it``" }
                 yield("**Permissions**" to perms)
             }
-            val usage = serializer.serialize(HelpGenerator.create(Stream.concat(parents, Stream.of(command)).toList()).usage)
+            val usage = reduceToRst(HelpGenerator.create(Stream.concat(parents, Stream.of(command)).toList()).usage)
             yield("**Usage**" to "``$usage``")
 
             // Part descriptions
             command.parts.filterNot { it is SubCommandPart }
                     .forEach {
-                        val title = "\u2001\u2001``" + serializer.serialize(it.textRepresentation) + "``"
-                        yield(title to serializer.serialize(it.description))
+                        val title = "\u2001\u2001``" + reduceToRst(it.textRepresentation) + "``"
+                        yield(title to reduceToRst(it.description))
                     }
         }.toMap()
     }
@@ -324,13 +334,15 @@ Other Permissions
          */
         @JvmStatic
         fun main(args: Array<String>) {
-            val printer = DocumentationPrinter()
+            try {
+                val printer = DocumentationPrinter()
 
-            printer.writeAllCommands()
-            writeOutput("commands.rst", printer.cmdOutput.toString())
-            writeOutput("permissions.rst", printer.permsOutput.toString())
-
-            WorldEdit.getInstance().sessionManager.unload()
+                printer.writeAllCommands()
+                writeOutput("commands.rst", printer.cmdOutput.toString())
+                writeOutput("permissions.rst", printer.permsOutput.toString())
+            } finally {
+                WorldEdit.getInstance().sessionManager.unload()
+            }
         }
 
         private fun writeOutput(file: String, output: String) {

worldedit-core/doctools/src/main/kotlin/com/sk89q/worldedit/internal/util/RstWorldEditText.kt

@@ -0,0 +1,69 @@
+package com.sk89q.worldedit.internal.util
+
+import com.sk89q.worldedit.util.formatting.WorldEditText
+import com.sk89q.worldedit.util.formatting.text.Component
+import com.sk89q.worldedit.util.formatting.text.TextComponent
+import com.sk89q.worldedit.util.formatting.text.TranslatableComponent
+import com.sk89q.worldedit.util.formatting.text.event.ClickEvent
+import com.sk89q.worldedit.util.formatting.text.format.TextDecoration
+import org.enginehub.piston.util.TextHelper
+
+fun reduceToRst(component: Component): String {
+    val formatted = WorldEditText.format(component)
+    return formatAsRst(formatted).toString()
+}
+
+private fun formatAsRst(component: Component, currentDeco: String? = null): CharSequence {
+    return when (component) {
+        is TextComponent -> {
+            val content = StringBuilder(component.content())
+
+            val deco = when {
+                // Actions that suggest themselves as commands are marked as code
+                component.isSuggestingAsCommand(content.toString()) -> "``"
+                component.decorations().any { it == TextDecoration.BOLD } -> "**"
+                component.decorations().any { it == TextDecoration.ITALIC } -> "*"
+                else -> null
+            }
+
+            component.children().joinTo(content, separator = "") {
+                formatAsRst(it, deco ?: currentDeco)
+            }
+
+            deco?.let {
+                require(currentDeco == null) {
+                    "Nested decorations are hell in RST. \n" +
+                        "Existing: $currentDeco; New: $deco\n" +
+                        "Offender: ${TextHelper.reduceToText(component)}"
+                }
+                content.rstDeco(deco)
+            }
+
+            content
+        }
+        is TranslatableComponent -> {
+            val content = StringBuilder(component.key())
+            component.children().joinTo(content, separator = "") { formatAsRst(it, currentDeco) }
+            content
+        }
+        else -> component.children().joinToString(separator = "") { formatAsRst(it, currentDeco) }
+    }
+}
+
+private fun Component.isSuggestingAsCommand(text: String): Boolean {
+    val ce = clickEvent()
+    return when (ce?.action()) {
+        ClickEvent.Action.RUN_COMMAND,
+        ClickEvent.Action.SUGGEST_COMMAND ->
+            ce.value() == text
+        else -> false
+    }
+}
+
+private fun StringBuilder.rstDeco(deco: String): StringBuilder = apply {
+    ensureCapacity(length + deco.length * 2)
+    val insertionPoint = indexOfFirst { !it.isWhitespace() }.coerceAtLeast(0)
+    insert(insertionPoint, deco)
+    val insertionPointEnd = (indexOfLast { !it.isWhitespace() } + 1).takeUnless { it < 1 } ?: length
+    insert(insertionPointEnd, deco)
+}

worldedit-core/src/main/java/com/sk89q/worldedit/command/ToolCommands.java

@@ -88,7 +88,7 @@ public class ToolCommands {
                 ).build();
             }
             commandManager.register(CommandUtil.deprecate(
-                command, "Using global tool names is deprecated " +
+                command, "Global tool names cause conflicts " +
                 "and will be removed in WorldEdit 8", ToolCommands::asNonGlobal
             ));
         }

worldedit-core/src/main/java/com/sk89q/worldedit/extension/platform/PlatformCommandManager.java

@@ -106,7 +106,8 @@ import com.sk89q.worldedit.util.logging.LogFormat;
 import com.sk89q.worldedit.world.World;
 import org.enginehub.piston.Command;
 import org.enginehub.piston.CommandManager;
-import org.enginehub.piston.TextConfig;
+import org.enginehub.piston.config.ConfigHolder;
+import org.enginehub.piston.config.TextConfig;
 import org.enginehub.piston.converter.ArgumentConverters;
 import org.enginehub.piston.exception.CommandException;
 import org.enginehub.piston.exception.CommandExecutionException;
@@ -152,10 +153,6 @@ public final class PlatformCommandManager {
     private static final java.util.logging.Logger COMMAND_LOG =
         java.util.logging.Logger.getLogger("com.sk89q.worldedit.CommandLog");
 
-    static {
-        TextConfig.setCommandPrefix("/");
-    }
-
     private final WorldEdit worldEdit;
     private final PlatformManager platformManager;
     private final CommandManagerServiceImpl commandManagerService;

worldedit-core/src/main/java/com/sk89q/worldedit/internal/command/CommandUtil.java

@@ -42,6 +42,7 @@ import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 import java.util.function.Function;
+import java.util.function.Predicate;
 import java.util.stream.Collectors;
 
 import static com.google.common.base.Preconditions.checkState;
@@ -49,11 +50,16 @@ import static java.util.stream.Collectors.toList;
 
 public class CommandUtil {
 
-    private static Component makeDeprecatedFooter(Component newCommand) {
-        return TextComponent.builder("This command is deprecated. Use ", TextColor.GOLD)
-            .decoration(TextDecoration.ITALIC, true)
+    private static final Component DEPRECATION_MARKER = TextComponent.of("This command is deprecated.");
+
+    private static Component makeDeprecatedFooter(String reason, Component newCommand) {
+        return TextComponent.builder()
+            .append(DEPRECATION_MARKER)
+            .append(" " + reason + ".")
+            .append(TextComponent.newline())
+            .append(TextComponent.of("Use ", TextColor.GOLD, TextDecoration.ITALIC))
             .append(newCommand)
-            .append(" instead.")
+            .append(TextComponent.of(" instead.", TextColor.GOLD, TextDecoration.ITALIC))
             .build();
     }
 
@@ -66,6 +72,7 @@ public class CommandUtil {
     public static Command deprecate(Command command, String reason,
                                     NewCommandGenerator newCommandGenerator) {
         Component deprecatedWarning = makeDeprecatedFooter(
+            reason,
             newCommandSuggestion(newCommandGenerator,
                 NoInputCommandParameters.builder().build(),
                 command)
@@ -80,6 +87,54 @@ public class CommandUtil {
             .build();
     }
 
+    public static Optional<Component> footerWithoutDeprecation(Command command) {
+        return command.getFooter()
+            .filter(footer -> anyComponent(footer, Predicate.isEqual(DEPRECATION_MARKER)))
+            .map(footer -> Optional.of(
+                replaceDeprecation(footer)
+            ))
+            .orElseGet(command::getFooter);
+    }
+
+    public static Optional<Component> deprecationWarning(Command command) {
+        return command.getFooter()
+            .map(CommandUtil::extractDeprecation)
+            .orElseGet(command::getFooter);
+    }
+
+    public static boolean isDeprecated(Command command) {
+        return command.getFooter()
+            .filter(footer -> anyComponent(footer, Predicate.isEqual(DEPRECATION_MARKER)))
+            .isPresent();
+    }
+
+    private static boolean anyComponent(Component component, Predicate<Component> test) {
+        return test.test(component) || component.children().stream()
+            .anyMatch(x -> anyComponent(x, test));
+    }
+
+    private static Component replaceDeprecation(Component component) {
+        if (component.children().stream().anyMatch(Predicate.isEqual(DEPRECATION_MARKER))) {
+            return TextComponent.empty();
+        }
+        return component.children(
+            component.children().stream()
+                .map(CommandUtil::replaceDeprecation)
+                .collect(toList())
+        );
+    }
+
+    private static Optional<Component> extractDeprecation(Component component) {
+        if (component.children().stream().anyMatch(Predicate.isEqual(DEPRECATION_MARKER))) {
+            return Optional.of(component);
+        }
+        return component.children().stream()
+            .map(CommandUtil::extractDeprecation)
+            .filter(Optional::isPresent)
+            .map(Optional::get)
+            .findAny();
+    }
+
     private static int deprecatedCommandWarning(
         CommandParameters parameters,
         Command command,

worldedit-core/src/main/java/com/sk89q/worldedit/util/formatting/WorldEditText.java

@@ -0,0 +1,45 @@
+/*
+ * WorldEdit, a Minecraft world manipulation toolkit
+ * Copyright (C) sk89q <http://www.sk89q.com>
+ * Copyright (C) WorldEdit team and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as published by the
+ * Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package com.sk89q.worldedit.util.formatting;
+
+import com.sk89q.worldedit.util.formatting.text.Component;
+import org.enginehub.piston.config.ConfigHolder;
+import org.enginehub.piston.config.TextConfig;
+import org.enginehub.piston.util.TextHelper;
+
+public class WorldEditText {
+    public static final ConfigHolder CONFIG_HOLDER = ConfigHolder.create();
+
+    static {
+        CONFIG_HOLDER.getConfig(TextConfig.commandPrefix()).setValue("/");
+    }
+
+    public static Component format(Component component) {
+        return CONFIG_HOLDER.replace(component);
+    }
+
+    public static String reduceToText(Component component) {
+        return TextHelper.reduceToText(format(component));
+    }
+
+    private WorldEditText() {
+    }
+
+}

worldedit-core/src/main/java/com/sk89q/worldedit/util/formatting/component/CommandUsageBox.java

@@ -24,9 +24,9 @@ import com.sk89q.worldedit.util.formatting.text.TextComponent;
 import com.sk89q.worldedit.util.formatting.text.event.ClickEvent;
 import com.sk89q.worldedit.util.formatting.text.event.HoverEvent;
 import com.sk89q.worldedit.util.formatting.text.format.TextDecoration;
-import org.enginehub.piston.ColorConfig;
 import org.enginehub.piston.Command;
 import org.enginehub.piston.CommandParameters;
+import org.enginehub.piston.config.ColorConfig;
 import org.enginehub.piston.util.HelpGenerator;
 
 import javax.annotation.Nullable;
@@ -72,15 +72,13 @@ public class CommandUsageBox extends TextComponentProducer {
             .append(HelpGenerator.create(commands).getFullHelp());
         if (getSubCommands(Iterables.getLast(commands)).size() > 0) {
             boxContent.append(TextComponent.newline())
-                .append(TextComponent.builder("> ")
-                    .color(ColorConfig.getHelpText())
-                    .append(TextComponent.builder("List Subcommands")
-                        .color(ColorConfig.getMainText())
+                .append(ColorConfig.helpText().wrap(TextComponent.builder("> ")
+                    .append(ColorConfig.mainText().wrap(TextComponent.builder("List Subcommands")
                         .decoration(TextDecoration.ITALIC, true)
                         .clickEvent(ClickEvent.runCommand(helpRootCommand + " -s " + commandString))
                         .hoverEvent(HoverEvent.showText(TextComponent.of("List all subcommands of this command")))
-                        .build())
-                    .build());
+                        .build()))
+                    .build()));
         }
         MessageBox box = new MessageBox("Help for " + commandString,
             boxContent);