Release Notes

A number of new features have been added, and there are a couple of fixes.

Changes

New Features

• #131 Added mechanism to enable improvements without breaking existing code.
• #126 Added a flag that also adds the argument values under the argument name to the result. This way the argument name can be used as the key without having to convert dashes to underscores.
• #130 Added option to add additional paragraph to mutual exclusive groups indicating only 1 argument of the group can be given.

Artifact and Build

• #103 Switched to Java 8. Merged the Java 7 extensions (argparse4j-java7) into the main JAR. If serious issues with the Java 6 version are reported, they will still be resolved.
• #123 Added module information to the main JAR for Java Module System compatibility.
• #125 Changed to only have to have JDK 9 (or higher) for building.

Fixes

• #115 Fixed how the or operator is handled for file verifications.
• #118 Fixed path of Sphinx sources in build script.
• #122 Documentation fix.
• #117 New and improved Russian translations, and localization bug fixes.

Release Note

This release fixes the missing argparse4j-root and argparse4j-extensions on maven repository.

Release Note

New features have been added, and things have been improved on a lot of fronts. See below.

The Maven build has been modified to allow for extension modules. All plug-ins have been upgraded too. CI builds are running on Travis CI now.

Multiple differently-configured parsers can now be used at the same time without interfering with each other. Client code that adds arguments to an argument container can be made reusable.

Optional arguments are now called named arguments. Arguments not given by the user can be suppressed in the resulting namespace. Case- insensitive enum argument types have been improved and extended.

The exit code will no longer indicate an error if the user requests help. The help text can be written to a destination other than standard output. Help can be suppressed for arguments and sub parsers.

Parsers can be configured to use a locale other than the default. Dutch and Russian translations have been added. CJK character widths have been updated.

Java 7 and Hadoop support has been added using extension modules. Both introduce a new argument type.

If you, or a project you use, implement "ArgumentParser" or "Subparser", you may run into run time issues when you upgrade.

Changes

Infrastructure

• The project has been restructured to allow for extension modules. Extension modules can add support for newer JDKs and external APIs without introducing JDK requirements or dependencies in the main module.

• The Maven plug-ins have been upgraded to latest versions.

• A CI build is now running for all commits on Travis CI. The build detects the use of classes of SDKs newer than the one we support. See: https://travis-ci.org/tatsuhiro-t/argparse4j

• Paths of IntelliJ IDEA have been added to the Git ignore list.

Parsers

• A new way to create parsers was introduced to allow for multiple, simultaneously-used parser instances with different configurations without interfering with each other. See "ArgumentParsers.newFor(String)".

• Arguments can be added to "ArgumentGroup", "MutuallyExclusiveArgumentGroup" and "ArgumentParser". Interface "ArgumentContainer" was introduced to allow code adding arguments to one of these to be reused for all of them.

Arguments

• Optional arguments (which could be configured to be required) have been renamed to "named arguments".

• Added (optional) suppression of key with value "null" in the namespace for arguments not present on the command line. See "Argument.setDefault(FeatureControl)".

• Case-insensitive enum matching has been fixed. It now uses the root locale for deterministic conversion of characters to lower case. You have to switch to "CaseInsensitiveEnumNameArgumentType" to make use of the improved implementation. "CaseInsensitiveEnumArgumentType" behaves like before, but its constructor has been deprecated. See "Arguments.caseInsensitiveEnumType(Class<T>)".

• A variant of case-insensitive enum matching has been added that uses "toString()" instead of "name()" for the enum value. See "Arguments.caseInsensitiveEnumStringType(Class<T>)".

• Customized conversion of an enum to a value is now possible by creating a sub class of "CaseInsensitiveEnumArgumentType". See the existing sub classes for an example.

• It is now possible to specify multiple verification groups for "File" (and Java 7 "Path") types. If at least one group is verified successfully, the argument is accepted. This is useful for applications that can create the missing file or directory themselves.

Help

• If you use "ArgumentParser.parseArgsOrFail(String[])" or "ArgumentParser.parseKnownArgsOrFail(String[], List<String>)", and the user requests help, the exit code will be 0 instead of 1 now.

