diff --git a/README-CHANGES.xml b/README-CHANGES.xml index b5681a2..4ce445d 100644 --- a/README-CHANGES.xml +++ b/README-CHANGES.xml @@ -4,18 +4,23 @@ - + - + + + + + + diff --git a/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/CLPApplicationConfigurationType.java b/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/CLPApplicationConfigurationType.java index 7858993..88084e3 100644 --- a/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/CLPApplicationConfigurationType.java +++ b/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/CLPApplicationConfigurationType.java @@ -20,7 +20,9 @@ import org.immutables.value.Value; import org.slf4j.Logger; +import java.net.URI; import java.util.List; +import java.util.Optional; /** * The application configuration. @@ -42,6 +44,12 @@ public interface CLPApplicationConfigurationType String programName(); + /** + * @return The URI of any documentation for the application + */ + + Optional documentationURI(); + /** * @return The list of commands */ diff --git a/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/Claypot.java b/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/Claypot.java index f1c315f..c7c81cd 100644 --- a/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/Claypot.java +++ b/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/Claypot.java @@ -126,7 +126,11 @@ public void execute( final String cmd = this.commander.getParsedCommand(); if (cmd == null) { - CLPBriefUsageFormatter.showBriefUsage(logger, this.commander); + CLPBriefUsageFormatter.showBriefUsage( + logger, + this.configuration, + this.commander + ); this.exitCode = 1; return; } diff --git a/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/internal/CLPBriefUsageFormatter.java b/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/internal/CLPBriefUsageFormatter.java index 0ebde2c..78ef8c9 100644 --- a/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/internal/CLPBriefUsageFormatter.java +++ b/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/internal/CLPBriefUsageFormatter.java @@ -20,6 +20,7 @@ import com.beust.jcommander.JCommander; import com.beust.jcommander.JCommander.ProgramName; import com.beust.jcommander.Parameters; +import com.io7m.claypot.core.CLPApplicationConfiguration; import com.io7m.claypot.core.CLPStrings; import com.io7m.claypot.core.CLPStringsType; import org.slf4j.Logger; @@ -30,14 +31,18 @@ public final class CLPBriefUsageFormatter extends DefaultUsageFormatter { + private final CLPApplicationConfiguration configuration; private final JCommander commander; private final CLPStringsType strings; public CLPBriefUsageFormatter( + final CLPApplicationConfiguration inConfiguration, final JCommander inCommander) { super(inCommander); + this.configuration = + Objects.requireNonNull(inConfiguration, "configuration"); this.commander = Objects.requireNonNull(inCommander, "commander"); this.strings = @@ -46,13 +51,15 @@ public CLPBriefUsageFormatter( public static void showBriefUsage( final Logger logger, + final CLPApplicationConfiguration inConfiguration, final JCommander commander) { Objects.requireNonNull(logger, "logger"); Objects.requireNonNull(commander, "commander"); final var console = new CLPStringBuilderConsole(); - commander.setUsageFormatter(new CLPBriefUsageFormatter(commander)); + commander.setUsageFormatter( + new CLPBriefUsageFormatter(inConfiguration, commander)); commander.setConsole(console); commander.usage(); logger.info("{}", console.builder().toString()); @@ -76,7 +83,7 @@ private static String indentLine( if (text.trim().isEmpty()) { return ""; } - return " " + text; + return String.format(" %s", text); } @Override @@ -86,6 +93,9 @@ public void appendCommands( final int descriptionIndent, final String indent) { + out.append('\n'); + this.showBasicHelp(out); + out.append('\n'); out.append(indent); out.append(" "); @@ -123,7 +133,22 @@ public void appendCommands( } out.append('\n'); + this.showDocumentation(out); + } + private void showDocumentation( + final StringBuilder out) + { + this.configuration.documentationURI().ifPresent(uri -> { + out.append(" "); + out.append(this.strings.format("com.io7m.claypot.documentation", uri)); + out.append('\n'); + }); + } + + private void showBasicHelp( + final StringBuilder out) + { final var programName = this.commander.getProgramName(); this.strings.format("com.io7m.claypot.help", programName) .trim() @@ -132,8 +157,6 @@ public void appendCommands( out.append(indentLine(line)); out.append('\n'); }); - - out.append('\n'); } @Override diff --git a/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/internal/CLPCommandHelp.java b/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/internal/CLPCommandHelp.java index f6fe844..cbe6a62 100644 --- a/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/internal/CLPCommandHelp.java +++ b/com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/internal/CLPCommandHelp.java @@ -79,7 +79,7 @@ protected Status executeActual() final var subCommander = commands.get(commandName); if (subCommander == null) { logger.error("Unknown command: {}", commandName); - showBriefUsage(logger, this.commander()); + showBriefUsage(logger, this.context().configuration(), this.commander()); return FAILURE; } diff --git a/com.io7m.claypot.core/src/main/resources/com/io7m/claypot/core/Claypot.xml b/com.io7m.claypot.core/src/main/resources/com/io7m/claypot/core/Claypot.xml index 6e77e38..855248c 100644 --- a/com.io7m.claypot.core/src/main/resources/com/io7m/claypot/core/Claypot.xml +++ b/com.io7m.claypot.core/src/main/resources/com/io7m/claypot/core/Claypot.xml @@ -8,6 +8,7 @@ Unrecognized log level: {0} Stacktrace of {0}: {1} Caused by: + > file.txt $ cex @file.txt ]]> + - \ No newline at end of file + + Documentation: {0} + diff --git a/com.io7m.claypot.example/src/main/java/com/io7m/claypot/example/CEXBlue.java b/com.io7m.claypot.example/src/main/java/com/io7m/claypot/example/CEXBlue.java new file mode 100644 index 0000000..462d38d --- /dev/null +++ b/com.io7m.claypot.example/src/main/java/com/io7m/claypot/example/CEXBlue.java @@ -0,0 +1,52 @@ +/* + * Copyright © 2020 Mark Raynsford http://io7m.com + * + * Permission to use, copy, modify, and/or distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY + * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR + * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +package com.io7m.claypot.example; + +import com.beust.jcommander.Parameters; +import com.io7m.claypot.core.CLPAbstractCommand; +import com.io7m.claypot.core.CLPCommandContextType; +import com.io7m.claypot.core.CLPStringsType; + +@Parameters(commandDescription = "Paint things blue.") +public final class CEXBlue extends CLPAbstractCommand +{ + private final CLPStringsType strings; + + public CEXBlue(final CLPCommandContextType inContext) + { + super(inContext); + this.strings = CEXStrings.create(); + } + + @Override + protected Status executeActual() + { + return Status.SUCCESS; + } + + @Override + public String extendedHelp() + { + return this.strings.format("blueExtendedHelp"); + } + + @Override + public String name() + { + return "blue"; + } +} diff --git a/com.io7m.claypot.example/src/main/java/com/io7m/claypot/example/CEXGreen.java b/com.io7m.claypot.example/src/main/java/com/io7m/claypot/example/CEXGreen.java new file mode 100644 index 0000000..457a2a6 --- /dev/null +++ b/com.io7m.claypot.example/src/main/java/com/io7m/claypot/example/CEXGreen.java @@ -0,0 +1,52 @@ +/* + * Copyright © 2020 Mark Raynsford http://io7m.com + * + * Permission to use, copy, modify, and/or distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY + * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR + * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +package com.io7m.claypot.example; + +import com.beust.jcommander.Parameters; +import com.io7m.claypot.core.CLPAbstractCommand; +import com.io7m.claypot.core.CLPCommandContextType; +import com.io7m.claypot.core.CLPStringsType; + +@Parameters(commandDescription = "Paint things green.") +public final class CEXGreen extends CLPAbstractCommand +{ + private final CLPStringsType strings; + + public CEXGreen(final CLPCommandContextType inContext) + { + super(inContext); + this.strings = CEXStrings.create(); + } + + @Override + protected Status executeActual() + { + return Status.SUCCESS; + } + + @Override + public String extendedHelp() + { + return this.strings.format("greenExtendedHelp"); + } + + @Override + public String name() + { + return "green"; + } +} diff --git a/com.io7m.claypot.example/src/main/java/com/io7m/claypot/example/CEXOthersMain.java b/com.io7m.claypot.example/src/main/java/com/io7m/claypot/example/CEXOthersMain.java index dcc48dd..32a227b 100644 --- a/com.io7m.claypot.example/src/main/java/com/io7m/claypot/example/CEXOthersMain.java +++ b/com.io7m.claypot.example/src/main/java/com/io7m/claypot/example/CEXOthersMain.java @@ -21,6 +21,8 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; +import java.net.URI; + public final class CEXOthersMain { private static final Logger LOG = @@ -37,8 +39,11 @@ public static void main( final var applicationConfiguration = CLPApplicationConfiguration.builder() .setProgramName("cex") + .addCommands(CEXBlue::new) + .addCommands(CEXGreen::new) .addCommands(CEXRed::new) .setLogger(LOG) + .setDocumentationURI(URI.create("https://www.example.com/")) .build(); final var claypot = Claypot.create(applicationConfiguration); diff --git a/com.io7m.claypot.example/src/main/resources/com/io7m/claypot/example/Example.xml b/com.io7m.claypot.example/src/main/resources/com/io7m/claypot/example/Example.xml index 290e262..6e316d7 100644 --- a/com.io7m.claypot.example/src/main/resources/com/io7m/claypot/example/Example.xml +++ b/com.io7m.claypot.example/src/main/resources/com/io7m/claypot/example/Example.xml @@ -13,5 +13,28 @@ Has found out thy bed Of crimson joy: And his dark secret love Does thy life destroy. +]]> + + + + \ No newline at end of file diff --git a/com.io7m.claypot.tests/src/test/java/com/io7m/claypot/tests/CLPLogLevelConverterTest.java b/com.io7m.claypot.tests/src/test/java/com/io7m/claypot/tests/CLPLogLevelConverterTest.java index c608a94..f408e00 100644 --- a/com.io7m.claypot.tests/src/test/java/com/io7m/claypot/tests/CLPLogLevelConverterTest.java +++ b/com.io7m.claypot.tests/src/test/java/com/io7m/claypot/tests/CLPLogLevelConverterTest.java @@ -18,11 +18,9 @@ import ch.qos.logback.classic.Level; import com.io7m.claypot.core.internal.CLPLogLevelConverter; -import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.*; -import static org.junit.jupiter.api.Assertions.assertEquals; public final class CLPLogLevelConverterTest { diff --git a/spotbugs-filter.xml b/spotbugs-filter.xml index 23104ec..2795d8d 100644 --- a/spotbugs-filter.xml +++ b/spotbugs-filter.xml @@ -43,6 +43,11 @@ + + + + +