Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 34 additions & 3 deletions docs/content/supported_formats/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -216,6 +216,35 @@ option in a token treats the next token as it would alone (`-qv false` sets
- Grouping needs the struct: the public `rfl::cli::parse_argv` reads `-abc`
as the one short option `abc`.

## 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: every occurrence is split at the commas, and the items are added
in argv order.

```cpp
struct Config {
rfl::Short<"r", std::vector<std::string>> report;
};

// ./app --report=a,b --report=c -> report = {"a", "b", "c"}
// ./app -r a --report=b -r c -> report = {"a", "b", "c"}
```

- Long 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.
- Nested lists (`--database.replicas=a --database.replicas=b`) and map
entries whose values are lists (`--groups.x=a --groups.x=b`) work the
same way.

Any other option can be given only once. That includes nested
fields and map entries: `Duplicate argument: --output`,
`Duplicate short argument: -o`, `Conflict: '-o' and '--output' both provided.`

## Combining wrappers

`Short` and `Positional` can be nested with `DefaultVal`, `std::optional`,
Expand Down Expand Up @@ -330,8 +359,10 @@ Arguments:

Each argument is shown as the option table that `read` parses with (see
[Architecture](#architecture)) reads it: a `bool`, also inside a nested
struct, is a flag whose value can be left out (`--verbose[=<bool>]`), and
every other option takes a value (`--port=<value>`).
struct, is a flag whose value can be left out (`--verbose[=<bool>]`), a list
takes comma-separated items and can be repeated (`--tags=<v1,v2,...>`, with
`Can be repeated.` in its row), and every other option takes a value
(`--port=<value>`).

`rfl::Positional` and `rfl::Short` are found through the other wrappers, as
the parser does (see [Combining wrappers](#combining-wrappers)), so
Expand Down Expand Up @@ -361,7 +392,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<T>` | omit for `nullopt` | |
| `std::vector<T>` | `--key=a,b,c` | Comma-separated; empty elements skipped |
| `std::vector<T>` | `--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<T>` | fields inlined | No prefix needed |
| `rfl::Rename<"x", T>` | `--x=val` | Bypasses kebab conversion |
Expand Down
54 changes: 50 additions & 4 deletions include/rfl/cli/Reader.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -26,20 +26,35 @@ static constexpr char path_separator = '.';
/// Example: `--ports=8080,8081,8082` for an array of ports.
static constexpr char array_delimiter = ',';

namespace internal {

/// The occurrences after the first of the list options given more than
/// once, by path, in argv order. The argument map holds the first one:
/// `--ports 80 --ports 81,82` is held as "80" in the argument map and
/// {"81,82"} here. Each occurrence is split at array_delimiter.
using CliLaterOccurrencesType =
std::map<std::string, std::vector<std::string>>;

} // 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.
struct CliVarType {
const std::map<std::string, std::string>* const args = nullptr;
const std::string path;
const std::optional<std::string> 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.
/// All child fields will be prefixed with this path.
struct CliObjectType {
const std::map<std::string, std::string>* 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.
Expand Down Expand Up @@ -167,7 +182,8 @@ struct Reader {
const auto child_path = _obj.prefix.empty()
? _name
: _obj.prefix + _name;
return InputVarType{_obj.args, child_path, std::nullopt};
return InputVarType{_obj.args, child_path, std::nullopt,
_obj.later_occurrences};
}

/// Checks if a CLI variable is empty (has no value).
Expand Down Expand Up @@ -240,7 +256,8 @@ struct Reader {
const auto child_path = _obj.prefix + child;
_object_reader.read(
std::string_view(child),
InputVarType{_obj.args, child_path, std::nullopt});
InputVarType{_obj.args, child_path, std::nullopt,
_obj.later_occurrences});
}
++it;
}
Expand All @@ -261,6 +278,8 @@ struct Reader {
}

/// Converts a CLI variable to an array by splitting the value on commas.
/// The items of every occurrence of a repeated list option are added in
/// order (see internal::CliLaterOccurrencesType).
/// @param _var The CLI variable containing a comma-delimited string
/// @return A Result containing a CliArrayType with the split values
rfl::Result<InputArrayType> to_array(
Expand All @@ -269,7 +288,7 @@ struct Reader {
if (!str) {
return InputArrayType{{}};
}
return InputArrayType{split(*str, array_delimiter)};
return InputArrayType{split_items(*str, _var)};
}

/// Converts a CLI variable to an object for reading nested fields.
Expand All @@ -287,7 +306,7 @@ struct Reader {
const auto prefix = _var.path.empty()
? std::string("")
: _var.path + path_separator;
return InputObjectType{_var.args, prefix};
return InputObjectType{_var.args, prefix, _var.later_occurrences};
}

/// Custom constructors are not supported for CLI parsing.
Expand Down Expand Up @@ -318,6 +337,33 @@ struct Reader {
return it->second;
}

/// Splits a list into its items: those of _first, the occurrence that
/// get_value returns for _var, then those of its later occurrences.
static std::vector<std::string> split_items(const std::string& _first,
const InputVarType& _var) {
std::vector<std::string> items;
add_items(_first, &items);
if (_var.direct_value || !_var.later_occurrences) {
return items;
}
const auto it = _var.later_occurrences->find(_var.path);
if (it != _var.later_occurrences->end()) {
for (const auto& occurrence : it->second) {
add_items(occurrence, &items);
}
}
return items;
}

/// Adds the items of one occurrence of a list, split at array_delimiter,
/// to _items.
static void add_items(const std::string& _occurrence,
std::vector<std::string>* _items) {
for (auto& item : split(_occurrence, array_delimiter)) {
_items->emplace_back(std::move(item));
}
}

static std::vector<std::string> split(
const std::string& _str, char _delim
) {
Expand Down
33 changes: 31 additions & 2 deletions include/rfl/cli/options.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,11 @@ enum class OptionKind {
/// How an option is given on the command line.
struct Option {
OptionKind kind = OptionKind::unknown;

/// 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
Expand Down Expand Up @@ -99,6 +104,12 @@ struct Options {
/// when it is given without '=' (rfl::cli::SeparateOptionValues).
bool separate_values = false;

/// Builds the table with every long option through nested structs and
/// maps, if this one lists only the top-level fields (see make_options).
/// parse_argv looks up nested options in it, for instance to tell whether
/// a repeated nested option is a list.
Options (*make_all_paths)() = nullptr;

/// Whether tokens such as `-5` and `-.5` are short options rather than
/// negative numbers. They are when parse_argv is called without the
/// struct. make_options clears it unless, as in argparse, a short option's
Expand Down Expand Up @@ -349,6 +360,20 @@ struct type_list {
using add = type_list<Ts..., T>;
};

/// 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 <class T>
constexpr bool is_option_list_v =
(parsing::is_vector_like_v<T> && !parsing::is_map_like_v<T>
&& !parsing::is_bytestring_v<T> && !parsing::is_vectorstring_v<T>)
|| parsing::is_array_v<T> || parsing::is_rfl_array_v<T>
|| parsing::is_c_array_v<T> || parsing::is_tuple_v<T>
|| parsing::is_rfl_tuple_v<T> || parsing::is_pair_v<T>;

/// The option for a field, or a key of a map or of rfl::ExtraFields, with
/// values of type T.
template <class T, class ProcessorsType>
Expand All @@ -362,7 +387,7 @@ Option option_for() {
return Option{OptionKind::other};
}
else {
return Option{OptionKind::value};
return Option{OptionKind::value, is_option_list_v<U>};
}
}

Expand Down Expand Up @@ -430,7 +455,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<U>};
}
}

Expand Down Expand Up @@ -529,6 +555,9 @@ Options make_options() {
options.group_short_options = true;
options.reject_unknown = rfl::internal::no_extra_fields_v<ProcessorsType>;
options.separate_values = separate_option_values_v<ProcessorsType>;
if constexpr (!_all_paths) {
options.make_all_paths = &make_options<T, ProcessorsType, true>;
}
using U = unwrapped_option_t<T, ProcessorsType>;
if constexpr (_all_paths) {
collect_value_options<T, ProcessorsType, type_list<>>(&options);
Expand Down
57 changes: 51 additions & 6 deletions include/rfl/cli/parse_argv.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
#include <concepts>
#include <initializer_list>
#include <map>
#include <optional>
#include <ranges>
#include <span>
#include <string>
Expand Down Expand Up @@ -61,6 +62,10 @@ namespace internal {
/// token (`-qf csv`). Without `_options` from make_options, short options
/// are not grouped: `-abc` is the short option `abc`.
/// Every element of `_args` is parsed; nothing is skipped as the program name.
/// Every occurrence of a list option (Option::is_list) adds to it, however
/// it is spelled. 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.
/// @param _args The command-line arguments to parse
/// @param _options The options of the target struct (see make_options)
/// @return A Result containing ParsedArgs with categorized arguments or an error
Expand All @@ -74,8 +79,48 @@ inline rfl::Result<ParsedArgs> parse_string_views(
const bool negative_numbers_are_options =
_options.negative_numbers_are_options;

// Without rfl::NoExtraFields, `_options` lists only the top-level fields
// (see make_options), so a nested option such as `--database.replicas` is
// looked up in the table of all paths, built the first time one is given.
std::optional<Options> all_paths;
const auto find_long = [&](const std::string& _key) {
if (!_options.make_all_paths
|| _key.find(path_separator) == std::string::npos) {
return _options.find_long(_key);
}
if (!all_paths) {
all_paths = _options.make_all_paths();
}
return all_paths->find_long(_key);
};

// 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<bool> {
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<bool> {
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));
Expand Down Expand Up @@ -144,7 +189,7 @@ inline rfl::Result<ParsedArgs> parse_string_views(
if (key.empty()) {
return error("Empty key in argument: " + std::string(arg_raw));
}
const auto option = _options.find_long(key);
const auto option = find_long(key);
if (option.kind == OptionKind::unknown && _options.reject_unknown) {
return error("Unknown option '--" + key + "'.");
}
Expand All @@ -156,9 +201,8 @@ inline rfl::Result<ParsedArgs> parse_string_views(
if (!v) { return error(v.error().what()); }
val = std::move(*v);
}
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;
}

Expand Down Expand Up @@ -218,7 +262,7 @@ inline rfl::Result<ParsedArgs> 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;
}
Expand All @@ -235,7 +279,8 @@ inline rfl::Result<ParsedArgs> parse_string_views(
val = std::move(*v);
}

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;
}
Expand Down
3 changes: 2 additions & 1 deletion include/rfl/cli/read.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,8 @@ rfl::Result<T> read_parsed(ParsedArgs _parsed, const Options& _options) {
return resolve_args(std::move(_parsed), _options)
.and_then([](auto _args) -> rfl::Result<T> {
const auto r = Reader();
const auto var = CliVarType{&_args, "", std::nullopt};
const auto var = CliVarType{&_args.values, "", std::nullopt,
&_args.later_occurrences};
return Parser<T, ProcessorsType>::read(r, var);
});
}
Expand Down
Loading