• It is now possible to write the help text to a specific "PrintWriter" instead of standard output. See "ArgumentParser.printHelp(PrintWriter)".

• Added (optional) suppression of help for arguments and sub parsers. See "Argument.help(FeatureControl)" and "Subparser.help(FeatureControl)".

Internationalization

• Added a feature to create a parser that uses a locale other than the default of the JVM. See "ArgumentParserBuilder.locale(Locale)".

• Added Dutch and Russian translations.

• All user messages have been localized. argparse4j is available in Dutch, English, German and Russian.

• The CJK character widths have been updated to Unicode 10.

Extension modules

• An extension module for Java 7 has been added. It contains the following features:

  • An argument type for "java.nio.file.Path".

• An extension module for Hadoop has been added. It contains the following features:

  • An argument type for "org.apache.hadoop.fs.Path".

Backward compatibility

• Methods have been added to interfaces "ArgumentParser" and "Subparser". Classes implementing these interfaces must be updated and recompiled. If you use existing binary artifacts containing classes implementing these interfaces, and you upgrade argparse4j, a "NoSuchMethodError" will be thrown if one of these new methods is invoked. These interfaces were not meant to be implemented by client code, so there should be very few, if any, custom implementations. The chances of running into problems should be very slim.

Release Note

This release adds several new functionalists. ArgumentParser#parseKnownArgs() family methods were added to parse known arguments only. Metavar for Boolean and Enum types are now automatically generated if neither Argument#metavar() nor Argument#choices() is used. To achieve this, MetavarInference interface, which is part of public API, was added for the underlying mechanism. The BooleanArgumenType and its helper method Arguments#booleanType() were added for strict boolean parameter handling. Previously, when parsing concatenated short options, the default prefix character ("-") is used, regardless of the prefix characters given by application. Now it is corrected, and the prefix characters given by application are used for this purpose.

We moved project web site from argparse4j.sourceforge.net to https://argparse4j.github.io/.

Changes

• Add BooleanArgumentType for strict boolean value conversion

• Infer metavar for enums

  Previously, when enum types is used as type, either with ReflectArgumentType or EnumStringArgumentType, application had to set metavar to show their available values. With this commit, metavar is automatically created using MetavarInference interface.

• Introduce MetavarInference interface, and infer Boolean metavar

  Previously, when Boolean.class is passed to Argument#type(), and no metavar is provided, the help message was like "-f F". This is intentional, and expected, but it is better for user to show them F is true or false. This commit introduce MetavarInference interface. When sub class of ArgumentType also implements MetavarInference, it can infer metavar from its interface. We made ReflectArgumentType implement this interface, and if Boolean.class is given for its constructor, then return useful Boolean value metavar from inferMetavar() method.

• Add ArgumentParser#parseKnownArgs() to parse known arguments only

  If a parameter, named unknown, is given, all unrecognized arguments are stored in it. This parsing operation does not work in all cases as you expect. In particular, if variable length positional arguments (nargs("*") or nargs("+")), all non-prefixed arguments are consumed.

• Use prefixChars to parse concatenated short options

Release Note

This release fixes the bug that nargs("*") or nargs("+") for positional argument consume all arguments, and do not left any arguments to the remaining required positional arguments which take at least 1 argument. By the product of this fix, we also fixed the bug that positional arguments are effectively separated and stop to consume by the existence of a flag. For example, we define positional argument "foo" which has nargs("+"), and optional argument, "-b" which takes not argument. Then previously, giving "a -b c d" to the program resulted error, because "d" was not consumed by "foo". Now "d" is identified as one of argument to "foo", and "foo" takes "a" and "d" correctly. This could possibly change the behaviour of the application, depending on how arguments are supplied. This release also adds EnumStringArgumentType, and its shortcut Arguments.enumStringType. Argument.type() already supports enum types, but it does not take into account toString() override for enum. EnumStringArgumentType converts strings to enums using toString as the enum String representation.

Changes

• Adds EnumStringArgumentType

  Adds EnumStringArgumentType that converts strings to enums using toString as the enum String representation.

  Patch from andrewj

• Fix bug that positional arguments are separated and not consumed if flag exists in between.

• Distribute arguments to positional Argument object to satisfy minimum number of arguments.