We only support opening a single case at a time, so I figured I would just use this for accepting the location as the main parameter:

@Parameter(descriptionKey = "DesktopMainArguments.docLocation")
public File docLocation;

Attempting to parse then throws the following exception:

com.beust.jcommander.ParameterException: Main parameter field public java.io.File com.acme.main.MainArguments.docLocation needs to be of type List, not class java.io.File

I'm sure I could change it to a list, but then I would have to put in boilerplate to check that the user hasn't specified more than one. Is there a proper way to do this directly? Because I can't seem to find it in the examples or in the API.

I thought validation might be the way to do it, but I suspect I was wrong about that because the validator receives the original command-line string, not the final converted object.

Would it be possible to sync or release the newer versions of jcommander to the Central Repository again? The last one available there is 1.48

https://repo1.maven.org/maven2/com/beust/jcommander/

Newer versions are available on jcenter

https://dl.bintray.com/cbeust/maven/com/beust/jcommander/

but it would just be nice to be able to use jcommander with Maven and other projects out of the box as well. Just makes it easier to use in open source projects imho..

Hi,

We are having a strange behaviour from the way JCommander is dealing with validator classes. Let me describe our scenario in more details. We have a parent command, called Parent, and two completely disjoint subclasses - A and B, which are as well both JCommander commands.

Both A and B define parameter with the same name - call it 'par', of the same type (Parent does not have this 'par' parameter). But only command B specifies a validator class for this parameter.

Now, what happens is that we call the command A from the command line, and we get an error ... from the validator for command B! But this validator shouldn't be called at all for command A - this breaks our semantics and intention.

I made some debugging and this is what happens:

When JCommander launches, it scans and installs all recoginzed comands - for example {B, A, Parent}. Next, it enters some initializing phase of setting default values for all command parameters - it iterates the commands, one by one. First, it reaches the command B, and next it reaches its parameter 'par'. It tries to set default value to it, which is firstly checked to be taken from a property provider file (if any). At this point in time, such a value is being set to our parameter, because we do use a property provider file. Next, the validator is called for this default value. And here the validation fails - which is completely OK, since this value is not suitable for command B - but is perfectly OK for command A.

So, to summarize: although I call only one command, JCommander initializes and sets default values (and then calls validators) on all commands, and on all of their parameters.

To my understanding, this is a bug and it should be fixed.

Kindest Regards, Krum.

Currently if you specify help = true in a parameter, exceptions are suppressed. However, you then have to manually check for required parameters not being set.

It would be great if there were a way to prevent exceptions from being thrown on missing required parameters, but print the usage text instead. Maybe in addition to adding help = true to a help parameter, you could also specify usage = true, and if a parameter is missing, even if the help option was not given on the commandline, JCommander could set the help parameter value to true, so that the usage text is displayed?

right now options which are based on their position rather than named; (i.e. @Parameter without a name) the current option is just to support a single @Parameter injection point which takes a List

for commands where you expect positional arguments this loses lots of the benefit of the injection & type coercion & validation using the @Parameter annotation along with the nicely generated usage documentation.

It would be nice if we could supply an indexed parameter as opposed to a the named/optional parameter.

e.g.

class Copy {
  @IndexParameter(0, name = "from", "the source file(s) used to copy")
  File from;

  @IndexParameter(1, name = "to", "the destination file")
  File to;
}

So rather than having to manually parse a List and figure out whats what, we can use the simpler annotation approach.

Also usage would be able to do something like...

Usage: copy [options] from to
    from   the source file(s) used to copy
    to       the destination file
  Options:    
    --bar        does something
    --another  something else

This also opens up the requirement for one of the parameters to be a collection, specifying minimum cardinality. e.g. you might want to do this...

class Copy {
  @IndexParameter(0, name = "from", "the source file(s) used to copy", arity = 1)
  List<File> from;

  @IndexParameter(1, name = "to", "the destination file")
  File to;
}

so that you could run the command

copy a b dest

but get an error you do any of the following

copy
copy a

I just realized that JCommander obviously requires Java 6 since it seems to use java.io.Console. I learned it the hard way. ;)

It would be nice if the usage of Console could be optional. I'm not sure if this can be achieved, though. I've seen that it's only used for reading a password. How about implementing an fallback that can be used on 1.5 Java?

