Version 1.0.0 - First stable release

Documentation now available!

Check out the complete documentation at https://darvil82.github.io/lanat-docs

Features

• Argument types

  • Add ActionArgumentType. This is the old BooleanArgumentType.
  • BooleanArgumentType can now receive values as well. Those being true, false, yes, no, etc.
  • TupleArgumentType is no longer abstract and does not take a default value in its constructor now. Instead takes another argument type instance. The tuple argument type can now work with any argument type passed to it.
  • Change forEachArgValue() to getArgValuesStream().
  • Add getRequiredUsageCount() to Parseable.
  • Add default implementation to getRequiredUsageCount and getRequiredArgValueCount in Parseable.
  • TryParseArgumentType will now try to infer the type first if possible.
  • Make Parseable a functional interface.
  • Add SimpleArgumentType. Allows to create argument types with a builder pattern. Implements the aforementioned Builder.
  • Add OptListArgumentType. Similar to EnumArgumentType, but accepts a list of all possible strings the user can introduce.
  • Add SingleValueListArgumentType abstract class. EnumArgumentType and OptListArgumentType both inherit this.
  • Add constructor to ArgumentType to pass a Parseable to check restrictions on.
  • Add unregisterSubType() to ArgumentType.
  • Add unregister to ArgumentTypeInfer.
  • Add ArgumentTypeError.
  • Argument types now throw ArgumentTypeError instead of CustomErrorImpl.

• AfterParseOptions

  • Actions are now supplied by using the withActions() method, which accepts a callback defining the actions chain.
  • Actions are now run when a terminating method is called. These are either getResult() or into(). This ensures other callbacks defined are invoked at the correct time.
  • The default actions chain is now DEFAULT_ACTIONS.

    public static final Consumer<@NotNull AfterParseActions> DEFAULT_ACTIONS = a -> a
        .printHelpIfNoInput()
        .exitIfNoInput()
        .printErrors()
        .exitIfErrors();

  • Add hasReceivedInput() to check if the program received any input at all.

• Arguments

  • Add visible property. This allows to hide this argument from the help message. Use the setVisible method. This property has been added to ArgumentBuilder and the Argument.Define annotation as well.
  • Remove Argument.createOfBoolType() in favor of new Argument.createOfActionType().
  • Arguments are now represented in help with a single prefix.
  • Positional arguments will now be the first to appear in the help synopsis representation.
  • Improve how arguments appear in help descriptions. Multiple names are now shown in a less confusing manner.
  • Add isOrphan(). Returns true if this argument doesn't belong to any command or group.
  • Add removePrefix() static method.
  • When specifying the argument type upon argument creation, a Builder<ArgumentType> may also be specified instead.

• Commands

  • Add int parameter to addHelpArgument() and addVersionArgument() to specify the exit code upon quitting.
  • Add onUsed callback. Can be set with setOnUsedCallback(). This callback is functionally equivalent to CommandTemplate#onUsed.
  • Command#getParseResult will return cached results if called multiple times.
  • Templates
    • Greatly improved error messages when creating arguments from command template fields.
    • Groups can now be defined in command templates by setting the group value in the Argument.Define annotation. Multiple argument fields defined with the same group value will be added to a group with that name.
    • Add argWithType helper method to CommandBuildHelper to remove the need to specify type parameters while setting the type.
    • Add CommandTemplate.Default.WithVerbose, which includes a verbose counter argument.
    • Add error to make it clear the user must manually provide the argument type when using Optional in the command template field.
    • onUsed now received the ParseResult instance as a parameter.

• Misc

  • Now supports the NO-COLOR environment variable.
  • com.darvil:utils and com.darvil:terminal-text-formatter are now both API dependencies, thus the user will no longer have to manually install them.
  • Add CLInput#fromFile and CLInput#fromStandardInput.
  • Add ArgumentParser#parseFromInto overload that takes String[] for ease of use.
  • Argument group help descriptions now always show arguments even if these don't have any description set. Applies to nested groups.
  • Greatly improve error messages when there is a failure when inferring types.
  • Parsing a help description tag like <tag=> will now be considered invalid syntax.
  • Add Builder<T> interface. Custom builders may be made implementing this interface.
    • ArgumentBuilder now implements Builder.
  • ArgumentAdder#addArgument now accepts a generic Builder instance too.
  • Improve toString representation of arguments and commands and groups.
  • Add setNames method to MultipleNamesAndDescription. Implementors now only implement this method. addNames has a default implementation now.
  • Add unregister method to Tag.
  • Negative margin and indent values are no longer silently capped to 0 when negative. Now throws.
  • Improve ColorTag syntax. Now accepts true color values with the color_name|#rrggbb|r,g,b syntax.
  • Add DefaultValueTag for arguments.
  • Errors may now choose to remove other errors by overriding the shouldRemoveOther() method in Error.
    • A RequiredArgumentNotUsedError will no longer appear if an IncorrectValueNumberError is present for the same argument.
    • An UnmatchedTokenError will no longer appear if a SimilarArgumentError is present for the same token index.
  • Add representationColor to ArgumentBuilder.
  • When mentioning elements in a a command (such as arguments), errors will now use their actual help representation instead of just the name.
  • Add SimpleError.
  • Commands may now contain Error<?> instead of being restricted to CustomError (now removed).

