hyphenType is a Java library to make it easy for programmers to parse command line interface (CLI) arguments.
hyphenType is different from other solutions in that it parses command line arguments into an object. Instead of having to specify parsing arguments using a library, a programmer needs only to write a simple annotated Java interface and hyphenType will do the rest.
hyphenType is licensed under the GNU Lesser General Public License (LGPL), therefore you can use this tool free of charge, even commercially.
This is the documentation site. Our GitHub site is https://github.com/aamm/hyphenType/.
Please use our mailing list to contact us.
Simply annotate a Java interface with descriptions and call a method.
You can add a number of documentation formatters to your CLI. The standard one, for instance, even formats the output to have a maximum number of columns.
-h can be declared to be the same as --help
-xyz is the same as -x -y -z
Easy to edit for non-European languages.
If a mandatory argument was not given as CLI argument, hyphenType can ask the user to type the argument in the command line, or even show a dialog window.
hyphenType can manage return codes (the number n in System.exit(n)), converting enumerations into integers. Also, it can convert exceptions into a certain return code.
Validation of CLI arguments can be made using built-in configurable validators. You can also easily create your own validator.
Unit testing parsing or the application that reads parsing.
Unit tests can easily write text files containing the result of executing your program, simulating a terminal. The outputs on this pages were all automatically generated using this feature.
Let's say that your application expects to receive only two arguments from the command line and ignore all other arguments. Both arguments should be plain strings. Let's take a look at a simple class that solves this problem using hyphenType:
package example.case1; import org.hyphenType.wrapper.StandAloneAppWrapper; public class XApp extends StandAloneAppWrapper { public void main(XOpt opt) { System.out.println(opt.argA()); System.out.println(opt.argB()); } }
The source code of the interface XOpt is:
package example.case1; import org.hyphenType.datastructure.Options; import org.hyphenType.datastructure.annotations.SimpleArgument; @SuppressWarnings("unchecked") public interface XOpt extends Options { @SimpleArgument(index = 0) public String argA(); @SimpleArgument(index = 1) public String argB(); }
Now if you run XApp as any ordinary stand alone Java application, the results will be:
_> java example.case1.XApp aaa bbb aaa bbb
_> java example.case1.XApp aaa bbb ccc ddd aaa bbb
What happens here is that we do not need to directly deal with the arguments received. In other words, the main class we wrote does not need to handle the standard String[] args. Instead, the arguments are read by hyphenType and transformed into simple Java objects.
As you may have already noticed, all arguments after the second were simply ignored.
Now what if we want to show a help message every time we do not receive anything as arguments? We will only need to change our application a little bit:
package example.case2; import org.hyphenType.wrapper.StandAloneAppWrapper; public class XApp extends StandAloneAppWrapper { public void main(XOpt opt) { if (opt.argA() == null) { opt.printDocumentation(); return; } System.out.println(opt.argA()); System.out.println(opt.argB()); } }
The opt object not only comes with the values of the arguments, but can also output a documentation on how to call your program.
What if we want to add some interesting message that actually explains what our simple program does?
We need only to change the interface XOpt.
package example.case2; import org.hyphenType.datastructure.Options; import org.hyphenType.datastructure.annotations.ArgumentsObject; import org.hyphenType.datastructure.annotations.SimpleArgument; @SuppressWarnings("unchecked") @ArgumentsObject(description = "Prints argA and argB to stdout.") public interface XOpt extends Options { @SimpleArgument(index = 0) public String argA(); @SimpleArgument(index = 1) public String argB(); }
So now if we try to run our application again we will see:
_> java example.case2.XApp usage: program [argA] [argB] Prints argA and argB to stdout. Arguments Options
What if we want to show a help message only where there is an argument -h or --help, which is a standard followed by several command line tools?
Again, we will only need add and change a few lines of source code. We need to add an extra method to our interface:
package example.case3; import org.hyphenType.datastructure.Options; import org.hyphenType.datastructure.annotations.ArgumentsObject; import org.hyphenType.datastructure.annotations.Option; import org.hyphenType.datastructure.annotations.SimpleArgument; @SuppressWarnings("unchecked") @ArgumentsObject(description = "Prints argA and argB to stdout.") public interface XOpt extends Options { @Option(names = { "h", "help" }, description = "Shows this help message") boolean h(); @SimpleArgument(index = 0, name = "a", description = "This is a short description of argument a.") public String argA(); @SimpleArgument(index = 1, name = "b", description = "This is the description of argument b. " + "This is a very long description to demonstrate the automated formatting " + "capability of hyphenType. As you can see, the output will have line " + "breaks that guarantee that text will only go until a certain column, " + "which ensures that documentation will look great even in low resolution " + "terminals.") public String argB(); }
And change one line of our class:
package example.case3; import org.hyphenType.wrapper.StandAloneAppWrapper; public class XApp extends StandAloneAppWrapper { public void main(XOpt opt) { if (opt.h()) { opt.printDocumentation(); return; } System.out.println(opt.argA()); System.out.println(opt.argB()); } }
Let's run it again. This time, passing the arguments -h or --help:
_> java example.case3.XApp -h usage: program [options] [a] [b] Prints argA and argB to stdout. Arguments a This is a short description of argument a. b This is the description of argument b. This is a very long description to demonstrate the automated formatting capability of hyphenType. As you can see, the output will have line breaks that guarantee that text will only go until a certain column, which ensures that documentation will look great even in low resolution terminals. Options -h, --help Shows this help message
We can also notice that we added documentation to the two options. So hyphenType will automatically print the documentation and format long lines so it looks good in low resolution terminals.
_> java example.case3.XApp --help usage: program [options] [a] [b] Prints argA and argB to stdout. Arguments a This is a short description of argument a. b This is the description of argument b. This is a very long description to demonstrate the automated formatting capability of hyphenType. As you can see, the output will have line breaks that guarantee that text will only go until a certain column, which ensures that documentation will look great even in low resolution terminals. Options -h, --help Shows this help message
Note that so far we did not call any class of hyphenType directly. The only references to hyphenType were the SimpleArgument annotation and extending Options and StandAloneAppWrapper.
Another interesting thing to notice is that the main method is not static. In fact, adding a static modifier to this method will not change the outcome. Internally, hyphenType will check whether the main method is static or not. If it is static, then it will simply call the method. If the method is not static, then hyphenType will first create an instance of the class (in the example above, an instance of XApp) and call the main method from that instance.
At this point you already know the basic idea behind hyphenType: you need to write an options interface and hyphenType will use it to both understand how command line arguments should be parsed, and to create an object that will give you easy access to the parsed data.
But hyphenType can parse arguments that are more complex then those of the examples we just saw. For instance, there are ways to tell hyphenType to create lists or parse arguments to custom classes.
We designed hyphenType to be not only a command line parsing tool, but also a tool to help unit test and document stand alone applications.
Check the menu on the left for more resources regarding hyphenType.