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
19 changes: 15 additions & 4 deletions docs/content/supported_formats/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,10 +133,21 @@ looks like an option (`-` followed by anything except a digit or `.`):
`Missing value for option '-o'.` Use `=` to pass an empty value or one that
starts with `-`: `-o=`, `-o=-x`.

## Combining Positional and Short

`Positional` and `Short` can be used together in the same struct, but
**cannot be nested** (`Positional<Short<...>>` is a compile-time error):
## Combining wrappers

`Short` and `Positional` can be nested with `DefaultVal`, `std::optional`,
`Description`, `Rename` and `Deprecated` in any order:
`rfl::Description<"...", rfl::Short<"o", T>>` is `-o`, and
`rfl::DefaultVal<rfl::Positional<T>>` is positional. Put `rfl::Rename`
outermost, as in `rfl::Rename<"out", rfl::Short<"o", T>>`; inside other
wrappers it is ignored.

Bare arguments go to the `Positional` fields in declaration order. Two fields
with the same `Short` name make every read fail with
`Duplicate short name '-o' in struct definition.` A field with more than one
`Short` or `Positional`, such as `rfl::Positional<rfl::Short<"o", T>>` or
`rfl::Short<"o", rfl::Description<"...", rfl::Positional<T>>>`, is a
compile-time error:

```cpp
struct Config {
Expand Down
84 changes: 59 additions & 25 deletions include/rfl/cli/options.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,12 @@
#include <utility>
#include <vector>

#include "../DefaultVal.hpp"
#include "../Deprecated.hpp"
#include "../Description.hpp"
#include "../Generic.hpp"
#include "../Positional.hpp"
#include "../Rename.hpp"
#include "../Short.hpp"
#include "../Tuple.hpp"
#include "../internal/StringLiteral.hpp"
Expand Down Expand Up @@ -62,8 +66,9 @@ struct Options {
/// of their field.
std::map<std::string, std::string> short_options;

/// The paths of the rfl::Positional fields, in declaration order. Each
/// takes one positional argument.
/// The paths of the rfl::Positional fields, in declaration order, wherever
/// rfl::Positional sits among a field's wrappers. Each takes one positional
/// argument.
std::vector<std::string> positionals;

/// Whether tokens such as `-5` and `-.5` are short options rather than
Expand Down Expand Up @@ -99,20 +104,52 @@ inline bool is_bool_literal(std::string_view _token) noexcept {
|| _token == "0";
}

/// Whether T is rfl::Short directly around rfl::Positional, or the other way
/// round, which is a compile-time error.
/// What rfl::Short and rfl::Positional say about a field of type T. They are
/// found through rfl::DefaultVal, std::optional, rfl::Description,
/// rfl::Deprecated and rfl::Rename, in any order. `count` is the number of
/// rfl::Short and rfl::Positional wrappers; a field may have at most one.
template <class T>
consteval bool is_short_around_positional() {
if constexpr (rfl::internal::is_short_v<T>) {
return rfl::internal::is_positional_v<typename T::Type>;
}
else if constexpr (rfl::internal::is_positional_v<T>) {
return rfl::internal::is_short_v<typename T::Type>;
}
else {
return false;
}
}
struct cli_annotations {
static constexpr bool is_short = false;
static constexpr bool is_positional = false;
static constexpr rfl::internal::StringLiteral<1> short_name = "";
static constexpr int count = 0;
};

template <class T>
using cli_annotations_t = cli_annotations<std::remove_cvref_t<T>>;

template <class T>
struct cli_annotations<DefaultVal<T>> : cli_annotations_t<T> {};

template <class T>
struct cli_annotations<std::optional<T>> : cli_annotations_t<T> {};

template <rfl::internal::StringLiteral _description, class T>
struct cli_annotations<Description<_description, T>> : cli_annotations_t<T> {};

template <rfl::internal::StringLiteral _deprecation_message,
rfl::internal::StringLiteral _description, class T>
struct cli_annotations<Deprecated<_deprecation_message, _description, T>>
: cli_annotations_t<T> {};

template <rfl::internal::StringLiteral _name, class T>
struct cli_annotations<Rename<_name, T>> : cli_annotations_t<T> {};

template <class T>
struct cli_annotations<Positional<T>> : cli_annotations_t<T> {
static constexpr bool is_short = false;
static constexpr bool is_positional = true;
static constexpr int count = cli_annotations_t<T>::count + 1;
};

template <rfl::internal::StringLiteral _name, class T>
struct cli_annotations<Short<_name, T>> : cli_annotations_t<T> {
static constexpr bool is_short = true;
static constexpr bool is_positional = false;
static constexpr auto short_name = _name;
static constexpr int count = cli_annotations_t<T>::count + 1;
};

/// The CLI metadata of the _i-th field of a NamedTuple. InnerType is the
/// declared type of the field, whichever wrappers it consists of.
Expand All @@ -121,17 +158,14 @@ struct field_info {
using FieldType = rfl::tuple_element_t<_i, typename NamedTupleType::Fields>;
using InnerType = typename FieldType::Type;
using OuterType = std::remove_pointer_t<std::remove_cvref_t<InnerType>>;
using Annotations = cli_annotations_t<OuterType>;

/// Whether rfl::Positional is the outermost wrapper of the field.
static constexpr bool is_positional =
rfl::internal::is_positional_v<OuterType>;
/// Whether rfl::Short is the outermost wrapper of the field.
static constexpr bool is_short = rfl::internal::is_short_v<OuterType>;
static constexpr bool is_positional = Annotations::is_positional;
static constexpr bool is_short = Annotations::is_short;

static_assert(
!is_short_around_positional<OuterType>(),
"Nested wrappers (Positional<Short<...>> or Short<..., Positional<...>>) "
"are not allowed.");
static_assert(Annotations::count <= 1,
"A field can have only one rfl::Short or rfl::Positional, "
"wherever it sits among the field's other wrappers.");

static constexpr std::string_view name() { return FieldType::name(); }
};
Expand All @@ -141,7 +175,7 @@ template <class NamedTupleType, size_t _i>
constexpr auto get_short_name() {
using Info = field_info<NamedTupleType, _i>;
if constexpr (Info::is_short) {
return Info::OuterType::short_name_;
return Info::Annotations::short_name;
}
else {
return rfl::internal::StringLiteral<1>("");
Expand Down
191 changes: 191 additions & 0 deletions tests/cli/test_wrapper_order.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
#include <gtest/gtest.h>

#include <optional>
#include <rfl.hpp>
#include <rfl/cli.hpp>
#include <string>
#include <vector>

// rfl::Short and rfl::Positional work through rfl::DefaultVal, std::optional,
// rfl::Description, rfl::Rename and rfl::Deprecated, in either order.
namespace test_wrapper_order {

template <class T, class... Ps>
rfl::Result<T> read(std::vector<const char*> _args) {
_args.insert(_args.begin(), "program");
return rfl::cli::read<T, Ps...>(static_cast<int>(_args.size()),
const_cast<char**>(_args.data()));
}

struct Shorts {
rfl::DefaultVal<rfl::Short<"o", std::string>> output = std::string("o");
rfl::Short<"O", std::optional<std::string>> other_output;
std::optional<rfl::Short<"f", std::string>> format;
rfl::Short<"F", std::optional<std::string>> other_format;
rfl::Description<"Log file", rfl::Short<"l", std::optional<std::string>>>
log;
rfl::Short<"L", rfl::Description<"Level", std::optional<int>>> level;
rfl::Rename<"outDir", rfl::Short<"d", std::optional<std::string>>> out_dir;
rfl::Deprecated<"Use -j.", "Threads", rfl::Short<"t", std::optional<int>>>
threads;
rfl::Short<"j", rfl::Deprecated<"", "Jobs", std::optional<int>>> jobs;
rfl::Description<"Title", std::optional<rfl::Short<"T", std::string>>>
title;
};

TEST(cli, test_short_through_wrappers_given) {
const auto result = read<Shorts, rfl::NoExtraFields>(
{"-o", "a", "-O", "b", "-f", "c", "-F", "d", "-l", "e", "-L", "4", "-d",
"f", "-t", "5", "-j", "6", "-T", "g"});
ASSERT_TRUE(result) << result.error().what();
const auto& s = result.value();
EXPECT_EQ(s.output().value(), "a");
EXPECT_EQ(s.other_output().value(), "b");
EXPECT_EQ(s.format.value().value(), "c");
EXPECT_EQ(s.other_format().value(), "d");
EXPECT_EQ(s.log().value().value(), "e");
EXPECT_EQ(s.level().value().value(), 4);
EXPECT_EQ(s.out_dir().value().value(), "f");
EXPECT_EQ(s.threads().value().value(), 5);
EXPECT_EQ(s.jobs().value().value(), 6);
EXPECT_EQ(s.title().value().value(), "g");
}

TEST(cli, test_short_through_wrappers_absent) {
const auto result = read<Shorts>({});
ASSERT_TRUE(result) << result.error().what();
const auto& s = result.value();
EXPECT_EQ(s.output().value(), "o");
EXPECT_FALSE(s.other_output().has_value());
EXPECT_FALSE(s.format.has_value());
EXPECT_FALSE(s.other_format().has_value());
EXPECT_FALSE(s.log().value().has_value());
EXPECT_FALSE(s.level().value().has_value());
EXPECT_FALSE(s.out_dir().value().has_value());
EXPECT_FALSE(s.threads().value().has_value());
EXPECT_FALSE(s.jobs().value().has_value());
EXPECT_FALSE(s.title().has_value());
}

TEST(cli, test_short_through_wrappers_conflict_with_long) {
const auto result = read<Shorts>({"-d", "a", "--outDir=b"});
EXPECT_FALSE(result);
}

// Positional fields take bare arguments in declaration order, wherever
// rfl::Positional sits among their wrappers.
struct Positionals {
rfl::DefaultVal<rfl::Positional<std::string>> first = std::string("1");
rfl::Positional<std::optional<std::string>> second;
rfl::Description<"Third", rfl::Positional<std::optional<std::string>>> third;
rfl::Positional<rfl::Description<"Fourth", std::optional<std::string>>>
fourth;
std::optional<rfl::Positional<std::string>> fifth;
rfl::Rename<"sixth", rfl::Positional<std::optional<std::string>>> sixth_;
rfl::Deprecated<"", "Seventh", rfl::Positional<std::optional<std::string>>>
seventh;
std::optional<bool> verbose;
};

TEST(cli, test_positional_through_wrappers_given) {
const auto result = read<Positionals>(
{"a", "b", "c", "--verbose", "d", "e", "f", "g"});
ASSERT_TRUE(result) << result.error().what();
const auto& p = result.value();
EXPECT_EQ(p.first().value(), "a");
EXPECT_EQ(p.second().value(), "b");
EXPECT_EQ(p.third().value().value(), "c");
EXPECT_EQ(p.fourth().value().value(), "d");
EXPECT_EQ(p.fifth.value().value(), "e");
EXPECT_EQ(p.sixth_().value().value(), "f");
EXPECT_EQ(p.seventh().value().value(), "g");
EXPECT_EQ(p.verbose, true);
}

TEST(cli, test_positional_through_wrappers_absent) {
const auto result = read<Positionals>({"a"});
ASSERT_TRUE(result) << result.error().what();
const auto& p = result.value();
EXPECT_EQ(p.first().value(), "a");
EXPECT_FALSE(p.second().has_value());
EXPECT_FALSE(p.third().value().has_value());
EXPECT_FALSE(p.fifth.has_value());
EXPECT_FALSE(p.seventh().value().has_value());

const auto none = read<Positionals>({});
ASSERT_TRUE(none) << none.error().what();
EXPECT_EQ(none.value().first().value(), "1");
EXPECT_FALSE(none.value().second().has_value());
}

TEST(cli, test_positional_through_wrappers_by_name) {
const auto result = read<Positionals>({"--sixth=f", "a"});
ASSERT_TRUE(result) << result.error().what();
EXPECT_EQ(result.value().first().value(), "a");
EXPECT_EQ(result.value().sixth_().value().value(), "f");
}

struct ShortFlags {
rfl::Short<"q", rfl::DefaultVal<bool>> quiet = false;
rfl::Short<"v", std::optional<bool>> verbose;
rfl::Description<"Dry run", rfl::Short<"n", bool>> dry_run;
rfl::DefaultVal<rfl::Short<"f", bool>> force = false;
rfl::Positional<std::optional<std::string>> input;
rfl::Positional<std::optional<std::string>> output;
};

TEST(cli, test_short_flags_through_wrappers_do_not_consume_token) {
for (const char* flag : {"-q", "-v", "-n", "-f"}) {
std::vector<const char*> args = {flag, "in.rep"};
if (std::string(flag) != "-n") {
args.push_back("--dry-run=false");
}
if (std::string(flag) != "-q") {
args.push_back("--quiet=false");
}
const auto result = read<ShortFlags>(args);
ASSERT_TRUE(result) << flag << ": " << result.error().what();
EXPECT_EQ(result.value().input().value(), "in.rep") << flag;
}

const auto result =
read<ShortFlags>({"-q", "-v", "in.rep", "-n", "out.csv", "-f"});
ASSERT_TRUE(result) << result.error().what();
const auto& f = result.value();
EXPECT_TRUE(f.quiet().value());
EXPECT_EQ(f.verbose(), true);
EXPECT_TRUE(f.dry_run().value());
EXPECT_TRUE(f.force().value());
EXPECT_EQ(f.input().value(), "in.rep");
EXPECT_EQ(f.output().value(), "out.csv");
}

TEST(cli, test_short_flags_through_wrappers_take_bool_literal) {
const auto result =
read<ShortFlags>({"-q", "true", "-v", "0", "-n", "false", "-f=1", "x"});
ASSERT_TRUE(result) << result.error().what();
const auto& f = result.value();
EXPECT_TRUE(f.quiet().value());
EXPECT_EQ(f.verbose(), false);
EXPECT_FALSE(f.dry_run().value());
EXPECT_TRUE(f.force().value());
EXPECT_EQ(f.input().value(), "x");
}

// Two fields with the same short name fail every read, wherever rfl::Short
// sits among their wrappers. A field with two rfl::Short or rfl::Positional
// wrappers, such as rfl::Short<"o", rfl::Description<"...",
// rfl::Positional<T>>>, does not compile.
struct WrappedAndDirectShort {
rfl::Description<"Name", rfl::Short<"o", std::string>> name;
rfl::Short<"o", int> count;
};

TEST(cli, test_wrapped_duplicate_short_name) {
const auto result = read<WrappedAndDirectShort>({"--count=5", "--name=x"});
ASSERT_FALSE(result);
EXPECT_EQ(std::string(result.error().what()),
"Duplicate short name '-o' in struct definition.");
}

} // namespace test_wrapper_order