[oscerd]

PatternOptionBuilder uses ! to mark an option as required, and it has always applied it to the option before the !: parsePattern("vp:!f/") makes -p mandatory, and the CLI-55 example "hc!<" makes -c mandatory. A ! at the start of the pattern marks the first option, which is the case testRequiredOption covers. The class Javadoc now says "The exclamation mark makes the preceding option mandatory", but apart from that one test nothing pinned the behavior down.

This adds tests for the Javadoc example, the CLI-55 example, a trailing ! and several ! in one pattern, plus a sentence in the class Javadoc about a ! at the start of the pattern. There's no behavior change.

An earlier version of this PR changed ! to mark the following option instead. That was dropped to keep existing patterns working, see the discussion below.

• Read the contribution guidelines for this project.
• Read the ASF Generative Tooling Guidance if you use Artificial Intelligence (AI).
• I used AI to create any part of, or all of, this pull request. Which AI tool was used to create this pull request, and to what extent did it contribute? Claude Code (Claude Opus 5.5) was used to analyze the issue and to prepare the change, its tests and this description.
• Run a successful build using the default Maven goal with mvn; that's mvn on the command line by itself.
• Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied. This may not always be possible, but it is a best practice. Not applicable: no behavior change; the new tests cover the current behavior.
• Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
• Each commit in the pull request should have a meaningful subject line and body. Note that a maintainer may squash commits during the merge process.

🤖 Generated with Claude Code

[garydgregory]

@oscerd
Note: I took the liberty to resolve conflicts in this PR.

[garydgregory]

Hello @oscerd

As you note this is a behavior breaking change. I want to confirm with you that this is really the intent.

As always when the docs and code don't match we have to ask "What's the intent and ground truth for this feature?" and also how much does compatibility matter.

What's confusing is that the PR doesn't update the documentation.

The class still says ! makes the preceding option mandatory, while the updated implementation makes the following option required.

Please review that code and docs match after changing code! ;)

The code now explicitly throws IllegalArgumentException but doesn't document it. We don't always document unchecked exceptions that we passthrough, but for the ones we throw, in this case, I think we should.

Setting to draft.

[oscerd]

Sorry Gary, I had it backwards. I went back to the history: in CLI-55 the example is hc!< making c mandatory, so ! was always meant to mark the option before it. That's what the code does and what your Javadoc now says. The 2008 sentence "The exclamation mark precede a mandatory option" is what threw me off.

Compatibility matters more here, so I've backed out the behavior change. Nothing changes for existing patterns and there's no new exception anymore. The PR now only adds tests for the current behavior (the Javadoc example, the CLI-55 example, a trailing ! and several ! in one pattern) and one sentence saying that a ! at the start of the pattern marks the first option. I've updated the title and description to match, and thanks for sorting out the conflicts.

P.S. 7dfda5b turned the TODO at the end of the class Javadoc into ODO.

[garydgregory]

Thank you @oscerd , merged 🚀