Add support for flag parameters in descriptions

Fixes #55

Change one of standard command samples, to see effect on it

spring-shell2-core/src/main/java/org/springframework/shell2/ParameterDescription.java

@@ -47,10 +47,17 @@ public class ParameterDescription {
 	private String formal;
 
 	/**
-	 * A string representation of the default value for the parameter, if any.
+	 * A string representation of the default value (if the option is left out entirely) for the parameter, if any.
 	 */
 	private Optional<String> defaultValue = Optional.empty();
 
+	/**
+	 * A string representation of the default value for this parameter, if it can be used as a mere flag (<em>e.g.</em>
+	 * {@literal --force} without a value, being an equivalent to {@literal --force true}).
+	 * <p>{@literal Optional.empty()} (the default) means that this parameter cannot be used as a flag.</p>
+	 */
+	private Optional<String> defaultValueWhenFlag = Optional.empty();
+
 	/**
 	 * The list of 'keys' that can be used to specify this parameter, if any.
 	 */
@@ -99,6 +106,11 @@ public class ParameterDescription {
 		return this;
 	}
 
+	public ParameterDescription whenFlag(String defaultValue) {
+		this.defaultValueWhenFlag = Optional.of(defaultValue);
+		return this;
+	}
+
 	public ParameterDescription keys(List<String> keys) {
 		this.keys = keys;
 		return this;
@@ -109,6 +121,7 @@ public class ParameterDescription {
 		return this;
 	}
 
+
 	public String type() {
 		return type;
 	}
@@ -121,6 +134,10 @@ public class ParameterDescription {
 		return help;
 	}
 
+	public Optional<String> defaultValueWhenFlag() {
+		return defaultValueWhenFlag;
+	}
+
 	public ParameterDescription formal(String formal) {
 		this.formal = formal;
 		return this;

spring-shell2-core/src/main/java/org/springframework/shell2/commands/Help.java

@@ -105,25 +105,32 @@ public class Help {
 		for (ParameterDescription description : parameterDescriptions) {
 
 			if (description.defaultValue().isPresent()) {
-				result.append("[");
+				result.append("["); // Whole parameter is optional, as there is a default value (1)
 			}
-			if(!description.keys().isEmpty()) {
+			List<String> keys = description.keys();
+			if(!keys.isEmpty()) {
 				if (!description.mandatoryKey()) {
-					result.append("[");
+					result.append("["); // Specifying a key is optional (ie positional params). (2)
 				}
-				result.append(description.keys().iterator().next(), AttributedStyle.BOLD);
+				result.append(first(keys), AttributedStyle.BOLD);
 				if (!description.mandatoryKey()) {
-					result.append("]");
+					result.append("]"); // (close 2)
 				}
 				if (!description.formal().isEmpty()) {
 					result.append(" ");
 				}
 			}
-			appendUnderlinedFormal(result, description);
-			if (description.defaultValue().isPresent()) {
-				result.append("]");
+			if (description.defaultValueWhenFlag().isPresent()) {
+				result.append("["); // Parameter can be used as a toggle flag (3)
 			}
-			result.append("  ");
+			appendUnderlinedFormal(result, description);
+			if (description.defaultValueWhenFlag().isPresent()) {
+				result.append("]"); // (close 3)
+			}
+			if (description.defaultValue().isPresent()) {
+				result.append("]"); // (close 1)
+			}
+			result.append("  "); // two spaces between each param for better legibility
 		}
 		result.append("\n\n");
 
@@ -137,7 +144,9 @@ public class Help {
 				if (!description.keys().isEmpty()) {
 					result.append("  ");
 				}
+				description.defaultValueWhenFlag().ifPresent(f -> result.append('['));
 				appendUnderlinedFormal(result, description);
+				description.defaultValueWhenFlag().ifPresent(f -> result.append(']'));
 				result.append("\n\t");
 			}
 			else if (description.keys().size() > 1) {
@@ -145,12 +154,27 @@ public class Help {
 			}
 			result.append("\t");
 			result.append(description.help());
+			// Optional parameter
 			if (description.defaultValue().isPresent()) {
 				result
 						.append("  [Optional, default = ", AttributedStyle.BOLD)
-						.append(description.defaultValue().get(), AttributedStyle.BOLD.italic())
-						.append("]", AttributedStyle.BOLD);
-			} else {
+						.append(description.defaultValue().get(), AttributedStyle.BOLD.italic());
+				description.defaultValueWhenFlag().ifPresent(
+					s -> result.append(", or ", AttributedStyle.BOLD)
+						.append(s, AttributedStyle.BOLD.italic())
+					.append(" if used as a flag", AttributedStyle.BOLD)
+				);
+
+				result.append("]", AttributedStyle.BOLD);
+			} // Mandatory parameter, but with a default when used as a flag
+			else if (description.defaultValueWhenFlag().isPresent()) {
+				result
+					.append("  [Mandatory, default = ", AttributedStyle.BOLD)
+					.append(description.defaultValueWhenFlag().get(), AttributedStyle.BOLD.italic())
+					.append(" when used as a flag]", AttributedStyle.BOLD)
+				;
+			} // true mandatory parameter
+			else {
 				result.append("  [Mandatory]", AttributedStyle.BOLD);
 			}
 			result.append("\n\n");
@@ -159,7 +183,7 @@ public class Help {
 		// ALSO KNOWN AS
 		Set<String> aliases = shell.listCommands().entrySet().stream()
 				.filter(e -> e.getValue().equals(methodTarget))
-				.map(e -> e.getKey())
+				.map(Map.Entry::getKey)
 				.filter(c -> !command.equals(c))
 				.collect(toCollection(TreeSet::new));
 
@@ -174,6 +198,10 @@ public class Help {
 		return result;
 	}
 
+	private String first(List<String> keys) {
+		return keys.iterator().next();
+	}
+
 	private CharSequence listCommands() {
 		Map<String, Set<String>> groupedByMethodTarget = shell.listCommands().entrySet().stream()
 				.collect(Collectors.groupingBy(e -> e.getValue().getHelp(), // Use help() as the grouping key
@@ -195,7 +223,7 @@ public class Help {
 	}
 
 	private Comparator<Map.Entry<String, Set<String>>> sortByFirstElement() {
-		return (e1, e2) -> e1.getValue().iterator().next().compareTo(e2.getValue().iterator().next());
+		return Comparator.comparing(e -> e.getValue().iterator().next());
 	}
 
 	private void appendUnderlinedFormal(AttributedStringBuilder result, ParameterDescription description) {