diff --git a/docs/content/supported_formats/cli.md b/docs/content/supported_formats/cli.md index d31c3111..e82fa1a5 100644 --- a/docs/content/supported_formats/cli.md +++ b/docs/content/supported_formats/cli.md @@ -288,6 +288,139 @@ 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.` + +### 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 +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`), 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.` +- 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. + +### 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 @@ -335,11 +468,11 @@ 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 | -| `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` | @@ -350,14 +483,18 @@ 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`. + `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`. @@ -370,6 +507,8 @@ 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/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 2cd15eef..85a8e571 100644 --- a/include/rfl/cli.hpp +++ b/include/rfl/cli.hpp @@ -2,7 +2,9 @@ #define RFL_CLI_HPP_ #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/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/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/Reader.hpp b/include/rfl/cli/Reader.hpp index 58c16d37..c15b53b5 100644 --- a/include/rfl/cli/Reader.hpp +++ b/include/rfl/cli/Reader.hpp @@ -24,8 +24,20 @@ 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 { + +/// 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 the list 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 +45,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 +54,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. @@ -144,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 @@ -167,7 +190,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 +264,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; } @@ -260,7 +285,9 @@ struct Reader { return parse_value(*str, _var.path); } - /// Converts a CLI variable to an array by splitting the value on commas. + /// 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( @@ -269,7 +296,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 +314,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. @@ -342,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/options.hpp b/include/rfl/cli/options.hpp index 83ab5cc6..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" @@ -65,6 +66,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 @@ -83,7 +89,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 @@ -119,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 @@ -144,6 +156,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); @@ -419,6 +437,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 +466,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 +486,7 @@ Option sub_key_option() { return Option{OptionKind::other}; } else { - return Option{OptionKind::value}; + return Option{OptionKind::value, "", is_option_list_v}; } } @@ -509,7 +542,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}; } } @@ -632,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 1e7da9f3..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 @@ -74,6 +77,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 +96,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 +224,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; } @@ -208,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; } @@ -256,7 +289,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,15 +308,18 @@ 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; } 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 8d5e1e43..c31919dc 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,8 +32,9 @@ 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 var = CliVarType{&_args, "", std::nullopt}; + const auto r = Reader(internal::list_delimiter_v); + const auto var = CliVarType{&_args.values, "", std::nullopt, + &_args.later_occurrences}; return Parser::read(r, var); }); } @@ -57,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, +/// 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) { /// 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, +/// 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/include/rfl/cli/resolve_args.hpp b/include/rfl/cli/resolve_args.hpp index 36cd3f30..93cdb0cf 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 @@ -93,32 +109,46 @@ 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). /// @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; // 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( @@ -143,7 +173,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 +184,11 @@ 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, 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 @@ -162,13 +197,24 @@ 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); + 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); + }); } } // 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_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 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 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 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