From 82d687ba466c9472ff0b135cf0f5b609aa011ec0 Mon Sep 17 00:00:00 2001 From: clockblocker Date: Tue, 10 Nov 2026 13:03:17 +0100 Subject: [PATCH 1/4] Accept repeated list options in rfl::cli Repeating an option failed, even for a list: `--report a --report b` gave "Duplicate argument: --report", and `-r a --report b` gave "Conflict: '-r' and '--report' both provided." Boost's composing options, argparse's "extend" and clap's Append accept both. A field that the reader reads as a list (vector-like types, sets, std::array, rfl::Array, C arrays, tuples and pairs, through any wrapper) now takes every occurrence of its option. Each occurrence is split at the commas and the items are added in argv order, so repeating is the same as joining with a comma: - `--report a,b --report c` gives [a, b, c]. - Long, abbreviated and short spellings add to the same list: `-r a --rep b --report=c`. - An empty occurrence (`--report=`) adds no items. - A bare rfl::ImplicitValue list option adds its implicit value, so `--help-reports --help-reports=cpu` gives [all, cpu]. - Nested lists and map entries whose values are lists work the same. Any other option, including nested scalars and map entries, still fails with the same messages as before. The option table marks list options (Option::is_list). parse_argv keeps their first occurrence in `named` under the long name, also for the short spelling, and the later ones, in argv order, in the new ParsedArgs::later_occurrences, so that no separator character is needed and an argument may contain any character. resolve_args with the options now returns internal::ResolvedArgs, the flat map plus the later occurrences, and the Reader splits each occurrence. resolve_args, for arguments parsed without the options, still returns the flat map, and reports a repeated option as a duplicate. Only inputs that used to fail change meaning. test_abbreviation_duplicate also checks that a list adds up. Co-Authored-By: Claude Opus 5.5 --- docs/content/supported_formats/cli.md | 39 +++- include/rfl/cli/Reader.hpp | 54 +++++- include/rfl/cli/options.hpp | 27 ++- include/rfl/cli/parse_argv.hpp | 40 +++- include/rfl/cli/read.hpp | 3 +- include/rfl/cli/resolve_args.hpp | 37 +++- tests/cli/test_abbreviations.cpp | 5 + tests/cli/test_repeated_options.cpp | 261 ++++++++++++++++++++++++++ 8 files changed, 446 insertions(+), 20 deletions(-) create mode 100644 tests/cli/test_repeated_options.cpp diff --git a/docs/content/supported_formats/cli.md b/docs/content/supported_formats/cli.md index d31c3111..50afc76c 100644 --- a/docs/content/supported_formats/cli.md +++ b/docs/content/supported_formats/cli.md @@ -288,6 +288,38 @@ to `false`). negative positionals after `--` (`./app -1 -- -1.5 -10`). An option still takes a negative number as its value (`-n -5`). +## Lists and repeated options + +A field that is read as a list (`std::vector`, `std::set`, `std::deque` and +the like, `std::array`, `rfl::Array`, tuples and pairs, inside any of the +wrappers above) takes comma-separated items. Its option can also be +repeated, like Boost's composing options and argparse's `extend`: every +occurrence is split at the commas, and the items are added in argv order. + +```cpp +struct Config { + rfl::Short<"r", std::vector> report; +}; + +// ./app --report a,b --report c -> report = {"a", "b", "c"} +// ./app -r a --report b --rep=c -> report = {"a", "b", "c"} +``` + +- Long, abbreviated and short spellings of a field all add to it. +- Repeating is the same as joining with a comma, so the size of a + `std::array` and validators such as `rfl::Size` see all items. An empty + occurrence (`--report=`) adds none. +- A bare occurrence of an `rfl::ImplicitValue` list adds its implicit value: + with `rfl::ImplicitValue>, "all">`, + `--help-reports --help-reports=cpu` gives `{"all", "cpu"}`. +- Nested lists (`--database.replicas a --database.replicas b`) and map + entries whose values are lists (`--groups.x a --groups.x b`) work the + same way. + +Any other option can be given only once. That includes nested +fields and map entries: `Duplicate argument: --output`, +`Duplicate short argument: -o`, `Conflict: '-o' and '--output' both provided.` + ## Combining wrappers `Short`, `Positional` and `ImplicitValue` can be nested with each other and @@ -335,7 +367,7 @@ leaving out `-o` gives `"out"`. | `bool` | `--flag` or `--flag=true` | No `=` implies `true` | | `enum` | `--key=value_name` | Via `rfl::string_to_enum` | | `std::optional` | omit for `nullopt` | | -| `std::vector` | `--key=a,b,c` | Comma-separated; empty elements skipped | +| `std::vector` | `--key=a,b,c` or `--key a --key b,c` | Comma-separated; empty elements skipped; [repeatable](#lists-and-repeated-options) | | Nested struct | `--parent.child=val` | Dot-separated path | | `rfl::Flatten` | fields inlined | No prefix needed | | `rfl::Rename<"x", T>` | `--x=val` | Bypasses kebab conversion | @@ -357,7 +389,10 @@ Parsing proceeds in three stages: one short option `abc`, and `-5` the short option `5`. 2. **`resolve_args`** — uses the same table to map short aliases to long names and to merge positional arguments. Produces a flat - `map`. + `map`. A list option given more than once keeps its + first occurrence there and the others, in argv order, beside it. The + public `resolve_args(parsed)`, for arguments parsed + without the table, returns the flat map alone. 3. **`Reader`** — implements reflect-cpp's `IsReader` concept by presenting virtual tree nodes over the flat map. Each node is a `{map*, path}` pair — no data copying, just prefix-based lookup via `lower_bound`. diff --git a/include/rfl/cli/Reader.hpp b/include/rfl/cli/Reader.hpp index 58c16d37..ccee2207 100644 --- a/include/rfl/cli/Reader.hpp +++ b/include/rfl/cli/Reader.hpp @@ -26,6 +26,17 @@ static constexpr char path_separator = '.'; /// Example: `--ports=8080,8081,8082` for an array of ports. static constexpr char array_delimiter = ','; +namespace internal { + +/// The occurrences after the first of the list options given more than +/// once, by path, in argv order. The argument map holds the first one: +/// `--ports 80 --ports 81,82` is held as "80" in the argument map and +/// {"81,82"} here. Each occurrence is split at array_delimiter. +using CliLaterOccurrencesType = + std::map>; + +} // namespace internal + /// Represents a CLI variable that can be a direct value or a path in the argument map. /// The `path` represents the hierarchical key (e.g., "database.host"). /// The `direct_value` is used when parsing array elements directly. @@ -33,6 +44,8 @@ struct CliVarType { const std::map* const args = nullptr; const std::string path; const std::optional direct_value; + /// The later occurrences of repeated list options, if any. + const internal::CliLaterOccurrencesType* const later_occurrences = nullptr; }; /// Represents a CLI object with a prefix path for accessing nested fields. @@ -40,6 +53,8 @@ struct CliVarType { struct CliObjectType { const std::map* const args = nullptr; const std::string prefix; + /// The later occurrences of repeated list options, if any. + const internal::CliLaterOccurrencesType* const later_occurrences = nullptr; }; /// Represents a CLI array containing multiple string values. @@ -167,7 +182,8 @@ struct Reader { const auto child_path = _obj.prefix.empty() ? _name : _obj.prefix + _name; - return InputVarType{_obj.args, child_path, std::nullopt}; + return InputVarType{_obj.args, child_path, std::nullopt, + _obj.later_occurrences}; } /// Checks if a CLI variable is empty (has no value). @@ -240,7 +256,8 @@ struct Reader { const auto child_path = _obj.prefix + child; _object_reader.read( std::string_view(child), - InputVarType{_obj.args, child_path, std::nullopt}); + InputVarType{_obj.args, child_path, std::nullopt, + _obj.later_occurrences}); } ++it; } @@ -261,6 +278,8 @@ struct Reader { } /// Converts a CLI variable to an array by splitting the value on commas. + /// The items of every occurrence of a repeated list option are added in + /// order (see internal::CliLaterOccurrencesType). /// @param _var The CLI variable containing a comma-delimited string /// @return A Result containing a CliArrayType with the split values rfl::Result to_array( @@ -269,7 +288,7 @@ struct Reader { if (!str) { return InputArrayType{{}}; } - return InputArrayType{split(*str, array_delimiter)}; + return InputArrayType{split_items(*str, _var)}; } /// Converts a CLI variable to an object for reading nested fields. @@ -287,7 +306,7 @@ struct Reader { const auto prefix = _var.path.empty() ? std::string("") : _var.path + path_separator; - return InputObjectType{_var.args, prefix}; + return InputObjectType{_var.args, prefix, _var.later_occurrences}; } /// Custom constructors are not supported for CLI parsing. @@ -318,6 +337,33 @@ struct Reader { return it->second; } + /// Splits a list into its items: those of _first, the occurrence that + /// get_value returns for _var, then those of its later occurrences. + static std::vector split_items(const std::string& _first, + const InputVarType& _var) { + std::vector items; + add_items(_first, &items); + if (_var.direct_value || !_var.later_occurrences) { + return items; + } + const auto it = _var.later_occurrences->find(_var.path); + if (it != _var.later_occurrences->end()) { + for (const auto& occurrence : it->second) { + add_items(occurrence, &items); + } + } + return items; + } + + /// Adds the items of one occurrence of a list, split at array_delimiter, + /// to _items. + static void add_items(const std::string& _occurrence, + std::vector* _items) { + for (auto& item : split(_occurrence, array_delimiter)) { + _items->emplace_back(std::move(item)); + } + } + static std::vector split( const std::string& _str, char _delim ) { diff --git a/include/rfl/cli/options.hpp b/include/rfl/cli/options.hpp index 83ab5cc6..3393e400 100644 --- a/include/rfl/cli/options.hpp +++ b/include/rfl/cli/options.hpp @@ -65,6 +65,11 @@ struct Option { /// For OptionKind::implicit_value: the value that the option stands for /// when it is given without one. std::string implicit_value = {}; + + /// Whether the field is a list (see is_option_list_v). Every + /// occurrence of a list option adds to it, however the option is spelled, + /// so it may be repeated. Any other option may be given only once. + bool is_list = false; }; /// The options that a target struct accepts, built from its fields by @@ -419,6 +424,20 @@ using option_fields_t = typename std::conditional_t< rfl::internal::is_named_tuple_v, std::type_identity, rfl::internal::Processed>::type; +/// Whether the reader reads T as a list, through Reader::to_array: vectors, +/// sets, deques and the like, std::array, rfl::Array, C arrays, tuples and +/// pairs. Maps are not lists, even those whose keys are not strings. The +/// value of a list option is split into items at the list delimiter, and +/// repeating the option adds the items of every occurrence, so `--x a --x b` +/// is `--x a,b`. +template +constexpr bool is_option_list_v = + (parsing::is_vector_like_v && !parsing::is_map_like_v + && !parsing::is_bytestring_v && !parsing::is_vectorstring_v) + || parsing::is_array_v || parsing::is_rfl_array_v + || parsing::is_c_array_v || parsing::is_tuple_v + || parsing::is_rfl_tuple_v || parsing::is_pair_v; + /// The option for a field of type T wrapped in rfl::ImplicitValue. template Option implicit_value_option() { @@ -434,7 +453,8 @@ Option implicit_value_option() { "rfl::ImplicitValue on a number needs an implicit value, such " "as rfl::ImplicitValue."); return Option{OptionKind::implicit_value, - std::string(Annotations::implicit_value.string_view())}; + std::string(Annotations::implicit_value.string_view()), + is_option_list_v}; } /// The option for a key of a map or of rfl::ExtraFields with values of @@ -453,7 +473,7 @@ Option sub_key_option() { return Option{OptionKind::other}; } else { - return Option{OptionKind::value}; + return Option{OptionKind::value, "", is_option_list_v}; } } @@ -509,7 +529,8 @@ void add_option(const std::string& _path, Options* _options) { } } else { - _options->long_options[_path] = Option{OptionKind::value}; + _options->long_options[_path] = + Option{OptionKind::value, "", is_option_list_v}; } } diff --git a/include/rfl/cli/parse_argv.hpp b/include/rfl/cli/parse_argv.hpp index 1e7da9f3..a65a2fe2 100644 --- a/include/rfl/cli/parse_argv.hpp +++ b/include/rfl/cli/parse_argv.hpp @@ -74,6 +74,11 @@ inline std::string ambiguous_option_message( /// A long option that matches no field stands for the one long option it /// is a prefix of (`--rep` for `--report`), unless several match, which is /// an error, or `_options.allow_abbreviations` is false. +/// Every occurrence of a list option (Option::is_list) adds to it, however +/// it is spelled: long, abbreviated or short. Its first occurrence is kept +/// in `named` under its long name, and the later ones in +/// `later_occurrences`, in argv order. Any other option given twice is an +/// error. /// Every element of `_args` is parsed; nothing is skipped as the program name. /// @param _args The command-line arguments to parse /// @param _options The options of the target struct (see make_options) @@ -88,8 +93,33 @@ inline rfl::Result parse_string_views( const bool negative_numbers_are_options = _options.negative_numbers_are_options; + // Every occurrence of a list option adds to it. Any other option can be + // given only once. + const auto add_long = [&](std::string _key, std::string _val, + const Option& _option, + std::string_view _raw) -> rfl::Result { + const auto it = result.named.find(_key); + if (it == result.named.end()) { + result.named.emplace(std::move(_key), std::move(_val)); + } + else if (_option.is_list) { + result.later_occurrences[it->first].emplace_back(std::move(_val)); + } + else { + return error("Duplicate argument: " + std::string(_raw)); + } + return true; + }; + const auto add_short = [&](std::string _key, std::string _val, + const Option& _option, std::string_view _raw) -> rfl::Result { + if (_option.is_list) { + // Under its long name, so that `-r a --report b` keeps argv order. A + // short option is only a list if it is in `_options`. + return add_long(_options.short_options.find(_key)->second, + std::move(_val), _option, _raw); + } result.short_order.emplace_back(_key); if (!result.short_args.emplace(std::move(_key), std::move(_val)).second) { return error("Duplicate short argument: " + std::string(_raw)); @@ -191,9 +221,8 @@ inline rfl::Result parse_string_views( result.named_without_value.insert(key); } } - if (!result.named.emplace(std::move(key), std::move(val)).second) { - return error("Duplicate argument: " + std::string(arg_raw)); - } + const auto r = add_long(std::move(key), std::move(val), option, arg_raw); + if (!r) { return error(r.error().what()); } continue; } @@ -256,7 +285,7 @@ inline rfl::Result parse_string_views( + std::string(arg_raw) + "'. Write '" + name + std::string(rest) + "' on its own."); } - const auto r = add_short(std::move(key), "", arg_raw); + const auto r = add_short(std::move(key), "", option, arg_raw); if (!r) { return error(r.error().what()); } continue; } @@ -275,7 +304,8 @@ inline rfl::Result parse_string_views( result.short_without_equals[key] = i != start; } - const auto r = add_short(std::move(key), std::move(val), arg_raw); + const auto r = + add_short(std::move(key), std::move(val), option, arg_raw); if (!r) { return error(r.error().what()); } break; } diff --git a/include/rfl/cli/read.hpp b/include/rfl/cli/read.hpp index 8d5e1e43..99bbbf62 100644 --- a/include/rfl/cli/read.hpp +++ b/include/rfl/cli/read.hpp @@ -30,7 +30,8 @@ rfl::Result parse_and_read(const ParseFn& _parse) { }) .and_then([](auto _args) -> rfl::Result { const auto r = Reader(); - const auto var = CliVarType{&_args, "", std::nullopt}; + const auto var = CliVarType{&_args.values, "", std::nullopt, + &_args.later_occurrences}; return Parser::read(r, var); }); } diff --git a/include/rfl/cli/resolve_args.hpp b/include/rfl/cli/resolve_args.hpp index 36cd3f30..567512e2 100644 --- a/include/rfl/cli/resolve_args.hpp +++ b/include/rfl/cli/resolve_args.hpp @@ -16,6 +16,10 @@ namespace rfl::cli { /// Holds the parsed command-line arguments categorized by type. /// Used as an intermediate structure before resolving to a flat key-value map. struct ParsedArgs { + /// The long options, by name. A list option is held here under its long + /// name however it is spelled, also as a short option. If it is given + /// more than once, this holds its first occurrence, and + /// `later_occurrences` the others. std::map named; std::map short_args; std::vector positional; @@ -26,10 +30,22 @@ struct ParsedArgs { /// The keys of `short_args` given without '=' (`-h`, `-h x`), and whether /// they took the next token as their value. std::map short_without_equals; + /// The occurrences after the first of each list option given more than + /// once, by long name, in argv order. + internal::CliLaterOccurrencesType later_occurrences; }; namespace internal { +/// The arguments resolved to the paths of their fields, which Reader reads. +struct ResolvedArgs { + /// The value of each field. For a list given more than once, its first + /// occurrence. + std::map values; + /// The occurrences after the first of each list given more than once. + CliLaterOccurrencesType later_occurrences; +}; + /// Applies what parse_argv could not know without the option table. /// Without it, every short option takes the next token, so `-v somefile` /// makes "somefile" the value of -v. If -v is a bool flag (by its type once @@ -102,8 +118,9 @@ inline rfl::Result check_short_names(const Options& _options) { /// The caller checks the short names first (check_short_names). /// @param _parsed The arguments, parsed by parse_argv with the same options /// @param _options The options of the target struct (see make_options) -/// @return A Result containing a flat map of field names to values or an error -inline rfl::Result> resolve_args( +/// @return A Result containing the values of the fields, by path, or an +/// error +inline rfl::Result resolve_args( ParsedArgs _parsed, const Options& _options ) { auto& result = _parsed.named; @@ -143,7 +160,8 @@ inline rfl::Result> resolve_args( result.emplace(long_name, std::move(value)); } - return std::move(result); + return ResolvedArgs{std::move(result), + std::move(_parsed.later_occurrences)}; } } // namespace internal @@ -153,7 +171,9 @@ inline rfl::Result> resolve_args( /// of T, but for arguments parsed by parse_argv without them: values that /// boolean and rfl::ImplicitValue short options took from the next token /// are returned to the positional arguments, and rfl::ImplicitValue -/// options given without a value get their implicit value. +/// options given without a value get their implicit value. A flat map +/// cannot hold the occurrences of a repeated list option, which parse_argv +/// without the options rejects. /// @tparam T The target struct type /// @tparam ProcessorsType The processors applied to the struct /// @param _parsed The parsed command-line arguments @@ -162,13 +182,20 @@ template rfl::Result> resolve_args( ParsedArgs _parsed ) { + if (!_parsed.later_occurrences.empty()) { + return rfl::error("Duplicate argument: --" + + _parsed.later_occurrences.begin()->first); + } const auto options = internal::make_options(); const auto short_names = internal::check_short_names(options); if (!short_names) { return rfl::error(short_names.error().what()); } internal::apply_option_kinds(options, &_parsed); - return internal::resolve_args(std::move(_parsed), options); + return internal::resolve_args(std::move(_parsed), options) + .transform([](internal::ResolvedArgs _args) { + return std::move(_args.values); + }); } } // namespace rfl::cli diff --git a/tests/cli/test_abbreviations.cpp b/tests/cli/test_abbreviations.cpp index 9e62f42b..162a4298 100644 --- a/tests/cli/test_abbreviations.cpp +++ b/tests/cli/test_abbreviations.cpp @@ -186,6 +186,11 @@ TEST(cli, test_abbreviation_duplicate) { const auto both_short = read({"--format-v=a", "--format-ver", "b"}); EXPECT_EQ(error_of(both_short), "Duplicate argument: --format-ver"); + + // A list option adds the values of every spelling. + const auto list = read({"--rep=a", "--report=b", "--re", "c"}); + ASSERT_TRUE(list) << list.error().what(); + EXPECT_EQ(list.value().report, (std::vector{"a", "b", "c"})); } TEST(cli, test_abbreviation_missing_value_names_the_option) { diff --git a/tests/cli/test_repeated_options.cpp b/tests/cli/test_repeated_options.cpp new file mode 100644 index 00000000..34984b93 --- /dev/null +++ b/tests/cli/test_repeated_options.cpp @@ -0,0 +1,261 @@ +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace test_repeated_options { + +template +rfl::Result read(std::vector _args) { + _args.insert(_args.begin(), "program"); + return rfl::cli::read(static_cast(_args.size()), + const_cast(_args.data())); +} + +template +std::string error_of(const rfl::Result& _result) { + return _result ? std::string("(no error)") + : std::string(_result.error().what()); +} + +using Strings = std::vector; + +struct Database { + std::optional host; + std::optional replicas; +}; + +struct Opts { + rfl::Short<"r", std::optional> report; + std::optional> ports; + std::optional> tags; + std::optional> queue; + std::optional> rgb; + std::optional> range; + rfl::Short<"o", std::optional> output; + std::optional level; + rfl::Short<"q", std::optional> quiet; + std::optional database; + std::optional> labels; + std::optional> groups; + rfl::ImplicitValue, "all"> help_reports; + rfl::Positional> input; +}; + +TEST(cli, test_repeated_long_option_appends) { + for (const auto& args : std::vector>{ + {"--report", "a", "--report", "b", "--report", "c"}, + {"--report=a", "--report=b", "--report=c"}, + {"--report", "a,b", "--report", "c"}, + {"--report=a", "--report", "b,c"}}) { + const auto result = read(args); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().report(), (Strings{"a", "b", "c"})); + } +} + +TEST(cli, test_repeated_short_and_long_merge_in_argv_order) { + const auto result = + read({"-r", "a", "--report", "b", "-r=c", "-rd", "--report=e"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().report(), (Strings{"a", "b", "c", "d", "e"})); +} + +TEST(cli, test_repeated_short_list_in_a_cluster) { + // -q is a flag, so -qra is -q -r a. + const auto result = read({"-qra", "-r", "b", "in.txt"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().quiet(), true); + EXPECT_EQ(result.value().report(), (Strings{"a", "b"})); + EXPECT_EQ(result.value().input(), "in.txt"); + + // The flag is still given only once. + EXPECT_EQ(error_of(read({"-qra", "-qrb"})), + "Duplicate short argument: -qrb"); +} + +TEST(cli, test_repeated_abbreviations_merge) { + const auto result = + read({"--rep", "a", "--report", "b", "--repo=c", "-r", "d"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().report(), (Strings{"a", "b", "c", "d"})); +} + +TEST(cli, test_repeated_other_list_types) { + const auto result = read( + {"--ports", "80", "--ports=81,82", "--tags", "b", "--tags", "a,b", + "--queue", "x", "--queue", "y", "--rgb", "1", "--rgb", "2,3", + "--range", "5", "--range", "five"}); + ASSERT_TRUE(result) << result.error().what(); + const auto& o = result.value(); + EXPECT_EQ(o.ports, (std::vector{80, 81, 82})); + EXPECT_EQ(o.tags, (std::set{"a", "b"})); + EXPECT_EQ(o.queue, (std::deque{"x", "y"})); + EXPECT_EQ(o.rgb, (std::array{1, 2, 3})); + EXPECT_EQ(o.range, (std::pair{5, "five"})); +} + +TEST(cli, test_repeated_fixed_size_checked_on_all_items) { + // Repeating is the same as joining with ',': the size is checked once. + EXPECT_EQ(error_of(read({"--rgb", "1", "--rgb", "2"})), + error_of(read({"--rgb=1,2"}))); + EXPECT_NE(error_of(read({"--rgb=1,2"})), "(no error)"); +} + +TEST(cli, test_repeated_empty_occurrence_adds_nothing) { + const auto some = read({"--report=a", "--report=", "--report=b"}); + ASSERT_TRUE(some) << some.error().what(); + EXPECT_EQ(some.value().report(), (Strings{"a", "b"})); + + const auto none = read({"--report=", "--report="}); + ASSERT_TRUE(none) << none.error().what(); + EXPECT_EQ(none.value().report(), Strings{}); +} + +TEST(cli, test_repeated_nested_list) { + const auto result = read({"--database.replicas", "a", + "--database.replicas=b,c", + "--database.host=db"}); + ASSERT_TRUE(result) << result.error().what(); + ASSERT_TRUE(result.value().database); + EXPECT_EQ(result.value().database->replicas, (Strings{"a", "b", "c"})); + EXPECT_EQ(result.value().database->host, "db"); +} + +TEST(cli, test_repeated_map_entry_list) { + const auto result = read( + {"--groups.x", "a", "--groups.y=c", "--groups.x=b"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().groups, + (std::map{{"x", {"a", "b"}}, {"y", {"c"}}})); +} + +TEST(cli, test_repeated_scalar_errors) { + EXPECT_EQ(error_of(read({"--output", "a", "--output", "b"})), + "Duplicate argument: --output"); + EXPECT_EQ(error_of(read({"--level=1", "--lev=2"})), + "Duplicate argument: --lev=2"); + EXPECT_EQ(error_of(read({"-o", "a", "-o", "b"})), + "Duplicate short argument: -o"); + EXPECT_EQ(error_of(read({"-o", "a", "--output=b"})), + "Conflict: '-o' and '--output' both provided."); + EXPECT_EQ(error_of(read({"--quiet", "--quiet"})), + "Duplicate argument: --quiet"); + EXPECT_EQ(error_of(read({"x", "--input=y"})), + "Conflict: positional argument and '--input' both provided."); +} + +TEST(cli, test_repeated_nested_scalar_and_map_key_error) { + EXPECT_EQ( + error_of(read({"--database.host=a", "--database.host", "b"})), + "Duplicate argument: --database.host"); + EXPECT_EQ(error_of(read({"--labels.env=a", "--labels.env=b"})), + "Duplicate argument: --labels.env=b"); + + const auto two_keys = read({"--labels.env=a", "--labels.os=b"}); + ASSERT_TRUE(two_keys) << two_keys.error().what(); + EXPECT_EQ(two_keys.value().labels, + (std::map{{"env", "a"}, {"os", "b"}})); +} + +TEST(cli, test_repeated_implicit_value_list) { + // A bare occurrence adds the implicit value, split like any other value. + const auto bare = read({"--help-reports"}); + ASSERT_TRUE(bare) << bare.error().what(); + EXPECT_EQ(bare.value().help_reports(), (Strings{"all"})); + + const auto mixed = read( + {"--help-reports=cpu", "--help-reports", "--help-rep=gpu,mem"}); + ASSERT_TRUE(mixed) << mixed.error().what(); + EXPECT_EQ(mixed.value().help_reports(), (Strings{"cpu", "all", "gpu", "mem"})); + + // It still never takes the next token. + const auto next = read({"--help-reports", "in.txt"}); + ASSERT_TRUE(next) << next.error().what(); + EXPECT_EQ(next.value().help_reports(), (Strings{"all"})); + EXPECT_EQ(next.value().input(), "in.txt"); + + const auto absent = read({}); + ASSERT_TRUE(absent) << absent.error().what(); + EXPECT_FALSE(absent.value().help_reports().has_value()); +} + +TEST(cli, test_repeated_with_no_extra_fields) { + const auto result = read( + {"--report", "a", "-r", "b"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().report(), (Strings{"a", "b"})); + + EXPECT_EQ(error_of(read({"--nope=1", "--nope=2"})), + "Unknown option '--nope'."); + // Without NoExtraFields, an unknown option is ignored, but may be given + // only once. + EXPECT_EQ(error_of(read({"--nope=1", "--nope=2"})), + "Duplicate argument: --nope=2"); +} + +struct Wrapped { + rfl::Description<"Files to include", + rfl::DefaultVal>> + include; + rfl::Rename<"L", std::optional>> lib_dirs; + rfl::Validator, rfl::Size>> pair; +}; + +TEST(cli, test_repeated_through_wrappers) { + const auto result = read( + {"--include", "a.h", "--include=b.h", "--L", "/x", "--L", "/y", + "--pair", "1", "--pair", "2"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().include().value(), (Strings{"a.h", "b.h"})); + EXPECT_EQ(result.value().lib_dirs(), (Strings{"/x", "/y"})); + EXPECT_EQ(result.value().pair.value(), (std::vector{1, 2})); + + // The validator sees every item. + EXPECT_NE(error_of(read({"--pair", "1", "--pair", "2,3"})), + "(no error)"); +} + +TEST(cli, test_repeated_occurrences_in_parsed_args) { + // The occurrences of a list option are held under its long name, + // the first in `named` and the others in `later_occurrences`. + const auto options = rfl::cli::internal::make_options< + Opts, rfl::Processors>(); + std::vector args = {"program", "-r", "a,b", "--report", "c"}; + const auto parsed = rfl::cli::internal::parse_argv( + static_cast(args.size()), const_cast(args.data()), options); + ASSERT_TRUE(parsed) << parsed.error().what(); + EXPECT_EQ(parsed.value().named.at("report"), "a,b"); + EXPECT_EQ(parsed.value().later_occurrences.at("report"), Strings{"c"}); + EXPECT_TRUE(parsed.value().short_args.empty()); + + // The flat map of resolve_args cannot hold them. + const auto resolved = rfl::cli::resolve_args< + Opts, rfl::Processors>(parsed.value()); + EXPECT_EQ(error_of(resolved), "Duplicate argument: --report"); +} + +TEST(cli, test_repeated_occurrences_keep_embedded_nul) { + // The occurrences are kept apart, not joined with a separator, so an + // argument that contains '\0', which the range overload can pass, is + // not split there. + const auto result = rfl::cli::read(std::vector{ + std::string("--report=a\0b", 12), "--report", "c"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().report(), (Strings{std::string("a\0b", 3), "c"})); + + const auto once = rfl::cli::read( + std::vector{std::string("--report=a\0b,c", 14)}); + ASSERT_TRUE(once) << once.error().what(); + EXPECT_EQ(once.value().report(), (Strings{std::string("a\0b", 3), "c"})); +} + +} // namespace test_repeated_options From 5142cd03b430a387dc28ce0d05c903c418d68abc Mon Sep 17 00:00:00 2001 From: clockblocker Date: Tue, 10 Nov 2026 13:08:08 +0100 Subject: [PATCH 2/4] Let a list as the last positional field take the remaining arguments With `rfl::Positional command;` and `rfl::Positional> files;`, `app run a b` failed with "Too many positional arguments: expected at most 2, got 3." A list took exactly one argument, split at the commas. If the last positional field is a list, it now takes every positional argument after those of the other positional fields, like argparse's nargs='+' and clap's num_args(1..). Each argument is split at the commas, as one occurrence of the list, so this is backward compatible: `app run a,b` still gives [a, b], `app run a b` gives [a, b], and `app run a,b c` gives [a, b, c]. - A plain list needs at least one argument ("Field named 'files' not found."). With std::optional or rfl::DefaultVal, no argument gives std::nullopt or the default, like nargs='*'. - Options can still come anywhere, as for any positional field. - The long form works as for any list, `--files=a,b` or `--files a --files b`, and cannot be mixed with bare arguments: "Conflict: positional argument and '--files' both provided." - Only the last positional field takes the remaining arguments. A list before other positional fields (a vector, set, pair, std::array and the like) takes one argument, split at the commas, as before. "Last" is in the order of Options::positionals: outermost Positional fields first, then those found through other wrappers, so std::optional>> declared first is last. Options::last_positional_is_list tells resolve_args, which adds the remaining arguments to the list as later occurrences. resolve_args, for arguments parsed without the options, cannot hold repeated lists, so there each positional field still takes one argument. Co-Authored-By: Claude Opus 5.5 --- docs/content/supported_formats/cli.md | 34 ++- include/rfl/cli/options.hpp | 10 +- include/rfl/cli/resolve_args.hpp | 35 +++- tests/cli/test_list_positional.cpp | 286 ++++++++++++++++++++++++++ 4 files changed, 355 insertions(+), 10 deletions(-) create mode 100644 tests/cli/test_list_positional.cpp diff --git a/docs/content/supported_formats/cli.md b/docs/content/supported_formats/cli.md index 50afc76c..a498be33 100644 --- a/docs/content/supported_formats/cli.md +++ b/docs/content/supported_formats/cli.md @@ -320,6 +320,38 @@ Any other option can be given only once. That includes nested fields and map entries: `Duplicate argument: --output`, `Duplicate short argument: -o`, `Conflict: '-o' and '--output' both provided.` +### A list as the last positional argument + +If the last positional field is a list, it takes all remaining positional +arguments (last in the order of [Combining wrappers](#combining-wrappers), +which is declaration order unless some `Positional`s are wrapped), like +argparse's `nargs='+'` (or `'*'` if it is optional), and each argument is +split at the commas: + +```cpp +struct Config { + rfl::Positional command; + rfl::Positional> files; +}; + +// ./app run a,b -> files = {"a", "b"} +// ./app run a b -> files = {"a", "b"} +// ./app run a,b c -> files = {"a", "b", "c"} +``` + +- A plain list needs at least one argument. With `std::optional` or + `rfl::DefaultVal`, no arguments give `std::nullopt` or the default. +- Options can still come anywhere: `./app run a --verbose b`. +- The long form works as for any list: `--files=a,b`, or + `--files a --files b`. It cannot be mixed with bare arguments: + `Conflict: positional argument and '--files' both provided.` +- Only the last positional field takes the remaining arguments. A list + before other positional fields, such as `std::vector`, `std::set`, a + pair or a `std::array`, takes one argument, split at the commas. +- `resolve_args`, for arguments parsed without the + option table, cannot repeat list options, so there a list as the last + positional field takes one argument. + ## Combining wrappers `Short`, `Positional` and `ImplicitValue` can be nested with each other and @@ -371,7 +403,7 @@ leaving out `-o` gives `"out"`. | Nested struct | `--parent.child=val` | Dot-separated path | | `rfl::Flatten` | fields inlined | No prefix needed | | `rfl::Rename<"x", T>` | `--x=val` | Bypasses kebab conversion | -| `rfl::Positional` | bare token | Matched in declaration order | +| `rfl::Positional` | bare token | Matched in declaration order; a list last takes the rest | | `rfl::Short<"x", T>` | `-x value`, `-x=value` or `-xvalue` | Single-character alias, can be grouped (`-qv`) | | `rfl::ImplicitValue` | `--key` or `--key=value` | Bare means `x` | diff --git a/include/rfl/cli/options.hpp b/include/rfl/cli/options.hpp index 3393e400..3e9cb89b 100644 --- a/include/rfl/cli/options.hpp +++ b/include/rfl/cli/options.hpp @@ -88,7 +88,9 @@ struct Options { /// The paths of the rfl::Positional fields: first those whose outermost /// wrapper is rfl::Positional, then those where it is found through other - /// wrappers, each in declaration order. + /// wrappers, each in declaration order. Each takes one positional + /// argument, except that a list as the last one takes the remaining + /// positional arguments (see last_positional_is_list). std::vector positionals; /// Prefixes (ending in path_separator, or empty for the root) under which @@ -149,6 +151,12 @@ struct Options { return names; } + /// Whether the last rfl::Positional field is a list. It then takes every + /// positional argument after those of the other positional fields. + bool last_positional_is_list() const { + return !positionals.empty() && find_long(positionals.back()).is_list; + } + /// Returns the long option `--_name`. Option find_long(const std::string& _name) const { const auto it = long_options.find(_name); diff --git a/include/rfl/cli/resolve_args.hpp b/include/rfl/cli/resolve_args.hpp index 567512e2..93cdb0cf 100644 --- a/include/rfl/cli/resolve_args.hpp +++ b/include/rfl/cli/resolve_args.hpp @@ -109,10 +109,19 @@ inline rfl::Result check_short_names(const Options& _options) { return true; } +/// The error for more positional arguments than positional fields. +inline rfl::Unexpected too_many_positionals(const size_t _expected, + const size_t _got) { + return rfl::error("Too many positional arguments: expected at most " + + std::to_string(_expected) + ", got " + + std::to_string(_got) + "."); +} /// Resolves ParsedArgs into a flat key-value map using the options of the /// target struct. /// This function: /// 1. Maps positional arguments to their corresponding field names based on declaration order +/// If the last positional field is a list, it takes all remaining +/// positional arguments, as later occurrences of the list. /// 2. Expands short arguments (e.g., -p) to long names (e.g., --port) using Short<> annotations /// 3. Detects conflicts between different ways of specifying the same field /// The caller checks the short names first (check_short_names). @@ -127,15 +136,19 @@ inline rfl::Result resolve_args( // Merge positional args. const auto& positional_names = _options.positionals; - if (_parsed.positional.size() > positional_names.size()) { - auto msg = std::string("Too many positional arguments: expected at most "); - msg += std::to_string(positional_names.size()); - msg += ", got "; - msg += std::to_string(_parsed.positional.size()); - msg += "."; - return rfl::error(std::move(msg)); + if (_parsed.positional.size() > positional_names.size() + && !_options.last_positional_is_list()) { + return internal::too_many_positionals(positional_names.size(), + _parsed.positional.size()); } for (size_t i = 0; i < _parsed.positional.size(); ++i) { + if (i >= positional_names.size()) { + // A list as the last positional field takes the rest, one occurrence + // per argument. + _parsed.later_occurrences[positional_names.back()].emplace_back( + std::move(_parsed.positional[i])); + continue; + } const auto& long_name = positional_names[i]; if (result.count(long_name)) { return rfl::error( @@ -173,7 +186,9 @@ inline rfl::Result resolve_args( /// are returned to the positional arguments, and rfl::ImplicitValue /// options given without a value get their implicit value. A flat map /// cannot hold the occurrences of a repeated list option, which parse_argv -/// without the options rejects. +/// without the options rejects, so a list as the last positional field does +/// not take the remaining positional arguments here either: each positional +/// field takes one. /// @tparam T The target struct type /// @tparam ProcessorsType The processors applied to the struct /// @param _parsed The parsed command-line arguments @@ -192,6 +207,10 @@ rfl::Result> resolve_args( return rfl::error(short_names.error().what()); } internal::apply_option_kinds(options, &_parsed); + if (_parsed.positional.size() > options.positionals.size()) { + return internal::too_many_positionals(options.positionals.size(), + _parsed.positional.size()); + } return internal::resolve_args(std::move(_parsed), options) .transform([](internal::ResolvedArgs _args) { return std::move(_args.values); diff --git a/tests/cli/test_list_positional.cpp b/tests/cli/test_list_positional.cpp new file mode 100644 index 00000000..05d99d9e --- /dev/null +++ b/tests/cli/test_list_positional.cpp @@ -0,0 +1,286 @@ +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace test_list_positional { + +template +rfl::Result read(std::vector _args) { + _args.insert(_args.begin(), "program"); + return rfl::cli::read(static_cast(_args.size()), + const_cast(_args.data())); +} + +template +std::string error_of(const rfl::Result& _result) { + return _result ? std::string("(no error)") + : std::string(_result.error().what()); +} + +using Strings = std::vector; + +struct Cmd { + rfl::Short<"v", std::optional> verbose; + rfl::Short<"l", std::optional> level; + rfl::Positional command; + rfl::Positional files; +}; + +TEST(cli, test_list_positional_takes_remaining_arguments) { + // Each argument is split at the commas. + for (const auto& [args, expected] : + std::vector, Strings>>{ + {{"run", "a,b"}, {"a", "b"}}, + {{"run", "a", "b"}, {"a", "b"}}, + {{"run", "a,b", "c"}, {"a", "b", "c"}}, + {{"run", "a", "b,c", "d"}, {"a", "b", "c", "d"}}}) { + const auto result = read(args); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().command(), "run"); + EXPECT_EQ(result.value().files(), expected); + } +} + +TEST(cli, test_list_positional_mixed_with_options) { + // Without rfl::cli::OptionsFirst, options can come anywhere. + const auto result = read({"run", "a", "-v", "b", "--level", "3", "c"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().verbose(), true); + EXPECT_EQ(result.value().level(), 3); + EXPECT_EQ(result.value().files(), (Strings{"a", "b", "c"})); + + const auto cluster = read({"run", "a", "-vl3", "b"}); + ASSERT_TRUE(cluster) << cluster.error().what(); + EXPECT_EQ(cluster.value().verbose(), true); + EXPECT_EQ(cluster.value().level(), 3); + EXPECT_EQ(cluster.value().files(), (Strings{"a", "b"})); +} + +TEST(cli, test_list_positional_after_double_dash) { + const auto result = read({"-v", "--", "run", "-x", "--y=1", "--"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().command(), "run"); + EXPECT_EQ(result.value().files(), (Strings{"-x", "--y=1", "--"})); +} + +struct Numbers { + rfl::Positional> n; +}; + +TEST(cli, test_list_positional_negative_numbers) { + const auto result = read({"1", "-2", "3,-4"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().n(), (std::vector{1, -2, 3, -4})); +} + +TEST(cli, test_list_positional_required_absent) { + // A plain list needs at least one argument, like argparse's nargs='+'. + EXPECT_EQ(error_of(read({"run"})), "Field named 'files' not found."); + + // An empty argument is an empty list, as `--files=` is. + const auto empty = read({"run", ""}); + ASSERT_TRUE(empty) << empty.error().what(); + EXPECT_EQ(empty.value().files(), Strings{}); +} + +struct Defaults { + rfl::Positional> first; + rfl::DefaultVal>> rest = + std::vector{7, 8}; +}; + +struct Optional { + rfl::Positional>> ids; +}; + +TEST(cli, test_list_positional_default_and_optional) { + const auto none = read({}); + ASSERT_TRUE(none) << none.error().what(); + EXPECT_FALSE(none.value().first().has_value()); + EXPECT_EQ(none.value().rest.value()(), (std::vector{7, 8})); + + const auto one = read({"x"}); + ASSERT_TRUE(one) << one.error().what(); + EXPECT_EQ(one.value().first(), "x"); + EXPECT_EQ(one.value().rest.value()(), (std::vector{7, 8})); + + const auto three = read({"x", "1", "2,3"}); + ASSERT_TRUE(three) << three.error().what(); + EXPECT_EQ(three.value().rest.value()(), (std::vector{1, 2, 3})); + + const auto absent = read({}); + ASSERT_TRUE(absent) << absent.error().what(); + EXPECT_FALSE(absent.value().ids().has_value()); + + const auto ids = read({"3", "1,3", "2"}); + ASSERT_TRUE(ids) << ids.error().what(); + EXPECT_EQ(ids.value().ids(), (std::set{1, 2, 3})); +} + +TEST(cli, test_list_positional_long_form) { + const auto equals = read({"run", "--files=a,b"}); + ASSERT_TRUE(equals) << equals.error().what(); + EXPECT_EQ(equals.value().files(), (Strings{"a", "b"})); + + const auto repeated = + read({"--files", "a", "run", "--fil=b,c", "--files", "d"}); + ASSERT_TRUE(repeated) << repeated.error().what(); + EXPECT_EQ(repeated.value().command(), "run"); + EXPECT_EQ(repeated.value().files(), (Strings{"a", "b", "c", "d"})); + + // Bare arguments and the long form are not mixed. + EXPECT_EQ(error_of(read({"run", "--files=a", "b"})), + "Conflict: positional argument and '--files' both provided."); +} + +TEST(cli, test_list_positional_with_no_extra_fields) { + const auto ok = read({"run", "a", "-v", "b"}); + ASSERT_TRUE(ok) << ok.error().what(); + EXPECT_EQ(ok.value().files(), (Strings{"a", "b"})); + + EXPECT_EQ(error_of(read({"run", "a", "--nope"})), + "Unknown option '--nope'."); +} + +struct Two { + rfl::Positional input; + rfl::Positional output; +}; + +TEST(cli, test_list_positional_scalar_last_overflows) { + EXPECT_EQ(error_of(read({"a", "b", "c"})), + "Too many positional arguments: expected at most 2, got 3."); +} + +TEST(cli, test_list_positional_without_option_table) { + // parse_argv without the option table cannot repeat list options, so + // resolve_args does not let a list take the remaining arguments + // either: each positional field takes one argument. + using P = rfl::Processors; + const auto resolve = [](std::vector _args) { + _args.insert(_args.begin(), "program"); + return rfl::cli::parse_argv(static_cast(_args.size()), + const_cast(_args.data())) + .and_then(rfl::cli::resolve_args); + }; + + // -v takes "run", and resolve_args returns it to the positional + // arguments, in argv order. + const auto resolved = resolve({"-v", "run", "a,b"}); + ASSERT_TRUE(resolved) << resolved.error().what(); + EXPECT_EQ(resolved.value().at("command"), "run"); + EXPECT_EQ(resolved.value().at("files"), "a,b"); + + EXPECT_EQ(error_of(resolve({"-v", "run", "a", "b"})), + "Too many positional arguments: expected at most 2, got 3."); +} + +struct PairFirst { + rfl::Positional> range; + rfl::Positional> names; + rfl::Positional>> extra; + rfl::Positional last; +}; + +TEST(cli, test_list_positional_fixed_size_not_last) { + // Pairs, tuples and std::array have a fixed size, so they can come + // before other positional fields. Each takes one argument, split at the + // commas. + const auto result = read({"1,2", "a,b", "3,true", "x"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().range(), (std::pair{1, 2})); + EXPECT_EQ(result.value().names(), (std::array{"a", "b"})); + EXPECT_EQ(result.value().extra(), (std::tuple{3, true})); + EXPECT_EQ(result.value().last(), "x"); + + EXPECT_EQ(error_of(read({"1", "2", "a,b", "3,true", "x"})), + "Too many positional arguments: expected at most 4, got 5."); +} + +struct ListFirst { + rfl::Positional files; + rfl::Positional dest; +}; + +struct ListInTheMiddle { + rfl::Positional a; + rfl::Positional> b; + std::optional flag; + rfl::Positional> c; +}; + +struct SetFirst { + rfl::Positional> ids; + rfl::Positional dest; +}; + +TEST(cli, test_list_positional_not_last_takes_one_argument) { + // A list that is not the last positional field takes one argument, split + // at the commas. + const auto first = read({"a,b", "d"}); + ASSERT_TRUE(first) << first.error().what(); + EXPECT_EQ(first.value().files(), (Strings{"a", "b"})); + EXPECT_EQ(first.value().dest(), "d"); + EXPECT_EQ(error_of(read({"a", "b", "d"})), + "Too many positional arguments: expected at most 2, got 3."); + EXPECT_EQ(error_of(read({"a"})), "Field named 'dest' not found."); + + const auto middle = read({"x", "1,2", "--flag", "y"}); + ASSERT_TRUE(middle) << middle.error().what(); + EXPECT_EQ(middle.value().a(), "x"); + EXPECT_EQ(middle.value().b(), (Strings{"1", "2"})); + EXPECT_EQ(middle.value().c(), "y"); + EXPECT_EQ(error_of(read({"x", "1", "2", "y"})), + "Too many positional arguments: expected at most 3, got 4."); + + const auto set = read({"3,1", "d"}); + ASSERT_TRUE(set) << set.error().what(); + EXPECT_EQ(set.value().ids(), (std::set{1, 3})); + EXPECT_EQ(set.value().dest(), "d"); +} + +struct ListLastAmongOptions { + rfl::Positional a; + rfl::Positional b; + std::optional not_positional; +}; + +TEST(cli, test_list_positional_last_among_options) { + // Only the last positional field takes the remaining arguments; a list + // option that is not positional does not. + const auto result = read( + {"x", "p", "--not-positional=n,m", "q,r"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().a(), "x"); + EXPECT_EQ(result.value().b(), (Strings{"p", "q", "r"})); + EXPECT_EQ(result.value().not_positional, (Strings{"n", "m"})); +} + +// A Positional found through other wrappers comes after the outermost ones, +// so a wrapped list declared first is the last positional field. +struct WrappedListFirst { + std::optional> files; + rfl::Positional command; +}; + +TEST(cli, test_list_positional_wrapped_list_comes_last) { + const auto result = read({"run", "a", "b,c"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().command(), "run"); + EXPECT_EQ(result.value().files.value().value(), (Strings{"a", "b", "c"})); + + const auto alone = read({"run"}); + ASSERT_TRUE(alone) << alone.error().what(); + EXPECT_EQ(alone.value().command(), "run"); + EXPECT_FALSE(alone.value().files.has_value()); +} + +} // namespace test_list_positional From 1fb2d88fcdf6ebb6e455b8e76f33bef880cb38bf Mon Sep 17 00:00:00 2001 From: clockblocker Date: Tue, 10 Nov 2026 13:11:44 +0100 Subject: [PATCH 3/4] Add rfl::cli::ListDelimiter to change or turn off list splitting rfl::cli always split list values at commas, so an item could not contain one, and a pass-through argument such as `a,b` became two items. ListDelimiter<";"> splits at ';' instead, and ListDelimiter<""> does not split: each occurrence of a list option, and each positional argument of a list, is then exactly one item, even if it is empty. The setting applies to every list option and list positional of the struct, as ',' did. Fields that are not lists are never split. The delimiter is a single ASCII character, which a static_assert checks. clap's value_delimiter and CLI11's delimiter take a char too, and a longer delimiter would make values such as "a;;;b" with ";;" ambiguous. A list whose items contain any character can use ListDelimiter<""> and repeat the option. Like rfl::cli::NoAbbreviations it is a processor that only rfl::cli::read looks at: read passes it to the Reader, which splits each occurrence with it. Other formats ignore it, and a test checks that rfl::json::write, read and to_schema give the same results with it. Co-Authored-By: Claude Opus 5.5 --- docs/content/supported_formats/cli.md | 24 ++++ include/rfl/cli.hpp | 1 + include/rfl/cli/ListDelimiter.hpp | 91 +++++++++++++++ include/rfl/cli/Reader.hpp | 77 +++++++----- include/rfl/cli/read.hpp | 13 ++- tests/cli/test_list_delimiter.cpp | 161 ++++++++++++++++++++++++++ 6 files changed, 333 insertions(+), 34 deletions(-) create mode 100644 include/rfl/cli/ListDelimiter.hpp create mode 100644 tests/cli/test_list_delimiter.cpp diff --git a/docs/content/supported_formats/cli.md b/docs/content/supported_formats/cli.md index a498be33..c8e75e50 100644 --- a/docs/content/supported_formats/cli.md +++ b/docs/content/supported_formats/cli.md @@ -320,6 +320,29 @@ Any other option can be given only once. That includes nested fields and map entries: `Duplicate argument: --output`, `Duplicate short argument: -o`, `Conflict: '-o' and '--output' both provided.` +### List delimiter + +`rfl::cli::ListDelimiter<"x">` splits lists at another character, and +`rfl::cli::ListDelimiter<"">` does not split them at all: + +```cpp +rfl::cli::read>(argc, argv); +// ./app --report 'a;b' --report c,d -> report = {"a", "b", "c,d"} + +rfl::cli::read>(argc, argv); +// ./app --report a,b --report '' -> report = {"a,b", ""} +``` + +- The delimiter is a single ASCII character, such as `;`, `:` or a space, + as in clap and CLI11. A longer one would make values such as `a;;;b` + ambiguous; repeat the option instead. +- It applies to every list option and list positional argument of the + struct. Other fields are never split. +- Without a delimiter, each occurrence, and each positional argument, is + exactly one item, even if it is empty. +- Other formats ignore it: `rfl::json::write`, `rfl::json::read` and + `rfl::json::to_schema` give the same results with it. + ### A list as the last positional argument If the last positional field is a list, it takes all remaining positional @@ -437,6 +460,7 @@ Parsing proceeds in three stages: - `include/rfl/cli/parse_argv.hpp` — `argv` -> `ParsedArgs` - `include/rfl/cli/options.hpp` — the internal option table: the long, short and positional options of a struct - `include/rfl/cli/NoAbbreviations.hpp` — `NoAbbreviations` processor +- `include/rfl/cli/ListDelimiter.hpp` — `ListDelimiter<"x">` processor - `include/rfl/cli/resolve_args.hpp` — `ParsedArgs` -> `map` - `include/rfl/cli.hpp` — aggregator header - `include/rfl/SnakeCaseToKebabCase.hpp` — processor diff --git a/include/rfl/cli.hpp b/include/rfl/cli.hpp index 2cd15eef..cae61674 100644 --- a/include/rfl/cli.hpp +++ b/include/rfl/cli.hpp @@ -2,6 +2,7 @@ #define RFL_CLI_HPP_ #include "../rfl.hpp" +#include "cli/ListDelimiter.hpp" #include "cli/NoAbbreviations.hpp" #include "cli/Parser.hpp" #include "cli/Reader.hpp" diff --git a/include/rfl/cli/ListDelimiter.hpp b/include/rfl/cli/ListDelimiter.hpp new file mode 100644 index 00000000..9eb6ab05 --- /dev/null +++ b/include/rfl/cli/ListDelimiter.hpp @@ -0,0 +1,91 @@ +#ifndef RFL_CLI_LISTDELIMITER_HPP_ +#define RFL_CLI_LISTDELIMITER_HPP_ + +#include +#include +#include + +#include "../Processors.hpp" +#include "../internal/StringLiteral.hpp" + +namespace rfl::cli { + +/// A setting for rfl::cli::read that sets the character at which the values +/// of list options and list positional arguments are split into items. The +/// default is ",": `--report=a,b` gives two items. ListDelimiter<";"> +/// splits at ';' instead, and ListDelimiter<""> does not split, so every +/// value, and every positional argument, is exactly one item. The setting +/// applies to every list in the struct. +/// The delimiter is a single ASCII character, as in clap and CLI11. Several +/// characters would make the splitting of a value such as "a;;;b" with ";;" +/// ambiguous; repeat the option instead. +/// This is a marker type (doesn't modify data) that only rfl::cli::read looks +/// at. Other formats ignore it. +/// Usage: rfl::cli::read>(argc, argv) +template +struct ListDelimiter { + static_assert(_delimiter.length == 0 + || (_delimiter.length == 1 && _delimiter.arr_[0] != '\0' + && static_cast(_delimiter.arr_[0]) + < 0x80), + "rfl::cli::ListDelimiter takes a single ASCII character, " + "such as \";\", or \"\" to not split lists."); + + /// The character at which list values are split, or std::nullopt if they + /// are not split. + static constexpr std::optional delimiter = + _delimiter.length == 0 ? std::nullopt + : std::optional(_delimiter.arr_[0]); + + /// Identity process function - returns the named tuple unchanged. + /// @tparam StructType The struct type being processed + /// @param _named_tuple The named tuple representation of the struct + /// @return The same named tuple (unchanged) + template + static auto process(auto&& _named_tuple) { + return _named_tuple; + } +}; + +namespace internal { + +/// `count` is the number of ListDelimiters in T, and `value` the delimiter +/// of the one there is. +template +struct list_delimiter { + static constexpr size_t count = 0; + static constexpr std::optional value = std::nullopt; +}; + +template +struct list_delimiter> { + static constexpr size_t count = 1; + static constexpr std::optional value = + ListDelimiter<_delimiter>::delimiter; +}; + +template +struct list_delimiter> { + static constexpr size_t count = (list_delimiter::count + ... + 0); + static_assert(count <= 1, "Pass at most one rfl::cli::ListDelimiter."); + // The other processors have no value, so this is the one ListDelimiter's. + static constexpr char code = static_cast( + (list_delimiter::value.value_or('\0') + ... + 0)); + static constexpr std::optional value = + code == '\0' ? std::nullopt : std::optional(code); +}; + +/// The character at which the processors say to split list values (',', +/// rfl::cli::array_delimiter, by default), or std::nullopt if they are not +/// split (ListDelimiter<"">). +template +constexpr std::optional list_delimiter_v = + list_delimiter>>::count == 0 + ? std::optional(',') + : list_delimiter>>::value; + +} // namespace internal + +} // namespace rfl::cli + +#endif diff --git a/include/rfl/cli/Reader.hpp b/include/rfl/cli/Reader.hpp index ccee2207..c15b53b5 100644 --- a/include/rfl/cli/Reader.hpp +++ b/include/rfl/cli/Reader.hpp @@ -24,6 +24,7 @@ static constexpr char path_separator = '.'; /// Character used to delimit array elements in CLI argument values. /// Example: `--ports=8080,8081,8082` for an array of ports. +/// rfl::cli::ListDelimiter replaces it. static constexpr char array_delimiter = ','; namespace internal { @@ -31,7 +32,7 @@ namespace internal { /// The occurrences after the first of the list options given more than /// once, by path, in argv order. The argument map holds the first one: /// `--ports 80 --ports 81,82` is held as "80" in the argument map and -/// {"81,82"} here. Each occurrence is split at array_delimiter. +/// {"81,82"} here. Each occurrence is split at the list delimiter. using CliLaterOccurrencesType = std::map>; @@ -159,6 +160,13 @@ struct Reader { template static constexpr bool has_custom_constructor = false; + Reader() = default; + + /// @param _list_delimiter The character at which list values are split + /// into items, or std::nullopt to not split them, see ListDelimiter. + explicit Reader(const std::optional _list_delimiter) noexcept + : list_delimiter_(_list_delimiter) {} + /// Gets a specific element from a CLI array by index. /// @param _idx The index of the element to retrieve /// @param _arr The CLI array @@ -277,9 +285,9 @@ struct Reader { return parse_value(*str, _var.path); } - /// Converts a CLI variable to an array by splitting the value on commas. - /// The items of every occurrence of a repeated list option are added in - /// order (see internal::CliLaterOccurrencesType). + /// Converts a CLI variable to an array by splitting the value on commas, + /// or on the list delimiter. The items of every occurrence of a repeated + /// list option are added in order (see internal::CliLaterOccurrencesType). /// @param _var The CLI variable containing a comma-delimited string /// @return A Result containing a CliArrayType with the split values rfl::Result to_array( @@ -337,33 +345,6 @@ struct Reader { return it->second; } - /// Splits a list into its items: those of _first, the occurrence that - /// get_value returns for _var, then those of its later occurrences. - static std::vector split_items(const std::string& _first, - const InputVarType& _var) { - std::vector items; - add_items(_first, &items); - if (_var.direct_value || !_var.later_occurrences) { - return items; - } - const auto it = _var.later_occurrences->find(_var.path); - if (it != _var.later_occurrences->end()) { - for (const auto& occurrence : it->second) { - add_items(occurrence, &items); - } - } - return items; - } - - /// Adds the items of one occurrence of a list, split at array_delimiter, - /// to _items. - static void add_items(const std::string& _occurrence, - std::vector* _items) { - for (auto& item : split(_occurrence, array_delimiter)) { - _items->emplace_back(std::move(item)); - } - } - static std::vector split( const std::string& _str, char _delim ) { @@ -388,6 +369,40 @@ struct Reader { return result; } + /// Splits a list into its items: those of _first, the occurrence that + /// get_value returns for _var, then those of its later occurrences. + std::vector split_items(const std::string& _first, + const InputVarType& _var) const { + std::vector items; + add_items(_first, &items); + if (_var.direct_value || !_var.later_occurrences) { + return items; + } + const auto it = _var.later_occurrences->find(_var.path); + if (it != _var.later_occurrences->end()) { + for (const auto& occurrence : it->second) { + add_items(occurrence, &items); + } + } + return items; + } + + /// Adds the items of one occurrence of a list, split at the list + /// delimiter, to _items. Without a delimiter, the occurrence is one item, + /// even if it is empty. + void add_items(const std::string& _occurrence, + std::vector* _items) const { + if (!list_delimiter_) { + _items->push_back(_occurrence); + return; + } + for (auto& item : split(_occurrence, *list_delimiter_)) { + _items->emplace_back(std::move(item)); + } + } + + /// The character at which list values are split, see ListDelimiter. + std::optional list_delimiter_ = array_delimiter; }; } // namespace rfl::cli diff --git a/include/rfl/cli/read.hpp b/include/rfl/cli/read.hpp index 99bbbf62..11220ca4 100644 --- a/include/rfl/cli/read.hpp +++ b/include/rfl/cli/read.hpp @@ -7,6 +7,7 @@ #include "../Processors.hpp" #include "../SnakeCaseToKebabCase.hpp" +#include "ListDelimiter.hpp" #include "Parser.hpp" #include "Reader.hpp" #include "options.hpp" @@ -17,6 +18,8 @@ namespace rfl::cli { namespace internal { +static_assert(list_delimiter_v> == array_delimiter); + /// Categorizes the arguments with `_parse`, which takes the options of T /// (see make_options) and returns ParsedArgs, and turns them into a struct. template @@ -29,7 +32,7 @@ rfl::Result parse_and_read(const ParseFn& _parse) { return resolve_args(std::move(_parsed), options); }) .and_then([](auto _args) -> rfl::Result { - const auto r = Reader(); + const auto r = Reader(internal::list_delimiter_v); const auto var = CliVarType{&_args.values, "", std::nullopt, &_args.later_occurrences}; return Parser::read(r, var); @@ -58,7 +61,9 @@ rfl::Result parse_and_read(const ParseFn& _parse) { /// yourself: `std::span(argv, argc)` would parse the program name as an /// argument. /// @tparam T The struct type to parse into -/// @tparam Ps Optional processors to apply during parsing +/// @tparam Ps Optional processors to apply during parsing, including the +/// settings rfl::NoExtraFields, rfl::cli::NoAbbreviations and +/// rfl::cli::ListDelimiter /// @param _args The command-line arguments to parse /// @return A Result containing the parsed struct or an error template read(R&& _args) { /// argv[0] is skipped as the program name. See the sequence overload above /// for the supported syntax. /// @tparam T The struct type to parse into -/// @tparam Ps Optional processors to apply during parsing +/// @tparam Ps Optional processors to apply during parsing, including the +/// settings rfl::NoExtraFields, rfl::cli::NoAbbreviations and +/// rfl::cli::ListDelimiter /// @param argc Number of command-line arguments /// @param argv Array of command-line argument strings /// @return A Result containing the parsed struct or an error diff --git a/tests/cli/test_list_delimiter.cpp b/tests/cli/test_list_delimiter.cpp new file mode 100644 index 00000000..caee1e81 --- /dev/null +++ b/tests/cli/test_list_delimiter.cpp @@ -0,0 +1,161 @@ +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace test_list_delimiter { + +template +rfl::Result read(std::vector _args) { + _args.insert(_args.begin(), "program"); + return rfl::cli::read(static_cast(_args.size()), + const_cast(_args.data())); +} + +template +std::string error_of(const rfl::Result& _result) { + return _result ? std::string("(no error)") + : std::string(_result.error().what()); +} + +using Strings = std::vector; + +struct Database { + std::optional hosts; +}; + +struct Opts { + rfl::Short<"t", std::optional> tags; + std::optional> ports; + std::optional> size; + std::optional name; + std::optional database; + std::optional> groups; + rfl::ImplicitValue, "cpu,gpu"> reports; + rfl::Positional> files; +}; + +using Semicolon = rfl::cli::ListDelimiter<";">; +using NoSplit = rfl::cli::ListDelimiter<"">; + +TEST(cli, test_list_delimiter_semicolon) { + const auto result = read( + {"--tags=a;b,c", "-t", "d", "--ports", "80;81", "--size=3;4", + "--name=x;y", "f;g", "h,i"}); + ASSERT_TRUE(result) << result.error().what(); + const auto& o = result.value(); + EXPECT_EQ(o.tags(), (Strings{"a", "b,c", "d"})); + EXPECT_EQ(o.ports, (std::vector{80, 81})); + EXPECT_EQ(o.size, (std::array{3, 4})); + // Only lists are split. + EXPECT_EQ(o.name, "x;y"); + EXPECT_EQ(o.files(), (Strings{"f", "g", "h,i"})); +} + +TEST(cli, test_list_delimiter_applies_to_every_list) { + const auto result = read( + {"--database.hosts=a;b", "--groups.x", "c;d", "--reports"}); + ASSERT_TRUE(result) << result.error().what(); + const auto& o = result.value(); + ASSERT_TRUE(o.database); + EXPECT_EQ(o.database->hosts, (Strings{"a", "b"})); + EXPECT_EQ(o.groups, (std::map{{"x", {"c", "d"}}})); + // The implicit value is split like any other value. + EXPECT_EQ(o.reports(), (Strings{"cpu,gpu"})); +} + +TEST(cli, test_list_delimiter_colon_and_space) { + const auto colon = + read>({"--tags", "/usr/bin:/bin"}); + ASSERT_TRUE(colon) << colon.error().what(); + EXPECT_EQ(colon.value().tags(), (Strings{"/usr/bin", "/bin"})); + + // As with ',', empty items are skipped. + const auto space = read>( + {"--tags", "a b c", "--tags= d", "x,y z"}); + ASSERT_TRUE(space) << space.error().what(); + EXPECT_EQ(space.value().tags(), (Strings{"a", "b", "c", "d"})); + EXPECT_EQ(space.value().files(), (Strings{"x,y", "z"})); +} + +TEST(cli, test_list_delimiter_comma_is_the_default) { + const auto explicit_comma = + read>({"--tags=a,b;c", "d,e"}); + const auto by_default = read({"--tags=a,b;c", "d,e"}); + ASSERT_TRUE(explicit_comma) << explicit_comma.error().what(); + ASSERT_TRUE(by_default) << by_default.error().what(); + EXPECT_EQ(by_default.value().tags(), (Strings{"a", "b;c"})); + EXPECT_EQ(by_default.value().files(), (Strings{"d", "e"})); + EXPECT_EQ(rfl::json::write(explicit_comma.value()), + rfl::json::write(by_default.value())); +} + +TEST(cli, test_list_delimiter_empty_disables_splitting) { + const auto result = read( + {"--tags=a,b", "-t", "c;d", "--tags=", "--reports", "x,y", "", + "z w"}); + ASSERT_TRUE(result) << result.error().what(); + const auto& o = result.value(); + // Each occurrence and each argument is exactly one item, even if empty. + EXPECT_EQ(o.tags(), (Strings{"a,b", "c;d", ""})); + EXPECT_EQ(o.reports(), (Strings{"cpu,gpu"})); + EXPECT_EQ(o.files(), (Strings{"x,y", "", "z w"})); + + const auto ints = read({"--ports", "80", "--ports", "81"}); + ASSERT_TRUE(ints) << ints.error().what(); + EXPECT_EQ(ints.value().ports, (std::vector{80, 81})); + EXPECT_NE(error_of(read({"--ports=80,81"})), "(no error)"); +} + +TEST(cli, test_list_delimiter_with_other_settings) { + for (const auto& result : + {read({"--tag=a;b", "c;d"}), + read({"--tag=a;b", "c;d"})}) { + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().tags(), (Strings{"a", "b"})); + EXPECT_EQ(result.value().files(), (Strings{"c", "d"})); + } + EXPECT_EQ(error_of(read({"--x=1"})), + "Unknown option '--x'."); +} + +// The trait that rfl::cli::read uses. +static_assert(rfl::cli::internal::list_delimiter_v> == ','); +static_assert(rfl::cli::internal::list_delimiter_v< + rfl::Processors> == ';'); +static_assert(!rfl::cli::internal::list_delimiter_v< + rfl::Processors> + .has_value()); + +struct Record { + std::string name; + std::vector tags; + std::optional> ports; +}; + +TEST(cli, test_list_delimiter_ignored_by_json) { + const auto record = Record{.name = "a;b", .tags = {"x,y", "z"}, + .ports = std::vector{1, 2}}; + + const auto json = rfl::json::write(record); + EXPECT_EQ(rfl::json::write(record), json); + EXPECT_EQ(rfl::json::write(record), json); + + const auto back = rfl::json::read(json); + ASSERT_TRUE(back) << back.error().what(); + EXPECT_EQ(rfl::json::write(back.value()), json); + + EXPECT_EQ((rfl::json::to_schema()), + rfl::json::to_schema()); + EXPECT_EQ((rfl::json::to_schema()), + rfl::json::to_schema()); +} + +} // namespace test_list_delimiter From 882218ec8720d9a1fc1320f63ef736ae292db5ff Mon Sep 17 00:00:00 2001 From: clockblocker Date: Fri, 13 Nov 2026 09:19:04 +0100 Subject: [PATCH 4/4] Add rfl::cli::OptionsFirst to pass the rest of the command line through A command such as `recipe [options] ` that hands everything after the name to another program could not be read: an option after the name, such as `recipe build --jobs 4`, was parsed (or, under rfl::NoExtraFields, rejected) as one of recipe's own, and `--` was dropped. With OptionsFirst, the options end at the first positional argument, like getopt's '+' mode (POSIXLY_CORRECT), argparse's REMAINDER and clap's trailing_var_arg. Every later token is a positional argument, taken as it is: `--x`, `-x`, unknown options and `--`. With a list as the last positional field and ListDelimiter<"">, the list gets the rest of the command line unchanged: struct Recipe { rfl::Positional name; rfl::Positional>> args; }; rfl::cli::read>(argc, argv); // recipe build --jobs 4 -- a,b // -> name = "build", args = [--jobs, 4, --, a,b] - Before the first positional argument, options work as usual, and `--` ends them and is dropped. - After it, `--` is kept. That is what getopt does in '+' mode: it stops at the first non-option and leaves the rest of argv, including a later `--`, to the program (checked with the macOS getopt_long). argparse instead drops a `--` that is the first token of a REMAINDER, and keeps any other. - A token that rfl reads as a positional argument, such as `-5`, also ends the options. The setting is a processor like rfl::cli::NoAbbreviations, which make_options turns into Options::options_first for parse_argv. It is off by default, which keeps the current behaviour, and other formats ignore it. Co-Authored-By: Claude Opus 5.5 --- docs/content/supported_formats/cli.md | 60 +++++++- include/rfl/cli.hpp | 1 + include/rfl/cli/OptionsFirst.hpp | 66 +++++++++ include/rfl/cli/options.hpp | 11 +- include/rfl/cli/parse_argv.hpp | 8 +- include/rfl/cli/read.hpp | 8 +- tests/cli/test_options_first.cpp | 188 ++++++++++++++++++++++++++ 7 files changed, 329 insertions(+), 13 deletions(-) create mode 100644 include/rfl/cli/OptionsFirst.hpp create mode 100644 tests/cli/test_options_first.cpp diff --git a/docs/content/supported_formats/cli.md b/docs/content/supported_formats/cli.md index c8e75e50..e82fa1a5 100644 --- a/docs/content/supported_formats/cli.md +++ b/docs/content/supported_formats/cli.md @@ -364,7 +364,8 @@ struct Config { - A plain list needs at least one argument. With `std::optional` or `rfl::DefaultVal`, no arguments give `std::nullopt` or the default. -- Options can still come anywhere: `./app run a --verbose b`. +- Options can still come anywhere (`./app run a --verbose b`), unless the + struct is read with `rfl::cli::OptionsFirst` (below). - The long form works as for any list: `--files=a,b`, or `--files a --files b`. It cannot be mixed with bare arguments: `Conflict: positional argument and '--files' both provided.` @@ -375,6 +376,51 @@ struct Config { option table, cannot repeat list options, so there a list as the last positional field takes one argument. +### Options first + +`rfl::cli::OptionsFirst` ends the options at the first positional argument, +like getopt's `+` mode (`POSIXLY_CORRECT`), argparse's `REMAINDER` and +clap's `trailing_var_arg`. Every later token is a positional argument, taken +as it is, even `--x`, `-x`, `--` and unknown options. With +`rfl::cli::ListDelimiter<"">`, a list as the last positional field gets the +rest of the command line unchanged, for example to pass it on to another +program: + +```cpp +struct Recipe { + rfl::Short<"v", std::optional> verbose; + rfl::Positional name; + rfl::Positional>> args; +}; + +const auto result = + rfl::cli::read>( + argc, argv); + +// ./recipe -v build --jobs 4 -v -- a,b +// -> verbose = true, name = "build", +// args = {"--jobs", "4", "-v", "--", "a,b"} +``` + +**Without `ListDelimiter<"">`, the passed-through arguments are lists like +any other:** each one is split at the commas and empty items are dropped. +`rfl::cli::read` reads +`./recipe build --jobs 4,5 "" x` as +`args = {"--jobs", "4", "5", "x"}`. Pass `ListDelimiter<"">` to get the +arguments unchanged. + +- Before the first positional argument, options work as usual, and `--` + ends them and is dropped (`./recipe -- -v` makes `-v` the name). +- After it, `--` is an argument like any other, as in getopt's `+` mode. + argparse drops a `--` that is the first token of a `REMAINDER` + (`recipe build -- x` gives `["x"]`); rfl keeps it. +- A token such as `-5` that is read as a positional argument (see + [grouped short options](#grouped-short-options)) also ends the options. +- `rfl::NoExtraFields` rejects unknown options before the first + positional argument. +- Without `OptionsFirst`, options and positional arguments can be mixed. + Other formats ignore the setting. + ## Combining wrappers `Short`, `Positional` and `ImplicitValue` can be nested with each other and @@ -437,11 +483,12 @@ Parsing proceeds in three stages: 1. **`parse_argv`** — categorizes raw tokens into `named`, `short_args`, and `positional` buckets (`ParsedArgs` struct). `rfl::cli::read` gives it an internal option table derived from the target struct, which says - which long and short options are flags, take a value or have an implicit - value, so that `--key value`, grouped short options and abbreviated long - options work, and whether a short option's name looks like a number. The - public `parse_argv`, which has no table, does none of these: `-abc` is the - one short option `abc`, and `-5` the short option `5`. + which long and short options are flags, take a value, have an implicit + value or are lists, so that `--key value`, grouped short options, + abbreviated long options and repeated list options work, and whether a + short option's name looks like a number. The public `parse_argv`, which + has no table, does none of these: `-abc` is the one short option `abc`, + and `-5` the short option `5`. 2. **`resolve_args`** — uses the same table to map short aliases to long names and to merge positional arguments. Produces a flat `map`. A list option given more than once keeps its @@ -461,6 +508,7 @@ Parsing proceeds in three stages: - `include/rfl/cli/options.hpp` — the internal option table: the long, short and positional options of a struct - `include/rfl/cli/NoAbbreviations.hpp` — `NoAbbreviations` processor - `include/rfl/cli/ListDelimiter.hpp` — `ListDelimiter<"x">` processor +- `include/rfl/cli/OptionsFirst.hpp` — `OptionsFirst` processor - `include/rfl/cli/resolve_args.hpp` — `ParsedArgs` -> `map` - `include/rfl/cli.hpp` — aggregator header - `include/rfl/SnakeCaseToKebabCase.hpp` — processor diff --git a/include/rfl/cli.hpp b/include/rfl/cli.hpp index cae61674..85a8e571 100644 --- a/include/rfl/cli.hpp +++ b/include/rfl/cli.hpp @@ -4,6 +4,7 @@ #include "../rfl.hpp" #include "cli/ListDelimiter.hpp" #include "cli/NoAbbreviations.hpp" +#include "cli/OptionsFirst.hpp" #include "cli/Parser.hpp" #include "cli/Reader.hpp" #include "cli/options.hpp" diff --git a/include/rfl/cli/OptionsFirst.hpp b/include/rfl/cli/OptionsFirst.hpp new file mode 100644 index 00000000..2f5b1551 --- /dev/null +++ b/include/rfl/cli/OptionsFirst.hpp @@ -0,0 +1,66 @@ +#ifndef RFL_CLI_OPTIONSFIRST_HPP_ +#define RFL_CLI_OPTIONSFIRST_HPP_ + +#include + +#include "../Processors.hpp" + +namespace rfl::cli { + +/// A setting for rfl::cli::read that ends the options at the first +/// positional argument, like getopt's '+' mode (POSIXLY_CORRECT), +/// argparse's REMAINDER and clap's trailing_var_arg. Every later token is a +/// positional argument, taken as it is, even if it looks like an option: +/// `--x`, `-x`, unknown options and `--`. A `--` before the first +/// positional argument still ends the options and is dropped. Without +/// OptionsFirst, options and positional arguments can be mixed. +/// With a list as the last rfl::Positional field and ListDelimiter<"">, the +/// list gets the remaining arguments unchanged: +/// struct Recipe { +/// rfl::Positional name; +/// rfl::Positional> args; +/// }; +/// rfl::cli::read> +/// // recipe build --jobs 4 -- x -> name = "build", +/// // args = {"--jobs", "4", "--", "x"} +/// Without ListDelimiter<"">, the list splits each argument at the commas +/// and drops empty items, like any other list: +/// rfl::cli::read +/// // recipe build --jobs 4,5 "" x -> args = {"--jobs", "4", "5", "x"} +/// This is a marker type (doesn't modify data) that only rfl::cli::read looks +/// at. Other formats ignore it. +/// Usage: rfl::cli::read(argc, argv) +struct OptionsFirst { + public: + /// Identity process function - returns the named tuple unchanged. + /// @tparam StructType The struct type being processed + /// @param _named_tuple The named tuple representation of the struct + /// @return The same named tuple (unchanged) + template + static auto process(auto&& _named_tuple) { + return _named_tuple; + } +}; + +namespace internal { + +template +struct options_first : std::false_type {}; + +template <> +struct options_first : std::true_type {}; + +template +struct options_first> + : std::bool_constant<(options_first::value || ...)> {}; + +/// Whether the processors contain rfl::cli::OptionsFirst. +template +constexpr bool options_first_v = + options_first>>::value; + +} // namespace internal + +} // namespace rfl::cli + +#endif diff --git a/include/rfl/cli/options.hpp b/include/rfl/cli/options.hpp index 3e9cb89b..46148882 100644 --- a/include/rfl/cli/options.hpp +++ b/include/rfl/cli/options.hpp @@ -32,6 +32,7 @@ #include "../internal/processed_t.hpp" #include "../parsing/is_string_map.hpp" #include "NoAbbreviations.hpp" +#include "OptionsFirst.hpp" #include "Parser.hpp" #include "Reader.hpp" @@ -126,6 +127,10 @@ struct Options { /// struct fails. std::string duplicate_short_name; + /// Whether the options end at the first positional argument, so that every + /// later token is a positional argument (rfl::cli::OptionsFirst). + bool options_first = false; + /// Returns the long options that `--_prefix` could abbreviate: every /// long option that starts with `_prefix`, in alphabetical order. Only the /// last segment of a dotted name is abbreviated, so `_prefix` must spell @@ -661,14 +666,16 @@ void collect_short_and_positional(Options* _options) { /// @tparam T The target struct type /// @tparam ProcessorsType The processors applied to the struct /// @return The options, with reject_unknown set if ProcessorsType contains -/// rfl::NoExtraFields, and allow_abbreviations cleared if it contains -/// rfl::cli::NoAbbreviations +/// rfl::NoExtraFields, allow_abbreviations cleared if it contains +/// rfl::cli::NoAbbreviations, and options_first set if it contains +/// rfl::cli::OptionsFirst template Options make_options() { Options options; options.group_short_options = true; options.reject_unknown = rfl::internal::no_extra_fields_v; options.allow_abbreviations = !no_abbreviations_v; + options.options_first = options_first_v; using U = unwrapped_option_t; collect_value_options>(&options); if constexpr (is_option_struct_v) { diff --git a/include/rfl/cli/parse_argv.hpp b/include/rfl/cli/parse_argv.hpp index a65a2fe2..b931e72d 100644 --- a/include/rfl/cli/parse_argv.hpp +++ b/include/rfl/cli/parse_argv.hpp @@ -54,6 +54,9 @@ inline std::string ambiguous_option_message( /// - Short options: -x value, -x=value, or -x (stored in `short_args`) /// - Positional arguments: bare arguments not prefixed with dashes (stored in `positional`) /// The special argument "--" forces all subsequent arguments to be treated as positional. +/// If `_options.options_first` is set (rfl::cli::OptionsFirst), so does the +/// first positional argument, which is kept: every later token is a +/// positional argument as it is, including "--", as in getopt's '+' mode. /// `_options` says what each option does with the token that follows it /// when it is given without '='. An option that takes a value consumes it, /// and fails if there is none. A long boolean flag never consumes it; a @@ -237,6 +240,7 @@ inline rfl::Result parse_string_views( // the short option "42". if (!looks_like_option(arg_raw) && !negative_numbers_are_options) { result.positional.emplace_back(arg_raw); + force_positional = _options.options_first; continue; } @@ -312,8 +316,10 @@ inline rfl::Result parse_string_views( continue; } - // Bare argument → positional. + // Bare argument → positional. With OptionsFirst, every later token is + // one too, as in getopt's '+' mode. result.positional.emplace_back(arg_raw); + force_positional = _options.options_first; } return result; } diff --git a/include/rfl/cli/read.hpp b/include/rfl/cli/read.hpp index 11220ca4..c31919dc 100644 --- a/include/rfl/cli/read.hpp +++ b/include/rfl/cli/read.hpp @@ -62,8 +62,8 @@ rfl::Result parse_and_read(const ParseFn& _parse) { /// argument. /// @tparam T The struct type to parse into /// @tparam Ps Optional processors to apply during parsing, including the -/// settings rfl::NoExtraFields, rfl::cli::NoAbbreviations and -/// rfl::cli::ListDelimiter +/// settings rfl::NoExtraFields, rfl::cli::NoAbbreviations, +/// rfl::cli::ListDelimiter and rfl::cli::OptionsFirst /// @param _args The command-line arguments to parse /// @return A Result containing the parsed struct or an error template read(R&& _args) { /// for the supported syntax. /// @tparam T The struct type to parse into /// @tparam Ps Optional processors to apply during parsing, including the -/// settings rfl::NoExtraFields, rfl::cli::NoAbbreviations and -/// rfl::cli::ListDelimiter +/// settings rfl::NoExtraFields, rfl::cli::NoAbbreviations, +/// rfl::cli::ListDelimiter and rfl::cli::OptionsFirst /// @param argc Number of command-line arguments /// @param argv Array of command-line argument strings /// @return A Result containing the parsed struct or an error diff --git a/tests/cli/test_options_first.cpp b/tests/cli/test_options_first.cpp new file mode 100644 index 00000000..2da0134d --- /dev/null +++ b/tests/cli/test_options_first.cpp @@ -0,0 +1,188 @@ +#include + +#include +#include +#include +#include +#include +#include + +namespace test_options_first { + +template +rfl::Result read(std::vector _args) { + _args.insert(_args.begin(), "program"); + return rfl::cli::read(static_cast(_args.size()), + const_cast(_args.data())); +} + +template +std::string error_of(const rfl::Result& _result) { + return _result ? std::string("(no error)") + : std::string(_result.error().what()); +} + +using Strings = std::vector; + +// recipe [options] : everything after the name goes to a +// backend, unchanged. +struct Recipe { + rfl::Short<"v", std::optional> verbose; + rfl::Short<"j", std::optional> jobs; + std::optional env; + rfl::ImplicitValue, "all"> help; + rfl::Positional name; + rfl::Positional> args; +}; + +template +rfl::Result recipe(std::vector _args) { + return read, + Ps...>(std::move(_args)); +} + +TEST(cli, test_options_first_recipe) { + const auto result = + recipe({"-v", "--jobs", "4", "build", "--jobs", "8", "-x", + "--unknown=1", "-v", "--", "y,z", ""}); + ASSERT_TRUE(result) << result.error().what(); + const auto& r = result.value(); + EXPECT_EQ(r.verbose(), true); + EXPECT_EQ(r.jobs(), 4); + EXPECT_EQ(r.name(), "build"); + EXPECT_EQ(r.args().value(), (Strings{"--jobs", "8", "-x", "--unknown=1", + "-v", "--", "y,z", ""})); +} + +TEST(cli, test_options_first_no_remaining_arguments) { + const auto result = recipe({"-v", "build"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().name(), "build"); + EXPECT_EQ(result.value().args().value(), Strings{}); + + EXPECT_EQ(error_of(recipe({"-v"})), "Field named 'name' not found."); +} + +TEST(cli, test_options_first_double_dash) { + // Before the first positional argument, '--' ends the options and is + // dropped. After it, '--' is an argument, as in getopt's '+' mode. + const auto before = recipe({"-v", "--", "-j", "build"}); + ASSERT_TRUE(before) << before.error().what(); + EXPECT_EQ(before.value().name(), "-j"); + EXPECT_EQ(before.value().args().value(), (Strings{"build"})); + + const auto twice = recipe({"--", "--", "build"}); + ASSERT_TRUE(twice) << twice.error().what(); + EXPECT_EQ(twice.value().name(), "--"); + EXPECT_EQ(twice.value().args().value(), (Strings{"build"})); + + const auto after = recipe({"build", "--"}); + ASSERT_TRUE(after) << after.error().what(); + EXPECT_EQ(after.value().args().value(), (Strings{"--"})); +} + +TEST(cli, test_options_first_options_before_the_name) { + // Short clusters, abbreviations, implicit values, bool literals and + // repeated list options work as usual before the first positional + // argument. + const auto ok = recipe({"-vj4", "--env", "A=1", "--en=B=2", "--help", + "build", "-vj8", "--env", "C", "--help"}); + ASSERT_TRUE(ok) << ok.error().what(); + const auto& r = ok.value(); + EXPECT_EQ(r.verbose(), true); + EXPECT_EQ(r.jobs(), 4); + EXPECT_EQ(r.env, (Strings{"A=1", "B=2"})); + EXPECT_EQ(r.help(), "all"); + EXPECT_EQ(r.name(), "build"); + EXPECT_EQ(r.args().value(), (Strings{"-vj8", "--env", "C", "--help"})); + + // A short bool flag takes a bool literal; a long one never does. + const auto literal = recipe({"-v", "false", "build", "x"}); + ASSERT_TRUE(literal) << literal.error().what(); + EXPECT_EQ(literal.value().verbose(), false); + EXPECT_EQ(literal.value().args().value(), (Strings{"x"})); +} + +TEST(cli, test_options_first_negative_number_is_positional) { + const auto result = recipe({"-j", "-1", "-2", "-v"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().jobs(), -1); + EXPECT_EQ(result.value().name(), "-2"); + EXPECT_EQ(result.value().args().value(), (Strings{"-v"})); +} + +TEST(cli, test_options_first_with_no_extra_fields) { + EXPECT_EQ(error_of(recipe({"--nope", "build"})), + "Unknown option '--nope'."); + EXPECT_EQ(error_of(recipe({"-x", "build"})), + "Unknown short argument: -x"); + + const auto after = recipe({"build", "--nope", "-x"}); + ASSERT_TRUE(after) << after.error().what(); + EXPECT_EQ(after.value().args().value(), (Strings{"--nope", "-x"})); +} + +TEST(cli, test_options_first_long_form_of_positionals) { + const auto result = recipe({"--args=x,y", "build"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().name(), "build"); + EXPECT_EQ(result.value().args().value(), (Strings{"x,y"})); +} + +TEST(cli, test_options_first_splits_with_the_default_delimiter) { + // Without ListDelimiter<"">, the remaining arguments are taken as they + // are, but still split at the commas. + const auto result = read( + {"build", "a,b", "--jobs=2,3"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_FALSE(result.value().jobs().has_value()); + EXPECT_EQ(result.value().args().value(), + (Strings{"a", "b", "--jobs=2", "3"})); +} + +TEST(cli, test_options_first_off_by_default) { + const auto result = read({"build", "--jobs", "8", "x", "--", "-v"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().jobs(), 8); + EXPECT_FALSE(result.value().verbose().has_value()); + EXPECT_EQ(result.value().args().value(), (Strings{"x", "-v"})); + + EXPECT_FALSE((rfl::cli::internal::make_options< + Recipe, rfl::Processors>() + .options_first)); +} + +struct One { + rfl::Positional file; + std::optional verbose; +}; + +TEST(cli, test_options_first_without_a_list_positional) { + // Like getopt's operands, the later tokens are positional arguments, so + // there are too many of them. + EXPECT_EQ(error_of(read({"f", "--verbose"})), + "Too many positional arguments: expected at most 1, got 2."); + + const auto ok = read({"--verbose", "f"}); + ASSERT_TRUE(ok) << ok.error().what(); + EXPECT_EQ(ok.value().file(), "f"); + EXPECT_EQ(ok.value().verbose, true); +} + +TEST(cli, test_options_first_ignored_by_json) { + Recipe r; + r.name = std::string("build"); + r.args = rfl::DefaultVal(Strings{"--x", "a,b"}); + const auto json = rfl::json::write(r); + EXPECT_EQ((rfl::json::write>(r)), + json); + const auto back = + rfl::json::read(json); + ASSERT_TRUE(back) << back.error().what(); + EXPECT_EQ(rfl::json::write(back.value()), json); + EXPECT_EQ((rfl::json::to_schema()), + rfl::json::to_schema()); +} + +} // namespace test_options_first