8 add new type command

README.md

@@ -16,6 +16,7 @@ catering to diverse application needs.
 
 - **Easy Definition of Parameters:** Define parameters with flag names and shorthands, 
   mandatory/optional status, as well as optional default values and descriptions.
+- **Custom Command Support:** Define custom commands and easily check if they were provided.  
 - **Robust Parsing-Error Handling:** Catch and handle custom exceptions for missing arguments, 
   invalid types, and other common parsing errors.
 - **Automatic exception handling** Alternatively of handling parsing errors manually, you can use a parsing method that 
@@ -60,13 +61,13 @@ Instantiate an ArgsParser object, and hand over the String array `args` from the
 public static void main(String[] args) {
     ArgsParser parser = new ArgsParser(args);
     // ...
-}
 ```
 
-### 2. Define the Parameters
+### 2. Define the Parameters or Commands
 This parser supports 5 **types**:
 - *String, Integer, Double, Boolean, Character*
 
+#### addParameter methods:
 The type of a Parameter is defined with its respective method on the parser object.
 For each type there are 5 `addParameter` methods (example for String):
 - `addMandatoryStringParameter(String fullFlag, String shortFlag, String description)`
@@ -77,28 +78,39 @@ For each type there are 5 `addParameter` methods (example for String):
 
 (see a list of all Methods at the end of this README)
 
+#### Available Fields for each Parameter:
 You can specify several fields for each parameter:
 
 - **fullFlag**: The flag name of the parameter.
 - **shortFlag**: A short version of the flag for the parameter.
 - **description**: A description of the parameter, insert `null` or an empty string`""` if not needed.
 - **defaultValue**: A default value that the parameter returns if no argument was provided but accessed in the program.
 
+#### Multiple Arguments to one flag:
 A **special type** are the `addArray` methods that are introduced in Version 4.0.0 of the ArgsParser. 
 They allow handing several arguments to a single flag:
 ```
 --file path/file1 path/file2 path/file3
 ```
 Several of these Array Parameters can be defined without problems.
 
+#### Commands:
+
+Another added feature in Version 4.0.0 is the "command" type.
+The parser checks if any commands were provided in the arguments, enabling the developer to activate different
+modes or functionalities based on the commands passed. 
+You simply define commands just like regular parameters, and the
+parser will recognize them when parsing the input arguments.
+
 ```java
-    // ...
+// ...
     Parameter<String> example = parser.addMandatoryStringParameter("parameterFlag", "pf", "short Description");
     Parameter<Integer> example2 = parser.addOptionalIntegerParameter("parameterFlag2", "pf2", null);
     Parameter<Double> argWithDefault = parser.addDefaultDoubleParameter("parameterFlag3", "pf3", "description", 5.6);
     Parameter<Boolean[]> booleanArrayParam = parser.addBooleanArrayParameter("boolArray", "bArr", "Array of several boolean values", false);
     Parameter<Integer[]> integerArrayParam = parser.addDefaultIntegerArrayParameter("intArray", "iArr", "Array of several integer values", new Integer[]{1, 2, 3});
-    // ...
+    Command command = parser.addCommand("commandName", "cN", "this is a description for the command");
+// ...
 ```
 
 ### 3. Parse the Arguments
@@ -150,6 +162,8 @@ or like the following example for manually handling the ArgsExceptions:
 ```
 
 ### 4. Access the Arguments
+
+#### direct access to arguments via its parameter
 Access the console arguments given by the user by calling the `getArgument()` method on the parameter variable.  
 The return type matches the type defined when adding the parameter.
 The **arguments can be used directly in your code**!
@@ -158,8 +172,18 @@ The **arguments can be used directly in your code**!
     // ...
     String providedArgument = example.getArgument();
     Double result = example2.getArgument() + argWithDefault.getArgument();
