Skip to content

Add --help and --version to rfl::cli through rfl::cli::App - #28

Open
clockblocker wants to merge 1 commit into
wave-base-11from
cli-help-and-version
Open

clockblocker wants to merge 1 commit into
wave-base-11from
cli-help-and-version

Conversation

@clockblocker

@clockblocker clockblocker commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Summary

Adds opt-in --help / -h and --version handling via rfl::cli::App and rfl::cli::read_app, without printing or exiting inside the library.

Related: munich-data-engineering/reflect-cpp#347.

Example

struct Copy {
  rfl::Positional<std::string> src;
  rfl::Positional<std::string> dst;
  rfl::Short<"v", rfl::DefaultVal<bool>> verbose = false;
};

using CopyApp = rfl::cli::App<"copy", "1.2.0", "Copies a file.">;

const auto result = rfl::cli::read_app<Copy, CopyApp>(argc, argv);
if (!result) { /* parse error, as from read */ }
if (const auto* info = std::get_if<rfl::cli::HelpOrVersion>(&*result)) {
  std::cout << info->text;  // detailed usage (with "copy 1.2.0\nCopies a file.") or "copy 1.2.0\n"
  return 0;
}
const Copy& copy = std::get<Copy>(*result);

Key details

  • Opt-in: without App, read and usage are unchanged. Passing App to read is a compile-time error pointing to read_app.
  • Single parse: -h, --help, and --version live in the option table, so -vh, --, NoExtraFields, AllowAbbreviations, and OptionsFirst handle them consistently. Help is returned before struct deserialization (missing required fields don't block --help) and wins over --version.
  • Compile-time clash checks: a field with Short<"h", ...>, help, or version (when version is non-empty) fails to compile; opt out explicitly via rfl::cli::BuiltinHelp::long_only, BuiltinHelp::none, or an empty version string.
  • read_app lives in its own header (rfl/cli/read_app.hpp, included by rfl/cli.hpp) so read.hpp does not pull in usage.hpp.
  • Docs updated in cli.md and README.md.

AI-authored. Depends on: #23, #24, #35 (tests also cover #27, #29–#32).

@clockblocker
clockblocker changed the base branch from wave-base-5 to wave-base-7 November 14, 2026 13:01
@clockblocker
clockblocker force-pushed the cli-help-and-version branch 2 times, most recently from e0d0e69 to 38d3560 Compare November 17, 2026 04:36
@clockblocker
clockblocker changed the base branch from wave-base-7 to wave-base-11 November 17, 2026 04:36
rfl::cli::App<"name", "version", "description"> is a setting that turns
on -h/--help and --version. rfl::cli::read_app, in the new header
rfl/cli/read_app.hpp, reads the struct, or returns an
rfl::cli::HelpOrVersion with the text to print, so callers tell help and
version apart from errors without looking at the message. The help is
returned before the struct is read, so required fields can be missing.

The options are flags in the parser's option table, so grouped short
options (-vh), -- and the other settings treat them like any other:
with rfl::cli::AllowAbbreviations, --hel is the help and --ver is
ambiguous next to --verbose; with rfl::cli::OptionsFirst, --help after
the first positional argument is passed through.

A field that takes their names does not compile: rfl::Short<"h", ...>
wherever it sits among the field's wrappers, a field named help, or one
named version when there is a version. The fourth parameter,
rfl::cli::BuiltinHelp::long_only or ::none, leaves -h or the help out,
and an empty version leaves out --version.

usage shows the rows of the options that read_app handles, and the
detailed form starts with the header. Without the setting, nothing
changes, and read rejects it at compile time, because Result<T> has no
room for a help request. rfl/cli/read.hpp does not include usage.hpp.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant