Command-line option parser for Java

Question

I'm writing a shell in Java because I haven't programmed in Java for far too long and I've forgotten a lot of it. I was going to write my own, but right now I'd like to get a working prototype, so I would like to drop in an existing command-line option parser.

Requirements:

• Takes an arbitrary String or String[] (i.e. doesn't use the arguments from the command line)
• Takes arguments in a similar format to getopt (the GNU enhanced version); specifically:
  • Multiple single-letter options can be joined (e.g. -a -b -c to -abc)
  • Supports long options (e.g. --message="Hello!") (though it doesn't have to support single-dash long options)
  • Assumes all non-option-like bits at the end are parameters to be passed normally (e.g. -abc --long="Hello!" param1 param2 tells me that the parameters are param1 and param2)
  • -- can be used to separate options from arguments (e.g. -ab --custom="hello" -- -file_starting_with_hyphen -another gives me the options/flags a, b, and custom with the appropriate values, and tells me that the arguments are -file_starting_with_hyphen and -another)
  • Whitespace can be part of arguments, if it's quoted.
  • An option name followed by a value is parsed as the option having that value (e.g. -h foo says that there is an option, h, with a value, foo)
• Entirely cross-platform
• Doesn't need me to specify which options I'm looking for (i.e. I pass it a String or String[] and it tells me which flags/options were set, as opposed to it looking for the options I want to set and assuming the rest are arguments)
  • This means it doesn't use annotations to specify where to store the flag values. At least two answers so far have done this.
• Free (as in beer)
• Can be legally used in any project (i.e. not noncommercial, not GPL)

Ideal, but not necessary:

• Small -- one file
• Minimal copyright license (Not copyleft -- I like not worrying about legal issues, and I hate people trying to tell me that I can't use my work, however, I damned well, please)
• Uses the built-in interfaces (java.util.Map, specifically) to return data. (This is so I can write my own function more easily later)
• Open source

Answer 1

You could check out FeSimpleArgs

I believe it fulfills all your requirements:

Concept: A very light-weight command-line parser. Takes arguments in either a String or String[] form, returns a class instance holding the arguments in a map, and the parameters in a list.

Requirements:

• Takes an arbitrary String or String[] (i.e. doesn't use the arguments from the command line) Yes
• Takes arguments in a similar format to getopt (the GNU enhanced version); specifically:
• Multiple single-letter options can be joined (e.g. -a -b -c to -abc) Yes
• Supports long options (e.g. --message="Hello!") (though it doesn't have to support single-dash long options) Yes
• Assumes all non-option-like bits at the end are parameters to be passed normally (e.g. -abc --long="Hello!" param1 param2 tells me that the parameters are param1 and param2) Yes
• -- can be used to separate options from arguments (e.g. -ab --custom="hello" -- -file_starting_with_hyphen -another gives me the options/flags a, b, and custom with the appropriate values, and tells me that the arguments are -file_starting_with_hyphen and -another) Yes
• Whitespace can be part of arguments, if it's quoted. Yes

• An option name followed by a value is parsed as the option having that value (e.g. -h foo says that there is an option, h, with a value, foo) Yes

• Entirely cross-platform Yes

• Doesn't need me to specify which options I'm looking for (i.e. I pass it a String or String[] and it tells me which flags/options were set, as opposed to it looking for the options I want to set and assuming the rest are arguments) Yes

as to usage:

• Free (as in beer) Yes - Apache 2.0
• Can be legally used in any project (i.e. not noncommercial, not GPL) Yes - Apache 2.0
• Minimal copyright license (Not copyleft -- I like not worrying about legal issues, and I hate people trying to tell me that I can't use my work, however, I damned well, please) Yes - Apache 2.0

Published under Apache 2.0 license.

Ideal, but not necessary:

• Small -- one file Yes (one file for the parser, one for the unit tests, not needed to parse)
• Uses the built-in interfaces (java.util.Map, specifically) to return data. (This is so I can write my own function more easily later) **Sort of ** (Returns a class holding a java.util.Map of arguments and a List of parameters)

USAGE Usage: 1) Construct an instance of FeSimpleArgs

FeSimpleArgs parser = new FeSimpleArgs();

2) Use it to parse your arguments:

FeSimpleArgs.Result result = parser.parse ("-def=value1 --GHI=value2 -a -b -c=value3 -n=\"foo bar baz\" -- param1 -param2"); 

3) Examine your results: From the above, result will consist of a Map containing the following arguments and flags (note that there's no real meaning to "argument" or "flag", I'm just using those terms to separate whether they take values or not - all are in the same Map).

• a
• b
• d
• e
• f with value=value1
• GHI with value=value2
• c with value=value3
• n with value=foo bar baz (note quotes are stripped)

And a list containing these parameters (note that the leading hyphen is preserved) - param1 - -param2

4) Profit?

For other examples, please see the included unit tests.

Disclaimer: I am the author of FeSimpleArgs

Answer 2

picocli may be of interest. It is a single source file to encourage command line app authors to include it as source as a simpler alternative to shading jars into an uberjar. It also fulfills all other requirements stated in the OP - UPDATE: except for the requirement that options cannot be fixed at compile time :-(.

UPDATE 2: picocli 3.x offers a programmatic API in addition to the annotations API, so now it meets all requirements. Note that Groovy CliBuilder is based on picocli since Groovy 2.5. This is exactly what the OP is asking for: dynamically add options and positional parameters to a command.

It recently added autocompletion functionality.

Another feature you may like is its colorized usage help.

Parser features:

• Annotation API: parsing is one line of code in your application
• Programmatic API: everything that is possible with annotations can be done programmatically
• Strongly typed everything - command line options as well as positional parameters
• POSIX clustered short options (<command> -xvfInputFile as well as <command> -x -v -f InputFile) and GNU long options
• An arity model that allows a minimum, maximum and variable number of parameters, e.g, "1..*", "3..5"
• Subcommands (can be nested to arbitrary depth)
• Works with Java 5 and higher

The usage help message is easy to customize with annotations (without programming). For example:

(source)

I couldn't resist adding one more screenshot to show what usage help messages are possible. Usage help is the face of your application, so be creative and have fun!

Disclaimer: I created picocli. Feedback or questions very welcome.

Answer 3

I have used args4j successfully in a number of projects. It was developed by Kohsuke Kawaguchi who who also developed Jenkins, was main developer for JAXB and other projects, so he has a very good pedigree.

Answer 4

Note: This answer is outdated, because OP edited the question to add a requirement that this doesn't fulfill (however, it is still a darn good thing to know). See the comments below. The OP does NOT want you to downvote this answer.

The classic for this in Unix/Linux, back from the days of C was GetOpt().

Gnome has a Java port here.