From 03f4447021eed788f59f8912375372913bc02cdd Mon Sep 17 00:00:00 2001 From: clockblocker Date: Sat, 14 Nov 2026 11:32:25 +0100 Subject: [PATCH] Let a list as the last positional field take the remaining arguments in rfl::cli If the last positional field is a list, it takes every positional argument after those of the other positional fields, each split at the commas: `app run a b,c` gives files = [a, b, c]. A list before other positional fields still takes one argument, and so does every positional field in the public resolve_args, whose flat-map result cannot hold them. usage shows a list as the last positional as `...`. Only inputs that used to fail change meaning. Co-Authored-By: Claude Opus 5.5 --- docs/content/supported_formats/cli.md | 31 +++- include/rfl/cli/options.hpp | 9 +- include/rfl/cli/resolve_args.hpp | 20 ++- include/rfl/cli/usage.hpp | 22 ++- tests/cli/test_list_positional.cpp | 243 ++++++++++++++++++++++++++ tests/cli/test_usage_options.cpp | 36 ++-- 6 files changed, 338 insertions(+), 23 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 ac25c874..3b1df7b4 100644 --- a/docs/content/supported_formats/cli.md +++ b/docs/content/supported_formats/cli.md @@ -288,6 +288,32 @@ 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 (in declaration order) is a list, it takes all +remaining positional arguments, 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. + ## Combining wrappers `Short` and `Positional` can be nested with `DefaultVal`, `std::optional`, @@ -404,7 +430,8 @@ Each argument is shown as the option table that `read` parses with (see [Architecture](#architecture)) reads it: a `bool`, also inside a nested struct, is a flag whose value can be left out (`--verbose[=]`), a list takes comma-separated items and can be repeated (`--tags=`, with -`Can be repeated.` in its row), and every other option takes a value +`Can be repeated.` in its row), a list as the last `rfl::Positional` takes +the remaining arguments (`...`), and every other option takes a value (`--port=`). `rfl::Positional` and `rfl::Short` are found through the other wrappers, as @@ -439,7 +466,7 @@ int main(int argc, char* argv[]) { | 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`) | ## Architecture diff --git a/include/rfl/cli/options.hpp b/include/rfl/cli/options.hpp index 818eeffd..69806ef2 100644 --- a/include/rfl/cli/options.hpp +++ b/include/rfl/cli/options.hpp @@ -80,7 +80,8 @@ struct Options { /// The paths of the rfl::Positional fields, in declaration order, wherever /// rfl::Positional sits among a field's wrappers. Each takes one positional - /// argument. + /// 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 @@ -204,6 +205,12 @@ struct Options { return it == short_options.end() ? Option{} : find_long(it->second); } + /// 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; + } + private: static bool has_prefix( const std::map& _map, const std::string& _prefix diff --git a/include/rfl/cli/resolve_args.hpp b/include/rfl/cli/resolve_args.hpp index dea0f72d..47422dcb 100644 --- a/include/rfl/cli/resolve_args.hpp +++ b/include/rfl/cli/resolve_args.hpp @@ -93,6 +93,8 @@ inline rfl::Unexpected too_many_positionals(const size_t _expected, /// 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). @@ -107,11 +109,19 @@ inline rfl::Result resolve_args( // Merge positional args. const auto& positional_names = _options.positionals; - if (_parsed.positional.size() > positional_names.size()) { + 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( @@ -184,7 +194,9 @@ inline rfl::Result> expand_abbreviations( /// of T, but for arguments parsed by parse_argv without them: values that /// boolean short options took from the next token are returned to the /// positional arguments. A flat map cannot hold the occurrences of a -/// repeated list option, which parse_argv without the options rejects. +/// repeated list option, which parse_argv 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. /// With rfl::cli::AllowAbbreviations, long options that match no field are /// expanded here (`--rep=a` for `--report=a`), but parse_argv, which does /// not know the struct, has already read `--rep value` as `--rep` and a @@ -215,6 +227,10 @@ rfl::Result> resolve_args( _parsed.named = std::move(*named); } 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/include/rfl/cli/usage.hpp b/include/rfl/cli/usage.hpp index 4b8bee2d..383b2092 100644 --- a/include/rfl/cli/usage.hpp +++ b/include/rfl/cli/usage.hpp @@ -57,6 +57,9 @@ struct UsageArg { OptionKind kind = OptionKind::value; /// Whether the field is a list, which can be repeated. bool is_list = false; + /// Whether the field is the last positional one and a list, so that it + /// takes the remaining positional arguments. + bool takes_rest = false; bool required = true; /// Whether `required` was taken from the parser's compile-time traits, so /// that the schema must not override it. @@ -322,6 +325,7 @@ class UsageCollector { auto root = UsageArg{}; root.required = !_all_optional; add(definition_->root_, std::move(root), _defaults, false); + mark_rest_positional(); return std::move(args_); } @@ -472,6 +476,18 @@ class UsageCollector { args_.emplace_back(std::move(_arg)); } + /// Marks the positional argument that takes the remaining arguments: a + /// list as the last one (Options::last_positional_is_list). + void mark_rest_positional() { + if (!options_->last_positional_is_list()) { + return; + } + for (auto& arg : args_) { + arg.takes_rest = + arg.positional && arg.name == options_->positionals.back(); + } + } + private: const parsing::schema::Definition* definition_; const std::map* meta_; @@ -493,11 +509,13 @@ inline std::string usage_value_to_string(const UsageArg& _arg) { return ""; } -/// "", "-p|--port=", "--verbose[=]" +/// "", "...", "-p|--port=", "--verbose[=]" inline std::string usage_arg_to_string(const UsageArg& _arg, const std::string& _short_sep) { if (_arg.positional) { - return "<" + _arg.name + ">"; + // A list as the last positional field takes the remaining arguments. + // Any other positional field takes one. + return "<" + _arg.name + ">" + (_arg.takes_rest ? "..." : ""); } auto str = _arg.short_name.empty() ? std::string() : "-" + _arg.short_name + _short_sep; diff --git a/tests/cli/test_list_positional.cpp b/tests/cli/test_list_positional.cpp new file mode 100644 index 00000000..fef28b92 --- /dev/null +++ b/tests/cli/test_list_positional.cpp @@ -0,0 +1,243 @@ +#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())); +} + +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) { + // Options can come anywhere, also between the list's arguments. + 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_FALSE(read({"run"})); + + // 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", "--files=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_FALSE(read({"run", "--files=a", "b"})); +} + +struct Two { + rfl::Positional input; + rfl::Positional output; +}; + +TEST(cli, test_list_positional_scalar_last_overflows) { + EXPECT_FALSE(read({"a", "b", "c"})); +} + +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_FALSE(read({"1", "2", "a,b", "3,true", "x"})); +} + +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_FALSE(read({"a", "b", "d"})); + EXPECT_FALSE(read({"a"})); + + 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_FALSE(read({"x", "1", "2", "y"})); + + 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 counts like any other, so a +// wrapped list declared last takes the remaining arguments. +struct WrappedListLast { + rfl::Positional command; + std::optional> files; +}; + +TEST(cli, test_list_positional_wrapped_list) { + 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 diff --git a/tests/cli/test_usage_options.cpp b/tests/cli/test_usage_options.cpp index 77ef51ae..4cacd774 100644 --- a/tests/cli/test_usage_options.cpp +++ b/tests/cli/test_usage_options.cpp @@ -7,8 +7,8 @@ #include // rfl::cli::usage for the parser's option features: wrappers in any order, -// repeated list options and positional order. Each test also reads the -// arguments as the help spells them. +// repeated list options, a list as the last positional field and positional +// order. Each test also reads the arguments as the help spells them. namespace test_usage_options { template @@ -45,49 +45,53 @@ struct Lists { rfl::Short<"r", rfl::Description<"Reports to write", Strings>> report; rfl::DefaultVal tags = Strings{"a", "b"}; rfl::Positional command; + rfl::Description<"Files to process", rfl::Positional> files; }; TEST(cli, test_usage_lists) { EXPECT_EQ(rfl::cli::usage("app", true).value(), "Usage: app -r|--report= [--tags=] " - "\n" + " ...\n" "\n" "Arguments:\n" " -r, --report= Reports to write. Can be repeated. " "Required.\n" " --tags= Default: a,b. Can be repeated.\n" - " Required.\n"); + " Required.\n" + " ... Files to process. Required.\n"); - const auto result = - read({"-r", "a", "run", "--report=b,c", "--tags=t"}); + const auto result = read( + {"-r", "a", "run", "--report=b,c", "x,y", "z", "--tags=t"}); ASSERT_TRUE(result) << result.error().what(); EXPECT_EQ(result.value().report.value().value(), (Strings{"a", "b", "c"})); EXPECT_EQ(result.value().tags.value(), (Strings{"t"})); EXPECT_EQ(result.value().command.value(), "run"); + EXPECT_EQ(result.value().files.value().value(), (Strings{"x", "y", "z"})); } /// The parser fills the rfl::Positional fields in declaration order, wherever -/// rfl::Positional sits among their wrappers. +/// rfl::Positional sits among their wrappers, and a list takes the remaining +/// arguments only as the last of them. struct PositionalOrder { - rfl::Description<"Files to process", rfl::Positional> files; - rfl::Positional pair; + rfl::Positional pair; rfl::Positional command; + rfl::Description<"Files to process", rfl::Positional> files; }; TEST(cli, test_usage_positional_order) { EXPECT_EQ(rfl::cli::usage("app", true).value(), - "Usage: app \n" + "Usage: app ...\n" "\n" "Arguments:\n" - " Files to process. Required.\n" - " Required.\n" - " Required.\n"); + " Required.\n" + " Required.\n" + " ... Files to process. Required.\n"); - const auto result = read({"x", "a", "run"}); + const auto result = read({"a,b", "run", "x", "y"}); ASSERT_TRUE(result) << result.error().what(); - EXPECT_EQ(result.value().pair.value(), "a"); + EXPECT_EQ(result.value().pair.value(), (Strings{"a", "b"})); EXPECT_EQ(result.value().command.value(), "run"); - EXPECT_EQ(result.value().files.value().value(), "x"); + EXPECT_EQ(result.value().files.value().value(), (Strings{"x", "y"})); } /// Two fields with the same short name fail every read, and usage too.