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
28 changes: 27 additions & 1 deletion docs/content/supported_formats/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -288,6 +288,28 @@ 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<Config, rfl::cli::ListDelimiter<";">>(argc, argv);
// ./app --report='a;b' --report=c,d -> report = {"a", "b", "c,d"}

rfl::cli::read<Config, rfl::cli::ListDelimiter<"">>(argc, argv);
// ./app --report=a,b --report= -> report = {"a,b", ""}
```

- The delimiter is a single ASCII character, such as `;`, `:` or a space.
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.

### A list as the last positional argument

If the last positional field (in declaration order) is a list, it takes all
Expand Down Expand Up @@ -432,7 +454,10 @@ 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), a list as the last `rfl::Positional` takes
the remaining arguments (`<files>...`), and every other option takes a value
(`--port=<value>`).
(`--port=<value>`). With `rfl::cli::ListDelimiter<";">`, a list is
`--tags=<v1;v2;...>` and its default is joined with `;`. With
`rfl::cli::ListDelimiter<"">`, it is `--tags=<value>`, and its default is
left out, because one value cannot spell several items.

`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 @@ -496,6 +521,7 @@ 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/AllowAbbreviations.hpp` — `AllowAbbreviations` processor
- `include/rfl/cli/ListDelimiter.hpp` — `ListDelimiter<"x">` processor
- `include/rfl/cli/resolve_args.hpp` — `ParsedArgs` -> `map<string, string>`
- `include/rfl/cli/usage.hpp` — `usage()` help text, built on `rfl::parsing::schema` and the internal option table
- `include/rfl/cli.hpp` — aggregator header
Expand Down
1 change: 1 addition & 0 deletions include/rfl/cli.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@

#include "../rfl.hpp"
#include "cli/AllowAbbreviations.hpp"
#include "cli/ListDelimiter.hpp"
#include "cli/Parser.hpp"
#include "cli/Reader.hpp"
#include "cli/SeparateOptionValues.hpp"
Expand Down
91 changes: 91 additions & 0 deletions include/rfl/cli/ListDelimiter.hpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
#ifndef RFL_CLI_LISTDELIMITER_HPP_
#define RFL_CLI_LISTDELIMITER_HPP_

#include <cstddef>
#include <optional>
#include <type_traits>

#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<Config, rfl::cli::ListDelimiter<";">>(argc, argv)
template <rfl::internal::StringLiteral _delimiter>
struct ListDelimiter {
static_assert(_delimiter.length == 0
|| (_delimiter.length == 1 && _delimiter.arr_[0] != '\0'
&& static_cast<unsigned char>(_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<char> delimiter =
_delimiter.length == 0 ? std::nullopt
: std::optional<char>(_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 <class StructType>
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 <class T>
struct list_delimiter {
static constexpr size_t count = 0;
static constexpr std::optional<char> value = std::nullopt;
};

template <rfl::internal::StringLiteral _delimiter>
struct list_delimiter<ListDelimiter<_delimiter>> {
static constexpr size_t count = 1;
static constexpr std::optional<char> value =
ListDelimiter<_delimiter>::delimiter;
};

template <class... Ps>
struct list_delimiter<Processors<Ps...>> {
static constexpr size_t count = (list_delimiter<Ps>::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<char>(
(list_delimiter<Ps>::value.value_or('\0') + ... + 0));
static constexpr std::optional<char> value =
code == '\0' ? std::nullopt : std::optional<char>(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 <class T>
constexpr std::optional<char> list_delimiter_v =
list_delimiter<std::remove_cvref_t<std::remove_pointer_t<T>>>::count == 0
? std::optional<char>(',')
: list_delimiter<std::remove_cvref_t<std::remove_pointer_t<T>>>::value;

} // namespace internal

} // namespace rfl::cli

#endif
77 changes: 46 additions & 31 deletions include/rfl/cli/Reader.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -24,14 +24,15 @@ 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 array_delimiter.
/// {"81,82"} here. Each occurrence is split at the list delimiter.
using CliLaterOccurrencesType =
std::map<std::string, std::vector<std::string>>;

Expand Down Expand Up @@ -159,6 +160,13 @@ struct Reader {
template <class T>
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<char> _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
Expand Down Expand Up @@ -277,9 +285,9 @@ struct Reader {
return parse_value<T>(*str, _var.path);
}

/// 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).
/// 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<InputArrayType> to_array(
Expand Down Expand Up @@ -337,33 +345,6 @@ 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 All @@ -388,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<std::string> split_items(const std::string& _first,
const InputVarType& _var) const {
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 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<std::string>* _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<char> list_delimiter_ = array_delimiter;
};

} // namespace rfl::cli
Expand Down
5 changes: 4 additions & 1 deletion include/rfl/cli/read.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@

#include "../Processors.hpp"
#include "../SnakeCaseToKebabCase.hpp"
#include "ListDelimiter.hpp"
#include "Parser.hpp"
#include "Reader.hpp"
#include "options.hpp"
Expand All @@ -17,12 +18,14 @@ namespace rfl::cli {

namespace internal {

static_assert(list_delimiter_v<Processors<>> == array_delimiter);

/// Resolves the parsed arguments and reads them into T.
template <class T, class ProcessorsType>
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 r = Reader(internal::list_delimiter_v<ProcessorsType>);
const auto var = CliVarType{&_args.values, "", std::nullopt,
&_args.later_occurrences};
return Parser<T, ProcessorsType>::read(r, var);
Expand Down
Loading