Unfortunately, I need to stay 1.5 compatible for a little bit longer :(

@cbeust Cedric, according to the Github statistics, your project is stale since one year. While there are recent issues and PRs, no commits have been pushed for one full year. Do you need project help? Our company could chime in and manage the project for you if you like.

Hello,

This is the basic skeleton of what I want to do with usage formatting.

• I have managed to extract most of the usage formatting to the UsageFormatter and its default subclass DefaultUsageFormatter.
• I only left behind JCommander#usage() to act as a simple way to print usage, without messing with the underlying UsageFormatter.
• I allow injecting UsageFormatter into JCommander through a setter.

I want to do the following before we consider this solution:

• [X] Try to implement a Unix-style usage formatter to test the flexibility of the solution
• [X] Try to restrict the access of members I exposed in JCommander to make this work
• [X] Clean up the DefaultUsageFormatter code some more
• [x] Test it

One problem is that this is a public API change, so you might choose to keep some of the old usage methods in JCommander for backwards compatibility sake.

This code allows users to enter the shortest unambiguous prefix of a parameter name. For example, given parameters --alpha --beta, and --barium, users need only type --a, --bet, and --bar on the command line.

Last November, we discussed implementing this as a "wrapper" to JCommander. However, that solution does not work well when commands are used. For example, JCommander allows the parameters for different commands to have different prefixes. It would be very difficult to implement the abbreviations as a wrapper and support similar behavior.

Instead, I made a few small changes right in JCommander. In particular I added an AbbreviationMap instance variable. This object maps abbreviated parameters to the appropriate ParameterDescription (if the abbreviation is unambiguous).

I then added this code at JCommander line 642 in parseValues:

ParameterDescription pd; if (allowAbbreviations) { pd = m_abbrevMap.get(a); } else { pd = m_descriptions.get(a); }

I got AbbreviationMap from Paul Hosler's JOptSimple package. It uses the MIT license.

I added these two methods:

/** * Parse and validate the command line parameters allowing abbreviated parameters. */ public void parseWithAbbreviations(String... args) { parseWithAbbreviations(true, args); }

/** * Parse the command line parameters allowing abbreviated parameters. / public void parseWithAbbreviations(boolean validate, String... args) { parse(validate, true / allow abbreviations */, args); }

Perhaps instead of parse, parseWithoutValidation, and two versions of parseWithAbbreviations, we want to simply make this method public:

private void parse(boolean validate, boolean allowAbbreviations, String... args) {

Let me know what you think.

Support for invoking runnable callbacks on command parsing

This started as an attempt to let users specify command names and aliases using annotations. However, since you still have to manually match command name against getParsedCommand() output in order to select the right action to be invoked, moving command name to the annotation provides little benefit by itself.

The solution, as proposed in issue #54, is to associate a callback (e.g. Runnable) with a command and automatically invoke it when the command is encountered and parsed (see CommandCallableScenarioTest). Additionally, I have added a custom JRunnable class that receives the parsed parameters as an argument to the callback.

The advantage is that you can define command name and aliases in the annotation once, specify the runnable, and the rest is handled by JCommander. You also don't need to save a reference to the parameters object, you can just do jc.addCommand(new MyCommandOpts(), new JCallable<MyCommandOpts>(){ ... }.

The drawbacks of the approach are:

1. The callback invoking logic is simply: parsed command --> associated callback. For anything more complex, the user will have to go back to the old-fashioned way.
2. The order in which JCommander#parse() is called and the associated callbacks are invoked will change. Currently you call parse() then your get the parsed command and invoke the associated callback. With the new approach first you define the callback, then you call parse(). This may cause problems if you need to insert custom logic that needs the original ordering.

Let me know if you have an opinion on this style of doing things. Maybe it's an overkill?

Hi,

it seems that there is some discrepancy in providing the library ..

latest tagged git release - 1.71 Maven Repository - 1.72 Bintray Maven - 1.74

Will only Bintray be maintained ?

Thx, P.

Fixes #548

I upgraded this by running the gradle wrapper command which also had the effect up updating the gradlew scripts.

gradle wrapper --gradle-version 7.6

I'm using Java 17 (openjdk version "17.0.5" 2022-10-18) on macos, and when I try to run the default build, it fails with a Java module error:

> ./gradlew assemble
> Task :compileJava FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':compileJava'.
> java.lang.IllegalAccessError: class org.gradle.internal.compiler.java.ClassNameCollector (in unnamed module @0x2f377c45) cannot access class com.sun.tools.javac.code.Symbol$TypeSymbol (in module jdk.compiler) because module jdk.compiler does not export com.sun.tools.javac.code to unnamed module @0x2f377c45

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.

* Get more help at https://help.gradle.org

BUILD FAILED in 780ms
1 actionable task: 1 executed

PR #542 (which implements #539) which introduced IParametersValidator included its documentation for it, but it is not deployed to the JCommander website.

This is the current paragraph for the global parameter validation section that is live:

The documentation which #542 added is linked here: https://github.com/cbeust/jcommander/blob/master/docs/index.adoc#global-parameter-validation.

Suppose that I have this converter which takes a String and attempts conversion into an Index - which is basically a wrapper around an int:

public class IndexConverter implements IStringConverter<Index> {
    @Override
    public Index convert(String value) {
        if (!StringUtil.isNonZeroUnsignedInteger(value)) {
            throw new ParameterException("The index must be a non-zero unsigned integer.");
        }
        return Index.fromOneBased(Integer.parseInt(value));
    }
}

However, if I define a parameter in my command class like so, and I attempt to let JCommander parse the command <command word> 123 abc, now I get the ParameterException thrown because the "abc" is not an integer - but should JCommander instead realize that the arity of 2 is incorrect before attempting conversion?:

@Parameters(commandDescription = "...")
public class ExampleCommand extends Command {

    @Parameter(description = "...", required = true, converter = IndexConverter.class, arity = 1)
    private Index targetIndex;
    ...
}

My rationale for raising this issue is that the exception message is of the wrong specificity - the exception from the failed conversion has higher priority than the exception from the arity.

This is behavior is undesirable for my use case as it's more important to reject the incorrect arity than to inform the user of a failed conversion.

Could there be a way to configure JCommander to validate arities before conversions?

I create a JobPriorityConverter class, it's inherit from EnumConverter.

public class JobPriorityConverter extends EnumConverter<JobPriority> {
  public JobPriorityConverter(final String str, final Class<JobPriority> clazz) {
    super(str, clazz);
  }

  @Override
  public JobPriority convert(String value) {
    JobPriority jobPriority = super.convert(value);
    if (jobPriority == JobPriority.VERY_HIGH || jobPriority == JobPriority.UNKNOWN_JOB_PRIORITY) {
      return JobPriority.HIGH;
    } else {
      return jobPriority;
    }
  }
}

The JobPriority is generated by proto, it look like below

public enum JobPriority implements com.google.protobuf.ProtocolMessageEnum {
  UNKNOWN_JOB_PRIORITY(0),
  VERY_HIGH(1),
  HIGH(2),
  NORMAL(3),
  UNRECOGNIZED(-1);
}

Now, I have a parameter.

@Parameter(names = {"--priority"}, converter = JobPriorityConverter.class)
protected JobPriority priority = JobPriority.NORMAL;

But I run the program, for example: java -classpath xxx ... className --priority VERY_HIGH, then it should be HIGH, actually it's still VERY_HIGH.

I pass the invalid priority, it output.

Exception in thread "main" com.beust.jcommander.ParameterException: Invalid value for -pr parameter. Allowed values:[UNKNOWN_JOB_PRIORITY, VERY_HIGH, HIGH, NORMAL, UNRECOGNIZED]
	at com.beust.jcommander.converters.EnumConverter.convert(EnumConverter.java:38)
	at com.beust.jcommander.converters.EnumConverter.convert(EnumConverter.java:13)
	at com.beust.jcommander.JCommander.convertValue(JCommander.java:1472)
	at com.beust.jcommander.ParameterDescription.addValue(ParameterDescription.java:238)
	at com.beust.jcommander.JCommander.processFixedArity(JCommander.java:895)
	at com.beust.jcommander.JCommander.processFixedArity(JCommander.java:870)
	at com.beust.jcommander.JCommander.parseValues(JCommander.java:721)
	at com.beust.jcommander.JCommander.parse(JCommander.java:340)
	at com.beust.jcommander.JCommander.parse(JCommander.java:319)

I am packaging this project and noticed this file outside of java source tree. Is it supposed to be added manually or not? If not, is there a reason why it is present in the project at all? I see that currently released jars are not modular. In any case even the module-info.java seems to be incomplete as I got the following errors when I attempted to build the project with the file added into the java source tree:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.10.1:compile (default-compile) on project jcommander: Compilation failure: Compilation failure: 
[ERROR] /builddir/build/BUILD/beust-jcommander-1.82/src/main/java/com/beust/jcommander/Parameterized.java:[11,17] package java.util.logging is not visible
[ERROR]   (package java.util.logging is declared in module java.logging, but module com.beust.jcommander does not read it)
[ERROR] /builddir/build/BUILD/beust-jcommander-1.82/src/main/java/com/beust/jcommander/Parameterized.java:[12,17] package java.util.logging is not visible
[ERROR]   (package java.util.logging is declared in module java.logging, but module com.beust.jcommander does not read it)

I just want to point out that the current situation creates confusion for others as to whether or not module-info.java should be used.