Fixes

• Fix help message not appearing if no input was provided. (Default actions)
• Fix index out of bounds exception being thrown when the last character in the input is a backslash.
• Optimized initialization of many internal lists that most of the time aren't filled that much.
• Fix description of commands always showing up in the help message.
• Fix crash when attempting to add arguments to a group that has already been added to a command.
• Fix argument group descriptions showing up if no arguments inside it have descriptions.
• Fix crash in some cases when registering a group.
• Fix default value of arguments not properly being used in some cases.
• Fix KeyValuesArgumentType adding null values when keys fail to parse.
• ArgumentTypeInfer can no longer be instantiated.
• Fix incorrect report for the SimilarArgument parse error.
• Fix an error when attempting to close a string inside a tuple.
• Optimize Argument#checkMatch to not perform many useless string concatenations.
• Fix Tag#register method allowing to replace previous entries.
• Fix DescriptionParser not properly parsing backslashes if no tags are present.
• Fix DescriptionParser throwing IllegalArgumentException instead of MalformedTagException in a case.
• Fix DescriptionParser not throwing a MalformedTagException if a tag is blank.
• Fix argument descriptions showing up as "null" if none had descriptions set.
• Tag name and value not being trimmed correctly.
• Fix being possible to use arguments when a unique argument was used. Added new parse error for this.
• Fix LinkTag giving incorrect representations for groups.
• Fix terminal sequences not resetting properly on descriptions.
• Fix HelpFormatter#setIndentSize, getIndentSize and all its usages not being static.
• Fix CommandTemplate#afterInit only accepting equal types, but not assignable to Command. (Can now accept ArgumentParser)
• Fix program details layout item missing an indentation in the help message.
• ArgumentTypeInfer allowing to set infer for Optional.
• Fix help message printing extra line feed.
• CLInput#fromSystemProperty not working properly when no input is passed in.
• Argument types allowing to throw errors before parsing started, potentially crashing.

Refactors

• Move AfterParseOptions to its own class.
• Rename Argument#argType to Argument#type. Applies to ArgumentBuilder and Argument.Define as well.
• Remove Argument.create() overloads involving char.
• Commands no longer have the ability to define the tuple char to use. This is now globally defined in TupleChar#current.
• Move CallbacksInvocationOption into Command.
• Change all \n usages to System#lineSeparator() to improve compatibility.
• PrefixChar is now an enum. It is no longer allowed to use any character for a prefix. The Argument.Define annotation now uses this enum for the prefixChar value.
• The default prefix may now be set with PrefixChar.setDefaultPrefix().
• Remove duplicated code in ArgumentGroupRepr.
• Reorganized many files and code.
• Argument groups are now added differently. The group hierarchy is linked right before parsing now.
• Remove MultipleNumbersArgumentType and MultipleStringsArgumentType. No longer needed with the new TupleArgumentType.
• Rename "license" to "program details" (help message).
• Rename "args" to "values" in argument types.
• Remove unnecessary anonymous subclassing in some places.
• Remove ArgumentType#setValue().
• Rename ErrorsContainer, ErrorsCollector and ErrorsContainerImpl to singular Error. (eg, ErrorContainer)
• Rename CommandTemplate#onValuesReceived to CommandTemplate#onUsed.
• Changed naming convention of setter methods in ArgumentBuilder.
• Rename DescriptionFormatter to DescriptionParser.
• lanat.parsing.errors.handlers is no longer exported.
• ArgumentBuilder boolean setters now accept values and other setters accept null values.
• Rename LayoutItem formatting methods.
• Replace all UtlMisc#nullOrElseGet() usages with Optionals. (Removed UtlMisc#nullOrElseGet())
• Replace all UtlString#allCharsMatch() with String#chars().
• HelpFormatter#indentSize is no longer an instance property.
• LayoutItem#indentCount, HelpFormatter#lineWrapMax and HelpFormatter#indentSize are now stored as an int.
• Remove all single/double character color value options in ColorTag. Now the whole name must be provided to avoid confusion. (except gray/grey)
• Remove single character value options in FormatTag for dim, blink, reverse and hidden.
• Supplying no values in FormatTag and ColorTag will now throw a MalformedTagException.
• Refactor some code to use Optional instead of regular null checks.
• Remove unnecessary Tokenizer#inputChars.
• ArgumentTypeInfer#register only accepts a single class now. Same with unregister. Added ArgumentTypeInfer#registerWithPrimitive and ArgumentTypeInfer#unregisterWithPrimitive.
• Rename getRequiredUsageCount to getUsageCountBounds and getRequiredArgValueCount to getValueCountBounds in ArgumentType.
• Rename PrefixChar to just Prefix.
• Slight method refactors in HelpFormatter and LayoutItem.
• Remove ParseResult#get(String). The only method is now the String... overload.
• Move addHelp and addVersion methods in Command to CommandTemplate.Default.

Misc

• Bump utils and terminal-text-formatter to latest.
• Update README.md to reflect all these changes.
• Remove ExampleTest.
• Fix logo.
• Fix plenty of typos in javadocs.
• Add more tests.
• Properly set nullability annotations.