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
56 changes: 55 additions & 1 deletion docs/content/supported_formats/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -363,14 +363,51 @@ struct Config {

- A plain list needs at least one argument. With `std::optional` or
`rfl::DefaultVal`, no arguments give `std::nullopt` or the default.
- Options can still come anywhere (`./app run a --verbose b`).
- Options can still come anywhere (`./app run a --verbose b`), unless the
struct is read with `rfl::cli::OptionsFirst` (below).
- The long form works as for any list: `--files=a,b`, or
`--files=a --files=b`. It cannot be mixed with bare arguments:
`Conflict: positional argument and '--files' both provided.`
- 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.

### Options first

`rfl::cli::OptionsFirst` ends the options at the first positional argument,
as in getopt's `+` mode. Every later token is a positional argument, taken
as it is, even `--x`, `-x`, `--` and unknown options. A list as the last
positional field gets the rest of the command line unchanged, whatever the
list delimiter: each argument is one item, never split at the commas, and
empty ones are kept. That way it can be passed on to another program:

```cpp
struct Recipe {
rfl::Short<"v", std::optional<bool>> verbose;
rfl::Positional<std::string> name;
rfl::Positional<rfl::DefaultVal<std::vector<std::string>>> args;
};

const auto result = rfl::cli::read<Recipe, rfl::cli::OptionsFirst>(argc, argv);

// ./recipe -v build --jobs 4 -v -- a,b ""
// -> verbose = true, name = "build",
// args = {"--jobs", "4", "-v", "--", "a,b", ""}
```

The long form, `--args=a,b` before the name, is an option, and is split as
usual.

- Before the first positional argument, options work as usual, and `--`
ends them and is dropped (`./recipe -- -v` makes `-v` the name).
- After it, `--` is an argument like any other, as in getopt's `+` mode.
- A token such as `-5` that is read as a positional argument (see
[grouped short options](#grouped-short-options)) also ends the options.
- `rfl::NoExtraFields` rejects unknown options before the first
positional argument.
- Without `OptionsFirst`, options and positional arguments can be mixed.
Other formats ignore the setting.

## Combining wrappers

`Short`, `Positional` and `ImplicitValue` can be nested with `DefaultVal`,
Expand Down Expand Up @@ -496,6 +533,22 @@ 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.

With `rfl::cli::OptionsFirst`, the options end at the first positional
argument, so the usage line lists every option before the positional
arguments. The rows of the detailed form keep the declaration order:

```cpp
struct Recipe {
rfl::Short<"v", std::optional<bool>> verbose;
rfl::Positional<std::string> name;
rfl::Positional<rfl::DefaultVal<std::vector<std::string>>> args;
rfl::Short<"j", std::optional<int>> jobs;
};

rfl::cli::usage<Recipe, rfl::cli::OptionsFirst>("recipe");
// Usage: recipe [-v|--verbose[=<bool>]] [-j|--jobs=<value>] <name> [<args>...]
```

`rfl::Positional` and `rfl::Short` are found through the other wrappers, as
the parser does (see [Combining wrappers](#combining-wrappers)), so
`rfl::Description<"...", rfl::Positional<std::string>>` is listed as a
Expand Down Expand Up @@ -560,6 +613,7 @@ Parsing proceeds in three stages:
- `include/rfl/cli/options.hpp` — the internal option table: the long, short and positional options of a struct
- `include/rfl/cli/AllowAbbreviations.hpp` — `AllowAbbreviations` processor
- `include/rfl/cli/ListDelimiter.hpp` — `ListDelimiter<"x">` processor
- `include/rfl/cli/OptionsFirst.hpp` — `OptionsFirst` processor
- `include/rfl/cli/resolve_args.hpp` — `ParsedArgs` -> `map<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 @@ -4,6 +4,7 @@
#include "../rfl.hpp"
#include "cli/AllowAbbreviations.hpp"
#include "cli/ListDelimiter.hpp"
#include "cli/OptionsFirst.hpp"
#include "cli/Parser.hpp"
#include "cli/Reader.hpp"
#include "cli/SeparateOptionValues.hpp"
Expand Down
63 changes: 63 additions & 0 deletions include/rfl/cli/OptionsFirst.hpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
#ifndef RFL_CLI_OPTIONSFIRST_HPP_
#define RFL_CLI_OPTIONSFIRST_HPP_

#include <type_traits>

#include "../Processors.hpp"

namespace rfl::cli {

/// A setting for rfl::cli::read that ends the options at the first
/// positional argument, like getopt's '+' mode (POSIXLY_CORRECT),
/// argparse's REMAINDER and clap's trailing_var_arg. Every later token is a
/// positional argument, taken as it is, even if it looks like an option:
/// `--x`, `-x`, unknown options and `--`. A `--` before the first
/// positional argument still ends the options and is dropped. Without
/// OptionsFirst, options and positional arguments can be mixed.
/// A list as the last rfl::Positional field gets the remaining arguments
/// unchanged, whatever the list delimiter: they are not split, and empty
/// ones are kept.
/// struct Recipe {
/// rfl::Positional<std::string> name;
/// rfl::Positional<std::vector<std::string>> args;
/// };
/// rfl::cli::read<Recipe, rfl::cli::OptionsFirst>
/// // recipe build --jobs 4,5 -- "" x -> name = "build",
/// // args = {"--jobs", "4,5", "--", "", "x"}
/// This is a marker type (doesn't modify data) that only rfl::cli::read looks
/// at. Other formats ignore it.
/// Usage: rfl::cli::read<Config, rfl::cli::OptionsFirst>(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 <class StructType>
static auto process(auto&& _named_tuple) {
return _named_tuple;
}
};

namespace internal {

template <class T>
struct options_first : std::false_type {};

template <>
struct options_first<OptionsFirst> : std::true_type {};

template <class... Ps>
struct options_first<Processors<Ps...>>
: std::bool_constant<(options_first<Ps>::value || ...)> {};

/// Whether the processors contain rfl::cli::OptionsFirst.
template <class T>
constexpr bool options_first_v =
options_first<std::remove_cvref_t<std::remove_pointer_t<T>>>::value;

} // namespace internal

} // namespace rfl::cli

#endif
26 changes: 18 additions & 8 deletions include/rfl/cli/Reader.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
#include <string>
#include <string_view>
#include <type_traits>
#include <utility>
#include <vector>

#include "../Result.hpp"
Expand Down Expand Up @@ -164,8 +165,12 @@ struct Reader {

/// @param _list_delimiter The character at which list values are split
/// into items, or std::nullopt to not split them, see ListDelimiter.
explicit Reader(const std::optional<char> _list_delimiter) noexcept
: list_delimiter_(_list_delimiter) {}
/// @param _verbatim_list The path of a list whose items are taken as they
/// are, never split or dropped, or empty (see OptionsFirst).
explicit Reader(const std::optional<char> _list_delimiter,
std::string _verbatim_list = std::string()) noexcept
: list_delimiter_(_list_delimiter),
verbatim_list_(std::move(_verbatim_list)) {}

/// Gets a specific element from a CLI array by index.
/// @param _idx The index of the element to retrieve
Expand Down Expand Up @@ -374,25 +379,27 @@ struct Reader {
std::vector<std::string> split_items(const std::string& _first,
const InputVarType& _var) const {
std::vector<std::string> items;
add_items(_first, &items);
const bool verbatim = !_var.direct_value && !verbatim_list_.empty()
&& _var.path == verbatim_list_;
add_items(_first, verbatim, &items);
if (_var.direct_value || !_var.later_occurrences) {
return items;
}
const auto it = _var.later_occurrences->find(_var.path);
if (it != _var.later_occurrences->end()) {
for (const auto& occurrence : it->second) {
add_items(occurrence, &items);
add_items(occurrence, verbatim, &items);
}
}
return items;
}

/// Adds the items of one occurrence of a list, split at the list
/// delimiter, to _items. Without a delimiter, the occurrence is one item,
/// even if it is empty.
void add_items(const std::string& _occurrence,
/// delimiter, to _items. Without a delimiter, or if `_verbatim`, the
/// occurrence is one item, even if it is empty.
void add_items(const std::string& _occurrence, const bool _verbatim,
std::vector<std::string>* _items) const {
if (!list_delimiter_) {
if (!list_delimiter_ || _verbatim) {
_items->push_back(_occurrence);
return;
}
Expand All @@ -403,6 +410,9 @@ struct Reader {

/// The character at which list values are split, see ListDelimiter.
std::optional<char> list_delimiter_ = array_delimiter;

/// The path of the list whose items are never split or dropped, or empty.
std::string verbatim_list_;
};

} // namespace rfl::cli
Expand Down
11 changes: 9 additions & 2 deletions include/rfl/cli/options.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
#include "../internal/processed_t.hpp"
#include "../parsing/is_string_map.hpp"
#include "AllowAbbreviations.hpp"
#include "OptionsFirst.hpp"
#include "Parser.hpp"
#include "SeparateOptionValues.hpp"
#include "Reader.hpp"
Expand Down Expand Up @@ -137,6 +138,10 @@ struct Options {
/// struct fails.
std::string duplicate_short_name;

/// Whether the options end at the first positional argument, so that every
/// later token is a positional argument (rfl::cli::OptionsFirst).
bool options_first = false;

/// Returns the long options that `--_prefix` could abbreviate: every
/// long option that starts with `_prefix`, in alphabetical order. Only the
/// last segment of a dotted name is abbreviated, so `_prefix` must spell
Expand Down Expand Up @@ -646,8 +651,9 @@ void collect_top_level_options(Options* _options) {
/// options, need them all.
/// @return The options, with reject_unknown set if ProcessorsType contains
/// rfl::NoExtraFields, separate_values if it contains
/// rfl::cli::SeparateOptionValues, and allow_abbreviations if it contains
/// rfl::cli::AllowAbbreviations
/// rfl::cli::SeparateOptionValues, allow_abbreviations if it contains
/// rfl::cli::AllowAbbreviations, and options_first if it contains
/// rfl::cli::OptionsFirst
template <class T, class ProcessorsType,
bool _all_paths = rfl::internal::no_extra_fields_v<ProcessorsType>
|| separate_option_values_v<ProcessorsType>
Expand All @@ -661,6 +667,7 @@ Options make_options() {
options.make_all_paths = &make_options<T, ProcessorsType, true>;
}
options.allow_abbreviations = allow_abbreviations_v<ProcessorsType>;
options.options_first = options_first_v<ProcessorsType>;
using U = unwrapped_option_t<T, ProcessorsType>;
if constexpr (_all_paths) {
collect_value_options<T, ProcessorsType, type_list<>>(&options);
Expand Down
8 changes: 7 additions & 1 deletion include/rfl/cli/parse_argv.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,9 @@ namespace internal {
/// - Short options: -x value, -x=value, or -x (stored in `short_args`)
/// - Positional arguments: bare arguments not prefixed with dashes (stored in `positional`)
/// The special argument "--" forces all subsequent arguments to be treated as positional.
/// If `_options.options_first` is set (rfl::cli::OptionsFirst), so does the
/// first positional argument, which is kept: every later token is a
/// positional argument as it is, including "--", as in getopt's '+' mode.
/// `_options` says what each option does with the token that follows it
/// when it is given without '='. A short option that takes a value consumes
/// it, and fails if there is none; so does a long one with
Expand Down Expand Up @@ -248,6 +251,7 @@ inline rfl::Result<ParsedArgs> 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;
}

Expand Down Expand Up @@ -318,8 +322,10 @@ inline rfl::Result<ParsedArgs> parse_string_views(
continue;
}

// Bare argument → positional.
// Bare argument → positional. With OptionsFirst, every later token is
// one too, as in getopt's '+' mode.
result.positional.emplace_back(arg_raw);
force_positional = _options.options_first;
}
return result;
}
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 @@ -25,7 +25,8 @@ 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(internal::list_delimiter_v<ProcessorsType>);
const auto r = Reader(internal::list_delimiter_v<ProcessorsType>,
std::move(_args.verbatim_list));
const auto var = CliVarType{&_args.values, "", std::nullopt,
&_args.later_occurrences};
return Parser<T, ProcessorsType>::read(r, var);
Expand Down
15 changes: 14 additions & 1 deletion include/rfl/cli/resolve_args.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@ struct ResolvedArgs {
std::map<std::string, std::string> values;
/// The occurrences after the first of each list given more than once.
CliLaterOccurrencesType later_occurrences;
/// The path of the list whose items are taken as they are, never split or
/// dropped, or empty: with rfl::cli::OptionsFirst, the list as the last
/// positional field when it gets the rest of the command line.
std::string verbatim_list;
};

/// Applies what parse_argv could not know without the option table.
Expand Down Expand Up @@ -146,8 +150,17 @@ inline rfl::Result<ResolvedArgs> resolve_args(
result.emplace(long_name, std::move(value));
}

// With rfl::cli::OptionsFirst, the rest of the command line is passed
// through to the list as it is.
auto verbatim_list = std::string();
if (_options.options_first && _options.last_positional_is_list()
&& _parsed.positional.size() >= positional_names.size()) {
verbatim_list = positional_names.back();
}

return ResolvedArgs{std::move(result),
std::move(_parsed.later_occurrences)};
std::move(_parsed.later_occurrences),
std::move(verbatim_list)};
}

/// The error for a long option that abbreviates several options, worded
Expand Down
15 changes: 12 additions & 3 deletions include/rfl/cli/usage.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
#include "../parsing/schema/make.hpp"
#include "../to_generic.hpp"
#include "ListDelimiter.hpp"
#include "OptionsFirst.hpp"
#include "Reader.hpp"
#include "options.hpp"
#include "resolve_args.hpp"
Expand Down Expand Up @@ -597,12 +598,20 @@ inline std::string usage_help_text(const UsageArg& _arg) {
return text;
}

/// @param _options_first Whether the options end at the first positional
/// argument (rfl::cli::OptionsFirst), so the synopsis lists them first.
inline std::string format_usage(const std::string& _program_name,
const std::vector<UsageArg>& _args,
const bool _detailed,
const std::optional<char> _delimiter) {
const std::optional<char> _delimiter,
const bool _options_first) {
auto synopsis = _args;
if (_options_first) {
std::stable_partition(synopsis.begin(), synopsis.end(),
[](const UsageArg& _arg) { return !_arg.positional; });
}
auto out = "Usage: " + _program_name;
for (const auto& arg : _args) {
for (const auto& arg : synopsis) {
const auto str = usage_arg_to_string(arg, "|", _delimiter);
out += arg.required ? " " + str : " [" + str + "]";
}
Expand Down Expand Up @@ -707,7 +716,7 @@ rfl::Result<std::string> usage(const std::string& _program_name,
rfl::internal::default_if_missing_v<ProcessorsType>,
internal::usage_defaults<T, Ps...>());
return internal::format_usage(_program_name, args, _detailed,
delimiter);
delimiter, options.options_first);
} catch (std::exception& e) {
return error(e.what());
}
Expand Down
Loading