From c15ea00cc934f33f391fc1b11deee343ecbf31d3 Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Mon, 26 Jan 2026 23:45:18 +0200 Subject: [PATCH] Enhance Javadocs across CLI Helper classes: Provide detailed parameter descriptions, clarify return values, and expand examples where applicable. --- .../commons/cli_helper/CLIHelper.java | 147 +++++++++++------- .../svjatoslav/commons/cli_helper/Menu.java | 48 ++++-- .../cli_helper/parameter_parser/Option.java | 34 ++-- .../cli_helper/parameter_parser/Parser.java | 19 ++- .../parameter/DirectoryOption.java | 12 +- .../parameter/FileOptions.java | 5 +- .../parameter/StringOption.java | 10 +- 7 files changed, 184 insertions(+), 91 deletions(-) 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 ae0ad34..7ead139 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/CLIHelper.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/CLIHelper.java @@ -52,23 +52,23 @@ public final class CLIHelper { /** * Repeatedly prompts the user for a Boolean value. *

- * Accepted affirmative tokens (case‑insensitive): y, yes, - * true.
- * Accepted negative tokens: n, no, false. + * Accepted affirmative tokens (case-insensitive): y, yes, true. + * Accepted negative tokens: n, no, false. *

- * - *

If the user submits an empty line:

+ *

+ * Behavior for empty input: *

- * - * @param prompt message shown to the user (without trailing colon) - * @param defaultValue value returned when the user simply hits {@code Enter}; may be {@code null} - * @param allowEmpty whether an empty line without a default should yield {@code null} - * @return {@code Boolean.TRUE}, {@code Boolean.FALSE}, the supplied {@code defaultValue}, or {@code null} + *

+ * @param prompt The prompt message to display (without trailing colon). + * @param defaultValue The default value to return if the user enters an empty line; may be {@code null}. + * @param allowEmpty If {@code true}, allows empty input to return {@code null}; otherwise, continues prompting. + * @return {@code Boolean.TRUE}, {@code Boolean.FALSE}, the {@code defaultValue}, or {@code null} (if allowed). */ + public static Boolean askBoolean(final String prompt, final Boolean defaultValue, final boolean allowEmpty) { while (true) { String displayPrompt = prompt + (defaultValue != null ? " [" + defaultValue + "]" : "") + ": "; @@ -124,16 +124,26 @@ public final class CLIHelper { /*‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑ Float ‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑*/ /** - * Prompts the user for a {@code float} value that satisfies optional - * minimum/maximum bounds. - * - * @param prompt message shown to the user - * @param defaultValue value returned on empty input; may be {@code null} - * @param min inclusive lower bound, or {@code null} for no check - * @param max inclusive upper bound, or {@code null} for no check - * @param allowEmpty whether an empty line without a default should yield {@code null} - * @return the parsed {@link Float}, {@code defaultValue}, or {@code null} + * Prompts the user for a {@code float} value within optional bounds. + *

+ * Behavior for empty input: + *

+ *

+ *

+ * Bounds are inclusive. If {@code min} or {@code max} is {@code null}, no check is applied. + *

+ * @param prompt The prompt message to display. + * @param defaultValue The default value to return if the user enters an empty line; may be {@code null}. + * @param min Inclusive lower bound for the value, or {@code null} to disable check. + * @param max Inclusive upper bound for the value, or {@code null} to disable check. + * @param allowEmpty If {@code true}, allows empty input to return {@code null}; otherwise, continues prompting. + * @return The parsed {@code float}, the {@code defaultValue}, or {@code null} (if allowed). */ + public static Float askFloat(final String prompt, final Float defaultValue, final Float min, final Float max, final boolean allowEmpty) { while (true) { @@ -190,15 +200,24 @@ public final class CLIHelper { /*‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑ Long ‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑*/ /** - * Prompts the user for a {@code long} value that satisfies optional - * minimum/maximum bounds. - * - * @param prompt message shown to the user - * @param defaultValue value returned on empty input; may be {@code null} - * @param min inclusive lower bound, or {@code null} - * @param max inclusive upper bound, or {@code null} - * @param allowEmpty whether an empty line without a default should yield {@code null} - * @return the parsed {@link Long}, {@code defaultValue}, or {@code null} + * Prompts the user for an {@code int} value within optional bounds. + *

+ * Behavior for empty input: + *

+ *

+ *

+ * Bounds are inclusive. If {@code min} or {@code max} is {@code null}, no check is applied. + *

+ * @param prompt The prompt message to display. + * @param defaultValue The default value to return if the user enters an empty line; may be {@code null}. + * @param min Inclusive lower bound for the value, or {@code null} to disable check. + * @param max Inclusive upper bound for the value, or {@code null} to disable check. + * @param allowEmpty If {@code true}, allows empty input to return {@code null}; otherwise, continues prompting. + * @return The parsed {@code int}, the {@code defaultValue}, or {@code null} (if allowed). */ public static Long askLong(final String prompt, final Long defaultValue, final Long min, final Long max, final boolean allowEmpty) { @@ -313,14 +332,24 @@ public final class CLIHelper { /*‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑ String ‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑*/ /** - * Prompts the user for a non‑empty {@link String} and validates its length. - * - * @param prompt message shown to the user - * @param defaultValue value returned on empty input; may be {@code null} - * @param minLength inclusive lower bound; {@code null} means no check - * @param maxLength inclusive upper bound; {@code null} means no check - * @param allowEmpty whether an empty line without a default should yield {@code null} - * @return the typed {@link String}, {@code defaultValue}, or {@code null} + * Prompts the user for a string value with optional length constraints. + *

+ * Behavior for empty input: + *

+ *

+ *

+ * Length constraints are inclusive. If {@code minLength} or {@code maxLength} is {@code null}, no check is applied. + *

+ * @param prompt The prompt message to display. + * @param defaultValue The default value to return if the user enters an empty line; may be {@code null}. + * @param minLength Minimum allowed string length (inclusive), or {@code null} to disable check. + * @param maxLength Maximum allowed string length (inclusive), or {@code null} to disable check. + * @param allowEmpty If {@code true}, allows empty input to return {@code null}; otherwise, continues prompting. + * @return The input string, the {@code defaultValue}, or {@code null} (if allowed). */ public static String askString(final String prompt, final String defaultValue, final Integer minLength, final Integer maxLength, final boolean allowEmpty) { @@ -370,21 +399,35 @@ public final class CLIHelper { /*‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑ File / Directory ‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑‑*/ /** - * Prompts the user for a file path and validates various - * attributes (existence, readability, writability, executability). + * Prompts the user for a file path and validates specified attributes. *

- * A {@link File} object is returned as‑is; no attempt is made to - * canonicalise or resolve symlinks. + * A {@link File} object is returned as-is; no canonicalization or symlink resolution is performed. *

- * - * @param prompt message shown to the user - * @param defaultValue value returned on empty input; may be {@code null} - * @param mustExist if non‑{@code null}: {@code true} ⇒ file must exist, {@code false} ⇒ file must not exist - * @param mustReadable if non‑{@code null}: {@code true} ⇒ {@link File#canRead()} must be {@code true} - * @param mustWritable if non‑{@code null}: {@code true} ⇒ {@link File#canWrite()} must be {@code true} - * @param mustExecutable if non‑{@code null}: {@code true} ⇒ {@link File#canExecute()} must be {@code true} - * @param allowEmpty whether an empty line without a default should yield {@code null} - * @return a {@link File} satisfying all constraints, {@code defaultValue}, or {@code null} + *

+ * Behavior for empty input: + *

+ *

+ *

+ * Attribute checks: + *

+ *

+ * @param prompt The prompt message to display. + * @param defaultValue The default file to return if the user enters an empty line; may be {@code null}. + * @param mustExist Whether the file must exist ({@code true}), must not exist ({@code false}), or no check ({@code null}). + * @param mustReadable Whether the file must be readable ({@code true}), not readable ({@code false}), or no check ({@code null}). + * @param mustWritable Whether the file must be writable ({@code true}), not writable ({@code false}), or no check ({@code null}). + * @param mustExecutable Whether the file must be executable ({@code true}), not executable ({@code false}), or no check ({@code null}). + * @param allowEmpty If {@code true}, allows empty input to return {@code null}; otherwise, continues prompting. + * @return A {@link File} object satisfying all constraints, the {@code defaultValue}, or {@code null} (if allowed). */ public static File askFile(final String prompt, final File defaultValue, diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/Menu.java b/src/main/java/eu/svjatoslav/commons/cli_helper/Menu.java index ac68d82..930cf1e 100644 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/Menu.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/Menu.java @@ -25,8 +25,21 @@ import static java.lang.Math.min; */ public class Menu { + /** - * Presents an interactive menu; returns selection or null + * Displays an interactive menu for the user to select an option from a list using fuzzy matching and cursor navigation. + *

+ * This method requires the terminal to be in raw mode for proper operation. On Unix-like systems, it automatically + * sets the terminal to raw mode. This functionality may not work correctly in standard line-buffered terminals or IDE consoles. + *

+ *

+ * The user can navigate the list using up/down arrow keys, type to filter options via fuzzy matching (e.g., "abc" matches + * "aXbYc" but not "acb"), press Enter to select the current option, or Escape to cancel. + *

+ * @param prompt The prompt message to display above the menu. + * @param options The list of options to present to the user. + * @return The selected option string, or {@code null} if the user canceled with Escape. + * @throws IOException If there's an error reading from the terminal or restoring terminal settings. */ public static String askSelection(String prompt, List options) throws IOException { if (options == null || options.isEmpty()) { @@ -98,7 +111,9 @@ public class Menu { } /** - * Gets the current terminal settings as a string. + * Retrieves the current terminal settings using the {@code stty -g} command. + * @return A string representing the current terminal settings. + * @throws IOException If the command fails to execute or read the output. */ private static String getTerminalSettings() throws IOException { Process p = Runtime.getRuntime().exec(new String[]{"/bin/sh", "-c", "stty -g < /dev/tty"}); @@ -112,8 +127,9 @@ public class Menu { } /** - * Sets the terminal to raw mode with no echo. - */ + * Sets the terminal to raw mode with no echo. + * @throws IOException If the terminal cannot be set to raw mode. + */ private static void setTerminalToRaw() throws IOException { Process p = Runtime.getRuntime().exec(new String[]{"/bin/sh", "-c", "stty raw -echo < /dev/tty"}); try { @@ -124,7 +140,9 @@ public class Menu { } /** - * Restores the terminal settings. + * Restores the terminal to the specified settings. + * @param settings The terminal settings string to restore. + * @throws IOException If the terminal settings cannot be restored. */ private static void restoreTerminalSettings(String settings) throws IOException { if (settings != null) { @@ -138,11 +156,11 @@ public class Menu { } /** - * Filters options based on fuzzy matching. - * - * @param options the list of options to filter - * @param filter the filter string - * @return filtered list of options that match the fuzzy pattern + * Filters the given list of options using a fuzzy matching algorithm. + * Characters in the filter must appear in order in the option string (not necessarily consecutively), case-insensitive. + * @param options The list of options to filter. + * @param filter The filter string (case-insensitive). + * @return A new list containing only the options that match the fuzzy pattern. */ private static List filterOptions(List options, String filter) { if (filter == null || filter.isEmpty()) return new ArrayList<>(options); @@ -177,8 +195,14 @@ public class Menu { } /** - * Updates the display based on the current state. - * @return the total number of lines in the display + * Updates the terminal display to show the current menu state, including the prompt, filter string, and filtered options. + * Handles cursor positioning and clearing previous output to avoid flicker. + * @param prompt The prompt message to display at the top. + * @param filteredOptions The list of options currently matching the filter. + * @param selectedIndex The index of the currently selected option. + * @param filterString The current filter string typed by the user. + * @param lastTotalLines The total number of lines in the previous display, used for cursor positioning. + * @return The total number of lines in the current display (prompt line + menu lines). */ private static int updateDisplay(String prompt, List filteredOptions, int selectedIndex, String filterString, int lastTotalLines) { diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Option.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Option.java index eb33fa7..0d907ff 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Option.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Option.java @@ -91,10 +91,13 @@ public abstract class Option> { } /** - * Adds a parameter to this option, validating it against {@link #isValid(String)}. - * - * @param parameterString the parameter string to add - * @return {@code true} if the parameter was valid and added, otherwise {@code false} + * Adds a parameter to this option after validating it against the configured rules. + *

+ * If the option is configured for {@link ParameterCount#NONE}, adding any parameter will fail. + * If the option is configured for {@link ParameterCount#ONE}, only one parameter is allowed. + *

+ * @param parameterString The parameter string to add. + * @return {@code true} if the parameter is valid and added; otherwise {@code false}. */ public boolean addParameter(final String parameterString) { // Check if this option is supposed to have parameters at all @@ -137,10 +140,14 @@ public abstract class Option> { } /** - * Returns a help message that includes the aliases, whether the option is mandatory, - * the format, and a brief description. - * - * @return a descriptive help string + * Generates a formatted help string for this option, including: + *
    + *
  • Aliases (e.g., "-f", "--file")
    • + *
  • Mandatory status
    • + *
  • Parameter format description
    • + *
  • Brief description of the option's purpose
    • + *
+ * @return A string suitable for console output, describing the option. */ public String getHelp() { StringBuilder result = new StringBuilder(); @@ -203,10 +210,13 @@ public abstract class Option> { } /** - * Called when no more arguments can be added to this option, giving it a chance - * to verify correct usage (e.g., check if required parameters are missing). - * - * @return {@code true} if the usage so far is valid; otherwise {@code false}. + * Finalizes the option's parameters and checks for required constraints. + *

+ * For options that require parameters, this method verifies that the required number + * of parameters have been provided. If not, it prints an error message to System.out + * and returns {@code false}. + *

+ * @return {@code true} if the option's parameters are valid; otherwise {@code false}. */ public boolean noMoreArguments() { // If we expect at least one parameter but none were provided diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Parser.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Parser.java index 41c6b40..23a6333 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Parser.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Parser.java @@ -56,10 +56,17 @@ public class Parser { } /** - * Parses the provided command-line arguments, matching them to registered options and their parameters. - * - * @param args command-line arguments (usually from main(String[])) - * @return {@code true} if parsing succeeded without errors; otherwise {@code false}. + * Parses command-line arguments against registered options and their parameters. + *

+ * Processes arguments sequentially: + *

    + *
  • Recognizes option aliases to switch between options.
    • + *
  • Adds subsequent arguments as parameters to the current option.
    • + *
  • Checks mandatory options are present at the end.
    • + *
+ *

+ * @param args Command-line arguments. + * @return {@code true} if parsing succeeded (all mandatory options present and no errors); otherwise {@code false}. */ public boolean parse(final String[] args) { Option currentOption = null; @@ -129,7 +136,9 @@ public class Parser { } /** - * Prints all available options, their formats, and their descriptions. Usually called upon parse failure. + * Prints formatted help information for all registered options to the console. + * Each option's aliases, parameter requirements, and description are displayed. + * Typically called when parsing fails due to missing mandatory options or invalid arguments. */ public void showHelp() { System.out.println("Available command-line arguments:"); diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/DirectoryOption.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/DirectoryOption.java index 63c1714..7994b68 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/DirectoryOption.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/DirectoryOption.java @@ -70,10 +70,14 @@ public class DirectoryOption extends Option { } /** - * Checks whether the provided path is valid based on the {@link ExistenceType}. - * - * @param value the directory path to validate - * @return {@code true} if valid, otherwise {@code false} + * Validates the directory path against the configured existence requirements. + *
    + *
  • {@link ExistenceType#MUST_EXIST}: path must exist and be a directory.
    • + *
  • {@link ExistenceType#MUST_NOT_EXIST}: path must not exist.
    • + *
  • {@link ExistenceType#DOES_NOT_MATTER}: path can exist (as directory or not), but if it exists and is a file, it's invalid.
    • + *
+ * @param value The directory path to validate. + * @return {@code true} if the path meets the requirements; otherwise {@code false}. */ @Override public boolean isValid(final String value) { diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/FileOptions.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/FileOptions.java index 2d0e8ab..435377b 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/FileOptions.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/FileOptions.java @@ -43,9 +43,8 @@ public class FileOptions extends Option, FileOptions> { } /** - * Returns the list of file paths as {@link File} objects. - * - * @return a list of {@link File} objects corresponding to user input. + * Converts all parameters to {@link File} objects and returns them as a list. + * @return A list of {@link File} objects corresponding to the parameters. */ @Override public List getValue() { diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/StringOption.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/StringOption.java index fa7f102..8cf2eae 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/StringOption.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/StringOption.java @@ -49,9 +49,13 @@ public class StringOption extends Option { } /** - * Returns the string parameter or the default value if none was provided. - * - * @throws RuntimeException if multiple parameters were provided. + * Returns the string parameter value based on the following rules: + *
    + *
  • If exactly one parameter is provided, returns that parameter.
    • + *
  • If no parameters are provided and a default value exists, returns the default.
    • + *
  • Otherwise, throws a {@link RuntimeException}.
    • + *
+ * @throws RuntimeException if there are zero parameters with no default or more than one parameter. */ @Override public String getValue() { -- 2.20.1