diff --git a/docs/content/supported_formats/cli.md b/docs/content/supported_formats/cli.md index 2a194d4b..7839d238 100644 --- a/docs/content/supported_formats/cli.md +++ b/docs/content/supported_formats/cli.md @@ -363,7 +363,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.` @@ -371,6 +372,42 @@ struct Config { before other positional fields, such as `std::vector`, `std::set`, a pair or a `std::array`, takes one argument, split at the commas. +### Options first + +`rfl::cli::OptionsFirst` ends the options at the first positional argument, +as in getopt's `+` mode. Every later token is a positional argument, taken +as it is, even `--x`, `-x`, `--` and unknown options. A list as the last +positional field gets the rest of the command line unchanged, whatever the +list delimiter: each argument is one item, never split at the commas, and +empty ones are kept. That way it can be passed 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", ""} +``` + +The long form, `--args=a,b` before the name, is an option, and is split as +usual. + +- 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. +- 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 `DefaultVal`, @@ -496,6 +533,22 @@ default is joined with `;`. With `rfl::cli::ListDelimiter<"">`, it is `--tags=`, and its default is left out, because one value cannot spell several items. +With `rfl::cli::OptionsFirst`, the options end at the first positional +argument, so the usage line lists every option before the positional +arguments. The rows of the detailed form keep the declaration order: + +```cpp +struct Recipe { + rfl::Short<"v", std::optional> verbose; + rfl::Positional name; + rfl::Positional>> args; + rfl::Short<"j", std::optional> jobs; +}; + +rfl::cli::usage("recipe"); +// Usage: recipe [-v|--verbose[=]] [-j|--jobs=] [...] +``` + `rfl::Positional` and `rfl::Short` are found through the other wrappers, as the parser does (see [Combining wrappers](#combining-wrappers)), so `rfl::Description<"...", rfl::Positional>` is listed as a @@ -560,6 +613,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/AllowAbbreviations.hpp` — `AllowAbbreviations` 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/usage.hpp` — `usage()` help text, built on `rfl::parsing::schema` and the internal option table - `include/rfl/cli.hpp` — aggregator header diff --git a/include/rfl/cli.hpp b/include/rfl/cli.hpp index f69cb9fc..87b45592 100644 --- a/include/rfl/cli.hpp +++ b/include/rfl/cli.hpp @@ -4,6 +4,7 @@ #include "../rfl.hpp" #include "cli/AllowAbbreviations.hpp" #include "cli/ListDelimiter.hpp" +#include "cli/OptionsFirst.hpp" #include "cli/Parser.hpp" #include "cli/Reader.hpp" #include "cli/SeparateOptionValues.hpp" diff --git a/include/rfl/cli/OptionsFirst.hpp b/include/rfl/cli/OptionsFirst.hpp new file mode 100644 index 00000000..b9eba739 --- /dev/null +++ b/include/rfl/cli/OptionsFirst.hpp @@ -0,0 +1,63 @@ +#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. +/// A list as the last rfl::Positional field gets the remaining arguments +/// unchanged, whatever the list delimiter: they are not split, and empty +/// ones are kept. +/// struct Recipe { +/// rfl::Positional name; +/// rfl::Positional> args; +/// }; +/// rfl::cli::read +/// // recipe build --jobs 4,5 -- "" x -> name = "build", +/// // 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/Reader.hpp b/include/rfl/cli/Reader.hpp index c15b53b5..53eb8e19 100644 --- a/include/rfl/cli/Reader.hpp +++ b/include/rfl/cli/Reader.hpp @@ -11,6 +11,7 @@ #include #include #include +#include #include #include "../Result.hpp" @@ -164,8 +165,12 @@ struct Reader { /// @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) {} + /// @param _verbatim_list The path of a list whose items are taken as they + /// are, never split or dropped, or empty (see OptionsFirst). + explicit Reader(const std::optional _list_delimiter, + std::string _verbatim_list = std::string()) noexcept + : list_delimiter_(_list_delimiter), + verbatim_list_(std::move(_verbatim_list)) {} /// Gets a specific element from a CLI array by index. /// @param _idx The index of the element to retrieve @@ -374,25 +379,27 @@ struct Reader { std::vector split_items(const std::string& _first, const InputVarType& _var) const { std::vector items; - add_items(_first, &items); + const bool verbatim = !_var.direct_value && !verbatim_list_.empty() + && _var.path == verbatim_list_; + add_items(_first, verbatim, &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); + add_items(occurrence, verbatim, &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, + /// delimiter, to _items. Without a delimiter, or if `_verbatim`, the + /// occurrence is one item, even if it is empty. + void add_items(const std::string& _occurrence, const bool _verbatim, std::vector* _items) const { - if (!list_delimiter_) { + if (!list_delimiter_ || _verbatim) { _items->push_back(_occurrence); return; } @@ -403,6 +410,9 @@ struct Reader { /// The character at which list values are split, see ListDelimiter. std::optional list_delimiter_ = array_delimiter; + + /// The path of the list whose items are never split or dropped, or empty. + std::string verbatim_list_; }; } // namespace rfl::cli diff --git a/include/rfl/cli/options.hpp b/include/rfl/cli/options.hpp index dcaee846..4ca17c23 100644 --- a/include/rfl/cli/options.hpp +++ b/include/rfl/cli/options.hpp @@ -31,6 +31,7 @@ #include "../internal/processed_t.hpp" #include "../parsing/is_string_map.hpp" #include "AllowAbbreviations.hpp" +#include "OptionsFirst.hpp" #include "Parser.hpp" #include "SeparateOptionValues.hpp" #include "Reader.hpp" @@ -137,6 +138,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 @@ -646,8 +651,9 @@ void collect_top_level_options(Options* _options) { /// options, need them all. /// @return The options, with reject_unknown set if ProcessorsType contains /// rfl::NoExtraFields, separate_values if it contains -/// rfl::cli::SeparateOptionValues, and allow_abbreviations if it contains -/// rfl::cli::AllowAbbreviations +/// rfl::cli::SeparateOptionValues, allow_abbreviations if it contains +/// rfl::cli::AllowAbbreviations, and options_first if it contains +/// rfl::cli::OptionsFirst template || separate_option_values_v @@ -661,6 +667,7 @@ Options make_options() { options.make_all_paths = &make_options; } options.allow_abbreviations = allow_abbreviations_v; + options.options_first = options_first_v; using U = unwrapped_option_t; if constexpr (_all_paths) { collect_value_options>(&options); diff --git a/include/rfl/cli/parse_argv.hpp b/include/rfl/cli/parse_argv.hpp index b32e673d..09889a23 100644 --- a/include/rfl/cli/parse_argv.hpp +++ b/include/rfl/cli/parse_argv.hpp @@ -43,6 +43,9 @@ namespace internal { /// - 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 '='. A short option that takes a value consumes /// it, and fails if there is none; so does a long one with @@ -248,6 +251,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; } @@ -318,8 +322,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 3d90a4f8..6e958da1 100644 --- a/include/rfl/cli/read.hpp +++ b/include/rfl/cli/read.hpp @@ -25,7 +25,8 @@ template rfl::Result read_parsed(ParsedArgs _parsed, const Options& _options) { return resolve_args(std::move(_parsed), _options) .and_then([](auto _args) -> rfl::Result { - const auto r = Reader(internal::list_delimiter_v); + const auto r = Reader(internal::list_delimiter_v, + std::move(_args.verbatim_list)); 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 81d24ede..ceafaa1e 100644 --- a/include/rfl/cli/resolve_args.hpp +++ b/include/rfl/cli/resolve_args.hpp @@ -38,6 +38,10 @@ struct ResolvedArgs { std::map values; /// The occurrences after the first of each list given more than once. CliLaterOccurrencesType later_occurrences; + /// The path of the list whose items are taken as they are, never split or + /// dropped, or empty: with rfl::cli::OptionsFirst, the list as the last + /// positional field when it gets the rest of the command line. + std::string verbatim_list; }; /// Applies what parse_argv could not know without the option table. @@ -146,8 +150,17 @@ inline rfl::Result resolve_args( result.emplace(long_name, std::move(value)); } + // With rfl::cli::OptionsFirst, the rest of the command line is passed + // through to the list as it is. + auto verbatim_list = std::string(); + if (_options.options_first && _options.last_positional_is_list() + && _parsed.positional.size() >= positional_names.size()) { + verbatim_list = positional_names.back(); + } + return ResolvedArgs{std::move(result), - std::move(_parsed.later_occurrences)}; + std::move(_parsed.later_occurrences), + std::move(verbatim_list)}; } /// The error for a long option that abbreviates several options, worded diff --git a/include/rfl/cli/usage.hpp b/include/rfl/cli/usage.hpp index c431e8d7..23d108c0 100644 --- a/include/rfl/cli/usage.hpp +++ b/include/rfl/cli/usage.hpp @@ -33,6 +33,7 @@ #include "../parsing/schema/make.hpp" #include "../to_generic.hpp" #include "ListDelimiter.hpp" +#include "OptionsFirst.hpp" #include "Reader.hpp" #include "options.hpp" #include "resolve_args.hpp" @@ -597,12 +598,20 @@ inline std::string usage_help_text(const UsageArg& _arg) { return text; } +/// @param _options_first Whether the options end at the first positional +/// argument (rfl::cli::OptionsFirst), so the synopsis lists them first. inline std::string format_usage(const std::string& _program_name, const std::vector& _args, const bool _detailed, - const std::optional _delimiter) { + const std::optional _delimiter, + const bool _options_first) { + auto synopsis = _args; + if (_options_first) { + std::stable_partition(synopsis.begin(), synopsis.end(), + [](const UsageArg& _arg) { return !_arg.positional; }); + } auto out = "Usage: " + _program_name; - for (const auto& arg : _args) { + for (const auto& arg : synopsis) { const auto str = usage_arg_to_string(arg, "|", _delimiter); out += arg.required ? " " + str : " [" + str + "]"; } @@ -707,7 +716,7 @@ rfl::Result usage(const std::string& _program_name, rfl::internal::default_if_missing_v, internal::usage_defaults()); return internal::format_usage(_program_name, args, _detailed, - delimiter); + delimiter, options.options_first); } catch (std::exception& e) { return error(e.what()); } diff --git a/tests/cli/test_options_first.cpp b/tests/cli/test_options_first.cpp new file mode 100644 index 00000000..a7d2501a --- /dev/null +++ b/tests/cli/test_options_first.cpp @@ -0,0 +1,174 @@ +#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 (with rfl::cli::AllowAbbreviations), + // 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_passes_the_rest_through_unsplit) { + // Whatever the list delimiter, the rest of the command line is passed + // through as it is: not split at the commas, and empty items are kept. + 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", ""})); + + // The long form is an option, so it is split as usual. + const auto long_form = + read({"--args=x,y", "build"}); + ASSERT_TRUE(long_form) << long_form.error().what(); + EXPECT_EQ(long_form.value().args().value(), (Strings{"x", "y"})); +} + +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"})); +} + +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); +} + +} // namespace test_options_first diff --git a/tests/cli/test_usage_options.cpp b/tests/cli/test_usage_options.cpp index c1d41178..693bf5aa 100644 --- a/tests/cli/test_usage_options.cpp +++ b/tests/cli/test_usage_options.cpp @@ -8,8 +8,9 @@ // rfl::cli::usage for the parser's option features: rfl::ImplicitValue, // wrappers in any order, repeated list options, a list as the last -// positional field and positional order. Each test also reads the arguments -// as the help spells them. +// positional field, positional order, rfl::cli::ListDelimiter and +// rfl::cli::OptionsFirst. Each test also reads the arguments as the help +// spells them. namespace test_usage_options { template @@ -189,4 +190,42 @@ TEST(cli, test_usage_list_delimiter) { EXPECT_EQ(no_split.value().files.value().value(), (Strings{"x,y", "z"})); } +// recipe [options] , as in test_options_first.cpp. +struct Recipe { + rfl::Short<"v", std::optional> verbose; + rfl::Positional name; + rfl::Positional> args; + rfl::Short<"j", std::optional> jobs; +}; + +TEST(cli, test_usage_options_first) { + // Without OptionsFirst, options and positional arguments can be mixed, so + // the synopsis keeps the declaration order. + EXPECT_EQ(rfl::cli::usage("recipe").value(), + "Usage: recipe [-v|--verbose[=]] [...] " + "[-j|--jobs=]\n"); + + // With OptionsFirst, the options end at the first positional argument, so + // the synopsis lists them first. The rows keep the declaration order. + EXPECT_EQ( + (rfl::cli::usage>("recipe", true).value()), + "Usage: recipe [-v|--verbose[=]] [-j|--jobs=] " + "[...]\n" + "\n" + "Arguments:\n" + " -v, --verbose[=]\n" + " Required.\n" + " ...\n" + " -j, --jobs=\n"); + + const auto result = + read>( + {"-v", "-j", "4", "build", "--jobs", "8"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().jobs.value(), 4); + EXPECT_EQ(result.value().name.value(), "build"); + EXPECT_EQ(result.value().args.value().value(), (Strings{"--jobs", "8"})); +} + } // namespace test_usage_options