required versus unmatched options

[LianOrt]

My environment is [picocli INFO] Picocli version: 4.7.7, JVM: 21.0.3 (Eclipse Adoptium OpenJDK 64-Bit Server VM 21.0.3+9-LTS), OS: Windows 11 10.0 amd64

I have a small test method that runs successfully:

    @Test public final void test_unknown_argument() {
        @Command(name = "check")
        class Args {
            @Option(names = {"-s" }, description = "path of surveys to execute%n")
            private String optSurveyDir = null;

            @Option(names = {"-r" }, description = "path where the report has to be generated%n")
            private String optReportDir = null;
                        
        }
        
        // check if "-to"  is reported as unmatched option
        Tests.assertThrows(UnmatchedArgumentException.class, () -> { 
            final Args args = new Args();
            CommandLine cmd = new CommandLine(args)
                    .setUnmatchedOptionsArePositionalParams(false)
                    .setPosixClusteredShortOptionsAllowed(false)
                 ;
            cmd.parseArgs("-to");
            
        });   
    }

Now when i change the option "-r" to "required=true" the exception is "Missing required option: '-r=<optReportDir>'".

My naive expectation would be that an unmatched option has a somewhat higher priority then an missing option, especially when its the only one. I experimented with some options for the CommandLine instance, but did not found a solution to this.

The following informations are given at the debug trace:

[picocli DEBUG] Creating CommandSpec for de.dmig.TestPicoCli$1Args@55f616cf with factory picocli.CommandLine$DefaultFactory
[picocli INFO] Picocli version: 4.7.7, JVM: 21.0.3 (Eclipse Adoptium OpenJDK 64-Bit Server VM 21.0.3+9-LTS), OS: Windows 11 10.0 amd64
[picocli INFO] Parsing 1 command line args [-to]
[picocli DEBUG] Parser configuration: optionsCaseInsensitive=false, subcommandsCaseInsensitive=false, abbreviatedOptionsAllowed=false, abbreviatedSubcommandsAllowed=false, allowOptionsAsOptionParameters=false, allowSubcommandsAsOptionParameters=false, aritySatisfiedByAttachedOptionParam=false, atFileCommentChar=#, caseInsensitiveEnumValuesAllowed=false, collectErrors=false, endOfOptionsDelimiter=--, expandAtFiles=true, limitSplit=false, overwrittenOptionsAllowed=false, posixClusteredShortOptionsAllowed=false, separator=null, splitQuotedStrings=false, stopAtPositional=false, stopAtUnmatched=false, toggleBooleanFlags=false, trimQuotes=false, unmatchedArgumentsAllowed=false, unmatchedOptionsAllowedAsOptionParameters=true, unmatchedOptionsArePositionalParams=false, useSimplifiedAtFiles=false
[picocli DEBUG] (ANSI is enabled by default: systemproperty[picocli.ansi]=true, isatty=false, TERM=null, OSTYPE=null, isWindows=true, JansiConsoleInstalled=false, ANSICON=null, ConEmuANSI=null, NO_COLOR=null, CLICOLOR=null, CLICOLOR_FORCE=null)
[picocli DEBUG] Initializing command 'check' (user object: de.dmig.TestPicoCli$1Args@55f616cf): 2 options, 0 positional parameters, 1 required, 0 groups, 0 subcommands.
[picocli DEBUG] Set initial value for field String de.dmig.TestPicoCli$1Args.optSurveyDir of type class java.lang.String to null.
[picocli DEBUG] Set initial value for field String de.dmig.TestPicoCli$1Args.optReportDir of type class java.lang.String to null.
[picocli DEBUG] [0] Processing argument '-to'. Remainder=[]
[picocli DEBUG] '-to' cannot be separated into <option>=<option-parameter>
[picocli DEBUG] Could not find option '-to', deciding whether to treat as unmatched option or positional parameter...
[picocli DEBUG] No option named '-to' found. Processing as positional parameter
[picocli DEBUG] '-to' resembles an option: 2 matching prefix chars out of 2 option names
[picocli DEBUG] Applying default values for command 'check'
[picocli DEBUG] defaultValue not defined for field String de.dmig.TestPicoCli$1Args.optSurveyDir
[picocli DEBUG] defaultValue not defined for field String de.dmig.TestPicoCli$1Args.optReportDir

[remkop]

Picocli will check mandatory options (and mandatory positional parameters) first, before validating unrecognized options/parameters.

So to me, the current behavior looks correct.

[LianOrt]

Unfortunately the geopts documentation is not clarifying this point. I would only argue that the order of the comments is a little hint :)
Found here: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/getopts.html

...
- If an option is found that was not specified in optstring, this error is identified and the invalid option character shall be identified in the message.
- If an option requiring an option-argument is found, but an option-argument is not found, this error shall be identified and the invalid option character shall be identified in the message.

I agree that the missing mandatory options error is important too. This leads me to: why not print out both errors? Eventually sampling the error messages during the parsing?

Both errors are important to know for the user, if one is missing chances are high, that the user will make that one again.