+    //...
+```
+
+#### check provision of a command
+For the commands, a simple call of `isProvided` on the Command instance will return if the command was provided in args:
+```java
+    //...
+    if (command.isProvided()) System.out.println("command provided");
+    //...
 ```
 
+#### access arguments indirectly via the ArgsParser instance they were defined on
 With version 3.0.0 the `getArgumentOf(String fullFlag)` method ia available, thus arguments provided to a specific
 parameter flag can be accessed by the parameter flugFlag name.
 But this comes with some restrictions:
@@ -174,7 +198,13 @@ But this comes with some restrictions:
     Integer getInteger = parser.getArgumentOf("parameterFlag2");
     Double getDouble = parser.getArgumentOf("parameterFlag3");
     Double result = getInteger + getDouble;
-}
+    //...
+```
+
+The same is possible with commands:
+```java
+    //...
+    if (parser.checkIfCommandIsProvided("commandName")) System.out.println("command still provided");
 ```
 
 ## Integrated --help function:
@@ -193,7 +223,7 @@ they were added** on the ArgsParser Instance:
 ############################################### HELP ###############################################
 #   [s]/[s+]=String | [i]/[i+]=Integer | [c]/[c+]=Character | [b]/[b+]=Boolean | [d]/[d+]=Double
 #       ('+' marks a flag that takes several arguments of the same type whitespace separated)
-#                                   (!)=mandatory | (?)=optional
+#                            (!)=mandatory | (?)=optional | (/)=command
 #
 #                                      Available Parameters:
 #
@@ -209,18 +239,20 @@ they were added** on the ArgsParser Instance:
 ###  --intArray        -iArr  [i+] (?)  Array of several integer values
 #                             default:  [1, 2, 3]
 #
+###  commandName       cN          (/)  this is a description for the command
+#
 ####################################################################################################
 ```
 
 while calling `--help` or `-h` with a specific parameter will only print the help message for that parameter:
 
-`> exampleProgramm -pf4 -h`
+`> exampleProgramm -pf3 -h`
 ```
 
 ############################################### HELP ###############################################
 #   [s]/[s+]=String | [i]/[i+]=Integer | [c]/[c+]=Character | [b]/[b+]=Boolean | [d]/[d+]=Double
 #       ('+' marks a flag that takes several arguments of the same type whitespace separated)
-#                                   (!)=mandatory | (?)=optional
+#                            (!)=mandatory | (?)=optional | (/)=command
 #
 ###  --parameterFlag3  -pf3   [d]  (?)  description
 #                             default:  5.6
@@ -232,33 +264,33 @@ while calling `--help` or `-h` with a specific parameter will only print the hel
 The ArgsParser will throw an `ArgsException` if the user provides invalid arguments.
 The printouts of these exceptions look like this:
 
-`> exampleProgramm -pf4 5.6 5.6`
+`> exampleProgramm -pf3 5.6 5.6`
 ```
 
-<!> Too many arguments provided to flag: -pf4
+<!> Too many arguments provided to flag: -pf3
 
 > Use --help for more information.
 
 ```
 
 or 
 
-`> exampleProgramm -pf4`
+`> exampleProgramm -pf3`
 ```
 
-<!> Missing argument for flag: -pf4
+<!> Missing argument for flag: -pf3
 
 > Use --help for more information.
 
 ```
 
 for misspelled flags, the Parser will even do a suggestion:
 
