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

Stack Overflow

Issues

QA forum

Rationale

for writing yet another argument parsing library (see Is there a good command line argument parser for Java? for others)

1. Because type-safety, immutability and readability matters

2. Compared to annotation based solutions (like JCommander) jargo can be updated at runtime to support more arguments

3. 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

4. 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();

5. 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.

For contributors

Possible candidates for refactoring

Check code-smells at codescene.io.