diff --git a/docs/content/supported_formats/cli.md b/docs/content/supported_formats/cli.md index 2a194d4b..df862230 100644 --- a/docs/content/supported_formats/cli.md +++ b/docs/content/supported_formats/cli.md @@ -345,6 +345,38 @@ rfl::cli::read>(argc, argv); exactly one item, even if it is empty. - Other formats ignore it. +### Empty list items + +By default, empty items in a split list are skipped: `--tags=a,,b` gives +`[a, b]`. Pass `rfl::cli::KeepEmptyItems` to keep each empty item as a +missing value at its index. The element type then decides, as it does for a +missing field: + +```cpp +const auto result = + rfl::cli::read(argc, argv); +``` + +| Element type | `--tags=a,,b` | +|---|---| +| `std::vector>` | `[a, nullopt, b]` | +| `std::vector>` | `[a, T{}, b]` | +| `std::vector` | Error: `Failed to parse field 'tags': Empty item at index 1.` | + +`T` is any type that needs a value, such as `std::string`, `std::wstring`, +a number or a `bool`. Smart pointers (`std::shared_ptr`, +`std::unique_ptr`) are never required, so an empty one is null, as a +missing field of that type is. + +Leading and trailing empty items (`,b`, `a,`) count, too. An empty value +(`--tags=`) is still an empty list. Other list types, such as `std::set`, +`std::deque` and `std::array`, behave the same way. A +[repeated option](#lists-and-repeated-options) keeps the empty items of +every occurrence, at their index in the combined list: `--tags=a,b +--tags=c,,d` has an empty item at index 3. With `rfl::cli::ListDelimiter<"">`, +lists are not split, so the setting would change nothing, and combining the +two is a compile-time error. + ### A list as the last positional argument If the last positional field (in declaration order) is a list, it takes all @@ -524,7 +556,7 @@ int main(int argc, char* argv[]) { | `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` or `--key=a --key=b,c` | Comma-separated; empty elements skipped; [repeatable](#lists-and-repeated-options) | +| `std::vector` | `--key=a,b,c` or `--key=a --key=b,c` | Comma-separated; empty items skipped unless [kept](#empty-list-items); [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 | @@ -555,7 +587,8 @@ Parsing proceeds in three stages: - `include/rfl/cli/read.hpp` — public API - `include/rfl/cli/Reader.hpp` — Reader + `parse_value` overloads -- `include/rfl/cli/Parser.hpp` — Parser type alias +- `include/rfl/cli/Parser.hpp` — Parser type alias + empty `DefaultVal` and `std::wstring` items +- `include/rfl/cli/KeepEmptyItems.hpp` — `KeepEmptyItems` processor - `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/AllowAbbreviations.hpp` — `AllowAbbreviations` processor diff --git a/include/rfl/cli.hpp b/include/rfl/cli.hpp index f69cb9fc..9568d8fa 100644 --- a/include/rfl/cli.hpp +++ b/include/rfl/cli.hpp @@ -3,6 +3,7 @@ #include "../rfl.hpp" #include "cli/AllowAbbreviations.hpp" +#include "cli/KeepEmptyItems.hpp" #include "cli/ListDelimiter.hpp" #include "cli/Parser.hpp" #include "cli/Reader.hpp" diff --git a/include/rfl/cli/KeepEmptyItems.hpp b/include/rfl/cli/KeepEmptyItems.hpp new file mode 100644 index 00000000..769053cb --- /dev/null +++ b/include/rfl/cli/KeepEmptyItems.hpp @@ -0,0 +1,57 @@ +#ifndef RFL_CLI_KEEPEMPTYITEMS_HPP_ +#define RFL_CLI_KEEPEMPTYITEMS_HPP_ + +#include + +#include "../Processors.hpp" + +namespace rfl::cli { + +/// A setting that keeps the empty items of split lists (`--tags=a,,b`), +/// reading each one as a missing value at its index. The element type then +/// decides, as it does for a missing field: std::optional becomes +/// std::nullopt, rfl::DefaultVal becomes T{}, std::shared_ptr and +/// std::unique_ptr become null, and a required type, such as std::string, +/// std::wstring or int, is an error. Without this setting, empty items are +/// skipped. +/// The index counts the items of every occurrence of a repeated list option, +/// or of a list positional argument. With ListDelimiter<"">, lists are not +/// split: every occurrence is one item as it is, even if it is empty, so +/// combining the two settings is a compile-time error. +/// This is a marker type (doesn't modify data) and other formats ignore it. +/// Usage: rfl::cli::read(argc, argv) +struct KeepEmptyItems { + public: + /// Identity process function - returns the named tuple unchanged. + /// The empty items are handled by the reader, not here. + /// @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 keep_empty_items : std::false_type {}; + +template <> +struct keep_empty_items : std::true_type {}; + +template +struct keep_empty_items> + : std::bool_constant<(keep_empty_items::value || ...)> {}; + +/// Whether the processors contain rfl::cli::KeepEmptyItems. +template +constexpr bool keep_empty_items_v = keep_empty_items< + std::remove_cvref_t>>::value; + +} // namespace internal + +} // namespace rfl::cli + +#endif diff --git a/include/rfl/cli/Parser.hpp b/include/rfl/cli/Parser.hpp index ae82964d..62a126e5 100644 --- a/include/rfl/cli/Parser.hpp +++ b/include/rfl/cli/Parser.hpp @@ -1,10 +1,60 @@ #ifndef RFL_CLI_PARSER_HPP_ #define RFL_CLI_PARSER_HPP_ +#include +#include + +#include "../DefaultVal.hpp" +#include "../Result.hpp" #include "../generic/Writer.hpp" +#include "../parsing/AreReaderAndWriter.hpp" #include "../parsing/Parser.hpp" +#include "../parsing/ParserDefaultVal.hpp" +#include "../parsing/ParserWString.hpp" #include "Reader.hpp" +namespace rfl::parsing { + +/// With rfl::cli::KeepEmptyItems, an empty item in a split list is a +/// missing value. A DefaultVal element then takes its default value, +/// T{}, much like a missing DefaultVal field keeps its default. Everything +/// else is handled by ParserDefaultVal. +template + requires AreReaderAndWriter> +struct Parser, ProcessorsType> + : public ParserDefaultVal, ProcessorsType> { + static Result> read(const cli::Reader& _r, + const cli::CliVarType& _var) noexcept { + if constexpr (std::is_default_constructible_v< + typename DefaultVal::Type>) { + if (cli::internal::is_empty_item(_var)) { + return DefaultVal(); + } + } + return ParserDefaultVal, + ProcessorsType>::read(_r, _var); + } +}; + +/// With rfl::cli::KeepEmptyItems, an empty std::wstring item is an +/// error, as an empty std::string item is. ParserWString would read it as an +/// empty string, because the reader reports it as empty. Everything else is +/// handled by ParserWString. +template + requires AreReaderAndWriter +struct Parser + : public ParserWString { + static Result read(const cli::Reader& _r, + const cli::CliVarType& _var) noexcept { + if (cli::internal::is_empty_item(_var)) { + return error(_r.template to_basic_type(_var).error()); + } + return ParserWString::read(_r, _var); + } +}; + +} // namespace rfl::parsing + namespace rfl::cli { template diff --git a/include/rfl/cli/Reader.hpp b/include/rfl/cli/Reader.hpp index c15b53b5..1fea3f23 100644 --- a/include/rfl/cli/Reader.hpp +++ b/include/rfl/cli/Reader.hpp @@ -41,12 +41,17 @@ using CliLaterOccurrencesType = /// 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. +/// An empty array element kept by KeepEmptyItems has neither: it is a +/// missing value, see `empty_item_index`. 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; + /// Only set for an empty array element: its index. `path` is then the key + /// of the array. + const std::optional empty_item_index = std::nullopt; }; /// Represents a CLI object with a prefix path for accessing nested fields. @@ -62,6 +67,8 @@ struct CliObjectType { /// Typically created by splitting a comma-delimited argument value. struct CliArrayType { const std::vector values; + /// The key the values were read from, used to report empty items. + const std::string path = ""; }; // --- Constrained overloads for string-to-type parsing --- @@ -164,8 +171,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 _keep_empty_items Whether to keep empty items in split lists + /// and read them as missing values, see KeepEmptyItems. + explicit Reader(const std::optional _list_delimiter, + const bool _keep_empty_items = false) noexcept + : list_delimiter_(_list_delimiter), + keep_empty_items_(_keep_empty_items) {} /// Gets a specific element from a CLI array by index. /// @param _idx The index of the element to retrieve @@ -177,7 +188,7 @@ struct Reader { return error( std::string("Index ") + std::to_string(_idx) + " out of bounds."); } - return InputVarType{nullptr, "", _arr.values[_idx]}; + return get_element(_idx, _arr); } /// Gets a specific field from a CLI object by name. @@ -196,6 +207,8 @@ struct Reader { /// Checks if a CLI variable is empty (has no value). /// A variable is empty if there's no direct value and no matching key in the argument map. + /// This includes empty array elements kept by KeepEmptyItems, which are + /// missing values. /// @param _var The CLI variable to check /// @return true if the variable is empty, false otherwise bool is_empty(const InputVarType& _var) const noexcept { @@ -224,9 +237,8 @@ struct Reader { const ArrayReader& _array_reader, const InputArrayType& _arr ) const noexcept { - for (const auto& val : _arr.values) { - auto err = _array_reader.read( - InputVarType{nullptr, "", val}); + for (size_t i = 0; i < _arr.values.size(); ++i) { + auto err = _array_reader.read(get_element(i, _arr)); if (err) { return err; } @@ -278,6 +290,9 @@ struct Reader { /// @return A Result containing the converted value or an error template rfl::Result to_basic_type(const InputVarType& _var) const noexcept { + if (_var.empty_item_index) { + return empty_item_error(_var); + } const auto str = get_value(_var); if (!str) { return error("No value for key '" + _var.path + "'."); @@ -292,11 +307,14 @@ struct Reader { /// @return A Result containing a CliArrayType with the split values rfl::Result to_array( const InputVarType& _var) const noexcept { + if (_var.empty_item_index) { + return empty_item_error(_var); + } const auto str = get_value(_var); if (!str) { return InputArrayType{{}}; } - return InputArrayType{split_items(*str, _var)}; + return InputArrayType{split_items(*str, _var), _var.path}; } /// Converts a CLI variable to an object for reading nested fields. @@ -305,6 +323,9 @@ struct Reader { /// @return A Result containing a CliObjectType or an error rfl::Result to_object( const InputVarType& _var) const noexcept { + if (_var.empty_item_index) { + return empty_item_error(_var); + } if (!_var.args) { return error("Cannot convert to object: no argument map available" + (_var.path.empty() @@ -329,6 +350,26 @@ struct Reader { } private: + /// Returns the element at _idx, which must be in bounds. An empty element + /// of a split list kept by KeepEmptyItems is a missing value, the others + /// are direct values. Without a list delimiter, nothing was split, so an + /// empty element is the empty string. + InputVarType get_element( + const size_t _idx, const InputArrayType& _arr + ) const noexcept { + if (keep_empty_items_ && list_delimiter_ && _arr.values[_idx].empty()) { + return InputVarType{.path = _arr.path, + .direct_value = std::nullopt, + .empty_item_index = _idx}; + } + return InputVarType{nullptr, "", _arr.values[_idx]}; + } + + static rfl::Unexpected empty_item_error(const InputVarType& _var) { + return error("Empty item at index " + + std::to_string(*_var.empty_item_index) + "."); + } + static std::optional get_value( const InputVarType& _var ) noexcept { @@ -345,8 +386,10 @@ struct Reader { return it->second; } + /// Splits _str at _delim. An empty _str has no pieces. Otherwise, empty + /// pieces are skipped, unless _keep_empty_items is set. static std::vector split( - const std::string& _str, char _delim + const std::string& _str, char _delim, const bool _keep_empty_items ) { std::vector result; if (_str.empty()) { @@ -356,12 +399,12 @@ struct Reader { while (true) { const auto pos = _str.find(_delim, start); if (pos == std::string::npos) { - if (start < _str.size()) { + if (start < _str.size() || _keep_empty_items) { result.emplace_back(_str.substr(start)); } break; } - if (pos > start) { + if (pos > start || _keep_empty_items) { result.emplace_back(_str.substr(start, pos - start)); } start = pos + 1; @@ -389,22 +432,36 @@ struct Reader { /// 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. + /// even if it is empty. With a delimiter, an empty occurrence has no + /// items, and empty items are skipped, unless keep_empty_items_ is set. 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_)) { + for (auto& item : split(_occurrence, *list_delimiter_, keep_empty_items_)) { _items->emplace_back(std::move(item)); } } /// The character at which list values are split, see ListDelimiter. std::optional list_delimiter_ = array_delimiter; + + /// Whether empty items in split lists are kept and read as missing values, + /// see KeepEmptyItems. + bool keep_empty_items_ = false; }; +namespace internal { + +/// Whether _var is an empty array element kept by KeepEmptyItems. +inline bool is_empty_item(const CliVarType& _var) noexcept { + return _var.empty_item_index.has_value(); +} + +} // namespace internal + } // namespace rfl::cli #endif diff --git a/include/rfl/cli/read.hpp b/include/rfl/cli/read.hpp index 3d90a4f8..5d2915af 100644 --- a/include/rfl/cli/read.hpp +++ b/include/rfl/cli/read.hpp @@ -7,6 +7,7 @@ #include "../Processors.hpp" #include "../SnakeCaseToKebabCase.hpp" +#include "KeepEmptyItems.hpp" #include "ListDelimiter.hpp" #include "Parser.hpp" #include "Reader.hpp" @@ -23,9 +24,17 @@ static_assert(list_delimiter_v> == array_delimiter); /// Resolves the parsed arguments and reads them into T. template rfl::Result read_parsed(ParsedArgs _parsed, const Options& _options) { + static_assert(!internal::keep_empty_items_v + || internal::list_delimiter_v.has_value(), + "rfl::cli::KeepEmptyItems has no effect with " + "rfl::cli::ListDelimiter<\"\">, which does not split lists, " + "so an empty item is kept as \"\" anyway. Remove one of " + "them."); 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, + internal::keep_empty_items_v); const auto var = CliVarType{&_args.values, "", std::nullopt, &_args.later_occurrences}; return Parser::read(r, var); diff --git a/tests/cli/test_empty_list_items.cpp b/tests/cli/test_empty_list_items.cpp new file mode 100644 index 00000000..55d76891 --- /dev/null +++ b/tests/cli/test_empty_list_items.cpp @@ -0,0 +1,243 @@ +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace test_empty_list_items { + +using KeepEmpty = rfl::cli::KeepEmptyItems; +using Path = std::vector; + +struct Config { + std::vector> tags; +}; + +TEST(cli, test_empty_items_skipped_by_default) { + const char* args[] = {"program", "--tags=,a,,b,"}; + const auto result = rfl::cli::read(2, const_cast(args)); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().tags, + (std::vector>{"a", "b"})); +} + +TEST(cli, test_empty_items_optional) { + const char* args[] = {"program", "--tags=a,,b"}; + const auto result = + rfl::cli::read(2, const_cast(args)); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().tags, + (std::vector>{"a", std::nullopt, "b"})); +} + +TEST(cli, test_empty_items_leading_and_trailing) { + const char* args[] = {"program", "--tags=,a,"}; + const auto result = + rfl::cli::read(2, const_cast(args)); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().tags, + (std::vector>{std::nullopt, "a", + std::nullopt})); +} + +TEST(cli, test_empty_items_empty_value) { + const char* args[] = {"program", "--tags="}; + const auto result = + rfl::cli::read(2, const_cast(args)); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_TRUE(result.value().tags.empty()); +} + +struct DefaultValConfig { + std::vector> names; + std::vector> counts; +}; + +TEST(cli, test_empty_items_default_val) { + const char* args[] = {"program", "--names=a,,b", "--counts=,2"}; + const auto result = + rfl::cli::read(3, const_cast(args)); + ASSERT_TRUE(result) << result.error().what(); + const auto& names = result.value().names; + ASSERT_EQ(names.size(), 3u); + EXPECT_EQ(names[0].value(), "a"); + EXPECT_EQ(names[1].value(), ""); + EXPECT_EQ(names[2].value(), "b"); + const auto& counts = result.value().counts; + ASSERT_EQ(counts.size(), 2u); + EXPECT_EQ(counts[0].value(), 0); + EXPECT_EQ(counts[1].value(), 2); +} + +struct RequiredConfig { + std::vector tags; +}; + +TEST(cli, test_empty_items_required_error) { + const char* args[] = {"program", "--tags=a,,b"}; + const auto result = + rfl::cli::read(2, const_cast(args)); + ASSERT_FALSE(result); + EXPECT_EQ(result.error().what(), + "Failed to parse field 'tags': Empty item at index 1."); + const auto details = result.error().details(); + ASSERT_EQ(details.size(), 1u); + EXPECT_EQ(details[0].path, (Path{"tags", size_t{1}})); + EXPECT_EQ(details[0].message, "Empty item at index 1."); +} + +struct BoolConfig { + std::vector flags; +}; + +TEST(cli, test_empty_items_required_bool_error) { + // An empty bool item is not read as `true`, unlike `--flag` or `--flag=`. + const char* args[] = {"program", "--flags=true,"}; + const auto result = + rfl::cli::read(2, const_cast(args)); + ASSERT_FALSE(result); + EXPECT_EQ( + result.error().what(), + "Failed to parse field 'flags': Empty item at index 1."); +} + +struct Inner { + std::vector> tags; + std::vector names; +}; + +struct Outer { + Inner a; +}; + +TEST(cli, test_empty_items_nested) { + const char* args[] = {"program", "--a.tags=x,,y", "--a.names=n"}; + const auto result = + rfl::cli::read(3, const_cast(args)); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().a.tags, + (std::vector>{"x", std::nullopt, "y"})); + EXPECT_EQ(result.value().a.names, (std::vector{"n"})); +} + +TEST(cli, test_empty_items_nested_error) { + const char* args[] = {"program", "--a.tags=x", "--a.names=,n"}; + const auto result = + rfl::cli::read(3, const_cast(args)); + ASSERT_FALSE(result); + EXPECT_EQ(result.error().what(), + "Failed to parse field 'a': Failed to parse field 'names': Empty " + "item at index 0."); + const auto details = result.error().details(); + ASSERT_EQ(details.size(), 1u); + EXPECT_EQ(details[0].path, (Path{"a", "names", size_t{0}})); +} + +struct Containers { + std::array, 3> numbers; + std::set names; + std::vector> pointers; +}; + +TEST(cli, test_empty_items_other_containers) { + const char* ok_args[] = {"program", "--numbers=1,,3", "--names=b,a", + "--pointers=,2"}; + const auto ok = + rfl::cli::read(4, const_cast(ok_args)); + ASSERT_TRUE(ok) << ok.error().what(); + EXPECT_EQ(ok.value().numbers, + (std::array, 3>{1, std::nullopt, 3})); + EXPECT_EQ(ok.value().names, (std::set{"a", "b"})); + // A smart pointer is never required, so an empty one is null. + ASSERT_EQ(ok.value().pointers.size(), 2u); + EXPECT_FALSE(ok.value().pointers[0]); + + const char* err_args[] = {"program", "--numbers=1,2,3", "--names=b,,a", + "--pointers=1"}; + const auto err = + rfl::cli::read(4, const_cast(err_args)); + ASSERT_FALSE(err); + EXPECT_EQ( + err.error().what(), + "Failed to parse field 'names': Empty item at index 1."); +} + +struct WideConfig { + std::vector names; + std::vector> tags; +}; + +TEST(cli, test_empty_items_wstring) { + // An empty std::wstring item is an error, as an empty std::string item is, + // not "". + const char* ok_args[] = {"program", "--names=a,b", "--tags=x,,y"}; + const auto ok = + rfl::cli::read(3, const_cast(ok_args)); + ASSERT_TRUE(ok) << ok.error().what(); + EXPECT_EQ(ok.value().names, (std::vector{L"a", L"b"})); + EXPECT_EQ(ok.value().tags, (std::vector>{ + L"x", std::nullopt, L"y"})); + + const char* err_args[] = {"program", "--names=a,,b", "--tags=x"}; + const auto err = + rfl::cli::read(3, const_cast(err_args)); + ASSERT_FALSE(err); + EXPECT_EQ( + err.error().what(), + "Failed to parse field 'names': Empty item at index 1."); + const auto details = err.error().details(); + ASSERT_EQ(details.size(), 1u); + EXPECT_EQ(details[0].path, (Path{"names", size_t{1}})); +} + +// --- With repeated options and list positionals --- + +template +rfl::Result read(std::vector _args) { + _args.insert(_args.begin(), "program"); + return rfl::cli::read(static_cast(_args.size()), + const_cast(_args.data())); +} + +using OptStrings = std::vector>; + +struct RepeatedConfig { + rfl::Short<"t", OptStrings> tags; +}; + +TEST(cli, test_empty_items_repeated_option) { + // The empty items of every occurrence are kept, at their index in the + // combined list. + const auto result = + read({"--tags=a,", "-t", ",b", "--tags=c"}); + ASSERT_TRUE(result) << result.error().what(); + EXPECT_EQ(result.value().tags(), + (OptStrings{"a", std::nullopt, std::nullopt, "b", "c"})); +} + +// With ListDelimiter<"">, lists are not split, so KeepEmptyItems would do +// nothing: rfl::cli::read, +// rfl::cli::KeepEmptyItems> does not compile. + +struct RequiredPositionalConfig { + rfl::Positional command; + rfl::Positional> files; +}; + +TEST(cli, test_empty_items_list_positional_error) { + const auto result = + read({"run", "a", "b,,c"}); + ASSERT_FALSE(result); + EXPECT_EQ( + result.error().what(), + "Failed to parse field 'files': Empty item at index 2."); + const auto details = result.error().details(); + ASSERT_EQ(details.size(), 1u); + EXPECT_EQ(details[0].path, (Path{"files", size_t{2}})); +} + +} // namespace test_empty_list_items