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 @@
+
+
+
+
+