diff --git a/README.md b/README.md index 0e104467..1d470a1a 100644 --- a/README.md +++ b/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.") diff --git a/src/main/java/lanat/Argument.java b/src/main/java/lanat/Argument.java index 0a699f78..ded72661 100644 --- a/src/main/java/lanat/Argument.java +++ b/src/main/java/lanat/Argument.java @@ -84,7 +84,7 @@ public class Argument, 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 createOfBoolType(@No /** - * Marks the argument as obligatory. This means that this argument should always be used by the user. + * Marks the argument as required. This means that this argument should always 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. *

* Order: - * Allows Unique > Positional > Obligatory > Optional. + * Allows Unique > Positional > Required > Optional. *

* * @param first the first argument to compare @@ -618,7 +618,7 @@ public static int compareByPriority(@NotNull Argument first, @NotNull Argu return new MultiComparator>() .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) { *

* Note 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. *

* diff --git a/src/main/java/lanat/ArgumentBuilder.java b/src/main/java/lanat/ArgumentBuilder.java index fccc13e2..09ee1f15 100644 --- a/src/main/java/lanat/ArgumentBuilder.java +++ b/src/main/java/lanat/ArgumentBuilder.java @@ -19,7 +19,7 @@ public class ArgumentBuilder, 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 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 withDescription(@NotNull String description return this; } - /** @see Argument#setObligatory(boolean) */ - public ArgumentBuilder obligatory() { - this.obligatory = true; + /** @see Argument#setRequired(boolean) */ + public ArgumentBuilder required() { + this.required = true; return this; } @@ -229,7 +229,7 @@ public Argument 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); diff --git a/src/main/java/lanat/CommandTemplate.java b/src/main/java/lanat/CommandTemplate.java index 07c33f7b..52f18967 100644 --- a/src/main/java/lanat/CommandTemplate.java +++ b/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; * } * } diff --git a/src/main/java/lanat/helpRepresentation/ArgumentRepr.java b/src/main/java/lanat/helpRepresentation/ArgumentRepr.java index 9afef39e..a8bd1325 100644 --- a/src/main/java/lanat/helpRepresentation/ArgumentRepr.java +++ b/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); } diff --git a/src/main/java/lanat/parsing/errors/ParseError.java b/src/main/java/lanat/parsing/errors/ParseError.java index 3222031a..77f756cc 100644 --- a/src/main/java/lanat/parsing/errors/ParseError.java +++ b/src/main/java/lanat/parsing/errors/ParseError.java @@ -19,7 +19,7 @@ public class ParseError extends ParseStateErrorBase { 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); } diff --git a/src/test/java/lanat/test/UnitTests.java b/src/test/java/lanat/test/UnitTests.java index 34caf87b..4f4c308c 100644 --- a/src/test/java/lanat/test/UnitTests.java +++ b/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()); }}); }}); diff --git a/src/test/java/lanat/test/units/TestTerminalOutput.java b/src/test/java/lanat/test/units/TestTerminalOutput.java index efc3ec7f..5e3dc8df 100644 --- a/src/test/java/lanat/test/units/TestTerminalOutput.java +++ b/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