Jargo
A tool to ease the handling of program arguments/options
Most basic usage
import static se.softhouse.jargo.Arguments.*;
...
String[] args = {"--enable-logging", "--listen-port", "8090", "Hello"};
Argument<?> helpArgument = helpArgument("-h", "--help"); //Will throw when -h is encountered
Argument<Boolean> enableLogging = optionArgument("-l", "--enable-logging")
.description("Output debug information to standard out").build();
Argument<String> greetingPhrase = stringArgument()
.description("A greeting phrase to greet new connections with").build();
Argument<List<Integer>> ports = integerArgument("-p", "--listen-port")
.defaultValue(8080)
.description("The port clients should connect to.")
.metaDescription("<port>")
.limitTo(Range.closed(0, 65536))
.repeated().build();
try
{
ParsedArguments arguments = CommandLineParser.withArguments(greetingPhrase, enableLogging, ports)
.andArguments(helpArgument)
.parse(args);
System.out.println("Logging enabled: " + arguments.get(enableLogging));
System.out.println("Ports: " + arguments.get(ports));
System.out.println("Greeting visitors with: " + arguments.get(greetingPhrase));
}
catch(ArgumentException exception)
{
System.out.println(exception.getMessageAndUsage());
System.exit(1);
}
Tab-completions
No program is complete without tab-completions! So after building your project's jar (.jar), you (and your users) need to specify:
alias my-app="java -jar <path-to-app>.jar"
complete -o default -o bashdefault -o nospace -C my-app "my-app"
in their ~/.bash_profile file to enjoy the automatic tab-completions Jargo provides.
For more examples see the Javadoc
Dependency
Jargo
<dependency>
<groupId>se.softhouse</groupId>
<artifactId>jargo</artifactId>
<version>0.4.13</version>
</dependency>
Common-test (optional) Javadoc
<dependency>
<groupId>se.softhouse</groupId>
<artifactId>common-test</artifactId>
<version>0.4.13</version>
JDK compatiblity
JDK 6
Version <= 0.4.1 (used Guava)
JDK 8
From version 0.4.2 and onwards this library requires jdk 8 and Guava was removed as a dependency. This made this library even more lightweight (179K, no external dependencies). Especially useful as command line tools are often distributed, so the small file-size can be useful. If you want to go even further in reducing the filesize of your program, you can try out Proguard
Bugs/Questions
Rationale
for writing yet another argument parsing library (see Is there a good command line argument parser for Java? for others)
-
Because type-safety, immutability and readability matters
-
Compared to annotation based solutions (like JCommander) jargo can be updated at runtime to support more arguments
-
The generics on Argument gives you compile-time errors when switching types
In JCommander:
@Parameter(names = "-file", converter = FileConverter.class) File file; //Oops, changing this to int would not work very well with FileConverter
In jargo:
Arguments.fileArgument("-file").parse("-file", "filename.txt").createNewFile();
if fileArgument would change to being integerArgument, trying to call createNewFile() would generate a compile-time error
-
Because JCommander doesn't support repeated arguments other than List<String>
String[] args = {"--numbers", "5", "6", "--numbers", "3", "4"}; Argument<List<List<Integer>>> numbers = Arguments.integerArgument("--numbers").arity(2).repeated().build();
-
Reflection makes it hard to analyze references to classes/methods and it often requires a granted suppressAccessChecks from the SecurityManager, this may not be wanted. No reflection is used in jargo.