Merge branch 'release/0.0.2'

Release: com.io7m.claypot 0.0.2
Change: Allow applications to publish documentation URIs. (Ticket: #2)
Change: Document @ syntax. (Ticket: #3)
Change: Add extended help methods. (Ticket: #1)

README-CHANGES.xml

@@ -1,9 +1,28 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <c:changelog project="com.io7m.claypot" xmlns:c="urn:com.io7m.changelog:4.0">
   <c:releases>
-    <c:release date="2020-06-26T14:07:02+00:00" ticket-system="com.github.io7m.claypot" version="0.0.1">
+    <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-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-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>
   <c:ticket-systems>
     <c:ticket-system default="true" id="com.github.io7m.claypot" url="https://www.github.com/io7m/claypot/issues/"/>

README-LICENSE.txt

@@ -0,0 +1,13 @@
+Copyright © 2020 Mark Raynsford <code@io7m.com> https://www.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.

com.io7m.claypot.core/pom.xml

@@ -9,7 +9,7 @@
   <parent>
     <artifactId>com.io7m.claypot</artifactId>
     <groupId>com.io7m.claypot</groupId>
-    <version>0.0.1</version>
+    <version>0.0.2</version>
   </parent>
 
   <artifactId>com.io7m.claypot.core</artifactId>

com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/CLPAbstractCommand.java

@@ -18,7 +18,7 @@
 
 import com.beust.jcommander.JCommander;
 import com.beust.jcommander.Parameter;
-import com.beust.jcommander.Parameters;
+import com.io7m.claypot.core.internal.CLPLogLevelConverter;
 import org.osgi.annotation.versioning.ProviderType;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -30,7 +30,6 @@
  */
 
 @ProviderType
-@Parameters(resourceBundle = "com.io7m.claypot.core.Claypot")
 public abstract class CLPAbstractCommand implements CLPCommandType
 {
   private final JCommander commander;
@@ -39,7 +38,7 @@ public abstract class CLPAbstractCommand implements CLPCommandType
   @Parameter(
     names = "--verbose",
     converter = CLPLogLevelConverter.class,
-    descriptionKey = "com.io7m.claypot.rootDescription"
+    description = "Set the minimum logging verbosity level."
   )
   private CLPLogLevel verbose = CLPLogLevel.LOG_INFO;
 
@@ -71,6 +70,11 @@ protected final Logger logger()
     return this.configuration().logger();
   }
 
+  protected final CLPStringsType strings()
+  {
+    return this.context.strings();
+  }
+
   protected final CLPApplicationConfiguration configuration()
   {
     return this.context().configuration();

com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/CLPAbstractStrings.java

@@ -16,8 +16,12 @@
 
 package com.io7m.claypot.core;
 
+import com.io7m.claypot.core.internal.CLPXMLResourceBundle;
 import org.osgi.annotation.versioning.ProviderType;
 
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.UncheckedIOException;
 import java.text.MessageFormat;
 import java.util.Objects;
 import java.util.ResourceBundle;
@@ -52,5 +56,28 @@ public final String format(
     Objects.requireNonNull(args, "args");
     return MessageFormat.format(this.resources.getString(id), args);
   }
+
+  protected static ResourceBundle ofXMLResource(
+    final Class<?> clazz,
+    final String resource)
+  {
+    try (var stream = clazz.getResourceAsStream(resource)) {
+      return ofXML(stream);
+    } catch (final IOException e) {
+      throw new UncheckedIOException(e);
+    }
+  }
+
+  protected static ResourceBundle ofXML(
+    final InputStream stream)
+  {
+    try {
+      return new CLPXMLResourceBundle(
+        Objects.requireNonNull(stream, "stream")
+      );
+    } catch (final IOException e) {
+      throw new UncheckedIOException(e);
+    }
+  }
 }
 

com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/CLPApplicationConfigurationType.java

@@ -20,15 +20,39 @@
 import org.immutables.value.Value;
 import org.slf4j.Logger;
 
+import java.net.URI;
 import java.util.List;
+import java.util.Optional;
+
+/**
+ * The application configuration.
+ */
 
 @ImmutablesStyleType
 @Value.Immutable
 public interface CLPApplicationConfigurationType
 {
+  /**
+   * @return The logger used for command-line messages
+   */
+
   Logger logger();
 
+  /**
+   * @return The name of the application
+   */
+
   String programName();
 
+  /**
+   * @return The URI of any documentation for the application
+   */
+
+  Optional<URI> documentationURI();
+
+  /**
+   * @return The list of commands
+   */
+
   List<CLPCommandConstructorType> commands();
 }

com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/CLPCommandConstructorType.java

@@ -22,5 +22,13 @@
 
 public interface CLPCommandConstructorType
 {
+  /**
+   * Create a new command instance.
+   *
+   * @param context The command context
+   *
+   * @return A new command
+   */
+
   CLPCommandType create(CLPCommandContextType context);
 }

com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/CLPCommandContextType.java

@@ -24,6 +24,8 @@
 
 public interface CLPCommandContextType
 {
+  CLPStringsType strings();
+
   CLPApplicationConfiguration configuration();
 
   JCommander commander();

com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/CLPCommandType.java

@@ -25,6 +25,14 @@
 @ProviderType
 public interface CLPCommandType
 {
+  /**
+   * @return Extra help text for the command
+   */
+
+  default String extendedHelp() {
+    return "";
+  }
+
   /**
    * @return The name of the command
    */

com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/CLPLogLevel.java

@@ -79,7 +79,11 @@ public String getName()
     return this.name;
   }
 
-  Level toLevel()
+  /**
+   * @return The level as a Logback level
+   */
+
+  public Level toLevel()
   {
     switch (this) {
       case LOG_TRACE:

com.io7m.claypot.core/src/main/java/com/io7m/claypot/core/CLPStrings.java

@@ -18,19 +18,26 @@
 
 import java.util.ResourceBundle;
 
-public final class CLPStrings
-  extends CLPAbstractStrings
+/**
+ * The default provider of strings.
+ */
+
+public final class CLPStrings extends CLPAbstractStrings
 {
   private CLPStrings(
     final ResourceBundle inResources)
   {
     super(inResources);
   }
 
+  /**
+   * @return A new string provider
+   */
+
   public static CLPStringsType create()
   {
     return new CLPStrings(
-      ResourceBundle.getBundle("com.io7m.claypot.core.Claypot")
+      ofXMLResource(CLPStrings.class, "/com/io7m/claypot/core/Claypot.xml")
     );
   }
 }