Improve Shell Completion

[skusel]

Describe your changes

The goal of this change is to improve shell completion by making the shell completion scripts more reliable.

I moved CLI option definitions from the source code to cli-options.json in the resources directory. I also added a cli-options.schema.json file so users with an editor that supports JSON schema diagnostics can take advantage of the warnings. A GitHub workflow step was also added to validate cli-options.json using the schema file.

cli-options.json is used to generate F3DCLIOptions.h, completion.bash, completion.fish, and completion.zsh during the CMake configuration step. Any updates to cli-options.json cause CMake to rerun configuration.

The bulk of the work is done in f3dCLIOptions.cmake.

The completion files have been tested against all three shells.

Many existing tests exercise CLI options. I added one additional TestHelp* check, but I believe the CLI options changes are already well covered by the existing tests.

Issue ticket number and link if any

#2121

Checklist for finalizing the PR

• I have performed a self-review of my code
• I have added tests for new features and bugfixes
• I have added documentation for new features
• If it is a modifying the libf3d API, I have updated bindings
• If it is a modifying the .github/workflows/versions.json, I have updated docker_timestamp

Continuous integration

Please write a comment to run CI, eg: \ci fast.
See here for more info.

[skusel]

\ci fast

[snoyer]

Would it be preferable to use the json file at build-time instead of run-time?

1. for the app that would mean either:

• generating the current static inline const std::array<CLIGroup, ...> CLIOptions = {{ lists but from the json instead of written by hand
• generating hardcoded/unrolled cxxopts code directly

2. for the completion files it would mean baking into the scripts whatever strings/commands this PR concatenates together at run-time with python (and then you have only a single hardcoded code path that replaces both the python3 and the _parse_help/grep/sed cases)

However before looking into it too hard I think there's a question about the implications of parsing a json file vs parsing the --help text:

• There are a few options that are behind #ifdef guards, meaning the completion may offer options that are not actually in the binary the user has (unless you somehow drag these condition over to the user and emulate the checks in the completion scripts?)
  That could be addressed by generating the completion strings/commands at build-time making sure to apply the same guards
• I haven't checked if that's actually the case but do we have options that are guarded at run-time? like with env vars or something?
  Because in that case using the binary as the only source of truth, whether it's parsing the help text or adding a dedicated way to generate completions, may be the only solution (short of duplicating the app's logic in the completion scripts)

[mwestphal]

python to parse json is a no-go, and indeed, better to parse at compile time, like we do with options.json.

[mwestphal]

Im afraid design needs to be discussed.

[mwestphal]

remove all unrelated style changes.

[skusel]

remove all unrelated style changes.

I believe you are referring to the stylistic changes made to application/F3DOptionsTools.cxx. These are needed for the formatting checks workflow to complete. Previously, buried in the CLIOptions array initialization, there was a clang-format off comment and no matching clang-format on comment. This disabled clang formatting for the majority of the application/F3DOptionsTools.cxx file. Now that the clang-format off comment has been removed, clang-format caught a bunch of formatting errors.

[mwestphal]

remove all unrelated style changes.

I believe you are referring to the stylistic changes made to application/F3DOptionsTools.cxx. These are needed for the formatting checks workflow to complete. Previously, buried in the CLIOptions array initialization, there was a clang-format off comment and no matching clang-format on comment. This disabled clang formatting for the majority of the application/F3DOptionsTools.cxx file. Now that the clang-format off comment has been removed, clang-format caught a bunch of formatting errors.

You are absolutely right! Do you think you could put these changes in a separate commit (or even PR) ?

[mwestphal]

changes and suggestions