Add documentation URIs

This adds the ability for applications to publish documentation URIs.

Fix: #2

README-CHANGES.xml

@@ -4,18 +4,23 @@
     <c:release date="2020-06-26T00:00:00+00:00" ticket-system="com.github.io7m.claypot" version="0.0.1">
       <c:changes/>
     </c:release>
-    <c:release date="2020-06-27T19:40:45+00:00" ticket-system="com.github.io7m.claypot" version="0.0.2">
+    <c:release date="2020-06-27T20:07:38+00:00" ticket-system="com.github.io7m.claypot" version="0.0.2">
       <c:changes>
         <c:change date="2020-06-27T00:00:00+00:00" summary="Add extended help methods.">
           <c:tickets>
             <c:ticket id="1"/>
           </c:tickets>
         </c:change>
-        <c:change date="2020-06-27T19:40:45+00:00" summary="Document @ syntax.">
+        <c:change date="2020-06-27T00:00:00+00:00" summary="Document @ syntax.">
           <c:tickets>
             <c:ticket id="3"/>
           </c:tickets>
         </c:change>
+        <c:change date="2020-06-27T20:07:38+00:00" summary="Allow applications to publish documentation URIs.">
+          <c:tickets>
+            <c:ticket id="2"/>
+          </c:tickets>
+        </c:change>
       </c:changes>
     </c:release>
   </c:releases>

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<URI> documentationURI();
+
   /**
    * @return The list of commands
    */

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;
       }

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

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;
     }
 

com.io7m.claypot.core/src/main/resources/com/io7m/claypot/core/Claypot.xml

@@ -8,6 +8,7 @@
   <entry key="com.io7m.claypot.logLevelUnrecognized">Unrecognized log level: {0}</entry>
   <entry key="com.io7m.claypot.stackTraceOf">Stacktrace of {0}: {1}</entry>
   <entry key="com.io7m.claypot.causedBy">Caused by:&#x20;</entry>
+
   <entry key="com.io7m.claypot.help"><![CDATA[
 Use the "help" command to examine specific commands:
 
@@ -20,6 +21,7 @@ can be referenced using the @ symbol:
   $ echo help >> file.txt
   $ cex @file.txt
 ]]></entry>
+
   <entry key="com.io7m.claypot.helpExtended"><![CDATA[
 The "help" command, executed without arguments, shows the names of all
 commands including the names and types of all of their parameters.
@@ -30,4 +32,6 @@ right now.
 
 Example: {0} help help
 ]]></entry>
-</properties>
+
+  <entry key="com.io7m.claypot.documentation">Documentation: {0}</entry>
+</properties>

com.io7m.claypot.example/src/main/java/com/io7m/claypot/example/CEXBlue.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright © 2020 Mark Raynsford <code@io7m.com> 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";
+  }
+}

com.io7m.claypot.example/src/main/java/com/io7m/claypot/example/CEXGreen.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright © 2020 Mark Raynsford <code@io7m.com> 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";
+  }
+}

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);

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.
+]]></entry>
+
+  <entry key="greenExtendedHelp"><![CDATA[
+How vainly men themselves amaze
+To win the palm, the oak, or bays,
+And their uncessant labours see
+Crown’d from some single herb or tree,
+Whose short and narrow verged shade
+Does prudently their toils upbraid;
+While all flow’rs and all trees do close
+To weave the garlands of repose.
+]]></entry>
+
+  <entry key="blueExtendedHelp"><![CDATA[
+Why make so much of fragmentary blue
+In here and there a bird, or butterfly,
+Or flower, or wearing-stone, or open eye,
+When heaven presents in sheets the solid hue?
+
+Since earth is earth, perhaps, not heaven (as yet)-
+Though some savants make earth include the sky;
+And blue so far above us comes so high,
+It only gives our wish for blue a whet.
 ]]></entry>
 </properties>

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
 {

spotbugs-filter.xml

@@ -43,6 +43,11 @@
     <Class name="~com\.io7m\.claypot\.example\..+"/>
   </Match>
 
+  <Match>
+    <Class name="com.io7m.claypot.core.internal.CLPBriefUsageFormatter"/>
+    <Bug pattern="OPM_OVERLY_PERMISSIVE_METHOD"/>
+  </Match>
+
   <Match>
     <Or>
       <Bug pattern="CRLF_INJECTION_LOGS"/>