Better documentation and bugfix

diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/CLIHelper.java b/src/main/java/eu/svjatoslav/commons/cli_helper/CLIHelper.java
index fb98f12..b2ee395 100755 (executable)
--- a/src/main/java/eu/svjatoslav/commons/cli_helper/CLIHelper.java
+++ b/src/main/java/eu/svjatoslav/commons/cli_helper/CLIHelper.java
@@ -4,9 +4,6 @@
  */
 package eu.svjatoslav.commons.cli_helper;
 
-import java.io.BufferedReader;
-import java.io.IOException;
-import java.io.InputStreamReader;
 import java.util.Scanner;
 
 import static java.lang.Float.parseFloat;
@@ -19,48 +16,70 @@ import static java.lang.String.valueOf;
 public class CLIHelper {
 
     /**
-     * Ask boolean value from user on command-line.
+     * Asks the user for a boolean value using the specified prompt on the command line.
+     * The user may respond with one of the following to indicate "true":
+     * <ul>
+     *   <li>y</li>
+     *   <li>yes</li>
+     *   <li>true</li>
+     * </ul>
+     * ...or one of the following to indicate "false":
+     * <ul>
+     *   <li>n</li>
+     *   <li>no</li>
+     *   <li>false</li>
+     * </ul>
+     * If the user presses ENTER (empty input), the provided defaultValue is returned.
      *
-     * @param prompt to show to the user
-     * @return <code>true</code> is user answered affirmative.
+     * @param prompt       the message to display to the user
+     * @param defaultValue the boolean value to return if the user provides no input
+     * @return {@code true} if the user answered affirmatively,
+     *         {@code false} if they answered negatively,
+     *         or {@code defaultValue} if input was empty
      */
     public static boolean askBoolean(final String prompt, final boolean defaultValue) {
+        while (true) {
+            // Show the user something like "Continue? [Y/n]: " or "Continue? [y/N]: "
+            String line = askString(prompt + " [" + (defaultValue ? "Y/n" : "y/N") + "]: ");
 
-            while (true)
-            {
-                String line = askString(prompt + " [" + (defaultValue ? "Y/n" : "y/N") + "]: ");
-                if (line == null) return defaultValue;
-
-                final String userInput = line.toLowerCase();
+            // If user provided an empty line, askString() returns null in this usage => default
+            if (line == null) {
+                return defaultValue;
+            }
 
-                if ("y".equals(userInput) || "yes".equals(userInput)
-                        || "true".equals(userInput))
-                    return true;
+            final String userInput = line.toLowerCase();
 
-                if ("n".equals(userInput) || "no".equals(userInput)
-                        || "false".equals(userInput))
-                    return false;
-                System.out
-                        .println("Invalid input. You shall enter y/yes/true or n/no/false.");
+            if ("y".equals(userInput) || "yes".equals(userInput) || "true".equals(userInput)) {
+                return true;
+            }
+            if ("n".equals(userInput) || "no".equals(userInput) || "false".equals(userInput)) {
+                return false;
             }
+
+            System.out.println("Invalid input. Please enter y/yes/true or n/no/false.");
+        }
     }
 
     /**
-     * Ask numerical double value from user on command-line.
+     * Asks the user for a float value using the specified prompt on the command line.
+     * The user is prompted until a valid float within the specified range [min..max] is provided.
+     * An empty input (just pressing ENTER) will use the provided defaultValue.
      *
-     * @param prompt to show to the user
-     * @param defaultValue Default value.
-     * @param min Minimum value (inclusive).
-     * @param max Maximum value (inclusive).
-     * @return value given by user
+     * @param prompt       the message to display to the user
+     * @param defaultValue the float value to use if the user provides no input
+     * @param min          the minimum acceptable value (inclusive)
+     * @param max          the maximum acceptable value (inclusive)
+     * @return a float value entered by the user, or {@code defaultValue} if empty input
      */
     private float askFloat(String prompt, float defaultValue, float min, float max) {
         while (true) {
             String input = askString(prompt, valueOf(defaultValue));
             try {
-                float value = parseFloat(input);
-                if (value >= min && value <= max) return value;
-                System.out.println("Value must be between " + min + " and " + max);
+                float parsedValue = parseFloat(input);
+                if (parsedValue >= min && parsedValue <= max) {
+                    return parsedValue;
+                }
+                System.out.println("Value must be between " + min + " and " + max + ".");
             } catch (NumberFormatException e) {
                 System.out.println("Invalid number format. Try again.");
             }
@@ -68,21 +87,25 @@ public class CLIHelper {
     }
 
     /**
-     * Ask numerical double value from user on command-line.
+     * Asks the user for a long value using the specified prompt on the command line.
+     * The user is prompted until a valid long within the specified range [min..max] is provided.
+     * An empty input (just pressing ENTER) will use the provided defaultValue.
      *
-     * @param prompt to show to the user
-     * @param defaultValue Default value.
-     * @param min Minimum value (inclusive).
-     * @param max Maximum value (inclusive).
-     * @return value given by user
+     * @param prompt       the message to display to the user
+     * @param defaultValue the long value to use if the user provides no input
+     * @param min          the minimum acceptable value (inclusive)
+     * @param max          the maximum acceptable value (inclusive)
+     * @return a long value entered by the user, or {@code defaultValue} if empty input
      */
-    private float askLong(String prompt, float defaultValue, long min, long max) {
+    private long askLong(String prompt, long defaultValue, long min, long max) {
         while (true) {
             String input = askString(prompt, valueOf(defaultValue));
             try {
-                float value = parseLong(input);
-                if (value >= min && value <= max) return value;
-                System.out.println("Value must be between " + min + " and " + max);
+                long parsedValue = parseLong(input);
+                if (parsedValue >= min && parsedValue <= max) {
+                    return parsedValue;
+                }
+                System.out.println("Value must be between " + min + " and " + max + ".");
             } catch (NumberFormatException e) {
                 System.out.println("Invalid number format. Try again.");
             }
@@ -90,24 +113,29 @@ public class CLIHelper {
     }
 
     /**
-     * Ask string value from user on command-line.
+     * Asks the user for a string value using the specified prompt on the command line.
+     * If the user presses ENTER without typing anything and {@code defaultValue} is non-null,
+     * that default value is returned.
      *
-     * @param prompt Prompt to show to the user.
-     * @param defaultValue Default value.
-     * @return value given by the user
+     * @param prompt       the message to display to the user
+     * @param defaultValue the value to return if the user provides no input
+     * @return the value typed by the user, or {@code defaultValue} if empty input
      */
     public static String askString(String prompt, String defaultValue) {
         Scanner scanner = new Scanner(System.in);
         System.out.print(prompt + (defaultValue != null ? " [" + defaultValue + "]" : "") + ": ");
         String input = scanner.nextLine().trim();
+
+        // Return the default if user just pressed ENTER
         return input.isEmpty() && defaultValue != null ? defaultValue : input;
     }
 
     /**
-     * Ask string value from user on command-line.
+     * Asks the user for a string value using the specified prompt on the command line.
+     * If the user presses ENTER without typing anything, {@code null} is returned.
      *
-     * @param prompt Prompt to show to the user.
-     * @return value given by the user or <code>null</code> if user did not provide any input.
+     * @param prompt the message to display to the user
+     * @return the value typed by the user, or {@code null} if empty input
      */
     public static String askString(String prompt) {
         return askString(prompt, null);