refactor: rename obligatory to required (suggestion by @fadeoffical)

README.md

@@ -9,7 +9,7 @@ Here is an example of a simple argument parser definition.
 ```java
 @Command.Define
 class MyProgram {
-	@Argument.Define(obligatory = true, positional = true, description = "The name of the user.")
+	@Argument.Define(required = true, positional = true, description = "The name of the user.")
 	public String name;
 
 	@Argument.Define(argType = StringArgumentType.class, description = "The surname of the user.")

src/main/java/lanat/Argument.java

@@ -84,7 +84,7 @@ public class Argument<Type extends ArgumentType<TInner>, TInner>
 	private PrefixChar prefixChar = PrefixChar.defaultPrefix;
 	private final @NotNull List<@NotNull String> names = new ArrayList<>();
 	private @Nullable String description;
-	private boolean obligatory = false,
+	private boolean required = false,
 		positional = false,
 		allowUnique = false;
 
@@ -227,19 +227,19 @@ public static ArgumentBuilder<BooleanArgumentType, Boolean> createOfBoolType(@No
 
 
 	/**
-	 * Marks the argument as obligatory. This means that this argument should <b>always</b> be used by the user.
+	 * Marks the argument as required. This means that this argument should <b>always</b> be used by the user.
 	 */
-	public void setObligatory(boolean obligatory) {
-		this.obligatory = obligatory;
+	public void setRequired(boolean required) {
+		this.required = required;
 	}
 
 	/**
-	 * Returns {@code true} if this argument is obligatory.
-	 * @return {@code true} if this argument is obligatory.
-	 * @see #setObligatory(boolean)
+	 * Returns {@code true} if this argument is required.
+	 * @return {@code true} if this argument is required.
+	 * @see #setRequired(boolean)
 	 */
-	public boolean isObligatory() {
-		return this.obligatory;
+	public boolean isRequired() {
+		return this.required;
 	}
 
 	/**
@@ -288,17 +288,17 @@ public PrefixChar getPrefix() {
 	}
 
 	/**
-	 * Specifies that this argument has priority over other arguments, even if they are obligatory. This means that if
-	 * an argument in a command is set as obligatory, but one argument with {@link #allowUnique} was used, then the
-	 * unused obligatory argument will not throw an error.
+	 * Specifies that this argument has priority over other arguments, even if they are required. This means that if
+	 * an argument in a command is set as required, but one argument with {@link #allowUnique} was used, then the
+	 * unused required argument will not throw an error.
 	 */
 	public void setAllowUnique(boolean allowUnique) {
 		this.allowUnique = allowUnique;
 	}
 
 	/**
-	 * Returns {@code true} if this argument has priority over other arguments, even if they are obligatory.
-	 * @return {@code true} if this argument has priority over other arguments, even if they are obligatory.
+	 * Returns {@code true} if this argument has priority over other arguments, even if they are required.
+	 * @return {@code true} if this argument has priority over other arguments, even if they are required.
 	 * @see #setAllowUnique(boolean)
 	 */
 	public boolean isUniqueAllowed() {
@@ -498,9 +498,9 @@ public void parseValues(short tokenIndex, @NotNull String... values) {
 	 */
 	private boolean finishParsing$checkUsageCount() {
 		if (this.getUsageCount() == 0) {
-			if (this.obligatory && !this.parentCommand.uniqueArgumentReceivedValue()) {
+			if (this.required && !this.parentCommand.uniqueArgumentReceivedValue()) {
 				this.parentCommand.getParser().addError(
-					ParseError.ParseErrorType.OBLIGATORY_ARGUMENT_NOT_USED, this, 0
+					ParseError.ParseErrorType.REQUIRED_ARGUMENT_NOT_USED, this, 0
 				);
 				return false;
 			}
@@ -606,7 +606,7 @@ public boolean equals(@NotNull Object obj) {
 	 * Compares two arguments by the synopsis view priority order.
 	 * <p>
 	 * <b>Order:</b>
-	 * Allows Unique > Positional > Obligatory > Optional.
+	 * Allows Unique > Positional > Required > Optional.
 	 * </p>
 	 *
 	 * @param first the first argument to compare
@@ -618,7 +618,7 @@ public static int compareByPriority(@NotNull Argument<?, ?> first, @NotNull Argu
 		return new MultiComparator<Argument<?, ?>>()
 			.addPredicate(Argument::isUniqueAllowed, 2)
 			.addPredicate(Argument::isPositional, 1)
-			.addPredicate(Argument::isObligatory)
+			.addPredicate(Argument::isRequired)
 			.compare(first, second);
 	}
 
@@ -642,9 +642,9 @@ public void resetState() {
 
 	@Override
 	public @NotNull String toString() {
-		return "Argument<%s>[names=%s, prefix='%c', obligatory=%b, positional=%b, allowUnique=%b, defaultValue=%s]"
+		return "Argument<%s>[names=%s, prefix='%c', required=%b, positional=%b, allowUnique=%b, defaultValue=%s]"
 			.formatted(
-				this.argType.getClass().getSimpleName(), this.names, this.getPrefix().character, this.obligatory,
+				this.argType.getClass().getSimpleName(), this.names, this.getPrefix().character, this.required,
 				this.positional, this.allowUnique, this.defaultValue
 			);
 	}
@@ -671,8 +671,8 @@ public void resetState() {
 		 * */
 		char prefix() default '-';
 
-		/** @see Argument#setObligatory(boolean) */
-		boolean obligatory() default false;
+		/** @see Argument#setRequired(boolean) */
+		boolean required() default false;
 
 		/** @see Argument#setPositional(boolean) */
 		boolean positional() default false;
@@ -730,7 +730,7 @@ public void setMinimumExitErrorLevel(@NotNull ErrorLevel level) {
 	 * <p>
 	 * <strong>Note</strong> that this callback is only called if the error was dispatched by this argument's type.
 	 * That
-	 * is, if the argument, for example, is obligatory, and the user does not specify a value, an error will be
+	 * is, if the argument, for example, is required, and the user does not specify a value, an error will be
 	 * thrown, but this callback will not be called, as the error was not dispatched by this argument's type.
 	 * </p>
 	 *

src/main/java/lanat/ArgumentBuilder.java

@@ -19,7 +19,7 @@ public class ArgumentBuilder<Type extends ArgumentType<TInner>, TInner> {
 	private @NotNull String @Nullable [] names;
 	private @Nullable String description;
 	private @Nullable Type argType;
-	private boolean obligatory = false,
+	private boolean required = false,
 		positional = false,
 		allowUnique = false;
 	private @Nullable TInner defaultValue;
@@ -75,7 +75,7 @@ ArgumentBuilder<Type, TInner> fromField(@NotNull Field field) {
 
 		argumentBuilder.withPrefix(Argument.PrefixChar.fromCharUnsafe(annotation.prefix()));
 		if (!annotation.description().isEmpty()) argumentBuilder.withDescription(annotation.description());
-		if (annotation.obligatory()) argumentBuilder.obligatory();
+		if (annotation.required()) argumentBuilder.required();
 		if (annotation.positional()) argumentBuilder.positional();
 		if (annotation.allowsUnique()) argumentBuilder.allowsUnique();
 
@@ -143,9 +143,9 @@ public ArgumentBuilder<Type, TInner> withDescription(@NotNull String description
 		return this;
 	}
 
-	/** @see Argument#setObligatory(boolean) */
-	public ArgumentBuilder<Type, TInner> obligatory() {
-		this.obligatory = true;
+	/** @see Argument#setRequired(boolean) */
+	public ArgumentBuilder<Type, TInner> required() {
+		this.required = true;
 		return this;
 	}
 
@@ -229,7 +229,7 @@ public Argument<Type, TInner> build() {
 
 		return new Argument<>(this.argType, this.names) {{
 			this.setDescription(ArgumentBuilder.this.description);
-			this.setObligatory(ArgumentBuilder.this.obligatory);
+			this.setRequired(ArgumentBuilder.this.required);
 			this.setPositional(ArgumentBuilder.this.positional);
 			this.setAllowUnique(ArgumentBuilder.this.allowUnique);
 			this.setDefaultValue(ArgumentBuilder.this.defaultValue);

src/main/java/lanat/CommandTemplate.java

@@ -61,7 +61,7 @@
  *   @Argument.Define(names = {"name", "n"}, argType = StringArgumentType.class)
  *   public String name;
  *
- *   @Argument.Define(argType = IntegerArgumentType.class, obligatory = true)
+ *   @Argument.Define(argType = IntegerArgumentType.class, required = true)
  *   public Integer number;
  * }
  * }</pre>

src/main/java/lanat/helpRepresentation/ArgumentRepr.java

@@ -35,7 +35,7 @@ private ArgumentRepr() {}
 		final String names = String.join("/", arg.getNames());
 		final char argPrefix = arg.getPrefix().character;
 
-		if (arg.isObligatory()) {
+		if (arg.isRequired()) {
 			outText.addFormat(FormatOption.BOLD, FormatOption.UNDERLINE);
 		}
 

src/main/java/lanat/parsing/errors/ParseError.java

@@ -19,7 +19,7 @@ public class ParseError extends ParseStateErrorBase<ParseError.ParseErrorType> {
 	private ArgumentGroup argumentGroup;
 
 	public enum ParseErrorType implements ErrorLevelProvider {
-		OBLIGATORY_ARGUMENT_NOT_USED,
+		REQUIRED_ARGUMENT_NOT_USED,
 		UNMATCHED_TOKEN(ErrorLevel.WARNING),
 		ARG_INCORRECT_VALUE_NUMBER,
 		ARG_INCORRECT_USAGES_COUNT,
@@ -56,13 +56,13 @@ public void setArgumentGroup(@NotNull ArgumentGroup argumentGroup) {
 
 		for (final var err : errors) {
 			/* if we are going to show an error about an argument being incorrectly used, and that argument is defined
-			 * as obligatory, we don't need to show the obligatory error since its obvious that the user knows that
-			 * the argument is obligatory */
+			 * as required, we don't need to show the required error since its obvious that the user knows that
+			 * the argument is required */
 			if (err.errorType == ParseErrorType.ARG_INCORRECT_VALUE_NUMBER) {
 				newList.removeIf(e ->
 					e.argument != null
 						&& e.argument.equals(err.argument)
-						&& e.errorType == ParseErrorType.OBLIGATORY_ARGUMENT_NOT_USED
+						&& e.errorType == ParseErrorType.REQUIRED_ARGUMENT_NOT_USED
 				);
 			}
 		}
@@ -98,16 +98,16 @@ protected void handleIncorrectUsagesCount() {
 			.displayTokens(this.tokenIndex + 1, this.valueCount, this.valueCount == 0);
 	}
 
-	@Handler("OBLIGATORY_ARGUMENT_NOT_USED")
-	protected void handleObligatoryArgumentNotUsed() {
+	@Handler("REQUIRED_ARGUMENT_NOT_USED")
+	protected void handleRequiredArgumentNotUsed() {
 		assert this.argument != null;
 		final var argCmd = this.argument.getParentCommand();
 
 		this.fmt()
 			.setContent(
 				argCmd instanceof ArgumentParser
-					? "Obligatory argument '%s' not used.".formatted(this.argument.getName())
-					: "Obligatory argument '%s' for command '%s' not used.".formatted(this.argument.getName(), argCmd.getName())
+					? "Required argument '%s' not used.".formatted(this.argument.getName())
+					: "Required argument '%s' for command '%s' not used.".formatted(this.argument.getName(), argCmd.getName())
 			)
 			.displayTokens(this.tokenIndex + 1);
 	}

src/test/java/lanat/test/UnitTests.java

@@ -58,7 +58,7 @@ protected TestingParser setParser() {
 			this.setErrorCode(0b0100);
 			this.addArgument(Argument.create(new StringJoiner(), "what")
 				.positional()
-				.obligatory()
+				.required()
 			);
 			this.addArgument(Argument.create(new RestrictedDoubleAdder(), "double-adder"));
 			this.addArgument(Argument.create(new StringArgumentType(), "a"));
@@ -71,7 +71,7 @@ protected TestingParser setParser() {
 				this.addCommand(new Command("another") {{
 					this.setErrorCode(0b0001);
 					this.addArgument(Argument.create(new StringJoiner(), "ball"));
-					this.addArgument(Argument.create(new IntegerArgumentType(), "number").positional().obligatory());
+					this.addArgument(Argument.create(new IntegerArgumentType(), "number").positional().required());
 				}});
 			}});
 

src/test/java/lanat/test/units/TestTerminalOutput.java

@@ -21,21 +21,21 @@ private void assertErrorOutput(String args, String expected) {
 	}
 
 	@Test
-	@DisplayName("Arrow points to the root command name on first obligatory argument missing")
-	public void testFirstObligatoryArgument() {
+	@DisplayName("Arrow points to the root command name on first required argument missing")
+	public void testFirstRequiredArgument() {
 		this.assertErrorOutput("subCommand", """
 			ERROR
 			Testing <- subCommand
-			Obligatory argument 'what' not used.""");
+			Required argument 'what' not used.""");
 	}
 
 	@Test
-	@DisplayName("Arrow points to the last token on last obligatory argument missing")
-	public void testLastObligatoryArgument() {
+	@DisplayName("Arrow points to the last token on last required argument missing")
+	public void testLastRequiredArgument() {
 		this.assertErrorOutput("foo subCommand another", """
 			ERROR
 			Testing foo subCommand another <-
-			Obligatory argument 'number' for command 'another' not used.""");
+			Required argument 'number' for command 'another' not used.""");
 	}
 
 	@Test