Document @ syntax

This makes the help message print usage information on both the `help` command and the `@` argument syntax. It also adds a missing package `opens`. Fix: #3
io7m · Jun 27, 2020 · 2167234 · 2167234
1 parent b13cb45
commit 2167234
Show file tree

Hide file tree

Showing 4 changed files with 40 additions and 11 deletions.
diff --git a/README-CHANGES.xml b/README-CHANGES.xml
@@ -4,13 +4,18 @@
     <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:06+00:00" ticket-system="com.github.io7m.claypot" version="0.0.2">
+    <c:release date="2020-06-27T19:40:45+00:00" ticket-system="com.github.io7m.claypot" version="0.0.2">
       <c:changes>
-        <c:change date="2020-06-27T19:40:06+00:00" summary="Add extended help methods.">
+        <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:tickets>
+            <c:ticket id="3"/>
+          </c:tickets>
+        </c:change>
       </c:changes>
     </c:release>
   </c:releases>

diff --git a/...o7m.claypot.core/src/main/java/com/io7m/claypot/core/internal/CLPBriefUsageFormatter.java b/...o7m.claypot.core/src/main/java/com/io7m/claypot/core/internal/CLPBriefUsageFormatter.java
@@ -67,17 +67,18 @@ public void appendMainLine(
     final String indent)
   {
     super.appendMainLine(out, hasOptions, hasCommands, indentCount, indent);
-
-    out.append('\n');
-    out.append("  ");
-    out.append(this.strings.format(
-      "com.io7m.claypot.help",
-      this.commander.getProgramName()
-    ).trim());
-    out.append('\n');
     out.append('\n');
   }
 
+  private static String indentLine(
+    final String text)
+  {
+    if (text.trim().isEmpty()) {
+      return "";
+    }
+    return "  " + text;
+  }
+
   @Override
   public void appendCommands(
     final StringBuilder out,
@@ -120,6 +121,19 @@ public void appendCommands(
         out.append('\n');
       }
     }
+
+    out.append('\n');
+
+    final var programName = this.commander.getProgramName();
+    this.strings.format("com.io7m.claypot.help", programName)
+      .trim()
+      .lines()
+      .forEach(line -> {
+        out.append(indentLine(line));
+        out.append('\n');
+      });
+
+    out.append('\n');
   }
 
   @Override

diff --git a/com.io7m.claypot.core/src/main/java/module-info.java b/com.io7m.claypot.core/src/main/java/module-info.java
@@ -30,6 +30,7 @@
   requires org.slf4j;
 
   opens com.io7m.claypot.core to jcommander;
+  opens com.io7m.claypot.core.internal to jcommander;
 
   exports com.io7m.claypot.core;
 }
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
@@ -9,7 +9,16 @@
   <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 (Try: {0} help help).
+Use the "help" command to examine specific commands:
+
+  $ {0} help help.
+
+Command-line arguments can be placed one per line into a file, and the file
+can be referenced using the @ symbol:
+
+  $ echo help > file.txt
+  $ 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