#503: Added -h / --help to the command line.

core/src/main/java/org/itsallcode/openfasttrace/core/cli/ArgumentValidator.java

@@ -40,7 +40,11 @@ private boolean validate()
     {
         final Optional<String> command = this.arguments.getCommand();
         boolean ok = false;
-        if (command.isEmpty())
+        if (this.arguments.isHelpSet())
+        {
+            ok = true;
+        }
+        else if (command.isEmpty())
         {
             this.error = "Missing command";
             this.suggestion = "Add one of " + listCommands();

core/src/main/java/org/itsallcode/openfasttrace/core/cli/CliArguments.java

@@ -19,7 +19,7 @@
  * This class implements a parameter object into which the command line parser
  * injects the results of parsing the command line.
  */
 public class CliArguments
 {
     /** Filter in command line arguments matching items with no tags. */
     public static final String NO_TAGS_MARKER = "_";
@@ -45,6 +45,7 @@
 
     // [impl->dsn~cli.plugins.log~1]
     private LogLevel logLevel;
+    private boolean isHelpSet;
 
     /**
      * Create new {@link CliArguments}.
@@ -255,17 +256,49 @@
     }
 
     /**
-     * Get a list of artifact types to be applied as filter during import
+     * Check if the help switch is set
+     *
+     * @return {@code true} if the help switch is set
+     */
+    public boolean isHelpSet()
+    {
+        return this.isHelpSet;
+    }
+
+    /**
+     * Set the help switch (no arguments)
+     *
+     * @param helpSet
+     *            {@code true} to set the help switch
+     */
+    public void setHelp(final boolean helpSet)
+    {
+        this.isHelpSet = helpSet;
+    }
+
+    /**
+     * Set the help switch (no arguments)
+     *
+     * @param helpSet
+     *            {@code true} to set the help switch
+     */
+    public void setH(final boolean helpSet)
+    {
+        setHelp(helpSet);
+    }
+
+    /**
+     * Get a list of artifact types to be applied as a filter during import
      * 
-     * @return list of wanted artifact types
+     * @return set of wanted artifact types
      */
     public Set<String> getWantedArtifactTypes()
     {
         return this.wantedArtifactTypes;
     }
 
     /**
-     * Set a list of artifact types to be applied as filter during import
+     * Set a list of artifact types to be applied as a filter during import
      * 
      * @param artifactTypes
      *            list of wanted artifact types
@@ -281,7 +314,7 @@
     }
 
     /**
-     * Set a list of artifact types to be applied as filter during import
+     * Set a list of artifact types to be applied as a filter during import
      * 
      * @param artifactTypes
      *            list of wanted artifact types
@@ -292,9 +325,9 @@
     }
 
     /**
-     * Get a list of tags to be applied as filter during import
+     * Get a list of tags to be applied as a filter during import
      * 
-     * @return list of wanted tags
+     * @return set of wanted tags
      */
     public Set<String> getWantedTags()
     {
@@ -337,7 +370,7 @@
     }
 
     /**
-     * Set a list of tags to be applied as filter during import
+     * Set a list of tags to be applied as a filter during import
      * 
      * @param tags
      *            list of wanted tags
@@ -348,7 +381,7 @@
     }
 
     /**
-     * Set a list of tags to be applied as filter during import
+     * Set a list of tags to be applied as a filter during import
      * 
      * @param tags
      *            list of wanted tags

core/src/main/java/org/itsallcode/openfasttrace/core/cli/CliStarter.java

@@ -1,16 +1,17 @@
 package org.itsallcode.openfasttrace.core.cli;
 
-import java.util.Optional;
-
 import org.itsallcode.openfasttrace.api.cli.DirectoryService;
 import org.itsallcode.openfasttrace.core.cli.commands.*;
 import org.itsallcode.openfasttrace.core.cli.logging.LoggingConfigurator;
 
+import static org.itsallcode.openfasttrace.core.cli.ExitStatus.*;
+
 /**
  * The main entry point class for the command line application.
  */
 public class CliStarter
 {
+    private static final String MISSING_COMMAND = "missing";
     private final CliArguments arguments;
 
     /**
@@ -33,7 +34,7 @@
     public static void main(final String[] args)
     {
         final DirectoryService directoryService = new StandardDirectoryService();
-        main(args, directoryService);
+        exit(mainDelegate(args, directoryService));
     }
 
     /**
@@ -45,38 +46,32 @@
      * @param directoryService
      *            directory service for getting the current directory. This
      *            allows injecting a mock in unit tests.
+     * @return exit status of the command.
      */
-    public static void main(final String[] args, final DirectoryService directoryService)
+    public static ExitStatus mainDelegate(final String[] args, final DirectoryService directoryService)
     {
-        final CliArguments arguments = parseCommandLineArguments(args, directoryService);
-        final ArgumentValidator validator = new ArgumentValidator(arguments);
-        if (validator.isValid())
-        {
-            LoggingConfigurator.create(arguments).configureLogging();
-            new CliStarter(arguments).run();
+        try {
+            final CliArguments arguments = parseCommandLineArguments(args, directoryService);
+            final ArgumentValidator validator = new ArgumentValidator(arguments);
+            if (validator.isValid()) {
+                LoggingConfigurator.create(arguments).configureLogging();
+                return new CliStarter(arguments).run();
+            } else {
+                printToStdError(
+                        "oft: " + validator.getError() + "\n" + validator.getSuggestion() + "\n");
+                return CLI_ERROR;
+            }
         }
-        else
-        {
-            printToStdError(
-                    "oft: " + validator.getError() + "\n" + validator.getSuggestion() + "\n");
-            exit(ExitStatus.CLI_ERROR);
+        catch (final CliException e) {
+            printToStdError("oft: " + e.getMessage());
+            return CLI_ERROR;
         }
     }
 
-    @SuppressWarnings("java:S1166") // Exceptions are reported to the user
     private static CliArguments parseCommandLineArguments(final String[] args,
-            final DirectoryService directoryService)
-    {
+            final DirectoryService directoryService) throws CliException {
         final CliArguments arguments = new CliArguments(directoryService);
-        try
-        {
-            new CommandLineInterpreter(args, arguments).parse();
-        }
-        catch (final CliException e)
-        {
-            printToStdError("oft: " + e.getMessage());
-            exit(ExitStatus.CLI_ERROR);
-        }
+        new CommandLineInterpreter(args, arguments).parse();
         return arguments;
     }
 
@@ -89,40 +84,28 @@
 
     /**
      * Process the command line arguments and execute the commands.
+     *
+     * @return the exit status of the command.
      */
     // [impl->dsn~cli.command-selection~1]
-    public void run()
+    public ExitStatus run()
     {
-        final Optional<String> command = this.arguments.getCommand();
-        if (!command.isPresent())
-        {
-            new HelpCommand().run();
-            throw new IllegalStateException("Command missing trying to execute OFT mode.");
-        }
-        final Performable performable;
-        switch (command.get())
+        final String command = this.arguments.isHelpSet()
+                ? HelpCommand.COMMAND_NAME
+                : this.arguments.getCommand().orElse(MISSING_COMMAND);
+        switch (command)
         {
         case ConvertCommand.COMMAND_NAME:
-            performable = new ConvertCommand(this.arguments);
-            break;
+            return new ConvertCommand(this.arguments).run() ? OK : FAILURE;
         case TraceCommand.COMMAND_NAME:
-            performable = new TraceCommand(this.arguments);
-            break;
+            return new TraceCommand(this.arguments).run() ? OK : FAILURE;
         case HelpCommand.COMMAND_NAME:
-            performable = new HelpCommand();
-            break;
+            return new HelpCommand(true).run() ? OK : FAILURE;
+        case MISSING_COMMAND:
         default:
-            new HelpCommand().run();
-            exit(ExitStatus.CLI_ERROR);
-            return;
-        }
-        if (performable.run())
-        {
-            exit(ExitStatus.OK);
-        }
-        else
-        {
-            exit(ExitStatus.FAILURE);
+            new HelpCommand(false).run();
+            printToStdError("Compand missing trying to execute OFT. Choose one of: trace, convert, help");
+            return CLI_ERROR;
         }
     }
 

core/src/main/java/org/itsallcode/openfasttrace/core/cli/CommandLineInterpreter.java

@@ -12,12 +12,13 @@
 
 /**
  * This class implements an interpreter for command line arguments
- *
+ * <p>
  * Users of this class must create a POJO that contains a setter method for each
  * command line argument that they want to use.
- *
- * Additionally they can add a setter called <code>setUnnamedValues</code> that
+ * </p><p>
+ * Additionally, they can add a setter called <code>setUnnamedValues</code> that
  * will receive all argument values that are unnamed.
+ * </p>
  */
 public class CommandLineInterpreter
 {

core/src/main/java/org/itsallcode/openfasttrace/core/cli/commands/HelpCommand.java

@@ -11,13 +11,17 @@ public class HelpCommand implements Performable
 {
     /** The command line action for running this command. */
     public static final String COMMAND_NAME = "help";
+    /** Whether the OFT command was used correctly. */
+    private final boolean validUsage;
 
     /**
      * Create a new {@link HelpCommand}.
+     *
+     * @param validUsage whether the OFT command was used correctly
      */
-    public HelpCommand()
+    public HelpCommand(final boolean validUsage)
     {
-        // empty by intention
+        this.validUsage = validUsage;
     }
 
     @Override
@@ -26,7 +30,7 @@ public boolean run()
     {
         final String usage = loadResource("/usage.txt");
         System.out.println(usage);
-        return true;
+        return validUsage;
     }
 
     private String loadResource(final String resourceName)
@@ -52,5 +56,4 @@ private URL getResource(final String resourceName)
         }
         return url;
     }
-
 }

doc/changes/changes.md

@@ -1,6 +1,7 @@
 # Changes
 
-* [4.3.1](changes_4.4.0.md)
+* [4.5.0](changes_4.5.0.md)
+* [4.4.0](changes_4.4.0.md)
 * [4.3.0](changes_4.3.0.md)
 * [4.2.3](changes_4.2.3.md)
 * [4.2.2](changes_4.2.2.md)

doc/changes/changes_4.5.0.md

@@ -0,0 +1,13 @@
+# OpenFastTrace 4.4.0, released 2026-05-??
+
+Code name: ???
+
+## Summary
+
+In this release we added the a `-h` / `--help` to the command line.
+
+We also refactored the tests around the CLI starter to improve readability and maintainability and made getting the test coverage easier.
+
+## Features
+
+* #503: Added `-h` / `--help` to the command line.