-`> exampleProgramm --paraeterflg4, 5.6`
+`> exampleProgramm --paraeterflg3, 5.6`
 ```
 
-<!> unknown flag: --paraeterflg4
-> did you mean: --parameterFlag4 ?
+<!> unknown flag: --paraeterflg3
+> did you mean: --parameterFlag3 ?
 
 > Use --help for more information.
 
@@ -300,3 +332,16 @@ for misspelled flags, the Parser will even do a suggestion:
 - `addDefaultCharacterParameter(String fullFlag, String shortFlag, String description, Character defaultValue)`
 - `addCharacterArrayParameter(String fullFlag, String shortFlag, String description, boolean isMandatory)`
 - `addDefaultCharacterArrayParameter(String fullFlag, String shortFlag, String description, Character[] defaultValue)`
+
+#### access an Argument of ANY of these Parameters:
+- `parameter.getArgument()`
+
+#### Command type:
+- `addCommand(String fullCommandName, String shortCommandName, String description)`
+
+#### check provision of a specific command:
+- `command.isProvided()`
+
+#### indirect access of parameters / commands:
+- `getArgumentOf(String fullFlag)`
+- `checkIfCommandIsProvided(String fullCommandName)`

src/ArgsParser/ArgsExceptions/UnknownFlagArgsException.java

@@ -1,54 +1,61 @@
 package ArgsParser.ArgsExceptions;
 
 import ArgsParser.ArgsException;
-import ArgsParser.ArgsParser;
-import jdk.jshell.SourceCodeAnalysis;
-
-import java.util.LinkedList;
 import java.util.Set;
 
 /**
  * Exception to be thrown if an unknown flag is provided
  */
 public class UnknownFlagArgsException extends ArgsException {
-    public UnknownFlagArgsException(String flagName, LinkedList<String> fullFlags, LinkedList<String> shortFlags) {
-        super("unknown flag: " + flagName + computeSuggestion(flagName, fullFlags, shortFlags), true);
+    public UnknownFlagArgsException(String flagName, Set<String> parameterFlags, Set<String> commandNames, boolean isFirstPosition) {
+        super("unknown flag or command: " + flagName + computeSuggestion(flagName, parameterFlags, commandNames, isFirstPosition), true);
     }
 
     /**
      * Compute a suggestion for the user based on the flag name
      * @param userInput the flag name provided by the user
-     * @param fullFlags the full flags available
-     * @param shortFlags the short flags available
+     * @param parameterFlags the full flags available
+     * @param commandNames the short flags available
      * @return a suggestion for the user
      */
-    protected static String computeSuggestion(String userInput, LinkedList<String> fullFlags, LinkedList<String> shortFlags) {
-        fullFlags.add("help");
-        shortFlags.add("h");
-        userInput = stripFlagPrefix(userInput);
+    protected static String computeSuggestion(String userInput, Set<String> parameterFlags, Set<String> commandNames, boolean isFirstPosition) {
+        String strippedInput = stripFlagPrefix(userInput);
         double highestSimilarity = 0.0;
         String suggestion = "";
 
-        for (String fullFlag : fullFlags) {
-            fullFlag = stripFlagPrefix(fullFlag);
-            double similarity = SimilarityScore(userInput, fullFlag);
+        for (String parameterFlag : parameterFlags) {
+            String strippedFlag = stripFlagPrefix(parameterFlag);
+            double similarity = SimilarityScore(strippedInput, strippedFlag);
+            if (similarity > highestSimilarity) {
+                highestSimilarity = similarity;
+                suggestion = parameterFlag;
+            }
+        }
+
+        for (String help : new String[]{"--help", "-h"}) {
+            String strippedFlag = stripFlagPrefix(help);
+            double similarity = SimilarityScore(strippedInput, strippedFlag);
             if (similarity > highestSimilarity) {
                 highestSimilarity = similarity;
-                suggestion = "--" + fullFlag;
+                suggestion = help;
             }
         }
 
-        for (String shortFlag : shortFlags) {
-            shortFlag = stripFlagPrefix(shortFlag);
-            double similarity = SimilarityScore(userInput, shortFlag);
+        for (String commandName : commandNames) {
+            commandName = stripFlagPrefix(commandName);
+            double similarity = SimilarityScore(strippedInput, commandName);
             if (similarity > highestSimilarity) {
                 highestSimilarity = similarity;
-                suggestion = "-" + shortFlag;
+                suggestion = commandName;
             }
         }
 
         if (highestSimilarity < 0.1) {
             return "";
+        } else if (isFirstPosition && !(userInput.charAt(0) == '-')) {
+            return "\n> did you mean: " + suggestion + " ?" +
+                    "\n" +
+                    "\n> flag or command expected in first position!";
         } else {
             return "\n> did you mean: " + suggestion + " ?";
         }